Build Your Interchain Security Consumer Chain
This tutorial will cover how to create a new ICS consumer chain using Ignite CLI.
In the chapters afterwards, you can learn how to create your own provider chain and connect both to create your own full development environment.
Requirements
Before proceeding, ensure you meet the following requirements:
- Go: Make sure you have Go installed on your machine. You can install it here.
- Ignite CLI: The Makefile handles the installation, but if you'd like to install it manually, visit the Ignite CLI Installation Guide.
Quick Start
Create a new Cosmos SDK consumer chain:
ignite scaffold chain <yourchainname> --consumer --skip-proto --no-module
Then name ccv
is a common convention for consumer and would be scaffolded as follows:
ignite scaffold chain ccv --consumer --skip-proto --no-module
This creates a new directory ccv
with a configured consumer chain. On this chain you are expected to add your business logic.
Learn how to create your own modules on our tutorials page.
Connect your chain
Next to creating a consumer chain is adding it to the provider chain to gain access to the security providers of the provider chain
.
In a production environment, the provider chain is typically already running, and you would only need to create and submit your proposal to connect the consumer chain. However, we provide a
Makefile
for testing and local development that automates the entire setup with scripts, allowing you to quickly create both the provider and consumer chains. If you prefer a more detailed approach or need manual configurations, refer to the Advanced Configuration Section.
This process will require the following steps:
- Download and install the Interchain Security (ICS) source code
- Run the provider chain
- Create a proposal to add the consumer chain to the provider chain
- Start the consumer chain
Makefile
To get started quickly, use the Makefile
provided. It automates the setup of both the provider and consumer chains for local testing and development with pre-defined scripts.
Extra Requirements
- Hermes Relayer: To handle cross-chain communication, install the Hermes relayer from here. Ensure that Hermes is properly configured before proceeding with IBC connections.
Setup
-
Clone the ICS repository and navigate to the ICS directory:
git clone https://github.com/cosmos/interchain-security && cd interchain-security
-
Once you are inside the
ics/
directory, run:make all
This will automatically perform the following steps:
- Install ICS binaries and Ignite CLI.
- Set up and start the provider chain.
- Scaffold the consumer chain.
- Submit a proposal for adding the consumer chain to the provider chain.
- Automatically cast a "yes" vote on the proposal.
-
After the vote passes, manually start the consumer chain:
interchain-security-cd start
-
To stop the provider chain, run:
make stop
-
To clean up your environment and remove all data, use:
make clean
Detailed Breakdown (Advanced Configuration)
For users who prefer a more manual setup and want to dive deeper into the process's inner workings, here is a breakdown of each step, including script execution and manual configuration.
Set Up the ICS Environment
Start by cloning the ICS repository and installing the necessary binaries:
git clone https://github.com/cosmos/interchain-security && cd interchain-security
git checkout v5.1.1
make install
This will install two binaries that we will use in the following steps:
# Provider chain binary
interchain-security-pd
# Consumer chain binary
interchain-security-cd
Run the Provider Chain
Next, set up and run the provider chain using the pre-defined script:
sh provider/create_and_start.sh
This script will perform the following actions:
- Initialize the provider chain
- Configure genesis parameters
- Generate key pairs for both the validator and delegator
- Add initial funds to the accounts
- Stake the validator and start the provider node
The provider chain will also generate the necessary genesis files and bootstrap the network, preparing it for the consumer chain proposal.
Scaffold a New Consumer Chain
In a separate terminal tab or window, scaffold the consumer chain using the Ignite CLI:
ignite scaffold chain ccv --consumer --skip-proto --no-module
Submit and Vote on the Proposal
Once your consumer chain is scaffolded, you need to submit a proposal to connect it to the provider chain. This step is critical, as the timing for the consumer chain's genesis must be carefully considered in relation to the proposal's approval.
-
Create the consumer chain proposal:
Ensure the spawn time is set to AFTER the proposal passes:
The following JSON configuration is an example setup for submitting a consumer chain proposal. Be sure to check and adjust values as needed, such as
chain_id
,genesis_hash
,binary_hash
,spawn_time
, and other parameters to match your specific chain configuration and requirements.tee $PROVIDER_HOME/consumer-proposal.json<<EOF { "messages": [ { "@type": "/interchain_security.ccv.provider.v1.MsgConsumerAddition", "chain_id": "ccv-1", "initial_height": { "revision_number": "1", "revision_height": "1" }, "genesis_hash": "519df96a862c30f53e67b1277e6834ab4bd59dfdd08c781d1b7cf3813080fb28", "binary_hash": "09184916f3e85aa6fa24d3c12f1e5465af2214f13db265a52fa9f4617146dea5", "spawn_time": "2024-08-01T12:03:00.000000000-00:00", "unbonding_period": "600s", "ccv_timeout_period": "1200s", "consumer_redistribution_fraction": "0.75", "blocks_per_distribution_transmission": "1000", "distribution_transmission_channel": "channel-1", "top_N": 95, "validators_power_cap": 0, "validator_set_cap": 0, "allowlist": [], "denylist": [], "authority": "cosmos10d07y265gmmuvt4z0w9aw880jnsr700j6zn9kn" } ], "metadata": "ipfs://CID", "deposit": "50000stake", "title": "Create a chain", "summary": "Gonna be a great chain", "expedited": false } EOF
-
Submit the proposal to the governance module:
$PROVIDER_BINARY tx gov submit-proposal $PROVIDER_HOME/consumer-proposal.json \ --chain-id $PROVIDER_CHAIN_ID --from $VALIDATOR --home $PROVIDER_HOME --node tcp://$PROVIDER_RPC_LADDR --keyring-backend test -b sync -y
-
Dynamically retrieve the proposal ID and vote on the proposal:
proposal_id=$($PROVIDER_BINARY q gov proposals --output json | jq -r '.proposals[-1].proposal_id') $PROVIDER_BINARY tx gov vote $$proposal_id yes --from $VALIDATOR --chain-id $PROVIDER_CHAIN_ID --node tcp://$PROVIDER_RPC_LADDR --home $PROVIDER_HOME -y --keyring-backend test sleep 5 # Wait for the vote to be processed
Start the Consumer Chain
Once the proposal has passed and the consumer chain is approved, you need to start the consumer chain and connect it to the provider chain.
-
Collect the Cross-Chain Validation (CCV) state from the provider chain:
interchain-security-pd q provider consumer-genesis ccv-1 --node tcp://localhost:26658
-
Update the consumer chain's genesis file with the CCV state:
jq -s '.[0].app_state.ccvconsumer = .[1] | .[0]' <consumer genesis without CCV state> ccv-state.json > <consumer genesis file with CCV state>
-
Start the consumer chain:
interchain-security-cd start
Create IBC Channels and Connections
Once both chains are running, you need to establish IBC channels for communication between the provider and consumer chains. This is done using the Hermes relayer:
-
Query the IBC client ID of the provider chain:
gaiad q provider list-consumer-chains
-
Use Hermes to create the necessary IBC connections and channels:
hermes create connection --a-chain <consumer chain ID> --a-client 07-tendermint-0 --b-client <provider chain client ID> hermes create channel --a-chain <consumer chain ID> --a-port consumer --b-port provider --order ordered --a-connection connection-0 --channel-version 1
Start the Hermes Relayer
Finally, start the Hermes relayer to sync the validator sets and ensure that the chains remain in sync:
hermes start
Ensure that the relayer's trusting period is configured correctly in line with the provider chain's settings (the trusting period fraction is typically set to 0.25).
We have created a short script for you to eventually stop all provider chains.
Congratulations, you've managed to create your own Consumer Chain and hook it to a running Provider Chain.