Starship
Configuration
Chains Directive Syntax

Chains YAML Syntax

Here we will go into details of the chains top level directive in the Starship config file.

id

ID of the chain, this is used as the chain-id of the chain

chains:
- id: osmosis-1
  ...
- id: gaia-2
  ...
- id: juno-1
  ...

name

Type of chain is a short hand to use the default key values for a chain found here (opens in a new tab)

chains:
- id: osmosis-1
  name: osmosis
  ...
- id: gaia-2
  name: cosmoshub
  ...

One can override the default values supported by defaultChain by simply mentioning it in the chain directive. Here is how one can set the docker image of the default values

chains:
- id: osmosis-1
  name: osmosis
  image: ghcr.io/cosmology-tech/starship/osmosis:v25.0.0
  coins: 100000000000000uosmo
  ...

name: custom

Optionally one can define the type to custom, and pass all the default params directly into the chain directive. This is useful when one is trying setup a chain not supported in the defaultChains.

chains:
- id: osmosis-1
  name: custom
  image: ghcr.io/cosmology-tech/starship/osmosis:v25.0.0
  home: /root/.osmosisd
  binary: osmosisd
  prefix: osmo
  denom: uosmo
  coins: 100000000000000uosmo,100000000000000uion
  hdPath: m/44'/118'/0'/0/0
  coinType: 118
  repo: https://github.com/osmosis-labs/osmosis
  ...

image (optional)

Already mentioned above, but here we will go deeper into how the docker images are used for the chain. By default this value is taken from the name directive. This is the standard way of running chains at specific versions.

chains:
- id: osmosis-1
  name: osmosis
  image: "<docker-image>"
  ...

One can use any docker image as long as it follows the following rules:

  • Packages curl,make,bash,jq,sed
  • Chain binaries installed in $PATH

We create docker images with this Dockerfile (opens in a new tab), using Heighliner base images. All supported docker images can be found here (opens in a new tab)

numValidators

Number of validators to run for the chain. It must be greater than 1, can go up to as many resources available.

chains:
- id: osmosis-1
  name: osmosis
  numValidators: 2

Note: The first node spun up is a genesis node, which spins up before all other validators. Once the genesis node starts then all other validator nodes are spun up simultaneously

If number of validators is more than the mnemonics available in the keys.json (opens in a new tab) file which is 5, then other validators are created with random mnemonic on initialization.

ports

Ports directive in the chains directive is used for kubectl port-forward forwarding kubernetes service ports to local host.

chains:
- id: osmosis-1
  name: osmosis
  numValidators: 2
  ports:
    rest: 1317     # Rest endpoint of the Genesis validator node (most used)
    rpc: 26657     # RPC endpoint of the genesis validator node (most used)
    grpc: 9091     # GRPC endpoint of the genesis validator node (less used)
    faucet: 8001   # Faucet running next to the genesis node (most used)
    exposer: 9090  # Exposer sidecar port (less used)

Available endpoints for extra services:

Note: Make sure the ports are not overlapping in the config file

resources (optional)

Resource directive is something with which you can control how much resources to provide to each of the chain node.

chains:
- id: osmosis-1
  name: osmosis
  numValidators: 1
  resources:
    cpu: 1       # 1 CPU
    memory: 1Gi  # 1 GB

Main benefit of this directive is to closely control the resources provided for each of the validator node. One can provide fractional cpus and memory as per the resource constraints of the system

Usually when running in the CI or locally you can provide partial resources like following:

chains:
- id: osmosis-1
  name: osmosis
  numValidators: 1
  resources:
    cpu: "0.2"      # 0.2 CPU
    memory: "400M"  # 0.4 GB

For more details on the resource directive have a look at kubernetes resources (opens in a new tab)

Note: If one provides less resources, the devnet will be stable for shorter timeframe. Nodes will start dying or restarting We recommend to specify resources as per your requirements

faucet (optional)

Every genesis node runs a faucet. We support 2 types of faucet:

Setting for cosmjs-faucet here (opens in a new tab) but can be overridden with this directive, specially for compatible cosmjs version with the chain version.

chains:
- id: osmosis-1
  name: osmosis
  numValidators: 1
  faucet:
    enabled: true           # optional, default is true, need to specify if want to disable faucet, set to false
    type: cosmjs            # default is cosmjs, allowed [cosmjs, starship]
    image: ghcr.io/cosmology-tech/starship/cosmjs-faucet:v0.30.1  # optional, default image set if not specified
    concurrency: 2          # optional, default is 5
    resources:
      cpu: "0.3"
      memory: "600M"

By default, we enable cosmjs faucet. Incase faucet.enabled is set to false, then we manually add validator and relayer keys at gentx on genesis. This will take longer during initialization.

Note concurrency in faucet is the number of concurrent requests the faucet can handle. If you are running a chain with less resources, or want faster startup time, then you can reduce the concurrency to a lower number.

Note: use faucet.type: starship for chains not supported by cosmjs. Mainly injective, evmos, cheqd etc.

build (optional)

With the build directive in the chain, one can basically build chain binaries on the fly before starting the chain. When the directive is enabled, then the docker image is set to a runner docker image (opens in a new tab) which is a basic alpine image with starship dependencies.

chains:
- id: osmosis-1
  name: osmosis
  numValidators: 2
  build:
    enabled: true
    source: v15.0.0  # can be a tag or a commit or a branch

We fetch the source from the repo defined in the defaultChains.

If you are using the name: custom, then you need to specify repo directive, from where to get the source.

upgrade (optional)

If you want to perform a software upgrade on a chain, then this directive is here help. This will not perform the chain upgrade, but prepare the chain nodes to be able to do an actual software upgrade.

chains:
- id: osmosis-1
  name: osmosis
  numValidators: 2
  upgrade:
    enabled: true             # enable the directive
    type: build               # type build specifies, this will be similar to the `build` directive
    genesis: v13.0.0          # current chain version, tag, branch or commit
    upgrades:
      - name: v14             # upgrade proposal name
        version: v14.0.0      # upgrade chain version, tag, branch or commit
      - name: v15
        version: v15.0.0-rc1  # next chain upgrade version

We use cosmovisor (opens in a new tab) to run the validators when this directive is enabled, which allows for external software-upgrade-proposal.

genesis (optional)

Patch genesis.json file directly from the config file using this directive. Once the genesis node creates the genesis file, then the patch for genesis is applied.

chains:
- id: osmosis-1
  name: osmosis
  numValidators: 2
  genesis:
    app_state:
      staking:
        params:
          unbonding_time: "5s"

scripts (optional)

Scripts directive will replace the default scripts with the given scripts. In order to use this directive, one must use scripts/install.sh (opens in a new tab) script for running the helm chart.

Since the local scripts are converted into configmaps that are then created in the kubernetes cluster, there is a limit of 1MBi

Types of scripts that are allowed inside the scripts dir are:

One can choose the sub-scripts that need to be overwritten, default scripts will be used instead.

chains:
  - id: osmosis-1
    name: osmosis
    numValidators: 1
    scripts:
      createGenesis:
        file: scripts/create-custom-genesis.sh
      updateGenesis:
        file: scripts/update-custom-genesis.sh
      updateConfig:
        file: scripts/update-custom-config.sh
      createValidator:
        file: scripts/create-custom-validator.sh
      transferTokens:
        file: scripts/transfer-custom-tokens.sh

Note file path is relative to the config file itself

Dir structure should look something like:

config.yaml
scripts/
  create-custom-genesis.sh
  update-custom-genesis.sh
  update-custom-config.sh
  create-custom-validator.sh
  transfer-custom-tokens.sh

cometmock (optional)

A dedicated feature flag, that will run the chain with InformalSystem's CometMock (opens in a new tab) binary. With cometmock enabled we will run all validators of the chain with out of process cometbft, that connect with the cometmock pod.

Enabling cometmock is really simple with following

chains:
- id: cosmoshub-4
  name: cosmoshub
  numValidators: 4
  cometmock:
    enabled: true
    image: ghcr.io/informalsystems/cometmock:v0.37.x  ## optional, default is 0.37.x

By default we use the cometbft v0.37.x version, but this can be set to other versions from cometmock releases (opens in a new tab). Noteable other versions are: v0.34.x as well as v0.38.x.

If cometmock is enabled, during port-forwarding, we forward the ports.rpc to the cometmock endpoint. For in-cluster communication, make sure to connect to the cometmock service instead of validator service for rpc connections.

env (optional)

The env directive allows you to set custom environment variables for the validator and genesis containers. This can be useful for enabling features like debug logging or configuring specific settings.

The env directive expects an array of objects, each containing a name and value field. Here's an example of how to use the env directive:

chains:
- id: agoriclocal
  name: agoric
  numValidators: 1
  env:
    - name: DEBUG
      value: SwingSet:vat,SwingSet:ls

Learn more

To more about CometMock, have a look at the blog (opens in a new tab) that explains its working

Note: Current support of cometmock has been tested with multiple chains with verion 0.34.x and 0.37.x.

ics (optional)

The ics directive allows you to enable interchain security on the chain. This is useful when you want to test a chain which is ICS enabled

chains:
- id: neutron-1
  name: neutron
  numValidators: 1
  ics:
    enabled: true
    provider: cosmoshub-4  # chain id of the provider chain
- id: cosmoshub-4
  name: cosmoshub
  numValidators: 1

Note: To complete the ICS setup one also needs to setup the relayer with ics enabled. Have a look at the relayer (opens in a new tab)

balances (optional)

The balances directive allows you to set the initial balances for the chain addresses. This is useful when you want to test a chain with specific initial balances.

chains:
- id: osmosis-1
  name: osmosis
  numValidators: 1
  balances:
    - address: cosmos1xv9tklw7d82sezh9haa573wufgy59vmwe6xxe5
      coins: 100000000000000uosmo
    - address: cosmos1xv9tklw7d82sezh9haa573wufgy59vmwe6xxe5
      coins: 100000000000000uion

readinessProbe (optional)

The readinessProbe directive allows you to set the readiness probe for the chain pods. This is useful when you want to test a chain with specific readiness probe settings. Note, this is the same as the kubernetes readiness probe (opens in a new tab)

chains:
- id: osmosis-1
  name: osmosis
  numValidators: 1
  readinessProbe:
    exec:
      command:
      - bash
      - -c
      - |
        $CHAIN_BIN status 2>&1 | jq -e '.SyncInfo.catching_up == false'
    initialDelaySeconds: 60
    periodSeconds: 20
IntroductionRelayers Directive Syntax