ICS Simulation Testing

7. December 2023

For the past few months, we at CryptoCrew, have been developing a testing suite to simulate the onboarding of new chains into the Atom Economic Zone. This work was done as part of our AADAO Grant: Replicated Security KickStart Service.

The goal of this testing suite is to make it easier for developers to check whether their chain is compatible with ICS (interchain security) and to provide methods for testing common ICS functions.

The entirety of the testing suite is written in bash script, so it is rather easy to adjust and expand with new tasks.

This article will mention the terms provider chain, consumer chain and sovereign chain. Here is a short definition, for clarification purposes:

  • Sovereign Chain = a standalone blockchain
  • Provider Chain = a blockchain that provides security to a consumer chain by sharing it’s validator set
  • Consumer Chain = a blockchain which is being secured by the validator set of a provider chain

What does the ICS Testing Suite encompass?

As stated above, the purpose of these tests is to help developers with testing their chains early on in the process, to reveal common ICS pitfalls or other unexpected problems that may become severe later in the development process.

Addition and Migration

There are two ways in which a chain may become a consumer chain.

  1. A consumer addition is proposed on the provider chain and the consumer chain will start once the spawn time, which is specified in the proposal, has been reached. (Addition)
  2. A chain is already running and decides to become a consumer chain via a similar consumer addition proposal on the provider chain. (Migration)

The ICS Testing Suite gives developers the option to test both scenarios.

Getting Started

At its core, the ICS Testing Suite launches two separate local blockchains with a predefined number of validators. The validator nodes are run in Vagrant virtual machines. 

The first thing that needs to be done is to adjust the environment file with the preferred number of validators as well as details on both chains. For the migration path, both the launch version as well as the upgrade version of the consumer chain need to be present. The configuration file for the Hermes Relayer also needs to be adjusted with chain relevant data.

Once the testing starts, a Hermes Relayer is configured on a validator node of the provider chain. 


In the case of addition, only the provider chain is launched at first and then a consumer addition proposal is passed on this chain. Once the spawn time of the consumer chain has passed, the consumer chain starts and the two chains are connected with each other via Hermes Relayer.

In the case of migration, both chains launch simultaneously. Before the consumer addition is proposed on the provider chain, a software upgrade proposal is being passed on the sovereign chain which updates the chain to a version that supports cross chain validation. Same as with addition, once the consumer addition proposal has passed, the two chains are being connected via Hermes Relayer.

Key Assignment

One important thing that a validator may choose to do when a consumer chain is being onboarded, is to assign a key different from the key they use on the provider chain. This may provide additional security.

The Interchain Testing Suite gives the option to test key assignment before the launch of a consumer chain as well as when the consumer chain is already running.

Using the validator consensus address on the provider chain, a new key is assigned to the same validator on the consumer chain. After the key has been assigned, it is checked if the key that has been assigned on the consumer chain reflects the key on the provider chain.

If Key Assignment is skipped in testing, all the private validator keys of the provider chain are simply copied to the respective validator nodes on the consumer chain.

CCV State (Migration)

After a consumer addition proposal has passed on the provider chain, a CCV (cross chain validation) state file is generated on the provider chain.

This state file is then copied to the validator nodes of the consumer chain where it is merged with the genesis file to create a CCV file that is used to start the upgraded consumer chain. 

IBC Connection

Once the consumer chain launches, new clients are created on the chains over which validator set changes will be sent.

The testing suite fetches the newly created client ids and then creates connections and channels between the two chains. 

Once the channels are active, the Hermes Relayer is launched and starts to relay validator set changes between the chains.


It is important to check if the validator set changes actually arrive on the counterparty chain. One of the methods to test this is to delegate funds to a validator on the provider chain.

The testing suite then checks if voting power appropriately changes on the provider chain as well as on the consumer chain.

Slashing Events

Another thing to keep in mind is that slashing events should be relayed between provider and consumer chain.

For this purpose, a private validator key is copied from one validator to another. Naturally, this will result in the validator being tombstoned on their respective chain. 

It is then checked if the voting power of the validator actually reaches 0 on their chain as well as on the counterparty chain.


https://github.com/cryptocrew-validators/ics-simulation-tests (addition)

https://github.com/cryptocrew-validators/ics-simulation-tests/tree/ics-consumer-migration (migration)

Paul Leonhard - CryptoCrew

Author: Paul Leonhard
Blockchain Developer
CryptoCrew Validators