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, Conway, and Dijkstra eras.
• Conway governance (CIP-1694) — DRep registration, voting, proposals, constitutional committee, treasury withdrawals.
• Pipelined sync — ChainSync headers are pipelined per peer (default depth 300, tunable via DUGITE_PIPELINE_DEPTH), decoupled from block fetching. Bulk block fetch uses a single active fetch slot contested by the fastest peers, mirroring cardano-node's maxConcurrencyBulkSync = 1.
• Plutus script execution — Plutus V1/V2/V3 (and V4 from Dijkstra) evaluation via the in-house dugite-uplc CEK machine (fully conformant, all 999 upstream test vectors pass).
• Node-to-Node (N2N) protocol — Full Ouroboros mini-protocol suite: ChainSync, BlockFetch, TxSubmission2, KeepAlive, PeerSharing.
• Node-to-Client (N2C) protocol — Unix domain socket server with LocalChainSync, LocalStateQuery, LocalTxSubmission, and LocalTxMonitor.
• UTxO RPC (gRPC) server — Optional native utxorpc server (sync, query, submit, watch) with reflection and gRPC-Web support. See UTxO RPC.
• cardano-cli compatible CLI — Key generation, transaction building, signing, submission, queries, and governance commands.
• Prometheus metrics — Real-time node metrics on port 12796 by default (deliberately offset from cardano-node's 12798 so both can run on one host).
• P2P networking — Peer manager with cold/warm/hot lifecycle, DNS multi-resolution (A/AAAA/SRV), ledger-based peer discovery, and inbound rate limiting.
• ChainSync Jumping (CSJ) — Phase A Ouroboros Genesis support: dynamic intersection discovery across multiple peers for faster tip-of-chain recovery.
• Mithril snapshot import — Fast initial sync by importing a Mithril-certified snapshot.
• SIGHUP topology reload — Update peer configuration without restarting the node.

Project Status

Dugite is in early development and is NOT recommended for production use. APIs, storage formats, and on-chain behavior may change without notice. Ledger validation is incomplete and may accept invalid transactions or reject valid ones. Do not use this software to operate a stake pool, manage real funds, or participate in mainnet governance. Use at your own risk on testnets only.

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, a container image, Nix, or built from source.

Pre-built Binaries

Download the latest release from GitHub Releases:

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

Each tarball contains dugite-node, dugite-cli, the config/ tree, README.md, and LICENSE. The two TUIs (dugite-monitor, dugite-config) are not in the release tarballs — get them from the container image or by building from source.

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

Verify checksums:

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

Container Image

Multi-arch (linux/amd64, linux/arm64) images are published to GitHub Container Registry on every tagged release:

docker pull ghcr.io/michaeljfazio/dugite:latest
# …or pin a release (tag = the release version without the leading "v")
docker pull ghcr.io/michaeljfazio/dugite:<version>

The image is distroless, runs as non-root (uid 65532), ships all four binaries (dugite-node, dugite-cli, dugite-config, dugite-monitor), and bundles the config/ tree at /opt/dugite/config/. ENTRYPOINT is dugite-node; the default command runs a preview relay.

docker run --rm \
  -v dugite-db:/opt/dugite/db \
  -v dugite-ipc:/opt/dugite/ipc \
  -p 3001:3001 \
  ghcr.io/michaeljfazio/dugite:latest \
  run --config /opt/dugite/config/preview/config.json \
      --topology /opt/dugite/config/preview/topology.json \
      --database-path /opt/dugite/db \
      --socket-path /opt/dugite/ipc/node.sock \
      --host-addr 0.0.0.0 --port 3001

A Helm chart is published alongside the image as an OCI artifact:

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

See Kubernetes Deployment for the full chart reference.

Nix

The repository is a flake (flake.nix plus the modules under nix/), supporting x86_64-linux, aarch64-linux, x86_64-darwin, and aarch64-darwin.

# Build a single binary
nix build github:michaeljfazio/dugite#dugite-node
nix build github:michaeljfazio/dugite#dugite-cli

# Build every binary in one derivation
nix build github:michaeljfazio/dugite#dugite-all

# Development shell (stable Rust via fenix, plus just, jq, fd, ripgrep)
nix develop

packages.default is dugite-node. A NixOS service module lives at nix/nixosModules/service-dugite.nix.

Caveats: the dugite-tui flake output is stale — no such crate exists in the workspace (the TUIs are dugite-monitor and dugite-config). The dev shell also does not yet provide protoc, which dugite-rpc's build script requires; install it separately (see System Dependencies) until the flake is updated.

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. The repository does not pin a toolchain — CI and the Nix flake both track stable, so there is no rust-toolchain.toml to honour.

System Dependencies

protoc is required. The dugite-rpc crate generates its gRPC stubs at build time from the vendored UTxO RPC .proto files, and its build script invokes protoc. Without it, cargo build fails on dugite-rpc (and therefore on dugite-node, which depends on it).

# Debian / Ubuntu — libprotobuf-dev supplies the google/protobuf/*.proto well-known types
sudo apt-get install -y protobuf-compiler libprotobuf-dev

# macOS
brew install protobuf

Beyond protoc, there is nothing else to install. The storage layer is pure Rust: block storage uses append-only chunk files, and the UTxO set uses dugite-lsm, a pure Rust LSM tree — no RocksDB, no LMDB, no C toolchain requirement.

Optionally install just to use the top-level task runner (just build, just check, …). See Development.

Build

Clone the repository:

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

Build in release mode:

cargo build --release
# …or, with just installed:
just build

On Linux with kernel 5.1+, you can enable io_uring for improved disk I/O in the UTxO LSM tree. The feature is defined on dugite-storage and re-exported by dugite-node:

cargo build --release --features io-uring

This produces four operator binaries in target/release/:

A workspace build also emits internal development helpers (apply_bench, probe_block, replay_phase2, capture-ratification-fixture, xtask). Those are not part of the operator surface and are not shipped in releases.

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 --bin dugite-cli
cargo install --path crates/dugite-monitor
cargo install --path crates/dugite-config

(--bin dugite-cli keeps the internal capture-ratification-fixture helper out of your bin/ directory.)

Running Tests

Verify everything is working (requires cargo-nextest):

cargo nextest run --workspace
cargo test --doc

The project enforces a zero-warning policy. Run the full CI gate locally with a single recipe:

just check     # fmt-check → clippy → build → test → test-doc

Or invoke the same steps directly:

cargo fmt --all -- --check
cargo clippy --all-targets -- -D warnings
cargo build --release --all-targets
cargo nextest run --workspace
cargo test --doc

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.

Dugite is in early development and is not recommended for production use. Run it on testnets only — see Project Status.

1. Install

Option A: Pre-built binary (fastest)

The release tarball contains dugite-node, dugite-cli, and the config/ tree.

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 /usr/local/bin/

Option B: Container image

docker pull ghcr.io/michaeljfazio/dugite:latest

Multi-arch (linux/amd64, linux/arm64), ships all four binaries, and bundles config/ at /opt/dugite/config/. See Installation.

Option C: Build from source

Requires a stable Rust toolchain and protoc — see Installation.

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 the chain from genesis:

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

This downloads the latest snapshot from the Mithril aggregator, verifies its certificate chain, extracts it, and bulk-imports the blocks into the ImmutableDB. The ancillary archive (the Haskell ledger state at the immutable tip) is downloaded by default, which cuts bootstrap from multi-hour to roughly 15 minutes; pass --no-include-ancillary to replay from blocks instead. See Mithril Snapshot Import for snapshot sizes, disk requirements, and the trust model.

Or via the justfile:

just mithril-import preview

3. Run the Node

Dugite ships with configuration files for mainnet, preview, and preprod, under config/<network>/ — config.json, topology.json, and four genesis files (byron-genesis.json, shelley-genesis.json, alonzo-genesis.json, conway-genesis.json). The release tarball and container image both bundle this tree. Network magic is 764824073 for mainnet, 2 for preview, and 1 for preprod.

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

Or via the top-level justfile:

just run-relay preview

The node will:

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

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

4. Query the Node

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

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

Example output (field order matches cardano-cli 10.x — alphabetical, no network field):

{
    "block": 4094745,
    "epoch": 1232,
    "era": "Conway",
    "hash": "8498ccda...",
    "slot": 106453897,
    "slotInEpoch": 9097,
    "slotsToEpochEnd": 77303,
    "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 12796 by default — deliberately offset from cardano-node's 12798 so both can run on the same host. Override with --metrics-port, or the MetricsPort field in config.json (the shipped configs set 12796 explicitly).

curl -s http://localhost:12796/metrics | grep dugite_sync_progress
# dugite_sync_progress_percent 10000

The value is a percentage scaled by 100 — divide by 100 for percent.

Next Steps

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

Development

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

Before your first build, install protoc — dugite-rpc's build script needs it. See System Dependencies.

Recipe arguments are positional, not named: just submit-txs 100, not just submit-txs n=100 (the latter passes the literal string n=100).

Quick reference

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

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

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

# Local devnet (testnet/local-devnet, loopback)
just devnet-setup           # one-time: render configs, generate keys, fetch reference binaries
just devnet-run             # start dugite-bp + dugite-relay + cardano-node-bp
just devnet-soak            # 30-minute soak
just devnet-verify          # check evidence from the last run/soak
just devnet-report          # single-round report from the latest evidence dir
just devnet-stop

# devnet-validate presets (see the devnet-validate skill)
just devnet-validate-smoke      # single boot, ~5 min — PR gate for core crates
just devnet-validate-extended   # 3 rounds, ~75 min — used for release tagging

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

# Monitoring (Prometheus + Grafana via Docker)
just monitor-start          # optional arg: Prometheus port (default 9090)
just monitor-status
just monitor-stop
just watch-metrics          # tail the Prometheus endpoint (default port 12796)

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

# Dual-decode validation (in-house decoder vs shadow decoder)
just dual-decode-smoke                  # serialization tests with DUGITE_DUAL_DECODE=panic
just dual-decode-soak preview 0         # NETWORK, MAX_BLOCKS (0 = unlimited), extra flags
just dual-decode-report                 # summarise mismatch artefacts

# Upstream conformance (corpus pinned in tests/conformance/upstream/manifest.toml)
just download-upstream-fixtures         # all seven fixture areas at the pinned tag
just download-upstream-fixtures-area plutus
just test-conformance                   # UPLC + every upstream golden test
just test-conformance-uplc              # 999 plutus-core evaluation vectors
just test-conformance-upstream          # all upstream goldens in one binary
just regenerate-corpus-local            # rebuild corpus tarballs locally

# Dev / release helpers
just licenses               # regenerate docs/src/reference/third-party-licenses.md
just clean-worktrees        # prune stale git worktree branches
just query-tip              # dugite-cli query tip against ./node.sock
just bump-utxorpc-spec v0.19.2   # refresh vendored utxorpc/spec protos

Per-area conformance filters also exist (just test-conformance-cardano-base, -cardano-ledger, -cardano-node, -ledger-rules, -mithril, -ouroboros-consensus, -status). These are for iteration only — the "N skipped" count they print is the tests belonging to other areas, not a coverage gap. Use just test-conformance-upstream for the unfiltered run.

Layout

Most recipes wrap scripts under scripts/<group>/; the devnet recipes wrap testnet/local-devnet/:

Most scripts cd "$(dirname "$0")/../.." before doing work, so they resolve ./config/ and ./target/release/ regardless of cwd — you can invoke them via just, from the repo root, or by absolute path. A minority (notably some under scripts/monitoring/ and scripts/validation/) assume the repo root; prefer the just recipe. See scripts/README.md and config/README.md for the canonical layout description.

Hard requirements

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

Configuration

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

Configuration File Format

The configuration file uses PascalCase keys (matching the cardano-node convention). This is config/preview/config.json as shipped in the repository:

{
  "Network": "Testnet",
  "NetworkMagic": 2,
  "DiffusionMode": "InitiatorAndResponder",
  "ByronGenesisFile": "byron-genesis.json",
  "ByronGenesisHash": "81cf23542e33d64c541699926c2b5e6e9c286583f0c8a3fb5f22ea7b352dd174",
  "ShelleyGenesisFile": "shelley-genesis.json",
  "ShelleyGenesisHash": "363498d1024f84bb39d3fa9593ce391483cb40d479b87233f868d6e57c3a400d",
  "AlonzoGenesisFile": "alonzo-genesis.json",
  "ConwayGenesisFile": "conway-genesis.json",
  "TargetNumberOfRootPeers": 60,
  "TargetNumberOfActivePeers": 15,
  "TargetNumberOfEstablishedPeers": 30,
  "TargetNumberOfKnownPeers": 85,
  "TargetNumberOfActiveBigLedgerPeers": 5,
  "TargetNumberOfEstablishedBigLedgerPeers": 10,
  "TargetNumberOfKnownBigLedgerPeers": 15,
  "MinSeverity": "Info",
  "LogDirective": "info",
  "MetricsPort": 12796,
  "ExperimentalHardForksEnabled": true
}

Unknown keys are ignored. The node's deserializer does not reject fields it does not recognise, so a typo in a key name silently leaves the default in force with no warning. Run dugite-config validate <file> to have unknown keys reported — see Configuration Editor.

Fields Reference

Network Settings

EnableP2P is not a Dugite config key. Dugite is always P2P; there is no non-P2P path to switch off. If your config file carries EnableP2P (from a cardano-node 8.x config) the node ignores it silently.

Protocol

These three are inert. They are parsed so a cardano-node config file drops in without error, but nothing in the workspace reads them — Dugite always sends the network magic in the N2N handshake. NetworkMagic is the field that actually decides which network you join.

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.

At startup the node checks that every configured genesis file exists (resolved against the config file's directory) and that every configured hash is exactly 64 hex characters. Either check failing is a fatal startup error naming the era.

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.

Two of these are advisory in Dugite rather than direct policy levers: TargetNumberOfRootPeers is validated and exported as a Prometheus gauge, but root-peer connectivity is actually driven per-group by the topology's hotValency / warmValency; and TargetNumberOfKnownBigLedgerPeers is not enforced as a separate cap, because the known set as a whole is bounded by TargetNumberOfKnownPeers and selectively forgetting scarce big ledger peers would hurt Genesis sync.

Genesis-mode sync targets

A second target set applies while the node is in Genesis-mode bulk sync. It is parsed and validated unconditionally, but only takes effect when ConsensusMode is "Genesis".

Startup validation

Both target sets are checked at startup against the same predicates as Haskell's sanePeerSelectionTargets, and a violation is a fatal startup error naming the set ([deadline] or [sync]):

• active <= established <= known, and root <= known
• activeBigLedger <= establishedBigLedger <= knownBigLedger
• active <= 100, established <= 1000, known <= 10000 (and the same three ceilings for the big-ledger-peer counts)

Churn

Ouroboros Genesis Tuning

LowLevelGenesisOptions mirrors cardano-node's object of the same name and is only consulted when ConsensusMode is "Genesis". Omit the whole object to get the upstream defaults.

"LowLevelGenesisOptions": {
  "EnableCSJ": true,
  "EnableLoEAndGDD": true,
  "EnableLoP": true,
  "BlockFetchGracePeriod": 10,
  "BucketCapacity": 100000,
  "BucketRate": 500,
  "CSJJumpSize": 4320,
  "GDDRateLimit": 1.0
}

Checkpoints

Connection Management

AcceptedConnectionsLimit also accepts the older long key names (acceptedConnectionsHardLimit, acceptedConnectionsSoftLimit, acceptedConnectionsDelay) as aliases.

The following four keys are parsed for cardano-node config-file compatibility but not currently enforced. Setting them changes nothing; they are reserved so that a cardano-node config drops in without a parse error.

Metrics, RPC, and Storage

Effective metrics port, highest precedence first: --no-metrics → 0; --metrics-port <PORT>; TurnOnLogMetrics: false → 0; MetricsPort; otherwise 12796. Note that an explicit --metrics-port wins even over TurnOnLogMetrics: false.

Tracing

Log Level Control

Verbosity is resolved with this precedence, highest first:

1. RUST_LOG environment variable
2. --log-level CLI flag
3. LogDirective config field
4. MinSeverity config field

# 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 ...

Because the config file is read after the tracing subscriber is constructed, the config-file values are applied via a live filter reload immediately after startup — but only when neither RUST_LOG nor --log-level is set, so an explicit operator override is never clobbered by the file.

That guard applies at startup only. A later SIGHUP applies LogDirective / MinSeverity unconditionally, so a reload will override a level you set on the command line or in the environment.

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

Live Reload (SIGHUP)

Sending SIGHUP re-reads both the config file and the topology file. Changed fields are partitioned into those that can be applied live and those that need a restart; restart-required changes are logged as warnings and the reloadable ones are still applied.

Hot-reloadable: all seven TargetNumberOf* deadline targets, ChurnIntervalNormalSecs, ChurnIntervalSyncSecs, LogDirective, MinSeverity.

Restart required: Network, NetworkMagic, every genesis file path and hash, MetricsPort, TurnOnLogMetrics, DiffusionMode, ExperimentalHardForksEnabled, ConsensusMode — plus everything set on the command line (database and socket paths, listen address and port, KES/VRF/OpCert paths).

kill -HUP $(pgrep -x dugite-node)

Stopping the Node

Always stop the node with SIGTERM (or SIGINT / Ctrl-C), never SIGKILL.

kill -TERM $(pgrep -x dugite-node)     # correct
kill -9    $(pgrep -x dugite-node)     # do not do this

On SIGTERM the node demotes its peers, flushes storage, and writes a final ledger snapshot. A hard kill skips all of that and risks damaging the active ImmutableDB chunk's secondary index. Since v2.4.0 the node reconciles that damage at open — verifying the tail chunk by CRC, truncating to the verified prefix, and quarantining an index-less tail chunk as .chunk.orphaned — but recovery still costs the un-flushed blocks, and damage below the tail chunk is a hard InconsistentChunk error rather than something the node repairs.

A second SIGINT/SIGTERM during shutdown forces an immediate exit, matching cardano-node's behaviour, so you never need kill -9 to get out of a wedged shutdown.

ChainDB::open takes an exclusive advisory flock on <database-path>/lock, so a second process pointed at the same directory fails fast and names the pid already holding it, instead of two nodes silently interleaving writes.

Minimal Configuration

The smallest viable configuration file specifies only the network:

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

All other fields use the defaults tabulated above. Note that with no genesis files specified the node falls back to built-in default protocol parameters, which will not match a real network — for anything beyond a smoke test, point at the genesis files for the network you are joining.

Format Support

The parser picks its format from the file extension: .json is parsed as cardano-node-compatible JSON, and anything else is parsed as TOML. If the path does not exist at all, the node starts on built-in defaults rather than failing — so a typo in --config produces a mainnet-default node, not an error.

Editing Configuration Interactively

dugite-config is a standalone TUI for browsing and editing these files with per-field type validation, tuning hints, a diff view, and a save-and-SIGHUP live reload. See Configuration Editor (dugite-config).

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

Argument shape: get and set take the key (and value) as positional arguments and the file as a --config flag — not the other way round.

edit

# Edit an explicit file
dugite-config edit config/preview/config.json

# Attach to a running node: discovers dugite-node processes on this machine,
# auto-attaches if exactly one is running, otherwise shows a selector
dugite-config edit

In discovery mode the command exits with an error if no dugite-node process is running, or if the discovered processes have no readable config file.

init

init is not an interactive wizard. It writes a complete default config for a named network in one shot:

# Write a preview default config
dugite-config init --network preview --out config.json

# Print to stdout instead
dugite-config init --network mainnet

validate

Check a configuration file against the schema without modifying it. Exits 0 when valid and 1 when it contains errors, so it drops straight into CI:

dugite-config validate config/preview/config.json

Known keys are validated against their declared type and range. Keys that are not in the schema are reported as warnings, not errors — this is how a stray EnableP2P or a typo'd key name gets surfaced, since the node itself ignores unknown keys silently.

Output on success (written to stderr):

OK — 'config/preview/config.json' is valid (21 parameters, 0 unknown).

Output on failure:

Errors:
  'TargetNumberOfActivePeers': value 200 exceeds maximum (100)
Error: 'config/preview/config.json' failed validation: 1 error(s)

get / set

Non-interactive field access for scripting:

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

# Get with the schema's type, default, section, description, and tuning hint
dugite-config get TargetNumberOfActivePeers --config config.json --verbose

# Set a field (creates config.json.bak first)
dugite-config set TargetNumberOfActivePeers 30 --config config.json

set validates the new value against the schema before writing, and coerces it to the JSON type the schema declares. A key that is in the schema but absent from the file is appended; a key in neither is rejected.

Only top-level keys are addressable. There is no dotted-path syntax, so nested values such as TraceOptions.TraceForge or Rpc.Port must be edited in the TUI (or by hand).

Interactive Editor

The interactive editor (dugite-config edit) renders a full-screen TUI with two panels: the parameter tree on the left (60%) and a description panel on the right (40%). Below 80 columns the right panel is hidden and the tree fills the terminal.

┌─ Parameters ──────────────────────────────┬─ TargetNumberOfActivePeers ────────┐
│ Network                                   │ Type:    integer (1-100)           │
│   Network                        Testnet  │ Default: 20                        │
│   NetworkMagic                         2  │ Section: Network                   │
│   DiffusionMode      InitiatorAndResponder│                                    │
│   TargetNumberOfActivePeers           15  │ Target number of fully active (hot)│
│   TargetNumberOfEstablishedPeers      30  │ peers. Raising this improves       │
│ Genesis                                   │ propagation at the cost of CPU and │
│   ByronGenesisFile     byron-genesis.json │ bandwidth.                         │
│   ShelleyGenesisFile shelley-genesis.json │                                    │
│ Logging                                   │ Hint: 20 is the cardano-node       │
│   MinSeverity                       Info  │ default. BPs may want 10-15.       │
└───────────────────────────────────────────┴────────────────────────────────────┘

Parameters are grouped into the sections Network, Genesis, Protocol, Logging, Diffusion, Storage, Rpc, and Advanced. Each schema entry also records whether the parameter is hot-reloadable or needs a restart.

Key bindings

Note that Ctrl+S saves and stays in the editor; use q to leave. There is no Ctrl+Q binding and no ? help overlay.

Inline editing

Pressing Enter on a field acts according to the field's type: booleans toggle immediately, enums cycle to the next choice, and string/number/path fields open a text buffer. In the text buffer, Enter confirms and Escape cancels.

Validation runs on confirmation against the schema's declared type and range.

Saving

Every save — from Ctrl+S, Ctrl+R, or the set subcommand — first copies the original file to <path>.bak. Only one level of backup is kept; the previous .bak is overwritten. Files are written with 4-space indentation and a trailing newline, matching the official Cardano config files.

Parameters that are absent from the file are shown in the tree seeded from their schema default, and are only written out if you actually change them — so saving does not balloon a minimal config into a fully-pinned one.

Live reload (Ctrl+R)

Ctrl+R saves and then sends SIGHUP to the running node, applying the hot-reloadable subset of the config without a restart. If the PID cannot be resolved the config is still saved and the signal is skipped with an error message. See Live Reload for which fields actually take effect live.

Search and filter

Press / to enter search mode, which fuzzy-filters the tree as you type. Backspace deletes, Enter confirms and returns to browse mode with the cursor on the first match, and Escape clears the filter. Note that j and k move the cursor while in search mode rather than being typed into the query.

Diff overlay

Ctrl+D opens an overlay comparing the on-disk original against your pending changes. While the overlay is showing, only Esc is accepted — it closes the overlay.

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
set -euo pipefail

CONFIG="config/preview/config.json"

dugite-config init --network preview --out "$CONFIG"

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

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": 0,
  "peerSnapshotFile": "peer-snapshot.json"
}

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 }
]

Bootstrap peers are unconditionally trustable — there is no per-entry flag. They are what satisfies the Honest-Availability-Assumption closure while the node is syncing, so a topology with none configured has to fall back on trustable local roots instead.

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"
  }
]

Dugite's peer governor drives root-peer connectivity from these per-group valencies, not from the aggregate TargetNumberOfRootPeers config field — so hotValency / warmValency are the levers that actually change behaviour here.

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. 0 enables it immediately — which is what the shipped config/mainnet/topology.json uses.

Peer Snapshot File

Optional path to a big ledger peer snapshot, used to seed the big-ledger-peer candidate pool at startup before the live ledger has caught up far enough for useLedgerAfterSlot discovery to populate it:

"peerSnapshotFile": "peer-snapshot.json"

The path is resolved relative to the topology file's directory (matching cardano-node), not the config file's. Two shapes are accepted: the IOG cardano-node 10.x format with a bigLedgerPools array of {relays: [{address, port}]}, and a legacy flat array of {addr, port} objects. Entries from either shape are treated as big ledger peers. Hostnames are resolved once, at startup.

Legacy Producers Format

The pre-P2P producers list is still parsed, for older topology files:

"producers": [
  { "addr": "relay.example.com", "port": 3001, "valency": 1 }
]

Legacy producers are registered as untrusted, non-advertised peers. Prefer localRoots / publicRoots for anything new.

Example Topologies

These are the topology files shipped in the repository under config/<network>/topology.json.

Preview Testnet Relay

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

Preprod Testnet Relay

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

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": [],
  "publicRoots": [
    {
      "accessPoints": [
        { "address": "backbone.cardano.iog.io", "port": 3001 },
        { "address": "backbone.mainnet.cardanofoundation.org", "port": 3001 }
      ],
      "advertise": false
    }
  ],
  "useLedgerAfterSlot": 0,
  "peerSnapshotFile": "peer-snapshot.json"
}

Relay with Block Producer

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

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

DNS SRV Resolution

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

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

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

SIGHUP Topology Reload

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

kill -HUP $(pgrep -x dugite-node)

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

The same signal also re-reads the node config file. Peer targets, churn intervals, and log verbosity are applied live; everything else is logged as needing a restart. See Live Reload.

If you use dugite-config edit, Ctrl+R saves and sends this signal for you.

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

Ready-Made Configs

The repository ships complete, self-contained config and topology files for all three networks under config/<network>/, alongside the genesis files they reference:

config/mainnet/{config,topology,byron-genesis,shelley-genesis,alonzo-genesis,conway-genesis}.json
config/preview/{...}
config/preprod/{...}

Paths inside them are relative, so they work in place:

just run-relay preview        # or: just run-bp preview

# equivalently
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

The sections below show minimal hand-written equivalents if you would rather build your own.

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": [],
  "publicRoots": [
    {
      "accessPoints": [
        { "address": "backbone.cardano.iog.io", "port": 3001 },
        { "address": "backbone.mainnet.cardanofoundation.org", "port": 3001 }
      ],
      "advertise": false
    }
  ],
  "useLedgerAfterSlot": 0
}

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.

Note: A config with no genesis files, like the minimal one above, starts on built-in default protocol parameters rather than mainnet's. Point at the real genesis files — config/mainnet/ has them — before syncing for real.

Connecting to Preview Testnet

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

Create a config-preview.json. The shipped config/preview/config.json sets ExperimentalHardForksEnabled: true, which makes the node signal ProtVer 12 0 and accept on-chain protocol versions up to 12, rather than the default ProtVer 11 0 / max 11:

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

Create a topology-preview.json:

{
  "bootstrapPeers": [
    { "address": "preview-node.play.dev.cardano.org", "port": 3001 }
  ],
  "localRoots": [
    { "accessPoints": [], "advertise": false, "trustable": false, "valency": 1 }
  ],
  "publicRoots": [
    {
      "accessPoints": [
        { "address": "preview-node.play.dev.cardano.org", "port": 3001 }
      ],
      "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, "trustable": false, "valency": 1 }
  ],
  "publicRoots": [
    {
      "accessPoints": [
        { "address": "preprod-node.play.dev.cardano.org", "port": 3001 }
      ],
      "advertise": false
    }
  ],
  "useLedgerAfterSlot": 76723200
}

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, but every one of the four per-node resources has to be distinct: the N2N port, the N2C socket path, the database directory, and the Prometheus metrics port.

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

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

The metrics port is the one that is easy to miss, because it does not appear on the command line unless you put it there. Dugite's default is 12796 (deliberately offset from cardano-node's 12798 so the two can coexist), so two Dugite nodes started without --metrics-port or a MetricsPort config field will collide on it. The shipped configs pre-assign distinct ports: mainnet 12800, preview 12796, preprod 12799.

By default a metrics bind failure is logged and the node keeps running. Pass --require-metrics to make it a fatal startup error instead, which is what you want under a supervisor.

Each database directory is protected by an exclusive flock on <db>/lock, so pointing two nodes at the same --database-path fails fast and names the pid already holding it rather than corrupting the database.

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 Cardano Database (V2) snapshot
2. Verifies the STM certificate chain back to the network's pinned genesis verification key
3. Downloads the snapshot archive (compressed with zstandard)
4. Extracts the cardano-node chunk files
5. Parses each block using Dugite's in-house multi-era CBOR decoder
6. Bulk-imports blocks into Dugite's ImmutableDB (append-only chunk files)
7. Imports the ancillary archive (the Haskell ledger state at the immutable tip) unless disabled

Usage

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

Or via the justfile wrapper, which builds the release binary if needed and picks the magic and database path for you (./db-<network>):

just mithril-import preview     # preview | preprod | mainnet

Arguments

All the standard logging flags (--log-output, --log-format, --log-level, …) also apply to mithril-import. See Logging.

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:

Interruption and Re-Runs

An interrupted import restarts from scratch. The temporary download directory is cleared at the start of every run so chunk files from a different snapshot cannot leak into the new one, and the Mithril client re-fetches everything. There is no partial-download resume.

Re-running the import is also destructive to the target database: before moving the new chunk files into place, mithril-import deletes any existing <database-path>/immutable/ directory, plus the Haskell ledger/ directory and stale ledger snapshots. It does not take the database lock while doing so.

Stop the node before importing. mithril-import writes to the database directory with plain filesystem operations and does not acquire the <db>/lock flock that dugite-node run holds, so it will not detect a running node and will delete the immutable directory out from under it. Stop the node with SIGTERM first, and point --database-path at a fresh directory if you want to keep the old one.

Download concurrency is tunable via DUGITE_MITHRIL_DOWNLOAD_PARALLELISM (per-immutable-file, default 20, clamped to 1–32).

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/mainnet/config.json \
  --topology config/mainnet/topology.json \
  --database-path ./db-mainnet \
  --socket-path ./node.sock \
  --host-addr 0.0.0.0 \
  --port 3001

Stop the node with SIGTERM, never kill -9 — a hard kill risks the active ImmutableDB chunk's index. See Stopping the Node.

When a Re-Import Is Required

The on-disk ledger snapshot carries a SNAPSHOT_VERSION. When a release bumps it, the old snapshot is rejected on load and the node replays chunks from the last compatible point; when the import format itself changed, a full mithril-import is required instead.

v2.4.0 additionally introduced two new files inside the database directory — lock and immutable/clean. Both are created automatically; no operator action is required.

Disk Space Requirements

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

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

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

Mithril Ancillary Import — Trust Model

The Mithril aggregator publishes two artefacts per snapshot:

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

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

On disk the handoff is a two-stage one:

1. mithril-import moves the unpacked ledger/ directory to <database-path>/haskell-ledger/.
2. The next dugite-node run picks the highest-numbered slot subdirectory under haskell-ledger/, decodes it, writes a native ledger-snapshot.bin, and deletes haskell-ledger/ once consumed. If the decode fails the node logs a warning and falls back to chain replay rather than aborting.

If ancillary is requested but no ledger/ directory was unpacked, the import is a hard error — precisely so the node cannot silently come up on genesis-default protocol parameters (issue #335). --allow-stale-pparams downgrades that to a warning.

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

Why ancillary matters

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

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

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

Trust model

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

• Dugite drives the official mithril-client SDK against the aggregator's Cardano Database (V2) API: list() for the snapshot set, get(hash) for the detail (Merkle root, immutables, ancillary), then a download that unpacks the standard cardano-node db/ layout — immutable/ for chunk files (0..=N, plus the ancillary tip chunk N+1) and ledger/ for the Haskell ledger-state snapshot.
• The ancillary archive carries its own Ed25519 manifest signature. Dugite supplies the network's pinned ancillary verification key to the client builder via set_ancillary_verification_key, so the SDK verifies that signature during unpack. Verification is therefore performed inside mithril-client, not by hand in mithril.rs.
• If the network has no pinned ancillary key, the import logs a warning that the ancillary signature cannot be verified and proceeds — it does not abort.

The verification keys are pinned in crates/dugite-node/src/mithril.rs:

The genesis key is resolved by genesis_verification_key() and the ancillary key by ancillary_verification_key_hex(). --mithril-genesis-vkey overrides the genesis key for private networks; there is no equivalent override for the ancillary key.

The aggregator's full STM certificate chain is also verified — verify_chain() walks every certificate's multi-signature back to the genesis certificate — unless --skip-certificate-verification is set. This is identical to the trust posture used for the main snapshot.

What we trust when we accept the ancillary

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

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

What we do not trust

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

Operator-exposure decision

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

Rationale:

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

Verification harness (issue #670 acceptance)

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

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

Acceptance procedure for a new era / boundary

1. Build two databases:

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

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

3. Compare:

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

4. Expected output on PASS:

   PASS — snapshots are semantically equal
   

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

Acceptance status

The harness must PASS for at least one preview boundary AND one preprod boundary before the ancillary path is considered fully verified for a given era.

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

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

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

Note also that the adapter is era-coupled: dugite's runtime types differ from Haskell's HFC-telescope / HKD-parameterised types, so each new era needs explicit adapter coverage in from_haskell_snapshot before the ancillary path will work for it. A new era landing upstream is a reason to re-run this harness, not to assume it still holds.

Code references

Line numbers are deliberately omitted below — search for the named symbol instead, since these files change often.

Related issues

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

Logging

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

Output Formats

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

Text (default)

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

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

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

JSON

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

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

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

Output Targets

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

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

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

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

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

Stdout

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

File

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

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

File output uses non-blocking I/O with buffered writes. The buffer is flushed automatically on shutdown — which is one more reason to stop the node with SIGTERM rather than kill -9.

Log files are named dugite.log (with a date/hour suffix under daily / hourly rotation). Note that --log-retention-days is accepted but the cleanup sweep is not currently wired into the running node, so old files accumulate until you rotate them out yourself (logrotate, a cron job, or a tmpfiles rule).

Journald

Native systemd journal integration. This requires building Dugite with the journald feature, which lives on the dugite-node crate:

cargo build --release -p dugite-node --features journald

Requesting --log-output journald from a binary built without the feature is a hard startup error, not a silent downgrade to stdout.

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

Verbosity is resolved with this precedence, highest first:

1. RUST_LOG environment variable
2. --log-level CLI flag
3. LogDirective config field
4. MinSeverity config field

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

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

The two config fields are applied by a live filter reload immediately after the config file is parsed, and only when neither RUST_LOG nor --log-level is set — so a CLI or environment override is never clobbered by the file. See Configuration → Log Level Control.

MinSeverity uses cardano-node's syslog vocabulary, which is wider than tracing's. It is translated rather than passed through: Notice → info, and Critical / Alert / Emergency → error. An unrecognised value falls back to info. Use LogDirective when you need per-target control — it is handed to EnvFilter unchanged.

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

The logging flags are shared by every subcommand that does work: run, mithril-import, dump-snapshot, verify-ledger-snapshot, and snapshot-convert. (db info does not initialise the subscriber and takes no logging flags.)

An unrecognised value for any of these is a startup error naming the valid set, not a silent fallback.

Non-blocking output and --stdout-overflow

Every tracing call hands its line to a background writer thread over a bounded channel rather than performing a synchronous write(2) on the emitting tokio worker. The default drop policy means that under a genuine log flood, lines are discarded rather than stalling block application — which is the right trade-off in production.

Use --stdout-overflow block for development, CI, or forensic capture where every line must survive. It re-introduces blocking on the hot path, so it defeats the point of the non-blocking writer under real overload.

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 $(pgrep -x dugite-node)
   

   The node re-reads the config file. If LogDirective is present and valid, the filter is reloaded immediately across every output target and the change is logged.

   The directive is parsed before any filter handle is touched, so an invalid string leaves the previous filter fully intact rather than half-applied.

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

Two details worth knowing, because they differ between startup and SIGHUP:

• At startup, LogDirective / MinSeverity are applied only when neither RUST_LOG nor --log-level is set, so an explicit operator override is never clobbered by the file.
• On SIGHUP, they are applied unconditionally, and the reload uses the directive directly rather than re-consulting RUST_LOG. A SIGHUP therefore does override a level you set on the command line or in the environment.

The log filter is only touched when at least one hot-reloadable field actually changed. A SIGHUP against an unmodified config file is a no-op, logged as config_reload: no fields changed.

SIGHUP also reloads the topology and the hot-reloadable peer-governor targets. See Live Reload for the full field partition.

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.

# Auto-discover a running dugite-node and attach
dugite-monitor

# Monitor a specific endpoint (skips discovery)
dugite-monitor --metrics-url http://192.168.1.100:12796/metrics

# Pin the epoch length instead of auto-detecting it from dugite_network_magic
dugite-monitor --network-magic 2

# Show disk usage for the node's database volume in the Resources panel
dugite-monitor --db-path ./db-preview

When --metrics-url is omitted, dugite-monitor enumerates running dugite-node processes (via sysinfo + netstat2) and probes their /metrics endpoints. One node found: it attaches silently. Multiple: a selection dialog appears. None: it falls back to http://localhost:12798/metrics.

Careful: that fallback (12798) is not the node's default metrics port (12796 — see Which port? below). The fallback only matters when discovery finds nothing, in which case there is usually no node to monitor anyway. If the monitor reports no data, pass --metrics-url explicitly with the port your config actually pins.

The dashboard displays five panels:

• Node — role, network, version, era, uptime
• Chain — epoch progress bar, block/slot/tip metrics, density, forks, tx counts
• Connections — P2P state, inbound/outbound, cold/warm/hot, uni/bi/duplex counts
• Resources — CPU %, live memory, RSS memory (plus disk when --db-path is set)
• Peers — RTT bands (0-50 ms, 50-100 ms, 100-200 ms, 200 ms+), min/avg/max RTT

Metrics are polled once per second. The interval is a compile-time constant — there is no flag to change it.

Prometheus Metrics Endpoint

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

Metrics Endpoint

The metrics server responds to any unrecognised HTTP path with Prometheus exposition format metrics:

http://localhost:12796/metrics

Which port?

The built-in fallback is 12796, deliberately offset from cardano-node's 12798 so a dugite node and a Haskell node can co-exist on one host. The shipped per-network configs each pin a port explicitly, so in practice the port comes from the config file:

Resolution order, highest priority first:

1. --no-metrics → server disabled.
2. --metrics-port <PORT> → explicit operator override (wins even over TurnOnLogMetrics=false).
3. TurnOnLogMetrics: false in the config JSON → server disabled (master off-switch, matching cardano-node).
4. MetricsPort in the config JSON.
5. Built-in default 12796.

Pass --require-metrics to make a bind failure a fatal startup error instead of a logged warning.

The examples below use 12796. Substitute your network's port from the table above.

Example response:

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

# HELP dugite_blocks_applied_total Total blocks applied to ledger
# TYPE dugite_blocks_applied_total counter
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:12796/health

Always returns 200 OK. The status field carries the verdict:

• 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_number": 142857392,
  "block_number": 11283746,
  "epoch_number": 512,
  "sync_progress": 99.95,
  "peers_connected": 8,
  "last_block_received_at": "2026-03-14T12:34:56.789Z"
}

last_block_received_at is null until the first block arrives.

Readiness Endpoint

For Kubernetes readiness probes:

GET http://localhost:12796/ready

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

{"ready": true}

or:

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

Liveness Endpoint

For Kubernetes liveness probes — this is the one that should restart a wedged pod:

GET http://localhost:12796/live

Returns 200 OK when a block has been applied within --liveness-threshold-secs (default 600), or when no block has arrived yet but the node has been up for less than that window (warm-up grace). Otherwise 503:

{"alive": true, "threshold_secs": 600}

{"alive": false, "threshold_secs": 600, "last_block_received_at": "2026-03-14T12:34:56.789Z"}

Set --liveness-threshold-secs 0 to make /live always return 200.

/ready tracks sync progress; /live tracks forward progress. A node that is 40% synced but applying blocks is correctly not-ready and alive. Wiring a liveness probe to /ready will restart-loop a node that is merely still syncing.

EKG Compatibility Endpoint

GET http://localhost:12796/ekg

Returns the nested-object JSON layout that cardano-node's EKG (System.Remote.Monitoring) exposes, so legacy gLiveView / CNTools dashboards that poll port 12788 can be pointed at dugite unmodified.

Available Metrics

Counters

Gauges

Chain and sync

Peers and connections

Mempool and transactions

Ledger and governance

Process and host

Histograms

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

Note: the block-fetch histogram is named dugite_peer_block_fetch_range_ms, not dugite_peer_block_fetch_ms. The bundled Grafana dashboard still queries the old name — see the caveat under Grafana Dashboard.

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:12800']    # mainnet; see the port table above
        labels:
          network: 'mainnet'
          node: 'relay-1'

A ready-made config is committed at config/monitoring/prometheus.yml. It scrapes every well-known dugite port so the dashboard works regardless of which just run-{bp,relay} <network> recipe is active — down targets simply show as DOWN in /targets:

Alert rules live alongside it in config/monitoring/prometheus-alerts.yml, covering forge failures, rollback rate, tip age, hot-peer starvation, and RSS growth.

Grafana Dashboard

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

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

Known stale panel: the block-fetch latency panels query dugite_peer_block_fetch_ms_bucket, but the node emits dugite_peer_block_fetch_range_ms_bucket. Those panels render empty until the dashboard JSON is updated. Every other metric referenced by the dashboard matches a metric the node actually emits.

Quick Start (Docker)

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

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

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

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

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

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

Environment variables for port customization:

Importing the Dashboard

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

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

Provisioning

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

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

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

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

Quick Start (macOS)

To quickly preview the dashboard locally with Homebrew:

# Install Prometheus and Grafana
brew install prometheus grafana

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

scrape_configs:
  - job_name: dugite
    static_configs:
      - targets: ['localhost:12796']    # match your config's MetricsPort
EOF

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

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

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

# Start services
brew services start prometheus
brew services start grafana

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

To stop:

brew services stop prometheus grafana

Key Queries

Console Logging

In addition to the Prometheus endpoint, Dugite logs sync progress to the console every 5 seconds — but only while catching up. Once the node is following the tip (remaining would be 0) the line stops being emitted, so silence here means "synced", not "stalled". The fields are:

Example log line:

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

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

UTxO RPC (gRPC) Server

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

Quick start

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

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

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

Services exposed

Every service ships in both v1alpha (for backwards compatibility with older clients) and v1beta (current), with one exception: QueryService.ReadState exists only in v1beta — upstream added it after v1alpha was frozen. The spec is pinned in-tree at crates/dugite-rpc/proto/VERSION (currently v0.19.2).

Every method above honours a request's google.protobuf.FieldMask (issue #1004): unselected fields are pruned from the response, recursively, including into repeated fields like FetchBlockResponse.block — see crates/dugite-rpc/src/masking.rs for the exact semantics (a mask that's absent or empty returns everything, matching the canonical FieldMask doc).

Configuration

JSON config block

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

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

All fields are optional. Defaults:

CLI flags

CLI flags override the JSON config block:

Precedence (highest first):

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

Configuration editor (dugite-config)

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

TLS

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

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

Operations

Metrics

The RPC server currently emits no Prometheus metrics. dugite-rpc defines an RpcMetricsSink trait (request_started, request_completed, stream_started, stream_ended) so a host can plug in Prometheus or OpenTelemetry, but dugite-node wires dugite_rpc::noop_metrics() — every callback is a no-op. No dugite_rpc_* series appear on the node's /metrics endpoint.

Until a real sink is wired, observe the RPC server through logs (below) and through the node-level metrics it drives indirectly (dugite_mempool_tx_count, dugite_n2c_txs_*, and friends).

Logging

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

Spec-bump workflow

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

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

The script:

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

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

Limitations

• ReadGenesis populates the full Shelley-genesis section of cardano.Genesis (network_magic, network_id, system_start, security_param, epoch_length, slot_length, max_lovelace_supply, max_kes_evolutions, slots_per_kes_period, update_quorum, active_slots_coeff — 10 of the message's 34 fields). Byron (avvm_distr, boot_stakeholders, heavy_delegation, vss_certs, ...), Alonzo (cost_models, execution_prices, ...), and Conway (committee, constitution, drep_voting_thresholds, ...) sections are unset, as are Shelley's gen_delegs / initial_funds / staking — those genesis structs aren't retained past dugite-node startup today. Tracked as #1009.
• ReadEraSummary's per-era protocol_params is unset: dugite's ledger retains only the CURRENT era's PParams, not a per-era history, so there is nothing truthful to report for a past era. start / end boundaries ARE real (slot, epoch, and absolute wall-clock ms).
• SearchUtxos with a fully-wildcard predicate (no match / combinators) is rejected with UNIMPLEMENTED: dugite refuses to materialise the entire UTxO set in a single response. Supply at least one selector (address / payment_part / delegation_part / asset / composite) so the result set is bounded.
• ReadTx walks at most the last ~43 200 slots of VolatileDB. A chain-wide tx index would extend the lookup window to immutable history; not built today.
• ReadData scans the live UTxO set's inline datums and the mempool's witness-set datums. Witness-set datums from immutable blocks are not retained — clients that need them should consult the originating tx via ReadTx.
• ReadState's AnyChainStateData.cardano is currently empty: the endpoint returns the ledger tip + epoch only. Per-query state projections (stake-pool distribution, DRep info) land on top of this stub.
• EvalTx's per-redeemer ex_units are CEK-machine consumed values, not declared. Cost-model overrides are not yet read from protocol params — the CEK falls back to per-step defaults, which is conservative (over-approximates) and therefore safe for fee-estimation use cases but may diverge slightly from cardano-node on the high end.
• WatchTx / WatchMempool filter on tx output fields (produces / has_address / moves_asset) and minting (mints_asset). Two TxPattern leaves are not implemented: consumes (needs resolved-input UTxO data the watch paths don't have) and has_certificate (needs a certificate-type matcher not yet built). A request naming either — anywhere, including nested under not / all_of / any_of — is rejected with UNIMPLEMENTED before it ever subscribes, rather than silently accepted and under-filtered.
• WatchTx is chain-sourced, matching the proto's own "stream transactions from the chain" comment (SubmitService.WatchMempool is the pre-confirmation counterpart). It subscribes to the same TipFeed/TipRollback broadcast FollowTip uses: each applied block yields one apply WatchTxResponse per matching tx (with AnyChainTx.block populated) or a single idle if the block matched nothing, and a rolled-back block replays its cached matches as undo, most-recent-first. The replay data comes from a per-subscriber bounded history (HISTORY_CAP = 4,320 blocks, above mainnet k = 2,160) built from the subscriber's own apply-time observations — TipRollback does not need to carry the rolled-back block's contents. Was #1007.
• FollowTip apply events carry AnyChainBlock.native_bytes (the raw block CBOR); clients that only need tip metadata can ignore the payload.

See also

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

Relay Node

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

Role in Stake Pool Architecture

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

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

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

Running a Relay

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

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

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

Relay Topology

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

Preview Testnet Relay

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

Mainnet Relay

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

Key topology settings for relays:

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

Multiple Relays

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

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

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

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

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

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

Firewall Configuration

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

Relay firewall rules

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

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

sudo ufw enable

Block producer firewall rules

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

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

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

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

Monitoring

Dugite exposes Prometheus metrics on the port pinned by your config's MetricsPort field — 12796 for preview, 12799 for preprod, 12800 for mainnet in the shipped configs. The built-in fallback when the field is absent is 12796. Key metrics to watch on a relay:

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

Also worth wiring into your supervisor: /ready returns 503 until sync progress reaches 99.9%, and /live returns 503 when no block has been applied within --liveness-threshold-secs (default 600).

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: 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 runs via Sandstone Pool [SAND] on both public testnets — preview (pool ID 6954ec11cf7097a693721104139b96c54e7f3e2a8f9e7577630f7856) and preprod. Forged blocks are additionally cross-validated byte-for-byte against cardano-node on the local devnet before every release.

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-issue-counter-file opcert.counter

--operational-certificate-issue-counter-file is the cardano-cli canonical spelling. The bare --operational-certificate-issue-counter and the legacy dugite spelling --operational-certificate-counter-file are both still accepted as aliases.

KES Keys (Hot)

KES (Key Evolving Signature) keys are rotated periodically. Each KES key is valid for maxKESEvolutions periods of slotsPerKESPeriod slots each. On mainnet, preprod, and preview alike this is 62 periods of 129,600 slots — about 93 days.

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

key-gen-KES, key-gen-VRF, and key-hash-VRF use cardano-cli's canonical mixed-case spelling. All-lowercase forms are accepted as aliases.

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-issue-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

slotsPerKESPeriod is 129,600 on mainnet, preprod, and preview.

Rather than computing it by hand, ask a running node:

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

This reads the opcert, decodes its counter and issue period, queries the node for the current KES period (GetCurrentKESPeriod), and reports whether the certificate is valid, expired, or not yet valid — matching cardano-cli query kes-period-info.

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.

An optional fourth flag, --shelley-cold-key <FILE>, points at the cold signing key and is used only to derive the pool ID for logging and the dugite_pool_id_info metric. It is not required for forging — and on a properly secured setup the cold key lives on an air-gapped machine, so most operators leave it unset.

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 against a running node:

dugite-cli query leadership-schedule \
  --socket-path ./node.sock \
  --testnet-magic 1 \
  --genesis config/preprod/shelley-genesis.json \
  --vrf-signing-key-file vrf.skey \
  --stake-pool-id <pool-id-hex> \
  --current

Required: --genesis (Shelley genesis path) and --vrf-signing-key-file. Identify the pool with either --stake-pool-id or --cold-verification-key-file. Choose the epoch with --current or --next. Output defaults to JSON; use --output-text for the human-readable table, and --out-file to write to disk.

This outputs all slots where your pool is elected to produce a block in the given epoch. The nonce, epoch boundaries, and stake distribution are read from the node — they are not passed as flags.

KES Key Rotation

KES keys must be rotated before they expire. A key issued at period N is valid for periods N through N + 61 (maxKESEvolutions = 62). At 129,600 slots per period and 1-second slots, that is roughly 93 days.

When to rotate

Check where you stand at any time:

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

Plan the rotation about two weeks before the expiry period. Missing it is not a soft failure: once the current KES period passes startPeriod + 62, the node can no longer sign headers and the pool silently stops producing blocks.

Rotation procedure

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, where cold.skey lives):

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

   issue-op-cert increments the counter file in place. Carry the updated opcert.counter back to the air-gapped store — reusing a stale counter produces a certificate the network rejects.

3. Copy kes-new.skey and opcert-new.cert to the block producer, replace the live files, and restart:

   cp kes-new.skey kes.skey
   cp opcert-new.cert opcert.cert
   # Restart the node (SIGTERM, never SIGKILL — see the warning below)
   

4. Confirm the new cert took effect:

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

   The node also logs the operational certificate sequence number and KES period at startup.

Practicalities

• Rotation requires a restart. There is no hot-reload path for forging credentials. Schedule it in a slot where you are not expected to be leader, and keep the restart short — a Mithril-seeded node rejoins in well under a minute, but a cold replay does not.
• Stop with SIGTERM, never SIGKILL. A hard kill can leave the ImmutableDB's active-chunk index unflushed. The node reconciles this at open, but a clean shutdown avoids the recovery path entirely.
• The counter is the state that matters. KES keys are cheap to regenerate; a desynchronised issue counter is what actually locks you out. Back up opcert.counter alongside the cold key.
• Rotate the KES key, not the VRF key. VRF keys are permanent — regenerating one changes your leader schedule and effectively orphans the pool's registration.

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_forged_total (blocks this node minted) alongside dugite_leader_checks_total and dugite_forge_failures_total. dugite_blocks_applied_total counts every block applied from any source, so it tells you nothing about your own forging.
• Set up KES key rotation reminders well before expiry (2 weeks in advance is a good practice).
• Use firewalls to ensure the block producer is not reachable from the public internet.

Snapshot Recovery & Block Forging Readiness

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

Epoch Nonce

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

Pool Stake Reconstruction

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

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

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

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

If your pool shows zero stake after startup, verify:

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

Epoch Numbering

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

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

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

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

Fork Recovery

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

How Fork Detection Works

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

Recovery Cases

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

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

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

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

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

Troubleshooting Block Producer Issues

"Block producer has ZERO stake"

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

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

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

"VRF leader eligibility check failed"

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

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

Pool Registered but No Forge Attempts

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

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

macOS App Nap (macOS only)

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

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

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

Complete Deployment

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

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

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

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

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

Deployment Checklist

1. Set up relay nodes (Relay Node guide)

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

2. Set up the block producer (this page)

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

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

4. Verify block production

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

Local Testnet

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

What this is

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

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

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

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

Prerequisites

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

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

Justfile recipes

The scripts below are the underlying entry points. For everyday use the justfile wraps them — both shapes are equivalent:

devnet-verify and devnet-report locate the newest directory containing a metadata.json under evidence/ or evidence-archive/auto/ — that file is what distinguishes a real soak round from the evidence directories that 09-cli-parity and protocols/ also create.

Both devnet-validate-* recipes install an EXIT trap that runs stop.sh, so an aborted run does not leave orphaned nodes holding ports 3001-3003.

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 under /tmp/ld-$(id -u)/:

Sockets live under /tmp/ld-<uid>/ rather than inside the repo because macOS caps sun_path at 104 bytes, and both a worktree path and the default macOS $TMPDIR (/var/folders/...) blow past that.

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 "/tmp/ld-$(id -u)/dbp.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 five pass/fail predicates and writes evidence/<timestamp>/report.md. Predicates:

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

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

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

Topology & port reference

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

Monitoring with dugite-monitor

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

./target/release/dugite-monitor

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

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

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

Configuration reference

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

config/spec/shelley-spec.json:

Note that the protocol version lives in shelley-spec.json, not in the Conway spec. config/spec/conway-spec.json carries the Conway governance parameters — pool/DRep voting thresholds, govActionLifetime (6 epochs), govActionDeposit, dRepDeposit, dRepActivity, minFeeRefScriptCostPerByte, and the Plutus V3 cost model. Those values are load-bearing for the governance, proposal, and voting categories of the tx-zoo, so they are not inert filler even on a short run.

Troubleshooting

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

What this validates

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

What this does NOT validate

• Byron-era code paths (chain boots in Conway)
• Hard-fork combinator era transitions (none occur during the soak)
• Multi-relay diffusion topologies (single hub)
• Plutus phase-2 / governance enactment — the soak itself submits only identical self-payments. Scripts, proposals, voting, and enactment are covered by the tx-zoo (03, 06, 07, 10, 12) under a separate driver
• Symmetric multi-forger chain selection (cardano-node is a validator here, not a forger — see "Historical note" at top)
• Mainnet-scale peer counts, NAT/firewall behaviour, or BGP-level routing
• Mithril snapshot import (covered by other tests)

Transaction validation (tx-zoo)

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

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

The zoo covers 12 categories (111 scripts total):

Each script submits through the dugite relay socket and waits for inclusion at that same socket to guarantee diffusion + validation on the dugite path before recording PASS/FAIL/SKIP into tx-zoo/state/results.csv.

Reading 09-cli-parity: it runs cardano-cli against both sockets and diffs the responses — it never invokes dugite-cli. What it measures is dugite-node's LSQ responses. A failure on both sides is a harness bug, never a dugite-cli gap.

Requirements

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

Caveats

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

Seated CC member

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

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

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

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

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

Kubernetes Deployment

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

Prerequisites

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

Quick Start

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

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

The chart version (0.9.3) and the node version it deploys (appVersion 2.4.3) move independently — check charts/dugite-node/Chart.yaml for the current pair. Omit --version to take the latest published chart.

Or install from a local checkout:

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

This will:

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

Chart Reference

Node role

The chart supports two deployment modes:

# Relay node (default)
role: relay

# Block producer
role: producer

Network selection

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

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

Persistence

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

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

Resources

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

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

Mithril import

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

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

Storage profile

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

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

Metrics and monitoring

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

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

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

UTxO RPC (gRPC) server — #672

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

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

Consensus mode (genesis sync) — #535

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

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

Logging

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

Liveness threshold

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

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

Topology

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

Peer targets and governor tuning

These mirror cardano-node's defaults. Leave them alone unless you have a measured reason to change them.

network:
  targetRootPeers: 60
  targetActivePeers: 20
  targetEstablishedPeers: 30
  targetKnownPeers: 150
  targetActiveBigLedgerPeers: 5
  targetEstablishedBigLedgerPeers: 10
  targetKnownBigLedgerPeers: 15

peerGovernor:
  churnIntervalNormalSecs: 3300   # 55 min
  churnIntervalSyncSecs: 900      # 15 min
  stallDemotionCycles: 6          # each ~30s
  errorDemotionThreshold: 5

Probes

livenessProbe:
  httpGet: { path: /live, port: metrics }
  initialDelaySeconds: 120
  periodSeconds: 30
  failureThreshold: 5

readinessProbe:
  httpGet: { path: /health, port: metrics }
  initialDelaySeconds: 30
  periodSeconds: 10
  failureThreshold: 3

Both probes are automatically disabled when metrics.enabled=false, since they target the metrics port. Liveness uses /live (forward progress — restarts a wedged node) rather than /ready (sync progress), so a node that is merely still syncing is never restart-looped. See Monitoring for the endpoint semantics.

Security contexts

The chart runs as non-root with a read-only root filesystem by default:

podSecurityContext:
  runAsNonRoot: true
  runAsUser: 65532
  runAsGroup: 65532
  fsGroup: 65532
  seccompProfile: { type: RuntimeDefault }

securityContext:
  allowPrivilegeEscalation: false
  readOnlyRootFilesystem: true
  capabilities: { drop: [ALL] }

readOnlyRootFilesystem: true is safe because the chart mounts writable volumes at /data/db, /ipc, and /tmp.

NetworkPolicy

networkPolicy:
  enabled: true    # only takes effect when role=producer

Set to false if your cluster has no NetworkPolicy controller — otherwise the policy is written but silently unenforced, which is worse than not having it.

Relay Node Deployment

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

Minimal relay

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

Relay with custom topology

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

relay-values.yaml:

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

Relay with Prometheus Operator

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

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

Block Producer Deployment

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

Create keys Secret

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

Deploy the producer

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

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

Producer security

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

• Restricts N2N ingress to pods labeled app.kubernetes.io/component: relay in the same namespace — the rule uses a bare podSelector with no namespaceSelector, so a relay deployed to a different namespace will be blocked.
• Allows metrics scraping (and, when rpc.enabled and rpc.service are both true, RPC) from anywhere in the cluster.
• Declares policyTypes: [Ingress] only, so egress stays unrestricted and the BP can reach its relay(s).

Set networkPolicy.enabled=false to skip it — for example on a cluster with no NetworkPolicy controller, where an unenforced policy gives false assurance.

Block producers should never be exposed directly to the internet.

Producer + Relay architecture

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

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

Deploy both:

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

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

producer-values.yaml:

network:
  diffusionMode: InitiatorOnly
  peerSharing: false

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

Verifying the Deployment

Pod status:

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

Logs:

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

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

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

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

Metrics:

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

UTxO RPC (if rpc.enabled=true):

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

Configuration Reference

CLI Overview

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

Binary

dugite-cli [COMMAND] [OPTIONS]

Command Groups

The key command group (generate-payment-key, generate-stake-key, verification-key-hash) is a dugite-only convenience extension with no cardano-cli counterpart. The cardano-cli equivalents — address key-gen, stake-address key-gen, and address key-hash — are also implemented, so scripts written against cardano-cli work unchanged. See Key Generation for the mapping.

Era Prefixes

cardano-cli 11 accepts commands only in their era-prefixed form, e.g. cardano-cli conway stake-pool registration-certificate .... dugite accepts both the era-prefixed form (conway, babbage, alonzo, mary, allegra, shelley, latest) and the flat form (dugite-cli stake-pool registration-certificate ...) — every era prefix routes to the same handler, since dugite is era-agnostic at the CLI surface. This makes dugite a strict superset: any cardano-cli-compatible script works unchanged, and existing dugite scripts using the flat form keep working too.

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. The two subcommands used in day-to-day operation are run (start the node) and mithril-import (import a Mithril snapshot for fast initial sync), documented below.

The binary also ships several operator/debug subcommands not covered in detail here: db info (database size and block count), dump-snapshot (replay the chain and dump ledger state at epoch boundaries, for cross-validation), verify-ledger-snapshot (byte-exact comparison of two ledger snapshots), and snapshot-convert (convert a ledger snapshot between the in-memory and LSM UTxO backends without a chain replay). Run dugite-node <subcommand> --help for their flags.

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.

The key group is a dugite extension. key generate-payment-key, key generate-stake-key, and key verification-key-hash have no cardano-cli counterpart — they are additive convenience commands. The cardano-cli equivalents are also implemented and produce compatible output:

dugite extension	cardano-cli equivalent
key generate-payment-key	address key-gen
key generate-stake-key	stake-address key-gen
key verification-key-hash	address key-hash / stake-address key-hash

Scripts written against cardano-cli never need the key group; it exists because it is convenient and already in use.

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)

The cardano-cli-compatible equivalent is dugite-cli address key-gen --verification-key-file payment.vkey --signing-key-file payment.skey.

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

The cardano-cli-compatible equivalent is dugite-cli stake-address key-gen --verification-key-file stake.vkey --signing-key-file stake.skey (see Stake Address Commands).

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.

Only Ed25519 verification-key envelope types are accepted (payment, stake, stake pool, genesis, genesis-delegate, genesis-UTxO, DRep, and CC cold/hot verification keys). Signing keys and KES/VRF verification keys are rejected with an error naming the offending envelope type — VRF key hashes use a different convention and are computed with node key-hash-VRF instead (see Node Commands).

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

See Node Commands for the full flag reference, including --key-output-bech32 / --key-output-text-envelope and the canonical --operational-certificate-issue-counter-file spelling. The short version:

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-issue-counter-file opcert.counter

--operational-certificate-issue-counter-file is the cardano-cli-canonical spelling; --operational-certificate-issue-counter and --operational-certificate-counter-file are accepted as aliases.

KES Keys

Generate Key Evolving Signature keys (rotated periodically). The canonical cardano-cli subcommand casing is key-gen-KES (cardano-cli rejects lowercase); dugite additionally accepts key-gen-kes as a backward-compatible alias:

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). Canonical casing is key-gen-VRF, with key-gen-vrf accepted as an alias:

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-issue-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

--mainnet and --testnet-magic <NATURAL> are mutually exclusive (cardano-cli compatible). Instead of a key file, the payment and stake keys can be passed inline as a bech32 or hex string:

dugite-cli address build \
  --payment-verification-key "addr_vk1..." \
  --stake-verification-key "stake_vk1..." \
  --mainnet

dugite additionally accepts a --network mainnet|testnet flag (its own extension, predating --mainnet/--testnet-magic) and, when none of --mainnet, --testnet-magic, or --network is given, falls back to the CARDANO_NODE_NETWORK_ID environment variable (mainnet or a magic number), matching cardano-cli. Resolution order: explicit flags, then --network, then CARDANO_NODE_NETWORK_ID, then mainnet. An unrecognized value from any of these sources is a hard error naming the accepted forms — it never falls back to testnet silently.

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

transaction build-raw accepts the identical flag set and produces identical output — it exists only so scripts that call cardano-cli transaction build-raw work unchanged.

Arguments

Plutus and Conway flags

Auto-balance mode

When --socket-path is provided and --fee is not explicitly set, transaction build connects to the node, queries UTxO values for the given inputs and the current protocol parameters, computes the fee automatically, derives a change output at --change-address, and writes a balanced transaction — matching cardano-cli transaction build's behavior (as opposed to build-raw's fully manual fee/change accounting):

dugite-cli transaction build \
  --tx-in "abc123...#0" \
  --tx-out "addr_test1qz...+5000000" \
  --change-address "addr_test1qp..." \
  --socket-path ./node.sock \
  --testnet-magic 2 \
  --out-file tx.body

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

Hash Script Data

Compute the script-data hash (datum + redeemers + language views) used in a transaction's scriptDataHash field:

dugite-cli transaction hash-script-data \
  --datum-file datum.json \
  --redeemer-file redeemer.json

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

Alternatively, query one or more specific UTxOs by transaction input reference (--tx-in may be repeated), or dump the entire UTxO set with --whole (warning: very large on mainnet):

dugite-cli query utxo \
  --tx-in "abc123...#0" \
  --tx-in "def456...#1" \
  --socket-path ./node.sock \
  --testnet-magic 2

dugite-cli query utxo --whole --socket-path ./node.sock

Exactly one of --address, --tx-in, or --whole must be provided.

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 is JSON by default (matching cardano-cli), keyed by pool ID hex with each pool's stake expressed as an exact num/den fraction of total active stake; pass --output-text for the human-readable table below, or --out-file to write to a file instead of stdout.

JSON output (default):

{
  "<pool_id_hex>": {
    "poolId": "<pool_id_hex>",
    "stakeFraction": "1/8523"
  }
}

--output-text output:

PoolId                                                       Stake Fraction
--------------------------------------------------------------------------------
<pool_id_hex>                                                    0.0001173413

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 the IDs of all registered stake pools (use Pool Parameters below for the pledge/cost/margin of a specific pool):

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

Output is a JSON array of bech32 pool IDs by default (matching cardano-cli), sorted by raw hash bytes; --output-text prints the same IDs newline-separated instead. --out-file writes to a file instead of stdout. --output-yaml is accepted by the flag parser but not yet implemented — it currently errors at runtime.

JSON output (default):

[
    "pool1abc...",
    "pool1def..."
]

Pool Parameters

Query detailed parameters for a specific pool:

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

Non-Myopic Member Rewards

Query expected (non-myopic) member rewards for hypothetical delegator stakes, matching cardano-cli query non-myopic-member-rewards. Returns the expected lovelace reward for each requested stake amount against every registered pool, assuming ideal performance — used as input to pool-ranking tools:

dugite-cli query non-myopic-member-rewards \
  --socket-path ./node.sock \
  --stake 1000000000

--stake may be repeated for multiple hypothetical stake values (in lovelace); it defaults to 1 ADA when omitted.

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 is JSON by default (matching cardano-cli); pass --output-text for the human-readable summary shown below, or --out-file to write to a file.

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. Exactly one DRep selector is required — there is no bare "all DReps" default:

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

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

These selector flags are mutually exclusive — pass exactly one.

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 balance (matches cardano-cli query treasury, which reports treasury only — not reserves):

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

The default output is the bare lovelace integer (cardano-cli-compatible):

1234567890000000

--output-text prints a human-readable summary that includes both treasury and reserves:

Account State
=============
Treasury: 1234567890000000 lovelace (1234567 ADA)
Reserves: 9876543210000000 lovelace (9876543 ADA)

--out-file writes the selected format to a file instead of stdout.

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

Governance Proposals (Conway)

Query active governance action proposals, matching cardano-cli query proposals:

# All live proposals
dugite-cli query proposals --socket-path ./node.sock

# Filter to a specific proposal
dugite-cli query proposals \
  --socket-path ./node.sock \
  --governance-action-tx-id a1b2c3d4... \
  --governance-action-index 0

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

Unlike the other queries above, the default output here is the human-readable text summary shown below; pass --output-json for JSON, or --out-file to write to a file.

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 slots a stake pool is expected to mint a block in, matching cardano-cli query leadership-schedule. This queries the running node for live stake and epoch state (via --socket-path) rather than taking manual stake/coefficient inputs:

dugite-cli query leadership-schedule \
  --socket-path ./node.sock \
  --testnet-magic 2 \
  --genesis config/preview/shelley-genesis.json \
  --stake-pool-id pool1abc... \
  --vrf-signing-key-file vrf.skey \
  --current

Ledger State (Debug)

Dump the raw ledger state (debug endpoint):

dugite-cli query ledger-state \
  --socket-path ./node.sock \
  --out-file ledger-state.cbor

Protocol State (Debug)

Dump the raw protocol (consensus) state — includes the KES evolving nonce, candidate nonce, and epoch nonce (debug endpoint):

# Raw CBOR hex (default)
dugite-cli query protocol-state --socket-path ./node.sock

# JSON, matching cardano-cli's --output-json
dugite-cli query protocol-state \
  --socket-path ./node.sock \
  --output-json

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

key-hash

Get the Blake2b-224 hash of a stake verification key:

dugite-cli stake-address key-hash \
  --stake-verification-key-file stake.vkey

This is the cardano-cli-compatible equivalent of dugite-cli key verification-key-hash --verification-key-file stake.vkey (see Key Generation).

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-issue-counter-file opcert.counter \
  --kes-period 400 \
  --out-file opcert.cert

This is the same underlying implementation as node issue-op-cert (see Node Commands) — the two subcommands are interchangeable.

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-issue-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. The canonical cardano-cli subcommand casing is key-gen-KES (cardano-cli itself rejects the lowercase form); dugite also accepts key-gen-kes as a backward-compatible alias.

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. Canonical casing is key-gen-VRF; key-gen-vrf is accepted as an alias.

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.

key-hash-VRF

Get the Blake2b-256 hash of a VRF verification key. Canonical casing is key-hash-VRF; key-hash-vrf is accepted as an alias.

dugite-cli node key-hash-VRF \
  --verification-key-file vrf.vkey

Note this hash uses Blake2b-256 (32 bytes) — a different convention from key verification-key-hash, which is Blake2b-224 (28 bytes) and rejects VRF/KES key types outright.

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-issue-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-issue-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 \
  --prev-governance-action-tx-id "d4e5f6a7..." \
  --prev-governance-action-index 0 \
  --constitution-script-hash "b8c9d0e1..." \
  --out-file pp-update.json

--prev-governance-action-tx-id/--prev-governance-action-index (the enacted-action chain pointer) and --constitution-script-hash (the optional guardrail script hash) may be omitted.

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 16-crate Cargo workspace under crates/ (plus an xtask build-tooling crate and two test-only crates, tests/conformance and tests/golden, outside crates/). Each crate has a focused responsibility and well-defined dependencies.

Crate Workspace