Joining the testnet using a custom genesis

A fresh Demos node ships with a default data/genesis.json that boots an isolated single-validator chain. To join an existing network — testnet or a privately restored chain — you need:

The same genesis file every other peer is using. The genesis hash is checked at startup, and a mismatch is unrecoverable: consensus can never form, and the node will exit.
At least one bootstrap peer to discover the rest of the network from.

Both Track 1 (Docker Compose) and Track 2 (bare metal ./run) consume the same data/genesis.json file — they only differ in where the file needs to live for the node process to read it.

Do not invent bootstrap hostnames or genesis URLs. Get the canonical data/genesis.json and a bootstrap peerlist from the Demos team or from a known healthy peer. Pointing at the wrong genesis simply means the node refuses to sync.

What’s in `genesis.json`

data/genesis.json defines:

The chain’s bootstrap accounts (GCR balances at height 0).
The initial validator set.
The forks section — activation heights for hard forks (e.g. osDenomination). These are loaded into SharedState.forkConfig at node startup and gate consensus-relevant code paths.

For the fork system in detail see Network Forks. The short version: every node on a network must agree on the forks section, because a different activation height produces a different chain. A genesis snippet with a scheduled fork looks like:

{
  "balances": [ "..." ],
  "validators": [ "..." ],
  "forks": {
    "osDenomination": {
      "activationHeight": 12345
    }
  }
}

A genesis with no forks section, or with activationHeight: null, leaves every fork unscheduled — the node behaves bit-identically to a pre-fork node.

Full genesis schema

data/genesis.json has the following top-level structure:

{
  "properties": {
    "id": 1,              // numeric chain id
    "name": "DEMOS",      // human-readable chain name
    "currency": "DEM"     // native currency ticker
  },
  "mutables": {
    "minBlocksForValidationOnlineStatus": 4
  },
  "forks": {
    "osDenomination":   { "activationHeight": 0 },
    "gasFeeSeparation": { "activationHeight": null, "treasuryAddress": "0x..." }
  },
  "balances": [
    ["0xPUBKEY", "1000000000000000000"]   // [pubkey, balance] tuples (OS denomination)
  ],
  "timestamp": "1692734616",   // genesis block timestamp (unix seconds, string)
  "status": "confirmed",
  "validators": [
    {
      "address": "0x...",                  // validator pubkey
      "status": "2",                       // validator state (see Validator Lifecycle)
      "connection_url": "https://node2.demos.sh",  // or null
      "staked_amount": "1000000000000000000",      // raw bigint string
      "first_seen": 0,
      "valid_at": 0
    }
  ]
}

Field	Description
`properties`	Chain identity: `id`, `name`, `currency`.
`mutables`	Tunable genesis values such as `minBlocksForValidationOnlineStatus`.
`forks`	Per-fork activation heights (see Network Forks). Every peer must agree on this section.
`balances`	Bootstrap account balances as `[pubkey, balance]` tuples. The balance side may be a decimal string, integer, or bigint-string and is coerced to a `bigint` in OS denomination; malformed or negative values cause the node to fail loudly at load.
`timestamp`	Genesis block timestamp (unix seconds, as a string).
`status`	Genesis block status (e.g. `confirmed`).
`validators`	Initial validator set. Each entry: `address`, `status`, `connection_url` (or `null`), `staked_amount` (raw bigint string), `first_seen`, `valid_at`. Validator state codes are documented in Validator Lifecycle.

The balances array is applied on top of any restored snapshot rows (see mergeGenesisBalances), so a fresh single-validator chain typically ships with an empty balances: []. Account rows themselves follow the gcr_main structure.

Get the genesis from a healthy peer

Every running node exposes its current genesis at /genesis. To pull one from a known peer:

curl -o data/genesis.json https://NODE_URL/genesis

Replace NODE_URL with the public URL of a peer the team has told you to bootstrap from. Verify the file is valid JSON before continuing:

jq . data/genesis.json > /dev/null && echo "OK"

You will also want that peer’s public key (from /info) so you can put it in your peerlist:

curl https://NODE_URL/info

Track 1: Docker Compose (recommended)

Track 1 stores chain runtime data in the named volume demos_node_data. The bundled data/ directory (including the default genesis.json) is baked into the node image at build time — to override it, you can either:

(A) Edit data/genesis.json in the repo and rebuild the image, or
(B) Mount your custom genesis over the in-container path via a compose override.

Option A: edit and rebuild

# 1. Replace the genesis file in the repo
curl -o data/genesis.json https://NODE_URL/genesis

# 2. Stop and DELETE existing volumes — a custom genesis means a new chain,
#    so the existing demos_pgdata is incompatible and must be wiped.
docker compose down -v

# 3. Rebuild the node image with the new genesis baked in, and start fresh
docker compose up -d --build

The down -v step is required: starting against the old demos_pgdata with a different genesis hash will refuse to sync. Your .demos_identity lives in demos_node_state and will also be deleted by down -v — back it up first if you need to keep it (see Backing up and restoring a node).

Option B: bind-mount the genesis

Create docker-compose.override.yml next to docker-compose.yml:

services:
  node:
    volumes:
      - ./data/genesis.json:/app/data/genesis.json:ro

Then:

docker compose down -v          # destroys old chain data; back up identity first
docker compose up -d

The bind mount is read-only and authoritative — the node reads it at startup just like the baked-in copy.

Seed the bootstrap peerlist

A fresh node has an empty demos_peerlist.json and cannot discover peers on its own. Seed the volume before first start:

cat > /tmp/demos_peerlist.json <<EOF
{
  "0xPEERPUBLICKEY": "https://NODE_URL"
}
EOF

docker run --rm \
  -v demos_node_state:/state \
  -v /tmp/demos_peerlist.json:/seed/demos_peerlist.json:ro \
  alpine sh -c 'cp /seed/demos_peerlist.json /state/ && chown 1000:1000 /state/demos_peerlist.json'

docker compose up -d

Replace 0xPEERPUBLICKEY and NODE_URL with the values from the peer’s /info and the URL the team gave you.

Track 2: Bare metal `./run` (advanced)

Track 2 reads data/genesis.json directly from the repo path — no volumes involved.

# 1. From the repo root, replace the genesis
curl -o data/genesis.json https://NODE_URL/genesis

# 2. Edit demos_peerlist.json to add at least one known peer
#    Format: { "<publicKey>": "<url>" }
$EDITOR demos_peerlist.json

Example demos_peerlist.json:

{
  "0xd0b2be2cb6d...": "https://NODE_URL"
}

Then start the node with -c true to wipe the local Postgres (the new genesis is incompatible with the old chain data):

./run -c true

Genesis hash check

On startup the node computes the hash of its loaded data/genesis.json and, before syncing the first block from a peer, compares it against the peer’s reported genesis hash. If they differ:

Genesis hash mismatch: local=0x... remote=0x...

The node terminates. Causes are almost always:

The peer is on a different network (e.g. you pointed at mainnet with a testnet genesis).
You edited data/genesis.json after first boot without also wiping chain data (docker compose down -v on Track 1, ./run -c true on Track 2).
The peer has rotated genesis (re-deploy after a custom-genesis restore) and you have not pulled the new one.

Re-pull the genesis from the peer and start over.

Genesis hash is height-0 only. Once both sides agree there, ongoing consensus is governed by the activated forks (see Network Forks) and the live validator set.

Internal Mechanisms

Validator Lifecycle

Network Governance

Global Change Registry

Consensus Mechanism

Network Forks

L2PS Privacy Subnets

ZK Identity

Architecture

Communications Stack

API Reference

Operations

Incentives

MCP Server

Bridges

Developers Testbed

Miscellaneous

Joining The Testnet Using A Custom Genesis

Joining the testnet using a custom genesis

What’s in `genesis.json`

Full genesis schema

Get the genesis from a healthy peer

Track 1: Docker Compose (recommended)

Option A: edit and rebuild

Option B: bind-mount the genesis

Seed the bootstrap peerlist

Track 2: Bare metal `./run` (advanced)

Genesis hash check

​Joining the testnet using a custom genesis

​What’s in genesis.json

​Full genesis schema

​Get the genesis from a healthy peer

​Track 1: Docker Compose (recommended)

​Option A: edit and rebuild

​Option B: bind-mount the genesis

​Seed the bootstrap peerlist

​Track 2: Bare metal ./run (advanced)

​Genesis hash check

Joining the testnet using a custom genesis

What’s in `genesis.json`

Full genesis schema

Get the genesis from a healthy peer

Track 1: Docker Compose (recommended)

Option A: edit and rebuild

Option B: bind-mount the genesis

Seed the bootstrap peerlist

Track 2: Bare metal `./run` (advanced)

Genesis hash check