Ouroboros Genesis Support

Dugite includes a Genesis State Machine (GSM) that tracks the node's sync progression through the Ouroboros Genesis protocol states.

Overview

The GSM implements three states matching the Ouroboros Genesis specification:

  • PreSyncing — Waiting for enough trusted big ledger peers (BLPs). The Historical Availability Assumption (HAA) requires a minimum number of active BLPs before sync begins.
  • Syncing — Active block download with density-based peer evaluation. The GSM monitors chain density across peers and can disconnect peers with insufficient chain density (GDD).
  • CaughtUp — Normal Praos operation. The node is at or near the chain tip and participates in standard consensus.

Enabling Genesis Mode

Genesis mode is opt-in via the --consensus-mode genesis CLI flag:

dugite-node run \
  --consensus-mode genesis \
  --config config/preview-config.json \
  ...

When not enabled (the default praos mode), the GSM immediately enters CaughtUp and all Genesis constraints are disabled. This is the recommended mode for nodes that sync from Mithril snapshots.

State Transitions

stateDiagram-v2
    [*] --> PreSyncing: genesis enabled, no marker
    [*] --> CaughtUp: marker file exists
    PreSyncing --> Syncing: HAA satisfied (enough BLPs)
    Syncing --> CaughtUp: all peers idle + tip fresh
    CaughtUp --> PreSyncing: tip becomes stale

A caught_up.marker file is written to the database directory when the node reaches CaughtUp, enabling fast restart without re-evaluating the Genesis bootstrap.

Features

  • State tracking: PreSyncing/Syncing/CaughtUp with automatic transitions
  • Big Ledger Peer identification: Pools in the top 90% of active stake are classified as BLPs
  • Genesis Density Disconnector (GDD): Compares chain density across peers within the genesis window and disconnects peers with insufficient density
  • Limit on Eagerness (LoE): Computes the maximum immutable tip slot based on candidate chain tips
  • Peer snapshot loading: JSON-based peer snapshot for initial peer discovery

The recommended deployment path uses Mithril snapshot import for fast sync with the default praos consensus mode:

# Import a Mithril snapshot first
dugite-node mithril-import --network-magic 2 --database-path ./db

# Then run in default praos mode
dugite-node run --config config/preview-config.json --database-path ./db ...