Build Your Interchain Security Consumer Chain

Tobias Schwarz

Sep 16, 2024 • 5 min read

Learn about Interchain Security with Ignite CLI.

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.

Once you have copied the Makefile, run:

make all

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 install
```
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.