Path: blob/main/docs/versioned_docs/version-v0.26/02-guide/07-interchange/03-walkthrough.md
1007 views
------Use the Interchain Exchange
In this chapter, you will learn about the exchange and how it will function once it is implemented. This will give you a better understanding of what you will be building in the coming chapters.
To achieve this, we will perform the following tasks:
Start two local blockchains
Set up an IBC relayer between the two chains
Create an exchange order book for a token pair on the two chains
Submit sell orders on the Mars chain
Submit buy orders on the Venus chain
Cancel sell or buy orders
Starting the two local blockchains and setting up the IBC relayer will allow us to create an exchange order book between the two chains. This order book will allow us to submit sell and buy orders, as well as cancel any orders that we no longer want to maintain.
It is important to note that the commands in this chapter will only work properly if you have completed all the following chapters in this tutorial. By the end of this chapter, you should have a good understanding of how the exchange will operate.
Start blockchain nodes
To start using the interchain exchange, you will need to start two separate blockchains. This can be done by running the ignite chain serve command, followed by the -c flag and the path to the configuration file for each blockchain. For example, to start the mars blockchain, you would run:
To start the venus blockchain, you would run a similar command, but with the path to the venus.yml configuration file:
Once both blockchains are running, you can proceed with configuring the relayer to enable interchain exchange between the two chains.
Relayer
Next, let's set up an IBC relayer between two chains. If you have used a relayer in the past, reset the relayer configuration directory:
Now you can use the ignite relayer configure command. This command allows you to specify the source and target chains, along with their respective RPC endpoints, faucet URLs, port numbers, versions, gas prices, and gas limits.
To create a connection between the two chains, you can use the ignite relayer connect command. This command will establish a connection between the source and target chains, allowing you to transfer data and assets between them.
Now that we have two separate blockchain networks up and running, and a relayer connection established to facilitate communication between them, we are ready to begin using the interchain exchange binary to interact with these networks. This will allow us to create order books and buy/sell orders, enabling us to trade assets between the two chains.
Order Book
To create an order book for a pair of tokens, you can use the following command:
This command will create an order book for the pair of tokens marscoin and venuscoin. The command will be executed by the user alice on the Mars blockchain. The --home parameter specifies the location of the configuration directory for the Mars blockchain.
Creating an order book affects state on the Mars blockchain to which the transaction was broadcast and the Venus blockchain.
On the Mars blockchain, the send-create-pair command creates an empty sell order book.
On the Venus blockchain, the same send-createPair command creates a buy order book:
In the create-pair command on the Mars blockchain, an IBC packet is sent to the Venus chain. This packet contains information that is used to create a buy order book on the Venus chain.
When the Venus chain receives the IBC packet, it processes the information contained in the packet and creates a buy order book. The Venus chain then sends an acknowledgement back to the Mars chain to confirm that the buy order book has been successfully created.
Upon receiving the acknowledgement from the Venus chain, the Mars chain creates a sell order book. This sell order book is associated with the buy order book on the Venus chain, allowing users to trade assets between the two chains.
Sell Order
After creating an order book, the next step is to create a sell order. This can be done using the send-sell-order command, which is used to broadcast a transaction with a message that locks a specified amount of tokens and creates a sell order on the Mars blockchain.
In the example provided, the send-sell-order command is used to create a sell order for 10 marscoin token and 15 venuscoin token. This sell order will be added to the order book on the Mars blockchain.
Buy order
After creating a sell order, the next step in the trading process is typically to create a buy order. This can be done using the send-buy-order command, which is used to lock a specified amount of tokens and create a buy order on the Venus blockchain
In the example provided, the send-buy-order command is used to create a buy order for 10 marscoin token and 5 venuscoin token. This buy order will be added to the order book on the Venus blockchain.
Perform an Exchange with a Sell Order
You currently have two open orders for marscoin:
A sell order on the Mars chain, where you are offering to sell 10
marscoinfor 15venuscoin.A buy order on the Venus chain, where you are willing to buy 5
marscoinfor 5venuscoin.
To perform an exchange, you can send a sell order to the Mars chain using the following command:
This sell order, offering to sell 5 marscoin for 3 venuscoin, will be filled on the Venus chain by the existing buy order. This will result in the amount of the buy order on the Venus chain being reduced by 5 marscoin.
The sender of the filled sell order traded 5 marscoin for 25 venuscoin tokens. This means that the amount of the sell order (5 marscoin) was multiplied by the price of the buy order (5 venuscoin) to determine the value of the exchange. In this case, the value of the exchange was 25 venuscoin vouchers.
The counterparty, or the sender of the buy marscoin order, will receive 5 marscoin as a result of the exchange.
The venuscoin balance has remained unchanged because the appropriate amount of venuscoin (50) was already locked at the time the buy order was created in the previous step.
Perform an Exchange with a Buy Order
To perform an exchange with a buy order, send a transaction to the decentralized exchange to buy 5 marscoin for 15 venuscoin. This is done by running the following command:
This buy order will be immediately filled on the Mars chain, and the creator of the sell order will receive 75 venuscoin vouchers as payment.
The amount of the sell order will be decreased by the amount of the filled buy order, so in this case it will be decreased by 5 marscoin.
The creator of the buy order receives 5 marscoin vouchers for 75 venuscoin (5marscoin * 15venuscoin):
Complete Exchange with a Partially Filled Sell Order
To complete the exchange with a partially filled sell order, send a transaction to the decentralized exchange to sell 10 marscoin for 3 venuscoin. This is done by running the following command:
In this scenario, the sell amount is 10 marscoin, but there is an existing buy order for only 5 marscoin. The buy order will be filled completely and removed from the order book. The author of the previously created buy order will receive 10 marscoin vouchers from the exchange.
To check the balances, she can run the following command:
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
To complete the exchange with a partially filled buy order, send a transaction to the decentralized exchange to buy 10 marscoin for 5 venuscoin. This is done by running the following command:
In this scenario, the buy order is only partially filled for 5 marscoin. There is an existing sell order for 5 marscoin (with a price of 3 venuscoin) on the Mars chain, which is completely filled and removed from the order book. The author of the closed sell order will receive 15 venuscoin vouchers as payment, which is the product of 5 marscoin and 3 venuscoin.
In this scenario, the author of the buy order will receive 5 marscoin vouchers as payment, which locks up 50 venuscoin of their token. The remaining 5 marscoin that is not filled by the sell order will create a new buy order on the Venus chain. This means that the author of the buy order is still interested in purchasing 5 marscoin, and is willing to pay the specified price for it. The new buy order will remain on the order book until it is filled by another sell order, or it is cancelled by the buyer.
Cancel an Order
After the exchanges described, there are still two open orders: a sell order on the Mars chain (5 marscoin for 15 venuscoin), and a buy order on the Venus chain (5 marscoin for 5 venuscoin).
To cancel an order on a blockchain, you can use the cancel-sell-order or cancel-buy-order command, depending on the type of order you want to cancel. The command takes several arguments, including the channel-id of the IBC connection, the amount-denom and price-denom of the order, and the order-id of the order you want to cancel.
To cancel a sell order on the Mars chain, you would run the following command:
This will cancel the sell order and remove it from the order book. The balance of Alice's marscoin will be increased by the amount of the cancelled sell order.
To check Alice's balances, including her updated marscoin balance, run the following command:
This will return a list of Alice's balances, including her updated marscoin balance.
After the sell order on the Mars chain has been cancelled, the sell order book on that blockchain will be empty. This means that there are no longer any active sell orders on the Mars chain, and anyone interested in purchasing marscoin will need to create a new buy order. The sell order book will remain empty until a new sell order is created and added to it.
To cancel a buy order on the Venus chain, you can run the following command:
This will cancel the buy order and remove it from the order book. The balance of Alice's venuscoin will be increased by the amount of the cancelled buy order.
To check Alice's balances, including her updated venuscoin balance, you can run the following command:
The amount of venuscoin is increased:
This will return a list of Alice's balances, including her updated venuscoin balance.
After canceling a buy order, the buy order book on the Venus blockchain will be empty. This means that there are no longer any active buy orders on the chain, and anyone interested in selling marscoin will need to create a new sell order. The buy order book will remain empty until a new buy order is created and added to it.
In this walkthrough, we demonstrated how to set up an interchain exchange for trading tokens between two different blockchain networks. This involved creating an exchange order book for a specific token pair and establishing a fixed exchange rate between the two.
Once the exchange was set up, users could send sell orders on the Mars chain and buy orders on the Venus chain. This allowed them to offer their tokens for sale or purchase tokens from the exchange. In addition, users could also cancel their orders if needed.