# How to Customize Genesis Files for Blockchain Networks in Starship

> Customize Starship genesis files by merging Helm values overriding create genesis sh script or referencing remote genesis URLs Learn how to tailor your blockchain network with Starship.

- Repository: [Hyperweb/starship](https://github.com/hyperweb-io/starship)
- Tags: how-to-guide
- Published: 2026-03-03

---

**You can customize genesis files in Starship by merging Helm values into `chains[].genesis`, overriding the default [`create-genesis.sh`](https://github.com/hyperweb-io/starship/blob/main/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`](https://github.com/hyperweb-io/starship/blob/main/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`](https://github.com/hyperweb-io/starship/blob/main/create-genesis.sh) script runs first, then the system merges your custom `genesis` map into the resulting [`genesis.json`](https://github.com/hyperweb-io/starship/blob/main/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`](https://github.com/hyperweb-io/starship/blob/main/values.yaml):

```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`](https://github.com/hyperweb-io/starship/blob/main/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:

```yaml
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`](https://github.com/hyperweb-io/starship/blob/main/starship/charts/devnet/scripts/default/create-genesis.sh) provides templates for common operations:

```bash
#!/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:

```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`](https://github.com/hyperweb-io/starship/blob/main/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`](https://github.com/hyperweb-io/starship/blob/main/create-genesis.sh) script finishes executing. According to the `Chain` struct implementation in [`starship/cmd/starship/model.go`](https://github.com/hyperweb-io/starship/blob/main/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`](https://github.com/hyperweb-io/starship/blob/main/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.