diff --git a/docs/.vuepress/configs/sidebar.ts b/docs/.vuepress/configs/sidebar.ts index 4dc7821..8052b90 100644 --- a/docs/.vuepress/configs/sidebar.ts +++ b/docs/.vuepress/configs/sidebar.ts @@ -178,12 +178,13 @@ export const sidebar: Record = { { text: 'Blockchain API', children: [ - '/reference/blockchain/rpc.md', - '/reference/blockchain/extrinsics.md', - '/reference/blockchain/events.md', + '/reference/blockchain/collections.md', + '/reference/blockchain/properties.md', '/reference/blockchain/nesting.md', '/reference/blockchain/owner-admin-roles.md', - ], + '/reference/blockchain/rpc.md', + '/reference/blockchain/extrinsics.md', + '/reference/blockchain/events.md', ], }, ], }, diff --git a/docs/build/sdk/C_sharp.md b/docs/_archive/C_sharp.md similarity index 100% rename from docs/build/sdk/C_sharp.md rename to docs/_archive/C_sharp.md diff --git a/docs/build/sdk/android.md b/docs/_archive/android.md similarity index 100% rename from docs/build/sdk/android.md rename to docs/_archive/android.md diff --git a/docs/build/sdk/ios.md b/docs/_archive/ios.md similarity index 100% rename from docs/build/sdk/ios.md rename to docs/_archive/ios.md diff --git a/docs/_todo/collection-limits.md b/docs/_todo/collection-limits.md deleted file mode 100644 index 71c468d..0000000 --- a/docs/_todo/collection-limits.md +++ /dev/null @@ -1,37 +0,0 @@ -# Collection limits - -**accountTokenOwnershipLimit: u32** - -The maximum number of tokens that one address can own - -**sponsoredDataSize: u32** - -The maximum byte size of custom token data that can be sponsored when tokens are minted in sponsored mode - -**sponsoredDataRateLimit: UpDataStructsSponsoringRateLimit** - -Defines how many blocks need to pass between setVariableMetadata transactions in order for them to be sponsored - -**tokenLimit: u32** - -The total amount of tokens that can be minted in this collection - -**sponsorTransferTimeout: u32** - -The time interval in blocks that defines once per how long a non-privileged user transfer or mint transaction can be sponsored - -**sponsorApproveTimeout: u32** - -The time interval in blocks that defines once per how long a non-privileged user approve transaction can be sponsored - -**ownerCanTransfer: bool** - -Boolean value that tells if collection owner or admins can transfer or burn tokens owned by other non-privileged users - -**ownerCanDestroy: bool** - -Boolean value that shows whether collection owner can destroy it - -**transfersEnabled: bool** - -The flag that defines whether token transfers between users are currently enabled \ No newline at end of file diff --git a/docs/reference/blockchain/collections.md b/docs/reference/blockchain/collections.md new file mode 100644 index 0000000..17b6c36 --- /dev/null +++ b/docs/reference/blockchain/collections.md @@ -0,0 +1,108 @@ +# Collection data + +[[toc]] + +## name, description, tokenPrefix + +These properties define the basic metadata required for each collection. + +- `name` - 64 bytes max +- `description` - 256 bytes max +- `tokenPrefix` - 16 bytes max + +## mode + + +- `NFT` - Non-fungible tokens format by Unique Network. ERC-721 compatible. +- `ReFungible` - essentially a non-fungible token (NFT) with a unique ability: partial ownership +- `Fungible` - fungible tokens format by Unique Network. ERC-20 compatible. + +## limits + +#### `accountTokenOwnershipLimit: u32` +The maximum number of tokens that one address can own + +#### `sponsoredDataSize: u32` + +The maximum byte size of custom token data that can be sponsored when tokens are minted in sponsored mode + +#### `sponsoredDataRateLimit: UpDataStructsSponsoringRateLimit` + +Defines how many blocks need to pass between setVariableMetadata transactions in order for them to be sponsored + +#### `tokenLimit: u32` + +The total amount of tokens that can be minted in this collection + +#### `sponsorTransferTimeout: u32` + +The time interval in blocks that defines once per how long a non-privileged user transfer or mint transaction can be sponsored + +#### `sponsorApproveTimeout: u32` + +The time interval in blocks defines once per how long a non-privileged user approve transaction can be sponsored. + +#### `ownerCanTransfer: bool` + +Boolean value that tells if the collection owner or admins can transfer or burn tokens owned by other non-privileged users +#### `ownerCanDestroy: bool` +Boolean value that shows whether the collection owner can destroy it +#### `transfersEnabled: bool` + +The flag that defines whether token transfers between users are currently enabled + +## permissions + +#### `access` +- `Normal` - default value. No extra permissions or limitations +- `AllowList` - only accounts added to the allow list (`unique.addToAllowList`) can own tokens. Also, these accounts can mint tokens if mint mode permission is set to true. +#### `mintMode` +Default to false. Add permission to mint tokens to addresses added to the AllowList +#### `nesting` +- `tokenOwner` - default to false. Allows nesting to token owner +- `collectionAdmin` - default to false. Allows nesting to collection administrators and collection owner +- `restricted` - default to null. Specifies collection IDs allowed for nesting + +Read more about [nesting](./nesting.md) + +## tokenPropertyPermissions + +Defines two main aspects: + +- Lists the properties that an NFT can have. A maximum of 64 properties can be set +- Defines who can or cannot change these properties + +This permission affects the following groups of methods in the unique pallet: +- Token creation: `createItem`, `createMultipleItems`, `createMultipleItemsEx` +- Token property management: `deleteTokenProperties`, `setTokenProperties` + +Here’s what these permissions mean: +- `mutable` – whether a token’s property can be set or overwritten after minting. It only makes sense if at least one of the following properties is set to true. +- `collectionAdmin` – whether a collection administrator can set a token’s property. +- `tokenOwner` – whether a token’s owner can set its property. + +Examples: +1) `{mutable: false, collectionAdmin: true, tokenOwner: false}` +Only the collection administrator can set the token’s property at the time of token creation. + +2) `{mutable: true, collectionAdmin: true, tokenOwner: true}` +The collection administrator and the token owner can set the token’s property at the time of the collection’s creation and through token property management methods. + +3) `{mutable: true, collectionAdmin: false, tokenOwner: true}` +Only the token owner can set the token’s property. If an administrator mints a token to their own address, they can set the property as the token owner. If the administrator mints a token to another address, only the new owner can set the property after the token is created. + +4) `{mutable: false, collectionAdmin: false, tokenOwner: false}` +No one can ever set the token’s property. + +Read more about [token properties](./properties.md) + +## properties + +Set of key/value pairs defined on a collection level. The maximum number of keys is 64. The maximum size of a parameter data block (keys and values) is 40kB. + +Read more about [collection properties](./properties.md) + +## adminList + +The list of privileged accounts. Read more about [roles and access rights](./owner-admin-roles.md) + diff --git a/docs/reference/blockchain/nesting.md b/docs/reference/blockchain/nesting.md index d72968a..349792d 100644 --- a/docs/reference/blockchain/nesting.md +++ b/docs/reference/blockchain/nesting.md @@ -1,4 +1,4 @@ -# Nesting and properties +# Nesting [[toc]] @@ -12,7 +12,7 @@ api.tx.unique.setCollectionPermissions(ACollectionId, { }); ``` -With the nesting enabled, tokens can be nested as long as they share a common owner, but they can belong to different collections. So in a case where tokens A1 and B1 share a common owner, a token from collection B (B1) can be nested under a token in collection A (A1). To reiterate an important point, the collections need not have a common owner. +With the nesting enabled, tokens can be nested as long as they share a common owner, but they can belong to different collections. So in a case where tokens A1 and B1 share a common owner, a token from collection B (B1) can be nested under a token in collection A (A1). However, this behavior can be restricted by imposing a list of allowed collections. This would ensure that only tokens from a restricted list of collections (defined by the collection IDs) can be nested: @@ -38,9 +38,9 @@ api.tx.unique.setCollectionPermissions(ACollectionId, { ); ``` -Administrators can nest only tokens owned by them to the managed collection’s tokens. However, they can nest into a token that is owned by someone else (owner or another administrator). If an administrator imposes a collection restriction list, this list will also extend to the owner, i.e. the owner must also obey collection restriction rules set forth by the administrator. +Administrators can only nest tokens they own to the managed collection's tokens. However, they can nest into a token that is owned by someone else (owner or another administrator). If an administrator imposes a collection restriction list, this list will also extend to the owner, i.e. the owner must also obey collection restriction rules set forth by the administrator. -To disable nesting we would use: +To disable nesting, we would use: ```javascript api.tx.unique.setCollectionPermissions(ACollectionId, { @@ -92,7 +92,7 @@ By invoking this function with the ids of collection A and token A1, a response >[{token: A2, collection: A}, {token: B1, collection: B}] -As presented in this example the `tokenChildren` lists only A1 and B2 as they are direct, or first generation, or layer 1 of nesting depth descendants. Token B2 is a second generation descendant, or a layer 2 nested token. However, B2 will appear as a result of a call invoked with ids for collection B and token B1. +As presented in this example, the `tokenChildren` lists only A1 and B2 as they are direct, or first generation, or layer 1 of nesting depth descendants. Token B2 is a second-generation descendant or a layer two nested token. However, B2 will appear as a result of a call invoked with ids for collection B and token B1. ## Notes @@ -113,96 +113,3 @@ So in the example provided below, to burn the token A3 which is the root of a br ![Nesting diagram 2](./nesting_diagram_02.png) Non-empty collections cannot be burned. - - - -## Collection and Token Properties - -Properties (hereinafter also referred to as 'parameters') of NFT collections and tokens are implemented in the blockchain as a BTreeMap data storage block. - -Furthermore, this BTreeMap consists of a unique set of keys and values which are defined by the owner or administrator of a collection. - -Each token of a collection inherits a list of common key/value pairs that can be attributed/set for that token and that are defined for that collection (listed in `tokenPropertyPermissions` - see below). A token cannot be attributed an arbitrary key, only a key from this list. But setting of an attribute's value is optional. An attribute can remain 'unset', i.e. there is no default value that is automatically set for a newly created token. If the user has the permissions that allow setting of properties, they may set and change the values of the token's keys. - -The parameter block is restricted by both the data size and the number of keys. The maximum number of keys is 64 for both the collections and tokens. The maximum size of a parameter data block (keys and values) for a collection is 40kB and for a token 32kB. - -Key naming is restricted to a limited set of the following characters: Latin letter any case, numbers, dot, hyphen and underscore (regex: ^[0-9a-zA-Z\.\-_]). - -Only the owner and designated administrators can modify the properties of a collection. - -Access to changing token parameters is based on access rights to token keys stored in the collection (`tokenPropertyPermissions`). - -Only the owner and designated administrators of a collection can add and modify keys. - -Keys can only be added. To avoid token corruption, a key cannot be removed once it is created/added. Although keys can't be deleted we can delete the values attributed to a key if the key is mutable. - -A value of a key can be changed by the owner/administrator only if it has not been declared as an immutable key ('mutable' attribute set to _false_). - -A note on the mutability attribute: if it is set to _false_ token data can only be set once. Immutable data stays immutable forever. Furthermore, the mutable attribute can be changed only from _true_ to _false_. Changing it from _false_ to _true_ is not possible. - -In summary, the configuration or permissions to create and modify properties of a collection is carried out using three keys - `mutable`, `collectionAdmin` and `tokenOwner`. - -- `mutable` attribute sets the immutability attribute. -- `collectionAdmin` grants the designated collection administrator and the collection owner 'write/modify' access -- `tokenOwner` grants the token owner 'write/modify' access - - -## RPC Methods - -### 🔶 collectionProperties - -Obtain collection properties array. - -```javascript -api.rpc.unique.collectionProperties(collectionId) -``` - -Returns an array of objects: `{key: string, value: string}` - -### 🔶 propertyPermissions - -Get property permissions array. - -```javascript -api.rpc.unique.propertyPermissions(collectionId) -``` - -Returns an array of objects: `{key: string, permission: {mutable: bool, tokenOwner: bool, collectionAdmin: bool}}` - -### 🔶 tokenData - -Get token data. - -Invoke: - -```javascript -api.rpc.unique.tokenData(collectionId, tokenId) -``` -with key `properties`. - -### 🔶 tokenProperties - -Token properties can also be obtained via the dedicated `tokenProperties` method: - -```javascript -api.rpc.unique.tokenProperties(collectionId, tokenId) -``` - -Returns an array of objects: `{key: string, value: string}` - -## Migrations for Existing Quartz Collections - -These collection fields have been deprecated and are not supported with the most recent upgrade to the blockchain: -- `schemaVersion` -- `offchainSchema` -- `constOnChainSchema` -- `variableOnChainSchema` - -For the existing collections, these fields have been moved to the corresponding property keys prefixed by '\_old\_'. - -The following token fields have been deprecated and are no longer supported with the new properties schema: -- `variableData` -- `constData` - -For the existing tokens, `constData` has been moved to `_old_constData`. - \ No newline at end of file diff --git a/docs/reference/blockchain/owner-admin-roles.md b/docs/reference/blockchain/owner-admin-roles.md index 7145b0e..59dc24b 100644 --- a/docs/reference/blockchain/owner-admin-roles.md +++ b/docs/reference/blockchain/owner-admin-roles.md @@ -2,7 +2,7 @@ ## Collection admins and collection owners Collection admins and collection owners access rights are listed in following table -| | Collection owner | Collection admin | +||Collection owner|Collection admin| |------------------------------------------------------------------------------------|:----------------------------------------------------------------------------------------------------------------------------------------------------------:|:---------------------------------------------------------------------------------------------------------------------------------------------------------:| | [addCollectionAdmin](/networks/extrinsics.html#addcollectionadmin) | ✅ | ❌ | | [addToAllowList](/networks/extrinsics.html#addtoallowlist) | ✅ | ✅ | @@ -33,7 +33,7 @@ Collection admins and collection owners access rights are listed in following ta | [transferFrom](/networks/extrinsics.html#transferfrom) | ✅
only if ownerCanTransfer: true | ✅
only if ownerCanTransfer: true | ## Token owners -| | Token owner | +||Token owner | |------------------------------------------------------------------------------------|:---------------------------------------------------------------------------------------------------------------------------------------------------:| | [addCollectionAdmin](/networks/extrinsics.html#addcollectionadmin) | ❌ | | [addToAllowList](/networks/extrinsics.html#addtoallowlist) | ❌ | diff --git a/docs/reference/blockchain/properties.md b/docs/reference/blockchain/properties.md new file mode 100644 index 0000000..1857531 --- /dev/null +++ b/docs/reference/blockchain/properties.md @@ -0,0 +1,73 @@ +# Collection and Token Properties + +Properties of NFT collections and tokens are implemented in the blockchain as a BTreeMap data storage block. + +Furthermore, this BTreeMap consists of a unique set of keys and values that are defined by the owner or administrator of a collection. + +Each token of a collection inherits a list of common key/value pairs that can be set for that token and that are defined for that collection (listed in `tokenPropertyPermissions` - see below). A token cannot be attributed to an arbitrary key; only a key from this list can be added. But the setting of a key's value is optional and can remain 'unset,' i.e., there is no default value that is automatically set for a newly created token. If the user has the permissions that allow the setting of properties, they may set and change the values of the token's keys. + +The parameter block is restricted by both the data size and the number of keys. The maximum number of keys is 64 for both the collections and tokens. The maximum size of a parameter data block (keys and values) for a collection is 40kB, and for a token, 32kB. + +Key naming is restricted to a limited set of the following characters: Latin letter any case, numbers, dot, hyphen, and underscore (regex: ^[0-9a-zA-Z\.\-_]). + +Only the owner and designated administrators can modify the properties of a collection. + +Access to changing token properties is based on access rights to token keys stored in the collection (`tokenPropertyPermissions`). + +Only the owner and designated administrators of a collection can add and modify keys. + +Keys can only be added. To avoid token corruption, a key cannot be removed once it is created/added. Although keys can't be deleted, we can delete the values attributed to a key if the key is mutable. + +The value of a key can be changed by the owner/administrator only if it has not been declared as an immutable key ('mutable' attribute set to _false_). + +A note on the mutability attribute: if it is set to _false_, token data can only be set once. Immutable data stays immutable forever. Furthermore, the mutable attribute can be changed only from _true_ to _false_. Changing it from _false_ to _true_ is not possible. + +In summary, the configuration or permissions to create and modify properties of a collection is carried out using three keys - `mutable,` `collectionAdmin`, and `tokenOwner.` + +- `mutable` attribute sets the immutability attribute. +- `collectionAdmin` grants the designated collection administrator and the collection owner 'write/modify' access +- `tokenOwner` grants the token owner 'write/modify' access + + +## RPC Methods + +### 🔶 collectionProperties + +Obtain collection properties array. + +```javascript +api.rpc.unique.collectionProperties(collectionId) +``` + +Returns an array of objects: `{key: string, value: string}` + +### 🔶 propertyPermissions + +Get property permissions array. + +```javascript +api.rpc.unique.propertyPermissions(collectionId) +``` + +Returns an array of objects: `{key: string, permission: {mutable: bool, tokenOwner: bool, collectionAdmin: bool}}` + +### 🔶 tokenData + +Get token data. + +Invoke: + +```javascript +api.rpc.unique.tokenData(collectionId, tokenId) +``` +with key `properties`. + +### 🔶 tokenProperties + +Token properties can also be obtained via the dedicated `tokenProperties` method: + +```javascript +api.rpc.unique.tokenProperties(collectionId, tokenId) +``` + +Returns an array of objects: `{key: string, value: string}`