Onboarding Checklist | Interchain Security

The following checklists will aid in onboarding a new consumer chain to interchain security.

Additionally, you can check the testnet repo for a comprehensive guide on preparing and launching consumer chains.

1. Complete testing & integration

2. Create an Onboarding Repository

To help validators and other node runners onboard onto your chain, please prepare a repository with information on how to run your chain.

3. Submit a Governance Proposal

Before you submit a ConsumerChainAddition proposal, please consider allowing at least a day between your proposal passing and the chain spawn time. This will allow the validators, other node operators and the community to prepare for the chain launch. If possible, please set your spawn time so people from different parts of the globe can be available in case of emergencies. Ideally, you should set your spawn time to be between 12:00 UTC and 20:00 UTC so most validator operators are available and ready to respond to any issues.

Additionally, reach out to the community via the forum to formalize your intention to become an ICS consumer, gather community support and accept feedback from the community, validators and developers.

// ConsumerAdditionProposal is a governance proposal on the provider chain to spawn a new consumer chain.
// If it passes, if the top_N parameter is not equal to 0, the top N% of validators by voting power on the provider chain are expected to validate the consumer chain at spawn time.
// Otherwise, only validators that opted in during the proposal period are expected to validate the consumer chain at spawn time.
// It is recommended that spawn time occurs after the proposal end time.
{
    // Title of the proposal
    "title": "Add consumer chain",
    // Description of the proposal
    // format the text as a .md file and include the file in your onboarding repository
    "description": ".md description of your chain and all other relevant information",
    // Proposed chain-id of the new consumer chain.
    // Must be unique from all other consumer chain ids of the executing provider chain.
    "chain_id": "newchain-1",
    // Initial height of new consumer chain.
    // For a completely new chain, this will be {0,1}.
    "initial_height" : {
        "revision_height": 0,
        "revision_number": 1,
    },
    // Hash of the consumer chain genesis state without the consumer CCV module genesis params.
    // It is used for off-chain confirmation of genesis.json validity by validators and other parties.
    "genesis_hash": "d86d756e10118e66e6805e9cc476949da2e750098fcc7634fd0cc77f57a0b2b0",
    // Hash of the consumer chain binary that should be run by validators on chain initialization.
    // It is used for off-chain confirmation of binary validity by validators and other parties.
    "binary_hash": "376cdbd3a222a3d5c730c9637454cd4dd925e2f9e2e0d0f3702fc922928583f1",
    // Time on the provider chain at which the consumer chain genesis is finalized and validators
    // will be responsible for starting their consumer chain validator node.
    "spawn_time": "2023-02-28T20:40:00.000000Z",
    // Unbonding period for the consumer chain.
    // It should be smaller than that of the provider.
    "unbonding_period": 86400000000000,
    // Timeout period for CCV related IBC packets.
    // Packets are considered timed-out after this interval elapses.
    "ccv_timeout_period": 259200000000000,
    // IBC transfer packets will timeout after this interval elapses.
    "transfer_timeout_period": 1800000000000,
    // The fraction of tokens allocated to the consumer redistribution address during distribution events.
    // The fraction is a string representing a decimal number. For example "0.75" would represent 75%.
    // The reward amount distributed to the provider is calculated as: 1 - consumer_redistribution_fraction.
    "consumer_redistribution_fraction": "0.75",
    // BlocksPerDistributionTransmission is the number of blocks between IBC token transfers from the consumer chain to the provider chain.
    // eg. send rewards to the provider every 1000 blocks
    "blocks_per_distribution_transmission": 1000,
    // The number of historical info entries to persist in store.
    // This param is a part of the cosmos sdk staking module. In the case of
    // a ccv enabled consumer chain, the ccv module acts as the staking module.
    "historical_entries": 10000,
    // The ID of a token transfer channel used for the Reward Distribution
	// sub-protocol. If DistributionTransmissionChannel == "", a new transfer
	// channel is created on top of the same connection as the CCV channel.
	// Note that transfer_channel_id is the ID of the channel end on the consumer chain.
    // it is most relevant for chains performing a standalone to consumer changeover
    // in order to maintain the existing ibc transfer channel
    "distribution_transmission_channel": "channel-123",
    // Corresponds to the percentage of validators that have to validate the chain under the Top N case.
    // For example, 53 corresponds to a Top 53% chain, meaning that the top 53% provider validators by voting power
    // have to validate the proposed consumer chain. top_N can either be 0 or any value in [50, 100].
    // A chain can join with top_N == 0 as an Opt In chain, or with top_N ∈ [50, 100] as a Top N chain.
    "top_N": 95,
    // Corresponds to the maximum power (percentage-wise) a validator can have on the consumer chain. For instance, if
    // `validators_power_cap` is set to 32, it means that no validator can have more than 32% of the voting power on the
    // consumer chain. Note that this might not be feasible. For example, think of a consumer chain with only
    // 5 validators and with `validators_power_cap` set to 10%. In such a scenario, at least one validator would need
    // to have more than 20% of the total voting power. Therefore, `validators_power_cap` operates on a best-effort basis.
    "validators_power_cap": 0,
    // Corresponds to the maximum number of validators that can validate a consumer chain.
    // Only applicable to Opt In chains. Setting `validator_set_cap` on a Top N chain is a no-op.
    "validator_set_cap": 0,
    // Corresponds to a list of provider consensus addresses of validators that are the ONLY ones that can validate
    // the consumer chain.
    "allowlist": [],
    // Corresponds to a list of provider consensus addresses of validators that CANNOT validate the consumer chain.
    "denylist": []
}

4. Launch

The consumer chain starts after at least 66.67% of its voting power comes online. Note that this means 66.67% of the voting power in the consumer validator set, which will be comprised of all validators that either opted in to the chain or are part of the top N% of the provider chain (and are thus automatically opted in). The consumer chain is considered interchain secured once the appropriate CCV channels are established and the first validator set update is propagated from the provider to the consumer

Consumer Onboarding Checklist

1. Complete testing & integration​

2. Create an Onboarding Repository​

3. Submit a Governance Proposal​

4. Launch​

1. Complete testing & integration

2. Create an Onboarding Repository

3. Submit a Governance Proposal

4. Launch