From 5cd7e5d52d0ab7736a715acfa172d25b14bd3a10 Mon Sep 17 00:00:00 2001 From: Hieu Vu Date: Sat, 1 Feb 2025 18:28:29 +0700 Subject: [PATCH] update spec --- x/asset/spec/01_concepts.md | 2 +- x/asset/spec/02_state.md | 4 ---- x/asset/spec/06_logic.md | 2 +- x/asset/spec/README.md | 26 +++++++++++++++----------- 4 files changed, 17 insertions(+), 17 deletions(-) diff --git a/x/asset/spec/01_concepts.md b/x/asset/spec/01_concepts.md index 28cfcc44..00b6ff2a 100644 --- a/x/asset/spec/01_concepts.md +++ b/x/asset/spec/01_concepts.md @@ -12,7 +12,7 @@ The Realio Asset module is centered around a token model where certain whitelist Token extensions are additional features that can be flug-in for each token. There're are four types of extensions `Mint`, `Burn`, `Transfer Auth` and `Freeze`. The `Issuer` can choose what extensions to be included for his token at creation time, and only the `manager` can trigger the extension's logic. -### EVM enable +### EVM integration While it is the asset token in represented in the bank module, enabling the token interface in evm environment is very convenient and open up the possibility of integrating new features into the ecosystem. diff --git a/x/asset/spec/02_state.md b/x/asset/spec/02_state.md index 57753fd5..c495da3c 100644 --- a/x/asset/spec/02_state.md +++ b/x/asset/spec/02_state.md @@ -33,10 +33,6 @@ type Token struct { } ``` -The token id for the token will be derived from the Issuer and the Symbol with the format of asset/{Issuer}/{Symbol-Lowercase}. This will allow 2 tokens to have the same name with different issuers. - -The `issuer` is the address that create token. They can control all informations about the token, define other whitelist roles likes `manager` and `distributor`. `issuer` also can enable the token's single evm representation mode, which is showed in [EVM precompiles](README.md#asset-module-and-erc-20-precompiles). - When create the token, `asset` module auto generate for it a evm address. This address is used as a dynamic precompiles. ### TokenManagement diff --git a/x/asset/spec/06_logic.md b/x/asset/spec/06_logic.md index b4649351..4bd60b70 100644 --- a/x/asset/spec/06_logic.md +++ b/x/asset/spec/06_logic.md @@ -35,7 +35,7 @@ We'll go into details on how each of the extension works ### -## EVM interaction +## EVM integration ### EVM interface diff --git a/x/asset/spec/README.md b/x/asset/spec/README.md index 1999c6be..0f31839d 100644 --- a/x/asset/spec/README.md +++ b/x/asset/spec/README.md @@ -9,27 +9,29 @@ parent: ## The Realio Asset Token Model -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 two different roles, manager and distributor. These roles can be assigned to arbitrary accounts (could be either user accounts or module/contract account) by the token issuer. +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 defined by the `issuer` and managed by the `manager` role. `manager` role can be assigned to arbitrary accounts (could be either user accounts or module/contract account) by the token issuer. -Each token can choose to enable extensions supported by the module. Currently, there are four extensions supported: "mint", "freeze", "clawback", "transfer_auth", each handle a completely different logic. We wanna decouple the logic of these extensions from the `Asset module`, meaning that they will be defined in separate packages/modules, thus, developers can customize new extensions without modifying the `Asset Module`. Doing this allows our token model to be extensible while keeping the core logic of `Asset Module` untouched and simple, avoiding complicated migration when we integrating new features. - -The token manager's task is to choose what extensions it wants to disable/enable for its token; and only the token manager can trigger those extensions, except for the `mint` extension which is handled by the `distributor`. +Token extensions are additional features that can be flug-in for each token. There're are four types of extensions `Mint`, `Burn`, `Transfer Auth` and `Freeze`. The `Issuer` can choose what extensions to be included for his token at creation time, and only the `manager` can trigger the extension's logic. ![asset_module](imgs/asset_module.png)` -## Asset Module and ERC-20 Precompiles +## Asset module precompile + +To enhance user experience as well as interoperability with EVM contracts, we decide to build a precompile for the asset module. All the messages of asset modules can now also be triggered with an evm call. Thus, evm contracts can interact with the module and users can call the modules via metamask or any ethereum friendly UI. + +## ERC-20 Precompiles -ERC-20 precompiles are offered by evmOS for better interacting with Cosmos SDK. Instead of changing the state of evm, with ERC-20 precompiles, modules now can represent ERC-20 token in the form of normal bank token and therefore can be managed by SDK modules (single token representation). Utilizing this feature enables the evm contracts to interact with the asset tokens via erc20 call, opening lots of defi usecases for the asset module. +ERC-20 precompiles are offered by evmOS for better integration with Cosmos SDK. With ERC-20 precompiles, we now can have bank tokens with the interface of erc-20 contracts and therefore can talk to other EVM contracts. Utilizing this feature enables the evm contracts to interact with the asset tokens via erc20 call, opening lots of defi usecases for the asset module. ### Link Asset to Precompiles -To link an asset to ERC20 Precompile, when issuer send the MsgIssueToken to the Asset Module, a new asset will be created and a new evm address is created randomly, which will be auto assigned an erc20-precompiles to interact with evm environment. After linking, all call to the token contract will now redirect to precompile instead of the evm. +Each token of the asset module is automatically linked to ERC20 Precompile, when issuer execute the MsgIssueToken, a new token instance will be created in the asset module and a new evm address is derived based on the token's info, which will be assigned an erc20-precompiles. After that, all calls to the evm address will now redirect to the erc20-precompiles. ![asset_precompiles](imgs/linking_precompiles.png) -### Mapping extensions +### Token extensions call via precompiles -ERC20 precompiles come with a limited number of extensions which are: +Each ERC20 precompiles come with a limited number of call which are: - Transfer - TransferFrom @@ -37,12 +39,14 @@ ERC20 precompiles come with a limited number of extensions which are: - IncreaseAllowance - DecreaseAllowance -We introduce additional extensions on these standard extensions: +We introduce these optional calls to precompile to execute the token's extensions: - Mint - Burn +- Freeze +- TransferAuth -All above extensions can be called from both AssetModule and EVM side (by metamask for example). +It's important to note that each token has its own set of enabled extensions, the precompile linked to that token must also reflect that. In other words, for each precompile these calls will be enabled/disabled however the linked token's extensions be. ![asset_evm](imgs/asset_evm.png)