Skip to content

Getting Started for Developers

Jump to bottom
Michael Fazio edited this page May 23, 2026 · 6 revisions

Getting Started for Developers

This guide covers everything you need to start contributing to Dugite.

Prerequisites

  • Rust (stable toolchain, edition 2021) — install via rustup
  • Git
  • ~8 GB RAM for building and running tests
  • Linux or macOS (Windows is untested)

No system-level library dependencies are required. The storage layer is pure Rust. On Linux, the optional io-uring feature can be enabled for async I/O.

Clone and Build

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

# Build everything (debug)
cargo build --all-targets

# Build release binary
cargo build --release

Run Tests

# Run all tests (nextest — parallel, matches CI)
cargo nextest run --workspace

# Run tests for a single crate
cargo nextest run -p dugite-ledger

# Run a single test by name
cargo nextest run -p dugite-ledger -E 'test(test_name)'

# Run doc tests (nextest doesn't support these yet)
cargo test --doc

Lint and Format

All code must pass these checks before committing:

# Clippy (zero warnings required)
cargo clippy --all-targets -- -D warnings

# Format check
cargo fmt --all -- --check

# Fix formatting
cargo fmt --all

Workspace Structure

The project is a 15-crate Cargo workspace under crates/:

Crate Purpose
dugite-primitives Core types: hashes, blocks, transactions, addresses, values, protocol parameters (all eras Byron-Conway)
dugite-crypto Ed25519 keys, VRF (ECVRF-ED25519-SHA512-Elligator2), KES (Sum6Kes), text envelope format
dugite-serialization In-house multi-era CBOR encoder/decoder (minicbor-based)
dugite-uplc In-house UPLC CEK machine — 100% conformant; used by dugite-ledger for Phase-2 Plutus evaluation
dugite-network Ouroboros mini-protocols (N2N/N2C), multiplexer, pipelined ChainSync client
dugite-consensus Ouroboros Praos, chain selection, epoch transitions, VRF leader check
dugite-ledger UTxO set (UTxO-HD), transaction validation (Phase-1/Phase-2), ledger state, certificates, rewards, governance
dugite-mempool Thread-safe transaction mempool with input-conflict checking and TTL sweep
dugite-lsm Pure-Rust LSM-tree engine for the on-disk UTxO set; optional io-uring feature on Linux
dugite-storage ChainDB = ImmutableDB (append-only chunk files) + VolatileDB (in-memory HashMap). On-disk UTxO set is backed by dugite-lsm
dugite-node Main node binary: config, topology, pipelined sync, Mithril import, block forging
dugite-cli cardano-cli compatible CLI (38+ subcommands)
dugite-monitor Terminal monitoring dashboard (ratatui-based, polls Prometheus endpoint)
dugite-config Interactive TUI configuration editor: tree navigation, inline editing, type validation, search/filter, diff view, init/validate/get/set subcommands

Plus integration test suites under tests/conformance (protocol conformance) and tests/golden (golden tests).

Key Files to Read First

If you are new to the codebase, start with these files to build understanding:

  1. CLAUDE.md (repo root) — Architecture overview, build commands, key patterns
  2. crates/dugite-node/src/main.rs — Entry point, node startup and sync loop
  3. crates/dugite-ledger/src/lib.rs — Ledger state and block application
  4. crates/dugite-storage/src/chain_db.rs — ChainDB (ImmutableDB + VolatileDB)
  5. crates/dugite-network/src/lib.rs — Network protocol multiplexer
  6. crates/dugite-consensus/src/lib.rs — Consensus engine and epoch transitions
  7. crates/dugite-primitives/src/lib.rs — Core type definitions

Running on Preview Testnet

The fastest way to get a running node is to use the preview testnet with Mithril snapshot import:

# Step 1: Build release binary
cargo build --release

# Step 2: Import Mithril snapshot (preview, network-magic=2)
./target/release/dugite-node mithril-import \
  --network-magic 2 \
  --database-path ./db-preview

# Step 3: Run the node
./target/release/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

Network magic values: Mainnet=764824073, Preview=2, Preprod=1

Prometheus metrics are available at http://localhost:12798/metrics.

Development Workflow

Dugite follows an iterative development approach:

  1. Assess — Evaluate the current state of the codebase and identify the highest-impact gap or bug to address next
  2. Implement — Build the next feature or fix, keeping changes focused and reviewable
  3. Test — Run cargo test --all and ensure zero failures before moving on
  4. Verify — Run clippy and fmt checks; all code must be warning-free and formatted
  5. Commit — Commit with a descriptive message and push to the remote branch
  6. Repeat — Move on to the next highest-priority item

Hard Rules

  • Zero compiler warnings (RUSTFLAGS="-D warnings")
  • Clippy clean
  • All tests passing
  • Code formatted
  • CI green before merge

Useful Environment Variables

Variable Default Description
DUGITE_PIPELINE_DEPTH 300 ChainSync pipeline depth
RUST_LOG info Log level (trace, debug, info, warn, error)

Further Reading

Clone this wiki locally
⚡