Network Forks

Demos uses a small, explicit hard-fork system to schedule consensus-rule changes at specific block heights. The same mechanism gates wire-format changes, state migrations, and any other rule that cannot vary across replicas without breaking consensus. The first production fork is osDenomination, which activates the sub-DEM (OS) denomination. A second fork, gasFeeSeparation (DEM-665), splits the single lump-sum gas fee into network/rpc/additional components with per-component burn/treasury/rpc-operator distribution.

Design goals

The fork machinery is intentionally minimal:

Bit-identical to pre-fork code paths until activation. A node booting without any forks scheduled is byte-for-byte equivalent to a pre-fork node. There is no implicit behavior change from upgrading the binary alone.
Deterministic. Activation is a function of block height, not wall-clock time, so all replicas activate at the same logical point.
Forward-compatible by construction. New forks are additive — adding one to the registry does not change the meaning of existing ones.
Cheap to query. Activation status is held in shared state and answered without a database round-trip.

Fork registry

Known forks live in src/forks/forkConfig.ts as a typed registry:

export type ForkName = "osDenomination" | "gasFeeSeparation"

export interface BaseForkConfig {
    activationHeight: number | null
    description?: string
}

// Per-fork variants extend BaseForkConfig with their own payload.
export type OsDenominationConfig = BaseForkConfig
export interface GasFeeSeparationConfig extends BaseForkConfig {
    treasuryAddress: string
}
export type ForkConfig = OsDenominationConfig | GasFeeSeparationConfig

export const DEFAULT_FORK_CONFIG: ForkConfigByName = {
    // Fresh chains boot post-fork by default (activationHeight: 0).
    // Operators upgrading an existing pre-fork chain must instead pin a
    // future block height in data/genesis.json.
    osDenomination: {
        activationHeight: 0,
        description:
            "DEM→OS denomination change. amount field becomes OS string.",
    },
    // gasFeeSeparation stays inactive by default — it also needs a real
    // treasuryAddress (the placeholder zero address is rejected by the
    // loader when activationHeight !== null).
    gasFeeSeparation: {
        activationHeight: null,
        description:
            "Gas fee separation (DEM-665). Splits gas into network/rpc/additional components.",
        treasuryAddress: PLACEHOLDER_TREASURY_ADDRESS,
    },
}

Adding a fork is a single line in this registry. Removing or renaming one is intentionally hard — the type union is a literal so typos surface at compile time rather than being silently treated as “unknown fork → inactive”.

Field	Meaning
`activationHeight`	Block height at which the fork rules become active. `null` means never active (configured but unscheduled).
`description`	Human-readable rationale, surfaced for operators and diagnostics. Not consumed by consensus.

Activation height & genesis loading

Activation heights are loaded from data/genesis.json at node startup and hydrated into SharedState.forkConfig. A fresh genesis without a forks section inherits DEFAULT_FORK_CONFIG: osDenomination defaults to activationHeight: 0 (fresh chains boot post-fork), while gasFeeSeparation defaults to null (configured but unscheduled). Operators upgrading an existing pre-fork chain must pin osDenomination.activationHeight to a future block in genesis and roll the upgrade in lock-step with their peers. The loader lives in src/forks/loadForkConfig.ts. The runtime registry is a deep copy of DEFAULT_FORK_CONFIG (via cloneDefaultForkConfig()), so per-instance mutation (e.g. genesis loading) does not leak into the module-level constant.

Gate function

Every consensus-relevant code path that depends on a fork consults the gate function:

import { isForkActive } from "@/forks/forkGates"

if (isForkActive("osDenomination", blockHeight)) {
    // post-fork logic
} else {
    // pre-fork logic
}

A fork is active iff its activationHeight is non-null and the supplied blockHeight >= activationHeight. Defensive paths return false (inactive) when:

forkConfig is missing from SharedState (e.g. tests booting without full startup).
The fork name is unknown — compile-time typing should prevent this, but the runtime check protects against explicit casts.

Where the gate lives

The current production gate is wired into:

Transaction hashing — the wire serializer routes through serializerGate so the digest matches the on-wire shape, pre or post-fork.
Block hashing — same gate, applied at the block level so consensus signatures cover the right format.
Block insertion — chainBlocks.insertBlock checks fork state before applying any post-fork validation rule (e.g. fork-specific state migrations).

Any new fork that changes wire format or state must hook into these same gate points.

State migrations

Forks that change persisted state (e.g. osDenomination re-denominating balances) ship as idempotent migrations under src/forks/migrations/. Each migration is recorded in the fork_state table so it runs at most once per chain. The recorded entry carries forensic data (pre/post sums, lost-value tally, applied-at block) for audit. The osDenomination migration is the canonical example:

Atomic: all three data sources (GCRv2 main balance, legacy GCR JSONB balance, validator stakes) migrate in one transaction or none.
Sum-invariant: postSumOs == preSumDem * 10^9 - totalValueLostOs is verified before commit.
Cap policy: legacy JSONB balances that would exceed Number.MAX_SAFE_INTEGER * 0.9 after multiplication are capped, with the lost OS recorded for accounting.

RPC: `getNetworkInfo`

The node exposes fork status via the getNetworkInfo RPC (src/libs/network/handlers/forkHandlers.ts). SDK clients use it to choose the correct wire format without an extra round-trip. Request: no arguments. Response:

{
  "forks": {
    "osDenomination": {
      "activationHeight": 12345,
      "activated": false,
      "currentHeight": 9876
    }
  },
  "nodeVersion": {
    "version": "0.9.8",
    "gitSha": "…",
    "branch": "stabilisation",
    "dirty": false,
    "buildTime": "…"
  }
}

The forks object surfaces only osDenomination today; nodeVersion carries the responding node’s build provenance (package version, git SHA, branch, dirty flag, build timestamp) so a single call answers both “is the fork active?” and “which binary is this node running?”.

Field	Meaning
`activationHeight`	The configured activation height, or `null` if the fork is unscheduled.
`activated`	Whether the fork’s rules are currently active — computed via the canonical `isForkActive` gate so it matches the serializer and validator code paths exactly.
`currentHeight`	In-memory cache of the latest block height the node has processed (`SharedState.lastBlockNumber`). Lets clients do their own near-fork detection without a separate `getLastBlockNumber` call.

The response is wrapped in forks.<name> so that adding a future fork is a strictly additive change rather than a breaking one. The handler is intentionally cheap — it reads from in-memory shared state, not the database. Extra fields on the request payload are ignored, so forward-compatible client extensions don’t choke the RPC.

Fork lifecycle phases

The osDenomination rollout introduced a phased pattern that future forks can reuse:

Phase	Scope
P2	Add the fork to the registry with `activationHeight: null`. Wire gates into the serializer/validator paths. Bit-identical to pre-fork.
P3a	Implement post-fork wire serializer and gate it on `isForkActive`. Still inactive at runtime.
P3b	Implement state migration. Hooked into block insertion but does nothing while the fork is unscheduled.
P3c	Add the `getNetworkInfo` RPC so SDK clients can detect activation.
P4 (SDK)	Ship the post-fork SDK that consults `getNetworkInfo` and emits the new wire format.
Activation	Deploy a genesis update that sets `activationHeight` to a real block. From that height onward, the gate flips to `true` and the new rules apply.

This phased rollout ensures that the network can carry the new code on every node before it ever changes behavior — there is no “big bang” deployment.

Operator notes

Inspecting the active configuration — the loaded registry is held in SharedState.forkConfig. Operators can confirm activation by calling getNetworkInfo against the local RPC.
Replaying from genesis — because activation height is genesis-defined, replaying a chain from genesis with a different forks section will produce a different chain.
Adding a fork to a running network — requires a coordinated genesis update across validators. The fork is not active for any node until its activationHeight block is processed; until then the gate falls through to legacy paths regardless of binary version.

Amounts & Denominations (SDK) — how SDK clients consume getNetworkInfo and switch wire format.
Network Governance — for governable parameters that change without requiring a fork.
Validator Lifecycle — for state transitions that interact with denomination changes.

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

Network Forks

Network Forks

Design goals

Fork registry

Activation height & genesis loading

Gate function

Where the gate lives

State migrations

RPC: `getNetworkInfo`

Fork lifecycle phases

Operator notes

​Network Forks

​Design goals

​Fork registry

​Activation height & genesis loading

​Gate function

​Where the gate lives

​State migrations

​RPC: getNetworkInfo

​Fork lifecycle phases

​Operator notes

​Related documentation

Network Forks

Design goals

Fork registry

Activation height & genesis loading

Gate function

Where the gate lives

State migrations

RPC: `getNetworkInfo`

Fork lifecycle phases

Operator notes

Related documentation