From 8edfe06c6864ac6c214af65ed5f61e39bebcfbd3 Mon Sep 17 00:00:00 2001 From: Duncan Dam Date: Thu, 21 Nov 2024 15:37:30 +0700 Subject: [PATCH 1/3] [BLOCK-2584] Add token tax, burn and metadata --- docs/.vitepress/navbar.ts | 1 + docs/.vitepress/sidebars/base.ts | 21 +++ .../token-actions/configburn.experimental.md | 57 +++++++++ .../token-actions/configtax.experimental.md | 59 +++++++++ .../token-actions/updatemeta.experimental.md | 61 +++++++++ .../token_tables.experimental.md | 121 ++++++++++++++++++ docs/tutorials/token/index.experimental.md | 10 ++ .../token/token-burn.experimental.md | 34 +++++ .../token/token-metadata.experimental.md | 26 ++++ .../tutorials/token/token-tax.experimental.md | 30 +++++ 10 files changed, 420 insertions(+) create mode 100644 docs/blockchain/contracts/token-contract/token-actions/configburn.experimental.md create mode 100644 docs/blockchain/contracts/token-contract/token-actions/configtax.experimental.md create mode 100644 docs/blockchain/contracts/token-contract/token-actions/updatemeta.experimental.md create mode 100644 docs/blockchain/contracts/token-contract/token_tables.experimental.md create mode 100644 docs/tutorials/token/index.experimental.md create mode 100644 docs/tutorials/token/token-burn.experimental.md create mode 100644 docs/tutorials/token/token-metadata.experimental.md create mode 100644 docs/tutorials/token/token-tax.experimental.md diff --git a/docs/.vitepress/navbar.ts b/docs/.vitepress/navbar.ts index 22414853a2..6a6dd097de 100644 --- a/docs/.vitepress/navbar.ts +++ b/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' }, ], }, ], diff --git a/docs/.vitepress/sidebars/base.ts b/docs/.vitepress/sidebars/base.ts index b0abfeb5ce..794bea1e56 100644 --- a/docs/.vitepress/sidebars/base.ts +++ b/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', diff --git a/docs/blockchain/contracts/token-contract/token-actions/configburn.experimental.md b/docs/blockchain/contracts/token-contract/token-actions/configburn.experimental.md new file mode 100644 index 0000000000..e2ad294958 --- /dev/null +++ b/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\ | 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, + } + ); +})(); +``` diff --git a/docs/blockchain/contracts/token-contract/token-actions/configtax.experimental.md b/docs/blockchain/contracts/token-contract/token-actions/configtax.experimental.md new file mode 100644 index 0000000000..a2dd892312 --- /dev/null +++ b/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\ | 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, + } + ); +})(); +``` diff --git a/docs/blockchain/contracts/token-contract/token-actions/updatemeta.experimental.md b/docs/blockchain/contracts/token-contract/token-actions/updatemeta.experimental.md new file mode 100644 index 0000000000..784534ba98 --- /dev/null +++ b/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, + } + ); +})(); +``` diff --git a/docs/blockchain/contracts/token-contract/token_tables.experimental.md b/docs/blockchain/contracts/token-contract/token_tables.experimental.md new file mode 100644 index 0000000000..dbdd329d02 --- /dev/null +++ b/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 accounts +``` + +- `curl` query example + +```shell script +curl /v1/chain/get_table_rows -X POST -d '{"scope":"", "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 stat +``` + +- `curl` query example + +```shell script +curl /v1/chain/get_table_rows -X POST -d '{"scope":"", "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 metadata +``` + +- `curl` query example + +```shell script +curl /v1/chain/get_table_rows -X POST -d '{"scope":"", "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\ | The accounts will be exempted from strategy | + +- `cleos` Query Example + +```shell script +cleos get table eosio.token tokenconfig +``` + +- `curl` query example + +```shell script +curl /v1/chain/get_table_rows -X POST -d '{"scope":"", "code":"eosio.token", "table":"tokenconfig", "json": true}'s +``` diff --git a/docs/tutorials/token/index.experimental.md b/docs/tutorials/token/index.experimental.md new file mode 100644 index 0000000000..6602779c29 --- /dev/null +++ b/docs/tutorials/token/index.experimental.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. diff --git a/docs/tutorials/token/token-burn.experimental.md b/docs/tutorials/token/token-burn.experimental.md new file mode 100644 index 0000000000..357c385a0f --- /dev/null +++ b/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 \ No newline at end of file diff --git a/docs/tutorials/token/token-metadata.experimental.md b/docs/tutorials/token/token-metadata.experimental.md new file mode 100644 index 0000000000..64152fa25d --- /dev/null +++ b/docs/tutorials/token/token-metadata.experimental.md @@ -0,0 +1,26 @@ +--- +title: 'Token Metadata' + +outline: [0,4] +order: 1 +--- + +# Token Metadata Overview + +## Overview + +Token creator can add metadata for their existing fungitable token, and metadata will include `name`, `icon` URL, `desciption` and `color`. + +Here some limit for metadata: + +- `name` must be more than 2 characters and less than 24 characters, and can only contain alphabet, number, `.` or `_`. + +- `icon` URL and `desciption` cannot have more than 128 characters. + +Usage of the actions for update token metadata + +- [updatemeta - Add or update token metadata](../../blockchain/contracts/token-contract/token-actions/updatemeta.md) + +## Benefits + +- Allow token creator config their own token metadata then later use this for displaying their token if needed. \ No newline at end of file diff --git a/docs/tutorials/token/token-tax.experimental.md b/docs/tutorials/token/token-tax.experimental.md new file mode 100644 index 0000000000..1a9d7c9f74 --- /dev/null +++ b/docs/tutorials/token/token-tax.experimental.md @@ -0,0 +1,30 @@ +--- +title: 'Token Metadata' + +outline: [0,4] +order: 3 +--- + +# Token Metadata Overview + +## Overview + +Token metadata will allow the token creator to include meta data + +When token supply reach certain level, any transfer will be taxed with specific percentage, which is set by token creator. + +Sender can be added to whitelist and will be exempted from any tax. + +The tax amount will be deducted directly from recipient and transfer to configured receiver. + +Only token creator and Ultra can set tax config for creator's token. + +Once tax config is set for token, you cannot switch to other strategy. + +Usage of the actions for config token tax + +- [configtax - Add or update tax config for token](../../blockchain/contracts/token-contract/token-actions/configtax.md) + +## Benefits + +- Allow token creator have more flexible policy with their token \ No newline at end of file From 7607492f33f61fe26433a1f3627a2292ad9f655b Mon Sep 17 00:00:00 2001 From: Duncan Dam Date: Thu, 21 Nov 2024 15:40:17 +0700 Subject: [PATCH 2/3] update --- docs/tutorials/token/token-tax.experimental.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/tutorials/token/token-tax.experimental.md b/docs/tutorials/token/token-tax.experimental.md index 1a9d7c9f74..bf0ba5775b 100644 --- a/docs/tutorials/token/token-tax.experimental.md +++ b/docs/tutorials/token/token-tax.experimental.md @@ -1,15 +1,15 @@ --- -title: 'Token Metadata' +title: 'Token Tax' outline: [0,4] order: 3 --- -# Token Metadata Overview +# Token Tax Overview ## Overview -Token metadata will allow the token creator to include meta data +Token tax will allow the token creator to apply tax policy on any transfer made with specific token. When token supply reach certain level, any transfer will be taxed with specific percentage, which is set by token creator. From 5c5b591ceda5531d5b192072aa6d1a80683baca6 Mon Sep 17 00:00:00 2001 From: Duncan Dam Date: Fri, 22 Nov 2024 14:22:14 +0700 Subject: [PATCH 3/3] rename file --- docs/tutorials/token/{index.experimental.md => index.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename docs/tutorials/token/{index.experimental.md => index.md} (100%) diff --git a/docs/tutorials/token/index.experimental.md b/docs/tutorials/token/index.md similarity index 100% rename from docs/tutorials/token/index.experimental.md rename to docs/tutorials/token/index.md