State Transitions
Last updated
Last updated
The erc20 modules allows for two types of registration state transitions. Depending on how token pairs are registered, with RegisterCoinProposal
or RegisterERC20Proposal
, there are four possible conversion state transitions.
A user registers a native Cosmos Coin. Once the proposal passes (i.e is Approval by governance), the ERC20 module uses a factory pattern to deploy an ERC20 token contract representation of the Cosmos Coin.
Note that the native Mnova coin cannot be registered, as any coin including "evm" in its denomination cannot be registered. Instead the Mnova token can be converted by Nomand's wrapped Mnova (WMNV) contract.
User submits a RegisterCoinProposal
Validators of the Mnova Chain vote on the proposal using MsgVote
and proposal passes
If Cosmos coin or IBC voucher exist on the bank module supply, create the ERC20 token contract on the EVM based on the ERC20Mintable () interface
Initial supply: 0
Token details (Name, Symbol, Decimals, etc) are derived from the bank module Metadata
field on the proposal content.
A user registers a ERC20 token contract that is already deployed on the EVM module. Once the proposal passes (i.e is approved by governance), the ERC20 module creates a Cosmos coin representation of the ERC20 token.
User submits a RegisterERC20Proposal
Validators of the Mnova chain vote on the proposal using MsgVote
and proposal passes
If ERC-20 contract is deployed on the EVM module, create a bank coin Metadata
from the ERC20 details.
Conversion of a registered TokenPair
can be done via:
Cosmos transaction (ConvertCoin
and ConvertERC20)
Ethereum transaction (i.e sending a MsgEthereumTx
that leverages the EVM hook)
Invariants
Only the ModuleAccount
should have the Minter Role on the ERC20. Otherwise, the user could unilaterally mint an infinite supply of the ERC20 token and then convert them to the native Coin
The user and the ModuleAccount
(owner) should be the only ones that have the Burn Role for a Cosmos Coin
There shouldn't exist any native Cosmos Coin ERC20 Contract (eg MNV, Atom, Osmo ERC20 contracts) that is not owned by the governance
Token/Coin supply is maintained at all times:
Total Coin supply = Coins + Escrowed Coins
Total Token supply = Escrowed Coins = Minted Tokens
1.1 Coin to ERC20
User submits ConvertCoin
Tx
Check if conversion is allowed for the pair, sender and recipient
global parameter is enabled
token pair is enabled
sender tokens are not vesting (checked in the bank module)
recipient address is not blocklisted
If Coin is a native Cosmos Coin and Token Owner is ModuleAccount
Escrow Cosmos coin by sending them to the erc20 module account
Call mint()
ERC20 tokens from the ModuleAccount
address and send minted tokens to recipient address
Check if token balance increased by amount
1.2 ERC20 to Coin
User submits a ConvertERC20
Tx
If token is a ERC20 and Token Owner is ModuleAccount
Call burnCoins()
on ERC20 to burn ERC20 tokens from the user balance
Check if
Coin balance increased by amount
Token balance decreased by amount
Invariants
ERC20 Token supply on the EVM runtime is maintained at all times:
Escrowed ERC20 + Minted Cosmos Coin representation of ERC20 = Burned Cosmos Coin representation of ERC20 + Unescrowed ERC20
Convert 10 ERC20 → Coin, the total supply increases by 10. Mint on Cosmos side, no changes on EVM
Convert 10 Coin → ERC20, the total supply decreases by 10. Burn on Cosmos side , no changes of supply on EVM
Total ERC20 token supply = Non Escrowed Tokens + Escrowed Tokens (on Module account address)
Total Coin supply for the native ERC20 = Escrowed ERC20 Tokens on module account (i.e balance) = Minted Coins
2.1 ERC20 to Coin
User submits a ConvertERC20
Tx
If token is a ERC20 and Token Owner is not ModuleAccount
Escrow ERC20 token by sending them to the erc20 module account
Mint Cosmos coins of the corresponding token pair denomination and send coins to the recipient address
Check if
Coin balance increased by amount
Token balance decreased by amount
Fail if unexpected Approval
event found in logs to prevent malicious contract behavior
2.2 Coin to ERC20
User submits ConvertCoin
Tx
Check if conversion is allowed for the pair, sender and recipient
If coin is a native Cosmos coin and Token Owner is not ModuleAccount
Escrow Cosmos Coins by sending them to the erc20 module account
Unlock escrowed ERC20 from the module address by sending it to the recipient
Burn escrowed Cosmos coins
Check if token balance increased by amount
Fail if unexpected Approval
event found in logs to prevent malicious contract behavior
Context: A TokenPair
has been created through a RegisterCoinProposal
governance proposal. The proposal created an ERC20
contract () of the ERC20 token representation of the Coin from the ModuleAccount
, assigning it as the owner
of the contract and thus granting it the permission to call the mint()
and burnFrom()
methods of the ERC20.
Check if conversion is allowed for the pair, sender and recipient (see )
Send Coins (previously escrowed, see ) from module to the recipient address.
Check if conversion is allowed for the pair, sender and recipient (See )