# Inter-Blockchain Communication: Basics
The Inter-Blockchain Communication protocol (IBC) is an important part of the Cosmos SDK ecosystem. The Hello World tutorial is a time-honored tradition in computer programming. This tutorial builds an understanding of how to create and send packets across blockchain. This foundational knowledge helps you navigate between blockchains with the Cosmos SDK.
You will learn how to
- Use IBC to create and send packets between blockchains.
- Navigate between blockchains using the Cosmos SDK and the Ignite CLI Relayer.
- Create a basic blog post and save the post on another blockchain.
# What is IBC?
The Inter-Blockchain Communication protocol (IBC) allows blockchains to talk to each other. IBC handles transport across different sovereign blockchains. This end-to-end, connection-oriented, stateful protocol provides reliable, ordered, and authenticated communication between heterogeneous blockchains.
The IBC protocol in the Cosmos SDK (opens new window) is the standard for the interaction between two blockchains. The IBCmodule interface defines how packets and messages are constructed to be interpreted by the sending and the receiving blockchain.
The IBC relayer lets you connect between sets of IBC-enabled chains. This tutorial teaches you how to create two blockchains and then start and use the relayer with Ignite CLI to connect two blockchains.
This tutorial covers essentials like modules, IBC packets, relayer, and the lifecycle of packets routed through IBC.
# Create a blockchain
Create a blockchain app with a blog module to write posts on other blockchains that contain the Hello World message. For this tutorial, you can write posts for the Cosmos SDK universe that contain Hello Mars, Hello Cosmos, and Hello Earth messages.
For this simple example, create an app that contains a blog module that has a post transaction with title and text.
After you define the logic, run two blockchains that have this module installed.
The chains can send posts between each other using IBC.
On the sending chain, save the
After the transaction is acknowledged by the receiving chain, you know that the post is saved on both blockchains.
The sending chain has the additional data
Sent posts that are acknowledged and timed out contain the title and the target chain of the post. These identifiers are visible on the parameter
chain. The following chart shows the lifecycle of a packet that travels through IBC.
# Build your blockchain app
Use Ignite CLI to scaffold the blockchain app and the blog module.
# Build a new blockchain
To scaffold a new blockchain named
A new directory named
planet is created in your home directory. The
planet directory contains a working blockchain app.
# Scaffold the blog module inside your blockchain
Next, use Ignite CLI to scaffold a blog module with IBC capabilities. The blog module contains the logic for creating blog posts and routing them through IBC to the second blockchain.
To scaffold a module named
A new directory with the code for an IBC module is created in
planet/x/blog. Modules scaffolded with the
--ibc flag include all the logic for the scaffolded IBC module.
# Generate CRUD actions for types
Next, create the CRUD actions for the blog module types.
ignite scaffold list command to scaffold the boilerplate code for the create, read, update, and delete (CRUD) actions.
ignite scaffold list commands create CRUD code for the following transactions:
Creating blog posts
Processing acknowledgments for sent posts
Managing post timeouts
The scaffolded code includes proto files for defining data structures, messages, messages handlers, keepers for modifying the state, and CLI commands.
# Ignite CLI Scaffold List Command Overview
The first argument of the
ignite scaffold list [typeName] command specifies the name of the type being created. For the blog app, you created
The next arguments define the fields that are associated with the type. For the blog app, you created
--module flag defines which module the new transaction type is added to. This optional flag lets you manage multiple modules within your Ignite CLI app. When the flag is not present, the type is scaffolded in the module that matches the name of the repo.
When a new type is scaffolded, the default behavior is to scaffold messages that can be sent by users for CRUD operations. The
--no-message flag disables this feature. Disable the messages option for the app since you want the posts to be created upon reception of IBC packets and not directly created from a user's messages.
# Scaffold a sendable and interpretable IBC packet
You must generate code for a packet that contains the title and the content of the blog post.
ignite packet command creates the logic for an IBC packet that can be sent to another blockchain.
contentare stored on the target chain.
postIDis acknowledged on the sending chain.
To scaffold a sendable and interpretable IBC packet:
Notice the fields in the
ibcPost packet match the fields in the
post type that you created earlier.
--ackflag defines which identifier is returned to the sending blockchain.
--moduleflag specifies to create the packet in a particular IBC module.
ignite packet command also scaffolds the CLI command that is capable of sending an IBC packet:
# Modify the source code
After you create the types and transactions, you must manually insert the logic to manage updates in the database. Modify the source code to save the data as specified earlier in this tutorial.
# Add creator to the blog post packet
Start with the proto file that defines the structure of the IBC packet.
To identify the creator of the post in the receiving blockchain, add the
creator field inside the packet. This field was not specified directly in the command because it would automatically become a parameter in the
SendIbcPost CLI command.
To make sure the receiving chain has content on the creator of a blog post, add the
msg.Creator value to the IBC
- The content of the
senderof the message is automatically included in
- The sender is verified as the signer of the message, so you can add the
msg.Senderas the creator to the new packet before it is sent over IBC.
# Receive the post
The methods for primary transaction logic are in the
planet/x/blog/keeper/ibc_post.go file. Use these methods to manage IBC packets:
TransmitIbcPostPacketis called manually to send the packet over IBC. This method also defines the logic before the packet is sent over IBC to another blockchain app.
OnRecvIbcPostPackethook is automatically called when a packet is received on the chain. This method defines the packet reception logic.
OnAcknowledgementIbcPostPackethook is called when a sent packet is acknowledged on the source chain. This method defines the logic when the packet has been received.
OnTimeoutIbcPostPackethook is called when a sent packet times out. This method defines the logic when the packet is not received on the target chain
You must modify the source code to add the logic inside those functions so that the data tables are modified accordingly.
On reception of the post message, create a new post with the title and the content on the receiving chain.
To identify the blockchain app that a message is originating from and who created the message, use an identifier in the following format:
Finally, the Ignite CLI-generated AppendPost function returns the ID of the new appended post. You can return this value to the source chain through acknowledgment.
Append the type instance as
PostID on receiving the packet:
- The context
ctxis an immutable data structure (opens new window) that has header data from the transaction. See how the context is initiated (opens new window)
- The identifier format that you defined earlier
titleis the Title of the blog post
contentis the Content of the blog post
x/blog/keeper/ibc_post.go file, make sure to import
Then modify the
OnRecvIbcPostPacket keeper function with the following code:
# Receive the post acknowledgement
On the sending blockchain, store a
sentPost so you know that the post has been received on the target chain.
Store the title and the target to identify the post.
When a packet is scaffolded, the default type for the received acknowledgment data is a type that identifies if the packet treatment has failed. The
Acknowledgement_Error type is set if
OnRecvIbcPostPacket returns an error from the packet.
# Store information about the timed-out packet
Store posts that have not been received by target chains in
timedoutPost posts. This logic follows the same format as
This last step completes the basic
blog module setup. The blockchain is now ready!
# Use the IBC modules
You can now spin up the blockchain and send a blog post from one blockchain app to the other. Multiple terminal windows are required to complete these next steps.
# Test the IBC modules
To test the IBC module, start two blockchain networks on the same machine. Both blockchains use the same source code. Each blockchain has a unique chain ID.
One blockchain is named
earth and the other blockchain is named
mars.yml files are required in the project directory:
Open a terminal window and run the following command to start the
Open a different terminal window and run the following command to start the
# Remove Existing Relayer and Ignite CLI Configurations
If you previously used the relayer, follow these steps to remove exiting relayer and Ignite CLI configurations:
Stop your blockchains and delete previous configuration files:
If existing relayer configurations do not exist, the command returns
no matches found and no action is taken.
# Configure and start the relayer
First, configure the relayer. Use the Ignite CLI
configure command with the
When prompted, press Enter to accept the default values for
Source Account and
The output looks like:
In a new terminal window, start the relayer process:
# Send packets
You can now send packets and verify the received posts:
To verify that the post has been received on Mars:
The packet has been received:
To check if the packet has been acknowledged on Earth:
To test timeout, set the timeout time of a packet to 1 nanosecond, verify that the packet is timed out, and check the timed-out posts:
Check the timed-out posts:
You can also send a post from Mars:
List post on Earth:
# Congratulations 🎉
By completing this tutorial, you've learned to use the Inter-Blockchain Communication protocol (IBC).
Here's what you accomplished in this tutorial:
- Built two Hello blockchain apps as IBC modules
- Modified the generated code to add CRUD action logic
- Configured and used the Ignite CLI relayer to connect two blockchains with each other
- Transferred IBC packets from one blockchain to another