diff --git a/README.md b/README.md index 8b554c1a2f..f5da6d074d 100644 --- 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 index b5da1ca817..ff66a5f25d 100644 --- a/consensus/README.md +++ b/consensus/README.md @@ -1,3 +1,26 @@ -Implementation of Dusk [Succinct Attestation] consensus protocol +
-[Succinct Attestation]: (https://github.com/dusk-network/docs/blob/main/src/content/docs/learn/deep-dive/succinct-attestation.md) \ No newline at end of file +# `๐Ÿ”— 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 +
+ +## 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 index e7421fb9a1..40f69009f0 100644 --- 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 +## 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 new file mode 100644 index 0000000000..7fe99b13c0 --- /dev/null +++ b/node-data/README.md @@ -0,0 +1,40 @@ +
+ +# `๐Ÿ“Š Node Data` + +> Core datatypes for the Dusk blockchain node โ€” ledger structures, network messages, and wire-format encoding +
+ +## 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 index c071c464f3..0f02672931 100644 --- a/node/README.md +++ b/node/README.md @@ -1,6 +1,37 @@ - # Dusk node library +
-The Dusk Node functionality crate. +# `๐ŸŒ Dusk Node` + +> Chain node implementation โ€” networking, mempool, storage, and synchronization +
+ +## 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 new file mode 100644 index 0000000000..fae8e5655a --- /dev/null +++ b/rusk-profile/README.md @@ -0,0 +1,32 @@ +
+ +# `๐Ÿชช Rusk Profile` + +> Manages the local Rusk profile directory for circuit artifacts, proving keys, and genesis state +
+ +## 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 new file mode 100644 index 0000000000..8eb27a12ae --- /dev/null +++ b/rusk-prover/README.md @@ -0,0 +1,35 @@ +
+ +# `๐Ÿ“จ Rusk Prover` + +> Local PLONK zero-knowledge prover for Phoenix (shielded) transactions +
+ +## 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 new file mode 100644 index 0000000000..1b51df9d7b --- /dev/null +++ b/rusk-recovery/README.md @@ -0,0 +1,48 @@ +
+ +# `โฌ‡๏ธ Rusk Recovery` + +> Bootstrap and recovery utilities for initializing a Dusk node +
+ +## 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 new file mode 100644 index 0000000000..efa934ff64 --- /dev/null +++ b/rusk-test/README.md @@ -0,0 +1,35 @@ +
+ +# `๐Ÿงช Rusk Test` + +> Integration test harness and utilities for the Rusk workspace +
+ +## 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 index 43c2bf9ea8..c19bba38cf 100644 --- 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 index ffcf019f20..44008e228e 100644 --- a/rusk/README.md +++ b/rusk/README.md @@ -5,6 +5,37 @@ > Entrypoint for the blockchain node +## 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 `examples/genesis.toml` will be used. Refer to `examples.toml` for configuration options you can set, such as stakes and balances on network initialization.