From 9e4724219804c0c96cedaca5f6131d06d2a681a4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?dj8yf0=CE=BCl?= Date: Thu, 30 Jan 2025 18:24:22 +0200 Subject: [PATCH 1/4] chore(near-contract-standards): add `build_info` field --- .../src/contract_metadata.rs | 154 +++++++++++++++++- 1 file changed, 151 insertions(+), 3 deletions(-) diff --git a/near-contract-standards/src/contract_metadata.rs b/near-contract-standards/src/contract_metadata.rs index c75714482..3e1296117 100644 --- a/near-contract-standards/src/contract_metadata.rs +++ b/near-contract-standards/src/contract_metadata.rs @@ -1,17 +1,165 @@ +pub use build_info::BuildInfo; use near_sdk::serde::{Deserialize, Serialize}; -/// The contract source metadata is a standard interface that allows auditing and viewing source code for a deployed smart contract. -#[derive(Debug, Serialize, Deserialize, PartialEq, Clone)] +/// The struct provides information about deployed contract's source code and supported standards. +/// +/// Contract source metadata follows [**NEP-330 standard**](https://github.com/near/NEPs/blob/master/neps/nep-0330.md) for smart contracts +/// +/// See documentation of [`near_api::types::contract::ContractSourceMetadata`](https://docs.rs/near-api/latest/near_api/types/contract/struct.ContractSourceMetadata.html) +/// and [`near_api::Contract::contract_source_metadata`](https://docs.rs/near-api/latest/near_api/struct.Contract.html#method.contract_source_metadata) +/// on how to query this piece of data from a contract via `near_api` crate +#[derive(Debug, Clone, PartialEq, Eq, Default, Serialize, Deserialize)] #[serde(crate = "near_sdk::serde")] pub struct ContractSourceMetadata { + /// Optional version identifier, typically a semantic version + /// + /// **NOTE**: + /// As of **NEP-330** standard version **1.2.0** + /// this field may or may not be consistent with [`Self::link`] and with [`BuildInfo::source_code_snapshot`], but only [`BuildInfo::source_code_snapshot`] defines source code for formal reproducibility verification, and [`Self::link`] and [`Self::version`] do not + /// + /// ## Examples: + /// + /// ```rust,no_run + /// # let version: Option = + /// // Semantic version + /// Some("1.0.0".into()) + /// # ; + /// ``` pub version: Option, + /// Optional URL to source code repository/tree + /// + /// **NOTE**: + /// As of **NEP-330** standard version **1.2.0** + /// this field may or may not be consistent with [`Self::version`] and with [`BuildInfo::source_code_snapshot`], but only [`BuildInfo::source_code_snapshot`] defines source code for formal reproducibility verification, and [`Self::link`] and [`Self::version`] do not + /// + /// ## Examples: + /// + /// ```rust,no_run + /// # let link: Option = + /// // GitHub URL + /// Some("https://github.com/near-examples/nft-tutorial".into()) + /// # ; + /// ``` + /// ```rust,no_run + /// # let link: Option = + /// // GitHub URL + /// Some("https://github.com/org/repo/tree/8d8a8a0fe86a1d8eb3bce45f04ab1a65fecf5a1b".into()) + /// # ; + /// ``` pub link: Option, + /// List of supported NEAR standards (NEPs) with their versions + /// + /// This field is an addition of **1.1.0** **NEP-330** revision + /// + /// ## Examples: + /// + /// This field will always include NEP-330 itself: + /// ```rust,no_run + /// # use near_contract_standards::contract_metadata::Standard; + /// # let link: Vec = + /// // this is always at least 1.1.0 + /// vec![Standard { standard: "nep330".into(), version: "1.1.0".into() }] + /// # ; + /// ``` + /// ```rust,no_run + /// # use near_contract_standards::contract_metadata::Standard; + /// # let link: Vec = + /// vec![Standard { standard: "nep330".into(), version: "1.2.0".into() }] + /// # ; + /// ``` + // it's a guess it was added as 1.1.0 of nep330, [nep330 1.1.0 standard recording](https://www.youtube.com/watch?v=pBLN9UyE6AA) actually discusses nep351 pub standards: Vec, + /// Optional details that are required for formal contract WASM build reproducibility verification + /// + /// This field is an addition of **1.2.0** **NEP-330** revision + pub build_info: Option, } -#[derive(Debug, Serialize, Deserialize, PartialEq, Clone)] +/// NEAR Standard implementation descriptor following [NEP-330](https://github.com/near/NEPs/blob/master/neps/nep-0330.md) +#[derive(Debug, Clone, PartialEq, Eq, Default, Serialize, Deserialize)] #[serde(crate = "near_sdk::serde")] pub struct Standard { + /// Standard name in lowercase NEP format + /// + /// ## Examples: + /// + /// ```rust,no_run + /// # let standard: String = + /// // for fungible tokens + /// "nep141".into() + /// # ; + /// ``` pub standard: String, + /// Implemented standard version using semantic versioning + /// + /// ## Examples: + /// + /// ```rust,no_run + /// # let version: String = + /// // for initial release + /// "1.0.0".into() + /// # ; + /// ``` pub version: String, } + +mod build_info { + use near_sdk::serde::{Deserialize, Serialize}; + + #[derive(Debug, Clone, PartialEq, Eq, Default, Serialize, Deserialize)] + #[serde(crate = "near_sdk::serde")] + pub struct BuildInfo { + /// Reference to a reproducible build environment docker image + /// + /// ## Examples: + /// + /// ```rust,no_run + /// # let build_environment: String = + /// "sourcescan/cargo-near:0.13.3-rust-1.84.0@sha256:722198ddb92d1b82cbfcd3a4a9f7fba6fd8715f4d0b5fb236d8725c4883f97de".into() + /// # ; + /// ``` + pub build_environment: String, + /// The exact command that was used to build the contract, with all the flags + /// + /// ## Examples: + /// + /// ```rust,no_run + /// # let build_command: Vec = + /// vec![ + /// "cargo".into(), + /// "near".into(), + /// "build".into(), + /// "non-reproducible-wasm".into(), + /// "--locked".into() + /// ] + /// # ; + /// ``` + pub build_command: Vec, + /// Relative path to contract crate within the source code + /// + /// ## Examples: + /// + /// ```rust,no_run + /// # let contract_path: String = + /// "near/omni-prover/wormhole-omni-prover-proxy".into() + /// # ; + /// ``` + /// ```rust,no_run + /// # let contract_path: String = + /// // root of a repo + /// "".into() + /// # ; + /// ``` + pub contract_path: String, + /// Reference to the source code snapshot that was used to build the contract + /// + /// ## Examples: + /// + /// ```rust,no_run + /// # let source_code_snapshot: String = + /// "git+https://github.com/org/repo?rev=8d8a8a0fe86a1d8eb3bce45f04ab1a65fecf5a1b".into() + /// # ; + /// ``` + pub source_code_snapshot: String, + } +} From a69d2cffdcbab02f154f06dffe747576dbac609f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?dj8yf0=CE=BCl?= Date: Fri, 31 Jan 2025 02:08:29 +0200 Subject: [PATCH 2/4] ci: fmt --- near-contract-standards/src/contract_metadata.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/near-contract-standards/src/contract_metadata.rs b/near-contract-standards/src/contract_metadata.rs index 3e1296117..0924693e3 100644 --- a/near-contract-standards/src/contract_metadata.rs +++ b/near-contract-standards/src/contract_metadata.rs @@ -6,7 +6,7 @@ use near_sdk::serde::{Deserialize, Serialize}; /// Contract source metadata follows [**NEP-330 standard**](https://github.com/near/NEPs/blob/master/neps/nep-0330.md) for smart contracts /// /// See documentation of [`near_api::types::contract::ContractSourceMetadata`](https://docs.rs/near-api/latest/near_api/types/contract/struct.ContractSourceMetadata.html) -/// and [`near_api::Contract::contract_source_metadata`](https://docs.rs/near-api/latest/near_api/struct.Contract.html#method.contract_source_metadata) +/// and [`near_api::Contract::contract_source_metadata`](https://docs.rs/near-api/latest/near_api/struct.Contract.html#method.contract_source_metadata) /// on how to query this piece of data from a contract via `near_api` crate #[derive(Debug, Clone, PartialEq, Eq, Default, Serialize, Deserialize)] #[serde(crate = "near_sdk::serde")] From 99309ea72b51614d3fa2fc8a8352c3ac9bbb1ba4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?dj8yf0=CE=BCl?= Date: Fri, 31 Jan 2025 02:15:08 +0200 Subject: [PATCH 3/4] remove noise --- near-contract-standards/src/contract_metadata.rs | 10 ++-------- 1 file changed, 2 insertions(+), 8 deletions(-) diff --git a/near-contract-standards/src/contract_metadata.rs b/near-contract-standards/src/contract_metadata.rs index 0924693e3..3be71f9fc 100644 --- a/near-contract-standards/src/contract_metadata.rs +++ b/near-contract-standards/src/contract_metadata.rs @@ -13,10 +13,6 @@ use near_sdk::serde::{Deserialize, Serialize}; pub struct ContractSourceMetadata { /// Optional version identifier, typically a semantic version /// - /// **NOTE**: - /// As of **NEP-330** standard version **1.2.0** - /// this field may or may not be consistent with [`Self::link`] and with [`BuildInfo::source_code_snapshot`], but only [`BuildInfo::source_code_snapshot`] defines source code for formal reproducibility verification, and [`Self::link`] and [`Self::version`] do not - /// /// ## Examples: /// /// ```rust,no_run @@ -28,10 +24,6 @@ pub struct ContractSourceMetadata { pub version: Option, /// Optional URL to source code repository/tree /// - /// **NOTE**: - /// As of **NEP-330** standard version **1.2.0** - /// this field may or may not be consistent with [`Self::version`] and with [`BuildInfo::source_code_snapshot`], but only [`BuildInfo::source_code_snapshot`] defines source code for formal reproducibility verification, and [`Self::link`] and [`Self::version`] do not - /// /// ## Examples: /// /// ```rust,no_run @@ -106,6 +98,8 @@ pub struct Standard { mod build_info { use near_sdk::serde::{Deserialize, Serialize}; + /// Defines all required details for formal WASM build reproducibility verification + /// according to [**NEP-330 standard**](https://github.com/near/NEPs/blob/master/neps/nep-0330.md) #[derive(Debug, Clone, PartialEq, Eq, Default, Serialize, Deserialize)] #[serde(crate = "near_sdk::serde")] pub struct BuildInfo { From f13180eb2b034c5d5b469a42841ce04741db315d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?dj8yf0=CE=BCl?= Date: Mon, 3 Feb 2025 16:32:44 +0200 Subject: [PATCH 4/4] review: comments --- .../src/contract_metadata.rs | 18 +++++++++++++++--- 1 file changed, 15 insertions(+), 3 deletions(-) diff --git a/near-contract-standards/src/contract_metadata.rs b/near-contract-standards/src/contract_metadata.rs index 3be71f9fc..765d47142 100644 --- a/near-contract-standards/src/contract_metadata.rs +++ b/near-contract-standards/src/contract_metadata.rs @@ -21,6 +21,12 @@ pub struct ContractSourceMetadata { /// Some("1.0.0".into()) /// # ; /// ``` + /// ```rust,no_run + /// # let version: Option = + /// // Git commit + /// Some("39f2d2646f2f60e18ab53337501370dc02a5661c".into()) + /// # ; + /// ``` pub version: Option, /// Optional URL to source code repository/tree /// @@ -29,13 +35,19 @@ pub struct ContractSourceMetadata { /// ```rust,no_run /// # let link: Option = /// // GitHub URL - /// Some("https://github.com/near-examples/nft-tutorial".into()) + /// Some("https://github.com/org/repo/tree/8d8a8a0fe86a1d8eb3bce45f04ab1a65fecf5a1b".into()) /// # ; /// ``` /// ```rust,no_run /// # let link: Option = /// // GitHub URL - /// Some("https://github.com/org/repo/tree/8d8a8a0fe86a1d8eb3bce45f04ab1a65fecf5a1b".into()) + /// Some("https://github.com/near-examples/nft-tutorial".into()) + /// # ; + /// ``` + /// ```rust,no_run + /// # let link: Option = + /// // IPFS CID + /// Some("bafybeiemxf5abjwjbikoz4mc3a3dla6ual3jsgpdr4cjr3oz3evfyavhwq".into()) /// # ; /// ``` pub link: Option, @@ -99,7 +111,7 @@ mod build_info { use near_sdk::serde::{Deserialize, Serialize}; /// Defines all required details for formal WASM build reproducibility verification - /// according to [**NEP-330 standard**](https://github.com/near/NEPs/blob/master/neps/nep-0330.md) + /// according to [**NEP-330 standard 1.2.0 revision**](https://github.com/near/NEPs/blob/master/neps/nep-0330.md) #[derive(Debug, Clone, PartialEq, Eq, Default, Serialize, Deserialize)] #[serde(crate = "near_sdk::serde")] pub struct BuildInfo {