--- a/client/rpc/src/lib.rs +++ b/client/rpc/src/lib.rs @@ -42,7 +42,7 @@ #[rpc(server)] #[async_trait] pub trait UniqueApi { - /// Get tokens owned by account + /// Get tokens owned by account. #[method(name = "unique_accountTokens")] fn account_tokens( &self, @@ -51,7 +51,7 @@ at: Option, ) -> Result>; - /// Get tokens contained in collection + /// Get tokens contained within a collection. #[method(name = "unique_collectionTokens")] fn collection_tokens( &self, @@ -59,7 +59,7 @@ at: Option, ) -> Result>; - /// Check if token exists + /// Check if the token exists. #[method(name = "unique_tokenExists")] fn token_exists( &self, @@ -68,7 +68,7 @@ at: Option, ) -> Result; - /// Get token owner + /// Get the token owner. #[method(name = "unique_tokenOwner")] fn token_owner( &self, @@ -77,7 +77,7 @@ at: Option, ) -> Result>; - /// Get token owner, in case of nested token - find the parent recursively + /// Get the topmost token owner in the hierarchy of a possibly nested token. #[method(name = "unique_topmostTokenOwner")] fn topmost_token_owner( &self, @@ -86,7 +86,7 @@ at: Option, ) -> Result>; - /// Get tokens nested directly into the token + /// Get tokens nested directly into the token. #[method(name = "unique_tokenChildren")] fn token_children( &self, @@ -95,7 +95,7 @@ at: Option, ) -> Result>; - /// Get collection properties + /// Get collection properties, optionally limited to the provided keys. #[method(name = "unique_collectionProperties")] fn collection_properties( &self, @@ -104,7 +104,7 @@ at: Option, ) -> Result>; - /// Get token properties + /// Get token properties, optionally limited to the provided keys. #[method(name = "unique_tokenProperties")] fn token_properties( &self, @@ -114,7 +114,7 @@ at: Option, ) -> Result>; - /// Get property permissions + /// Get property permissions, optionally limited to the provided keys. #[method(name = "unique_propertyPermissions")] fn property_permissions( &self, @@ -123,7 +123,7 @@ at: Option, ) -> Result>; - /// Get token data + /// Get token data, including properties, optionally limited to the provided keys, and total pieces for an RFT. #[method(name = "unique_tokenData")] fn token_data( &self, @@ -133,11 +133,11 @@ at: Option, ) -> Result>; - /// Get amount of unique collection tokens + /// Get the amount of distinctive tokens present in a collection. #[method(name = "unique_totalSupply")] fn total_supply(&self, collection: CollectionId, at: Option) -> Result; - /// Get owned amount of any user tokens + /// Get the amount of any user tokens owned by an account. #[method(name = "unique_accountBalance")] fn account_balance( &self, @@ -146,7 +146,7 @@ at: Option, ) -> Result; - /// Get owned amount of specific account token + /// Get the amount of a specific token owned by an account. #[method(name = "unique_balance")] fn balance( &self, @@ -156,7 +156,7 @@ at: Option, ) -> Result; - /// Get allowed amount + /// Get the amount of currently possible sponsored transactions on a token for the fee to be taken off a sponsor. #[method(name = "unique_allowance")] fn allowance( &self, @@ -167,7 +167,7 @@ at: Option, ) -> Result; - /// Get admin list + /// Get the list of admin accounts of a collection. #[method(name = "unique_adminlist")] fn adminlist( &self, @@ -175,7 +175,7 @@ at: Option, ) -> Result>; - /// Get allowlist + /// Get the list of accounts allowed to operate within a collection. #[method(name = "unique_allowlist")] fn allowlist( &self, @@ -183,7 +183,7 @@ at: Option, ) -> Result>; - /// Check if user is allowed to use collection + /// Check if a user is allowed to operate within a collection. #[method(name = "unique_allowed")] fn allowed( &self, @@ -192,11 +192,11 @@ at: Option, ) -> Result; - /// Get last token ID created in a collection + /// Get the last token ID created in a collection. #[method(name = "unique_lastTokenId")] fn last_token_id(&self, collection: CollectionId, at: Option) -> Result; - /// Get collection by specified ID + /// Get collection info by the specified ID. #[method(name = "unique_collectionById")] fn collection_by_id( &self, @@ -204,11 +204,11 @@ at: Option, ) -> Result>>; - /// Get collection stats + /// Get chain stats about collections. #[method(name = "unique_collectionStats")] fn collection_stats(&self, at: Option) -> Result; - /// Get number of blocks when sponsored transaction is available + /// Get the number of blocks until sponsoring a transaction is available. #[method(name = "unique_nextSponsored")] fn next_sponsored( &self, @@ -218,7 +218,7 @@ at: Option, ) -> Result>; - /// Get effective collection limits + /// Get effective collection limits. If not explicitly set, get the chain defaults. #[method(name = "unique_effectiveCollectionLimits")] fn effective_collection_limits( &self, @@ -226,7 +226,7 @@ at: Option, ) -> Result>; - /// Get total pieces of token + /// Get the total amount of pieces of an RFT. #[method(name = "unique_totalPieces")] fn total_pieces( &self, @@ -253,20 +253,20 @@ Theme, > { + /// Get the latest created collection ID. #[method(name = "rmrk_lastCollectionIdx")] - /// Get the latest created collection id fn last_collection_idx(&self, at: Option) -> Result; + /// Get collection info by ID. #[method(name = "rmrk_collectionById")] - /// Get collection by id fn collection_by_id( &self, id: RmrkCollectionId, at: Option, ) -> Result>; + /// Get NFT info by collection and NFT IDs. #[method(name = "rmrk_nftById")] - /// Get NFT by collection id and NFT id fn nft_by_id( &self, collection_id: RmrkCollectionId, @@ -274,8 +274,8 @@ at: Option, ) -> Result>; + /// Get tokens owned by an account in a collection. #[method(name = "rmrk_accountTokens")] - /// Get tokens owned by an account in a collection fn account_tokens( &self, account_id: AccountId, @@ -283,8 +283,8 @@ at: Option, ) -> Result>; + /// Get tokens nested in an NFT - its direct children (not the children's children). #[method(name = "rmrk_nftChildren")] - /// Get NFT children fn nft_children( &self, collection_id: RmrkCollectionId, @@ -292,8 +292,8 @@ at: Option, ) -> Result>; + /// Get collection properties, created by the user - not the proxy-specific properties. #[method(name = "rmrk_collectionProperties")] - /// Get collection properties fn collection_properties( &self, collection_id: RmrkCollectionId, @@ -301,8 +301,8 @@ at: Option, ) -> Result>; + /// Get NFT properties, created by the user - not the proxy-specific properties. #[method(name = "rmrk_nftProperties")] - /// Get NFT properties fn nft_properties( &self, collection_id: RmrkCollectionId, @@ -311,8 +311,8 @@ at: Option, ) -> Result>; + /// Get data of resources of an NFT. #[method(name = "rmrk_nftResources")] - /// Get NFT resources fn nft_resources( &self, collection_id: RmrkCollectionId, @@ -320,8 +320,8 @@ at: Option, ) -> Result>; + /// Get the priority of a resource in an NFT. #[method(name = "rmrk_nftResourcePriority")] - /// Get NFT resource priority fn nft_resource_priority( &self, collection_id: RmrkCollectionId, @@ -330,24 +330,24 @@ at: Option, ) -> Result>; + /// Get base info by its ID. #[method(name = "rmrk_base")] - /// Get base info fn base(&self, base_id: RmrkBaseId, at: Option) -> Result>; + /// Get all parts of a base. #[method(name = "rmrk_baseParts")] - /// Get all Base's parts fn base_parts(&self, base_id: RmrkBaseId, at: Option) -> Result>; + /// Get the theme names belonging to a base. #[method(name = "rmrk_themeNames")] - /// Get Base's theme names fn theme_names( &self, base_id: RmrkBaseId, at: Option, ) -> Result>; + /// Get theme info, including properties, optionally limited to the provided keys. #[method(name = "rmrk_themes")] - /// Get Theme info -- name, properties, and inherit flag fn theme( &self, base_id: RmrkBaseId, --- a/primitives/data-structs/src/lib.rs +++ b/primitives/data-structs/src/lib.rs @@ -367,32 +367,37 @@ /// Limits and restrictions of a collection. /// All fields are wrapped in `Option`s, where None means chain default. -// When adding/removing fields from this struct - don't forget to also update clamp_limits +/// +/// todo:doc links to chain defaults +// IMPORTANT: When adding/removing fields from this struct - don't forget to also +// update clamp_limits() in pallet-common. #[derive(Encode, Decode, Debug, Default, Clone, PartialEq, TypeInfo, MaxEncodedLen)] #[cfg_attr(feature = "serde1", derive(Serialize, Deserialize))] pub struct CollectionLimits { - /// Maximum number of owned tokens per account + /// Maximum number of owned tokens per account. Chain default: [`ACCOUNT_TOKEN_OWNERSHIP_LIMIT`] pub account_token_ownership_limit: Option, - /// Maximum size of data of a sponsored transaction + /// Maximum size of data in bytes of a sponsored transaction. Chain default: [`CUSTOM_DATA_LIMIT`] pub sponsored_data_size: Option, /// FIXME should we delete this or repurpose it? /// None - setVariableMetadata is not sponsored /// Some(v) - setVariableMetadata is sponsored /// if there is v block between txs + /// + /// In any case, chain default: [`SponsoringRateLimit::SponsoringDisabled`] pub sponsored_data_rate_limit: Option, - /// Maximum amount of tokens inside the collection + /// Maximum amount of tokens inside the collection. Chain default: [`COLLECTION_TOKEN_LIMIT`] pub token_limit: Option, - /// Timeout for sponsoring a token transfer in passed blocks + /// Timeout for sponsoring a token transfer in passed blocks. Chain default: [`MAX_SPONSOR_TIMEOUT`] pub sponsor_transfer_timeout: Option, - /// Timeout for sponsoring an approval in passed blocks + /// Timeout for sponsoring an approval in passed blocks. Chain default: [`SPONSOR_APPROVE_TIMEOUT`] pub sponsor_approve_timeout: Option, - /// Can a token be transferred by the owner + /// Can a token be transferred by the owner. Chain default: `false` pub owner_can_transfer: Option, - /// Can a token be burned by the owner + /// Can a token be burned by the owner. Chain default: `true` pub owner_can_destroy: Option, - /// Can a token be transferred at all + /// Can a token be transferred at all. Chain default: `true` pub transfers_enabled: Option, } @@ -445,7 +450,10 @@ } } -// When adding/removing fields from this struct - don't forget to also update clamp_limits +/// Permissions on certain operations within a collection. +/// All fields are wrapped in `Option`s, where None means chain default. +// IMPORTANT: When adding/removing fields from this struct - don't forget to also +// update clamp_limits() in pallet-common. #[derive(Encode, Decode, Debug, Default, Clone, PartialEq, TypeInfo, MaxEncodedLen)] #[cfg_attr(feature = "serde1", derive(Serialize, Deserialize))] pub struct CollectionPermissions { @@ -500,6 +508,7 @@ } } +/// Part of collection permissions, if set, defines who is able to nest tokens into other tokens. #[derive(Encode, Decode, Clone, PartialEq, TypeInfo, MaxEncodedLen, Derivative)] #[cfg_attr(feature = "serde1", derive(Serialize, Deserialize))] #[derivative(Debug)] @@ -516,14 +525,17 @@ pub permissive: bool, } +/// Enum denominating how often can sponsoring occur if it is enabled. #[derive(Encode, Decode, Debug, Clone, Copy, PartialEq, TypeInfo, MaxEncodedLen)] #[cfg_attr(feature = "serde1", derive(Serialize, Deserialize))] pub enum SponsoringRateLimit { + /// Sponsoring is disabled, and the collection sponsor will not pay for transactions SponsoringDisabled, /// Once per how many blocks can sponsorship of a transaction type occur Blocks(u32), } +/// Data used to describe an NFT at creation. #[derive(Encode, Decode, MaxEncodedLen, Default, PartialEq, Clone, Derivative, TypeInfo)] #[cfg_attr(feature = "serde1", derive(Serialize, Deserialize))] #[derivative(Debug)] @@ -534,17 +546,20 @@ pub properties: CollectionPropertiesVec, } +/// Data used to describe a Fungible token at creation. #[derive(Encode, Decode, MaxEncodedLen, Default, Debug, Clone, PartialEq, TypeInfo)] #[cfg_attr(feature = "serde1", derive(Serialize, Deserialize))] pub struct CreateFungibleData { - /// Number of fungible tokens minted + /// Number of fungible coins minted pub value: u128, } +/// Data used to describe a Refungible token at creation. #[derive(Encode, Decode, MaxEncodedLen, Default, PartialEq, Clone, Derivative, TypeInfo)] #[cfg_attr(feature = "serde1", derive(Serialize, Deserialize))] #[derivative(Debug)] pub struct CreateReFungibleData { + /// Immutable metadata of the token #[cfg_attr(feature = "serde1", serde(with = "bounded::vec_serde"))] #[derivative(Debug(format_with = "bounded::vec_debug"))] pub const_data: BoundedVec, @@ -560,6 +575,7 @@ None, } +/// Enum holding data used for creation of all three item types. #[derive(Encode, Decode, MaxEncodedLen, PartialEq, Clone, Debug, TypeInfo)] #[cfg_attr(feature = "serde1", derive(Serialize, Deserialize))] pub enum CreateItemData { --- a/tests/src/interfaces/unique/definitions.ts +++ b/tests/src/interfaces/unique/definitions.ts @@ -37,48 +37,123 @@ export default { types: {}, rpc: { - adminlist: fun('Get admin list', [collectionParam], 'Vec'), - allowlist: fun('Get allowlist', [collectionParam], 'Vec'), + accountTokens: fun( + 'Get tokens owned by an account in a collection', + [collectionParam, crossAccountParam()], + 'Vec', + ), + collectionTokens: fun( + 'Get tokens contained within a collection', + [collectionParam], + 'Vec', + ), + tokenExists: fun( + 'Check if the token exists', + [collectionParam, tokenParam], + 'bool', + ), - accountTokens: fun('Get tokens owned by account', [collectionParam, crossAccountParam()], 'Vec'), - collectionTokens: fun('Get tokens contained in collection', [collectionParam], 'Vec'), + tokenOwner: fun( + 'Get the token owner', + [collectionParam, tokenParam], + `Option<${CROSS_ACCOUNT_ID_TYPE}>`, + ), + topmostTokenOwner: fun( + 'Get the topmost token owner in the hierarchy of a possibly nested token', + [collectionParam, tokenParam], + `Option<${CROSS_ACCOUNT_ID_TYPE}>`, + ), + tokenChildren: fun( + 'Get tokens nested directly into the token', + [collectionParam, tokenParam], + 'Vec', + ), - lastTokenId: fun('Get last token ID created in a collection', [collectionParam], 'u32'), - totalSupply: fun('Get amount of unique collection tokens', [collectionParam], 'u32'), - accountBalance: fun('Get owned amount of any user tokens', [collectionParam, crossAccountParam()], 'u32'), - balance: fun('Get owned amount of specific account token', [collectionParam, crossAccountParam(), tokenParam], 'u128'), - allowance: fun('Get allowed amount', [collectionParam, crossAccountParam('sender'), crossAccountParam('spender'), tokenParam], 'u128'), - tokenOwner: fun('Get token owner', [collectionParam, tokenParam], `Option<${CROSS_ACCOUNT_ID_TYPE}>`), - topmostTokenOwner: fun('Get token owner, in case of nested token - find the parent recursively', [collectionParam, tokenParam], `Option<${CROSS_ACCOUNT_ID_TYPE}>`), - tokenChildren: fun('Get tokens nested directly into the token', [collectionParam, tokenParam], 'Vec'), - constMetadata: fun('Get token constant metadata', [collectionParam, tokenParam], 'Vec'), - variableMetadata: fun('Get token variable metadata', [collectionParam, tokenParam], 'Vec'), collectionProperties: fun( - 'Get collection properties', + 'Get collection properties, optionally limited to the provided keys', [collectionParam, propertyKeysParam], 'Vec', ), tokenProperties: fun( - 'Get token properties', + 'Get token properties, optionally limited to the provided keys', [collectionParam, tokenParam, propertyKeysParam], 'Vec', ), propertyPermissions: fun( - 'Get property permissions', + 'Get property permissions, optionally limited to the provided keys', [collectionParam, propertyKeysParam], 'Vec', ), + tokenData: fun( - 'Get token data', + 'Get token data, including properties, optionally limited to the provided keys, and total pieces for an RFT', [collectionParam, tokenParam, propertyKeysParam], 'UpDataStructsTokenData', ), - tokenExists: fun('Check if token exists', [collectionParam, tokenParam], 'bool'), - collectionById: fun('Get collection by specified ID', [collectionParam], 'Option'), - collectionStats: fun('Get collection stats', [], 'UpDataStructsCollectionStats'), - allowed: fun('Check if user is allowed to use collection', [collectionParam, crossAccountParam()], 'bool'), - nextSponsored: fun('Get number of blocks when sponsored transaction is available', [collectionParam, crossAccountParam(), tokenParam], 'Option'), - effectiveCollectionLimits: fun('Get effective collection limits', [collectionParam], 'Option'), - totalPieces: fun('Get total pieces of token', [collectionParam, tokenParam], 'Option'), + totalSupply: fun( + 'Get the amount of distinctive tokens present in a collection', + [collectionParam], + 'u32', + ), + + accountBalance: fun( + 'Get the amount of any user tokens owned by an account', + [collectionParam, crossAccountParam()], + 'u32', + ), + balance: fun( + 'Get the amount of a specific token owned by an account', + [collectionParam, crossAccountParam(), tokenParam], + 'u128', + ), + allowance: fun( + 'Get the amount of currently possible sponsored transactions on a token for the fee to be taken off a sponsor', + [collectionParam, crossAccountParam('sender'), crossAccountParam('spender'), tokenParam], + 'u128', + ), + + adminlist: fun( + 'Get the list of admin accounts of a collection', + [collectionParam], + 'Vec', + ), + allowlist: fun( + 'Get the list of accounts allowed to operate within a collection', + [collectionParam], + 'Vec', + ), + allowed: fun( + 'Check if a user is allowed to operate within a collection', + [collectionParam, crossAccountParam()], + 'bool', + ), + + lastTokenId: fun('Get the last token ID created in a collection', [collectionParam], 'u32'), + collectionById: fun( + 'Get a collection by the specified ID', + [collectionParam], + 'Option', + ), + collectionStats: fun( + 'Get chain stats about collections', + [], + 'UpDataStructsCollectionStats', + ), + + nextSponsored: fun( + 'Get the number of blocks until sponsoring a transaction is available', + [collectionParam, crossAccountParam(), tokenParam], + 'Option', + ), + effectiveCollectionLimits: fun( + 'Get effective collection limits', + [collectionParam], + 'Option', + ), + totalPieces: fun( + 'Get the total amount of pieces of an RFT', + [collectionParam, tokenParam], + 'Option', + ), }, };