How Starship Implements Interchain Security (ICS) Support in Cosmos Deployments

Starship treats Interchain Security (ICS) as a first-class feature that automates provider chain provisioning, consumer-addition governance proposals, and IBC channel wiring through a single ics.enabled configuration flag.

Interchain Security (ICS) allows Cosmos chains to lease economic security from a provider chain like the Cosmos Hub. In the hyperweb-io/starship repository, ICS support is implemented as a declarative configuration option that handles the complex multi-step registration process automatically. When enabled, Starship deploys the provider infrastructure, submits governance proposals, generates compatible genesis files, and establishes IBC channels without manual intervention.

Configuration: Enabling ICS for Consumer Chains

To activate Interchain Security support, add the ics block to any consumer chain definition in your Starship values file. The configuration requires two components: the consumer flag and the provider chain definition.

chains:
  cosmoshub:
    ics:
      enabled: true          # Activates ICS for this consumer

      provider: ics          # References the provider chain name

    # ... other chain settings

  
  ics:                       # Provider chain definition (required)

    image: ghcr.io/cosmology-tech/starship/ics:v0.1.0
    home: /root/.ics
    binary: interchain-security-pd
    denom: uatom
    prettyName: ICS

Starship validates this configuration against the chart defaults defined in starship/charts/devnet/defaults.yaml【/cache/repos/github.com/hyperweb-io/starship/main/starship/charts/devnet/defaults.yaml#L212-L219】. The generator component (TypeScript CLI) reads this ics block from packages/packages/generator/configs/defaults.yaml【/cache/repos/github.com/hyperweb-io/starship/main/packages/packages/generator/configs/defaults.yaml#L1001-L1002】 and emits the appropriate Helm values and Kubernetes objects.

The ICS Initialization Pipeline

When ics.enabled is set to true, Starship executes a five-stage pipeline that runs automatically during deployment.

Provider Chain Provisioning

Starship first ensures the provider chain (the "ICS hub") is available. The system pulls the provider's Docker image, home directory, binary, and denomination from the defaults configuration. This provider definition must be referenced in the consumer's ics.provider field.

Consumer-Addition Proposal Execution

The platform injects an init-container named init-ics into the consumer's genesis pod. This container runs scripts/default/create-ics.sh【/cache/repos/github.com/hyperweb-io/starship/main/starship/charts/devnet/scripts/default/create-ics.sh#L1-L43】 to handle on-chain registration.

The script performs the following actions:

1. Recovers a test key from the keys configuration
2. Stakes tokens to the provider's validator
3. Submits a consumer-addition governance proposal using the provider's binary
4. Votes "yes" on the proposal and waits for it to pass

This automation eliminates the need for manual governance transactions when setting up a consumer chain.

Genesis File Generation

After the proposal succeeds, Starship generates the consumer genesis file. The logic resides in the cosmos genesis template at starship/charts/devnet/templates/chains/cosmos/genesis.yaml【/cache/repos/github.com/hyperweb-io/starship/main/starship/charts/devnet/templates/chains/cosmos/genesis.yaml#L187-L223】.

The init-ics container executes the following workflow:

- name: init-ics
  image: {{ $icsChain.image }}
  env:
    - name: DENOM
      value: "{{ $icsChain.denom }}"
    - name: CHAIN_ID
      value: "{{ $icsChain.id }}"
    - name: CHAIN_BIN
      value: "{{ $icsChain.binary }}"
    - name: NODE_URL
      value: http://{{ $icsChain.hostname }}-genesis.$NAMESPACE.svc.cluster.local:26657
  command: ["/bin/bash", "-c"]
  args:
    - |
      bash -e /scripts/create-ics.sh

The script pulls the provider's private validator key and uses the provider consumer-genesis command to build a compatible genesis file for the consumer chain.

Script Injection via ConfigMap

Starship creates a ConfigMap that includes the create-ics.sh script so it is available inside the consumer pod. This is defined in starship/charts/devnet/templates/chains/cosmos/configmap.yaml【/cache/repos/github.com/hyperweb-io/starship/main/starship/charts/devnet/templates/chains/cosmos/configmap.yaml#L90-L92】.

The script handles key recovery and proposal submission:

#!/bin/bash
set -euxo pipefail

# Recover test key

jq -r ".keys[0].mnemonic" $KEYS_CONFIG | $CHAIN_BIN keys add ics-setup --recover --keyring-backend="test"

# Stake tokens

$CHAIN_BIN tx staking delegate $VALIDATOR_ADDRESS 10000000$DENOM \
  --from ics-setup --keyring-backend="test" --gas auto --gas-adjustment 2 --yes

# Submit consumer-addition proposal

$CHAIN_BIN tx gov $SUBMIT_PROPOSAL_CMD consumer-addition $PROPOSAL_FILE \
  --from ics-setup --yes

# Vote and wait

$CHAIN_BIN tx gov vote $PROPOSAL_ID yes --from ics-setup --yes

IBC Channel Automation

When relayers are enabled, Starship automatically establishes IBC channels between the provider and consumer. The Helm helpers in starship/charts/devnet/templates/_relayers.tpl【/cache/repos/github.com/hyperweb-io/starship/main/starship/charts/devnet/templates/_relayers.tpl#L24-L31】 add a default ics20 channel if ics.enabled is true.

For Hermes relayers, the template injects connection creation logic:

{{- if $relayer.ics.enabled }}
  echo "Creating IBC connection for {{ $relayer.ics.consumer }}..."
  hermes create connection --a-chain {{ $relayer.ics.consumer }} --a-client 07-tendermint-0 --b-client 07-tendermint-0
{{- end }}

Key Implementation Files

The Interchain Security support in Starship is implemented across several critical files:

• starship/charts/devnet/defaults.yaml (lines 212-219): Defines default ICS provider images, binaries, and denominations
• starship/charts/devnet/scripts/default/create-ics.sh: Bash script that executes the consumer-addition proposal workflow on the provider chain
• starship/charts/devnet/templates/chains/cosmos/genesis.yaml (lines 187-223): Helm template that injects the init-ics container into consumer genesis pods
• starship/charts/devnet/templates/chains/cosmos/configmap.yaml (lines 90-92): Packages the create-ics.sh script into the consumer pod
• starship/charts/devnet/templates/_relayers.tpl (lines 24-31): Helper template that configures automatic ics20 IBC channels for relayers
• packages/packages/generator/configs/defaults.yaml (lines 1001-1002): Generator defaults used by the TypeScript CLI to produce Helm values

Summary

Starship abstracts the complex Interchain Security setup into a declarative configuration workflow:

• Declarative activation: Set ics.enabled: true to enable consumer chain registration
• Automated provisioning: The platform deploys provider chains and handles governance proposals automatically
• Genesis compatibility: Starship generates proper consumer genesis files by interfacing with the provider's validator set
• IBC integration: Relayers automatically establish ics20 channels between provider and consumer when ICS is enabled
• Script-driven workflow: The create-ics.sh script handles key recovery, staking, proposal submission, and voting

Frequently Asked Questions

What is the minimum configuration required to enable ICS in Starship?

You must add an ics block to your consumer chain with enabled: true and a provider field referencing a defined provider chain. The provider chain must also be declared in the same configuration file with its image, binary, and denomination settings. Starship handles all remaining setup through the init-ics container and create-ics.sh script.

How does Starship handle the consumer-addition proposal process?

Starship injects an init-container that runs create-ics.sh inside the consumer's genesis pod. This script recovers a test key, stakes tokens on the provider chain, submits a consumer-addition governance proposal, votes "yes," and waits for the proposal to pass. This eliminates manual governance interactions during deployment.

Which IBC channels are automatically created for ICS chains?

When relayers are enabled and ics.enabled is true, Starship automatically configures an ics20 IBC channel between the provider and consumer chains. The Helm helpers in _relayers.tpl add this default channel configuration, and Hermes relayer templates create the necessary connections using the 07-tendermint-0 client identifiers.

Can I use custom provider chains other than the default ICS configuration?

Yes. While Starship provides defaults in starship/charts/devnet/defaults.yaml, you can define custom provider chains by specifying your own image, home directory, binary name, and denomination in the provider chain definition. The ics.provider field in the consumer configuration simply references the name of whichever chain serves as the security provider.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}