diff --git a/x/asset/spec/01_concepts.md b/x/asset/spec/01_concepts.md index 51be75c9..ed473ff0 100644 --- a/x/asset/spec/01_concepts.md +++ b/x/asset/spec/01_concepts.md @@ -8,13 +8,13 @@ order: 1 The Realio Asset module is centered around a token model where certain whitelisted accounts can issue their own token. A token issued by this module will be managed by a set of `manager` and `distributor` accounts. These accounts are assigned role by the issuer of the asset. -### System of functionality accounts +### System of privileged accounts -Functionality accounts of a token are accounts that can execute certain actions for that token. There're are several types of functionalities, each has its own logic to define the actions which accounts of said type can execute. We wanna decouple the logic of these functionalities from the `Asset module` logic, meaning that functionalities will be defined in separate packages/modules, thus, developers can customize their type of functionality without modifying the `Asset Module`. Doing this allows our functionalities system to be extensible while keeping the core logic of `Asset Module` untouched and simple, avoiding complicated migration when we expand our functionalities system. +Privileged accounts of a token are accounts that can execute certain actions for that token. There're are several types of extensions, each has its own logic to define the actions which accounts of said type can execute. We wanna decouple the logic of these extensions from the `Asset module` logic, meaning that extensions will be defined in separate packages/modules, thus, developers can customize their type of extension without modifying the `Asset Module`. Doing this allows our extensions system to be extensible while keeping the core logic of `Asset Module` untouched and simple, avoiding complicated migration when we expand our extensions system. -In order for a functionality to integrate into the `Asset Module`. It has to implement the `Functionality` interface and has its implementation registered via the method `AddFunctionality`. Once that is done, we can make said functionality available onchain by executing `SoftwareUpgradeProposal` like a regular chain upgrade process. +In order for a extension to integrate into the `Asset Module`. It has to implement the `Extension` interface and has its implementation registered via the method `AddExtension`. Once that is done, we can make said extension available onchain by executing `SoftwareUpgradeProposal` like a regular chain upgrade process. -Currently, there are 2 type of functionality accounts: `manager` and `distributor`. Each can execute different functionalities. While `distributor` can control the `mint` functionality and custom the `DistributionSettings`, the `manager` can execute the other functionalities like `burn` or `freeze` and could modify the `functionalities_list`. It's important to note that the `manager` can choose what functionalities it wants to disable for its token. +Currently, there are 2 type of privileged accounts: `manager` and `distributor`. Each can execute different extensions. While `distributor` can control the `mint` extension and custom the `DistributionSettings`, the `manager` can execute the other extensions like `burn` or `freeze` and could modify the `extensions_list`. It's important to note that the `manager` can choose what extensions it wants to disable for its token. ### EVM enable diff --git a/x/asset/spec/02_state.md b/x/asset/spec/02_state.md index eac54ef7..ac45452d 100644 --- a/x/asset/spec/02_state.md +++ b/x/asset/spec/02_state.md @@ -16,7 +16,6 @@ The `x/asset` module keeps the following objects in state: | `TokenDistributor` | TokenDistributor info of a denom | `[]byte{4} + []byte(id)` | `[]byte{token_distributor}`| KV | | `FrozenAddresses` | Frozen Addresses bytecode | `[]byte{5} + []byte(id)` | `[]byte{[]address}` | KV | - ### Token Allows creation of tokens with optional user authorization. @@ -41,12 +40,14 @@ The `issuer` is the address that create token. They can control all informations ```go type TokenManager struct{ Managers []string `protobuf:"bytes,7,rep,name=managers,proto3" json:"managers,omitempty"` - AllowNewFuctionalities bool `protobuf:"varint,10,opt,name=allow_new_fuctionalities,json=allowNewFuctionalities,proto3" json:"allow_new_fuctionalities,omitempty"` - FunctionalitiesList []string `protobuf:"bytes,11,rep,name=functionalities_list,json=functionalitiesList,proto3" json:"functionalities_list,omitempty"` + AllowNewExtensions bool `protobuf:"varint,10,opt,name=allow_new_Extensions,json=allowNewExtensions,proto3" json:"allow_new_Extensions,omitempty"` + ExtensionsList []string `protobuf:"bytes,11,rep,name=extensions_list,json=extensionsList,proto3" json:"extensions_list,omitempty"` EvmEnable bool `protobuf:"varint,9,opt,name=evm_enable,json=evmEnable,proto3" json:"evm_enable,omitempty"` } ``` +By setting `allow_new_extensions`, `issuer` can specify whether they accept new extensions or not when creating a new token. If he permits it, when upgrading the chain, the new features will be automatically added to the `extensions_list`and the `manager` can then modify the `extensions_list` as he sees fit. Otherwise, the `manager` can not chaing the `extensions_list`. + ### TokenDistributor ```go @@ -56,32 +57,18 @@ type TokenDistributor struct{ } ``` -By setting `allow_new_fuctionalities`, `issuer` can specify whether they accept new functionalities or not when creating a new token. If he permits it, when upgrading the chain, the new features will be automatically added to the `functionalities_list`and the `manager` can then modify the `functionalities_list` as he sees fit. Otherwise, the `manager` can not chaing the `functionalities_list`. - ### DistributionSettings ```go type DistributionSettings struct{ - MaxSupply string - MaxRatelimit string + MaxSupply math.Int + MaxRatelimit math.Int } ``` `MaxSupply` defines the maximum number of tokens can be minted. `MaxRatelimit` defines the ratelimit of tokens can be minted per epoch (each epoch last 1 day). -### FreezedAddress - -List of addresses that is freezed by the manager. This only exists when the Token enable the `freeze` functionality. The addresses in list will not be able to execute any msg about the token. - +### FrozenAddress - +List of addresses that is frozen by the manager. This only exists when the Token enable the `freeze` functionality. The addresses in list will not be able to execute any msg about the token. diff --git a/x/asset/spec/03_params.md b/x/asset/spec/03_params.md index bd1fc1ae..9cad431a 100644 --- a/x/asset/spec/03_params.md +++ b/x/asset/spec/03_params.md @@ -8,12 +8,12 @@ The asset module contains the following parameters: | Key | Type | Example | |----------------------|---------------|------------------------| -| AllowFunctionalities | []string | ["burn","freeze"] | +| AllowExtensions | []string | ["burn","freeze"] | | RatelimitDuration | time.Duration | "86400s" | | WhitelistAddresses | []address | ["realio1..."] | ## Details -- AllowFunctionalities: list of functionalities that the module provides. They can be update after the chain upgrade to enable new functionality add-on to the module. -- RatelimitDuration: duration of ratelimit for `mint` functionality. +- AllowExtensions: list of extensions that the module provides. They can be update after the chain upgrade to enable new extension add-on to the module. +- RatelimitDuration: duration of ratelimit for `mint` extension. - WhitelistAddresses: list of the address that's allow to create new token. diff --git a/x/asset/spec/04_msgs.md b/x/asset/spec/04_msgs.md index 484518e1..53da4436 100644 --- a/x/asset/spec/04_msgs.md +++ b/x/asset/spec/04_msgs.md @@ -17,8 +17,8 @@ order: 4 Decimal uint32 Description string EvmEnable bool - AllowNewFuctionalities bool - FunctionalitiesList [ ]string + AllowNewExtensions bool + ExtensionsList [ ]string } ``` @@ -43,17 +43,19 @@ Example token.json: "Decimal": "rielio", "Description": "", "EvmEnable": true, - "AllowNewFuctionalities": true, - "FunctionalitiesList": [], + "AllowNewExtensions": true, + "ExtensionsList": [], } ``` Validation: + - Check if Creator is whitelisted. We only allow some certain accounts to create tokens, these accounts is determined via gov proposal. - Check if token has been created or not by iterating through all denom existing. -- Sanity check on token info like decimal, description, +- Sanity check on token info like decimal, description Flow: + 1. The denom for the token will be derived from Creator and Symbol with the format of asset/{Issuer}/{Symbol-Lowercase} 2. If `EvmEnable` is true, create a dynamic precompiles for the token. 3. Save the token basic information (name, symbol, decimal and description) in the x/bank metadata store @@ -102,13 +104,17 @@ Example privilege.json: ``` Validation: + - Check if token exists - Check if caller is issuer of the token +- Check if addresses is valid - Check if manager doesn't exist in the current managers list of token - Check if distributor doesn't exist in the current distributor list of token Flow: -1. + +- Get `TokenManager` and `TokenDistributor` from store by token_id +- Loop through addresses and append manager addresses to `TokenManager.Managers`, distributor addresses to `TokenDistributor.Distributors` ## 3. UnassignRole @@ -125,35 +131,45 @@ Flow: } ``` -## 4. ExecuteFunctionality +Validation: + +- Check if token exists +- Check if caller is issuer of the token +- Check if addresses is valid +- Check if addresses is in `TokenManager.Managers` or `TokenDistributor.Distributors` + +Flow: + +- Get `TokenManager` and `TokenDistributor` from store by token_id +- Loop through addresses and remove manager addresses from `TokenManager.Managers`, distributor addresses to `TokenDistributor.Distributors` -After setting the managers, the managers can execute their allowed functionality. +## 4. ExecuteExtension + +After setting the managers, the managers can execute their allowed extension. ```go - type MsgExecuteFunctionality struct { + type MsgExecuteExtension struct { Manager address TokenId string - FunctionalityMsg *types.Any + ExtensionMsg *types.Any } ``` -### Flow - Validation: - Checks if the token specified in the msg exists. -- Checks if the functionality is supported. -- Checks if the `Msg.Address` has the corresponding `Functionality` specified by `FunctionalityMsg.NeedFunctionality()` +- Checks if the extension is supported. +- Checks if the `Msg.Address` has the corresponding `Extension` specified by `ExtensionMsg.NeedExtension()` Flow: -- Prepare store for the functionality of the token via `MakeFunctionalityStore(functionality name, token denom)`. That store is the only store accessable by the functionality's `MsgHandler`. -- `FunctionalityMsgRouting` routes the `FunctionalityMsg` to the its `MsgHandler`. -- `MsgHandler` now handles the `FunctionalityMsg`. +- Prepare store for the extension of the token via `MakeExtensionStore(extension name, token denom)`. That store is the only store accessable by the extension's `MsgHandler`. +- `ExtensionMsgRouting` routes the `ExtensionMsg` to the its `MsgHandler`. +- `MsgHandler` now handles the `ExtensionMsg`. ### 5. Mint -This function only can be executed when the token's `FunctionalitiesList` has `mint` functionality. +This msg only can be executed when the token's `ExtensionsList` has `mint` extension. ```go type MsgMint struct { @@ -164,6 +180,20 @@ This function only can be executed when the token's `FunctionalitiesList` has `m } ``` +Validation: + +- Checks if the token specified in the msg exists. +- Checks if the extension is supported. +- Check if addresses is valid +- Checks if the distributor address is in `TokenDistributor.Distributors` +- Checks if mint amount exceed `MaxSupply` or `MaxRatelimit`. + +Flow: + +- Get `TokenDistributor` from store by token_id +- Mint the asset for corresponding reciever +- Increase the ratelimit + ### 6. UpdateDistributionSetting Distributor can change the max supply and mint ratelimit of the token. @@ -176,16 +206,29 @@ Distributor can change the max supply and mint ratelimit of the token. } ``` -### 7. UpdateFunctionalitiesList +Validation: + +- Checks if the token specified in the msg exists. +- Checks if the extension is supported. +- Checks if the distributor address is in `TokenDistributor.Distributors` +- Checks if current supply exceed new settings `MaxSupply` + +### 7. UpdateExtensionsList -Manager can update the `FunctionalitiesList` of the token. This only can be executed when the token's `AllowNewFuctionalities` is enable. +Manager can update the `ExtensionsList` of the token. This only can be executed when the token's `AllowNewExtensions` is enable. ```go - type FunctionalitiesList struct { + type ExtensionsList struct { Manager address TokenId string - NewFunctionalities []string + NewExtensions []string } ``` +Validation: + +- Checks if the token specified in the msg exists. +- Checks if manager addresses is in `TokenManager.Managers` +- Checks if the new extension is supported. + ### 8. UpdateParams diff --git a/x/asset/spec/05_query.md b/x/asset/spec/05_query.md index 16f2d486..8faec520 100644 --- a/x/asset/spec/05_query.md +++ b/x/asset/spec/05_query.md @@ -99,4 +99,4 @@ CLI: ```bash realio-networkd q frozen-addresses -``` \ No newline at end of file +``` diff --git a/x/asset/spec/06_logic.md b/x/asset/spec/06_logic.md index 45077243..59a636cf 100644 --- a/x/asset/spec/06_logic.md +++ b/x/asset/spec/06_logic.md @@ -63,4 +63,4 @@ The token includes a field named `evm_enable`, which allows it to integrate with The token itself exists as a coin within the bank state, maintaining its own logic and functionalities independently of any ERC20 or EVM contract logic. The ERC20 contract deployed on the EVM serves purely as an interface, with its logic effectively bypassed. When other EVM contracts interact with this interface, their requests are forwarded via JSON-RPC calls to the `asset` module, which directly handles and executes the necessary operations. This is achieved by creating a `dynamic precompile` when `evm_enable` is activated, ensuring that the token’s behavior aligns with its internal state while still providing compatibility with the EVM ecosystem. -### ERC20 Precompiles \ No newline at end of file +### ERC20 Precompiles