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 uplc CEK machine.
• 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, ledger-based peer discovery, and inbound rate limiting.
• 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, container images, or built from source.

Pre-built Binaries

Download the latest release from GitHub Releases:

# 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

Multi-architecture container images (amd64 and arm64) are published to GitHub Container Registry:

docker pull ghcr.io/michaeljfazio/dugite:latest

The image uses a distroless base (gcr.io/distroless/cc-debian12:nonroot) for minimal attack surface — no shell, no package manager, runs as nonroot (UID 65532).

Run the node:

docker run -d \
  --name dugite \
  -p 3001:3001 \
  -p 12798:12798 \
  -v dugite-data:/opt/dugite/db \
  ghcr.io/michaeljfazio/dugite:latest

See Kubernetes Deployment for production container deployments.

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

docker pull ghcr.io/michaeljfazio/dugite:latest

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 the config/ directory:

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 with Docker:

docker run -d \
  --name dugite \
  -p 3001:3001 \
  -p 12798:12798 \
  -v dugite-data:/opt/dugite/db \
  ghcr.io/michaeljfazio/dugite:latest

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

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": 40,
  "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 40
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
}

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

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 the pallas 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.

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/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
./scripts/start-monitoring.sh

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

# Check status
./scripts/start-monitoring.sh status

# Stop
./scripts/start-monitoring.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/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/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/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.

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 peers_connected metrics on relays and BP
   • Monitor blocks_forged 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 block producer, all on the same machine, all on the loopback interface — both BPs connect to the network only through the dugite relay.

What this is

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

The dugite relay is the only path between the two BPs. A block forged by dugite-bp must transit dugite-relay's BlockFetch server before cardano-bp can fetch it (and vice versa). This is what the soak test exercises.

The chain boots into Conway PV10 from a fresh genesis with two equally-staked pools, 1-second slots, activeSlotsCoeff = 0.2, epochLength = 500, and securityParam = 10. Blocks are minted every ~5 seconds on average, and the 30-minute soak crosses 3–4 epoch boundaries.

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 BP 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 bidirectional ChainSync/BlockFetch (Haskell <-> Rust <-> Haskell)
• Dugite N2N peer connection lifecycle on loopback
• Dugite N2C local-socket tx submission, query tip, query utxo
• Cross-implementation chain agreement under healthy conditions

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)
• Mainnet-scale peer counts, NAT/firewall behaviour, or BGP-level routing
• Mithril snapshot import (covered by other tests)

Known dugite-node bugs surfaced by this testnet

Bringing up the devnet for the first time exposed four real defects in dugite-node. Three were fixed on this branch as part of bringing the test infrastructure online; the fourth is tracked separately and remains the blocker for full predicate parity.

• Bug A (FIXED in this branch as 7e6a4af54): ChainSync intersection at Origin with a non-Origin local tip used to leave the node permanently stuck on its own fork — the node sat at the local tip and never re-intersected once the peer caught up. The fix disconnects after a backoff so the next reconnection can intersect at a real shared point. This was the root cause behind the "node appears to hang" reports.
• Bug B (FIXED in this branch as 59a5fc64d): the live BlockFetch apply path did not push LedgerDeltas onto the LedgerSeq, so a fork-switch rollback would fail to find the rollback ledger state on shallow chains and silently keep the wrong tip. The fix pushes deltas in all apply paths (live, replay, and triggered-fork) so rollback is always possible up to k.
• Bug C (FIXED in this branch as 9d30beaf2): the forge loop fired as soon as the node finished booting, even before any peer connection or ChainSync intersection had completed. On a fresh devnet, dugite-bp would self-forge an orphan block at chain start, then refuse to abandon it. The fix gates the forge loop on peer_hot_count > 0 AND at least one successful ChainSync intersection.
• Bug D (NOT YET FIXED — tracked in #497): after initial sync, dugite-bp's chain selection does not switch to a peer's longer competing chain when two BPs forge concurrently. The peer chain's blocks are received and stored in VolatileDB, but the local chain selector never adopts them — dugite_blocks_applied_total stays stuck at the initial-sync count while dugite_blocks_forged_total continues to grow on the local fork. Predicates 1 (forge cross-check) and 3 (tx round-trip) will FAIL for dugite-bp until this is resolved. The relay is unaffected (it doesn't forge) and adopts the canonical chain cleanly.

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

Kubernetes Deployment

Dugite includes a Helm chart for deploying to Kubernetes as either a relay node or a block producer.

Prerequisites

• Kubernetes 1.25+
• Helm 3.x
• A StorageClass that supports ReadWriteOnce persistent volumes

Quick Start

Deploy a relay node on the preview testnet:

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

This will:

1. Run a Mithril snapshot import (init container) for fast bootstrap
2. Start the node syncing with the preview testnet
3. Create a 100Gi persistent volume for the chain database
4. Expose Prometheus metrics on port 12798

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"

Network magic is derived automatically from the network name. Override with network.magic if needed.

Persistence

persistence:
  enabled: true
  storageClass: ""    # Use default StorageClass
  size: 100Gi         # 100Gi for testnet, 500Gi+ for mainnet
  accessMode: ReadWriteOnce
  existingClaim: ""   # Use an existing PVC

Resources

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

For mainnet, increase memory limits to 24-32Gi during initial sync and ledger replay.

Mithril Import

mithril:
  enabled: true     # Run Mithril import on first startup

The init container is idempotent — it skips the import on subsequent restarts if blocks already exist.

Ledger Replay

ledger:
  replayLimit: null    # null = unlimited (replay all blocks)
  pipelineDepth: 150   # Chain sync pipeline depth

After Mithril import, the node replays all imported blocks through the ledger to build correct UTxO state, delegations, and protocol parameters. Set replayLimit: 0 to skip replay for faster startup (at the cost of incomplete ledger state).

Metrics and Monitoring

metrics:
  enabled: true
  port: 12798
  serviceMonitor:
    enabled: false     # Set true if using Prometheus Operator
    interval: 30s
    labels: {}

When serviceMonitor.enabled is true, the chart creates a ServiceMonitor resource for automatic Prometheus scraping.

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

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=500Gi

Relay with Custom Topology

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

relay-values.yaml:

topology:
  bootstrapPeers:
    - address: relays-new.cardano-mainnet.iohk.io
      port: 3001
  localRoots:
    - accessPoints:
        - address: dugite-producer.default.svc.cluster.local
          port: 3001
      advertise: false
      trustable: true
      valency: 1
  publicRoots:
    - accessPoints:
        - address: relays-new.cardano-mainnet.iohk.io
          port: 3001
      advertise: false
  useLedgerAfterSlot: 110332800

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

Block Producer Deployment

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

Create Keys Secret

First, create a Kubernetes secret with your block producer keys:

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=500Gi

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 from any pod in the cluster
• 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:

# Deploy the 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

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

producer-values.yaml:

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

relay-values.yaml:

topology:
  bootstrapPeers:
    - address: relays-new.cardano-mainnet.iohk.io
      port: 3001
  localRoots:
    - accessPoints:
        - address: dugite-producer-dugite-node.default.svc.cluster.local
          port: 3001
      advertise: false
      trustable: true
      valency: 1
  publicRoots:
    - accessPoints:
        - address: relays-new.cardano-mainnet.iohk.io
          port: 3001
      advertise: false
  useLedgerAfterSlot: 110332800

Verifying the Deployment

Check pod status:

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

View logs:

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

Query the node tip:

kubectl exec deploy/dugite-relay-dugite-node -- \
  dugite-cli query tip --testnet-magic 2

Check metrics:

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

Configuration Reference

All configurable values with defaults:

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 14-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]
    STORE --> PRIM
    STORE --> SER
    POOL --> PRIM
    SER --> PRIM
    CRYPTO --> PRIM

Key Dependencies

Dugite leverages the pallas family of crates (v1.0.0-alpha.5) for Cardano wire-format compatibility:

• pallas-network — Ouroboros multiplexer and handshake
• pallas-codec — CBOR encoding/decoding
• pallas-primitives — Cardano primitive types
• pallas-traverse — Multi-era block traversal
• pallas-crypto — Cryptographic primitives
• pallas-addresses — Address parsing and construction

Other 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
• uplc — Plutus CEK machine for script evaluation
• 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.

Pallas Interoperability

Dugite uses pallas for network protocol handling and block deserialization, ensuring wire-format compatibility with cardano-node. Internal types (in dugite-primitives) are converted from pallas types during deserialization.

Key conversion patterns:

• Transaction.hash is set during deserialization from pallas tx.hash()
• 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 pallas
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 pallas' 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 utxo_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 hash_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/>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 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 (V14=14, V15=15, V16=16, ...)
; Note: N2N does NOT set bit-15. Only N2C uses bit-15.
versionNumber = 14 / 15 / 16

; Version data for V14/V15: 4-element array
versionData_v14 = [networkMagic, initiatorOnly, peerSharing, query]
; Version data for V16+: 5-element array (adds perasSupport)
versionData_v16 = [networkMagic, initiatorOnly, peerSharing, query, perasSupport]

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
perasSupport  = 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)

Wire Format

Source: ouroboros-network/ouroboros-network/protocols/lib/Ouroboros/Network/Protocol/BlockFetch/Codec.hs and cardano-diffusion/protocols/cddl/specs/block-fetch.cddl

MsgRequestRange = [0, lower_point, upper_point]
MsgClientDone   = [1]
MsgStartBatch   = [2]
MsgNoBlocks     = [3]
MsgBlock        = [4, block]
MsgBatchDone    = [5]

MsgRequestRange: Both lower_point and upper_point are inclusive (the range spans from lower to upper, both included). Each point uses the standard point encoding ([] for Origin, [slot, hash] for specific).

Block encoding in MsgBlock: For CardanoBlock, the block is encoded as:

block = [era_index, tag(24)(bstr(cbor_encoded_block))]

The full block (including header and body) is CBOR-serialized, then wrapped in tag(24)(bytes(cbor_bytes)) (CBOR-in-CBOR), then placed in a 2-element array with the HFC era index.

Source: ouroboros-consensus/ouroboros-consensus-cardano/src/shelley/Ouroboros/Consensus/Shelley/Node/Serialisation.hs

Timing

Source: ouroboros-network/ouroboros-network/protocols/lib/Ouroboros/Network/Protocol/BlockFetch/Codec.hs:timeLimitsBlockFetch

Byte Limits

BlockFetch Decision Loop

The blockFetchLogic thread runs continuously, waking every 10 ms (Praos) or 40 ms (Genesis). It reads candidate chains from ChainSync via STM, computes which block ranges need to be fetched, and issues MsgRequestRange messages.

Source: cardano-diffusion/lib/Cardano/Network/Diffusion/Configuration.hs:defaultBlockFetchConfiguration

Ingress Queue Limit

max(10 × 2 097 154, 100 × 90 112) × 1.1 ≈ 22 MB.

N2N Protocol 4: TxSubmission2

Identity

• Protocol ID: 4
• Temperature: Hot
• Direction: Inverted agency — the server (inbound/receiver) has agency first. The server requests transactions; the client replies with them. This is the opposite of most protocols.
• Versions: All N2N versions. V2 logic (multi-peer decision loop) is enabled server-side when TxSubmissionLogicV2 is configured; V1 is the current default in cardano-node.

State Machine

Source: ouroboros-network/ouroboros-network/protocols/lib/Ouroboros/Network/Protocol/TxSubmission2/Type.hs

StInit  (ClientAgency)   -- client must send MsgInit before anything else
    │
    │ MsgInit
    ▼
StIdle  (ServerAgency)   -- server has agency; requests txids or terminates
    │
    ├─── MsgRequestTxIds(blocking=true)    ──→ StTxIds(StBlocking)
    ├─── MsgRequestTxIds(blocking=false)   ──→ StTxIds(StNonBlocking)
    ├─── MsgRequestTxs                     ──→ StTxs
    └─── MsgDone                           ──→ StDone

StTxIds(StBlocking)   (ClientAgency)   -- client MUST reply, no timeout
    │
    └─── MsgReplyTxIds(NonEmpty list)  ──→ StIdle
         (BlockingReply: list must be non-empty)

StTxIds(StNonBlocking)  (ClientAgency)  -- client must reply within shortWait
    │
    └─── MsgReplyTxIds(possibly empty) ──→ StIdle

StTxs  (ClientAgency)  -- client must reply with requested tx bodies
    │
    └─── MsgReplyTxs(tx list)  ──→ StIdle

StDone (NobodyAgency)

MsgDone constraint: MsgDone can only be sent from StIdle (server side). It is the server's prerogative to terminate, not the client's.

Wire Format

Source: ouroboros-network/ouroboros-network/protocols/lib/Ouroboros/Network/Protocol/TxSubmission2/Codec.hs:encodeTxSubmission2 and cardano-diffusion/protocols/cddl/specs/tx-submission2.cddl

MsgInit           = [6]

MsgRequestTxIds   = [0, blocking:bool, ack:word16, req:word16]
                  ; blocking=true  → StTxIds(StBlocking)
                  ; blocking=false → StTxIds(StNonBlocking)

MsgReplyTxIds     = [1, [_ *[txid, size:word32] ]]
                  ; INDEFINITE-length outer list (encodeListLenIndef)
                  ; Each inner entry is a DEFINITE-length array(2)

MsgRequestTxs     = [2, [_ *txid ]]
                  ; INDEFINITE-length list

MsgReplyTxs       = [3, [_ *tx ]]
                  ; INDEFINITE-length list

MsgDone           = [4]

IMPORTANT: Both MsgReplyTxIds, MsgRequestTxs, and MsgReplyTxs use indefinite-length CBOR arrays (encoded with encodeListLenIndef and terminated with encodeBreak). The codec explicitly requires this. Using definite-length arrays is a decoding error.

HFC era-tag wrapping for txids and txs:

For the Cardano HFC instantiation, each txid and each tx is wrapped with the era index before being placed into the list. The wrapping is done by encodeNS in ouroboros-consensus:

; txid (GenTxId) encoding
txid = [era_index:uint8, bstr(32)]
     ; era_index: 0=Byron, 1=Shelley, 2=Allegra, 3=Mary, 4=Alonzo,
     ;            5=Babbage, 6=Conway, 7=Dijkstra
     ; payload:   32 raw bytes = Blake2b-256 hash of tx body (no CBOR tag)

; tx (GenTx) encoding
tx = [era_index:uint8, tag(24)(bstr(cbor_of_tx))]
   ; The transaction CBOR bytes are wrapped in CBOR tag 24 (embedded CBOR)

Example for Conway (era_index=6):

txid = [6, bstr(32_bytes_of_txhash)]
tx   = [6, #6.24(bstr(cbor_bytes_of_transaction))]

Source: ouroboros-consensus/ouroboros-consensus-diffusion/src/.../Consensus/Network/NodeToNode.hs and ouroboros-consensus/src/.../HardFork/Combinator/Serialisation/Common.hs:encodeNS

MsgReplyTxIds — Size Reporting

Each entry in MsgReplyTxIds carries a SizeInBytes (word32) alongside the txid. This size must include the full HFC envelope overhead that the tx will have in MsgReplyTxs. For Conway: 3 bytes overhead (1 byte array-of-2 header, 1 byte era_index word8, CBOR tag 24 header). Mismatches beyond the tolerance threshold (const_MAX_TX_SIZE_DISCREPANCY = 10 bytes in V2 inbound) terminate the connection.

Blocking vs Non-Blocking Rules

In blocking mode (MsgRequestTxIds(blocking=true)):

• req_count must be >= 1
• MsgReplyTxIds reply must contain a non-empty list (BlockingReply)
• No timeout: the client MAY block indefinitely in STM waiting for new mempool entries

In non-blocking mode (MsgRequestTxIds(blocking=false)):

• At least one of ack_count or req_count must be non-zero
• MsgReplyTxIds reply may be empty (NonBlockingReply [])
• Timeout: shortWait (10 seconds)

Acknowledgment semantics: ack_count tells the client how many previously announced txids can now be removed from the outbound window. The client maintains a FIFO of unacknowledgedTxIds. When the server sends MsgRequestTxIds(ack=N, req=M), the client drops the first N entries from the FIFO and adds up to M new txids from the mempool.

Timing

Source: ouroboros-network/ouroboros-network/protocols/lib/Ouroboros/Network/Protocol/TxSubmission2/Codec.hs:timeLimitsTxSubmission2

V1 Server Constants (current default)

The 60-second init delay is applied via threadDelay before the V1 server makes its first MsgRequestTxIds. This intentionally avoids requesting transactions during initial chain sync.

V2 Server Constants (experimental)

Source: ouroboros-network/ouroboros-network/lib/Ouroboros/Network/TxSubmission/Inbound/V2/

MsgInit Requirement

MsgInit (tag=6, one-element array [6]) must be the very first message sent by the client (outbound side) after the mux connection is established for the TxSubmission2 protocol. The server waits for MsgInit in StInit before transitioning to StIdle. Sending any other message first is a protocol error.

Ingress Queue Limit

maxUnacknowledgedTxIds × (44 + 65536) × 1.1

With maxUnacknowledgedTxIds=100: approximately 6 666 400 bytes.

N2N Protocol 8: KeepAlive

Identity

• Protocol ID: 8
• Temperature: Established (started on cold→warm, runs for entire connection lifetime)
• Purpose: Detects connection failure and measures round-trip time for GSV (Good-Spread-Variable) calculations used in BlockFetch prioritization.

State Machine

Source: ouroboros-network/ouroboros-network/protocols/lib/Ouroboros/Network/Protocol/KeepAlive/Type.hs

StClient  (ClientAgency)  -- client sends keep-alive request
    │
    ├─── MsgKeepAlive(cookie)  ──→ StServer
    └─── MsgDone               ──→ StDone

StServer  (ServerAgency)  -- server must respond with same cookie
    │
    └─── MsgKeepAliveResponse(cookie)  ──→ StClient

StDone (NobodyAgency)

Wire Format

Source: ouroboros-network/ouroboros-network/protocols/lib/Ouroboros/Network/Protocol/KeepAlive/Codec.hs:codecKeepAlive_v2

MsgKeepAlive         = [0, cookie:word16]
MsgKeepAliveResponse = [1, cookie:word16]
MsgDone              = [2]

Cookie matching: The server must echo back the exact cookie value sent by the client. A mismatch raises KeepAliveCookieMissmatch (note: the Haskell source has the typo "Missmatch" with double-s), which terminates the connection.

Timing

Source: ouroboros-network/ouroboros-network/protocols/lib/Ouroboros/Network/Protocol/KeepAlive/Codec.hs:timeLimitsKeepAlive

The asymmetry is intentional: the client side (97 s) is how long the client waits before sending the next keep-alive; the server side (60 s) is how long the server has to respond. The comment in source notes that StServer timeout "should be 10s" (issue #2505) but is currently 60 s.

Byte Limits

Both states: smallByteLimit (65535 bytes).

Protocol Error Condition

KeepAliveCookieMissmatch oldCookie receivedCookie — thrown when MsgKeepAliveResponse cookie does not match the outstanding request cookie. This terminates the connection.

N2N Protocol 10: PeerSharing

Identity

• Protocol ID: 10
• Temperature: Established (started on cold→warm)
• Purpose: Exchange of peer addresses to assist in peer discovery. Only active when both sides negotiated peerSharing=1 in Handshake.

State Machine

Source: ouroboros-network/ouroboros-network/protocols/lib/Ouroboros/Network/Protocol/PeerSharing/Type.hs

StIdle  (ClientAgency)  -- client requests peer addresses or terminates
    │
    ├─── MsgShareRequest(amount)  ──→ StBusy
    └─── MsgDone                  ──→ StDone

StBusy  (ServerAgency)  -- server must reply with peer list
    │
    └─── MsgSharePeers(addrs)  ──→ StIdle

StDone (NobodyAgency)

Wire Format

Source: ouroboros-network/cardano-diffusion/protocols/lib/Cardano/Network/Protocol/PeerSharing/Codec.hs and cardano-diffusion/protocols/cddl/specs/peer-sharing-v14.cddl

MsgShareRequest = [0, amount:word8]
MsgSharePeers   = [1, [* peerAddress]]
MsgDone         = [2]

; Peer address encoding (SockAddr)
peerAddress = [0, ipv4:word32, port:word16]
            ; IPv4: single u32 in network byte order, then port as word16
            / [1, word32, word32, word32, word32, port:word16]
            ; IPv6: four u32s (network byte order), then port as word16

Protocol error condition: If the server replies with more addresses than amount requested, it is a protocol error. The client must request no more than 255 peers (word8 max).

Timing

Server Address Selection Policy

The server only shares addresses for peers that satisfy all of:

• knownPeerAdvertise = DoAdvertisePeer
• knownSuccessfulConnection = True
• knownPeerFailCount = 0

Addresses are randomized using a hash with a salt that rotates every 823 seconds to prevent fingerprinting.

Source: ouroboros-network/ouroboros-network/api/lib/Ouroboros/Network/PeerSelection/PeerSharing/Codec.hs and ouroboros-network/ouroboros-network/lib/Ouroboros/Network/PeerSharing.hs

Key Policy Constants

Source: ouroboros-network/ouroboros-network/lib/Ouroboros/Network/Diffusion/Policies.hs

N2C Protocol 0: Handshake (Node-to-Client)

Identity

• Protocol ID: 0 (same as N2N, runs on raw socket before mux)
• Direction: Same as N2N: client proposes, server accepts or refuses
• Versions: V16 (=32784) through V23 (=32791)

Wire Format

Source: CDDL: cardano-diffusion/protocols/cddl/specs/handshake-node-to-client.cddl Codec: same codecHandshake function as N2N, parameterized on version number type.

; Messages are identical in structure to N2N handshake
MsgProposeVersions = [0, versionTable]
MsgAcceptVersion   = [1, versionNumber, nodeToClientVersionData]
MsgRefuse          = [2, refuseReason]
MsgQueryReply      = [3, versionTable]

; N2C version numbers have bit 15 set to distinguish from N2N
; V16=32784, V17=32785, V18=32786, V19=32787,
; V20=32788, V21=32789, V22=32790, V23=32791
versionNumber = 32784 / 32785 / 32786 / 32787 / 32788 / 32789 / 32790 / 32791

; Encoding: versionNumber_wire = logical_version | 0x8000
; Decoding: logical_version = wire_value & 0x7FFF (after verifying bit 15 is set)

; Version data (V16+): 2-element array
nodeToClientVersionData = [networkMagic:uint, query:bool]

The versionTable in MsgProposeVersions is a definite-length CBOR map with entries sorted in ascending key order.

Version Features

Source: cardano-diffusion/api/lib/Cardano/Network/NodeToClient/Version.hs

Version Negotiation

Same rules as N2N:

• Highest common version wins.
• networkMagic must match.
• query = local || remote (logical OR).
• No initiatorOnlyDiffusionMode or peerSharing fields in N2C version data.

N2C Protocol 5: LocalChainSync

Identity

• Protocol ID: 5
• Direction: N2C clients receive full serialized blocks (not just headers). This is the key difference from N2N ChainSync.
• Versions: All N2C versions

State Machine

Identical state machine to N2N ChainSync (same Type.hs). See that section for the complete state machine diagram.

Wire Format

Messages tags are identical to N2N ChainSync (0–7). The key difference is the content of MsgRollForward.

N2C MsgRollForward block encoding:

; N2C LocalChainSync block payload in MsgRollForward
block = [era_id:uint, tag(24)(bstr(cbor_of_full_block))]

The entire block (header + body) is CBOR-encoded, wrapped in CBOR tag(24) (embedded CBOR), and then paired with the era index in a 2-element array.

Era indices: same as TxSubmission2 (0=Byron through 7=Dijkstra).

This matches the same HFC wrapping used by BlockFetch MsgBlock in N2N.

Differences from N2N ChainSync

Source: ouroboros-network/ouroboros-network/protocols/lib/Ouroboros/Network/Protocol/ChainSync/Codec.hs (same codec)

N2C Protocol 6: LocalTxSubmission

Identity

• Protocol ID: 6
• Direction: Client submits a single transaction; server accepts or rejects.
• No HFC era-tag wrapping: Unlike N2N TxSubmission2, N2C LocalTxSubmission sends raw transaction CBOR without any HFC era-index prefix.
• Versions: All N2C versions

State Machine

Source: ouroboros-network/ouroboros-network/protocols/lib/Ouroboros/Network/Protocol/LocalTxSubmission/Type.hs

StIdle  (ClientAgency)  -- client submits a transaction or terminates
    │
    ├─── MsgSubmitTx(tx)  ──→ StBusy
    └─── MsgDone          ──→ StDone

StBusy  (ServerAgency)  -- server validates and responds
    │
    ├─── MsgAcceptTx   ──→ StIdle
    └─── MsgRejectTx   ──→ StIdle

StDone (NobodyAgency)

Blocking semantics: After sending MsgSubmitTx, the client must wait for MsgAcceptTx or MsgRejectTx before sending another transaction. This protocol processes one transaction at a time. This is intentional: N2C is only used by local trusted clients (wallets, CLI), so throughput is not a concern.

Wire Format

Source: ouroboros-network/ouroboros-network/protocols/lib/Ouroboros/Network/Protocol/LocalTxSubmission/Codec.hs:encodeLocalTxSubmission and cardano-diffusion/protocols/cddl/specs/local-tx-submission.cddl

MsgSubmitTx = [0, tx]
MsgAcceptTx = [1]
MsgRejectTx = [2, rejectReason]
MsgDone     = [3]

Transaction encoding (tx): Raw transaction CBOR, exactly as produced by toCBOR on the ledger's Tx type. No HFC wrapper, no era tag, no tag(24). The server determines the era from the ledger state.

Rejection reason (rejectReason): The full ApplyTxError encoded via the ledger's EncCBOR instance. For Conway, this is a nested structure of ConwayLedgerPredFailure variants. The exact encoding is era-specific and defined in cardano-ledger.

Source: cardano-ledger/eras/conway/impl/src/Cardano/Ledger/Conway/Rules/

N2C Protocol 7: LocalStateQuery

Identity

• Protocol ID: 7
• Direction: Client acquires a ledger state snapshot and submits queries; server responds with query results.
• Versions: All N2C versions. Some queries require specific minimum versions (see Shelley query tag table).

State Machine

Source: ouroboros-network/ouroboros-network/protocols/lib/Ouroboros/Network/Protocol/LocalStateQuery/Type.hs

StIdle      (ClientAgency)   -- client acquires a state or terminates
    │
    ├─── MsgAcquire(target)  ──→ StAcquiring
    └─── MsgDone             ──→ StDone

StAcquiring  (ServerAgency)  -- server acquiring the requested state
    │
    ├─── MsgAcquired         ──→ StAcquired
    └─── MsgFailure(reason)  ──→ StIdle

StAcquired   (ClientAgency)  -- client can query or release
    │
    ├─── MsgQuery(query)     ──→ StQuerying
    ├─── MsgRelease          ──→ StIdle
    └─── MsgReAcquire(target)──→ StAcquiring

StQuerying   (ServerAgency)  -- server computing query result
    │
    └─── MsgResult(result)   ──→ StAcquired

StDone (NobodyAgency)

Re-acquire: MsgReAcquire transitions from StAcquired directly back to StAcquiring, allowing the client to acquire a new state without going through StIdle. This avoids a round trip.

Acquire Targets

Three targets exist for MsgAcquire and MsgReAcquire:

For MsgReAcquire: tags are shifted by 3 → SpecificPoint=[6, point], VolatileTip=[9], ImmutableTip=[11] (V16+).

VolatileTip and ImmutableTip cannot fail (they always succeed with MsgAcquired). SpecificPoint can fail if the point is not in the volatile chain window (yields MsgFailure).

Acquire Failure Codes

AcquireFailurePointTooOld     = 0
AcquireFailurePointNotOnChain = 1

Wire Format

Source: ouroboros-network/ouroboros-network/protocols/lib/Ouroboros/Network/Protocol/LocalStateQuery/Codec.hs:codecLocalStateQuery and cardano-diffusion/protocols/cddl/specs/local-state-query.cddl

; Acquire / Re-acquire
MsgAcquire(SpecificPoint pt)  = [0, point]
MsgAcquire(VolatileTip)       = [8]
MsgAcquire(ImmutableTip)      = [10]    ; V16+ only

MsgAcquired                   = [1]

MsgFailure(reason)            = [2, failure_code:uint]
                              ; 0=PointTooOld, 1=PointNotOnChain

MsgQuery(query)               = [3, query_encoding]
MsgResult(result)             = [4, result_encoding]
MsgRelease                    = [5]

MsgReAcquire(SpecificPoint pt)= [6, point]
MsgReAcquire(VolatileTip)     = [9]
MsgReAcquire(ImmutableTip)    = [11]    ; V16+ only

MsgDone                       = [7]

Query Encoding (Three-Level HFC Wrapping)

Queries are wrapped in three layers. The outermost layer is the consensus-level Query type (in Ouroboros.Consensus.Ledger.Query):

; Outermost consensus layer
query = [2, tag=0, wrapped_block_query]   ; BlockQuery — delegates to HFC
      / [1, tag=1]                         ; GetSystemStart
      / [1, tag=2]                         ; GetChainBlockNo (V16+ / QueryVersion2)
      / [1, tag=3]                         ; GetChainPoint  (V16+ / QueryVersion2)
      / [1, tag=4]                         ; DebugLedgerConfig (V20+ / QueryVersion3)

For BlockQuery (tag=0), the next layer is the HFC query:

; HFC (Hard Fork Combinator) layer
hfc_query = [2, tag=0, era_query]   ; QueryIfCurrent — query current era
          / [3, tag=1, era_query, era_index]   ; QueryAnytime
          / [2, tag=2, hf_specific]            ; QueryHardFork

For QueryIfCurrent, the era index is determined by dispatch; there is no explicit era tag in the message. The era_query is the era-level query:

; Era-level query (Shelley BlockQuery tags)
; These are 1-element or 2-element arrays with a numeric tag
era_query = [1, tag=0]    ; GetLedgerTip
          / [1, tag=1]    ; GetEpochNo
          / [2, tag=2, ..] ; GetNonMyopicMemberRewards
          / [1, tag=3]    ; GetCurrentPParams
          ; ... (see full table below)

Shelley BlockQuery Tag Table