Guide: Enabling Namada support for a new IBC token

mindstyle85 · 17 July 2025 16:17

Hello, here is the first version. I think we mostly got everything in:

Guide to Adding a New IBC Token to Namada

Overview

Adding a new IBC (Inter-Blockchain Communication) token to Namada involves several steps, including preparing the necessary governance proposal, updating the Namada registry, and ensuring the token is correctly integrated into the Namada network. This guide will walk you through the process using the provided resources.

Step 1: Opening and Testing IBC Channels on the Campfire Testnet

Ensure you have the necessary tools and dependencies installed. Please see hardware requirements, node configuration and IBC relaying documentation.

Step 2: Verifying Compatibility and Completing Integration Testing on the Campfire Testnet

2.1 Verify Token Compatibility

Ensure that the token you want to add is compatible with Namada’s IBC module. Check the token’s denom and ensure it matches the expected format.

2.2 Perform Integration Testing

Conduct thorough integration testing to ensure that the token can be successfully transferred and managed within the Namada network. This includes testing both sending and receiving transactions.

Testing Action Items:

Each token can be IBC transferred into a Namada transparent address
Each token can be directly shielded into Namada over IBC
Each token can be unshielded natively within Namada and out of directly out of Namada over IBC
Shielded transfers of these tokens are working
Each token can be used for gas payment
The rate limit caps work as intended, e.g. an IBC transfer of more than 20 tokens for any of the tokens can never succeed in either direction
NAM can still not be transferred or shielded
No shielded rewards are minted
Staking rewards and other proof-of-stake actions still work as in Phase 2
All of the above functionality works via the CLI and Namadillo
Example report: Housefire testnet Phase 3 Checklist - #4 by Daniel

Step 3: Governance Proposal to Add the IBC Token on mainnet

3.1 Create the Proposal

Draft a governance proposal to add the new IBC token in the forums. You can refer to the following proposal for structure and content.

3.2 Submit the Proposal

Submit the proposal using the Namada governance module. Please refer to documentation for proposal structure, default proposal type and governance actions.

Please refer to this section on how to create wasm code. Additionally the following example can be used as reference.

Please keep in mind that when adding a new IBC token, the following values have to be correctly added:

ChannelId
BaseToken
MintTokenLimit
ThroughtputTokenLimit
MinimumGasPrice

Refer to an example below:

    (
        "channel-4", // ChannelId - the id of the IBC channel
        "upenumbra", // BaseToken - base token and denom to be added, default is usually "utoken"
        MintTokenLimit::from_u64(5000000000000), // 5M UM - the amount of token that can be minted on Namada, in "utoken"
        ThroughtputTokenLimit::from_u64(1000000000000), // 1M UM - the maximum amount allowed within 24 hours
        Some(Gas::from_u64(10)),                 // 10 upenumbra / gas unit - how many IBC tokens per gas unit are needed to pay for transaction fees
    )

Notes:

Non-native token gas payment such that the minimum tx cost in a non-native asset will be in the approximate $0.20 - $0.30 range
Global mint limit of ~$5M of a given non-native asset allowed into Namada
Throughput limit of ~$1M of a given non-native asset to flow into/out of Namada per epoch

Finally, submit the proposal on-chain:

namadac init-proposal --data-path proposal.json --gas-limit 500000

Step 4: Opening IBC Channels on mainnet

Ensure you have the necessary tools and dependencies installed. Please see hardware requirements, node configuration and IBC relaying documentation.

Step 5: Add the Assets to Chain Registry

5.1 Update the Chain Registry IBC channels

Update the Namada chain registry and Namada ecosystem repo from Luminara, to include the new IBC channels. Refer to the pull request for an example of how to update the registry.

An example to add Penumbra:

Create namada-penumbra.json with the following:

{
  "$schema": "../ibc_data.schema.json",
  "chain_1": {
    "chain_name": "namada",
    "client_id": "07-tendermint-6",
    "connection_id": "connection-4"
  },
  "chain_2": {
    "chain_name": "penumbra",
    "client_id": "07-tendermint-18",
    "connection_id": "connection-14"
  },
  "channels": [
    {
      "chain_1": {
        "channel_id": "channel-4",
        "port_id": "transfer"
      },
      "chain_2": {
        "channel_id": "channel-13",
        "port_id": "transfer"
      },
      "ordering": "unordered",
      "version": "ics20-1"
    }
  ]
}

5.2 Update the Chain Registry IBC tokens

Update the Namada chain registry to include the new IBC tokens. Refer to the pull request for an example of how to update the registry.