From 8802cb5ce6be031807d57d508e1df1eb4c4a3fec Mon Sep 17 00:00:00 2001 From: BenKurrek Date: Thu, 3 Mar 2022 14:32:06 -0500 Subject: [PATCH 1/7] Initial implementation of contract metadata standard --- specs/Standards/ContractMetadata.md | 49 +++++++++++++++++++++++++++++ 1 file changed, 49 insertions(+) create mode 100644 specs/Standards/ContractMetadata.md diff --git a/specs/Standards/ContractMetadata.md b/specs/Standards/ContractMetadata.md new file mode 100644 index 000000000..52a8e9068 --- /dev/null +++ b/specs/Standards/ContractMetadata.md @@ -0,0 +1,49 @@ +# Contract Metadata + +## [NEP-329](https://github.com/near/NEPs/discussions/329) + +Version `1.0.0` + +## Summary + +The contract metadata is a standard interface to allow for auditing and viewing source code for a deployed smart contract. Implementation of this standard is purely optional but is recommended for developers whose contracts are open source. + +## Motivation + +There is no trivial way of finding the source code or author of a deployed smart contract. By having a standard that outlines how to view the source code of an abitrary smart contract, an environment of openness and collaboration is created. + +The initial discussion can be found [here](https://github.com/near/NEPs/discussions/329). + +## Interface + +Metadata applies at the contract level (`ContractMetadata`): + +```ts +type ContractMetadata = { + 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. +} +``` + +A new function for querying the metadata must be supported on each smart contract implementing the standard: + +```ts +function contract_metadata(): ContractMetadata {} +``` + +A new function for setting the contract metadata in case of updates to the currently deployed wasm or link to the open source code may optionally be implemented: + +```ts +function set_contract_metadata( + metadata: ContractMetadata, +): ContractMetadata {} +``` + +### An implementing contract MAY include the following fields on-chain + +- `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. + +## Future possibilities + +- 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. From 27a855dc032ef1231975e77f7e0d6d4bcdebf3c0 Mon Sep 17 00:00:00 2001 From: BenKurrek Date: Thu, 3 Mar 2022 14:34:48 -0500 Subject: [PATCH 2/7] bumped NEP version and fixed minor typo --- specs/Standards/ContractMetadata.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/specs/Standards/ContractMetadata.md b/specs/Standards/ContractMetadata.md index 52a8e9068..e7c9a4c6b 100644 --- a/specs/Standards/ContractMetadata.md +++ b/specs/Standards/ContractMetadata.md @@ -1,6 +1,6 @@ # Contract Metadata -## [NEP-329](https://github.com/near/NEPs/discussions/329) +## [NEP-330](https://github.com/near/NEPs/discussions/329) Version `1.0.0` @@ -10,7 +10,7 @@ The contract metadata is a standard interface to allow for auditing and viewing ## Motivation -There is no trivial way of finding the source code or author of a deployed smart contract. By having a standard that outlines how to view the source code of an abitrary smart contract, an environment of openness and collaboration is created. +There is no trivial way of finding the source code or author of a deployed smart contract. By having a standard that outlines how to view the source code of an arbitrary smart contract, an environment of openness and collaboration is created. The initial discussion can be found [here](https://github.com/near/NEPs/discussions/329). From 89f044c059cb5433214b23c58809672f027030e5 Mon Sep 17 00:00:00 2001 From: BenKurrek Date: Thu, 3 Mar 2022 16:58:32 -0500 Subject: [PATCH 3/7] removed setter function --- specs/Standards/ContractMetadata.md | 8 +------- 1 file changed, 1 insertion(+), 7 deletions(-) diff --git a/specs/Standards/ContractMetadata.md b/specs/Standards/ContractMetadata.md index e7c9a4c6b..4fd7d84c6 100644 --- a/specs/Standards/ContractMetadata.md +++ b/specs/Standards/ContractMetadata.md @@ -31,13 +31,7 @@ A new function for querying the metadata must be supported on each smart contrac function contract_metadata(): ContractMetadata {} ``` -A new function for setting the contract metadata in case of updates to the currently deployed wasm or link to the open source code may optionally be implemented: - -```ts -function set_contract_metadata( - metadata: ContractMetadata, -): ContractMetadata {} -``` +It is up to the author of the contract to keep the version and link up to date when new code is deployed. They can choose to update the metadata with a setter, have it static on the contract, or any other way of their choosing. ### An implementing contract MAY include the following fields on-chain From 9617b0946b146a0c029ae44dfa669d40734ae768 Mon Sep 17 00:00:00 2001 From: Benjamin Kurrek <57506486+BenKurrek@users.noreply.github.com> Date: Fri, 4 Mar 2022 14:30:03 -0500 Subject: [PATCH 4/7] Apply suggestions from code review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Damián Parrino --- specs/Standards/ContractMetadata.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/specs/Standards/ContractMetadata.md b/specs/Standards/ContractMetadata.md index 4fd7d84c6..f1fad6da4 100644 --- a/specs/Standards/ContractMetadata.md +++ b/specs/Standards/ContractMetadata.md @@ -6,11 +6,11 @@ Version `1.0.0` ## Summary -The contract metadata is a standard interface to allow for auditing and viewing source code for a deployed smart contract. Implementation of this standard is purely optional but is recommended for developers whose contracts are open source. +The contract metadata is a standard interface that allows auditing and viewing source code for a deployed smart contract. Implementation of this standard is purely optional but is recommended for developers whose contracts are open source. ## Motivation -There is no trivial way of finding the source code or author of a deployed smart contract. By having a standard that outlines how to view the source code of an arbitrary smart contract, an environment of openness and collaboration is created. +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. The initial discussion can be found [here](https://github.com/near/NEPs/discussions/329). @@ -36,7 +36,7 @@ It is up to the author of the contract to keep the version and link up to date w ### An implementing contract MAY include the following fields on-chain - `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. +- `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. ## Future possibilities From 657dd683705b07db36adf616589aa80aff55df4c Mon Sep 17 00:00:00 2001 From: BenKurrek Date: Tue, 29 Mar 2022 11:02:14 -0400 Subject: [PATCH 5/7] Updated to new templates and standard formatting --- neps/nep-0330.md | 75 +++++++++++++++++++++++++++++ specs/Standards/ContractMetadata.md | 36 +++++++++++--- 2 files changed, 104 insertions(+), 7 deletions(-) create mode 100644 neps/nep-0330.md diff --git a/neps/nep-0330.md b/neps/nep-0330.md new file mode 100644 index 000000000..a2dfb4478 --- /dev/null +++ b/neps/nep-0330.md @@ -0,0 +1,75 @@ +--- +NEP: 330 +Title: Contract Metadata +Author: Ben Kurrek +DiscussionsTo: https://github.com/near/NEPs/discussions/329 +Status: Draft +Type: Standards Track +Category: Contract +Created: 27-Feb-2022 +--- + +## Summary + +The contract metadata is a standard interface that allows auditing and viewing source code for a deployed smart contract. Implementation of this standard is purely optional but is recommended for developers whose contracts are open source. + +## Motivation + +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. + +The initial discussion can be found [here](https://github.com/near/NEPs/discussions/329). + +## Rationale and alternatives + +There is a lot of information that can be held about a contract. Ultimately, we wanted to limit it to the least amount fields while still maintaining our goal. This decision was made to not bloat the contracts with unnecessary storage and also to keep the standard simple and understandable. + +## Specification + +Successful implementations of this standard will introduce a new (`ContractMetadata`) 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 two 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. + +```ts +type ContractMetadata = { + 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. +} +``` + +In order to view this information, contracts must include a getter which will return the struct. + +```ts +function contract_metadata(): ContractMetadata {} +``` + +## Reference Implementation + +As an example, say there was an NFT contract deployed on-chain which was currently using the commit hash `39f2d2646f2f60e18ab53337501370dc02a5661c` and had its open source code located at `https://github.com/near-examples/nft-tutorial`. This contract would then include a struct which has the following fields: + +```ts +type ContractMetadata = { + version: "39f2d2646f2f60e18ab53337501370dc02a5661c" + link: "https://github.com/near-examples/nft-tutorial" +} +``` + +If someone were to call the view function `contract_metadata`, the contract would return: + +```bash +{ + version: "39f2d2646f2f60e18ab53337501370dc02a5661c" + link: "https://github.com/near-examples/nft-tutorial" +} +``` + + +## Future possibilities + +- 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. + +## Copyright +[copyright]: #copyright + +Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/). \ No newline at end of file diff --git a/specs/Standards/ContractMetadata.md b/specs/Standards/ContractMetadata.md index f1fad6da4..7793e35ba 100644 --- a/specs/Standards/ContractMetadata.md +++ b/specs/Standards/ContractMetadata.md @@ -14,9 +14,17 @@ There is no trivial way of finding the source code or author of a deployed smart The initial discussion can be found [here](https://github.com/near/NEPs/discussions/329). -## Interface +## Rationale and alternatives -Metadata applies at the contract level (`ContractMetadata`): +There is a lot of information that can be held about a contract. Ultimately, we wanted to limit it to the least amount fields while still maintaining our goal. This decision was made to not bloat the contracts with unnecessary storage and also to keep the standard simple and understandable. + +## Specification + +Successful implementations of this standard will introduce a new (`ContractMetadata`) 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 two 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. ```ts type ContractMetadata = { @@ -25,18 +33,32 @@ type ContractMetadata = { } ``` -A new function for querying the metadata must be supported on each smart contract implementing the standard: +In order to view this information, contracts must include a getter which will return the struct. ```ts function contract_metadata(): ContractMetadata {} ``` -It is up to the author of the contract to keep the version and link up to date when new code is deployed. They can choose to update the metadata with a setter, have it static on the contract, or any other way of their choosing. +## Reference Implementation -### An implementing contract MAY include the following fields on-chain +As an example, say there was an NFT contract deployed on-chain which was currently using the commit hash `39f2d2646f2f60e18ab53337501370dc02a5661c` and had its open source code located at `https://github.com/near-examples/nft-tutorial`. This contract would then include a struct which has the following fields: + +```ts +type ContractMetadata = { + version: "39f2d2646f2f60e18ab53337501370dc02a5661c" + link: "https://github.com/near-examples/nft-tutorial" +} +``` + +If someone were to call the view function `contract_metadata`, the contract would return: + +```bash +{ + version: "39f2d2646f2f60e18ab53337501370dc02a5661c" + link: "https://github.com/near-examples/nft-tutorial" +} +``` -- `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. ## Future possibilities From 4add7367753eb22c51deb1820e260d72da22fa24 Mon Sep 17 00:00:00 2001 From: BenKurrek Date: Tue, 29 Mar 2022 11:14:50 -0400 Subject: [PATCH 6/7] Added example implementation for contract metadata view function --- neps/nep-0330.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/neps/nep-0330.md b/neps/nep-0330.md index a2dfb4478..f31074e97 100644 --- a/neps/nep-0330.md +++ b/neps/nep-0330.md @@ -64,6 +64,14 @@ If someone were to call the view function `contract_metadata`, the contract woul } ``` +The example implementation of the view function can be seen below. + +```rust +pub fn contract_metadata(&self) -> ContractMetadata { + self.contract_metadata +} +``` + ## Future possibilities From 63c32676dee9c0ede1ddd5e06ada51b0d2641960 Mon Sep 17 00:00:00 2001 From: BenKurrek Date: Tue, 29 Mar 2022 11:46:26 -0400 Subject: [PATCH 7/7] Added more fleshed out implementation --- neps/nep-0330.md | 28 +++++++++++++++++++++++---- specs/Standards/ContractMetadata.md | 30 ++++++++++++++++++++++++++++- 2 files changed, 53 insertions(+), 5 deletions(-) diff --git a/neps/nep-0330.md b/neps/nep-0330.md index f31074e97..4b544c6d6 100644 --- a/neps/nep-0330.md +++ b/neps/nep-0330.md @@ -64,14 +64,34 @@ If someone were to call the view function `contract_metadata`, the contract woul } ``` -The example implementation of the view function can be seen below. +An example implementation can be seen below. ```rust -pub fn contract_metadata(&self) -> ContractMetadata { - self.contract_metadata +/// Simple Implementation +#[near_bindgen] +pub struct Contract { + pub contract_metadata: ContractMetadata +} + +/// Contract metadata structure +pub struct ContractMetadata { + pub version: String, + pub link: String, } -``` +/// Minimum Viable Interface +pub trait ContractMetadataTrait { + fn contract_metadata(&self) -> ContractMetadata; +} + +/// Implementation of the view function +#[near_bindgen] +impl ContractMetadataTrait for Contract { + fn contract_metadata(&self) -> ContractMetadata { + self.contract_metadata.get().unwrap() + } +} +``` ## Future possibilities diff --git a/specs/Standards/ContractMetadata.md b/specs/Standards/ContractMetadata.md index 7793e35ba..94465128d 100644 --- a/specs/Standards/ContractMetadata.md +++ b/specs/Standards/ContractMetadata.md @@ -59,7 +59,35 @@ If someone were to call the view function `contract_metadata`, the contract woul } ``` +An example implementation can be seen below. + +```rust +/// Simple Implementation +#[near_bindgen] +pub struct Contract { + pub contract_metadata: ContractMetadata +} + +/// Contract metadata structure +pub struct ContractMetadata { + pub version: String, + pub link: String, +} + +/// Minimum Viable Interface +pub trait ContractMetadataTrait { + fn contract_metadata(&self) -> ContractMetadata; +} + +/// Implementation of the view function +#[near_bindgen] +impl ContractMetadataTrait for Contract { + fn contract_metadata(&self) -> ContractMetadata { + self.contract_metadata.get().unwrap() + } +} +``` ## Future possibilities -- 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. +- 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. \ No newline at end of file