[BLOCK-2536] update on-chain data docs (#252)

* [BLOCK-2536] update on-chain data docs

* BLOCK-2536 - Update documentation and descriptor

* BLOCK-2536 - Add documentation for missing table fields

---------

Co-authored-by: Igor Sikachyna <[email protected]>

docs/.vitepress/sidebars/base.ts

@@ -90,6 +90,11 @@ const sidebar: { [key: string]: DefaultTheme.SidebarItem[] } = {
             items: getMarkdownFiles('/tutorials/uniq-factories/uniq-auction'),
             collapsed: true,
         },
+        {
+            text: 'Uniq On-chain Data',
+            items: getMarkdownFiles('/tutorials/uniq-factories/uniq-on-chain-data'),
+            collapsed: true,
+        },
         {
             text: 'Token Swap',
             items: getMarkdownFiles('/tutorials/token-swap'),
@@ -270,6 +275,11 @@ const sidebar: { [key: string]: DefaultTheme.SidebarItem[] } = {
             items: getMarkdownFiles('/tutorials/uniq-factories/uniq-auction'),
             collapsed: true,
         },
+        {
+            text: 'Uniq On-chain Data',
+            items: getMarkdownFiles('/tutorials/uniq-factories/uniq-on-chain-data'),
+            collapsed: true,
+        },
     ],
     '/tutorials/token-swap': [
         {

docs/blockchain/contracts/nft-contract/nft-actions/addkeys.a.experimental.md

@@ -0,0 +1,123 @@
+---
+title: 'addkeys.a'
+order: 49
+
+---
+
+# addkeys.a
+
+Add key pairs for Uniq factory
+
+## Technical Behavior
+
+The manager of an Uniq factory should be able to add one or more key pairs at the factory level at any time, which means key pairs at the factory level can change over time. When that happens, all Uniqs minted from that factory should be able to use all key pairs no matter when minted.
+
+Key `name` has to be unique.
+
+Key `type` is the data type of the value, and it has to be in the supported list from `keytypes` table.
+
+`edit_rights` define which permission can edit the value including manager | owner | authorized editor | user group.
+
+`editor` this is authorized editor mentioned above, and it required to have at least one account here.
+
+`default_value` has to match the key `type`, like integer if it's `uint` or `int`. Also, if the type is an array, total element cannot exceed the limit from [`keytypes` action](./setktypes.md). In case of the `string` or `string[]`, total character cannot exceed the limit.
+
+Factory RAM payment will be calculated based on the usage of `key_defs` which include some fixed RAM usage and usage which will determined by the key `type`. And the payment is non-refundable.
+
+Uniq RAM payment for the new key will be calculated based on how many Uniq are already minted from factory. And this payment will be put into factory on-chain RAM vault, which will be refunded when Uniq is burn.
+
+## Action Parameters
+
+The properties of this type are provided below:
+
+| Property Name | C++ Type                     | JavaScript Type | Description                                                                             |
+| ------------- | ---------------------------- | --------------- | --------------------------------------------------------------------------------------- |
+| factory_id    | uint64_t                     | Number          | ID of the Uniq factory for which key pairs will be added.                               |
+| key_defs      | std::vector\<key_def_action> | Object[]        | The definition of the key including name, type, edit right, editors and default values. |
+| memo          | string                       | String          | Memo                                                                                    |
+
+### `key_def_action` interface
+
+| Property Name | C++ Type                        | JavaScript Type | Description                                                                                               |
+| ------------- | ------------------------------- | --------------- | --------------------------------------------------------------------------------------------------------- |
+| name          | string                          | String          | The name of the key, needs to be unique.                                                                  |
+| type          | string                          | String          | The type of the value stored in the key.                                                                  |
+| edit_rights   | uint8_t                         | Number          | Bitmask, determines who can edit the key including asset manager, owner, authorized editor or user group. |
+| editors       | std::vector\<name>              | String[]        | The editor if authorized editor is set.                                                                   |
+| default_value | std::optional\<key_value_store> | Object          | The default value of the key which needs to match with type.                                              |
+
+`key_value_store` will be an array with first element is type of the value and second is the value. Here is the support list and example:
+
+| Value Type | Key Def Type string | Example                    |
+| ---------- | ------------------- | -------------------------- |
+| int8       | int8                | ["int8", 0]                |
+| int16      | int16               | ["int16", 0]               |
+| int32      | int32               | ["int32", 0]               |
+| int64      | int64               | ["int64", 0]               |
+| uint8      | uint8               | ["uint8", 0]               |
+| uint16     | uint16              | ["uint16", 0]              |
+| uint32     | uint32              | ["uint32", 0]              |
+| uint64     | uint64              | ["uint64", 0]              |
+| float      | float               | ["float", 0.1]             |
+| double     | double              | ["double", 0.1]            |
+| string     | string              | ["string", "a"]            |
+| INT8_VEC   | int8[]              | ["INT8_VEC", [0,1,2]]      |
+| INT16_VEC  | int16[]             | ["INT16_VEC", [0,1,2]]     |
+| INT32_VEC  | int32[]             | ["INT32_VEC", [0,1,2]]     |
+| INT64_VEC  | int64[]             | ["INT64_VEC", [0,1,2]]     |
+| UINT8_VEC  | uint8[]             | ["UINT8_VEC", [0,1,2]]     |
+| UINT16_VEC | uint16[]            | ["UINT16_VEC", [0,1,2]]    |
+| UINT32_VEC | uint32[]            | ["UINT32_VEC", [0,1,2]]    |
+| UINT64_VEC | uint64[]            | ["UINT64_VEC", [0,1,2]]    |
+| FLOAT_VEC  | float[]             | ["FLOAT_VEC", [0.1,1.2]]   |
+| DOUBLE_VEC | double[]            | ["DOUBLE_VEC", [0.1,1.2]]  |
+| STRING_VEC | string[]            | ["STRING_VEC", ["a", "b"]] |
+
+### `edit_rights` bitmask breakdown
+
+| Value  | Description                                   |
+| ------ | --------------------------------------------- |
+| `0x01` | Manager can edit                              |
+| `0x02` | Owner can edit                                |
+| `0x04` | Authorized editor can edit (used with `0x08`) |
+| `0x08` | Editor is a user group                        |
+
+## CLI - cleos
+
+```bash
+cleos push action eosio.nft.ft addkeys.a '{ "factory_id": "10", "key_defs": [ { "name": "id", "type": "uint8[]", "edit_rights": 8, "editors": [ "bob" ], "default_value": [ "UINT8_VEC", [0, 1] ] } ], "memo": "new key pairs" }' -p alice@active
+```
+
+## JavaScript - eosjs
+
+```js
+await transact(
+    [
+        {
+            account: 'eosio.nft.ft',
+            name: 'addkeys.a',
+            authorization: [{ actor: 'alice', permission: 'active' }],
+            data: {
+                factory_id: 10,
+                key_defs: [{
+                    name: "id",
+                    type: "uint8[]",
+                    edit_rights: 8,
+                    editors: [
+                        "bob"
+                    ],
+                    default_value: [
+                        "UINT8_VEC",
+                        [0, 1]
+                    ]
+                }],
+                "memo": "add new key pairs"
+            },
+        },
+    ],
+    {
+        blocksBehind: 3,
+        expireSeconds: 30,
+    }
+);
+```

docs/blockchain/contracts/nft-contract/nft-actions/setktypes.experimental.md

@@ -0,0 +1,109 @@
+---
+title: 'setktypes'
+order: 48
+
+---
+
+# setktypes.a
+
+Update supported value type for on chain data
+
+## Technical Behavior
+
+Here is the default table of supported value type and its limit.
+
+| C++ Type   | Type string | Limit by element |
+| ---------- | ----------- | ---------------- |
+| int8       | int8        | 1                |
+| int16      | int16       | 1                |
+| int32      | int32       | 1                |
+| int64      | int64       | 1                |
+| uint8      | uint8       | 1                |
+| uint16     | uint16      | 1                |
+| uint32     | uint32      | 1                |
+| uint64     | uint64      | 1                |
+| float      | float       | 1                |
+| double     | double      | 1                |
+| string     | string      | 128              |
+| INT8_VEC   | int8[]      | 128              |
+| INT16_VEC  | int16[]     | 64               |
+| INT32_VEC  | int32[]     | 32               |
+| INT64_VEC  | int64[]     | 16               |
+| UINT8_VEC  | uint8[]     | 128              |
+| UINT16_VEC | uint16[]    | 64               |
+| UINT32_VEC | uint32[]    | 32               |
+| UINT64_VEC | uint64[]    | 16               |
+| FLOAT_VEC  | float[]     | 32               |
+| DOUBLE_VEC | double[]    | 16               |
+| STRING_VEC | string[]    | 256              |
+
+**Note**: In case of `string` and `string[]`, it will count the total characters instead.
+
+Only Ultra will have authority to update this list.
+
+`key_types` can only extend the default list, cannot change the type name and its order, since we use this order to store type index in factory's keys.
+
+## Action Parameters
+
+The properties of this type are provided below:
+
+| Property Name | C++ Type                    | JavaScript Type | Description                        |
+| ------------- | --------------------------- | --------------- | ---------------------------------- |
+| key_types     | std::vector\<key_type_info> | Object[]        | The key types that will be updated |
+
+### `key_type_info` interface
+
+| Property Name        | C++ Type | JavaScript Type | Description                                                                             |
+| -------------------- | -------- | --------------- | --------------------------------------------------------------------------------------- |
+| key_type             | string   | String          | The name of the key, needs to be unique.                                                |
+| element_number_limit | uint16_t | Number          | The maximum number of entries allowed in dynamic types. For static types defaults to 1. |
+
+## CLI - cleos
+
+```bash
+cleos push action eosio.nft.ft setktypes '{ "key_types": [ {"key_type": "int8", "element_number_limit": 1}, {"key_type": "int16", "element_number_limit": 1}, {"key_type": "int32", "element_number_limit": 1}, {"key_type": "int64", "element_number_limit": 1}, {"key_type": "uint8", "element_number_limit": 1}, {"key_type": "uint16", "element_number_limit": 1}, {"key_type": "uint32", "element_number_limit": 1}, {"key_type": "uint64", "element_number_limit": 1}, {"key_type": "float", "element_number_limit": 1}, {"key_type": "double", "element_number_limit": 1}, {"key_type": "string", "element_number_limit": 128}, {"key_type": "int8[]", "element_number_limit": 128}, {"key_type": "int16[]", "element_number_limit": 64}, {"key_type": "int32[]", "element_number_limit": 32}, {"key_type": "int64[]", "element_number_limit": 16}, {"key_type": "uint8[]", "element_number_limit": 128}, {"key_type": "uint16[]", "element_number_limit": 64}, {"key_type": "uint32[]", "element_number_limit": 32}, {"key_type": "uint64[]", "element_number_limit": 16}, {"key_type": "float[]", "element_number_limit": 32}, {"key_type": "double[]", "element_number_limit": 16}, {"key_type": "string[]", "element_number_limit": 256} ] }' -p ultra.nft.ft@active
+```
+
+## JavaScript - eosjs
+
+```js
+await transact(
+    [
+        {
+            account: 'eosio.nft.ft',
+            name: 'addkeys.a',
+            authorization: [{ actor: 'ultra.nft.ft', permission: 'active' }],
+            data: {
+                key_types: [
+                    {key_type: "int8", element_number_limit: 1},
+                    {key_type: "int16", element_number_limit: 1},
+                    {key_type: "int32", element_number_limit: 1},
+                    {key_type: "int64", element_number_limit: 1},
+                    {key_type: "uint8", element_number_limit: 1},
+                    {key_type: "uint16", element_number_limit: 1},
+                    {key_type: "uint32", element_number_limit: 1},
+                    {key_type: "uint64", element_number_limit: 1},
+                    {key_type: "float", element_number_limit: 1},
+                    {key_type: "double", element_number_limit: 1},
+                    {key_type: "string", element_number_limit: 128},
+                    {key_type: "int8[]", element_number_limit: 128},
+                    {key_type: "int16[]", element_number_limit: 64},
+                    {key_type: "int32[]", element_number_limit: 32},
+                    {key_type: "int64[]", element_number_limit: 16},
+                    {key_type: "uint8[]", element_number_limit: 128},
+                    {key_type: "uint16[]", element_number_limit: 64},
+                    {key_type: "uint32[]", element_number_limit: 32},
+                    {key_type: "uint64[]", element_number_limit: 16},
+                    {key_type: "float[]", element_number_limit: 32},
+                    {key_type: "double[]", element_number_limit: 16},
+                    {key_type: "string[]", element_number_limit: 256}
+                ]
+            },
+        },
+    ],
+    {
+        blocksBehind: 3,
+        expireSeconds: 30,
+    }
+);
+```

docs/blockchain/contracts/nft-contract/nft-actions/setvals.a.experimental.md

@@ -0,0 +1,105 @@
+---
+title: 'setvals.a'
+order: 50
+
+---
+
+# setvals.a
+
+Set key values of an Uniq
+
+## Technical Behavior
+
+Before setting values, the key have to be defined in factory with [`addkeys.a` action](./addkeys.a.md)
+
+Only editor including owner | manager | authorized editor can update Uniq's values if the edit right is configured for them.
+
+The key value will only store in Uniq, and will be stored as key index and key value. Key index will be referred to factory key definition list.
+
+In `key_values`, `key_name` must be unique and existed in factory keys. `key_value` must match the type defined in factory keys.
+
+If no `editor` is included, owner will be the editor and the editor also need to sign the contract.
+
+No RAM payment requires for this action since it's already paid in factory level.
+
+## Action Parameters
+
+The properties of this type are provided below:
+
+| Property Name | C++ Type              | JavaScript Type | Description                                   |
+| ------------- | --------------------- | --------------- | --------------------------------------------- |
+| owner         | name                  | String          | Onwer of the Uniq                             |
+| editor        | optional\<name>       | String          | The authorized editor of the key              |
+| token_id      | uint64_t              | Number          | The ID of the Uniq that value will be updated |
+| key_values    | key_values_action_vec | Object[]        | The list of key name and value for updating   |
+| memo          | string                | String          | Memo                                          |
+
+`key_values_action_vec` is the vector of `key_values_action`
+
+### `key_values_action` interface
+
+| Property Name | C++ Type        | JavaScript Type | Description                                                                                    |
+| ------------- | --------------- | --------------- | ---------------------------------------------------------------------------------------------- |
+| key_name      | string          | String          | The name of the key defined in factory keys.                                                   |
+| key_value     | key_value_store | Object[]        | The value that will be set for the key. Value needs to match the type defined in factory keys. |
+
+`key_value_store` will be an array with first element is type of the value and second is the value. Here is the support list and example:
+
+| Value Type | Key Def Type string | Example                    |
+| ---------- | ------------------- | -------------------------- |
+| int8       | int8                | ["int8", 0]                |
+| int16      | int16               | ["int16", 0]               |
+| int32      | int32               | ["int32", 0]               |
+| int64      | int64               | ["int64", 0]               |
+| uint8      | uint8               | ["uint8", 0]               |
+| uint16     | uint16              | ["uint16", 0]              |
+| uint32     | uint32              | ["uint32", 0]              |
+| uint64     | uint64              | ["uint64", 0]              |
+| float      | float               | ["float", 0.1]             |
+| double     | double              | ["double", 0.1]            |
+| string     | string              | ["string", "a"]            |
+| INT8_VEC   | int8[]              | ["INT8_VEC", [0,1,2]]      |
+| INT16_VEC  | int16[]             | ["INT16_VEC", [0,1,2]]     |
+| INT32_VEC  | int32[]             | ["INT32_VEC", [0,1,2]]     |
+| INT64_VEC  | int64[]             | ["INT64_VEC", [0,1,2]]     |
+| UINT8_VEC  | uint8[]             | ["UINT8_VEC", [0,1,2]]     |
+| UINT16_VEC | uint16[]            | ["UINT16_VEC", [0,1,2]]    |
+| UINT32_VEC | uint32[]            | ["UINT32_VEC", [0,1,2]]    |
+| UINT64_VEC | uint64[]            | ["UINT64_VEC", [0,1,2]]    |
+| FLOAT_VEC  | float[]             | ["FLOAT_VEC", [0.1,1.2]]   |
+| DOUBLE_VEC | double[]            | ["DOUBLE_VEC", [0.1,1.2]]  |
+| STRING_VEC | string[]            | ["STRING_VEC", ["a", "b"]] |
+
+## CLI - cleos
+
+```bash
+cleos push action eosio.nft.ft setvals.a '{ "owner": "alice", "editor": null, "token_id": 8, "keys_values": [ "key_name": "keyname", "key_value": [ "uint8", 3 ] ], "memo": "set key value" }' -p alice@active
+```
+
+## JavaScript - eosjs
+
+```js
+await transact(
+    [
+        {
+            account: 'eosio.nft.ft',
+            name: 'addkeys.a',
+            authorization: [{ actor: 'alice', permission: 'active' }],
+            data:  {
+                owner: "alice",
+                editor: null,
+                token_id: 8,
+                keys_values: [
+                    key_name: "keyname",
+                    key_value: [ "uint8", 3 ]
+                ],
+                "memo": "set key value"
+            },
+        },
+    ],
+    {
+        blocksBehind: 3,
+        expireSeconds: 30,
+    }
+);
+```