Skip to content

Handle ERC20 and Bank Token State #65

@vladjdk

Description

@vladjdk

Overview

We need to determine the optimal strategy for representing and storing state for two types of tokens onchain:

  1. ERC20 tokens created on the EVM layer
  2. Bank tokens originating at the module level (IBC tokens, gas tokens, denoms)

Problem Statement

We currently lack a clear architecture for how tokens should be represented across the system. This creates several challenges:

  • Potential inconsistencies in token representation
  • Unclear paths for IBC transfers
  • Potential confusion for developers building on our platform
  • Potential inefficiencies in token management

Token Representation Matrix

Below is a table describing each method of representing tokens and how they are structured in the current version of Cosmos EVM.

Token Type Current State Current Representation EVM Access Pattern Module Access Pattern External Access Pattern
ERC20 (EVM-native) Exists within EVM state EVM state only. EVM contracts access the state regularly. ABI calls into EVM via evmKeeper.CallEVM EVM queries via JSON-RPC.
Bank (Cosmos-native) Exists within module state Module state only. EVM contracts access the state regularly. Bank module keeper storage EVM queries via JSON-RPC and Cosmos gRPC.

ERC20 (EVM-native) Tokens

These tokens originate within the EVM environment:

  • Current State: ERC20 tokens exist within the EVM state storage. Their balances, allowances, and other properties are managed by the EVM.
  • Current Representation: These tokens are represented in the EVM state only, with no representation at the Cosmos module level.
  • EVM Access Pattern: EVM contracts access these tokens through normal ERC20 interface calls.
  • Module Access Pattern: Cosmos modules access ERC20 tokens through ABI calls into the EVM via the evmKeeper.Call method.
  • External Access Pattern: External systems (like wallets or explorers) interact with these tokens through JSON-RPC queries to the EVM, using standard Ethereum interfaces.

Bank (Cosmos-native) Tokens

These tokens originate within the Cosmos SDK’s bank module:

  • Current State: Bank tokens exist within the Cosmos module state, managed by the bank module keeper.
  • Current Representation: These tokens are represented at the module state level only.
  • EVM Access Pattern: EVM contracts access bank tokens through an ERC20 precompile that serves as a translation layer. The precompile maps ERC20 interface calls to bank module operations without duplicating state.
  • Module Access Pattern: Cosmos modules access bank tokens directly through the bank module keeper storage.
  • External Access Pattern: External systems can access bank tokens through both JSON-RPC queries to the EVM and by querying bank module state through the Cosmos gRPC. The ERC20 precompile enables dual access by exposing bank tokens as ERC20-compatible tokens while maintaining the state in the bank module.

Key Observations

  1. Single Source of Truth: Each token type has a single source of truth for its state—ERC20 tokens in the EVM state and bank tokens in the module state.
  2. Translation Layer: The ERC20 precompile serves as a translation layer for bank tokens, exposing them to the EVM context without duplicating state.
  3. Token Pairs: The system uses token pairs that map Cosmos denoms to ERC20 contract addresses, enabling the precompile to represent bank tokens as ERC20 tokens.
  4. Different Access Patterns: EVM-native tokens require module-level ABI calls for Cosmos module to access them, while Cosmos-native tokens are made available to EVM contracts through the precompile interface.

Current Architecture Limitations

  1. Limited Permissionless Creation of ERC20 Precompiles
    • There is no way to permissionlessly create instances of the ERC20 precompile for tokens to be mirrored from EVM into bank module state
    • Only IBC tokens are automatically converted into ERC20 precompiles via the IBC middleware OnRecvPacket function
    • Architectural asymmetry, where incoming tokens are represented, but EVM-native tokens lack equivalent representation in module state
    • The only way to represent ERC20s as a bank token is via the conversion method, but even that requires registration via a governance proposal
  2. Lack of Extensibility for ERC20 Precompiles
    • Current ERC20 precompile implementation cannot be extended to support advanced ERC20 functionalities
    • Missing support for important ERC20 extensions that applications
      • Examples:
        • ERC20Permit (ERC2612): Gasless approval of tokens
        • ERC20Burnable: Token destruction capabilities
        • ERC20Capped: Supply cap enforcement
        • ERC20Pausable: Circuit breaker functionality
        • ERC20Snapshot: Historical balance tracking
        • ERC20FlashMint (ERC3156): Flash loan support
        • ERC20Votes: Governance capabilities
        • ERC20Wrapper: Token wrapping functionality
        • ERC4626: Tokenized vault standard
  3. Limited Interoperability for EVM-Native Tokens
    • ERC20 tokens originating on the EVM have no pathway to be used in Cosmos modules apart from conversion between the two states
    • Particularly problematic for IBC transfers, as EVM-native tokens cannot be directly sent via IBC
    • Two potential approaches:
      • Represent these as bank tokens
      • Rewrite ICS20 and extend escrow functionality to tap straight into the EVM
  4. Incomplete State Mirroring
    • Current system implements one-way mirroring (bank tokens → EVM) through precompiles
    • No equivalent system for mirroring EVM tokens to module state, only conversions between the two

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions