Replace erc20/ Prefix to erc20: in Native ERC20 Coin Denoms

[zsystm]

Background

1. IBC v2 does not allow / in the base denomination.

   IBC version 2 introduces a restriction that disallows slashes (/) in base denominations. As a r esult, any denom containing / cannot be transferred using the IBC v2 router.

2. Native ERC20 coins currently use the erc20/ prefix, making them incompatible with IBC v2.

   • What is a native ERC20 coin?

     A native ERC20 coin is a Cosmos bank coin that represents an existing ERC20 token contract. It is created when a governance proposal registers a token pair between the ERC20 contract and a new bank denom (which starts with erc20/).

     This regsitration sets the contract owner to OWNER_EXTERNAL, since the ERC20 contract was already deployed by an EoA or CA(not the module itself).

   • Why do we pair an existing ERC20 with a bank denom?

     Because IBC works only with coins stored in the Cosmos bank module, not EVM state. So, in order to send ERC20 tokens (stored in EVM) from a Cosmos EVM-based chain to another chain via IBC, we must first convert them a bank-native coin.

   • When is the erc20/ prefix added?

     • It’s added when a token pair is manually registered via governance through the RegisterERC20 flow, which internally triggers:
       1. registerERC20
       2. CreateCoinMetadata
       3. CreateDenom
          resulting in a denom like erc20/0x…

   • What is an ERC20 token with OWNER_MODULE?

     This represents the “Single Token Representation V2” model. In this case, when a native coin from an external chain is received through IBC, the chain automatically:

     • Deploys an ERC20 contract
     • Adds it to the active precompile list

     This allows the coin to behave like a native bank coin in the EVM envrionment without requiring manual wrapping/unwrapping.

Discussion Points

1. Remove the /erc20 prefix
   • Pros
     1. Full IBC v2 Compatibility: No slash in the denom → Can transfer via IBC v2.
     2. Simplified Denom Handling – We eliminate the special-case prefix logic.
   • Cons
     1. Migration needed if chain:
        1. Uses the erc20 module in cosmos/evm or evmos/os, and
        • Already have native ERC20 coins (with the erc20/ prefix) in its state.
     2. If any chain in production meets these conditions, a uprade handler logic must be added for migrating states.
2. Keep the prefix and continue supporting IBC v1
   • Pros
     1. No Immediate Changes required – Zero migration or code modifications.
   • Cons
     1. Cannot send erc20/ tokens via IBC v2.
     2. Forces indefinite reliance on IBC v1, even if/when it becomes deprecated.

Internal Discussion & Additional Considerations

Recently, two main opinions emerged within our team:

• Opinion 1
  Even if IBC v1 deprecation seems unlikely or very far off, if/when it actually happens, all tokens using the erc20/… prefix (potentially scattered across multiple chains) would need to coordinate a simultaneous upgrade. This could create a huge migration task for every chain involved. Therefore, removing the prefix now (even if some chains already use it) might be better in the long run, avoiding future technical debt.

• Opinion 2
  It might be best to gather more information before deciding:

  • Are there actually any chains that depend on erc20/0x... prefixed coins in production?
  • How likely is it that IBC v1 will be deprecated soon?

  If usage is practically nonexistent (or no real user scenario), removing the prefix is simple. If there are many chains actively using it, perhaps continuing to rely on IBC v1 is acceptable, at least for now. The only downside is not being able to interoperate with IBC v2-only chains.

[checkboot]

It's recommended to abandon legacy burdens and move forward with the new architecture.

[vladjdk]

I don't think that changing token denoms is generally a safe practice, as it could break things with IBC and modules on other chains. The chain can't know for certain where the token has been transferred to, nor would we be able to migrate external chains if we wanted to.

There are users that have the erc20/ prefix on already existing chains, but what are the implications if we just remove the prefix for tokens going forward?

The only place I really see a check being done is ValidateErc20Denom, which is only actually ever used in a test.

So unless I'm missing something, removing the prefix from tokens wouldn't actually break anyone existing. We know that the IBC team has an issue open to support the / delimiter in IBC v2, so existing coins would just use IBC Classic until the v2 supported them.

Seems fine to me if we just remove the prefix for future denoms and keep the current ones as is.

[vladjdk]

Apps that build modules that use the legacy token wouldn't even need to handle the existing denoms with the prefix and new ones without the prefix separately since they're stored as a TokenPair in the module anyways. The only time you'd need to handle separately is if you're doing some kind of denom validation. As mentioned above, it looks like we don't.

[Eric-Warehime]

TODO: Add something in a "migration guide" type readme where we mention that old denoms with erc20/ won't be supported by ibcv2.

[zsystm]

@vladjdk
Yeah, agreed — given the points you raised, I also think we don’t need any migration logic when removing the erc20/ prefix.

We can keep existing denoms as-is, and apply the change only to newly created ones going forward.

I also double-checked whether this change could result in two token pairs being registered for the same contract. Thankfully, IsERC20Registered validates by contract address rather than denom, so we’re safe there — if the check had been done by denom, it might have led to duplicates.

So from what I can see, the prefix removal looks safe, and I don’t see any obvious risks at this point. Happy to move forward with it unless there’s anything else we should consider.

[zsystm]

TODO: Add something in a "migration guide" type readme where we mention that old denoms with erc20/ won't be supported by ibcv2.

@Eric-Warehime
Yeah, I think adding a note in the README makes sense — not because these denoms will never be supported, but because they're not supported in IBC v2 yet. (They will be likely be supported in the future [github], [thread])

So the message could be something like:

“erc20/-prefixed native erc20 coins are currently not supported in IBC v2, but may be supported in the future once ICS20 Transfer v2 is implemented. If a chain is already using such a denom prior to the prefix removal patch, it may need to continue using IBC v1 routes in the meantime.”

[zsystm]

@vladjdk I just realized that we can’t directly use the contract address as a denom when registering an ERC20 as a native token. The Cosmos bank module enforces the regex [a-zA-Z][a-zA-Z0-9/:._-]{2,127}, which requires all denoms to start with an alphabet character. That means we can’t completely remove the prefix.

How about keeping erc20 as the prefix instead?

What do you think?

[vladjdk]

Since we don't really have a requirement for keeping the denom equivalent to the contract address, I say we go with erc20:. It's readable, has no implications for denom balance representation, and is IBC compatible.

[zsystm]

Since we don't really have a requirement for keeping the denom equivalent to the contract address, I say we go with erc20:. It's readable, has no implications for denom balance representation, and is IBC compatible.

@vladjdk Sounds good to me — I’ll proceed with replacing the current erc20/ prefix with erc20:.
(Working PR: #92)