# Understand IBC Denoms with Gaia
One of the most powerful technologies when using the Cosmos SDK is the Interblockchain Communication Protocol (IBC). In the Cosmos ecosystem, every blockchain is intended to be sovereign and application-specific. With IBC, every blockchain can connect to another blockchain using the IBC protocol. This communication protocol will eventually create a system of sovereign and connected blockchains.
The most used feature of IBC is to send tokens from one blockchain to another. When sending a token to another blockchain, a token
voucher is generated on the other (target) blockchain.
Imagine two blockchains, blockchain A and blockchain B. In the beginning, you have your token on blockchain A.
Sending token from blockchain A to blockchain B
The value that tokens represent can be transferred across chains, but the token itself cannot. When sending the tokens with IBC to another blockchain:
- Blockchain A locks the tokens and relays proof to blockchain B
- Blockchain B mints its own representative tokens in the form of voucher replacement tokens
- Blockchain B sends the voucher tokens back to blockchain A
- The voucher tokens are destroyed (burned) on blockchain B
- The locked tokens on blockchain A are unlocked
The only way to unlock the locked tokens on blockchain A is to send the voucher token back from blockchain B. The result is that the voucher token on blockchain B is burned. The burn process purposefully takes the tokens out of circulation.
In this tutorial, you learn the format of the voucher token on blockchain B. You learn what information the token voucher includes and what the token voucher looks like, and you learn how to make sense of them. The information of the token is described as an IBC denom. You can parse this IBC denom to receive information about the voucher and learn which blockchain the token voucher came from.
You will learn how to:
- Trace the IBC denom
- Understand how denoms work
- Find out which chain the token came from
Install the gaia binary:
The output of
gaiad version should print:
# What Is This IBC Denom
voucher tokens introduced in the asset transfer are called IBC Denominations (IBC denom). The voucher tokens are the result of a token transfer using IBC from one blockchain to another. The format of the voucher token is:
Imagine that you've received a new
ibc/ token on blockchain B where you initially held
Your balance now looks like:
ibc/CDC458787... is the denomination (denom) of the token received from IBC. After
ibc/CDC458787... is a hash of the denom, the IBC port, and the channel.
CDC458787... a hash?
- The hash contains paths that track the token on multiple hops from other blockchains to your account.
- This path could potentially be unbearably long when directly printing the path.
- The Cosmos SDK has a 64-character limit on the denomination of the token.
The tradeoff of using a hash is that you must query a node to find out what the actual path and denomination is. This query is called the denomtrace.
Follow along with the
gaiad subcommands to query the denom and learn about the channel the tokens came from.
From the command output, you now know that there is an IBC port
transfer and channel
channel-14. But to know the IBC light client behind the port and channel, you need to perform another query.
Why is it called a light client? Because it is a light client of the other chain, keeping track of its blockhashes. The
ibc channel client-state transfer command explains the details of the denom path.
That's a lot of information, but it doesn't answer the question: how do you know if this IBC client can be relied upon?
# The Chain ID and the Client ID
Anybody can start a chain with the same chain ID. However, the IBC client ID is generated by the Cosmos SDK IBC Keeper module (opens new window) (ICS-02 does not specify a standard for IBC client IDs). A Chain Name Service and the not-so-decentralized Github chain-registrar repo can verify the combination of the chain ID and the client ID. Both the Chain Name Service and the chain-registrar repo are under development and are considered experimental.
# Ensure the IBC Client Isn't Expired
In the event that Tendermint consensus fails (if >1/3 of validators produce a conflicting block), and proof of this consensus failure is submitted on-chain, the IBC client becomes frozen with a
frozen_height that is nonzero. In the previous example, the output of
gaiad query ibc channel client-state confirms the client status and you know the IBC client is not expired.
latest_height.revision_height is the block height when the IBC client was last updated. To ensure that the block height is still up to date, you would have to query the blockchain itself for the block height 2207, and ensure that the timestamp of that block + the
trusting_period of 1209600s/336h/14d is after the current time.
For example, you can verify the IBC client status using the query:
# Find the Path of Another Blockchain
Being able to list all possible blockchain paths is still an unsolved problem.
Any created blockchain can create a new
channel to another blockchain without revealing too much of its information.
Currently, channels must communicate with each other using a person-to-person protocol to be trustable. This person-to-person communication protocol uses an IBC denom so you can identify which tokens to accept for an app.
One approach to solve this problem is to use a centralized or decentralized database of chain IDs and their nodes. There are two solutions under development:
Chain Name Service (decentralized)
The CNS (opens new window) aims to be a Cosmos SDK module that the Cosmos Hub will one day run. As a hub through which cross-chain transactions go, it only makes sense for the Cosmos Hub to host the critical information on how to reach the other chain IDs. CNS is still new and under development.
Cosmos Registry (semi-decentralized)
The github.com/cosmos/registry (opens new window) repo is a stopgap solution. Each chain ID has a folder describing its genesis and a list of peers. To claim their chain ID, a blockchain operator must fork the
registryrepo, create a branch with their chain ID, and submit a pull request to include their chain ID in the official
cosmos/registryof chain IDs.
Every chain ID is represented by a folder, and within that folder a
peers.jsonfile contains a list of nodes that you can connect to.
Cosmos Registrar (semi-decentralized)
The cosmos-registrar (opens new window) is a tool that was started by Jack Zampolin and further developed by Ape Unit. The cosmos-registrar automates claiming and updating a chain ID. In this case, updating a chain ID means committing a fresh peerlist to the GitHub repository. This commit should be run with a cronjob. Its state is best described as v1.0, so go ahead and report any bugs as Github issues.
Choose the approach that best suits you and your use case.