Integrating with Babylon
Learn how to integrate a Cosmos Zone with Babylon.
At the moment, Babylon provides a canonical chain oracle for each integrated Cosmos zone, and allows anyone to query the canonical chains of integrated Cosmos zones and query the fork headers created by a validator set with dishonest majority. In the future, integrating Babylon will allows Cosmos zones to raise alarms upon dishonest majority attacks, and reduce the unbonding time.
In order to integrate a Cosmos zone to Babylon, the first option would be sending an email to the Babylon team, then the Babylon team will deploy a relayer for your blockchain. Alternatively, anyone can integrate any Cosmos zone to Babylon by running an IBC relayer specialized for Babylon. The special IBC relayer uses a subset of the IBC protocol, and there is no need to modify the integrated Cosmos zone's code, or have tokens in the integrated Cosmos zone.
Babylon IBC relayer
In order to provide a canonical chain oracle for Cosmos zones, Babylon only needs to use a subset of IBC protocols. Specifically, Babylon needs to maintain an IBC light client for the integrated Cosmos zone, but not the other way. However, existing relayers, including the Go relayer and the Rust Hermes relayer, are designed for the full IBC protocol stack with an emphasis on IBC packets, thus only provide functionalities for updating both IBC clients in two Cosmos zones and relaying IBC packets among them.
To this end, the Babylon team has developed a special IBC relayer based on the official IBC relayer in Golang. The special IBC relayer allows one to maintain an IBC light client of a Cosmos zone in Babylon, and periodically forward headers of the Cosmos zone to Babylon. It gives us the following advantages:
- Integrating a Cosmos zone to Babylon only needs Babylon accounts and tokens. Accounts and tokens of integrated Cosmos zones are not needed.
- Integrating a Cosmos zone to Babylon incurs zero computational or storage overhead on integrated Cosmos zones.
Running a Babylon IBC relayer
Running a Babylon IBC relayer consists of the following steps:
- Install the Babylon Relayer
- Configure the Babylon Relayer
- Create a keyring for the Babylon relayer
- Obtain Babylon tokens
- Start the Babylon Relayer
Install the Babylon Relayer
The Babylon relayer is located at GitHub.
Please follow the documentation for installing it.
In summary, after cloning the repository,
navigate to the folder in which you cloned it,
checkout to the version you want to install (e.g.
git checkout v0.3.0),
$ make install
This will install the
babylon-relayer binary. You can verify that everything worked properly by running,
$ babylon-relayer --help
1. Configuration management for Chains and Paths
2. Key management for managing multiple keys for multiple chains
3. Query and transaction functionality for IBC
4. Functionality for relaying headers from Cosmos Zones to Babylon periodically
NOTE: Most of the commands have aliases that make typing them much quicker
(i.e. 'babylon-relayer tx', 'babylon-relayer q', etc...)
Configure the Babylon Relayer
The default Babylon relayer home directory is
You can specify a different Babylon relayer home directory through the
--home CLI flag.
For the purposes of this document and for simplicity,
we will assume that the home directory is
The configuration file for the relayer is located under the
In our case,
An example config file for integrating Osmosis testnet is as follows:
# Name for the Babylon chain
# REPLACEME: Name of the key in the keyring that will be used to send transactions to Babylon.
# We will create this key on the next step.
# REPLACEME: The Chain ID of the Babylon network you want to connect to.
# For example, for the current testnet, this is `bbn-test-2`
# Note that this chain ID should be the same one you used for creating the keyring.
# REPLACEME: The RPC endpoint of a node that runs on the Babylon network you want to connect to.
# The backend of the keyring you're using. Recall that this should always be `test`.
# Gas prices and gas adjustment.
# Name for the chain to be integrated
# REPLACEME: The chain ID of the chain you want to integrate with Babylon
# REPLACEME: The RPC endpoint of a node that runs on the network of the chain you want to integrate with Babylon.
# Name of the relayer path
# Chain IDs that this path will connect
# REPLACEME: Use the chain IDs For Babylon and the integrated chain you specified above.
Create a key for the Babylon relayer
After specifying the configuration, we need to create a keyring that will pay the transaction fees for sending transactions to the Babylon chain.
We have two options:
- Create a keyring from scratch
$ babylon-relayer keys add $BABYLON_NAME $BABYLON_KEY_NAME
- Import an already existing keyring. For this you're going to need the mnemonic
$ babylon-relayer keys restore $BABYLON_NAME $BABYLON_KEY_NAME "$MNEMONIC"
In the above commands,
$BABYLON_NAMEis the name assigned to the Babylon chain in the configuration file. In the example configuration above this is
$BABYLON_KEY_NAMEis the name assigned to the key for Babylon in the configuration file. In the example configuration above this is
$MNEMONICis the mnemonic for the key you want to import.
To verify that your key has been included, you can execute:
$ babylon-relayer keys list $BABYLON_NAME
If all worked as expected, you should see the key address in the output.
Obtain Babylon Tokens
Now it's time to obtain the tokens that will be used to pay for Babylon transaction fees for relaying headers. Those funds should go to the address of the key you created on the previous step. You can obtain funds through the faucet found in the Babylon Discord.
Start the Babylon Relayer
To start the Babylon relayer,
$ babylon-relayer keep-update-clients --interval $INTERVAL
$INTERVAL is the interval for relaying a header (e.g.,
10m to denote 10 minutes per header).
Check if the Integration is Successful
After the above steps, the Cosmos zone has been integrated to Babylon. You can do the following things to check the status of the integration:
- Check the Babylon node API http://rpc.testnet.babylonchain.io:1317/babylon/zoneconcierge/v1/chain_info/<your_chain_id> that shows the information of the Cosmos zone in Babylon's view.
- Check whether BabylonScan shows the information of the Cosmos zone or not.
- NOTE: one needs to submit a PR to Babylon's chain registry in order to be shown on BabylonScan
Future Integration Phases
In the future, Babylon will enable further integration phases, such as raising alarms upon dishonest majority attacks and reducing the unbonding time period. Such integrations will need IBC packets, thus require using the original IBC relayer rather than the above specialized one. Please see Zone Concierge for more details.