Skip to content

Getting Started for Developers

Jump to bottom
Michael Fazio edited this page Mar 17, 2026 · 6 revisions

Getting Started for Developers

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

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/torsten.git
cd torsten

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

# Build release binary
cargo build --release

Run Tests

# Run all tests
cargo test --all

# Run tests for a single crate
cargo test -p torsten-ledger

# Run a single test by name
cargo test -p torsten-ledger -- test_name

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 14-crate Cargo workspace under crates/:

Crate Purpose
torsten-primitives Core types: hashes, blocks, transactions, addresses, values, protocol parameters (all eras Byron-Conway)
torsten-crypto Ed25519 keys, VRF (ECVRF-ED25519-SHA512-Elligator2), KES (Sum6Kes), text envelope format
torsten-serialization CBOR encoding/decoding via pallas
torsten-network Ouroboros mini-protocols (N2N/N2C), multiplexer, pipelined ChainSync client
torsten-consensus Ouroboros Praos, chain selection, epoch transitions, VRF leader check
torsten-ledger UTxO set (UTxO-HD), transaction validation (Phase-1/Phase-2), ledger state, certificates, rewards, governance
torsten-mempool Thread-safe transaction mempool
torsten-storage ChainDB = ImmutableDB (append-only chunk files) + VolatileDB (in-memory HashMap)
torsten-lsm Custom LSM-tree storage engine with WAL for the on-disk UTxO store
torsten-node Main node binary: config, topology, pipelined sync, Mithril import, block forging
torsten-cli cardano-cli compatible CLI (33+ subcommands)
torsten-integration-tests Integration test suite
tests/conformance Protocol conformance tests
tests/golden Golden test suite

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/torsten-node/src/main.rs — Entry point, node startup and sync loop
  3. crates/torsten-ledger/src/lib.rs — Ledger state and block application
  4. crates/torsten-storage/src/chain_db.rs — ChainDB (ImmutableDB + VolatileDB)
  5. crates/torsten-network/src/lib.rs — Network protocol multiplexer
  6. crates/torsten-consensus/src/lib.rs — Consensus engine and epoch transitions
  7. crates/torsten-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/torsten-node mithril-import \
  --network-magic 2 \
  --database-path ./db-preview

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

Torsten 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
TORSTEN_PIPELINE_DEPTH 150 ChainSync pipeline depth
RUST_LOG info Log level (trace, debug, info, warn, error)

Further Reading

Clone this wiki locally