dusk-network · HDauven · Feb 12, 2026 · Feb 11, 2026
diff --git a/README.md b/README.md
@@ -40,6 +40,7 @@ For more information on **running a node for main- or testnet**, see our
   - [Setup script](#setup-script)
   - [Rust Installation](#rust-installation)
 - [Build and Tests](#️-build-and-tests)
+- [Make Commands](#-make-commands)
 - [Run a local node for development](#-run-a-local-node-for-development)
   - [Spin up local node](#spin-up-local-node)
     - [Prepare modules](#prepare-modules)
@@ -123,7 +124,30 @@ make test
 ```
 
 That will also compile all the genesis contracts and its associated circuits.
-See also `make help` for all the available commands
+See also `make help` for all the available commands.
+
+## 📋 Make Commands
+
+| Command | Description |
+|---------|-------------|
+| `make` | Build everything (keys, wasm, abi, state, rusk, rusk-wallet) |
+| `make help` | Display available make commands |
+| `make abi` | Build the ABI |
+| `make keys` | Generate ZK circuit proving keys |
+| `make state` | Create the network genesis state |
+| `make wasm` | Compile wallet-core to WASM |
+| `make data-drivers` | Build data-driver WASM files |
+| `make data-drivers-js` | Build data-driver WASM files with JS/alloc support |
+| `make rusk` | Build the rusk node binary |
+| `make rusk-wallet` | Build the CLI wallet binary |
+| `make test` | Run the full test suite |
+| `make clippy` | Run clippy on all crates (warnings = errors) |
+| `make doc` | Generate documentation for all crates |
+| `make bench` | Run benchmarks for node and rusk |
+| `make prepare-dev` | One-time setup for local development node |
+| `make run-dev` | Launch local ephemeral node |
+| `make run-dev-archive` | Launch local ephemeral archive node |
+| `make run` | Build and run the node (with keys and state) |
 
 ## 💻 Run a local node for development
 

diff --git a/consensus/README.md b/consensus/README.md
@@ -1,3 +1,26 @@
-Implementation of Dusk [Succinct Attestation] consensus protocol 
+<div align="center">
 
-[Succinct Attestation]: (https://github.com/dusk-network/docs/blob/main/src/content/docs/learn/deep-dive/succinct-attestation.md)
+# `🔗 Dusk Consensus`
+
+> Implementation of Dusk's [Succinct Attestation](https://github.com/dusk-network/docs/blob/main/src/content/docs/learn/deep-dive/succinct-attestation.md) consensus protocol
+</div>
+
+## Overview
+
+Dusk Consensus implements the Succinct Attestation (SA) protocol, which drives block production and finality on the Dusk network. It coordinates a multi-phase process — proposal, validation, and ratification — where provisioners vote on candidate blocks and aggregate their votes into a compact attestation.
+
+## Key Components
+
+| Component | Description |
+|-----------|-------------|
+| Consensus state machine | Drives the proposal / validation / ratification phases |
+| Vote aggregation | Collects and verifies BLS-signed votes from provisioners |
+| Quorum logic | Determines when sufficient stake weight has voted to finalize |
+| Merkle aggregation | Batches proofs for efficient on-chain verification |
+
+## Related Crates
+
+- [`node-data`](../node-data/) — defines consensus message types and ledger structures
+- [`dusk-core`](../core/) — BLS signatures used for vote signing
+- [`node`](../node/) — integrates the consensus engine into the full node runtime
+- [`rusk`](../rusk/) — orchestrates consensus as part of the node entrypoint
diff --git a/core/README.md b/core/README.md
@@ -5,8 +5,26 @@
 > Core types used within Dusk, for writing smart contracts and interacting with Dusk
 </div>
 
+## Overview
+
+Dusk-core is the foundation crate for the entire Rusk workspace. It provides the cryptographic primitives, transaction types, and contract ABI that nearly every other crate depends on. It is `no_std` compatible, making it suitable for use inside WASM smart contracts.
+
+## What It Provides
+
+| Area | Description |
+|------|-------------|
+| Signatures | BLS signatures (bls12-381) and Schnorr signatures (JubJub) |
+| Zero-knowledge | PLONK and Groth16 circuit types and proof structures |
+| Transactions | Types for both Phoenix (shielded/UTXO) and Moonlight (public/account) models |
+| Contract ABI | Host functions and interfaces for smart contract development |
+| Serialization | `rkyv` and `dusk-bytes` based encoding for all core types |
+
 ## abi / abi-dlmalloc feature
 
 When importing core with `abi-dlmalloc`, a smart contract developer on Dusk is able to use the abi host functions provided through it.
 
-The current available host functions can be seen in the host_queries module in [abi.rs](./src/abi.rs) 
+The current available host functions can be seen in the host_queries module in [abi.rs](./src/abi.rs)
+
+## Related Crates
+
+Dusk-core is foundational — it is depended on by nearly every other crate in the workspace, including [`node-data`](../node-data/), [`consensus`](../consensus/), [`node`](../node/), [`vm`](../vm/), [`rusk`](../rusk/), [`wallet-core`](../wallet-core/), [`rusk-prover`](../rusk-prover/), and the [contracts](https://github.com/dusk-network/contracts).
diff --git a/node-data/README.md b/node-data/README.md
@@ -0,0 +1,40 @@
+<div align="center">
+
+# `📊 Node Data`
+
+> Core datatypes for the Dusk blockchain node — ledger structures, network messages, and wire-format encoding
+</div>
+
+## Overview
+
+Node Data is the shared vocabulary between [`node`](../node/), [`consensus`](../consensus/), and [`rusk`](../rusk/). It defines all types that travel across the network or get persisted to the ledger, along with deterministic serialization logic for wire compatibility.
+
+## Modules
+
+| Module | Description |
+|--------|-------------|
+| `bls` | BLS public key wrappers with base58 and hex encoding |
+| `ledger` | `Header`, `Block`, `SpentTransaction`, `Fault`, `Slash`, `Attestation` |
+| `message` | Consensus message types with versioning and status tracking |
+| `encoding` | `Serializable` trait for deterministic wire-format encoding |
+| `events` | Block, transaction, and contract event types |
+
+## Serialization
+
+> **Warning**: Field ordering in serialized types is protocol-sensitive. Reordering fields or changing encoding can break network compatibility between nodes.
+
+All wire-format types implement the `Serializable` trait, which provides `read` and `write` methods for deterministic binary encoding.
+
+## Features
+
+| Feature | Description |
+|---------|-------------|
+| `faker` | Generates test data via the `fake` crate |
+
+## Related Crates
+
+- [`dusk-core`](../core/) — foundation types (signatures, scalars)
+- [`node`](../node/) — consumes ledger and message types for chain operations
+- [`consensus`](../consensus/) — consumes message types for consensus protocol
+- [`rusk`](../rusk/) — consumes event and ledger types for APIs
+- [`rusk-wallet`](../rusk-wallet/) — consumes ledger types for transaction display
diff --git a/node/README.md b/node/README.md
@@ -1,6 +1,37 @@
- # Dusk node library
+<div align="center">
 
-The Dusk Node functionality crate.
+# `🌐 Dusk Node`
+
+> Chain node implementation — networking, mempool, storage, and synchronization
+</div>
+
+## Overview
+
+Dusk Node is the chain layer of the Dusk blockchain. It manages peer-to-peer networking, transaction pooling, persistent ledger storage, and chain synchronization. It integrates the [`consensus`](../consensus/) engine and is orchestrated by [`rusk`](../rusk/).
+
+## Key Modules
+
+| Module | Description |
+|--------|-------------|
+| `database` | RocksDB-based ledger storage |
+| `mempool` | Transaction pool management and eviction |
+| `network` | Peer communication via Kadcast |
+| `databroker` | Block and transaction serving to peers |
+| `telemetry` | Metrics collection and reporting |
+
+## Features
+
+| Feature | Description |
+|---------|-------------|
+| `archive` | SQLite-based historical data indexing (see below) |
+| `network-trace` | Network-level debug tracing |
+
+## Related Crates
+
+- [`node-data`](../node-data/) — ledger and message types consumed by the node
+- [`dusk-consensus`](../consensus/) — consensus engine driving block production
+- [`dusk-core`](../core/) — cryptographic signatures and transaction types
+- [`rusk`](../rusk/) — orchestrates the node as part of the full binary
 
 ## Archive feature
 

diff --git a/rusk-profile/README.md b/rusk-profile/README.md
@@ -0,0 +1,32 @@
+<div align="center">
+
+# `🪪 Rusk Profile`
+
+> Manages the local Rusk profile directory for circuit artifacts, proving keys, and genesis state
+</div>
+
+## Overview
+
+Rusk Profile manages the `~/.dusk/rusk/` directory tree that stores ZK circuit artifacts, proving/verifier keys, the Common Reference String (CRS), consensus keys, and genesis state. It provides integrity verification (blake3, SHA-256) for all trusted setup artifacts.
+
+## Directory Layout
+
+```
+~/.dusk/rusk/
+├── circuits/    # ZK circuit prover/verifier keys (blake3-verified)
+├── keys/        # Consensus keys
+├── state/       # Genesis and recovered chain state
+└── drivers/     # Data-driver WASM storage
+```
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `RUSK_PROFILE_PATH` | Override the default `~/.dusk/rusk` profile location |
+
+## Related Crates
+
+- [`rusk-prover`](../rusk-prover/) — loads circuit prover keys from the profile
+- [`rusk-recovery`](../rusk-recovery/) — writes state and keys into the profile
+- [`rusk`](../rusk/) — reads genesis state from the profile at startup
diff --git a/rusk-prover/README.md b/rusk-prover/README.md
@@ -0,0 +1,35 @@
+<div align="center">
+
+# `📨 Rusk Prover`
+
+> Local PLONK zero-knowledge prover for Phoenix (shielded) transactions
+</div>
+
+## Overview
+
+Rusk Prover generates PLONK zero-knowledge proofs for Phoenix transactions locally. It implements the `dusk_core::transfer::phoenix::Prove` trait and supports transaction circuits with 1 to 4 input notes (each producing 2 output notes). Prover keys are loaded lazily from [`rusk-profile`](../rusk-profile/).
+
+## How It Works
+
+1. Receives a serialized `TxCircuitVec` containing the transaction circuit data
+2. Selects the matching circuit variant based on the number of input notes:
+   - `1-in / 2-out`
+   - `2-in / 2-out`
+   - `3-in / 2-out`
+   - `4-in / 2-out`
+3. Loads the corresponding prover key from the profile directory (cached after first load)
+4. Generates and returns the PLONK proof
+
+## Features
+
+| Feature | Description |
+|---------|-------------|
+| `no_random` | Use a seeded RNG for deterministic proofs (for testing) |
+| `debug` | Enable tracing and hex logging of proof data |
+
+## Related Crates
+
+- [`dusk-core`](../core/) — defines the `Prove` trait and Phoenix circuit types
+- [`rusk-profile`](../rusk-profile/) — stores and retrieves circuit prover keys
+- [`rusk`](../rusk/) — uses the prover in prover node mode (`--features prover`)
+- [`rusk-test`](../rusk-test/) — uses the prover with `no_random` + `debug` for deterministic test proofs
diff --git a/rusk-recovery/README.md b/rusk-recovery/README.md
@@ -0,0 +1,48 @@
+<div align="center">
+
+# `⬇️ Rusk Recovery`
+
+> Bootstrap and recovery utilities for initializing a Dusk node
+</div>
+
+## Overview
+
+Rusk Recovery provides tools to bootstrap a new node or restore an existing one. It can deploy genesis state from snapshot configurations and download circuit proving keys, writing everything into the [`rusk-profile`](../rusk-profile/) directory.
+
+## Features
+
+Both features are optional and gated behind Cargo feature flags:
+
+| Feature | Description |
+|---------|-------------|
+| `state` | Deploy genesis state from snapshots (local TOML, HTTP, zip, or tar archives) |
+| `keys` | Download and verify ZK circuit proving keys from the network |
+
+### State Recovery
+
+The `state` feature provides:
+- `Snapshot` — genesis configuration defining initial balances and stakes
+- `PhoenixBalance` — shielded (Phoenix) balance entries
+- `GenesisStake` — initial stake allocations
+- `deploy()` — populates the transfer and stake contracts with genesis data
+
+### Key Recovery
+
+The `keys` feature downloads circuit prover/verifier keys and verifies their integrity before storing them in the profile directory.
+
+## Usage
+
+Recovery is typically invoked through Make targets rather than directly:
+
+```bash
+make keys          # Download circuit proving keys
+make state         # Generate genesis state
+make prepare-dev   # Keys + state + example consensus keys
+```
+
+## Related Crates
+
+- [`rusk-profile`](../rusk-profile/) — target directory for recovered state and keys
+- [`dusk-vm`](../vm/) — used to deploy genesis state into the VM
+- [`rusk`](../rusk/) — invokes recovery during first-run initialization
+- [`rusk-test`](../rusk-test/) — uses state recovery to set up ephemeral test nodes
diff --git a/rusk-test/README.md b/rusk-test/README.md
@@ -0,0 +1,35 @@
+<div align="center">
+
+# `🧪 Rusk Test`
+
+> Integration test harness and utilities for the Rusk workspace
+</div>
+
+## Overview
+
+Rusk Test provides a shared test harness for integration tests across the workspace. It can spin up an ephemeral Rusk node with genesis state, offers a deterministic test wallet, and includes async helpers for bridging async code into synchronous test contexts.
+
+## Key Utilities
+
+| Utility | Description |
+|---------|-------------|
+| `new_state()` | Creates an ephemeral Rusk instance populated from a genesis snapshot |
+| `new_state_with_chainid()` | Same as above, with a custom chain ID |
+| `TestStateClient` | Wraps a Rusk instance with a mock Phoenix note cache |
+| `TestStore` | Wallet store backed by a fixed seed (`[0u8; 64]`) for deterministic keys |
+| `logger()` | Initializes `tracing` with a default filter (overridable via `RUST_LOG`) |
+| `Block::wait()` | Async-to-sync bridge for blocking on futures in test contexts |
+
+## Features
+
+| Feature | Description |
+|---------|-------------|
+| `archive` | Enables archive mode on the test node |
+
+## Related Crates
+
+- [`dusk-rusk`](../rusk/) — the node instance spun up for tests
+- [`rusk-recovery`](../rusk-recovery/) — provides genesis state deployment
+- [`rusk-prover`](../rusk-prover/) — used with `no_random` + `debug` for deterministic proofs
+- [`wallet-core`](../wallet-core/) — wallet primitives used by the test wallet
+- [`dusk-core`](../core/) — transaction and key types
diff --git a/rusk-wallet/README.md b/rusk-wallet/README.md
@@ -4,6 +4,26 @@
 
 # Dusk Wallet
 
-Library providing functionalities to create wallets compatible with Dusk Network
+Library providing functionalities to create wallets compatible with the Dusk network.
 
 This library is used to implement the official [Dusk CLI wallet](https://github.com/dusk-network/rusk/blob/master/rusk-wallet/src/bin/README.md).
+
+## Overview
+
+Rusk Wallet is both a Rust library and a CLI application for interacting with the Dusk network. It supports multi-account management, Phoenix (shielded) and Moonlight (public) transactions, staking operations, and contract interaction.
+
+## Key Features
+
+| Feature | Description |
+|---------|-------------|
+| Interactive CLI | Terminal UI for wallet operations |
+| Multi-account | Profile and account management |
+| Encrypted storage | AES-GCM encrypted wallet files backed by RocksDB |
+| Node communication | GraphQL client for querying the Rusk node |
+| Dual transaction models | Phoenix (shielded/UTXO) and Moonlight (public/account) support |
+
+## Related Crates
+
+- [`wallet-core`](../wallet-core/) — low-level wallet primitives (key derivation, note handling, transaction construction)
+- [`node-data`](../node-data/) — ledger types for transaction display
+- [`dusk-core`](../core/) — cryptographic signatures and transaction types
diff --git a/rusk/README.md b/rusk/README.md
@@ -5,6 +5,37 @@
 > Entrypoint for the blockchain node
 </div>
 
+## Overview
+
+Rusk is the main binary and orchestration layer for the Dusk blockchain. It wires together the chain node, consensus engine, contract VM, and exposes HTTP/GraphQL APIs for wallets and applications to interact with the network.
+
+## Node Modes
+
+| Mode | Flag | Description |
+|------|------|-------------|
+| Provisioner | *(default)* | Full consensus participation — proposes and validates blocks |
+| Archive | `--features archive` | Historical data indexing via SQLite for explorers and analytics |
+| Prover | `--features prover` | Local ZK proving service for Phoenix transactions |
+
+## Key Modules
+
+| Module | Description |
+|--------|-------------|
+| `http` | GraphQL server for blockchain queries and transaction submission |
+| `node` | Integration point for chain + consensus + networking |
+| `verifier` | Proof verification (PLONK, Groth16) for incoming transactions |
+
+## Related Crates
+
+- [`dusk-vm`](../vm/) — contract execution engine
+- [`dusk-core`](../core/) — transaction and cryptographic types
+- [`node`](../node/) — chain node (networking, storage, mempool)
+- [`dusk-consensus`](../consensus/) — block ordering and finality
+- [`rusk-profile`](../rusk-profile/) — circuit artifact management
+- [`rusk-prover`](../rusk-prover/) — local ZK prover (optional)
+- [`rusk-recovery`](../rusk-recovery/) — state and key bootstrapping
+- [`node-data`](../node-data/) — ledger and message types
+
 ## Configure example's data
 
 When running `prepare-dev` in the root repository, the Genesis state according to your local <a href="https://github.com/dusk-network/rusk/blob/master/examples/genesis.toml" target="_blank">`examples/genesis.toml`</a> will be used. Refer to <a href="https://github.com/dusk-network/rusk/blob/master/rusk-recovery/config/example.toml" target="_blank">`examples.toml`</a> for configuration options you can set, such as stakes and balances on network initialization.