In this chapter, you learn how the interchain exchange module is designed. The module has order books, buy orders, and sell orders.
- First, create an order book for a pair of token.
- After an order book exists, you can create buy and sell orders for this pair of token.
The module uses the Inter-Blockchain Communication protocol IBC. By using IBC, the module can create order books so that multiple blockchains can interact and exchange their token.
You create an order book pair with a token from one blockchain and another token from another blockchain. In this
tutorial, call the module you create the
When a user exchanges a token with the
voucherof that token is received on the other blockchain. This voucher is similar to how an
ibc-transferis constructed. Since a blockchain module does not have the rights to mint new token of a blockchain into existence, the token on the target chain is locked up, and the buyer receives a
voucherof that token.
This process can be reversed when the
voucher gets burned to unlock the original token. This exchange process is
explained in more detail throughout the tutorial.
Assumption of the Design
An order book can be created for the exchange of any tokens between any pair of chains.
- Both blockchains require the
dexmodule to be installed and running.
- There can only be one order book for a pair of token at the same time.
A specific chain cannot mint new coins of its native token.
This module is inspired by the
module on the Cosmos SDK. The
dex module you create in this tutorial has similarities, like the
However, the new
dex module you are creating is more complex because it supports creation of:
- Several types of packets to send
- Several types of acknowledgments to treat
- More complex logic on how to treat a packet on receipt, on timeout, and more
Interchain Exchange Overview
Assume you have two blockchains: Venus and Mars.
- The native token on Venus is
- The native token on Mars is
When a token is exchanged from Mars to Venus:
- The Venus blockchain has an IBC
vouchertoken with a denom that looks like
- The long string of characters after
ibc/is a denom trace hash of a token that was transferred using IBC.
Using the blockchain's API you can get a denom trace from that hash. The denom trace consists of a
base_denom and a
path. In our example:
pathcontains pairs of ports and channels through which the token has been transferred.
For a single-hop transfer, the
path is identified by
Learn more about token paths in ICS 20 Fungible Token Transfer.
Note: This token
ibc/Venus/marscoin cannot be sold back using the same order book. If you want to "reverse" the
exchange and receive the Mars token back, you must create and use a new order book for the
The Design of the Order Books
As a typical exchange, a new pair implies the creation of an order book with orders to sell
marscoin or orders to buy
venuscoin. Here, you have two chains and this data structure must be split between Mars and Venus.
- Users from chain Mars sell
- Users from chain Venus buy
Therefore, we represent:
- All orders to sell
marscoinon chain Mars.
- All orders to buy
marscoinon chain Venus.
In this example, blockchain Mars holds the sell orders and blockchain Venus holds the buy orders.
Exchanging Tokens Back
ibc-transfer, each blockchain keeps a trace of the token voucher that was created on the other blockchain.
If blockchain Mars sells
marscoin to chain Venus and
ibc/Venus/marscoin is minted on Venus then, if
ibc/Venus/marscoin is sold back to Mars, the token is unlocked and the token that is received is
The features supported by the interchain exchange module are:
- Create an exchange order book for a token pair between two chains
- Send sell orders on source chain
- Send buy orders on target chain
- Cancel sell or buy orders