Overview
We advise that you join the Interchain Security testnet to gain hands-on experience with running consumer chains.
At present, Interchain Security requires some or all the validators of the provider chain (ie. Cosmos Hub) to run validator nodes for a consumer chain.
Whether a validator has to run a validator node for a consumer chain depends on whether the consumer chain is a Top N or an
Opt-In chain and also on the power-shaping features. A validator can use the
has-to-validate query
to keep track of all the chains it has to validate.
Once a ConsumerAdditionProposal passes, relevant validators need to prepare to run the consumer chain binaries (these will be linked in their proposals) and set up validator nodes on governance-approved consumer chains.
Provider chain and consumer chains represent standalone chains that only share part of the validator set.
To validate a consumer chain and be eligible for rewards, validators are required to be in the active set of the provider chain (first 180 validators for Cosmos Hub).
Startup sequence overview
Consumer chains cannot start and be secured by the validator set of the provider unless a ConsumerAdditionProposal is passed.
Each proposal contains defines a spawn_time - the timestamp when the consumer chain genesis is finalized and the consumer chain clients get initialized on the provider.
Validators are required to run consumer chain binaries only after spawn_time has passed.
Please note that any additional instructions pertaining to specific consumer chain launches will be available before spawn time. The chain start will be stewarded by the Cosmos Hub team and the teams developing their respective consumer chains.
The image below illustrates the startup sequence
1. Consumer Chain init + 2. Genesis generation
Consumer chain team initializes the chain genesis.json and prepares binaries which will be listed in the ConsumerAdditionProposal
3. Submit Proposal
Consumer chain team (or their advocates) submits a ConsumerAdditionProposal.
The most important parameters for validators are:
spawn_time- the time after which the consumer chain must be startedgenesis_hash- hash of the pre-ccv genesis.json; the file does not contain any validator info -> the information is available only after the proposal is passed andspawn_timeis reachedbinary_hash- hash of the consumer chain binary used to validate the software builds
4. CCV Genesis state generation
After reaching spawn_time the provider chain will automatically create the CCV validator states that will be used to populate the corresponding fields in the consumer chain genesis.json. The CCV validator set consists of the validator set on the provider at spawn_time.
The state can be queried on the provider chain (in this case the Cosmos Hub):
gaiad query provider consumer-genesis <consumer chain ID> -o json > ccvconsumer_genesis.json
This is used by the launch coordinator to create the final genesis.json that will be distributed to validators in step 5.
5. Updating the genesis file
Upon reaching the spawn_time the initial validator set state will become available on the provider chain. The initial validator set is included in the final genesis.json of the consumer chain.
6. Chain start
The consumer chain will start producing blocks as soon as 66.67% of the provider chain's voting power comes online (on the consumer chain). The relayer should be started after block production commences.
The new genesis.json containing the initial validator set will be distributed to validators by the consumer chain team (launch coordinator). Each validator should use the provided genesis.json to start their consumer chain node.
Please pay attention to any onboarding repositories provided by the consumer chain teams. Recommendations are available in Consumer Onboarding Checklist. Another comprehensive guide is available in the Interchain Security testnet repo.
7. Creating IBC connections
Finally, to fully establish interchain security an IBC relayer is used to establish connections and create the required channels.
The relayer can establish the connection only after the consumer chain starts producing blocks.
hermes create connection --a-chain <consumer chain ID> --a-client 07-tendermint-0 --b-client <client assigned by provider chain>
hermes create channel --a-chain <consumer chain ID> --a-port consumer --b-port provider --order ordered --a-connection connection-0 --channel-version 1
hermes start
Downtime Infractions
At present, the consumer chain can report evidence about downtime infractions to the provider chain. The min_signed_per_window and signed_blocks_window can be different on each consumer chain and are subject to changes via consumer chain governance.
Causing a downtime infraction on any consumer chain will not incur a slash penalty. Instead, the offending validator will be jailed on the provider chain and consequently on all consumer chains.
To unjail, the validator must wait for the jailing period to elapse on the provider chain and submit an unjail transaction on the provider chain. After unjailing on the provider, the validator will be unjailed on all consumer chains.
More information is available in Downtime Slashing documentation
Double-signing Infractions
To learn more about equivocation handling in interchain security check out the Slashing documentation section.
Key assignment
Validators can use different consensus keys on the provider and each of the consumer chains. The consumer chain consensus key must be registered on the provider before use.
For more information check out the Key assignment overview and guide