Path: blob/main/docs/versioned_docs/version-v0.25/guide/08-interchange/03-walkthrough.md
1007 views
------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:
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:
On the target blockchain, the same send-createPair command creates a buy order book:
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:
The send-sellOrder command broadcasts a message that locks token on the source blockchain and creates a sell order on the source blockchain:
Buy Order
A buy order has the same arguments, the amount of token to be purchased and a price:
The send-buy-order command locks token on the target blockchain:
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:
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:
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):
The counterparty (the sender of the buy marscoin order) receives 5 marscoin vouchers:
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:
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):
The creator of the buy order receives 5 marscoin vouchers for 75 venuscoin (5marscoin * 15venuscoin):
Complete Exchange with a Partially Filled Sell Order
Send an order to sell 10marscoin for 3venuscoin:
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:
The author of the sell order successfully exchanged 5 marscoin and received 25 venuscoin vouchers. The other 5marscoin created a sell order:
Complete Exchange with a Partially Filled Buy Order
Create an order to buy 10 marscoin for 5 venuscoin:
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):
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:
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:
The balance of marscoin is increased:
The sell order book on the source blockchain is now empty.
To cancel a buy order:
The amount of venuscoin is increased:
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