How to Customize Genesis Files for Blockchain Networks in Starship

You can customize genesis files in Starship by merging Helm values into chains[].genesis, overriding the default create-genesis.sh script with custom logic, or referencing remote genesis URLs via the Starship registry.

Starship provides a Kubernetes-native environment for spinning up local blockchain testnets, and controlling the initial chain state requires modifying the genesis file. This guide explains three distinct methods to customize genesis configurations in the hyperweb-io/starship repository, ranging from simple parameter overrides to complete file replacement.

Using Helm Values (chains[].genesis)

The simplest method injects custom JSON into the genesis file through your Helm configuration. In starship/cmd/starship/model.go, the Chain struct defines a Genesis field of type map[string]interface{} that captures arbitrary key-value pairs from your values file.

When Starship initializes a chain, the default create-genesis.sh script runs first, then the system merges your custom genesis map into the resulting genesis.json. This approach works best for tweaking specific module parameters like staking unbonding times or governance deposit periods.

Add your overrides under the chains array in your values.yaml:

chains:
  - id: mychain
    image: ghcr.io/myorg/mychain-node:v1.0.0
    num_validators: 2
    genesis:
      staking:
        params:
          unbonding_time: "15s"
      gov:
        deposit_params:
          max_deposit_period: "30s"

The merge operation preserves the default validator setup and gentx transactions while applying your specific parameter changes.

Creating Custom Genesis Scripts

For deeper customization—such as adding custom module genesis states, replacing validator keys, or modifying IBC parameters—you can override the default initialization script. The documentation in docs/development/add-new-chain.md (lines 91-96) describes how to plug custom scripts into the Helm deployment.

Place your script at starship/charts/scripts/<your-chain>/create-genesis.sh and reference it in your configuration:

scripts:
  createGenesis:
    file: scripts/mychain/create-genesis.sh

Your custom script executes before the node starts, giving you full control over the genesis file using tools like jq. The default script at starship/charts/devnet/scripts/default/create-genesis.sh provides templates for common operations:

#!/usr/bin/env bash
set -eux

DENOM="${DENOM:=umy}"
CHAIN_DIR="${CHAIN_DIR:=$HOME/.mychaind}"

# Initialize chain with recovered key

jq -r ".genesis[0].mnemonic" "$KEYS_CONFIG" | $CHAIN_BIN init "$CHAIN_ID" --chain-id "$CHAIN_ID" --recover

# Set custom bond denom

jq -r ".app_state.staking.params.bond_denom |= \"$DENOM\"" "$CHAIN_DIR/config/genesis.json" > /tmp/genesis && mv /tmp/genesis "$CHAIN_DIR/config/genesis.json"

# Adjust unbonding time

jq -r ".app_state.staking.params.unbonding_time |= \"20s\"" "$CHAIN_DIR/config/genesis.json" > /tmp/genesis && mv /tmp/genesis "$CHAIN_DIR/config/genesis.json"

This method bypasses the automatic merging of Helm values, giving you complete control over the JSON structure.

Loading Genesis from Remote URLs

When integrating with existing mainnets or standardized testnets, you can instruct Starship to download a pre-built genesis file from a remote URL. The registry system, defined in starship/proto/registry/chain.proto (lines 38-40), supports a genesis_url field that points to externally hosted genesis files.

Add the URL to your chain definition in the registry JSON:

{
  "chain_id": "osmosis-1",
  "genesis": {
    "genesis_url": "https://github.com/osmosis-labs/networks/raw/main/osmosis-1/genesis.json.gz"
  }
}

Starship automatically downloads the file, decompresses it if necessary (supporting both .json and .json.gz formats), and mounts it into the pod before the chain binary starts. This approach requires no local script modifications and ensures your local testnet mirrors the exact genesis state of the target chain.

Summary

• Helm values (chains[].genesis) provide the simplest path for parameter overrides, merging your JSON into the default genesis after initialization completes.
• Custom scripts override the default create-genesis.sh logic, enabling complex modifications using jq or other tools to manipulate the raw genesis JSON.
• Remote URLs via the Starship registry allow you to import existing genesis files from external sources, supporting compressed archives and eliminating the need for local generation scripts.

Frequently Asked Questions

How does the Helm values method merge with existing genesis content?

The Helm values approach performs a deep merge after the default create-genesis.sh script finishes executing. According to the Chain struct implementation in starship/cmd/starship/model.go, the genesis map is applied as a final overlay, preserving the validator set and gentx transactions generated by the default script while updating your specified module parameters.

Can I combine custom scripts with Helm genesis values?

No, using a custom script at scripts.createGenesis.file replaces the default initialization logic entirely, including the automatic merge of Helm genesis values. If you use a custom script, you must implement all desired genesis modifications within that script using tools like jq, or explicitly call the default script first and then apply additional changes.

What file formats does the remote genesis URL support?

The registry system supports both plain JSON and gzip-compressed JSON files. When you specify a genesis_url in starship/proto/registry/chain.proto, Starship detects the compression based on the file extension or content encoding and automatically decompresses .gz archives before mounting the genesis file into the chain container.

Where is the default genesis creation logic located?

The default script that initializes validators, creates accounts, and generates gentx transactions resides at starship/charts/devnet/scripts/default/create-genesis.sh. This script serves as the foundation for chain initialization and contains examples of jq commands for modifying staking, slashing, and governance parameters that you can reference when building custom scripts.

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