Skip to main content

Use the Interchain Exchange

In this chapter, you learn details about the order book and commands to:

  • 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

The next chapter contains the code for the implementation.

Order Book

To use the exchange, start by creating an order book for a pair of tokens:

interchanged tx dex send-create-pair [src-port] [src-channel] [sourceDenom] [targetDenom]
# Create pair broadcasted to the source blockchain

interchanged tx dex send-create-pair dex channel-0 marscoin venuscoin

Define a pair of token with two denominations:

  • Source denom (in this example, marscoin)
  • Target denom (venuscoin)

Creating an order book affects state on the source blockchain to which the transaction was broadcast and the target blockchain.

On the source blockchain, the send-create-pair command creates an empty sell order book:

# Created a sell order book on the source blockchain
SellOrderBook:
- amountDenom: marscoin
creator: ""
index: dex-channel-0-marscoin-venuscoin
orderIDTrack: 0
orders: []
priceDenom: venuscoin

On the target blockchain, the same send-createPair command creates a buy order book:

# Created a buy order book on the target blockchain
BuyOrderBook:
- amountDenom: marscoin
creator: ""
index: dex-channel-0-marscoin-venuscoin
orderIDTrack: 1
orders: []
priceDenom: venuscoin

To make an exchange possible, the createPair transaction sends an IBC packet to the target chain.

  • When the target chain receives a packet, the target chain creates a buy order book and sends an acknowledgement back to the source chain.
  • When the source chain receives an acknowledgement, the source chain creates a sell order book.

Sending an IBC packet requires a user to specify a port and a channel through which a packet is transferred.

Sell Order

After an order book is created, the next step is to create a sell order:

interchanged tx dex send-sell-order [src-port] [src-channel] [amountDenom] [amount] [priceDenom] [price]

# Sell order broadcasted to the source blockchain
interchanged tx dex send-sell-order dex channel-0 marscoin 10 venuscoin 15

The send-sellOrder command broadcasts a message that locks token on the source blockchain and creates a sell order on the source blockchain:

# Source blockchain
balances:
- amount: "990" # decreased from 1000
denom: marscoin
SellOrderBook:
- amountDenom: marscoin
creator: ""
index: dex-channel-0-marscoin-venuscoin
orderIDTrack: 2
orders: # a new sell order is created
- amount: 10
creator: cosmos1v3p3j7c64c4ls32pcjct333e8vqe45gwwa289q
id: 0
price: 15
priceDenom: venuscoin

Buy Order

A buy order has the same arguments, the amount of token to be purchased and a price:

`interchanged tx dex send-buy-order [src-port] [src-channel] [amountDenom] [amount] [priceDenom] [price]`

# Buy order broadcasted to the target blockchain
interchanged tx dex send-buy-order dex channel-0 marscoin 10 venuscoin 5

The send-buy-order command locks token on the target blockchain:

# Target blockchain
balances:
- amount: "950" # decreased from 1000
denom: venuscoin
BuyOrderBook:
- amountDenom: marscoin
creator: ""
index: dex-channel-0-marscoin-venuscoin
orderIDTrack: 3
orders: # a new buy order is created
- amount: 10
creator: cosmos1qlrz3peenc6s3xjv9k97e8ef72nk3qn3a0xax2
id: 1
price: 5
priceDenom: venuscoin

Perform an Exchange with a Sell Order

You now have two orders open for marscoin:

  • A sell order on the source chain (for 10marscoin at 15venuscoin)
  • A buy order on the target chain (for 5marscoin at 5venuscoin)

Now, perform an exchange by sending a sell order to the source chain:

# Sell order broadcasted to the source chain
interchanged tx dex send-sell-order dex channel-0 marscoin 5 venuscoin 3

The sell order (for 5marscoin at 3venuscoin) is filled on the target chain by the buy order.

The amount of the buy order on the target chain is decreased by 5marscoin:

# Target blockchain
BuyOrderBook:
- amountDenom: marscoin
creator: ""
index: dex-channel-0-marscoin-venuscoin
orderIDTrack: 5
orders:
- amount: 5 # decreased from 10
creator: cosmos1qlrz3peenc6s3xjv9k97e8ef72nk3qn3a0xax2
id: 3
price: 5
priceDenom: venuscoin

The sender of the filled sell order exchanged 5marscoin for 25 venuscoin vouchers.

25 vouchers is a product of the amount of the sell order (5marscoin) and price of the buy order (5venuscoin):

# Source blockchain
balances:
- amount: "25" # increased from 0
denom: ibc/50D70B7748FB8AA69F09114EC9E5615C39E07381FE80E628A1AF63A6F5C79833 # venuscoin voucher
- amount: "985" # decreased from 990
denom: marscoin

The counterparty (the sender of the buy marscoin order) receives 5 marscoin vouchers:

# Target blockchain
balances:
- amount: "5" # increased from 0
denom: ibc/99678A10AF684E33E88959727F2455AE42CCC64CD76ECFA9691E1B5A32342D33 # marscoin voucher

The venuscoin balance hasn't changed because the correct amount of venuscoin (50) was locked at the creation of the buy order during the previous step.

Perform an Exchange with a Buy Order

Now, send an order to buy 5marscoin for 15venuscoin:

# Buy order broadcasted to the target chain
interchanged tx dex send-buy-order dex channel-0 marscoin 5 venuscoin 15

A buy order is immediately filled on the source chain and the sell order creator receives 75 venuscoin vouchers.

The sell order amount is decreased by the amount of the filled buy order (by 5marscoin):

# Source blockchain
balances:
- amount: "100" # increased from 25
denom: ibc/50D70B7748FB8AA69F09114EC9E5615C39E07381FE80E628A1AF63A6F5C79833 # venuscoin voucher
SellOrderBook:
- amountDenom: marscoin
creator: ""
index: dex-channel-0-marscoin-venuscoin
orderIDTrack: 4
orders:
- amount: 5 # decreased from 10
creator: cosmos1v3p3j7c64c4ls32pcjct333e8vqe45gwwa289q
id: 2
price: 15
priceDenom: venuscoin

The creator of the buy order receives 5 marscoin vouchers for 75 venuscoin (5marscoin * 15venuscoin):

# Target blockchain
balances:
- amount: "10" # increased from 5
denom: ibc/99678A10AF684E33E88959727F2455AE42CCC64CD76ECFA9691E1B5A32342D33 # marscoin vouchers
- amount: "875" # decreased from 950
denom: venuscoin

Complete Exchange with a Partially Filled Sell Order

Send an order to sell 10marscoin for 3venuscoin:

# Source blockchain
interchanged tx dex send-sell-order dex channel-0 marscoin 10 venuscoin 3

The sell amount is 10marscoin, but the opened buy order amount is only 5marscoin. The buy order gets filled completely and removed from the order book. The author of the previously created buy order receives 10 marscoin vouchers from the exchange:

# Target blockchain
balances:
- amount: "15" # increased from 5
denom: ibc/99678A10AF684E33E88959727F2455AE42CCC64CD76ECFA9691E1B5A32342D33 # marscoin voucher
BuyOrderBook:
- amountDenom: marscoin
creator: ""
index: dex-channel-0-marscoin-venuscoin
orderIDTrack: 5
orders: [] # buy order with amount 5marscoin has been closed
priceDenom: venuscoin

The author of the sell order successfuly exchanged 5 marscoin and received 25 venuscoin vouchers. The other 5marscoin created a sell order:

# Source blockchain
balances:
- amount: "125" # increased from 100
denom: ibc/50D70B7748FB8AA69F09114EC9E5615C39E07381FE80E628A1AF63A6F5C79833 # venuscoin vouchers
- amount: "975" # decreased from 985
denom: marscoin
- amountDenom: marscoin
SellOrderBook:
creator: ""
index: dex-channel-0-marscoin-venuscoin
orderIDTrack: 6
orders:
- amount: 5 # hasn't changed
creator: cosmos1v3p3j7c64c4ls32pcjct333e8vqe45gwwa289q
id: 2
price: 15
- amount: 5 # new order is created
creator: cosmos1v3p3j7c64c4ls32pcjct333e8vqe45gwwa289q
id: 4
price: 3

Complete Exchange with a Partially Filled Buy Order

Create an order to buy 10 marscoin for 5 venuscoin:

# Target blockchain
interchanged tx dex send-buy-order dex channel-0 marscoin 10 venuscoin 5

The buy order is partially filled for 5marscoin. An existing sell order for 5 marscoin (with a price of 3 venuscoin) on the source chain is completely filled and is removed from the order book. The author of the closed sell order receives 15 venuscoin vouchers (product of 5marscoin and 3venuscoin):

# Source blockchain
balances:
- amount: "140" # increased from 125
denom: ibc/50D70B7748FB8AA69F09114EC9E5615C39E07381FE80E628A1AF63A6F5C79833 # venuscoin vouchers
SellOrderBook:
- amountDenom: marscoin
creator: ""
index: dex-channel-0-marscoin-venuscoin
orderIDTrack: 6
orders:
- amount: 5 # order hasn't changed
creator: cosmos1v3p3j7c64c4ls32pcjct333e8vqe45gwwa289q
id: 2
price: 15
# a sell order for 5 marscoin has been closed
priceDenom: venuscoin

The author of the buy order receives 5 marscoin vouchers which locks 50 venuscoin of their token. The 5marscoin amount that is not filled by the sell order creates a buy order on the target chain:

# Target blockchain
balances:
- amount: "20" # increased from 15
denom: ibc/99678A10AF684E33E88959727F2455AE42CCC64CD76ECFA9691E1B5A32342D33 # marscoin vouchers
- amount: "825" # decreased from 875
denom: venuscoin
BuyOrderBook:
- amountDenom: marscoin
creator: ""
index: dex-channel-0-marscoin-venuscoin
orderIDTrack: 7
orders:
- amount: 5 # new buy order is created
creator: cosmos1qlrz3peenc6s3xjv9k97e8ef72nk3qn3a0xax2
id: 5
price: 5
priceDenom: venuscoin

Cancel an Order

After these exchanges, you still have two orders open:

  • A sell order on the source chain (5marscoin for 15venuscoin)
  • A buy order on the target chain (5marscoin for 5venuscoin)

To cancel a sell order:

# Source blockchain
interchanged tx dex cancel-sell-order dex channel-0 marscoin venuscoin 2

The balance of marscoin is increased:

# Source blockchain
balances:
- amount: "980" # increased from 975
denom: marscoin

The sell order book on the source blockchain is now empty.

To cancel a buy order:

# Target blockchain
interchanged tx dex cancel-buy-order dex channel-0 marscoin venuscoin 5

The amount of venuscoin is increased:

# Target blockchain
balances:
- amount: "850" # increased from 825
denom: venuscoin

The buy order book on the target blokchain is now empty.

This walkthrough of the interchain exchange showed you how to:

  • 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