diff --git a/docs/architecture/README.md b/docs/architecture/README.md index f73f2299a5..9b30a12134 100644 --- a/docs/architecture/README.md +++ b/docs/architecture/README.md @@ -27,6 +27,7 @@ To suggest an ADR, please make use of the [ADR template](./adr-template.md) prov | ADR \# | Description | Status | | ------ | ----------- | ------ | -| [001](./adr-001.md) | Disable Gravity Bridge at Genesis | Proposed | -| [002](./adr-002.md) | Use a custom fork of ibc-go | Proposed | -| [003](./adr-003.md) | Add Fee Market Module | Proposed | +| [001](./adr-001.md) | Disable Gravity Bridge at Genesis | Accepted | +| [002](./adr-002.md) | Use a custom fork of ibc-go | Accepted | +| [003](./adr-003.md) | Add Fee Market Module | Accepted | +| [004](./adr-004.md) | Tokens conversion in Cronos | Accepted | diff --git a/docs/architecture/adr-003.md b/docs/architecture/adr-003.md index 21fddc7e0b..05b20bdbf6 100644 --- a/docs/architecture/adr-003.md +++ b/docs/architecture/adr-003.md @@ -6,7 +6,7 @@ ## Status -PROPOSED +Accepted ## Abstract diff --git a/docs/architecture/adr-004.md b/docs/architecture/adr-004.md new file mode 100644 index 0000000000..558589e45d --- /dev/null +++ b/docs/architecture/adr-004.md @@ -0,0 +1,80 @@ +# ADR 004: Tokens conversion in Cronos + +## Changelog + +- 2022-02-28: first draft + +## Status + +Accepted + +## Abstract + +This ADR documents the "auto" token conversion mechanism implemented in Cronos which aim to improve user-experience by allowing tokens to be converted to a single type (erc20) while in the underlying chain, multiple type of tokens coexist. + + +## Context + +With the bank module, a cosmos-chain is able to produce and manage multi-asset coin. Later, with IBC, it became also possible for a cosmos chain to transfer coin-asset to another chain and also manage asset originated from another chain. All coin-assets in Cosmos follow the same standard and are managed by the bank module. +We are calling them "native tokens" + +On the other side, the evm module introduce the notion of ethereum virtual machine. Like in Ethereum, it is possible with smart contract to create all form of assets. The erc20 standard is the most popular standard to describe fungible tokens and are integrated in most web3 tools (metamask, explorer etc). + +This ADR describes a mechanism to convert seamlessly native tokens to evm tokens (erc20) out of an IBC transfer. In a more general concept, any kind of native tokens can be converted to an evm tokens (and vice versa) using cronos native transactions. + +In our reasoning, most of our users comes from the Ethereum world and are more familiar to interact with ethereum web3 tools for signing transactions and managing assets. This is why this proposal is important for the chain adoption. + + +## Proposal + +- Implement in x/cronos module two cosmos transactions : `convert-vouchers` allows to convert an ibc-originated asset to its erc20 representation and `transfer-tokens` allows to send a erc20 to another cosmos chain through ibc. +- Implement logic in `ibc-hooks` that allows to trigger automatically a `convert-vouchers` to asset originating from an ibc transfer. +- Implement logic in `evm-hooks` that allows to trigger an IBC transfer from a contract account when a specific event is fired from the contract. + + +## EVM + +To be able to control native tokens with a smart contract, we are defining specific instruction that can be called by a module within a smart contract : + +- mint_by_cronos_module(address user, uint256 amount) +- burn_by_cronos_module(address user, uint256 amount) +- native_denom() returns (string) + +When calling a smart contract, the caller address is a constant value which represents the module address + + // sha256('cronos-evm')[:20] + address constant module_address = 0x89A7EF2F08B1c018D5Cc88836249b84Dd5392905; + +Contracts can use the `require` instruction to allow restricted operation to be performed + + function mint_by_cronos_module(address addr, uint amount) public { + require(msg.sender == module_address); + mint(addr, amount); + } + + + +We are also defining specific events that can trigger specific action from smart contract's account on cosmos side +- __CronosSendToAccount(address recipient, uint256 amount) : send a specific token amount from contract address to recipient address +- __CronosSendToIBCChannel(address recipient, uint256 amount) : send a specific token amount through ibc to recipient address in destination chain + +At end block, all events fired by smart contract are processed by the module and post-operation hooks are trigerred. + +## Consequences + +Same as https://github.com/tharsis/ethermint/blob/main/docs/architecture/adr-002-evm-hooks.md + +As this design allows a strong interoperability between the EVM and cosmos module, it also breaks the isolation layer of the EVM. Operations should be strictly limited to a bounded scope (ie Contract account). + + +## Further Discussions + + + + +## References + +* https://github.com/tharsis/ethermint/blob/main/docs/architecture/adr-002-evm-hooks.md +* https://github.com/crypto-org-chain/cronos/blob/main/contracts/src/ModuleCRC20.sol +* https://github.com/crypto-org-chain/cronos/blob/main/docs/architecture/adr-002.md \ No newline at end of file