# kaspanet/rusty-kaspa architecture

> Architecture diagram of the GitHub repository kaspanet/rusty-kaspa, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kaspanet/rusty-kaspa
- Repository: https://github.com/kaspanet/rusty-kaspa

## Overview

#### 1. Purpose and workspace shape
Rusty Kaspa is the Rust full-node implementation for the Kaspa network, plus reusable blockchain, wallet, RPC, mining, simulation, and WebAssembly libraries. The Cargo workspace is organized around a native node (`kaspad`), domain crates for consensus/networking/storage, and client-facing SDKs.

#### 2. Primary executables and deployment targets
- **Full node:** `kaspad/src/main.rs` starts the native daemon; `kaspad/src/daemon.rs` assembles runtime services and `kaspad/src/args.rs` owns node arguments.
- **CLI/wallet terminal:** `cli/src/main.rs` dispatches node RPC and wallet commands through `cli/src/modules/mod.rs`.
- **Mining bridge:** `bridge/src/main.rs` exposes a Stratum bridge backed by a Kaspa RPC client and optional dashboard assets.
- **Simulation:** `simpa/src/main.rs` runs in-process DAG/network simulations via `simpa/src/simulator/network.rs`.
- **WASM SDK:** `wasm/src/lib.rs`, `wallet/wasm/src/lib.rs`, and `rpc/wrpc/wasm/src/lib.rs` export browser/Node.js-compatible bindings.

Docker images exist for the node, wallet, simulator, bridge, and other tools under `docker/`.

#### 3. Node composition and lifecycle
The daemon is the principal control boundary: it parses network/storage/RPC/mining settings, initializes services, and supervises them through shared runtime utilities.
- Node startup and platform-specific daemon behavior: `kaspad/src/daemon.rs`, `daemon/src/kaspad/native.rs`.
- Shared task/service/signal runtime: `core/src/task/runtime.rs`, `core/src/service.rs`, `core/src/signals.rs`.
- Node-facing consensus construction and service wiring: `consensus/src/consensus/factory.rs`, `consensus/src/consensus/services.rs`.

#### 4. Consensus and block-processing pipeline
Consensus is the authoritative state transition layer. It models the Kaspa DAG, validates blocks and transactions, updates the virtual selected chain/UTXO state, and enforces PoW, difficulty, pruning, and GHOSTDAG rules.
- Core domain types, network parameters, transaction and UTXO structures: `consensus/core/src/lib.rs`, `consensus/core/src/tx.rs`, `consensus/core/src/config/params.rs`.
- Ordered ingestion pipeline: header validation → body validation → virtual-state update/pruning in `consensus/src/pipeline/header_processor/processor.rs`, `consensus/src/pipeline/body_processor/processor.rs`, `consensus/src/pipeline/virtual_processor/processor.rs`.
- DAG ordering and reachability algorithms: `consensus/src/processes/ghostdag/protocol.rs`, `consensus/src/processes/reachability/mod.rs`.
- Script and signature execution are isolated in `crypto/txscript/src/engine_context.rs` and `crypto/txscript/src/covenants.rs`.

#### 5. Persistent state, indexes, and mining
Consensus state is persisted through a database abstraction backed by RocksDB-oriented configuration. Storage boundaries separate consensus stores from optional derived indexes.
- Database access and RocksDB presets: `database/src/db.rs`, `database/src/db/rocksdb_preset.rs`.
- Consensus storage registry and stores: `consensus/src/consensus/storage.rs`, `consensus/src/model/stores/mod.rs`.
- Optional address/UTXO indexing consumes virtual-chain changes: `indexes/processor/src/processor.rs`, `indexes/utxoindex/src/index.rs`.
- Mempool admission, replacement, and block-template production: `mining/src/mempool/validate_and_insert_transaction.rs`, `mining/src/manager.rs`, `mining/src/block_template/builder.rs`.

Flow: network/RPC transactions enter the mempool; mining selects valid transactions into templates; submitted blocks traverse consensus and trigger index/notification updates.

#### 6. P2P synchronization and public RPC
P2P transports exchange protocol messages and feed blocks/transactions into consensus flows. RPC is a separate adapter layer over node/consensus/index/mining services.
- Peer lifecycle, routing, and handshake: `protocol/p2p/src/core/hub.rs`, `protocol/p2p/src/core/router.rs`, `protocol/p2p/src/handshake.rs`.
- Initial block download, block relay, transaction relay, and pruning sync: `protocol/flows/src/ibd/flow.rs`, `protocol/flows/src/v7/blockrelay/flow.rs`, `protocol/flows/src/v7/txrelay/flow.rs`.
- RPC contract and conversion boundary: `rpc/core/src/api/mod.rs`, `rpc/service/src/service.rs`.
- Transport servers: gRPC in `rpc/grpc/server/src/service.rs`; WebSocket-framed wRPC in `rpc/wrpc/server/src/server.rs`. wRPC supports JSON and Borsh encodings.

#### 7. Clients, notifications, and observability
Notification subsystems decouple state changes from subscribers, RPC clients, indexes, wallets, and bridge consumers.
- General event subscription machinery: `notify/src/notifier.rs`, `notify/src/subscription/mod.rs`.
- RPC notification adaptation: `rpc/core/src/notify/mod.rs`, `rpc/grpc/server/src/collector.rs`.
- Wallets maintain account/key/storage state and synchronize UTXOs over RPC: `wallet/core/src/wallet/mod.rs`, `wallet/core/src/utxo/processor.rs`, `wallet/core/src/storage/local/storage.rs`.
- Metrics/performance monitoring live in `metrics/perf_monitor/src/lib.rs`; the bridge additionally exposes Prometheus support in `bridge/src/prom.rs`.

Main entry points: [`consensus/src/consensus/services.rs`](https://github.com/kaspanet/rusty-kaspa/blob/master/consensus/src/consensus/services.rs) (Consensus engine), [`rpc/service/src/service.rs`](https://github.com/kaspanet/rusty-kaspa/blob/master/rpc/service/src/service.rs) (RPC service), [`rpc/grpc/server/src/service.rs`](https://github.com/kaspanet/rusty-kaspa/blob/master/rpc/grpc/server/src/service.rs) (gRPC and wRPC servers), [`consensus/src/pipeline/body_processor/processor.rs`](https://github.com/kaspanet/rusty-kaspa/blob/master/consensus/src/pipeline/body_processor/processor.rs) (Body validation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_node["Node runtime"]
  node_kaspad["kaspad daemon<br/>executable<br/>[daemon.rs]"]
  node_runtime["Service runtime<br/>[runtime.rs]"]
  node_consensus_factory["Consensus wiring<br/>service factory<br/>[factory.rs]"]
end

subgraph group_ledger["Ledger and mining"]
  node_consensus{{"Consensus engine<br/>state transition<br/>[services.rs]"}}
  node_header_pipeline["Header validation<br/>pipeline stage<br/>[processor.rs]"]
  node_body_pipeline["Body validation<br/>pipeline stage<br/>[processor.rs]"]
  node_virtual_pipeline["Virtual-state update<br/>pipeline stage<br/>[processor.rs]"]
  node_dag_algorithms["GHOSTDAG and reachability<br/>consensus algorithms<br/>[protocol.rs]"]
  node_txscript["Script execution<br/>transaction validation<br/>[engine_context.rs]"]
  node_consensus_store[("Consensus stores<br/>storage registry<br/>[storage.rs]")]
  node_database[("Database backend<br/>RocksDB access<br/>[db.rs]")]
  node_mempool_mining["Mempool and mining<br/>block production<br/>[manager.rs]"]
  node_indexes["Derived indexes<br/>index processor<br/>[processor.rs]"]
end

subgraph group_network["Network and RPC"]
  node_p2p["P2P transport<br/>peer network<br/>[hub.rs]"]
  node_sync_relay["Sync and relay flows<br/>protocol flows<br/>[flow.rs]"]
  node_rpc_service["RPC service<br/>service adapter<br/>[service.rs]"]
  node_rpc_transports["gRPC and wRPC servers<br/>RPC transports<br/>[service.rs]"]
  node_notifications["Notifications<br/>event subscriptions<br/>[notifier.rs]"]
end

subgraph group_clients["Clients and tools"]
  node_wallet["Wallet SDK<br/>wallet client<br/>[mod.rs]"]
  node_cli["CLI and wallet terminal<br/>executable<br/>[main.rs]"]
  node_bridge["Stratum bridge<br/>executable<br/>[main.rs]"]
  node_wasm_sdk["WASM SDKs<br/>browser bindings<br/>[lib.rs]"]
  node_simulator["DAG simulator<br/>executable<br/>[main.rs]"]
end

node_kaspad -->|"supervises"| node_runtime
node_kaspad -->|"initializes"| node_consensus_factory
node_consensus_factory -->|"constructs"| node_consensus
node_consensus -->|"ingests blocks"| node_header_pipeline
node_header_pipeline -->|"valid headers"| node_body_pipeline
node_body_pipeline -->|"valid bodies"| node_virtual_pipeline
node_virtual_pipeline -->|"orders DAG"| node_dag_algorithms
node_body_pipeline -->|"validates scripts"| node_txscript
node_consensus -->|"persists state"| node_consensus_store
node_consensus_store -->|"uses"| node_database
node_virtual_pipeline -->|"chain changes"| node_indexes
node_mempool_mining -->|"submits mined blocks"| node_consensus
node_p2p -->|"hosts flows"| node_sync_relay
node_sync_relay -->|"relays blocks"| node_consensus
node_sync_relay -->|"relays transactions"| node_mempool_mining
node_rpc_service -->|"queries and submits"| node_consensus
node_rpc_service -->|"transaction and template API"| node_mempool_mining
node_rpc_service -->|"index queries"| node_indexes
node_rpc_transports -->|"serves"| node_rpc_service
node_consensus -->|"state events"| node_notifications
node_notifications -->|"subscription events"| node_rpc_service
node_wallet -->|"syncs over RPC"| node_rpc_transports
node_cli -->|"node commands"| node_rpc_transports
node_cli -->|"wallet commands"| node_wallet
node_bridge -->|"Kaspa RPC client"| node_rpc_transports
node_wasm_sdk -->|"client bindings"| node_rpc_transports
node_simulator -->|"simulates DAG processing"| node_consensus

click node_kaspad "https://github.com/kaspanet/rusty-kaspa/blob/master/kaspad/src/daemon.rs"
click node_runtime "https://github.com/kaspanet/rusty-kaspa/blob/master/core/src/task/runtime.rs"
click node_consensus_factory "https://github.com/kaspanet/rusty-kaspa/blob/master/consensus/src/consensus/factory.rs"
click node_consensus "https://github.com/kaspanet/rusty-kaspa/blob/master/consensus/src/consensus/services.rs"
click node_header_pipeline "https://github.com/kaspanet/rusty-kaspa/blob/master/consensus/src/pipeline/header_processor/processor.rs"
click node_body_pipeline "https://github.com/kaspanet/rusty-kaspa/blob/master/consensus/src/pipeline/body_processor/processor.rs"
click node_virtual_pipeline "https://github.com/kaspanet/rusty-kaspa/blob/master/consensus/src/pipeline/virtual_processor/processor.rs"
click node_dag_algorithms "https://github.com/kaspanet/rusty-kaspa/blob/master/consensus/src/processes/ghostdag/protocol.rs"
click node_txscript "https://github.com/kaspanet/rusty-kaspa/blob/master/crypto/txscript/src/engine_context.rs"
click node_consensus_store "https://github.com/kaspanet/rusty-kaspa/blob/master/consensus/src/consensus/storage.rs"
click node_database "https://github.com/kaspanet/rusty-kaspa/blob/master/database/src/db.rs"
click node_mempool_mining "https://github.com/kaspanet/rusty-kaspa/blob/master/mining/src/manager.rs"
click node_indexes "https://github.com/kaspanet/rusty-kaspa/blob/master/indexes/processor/src/processor.rs"
click node_p2p "https://github.com/kaspanet/rusty-kaspa/blob/master/protocol/p2p/src/core/hub.rs"
click node_sync_relay "https://github.com/kaspanet/rusty-kaspa/blob/master/protocol/flows/src/ibd/flow.rs"
click node_rpc_service "https://github.com/kaspanet/rusty-kaspa/blob/master/rpc/service/src/service.rs"
click node_rpc_transports "https://github.com/kaspanet/rusty-kaspa/blob/master/rpc/grpc/server/src/service.rs"
click node_notifications "https://github.com/kaspanet/rusty-kaspa/blob/master/notify/src/notifier.rs"
click node_wallet "https://github.com/kaspanet/rusty-kaspa/blob/master/wallet/core/src/wallet/mod.rs"
click node_cli "https://github.com/kaspanet/rusty-kaspa/blob/master/cli/src/main.rs"
click node_bridge "https://github.com/kaspanet/rusty-kaspa/blob/master/bridge/src/main.rs"
click node_wasm_sdk "https://github.com/kaspanet/rusty-kaspa/blob/master/wasm/src/lib.rs"
click node_simulator "https://github.com/kaspanet/rusty-kaspa/blob/master/simpa/src/main.rs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_kaspad,node_runtime,node_consensus_factory toneBlue
class node_consensus,node_header_pipeline,node_body_pipeline,node_virtual_pipeline,node_dag_algorithms,node_txscript,node_consensus_store,node_database,node_mempool_mining,node_indexes toneAmber
class node_p2p,node_sync_relay,node_rpc_service,node_rpc_transports,node_notifications toneMint
class node_wallet,node_cli,node_bridge,node_wasm_sdk,node_simulator toneRose
```

## Components

### Node runtime

Native daemon composition and shared lifecycle.

- [kaspad daemon](https://github.com/kaspanet/rusty-kaspa/blob/master/kaspad/src/daemon.rs): executable · Assembles and supervises native node services. · `kaspad/src/daemon.rs`
- [Service runtime](https://github.com/kaspanet/rusty-kaspa/blob/master/core/src/task/runtime.rs): runtime · Shared task, service, and signal lifecycle. · `core/src/task/runtime.rs`
- [Consensus wiring](https://github.com/kaspanet/rusty-kaspa/blob/master/consensus/src/consensus/factory.rs): service factory · Constructs consensus and its service layer. · `consensus/src/consensus/factory.rs`

### Ledger and mining

Consensus state transition, storage, and block production.

- [Consensus engine](https://github.com/kaspanet/rusty-kaspa/blob/master/consensus/src/consensus/services.rs): state transition · Authoritative DAG, UTXO, PoW, and pruning rules. · `consensus/src/consensus/services.rs`
- [Header validation](https://github.com/kaspanet/rusty-kaspa/blob/master/consensus/src/pipeline/header_processor/processor.rs): pipeline stage · `consensus/src/pipeline/header_processor/processor.rs`
- [Body validation](https://github.com/kaspanet/rusty-kaspa/blob/master/consensus/src/pipeline/body_processor/processor.rs): pipeline stage · `consensus/src/pipeline/body_processor/processor.rs`
- [Virtual-state update](https://github.com/kaspanet/rusty-kaspa/blob/master/consensus/src/pipeline/virtual_processor/processor.rs): pipeline stage · Updates selected chain, UTXO state, and pruning. · `consensus/src/pipeline/virtual_processor/processor.rs`
- [GHOSTDAG and reachability](https://github.com/kaspanet/rusty-kaspa/blob/master/consensus/src/processes/ghostdag/protocol.rs): consensus algorithms · `consensus/src/processes/ghostdag/protocol.rs`
- [Script execution](https://github.com/kaspanet/rusty-kaspa/blob/master/crypto/txscript/src/engine_context.rs): transaction validation · Executes signatures and covenants. · `crypto/txscript/src/engine_context.rs`
- [Consensus stores](https://github.com/kaspanet/rusty-kaspa/blob/master/consensus/src/consensus/storage.rs): storage registry · `consensus/src/consensus/storage.rs`
- [Database backend](https://github.com/kaspanet/rusty-kaspa/blob/master/database/src/db.rs): RocksDB access · `database/src/db.rs`
- [Mempool and mining](https://github.com/kaspanet/rusty-kaspa/blob/master/mining/src/manager.rs): block production · Admits transactions and builds block templates. · `mining/src/manager.rs`
- [Derived indexes](https://github.com/kaspanet/rusty-kaspa/blob/master/indexes/processor/src/processor.rs): index processor · Consumes virtual-chain changes for address and UTXO queries. · `indexes/processor/src/processor.rs`

### Network and RPC

Peer synchronization and public service adapters.

- [P2P transport](https://github.com/kaspanet/rusty-kaspa/blob/master/protocol/p2p/src/core/hub.rs): peer network · Manages peers, routing, and handshake. · `protocol/p2p/src/core/hub.rs`
- [Sync and relay flows](https://github.com/kaspanet/rusty-kaspa/blob/master/protocol/flows/src/ibd/flow.rs): protocol flows · Performs IBD plus block and transaction relay. · `protocol/flows/src/ibd/flow.rs`
- [RPC service](https://github.com/kaspanet/rusty-kaspa/blob/master/rpc/service/src/service.rs): service adapter · Exposes node, consensus, index, and mining operations. · `rpc/service/src/service.rs`
- [gRPC and wRPC servers](https://github.com/kaspanet/rusty-kaspa/blob/master/rpc/grpc/server/src/service.rs): RPC transports · Serves gRPC and WebSocket-framed JSON/Borsh RPC. · `rpc/grpc/server/src/service.rs`
- [Notifications](https://github.com/kaspanet/rusty-kaspa/blob/master/notify/src/notifier.rs): event subscriptions · Decouples state-change producers from subscribers. · `notify/src/notifier.rs`

### Clients and tools

User-facing and integration runtimes.

- [Wallet SDK](https://github.com/kaspanet/rusty-kaspa/blob/master/wallet/core/src/wallet/mod.rs): wallet client · Maintains local account state and syncs UTXOs over RPC. · `wallet/core/src/wallet/mod.rs`
- [CLI and wallet terminal](https://github.com/kaspanet/rusty-kaspa/blob/master/cli/src/main.rs): executable · Dispatches node RPC and wallet commands. · `cli/src/main.rs`
- [Stratum bridge](https://github.com/kaspanet/rusty-kaspa/blob/master/bridge/src/main.rs): executable · Connects miners to a Kaspa RPC client. · `bridge/src/main.rs`
- [WASM SDKs](https://github.com/kaspanet/rusty-kaspa/blob/master/wasm/src/lib.rs): browser bindings · Exports Node.js and browser-compatible APIs. · `wasm/src/lib.rs`
- [DAG simulator](https://github.com/kaspanet/rusty-kaspa/blob/master/simpa/src/main.rs): executable · Runs in-process network simulations. · `simpa/src/main.rs`

## Connections

- kaspad daemon → Service runtime: supervises
- kaspad daemon → Consensus wiring: initializes
- Consensus wiring → Consensus engine: constructs
- Consensus engine → Header validation: ingests blocks
- Header validation → Body validation: valid headers
- Body validation → Virtual-state update: valid bodies
- Virtual-state update → GHOSTDAG and reachability: orders DAG
- Body validation → Script execution: validates scripts
- Consensus engine → Consensus stores: persists state
- Consensus stores → Database backend: uses
- Virtual-state update → Derived indexes: chain changes
- Mempool and mining → Consensus engine: submits mined blocks
- P2P transport → Sync and relay flows: hosts flows
- Sync and relay flows → Consensus engine: relays blocks
- Sync and relay flows → Mempool and mining: relays transactions
- RPC service → Consensus engine: queries and submits
- RPC service → Mempool and mining: transaction and template API
- RPC service → Derived indexes: index queries
- gRPC and wRPC servers → RPC service: serves
- Consensus engine → Notifications: state events
- Notifications → RPC service: subscription events
- Wallet SDK → gRPC and wRPC servers: syncs over RPC
- CLI and wallet terminal → gRPC and wRPC servers: node commands
- CLI and wallet terminal → Wallet SDK: wallet commands
- Stratum bridge → gRPC and wRPC servers: Kaspa RPC client
- WASM SDKs → gRPC and wRPC servers: client bindings
- DAG simulator → Consensus engine: simulates DAG processing
