From 8faf0ecf50f80e30debd59919445e85c760fa894 Mon Sep 17 00:00:00 2001 From: Andrey Gruzdev Date: Mon, 19 Feb 2024 22:57:35 +0100 Subject: [PATCH 01/41] update nep-0330 specification --- neps/nep-0330.md | 80 ++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 63 insertions(+), 17 deletions(-) diff --git a/neps/nep-0330.md b/neps/nep-0330.md index 0d56e4018..a93e65f44 100644 --- a/neps/nep-0330.md +++ b/neps/nep-0330.md @@ -31,23 +31,36 @@ There is a lot of information that can be held about a contract. Ultimately, we 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: +The metadata will include 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. +- `version`: a string that references the specific commit hash or version of the code currently deployed on-chain. If the link is to a GitHub repo URL, this is crucial, as it is needed to make the contract reproducible. - `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. - `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"}`). +- `build_details`: a build details object (see type definition below) that contains all the necessary information about how the contract was built, making it possible for others to reproduce the same WASM of this contract. ```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"}]. + build_details: BuildDetails|null, // optional, details that are required for contract WASM reproducibility. } type Standard { standard: string, // standard name e.g. "nep141" version: string, // semantic version number of the Standard e.g. "1.0.0" } + +type BuildDetails { + env_image: EnvImage, // reference to a reproducible build environment image, e.g. "{tag: "sourcescan/cargo-near:0.6.0", digest: "sha256:bf488476d9c4e49e36862bbdef2c595f88d34a295fd551cc65dc291553849471"}" + contract_path: string|null // relative path to contract folder within the source code e.g. "src/contract". Often, it is the root of the repository, so can be omitted. + build_command: string[] // the exact command that was used to build the contract, with all the flags e.g. ["cargo", "near", "build", "no-abi"]. +} + +type EnvImage { + tag: string // tag of the image e.g. "sourcescan/cargo-near:0.6.0" + digest: string // a sha256 hash unique, immutable identifier for a container image, used to verify that the image under the same tag has not changed e.g. "sha256:bf488476d9c4e49e36862bbdef2c595f88d34a295fd551cc65dc291553849471" +} ``` In order to view this information, contracts must include a getter which will return the struct. @@ -58,30 +71,39 @@ function contract_source_metadata(): ContractSourceMetadata {} ## 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: +As an example, consider an NFT contract located at the relative path `nft-contract`, which was deployed using the `cargo near deploy --no-abi` environment image `sourcescan/cargo-near:0.6.0`. Its latest commit hash is `39f2d2646f2f60e18ab53337501370dc02a5661c`, and its open-source code can be found at `https://github.com/near-examples/nft-tutorial`. This contract would then include a struct with the following fields: ```ts type ContractSourceMetadata = { - version: "39f2d2646f2f60e18ab53337501370dc02a5661c" + version: "39f2d2646f2f60e18ab53337501370dc02a5661c", link: "https://github.com/near-examples/nft-tutorial", standards: [ { - standard: "nep330", - version: "1.1.0" + standard: "nep330", + version: "1.1.0" }, { - standard: "nep171", - version: "1.0.0" + standard: "nep171", + version: "1.0.0" }, { - standard: "nep177", - version: "2.0.0" + standard: "nep177", + version: "2.0.0" } - ] + ], + build_details: { + env_image: { + tag: "sourcescan/cargo-near:0.6.0", + digest: "sha256:bf488476d9c4e49e36862bbdef2c595f88d34a295fd551cc65dc291553849471" + }, + contract_path: "nft-contract", + build_command: ["cargo", "near", "deploy", "--no-abi"] + } } + ``` -If someone were to call the view function `contract_metadata`, the contract would return: +Calling the view function `contract_metadata`, the contract would return: ```bash { @@ -100,10 +122,20 @@ If someone were to call the view function `contract_metadata`, the contract woul standard: "nep177", version: "2.0.0" } - ] + ], + build_details: { + env_image: { + tag: "sourcescan/cargo-near:0.6.0", + digest: "sha256:bf488476d9c4e49e36862bbdef2c595f88d34a295fd551cc65dc291553849471" + }, + contract_path: "nft-contract", + build_command: ["cargo", "near", "deploy", "--no-abi"] + } } ``` +This could be used by SourceScan to reproduce the same WASM using the build details and to verify the on-chain WASM code with the reproduced one. + An example implementation can be seen below. ```rust @@ -113,17 +145,31 @@ pub struct Contract { pub contract_metadata: ContractSourceMetadata } -// Standard structure +/// Standard structure pub struct Standard { pub standard: String, pub version: String } +/// EnvImage structure +pub struct EnvImage { + pub tag: String, + pub digest: String, +} + +/// BuildDetails structure +pub struct BuildDetails { + pub env_image: EnvImage, + pub contract_path: Option, + pub build_command: Vec, +} + /// Contract metadata structure pub struct ContractSourceMetadata { - pub version: String, - pub link: String, - pub standards: Vec + pub version: Option, + pub link: Option, + pub standards: Option>, + pub build_details: Option, } /// Minimum Viable Interface From b976790d1c4fa2fd7d10db017a045578650ac896 Mon Sep 17 00:00:00 2001 From: Andrey Gruzdev Date: Mon, 19 Feb 2024 23:00:16 +0100 Subject: [PATCH 02/41] add nep-0330 version 1.2.0 --- neps/nep-0330.md | 13 ++++++++++--- 1 file changed, 10 insertions(+), 3 deletions(-) diff --git a/neps/nep-0330.md b/neps/nep-0330.md index a93e65f44..e5a74041e 100644 --- a/neps/nep-0330.md +++ b/neps/nep-0330.md @@ -1,14 +1,14 @@ --- NEP: 330 Title: Source Metadata -Author: Ben Kurrek , Osman Abdelnasir +Author: Ben Kurrek , Osman Abdelnasir , Andrey Gruzdev <@canvi> DiscussionsTo: https://github.com/near/NEPs/discussions/329 Status: Approved Type: Standards Track Category: Contract -Version: 1.1.0 +Version: 1.2.0 Created: 27-Feb-2022 -Updated: 13-Jan-2023 +Updated: 19-Feb-2023 --- ## Summary @@ -214,6 +214,13 @@ The extension NEP-351 that added Contract Metadata to this NEP-330 was approved | 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 | +### 1.2.0 - Build Details Extension + +The NEP extension adds build details to the contract metadata, containing necessary information about how the contract was built. This makes it possible for others to reproduce the same WASM of this contract. The idea first appeared in the [cargo-near SourceScan integration thread](https://github.com/near/cargo-near/issues/131). + +#### Benefits + +- This NEP extension gives developers the capability to save all the required build details, making it possible to reproduce the same WASM code in the future. This ensures greater consistency in contracts and the ability to verify source code. With the assistance of tools like SourceScan and cargo-near, the development process on NEAR becomes significantly easier ## Copyright From 7238821baaf379be9f5c543e5b2c344cc9eaa6cb Mon Sep 17 00:00:00 2001 From: ztsalexey Date: Mon, 19 Feb 2024 16:08:13 -0600 Subject: [PATCH 03/41] update nep-0330 summary and motivation --- neps/nep-0330.md | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/neps/nep-0330.md b/neps/nep-0330.md index e5a74041e..46b20fae4 100644 --- a/neps/nep-0330.md +++ b/neps/nep-0330.md @@ -1,7 +1,7 @@ --- NEP: 330 Title: Source Metadata -Author: Ben Kurrek , Osman Abdelnasir , Andrey Gruzdev <@canvi> +Author: Ben Kurrek , Osman Abdelnasir , Andrey Gruzdev <@canvi>, Alexey Zenin <@alexthebuildr> DiscussionsTo: https://github.com/near/NEPs/discussions/329 Status: Approved Type: Standards Track @@ -13,13 +13,17 @@ Updated: 19-Feb-2023 ## Summary -The contract source 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. +The contract source metadata represents a standardized interface designed to facilitate the auditing and inspection of source code associated with a deployed smart contract. Adoption of this standard remains discretionary; however, it is strongly advocated for developers who maintain an open-source approach to their contracts. This initiative promotes greater accountability and transparency within the ecosystem, encouraging best practices in contract development and deployment. ## 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 incorporation of metadata facilitates the discovery and validation of deployed source code, thereby significantly reducing the requisite level of trust during code integration or interaction processes. -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 absence of an accepted protocol for identifying the source code or originator of a deployed smart contract presents a challenge. Establishing a standardized framework for accessing the source code of any given smart contract would foster a culture of transparency and collaborative engagement. + +Moreover, the current landscape does not offer a straightforward mechanism to verify the authenticity of a smart contract's deployed source code against its deployed version. To address this issue, it is imperative that metadata includes specific details that enable contract verification through reproducible builds. + +Furthermore, it is desirable for users and dApps to possess the capability to interpret this metadata, thereby identifying executable methods and generating UIs that facilitate such functionalities. This also extends to acquiring comprehensive insights into potential future modifications by the contract or its developers, enhancing overall system transparency and user trust. The initial discussion can be found [here](https://github.com/near/NEPs/discussions/329). From 811cc3668ba7e04666b5f1b16f9381cca68aa80c Mon Sep 17 00:00:00 2001 From: Andrey Gruzdev <44225021+Canvinus@users.noreply.github.com> Date: Tue, 5 Mar 2024 22:35:54 +0100 Subject: [PATCH 04/41] Update neps/nep-0330.md Co-authored-by: Alexander Fadeev --- neps/nep-0330.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/neps/nep-0330.md b/neps/nep-0330.md index 46b20fae4..daf0261ce 100644 --- a/neps/nep-0330.md +++ b/neps/nep-0330.md @@ -107,7 +107,7 @@ type ContractSourceMetadata = { ``` -Calling the view function `contract_metadata`, the contract would return: +Calling the view function `contract_source_metadata`, the contract would return: ```bash { From fddcee485be341d680fa38f570e2954c158b6b6f Mon Sep 17 00:00:00 2001 From: Andrey Gruzdev <44225021+Canvinus@users.noreply.github.com> Date: Tue, 5 Mar 2024 22:39:13 +0100 Subject: [PATCH 05/41] Update neps/nep-0330.md Co-authored-by: Robert Zaremba --- neps/nep-0330.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/neps/nep-0330.md b/neps/nep-0330.md index daf0261ce..e1ab78224 100644 --- a/neps/nep-0330.md +++ b/neps/nep-0330.md @@ -55,7 +55,7 @@ type Standard { version: string, // semantic version number of the Standard e.g. "1.0.0" } -type BuildDetails { +type BuildInfo { env_image: EnvImage, // reference to a reproducible build environment image, e.g. "{tag: "sourcescan/cargo-near:0.6.0", digest: "sha256:bf488476d9c4e49e36862bbdef2c595f88d34a295fd551cc65dc291553849471"}" contract_path: string|null // relative path to contract folder within the source code e.g. "src/contract". Often, it is the root of the repository, so can be omitted. build_command: string[] // the exact command that was used to build the contract, with all the flags e.g. ["cargo", "near", "build", "no-abi"]. From b1ebba057210000ae3720c0e016ecccdb50b836c Mon Sep 17 00:00:00 2001 From: Andrey Gruzdev <44225021+Canvinus@users.noreply.github.com> Date: Tue, 5 Mar 2024 22:39:27 +0100 Subject: [PATCH 06/41] Update neps/nep-0330.md Co-authored-by: Robert Zaremba --- neps/nep-0330.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/neps/nep-0330.md b/neps/nep-0330.md index e1ab78224..42d014af2 100644 --- a/neps/nep-0330.md +++ b/neps/nep-0330.md @@ -47,7 +47,7 @@ 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"}]. - build_details: BuildDetails|null, // optional, details that are required for contract WASM reproducibility. + build_info: BuildInfo|null, // optional, details that are required for contract WASM reproducibility. } type Standard { From 8a1115da5e5bfcc4f3c2c3480add4c97bbcaf0dc Mon Sep 17 00:00:00 2001 From: Andrey Gruzdev <44225021+Canvinus@users.noreply.github.com> Date: Tue, 5 Mar 2024 22:40:52 +0100 Subject: [PATCH 07/41] Update neps/nep-0330.md Co-authored-by: Robert Zaremba --- neps/nep-0330.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/neps/nep-0330.md b/neps/nep-0330.md index 42d014af2..d9b0e0b06 100644 --- a/neps/nep-0330.md +++ b/neps/nep-0330.md @@ -37,7 +37,7 @@ Successful implementations of this standard will introduce a new (`ContractSour The metadata will include optional fields: -- `version`: a string that references the specific commit hash or version of the code currently deployed on-chain. If the link is to a GitHub repo URL, this is crucial, as it is needed to make the contract reproducible. +- `version`: a string that references the specific commit ID or a tag of the code currently deployed on-chain. Examples: `"v0.8.1"`, `"a80bc29"`. - `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. - `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"}`). - `build_details`: a build details object (see type definition below) that contains all the necessary information about how the contract was built, making it possible for others to reproduce the same WASM of this contract. From 2b3bd1374e2f1e26dbdf66449498c6e3a755b922 Mon Sep 17 00:00:00 2001 From: Andrey Gruzdev <44225021+Canvinus@users.noreply.github.com> Date: Tue, 5 Mar 2024 22:41:01 +0100 Subject: [PATCH 08/41] Update neps/nep-0330.md Co-authored-by: Robert Zaremba --- neps/nep-0330.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/neps/nep-0330.md b/neps/nep-0330.md index d9b0e0b06..4d424cc80 100644 --- a/neps/nep-0330.md +++ b/neps/nep-0330.md @@ -38,7 +38,7 @@ Successful implementations of this standard will introduce a new (`ContractSour The metadata will include optional fields: - `version`: a string that references the specific commit ID or a tag of the code currently deployed on-chain. Examples: `"v0.8.1"`, `"a80bc29"`. -- `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`: an URL to the currently deployed code. It must include version or a tag if using a GitHub or a GitLab link. Examples: https://github.com/near/near-cli-rs/releases/tag/v0.8.1, an IPFS CID. - `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"}`). - `build_details`: a build details object (see type definition below) that contains all the necessary information about how the contract was built, making it possible for others to reproduce the same WASM of this contract. From 60466476765616105ad8ba456968943fdfebb89e Mon Sep 17 00:00:00 2001 From: Andrey Gruzdev <44225021+Canvinus@users.noreply.github.com> Date: Tue, 5 Mar 2024 22:42:31 +0100 Subject: [PATCH 09/41] Update neps/nep-0330.md Co-authored-by: Robert Zaremba --- neps/nep-0330.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/neps/nep-0330.md b/neps/nep-0330.md index 4d424cc80..069813557 100644 --- a/neps/nep-0330.md +++ b/neps/nep-0330.md @@ -149,7 +149,7 @@ pub struct Contract { pub contract_metadata: ContractSourceMetadata } -/// Standard structure +/// NEP supported by the contract. pub struct Standard { pub standard: String, pub version: String From 29f9f11bc0292836d3cc40a122ad7a14c8240072 Mon Sep 17 00:00:00 2001 From: Andrey Gruzdev <44225021+Canvinus@users.noreply.github.com> Date: Tue, 5 Mar 2024 22:43:17 +0100 Subject: [PATCH 10/41] Update neps/nep-0330.md Co-authored-by: Robert Zaremba --- neps/nep-0330.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/neps/nep-0330.md b/neps/nep-0330.md index 069813557..3b62f73f3 100644 --- a/neps/nep-0330.md +++ b/neps/nep-0330.md @@ -19,7 +19,7 @@ The contract source metadata represents a standardized interface designed to fac The incorporation of metadata facilitates the discovery and validation of deployed source code, thereby significantly reducing the requisite level of trust during code integration or interaction processes. -The absence of an accepted protocol for identifying the source code or originator of a deployed smart contract presents a challenge. Establishing a standardized framework for accessing the source code of any given smart contract would foster a culture of transparency and collaborative engagement. +The absence of an accepted protocol for identifying the source code or author contact details of a deployed smart contract presents a challenge. Establishing a standardized framework for accessing the source code of any given smart contract would foster a culture of transparency and collaborative engagement. Moreover, the current landscape does not offer a straightforward mechanism to verify the authenticity of a smart contract's deployed source code against its deployed version. To address this issue, it is imperative that metadata includes specific details that enable contract verification through reproducible builds. From 18968ea09c965845b92ab7fdb39a8a1df319b7cd Mon Sep 17 00:00:00 2001 From: Andrey Gruzdev Date: Tue, 5 Mar 2024 23:03:08 +0100 Subject: [PATCH 11/41] implement suggested updates --- neps/nep-0330.md | 45 ++++++++++++++++----------------------------- 1 file changed, 16 insertions(+), 29 deletions(-) diff --git a/neps/nep-0330.md b/neps/nep-0330.md index 3b62f73f3..fa1ea887e 100644 --- a/neps/nep-0330.md +++ b/neps/nep-0330.md @@ -40,7 +40,7 @@ The metadata will include optional fields: - `version`: a string that references the specific commit ID or a tag of the code currently deployed on-chain. Examples: `"v0.8.1"`, `"a80bc29"`. - `link`: an URL to the currently deployed code. It must include version or a tag if using a GitHub or a GitLab link. Examples: https://github.com/near/near-cli-rs/releases/tag/v0.8.1, an IPFS CID. - `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"}`). -- `build_details`: a build details object (see type definition below) that contains all the necessary information about how the contract was built, making it possible for others to reproduce the same WASM of this contract. +- `build_info`: a build details object (see type definition below) that contains all the necessary information about how the contract was built, making it possible for others to reproduce the same WASM of this contract. ```ts type ContractSourceMetadata = { @@ -56,14 +56,10 @@ type Standard { } type BuildInfo { - env_image: EnvImage, // reference to a reproducible build environment image, e.g. "{tag: "sourcescan/cargo-near:0.6.0", digest: "sha256:bf488476d9c4e49e36862bbdef2c595f88d34a295fd551cc65dc291553849471"}" - contract_path: string|null // relative path to contract folder within the source code e.g. "src/contract". Often, it is the root of the repository, so can be omitted. - build_command: string[] // the exact command that was used to build the contract, with all the flags e.g. ["cargo", "near", "build", "no-abi"]. -} - -type EnvImage { - tag: string // tag of the image e.g. "sourcescan/cargo-near:0.6.0" - digest: string // a sha256 hash unique, immutable identifier for a container image, used to verify that the image under the same tag has not changed e.g. "sha256:bf488476d9c4e49e36862bbdef2c595f88d34a295fd551cc65dc291553849471" + build_environment_ref: string, // reference to a reproducible build environment image, e.g. "sourcescan/cargo-near@sha256:bf488476d9c4e49e36862bbdef2c595f88d34a295fd551cc65dc291553849471" or something else pointing to the build environment. + source_code_snapshot: string, // reference to the source code snapshot that was used to build the contract, e.g. "git+https://github.com/near-DevHub/neardevhub-contract.git#335e89edec95d56a4744e7160c3fd590e41ec38e" or "ipfs://" + contract_path: string|null, // relative path to contract folder within the source code e.g. "src/contract". Often, it is the root of the repository, so can be omitted. + build_command: string[], // the exact command that was used to build the contract, with all the flags e.g. ["cargo", "near", "build", "no-abi"]. } ``` @@ -75,11 +71,11 @@ function contract_source_metadata(): ContractSourceMetadata {} ## Reference Implementation -As an example, consider an NFT contract located at the relative path `nft-contract`, which was deployed using the `cargo near deploy --no-abi` environment image `sourcescan/cargo-near:0.6.0`. Its latest commit hash is `39f2d2646f2f60e18ab53337501370dc02a5661c`, and its open-source code can be found at `https://github.com/near-examples/nft-tutorial`. This contract would then include a struct with the following fields: +As an example, consider an NFT contract located at the relative path `nft-contract`, which was deployed using the `cargo near deploy --no-abi` environment image `sourcescan/cargo-near@sha256:bf488476d9c4e49e36862bbdef2c595f88d34a295fd551cc65dc291553849471`. Its latest commit hash is `39f2d2646f2f60e18ab53337501370dc02a5661c`, and its open-source code can be found at `https://github.com/near-examples/nft-tutorial`. This contract would then include a struct with the following fields: ```ts type ContractSourceMetadata = { - version: "39f2d2646f2f60e18ab53337501370dc02a5661c", + version: "1.0.0", link: "https://github.com/near-examples/nft-tutorial", standards: [ { @@ -95,11 +91,9 @@ type ContractSourceMetadata = { version: "2.0.0" } ], - build_details: { - env_image: { - tag: "sourcescan/cargo-near:0.6.0", - digest: "sha256:bf488476d9c4e49e36862bbdef2c595f88d34a295fd551cc65dc291553849471" - }, + build_info: { + build_environment_ref: "sourcescan/cargo-near@sha256:bf488476d9c4e49e36862bbdef2c595f88d34a295fd551cc65dc291553849471", + source_code_snapshot: "git+https://github.com/near-examples/nft-tutorial.git#39f2d2646f2f60e18ab53337501370dc02a5661c", contract_path: "nft-contract", build_command: ["cargo", "near", "deploy", "--no-abi"] } @@ -127,11 +121,9 @@ Calling the view function `contract_source_metadata`, the contract would return: version: "2.0.0" } ], - build_details: { - env_image: { - tag: "sourcescan/cargo-near:0.6.0", - digest: "sha256:bf488476d9c4e49e36862bbdef2c595f88d34a295fd551cc65dc291553849471" - }, + build_info: { + build_environment_ref: "sourcescan/cargo-near@sha256:bf488476d9c4e49e36862bbdef2c595f88d34a295fd551cc65dc291553849471", + source_code_snapshot: "git+https://github.com/near-examples/nft-tutorial.git#39f2d2646f2f60e18ab53337501370dc02a5661c", contract_path: "nft-contract", build_command: ["cargo", "near", "deploy", "--no-abi"] } @@ -155,15 +147,10 @@ pub struct Standard { pub version: String } -/// EnvImage structure -pub struct EnvImage { - pub tag: String, - pub digest: String, -} - /// BuildDetails structure pub struct BuildDetails { - pub env_image: EnvImage, + pub build_environment_ref: String, + pub source_code_snapshot: String, pub contract_path: Option, pub build_command: Vec, } @@ -173,7 +160,7 @@ pub struct ContractSourceMetadata { pub version: Option, pub link: Option, pub standards: Option>, - pub build_details: Option, + pub build_info: Option, } /// Minimum Viable Interface From f47d5ede90e0e542b99ac9f81b257789f21d7b4c Mon Sep 17 00:00:00 2001 From: Andrey Gruzdev Date: Tue, 5 Mar 2024 23:05:12 +0100 Subject: [PATCH 12/41] fix indentation --- neps/nep-0330.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/neps/nep-0330.md b/neps/nep-0330.md index fa1ea887e..79f748f6e 100644 --- a/neps/nep-0330.md +++ b/neps/nep-0330.md @@ -44,10 +44,10 @@ The metadata will include optional fields: ```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"}]. - build_info: BuildInfo|null, // optional, details that are required for contract WASM reproducibility. + 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"}]. + build_info: BuildInfo|null, // optional, details that are required for contract WASM reproducibility. } type Standard { @@ -56,10 +56,10 @@ type Standard { } type BuildInfo { - build_environment_ref: string, // reference to a reproducible build environment image, e.g. "sourcescan/cargo-near@sha256:bf488476d9c4e49e36862bbdef2c595f88d34a295fd551cc65dc291553849471" or something else pointing to the build environment. - source_code_snapshot: string, // reference to the source code snapshot that was used to build the contract, e.g. "git+https://github.com/near-DevHub/neardevhub-contract.git#335e89edec95d56a4744e7160c3fd590e41ec38e" or "ipfs://" - contract_path: string|null, // relative path to contract folder within the source code e.g. "src/contract". Often, it is the root of the repository, so can be omitted. - build_command: string[], // the exact command that was used to build the contract, with all the flags e.g. ["cargo", "near", "build", "no-abi"]. + build_environment_ref: string, // reference to a reproducible build environment image, e.g. "sourcescan/cargo-near@sha256:bf488476d9c4e49e36862bbdef2c595f88d34a295fd551cc65dc291553849471" or something else pointing to the build environment. + source_code_snapshot: string, // reference to the source code snapshot that was used to build the contract, e.g. "git+https://github.com/near-DevHub/neardevhub-contract.git#335e89edec95d56a4744e7160c3fd590e41ec38e" or "ipfs://" + contract_path: string|null, // relative path to contract folder within the source code e.g. "src/contract". Often, it is the root of the repository, so can be omitted. + build_command: string[], // the exact command that was used to build the contract, with all the flags e.g. ["cargo", "near", "build", "no-abi"]. } ``` From 7a186fe210c6391a4fe3c97101f1910b99cdd908 Mon Sep 17 00:00:00 2001 From: Andrey Gruzdev Date: Tue, 5 Mar 2024 23:09:25 +0100 Subject: [PATCH 13/41] fix indentation in examples --- neps/nep-0330.md | 60 ++++++++++++++++++++++++------------------------ 1 file changed, 30 insertions(+), 30 deletions(-) diff --git a/neps/nep-0330.md b/neps/nep-0330.md index 79f748f6e..b68b0ddda 100644 --- a/neps/nep-0330.md +++ b/neps/nep-0330.md @@ -75,28 +75,28 @@ As an example, consider an NFT contract located at the relative path `nft-contra ```ts type ContractSourceMetadata = { - version: "1.0.0", - 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" + version: "1.0.0", + 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" + } + ], + build_info: { + build_environment_ref: "sourcescan/cargo-near@sha256:bf488476d9c4e49e36862bbdef2c595f88d34a295fd551cc65dc291553849471", + source_code_snapshot: "git+https://github.com/near-examples/nft-tutorial.git#39f2d2646f2f60e18ab53337501370dc02a5661c", + contract_path: "nft-contract", + build_command: ["cargo", "near", "deploy", "--no-abi"] } - ], - build_info: { - build_environment_ref: "sourcescan/cargo-near@sha256:bf488476d9c4e49e36862bbdef2c595f88d34a295fd551cc65dc291553849471", - source_code_snapshot: "git+https://github.com/near-examples/nft-tutorial.git#39f2d2646f2f60e18ab53337501370dc02a5661c", - contract_path: "nft-contract", - build_command: ["cargo", "near", "deploy", "--no-abi"] - } } ``` @@ -122,11 +122,11 @@ Calling the view function `contract_source_metadata`, the contract would return: } ], build_info: { - build_environment_ref: "sourcescan/cargo-near@sha256:bf488476d9c4e49e36862bbdef2c595f88d34a295fd551cc65dc291553849471", - source_code_snapshot: "git+https://github.com/near-examples/nft-tutorial.git#39f2d2646f2f60e18ab53337501370dc02a5661c", - contract_path: "nft-contract", - build_command: ["cargo", "near", "deploy", "--no-abi"] - } + build_environment_ref: "sourcescan/cargo-near@sha256:bf488476d9c4e49e36862bbdef2c595f88d34a295fd551cc65dc291553849471", + source_code_snapshot: "git+https://github.com/near-examples/nft-tutorial.git#39f2d2646f2f60e18ab53337501370dc02a5661c", + contract_path: "nft-contract", + build_command: ["cargo", "near", "deploy", "--no-abi"] + } } ``` @@ -149,10 +149,10 @@ pub struct Standard { /// BuildDetails structure pub struct BuildDetails { - pub build_environment_ref: String, - pub source_code_snapshot: String, - pub contract_path: Option, - pub build_command: Vec, + pub build_environment_ref: String, + pub source_code_snapshot: String, + pub contract_path: Option, + pub build_command: Vec, } /// Contract metadata structure From 04c54a5040d4f73e76b15087022c652d82823693 Mon Sep 17 00:00:00 2001 From: Andrey Gruzdev Date: Tue, 5 Mar 2024 23:15:14 +0100 Subject: [PATCH 14/41] add link with commit reference --- neps/nep-0330.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/neps/nep-0330.md b/neps/nep-0330.md index b68b0ddda..a7acd900f 100644 --- a/neps/nep-0330.md +++ b/neps/nep-0330.md @@ -38,14 +38,14 @@ Successful implementations of this standard will introduce a new (`ContractSour The metadata will include optional fields: - `version`: a string that references the specific commit ID or a tag of the code currently deployed on-chain. Examples: `"v0.8.1"`, `"a80bc29"`. -- `link`: an URL to the currently deployed code. It must include version or a tag if using a GitHub or a GitLab link. Examples: https://github.com/near/near-cli-rs/releases/tag/v0.8.1, an IPFS CID. +- `link`: an URL to the currently deployed code. It must include version or a tag if using a GitHub or a GitLab link. Examples: "https://github.com/near/near-cli-rs/releases/tag/v0.8.1", "https://github.com/near-examples/nft-tutorial/tree/39f2d2646f2f60e18ab53337501370dc02a5661c" or an IPFS CID. - `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"}`). - `build_info`: a build details object (see type definition below) that contains all the necessary information about how the contract was built, making it possible for others to reproduce the same WASM of this contract. ```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. + link: string|null, // optional, link to open source code such as a Github repository or a CID to somewhere on IPFS. e.g. https://"github.com/near-examples/nft-tutorial/tree/39f2d2646f2f60e18ab53337501370dc02a5661c" 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"}]. build_info: BuildInfo|null, // optional, details that are required for contract WASM reproducibility. } @@ -76,7 +76,7 @@ As an example, consider an NFT contract located at the relative path `nft-contra ```ts type ContractSourceMetadata = { version: "1.0.0", - link: "https://github.com/near-examples/nft-tutorial", + link: "https://github.com/near-examples/nft-tutorial/tree/39f2d2646f2f60e18ab53337501370dc02a5661c", standards: [ { standard: "nep330", @@ -106,7 +106,7 @@ Calling the view function `contract_source_metadata`, the contract would return: ```bash { version: "39f2d2646f2f60e18ab53337501370dc02a5661c" - link: "https://github.com/near-examples/nft-tutorial", + link: "https://github.com/near-examples/nft-tutorial/tree/39f2d2646f2f60e18ab53337501370dc02a5661c", standards: [ { standard: "nep330", From 35bbcded50a0419a5a24090bd2b0e27b8bcafed5 Mon Sep 17 00:00:00 2001 From: Andrey Gruzdev Date: Tue, 5 Mar 2024 23:17:44 +0100 Subject: [PATCH 15/41] specify that image is in context of docker --- neps/nep-0330.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/neps/nep-0330.md b/neps/nep-0330.md index a7acd900f..744262e30 100644 --- a/neps/nep-0330.md +++ b/neps/nep-0330.md @@ -56,7 +56,7 @@ type Standard { } type BuildInfo { - build_environment_ref: string, // reference to a reproducible build environment image, e.g. "sourcescan/cargo-near@sha256:bf488476d9c4e49e36862bbdef2c595f88d34a295fd551cc65dc291553849471" or something else pointing to the build environment. + build_environment_ref: string, // reference to a reproducible build environment docker image, e.g. "sourcescan/cargo-near@sha256:bf488476d9c4e49e36862bbdef2c595f88d34a295fd551cc65dc291553849471" or something else pointing to the build environment. source_code_snapshot: string, // reference to the source code snapshot that was used to build the contract, e.g. "git+https://github.com/near-DevHub/neardevhub-contract.git#335e89edec95d56a4744e7160c3fd590e41ec38e" or "ipfs://" contract_path: string|null, // relative path to contract folder within the source code e.g. "src/contract". Often, it is the root of the repository, so can be omitted. build_command: string[], // the exact command that was used to build the contract, with all the flags e.g. ["cargo", "near", "build", "no-abi"]. @@ -71,7 +71,7 @@ function contract_source_metadata(): ContractSourceMetadata {} ## Reference Implementation -As an example, consider an NFT contract located at the relative path `nft-contract`, which was deployed using the `cargo near deploy --no-abi` environment image `sourcescan/cargo-near@sha256:bf488476d9c4e49e36862bbdef2c595f88d34a295fd551cc65dc291553849471`. Its latest commit hash is `39f2d2646f2f60e18ab53337501370dc02a5661c`, and its open-source code can be found at `https://github.com/near-examples/nft-tutorial`. This contract would then include a struct with the following fields: +As an example, consider an NFT contract located at the relative path `nft-contract`, which was deployed using the `cargo near deploy --no-abi` environment docker image `sourcescan/cargo-near@sha256:bf488476d9c4e49e36862bbdef2c595f88d34a295fd551cc65dc291553849471`. Its latest commit hash is `39f2d2646f2f60e18ab53337501370dc02a5661c`, and its open-source code can be found at `https://github.com/near-examples/nft-tutorial`. This contract would then include a struct with the following fields: ```ts type ContractSourceMetadata = { From 6a10073c8fc16238f7849b7788722380ddc13af1 Mon Sep 17 00:00:00 2001 From: Andrey Gruzdev <44225021+Canvinus@users.noreply.github.com> Date: Wed, 6 Mar 2024 14:40:35 +0100 Subject: [PATCH 16/41] Update nep-0330.md Co-authored-by: Alexander Fadeev --- neps/nep-0330.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/neps/nep-0330.md b/neps/nep-0330.md index 744262e30..29283a291 100644 --- a/neps/nep-0330.md +++ b/neps/nep-0330.md @@ -58,8 +58,8 @@ type Standard { type BuildInfo { build_environment_ref: string, // reference to a reproducible build environment docker image, e.g. "sourcescan/cargo-near@sha256:bf488476d9c4e49e36862bbdef2c595f88d34a295fd551cc65dc291553849471" or something else pointing to the build environment. source_code_snapshot: string, // reference to the source code snapshot that was used to build the contract, e.g. "git+https://github.com/near-DevHub/neardevhub-contract.git#335e89edec95d56a4744e7160c3fd590e41ec38e" or "ipfs://" - contract_path: string|null, // relative path to contract folder within the source code e.g. "src/contract". Often, it is the root of the repository, so can be omitted. - build_command: string[], // the exact command that was used to build the contract, with all the flags e.g. ["cargo", "near", "build", "no-abi"]. + contract_path: string|null, // relative path to contract folder within the source code e.g. "src/contract". Often, it is the root of the repository, so can be omitted. + build_command: string[], // the exact command that was used to build the contract, with all the flags e.g. ["cargo", "near", "build", "no-abi"]. } ``` From 837d81b33015cc8c25b15dabc926e59520fe54b7 Mon Sep 17 00:00:00 2001 From: Andrey Gruzdev <44225021+Canvinus@users.noreply.github.com> Date: Wed, 6 Mar 2024 14:40:42 +0100 Subject: [PATCH 17/41] Update nep-0330.md Co-authored-by: Alexander Fadeev --- neps/nep-0330.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/neps/nep-0330.md b/neps/nep-0330.md index 29283a291..c4fb78cc9 100644 --- a/neps/nep-0330.md +++ b/neps/nep-0330.md @@ -122,11 +122,11 @@ Calling the view function `contract_source_metadata`, the contract would return: } ], build_info: { - build_environment_ref: "sourcescan/cargo-near@sha256:bf488476d9c4e49e36862bbdef2c595f88d34a295fd551cc65dc291553849471", + build_environment_ref: "sourcescan/cargo-near@sha256:bf488476d9c4e49e36862bbdef2c595f88d34a295fd551cc65dc291553849471", source_code_snapshot: "git+https://github.com/near-examples/nft-tutorial.git#39f2d2646f2f60e18ab53337501370dc02a5661c", - contract_path: "nft-contract", - build_command: ["cargo", "near", "deploy", "--no-abi"] - } + contract_path: "nft-contract", + build_command: ["cargo", "near", "deploy", "--no-abi"] + } } ``` From c38d9f5a696b44d36654260f9ea89fbb7281ee1a Mon Sep 17 00:00:00 2001 From: Andrey Gruzdev Date: Wed, 6 Mar 2024 15:10:34 +0100 Subject: [PATCH 18/41] use semantic version in example --- neps/nep-0330.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/neps/nep-0330.md b/neps/nep-0330.md index c4fb78cc9..00d861c48 100644 --- a/neps/nep-0330.md +++ b/neps/nep-0330.md @@ -105,7 +105,7 @@ Calling the view function `contract_source_metadata`, the contract would return: ```bash { - version: "39f2d2646f2f60e18ab53337501370dc02a5661c" + version: "1.0.0" link: "https://github.com/near-examples/nft-tutorial/tree/39f2d2646f2f60e18ab53337501370dc02a5661c", standards: [ { From aa84739feadf6b04bbfd7fdd06102b6d189367c8 Mon Sep 17 00:00:00 2001 From: Andrey Gruzdev Date: Wed, 6 Mar 2024 15:12:11 +0100 Subject: [PATCH 19/41] rename build_environment --- neps/nep-0330.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/neps/nep-0330.md b/neps/nep-0330.md index 00d861c48..95f123324 100644 --- a/neps/nep-0330.md +++ b/neps/nep-0330.md @@ -56,7 +56,7 @@ type Standard { } type BuildInfo { - build_environment_ref: string, // reference to a reproducible build environment docker image, e.g. "sourcescan/cargo-near@sha256:bf488476d9c4e49e36862bbdef2c595f88d34a295fd551cc65dc291553849471" or something else pointing to the build environment. + build_environment: string, // reference to a reproducible build environment docker image, e.g. "sourcescan/cargo-near@sha256:bf488476d9c4e49e36862bbdef2c595f88d34a295fd551cc65dc291553849471" or something else pointing to the build environment. source_code_snapshot: string, // reference to the source code snapshot that was used to build the contract, e.g. "git+https://github.com/near-DevHub/neardevhub-contract.git#335e89edec95d56a4744e7160c3fd590e41ec38e" or "ipfs://" contract_path: string|null, // relative path to contract folder within the source code e.g. "src/contract". Often, it is the root of the repository, so can be omitted. build_command: string[], // the exact command that was used to build the contract, with all the flags e.g. ["cargo", "near", "build", "no-abi"]. @@ -92,7 +92,7 @@ type ContractSourceMetadata = { } ], build_info: { - build_environment_ref: "sourcescan/cargo-near@sha256:bf488476d9c4e49e36862bbdef2c595f88d34a295fd551cc65dc291553849471", + build_environment: "sourcescan/cargo-near@sha256:bf488476d9c4e49e36862bbdef2c595f88d34a295fd551cc65dc291553849471", source_code_snapshot: "git+https://github.com/near-examples/nft-tutorial.git#39f2d2646f2f60e18ab53337501370dc02a5661c", contract_path: "nft-contract", build_command: ["cargo", "near", "deploy", "--no-abi"] @@ -122,7 +122,7 @@ Calling the view function `contract_source_metadata`, the contract would return: } ], build_info: { - build_environment_ref: "sourcescan/cargo-near@sha256:bf488476d9c4e49e36862bbdef2c595f88d34a295fd551cc65dc291553849471", + build_environment: "sourcescan/cargo-near@sha256:bf488476d9c4e49e36862bbdef2c595f88d34a295fd551cc65dc291553849471", source_code_snapshot: "git+https://github.com/near-examples/nft-tutorial.git#39f2d2646f2f60e18ab53337501370dc02a5661c", contract_path: "nft-contract", build_command: ["cargo", "near", "deploy", "--no-abi"] @@ -149,10 +149,10 @@ pub struct Standard { /// BuildDetails structure pub struct BuildDetails { - pub build_environment_ref: String, + pub build_environment: String, pub source_code_snapshot: String, - pub contract_path: Option, - pub build_command: Vec, + pub contract_path: Option, + pub build_command: Vec, } /// Contract metadata structure From 61025bc366a31cac88b535ff119b12282a6cd7dd Mon Sep 17 00:00:00 2001 From: Andrey Gruzdev Date: Wed, 6 Mar 2024 15:14:22 +0100 Subject: [PATCH 20/41] suggest using docker image digest --- neps/nep-0330.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/neps/nep-0330.md b/neps/nep-0330.md index 95f123324..3bd61afb0 100644 --- a/neps/nep-0330.md +++ b/neps/nep-0330.md @@ -56,7 +56,7 @@ type Standard { } type BuildInfo { - build_environment: string, // reference to a reproducible build environment docker image, e.g. "sourcescan/cargo-near@sha256:bf488476d9c4e49e36862bbdef2c595f88d34a295fd551cc65dc291553849471" or something else pointing to the build environment. + build_environment: string, // reference to a reproducible build environment docker image, e.g. "sourcescan/cargo-near@sha256:bf488476d9c4e49e36862bbdef2c595f88d34a295fd551cc65dc291553849471" or something else pointing to the build environment. When using a Docker image as a reference, it's important to specify the digest of the image to ensure reproducibility, since a tag could be reassigned to a different image. source_code_snapshot: string, // reference to the source code snapshot that was used to build the contract, e.g. "git+https://github.com/near-DevHub/neardevhub-contract.git#335e89edec95d56a4744e7160c3fd590e41ec38e" or "ipfs://" contract_path: string|null, // relative path to contract folder within the source code e.g. "src/contract". Often, it is the root of the repository, so can be omitted. build_command: string[], // the exact command that was used to build the contract, with all the flags e.g. ["cargo", "near", "build", "no-abi"]. From cce3cd17ade820b9898c0f67a7c41fa1675938d0 Mon Sep 17 00:00:00 2001 From: Andrey Gruzdev <44225021+Canvinus@users.noreply.github.com> Date: Wed, 6 Mar 2024 15:19:03 +0100 Subject: [PATCH 21/41] fix indentation in Rust struct --- neps/nep-0330.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/neps/nep-0330.md b/neps/nep-0330.md index 3bd61afb0..a9f6d90cc 100644 --- a/neps/nep-0330.md +++ b/neps/nep-0330.md @@ -151,8 +151,8 @@ pub struct Standard { pub struct BuildDetails { pub build_environment: String, pub source_code_snapshot: String, - pub contract_path: Option, - pub build_command: Vec, + pub contract_path: Option, + pub build_command: Vec, } /// Contract metadata structure From 66db5e8f2de6c32eaa15d05c01d811b2f4ee0456 Mon Sep 17 00:00:00 2001 From: Andrey Gruzdev Date: Wed, 6 Mar 2024 15:24:13 +0100 Subject: [PATCH 22/41] contract_path in context of crates --- neps/nep-0330.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/neps/nep-0330.md b/neps/nep-0330.md index a9f6d90cc..4c8c1ae96 100644 --- a/neps/nep-0330.md +++ b/neps/nep-0330.md @@ -58,7 +58,7 @@ type Standard { type BuildInfo { build_environment: string, // reference to a reproducible build environment docker image, e.g. "sourcescan/cargo-near@sha256:bf488476d9c4e49e36862bbdef2c595f88d34a295fd551cc65dc291553849471" or something else pointing to the build environment. When using a Docker image as a reference, it's important to specify the digest of the image to ensure reproducibility, since a tag could be reassigned to a different image. source_code_snapshot: string, // reference to the source code snapshot that was used to build the contract, e.g. "git+https://github.com/near-DevHub/neardevhub-contract.git#335e89edec95d56a4744e7160c3fd590e41ec38e" or "ipfs://" - contract_path: string|null, // relative path to contract folder within the source code e.g. "src/contract". Often, it is the root of the repository, so can be omitted. + contract_path: string|null, // relative path to contract crate within the source code e.g. "src/contract". Often, it is the root of the repository, so can be omitted. build_command: string[], // the exact command that was used to build the contract, with all the flags e.g. ["cargo", "near", "build", "no-abi"]. } ``` From ddbf6b06a9bf61110304497a52464db78528c24a Mon Sep 17 00:00:00 2001 From: Andrey Gruzdev <44225021+Canvinus@users.noreply.github.com> Date: Thu, 7 Mar 2024 13:35:13 +0100 Subject: [PATCH 23/41] Update neps/nep-0330.md Co-authored-by: Vlad Frolov --- neps/nep-0330.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/neps/nep-0330.md b/neps/nep-0330.md index 4c8c1ae96..3d5316de5 100644 --- a/neps/nep-0330.md +++ b/neps/nep-0330.md @@ -56,7 +56,7 @@ type Standard { } type BuildInfo { - build_environment: string, // reference to a reproducible build environment docker image, e.g. "sourcescan/cargo-near@sha256:bf488476d9c4e49e36862bbdef2c595f88d34a295fd551cc65dc291553849471" or something else pointing to the build environment. When using a Docker image as a reference, it's important to specify the digest of the image to ensure reproducibility, since a tag could be reassigned to a different image. + build_environment: string, // reference to a reproducible build environment docker image, e.g. "docker.io/sourcescan/cargo-near@sha256:bf488476d9c4e49e36862bbdef2c595f88d34a295fd551cc65dc291553849471" or something else pointing to the build environment. When using a Docker image as a reference, it's important to specify the digest of the image to ensure reproducibility, since a tag could be reassigned to a different image. source_code_snapshot: string, // reference to the source code snapshot that was used to build the contract, e.g. "git+https://github.com/near-DevHub/neardevhub-contract.git#335e89edec95d56a4744e7160c3fd590e41ec38e" or "ipfs://" contract_path: string|null, // relative path to contract crate within the source code e.g. "src/contract". Often, it is the root of the repository, so can be omitted. build_command: string[], // the exact command that was used to build the contract, with all the flags e.g. ["cargo", "near", "build", "no-abi"]. From 360ed5886019f0c74a1e4d34838d025dc9c4dcae Mon Sep 17 00:00:00 2001 From: Andrey Gruzdev <44225021+Canvinus@users.noreply.github.com> Date: Thu, 7 Mar 2024 13:35:35 +0100 Subject: [PATCH 24/41] Update neps/nep-0330.md Co-authored-by: Vlad Frolov --- neps/nep-0330.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/neps/nep-0330.md b/neps/nep-0330.md index 3d5316de5..c9f591e0e 100644 --- a/neps/nep-0330.md +++ b/neps/nep-0330.md @@ -58,7 +58,7 @@ type Standard { type BuildInfo { build_environment: string, // reference to a reproducible build environment docker image, e.g. "docker.io/sourcescan/cargo-near@sha256:bf488476d9c4e49e36862bbdef2c595f88d34a295fd551cc65dc291553849471" or something else pointing to the build environment. When using a Docker image as a reference, it's important to specify the digest of the image to ensure reproducibility, since a tag could be reassigned to a different image. source_code_snapshot: string, // reference to the source code snapshot that was used to build the contract, e.g. "git+https://github.com/near-DevHub/neardevhub-contract.git#335e89edec95d56a4744e7160c3fd590e41ec38e" or "ipfs://" - contract_path: string|null, // relative path to contract crate within the source code e.g. "src/contract". Often, it is the root of the repository, so can be omitted. + contract_path: string|null, // relative path to contract crate within the source code e.g. "contracts/contract-one". Often, it is the root of the repository, so can be omitted. build_command: string[], // the exact command that was used to build the contract, with all the flags e.g. ["cargo", "near", "build", "no-abi"]. } ``` From 510f8319a3f40b1e12897ecb8b313b1a7d6446b9 Mon Sep 17 00:00:00 2001 From: Andrey Gruzdev <44225021+Canvinus@users.noreply.github.com> Date: Thu, 7 Mar 2024 13:36:00 +0100 Subject: [PATCH 25/41] Update neps/nep-0330.md Co-authored-by: Vlad Frolov --- neps/nep-0330.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/neps/nep-0330.md b/neps/nep-0330.md index c9f591e0e..35a00dcd4 100644 --- a/neps/nep-0330.md +++ b/neps/nep-0330.md @@ -59,7 +59,7 @@ type BuildInfo { build_environment: string, // reference to a reproducible build environment docker image, e.g. "docker.io/sourcescan/cargo-near@sha256:bf488476d9c4e49e36862bbdef2c595f88d34a295fd551cc65dc291553849471" or something else pointing to the build environment. When using a Docker image as a reference, it's important to specify the digest of the image to ensure reproducibility, since a tag could be reassigned to a different image. source_code_snapshot: string, // reference to the source code snapshot that was used to build the contract, e.g. "git+https://github.com/near-DevHub/neardevhub-contract.git#335e89edec95d56a4744e7160c3fd590e41ec38e" or "ipfs://" contract_path: string|null, // relative path to contract crate within the source code e.g. "contracts/contract-one". Often, it is the root of the repository, so can be omitted. - build_command: string[], // the exact command that was used to build the contract, with all the flags e.g. ["cargo", "near", "build", "no-abi"]. + build_command: string[], // the exact command that was used to build the contract, with all the flags e.g. ["cargo", "near", "build", "--no-abi"]. } ``` From 2cbbda31bf300b8040cf3a4586248b1b00ec637e Mon Sep 17 00:00:00 2001 From: Andrey Gruzdev Date: Thu, 7 Mar 2024 13:36:48 +0100 Subject: [PATCH 26/41] rename Rust struct to BuildInfo --- neps/nep-0330.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/neps/nep-0330.md b/neps/nep-0330.md index 35a00dcd4..28b564b65 100644 --- a/neps/nep-0330.md +++ b/neps/nep-0330.md @@ -147,8 +147,8 @@ pub struct Standard { pub version: String } -/// BuildDetails structure -pub struct BuildDetails { +/// BuildInfo structure +pub struct BuildInfo { pub build_environment: String, pub source_code_snapshot: String, pub contract_path: Option, @@ -160,7 +160,7 @@ pub struct ContractSourceMetadata { pub version: Option, pub link: Option, pub standards: Option>, - pub build_info: Option, + pub build_info: Option, } /// Minimum Viable Interface From 4e24ceb533b99ec45abe02f5f4d9b48227958066 Mon Sep 17 00:00:00 2001 From: Andrey Gruzdev <44225021+Canvinus@users.noreply.github.com> Date: Thu, 7 Mar 2024 15:50:14 +0100 Subject: [PATCH 27/41] Update neps/nep-0330.md Co-authored-by: Alexander Fadeev --- neps/nep-0330.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/neps/nep-0330.md b/neps/nep-0330.md index 28b564b65..73850d14f 100644 --- a/neps/nep-0330.md +++ b/neps/nep-0330.md @@ -92,7 +92,7 @@ type ContractSourceMetadata = { } ], build_info: { - build_environment: "sourcescan/cargo-near@sha256:bf488476d9c4e49e36862bbdef2c595f88d34a295fd551cc65dc291553849471", + build_environment: "docker.io/sourcescan/cargo-near@sha256:bf488476d9c4e49e36862bbdef2c595f88d34a295fd551cc65dc291553849471", source_code_snapshot: "git+https://github.com/near-examples/nft-tutorial.git#39f2d2646f2f60e18ab53337501370dc02a5661c", contract_path: "nft-contract", build_command: ["cargo", "near", "deploy", "--no-abi"] From 41f3c9c6b35ff03567c68a75f23be1ebb69a4982 Mon Sep 17 00:00:00 2001 From: Andrey Gruzdev <44225021+Canvinus@users.noreply.github.com> Date: Thu, 7 Mar 2024 15:50:23 +0100 Subject: [PATCH 28/41] Update neps/nep-0330.md Co-authored-by: Alexander Fadeev --- neps/nep-0330.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/neps/nep-0330.md b/neps/nep-0330.md index 73850d14f..21d0c7817 100644 --- a/neps/nep-0330.md +++ b/neps/nep-0330.md @@ -122,7 +122,7 @@ Calling the view function `contract_source_metadata`, the contract would return: } ], build_info: { - build_environment: "sourcescan/cargo-near@sha256:bf488476d9c4e49e36862bbdef2c595f88d34a295fd551cc65dc291553849471", + build_environment: "docker.io/sourcescan/cargo-near@sha256:bf488476d9c4e49e36862bbdef2c595f88d34a295fd551cc65dc291553849471", source_code_snapshot: "git+https://github.com/near-examples/nft-tutorial.git#39f2d2646f2f60e18ab53337501370dc02a5661c", contract_path: "nft-contract", build_command: ["cargo", "near", "deploy", "--no-abi"] From 222d2602059765f1a127223840a72f2de64bb219 Mon Sep 17 00:00:00 2001 From: Andrey Gruzdev Date: Sat, 9 Mar 2024 12:53:55 +0100 Subject: [PATCH 29/41] add note on having Cargo.lock in source code snapshot --- neps/nep-0330.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/neps/nep-0330.md b/neps/nep-0330.md index 21d0c7817..b20664c1e 100644 --- a/neps/nep-0330.md +++ b/neps/nep-0330.md @@ -57,7 +57,7 @@ type Standard { type BuildInfo { build_environment: string, // reference to a reproducible build environment docker image, e.g. "docker.io/sourcescan/cargo-near@sha256:bf488476d9c4e49e36862bbdef2c595f88d34a295fd551cc65dc291553849471" or something else pointing to the build environment. When using a Docker image as a reference, it's important to specify the digest of the image to ensure reproducibility, since a tag could be reassigned to a different image. - source_code_snapshot: string, // reference to the source code snapshot that was used to build the contract, e.g. "git+https://github.com/near-DevHub/neardevhub-contract.git#335e89edec95d56a4744e7160c3fd590e41ec38e" or "ipfs://" + source_code_snapshot: string, // reference to the source code snapshot used to build the contract, e.g., "git+https://github.com/near-DevHub/neardevhub-contract.git#335e89edec95d56a4744e7160c3fd590e41ec38e" or "ipfs://". It is important to have Cargo.lock inside the source code snapshot to ensure reproducibility. contract_path: string|null, // relative path to contract crate within the source code e.g. "contracts/contract-one". Often, it is the root of the repository, so can be omitted. build_command: string[], // the exact command that was used to build the contract, with all the flags e.g. ["cargo", "near", "build", "--no-abi"]. } From 35bed0fbc75783132b7ca95a11c9c51974844824 Mon Sep 17 00:00:00 2001 From: Andrey Gruzdev Date: Sat, 9 Mar 2024 13:01:53 +0100 Subject: [PATCH 30/41] add cargo-near-new-project-template as an example --- neps/nep-0330.md | 32 ++++++++------------------------ 1 file changed, 8 insertions(+), 24 deletions(-) diff --git a/neps/nep-0330.md b/neps/nep-0330.md index b20664c1e..7950cec1e 100644 --- a/neps/nep-0330.md +++ b/neps/nep-0330.md @@ -45,7 +45,7 @@ The metadata will include optional fields: ```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. e.g. https://"github.com/near-examples/nft-tutorial/tree/39f2d2646f2f60e18ab53337501370dc02a5661c" + link: string|null, // optional, link to open source code such as a Github repository or a CID to somewhere on IPFS. e.g. git+https://github.com/near/cargo-near-new-project-template.git#9c16aaff3c0fe5bda4d8ffb418c4bb2b535eb420" 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"}]. build_info: BuildInfo|null, // optional, details that are required for contract WASM reproducibility. } @@ -71,30 +71,22 @@ function contract_source_metadata(): ContractSourceMetadata {} ## Reference Implementation -As an example, consider an NFT contract located at the relative path `nft-contract`, which was deployed using the `cargo near deploy --no-abi` environment docker image `sourcescan/cargo-near@sha256:bf488476d9c4e49e36862bbdef2c595f88d34a295fd551cc65dc291553849471`. Its latest commit hash is `39f2d2646f2f60e18ab53337501370dc02a5661c`, and its open-source code can be found at `https://github.com/near-examples/nft-tutorial`. This contract would then include a struct with the following fields: +As an example, consider a contract located at the root path of the repository, which was deployed using the `cargo near deploy --no-abi` and environment docker image `sourcescan/cargo-near@sha256:bf488476d9c4e49e36862bbdef2c595f88d34a295fd551cc65dc291553849471`. Its latest commit hash is `9c16aaff3c0fe5bda4d8ffb418c4bb2b535eb420`, and its open-source code can be found at `https://github.com/near/cargo-near-new-project-template`. This contract would then include a struct with the following fields: ```ts type ContractSourceMetadata = { version: "1.0.0", - link: "https://github.com/near-examples/nft-tutorial/tree/39f2d2646f2f60e18ab53337501370dc02a5661c", + link: "https://github.com/near/cargo-near-new-project-template/commit/9c16aaff3c0fe5bda4d8ffb418c4bb2b535eb420", standards: [ { standard: "nep330", version: "1.1.0" - }, - { - standard: "nep171", - version: "1.0.0" - }, - { - standard: "nep177", - version: "2.0.0" } ], build_info: { build_environment: "docker.io/sourcescan/cargo-near@sha256:bf488476d9c4e49e36862bbdef2c595f88d34a295fd551cc65dc291553849471", - source_code_snapshot: "git+https://github.com/near-examples/nft-tutorial.git#39f2d2646f2f60e18ab53337501370dc02a5661c", - contract_path: "nft-contract", + source_code_snapshot: "git+https://github.com/near/cargo-near-new-project-template.git#9c16aaff3c0fe5bda4d8ffb418c4bb2b535eb420", + contract_path: ".", build_command: ["cargo", "near", "deploy", "--no-abi"] } } @@ -106,25 +98,17 @@ Calling the view function `contract_source_metadata`, the contract would return: ```bash { version: "1.0.0" - link: "https://github.com/near-examples/nft-tutorial/tree/39f2d2646f2f60e18ab53337501370dc02a5661c", + link: "https://github.com/near/cargo-near-new-project-template/commit/9c16aaff3c0fe5bda4d8ffb418c4bb2b535eb420", standards: [ { standard: "nep330", version: "1.1.0" - }, - { - standard: "nep171", - version: "1.0.0" - }, - { - standard: "nep177", - version: "2.0.0" } ], build_info: { build_environment: "docker.io/sourcescan/cargo-near@sha256:bf488476d9c4e49e36862bbdef2c595f88d34a295fd551cc65dc291553849471", - source_code_snapshot: "git+https://github.com/near-examples/nft-tutorial.git#39f2d2646f2f60e18ab53337501370dc02a5661c", - contract_path: "nft-contract", + source_code_snapshot: "git+https://github.com/near/cargo-near-new-project-template.git#9c16aaff3c0fe5bda4d8ffb418c4bb2b535eb420", + contract_path: ".", build_command: ["cargo", "near", "deploy", "--no-abi"] } } From 586ddd30ae90e7d85b26bcbc88754e8719e62f1a Mon Sep 17 00:00:00 2001 From: Andrey Gruzdev Date: Sat, 9 Mar 2024 13:04:54 +0100 Subject: [PATCH 31/41] fix the comment of source_code_snapshot --- neps/nep-0330.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/neps/nep-0330.md b/neps/nep-0330.md index 7950cec1e..81c65dc2b 100644 --- a/neps/nep-0330.md +++ b/neps/nep-0330.md @@ -57,7 +57,7 @@ type Standard { type BuildInfo { build_environment: string, // reference to a reproducible build environment docker image, e.g. "docker.io/sourcescan/cargo-near@sha256:bf488476d9c4e49e36862bbdef2c595f88d34a295fd551cc65dc291553849471" or something else pointing to the build environment. When using a Docker image as a reference, it's important to specify the digest of the image to ensure reproducibility, since a tag could be reassigned to a different image. - source_code_snapshot: string, // reference to the source code snapshot used to build the contract, e.g., "git+https://github.com/near-DevHub/neardevhub-contract.git#335e89edec95d56a4744e7160c3fd590e41ec38e" or "ipfs://". It is important to have Cargo.lock inside the source code snapshot to ensure reproducibility. + source_code_snapshot: string, // reference to the source code snapshot that was used to build the contract e.g. "git+https://github.com/near-DevHub/neardevhub-contract.git#335e89edec95d56a4744e7160c3fd590e41ec38e" or "ipfs://". It is important to have Cargo.lock inside the source code snapshot to ensure reproducibility. contract_path: string|null, // relative path to contract crate within the source code e.g. "contracts/contract-one". Often, it is the root of the repository, so can be omitted. build_command: string[], // the exact command that was used to build the contract, with all the flags e.g. ["cargo", "near", "build", "--no-abi"]. } From 2005598ae21165744a88d27a10041f0014cb77a7 Mon Sep 17 00:00:00 2001 From: Andrey Gruzdev Date: Sat, 9 Mar 2024 13:05:52 +0100 Subject: [PATCH 32/41] fix the comment of source_code_snapshot --- neps/nep-0330.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/neps/nep-0330.md b/neps/nep-0330.md index 81c65dc2b..c0e22cc64 100644 --- a/neps/nep-0330.md +++ b/neps/nep-0330.md @@ -57,7 +57,7 @@ type Standard { type BuildInfo { build_environment: string, // reference to a reproducible build environment docker image, e.g. "docker.io/sourcescan/cargo-near@sha256:bf488476d9c4e49e36862bbdef2c595f88d34a295fd551cc65dc291553849471" or something else pointing to the build environment. When using a Docker image as a reference, it's important to specify the digest of the image to ensure reproducibility, since a tag could be reassigned to a different image. - source_code_snapshot: string, // reference to the source code snapshot that was used to build the contract e.g. "git+https://github.com/near-DevHub/neardevhub-contract.git#335e89edec95d56a4744e7160c3fd590e41ec38e" or "ipfs://". It is important to have Cargo.lock inside the source code snapshot to ensure reproducibility. + source_code_snapshot: string, // reference to the source code snapshot that was used to build the contract, e.g. "git+https://github.com/near-DevHub/neardevhub-contract.git#335e89edec95d56a4744e7160c3fd590e41ec38e" or "ipfs://". It is important to have Cargo.lock inside the source code snapshot to ensure reproducibility. contract_path: string|null, // relative path to contract crate within the source code e.g. "contracts/contract-one". Often, it is the root of the repository, so can be omitted. build_command: string[], // the exact command that was used to build the contract, with all the flags e.g. ["cargo", "near", "build", "--no-abi"]. } From 67810147e822541cfd6074255987c20a6c45c750 Mon Sep 17 00:00:00 2001 From: Andrey Gruzdev Date: Sat, 9 Mar 2024 13:08:44 +0100 Subject: [PATCH 33/41] fix link examples --- neps/nep-0330.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/neps/nep-0330.md b/neps/nep-0330.md index c0e22cc64..d83e27bbc 100644 --- a/neps/nep-0330.md +++ b/neps/nep-0330.md @@ -38,14 +38,14 @@ Successful implementations of this standard will introduce a new (`ContractSour The metadata will include optional fields: - `version`: a string that references the specific commit ID or a tag of the code currently deployed on-chain. Examples: `"v0.8.1"`, `"a80bc29"`. -- `link`: an URL to the currently deployed code. It must include version or a tag if using a GitHub or a GitLab link. Examples: "https://github.com/near/near-cli-rs/releases/tag/v0.8.1", "https://github.com/near-examples/nft-tutorial/tree/39f2d2646f2f60e18ab53337501370dc02a5661c" or an IPFS CID. +- `link`: an URL to the currently deployed code. It must include version or a tag if using a GitHub or a GitLab link. Examples: "https://github.com/near/near-cli-rs/releases/tag/v0.8.1", "https://github.com/near/cargo-near-new-project-template/tree/9c16aaff3c0fe5bda4d8ffb418c4bb2b535eb420" or an IPFS CID. - `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"}`). - `build_info`: a build details object (see type definition below) that contains all the necessary information about how the contract was built, making it possible for others to reproduce the same WASM of this contract. ```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. e.g. git+https://github.com/near/cargo-near-new-project-template.git#9c16aaff3c0fe5bda4d8ffb418c4bb2b535eb420" + link: string|null, // optional, link to open source code such as a Github repository or a CID to somewhere on IPFS. e.g. "https://github.com/near/cargo-near-new-project-template/tree/9c16aaff3c0fe5bda4d8ffb418c4bb2b535eb420" 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"}]. build_info: BuildInfo|null, // optional, details that are required for contract WASM reproducibility. } @@ -76,7 +76,7 @@ As an example, consider a contract located at the root path of the repository, w ```ts type ContractSourceMetadata = { version: "1.0.0", - link: "https://github.com/near/cargo-near-new-project-template/commit/9c16aaff3c0fe5bda4d8ffb418c4bb2b535eb420", + link: "https://github.com/near/cargo-near-new-project-template/tree/9c16aaff3c0fe5bda4d8ffb418c4bb2b535eb420", standards: [ { standard: "nep330", @@ -98,7 +98,7 @@ Calling the view function `contract_source_metadata`, the contract would return: ```bash { version: "1.0.0" - link: "https://github.com/near/cargo-near-new-project-template/commit/9c16aaff3c0fe5bda4d8ffb418c4bb2b535eb420", + link: "https://github.com/near/cargo-near-new-project-template/tree/9c16aaff3c0fe5bda4d8ffb418c4bb2b535eb420", standards: [ { standard: "nep330", From 0f70f5d73dec738d21a27602a4f7c5b7a4ff5959 Mon Sep 17 00:00:00 2001 From: Andrey Gruzdev Date: Sat, 9 Mar 2024 13:17:12 +0100 Subject: [PATCH 34/41] add commas to e.g. --- neps/nep-0330.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/neps/nep-0330.md b/neps/nep-0330.md index d83e27bbc..9dbf41944 100644 --- a/neps/nep-0330.md +++ b/neps/nep-0330.md @@ -44,22 +44,22 @@ The metadata will include optional fields: ```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. e.g. "https://github.com/near/cargo-near-new-project-template/tree/9c16aaff3c0fe5bda4d8ffb418c4bb2b535eb420" - 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"}]. + 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, e.g., "https://github.com/near/cargo-near-new-project-template/tree/9c16aaff3c0fe5bda4d8ffb418c4bb2b535eb420" + 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"}]. build_info: BuildInfo|null, // optional, details that are required for contract WASM reproducibility. } type Standard { - standard: string, // standard name e.g. "nep141" - version: string, // semantic version number of the Standard e.g. "1.0.0" + standard: string, // standard name, e.g., "nep141" + version: string, // semantic version number of the Standard, e.g., "1.0.0" } type BuildInfo { - build_environment: string, // reference to a reproducible build environment docker image, e.g. "docker.io/sourcescan/cargo-near@sha256:bf488476d9c4e49e36862bbdef2c595f88d34a295fd551cc65dc291553849471" or something else pointing to the build environment. When using a Docker image as a reference, it's important to specify the digest of the image to ensure reproducibility, since a tag could be reassigned to a different image. - source_code_snapshot: string, // reference to the source code snapshot that was used to build the contract, e.g. "git+https://github.com/near-DevHub/neardevhub-contract.git#335e89edec95d56a4744e7160c3fd590e41ec38e" or "ipfs://". It is important to have Cargo.lock inside the source code snapshot to ensure reproducibility. - contract_path: string|null, // relative path to contract crate within the source code e.g. "contracts/contract-one". Often, it is the root of the repository, so can be omitted. - build_command: string[], // the exact command that was used to build the contract, with all the flags e.g. ["cargo", "near", "build", "--no-abi"]. + build_environment: string, // reference to a reproducible build environment docker image, e.g., "docker.io/sourcescan/cargo-near@sha256:bf488476d9c4e49e36862bbdef2c595f88d34a295fd551cc65dc291553849471" or something else pointing to the build environment. When using a Docker image as a reference, it's important to specify the digest of the image to ensure reproducibility, since a tag could be reassigned to a different image. + source_code_snapshot: string, // reference to the source code snapshot that was used to build the contract, e.g., "git+https://github.com/near-DevHub/neardevhub-contract.git#335e89edec95d56a4744e7160c3fd590e41ec38e" or "ipfs://". It is important to have Cargo.lock inside the source code snapshot to ensure reproducibility. + contract_path: string|null, // relative path to contract crate within the source code, e.g., "contracts/contract-one". Often, it is the root of the repository, so can be omitted. + build_command: string[], // the exact command that was used to build the contract, with all the flags, e.g., ["cargo", "near", "build", "--no-abi"]. } ``` From 55d3f1eb023cb4222f6e4f71b5a7fec152be32b1 Mon Sep 17 00:00:00 2001 From: Andrey Gruzdev Date: Sat, 9 Mar 2024 13:18:15 +0100 Subject: [PATCH 35/41] add cargo-near-template in source_code_snapshot example --- neps/nep-0330.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/neps/nep-0330.md b/neps/nep-0330.md index 9dbf41944..5aa33b663 100644 --- a/neps/nep-0330.md +++ b/neps/nep-0330.md @@ -57,7 +57,7 @@ type Standard { type BuildInfo { build_environment: string, // reference to a reproducible build environment docker image, e.g., "docker.io/sourcescan/cargo-near@sha256:bf488476d9c4e49e36862bbdef2c595f88d34a295fd551cc65dc291553849471" or something else pointing to the build environment. When using a Docker image as a reference, it's important to specify the digest of the image to ensure reproducibility, since a tag could be reassigned to a different image. - source_code_snapshot: string, // reference to the source code snapshot that was used to build the contract, e.g., "git+https://github.com/near-DevHub/neardevhub-contract.git#335e89edec95d56a4744e7160c3fd590e41ec38e" or "ipfs://". It is important to have Cargo.lock inside the source code snapshot to ensure reproducibility. + source_code_snapshot: string, // reference to the source code snapshot that was used to build the contract, e.g., "git+https://github.com/near/cargo-near-new-project-template.git#9c16aaff3c0fe5bda4d8ffb418c4bb2b535eb420" or "ipfs://". It is important to have Cargo.lock inside the source code snapshot to ensure reproducibility. contract_path: string|null, // relative path to contract crate within the source code, e.g., "contracts/contract-one". Often, it is the root of the repository, so can be omitted. build_command: string[], // the exact command that was used to build the contract, with all the flags, e.g., ["cargo", "near", "build", "--no-abi"]. } From c06b054f4ec19e77ce92df2fe30a4bab5b8e0ea7 Mon Sep 17 00:00:00 2001 From: Andrey Gruzdev Date: Wed, 13 Mar 2024 16:40:45 +0100 Subject: [PATCH 36/41] add ensuring wasm reproducibility section --- neps/nep-0330.md | 14 ++++++++++++-- 1 file changed, 12 insertions(+), 2 deletions(-) diff --git a/neps/nep-0330.md b/neps/nep-0330.md index 5aa33b663..41645ec20 100644 --- a/neps/nep-0330.md +++ b/neps/nep-0330.md @@ -56,8 +56,8 @@ type Standard { } type BuildInfo { - build_environment: string, // reference to a reproducible build environment docker image, e.g., "docker.io/sourcescan/cargo-near@sha256:bf488476d9c4e49e36862bbdef2c595f88d34a295fd551cc65dc291553849471" or something else pointing to the build environment. When using a Docker image as a reference, it's important to specify the digest of the image to ensure reproducibility, since a tag could be reassigned to a different image. - source_code_snapshot: string, // reference to the source code snapshot that was used to build the contract, e.g., "git+https://github.com/near/cargo-near-new-project-template.git#9c16aaff3c0fe5bda4d8ffb418c4bb2b535eb420" or "ipfs://". It is important to have Cargo.lock inside the source code snapshot to ensure reproducibility. + build_environment: string, // reference to a reproducible build environment docker image, e.g., "docker.io/sourcescan/cargo-near@sha256:bf488476d9c4e49e36862bbdef2c595f88d34a295fd551cc65dc291553849471" or something else pointing to the build environment. + source_code_snapshot: string, // reference to the source code snapshot that was used to build the contract, e.g., "git+https://github.com/near/cargo-near-new-project-template.git#9c16aaff3c0fe5bda4d8ffb418c4bb2b535eb420" or "ipfs://". contract_path: string|null, // relative path to contract crate within the source code, e.g., "contracts/contract-one". Often, it is the root of the repository, so can be omitted. build_command: string[], // the exact command that was used to build the contract, with all the flags, e.g., ["cargo", "near", "build", "--no-abi"]. } @@ -69,6 +69,16 @@ In order to view this information, contracts must include a getter which will re function contract_source_metadata(): ContractSourceMetadata {} ``` +### Ensuring WASM Reproducibility + +#### Build Environment Docker Image + +When using a Docker image as a reference, it's important to specify the digest of the image to ensure reproducibility, since a tag could be reassigned to a different image. + +#### Cargo.lock + +It is important to have `Cargo.lock` inside the source code snapshot to ensure reproducibility. Example: https://github.com/near/core-contracts. + ## Reference Implementation As an example, consider a contract located at the root path of the repository, which was deployed using the `cargo near deploy --no-abi` and environment docker image `sourcescan/cargo-near@sha256:bf488476d9c4e49e36862bbdef2c595f88d34a295fd551cc65dc291553849471`. Its latest commit hash is `9c16aaff3c0fe5bda4d8ffb418c4bb2b535eb420`, and its open-source code can be found at `https://github.com/near/cargo-near-new-project-template`. This contract would then include a struct with the following fields: From cbf4f0fc9d906906451010198d0588d976c89d2c Mon Sep 17 00:00:00 2001 From: Andrey Gruzdev Date: Thu, 11 Apr 2024 11:43:36 +0200 Subject: [PATCH 37/41] add info about pathes in ensuring reproducibility --- neps/nep-0330.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/neps/nep-0330.md b/neps/nep-0330.md index 41645ec20..b9ba506ea 100644 --- a/neps/nep-0330.md +++ b/neps/nep-0330.md @@ -75,6 +75,12 @@ function contract_source_metadata(): ContractSourceMetadata {} When using a Docker image as a reference, it's important to specify the digest of the image to ensure reproducibility, since a tag could be reassigned to a different image. +### Paths Inside Docker Image + +During the build, paths from the source of the build as well as the location of the cargo registry could be saved into WASM, which affects reproducibility. Therefore, we need to ensure that everyone uses the same paths inside the Docker image. We propose using the following paths: +- `/home/near/code` - Mounting volume from the host system containing the source code. +- `/home/near/.cargo` - Cargo registry. + #### Cargo.lock It is important to have `Cargo.lock` inside the source code snapshot to ensure reproducibility. Example: https://github.com/near/core-contracts. From 44e681dc0137361c2a99417ffe4dffd6461ed70f Mon Sep 17 00:00:00 2001 From: Andrey Gruzdev Date: Thu, 11 Apr 2024 11:46:05 +0200 Subject: [PATCH 38/41] add blank line to list --- neps/nep-0330.md | 1 + 1 file changed, 1 insertion(+) diff --git a/neps/nep-0330.md b/neps/nep-0330.md index b9ba506ea..6615165c4 100644 --- a/neps/nep-0330.md +++ b/neps/nep-0330.md @@ -78,6 +78,7 @@ When using a Docker image as a reference, it's important to specify the digest o ### Paths Inside Docker Image During the build, paths from the source of the build as well as the location of the cargo registry could be saved into WASM, which affects reproducibility. Therefore, we need to ensure that everyone uses the same paths inside the Docker image. We propose using the following paths: + - `/home/near/code` - Mounting volume from the host system containing the source code. - `/home/near/.cargo` - Cargo registry. From ccf93305be4f729ea6637721a4ce730d7d10869d Mon Sep 17 00:00:00 2001 From: Andrey Gruzdev Date: Thu, 11 Apr 2024 22:44:32 +0200 Subject: [PATCH 39/41] fix linter error --- specs/ChainSpec/SelectingBlockProducers.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specs/ChainSpec/SelectingBlockProducers.md b/specs/ChainSpec/SelectingBlockProducers.md index 875ac9fa9..ede0240eb 100644 --- a/specs/ChainSpec/SelectingBlockProducers.md +++ b/specs/ChainSpec/SelectingBlockProducers.md @@ -185,7 +185,7 @@ We sample validators with probability proportional to their stake using the foll * `weighted_sampler: WeightedIndex` - Allow $O(1)$ sampling - This structure will be based on the - [WeightedIndex](https://rust-random.github.io/rand/rand/distributions/weighted/alias_method/struct.WeightedIndex.html) + [WeightedIndex](https://rust-random.github.io/rand/rand/distributions/struct.WeightedIndex.html) implementation (see a description of [Vose's Alias Method](https://en.wikipedia.org/wiki/Alias_method) for details) From 401b04a9eb4f387c4df752a1234396b3f0ca2115 Mon Sep 17 00:00:00 2001 From: Andrey Gruzdev Date: Thu, 11 Apr 2024 23:07:31 +0200 Subject: [PATCH 40/41] fix more linter errors in SelectingBlockProducers.md --- specs/ChainSpec/SelectingBlockProducers.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/specs/ChainSpec/SelectingBlockProducers.md b/specs/ChainSpec/SelectingBlockProducers.md index ede0240eb..426606225 100644 --- a/specs/ChainSpec/SelectingBlockProducers.md +++ b/specs/ChainSpec/SelectingBlockProducers.md @@ -25,6 +25,7 @@ block producers to be the one responsible for producing the chunk/block at each shard. There are several desiderata for these algorithms: + * Larger stakes should be preferred (more staked tokens means more security) * The frequency with which a given participant is selected to produce a particular chunk/block is proportional to that participant's stake @@ -71,6 +72,7 @@ In mainnet and testnet, `epoch_length` is set to `43200`. Let $\text{PROBABILITY we obtain, $s_\text{min} / S = 160/1000,000$. ## Algorithm for selecting block and chunk producers + A potential validator cannot specify whether they want to become a block producer or a chunk-only producer. There is only one type of proposal. The same algorithm is used for selecting block producers and chunk producers, but with different thresholds. The threshold for becoming block producers is higher, so if a node is selected as a block @@ -78,7 +80,9 @@ producer, it will also be a chunk producer, but not the other way around. Valida but not block producers are chunk-only producers. ### select_validators + ### Input + * `max_num_validators: u16` max number of validators to be selected * `min_stake_fraction: Ratio` minimum stake ratio for selected validator * `validator_proposals: Vec` (proposed stakes for the next epoch from nodes sending @@ -110,7 +114,9 @@ return (validators, validator_sampler) ``` ### Algorithm for selecting block producers + ### Input + * `MAX_NUM_BP: u16` Max number of block producers, see Assumptions * `min_stake_fraction: Ratio` $s_\text{min} / S$, see Assumptions * `validator_proposals: Vec` (proposed stakes for the next epoch from nodes sending @@ -121,7 +127,9 @@ select_validators(MAX_NUM_BP, min_stake_fraction, validator_proposals) ``` ### Algorithm for selecting chunk producers + ### Input + * `MAX_NUM_CP: u16` max number of chunk producers, see Assumptions` * `min_stake_fraction: Ratio` $s_\text{min} / S$, see Assumptions * `num_shards: u64` number of shards @@ -137,6 +145,7 @@ them in a way that the total stake in each shard is distributed as evenly as pos So the total stake in each shard will be roughly be `total_stake_all_chunk_producers / num_shards`. ## Algorithm for assigning chunk producers to shards + Note that block producers are a subset of chunk producers, so this algorithm will also assign block producers to shards. This also means that a block producer may only be assigned to a subset of shards. For the security of the protocol, all block producers must track all shards, even if they are not assigned to produce chunks for all shards. @@ -181,6 +190,7 @@ the same algorithm works to assign chunk producers to shards; it is only a matte variables referencing "block producers" to reference "chunk producers" instead. ## Algorithm for sampling validators proportional to stake + We sample validators with probability proportional to their stake using the following data structure. * `weighted_sampler: WeightedIndex` - Allow $O(1)$ sampling From b7224ca3c16e70d633ed85219ef071fdf2f32c9e Mon Sep 17 00:00:00 2001 From: Andrey Gruzdev Date: Fri, 12 Apr 2024 20:46:48 +0200 Subject: [PATCH 41/41] revert to commit 44e681dc0137361c2a99417ffe4dffd6461ed70f --- specs/ChainSpec/SelectingBlockProducers.md | 12 +----------- 1 file changed, 1 insertion(+), 11 deletions(-) diff --git a/specs/ChainSpec/SelectingBlockProducers.md b/specs/ChainSpec/SelectingBlockProducers.md index 426606225..875ac9fa9 100644 --- a/specs/ChainSpec/SelectingBlockProducers.md +++ b/specs/ChainSpec/SelectingBlockProducers.md @@ -25,7 +25,6 @@ block producers to be the one responsible for producing the chunk/block at each shard. There are several desiderata for these algorithms: - * Larger stakes should be preferred (more staked tokens means more security) * The frequency with which a given participant is selected to produce a particular chunk/block is proportional to that participant's stake @@ -72,7 +71,6 @@ In mainnet and testnet, `epoch_length` is set to `43200`. Let $\text{PROBABILITY we obtain, $s_\text{min} / S = 160/1000,000$. ## Algorithm for selecting block and chunk producers - A potential validator cannot specify whether they want to become a block producer or a chunk-only producer. There is only one type of proposal. The same algorithm is used for selecting block producers and chunk producers, but with different thresholds. The threshold for becoming block producers is higher, so if a node is selected as a block @@ -80,9 +78,7 @@ producer, it will also be a chunk producer, but not the other way around. Valida but not block producers are chunk-only producers. ### select_validators - ### Input - * `max_num_validators: u16` max number of validators to be selected * `min_stake_fraction: Ratio` minimum stake ratio for selected validator * `validator_proposals: Vec` (proposed stakes for the next epoch from nodes sending @@ -114,9 +110,7 @@ return (validators, validator_sampler) ``` ### Algorithm for selecting block producers - ### Input - * `MAX_NUM_BP: u16` Max number of block producers, see Assumptions * `min_stake_fraction: Ratio` $s_\text{min} / S$, see Assumptions * `validator_proposals: Vec` (proposed stakes for the next epoch from nodes sending @@ -127,9 +121,7 @@ select_validators(MAX_NUM_BP, min_stake_fraction, validator_proposals) ``` ### Algorithm for selecting chunk producers - ### Input - * `MAX_NUM_CP: u16` max number of chunk producers, see Assumptions` * `min_stake_fraction: Ratio` $s_\text{min} / S$, see Assumptions * `num_shards: u64` number of shards @@ -145,7 +137,6 @@ them in a way that the total stake in each shard is distributed as evenly as pos So the total stake in each shard will be roughly be `total_stake_all_chunk_producers / num_shards`. ## Algorithm for assigning chunk producers to shards - Note that block producers are a subset of chunk producers, so this algorithm will also assign block producers to shards. This also means that a block producer may only be assigned to a subset of shards. For the security of the protocol, all block producers must track all shards, even if they are not assigned to produce chunks for all shards. @@ -190,12 +181,11 @@ the same algorithm works to assign chunk producers to shards; it is only a matte variables referencing "block producers" to reference "chunk producers" instead. ## Algorithm for sampling validators proportional to stake - We sample validators with probability proportional to their stake using the following data structure. * `weighted_sampler: WeightedIndex` - Allow $O(1)$ sampling - This structure will be based on the - [WeightedIndex](https://rust-random.github.io/rand/rand/distributions/struct.WeightedIndex.html) + [WeightedIndex](https://rust-random.github.io/rand/rand/distributions/weighted/alias_method/struct.WeightedIndex.html) implementation (see a description of [Vose's Alias Method](https://en.wikipedia.org/wiki/Alias_method) for details)