From d13ed0996ee58a4875841c53591fc3a1f62874d4 Mon Sep 17 00:00:00 2001 From: Gregory Roussac Date: Mon, 8 Jul 2024 11:38:53 +0200 Subject: [PATCH] #270 Back port fix from cep-18 + #267 nft_kind should be optional on install + default (#280) * #270 Back port fix from cep-18 #267 nft_kind should be optional on install + default * clippy * Update doc * Revert in get_optional_named_arg_with_user_errors --- README.md | 3 +-- client-js/TUTORIAL.md | 10 +++++----- contract/src/main.rs | 9 +++------ contract/src/modalities.rs | 2 ++ contract/src/utils.rs | 3 ++- docs/modalities.md | 5 ++--- 6 files changed, 15 insertions(+), 17 deletions(-) diff --git a/README.md b/README.md index 21989055..fc568d09 100644 --- a/README.md +++ b/README.md @@ -48,7 +48,6 @@ The following are the required runtime arguments that must be passed to the inst - `"collection_symbol"`: The symbol representing a given NFT collection, passed in as a `String`. This parameter is required and cannot be changed post installation. - `"total_token_supply"`: The total number of NFTs that a specific instance of a contract will mint passed in as a `U64` value. This parameter is required. - `"ownership_mode"`: The [`OwnershipMode`](/docs/modalities.md#ownership) modality that dictates the ownership behavior of the NFT contract. This argument is passed in as a `u8` value and is required at the time of installation. -- `"nft_kind"`: The [`NFTKind`](/docs/modalities.md#nftkind) modality that specifies the off-chain items represented by the on-chain NFT data. This argument is passed in as a `u8` value and is required at the time of installation. - `"json_schema"`: The JSON schema for the NFT tokens that will be minted by the NFT contract passed in as a `String`. This parameter is required if the metadata kind is set to `CustomValidated(3)` and cannot be changed post installation. - `"nft_metadata_kind"`: The base metadata schema for the NFTs to be minted by the NFT contract. This argument is passed in as a `u8` value and is required at the time of installation. - `"identifier_mode"`: The [`NFTIdentifierMode`](/docs/modalities.md#nftidentifiermode) modality dictates the primary identifier for NFTs minted by the contract. This argument is passed in as a `u8` value and is required at the time of installation. @@ -58,7 +57,7 @@ The following are the optional parameters that can be passed in at the time of i - `"minting_mode"`: The [`MintingMode`](/docs/modalities.md#minting) modality that dictates the access to the `mint()` entry-point in the NFT contract. This is an optional parameter that will default to restricting access to the installer of the contract. This parameter cannot be changed once the contract has been installed. - `"allow_minting"`: The `"allow_minting"` flag allows the installer of the contract to pause the minting of new NFTs. The `allow_minting` is a boolean toggle that allows minting when `true`. If not provided at install the toggle will default to `true`. This value can be changed by the installer by calling the `set_variables()` entrypoint. - +- `"nft_kind"`: The [`NFTKind`](/docs/modalities.md#nftkind) modality that specifies the off-chain items represented by the on-chain NFT data. This argument is passed in as a `u8` value and is optional at the time of installation. If not provided at install the toggle will default to `Virtual` This parameter cannot be changed once the contract has been installed. - `"whitelist_mode"`: The [`WhitelistMode`](/docs/modalities.md#whitelistmode) modality dictates whether the contract whitelist can be updated. This optional parameter will default to an unlocked whitelist that can be updated post installation. This parameter cannot be changed once the contract has been installed. - `"holder_mode"`: The [`NFTHolderMode`](/docs/modalities.md#nftholdermode) modality dictates which entities can hold NFTs. This is an optional parameter and will default to a mixed mode allowing either `Accounts` or `Contracts` to hold NFTs. This parameter cannot be changed once the contract has been installed. - `"acl_whitelist"`: The ACL whitelist is a list of accounts and/or contract/package hashes that specifies which accounts and/or contracts can call the `mint()` entrypoint to mint NFTs. This is an optional parameter which will default to an empty whitelist. This value can be changed via the `set_variables` post installation. If the whitelist mode is set to locked, a non-empty whitelist must be passed; else, installation of the contract will fail. diff --git a/client-js/TUTORIAL.md b/client-js/TUTORIAL.md index 2cb9cea6..17e60218 100644 --- a/client-js/TUTORIAL.md +++ b/client-js/TUTORIAL.md @@ -19,7 +19,7 @@ npm install casper-cep78-js-client ## Installing a CEP-78 Contract using the JavaScript Client The `install` method crafts a [Deploy](https://docs.casper.network/deploy-and-deploy-lifecycle/#execution-semantics-deploys) using `InstallArgs`. -As with every deploy created by the SDK, you can send it using the `.send(rpcUrl)` method providing the RPC URL that you want to use. It will return deployHash. +As with every deploy created by the SDK, you can send it using the `.send(rpcUrl)` method providing the RPC URL that you want to use. It will return deployHash. ```js @@ -65,7 +65,7 @@ As with every deploy created by the SDK, you can send it using the `.send(rpcUrl * `ownershipMode` - The `OwnershipMode` modality that dictates the ownership behavior of the NFT contract. This argument is passed in as a `u8` value and is required at the time of installation. -* `nftKind` - The `NFTKind` modality that specifies the off-chain items represented by the on-chain NFT data. This argument is passed in as a `u8` value and is required at the time of installation. +* `nftKind` - The `NFTKind` modality that specifies the off-chain items represented by the on-chain NFT data. This argument is passed in as a `u8` value and is optional at the time of installation. * `jsonSchema` - The JSON schema for the NFT tokens that will be minted by the NFT contract passed in as a `String`. More information on `NFTMetadataKind` can be found [here](../docs/modalities.md#nftmetadatakind). This parameter may be left empty if metadata kind is set to `Raw(3)`. If the metadata kind is set to `CustomValidated(4)`, it will require a specifically formatted custom schema. This parameter **cannot be changed post installation**. @@ -116,7 +116,7 @@ In this example, the [`useSessionCode`](https://github.com/casper-ecosystem/cep- If `OwnerReverseLookupMode` is set to `NoLookup`, `useSessionCode` will be set to `false` and it will simply mint the token as it does not need to register the recipient. -## Register Recipient +## Register Recipient As we used `ownerReverseLookupMode: OwnerReverseLookupMode.Complete` in this contract installation, we must register the recipient. To do this, we construct a `register` deploy: @@ -132,9 +132,9 @@ As we used `ownerReverseLookupMode: OwnerReverseLookupMode.Complete` in this con ); const registerDeployHash = await registerDeploy.send("http://localhost:11101/rpc"); - + ``` - + ## Transferring a Token After minting one or more tokens, you can then use the following code to transfer the tokens between accounts: diff --git a/contract/src/main.rs b/contract/src/main.rs index 12b01b4e..e35ec14f 100644 --- a/contract/src/main.rs +++ b/contract/src/main.rs @@ -2574,12 +2574,9 @@ fn install_contract() { // Refer to the enum `NFTKind` // in the `src/modalities.rs` file for details. // This value cannot be changed after installation. - let nft_kind: u8 = utils::get_named_arg_with_user_errors( - ARG_NFT_KIND, - NFTCoreError::MissingNftKind, - NFTCoreError::InvalidNftKind, - ) - .unwrap_or_revert(); + let nft_kind: u8 = + utils::get_optional_named_arg_with_user_errors(ARG_NFT_KIND, NFTCoreError::InvalidNftKind) + .unwrap_or(NFTKind::default() as u8); // Represents whether Accounts or Contracts, or both can hold NFTs for // a given contract instance. Refer to the enum `NFTHolderMode` diff --git a/contract/src/modalities.rs b/contract/src/modalities.rs index 8d9c11b6..14f25665 100644 --- a/contract/src/modalities.rs +++ b/contract/src/modalities.rs @@ -78,6 +78,7 @@ impl TryFrom for MintingMode { } } +#[derive(PartialEq, Eq, Default, Debug)] #[repr(u8)] pub enum NFTKind { /// The NFT represents a real-world physical @@ -89,6 +90,7 @@ pub enum NFTKind { /// The NFT is the virtual representation /// of a physical notion, e.g a patent /// or copyright. + #[default] Virtual = 2, } diff --git a/contract/src/utils.rs b/contract/src/utils.rs index 05472c77..6c4790a9 100644 --- a/contract/src/utils.rs +++ b/contract/src/utils.rs @@ -148,7 +148,8 @@ pub fn get_optional_named_arg_with_user_errors( ) -> Option { match get_named_arg_with_user_errors::(name, NFTCoreError::Phantom, invalid) { Ok(val) => Some(val), - Err(_) => None, + Err(NFTCoreError::Phantom) => None, + Err(e) => runtime::revert(e), } } diff --git a/docs/modalities.md b/docs/modalities.md index 8d2d355f..c2c45ddd 100644 --- a/docs/modalities.md +++ b/docs/modalities.md @@ -59,7 +59,7 @@ and only exists to specify the correlation between on-chain data and off-chain i 2. `Digital`: The NFT represents a digital item, e.g., a unique JPEG or digital art. 3. `Virtual`: The NFT is the virtual representation of a physical notion, e.g., a patent or copyright. -The `NFTKind` mode is a required installation parameter and cannot be changed once the contract has been installed. +This modality is an optional installation parameter and will default to the `Virtual` mode if not provided. However, this mode cannot be changed once the contract has been installed. The mode is passed in as a `u8` value to `nft_kind` runtime argument. | NFTKind | u8 | @@ -85,8 +85,7 @@ If the `NFTHolderMode` is set to `Contracts` a `ContractHash` whitelist must be | Contracts | 1 | | Mixed | 2 | -This modality is an optional installation parameter and will default to the `Mixed` mode if not provided. However, this -mode cannot be changed once the contract has been installed. +This modality is an optional installation parameter and will default to the `Mixed` mode if not provided. However, this mode cannot be changed once the contract has been installed. The mode is passed in as a `u8` value to `nft_holder_mode` runtime argument. ## WhitelistMode