Merge pull request #255 from ultraio/feature/BLOCK-2584-add-token-tax…

…-burn-metadata

[BLOCK-2584] Add token tax, burn and metadata

docs/.vitepress/navbar.ts

@@ -15,6 +15,7 @@ const navbar: DefaultTheme.NavItem[] = [
                     { text: 'Smart Contracts', link: '/tutorials/smart-contracts/index' },
                     { text: 'Uniq Factories', link: '/tutorials/uniq-factories/index' },
                     { text: 'Token Swap', link: '/tutorials/token-swap/index' },
+                    { text: 'Fungitable Token', link: '/tutorials/token/index' },
                 ],
             },
         ],

docs/.vitepress/sidebars/base.ts

@@ -100,6 +100,11 @@ const sidebar: { [key: string]: DefaultTheme.SidebarItem[] } = {
             items: getMarkdownFiles('/tutorials/token-swap'),
             collapsed: true,
         },
+        {
+            text: 'Fungitable Token',
+            items: getMarkdownFiles('/tutorials/token'),
+            collapsed: true,
+        },
         {
             text: 'Oracle',
             items: getMarkdownFiles('/tutorials/oracle'),
@@ -296,6 +301,22 @@ const sidebar: { [key: string]: DefaultTheme.SidebarItem[] } = {
             items: getMarkdownFiles('/tutorials/token-swap'),
         },
     ],
+    '/tutorials/token': [
+        {
+            text: 'Tutorials',
+            items: [
+                {
+                    text: '< Go Back to Tutorials',
+                    link: '/tutorials/index/index',
+                },
+            ],
+        },
+        {
+            text: 'Fungitable Token',
+            items: getMarkdownFiles('/tutorials/token'),
+            collapsed: false,
+        },
+    ],
     '/tutorials/oracle': [
         {
             text: 'Tutorials',

docs/blockchain/contracts/token-contract/token-actions/configburn.experimental.md

@@ -0,0 +1,57 @@
+---
+title: 'configburn'
+order: 7
+
+---
+
+# configburn
+
+This action will allow token `issuer` to config the `trigger_supply` and when token supply surpass this any transfer will be applied with `rate_bp` tax except for `whitelisted_accounts`. All burnt amounts will be deducted to token supply.
+
+-   Parameters
+
+| Fields                 | Type                      | Description                                                    |
+| ---------------------- | ------------------------- | -------------------------------------------------------------- |
+| `trigger_supply`       | eosio::asset              | The threshold supply for when burn will be applied to transfer |
+| `rate_bp`              | uint16_t                  | The rate where burn will be applied in basis where 1 is 0.01%  |
+| `whitelisted_accounts` | std::vector\<eosio::name> | The accounts will be exempted from burn                        |
+
+Required Permissions: `issuer` or `ultra`
+
+-   `cleos` Example
+
+```shell script
+cleos push action eosio.token configburn '["6,BURN", 1000, '["account1", "account2"]']' -p issuer
+```
+
+-   `eos-js` Example
+
+```typescript
+(async () => {
+    const result = await api.transact(
+        {
+            actions: [
+                {
+                    account: 'eosio.token',
+                    name: 'configburn',
+                    authorization: [
+                        {
+                            actor: 'issuer',
+                            permission: 'active',
+                        },
+                    ],
+                    data: {
+                        trigger_supply: '6,BURN',
+                        rate_bp: 1000,
+                        whitelisted_accounts: ['account1', 'account2'],
+                    },
+                },
+            ],
+        },
+        {
+            blocksBehind: 3,
+            expireSeconds: 30,
+        }
+    );
+})();
+```

docs/blockchain/contracts/token-contract/token-actions/configtax.experimental.md

@@ -0,0 +1,59 @@
+---
+title: 'configtax'
+order: 8
+
+---
+
+# configtax
+
+This action will allow token `issuer` to config the `trigger_supply` and when token supply surpass this, any transfer will be applied with `rate_bp` tax except for `whitelisted_accounts`. All tax amount will be transferred to `tax_receiver`.
+
+-   Parameters
+
+| Fields                 | Type                      | Description                                                   |
+| ---------------------- | ------------------------- | ------------------------------------------------------------- |
+| `trigger_supply`       | eosio::asset              | The threshold supply for when tax will be applied to transfer |
+| `rate_bp`              | uint16_t                  | The rate where tax will be applied in basis where 1 is 0.01%  |
+| `tax_receiver`         | eosio::name               | The account where tax will be transfer to                     |
+| `whitelisted_accounts` | std::vector\<eosio::name> | The accounts will be exempted from tax                        |
+
+Required Permissions: `issuer` or `ultra`
+
+-   `cleos` Example
+
+```shell script
+cleos push action eosio.token configtax '["8,TAX", 100, "taxreceiver", '["account1", "account2"]']' -p issuer
+```
+
+-   `eos-js` Example
+
+```typescript
+(async () => {
+    const result = await api.transact(
+        {
+            actions: [
+                {
+                    account: 'eosio.token',
+                    name: 'configtax',
+                    authorization: [
+                        {
+                            actor: 'issuer',
+                            permission: 'active',
+                        },
+                    ],
+                    data: {
+                        trigger_supply: '8,TAX',
+                        rate_bp: 100,
+                        tax_receiver: 'taxreceiver',
+                        whitelisted_accounts: ['account1', 'account2'],
+                    },
+                },
+            ],
+        },
+        {
+            blocksBehind: 3,
+            expireSeconds: 30,
+        }
+    );
+})();
+```

docs/blockchain/contracts/token-contract/token-actions/updatemeta.experimental.md

@@ -0,0 +1,61 @@
+---
+title: 'updatemeta'
+order: 6
+
+---
+
+# updatemeta
+
+Update token with `symbol` with metadata including `name`, `icon` URL, `description` and `color`.
+
+-   Parameters
+
+| Fields        | Type          | Description                    |
+| ------------- | ------------- | ------------------------------ |
+| `symbol`      | eosio::symbol | The symbol of the token        |
+| `name`        | eosio::name   | The name of the token          |
+| `icon`        | string        | The URL of token's icon        |
+| `description` | string        | The description of the token   |
+| `color`       | uint32_t      | The display color of the token |
+
+Required Permissions: `issuer` or `ultra`
+
+-   `cleos` Example
+
+```shell script
+cleos push action eosio.token updatemeta '["4,META", "Meta", "http://token.icon", "Token Metadata", 0]' -p issuer
+```
+
+-   `eos-js` Example
+
+```typescript
+(async () => {
+    const result = await api.transact(
+        {
+            actions: [
+                {
+                    account: 'eosio.token',
+                    name: 'updatemeta',
+                    authorization: [
+                        {
+                            actor: 'issuer',
+                            permission: 'active',
+                        },
+                    ],
+                    data: {
+                        symbol: '4,META',
+                        name: 'Meta',
+                        icon: 'http://token.icon',
+                        description: 'Token Metadata',
+                        color: 0,
+                    },
+                },
+            ],
+        },
+        {
+            blocksBehind: 3,
+            expireSeconds: 30,
+        }
+    );
+})();
+```

docs/blockchain/contracts/token-contract/token_tables.experimental.md

@@ -0,0 +1,121 @@
+---
+title: 'Token Tables'
+order: 1
+
+---
+
+# Token Tables
+
+## accounts
+
+Store all account balance created by this contract
+
+-   Code: `eosio.token`
+-   Table: `accounts`
+-   Scope: `user`
+-   Key: `symbol_raw_value`
+-   Data
+
+| Fields    | Type         | Description   |
+| --------- | ------------ | ------------- |
+| `balance` | eosio::asset | Token balance |
+
+-   `cleos` Query Example
+
+```shell script
+cleos get table eosio.token <USER> accounts
+```
+
+-   `curl` query example
+
+```shell script
+curl <NODEOS_API_IP>/v1/chain/get_table_rows -X POST -d '{"scope":"<USER>", "code":"eosio.token", "table":"accounts", "json": true}'
+```
+
+## stat
+
+Store token supply created by this contract
+
+-   Code: `eosio.token`
+-   Table: `stat`
+-   Scope: `symbol_raw_value`
+-   Key: `symbol_raw_value`
+-   Data
+
+| Fields       | Type         | Description            |
+| ------------ | ------------ | ---------------------- |
+| `supply`     | eosio::asset | Available token supply |
+| `max_supply` | eosio::asset | Maximum token supply   |
+| `issuer`     | eosio::name  | Issuer of this token   |
+
+-   `cleos` Query Example
+
+```shell script
+cleos get table eosio.token <SYMBOL_RAW_VALUE> stat
+```
+
+-   `curl` query example
+
+```shell script
+curl <NODEOS_API_IP>/v1/chain/get_table_rows -X POST -d '{"scope":"<SYMBOL_RAW_VALUE>", "code":"eosio.token", "table":"stat", "json": true}'s
+```
+
+## metadata
+
+Store token metadata
+
+-   Code: `eosio.token`
+-   Table: `metadata`
+-   Scope: `symbol_raw_value`
+-   Key: `symbol_raw_value`
+-   Data
+
+| Fields        | Type          | Description                    |
+| ------------- | ------------- | ------------------------------ |
+| `symbol`      | eosio::symbol | The symbol of the token        |
+| `name`        | eosio::name   | The name of the token          |
+| `icon`        | string        | The URL of token's icon        |
+| `description` | string        | The description of the token   |
+| `color`       | uint32_t      | The display color of the token |
+
+-   `cleos` Query Example
+
+```shell script
+cleos get table eosio.token <SYMBOL_RAW_VALUE> metadata
+```
+
+-   `curl` query example
+
+```shell script
+curl <NODEOS_API_IP>/v1/chain/get_table_rows -X POST -d '{"scope":"<SYMBOL_RAW_VALUE>", "code":"eosio.token", "table":"metadata", "json": true}'s
+```
+
+## tokenconfig
+
+Store token strategy configuration
+
+-   Code: `eosio.token`
+-   Table: `tokenconfig`
+-   Scope: `symbol_raw_value`
+-   Key: `symbol_raw_value`
+-   Data
+
+| Fields                 | Type                      | Description                                                                                   |
+| ---------------------- | ------------------------- | --------------------------------------------------------------------------------------------- |
+| `trigger_supply`       | eosio::asset              | The threshold supply for when strategy will be applied to transfer                            |
+| `strategy`             | uint16_t                  | The strategy will be used to decide which config to use tax or burn. 0 nothing, 1 burn, 2 tax |
+| `rate_bp`              | uint16_t                  | The rate where strategy will be applied in basis where 1 is 0.01%                             |
+| `tax_receiver`         | eosio::name               | The account where tax will be transfer to                                                     |
+| `whitelisted_accounts` | std::vector\<eosio::name> | The accounts will be exempted from strategy                                                   |
+
+-   `cleos` Query Example
+
+```shell script
+cleos get table eosio.token <SYMBOL_RAW_VALUE> tokenconfig
+```
+
+-   `curl` query example
+
+```shell script
+curl <NODEOS_API_IP>/v1/chain/get_table_rows -X POST -d '{"scope":"<SYMBOL_RAW_VALUE>", "code":"eosio.token", "table":"tokenconfig", "json": true}'s
+```

docs/tutorials/token/index.md

@@ -0,0 +1,10 @@
+---
+title: 'Token Overview'
+
+outline: [0, 4]
+order: 0
+---
+
+# Token
+
+A fungible token is token system that is built in Ultra.

docs/tutorials/token/token-burn.experimental.md

@@ -0,0 +1,34 @@
+---
+title: 'Token Burn'
+
+outline: [0,4]
+order: 2
+---
+
+# Token Burn Overview
+
+## Overview
+
+Token burn will allow the token creator to apply burn policy on any transfer made with specific token.
+
+When token supply reach certain level, any transfer will be burnt with specific percentage, which is set by token creator.
+
+Sender can be added to whitelist and will be exempted from any burn.
+
+The burnt token amount will be deducted directly from recipient and transfer to configured receiver.
+
+Also burn amount will be deducted directly to token current supply.
+
+Actual burnt amount will be capped to make sure token supply will never go below the trigger threshold.
+
+Only token creator and Ultra can set burn config for creator's token.
+
+Once burn config is set for token, you cannot switch to other strategy.
+
+Usage of the actions for config token burn
+
+-   [configburn - Add or update burn config for token](../../blockchain/contracts/token-contract/token-actions/configburn.md)
+
+## Benefits
+
+- Allow token creator have more flexible policy with their token