Introduction

Dugite is a Cardano node implementation written in Rust, aiming for 100% compatibility with cardano-node (Haskell).

Built by Sandstone Pool.

Why Dugite?

The Cardano ecosystem benefits from client diversity. Running multiple independent node implementations strengthens the network by:

• Resilience — A bug in one implementation does not bring down the entire network.
• Performance — Rust's zero-cost abstractions and memory safety without garbage collection enable high-throughput block processing.
• Verification — An independent implementation validates the Cardano specification against the reference Haskell node, catching ambiguities and edge cases.
• Accessibility — A Rust codebase broadens the pool of developers who can contribute to Cardano infrastructure.

Key Features

• Full Ouroboros Praos consensus — Slot leader checks, VRF validation, KES period tracking, epoch nonce computation.
• Multi-era support — Byron, Shelley, Allegra, Mary, Alonzo, Babbage, and Conway eras.
• Conway governance (CIP-1694) — DRep registration, voting, proposals, constitutional committee, treasury withdrawals.
• Pipelined multi-peer sync — Header collection from a primary peer with parallel block fetching from multiple peers.
• Plutus script execution — Plutus V1/V2/V3 evaluation via the in-house dugite-uplc CEK machine (fully conformant, all test vectors pass).
• Node-to-Node (N2N) protocol — Full Ouroboros mini-protocol suite: ChainSync, BlockFetch, TxSubmission2, KeepAlive, PeerSharing.
• Node-to-Client (N2C) protocol — Unix domain socket server with LocalChainSync, LocalStateQuery, LocalTxSubmission, and LocalTxMonitor.
• cardano-cli compatible CLI — Key generation, transaction building, signing, submission, queries, and governance commands.
• Prometheus metrics — Real-time node metrics on port 12798.
• P2P networking — Peer manager with cold/warm/hot lifecycle, DNS multi-resolution (A/AAAA/SRV), ledger-based peer discovery, and inbound rate limiting.
• ChainSync Jumping (CSJ) — Phase A Ouroboros Genesis support: dynamic intersection discovery across multiple peers for faster tip-of-chain recovery.
• Mithril snapshot import — Fast initial sync by importing a Mithril-certified snapshot.
• SIGHUP topology reload — Update peer configuration without restarting the node.

Project Status

Dugite is under active development. It can sync against both the Cardano mainnet and preview/preprod testnets. The node implements the full N2N and N2C protocol stacks, ledger validation, epoch transitions with stake snapshots and reward distribution, and Conway-era governance.

For a detailed checklist of implemented and pending features, see the Developer Wiki.

License

Dugite is released under the Apache-2.0 License.

Installation

Dugite can be installed from pre-built binaries or built from source.

Pre-built Binaries

Download the latest release from GitHub Releases:

Note: macOS x86_64 (Intel) binaries are not published — GitHub's macOS runners are aarch64-only. Intel Mac users should build from source.

# Example: download and extract for Linux x86_64
curl -LO https://github.com/michaeljfazio/dugite/releases/latest/download/dugite-x86_64-linux.tar.gz
tar xzf dugite-x86_64-linux.tar.gz
sudo mv dugite-node dugite-cli dugite-monitor dugite-config /usr/local/bin/

Verify checksums:

curl -LO https://github.com/michaeljfazio/dugite/releases/latest/download/SHA256SUMS.txt
sha256sum -c SHA256SUMS.txt

Container Image

Coming soon: Container images (ghcr.io/michaeljfazio/dugite) are not yet published. Track progress in issue #507. For now, use pre-built binaries or build from source.

See Kubernetes Deployment for production container deployments once images are available.

Building from Source

Prerequisites

Rust Toolchain

Install the latest stable Rust toolchain via rustup:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

Verify the installation:

rustc --version
cargo --version

Dugite requires the latest stable Rust toolchain (edition 2021). Use rustup update stable to stay current.

System Dependencies

Dugite's storage layer is pure Rust with no system dependencies beyond the Rust toolchain. Block storage uses append-only chunk files, and the UTxO set uses dugite-lsm, a pure Rust LSM tree. On all platforms, cargo build works out of the box.

Build

Clone the repository:

git clone https://github.com/michaeljfazio/dugite.git
cd dugite

Build in release mode:

cargo build --release

On Linux with kernel 5.1+, you can enable io_uring for improved disk I/O in the UTxO LSM tree:

cargo build --release --features io-uring

This produces four binaries in target/release/:

Install Binaries

To install the binaries into your $CARGO_HOME/bin (typically ~/.cargo/bin/):

cargo install --path crates/dugite-node
cargo install --path crates/dugite-cli
cargo install --path crates/dugite-monitor
cargo install --path crates/dugite-config

Running Tests

Verify everything is working (requires cargo-nextest):

cargo nextest run --workspace

Or with the built-in test runner:

cargo test --workspace

The project enforces a zero-warning policy. You can run the full CI check locally:

cargo fmt --all -- --check
cargo clippy --all-targets -- -D warnings
cargo nextest run --workspace

Development Build

For faster compilation during development, use the debug profile (the default):

cargo build

Debug builds are significantly faster to compile but produce slower binaries. Always use --release for running a node against a live network.

Quick Start

This guide walks you through getting Dugite running on the Cardano preview testnet.

1. Install

Option A: Pre-built binary (fastest)

curl -LO https://github.com/michaeljfazio/dugite/releases/latest/download/dugite-x86_64-linux.tar.gz
tar xzf dugite-x86_64-linux.tar.gz
sudo mv dugite-node dugite-cli dugite-monitor dugite-config /usr/local/bin/

Option B: Container image (coming soon — #507)

Option C: Build from source

git clone https://github.com/michaeljfazio/dugite.git
cd dugite
cargo build --release

2. Fast Sync with Mithril (Recommended)

Import a Mithril-certified snapshot to skip syncing millions of blocks from genesis:

dugite-node mithril-import \
  --network-magic 2 \
  --database-path ./db-preview

This downloads the latest snapshot from the Mithril aggregator, extracts it, and imports all blocks into the database. On preview testnet this takes approximately 9 minutes (downloading a ~2.7 GB snapshot containing ~4M blocks).

3. Run the Node

Dugite ships with configuration files for all networks. If you built from source, they are in config/<network>/ (config.json, topology.json, and four genesis files per network):

dugite-node run \
  --config config/preview/config.json \
  --topology config/preview/topology.json \
  --database-path ./db-preview \
  --socket-path ./node.sock \
  --host-addr 0.0.0.0 \
  --port 3001

Or via the top-level justfile:

just run-relay preview

The node will:

1. Load the configuration and genesis files
2. Replay imported blocks through the ledger (builds UTxO set, protocol params, delegations)
3. Connect to preview testnet peers
4. Sync remaining blocks to chain tip

Progress is logged every 5 seconds, showing sync percentage, blocks-per-second throughput, UTxO count, and epoch number. Logs go to stdout by default; add --log-output file --log-dir /var/log/dugite for file logging. See Logging for all options.

4. Query the Node

Once the node is running, query it using the CLI via the Unix domain socket:

# Query the current tip
dugite-cli query tip \
  --socket-path ./node.sock \
  --testnet-magic 2

Example output:

{
    "slot": 106453897,
    "hash": "8498ccda...",
    "block": 4094745,
    "epoch": 1232,
    "era": "Conway",
    "syncProgress": "100.00"
}

# Query protocol parameters
dugite-cli query protocol-parameters \
  --socket-path ./node.sock \
  --testnet-magic 2

# Query mempool
dugite-cli query tx-mempool info \
  --socket-path ./node.sock \
  --testnet-magic 2

5. Check Metrics

Prometheus metrics are served on port 12798:

curl -s http://localhost:12798/metrics | grep sync_progress
# sync_progress_percent 10000

Next Steps

• Configuration — Detailed configuration options
• Networks — Connecting to mainnet, preview, or preprod
• Mithril Import — Fast initial sync details
• Monitoring — Prometheus metrics endpoint
• Kubernetes Deployment — Helm chart for production deployments
• Relay Node — Running relay nodes for a stake pool
• Block Producer — Running a stake pool
• CLI Reference — Full CLI command reference

Development

Day-to-day tasks (build, test, lint, run a network, soak, monitor) are wrapped by a top-level justfile. Install just (brew install just, cargo install just, or your package manager) and just --list shows the full menu.

Quick reference

# Full CI gate (run this before opening a PR).
just check

# Individual gates
just build                  # cargo build --release --all-targets
just test                   # cargo nextest run --workspace
just test-doc               # cargo test --doc
just clippy                 # cargo clippy --all-targets -- -D warnings
just fmt-check              # cargo fmt --all -- --check
just fmt                    # apply rustfmt

# Run a node
just run-relay preview
just run-bp mainnet
just mithril-import preview

# Local devnet (loopback testnet)
just devnet-setup           # one-time
just devnet-run             # start dugite-bp + dugite-relay + cardano-node-bp
just devnet-soak            # 30-minute soak
just devnet-verify          # check evidence
just devnet-stop

# Preview Sandstone soak
just soak-6h                # Haskell relay + dugite BP, 6h orchestrator
just soak-bare-bp           # dugite BP alone
just soak-status

# Monitoring (Prometheus + Grafana via Docker)
just monitor-start
just monitor-status
just monitor-stop
just watch-metrics          # tail the Prometheus endpoint

# Validation
just compat-n2c             # cardano-cli vs dugite-cli N2C diff
just compat-leader          # leader-schedule N2C diff
just submit-txs n=100       # submit N test transactions
just stress-test
just stress-relay
just benchmark-pipeline

# Dev / release helpers
just licenses               # regenerate docs/src/reference/third-party-licenses.md
just clean-worktrees        # prune stale git worktree branches
just query-tip              # dugite-cli query tip against ./node.sock

Layout

The recipes wrap scripts under scripts/<group>/:

Each script does cd "$(dirname "$0")/../.." first, so you can invoke them from anywhere — just, the repo root, or by absolute path. See scripts/README.md and config/README.md for the canonical layout description.

Hard requirements

• Zero warnings — cargo clippy --all-targets -- -D warnings (also run by just clippy and just check)
• Formatted — cargo fmt --all -- --check (just fmt-check)
• All tests pass — cargo nextest run --workspace and cargo test --doc (just test, just test-doc)
• CI green before merging
• Focused commits — stage explicit filenames; the pre-commit hook warns if staged paths span more than two crates (set DUGITE_PRECOMMIT_STRICT=1 to make this fatal)

Configuration

Dugite reads a JSON configuration file that controls network settings, genesis file paths, P2P parameters, and tracing options. The format is compatible with the cardano-node configuration format.

Configuration File Format

The configuration file uses PascalCase keys (matching the cardano-node convention):

{
  "Network": "Testnet",
  "NetworkMagic": 2,
  "EnableP2P": true,
  "DiffusionMode": "InitiatorAndResponder",
  "PeerSharing": null,
  "Protocol": {
    "RequiresNetworkMagic": "RequiresMagic"
  },
  "ShelleyGenesisFile": "shelley-genesis.json",
  "ByronGenesisFile": "byron-genesis.json",
  "AlonzoGenesisFile": "alonzo-genesis.json",
  "ConwayGenesisFile": "conway-genesis.json",
  "TargetNumberOfRootPeers": 60,
  "TargetNumberOfActivePeers": 15,
  "TargetNumberOfEstablishedPeers": 30,
  "TargetNumberOfKnownPeers": 85,
  "TargetNumberOfActiveBigLedgerPeers": 5,
  "TargetNumberOfEstablishedBigLedgerPeers": 10,
  "TargetNumberOfKnownBigLedgerPeers": 15,
  "MinSeverity": "Info",
  "TraceOptions": {
    "TraceBlockFetchClient": false,
    "TraceBlockFetchServer": false,
    "TraceChainDb": false,
    "TraceChainSyncClient": false,
    "TraceChainSyncServer": false,
    "TraceForge": false,
    "TraceMempool": false
  }
}

Fields Reference

Network Settings

Protocol

Genesis Files

Genesis file paths are resolved relative to the directory containing the configuration file. For example, if your config is at /opt/cardano/config.json and specifies "ShelleyGenesisFile": "shelley-genesis.json", Dugite will look for /opt/cardano/shelley-genesis.json.

Tip: Genesis files for each network can be downloaded from the Cardano Operations Book.

P2P Parameters

These parameters control the P2P peer governor's target counts, matching the cardano-node defaults. The governor continuously works to maintain these targets by promoting/demoting peers and discovering new ones.

Tracing

Log Level Control

The log level can be set via CLI flag or environment variable:

# Via CLI flag
dugite-node run --log-level debug ...

# Via environment variable (takes priority over --log-level)
RUST_LOG=info dugite-node run ...

# Debug only for specific crates
RUST_LOG=dugite_network=debug,dugite_consensus=debug dugite-node run ...

Dugite supports multiple log output targets (stdout, file, journald) and file rotation. See Logging for full details on output configuration.

Minimal Configuration

The smallest viable configuration file specifies only the network:

{
  "Network": "Testnet",
  "NetworkMagic": 2
}

All other fields use sensible defaults. When no genesis files are specified, the node operates with built-in default parameters.

Format Support

Dugite supports both JSON (.json) and TOML (.toml) configuration files. The format is determined by the file extension. JSON files use the cardano-node compatible PascalCase format shown above.

Interactive Configuration Editor (dugite-config)

dugite-config is a standalone TUI tool for creating and editing Dugite configuration files interactively, without needing to remember field names or valid value ranges.

Installation

Built as part of the standard workspace:

cargo build --release -p dugite-config

Commands

# Interactively create a new configuration file
dugite-config init --out-file config.json

# Launch the interactive editor for an existing config file
dugite-config edit config.json

# Validate a configuration file and report errors
dugite-config validate config.json

# Get the value of a specific field
dugite-config get config.json TargetNumberOfActivePeers

# Set the value of a specific field
dugite-config set config.json TargetNumberOfActivePeers 30

Interactive Editor Features

The editor provides a tree view of all configuration fields with inline editing:

• Tree navigation — expand/collapse sections, navigate fields with arrow keys
• Inline editing — press Enter on any field to edit its value in place
• Type validation — invalid values are rejected with an inline error message and a description of the expected type and range
• Tuning hints — contextual hints appear alongside each field explaining the impact of changes (for example, peer count targets and their effect on network connectivity)
• Search/filter — press / to search fields by name
• Diff view — press d to see a side-by-side diff of your changes before saving
• Save/discard — Ctrl+S to save, Ctrl+Q or Esc to discard

The editor validates the full configuration on save and will not write an invalid file.

Configuration Editor (dugite-config)

dugite-config is a standalone TUI tool for creating and editing Dugite configuration files interactively. It provides a full-screen terminal interface with tree navigation, inline editing, type validation, and a diff view — no need to remember field names or look up valid ranges.

Installation

dugite-config is built as part of the standard workspace:

cargo build --release -p dugite-config
cp target/release/dugite-config /usr/local/bin/

Commands

init

Create a new configuration file, guided step by step:

dugite-config init --out-file config.json

The init wizard prompts for the network (mainnet/preview/preprod), genesis file paths, P2P targets, and tracing options, then writes a validated JSON file.

edit

Launch the full-screen interactive editor:

dugite-config edit config.json

validate

Check a configuration file for errors without modifying it:

dugite-config validate config.json

Output on success:

config.json: OK (all fields valid)

Output on failure:

config.json: 2 error(s)
  Line 7 — TargetNumberOfActivePeers: value 200 exceeds maximum (100)
  Line 12 — MinSeverity: unknown value "Verbose" (expected: Trace, Debug, Info, Warning, Error)

get / set

Non-interactive field access for scripting:

# Get a field
dugite-config get config.json TargetNumberOfActivePeers
# Output: 20

# Set a field
dugite-config set config.json TargetNumberOfActivePeers 30

# Set a nested field
dugite-config set config.json TraceOptions.TraceForge true

Interactive Editor

The interactive editor (dugite-config edit) renders a full-screen TUI with three panes:

┌─ Fields ──────────────────────┬─ Value ───────────┬─ Hints ───────────────────────────┐
│ > Network Settings            │                   │                                   │
│     Network                   │ Testnet           │ Network identifier. Use "Mainnet" │
│     NetworkMagic              │ 2                 │ for mainnet or "Testnet" for      │
│     EnableP2P                 │ true              │ testnets. If omitted, defaults    │
│ > Genesis Files               │                   │ based on Network field.           │
│     ShelleyGenesisFile        │ shelley-gen...    │                                   │
│     ByronGenesisFile          │ byron-genesi...   │                                   │
│     AlonzoGenesisFile         │ alonzo-genes...   │                                   │
│     ConwayGenesisFile         │ conway-genes...   │                                   │
│ > P2P Parameters              │                   │                                   │
│     DiffusionMode             │ InitiatorAn...    │                                   │
│     PeerSharing               │ PeerSharing...    │                                   │
│     TargetNumberOfActivePeers │ 15                │                                   │
└───────────────────────────────┴───────────────────┴───────────────────────────────────┘

Navigation

Inline Editing

Pressing Enter on a field opens it for editing in place. The current value is pre-filled. Type a new value and press Enter to confirm or Escape to cancel.

Type validation runs immediately on confirmation. If the value is invalid (for example, a string where an integer is expected, or a number outside the valid range), an inline error message appears below the field. The cursor stays on the field until a valid value is entered or the edit is cancelled.

Tuning Hints

The right-hand pane shows contextual hints for the selected field, including:

• A description of what the field controls
• The valid type and range
• Practical advice on the impact of different values

For example, TargetNumberOfActivePeers shows advice on the trade-off between connectivity and bandwidth, and notes that values above 50 are rarely beneficial for relay nodes.

Search and Filter

Press / to open the search bar. Typing narrows the visible fields to those whose names match the query. Press Escape to clear the filter and return to the full tree.

Diff View

Press d to toggle the diff view, which shows a side-by-side comparison of the original file and your pending changes. Fields with modified values are highlighted. Use this before saving to confirm your edits.

Scripted Workflows

dugite-config can be used in deployment scripts for automated configuration management:

#!/usr/bin/env bash
# Example: configure a relay node for preview testnet

CONFIG="config/preview/config.json"

dugite-config init --out-file "$CONFIG" \
  --network Testnet \
  --network-magic 2 \
  --shelley-genesis shelley-genesis.json \
  --byron-genesis byron-genesis.json \
  --alonzo-genesis alonzo-genesis.json \
  --conway-genesis conway-genesis.json

dugite-config set "$CONFIG" EnableP2P true
dugite-config set "$CONFIG" DiffusionMode InitiatorAndResponder
dugite-config set "$CONFIG" TargetNumberOfActivePeers 15
dugite-config set "$CONFIG" TargetNumberOfEstablishedPeers 30
dugite-config set "$CONFIG" TargetNumberOfKnownPeers 85
dugite-config validate "$CONFIG"

Topology

The topology file defines the peers that the node connects to. Dugite supports the full cardano-node 10.x+ P2P topology format.

Topology File Format

{
  "bootstrapPeers": [
    { "address": "backbone.cardano.iog.io", "port": 3001 },
    { "address": "backbone.mainnet.cardanofoundation.org", "port": 3001 },
    { "address": "backbone.mainnet.emurgornd.com", "port": 3001 }
  ],
  "localRoots": [
    {
      "accessPoints": [
        { "address": "192.168.1.100", "port": 3001 }
      ],
      "advertise": false,
      "hotValency": 1,
      "warmValency": 2,
      "trustable": true
    }
  ],
  "publicRoots": [
    {
      "accessPoints": [
        { "address": "relays-new.cardano-mainnet.iohk.io", "port": 3001 }
      ],
      "advertise": false
    }
  ],
  "useLedgerAfterSlot": 177724800
}

Peer Categories

Bootstrap Peers

Trusted peers from founding organizations, used during initial sync. These are the first peers the node contacts when starting.

"bootstrapPeers": [
  { "address": "backbone.cardano.iog.io", "port": 3001 }
]

Set to null or an empty array to disable bootstrap peers:

"bootstrapPeers": null

Local Roots

Peers the node should always maintain connections with. Typically used for:

• Your block producer (if running a relay)
• Peer arrangements with other stake pool operators
• Trusted relay nodes you operate

"localRoots": [
  {
    "accessPoints": [
      { "address": "192.168.1.100", "port": 3001 }
    ],
    "advertise": true,
    "hotValency": 2,
    "warmValency": 3,
    "trustable": true,
    "behindFirewall": false,
    "diffusionMode": "InitiatorAndResponder"
  }
]

Public Roots

Publicly known nodes (e.g., IOG relays) serving as fallback peers before the node has synced to the useLedgerAfterSlot threshold.

"publicRoots": [
  {
    "accessPoints": [
      { "address": "relays-new.cardano-mainnet.iohk.io", "port": 3001 }
    ],
    "advertise": false
  }
]

Ledger-Based Peer Discovery

After the node syncs past the useLedgerAfterSlot slot, it discovers peers from stake pool registrations in the ledger state. This provides decentralized peer discovery without relying on centralized relay lists.

"useLedgerAfterSlot": 177724800

Set to a negative value or omit to disable ledger peer discovery.

Peer Snapshot File

Optional path to a big ledger peer snapshot file for Genesis bootstrap:

"peerSnapshotFile": "peer-snapshot.json"

Example Topologies

Preview Testnet Relay

{
  "bootstrapPeers": [
    { "address": "preview-node.play.dev.cardano.org", "port": 3001 }
  ],
  "localRoots": [
    { "accessPoints": [], "advertise": false, "valency": 1 }
  ],
  "publicRoots": [
    { "accessPoints": [], "advertise": false }
  ],
  "useLedgerAfterSlot": 102729600
}

Mainnet Relay

{
  "bootstrapPeers": [
    { "address": "backbone.cardano.iog.io", "port": 3001 },
    { "address": "backbone.mainnet.cardanofoundation.org", "port": 3001 },
    { "address": "backbone.mainnet.emurgornd.com", "port": 3001 }
  ],
  "localRoots": [
    { "accessPoints": [], "advertise": false, "valency": 1 }
  ],
  "publicRoots": [
    { "accessPoints": [], "advertise": false }
  ],
  "useLedgerAfterSlot": 177724800
}

Relay with Block Producer

A relay node that maintains a connection to your block producer:

{
  "bootstrapPeers": [
    { "address": "backbone.cardano.iog.io", "port": 3001 },
    { "address": "backbone.mainnet.cardanofoundation.org", "port": 3001 }
  ],
  "localRoots": [
    {
      "accessPoints": [
        { "address": "10.0.0.10", "port": 3001 }
      ],
      "advertise": false,
      "hotValency": 1,
      "warmValency": 2,
      "trustable": true,
      "behindFirewall": true
    }
  ],
  "publicRoots": [
    { "accessPoints": [], "advertise": false }
  ],
  "useLedgerAfterSlot": 177724800
}

DNS SRV Resolution

When a hostname is specified in any accessPoints entry, Dugite queries DNS for SRV records at _cardano._tcp.<host> before falling back to A/AAAA lookup — matching the behaviour of the Haskell cardano-node. SRV records carry port, priority, and weight fields (RFC 2782); Dugite honours priority ordering and performs a weighted shuffle within equal-priority groups.

If no SRV records exist (NXDOMAIN or empty answer), Dugite falls back to a direct A/AAAA lookup using the port specified in the topology entry.

IPv4 and IPv6 addresses are both accepted; Dugite resolves A and AAAA records concurrently.

SIGHUP Topology Reload

Dugite supports live topology reloading. Send a SIGHUP signal to the running node process, and it will re-read the topology file and update the peer manager with the new configuration:

kill -HUP $(pidof dugite-node)

This allows you to add or remove peers without restarting the node.

Networks

Dugite can connect to any Cardano network. Each network is identified by a unique magic number used during the N2N handshake.

Network Magic Values

Connecting to Mainnet

Create a config-mainnet.json:

{
  "Network": "Mainnet",
  "NetworkMagic": 764824073
}

Create a topology-mainnet.json:

{
  "bootstrapPeers": [
    { "address": "backbone.cardano.iog.io", "port": 3001 },
    { "address": "backbone.mainnet.cardanofoundation.org", "port": 3001 },
    { "address": "backbone.mainnet.emurgornd.com", "port": 3001 }
  ],
  "localRoots": [{ "accessPoints": [], "advertise": false, "valency": 1 }],
  "publicRoots": [{ "accessPoints": [], "advertise": false }],
  "useLedgerAfterSlot": 177724800
}

Run the node:

dugite-node run \
  --config config-mainnet.json \
  --topology topology-mainnet.json \
  --database-path ./db-mainnet \
  --socket-path ./node-mainnet.sock \
  --host-addr 0.0.0.0 \
  --port 3001

Tip: For a faster initial mainnet sync, consider using Mithril snapshot import first.

Connecting to Preview Testnet

Note: Preview testnet is at Protocol Version 11 (PV11). Peers running cardano-node 10.x will reject the connection with a version mismatch. Use cardano-node 11.0.1+ for any preview peer or soak rig.

Create a config-preview.json:

{
  "Network": "Testnet",
  "NetworkMagic": 2
}

Create a topology-preview.json:

{
  "bootstrapPeers": [
    { "address": "preview-node.play.dev.cardano.org", "port": 3001 }
  ],
  "localRoots": [{ "accessPoints": [], "advertise": false, "valency": 1 }],
  "publicRoots": [{ "accessPoints": [], "advertise": false }],
  "useLedgerAfterSlot": 102729600
}

Run the node:

dugite-node run \
  --config config-preview.json \
  --topology topology-preview.json \
  --database-path ./db-preview \
  --socket-path ./node-preview.sock \
  --host-addr 0.0.0.0 \
  --port 3001

Connecting to Preprod Testnet

Create a config-preprod.json:

{
  "Network": "Testnet",
  "NetworkMagic": 1
}

Create a topology-preprod.json:

{
  "bootstrapPeers": [
    { "address": "preprod-node.play.dev.cardano.org", "port": 3001 }
  ],
  "localRoots": [{ "accessPoints": [], "advertise": false, "valency": 1 }],
  "publicRoots": [{ "accessPoints": [], "advertise": false }],
  "useLedgerAfterSlot": 76924800
}

Run the node:

dugite-node run \
  --config config-preprod.json \
  --topology topology-preprod.json \
  --database-path ./db-preprod \
  --socket-path ./node-preprod.sock \
  --host-addr 0.0.0.0 \
  --port 3001

Official Configuration Files

Official configuration and topology files for each network are maintained in the Cardano Operations Book:

• Preview: book.world.dev.cardano.org/environments/preview/
• Preprod: book.world.dev.cardano.org/environments/preprod/
• Mainnet: book.world.dev.cardano.org/environments/mainnet/

These include the full genesis files (Byron, Shelley, Alonzo, Conway) required for complete protocol parameter initialization.

Using the CLI with Different Networks

When querying a node connected to a testnet, pass the --testnet-magic flag to the CLI:

# Preview
dugite-cli query tip --socket-path ./node-preview.sock --testnet-magic 2

# Preprod
dugite-cli query tip --socket-path ./node-preprod.sock --testnet-magic 1

# Mainnet (default, --testnet-magic not needed)
dugite-cli query tip --socket-path ./node-mainnet.sock

Multiple Nodes

You can run multiple Dugite instances on the same machine by using different ports, database paths, and socket paths:

# Preview on port 3001
dugite-node run --port 3001 --database-path ./db-preview --socket-path ./preview.sock ...

# Preprod on port 3002
dugite-node run --port 3002 --database-path ./db-preprod --socket-path ./preprod.sock ...

Mithril Snapshot Import

Syncing a Cardano node from genesis can take a very long time. Dugite supports importing Mithril-certified snapshots of the immutable database to drastically reduce initial sync time.

How It Works

Mithril is a stake-based threshold multi-signature scheme that produces certified snapshots of the Cardano immutable database. These snapshots are verified by Mithril signers (stake pool operators) and made available through Mithril aggregator endpoints.

The import process:

1. Queries the Mithril aggregator for the latest available snapshot
2. Downloads the snapshot archive (compressed with zstandard)
3. Extracts the cardano-node chunk files
4. Parses each block using Dugite's in-house multi-era CBOR decoder
5. Bulk-imports blocks into Dugite's ImmutableDB (append-only chunk files)

Usage

dugite-node mithril-import \
  --network-magic <magic> \
  --database-path <path>

Arguments

Examples

Mainnet:

dugite-node mithril-import \
  --network-magic 764824073 \
  --database-path ./db-mainnet

Preview testnet:

dugite-node mithril-import \
  --network-magic 2 \
  --database-path ./db-preview

Preprod testnet:

dugite-node mithril-import \
  --network-magic 1 \
  --database-path ./db-preprod

Mithril Aggregator Endpoints

Dugite automatically selects the correct aggregator for each network:

Resume Support

The import process supports resuming interrupted downloads and imports:

• If the snapshot archive has already been downloaded (same size), the download is skipped
• If the archive has already been extracted, extraction is skipped
• Blocks already present in the database are skipped during import

This means you can safely interrupt the import and restart it later.

After Import

Once the import completes, start the node normally. It will detect the imported blocks and resume syncing from where the snapshot left off:

dugite-node run \
  --config config.json \
  --topology topology.json \
  --database-path ./db-mainnet \
  --socket-path ./node.sock \
  --host-addr 0.0.0.0 \
  --port 3001

Disk Space Requirements

Mithril snapshots are large. Approximate sizes (which grow over time):

The temporary directory needs enough space for both the compressed archive and the extracted files. After import, temporary files are automatically cleaned up.

Note: Ensure you have sufficient disk space before starting the import. The --temp-dir flag can be used to direct temporary files to a different volume if needed.

Mithril Ancillary Import — Trust Model

The Mithril aggregator publishes two artefacts per snapshot:

1. Main archive — the certified ImmutableDB chunk files (immutable/*.{chunk,primary,secondary}).
2. Ancillary archive — the serialised Haskell ExtLedgerState at the immutable tip, plus the partial next-chunk trio (ledger/<slot>/state, ledger/<slot>/tables).

Dugite consumes both: the main archive populates ImmutableDB, and the ancillary archive lets the node skip the multi-hour chain-from-genesis replay normally needed to rebuild ledger state.

This document records the trust model, the operator-exposure decision, and the verification harness used to confirm byte-exactness.

Why ancillary matters

Without ancillary, after mithril-import returns the node still has to replay every certified block through its own validator to rebuild:

• The UTxO set
• Pool, DRep, committee and proposal state
• Treasury, reserves, fees, deposits
• All five Praos nonces (evolving, candidate, epoch, lab, last_epoch_block)
• Operational-certificate counters per pool
• Stake distribution + mark/set/go snapshots
• Pending reward updates and MIR deltas

On mainnet that replay takes multi-hour today (typically 10+ hours on commodity hardware). Importing the ancillary directly drops cold-start to ~15 minutes of decode + LSM bulk-load.

Trust model

The ancillary archive is signed and certified by Mithril's threshold multi-signature scheme using the same ≥ 2/3 stake-weighted aggregator key that signs the immutable chunks. Concretely:

• Dugite downloads the ancillary.tar.zst from the aggregator's V2 /artifact/cardano-database/{hash}/cardano-database-snapshots endpoint.
• The manifest is a JSON map of filename → SHA-256(content) plus an Ed25519 signature over the sorted key+value pairs, signed by a network-specific ancillary verification key. Dugite verifies the signature before unpacking.
• Per-file SHA-256 hashes are checked against the manifest as files are extracted (mithril.rs::verify_ancillary_manifest).

The Ed25519 verification keys are pinned in source:

The aggregator's full STM certificate chain is also verified (back to the genesis certificate) when --skip-certificate-verification is not set. This is identical to the trust posture used for the main snapshot.

What we trust when we accept the ancillary

We trust that a Haskell cardano-node implementation honestly computed the ledger state at the certified immutable tip and published it. We do not re-validate the state against our own from-genesis replay before using it.

This is a stronger trust assumption than the main snapshot alone: the main snapshot is a certified statement that "this chain is canonical and ≥ 2/3 of stake agrees"; the ancillary is a stronger statement that "the state derived by Haskell from this chain is also correct."

What we do not trust

We do not trust the ancillary's CBOR encoder to be implementation-independent: dugite's runtime types differ from Haskell's HFC-telescope / HKD-parameterised types, so the adapter (LedgerState::from_haskell_snapshot, crates/dugite-ledger/src/state/mod.rs:697) explicitly converts every field. Any new era will need adapter coverage before the ancillary path will work for that era.

Operator-exposure decision

The flag --include-ancillary is default-on. Passing --no-include-ancillary skips the ancillary download and falls back to chain-from-genesis replay.

Rationale:

• Most end-users prefer fast bootstrap and accept the certified-ancillary trust posture (which is the same posture used for the main snapshot's stake-weighted certification).
• The pre-ancillary import path (chunk-only) historically caused issue #335 — stale genesis-default protocol parameters at the imported tip — because the node had no way to learn current PParams without replay. The ancillary path resolves this by providing live PParams directly.
• Operators who need byte-exact verification of dugite's own ledger derivation against the Haskell reference should run two imports — one with --include-ancillary and one with --no-include-ancillary (waiting for the replay to complete) — then diff the two ledger-snapshot.bin files via dugite-node verify-ledger-snapshot.

Verification harness (issue #670 acceptance)

dugite-node verify-ledger-snapshot --left <path> --right <path> performs a semantic byte-exact comparison of two ledger snapshots. The harness reports any field-level mismatch with full diagnostic detail and exits non-zero on failure.

Each <path> may be either a ledger-snapshot.bin file or a database directory containing one.

Acceptance procedure for a new era / boundary

1. Build two databases:

   dugite-node mithril-import \
     --network-magic 2 \
     --database-path ./db-preview-ancillary \
     --include-ancillary
   
   dugite-node mithril-import \
     --network-magic 2 \
     --database-path ./db-preview-replay \
     --no-include-ancillary
   

2. Replay the no-ancillary database by running dugite-node run against it until the ledger state catches up to the same anchor as the ancillary database. The replay is the slow path the ancillary is designed to avoid; allow multi-hour wall time.

3. Compare:

   dugite-node verify-ledger-snapshot \
     --left ./db-preview-ancillary \
     --right ./db-preview-replay
   

4. Expected output on PASS:

   PASS — snapshots are semantically equal
   

5. On FAIL, the harness prints one line per differing field. Use those entries to locate the divergence — for example a governance.proposals mismatch points to the Conway governance decoder, a snapshots.set mismatch points to mark/set/go snapshot semantics, etc.

Acceptance status

The harness must PASS for at least one preview boundary AND one preprod boundary before #670 is considered fully verified.

Prior to commits in 2026 Q2 (issues #438, #481, #624, #626, #678, #685) the from-genesis replay did not match the Haskell ancillary at all boundaries — the harness reported drift in pot fields (treasury, reserves, epoch_fees) cascading from a missing Babbage→Conway PPUP path that left the on-chain protocol version stuck at 8 in dugite while the canonical chain ran at 9. With those resolved, a preview-mainnet-style chunk replay through to the mithril anchor now reproduces the Haskell ledger byte-exact, including:

• Pots (treasury, reserves, fees, deposits, donation)
• All five Praos nonces
• DRep + committee + proposal + vote state
• Mark/set/go snapshots + ssFee
• bprev block production counters
• Stake distribution + per-credential deposits

Any remaining open epoch-diff issue is a blocker for re-claiming the gate; consult the project tracker before signing off a new release that touches era-translation, governance enactment, or PPUP semantics.

Code references

Related issues

• #670 — This issue. Adds the explicit CLI flag, documents the trust model and operator-exposure decision, and ships the byte-exact verification harness.
• #335 — Stale genesis-default protocol parameters when ancillary was skipped (root cause for making ancillary default-on).
• #626 — Residual +297K-ADA drift at preview boundary 3→4 (resolved; PPUP timing aligned with Haskell HFC tick).
• #624 — Pre-Conway PPUP decoder fix that closed earlier boundary drifts.
• #678 — Conway treasury-value check incorrectly gated; resolved by mode-gating on ValidateAll to match Haskell ApplySTSOpts.asoValidation.
• #685 — Missing PPUP application at Babbage→Conway era boundary + prev_pp captured AFTER ratify_proposals_impl. Both fixed; replay now byte-exact through the originally-failing preview slot 76172461 and past.
• #516 — Single-use channel constraint workaround (unrelated to ancillary but referenced from the same lifecycle code).

Logging

Dugite uses the tracing ecosystem for structured logging. It supports multiple output targets, structured and human-readable formats, log rotation for file output, and fine-grained level control.

Output Formats

Dugite supports two log formats, selectable via the --log-format flag:

Text (default)

Human-readable compact output with timestamps, level, target module, and structured fields:

dugite-node run --log-format text ...

2026-03-12T12:34:56.789Z  INFO dugite_node::node: Syncing progress="95.42%" epoch=512 block=11283746 tip=11300000 remaining=16254 speed="312 blk/s" utxos=15234892
2026-03-12T12:34:56.790Z  INFO dugite_node::node: Peer connected peer=1.2.3.4:3001 rtt_ms=42

JSON

Structured JSON output, one object per line. Ideal for log aggregation systems (ELK, Loki, Datadog):

dugite-node run --log-format json ...

{"timestamp":"2026-03-12T12:34:56.789Z","level":"INFO","target":"dugite_node::node","fields":{"message":"Syncing","progress":"95.42%","epoch":512,"block":11283746}}

Output Targets

Dugite can log to one or more output targets simultaneously using the --log-output flag. You can specify this flag multiple times to enable multiple targets:

# Stdout only (default)
dugite-node run --log-output stdout ...

# File only
dugite-node run --log-output file ...

# Both stdout and file
dugite-node run --log-output stdout --log-output file ...

# Systemd journal (requires journald feature)
dugite-node run --log-output journald ...

Stdout

The default output target. Logs are written to standard output with ANSI color codes when the output is a terminal. Colors can be disabled with --log-no-color.

File

Logs are written to rotating log files in the directory specified by --log-dir (default: logs/). The rotation strategy is configured with --log-file-rotation:

dugite-node run \
  --log-output file \
  --log-dir /var/log/dugite \
  --log-file-rotation daily \
  ...

File output uses non-blocking I/O with buffered writes. The buffer is flushed automatically on shutdown.

Journald

Native systemd journal integration. This requires building Dugite with the journald feature:

cargo build --release --features journald

Then run with:

dugite-node run --log-output journald ...

View logs with journalctl:

journalctl -u dugite-node -f
journalctl -u dugite-node --since "1 hour ago"

Log Levels

The log level can be set via the --log-level CLI flag or the RUST_LOG environment variable. If both are set, RUST_LOG takes priority.

# Via CLI flag
dugite-node run --log-level debug ...

# Via environment variable (takes priority)
RUST_LOG=debug dugite-node run ...

Available levels (from most to least verbose):

Per-Crate Filtering

Use RUST_LOG for fine-grained control over which components produce output:

# Debug only for specific crates
RUST_LOG=dugite_network=debug,dugite_consensus=debug dugite-node run ...

# Trace storage operations, debug everything else
RUST_LOG=dugite_storage=trace,debug dugite-node run ...

# Silence noisy crates
RUST_LOG=info,dugite_network=warn dugite-node run ...

CLI Reference

All logging flags are shared between the run and mithril-import subcommands:

Runtime Log Verbosity Reload (SIGHUP)

Dugite supports changing per-subsystem log verbosity at runtime without restarting the node. This is useful for debugging a specific issue (for example, enabling trace logging for the network layer) without disrupting ongoing block production or sync.

Workflow:

1. Edit the node configuration file and add (or update) the LogDirective field:

   {
     "LogDirective": "info,dugite_network=trace,dugite_consensus=debug"
   }
   

   The value accepts any RUST_LOG-compatible directive, including *=debug, trace, or per-module overrides like dugite_ledger=warn.

2. Send SIGHUP to the running node:

   kill -HUP $(pidof dugite-node)
   

   The node re-reads the config file. If LogDirective is present and valid, the filter is reloaded immediately and logged:

   INFO dugite_node: Reloaded log directive: "info,dugite_network=trace"
   

   If the directive string is invalid, the previous filter is left intact.

3. To restore the original level, remove LogDirective from the config and send SIGHUP again, or set it back to "info".

Note: LogDirective is only applied via SIGHUP. The initial startup level is controlled by --log-level / RUST_LOG as before.

Production Recommendations

For production deployments with log aggregation:

dugite-node run \
  --log-output file \
  --log-output journald \
  --log-format json \
  --log-dir /var/log/dugite \
  --log-file-rotation daily \
  ...

This configuration:

• Writes structured JSON logs to systemd journal for journalctl integration
• Writes rotated JSON log files for archival and ingestion by log aggregators
• JSON format ensures all structured fields are machine-parseable

For human operators monitoring the console:

dugite-node run --log-output stdout --log-format text ...

For containerized deployments (Docker, Kubernetes), stdout with JSON is ideal since the container runtime captures output and log drivers can parse the structured format:

dugite-node run --log-output stdout --log-format json ...

Monitoring

Dugite provides two complementary monitoring tools: a terminal dashboard (dugite-monitor) for quick at-a-glance status, and a Prometheus-compatible metrics endpoint for production alerting and dashboards.

Terminal Dashboard (dugite-monitor)

dugite-monitor is a standalone binary that renders a real-time status dashboard in the terminal by polling the node's Prometheus endpoint. It requires no external infrastructure and works over SSH.

# Monitor a local node (default: http://localhost:12798/metrics)
dugite-monitor

# Monitor a remote node
dugite-monitor --metrics-url http://192.168.1.100:12798/metrics

# Custom refresh interval (default: 2 seconds)
dugite-monitor --refresh-interval 5

The dashboard displays four panels:

• Chain Status — sync progress, current slot/block/epoch, tip age, GSM state
• Peers — out/in/total connection counts, hot/warm/cold breakdown, EWMA latency
• Performance — block rate sparkline, replay throughput, transaction counts
• Governance — treasury balance, DRep count, active proposals, pool count

Color-coded health indicators (green/yellow/red) reflect tip age and sync progress. The block rate sparkline shows the last 30 data points so you can spot throughput trends at a glance.

Keyboard navigation: q to quit, Tab to cycle panels, j/k (vim-style) to scroll within a panel.

Prometheus Metrics Endpoint

Dugite exposes a Prometheus-compatible metrics endpoint for monitoring node health and sync progress.

Metrics Endpoint

The metrics server runs on port 12798 by default and responds to any HTTP request with Prometheus exposition format metrics:

http://localhost:12798/metrics

Example response:

# HELP dugite_blocks_received_total Total blocks received from peers
# TYPE dugite_blocks_received_total gauge
dugite_blocks_received_total 1523847

# HELP dugite_blocks_applied_total Total blocks applied to ledger
# TYPE dugite_blocks_applied_total gauge
dugite_blocks_applied_total 1523845

# HELP dugite_slot_number Current slot number
# TYPE dugite_slot_number gauge
dugite_slot_number 142857392

# HELP dugite_block_number Current block number
# TYPE dugite_block_number gauge
dugite_block_number 11283746

# HELP dugite_epoch_number Current epoch number
# TYPE dugite_epoch_number gauge
dugite_epoch_number 512

# HELP dugite_sync_progress_percent Chain sync progress (0-10000, divide by 100 for %)
# TYPE dugite_sync_progress_percent gauge
dugite_sync_progress_percent 9542

# HELP dugite_utxo_count Number of entries in the UTxO set
# TYPE dugite_utxo_count gauge
dugite_utxo_count 15234892

# HELP dugite_mempool_tx_count Number of transactions in the mempool
# TYPE dugite_mempool_tx_count gauge
dugite_mempool_tx_count 42

# HELP dugite_peers_connected Number of connected peers
# TYPE dugite_peers_connected gauge
dugite_peers_connected 8

Health Endpoint

The metrics server exposes a /health endpoint for monitoring node status:

GET http://localhost:12798/health

Returns JSON with three possible statuses:

• healthy: Sync progress >= 99.9%
• syncing: Actively catching up to chain tip
• stalled: No blocks received for > 5 minutes AND sync < 99%

{
  "status": "healthy",
  "uptime_seconds": 3421,
  "slot": 142857392,
  "block": 11283746,
  "epoch": 512,
  "sync_progress": 99.95,
  "peers": 8,
  "last_block_received": "2026-03-14T12:34:56.789Z"
}

Readiness Endpoint

For Kubernetes readiness probes:

GET http://localhost:12798/ready

Returns 200 OK when sync_progress >= 99.9%, 503 Service Unavailable otherwise:

{"ready": true}

or:

{"ready": false, "sync_progress": 75.42}

Available Metrics

Counters

Gauges

Histograms

Histograms expose _bucket, _count, and _sum suffixes for standard Prometheus histogram queries.

Prometheus Configuration

Add the Dugite node as a scrape target in your prometheus.yml:

scrape_configs:
  - job_name: 'dugite'
    scrape_interval: 15s
    static_configs:
      - targets: ['localhost:12798']
        labels:
          network: 'mainnet'
          node: 'relay-1'

Grafana Dashboard

Dugite ships with a pre-built Grafana dashboard at config/monitoring/grafana-dashboard.json. The dashboard covers all node metrics organized into nine sections:

• Overview — Sync progress gauge, block height, epoch, slot, connected peers, blocks forged
• Node Health — Uptime, disk available (stat + time series)
• Sync & Throughput — Sync progress over time, block apply/receive rate (blk/s), block height, rollbacks
• Peers — Connected peer count over time, peer state breakdown (hot/warm/cold stacked)
• Mempool & Transactions — Mempool tx count, mempool size (bytes), transaction rate (received/validated/rejected)
• Ledger State — UTxO set size, stake delegations, treasury balance (ADA), registered stake pools
• Governance — Registered DReps, active governance proposals
• Block Production — Total blocks forged, block forge rate (blk/h)
• Network Latency — Handshake RTT and block fetch latency percentiles (p50/p95/p99), request counts
• Validation Errors — Error breakdown by type (stacked bars), error totals (bar chart)

Quick Start (Docker)

The fastest way to start a local monitoring stack is with the included script:

# Start Prometheus + Grafana
just monitor-start         # or: ./scripts/monitoring/start.sh

# Open the dashboard (admin/admin)
open http://localhost:3000/d/dugite-node/dugite-node

# Check status
just monitor-status        # or: ./scripts/monitoring/start.sh status

# Stop
just monitor-stop          # or: ./scripts/monitoring/start.sh stop

The script starts Prometheus (port 9090) and Grafana (port 3000) as Docker containers, auto-configures the Prometheus datasource, and imports the Dugite dashboard. Prometheus data is persisted in .monitoring-data/ so metrics survive restarts.

Environment variables for port customization:

Importing the Dashboard

1. Open Grafana and go to Dashboards > Import
2. Click Upload JSON file and select config/monitoring/grafana-dashboard.json
3. Select your Prometheus data source when prompted
4. Click Import

The dashboard includes an instance template variable so you can monitor multiple Dugite nodes (relays + block producer) from a single dashboard. It auto-refreshes every 30 seconds.

Provisioning

To auto-provision the dashboard, copy it into your Grafana provisioning directory:

cp config/monitoring/grafana-dashboard.json /etc/grafana/provisioning/dashboards/dugite.json

Add a dashboard provider in /etc/grafana/provisioning/dashboards/dugite.yaml:

apiVersion: 1
providers:
  - name: Dugite
    folder: Cardano
    type: file
    options:
      path: /etc/grafana/provisioning/dashboards
      foldersFromFilesStructure: false

Quick Start (macOS)

To quickly preview the dashboard locally with Homebrew:

# Install Prometheus and Grafana
brew install prometheus grafana

# Configure Prometheus to scrape Dugite
cat > /opt/homebrew/etc/prometheus.yml << 'EOF'
global:
  scrape_interval: 5s

scrape_configs:
  - job_name: dugite
    static_configs:
      - targets: ['localhost:12798']
EOF

# Provision the datasource
cat > "$(brew --prefix)/opt/grafana/share/grafana/conf/provisioning/datasources/dugite.yaml" << 'EOF'
apiVersion: 1
datasources:
  - name: Prometheus
    type: prometheus
    access: proxy
    url: http://localhost:9090
    isDefault: true
    uid: DS_PROMETHEUS
EOF

# Provision the dashboard
cat > "$(brew --prefix)/opt/grafana/share/grafana/conf/provisioning/dashboards/dugite.yaml" << 'EOF'
apiVersion: 1
providers:
  - name: Dugite
    folder: Cardano
    type: file
    options:
      path: /opt/homebrew/var/lib/grafana/dashboards
EOF

mkdir -p /opt/homebrew/var/lib/grafana/dashboards
sed 's/${DS_PROMETHEUS}/DS_PROMETHEUS/g' config/monitoring/grafana-dashboard.json \
  > /opt/homebrew/var/lib/grafana/dashboards/dugite.json

# Start services
brew services start prometheus
brew services start grafana

# Open the dashboard (default login: admin/admin)
open "http://localhost:3000/d/dugite-node/dugite-node"

To stop:

brew services stop prometheus grafana

Key Queries

Console Logging

In addition to the Prometheus endpoint, Dugite logs sync progress to the console every 5 seconds. The log output includes:

• Current slot and block number
• Epoch number
• UTxO count
• Sync percentage
• Blocks-per-second throughput

Example log line:

2026-03-12T12:34:56.789Z  INFO dugite_node::node: Syncing progress="95.42%" epoch=512 block=11283746 tip=11300000 remaining=16254 speed="312 blk/s" utxos=15234892

Log output can be directed to stdout, file, or systemd journal. See Logging for full details on output targets, file rotation, and log level configuration.

UTxO RPC (gRPC) Server

Dugite-node ships a native UTxO RPC gRPC server — the emerging standard programmable interface for UTxO chains adopted by Dolos, Demeter, and most Cardano indexers. The server is disabled by default; opt in via the Rpc config block or CLI flags below.

Quick start

# Enable on the default port (50051), bind loopback only.
dugite-node run \
    --config config/mainnet/config.json \
    --topology config/mainnet/topology.json \
    --database-path ./db-mainnet \
    --socket-path ./node.sock \
    --host-addr 0.0.0.0 --port 3001 \
    --rpc-port 50051

# Verify it's up and list registered services.
grpcurl -plaintext localhost:50051 list
# Expect: utxorpc.v1alpha.{sync,query,submit,watch}.{Sync,Query,Submit,Watch}Service
#         utxorpc.v1beta.{sync,query,submit,watch}.{Sync,Query,Submit,Watch}Service
#         grpc.reflection.v1.ServerReflection

grpcurl -plaintext localhost:50051 utxorpc.v1beta.sync.SyncService/ReadTip
# {
#   "tip": {
#     "slot": "...",
#     "hash": "...",
#     "height": "..."
#   }
# }

Services exposed

Every service ships in both v1alpha (for backwards compatibility with older clients) and v1beta (current). The spec is pinned in-tree at crates/dugite-rpc/proto/VERSION.

Configuration

JSON config block

Add an Rpc block to config/<network>/config.json:

{
  "Rpc": {
    "Enabled": true,
    "ListenAddr": "127.0.0.1",
    "Port": 50051,
    "MaxConcurrentStreams": 64,
    "StreamBufferSize": 256,
    "ReflectionEnabled": true,
    "WebEnabled": false,
    "AlphaEnabled": true,
    "Tls": {
      "CertPath": "/etc/dugite/tls/rpc.crt",
      "KeyPath": "/etc/dugite/tls/rpc.key"
    }
  }
}

All fields are optional. Defaults:

CLI flags

CLI flags override the JSON config block:

Precedence (highest first):

1. --no-rpc → server disabled.
2. --rpc-host / --rpc-port → server enabled with CLI values overriding the config block.
3. Rpc.Enabled = true in JSON → server enabled with config values.
4. Otherwise → server disabled.

Configuration editor (dugite-config)

The Rpc section is exposed read-only as a JSON Object in dugite-config so operators can see what's configured at a glance. Edit sub-fields directly in the config JSON.

TLS

For non-loopback deployments, set Tls.CertPath + Tls.KeyPath to PEM-encoded files. Both files are read at startup; missing or unreadable files fail-fast with an io::Error rather than letting the server come up unsecured.

For mTLS, mutual auth, or rotating certificates, terminate TLS at a reverse proxy (Envoy, nginx) and leave Dugite's Tls block absent.

Operations

Metrics

The RPC server emits standard Prometheus counters / histograms via the node's existing metrics endpoint:

• dugite_rpc_requests_total{service, method, status} (counter)
• dugite_rpc_request_duration_seconds{service, method} (histogram)
• dugite_rpc_active_streams{service, method} (gauge)

Logging

Service-level events log at INFO or DEBUG under the dugite_rpc::server target. Streaming RPCs log slow-consumer drops at WARN with service / method labels.

Spec-bump workflow

The UTxO RPC .proto files are vendored at crates/dugite-rpc/proto/utxorpc/ and pinned via crates/dugite-rpc/proto/VERSION. To refresh:

just bump-utxorpc-spec v0.20.0    # replace with the desired tag

The script:

1. Clones the tag from https://github.com/utxorpc/spec into a tempdir.
2. Re-copies the Cardano-only subset (cardano + sync + query + submit + watch for both v1alpha and v1beta; bitcoin and handshake intentionally omitted).
3. Rewrites VERSION with the new tag + resolved commit + today's date.
4. Builds and tests dugite-rpc so codegen breakage / golden-test drift surfaces before the resulting commit is pushed.

Bumps land as their own PRs alongside any code changes needed to track upstream protobuf shape changes. The single-source-of-truth lives in VERSION — out-of-sync bumps (e.g. files refreshed without VERSION updated, or vice versa) are caught by code review against the diff.

Limitations

• SearchUtxos with a fully-wildcard predicate (no match / combinators) is rejected with UNIMPLEMENTED: dugite refuses to materialise the entire UTxO set in a single response. Supply at least one selector (address / payment_part / delegation_part / asset / composite) so the result set is bounded.
• ReadTx walks at most the last ~43 200 slots of VolatileDB. A chain-wide tx index would extend the lookup window to immutable history; not built today.
• ReadData scans the live UTxO set's inline datums and the mempool's witness-set datums. Witness-set datums from immutable blocks are not retained — clients that need them should consult the originating tx via ReadTx.
• ReadState's AnyChainStateData.cardano is currently empty: the endpoint returns the ledger tip + epoch only. Per-query state projections (stake-pool distribution, DRep info) land on top of this stub.
• EvalTx's per-redeemer ex_units are CEK-machine consumed values, not declared. Cost-model overrides are not yet read from protocol params — the CEK falls back to per-step defaults, which is conservative (over-approximates) and therefore safe for fee-estimation use cases but may diverge slightly from cardano-node on the high end.
• WatchTx filters on tx output fields (produces / has_address / moves_asset) and minting (mints_asset) — but not on resolved inputs (consumes / has_certificate) since those require live UTxO lookups against pending mempool txs.
• FollowTip apply events carry AnyChainBlock.native_bytes (the raw block CBOR); clients that only need tip metadata can ignore the payload.

See also

• UTxO RPC spec
• crates/dugite-rpc/proto/VERSION — the pinned spec tag.
• crates/dugite-rpc/tests/ — golden + integration tests covering each service.

Relay Node

A relay node is the public-facing component of a stake pool deployment. It bridges your block producer to the wider Cardano network while shielding the BP from direct internet exposure.

Role in Stake Pool Architecture

In a properly secured stake pool, the block producer never communicates directly with the public network. Instead, one or more relay nodes handle all external connectivity:

graph LR
    Internet["Cardano Network"] <-->|N2N| Relay1["Relay 1<br/>Public IP"]
    Internet <-->|N2N| Relay2["Relay 2<br/>Public IP"]
    Relay1 <-->|Private| BP["Block Producer<br/>Private IP"]
    Relay2 <-->|Private| BP

• Relays accept inbound connections from any Cardano peer, discover peers via bootstrap/ledger, and forward blocks to/from the BP.
• Block producer connects only to your relays, never to the public internet.

Running a Relay

A relay is simply a Dugite node started without block production keys:

dugite-node run \
  --config config.json \
  --topology topology-relay.json \
  --database-path ./db \
  --socket-path ./node.sock \
  --host-addr 0.0.0.0 \
  --port 3001

Tip: For initial sync, use Mithril snapshot import first to skip millions of blocks.

Relay Topology

A relay topology combines public peer discovery with a local root pointing to your block producer.

Preview Testnet Relay

{
  "bootstrapPeers": [
    { "address": "preview-node.play.dev.cardano.org", "port": 3001 }
  ],
  "localRoots": [
    {
      "accessPoints": [
        { "address": "10.0.0.10", "port": 3001 }
      ],
      "advertise": false,
      "hotValency": 1,
      "warmValency": 2,
      "trustable": true,
      "behindFirewall": true
    }
  ],
  "publicRoots": [
    { "accessPoints": [], "advertise": false }
  ],
  "useLedgerAfterSlot": 102729600
}

Mainnet Relay

{
  "bootstrapPeers": [
    { "address": "backbone.cardano.iog.io", "port": 3001 },
    { "address": "backbone.mainnet.cardanofoundation.org", "port": 3001 },
    { "address": "backbone.mainnet.emurgornd.com", "port": 3001 }
  ],
  "localRoots": [
    {
      "accessPoints": [
        { "address": "10.0.0.10", "port": 3001 }
      ],
      "advertise": false,
      "hotValency": 1,
      "warmValency": 2,
      "trustable": true,
      "behindFirewall": true
    }
  ],
  "publicRoots": [
    { "accessPoints": [], "advertise": false }
  ],
  "useLedgerAfterSlot": 177724800
}

Key topology settings for relays:

• bootstrapPeers — Trusted initial peers for syncing from genesis or after restart.
• localRoots with behindFirewall: true — Your block producer. The relay waits for inbound connections from the BP rather than connecting outbound, which works correctly when the BP is behind a firewall.
• useLedgerAfterSlot — Enables ledger-based peer discovery once synced past this slot, providing decentralized peer resolution from on-chain stake pool registrations.
• advertise: false — Set to true if you want your relay to be discoverable via peer sharing.

Multiple Relays

Running two or more relays provides redundancy. If one relay goes down, the block producer stays connected through the other.

To run multiple relays on the same machine, use different ports, database paths, and socket paths:

# Relay 1 on port 3001
dugite-node run \
  --config config.json \
  --topology topology-relay1.json \
  --database-path ./db-relay1 \
  --socket-path ./relay1.sock \
  --host-addr 0.0.0.0 \
  --port 3001

# Relay 2 on port 3002
dugite-node run \
  --config config.json \
  --topology topology-relay2.json \
  --database-path ./db-relay2 \
  --socket-path ./relay2.sock \
  --host-addr 0.0.0.0 \
  --port 3002

Each relay's topology should include the block producer as a local root. The block producer's topology should list all relays (see Block Producer Topology).

For production deployments, run relays on separate machines or in different availability zones for better fault tolerance.

Firewall Configuration

Relay nodes need port 3001 (or your chosen port) open to the public for Cardano N2N traffic. The block producer should only be reachable from your relays.

Relay firewall rules

# Allow inbound Cardano N2N from anywhere
sudo ufw allow 3001/tcp

# Allow SSH (adjust as needed)
sudo ufw allow 22/tcp

sudo ufw enable

Block producer firewall rules

# Allow inbound only from relay IPs
sudo ufw allow from <relay1-ip> to any port 3001
sudo ufw allow from <relay2-ip> to any port 3001

# Allow SSH (adjust as needed)
sudo ufw allow 22/tcp

# Deny everything else
sudo ufw default deny incoming
sudo ufw enable

Important: The block producer should have no public-facing ports. All Cardano traffic flows exclusively through your relays.

Monitoring

Dugite exposes Prometheus metrics on port 12798 by default. Key metrics to watch on a relay:

curl -s http://localhost:12798/metrics | grep -E "peers_connected|sync_progress"

See Monitoring for the full list of available metrics and Grafana dashboard setup.

Next Steps

• Block Producer — Set up key generation, operational certificates, and block production
• Topology — Full topology format reference
• Monitoring — Prometheus metrics and alerting

Block Producer

Dugite can operate as a block-producing node (stake pool). This requires KES keys, VRF keys, and an operational certificate.

Architecture

A block producer is never directly exposed to the public internet. Instead, it sits behind one or more relay nodes that handle all external network connectivity. The relays forward blocks and transactions to the BP over a private network, and the BP announces forged blocks back through the relays.

Status (2026-05-09): Dugite block forging is operational and on-chain verified. Block 4265661 at slot 111661041 was forged by Dugite, accepted by the network, and confirmed on the canonical chain (Conway era, 1 tx, built upon by a subsequent block). Ongoing soak testing continues on the preview testnet via Sandstone Pool ([SAND], pool ID 6954ec11cf7097a693721104139b96c54e7f3e2a8f9e7577630f7856).

See the Complete Deployment section at the bottom of this page for the full architecture diagram and setup checklist.

Overview

A block producer is a node that has been registered as a stake pool and is capable of minting new blocks when it is elected as a slot leader. The block production pipeline involves:

1. Slot leader check — Each slot, the node uses its VRF key and the epoch nonce to determine if it is elected to produce a block.
2. Block forging — If elected, the node assembles a block from pending mempool transactions, signs it with the KES key, and includes the VRF proof.
3. Block announcement — The forged block is propagated to connected peers via the N2N protocol.

Required Keys

Cold Keys (Offline)

Cold keys identify the stake pool and should be kept offline (air-gapped) after initial setup.

Generate cold keys using the CLI:

dugite-cli node key-gen \
  --cold-verification-key-file cold.vkey \
  --cold-signing-key-file cold.skey \
  --operational-certificate-counter-file opcert.counter

KES Keys (Hot)

KES (Key Evolving Signature) keys are rotated periodically. Each KES key is valid for a limited number of KES periods (typically 62 periods of 129600 slots each on mainnet, approximately 90 days total).

Generate KES keys:

dugite-cli node key-gen-kes \
  --verification-key-file kes.vkey \
  --signing-key-file kes.skey

VRF Keys

VRF (Verifiable Random Function) keys are used for slot leader election. They are generated once and do not need rotation.

Generate VRF keys:

dugite-cli node key-gen-vrf \
  --verification-key-file vrf.vkey \
  --signing-key-file vrf.skey

Operational Certificate

The operational certificate binds the cold key to the current KES key. It must be regenerated each time the KES key is rotated.

Issue an operational certificate:

dugite-cli node issue-op-cert \
  --kes-verification-key-file kes.vkey \
  --cold-signing-key-file cold.skey \
  --operational-certificate-counter-file opcert.counter \
  --kes-period <current-kes-period> \
  --out-file opcert.cert

The --kes-period should be set to the current KES period at the time of issuance. You can calculate the current KES period as:

current_kes_period = current_slot / slots_per_kes_period

On mainnet, slots_per_kes_period is 129600.

Running as Block Producer

Pass the key and certificate paths when starting the node:

dugite-node run \
  --config config.json \
  --topology topology.json \
  --database-path ./db \
  --socket-path ./node.sock \
  --host-addr 0.0.0.0 \
  --port 3001 \
  --shelley-kes-key kes.skey \
  --shelley-vrf-key vrf.skey \
  --shelley-operational-certificate opcert.cert

When all three arguments are provided, the node enters block production mode. Without them, it operates as a relay-only node.

Block Producer Topology

A block producer should not be directly exposed to the public internet. Instead, it should connect only to your relay nodes:

{
  "bootstrapPeers": null,
  "localRoots": [
    {
      "accessPoints": [
        { "address": "relay1.example.com", "port": 3001 },
        { "address": "relay2.example.com", "port": 3001 }
      ],
      "advertise": false,
      "hotValency": 2,
      "warmValency": 3,
      "trustable": true
    }
  ],
  "publicRoots": [{ "accessPoints": [], "advertise": false }],
  "useLedgerAfterSlot": -1
}

Key points:

• No bootstrap peers — The block producer syncs exclusively through your relays.
• No public roots — No connections to unknown peers.
• Ledger peers disabled — useLedgerAfterSlot: -1 disables ledger-based peer discovery.
• Only local roots — All connections are to your own relay nodes.

Leader Schedule

You can compute your pool's leader schedule for an epoch:

dugite-cli query leadership-schedule \
  --vrf-signing-key-file vrf.skey \
  --epoch-nonce <64-char-hex> \
  --epoch-start-slot <slot> \
  --epoch-length 432000 \
  --relative-stake 0.001 \
  --active-slot-coeff 0.05

This outputs all slots where your pool is elected to produce a block in the given epoch.

KES Key Rotation

KES keys must be rotated before they expire. The rotation process:

1. Generate new KES keys:

   dugite-cli node key-gen-kes \
     --verification-key-file kes-new.vkey \
     --signing-key-file kes-new.skey
   

2. Issue a new operational certificate with the new KES key (on the air-gapped machine):

   dugite-cli node issue-op-cert \
     --kes-verification-key-file kes-new.vkey \
     --cold-signing-key-file cold.skey \
     --operational-certificate-counter-file opcert.counter \
     --kes-period <current-kes-period> \
     --out-file opcert-new.cert
   

3. Replace the KES key and certificate on the block producer and restart:

   cp kes-new.skey kes.skey
   cp opcert-new.cert opcert.cert
   # Restart the node
   

Important: Always rotate KES keys before they expire. If a KES key expires, your pool will stop producing blocks until a new key is issued.

Security Recommendations

• Keep cold keys on an air-gapped machine. They are only needed to issue new operational certificates.
• Restrict access to the block producer machine. Only your relay nodes should be able to connect.
• Monitor your pool's block production. Use the Prometheus metrics endpoint to track dugite_blocks_applied_total.
• Set up KES key rotation reminders well before expiry (2 weeks in advance is a good practice).
• Use firewalls to ensure the block producer is not reachable from the public internet.

Snapshot Recovery & Block Forging Readiness

When a block producer starts up, several subsystems must be initialized before it can begin forging blocks. The path to readiness depends on how the node was bootstrapped.

Epoch Nonce

The epoch nonce is critical for VRF leader election. It is serialized in the ledger snapshot alongside the consensus state (epoch_nonce, evolving_nonce, candidate_nonce, last_epoch_block_nonce), so it is immediately authoritative after a snapshot load or Mithril import — matching the Haskell cardano-node's treatment of praosStateEpochNonce. Forging is enabled as soon as the node catches up to the chain tip and its pool has non-zero stake in the "set" snapshot; no additional epoch boundary is required.

Pool Stake Reconstruction

On startup, after loading a ledger snapshot, the node rebuilds the stake distribution from the UTxO store to ensure consistency:

1. rebuild_stake_distribution() recomputes per-pool stake totals from the current UTxO set and delegation map.
2. recompute_snapshot_pool_stakes() updates the mark/set/go snapshots so that the "set" snapshot (used for leader election) reflects the rebuilt distribution.

This runs automatically when the UTxO store is non-empty. After completion, the node logs the pool's stake in the "set" snapshot:

Block producer: pool stake in 'set' snapshot (used for leader election)
  pool_id=<hash>, pool_stake_lovelace=<n>, total_active_stake_lovelace=<n>, relative_stake=<f>

If your pool shows zero stake after startup, verify:

• The pool registration certificate transaction is confirmed on-chain.
• At least one stake address is delegated to the pool and that delegation is confirmed.
• The UTxO store was properly attached (the node logs Rebuilding stake distribution from UTxO store on startup).
• The "set" snapshot epoch is recent enough to include your pool's registration and delegation.

Epoch Numbering

Each network has its own epoch length defined in the Shelley genesis configuration:

When a ledger snapshot is loaded, the node recalculates the current epoch from the tip slot using the genesis parameters. If the snapshot was saved with incorrect epoch parameters (for example, using mainnet's default 432,000 instead of preview's 86,400), the epoch number baked into the snapshot will be wrong. The node detects this automatically and corrects it:

Snapshot epoch differs from computed epoch — correcting
  snapshot_epoch=<wrong>, correct_epoch=<right>, tip_slot=<slot>

Without this correction, apply_block would attempt to process hundreds of spurious epoch transitions, and the stake snapshots would land at wrong epochs, causing pool_stake=0 for block producers.

Fork Recovery

When a block producer forges a block but another pool wins the slot battle (their block is adopted by the network instead), the forged block becomes orphaned. Dugite detects this situation during chain synchronization and recovers automatically.

How Fork Detection Works

During ChainSync, the node presents historical chain points (up to 10 ancestors, walked backwards through the volatile DB) to the upstream peer. If the local tip is an orphaned forged block that the peer does not recognize, the ancestor blocks provide fallback intersection points.

Recovery Cases

Case A: Full Reset. The intersection falls back to Origin despite having a non-trivial ledger tip. This means no peer recognizes any of the node's chain points. The node:

1. Clears the volatile DB.
2. Rolls back the ledger state to Origin.
3. Disables strict VRF verification (so replay can proceed without rejecting blocks due to stale nonce).
4. Reconnects and replays from the ImmutableDB.

Case B: Targeted ImmutableDB Replay. The intersection is behind the ledger tip but not at Origin. The node:

1. Clears the volatile DB.
2. Detaches the LSM UTxO store (switches to fast in-memory replay).
3. Replays the ImmutableDB from genesis up to the intersection slot.
4. Reattaches the UTxO store and resumes syncing from the canonical chain.

In both cases, orphaned forged blocks are not propagated to downstream peers. The node resumes normal operation on the canonical chain after recovery completes.

Troubleshooting Block Producer Issues

"Block producer has ZERO stake"

Block producer has ZERO stake in 'set' snapshot — will not be elected slot leader.

This warning appears at startup when the "set" snapshot contains no stake for your pool. Possible causes:

• Pool not registered: Submit a pool registration certificate transaction and wait for it to be confirmed.
• No delegations: At least one stake address must delegate to the pool. Submit a delegation certificate and wait for confirmation.
• Snapshot too old: The "set" snapshot reflects stake from two epoch boundaries ago. A newly registered pool must wait 2 epoch transitions before appearing in the "set" snapshot.
• UTxO store not attached: If the node started without a UTxO store, stake reconstruction is skipped. Check for the Rebuilding stake distribution from UTxO store log message.

"VRF leader eligibility check failed"

VRF leader check failures during the first few epochs after a full replay are non-fatal and expected. The mark/set/go snapshot rotation means the "set" snapshot needs up to 3 epoch transitions to stabilize with correct stake distributions derived from the replayed state. During this window:

• The node may compute incorrect leader eligibility for some slots.
• Your pool may miss some leader slots — this is temporary and self-correcting.

Pool Registered but No Forge Attempts

If your pool is registered on-chain but the node never logs any forge attempts:

1. Check the "set" snapshot log: Look for the startup message Block producer: pool stake in 'set' snapshot. Verify that pool_stake_lovelace is greater than zero.
2. Check the "set" snapshot availability: If you see Block producer: no 'set' snapshot available — leader election disabled until epoch transition, the node has not yet completed enough epoch transitions. Wait for at least 2 epoch boundaries.
3. Verify key files: Ensure --shelley-kes-key, --shelley-vrf-key, and --shelley-operational-certificate are all provided and point to valid files. Without all three, the node runs in relay-only mode.
4. Check KES period: If the KES key has expired (current KES period exceeds the operational certificate's start period plus maxKESEvolutions), rotate the KES key and issue a new operational certificate.

macOS App Nap (macOS only)

macOS can suspend background processes via "App Nap" to save power. A suspended node misses every leader slot during the freeze window. Wrap the node in caffeinate to prevent this:

caffeinate -dimsu dugite-node run \
  --config config.json \
  --topology topology.json \
  --database-path ./db \
  --socket-path ./node.sock \
  --shelley-kes-key kes.skey \
  --shelley-vrf-key vrf.skey \
  --shelley-operational-certificate opcert.cert

The -dimsu flags prevent disk-idle, display, idle, system, and user-idle sleep from suspending the process. Required for reliable block production on macOS development machines.

Complete Deployment

A full stake pool deployment consists of one block producer and one or more relay nodes working together:

graph TB
    subgraph Public Network
        Peers["Cardano Peers"]
    end

    subgraph Your Infrastructure
        subgraph Relay Tier
            R1["Relay 1<br/>Port 3001<br/>Public IP"]
            R2["Relay 2<br/>Port 3001<br/>Public IP"]
        end

        subgraph Private Network
            BP["Block Producer<br/>Port 3001<br/>Private IP<br/>KES + VRF + OpCert"]
        end
    end

    Peers <-->|N2N| R1
    Peers <-->|N2N| R2
    R1 <-->|Private| BP
    R2 <-->|Private| BP

Deployment Checklist

1. Set up relay nodes (Relay Node guide)

   • Install Dugite on relay machines
   • Import Mithril snapshot for fast initial sync
   • Configure relay topology with bootstrap peers and BP as local root
   • Open port 3001 to the public
   • Start relay nodes and verify they sync to tip

2. Set up the block producer (this page)

   • Install Dugite on the BP machine
   • Import Mithril snapshot
   • Generate cold keys, VRF keys, and KES keys
   • Issue an operational certificate
   • Configure BP topology with relays as local roots (no public peers)
   • Restrict firewall to relay IPs only
   • Start the BP node with --shelley-kes-key, --shelley-vrf-key, --shelley-operational-certificate

3. Register the stake pool on-chain (requires a transaction with pool registration certificate)

4. Verify block production

   • Confirm sync progress is 100% on all nodes
   • Check dugite_peers_connected metrics on relays and BP
   • Monitor dugite_blocks_forged_total metric on the BP after epoch transition
   • Set up monitoring and KES rotation reminders

Local Testnet

A 3-node loopback testnet for verifying dugite block production and diffusion against the Haskell reference implementation. One dugite block producer, one dugite relay, and one cardano-node validator (relay role), all on the same machine, all on the loopback interface — the cardano-node connects through the dugite relay.

What this is

graph LR
  dbp[dugite-bp<br/>N2N 3001<br/>metrics 12798<br/>pool1 — sole forger] <--> dr[dugite-relay<br/>N2N 3002<br/>metrics 12799<br/>hub]
  dr <--> cbp[cardano-node<br/>N2N 3003<br/>validator only]

dugite-bp is the sole block producer. cardano-node runs as a passive validator (no forging keys passed) and chainsync+blockfetches every block forged by dugite-bp, applying each one through the Haskell ledger. This gives us byte-exact cross-validation of dugite's forged blocks against the reference implementation with zero risk of asymmetric forks (no two forgers competing for the same height).

The chain boots into Conway PV10 from a fresh genesis with a single forging pool (pool1, 100% of active stake; pool2's keys exist but its stake is 0), 1-second slots, activeSlotsCoeff = 0.2, epochLength = 200, and securityParam = 10. Blocks are minted every ~5 seconds on average and an epoch elapses every ~3.3 minutes, so the 30-minute soak crosses ~9 epoch boundaries (enough for reward distribution to complete before the soak ends).

Historical note: prior to 2026-05-18, cardano-node also ran as a forger (pool2, equal stake) for symmetric multi-forger cross-validation. That topology produced an asymmetric-fork class that no per-tx test could survive: the slower side's leader-slot timer fired before propagation completed and each pool ended up on its own short chain permanently (first-seen tiebreaker, equal lengths). Making cardano-node a validator eliminates that class entirely while preserving the cross-validation we actually rely on (does cardano-node accept every dugite block byte-for-byte?).

Prerequisites

• cardano-node >= 11.0.1 and cardano-cli >= 11.0.0 on $PATH
• target/release/dugite-node built (cargo build --release from the repo root)
• jq for JSON manipulation
• ~2 GB of free disk for the soak
• macOS: the system-builtin caffeinate (used to suppress App Nap during the soak). This dependency is macOS-only; on Linux the soak runs unwrapped.

The setup script's prereq check will refuse to run if any of these are missing.

One-time setup

./testnet/local-devnet/setup.sh

This generates a fresh genesis (4 files: byron, shelley, alonzo, conway), key sets for two stake pools, four stake delegators, three genesis keys, and one UTxO funding key. All output lands under testnet/local-devnet/genesis/, testnet/local-devnet/keys/, and testnet/local-devnet/config/ (rendered configs). Generated keys and genesis files are gitignored.

Expected output ends with:

[INFO]  All configs + topologies rendered to testnet/local-devnet/config/
[INFO]  Setup complete. Next: ./run.sh

The genesis start time is set to "now + 30 seconds." Re-run setup.sh if more than ~5 minutes pass before you call run.sh (the start-time freshness check will refuse to start a stale chain).

Running the network

./testnet/local-devnet/run.sh

This starts the three nodes in the background (caffeinate-wrapped on macOS), records PIDs to state/<node>.pid, sends logs to logs/<node>.log, and exposes N2C sockets at:

• testnet/local-devnet/state/dugite-relay.sock
• testnet/local-devnet/state/dugite-bp.sock
• testnet/local-devnet/state/cardano-bp.sock

You can query each socket with cardano-cli (or dugite-cli, which speaks the same N2C protocol):

cardano-cli query tip \
  --testnet-magic 42 \
  --socket-path testnet/local-devnet/state/dugite-bp.sock

To stop the network:

./testnet/local-devnet/stop.sh

This sends SIGTERM, waits 5 seconds, then SIGKILL if needed. DBs and logs are preserved in state/ and logs/.

Running the soak test

./testnet/local-devnet/soak.sh         # default: 1800s (30 minutes)
./testnet/local-devnet/soak.sh 300     # 5-minute smoke test

The soak runs three concurrent samplers while it's alive:

• tip-sampler — every 5 seconds, queries tip on each socket and appends (ts, node, slot, block_no, hash, era) rows to tip-samples.csv.
• block-recorder — tails the three node logs and writes one row per first- sight of each block, with observer, forge/recv flag, slot, hash, and (for forge events) the issuer's vkey.
• tx-injector — at T+2 min, T+10 min, and T+20 min, submits 5 self-transfer payment transactions to each of the 3 sockets (15 per wave, 45 total) and records each submission's txid and return code.

Evidence lands in testnet/local-devnet/evidence/<timestamp>/. A heartbeat line is printed every 30 seconds with current tips from all three nodes.

Verifying results

After the soak finishes, soak.sh does not automatically run verify — run it manually:

./testnet/local-devnet/verify.sh testnet/local-devnet/evidence/<timestamp>/

The verifier evaluates four pass/fail predicates and writes evidence/<timestamp>/report.md. Predicates:

The report.md includes a metadata snapshot (versions, genesis hashes, magic), counts (block events, tx submissions, tip samples), a forge-attribution breakdown, and a per-predicate result table.

You can also self-test the verifier (without a real soak) using committed test fixtures:

./testnet/local-devnet/verify.sh --self-test

Topology & port reference

The devnet uses the standard Cardano N2N port (3001) for dugite-bp and single-digit increments for the relay (3002) and the Haskell BP (3003). The metrics ports follow the same convention: dugite-bp keeps the well-known Prometheus default (12798), the relay exposes 12799. If a public-network soak is running on the same host it must be stopped before the devnet boots, since both processes would otherwise bind 3001/12798.

Monitoring with dugite-monitor

Because dugite-bp runs on the default metrics port (12798), the bundled TUI monitor connects with no overrides. In a separate terminal once the devnet is up:

./target/release/dugite-monitor

To inspect the relay instead of the BP, point the monitor at its metrics port:

./target/release/dugite-monitor --metrics-url http://localhost:12799/metrics

The cardano-node validator does not expose a Prometheus endpoint in this devnet (its EKG/Prometheus exporters are disabled to keep the configuration minimal and avoid port collisions).

Configuration reference

The genesis is generated by cardano-cli conway genesis create-testnet-data with two override fragments committed under config/spec/. Only fields that differ from cardano-cli's defaults are listed below.

config/spec/shelley-spec.json:

config/spec/conway-spec.json carries Conway governance parameters; for a 30-min run with no proposals only the protocol version matters. PV is set to 10.0 so the chain boots straight into Conway.

Troubleshooting

• ERROR: cardano-cli x.y.z < 11.0.0 required — install a newer cardano-cli; see prerequisites.
• ERROR: Port 3001 is in use — another devnet (or the public soak rig) is using a port. Run ./stop.sh or lsof -iTCP:3001.
• Genesis is N seconds old (>300s). Re-run ./setup.sh — the start time has drifted; re-run setup.
• Tips not advancing after run.sh — check logs/<node>.log for the failing node. Most common cause is a KES key path mismatch (re-run setup.sh).
• Soak hangs on macOS — confirm caffeinate is wrapping the dugite processes via ps auxw | grep caffeinate. App Nap can freeze dugite for tens of minutes without it.
• dugite-monitor shows no data — confirm the BP is exposing metrics on 12798 with curl -s localhost:12798/metrics | head. If empty, the BP either failed to start or its config doesn't have the Prometheus exporter enabled (the devnet template enables it by default).

What this validates

• Dugite block production end-to-end (forge -> adopt -> diffuse)
• Dugite relay's ChainSync/BlockFetch serving (Rust -> Haskell validator)
• Dugite N2N peer connection lifecycle on loopback
• Dugite N2C local-socket tx submission, query tip, query utxo
• Byte-exact acceptance of every dugite-forged block by cardano-node 11.0.1+ (the Haskell ledger applies each block; any header / body / Conway predicate mismatch surfaces as a ChainDB.AddBlockValidation.InvalidBlock trace in logs/cardano-bp.log)

What this does NOT validate

• Byron-era code paths (chain boots in Conway)
• Hard-fork combinator era transitions (none occur during the soak)
• Multi-relay diffusion topologies (single hub)
• Plutus phase-2 / governance enactment (no proposals or scripts in the soak; the tx-zoo covers governance under a separate driver)
• Symmetric multi-forger chain selection (cardano-node is a validator here, not a forger — see "Historical note" at top)
• Mainnet-scale peer counts, NAT/firewall behaviour, or BGP-level routing
• Mithril snapshot import (covered by other tests)

Transaction validation (tx-zoo)

In addition to the soak (which exercises block production + diffusion under a steady-state load of identical self-payments), the devnet ships with a transaction zoo that exercises the full Conway tx surface against the same 3-node hub. Use this when you want to verify that the dugite mempool, forger, and validator accept every transaction class that mainnet allows.

./testnet/local-devnet/tx-zoo/run-all.sh --setup    # one-time: keys + Plutus binaries
./testnet/local-devnet/tx-zoo/run-all.sh            # run everything
./testnet/local-devnet/tx-zoo/run-all.sh 03-plutus  # one category
./testnet/local-devnet/tx-zoo/run-all.sh --summary  # totals from the last run

The zoo covers 8 categories (59 scripts total): bookkeeping (simple-pay, multi-output, metadata CIP-20/CIP-25, validity intervals, required signers, treasury donation, tx chaining), native scripts (all/any/atLeast policies, time-locked, burns, pay-to-script, spend-from-script), Plutus V1/V2/V3 (spend, mint, inline datums, reference scripts, reference inputs, datum-hash reveal, collateral consumption), stake operations (register, delegate, combined certs, deregister, pool register/retire, reward withdrawal), governance certificates (DRep register/update/deregister, vote-delegation to DRep + always-abstain + always-no-confidence, CC hot-key authorisation, CC resignation), proposals (Info, ParameterChange, HardForkInitiation, TreasuryWithdrawal, NoConfidence, UpdateCommittee, NewConstitution), voting (DRep + SPO + CC yes/no/abstain), and negative paths (min-utxo violation, fee-too-low, expired TTL, insufficient collateral). Each script submits through the dugite relay socket and waits for inclusion at that same socket to guarantee diffusion + validation on the dugite path before recording PASS/FAIL/SKIP into tx-zoo/state/results.csv.

Requirements

• The devnet must be up via ./run.sh (the zoo refuses to start without all 3 sockets).
• The Conway genesis must boot at protocol version >= 10 so Plutus V1/V2/V3 and Conway-only certs are admissible. The committed shelley-spec.json already sets protocolVersion.major = 10; if you fork the spec to a lower version every script that touches Plutus or governance will record FAIL with "ScriptFailed: requires protocol >= N" from cardano-cli or the dugite mempool.
• The zoo uses vendored always-true Plutus binaries for V1/V2/V3 scripts. Three categories (collateral, ref-scripts, inline-datum) run with these vendored versions; only the negative-path "insufficient collateral" needs a real V2 always-true script (also vendored).

Caveats

• not-included failures: the zoo uses a single shared funding wallet (the genesis UTxO key) and runs scripts in lexical order. Each test consumes the largest UTxO at that wallet, so concurrent runs against the same socket will race. If you see intermittent not-included in results.csv for a tx that was added to the mempool, check that no other client is submitting to the same socket — the zoo expects exclusive access.
• Rewards warmup: reward-withdrawal cannot succeed until the delegated stake earns rewards, which requires at least two epoch boundaries after delegation. On the 200-slot epoch this means the script SKIPs for the first ~7 minutes after a fresh devnet boot. The script records SKIP with reason no-rewards rather than failing.

Seated CC member

cardano-cli conway genesis create-testnet-data emits an empty Constitutional Committee (members={}, threshold=0), which would make the CC hot-key auth, CC resignation, and CC voting scripts non-runnable. To provide full governance coverage out of the box, setup.sh generates a CC cold/hot key pair at keys/cc-1/ and post-processes the generated conway-genesis.json to seat that member with a 1-of-1 threshold and a long expiry term (epoch 1000). tx-zoo/lib/keygen.sh then reuses those same keys, so 05g-cc-hot-key-authorization, 05h-cc-resign, 07f-cc-vote-yes, and 07g-cc-vote-no operate on a genuine seated member rather than an orphan keypair.

If you fork setup.sh or generate genesis through any other path, ensure the resulting conway-genesis.json has a non-empty committee.members map and a threshold matching that membership; otherwise those four scripts will auto-SKIP with reason empty-committee / cc-not-authorized.

Results are appended to tx-zoo/state/results.csv (one row per script with ts, name, status, txid, detail) and the per-script stderr lives under tx-zoo/state/logs/<name>.log. After a failed run, re-run a single category or script directly:

./testnet/local-devnet/tx-zoo/03-plutus/03a-spend-v1.sh

Tracking: see the GitHub issue linked from docs/superpowers/specs/2026-05-16-local-testnet-design.md.

Kubernetes Deployment

Dugite ships a Helm chart at charts/dugite-node/ for deploying to Kubernetes as either a relay node or a block producer. Container images are published on every tagged release as multi-arch (linux/amd64, linux/arm64) images at ghcr.io/michaeljfazio/dugite.

Prerequisites

• Kubernetes 1.27+
• Helm 3.12+ (chart was tested against Helm 4.x)
• A StorageClass that supports ReadWriteOnce persistent volumes
• (Optional) Prometheus Operator for ServiceMonitor scraping

Quick Start

The chart is published as an OCI artifact on every tagged release. Install directly from the registry:

helm install dugite-relay \
  oci://ghcr.io/michaeljfazio/charts/dugite-node \
  --version 0.4.0 \
  --set network.name=preview

Or install from a local checkout:

helm install dugite-relay ./charts/dugite-node \
  --set network.name=preview

This will:

1. Run a Mithril snapshot import (init container) with the Haskell ancillary state — bootstrap time drops from a multi-hour replay to ~15 minutes.
2. Start the node syncing with the preview testnet.
3. Create a 100 GiB persistent volume for the chain database.
4. Expose Prometheus metrics on port 12796.

Chart Reference

Node role

The chart supports two deployment modes:

# Relay node (default)
role: relay

# Block producer
role: producer

Network selection

network:
  name: preview              # mainnet, preview, or preprod
  port: 3001                 # N2N port
  hostAddr: "0.0.0.0"
  diffusionMode: InitiatorAndResponder  # use InitiatorOnly for BPs behind NAT
  peerSharing: null          # null = auto (on for relay, off for BP); set true/false to override

network.magic is derived automatically from network.name. Override only for private networks.

Persistence

persistence:
  enabled: true
  storageClass: ""           # blank = cluster default; "-" = no storageClassName
  size: 100Gi                # preview ~16 GiB, preprod ~50 GiB, mainnet 150+ GiB
  accessMode: ReadWriteOnce
  existingClaim: ""          # use an existing PVC

For mainnet, 200 GiB is a safe minimum once Conway-era state and the LSM UTxO backend are accounted for.

Resources

resources:
  requests:
    cpu: "1"
    memory: 3Gi
  limits:
    cpu: "4"
    memory: 16Gi

Soak-test RSS on preview is ~2.6 GiB; mainnet steady state is 8–10 GiB. Raise requests.memory to 4–6 GiB and limits.memory to 24–32 GiB for mainnet bulk sync.

Mithril import

mithril:
  enabled: true              # run Mithril import on first start (idempotent)
  includeAncillary: true     # download Haskell ledger state — drops bootstrap to ~15 min

Set mithril.includeAncillary: false to fall back to chunk-by-chunk replay. Trust model is documented in Mithril Ancillary.

Storage profile

storageProfile: high-memory  # ultra-memory | high-memory (default) | low-memory | minimal

Match this to resources.limits.memory: high-memory ≈ 16 GiB, low-memory ≈ 8 GiB, minimal ≈ 4 GiB.

Metrics and monitoring

metrics:
  enabled: true
  port: 12796                # 12796 keeps dugite from colliding with cardano-node (12798)
  compat: false              # emit cardano_node_metrics_* aliases for legacy dashboards
  require: false             # treat metrics bind failure as fatal startup error
  serviceMonitor:
    enabled: false           # set true if running Prometheus Operator
    interval: 30s
    labels: {}

When serviceMonitor.enabled is true the chart creates a ServiceMonitor resource for automatic Prometheus scraping. Enable compat: true to keep existing cardano-node Grafana dashboards working unmodified.

Available metrics include sync_progress_percent, blocks_applied_total, utxo_count, epoch_number, peers_connected, and more. See Monitoring for the full list.

UTxO RPC (gRPC) server — #672

rpc:
  enabled: false             # set true to enable the v1beta UTxO RPC API
  port: 50051
  host: "127.0.0.1"          # set to 0.0.0.0 to expose via Service
  service: false             # expose RPC on the cluster Service (requires host: 0.0.0.0)

When rpc.enabled is true the deployment adds an rpc container port and the node starts the gRPC server. Setting rpc.service: true adds an rpc port to the Service and a NetworkPolicy rule (for the producer NetworkPolicy) allowing cross-pod gRPC access.

Consensus mode (genesis sync) — #535

consensusMode: ""            # "" = praos (default); set "genesis" to opt in to Genesis sync

Currently the JSON config field ConsensusMode is not wired through to the runtime gate, so the chart passes the value via --consensus-mode on the CLI when set.

Logging

logging:
  minSeverity: Info          # Debug | Info | Notice | Warning | Error | Critical
  rustLog: "info"            # tracing_subscriber EnvFilter directive
  format: text               # text (human-readable) or json (structured for log shippers)
  noColor: true              # disable ANSI colors in container stdout

Liveness threshold

livenessThresholdSecs: 600   # /live returns 503 if no block applied in this window

This is passed via --liveness-threshold-secs. Set to 0 to make /live always return 200 (probes still pass even if the node has stalled).

Topology

topology:
  bootstrapPeers:
    - address: preview-node.play.dev.cardano.org
      port: 3001
  localRoots: []
  publicRoots:
    - accessPoints:
        - address: preview-node.play.dev.cardano.org
          port: 3001
      advertise: false
  useLedgerAfterSlot: 102729600   # mainnet=0, preview=102729600, preprod=76723200

Relay Node Deployment

A relay node connects to the Cardano network, syncs blocks, and serves them to connected peers and local clients.

Minimal relay

helm install dugite-relay ./charts/dugite-node \
  --set network.name=mainnet \
  --set persistence.size=200Gi

Relay with custom topology

helm install dugite-relay ./charts/dugite-node \
  --set network.name=mainnet \
  --set persistence.size=200Gi \
  -f relay-values.yaml

relay-values.yaml:

topology:
  bootstrapPeers:
    - address: backbone.cardano.iog.io
      port: 3001
    - address: backbone.mainnet.cardanofoundation.org
      port: 3001
    - address: backbone.mainnet.emurgornd.com
      port: 3001
  localRoots:
    - accessPoints:
        - address: dugite-producer-dugite-node.default.svc.cluster.local
          port: 3001
      advertise: false
      trustable: true
      valency: 1
  publicRoots:
    - accessPoints:
        - address: backbone.cardano.iog.io
          port: 3001
        - address: backbone.mainnet.cardanofoundation.org
          port: 3001
      advertise: false
  useLedgerAfterSlot: 0

Relay with Prometheus Operator

helm install dugite-relay ./charts/dugite-node \
  --set network.name=mainnet \
  --set metrics.serviceMonitor.enabled=true \
  --set metrics.serviceMonitor.labels.release=prometheus

Enable metrics.compat=true if your dashboards still reference cardano_node_metrics_* series.

Block Producer Deployment

A block producer creates blocks when elected as slot leader. It requires KES, VRF, and operational certificate keys.

Create keys Secret

kubectl create secret generic dugite-producer-keys \
  --from-file=kes.skey=kes.skey \
  --from-file=vrf.skey=vrf.skey \
  --from-file=node.cert=node.cert

Deploy the producer

helm install dugite-producer ./charts/dugite-node \
  --set role=producer \
  --set network.name=mainnet \
  --set producer.existingSecret=dugite-producer-keys \
  --set persistence.size=200Gi \
  --set network.diffusionMode=InitiatorOnly \
  --set network.peerSharing=false

InitiatorOnly is the canonical block-producer diffusion mode — the BP only opens outbound connections to its relays.

Producer security

When role=producer, the chart automatically creates a NetworkPolicy that:

• Restricts N2N ingress to pods labeled app.kubernetes.io/component: relay.
• Allows metrics scraping (and, when rpc.service=true, RPC) from anywhere in the cluster.
• Leaves egress unrestricted so the BP can reach its relay(s).

Block producers should never be exposed directly to the internet.

Producer + Relay architecture

A typical production deployment uses one or more relay nodes that shield the block producer:

graph LR
    Internet[Cardano Network] --> R1[Relay 1]
    Internet --> R2[Relay 2]
    R1 --> BP[Block Producer]
    R2 --> BP
    BP -. blocks .-> R1
    BP -. blocks .-> R2

Deploy both:

# Block producer
helm install dugite-producer ./charts/dugite-node \
  --set role=producer \
  --set network.name=mainnet \
  --set producer.existingSecret=dugite-producer-keys \
  -f producer-values.yaml

# Relay(s) pointing at the producer
helm install dugite-relay ./charts/dugite-node \
  --set role=relay \
  --set network.name=mainnet \
  -f relay-values.yaml

producer-values.yaml:

network:
  diffusionMode: InitiatorOnly
  peerSharing: false

topology:
  bootstrapPeers: []
  localRoots:
    - accessPoints:
        - address: dugite-relay-dugite-node.default.svc.cluster.local
          port: 3001
      advertise: false
      trustable: true
      valency: 1
  publicRoots: []
  useLedgerAfterSlot: -1

Verifying the Deployment

Pod status:

kubectl get pods -l app.kubernetes.io/name=dugite-node

Logs:

kubectl logs -f deploy/dugite-relay-dugite-node

Query the node tip via N2C (the IPC socket is shared with the pod):

kubectl exec deploy/dugite-relay-dugite-node -- \
  dugite-cli query tip \
  --testnet-magic 2 \
  --socket-path /ipc/node.sock

For mainnet, replace --testnet-magic 2 with --mainnet.

Metrics:

kubectl port-forward svc/dugite-relay-dugite-node 12796:12796
curl -s http://localhost:12796/metrics | grep sync_progress

UTxO RPC (if rpc.enabled=true):

kubectl port-forward svc/dugite-relay-dugite-node 50051:50051
grpcurl -plaintext localhost:50051 list

Configuration Reference

CLI Overview

Dugite provides dugite-cli, a cardano-cli compatible command-line interface for interacting with a running Dugite node and managing keys, transactions, and governance.

Binary

dugite-cli [COMMAND] [OPTIONS]

Command Groups

Common Patterns

Socket Path

Most commands that interact with a running node require --socket-path to specify the Unix domain socket:

dugite-cli query tip --socket-path ./node.sock

The default socket path is node.sock in the current directory.

Testnet Magic

When querying a node on a testnet, pass the --testnet-magic flag:

dugite-cli query tip --socket-path ./node.sock --testnet-magic 2

For mainnet, --testnet-magic is not needed (defaults to mainnet magic 764824073).

Text Envelope Format

Keys, certificates, and transactions are stored in the cardano-node "text envelope" JSON format:

{
  "type": "PaymentSigningKeyShelley_ed25519",
  "description": "Payment Signing Key",
  "cborHex": "5820..."
}

This format is interchangeable with files produced by cardano-cli.

Output Files

Commands that produce artifacts use --out-file:

dugite-cli transaction build ... --out-file tx.body
dugite-cli transaction sign ... --out-file tx.signed

Help

Every command supports --help:

dugite-cli --help
dugite-cli transaction --help
dugite-cli transaction build --help

dugite-node Reference

dugite-node is the main Dugite node binary. It supports two subcommands: run (start the node) and mithril-import (import a Mithril snapshot for fast initial sync).

run

Start the Dugite node:

dugite-node run [OPTIONS]

Options

Relay Node (default)

Run as a relay node with no block production keys:

dugite-node run \
  --config config/preview/config.json \
  --topology config/preview/topology.json \
  --database-path ./db-preview \
  --socket-path ./node.sock \
  --host-addr 0.0.0.0 \
  --port 3001

Block Producer

Run as a block producer by providing all three key/certificate paths:

dugite-node run \
  --config config/preview/config.json \
  --topology config/preview/topology.json \
  --database-path ./db-preview \
  --socket-path ./node.sock \
  --host-addr 0.0.0.0 \
  --port 3001 \
  --shelley-kes-key ./keys/kes.skey \
  --shelley-vrf-key ./keys/vrf.skey \
  --shelley-operational-certificate ./keys/opcert.cert

When all three block producer flags are provided, the node enters block production mode. The cold signing key is not needed at runtime — the cold verification key is extracted from the operational certificate, matching cardano-node behavior.

If any of the three flags is missing, the node runs in relay-only mode.

Environment Variables

See Logging for details on output targets, file rotation, and per-crate filtering.

Configuration File

The --config file follows the same JSON format as cardano-node. Key fields:

{
  "Protocol": "Cardano",
  "RequiresNetworkMagic": "RequiresMagic",
  "ByronGenesisFile": "byron-genesis.json",
  "ShelleyGenesisFile": "shelley-genesis.json",
  "AlonzoGenesisFile": "alonzo-genesis.json",
  "ConwayGenesisFile": "conway-genesis.json"
}

Genesis file paths are resolved relative to the directory containing the config file.

Metrics

When --metrics-port is non-zero, Prometheus metrics are served at http://localhost:<port>/metrics. See Monitoring for the full list of available metrics.

mithril-import

Import a Mithril snapshot for fast initial sync. This downloads and verifies a certified snapshot from a Mithril aggregator, then imports all blocks into the local database.

dugite-node mithril-import [OPTIONS]

Options

Network Magic Values

Example: Preview Testnet

dugite-node mithril-import \
  --network-magic 2 \
  --database-path ./db-preview

# Then start the node to sync from the snapshot to tip
dugite-node run \
  --config config/preview/config.json \
  --topology config/preview/topology.json \
  --database-path ./db-preview \
  --socket-path ./node.sock

The import process:

1. Downloads the latest snapshot from the Mithril aggregator
2. Verifies the snapshot digest (SHA256)
3. Extracts and parses immutable chunk files
4. Imports blocks into ChainDB with CRC32 verification
5. Supports resume — skips blocks already in the database

On preview testnet, importing ~4M blocks takes approximately 2 minutes.

Key Generation

Dugite CLI supports generating all key types needed for Cardano operations.

Payment Keys

Generate an Ed25519 key pair for payments:

dugite-cli key generate-payment-key \
  --signing-key-file payment.skey \
  --verification-key-file payment.vkey

Output files:

• payment.skey — Payment signing key (keep secret)
• payment.vkey — Payment verification key (safe to share)

Stake Keys

Generate an Ed25519 key pair for staking:

dugite-cli key generate-stake-key \
  --signing-key-file stake.skey \
  --verification-key-file stake.vkey

Output files:

• stake.skey — Stake signing key
• stake.vkey — Stake verification key

Verification Key Hash

Compute the Blake2b-224 hash of any verification key:

dugite-cli key verification-key-hash \
  --verification-key-file payment.vkey

This outputs the 28-byte key hash in hexadecimal, used in addresses and certificates.

DRep Keys

Generate keys for a Delegated Representative (Conway governance):

dugite-cli governance drep key-gen \
  --signing-key-file drep.skey \
  --verification-key-file drep.vkey

Get the DRep ID:

# Bech32 format (default)
dugite-cli governance drep id \
  --drep-verification-key-file drep.vkey

# Hex format
dugite-cli governance drep id \
  --drep-verification-key-file drep.vkey \
  --output-format hex

Node Keys

Cold Keys

Generate cold keys and an operational certificate issue counter:

dugite-cli node key-gen \
  --cold-verification-key-file cold.vkey \
  --cold-signing-key-file cold.skey \
  --operational-certificate-counter-file opcert.counter

KES Keys

Generate Key Evolving Signature keys (rotated periodically):

dugite-cli node key-gen-kes \
  --verification-key-file kes.vkey \
  --signing-key-file kes.skey

VRF Keys

Generate Verifiable Random Function keys (for slot leader election):

dugite-cli node key-gen-vrf \
  --verification-key-file vrf.vkey \
  --signing-key-file vrf.skey

Operational Certificate

Issue an operational certificate binding the cold key to the current KES key:

dugite-cli node issue-op-cert \
  --kes-verification-key-file kes.vkey \
  --cold-signing-key-file cold.skey \
  --operational-certificate-counter-file opcert.counter \
  --kes-period 400 \
  --out-file opcert.cert

Address Generation

Payment Address

Build a payment address from keys:

# Enterprise address (no staking)
dugite-cli address build \
  --payment-verification-key-file payment.vkey \
  --testnet-magic 2

# Base address (with staking)
dugite-cli address build \
  --payment-verification-key-file payment.vkey \
  --stake-verification-key-file stake.vkey \
  --testnet-magic 2

# Mainnet address
dugite-cli address build \
  --payment-verification-key-file payment.vkey \
  --stake-verification-key-file stake.vkey \
  --mainnet

Key File Format

All keys are stored in the cardano-node text envelope format:

{
  "type": "PaymentSigningKeyShelley_ed25519",
  "description": "Payment Signing Key",
  "cborHex": "5820a1b2c3d4..."
}

The cborHex field contains the CBOR-encoded key bytes. The type field identifies the key type and is used for validation when loading keys.

Key files generated by Dugite are compatible with cardano-cli and vice versa.

Complete Workflow Example

Generate all keys needed for a basic wallet:

# 1. Generate payment keys
dugite-cli key generate-payment-key \
  --signing-key-file payment.skey \
  --verification-key-file payment.vkey

# 2. Generate stake keys
dugite-cli key generate-stake-key \
  --signing-key-file stake.skey \
  --verification-key-file stake.vkey

# 3. Build a testnet address
dugite-cli address build \
  --payment-verification-key-file payment.vkey \
  --stake-verification-key-file stake.vkey \
  --testnet-magic 2

# 4. Get the payment key hash
dugite-cli key verification-key-hash \
  --verification-key-file payment.vkey

Transactions

Dugite CLI supports the full transaction lifecycle: building, signing, submitting, and inspecting transactions.

Building a Transaction

dugite-cli transaction build \
  --tx-in <tx_hash>#<index> \
  --tx-out <address>+<lovelace> \
  --change-address <address> \
  --fee <lovelace> \
  --out-file tx.body

Arguments

Example: Simple ADA Transfer

dugite-cli transaction build \
  --tx-in "abc123...#0" \
  --tx-out "addr_test1qz...+5000000" \
  --change-address "addr_test1qp..." \
  --fee 200000 \
  --ttl 50000000 \
  --out-file tx.body

Multi-Asset Outputs

To include native tokens in an output, use the extended format:

address+lovelace+"policy_id.asset_name quantity"

Example:

dugite-cli transaction build \
  --tx-in "abc123...#0" \
  --tx-out 'addr_test1qz...+2000000+"a1b2c3...d4e5f6.4d79546f6b656e 100"' \
  --change-address "addr_test1qp..." \
  --fee 200000 \
  --out-file tx.body

Multiple tokens can be separated with + inside the quoted string:

"policy1.asset1 100+policy2.asset2 50"

Including Certificates

dugite-cli transaction build \
  --tx-in "abc123...#0" \
  --tx-out "addr_test1qz...+5000000" \
  --change-address "addr_test1qp..." \
  --fee 200000 \
  --certificate-file stake-reg.cert \
  --certificate-file stake-deleg.cert \
  --out-file tx.body

Including Metadata

Create a metadata JSON file with integer keys:

{
  "674": {
    "msg": ["Hello, Cardano!"]
  }
}

dugite-cli transaction build \
  --tx-in "abc123...#0" \
  --tx-out "addr_test1qz...+5000000" \
  --change-address "addr_test1qp..." \
  --fee 200000 \
  --metadata-json-file metadata.json \
  --out-file tx.body

Signing a Transaction

dugite-cli transaction sign \
  --tx-body-file tx.body \
  --signing-key-file payment.skey \
  --out-file tx.signed

Multiple signing keys can be provided:

dugite-cli transaction sign \
  --tx-body-file tx.body \
  --signing-key-file payment.skey \
  --signing-key-file stake.skey \
  --out-file tx.signed

Submitting a Transaction

dugite-cli transaction submit \
  --tx-file tx.signed \
  --socket-path ./node.sock

The node validates the transaction (Phase-1 and Phase-2 for Plutus transactions) and, if valid, adds it to the mempool for propagation.

Viewing a Transaction

dugite-cli transaction view --tx-file tx.signed

Output includes:

• Transaction type
• CBOR size
• Transaction hash
• Number of inputs and outputs
• Fee
• TTL (if set)

Transaction ID

Compute the transaction hash:

dugite-cli transaction txid --tx-file tx.body

Works with both transaction body files and signed transaction files.

Calculate Minimum Fee

dugite-cli transaction calculate-min-fee \
  --tx-body-file tx.body \
  --witness-count 2 \
  --protocol-params-file protocol-params.json

The fee calculation accounts for:

• Base fee: txFeeFixed + txFeePerByte * tx_size
• Script execution: executionUnitPrices * total_ExUnits for any Plutus witnesses
• Reference script surcharge: CIP-0112 tiered fee for reference scripts (25KiB tiers, 1.2x multiplier per tier)

To get the current protocol parameters:

dugite-cli query protocol-parameters \
  --socket-path ./node.sock \
  --out-file protocol-params.json

Calculate Minimum Required UTxO

Compute the minimum lovelace required for a transaction output to satisfy the minUTxOValue protocol parameter:

dugite-cli transaction calculate-min-required-utxo \
  --protocol-params-file protocol-params.json \
  --tx-out "addr_test1qz...+0+\"policy1.asset1 100\""

Output:

Minimum required lovelace: 1724100

This is particularly useful when constructing outputs that carry native tokens, since the minimum lovelace depends on the byte-size of the value bundle (number of policy IDs, asset names, and quantities).

Creating Witnesses

For multi-signature workflows, you can create witnesses separately and assemble them:

Create a Witness

dugite-cli transaction witness \
  --tx-body-file tx.body \
  --signing-key-file payment.skey \
  --out-file payment.witness

Assemble a Transaction

dugite-cli transaction assemble \
  --tx-body-file tx.body \
  --witness-file payment.witness \
  --witness-file stake.witness \
  --out-file tx.signed

Policy ID

Compute the policy ID (Blake2b-224 hash) of a native script:

dugite-cli transaction policyid --script-file policy.script

Complete Workflow

# 1. Query UTxOs to find inputs
dugite-cli query utxo \
  --address addr_test1qz... \
  --socket-path ./node.sock \
  --testnet-magic 2

# 2. Get protocol parameters for fee calculation
dugite-cli query protocol-parameters \
  --socket-path ./node.sock \
  --testnet-magic 2 \
  --out-file pp.json

# 3. Build the transaction
dugite-cli transaction build \
  --tx-in "abc123...#0" \
  --tx-out "addr_test1qr...+5000000" \
  --change-address "addr_test1qz..." \
  --fee 200000 \
  --out-file tx.body

# 4. Calculate the exact fee
dugite-cli transaction calculate-min-fee \
  --tx-body-file tx.body \
  --witness-count 1 \
  --protocol-params-file pp.json

# 5. Rebuild with the correct fee (repeat step 3 with updated --fee)

# 6. Sign
dugite-cli transaction sign \
  --tx-body-file tx.body \
  --signing-key-file payment.skey \
  --out-file tx.signed

# 7. Submit
dugite-cli transaction submit \
  --tx-file tx.signed \
  --socket-path ./node.sock

Queries

Dugite CLI provides a comprehensive set of queries against a running node via the N2C (Node-to-Client) protocol over a Unix domain socket.

Chain Tip

Query the current chain tip:

dugite-cli query tip --socket-path ./node.sock

For testnets:

dugite-cli query tip --socket-path ./node.sock --testnet-magic 2

Output:

{
    "slot": 73429851,
    "hash": "a1b2c3d4e5f6...",
    "block": 2847392,
    "epoch": 170,
    "era": "Conway",
    "syncProgress": "99.87"
}

UTxO Query

Query UTxOs at a specific address:

dugite-cli query utxo \
  --address addr_test1qz... \
  --socket-path ./node.sock \
  --testnet-magic 2

Output:

TxHash#Ix                                                            Datum           Lovelace
------------------------------------------------------------------------------------------------
a1b2c3d4...#0                                                           no            5000000
e5f6a7b8...#1                                                          yes           10000000

Total UTxOs: 2

Protocol Parameters

Query current protocol parameters:

# Print to stdout
dugite-cli query protocol-parameters \
  --socket-path ./node.sock

# Save to file
dugite-cli query protocol-parameters \
  --socket-path ./node.sock \
  --out-file protocol-params.json

The output is a JSON object containing all active protocol parameters, including fee settings, execution unit limits, and governance thresholds.

Stake Distribution

Query the stake distribution across all registered pools:

dugite-cli query stake-distribution \
  --socket-path ./node.sock

Output:

PoolId                                                             Stake (lovelace)   Pledge (lovelace)
----------------------------------------------------------------------------------------------------------
pool1abc...                                                        15234892000000      500000000000
pool1def...                                                         8923451000000      250000000000

Total pools: 3200

Stake Address Info

Query delegation and rewards for a stake address:

dugite-cli query stake-address-info \
  --address stake_test1uz... \
  --socket-path ./node.sock \
  --testnet-magic 2

Output:

[
  {
    "address": "stake_test1uz...",
    "delegation": "pool1abc...",
    "rewardAccountBalance": 5234000
  }
]

Stake Pools

List all registered stake pools with their parameters:

dugite-cli query stake-pools \
  --socket-path ./node.sock

Output:

PoolId                                                      Pledge (ADA)    Cost (ADA)   Margin
----------------------------------------------------------------------------------------------------
pool1abc...                                                   500.000000     340.000000    1.00%
pool1def...                                                   250.000000     340.000000    2.50%

Total pools: 3200

Pool Parameters

Query detailed parameters for a specific pool:

dugite-cli query pool-params \
  --socket-path ./node.sock \
  --stake-pool-id pool1abc...

Stake Snapshots

Query the mark/set/go stake snapshots:

dugite-cli query stake-snapshot \
  --socket-path ./node.sock

# Filter by pool
dugite-cli query stake-snapshot \
  --socket-path ./node.sock \
  --stake-pool-id pool1abc...

Governance State (Conway)

Query the overall governance state:

dugite-cli query gov-state --socket-path ./node.sock

Output:

Governance State (Conway)
========================
Treasury:         1234567890 ADA
Registered DReps: 456
Committee Members: 7
Active Proposals: 12

Proposals:
Type                 TxId     Yes     No  Abstain
----------------------------------------------------
InfoAction           a1b2c3#0    42     3        5
TreasuryWithdrawals  d4e5f6#1    28    12        8

DRep State (Conway)

Query registered DReps:

# All DReps
dugite-cli query drep-state --socket-path ./node.sock

# Specific DRep by key hash
dugite-cli query drep-state \
  --socket-path ./node.sock \
  --drep-key-hash a1b2c3d4...

Output:

DRep State (Conway)
===================
Total DReps: 456

Credential Hash                                                    Deposit (ADA)    Epoch
--------------------------------------------------------------------------------------------
a1b2c3d4...                                                                500      412
  Anchor: https://example.com/drep-metadata.json

Committee State (Conway)

Query the constitutional committee:

dugite-cli query committee-state --socket-path ./node.sock

Output:

Constitutional Committee State (Conway)
=======================================
Active Members: 7
Resigned Members: 1

Cold Credential                                                    Hot Credential
--------------------------------------------------------------------------------------------------------------------------------------
a1b2c3d4...                                                        e5f6a7b8...

Resigned:
  d4e5f6a7...

Transaction Mempool

Query the node's transaction mempool:

# Mempool info (size, capacity, tx count)
dugite-cli query tx-mempool info --socket-path ./node.sock

# Check if a specific transaction is in the mempool
dugite-cli query tx-mempool has-tx \
  --socket-path ./node.sock \
  --tx-id a1b2c3d4...

Info output:

Mempool snapshot at slot 73429851:
  Capacity:     2000000 bytes
  Size:         45320 bytes
  Transactions: 12

Treasury

Query the treasury and reserves:

dugite-cli query treasury --socket-path ./node.sock

Output:

Account State
=============
Treasury: 1234567 ADA
Reserves: 9876543 ADA

Constitution (Conway)

Query the current constitution:

dugite-cli query constitution --socket-path ./node.sock

Output:

Constitution
============
URL:         https://constitution.gov/hash.json
Data Hash:   a1b2c3d4e5f6...
Script Hash: none

Ratification State (Conway)

Query the ratification state (enacted/expired proposals from the most recent epoch transition):

dugite-cli query ratify-state --socket-path ./node.sock

Output:

Ratification State
==================
Enacted proposals: 1
  a1b2c3d4e5f6...#0
Expired proposals: 2
  d4e5f6a7b8c9...#1
  e5f6a7b8c9d0...#0
Delayed:           false

Slot Number

Convert a wall-clock time to a Cardano slot number:

dugite-cli query slot-number \
  --socket-path ./node.sock \
  --testnet-magic 2 \
  --utc-time "2026-03-20T12:00:00Z"

Output:

Slot: 73851200

This is useful for computing TTL values or verifying that a specific point in time falls within a given epoch.

KES Period Info

Query KES period information for an operational certificate:

dugite-cli query kes-period-info \
  --socket-path ./node.sock \
  --op-cert-file opcert.cert

Output:

KES Period Info
===============
On-chain: yes
Operational certificate counter on-chain: 3
Certificate issue counter: 3

Current KES period: 418
Operational certificate start KES period: 418
KES max evolutions: 62
KES periods remaining: 62

Node start time: 2026-03-19T08:00:00Z
KES key expiry: 2026-09-14T08:00:00Z

Use this command to verify that a KES key is current and to determine when rotation is needed.

Leadership Schedule

Compute the leader schedule for a stake pool:

dugite-cli query leadership-schedule \
  --vrf-signing-key-file vrf.skey \
  --epoch-nonce a1b2c3d4... \
  --epoch-start-slot 73000000 \
  --epoch-length 432000 \
  --relative-stake 0.001 \
  --active-slot-coeff 0.05

Output:

Computing leader schedule for epoch starting at slot 73000000...
Epoch length: 432000 slots
Relative stake: 0.001000
Active slot coefficient: 0.05

SlotNo       VRF Output (first 16 bytes)
--------------------------------------------------
73012345     a1b2c3d4e5f6a7b8...
73045678     d4e5f6a7b8c9d0e1...

Total leader slots: 2
Expected: ~22 (f=0.05, stake=0.001000)

Stake Address Commands

The dugite-cli stake-address subcommands manage stake key generation, reward address construction, and certificate creation for staking operations.

key-gen

Generate a stake key pair:

dugite-cli stake-address key-gen \
  --verification-key-file stake.vkey \
  --signing-key-file stake.skey

build

Build a stake (reward) address from a stake verification key:

dugite-cli stake-address build \
  --stake-verification-key-file stake.vkey \
  --network testnet

registration-certificate

Create a stake address registration certificate:

# Conway era (with deposit)
dugite-cli stake-address registration-certificate \
  --stake-verification-key-file stake.vkey \
  --key-reg-deposit-amt 2000000 \
  --out-file stake-reg.cert

# Legacy Shelley era (no deposit parameter)
dugite-cli stake-address registration-certificate \
  --stake-verification-key-file stake.vkey \
  --out-file stake-reg.cert

The deposit amount should match the current stakeAddressDeposit protocol parameter (typically 2 ADA = 2000000 lovelace).

deregistration-certificate

Create a stake address deregistration certificate to reclaim the deposit:

dugite-cli stake-address deregistration-certificate \
  --stake-verification-key-file stake.vkey \
  --key-reg-deposit-amt 2000000 \
  --out-file stake-dereg.cert

delegation-certificate

Create a stake delegation certificate to delegate to a stake pool:

dugite-cli stake-address delegation-certificate \
  --stake-verification-key-file stake.vkey \
  --stake-pool-id pool1abc... \
  --out-file delegation.cert

vote-delegation-certificate

Create a vote delegation certificate (Conway era) to delegate voting power to a DRep:

# Delegate to a specific DRep
dugite-cli stake-address vote-delegation-certificate \
  --stake-verification-key-file stake.vkey \
  --drep-verification-key-file drep.vkey \
  --out-file vote-deleg.cert

# Delegate to always-abstain
dugite-cli stake-address vote-delegation-certificate \
  --stake-verification-key-file stake.vkey \
  --always-abstain \
  --out-file vote-deleg.cert

# Delegate to always-no-confidence
dugite-cli stake-address vote-delegation-certificate \
  --stake-verification-key-file stake.vkey \
  --always-no-confidence \
  --out-file vote-deleg.cert

Complete Staking Workflow

# 1. Generate stake keys
dugite-cli stake-address key-gen \
  --verification-key-file stake.vkey \
  --signing-key-file stake.skey

# 2. Create registration certificate
dugite-cli stake-address registration-certificate \
  --stake-verification-key-file stake.vkey \
  --key-reg-deposit-amt 2000000 \
  --out-file stake-reg.cert

# 3. Create delegation certificate
dugite-cli stake-address delegation-certificate \
  --stake-verification-key-file stake.vkey \
  --stake-pool-id pool1abc... \
  --out-file delegation.cert

# 4. Submit both in a single transaction
dugite-cli transaction build \
  --tx-in "abc123...#0" \
  --tx-out "addr_test1qz...+5000000" \
  --change-address "addr_test1qp..." \
  --fee 200000 \
  --certificate-file stake-reg.cert \
  --certificate-file delegation.cert \
  --out-file tx.body

dugite-cli transaction sign \
  --tx-body-file tx.body \
  --signing-key-file payment.skey \
  --signing-key-file stake.skey \
  --out-file tx.signed

dugite-cli transaction submit \
  --tx-file tx.signed \
  --socket-path ./node.sock

Stake Pool Commands

The dugite-cli stake-pool subcommands manage stake pool key generation, pool registration, and operational certificate issuance.

key-gen

Generate pool cold keys and an operational certificate counter:

dugite-cli stake-pool key-gen \
  --cold-verification-key-file cold.vkey \
  --cold-signing-key-file cold.skey \
  --operational-certificate-counter-file opcert.counter

id

Get the pool ID (Blake2b-224 hash of the cold verification key):

dugite-cli stake-pool id \
  --cold-verification-key-file cold.vkey

vrf-key-gen

Generate a VRF key pair:

dugite-cli stake-pool vrf-key-gen \
  --verification-key-file vrf.vkey \
  --signing-key-file vrf.skey

kes-key-gen

Generate a KES key pair:

dugite-cli stake-pool kes-key-gen \
  --verification-key-file kes.vkey \
  --signing-key-file kes.skey

issue-op-cert

Issue an operational certificate:

dugite-cli stake-pool issue-op-cert \
  --kes-verification-key-file kes.vkey \
  --cold-signing-key-file cold.skey \
  --operational-certificate-counter-file opcert.counter \
  --kes-period 400 \
  --out-file opcert.cert

registration-certificate

Create a stake pool registration certificate:

dugite-cli stake-pool registration-certificate \
  --cold-verification-key-file cold.vkey \
  --vrf-verification-key-file vrf.vkey \
  --pledge 500000000 \
  --cost 340000000 \
  --margin 0.02 \
  --reward-account-verification-key-file stake.vkey \
  --pool-owner-verification-key-file stake.vkey \
  --single-host-pool-relay "relay.example.com:3001" \
  --metadata-url "https://example.com/pool-metadata.json" \
  --metadata-hash "a1b2c3d4..." \
  --out-file pool-reg.cert

metadata-hash

Compute the Blake2b-256 hash of a pool metadata file:

dugite-cli stake-pool metadata-hash \
  --pool-metadata-file pool-metadata.json

Output:

a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2

This hash is required when registering a pool. The metadata file must be served at the URL specified in the registration certificate and the hash must match. The file contents at that URL are checked by other nodes during pool discovery.

Example pool metadata file:

{
  "name": "Sandstone Pool",
  "description": "A Cardano stake pool running Dugite",
  "ticker": "SAND",
  "homepage": "https://sandstone.io"
}

retirement-certificate

Create a stake pool retirement certificate:

dugite-cli stake-pool retirement-certificate \
  --cold-verification-key-file cold.vkey \
  --epoch 500 \
  --out-file pool-retire.cert

Complete Pool Registration Workflow

# 1. Generate all keys
dugite-cli stake-pool key-gen \
  --cold-verification-key-file cold.vkey \
  --cold-signing-key-file cold.skey \
  --operational-certificate-counter-file opcert.counter

dugite-cli stake-pool vrf-key-gen \
  --verification-key-file vrf.vkey \
  --signing-key-file vrf.skey

dugite-cli stake-pool kes-key-gen \
  --verification-key-file kes.vkey \
  --signing-key-file kes.skey

# 2. Issue operational certificate
dugite-cli stake-pool issue-op-cert \
  --kes-verification-key-file kes.vkey \
  --cold-signing-key-file cold.skey \
  --operational-certificate-counter-file opcert.counter \
  --kes-period 400 \
  --out-file opcert.cert

# 3. Create registration certificate
dugite-cli stake-pool registration-certificate \
  --cold-verification-key-file cold.vkey \
  --vrf-verification-key-file vrf.vkey \
  --pledge 500000000 \
  --cost 340000000 \
  --margin 0.02 \
  --reward-account-verification-key-file stake.vkey \
  --pool-owner-verification-key-file stake.vkey \
  --single-host-pool-relay "relay.example.com:3001" \
  --metadata-url "https://example.com/pool.json" \
  --metadata-hash "a1b2c3..." \
  --out-file pool-reg.cert

# 4. Submit registration in a transaction
dugite-cli transaction build \
  --tx-in "abc123...#0" \
  --tx-out "addr_test1qz...+5000000" \
  --change-address "addr_test1qp..." \
  --fee 200000 \
  --certificate-file pool-reg.cert \
  --out-file tx.body

dugite-cli transaction sign \
  --tx-body-file tx.body \
  --signing-key-file payment.skey \
  --signing-key-file cold.skey \
  --signing-key-file stake.skey \
  --out-file tx.signed

dugite-cli transaction submit \
  --tx-file tx.signed \
  --socket-path ./node.sock

Node Commands

The dugite-cli node subcommands manage cold keys, KES keys, VRF keys, and operational certificates for block producer setup.

key-gen

Generate a cold key pair and an operational certificate issue counter:

dugite-cli node key-gen \
  --cold-verification-key-file cold.vkey \
  --cold-signing-key-file cold.skey \
  --operational-certificate-counter-file opcert.counter

The cold key identifies your stake pool. Keep the signing key offline (air-gapped) after initial setup.

key-gen-kes

Generate a KES (Key Evolving Signature) key pair:

dugite-cli node key-gen-kes \
  --verification-key-file kes.vkey \
  --signing-key-file kes.skey

KES keys are rotated periodically. Each key is valid for a limited number of KES periods (62 periods on mainnet, approximately 90 days total).

key-gen-vrf

Generate a VRF (Verifiable Random Function) key pair:

dugite-cli node key-gen-vrf \
  --verification-key-file vrf.vkey \
  --signing-key-file vrf.skey

VRF keys are used for slot leader election and do not need rotation.

issue-op-cert

Issue an operational certificate binding the cold key to the current KES key:

dugite-cli node issue-op-cert \
  --kes-verification-key-file kes.vkey \
  --cold-signing-key-file cold.skey \
  --operational-certificate-counter-file opcert.counter \
  --kes-period 400 \
  --out-file opcert.cert

The opcert must be regenerated each time you rotate KES keys. The counter file is incremented each time to prevent replay attacks.

new-counter

Create a new operational certificate issue counter (useful if the original counter is lost):

dugite-cli node new-counter \
  --cold-verification-key-file cold.vkey \
  --counter-value 5 \
  --operational-certificate-counter-file opcert.counter

Governance

Dugite CLI supports Conway-era governance operations as defined in CIP-1694. This includes DRep management, voting, and governance action creation.

DRep Operations

Generate DRep Keys

dugite-cli governance drep key-gen \
  --signing-key-file drep.skey \
  --verification-key-file drep.vkey

Get DRep ID

# Bech32 format (default)
dugite-cli governance drep id \
  --drep-verification-key-file drep.vkey

# Hex format
dugite-cli governance drep id \
  --drep-verification-key-file drep.vkey \
  --output-format hex

DRep Registration

Create a DRep registration certificate:

dugite-cli governance drep registration-certificate \
  --drep-verification-key-file drep.vkey \
  --key-reg-deposit-amt 500000000 \
  --anchor-url "https://example.com/drep-metadata.json" \
  --anchor-data-hash "a1b2c3d4..." \
  --out-file drep-reg.cert

The --key-reg-deposit-amt should match the current DRep deposit parameter (currently 500 ADA = 500000000 lovelace on mainnet).

DRep Retirement

dugite-cli governance drep retirement-certificate \
  --drep-verification-key-file drep.vkey \
  --deposit-amt 500000000 \
  --out-file drep-retire.cert

DRep Update

Update DRep metadata:

dugite-cli governance drep update-certificate \
  --drep-verification-key-file drep.vkey \
  --anchor-url "https://example.com/drep-metadata-v2.json" \
  --anchor-data-hash "d4e5f6a7..." \
  --out-file drep-update.cert

Voting

Create a Vote

Votes can be cast by DReps, SPOs, or Constitutional Committee members:

DRep vote:

dugite-cli governance vote create \
  --governance-action-tx-id "a1b2c3d4..." \
  --governance-action-index 0 \
  --vote yes \
  --drep-verification-key-file drep.vkey \
  --out-file vote.json

SPO vote:

dugite-cli governance vote create \
  --governance-action-tx-id "a1b2c3d4..." \
  --governance-action-index 0 \
  --vote no \
  --cold-verification-key-file cold.vkey \
  --out-file vote.json

Constitutional Committee vote:

dugite-cli governance vote create \
  --governance-action-tx-id "a1b2c3d4..." \
  --governance-action-index 0 \
  --vote yes \
  --cc-hot-verification-key-file cc-hot.vkey \
  --out-file vote.json

Vote Values

Vote with Anchor

Attach rationale metadata to a vote:

dugite-cli governance vote create \
  --governance-action-tx-id "a1b2c3d4..." \
  --governance-action-index 0 \
  --vote yes \
  --drep-verification-key-file drep.vkey \
  --anchor-url "https://example.com/vote-rationale.json" \
  --anchor-data-hash "e5f6a7b8..." \
  --out-file vote.json

Governance Actions

Info Action

A governance action that carries no on-chain effect (used for signaling):

dugite-cli governance action create-info \
  --anchor-url "https://example.com/proposal.json" \
  --anchor-data-hash "a1b2c3d4..." \
  --deposit 100000000000 \
  --return-addr "addr_test1qz..." \
  --out-file info-action.json

No Confidence Motion

Express no confidence in the current constitutional committee:

dugite-cli governance action create-no-confidence \
  --anchor-url "https://example.com/no-confidence.json" \
  --anchor-data-hash "a1b2c3d4..." \
  --deposit 100000000000 \
  --return-addr "addr_test1qz..." \
  --prev-governance-action-tx-id "d4e5f6a7..." \
  --prev-governance-action-index 0 \
  --out-file no-confidence.json

New Constitution

Propose a new constitution:

dugite-cli governance action create-constitution \
  --anchor-url "https://example.com/constitution-proposal.json" \
  --anchor-data-hash "a1b2c3d4..." \
  --deposit 100000000000 \
  --return-addr "addr_test1qz..." \
  --constitution-url "https://example.com/constitution.txt" \
  --constitution-hash "e5f6a7b8..." \
  --constitution-script-hash "b8c9d0e1..." \
  --out-file new-constitution.json

Hard Fork Initiation

Propose a protocol version change:

dugite-cli governance action create-hard-fork-initiation \
  --anchor-url "https://example.com/hardfork.json" \
  --anchor-data-hash "a1b2c3d4..." \
  --deposit 100000000000 \
  --return-addr "addr_test1qz..." \
  --protocol-major-version 10 \
  --protocol-minor-version 0 \
  --out-file hardfork.json

Protocol Parameters Update

Propose changes to protocol parameters:

dugite-cli governance action create-protocol-parameters-update \
  --anchor-url "https://example.com/pp-update.json" \
  --anchor-data-hash "a1b2c3d4..." \
  --deposit 100000000000 \
  --return-addr "addr_test1qz..." \
  --protocol-parameters-update pp-changes.json \
  --out-file pp-update.json

The pp-changes.json file contains the parameter fields to change:

{
  "txFeePerByte": 44,
  "txFeeFixed": 155381,
  "maxBlockBodySize": 90112,
  "maxTxSize": 16384
}

Update Committee

Propose changes to the constitutional committee:

dugite-cli governance action create-update-committee \
  --anchor-url "https://example.com/committee-update.json" \
  --anchor-data-hash "a1b2c3d4..." \
  --deposit 100000000000 \
  --return-addr "addr_test1qz..." \
  --remove-cc-cold-verification-key-hash "old_member_hash" \
  --add-cc-cold-verification-key-hash "new_member_hash,500" \
  --threshold "2/3" \
  --out-file committee-update.json

The --add-cc-cold-verification-key-hash uses the format key_hash,expiry_epoch.

Treasury Withdrawal

Propose a withdrawal from the treasury:

dugite-cli governance action create-treasury-withdrawal \
  --anchor-url "https://example.com/withdrawal.json" \
  --anchor-data-hash "a1b2c3d4..." \
  --deposit 100000000000 \
  --return-addr "addr_test1qz..." \
  --funds-receiving-stake-verification-key-file recipient.vkey \
  --transfer 50000000000 \
  --out-file treasury-withdrawal.json

Hash Anchor Data

Compute the Blake2b-256 hash of an anchor data file:

# Binary file
dugite-cli governance action hash-anchor-data \
  --file-binary proposal.json

# Text file
dugite-cli governance action hash-anchor-data \
  --file-text proposal.txt

Submitting Governance Actions

Governance actions and votes are submitted as part of transactions. Include the certificate or vote file when building the transaction:

# Submit a DRep registration
dugite-cli transaction build \
  --tx-in "abc123...#0" \
  --tx-out "addr_test1qz...+5000000" \
  --change-address "addr_test1qp..." \
  --fee 200000 \
  --certificate-file drep-reg.cert \
  --out-file tx.body

dugite-cli transaction sign \
  --tx-body-file tx.body \
  --signing-key-file payment.skey \
  --signing-key-file drep.skey \
  --out-file tx.signed

dugite-cli transaction submit \
  --tx-file tx.signed \
  --socket-path ./node.sock

Architecture Overview

Dugite is organized as a 15-crate Cargo workspace. Each crate has a focused responsibility and well-defined dependencies.

Crate Workspace

Crate Dependency Graph

graph TD
    NODE[dugite-node] --> NET[dugite-network]
    NODE --> CONS[dugite-consensus]
    NODE --> LEDGER[dugite-ledger]
    NODE --> STORE[dugite-storage]
    NODE --> POOL[dugite-mempool]
    CLI[dugite-cli] --> NET
    CLI --> PRIM[dugite-primitives]
    CLI --> CRYPTO[dugite-crypto]
    CLI --> SER[dugite-serialization]
    MON[dugite-monitor] --> PRIM
    CFG[dugite-config] --> PRIM
    NET --> PRIM
    NET --> CRYPTO
    NET --> SER
    NET --> POOL
    CONS --> PRIM
    CONS --> CRYPTO
    LEDGER --> PRIM
    LEDGER --> CRYPTO
    LEDGER --> SER
    LEDGER --> LSM[dugite-lsm]
    LEDGER --> UPLC[dugite-uplc]
    STORE --> PRIM
    STORE --> SER
    POOL --> PRIM
    SER --> PRIM
    CRYPTO --> PRIM

Key Dependencies

• tokio — Async runtime
• dugite-lsm — Pure Rust LSM tree for the on-disk UTxO set (UTxO-HD)
• minicbor — CBOR encoding for custom types
• ed25519-dalek — Ed25519 signatures
• blake2b_simd — SIMD-accelerated Blake2b hashing
• clap — CLI argument parsing
• tracing — Structured logging

Design Principles

Zero-Warning Policy

All code must compile with RUSTFLAGS="-D warnings" and pass cargo clippy --all-targets -- -D warnings. This is enforced by CI.

Wire-Format Compatibility

Dugite uses an in-house multi-era CBOR decoder (dugite-serialization) for all block and transaction deserialization, ensuring exact wire-format compatibility with cardano-node. Internal types (dugite-primitives) are populated directly from the decoded CBOR.

Key patterns:

• Transaction.hash is blake2b_256(raw_body_cbor) over bytes captured by KeepRaw::parse_with during decode
• ChainSyncEvent::RollForward uses Box<Block> to avoid large enum variant size
• Invalid transactions (is_valid: false) are skipped during apply_block
• Pool IDs are Hash28 (Blake2b-224), not Hash32

Multi-Era Support

Dugite handles all Cardano eras from Byron through Conway. The serialization layer handles era-specific block formats transparently, while the ledger layer applies era-appropriate validation rules.

Sync Pipeline

Dugite uses a pipelined multi-peer architecture for block synchronization, separating header collection from block fetching for maximum throughput.

Architecture

flowchart LR
    subgraph Primary Peer
        CS[ChainSync<br/>Header Collection]
    end

    CS -->|headers| HQ[Header Queue]

    subgraph Block Fetch Pool
        BF1[Peer 1<br/>BlockFetch]
        BF2[Peer 2<br/>BlockFetch]
        BF3[Peer N<br/>BlockFetch]
    end

    HQ -->|range 1| BF1
    HQ -->|range 2| BF2
    HQ -->|range N| BF3

    BF1 -->|blocks| BP[Block Processor]
    BF2 -->|blocks| BP
    BF3 -->|blocks| BP

    BP --> CDB[(ChainDB)]
    BP --> LS[Ledger State]

Pipeline Stages

1. Header Collection (ChainSync)

A primary peer is selected for the ChainSync protocol. The node requests block headers sequentially using the N2N ChainSync mini-protocol (V14+). Headers are collected into batches.

The ChainSync protocol involves:

1. MsgFindIntersect — Find a common point between the node and the peer
2. MsgRequestNext — Request the next header
3. MsgRollForward — Receive a new header
4. MsgRollBackward — Handle a chain reorganization

2. Block Fetch Pool

Collected headers are distributed across multiple peers for parallel block retrieval. The block fetch pool supports up to 4 concurrent peers, each fetching a range of blocks.

The BlockFetch protocol involves:

1. MsgRequestRange — Request a range of blocks by header hash
2. MsgBlock — Receive a block
3. MsgBatchDone — Signal the end of a batch

Blocks are fetched in batches of 500 headers, with sub-batches of 100 headers each. Each sub-batch is decoded on a spawn_blocking task to avoid blocking the async runtime.

3. Block Processing

Fetched blocks are applied to the ledger state in order:

1. Deserialization — Raw CBOR bytes are decoded into Dugite's internal Block type using Dugite's in-house multi-era CBOR decoder
2. Ledger validation — Each block is validated against the current ledger state (UTxO checks, fee validation, certificate processing)
3. Storage — Valid blocks are added to the ChainDB (volatile database first, flushed to immutable when k-deep)
4. Epoch transitions — At epoch boundaries, stake snapshots are rotated and rewards are calculated

Batched Lock Acquisition

To minimize lock contention, the sync loop acquires a single lock on both the ChainDB and ledger state for each batch of 500 blocks, rather than locking per-block.

Progress Reporting

Progress is logged every 5 seconds, showing:

• Current slot and block number
• Epoch number
• UTxO count
• Sync percentage (based on slot vs. wall-clock time)
• Blocks-per-second throughput metric

Rollback Handling

When the ChainSync peer sends a MsgRollBackward message, the node:

1. Identifies the rollback point (a slot/hash pair)
2. Removes rolled-back blocks from the VolatileDB
3. Reverts the ledger state to the rollback point
4. Resumes header collection from the new tip

Only blocks in the VolatileDB (the last k=2160 blocks) can be rolled back. Blocks that have been flushed to the ImmutableDB are permanent.

Pipelined ChainSync

Dugite uses pipelined ChainSync to avoid the round-trip latency bottleneck of serial header requests. Instead of waiting for each MsgRollForward before requesting the next header, the node sends up to 300 MsgRequestNext messages concurrently (configurable via DUGITE_PIPELINE_DEPTH).

This bypasses a serial ChainSync state machine in favor of a custom implementation that manages the pipeline depth directly.

Performance Characteristics

• Header collection is pipelined per peer (up to 300 in-flight requests, configurable via DUGITE_PIPELINE_DEPTH)
• Block fetching is parallelized across up to 4 concurrent peers
• Block processing is batched (500 blocks per batch) with single-lock acquisition
• Throughput depends on network latency, peer count, and block sizes

On preview testnet, full sync from genesis completes in approximately 10 hours, with block replay (from Mithril snapshot) achieving ~13,700 blocks/second.

Storage

Dugite's storage layer is implemented in the dugite-storage and dugite-ledger crates. It closely mirrors the cardano-node architecture with three distinct storage subsystems coordinated by ChainDB.

Storage Architecture

flowchart TD
    CDB[ChainDB] --> VOL[VolatileDB<br/>In-Memory HashMap<br/>Last k=2160 blocks]
    CDB --> IMM[ImmutableDB<br/>Append-Only Chunk Files<br/>Finalized blocks]

    NEW[New Block] -->|add_block| VOL
    VOL -->|flush when > k blocks| IMM

    READ[Block Query] -->|1. check volatile| VOL
    READ -->|2. fallback to immutable| IMM

    ROLL[Rollback] -->|remove from volatile| VOL

    LS[LedgerState] --> UTXO[UtxoStore<br/>dugite-lsm LSM tree<br/>On-disk UTxO set]
    LS --> DIFF[DiffSeq<br/>Last k UTxO diffs<br/>For rollback]

Block Storage

ImmutableDB (Append-Only Chunk Files)

The ImmutableDB stores finalized blocks in append-only chunk files on disk. This matches cardano-node's ImmutableDB design — blocks are simply appended to files and are inherently durable without any snapshot mechanism.

Properties:

• Always durable — append-only writes survive process crashes without special persistence logic
• No LSM tree — plain chunk files, no compaction or memtable overhead
• Sequential access — optimized for the append-heavy, read-sequential block storage workload
• Secondary indexes — slot-to-offset and hash-to-slot mappings for efficient lookups
• Memory-mapped block index — on-disk open-addressing hash table (hash_index.dat) provides 3-5x faster lookups than in-memory HashMap while using near-zero RSS

VolatileDB (In-Memory HashMap)

The VolatileDB stores recent blocks (the last k=2160 blocks) in an in-memory HashMap. This enables:

• Fast reads — no disk I/O for recent blocks
• Efficient rollback — blocks can be removed without touching disk
• Simple eviction — when a block becomes k-deep, it is flushed to the ImmutableDB

The VolatileDB has no on-disk representation — it exists only in memory and is rebuilt from the ImmutableDB tip on restart.

ChainDB

ChainDB is the unified interface for block storage. It coordinates the ImmutableDB and VolatileDB:

1. New blocks arrive from peers and are added to the VolatileDB
2. Once a block is more than k slots deep (k=2160 for mainnet), it is flushed from the VolatileDB to the ImmutableDB
3. Flushed blocks are removed from the VolatileDB

When querying for a block:

1. The VolatileDB is checked first (fast, in-memory)
2. If not found, the ImmutableDB is consulted (disk-based)

Block Range Queries

ChainDB supports querying blocks by slot range:

• VolatileDB scans its HashMap for matching slots
• ImmutableDB uses secondary indexes for slot range scanning
• Results from both databases are merged

UTxO Storage (UTxO-HD)

The UTxO set is stored on disk using dugite-lsm, a pure Rust LSM tree. This matches Haskell cardano-node's UTxO-HD architecture, where the UTxO set lives in an LSM-backed on-disk store rather than entirely in memory.

UtxoStore

The UtxoStore (in dugite-ledger) wraps a dugite-lsm LsmTree and provides:

• Disk-backed UTxO set — the full UTxO set lives on disk, not in memory
• Efficient point lookups — bloom filters for fast negative lookups
• Batch writes — UTxO inserts and deletes are batched per block
• Snapshots — periodic snapshots for crash recovery

dugite-lsm is configured via storage profiles that maximize available system memory:

All profiles use 10 bits per key bloom filters and hybrid compaction (tiered L0, leveled L1+).

DiffSeq (Rollback Support)

The DiffSeq (in dugite-ledger) maintains the last k blocks of UTxO diffs, enabling rollback without replaying blocks:

• Each block produces a UtxoDiff recording which UTxOs were added and removed
• The DiffSeq holds the last k=2160 diffs
• On rollback, diffs are applied in reverse to restore the UTxO set

io_uring Support (Linux)

On Linux with kernel 5.1+, enable io_uring for async I/O in the UTxO LSM tree:

cargo build --release --features io-uring

On other platforms (macOS, Windows), the feature flag is accepted but falls back to synchronous I/O automatically.

Snapshot Policy

Dugite uses a time-based snapshot policy matching Haskell's cardano-node:

• Normal sync: snapshots every 72 minutes (k * 2 seconds, where k=2160)
• Bulk sync: snapshots every 50,000 blocks plus 6 minutes of wall-clock time
• Maximum retained: 2 snapshots on disk at any time

Ledger snapshots include the full ledger state (stake distribution, protocol parameters, governance state, etc.). The UTxO set is persisted separately via the UtxoStore's LSM snapshots.

Tip Recovery

When the node restarts:

1. The ImmutableDB tip is read from the chunk files (always durable)
2. The VolatileDB starts empty (in-memory state is rebuilt)
3. The ledger state is restored from the most recent snapshot
4. The UTxO set is restored from the UtxoStore's LSM snapshot
5. The node resumes syncing from the recovered tip

Disk Layout

database-path/
  immutable/          # Append-only block chunk files
    chunks/           # Block data files
    index/            # Secondary indexes (slot, hash)
    hash_index.dat    # Mmap block index (open-addressing hash table)
  utxo-store/         # dugite-lsm database (UTxO set)
    active/           # Current SSTables
    snapshots/        # Durable snapshots
  ledger/             # Ledger state snapshots

Performance Considerations

• Block writes — append-only chunk files provide consistent write performance without compaction pauses
• UTxO lookups — LSM tree with bloom filters provides efficient point lookups for transaction validation
• Memory usage — the VolatileDB holds approximately k blocks in memory (typically a few hundred MB). The UTxO set lives on disk, significantly reducing memory pressure compared to an all-in-memory approach
• Batch size — the flush batch size balances memory usage against write efficiency

Storage Profiles

Dugite provides four storage profiles sized to maximize available system memory:

# Select a profile via CLI
./dugite-node run --storage-profile high-memory ...

# Override individual parameters
./dugite-node run --storage-profile low-memory --utxo-block-cache-size-mb 4096 ...

Profiles can also be set in the node configuration file:

{
  "storage": {
    "profile": "high-memory",
    "utxoBlockCacheSizeMb": 8192
  }
}

Resolution order: profile defaults < config file overrides < CLI overrides.

Fork Recovery & ImmutableDB Contamination

Problem

When a forged block loses a slot battle, flush_all_to_immutable on graceful shutdown can persist orphaned blocks permanently in the ImmutableDB. Since the ImmutableDB is append-only and designed for finalized blocks, these orphaned blocks contaminate the canonical chain history and can cause intersection failures on reconnect.

sequenceDiagram
    participant Node as Dugite Node
    participant Vol as VolatileDB
    participant Imm as ImmutableDB
    participant Peer as Upstream Peer

    Node->>Vol: Forge block at slot S
    Peer->>Node: Competing block at slot S wins
    Note over Vol: Orphaned forged block still in VolatileDB
    Node->>Imm: flush_all_to_immutable (graceful shutdown)
    Note over Imm: Orphaned block now persisted permanently
    Node->>Peer: Restart — intersection negotiation fails

Detection

• ChainDB.get_chain_points() walks backwards through volatile blocks via prev_hash links, providing the peer with enough ancestry for intersection even when the tip is orphaned.
• ImmutableDB.get_historical_points() samples older chunk secondary indexes in reverse order, providing canonical intersection points even when the immutable tip is contaminated.
• When fork divergence is detected, contaminated ChainDB chain points are excluded from intersection negotiation, preventing the node from advertising orphaned blocks to peers.

Recovery

• Case A (Origin intersection): The volatile DB is cleared, the ledger state is reset, and the node reconnects from genesis. This is the fallback when no valid intersection can be found.
• Case B (Intersection behind ledger): A targeted ImmutableDB replay is performed up to the intersection slot using a detached LSM store, achieving approximately 50K blocks/second replay speed. This avoids a full resync while restoring the ledger to a consistent state.

Benchmarks

Run storage benchmarks with:

# Storage benchmarks (block index, ImmutableDB, ChainDB, scaling to 1M entries)
cargo bench -p dugite-storage --bench storage_bench

# UTxO store benchmarks (insert, lookup, apply_tx, LSM configs, scaling to 1M entries)
cargo bench -p dugite-ledger --bench ledger_bench

# Crypto benchmarks (Ed25519, blake2b keyhash)
cargo bench -p dugite-crypto --bench crypto_bench

# Hash benchmarks (blake2b_256, blake2b_224, batch hashing)
cargo bench -p dugite-primitives --bench primitives_bench

Results are saved to target/criterion/ with HTML reports. Baseline results are tracked in benches/.

Latest Results (Apple M2 Max, 32GB, 2026-03-14)

Block Index Lookup (500 random lookups, mmap vs in-memory HashMap)

Mmap lookup advantage grows with scale — at mainnet block counts (~10M), the gap widens further.

UTxO Store Scaling (dugite-lsm LSM tree)

Insert and lookup scale near-linearly. At mainnet scale (~20M UTxOs), estimated full scan ~6.6s.

Crypto & Hashing

A typical block with 50 witnesses: ~1.4ms for signature verification, ~6.4µs for keyhash computation.

LSM Config Comparison (100K entries)

All storage profiles perform identically at benchmark scale — config differences emerge at mainnet scale (20M+ UTxOs) where working set exceeds cache capacity.

See benches/2026-03-14-all-profiles.md for full results.

Ledger

Dugite's ledger layer (dugite-ledger) implements full Cardano transaction validation, UTxO management, stake distribution, reward calculation, and Conway-era governance. It closely follows the Haskell cardano-ledger STS (State Transition System) rules.

Ledger State

The LedgerState is the complete mutable state of the Cardano ledger at a given point in the chain:

flowchart TD
    LS[LedgerState] --> UTXO[UtxoSet<br/>On-disk via LSM tree]
    LS --> DELEG[Delegations<br/>Stake → Pool mapping]
    LS --> POOLS[Pool Parameters<br/>Registered pools + future updates]
    LS --> REWARDS[Reward Accounts<br/>Per-credential balances]
    LS --> GOV[GovernanceState<br/>DReps, proposals, committee, constitution]
    LS --> SNAP[EpochSnapshots<br/>Mark / Set / Go]
    LS --> PP[Protocol Parameters<br/>Current + previous epoch]
    LS --> FIN[Treasury + Reserves<br/>Financial state]

Key design decisions:

• Arc-wrapped collections — Large mutable fields (delegations, pool_params, reward_accounts, governance) are wrapped in Arc for copy-on-write semantics. Cloning LedgerState bumps reference counts; mutations via Arc::make_mut() only copy when shared.
• On-disk UTxO — The UTxO set lives in an LSM tree (dugite-lsm) rather than in memory, matching Haskell's UTxO-HD architecture. At mainnet scale (~20M UTxOs), this avoids multi-gigabyte memory pressure.
• Exact rational arithmetic — Reward calculations use Rat (backed by num_bigint::BigInt) for lossless intermediate computation, with a single floor operation at the end matching Haskell's rationalToCoinViaFloor.

Block Application Pipeline

When a new block arrives, apply_block() processes it through this pipeline:

flowchart TD
    BLK[New Block] --> CONN[Check prev_hash chain]
    CONN --> EPOCH{Epoch boundary?}
    EPOCH -->|Yes| ET[Process epoch transition]
    EPOCH -->|No| TXS[Process transactions]
    ET --> TXS
    TXS --> P1[Phase-1 Validation<br/>Structural + witness checks]
    P1 --> P2{Plutus scripts?}
    P2 -->|Yes| EVAL[Phase-2 Evaluation<br/>dugite-uplc CEK machine]
    P2 -->|No| APPLY[Apply UTxO changes]
    EVAL --> APPLY
    APPLY --> CERT[Process certificates]
    CERT --> GOV[Process governance actions]
    GOV --> DIFF[Record UtxoDiff]

Block Validation Modes

Invalid transactions (is_valid: false) skip normal input/output processing. Instead, collateral inputs are consumed and collateral return is added.

Transaction Validation

Phase-1 (Structural + Witness)

Phase-1 validation checks structural rules without executing scripts:

1. Inputs exist — All transaction inputs are present in the UTxO set
2. Fee sufficient — Fee covers minimum fee based on tx size, execution units, and reference script size (CIP-0112 tiered pricing in Conway)
3. Value conserved — Inputs = outputs + fee (+ minting/burning for multi-asset)
4. TTL valid — Transaction has not expired (time-to-live check against current slot)
5. Witness verification — Ed25519 signatures match required signers from inputs, withdrawals, and certificates
6. Multi-asset rules — No negative quantities, minting requires policy witness
7. Reference inputs — All reference inputs exist (not consumed, only read)
8. Output minimum — Each output meets the minimum lovelace requirement
9. Transaction size — Does not exceed max transaction size
10. Network ID — Matches the expected network

Phase-2 (Plutus Script Execution)

For transactions containing Plutus scripts (V1/V2/V3):

1. Script data hash — Matches the hash of redeemers + datums + cost models
2. Collateral — Sufficient collateral provided (150% of estimated fees in Conway)
3. Execution units — Each redeemer's CPU and memory within budget
4. Script evaluation — Each script is executed via the dugite-uplc CEK machine with the appropriate cost model
5. Block budget — Total execution units across all transactions do not exceed block limits

Scripts are evaluated in parallel using rayon when the parallel-verification feature is enabled (default).

Validation Error Types

The ValidationError enum covers 50+ error variants across all categories: structural, UTxO, fees, witnesses, time, scripts, collateral, Plutus, era-gating, certificates, governance, datums, withdrawals, network, and auxiliary data.

Certificate Processing

Dugite processes all Shelley through Conway certificate types:

Governance (CIP-1694)

The GovernanceState tracks all Conway-era governance:

DRep Lifecycle

• Registration — DReps register with a deposit, becoming eligible to vote
• Activity tracking — DReps must vote within drepActivity epochs or become inactive
• Expiration — Inactive DReps' delegated stake counts as abstaining
• Delegation — Stake credentials delegate voting power to DReps, AlwaysAbstain, or AlwaysNoConfidence

Constitutional Committee

• Hot key authorization — Cold keys authorize hot keys for voting
• Member expiration — Each member has an epoch-based term limit
• Quorum — Threshold fraction of non-expired, non-resigned members must approve

Governance Actions

Seven action types with per-type ratification thresholds:

Ratification

Ratification uses a two-epoch delay: proposals and votes from epoch E are considered at the E+1 → E+2 boundary using a frozen RatificationSnapshot. This prevents mid-epoch voting from affecting the current epoch's ratification. Thresholds use exact rational arithmetic via u128 cross-multiplication.

Epoch Transitions

At each epoch boundary, process_epoch_transition() follows the Haskell NEWEPOCH STS rule:

flowchart TD
    NE[NEWEPOCH] --> RUPD[Apply pending RUPD<br/>treasury += deltaT<br/>reserves -= deltaR<br/>credit rewards]
    RUPD --> SNAP[SNAP<br/>Rotate mark → set → go<br/>Capture current fees]
    SNAP --> POOLREAP[POOLREAP<br/>Process pool retirements<br/>Refund deposits]
    POOLREAP --> RAT[RATIFY<br/>Governance ratification<br/>Enact approved actions]
    RAT --> RESET[Reset block counters<br/>Clear RUPD state]

Reward Distribution (RUPD)

Rewards follow a deferred schedule matching Haskell's pulsing reward computation:

1. Epoch E → E+1: Compute RUPD (monetary expansion + fees - treasury cut)
2. Epoch E+1 → E+2: Apply RUPD (credit rewards to accounts, update treasury/reserves)

The reward calculation uses the "go" snapshot (two epochs old) for stake distribution, ensuring a stable base for computation.

Stake Snapshots

The mark/set/go model ensures different subsystems use consistent, non-overlapping snapshots:

UTxO Storage

UtxoStore

The persistent UTxO set wraps a dugite-lsm LSM tree:

• 36-byte keys — 32-byte transaction hash + 4-byte output index (big-endian)
• Bincode values — TransactionOutput serialized via bincode
• Address index — In-memory HashMap<Address, HashSet<TransactionInput>> for N2C LocalStateQuery GetUTxOByAddress efficiency
• Bloom filters — 10 bits per key (~1% false positive rate) for fast negative lookups during validation

DiffSeq (Rollback Support)

Each block produces a UtxoDiff recording inserted and deleted UTxOs. The DiffSeq holds the last k=2160 diffs, enabling O(1) rollback by applying diffs in reverse without reloading snapshots.

LedgerSeq (Anchored State Sequence)

LedgerSeq implements Haskell's V2 LedgerDB architecture:

• Anchor — One full LedgerState at the immutable tip (persisted to disk)
• Volatile deltas — Per-block LedgerDelta for the last k blocks
• Checkpoints — Full state snapshots every ~100 blocks for fast reconstruction
• Rollback — Drop trailing deltas and reconstruct from the nearest checkpoint

This avoids the 17-34 GB memory overhead of storing k full state copies.

CompositeUtxoView (Mempool Support)

All validate_transaction_* functions accept any UtxoLookup implementation. The CompositeUtxoView layers a mempool overlay on top of the on-chain UTxO set, enabling validation of chained mempool transactions (where one tx spends outputs of another unconfirmed tx) without mutating the live ledger state.

Consensus

Dugite implements the Ouroboros Praos consensus protocol, the proof-of-stake protocol used by Cardano since the Shelley era.

Ouroboros Praos Overview

Ouroboros Praos divides time into fixed-length slots. Each slot, a slot leader is selected based on their stake proportion. The leader is entitled to produce a block for that slot. Key properties:

• Slot-based — Time is divided into slots (1 second each on mainnet)
• Epoch-based — Slots are grouped into epochs (432000 slots / 5 days on mainnet)
• Stake-proportional — The probability of being elected is proportional to the pool's active stake
• Private leader selection — Only the pool operator knows if they are elected (until they publish the block)

Slot Leader Election

VRF-Based Selection

Each slot, the pool operator evaluates a VRF (Verifiable Random Function) using:

• Their VRF signing key
• The slot number
• The epoch nonce

The VRF produces:

1. A VRF output — A deterministic pseudo-random value
2. A VRF proof — A proof that the output was correctly computed

Leader Threshold

The VRF output is compared against a threshold derived from:

• The pool's relative stake (sigma)
• The active slot coefficient (f = 0.05 on mainnet)

The threshold is computed using the phi function:

phi(sigma) = 1 - (1 - f)^sigma

A slot leader is elected if VRF_output < phi(sigma).

VRF Exact Rational Arithmetic

The leader check is a critical consensus operation — any deviation from the Haskell reference implementation would cause a node to disagree on which blocks are valid. Dugite uses exact 34-digit fixed-point arithmetic via dashu-int IBig, matching Haskell's FixedPoint E34 type exactly. No floating-point operations are used anywhere in the VRF computation path.

Era-dependent VRF modes:

In TPraos mode (Shelley through Alonzo), the raw 64-byte VRF output is used directly for the leader check, with a certNatMax of 2^512 defining the output space. In Praos mode (Babbage onward), the VRF output is hashed with Blake2b-256("L" || output) to produce a 32-byte value, reducing certNatMax to 2^256. The "L" prefix distinguishes the leader VRF output from the nonce VRF output (which uses "N").

Mathematical primitives:

• ln(1 + x) — Uses the Euler continued fraction expansion, matching Haskell's lncf function. This converges for all x >= 0, unlike Taylor series which has a limited radius of convergence.
• taylorExpCmp — Computes exp() via Taylor series with rigorous error bounds, enabling early termination when the comparison result can be determined without computing the full expansion. This avoids unnecessary precision in the common case where the VRF output is far from the threshold.

Epoch Nonce

The epoch nonce is computed at each epoch boundary:

epoch_nonce = hash(candidate_nonce || lab_nonce)

Where:

• candidate_nonce is the evolving nonce frozen at the stability window boundary of the previous epoch
• lab_nonce is a hash derived from the previous epoch's first block (the "laboratory" nonce)

The initial nonce is derived from the Shelley genesis hash.

Nonce Establishment

The nonce lifecycle follows a precise sequence across epoch boundaries:

1. Evolving nonce — Accumulates VRF nonce contributions from every block: evolving_nonce = hash(prev_evolving_nonce || hash(vrf_nonce_output))
2. Candidate nonce — The evolving nonce is frozen (snapshotted) at the stability window boundary within each epoch. After this point, new VRF contributions only affect the evolving nonce, not the candidate.
3. Epoch nonce — At the epoch boundary, the new epoch nonce is computed as hash(candidate_nonce_from_prev_epoch || lab_nonce).

flowchart LR
    A["Block VRF<br/>contributions"] -->|"accumulated<br/>every block"| B["Evolving<br/>Nonce"]
    B -->|"frozen at<br/>stability window"| C["Candidate<br/>Nonce"]
    C -->|"hash(candidate ∥ lab)"| D["Epoch Nonce<br/>(next epoch)"]

Nonce availability after startup:

The epoch nonce and its accumulators (evolving_nonce, candidate_nonce, last_epoch_block_nonce) are serialized in the ledger snapshot and considered authoritative immediately after a snapshot load or Mithril import. This matches Haskell cardano-node's treatment of praosStateEpochNonce, which is read directly from the deserialized PraosState with no warm-up or "established" gate.

Era-Dependent Nonce Stabilisation Window

The stability window determines how early in an epoch the candidate nonce is frozen. This varies by era:

Where k is the security parameter (2160 on mainnet) and f is the active slot coefficient (0.05 on mainnet). The longer Conway window provides additional time for nonce contributions to accumulate, improving randomness quality.

Chain Selection

When multiple valid chains exist, Ouroboros Praos selects the chain with the most blocks (longest chain rule). Dugite implements:

1. Chain comparison — Compare the block height of competing chains
2. Rollback support — Roll back up to k=2160 blocks to switch to a longer chain
3. Immutability — Blocks deeper than k are considered final

Epoch Transitions

At each epoch boundary, Dugite performs:

Stake Snapshot Rotation

Dugite uses the mark/set/go snapshot model:

• Mark — The current epoch boundary snapshot (will be used for leader election two epochs from now)
• Set — The previous epoch's mark (used for leader election in the current epoch)
• Go — Two epochs ago (used for reward distribution in the current epoch)

At each epoch boundary:

1. Go becomes the active snapshot for reward distribution
2. Set moves to go
3. Mark moves to set
4. A new mark is taken from the current ledger state

flowchart LR
    subgraph "Epoch N Boundary"
        direction TB
        L["Current Ledger<br/>State"] -->|"snapshot"| M["Mark"]
        M -->|"rotate"| S["Set"]
        S -->|"rotate"| G["Go"]
    end
    S -.- LE["Leader Election<br/>(epoch N)"]
    G -.- RD["Reward Distribution<br/>(epoch N)"]

Snapshot Establishment

After a node starts, the snapshots are not immediately trustworthy for block production:

• snapshots_established requires at least 3 live (post-replay) epoch transitions before returning true. This ensures that all three snapshot positions (mark, set, go) have been populated by the running node with precise stake calculations.
• Replay-built snapshots may contain approximate stake values due to differences in reward calculation during fast replay versus live operation. These are sufficient for validation but not authoritative for forging.
• VRF leader eligibility failures are non-fatal until snapshots are fully established. During the establishment period, a pool may fail leader checks because the stake distribution in the snapshot does not yet reflect the true on-chain state. The node logs these failures but continues normal operation.

Reward Calculation and Distribution

At each epoch boundary, rewards are calculated and distributed:

1. Monetary expansion — New ADA is created from the reserves based on the monetary expansion rate
2. Fee collection — Transaction fees from the epoch are collected
3. Treasury cut — A fraction (tau) of rewards goes to the treasury
4. Pool rewards — Remaining rewards are distributed to pools based on their performance
5. Member distribution — Pool rewards are split between the operator and delegators based on pool parameters (cost, margin, pledge)

Validation Checks

Dugite validates the following consensus-level properties:

KES Period Validation

The KES (Key Evolving Signature) period in the block header must be within the valid range for the operational certificate:

opcert_start_kes_period <= current_kes_period < opcert_start_kes_period + max_kes_evolutions

VRF Verification

Full VRF verification includes:

1. VRF key binding — blake2b_256(header.vrf_vkey) must match the pool's registered vrf_keyhash
2. VRF proof verification — The VRF proof is cryptographically verified against the VRF public key
3. Leader eligibility — The VRF leader value is checked against the Praos threshold for the pool's relative stake using the phi function

Operational Certificate Verification

The operational certificate's Ed25519 signature is verified against the raw bytes signable format (matching Haskell's OCertSignable):

signable = hot_vkey(32 bytes) || counter(8 bytes BE) || kes_period(8 bytes BE)
signature = sign(cold_skey, signable)

The counter must be monotonically increasing per pool to prevent certificate replay.

KES Signature Verification

Block headers are signed using the Sum6Kes scheme (depth-6 binary sum composition over Ed25519). The KES key is evolved to the correct period offset from the operational certificate's start period. Verification checks:

1. The KES signature over the header body bytes is valid
2. The KES period matches the expected value for the block's slot

Slot Leader Eligibility

The VRF proof is checked to confirm the block producer was indeed elected for the slot, given the epoch nonce and their pool's stake.

Networking

Dugite implements the full Ouroboros network protocol stack, supporting both Node-to-Node (N2N) and Node-to-Client (N2C) communication.

Protocol Stack

flowchart TB
    subgraph N2N ["Node-to-Node (TCP)"]
        HS[Handshake V14/V15]
        CSP[ChainSync<br/>Headers]
        BFP[BlockFetch<br/>Block Bodies]
        TX[TxSubmission2<br/>Transactions]
        KA[KeepAlive<br/>Liveness]
    end

    subgraph N2C ["Node-to-Client (Unix Socket)"]
        HSC[Handshake]
        LCS[LocalChainSync<br/>Block Delivery]
        LSQ[LocalStateQuery<br/>Ledger Queries]
        LTS[LocalTxSubmission<br/>Submit Transactions]
        LTM[LocalTxMonitor<br/>Mempool Queries]
    end

    MUX[Multiplexer] --> N2N
    MUX --> N2C

Relay Node Architecture

flowchart TB
    subgraph Inbound ["Inbound Connections"]
        IN1[Peer A] -->|N2N| MUX_IN[Multiplexer]
        IN2[Peer B] -->|N2N| MUX_IN
        IN3[Wallet] -->|N2C| MUX_N2C[N2C Server]
    end

    subgraph Outbound ["Outbound Connections"]
        MUX_OUT[Multiplexer] -->|ChainSync| PEER1[Bootstrap Peer]
        MUX_OUT -->|BlockFetch| PEER1
        MUX_OUT -->|TxSubmission| PEER1
    end

    subgraph Core ["Node Core"]
        PM[Peer Manager<br/>Cold→Warm→Hot]
        MP[Mempool<br/>Tx Validation]
        CDB[(ChainDB)]
        LS[Ledger State]
        CONS[Consensus<br/>Ouroboros Praos]
    end

    MUX_IN -->|ChainSync| CDB
    MUX_IN -->|BlockFetch| CDB
    MUX_IN -->|TxSubmission| MP
    MUX_N2C -->|LocalStateQuery| LS
    MUX_N2C -->|LocalTxSubmission| MP
    MUX_N2C -->|LocalTxMonitor| MP

    PEER1 -->|blocks| CDB
    CDB --> LS
    LS --> CONS
    PM -->|manage| MUX_OUT
    PM -->|manage| MUX_IN

Node-to-Node (N2N) Protocol

N2N connections use TCP and carry multiple mini-protocols over a multiplexed connection.

Handshake (V14/V15)

The N2N handshake negotiates the protocol version and network parameters:

• Protocol version V14 (Plomin HF) and V15 (SRV DNS support)
• Network magic number
• Diffusion mode: InitiatorOnly or InitiatorAndResponder
• Peer sharing flags

ChainSync

The ChainSync mini-protocol synchronizes block headers between peers:

• Client mode: Requests headers sequentially from a peer to track the chain
• Server mode: Serves headers to connected peers, with per-peer cursor tracking

Key messages:

• MsgFindIntersect — Find a common chain point
• MsgRequestNext — Request the next header
• MsgRollForward — Header delivered
• MsgRollBackward — Chain reorganization
• MsgAwaitReply — Peer has no new headers (at tip)

BlockFetch

The BlockFetch mini-protocol retrieves block bodies by hash:

• Client mode: Requests ranges of blocks from peers
• Server mode: Serves blocks to peers, validates block existence before serving

Key messages:

• MsgRequestRange — Request blocks in a slot range
• MsgBlock — Block delivered
• MsgNoBlocks — Requested blocks not available
• MsgBatchDone — End of batch

TxSubmission2

The TxSubmission2 mini-protocol propagates transactions between peers:

• Bidirectional handshake (MsgInit)
• Flow-controlled transaction exchange with ack/req counts
• Inflight tracking per peer
• Mempool integration for serving transaction IDs and bodies

KeepAlive

The KeepAlive mini-protocol maintains connection liveness with periodic heartbeat messages.

PeerSharing

The PeerSharing mini-protocol enables gossip-based peer discovery. Peers exchange addresses of other known peers to help the network self-organize.

Node-to-Client (N2C) Protocol

N2C connections use Unix domain sockets and serve local clients (wallets, CLI tools). The N2C handshake supports versions V16-V22 (Conway era) with automatic detection of the Haskell bit-15 version encoding used by cardano-cli 10.x.

LocalStateQuery

Supports all 39 Shelley BlockQuery tags (0-38) plus cross-era queries, providing full compatibility with cardano-node. The query protocol uses an acquire/query/release pattern:

1. MsgAcquire — Lock the ledger state at the current tip
2. MsgQuery — Execute queries against the locked state
3. MsgRelease — Release the lock

All BlockQuery messages are wrapped in the Hard Fork Combinator (HFC) envelope. Results from era-specific BlockQuery tags are returned inside an array(1) success wrapper, while QueryAnytime and QueryHardFork results are returned unwrapped.

Shelley BlockQuery Tags 0-38

Cross-Era Queries

In addition to the Shelley BlockQuery tags, the following queries operate outside the HFC era-specific envelope:

CBOR Encoding Notes

• PParams are encoded as a positional array(31) with integer keys 0-33, matching Haskell's EncCBOR instance (not JSON string keys).
• CBOR Sets (e.g., pool IDs, stake key owners) use tag(258) and elements must be sorted for canonical encoding.
• Value encoding: plain integer for ADA-only UTxOs, [coin, multiasset_map] for multi-asset UTxOs.

LocalTxSubmission

Submits transactions from local clients to the node's mempool:

Submitted transactions undergo both Phase-1 (structural) and Phase-2 (Plutus script) validation before mempool admission.

LocalTxMonitor

Monitors the transaction mempool:

P2P Networking

Dugite implements the full Ouroboros P2P peer selection governor, enabled by default (EnableP2P: true). The governor manages peer connections through a target-driven state machine that continuously maintains optimal connectivity.

Diffusion Mode

The DiffusionMode config field controls how the node participates in the network:

• InitiatorAndResponder (default) — Full relay mode. The node opens a listening port and accepts inbound N2N connections from other peers, in addition to making outbound connections. This is the correct mode for relay nodes.
• InitiatorOnly — Block producer mode. The node only makes outbound connections to its configured relays and never opens a listening port. This prevents direct internet exposure of block producers.

Peer Sharing

The PeerSharing mini-protocol enables gossip-based peer discovery. When enabled, the node exchanges addresses of known routable peers with connected peers.

Peer sharing behaviour is auto-configured by default:

• Relays — Peer sharing is enabled, allowing the node to both request and serve peer addresses.
• Block producers — Peer sharing is disabled (when --shelley-kes-key is provided) to avoid leaking the BP's network position.

Override with the PeerSharing config field (true/false) if needed.

The PeerSharing protocol filters out non-routable addresses (RFC1918, CGNAT, loopback, link-local, IPv6 ULA) before sharing.

Peer Manager

The peer manager classifies peers into three temperature categories following the cardano-node model:

• Cold — Known but not connected
• Warm — TCP connected, keepalive running, but not actively syncing
• Hot — Fully active with ChainSync, BlockFetch, and TxSubmission2

Peer Lifecycle

stateDiagram-v2
    [*] --> Cold: Discovered
    Cold --> Warm: TCP connect + handshake
    Warm --> Hot: Mini-protocols activated (5s dwell)
    Hot --> Warm: Demotion (poor performance / churn)
    Warm --> Cold: Disconnection / backoff
    Cold --> [*]: Evicted (max failures)

Warm peers must dwell for at least 5 seconds before promotion to Hot, preventing rapid cycling.

Peer Sources

Peers enter the Cold pool from four sources:

Peer Selection & Scoring

Peers are ranked using a composite score:

score = 0.4 × reputation + 0.4 × latency_score + 0.2 × failure_score

Where:

• Reputation — 0.0 (worst) to 1.0 (best), adjusted +0.01 per success, -0.1 per failure
• Latency score — 1 / (1 + ms/200), based on EWMA latency (smoothing α=0.3)
• Failure score — max(1.0 - failures×0.1, 0.0), failure counts decay (halve every 5 minutes)

Subnet diversity is enforced: peers from the same /24 (IPv4) or /48 (IPv6) subnet receive a selection penalty.

Failure Handling

• Exponential backoff on connection failures: 5s → 10s → 20s → 40s → 80s → 160s (capped), with ±2s random fuzz
• Max cold failures: 5 consecutive failures before a peer is evicted from the peer table
• Failure decay: Failure counts halve every 5 minutes, allowing peers to recover reputation over time
• Circuit breaker: Closed → Open → HalfOpen with exponential cooldown

Inbound Connections

• Per-IP token bucket rate limiting for DoS protection
• N2N server handles handshake, ChainSync, BlockFetch, KeepAlive, TxSubmission2, and PeerSharing
• DiffusionMode controls whether inbound connections are accepted

P2P Governor

The governor runs as a tokio task on a 30-second interval, continuously evaluating peer counts against configured targets and emitting promotion/demotion/connect/disconnect actions.

Target Counts

The governor maintains six independent target counts (matching cardano-node defaults):

When any target is not met, the governor promotes peers to fill the deficit. When any target is exceeded, the governor demotes the lowest-scoring surplus peers. Local root peers are never demoted.

Sync-State-Aware Targeting

The governor adjusts behaviour based on sync state:

• PreSyncing / Syncing — Big ledger peers are prioritised for fast block download
• CaughtUp — Normal target enforcement with balanced peer selection

Churn

The governor periodically rotates a subset of peers to discover better alternatives:

• Configurable churn interval (default: 20% target reduction cycle)
• Local root peers are exempt from churn
• Churn ensures the node explores the peer landscape rather than settling on suboptimal connections

Prometheus Metrics

The P2P subsystem exports the following metrics:

Peer Discovery

Peers are discovered through multiple channels:

1. Topology file — Bootstrap peers, local roots, and public roots
2. PeerSharing protocol — Gossip-based discovery from connected peers
3. Ledger-based discovery — SPO relay addresses extracted from pool registration certificates

Ledger-Based Peer Discovery

Once the node has synced past the slot threshold configured by useLedgerAfterSlot in the topology file, it activates ledger-based peer discovery. This mechanism extracts SPO relay addresses directly from pool registration parameters (pool_params) stored in the ledger state.

The discovery process runs on a periodic 5-minute interval and works as follows:

1. Slot check — The current ledger tip slot is compared against useLedgerAfterSlot. If the topology sets this value to a negative number or omits it entirely, ledger peer discovery remains disabled.
2. Relay extraction — All registered pool parameters are iterated, extracting relay entries of three types:
   • SingleHostAddr — IPv4 address and port
   • SingleHostName — DNS hostname and port
   • MultiHostName — DNS hostname with default port 3001
3. Sampling — A deterministic subset (up to 20 relays) is sampled from the full relay set to avoid resolving thousands of addresses at once. The sample offset rotates based on the current slot for coverage diversity.
4. DNS resolution — Hostnames are resolved to socket addresses via async DNS lookup.
5. Peer manager integration — Resolved addresses are added as cold peers with PeerSource::Ledger classification, alongside existing bootstrap and public root peers.

As pool registrations change over time (new pools register, existing pools update relay addresses, pools retire), the ledger peer set evolves dynamically. This provides a protocol-native discovery mechanism that does not depend on any centralized directory.

Block Relay

Dugite implements full relay node behavior, propagating blocks received from upstream peers to all downstream N2N connections. This ensures that blocks flow through the network without requiring every node to sync directly from the block producer.

Broadcast Architecture

Block propagation uses a tokio::sync::broadcast channel with a capacity of 64 announcements. The architecture has three components:

1. Sender — The node core holds a broadcast::Sender<BlockAnnouncement> obtained from the N2N server at startup. When the sync pipeline processes new blocks or the forge module produces a new block, it sends an announcement containing the slot, block hash, and block number.
2. Receivers — Each N2N server connection spawns with its own broadcast::Receiver subscription. The connection handler uses tokio::select! to concurrently service mini-protocol messages and listen for block announcements.
3. Delivery — When a downstream peer is waiting at the tip (having received MsgAwaitReply from ChainSync), an incoming block announcement triggers a MsgRollForward message to that peer, along with the block header. The peer can then fetch the full block body via BlockFetch.

Relay vs. Forger Announcements

Both synced and forged blocks flow through the same broadcast channel:

• Synced blocks — When the pipelined ChainSync client receives blocks from an upstream peer and the node is following the tip (strict mode), each batch's final block is announced to all downstream connections. This enables relay behavior where blocks received from one upstream peer propagate to all other connected peers.
• Forged blocks — When the block producer creates a new block, it is announced through the same channel after being written to ChainDB and applied to the ledger.

A parallel broadcast::Sender<RollbackAnnouncement> handles chain rollbacks, sending MsgRollBackward to downstream peers when the node's chain selection switches to a different fork.

Lagged Receivers

If a downstream peer falls behind (e.g., slow network or processing), the broadcast channel's bounded capacity means the receiver may lag. Lagged receivers skip missed announcements and log the gap, ensuring a slow peer does not block propagation to others.

Multiplexer

All mini-protocols run over a single TCP connection (N2N) or Unix socket (N2C), multiplexed by protocol ID:

The multiplexer uses length-prefixed frames with protocol ID headers, matching the Ouroboros specification.

P2P Governor

This document describes Dugite's peer management architecture, implementing the Ouroboros P2P peer selection governor.

Architecture

Two modules implement peer management in dugite-network:

PeerManager (peer_manager.rs)

The data layer. Tracks every known peer in a flat HashMap<SocketAddr, PeerInfo> together with three HashSets for the cold/warm/hot buckets.

Governor (governor.rs)

The policy layer. Runs on a 30-second tokio::interval in dugite-node.

Wiring

The governor runs as a standalone tokio::spawn task in node/mod.rs. Every 30 seconds it:

1. Acquires a read lock on Arc<RwLock<PeerManager>> and calls governor.evaluate() and governor.maybe_churn().
2. Acquires a write lock and applies the resulting GovernorEvents by calling promote_to_hot, demote_to_warm, peer_disconnected, and recompute_reputations.
3. GovernorEvent::Connect is acknowledged but not executed here — outbound connections originate from the main connection loop via peers_to_connect().

Peer Selection State Machine

Peers progress through a formal state machine:

stateDiagram-v2
    [*] --> Cold
    Cold --> Warm: TCP connect + handshake
    Warm --> Hot: Activate mini-protocols
    Hot --> Warm: Deactivate mini-protocols
    Warm --> Cold: Disconnect
    Hot --> Cold: Forceful disconnect

Target Counts

The governor maintains six independent target counts:

When any target is not met, the governor attempts to satisfy the deficit. When any target is exceeded, surplus peers are demoted by lowest reputation.

Local Root Peer Pinning

Local root peers (from localRoots in the topology file) have pinned targets that override the normal target counts. Local roots are never demoted for surplus reduction and are never churned.

Churn

The governor performs periodic churn to rotate peers:

• Deadline churn (normal mode) — Approximately every 55 minutes, a fraction of established and active peers are replaced.
• Bulk sync churn — During active block download, churn cycles are more aggressive (~15 minutes) to shed peers with poor block-fetch performance.

Big Ledger Peer Preference During Sync

Big ledger peers (SPOs in the top 90% of stake, obtained via GetLedgerPeerSnapshot) serve as trusted anchors during bulk block download. The governor maintains a separate target bucket for BLPs. When SyncState is Syncing or PreSyncing, BLP targets take priority.

Thread Safety

The PeerManager is wrapped in Arc<RwLock<PeerManager>>. The governor task acquires a read lock for evaluate() and a write lock only for event application, keeping the write-lock window minimal.

Files

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

Recommended Deployment

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 ...

Protocol Parameters Reference

Cardano protocol parameters control the behavior of the network, including fees, block sizes, staking mechanics, and governance. These parameters can be queried from a running node and updated through governance actions.

Querying Parameters

dugite-cli query protocol-parameters \
  --socket-path ./node.sock \
  --out-file protocol-params.json

Fee Parameters

The transaction fee formula is:

fee = txFeePerByte * tx_size_in_bytes + txFeeFixed

Block Size Parameters

Staking Parameters

Monetary Policy

Plutus Execution Parameters

Governance Parameters (Conway)

Voting Thresholds

Different governance action types require different voting thresholds from DReps, SPOs, and the Constitutional Committee:

CBOR Field Numbers

When encoding protocol parameter updates in governance actions, each parameter maps to a CBOR field number:

Cardano Mini-Protocol Reference

This document is the definitive implementation reference for every Cardano mini-protocol used in node-to-node (N2N) and node-to-client (N2C) communication. It covers the complete state machine, exact CBOR wire format, timing constraints, flow-control rules, and every protocol-error condition for each protocol. The information is derived directly from the Haskell source in the IntersectMBO/ouroboros-network repository.

Connection Model and Multiplexer

All mini-protocols share a single TCP connection per peer, multiplexed by the network-mux layer using 8-byte SDU headers:

  Bytes  Field
  -----  -----
   0-3   timestamp (u32, microseconds, used for RTT measurement)
   4-5   mini_protocol_num (u16)
     6   flags (bit 0 = direction: 0=initiator, 1=responder)
   7-8   payload_length (u16, max 65535)

Large messages are fragmented across multiple SDUs transparently. Handshake (protocol 0) runs on the raw socket before the mux is started.

Key invariant: if any single mini-protocol thread throws an exception, the entire mux — and therefore the entire TCP connection — is torn down. Protocol errors are fatal to the connection, not just to the affected mini-protocol.

Sources:

• ouroboros-network/network-mux/src/Network/Mux/Types.hs
• ouroboros-network/network-mux/src/Network/Mux/Egress.hs

Shared Encoding Primitives

These types are used identically across all protocols.

Point

A Point identifies a position on the chain by slot and header hash.

; CBOR encoding (Haskell: encodePoint / decodePoint)
point = []                         ; Origin — empty definite-length list
      / [slot_no, header_hash]     ; At(slot, hash) — definite-length list of 2

slot_no     = uint     ; word64
header_hash = bstr     ; 32 bytes (Blake2b-256 of header)

Source: ouroboros-network/ouroboros-network/api/lib/Ouroboros/Network/Block.hs

Tip

A Tip is the chain tip as seen by the server. It is a (Point, BlockNo) pair.

; N2N ChainSync / N2C LocalChainSync
tip = [slot_no, header_hash, block_no]   ; At(pt, blockno)
    / [0]                                ; TipGenesis (Origin point, blockno=0)

block_no = uint   ; word64

Source: ouroboros-network/ouroboros-network/api/lib/Ouroboros/Network/Block.hs (encodeTip / decodeTip)

Byte and Time Limit Constants

These constants appear in state-machine timeout and size-limit tables throughout this document.

Source: ouroboros-network/ouroboros-network/api/lib/Ouroboros/Network/Protocol/Limits.hs

N2N Mini-Protocol IDs

N2C Mini-Protocol IDs

Protocol Temperatures (N2N)

Protocol temperature determines when each N2N mini-protocol is started during the peer lifecycle (cold → warm → hot).

Hot protocols use StartOnDemand for the responder side (they wait for the first inbound byte). Initiator sides are started eagerly by startProtocols.

Source: ouroboros-network/cardano-diffusion/lib/Cardano/Network/Diffusion/Peer/

N2N Protocol 0: Handshake

Identity

• Protocol ID: 0 (runs on raw socket bearer before mux starts)
• Direction: Initiator sends MsgProposeVersions, responder replies
• Versions: V14 (Plomin HF, mandatory since 2025-01-29), V15 (SRV DNS)

State Machine

StPropose  (ClientAgency)  -- initiator has agency
    │
    │ MsgProposeVersions
    ▼
StConfirm  (ServerAgency)  -- server chooses version
    │
    ├─── MsgAcceptVersion ──→ StDone
    ├─── MsgRefuse        ──→ StDone
    └─── MsgQueryReply    ──→ StDone

Terminal state: StDone — connection is closed after handshake completes (for N2N; the mux then starts).

Wire Format

Source: ouroboros-network/ouroboros-network/framework/lib/Ouroboros/Network/Protocol/Handshake/Codec.hs and cardano-diffusion/protocols/cddl/specs/handshake-node-to-node-v14.cddl

; Every handshake message is a definite-length CBOR array.
MsgProposeVersions = [0, versionTable]
MsgAcceptVersion   = [1, versionNumber, versionData]
MsgRefuse          = [2, refuseReason]
MsgQueryReply      = [3, versionTable]

; versionTable is a CBOR definite-length MAP (not an array).
; Keys are encoded in ascending order.
versionTable = { * versionNumber => versionData }

; N2N version numbers implemented by Dugite (V14=14, V15=15)
; Note: N2N does NOT set bit-15. Only N2C uses bit-15.
; V16 (adds perasSupport) is defined in the Peras spec but not yet implemented.
versionNumber = 14 / 15

; Version data for V14/V15: 4-element array
versionData_v14 = [networkMagic, initiatorOnly, peerSharing, query]

networkMagic = uint .size 4   ; word32 (mainnet=764824073, preview=2, preprod=1)
initiatorOnly = bool           ; true=InitiatorOnly, false=InitiatorAndResponder
peerSharing   = 0 / 1          ; 0=Disabled, 1=Enabled
query         = bool

refuseReason
  = [0, [* versionNumber]]           ; VersionMismatch
  / [1, versionNumber, tstr]         ; HandshakeDecodeError
  / [2, versionNumber, tstr]         ; Refused

Version Negotiation Rules

Source: cardano-diffusion/api/lib/Cardano/Network/NodeToNode/Version.hs

• The responder picks the highest version number that appears in both the initiator's and responder's version tables.
• If no common version: MsgRefuse with VersionMismatch.
• networkMagic must match exactly; mismatch → MsgRefuse with Refused.
• initiatorOnlyDiffusionMode = min(local, remote) — more restrictive wins (i.e., InitiatorOnly if either side is).
• peerSharing = local <> remote (Semigroup): both must be Enabled for Enabled; any Disabled results in Disabled. InitiatorOnly nodes automatically have Disabled.
• query = local || remote (logical OR).

MsgQueryReply Semantics

When the initiator sends MsgProposeVersions with query=true, the responder must reply with MsgQueryReply (a copy of its own version table) and then close the connection. This is used by cardano-cli for version probing. The mux never starts in this case.

Timeout

Handshake SDU read/write: 10 seconds per SDU. There is no per-state timeout beyond this; the handshake exchange must complete within one SDU read cycle on each side.

N2N Protocol 2: ChainSync

Identity

• Protocol ID: 2
• Temperature: Hot (started on warm→hot promotion)
• Direction: N2N ChainSync streams block headers only (not full blocks). Full blocks are fetched via BlockFetch.
• Versions: All N2N versions (V7+)

State Machine

Source: ouroboros-network/ouroboros-network/protocols/lib/Ouroboros/Network/Protocol/ChainSync/Type.hs

StIdle       (ClientAgency)  -- client requests next update or intersect
    │
    ├─── MsgRequestNext      ──→ StNext(StCanAwait)
    ├─── MsgFindIntersect    ──→ StIntersect
    └─── MsgDone             ──→ StDone

StNext(StCanAwait)  (ServerAgency)  -- server can immediately reply or defer
    │
    ├─── MsgAwaitReply       ──→ StNext(StMustReply)
    ├─── MsgRollForward      ──→ StIdle
    └─── MsgRollBackward     ──→ StIdle

StNext(StMustReply)  (ServerAgency)  -- server MUST reply (already sent await)
    │
    ├─── MsgRollForward      ──→ StIdle
    └─── MsgRollBackward     ──→ StIdle

StIntersect  (ServerAgency)  -- server searching for intersection
    │
    ├─── MsgIntersectFound   ──→ StIdle
    └─── MsgIntersectNotFound ─→ StIdle

StDone (NobodyAgency)

Critical invariant: MsgAwaitReply is only valid in state StNext(StCanAwait). The server transitions to StNext(StMustReply) after sending it. Sending MsgAwaitReply when the client sent a non-blocking variant (Pipeline rather than Request) or when the server has already sent MsgAwaitReply this round is a protocol error (ProtocolErrorRequestNonBlocking). The typed-protocol framework enforces this at compile time; a Rust implementation must enforce it at runtime by tracking which sub-state of StNext is current.

Wire Format

Source: ouroboros-network/ouroboros-network/protocols/lib/Ouroboros/Network/Protocol/ChainSync/Codec.hs and cardano-diffusion/protocols/cddl/specs/chain-sync.cddl

MsgRequestNext        = [0]
MsgAwaitReply         = [1]
MsgRollForward        = [2, header, tip]
MsgRollBackward       = [3, point, tip]
MsgFindIntersect      = [4, points]
MsgIntersectFound     = [5, point, tip]
MsgIntersectNotFound  = [6, tip]
MsgDone               = [7]

; points is a DEFINITE-length array (not indefinite)
points = [* point]

N2N header encoding in MsgRollForward: For the CardanoBlock HFC block type, the header is wrapped as:

header = [era_index, serialised_header_bytes]

where era_index is 0=Byron, 1=Shelley, ..., 6=Conway, 7=Dijkstra (see TxSubmission2 section for full table), and serialised_header_bytes is tag(24)(bstr(cbor_encoded_header)) — CBOR-in-CBOR wrapping via wrapCBORinCBOR.

Source: ouroboros-consensus/ouroboros-consensus-cardano/src/shelley/Ouroboros/Consensus/Shelley/Node/Serialisation.hs

Pipelining

Source: ouroboros-network/ouroboros-network/protocols/lib/Ouroboros/Network/Protocol/ChainSync/PipelineDecision.hs

ChainSync uses the pipelineDecisionLowHighMark strategy with default marks lowMark=200, highMark=300 (Dugite uses configurable depth via DUGITE_PIPELINE_DEPTH, default 300).

pipelineDecisionLowHighMark :: Word16 -> Word16 -> MkPipelineDecision

Decision logic (given n outstanding requests, clientTip, serverTip):

• n=0, clientTip == serverTip → Request (non-pipelined, triggers await semantics)
• n=0, clientTip < serverTip → Pipeline
• n>0, clientTip + n >= serverTip → Collect (we're caught up, stop pipelining)
• n >= highMark → Collect (high-water: drain before adding more)
• n < lowMark → CollectOrPipeline (can collect or pipeline)
• n >= lowMark → Collect (above low mark in high state)

When n=0 and clientTip == serverTip: the client sends a non-pipelined Request, the server is at its tip and sends MsgAwaitReply (valid because the client sent a blocking request). This is the "at tip" steady state.

Timing

Source: ouroboros-network/cardano-diffusion/protocols/lib/Cardano/Network/Protocol/ChainSync/Codec/TimeLimits.hs

The random range for untrusted StMustReply corresponds to streak-of-empty-slots probabilities between 99.9% and 99.9999% at f=0.05.

Default ChainSyncIdleTimeout = 3373 seconds. Source: cardano-diffusion/lib/Cardano/Network/Diffusion/Configuration.hs:defaultChainSyncIdleTimeout

Ingress Queue Limit

highMark × 1400 bytes × 1.1 safety factor

With highMark=300: approximately 462 000 bytes.

N2N Protocol 3: BlockFetch

Identity

• Protocol ID: 3
• Temperature: Hot
• Purpose: Bulk download of full block bodies, driven by the BlockFetch decision logic after ChainSync supplies candidate chain headers.

State Machine

Source: ouroboros-network/ouroboros-network/protocols/lib/Ouroboros/Network/Protocol/BlockFetch/Type.hs

BFIdle      (ClientAgency)  -- client decides what to fetch
    │
    ├─── MsgRequestRange  ──→ BFBusy
    └─── MsgClientDone    ──→ BFDone

BFBusy      (ServerAgency)  -- server preparing batch
    │
    ├─── MsgStartBatch    ──→ BFStreaming
    └─── MsgNoBlocks      ──→ BFIdle

BFStreaming  (ServerAgency)  -- server streaming blocks
    │
    ├─── MsgBlock         ──→ BFStreaming  (self-loop, one block per message)
    └─── MsgBatchDone     ──→ BFIdle

BFDone (NobodyAgency)