feat: add standards key to ContractSourceMetadata
#351
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,12 +1,14 @@ | ||
| --- | ||
| NEP: 330 | ||
| Title: Source Metadata | ||
| Author: Ben Kurrek <[email protected]>, Osman Abdelnasir <[email protected]> | ||
| DiscussionsTo: https://github.com/near/NEPs/discussions/329 | ||
| Status: Approved | ||
| Type: Standards Track | ||
| Category: Contract | ||
| Version: 1.1.0 | ||
| Created: 27-Feb-2022 | ||
| Updated: 13-Jan-2023 | ||
| --- | ||
|
|
||
| ## Summary | ||
|
|
@@ -17,6 +19,8 @@ The contract source metadata is a standard interface that allows auditing and vi | |
|
|
||
| There is no trivial way of finding the source code or author of a deployed smart contract. Having a standard that outlines how to view the source code of an arbitrary smart contract creates an environment of openness and collaboration. | ||
|
|
||
| Additionally, we would like for wallets and dApps to be able to parse this information and determine which methods they are able to call and render UIs that provide that functionality. | ||
|
|
||
| The initial discussion can be found [here](https://github.com/near/NEPs/discussions/329). | ||
|
|
||
| ## Rationale and alternatives | ||
|
|
@@ -25,16 +29,23 @@ There is a lot of information that can be held about a contract. Ultimately, we | |
|
|
||
| ## Specification | ||
|
|
||
| Successful implementations of this standard will introduce a new (`ContractSourceMetadata`) struct that will hold all the necessary information to be queried for. This struct will be kept on the contract level. | ||
|
|
||
| The metadata will include three optional fields: | ||
| - `version`: a string that references the specific commit hash or version of the code that is currently deployed on-chain. This can be included regardless of whether or not the contract is open-sourced and can also be used for organizational purposes. | ||
| - `link`: a string that references the link to the open-source code. This can be anything such as Github or a CID to somewhere on IPFS. | ||
frol marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| - `standards`: a list of objects (see type definition below) that enumerates the NEPs supported by the contract. If this extension is supported, it is advised to also include NEP-330 version 1.1.0 in the list (`{standard: "nep330", version: "1.1.0"}`). | ||
|
There was a problem hiding this comment. @esaminu I have added the |
||
|
|
||
| ```ts | ||
| type ContractSourceMetadata = { | ||
| version: string|null, // optional, commit hash being used for the currently deployed wasm. If the contract is not open-sourced, this could also be a numbering system for internal organization / tracking such as "1.0.0" and "2.1.0". | ||
| link: string|null, // optional, link to open source code such as a Github repository or a CID to somewhere on IPFS. | ||
| standards: Standard[]|null, // optional, standards and extensions implemented in the currently deployed wasm e.g. [{standard: "nep330", version: "1.1.0"},{standard: "nep141", version: "1.0.0"}]. | ||
| } | ||
|
|
||
| type Standard { | ||
| standard: string, // standard name e.g. "nep141" | ||
| version: string, // semantic version number of the Standard e.g. "1.0.0" | ||
| } | ||
| ``` | ||
|
|
||
|
|
@@ -51,7 +62,21 @@ As an example, say there was an NFT contract deployed on-chain which was current | |
| ```ts | ||
| type ContractSourceMetadata = { | ||
| version: "39f2d2646f2f60e18ab53337501370dc02a5661c" | ||
| link: "https://github.com/near-examples/nft-tutorial", | ||
| standards: [ | ||
| { | ||
| standard: "nep330", | ||
| version: "1.1.0" | ||
| }, | ||
|
Comment on lines
+67
to
+70
There was a problem hiding this comment. I have added reference to NEP-330 into all the examples to ensure that readers follow the advice. |
||
| { | ||
| standard: "nep171", | ||
| version: "1.0.0" | ||
| }, | ||
| { | ||
| standard: "nep177", | ||
| version: "2.0.0" | ||
| } | ||
| ] | ||
frol marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| } | ||
| ``` | ||
|
|
||
|
|
@@ -60,7 +85,21 @@ If someone were to call the view function `contract_metadata`, the contract woul | |
| ```bash | ||
| { | ||
| version: "39f2d2646f2f60e18ab53337501370dc02a5661c" | ||
| link: "https://github.com/near-examples/nft-tutorial", | ||
| standards: [ | ||
| { | ||
| standard: "nep330", | ||
| version: "1.1.0" | ||
| }, | ||
| { | ||
| standard: "nep171", | ||
| version: "1.0.0" | ||
| }, | ||
| { | ||
| standard: "nep177", | ||
| version: "2.0.0" | ||
| } | ||
| ] | ||
| } | ||
| ``` | ||
|
|
||
|
|
@@ -73,15 +112,22 @@ pub struct Contract { | |
| pub contract_metadata: ContractSourceMetadata | ||
| } | ||
|
|
||
| // Standard structure | ||
| pub struct Standard { | ||
| pub standard: String, | ||
| pub version: String | ||
| } | ||
|
|
||
| /// Contract metadata structure | ||
| pub struct ContractSourceMetadata { | ||
| pub version: String, | ||
| pub link: String, | ||
| pub standards: Vec<Standard> | ||
| } | ||
|
|
||
| /// Minimum Viable Interface | ||
| pub trait ContractSourceMetadataTrait { | ||
| fn contract_source_metadata(&self) -> ContractSourceMetadata; | ||
| } | ||
|
|
||
| /// Implementation of the view function | ||
|
|
@@ -97,6 +143,31 @@ impl ContractSourceMetadataTrait for Contract { | |
|
|
||
| - By having a standard outlining metadata for an arbitrary contract, any information that pertains on a contract level can be added based on the requests of the developer community. | ||
|
|
||
| ## Decision Context | ||
|
|
||
| ### 1.0.0 - Initial Version | ||
|
|
||
| The initial version of NEP-330 was approved by @jlogelin on Mar 29, 2022. | ||
|
|
||
| ### 1.1.0 - Contract Metadata Extension | ||
|
|
||
| The extension NEP-351 that added Contract Metadata to this NEP-330 was approved by Contract Standards Working Group members on January 17, 2023 ([meeting recording](https://youtu.be/pBLN9UyE6AA)). | ||
|
|
||
| #### Benefits | ||
|
|
||
| - Unlocks NEP extensions that otherwise would be hard to integrate into the tooling as it would be guess-based (e.g. see "interface detection" concerns in the Non-transferrable NFT NEP) | ||
| - Standardization enables composability as it makes it easier to interact with contracts when you can programmatically check compatibility | ||
| - This NEP extension introduces an optional field, so there is no breaking change to the original NEP | ||
|
|
||
| #### Concerns | ||
|
|
||
| | # | Concern | Resolution | Status | | ||
| | - | - | - | - | | ||
| | 1 | Integer field as a standard reference is limiting as third-party projects may want to introduce their own standards without pushing it through the NEP process | Author accepted the proposed string-value standard reference (e.g. “nep123” instead of just 123, and allow “xyz001” as previously it was not possible to express it) | Resolved | | ||
| | 2 | NEP-330 and NEP-351 should be included in the list of the supported NEPs | There seems to be a general agreement that it is a good default, so NEP was updated | Resolved | | ||
| | 3 | JSON Event could be beneficial, so tooling can react to the changes in the supported standards | It is outside the scope of this NEP. Also, list of supported standards only changes with contract re-deployment, so tooling can track DEPLOY_CODE events and check the list of supported standards when new code is deployed | Won’t fix | | ||
|
Comment on lines
+146
to
+168
There was a problem hiding this comment. I have added this "Decision Context" as per NEP process |
||
|
|
||
|
|
||
| ## Copyright | ||
| [copyright]: #copyright | ||
|
|
||
|
|
||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@ori-near I have introduced NEPs versioning as part of the metadata. I will go over all of the approved NEPs and set the version to 1.0.0 if it is not set, and update NEP-001.