How kaspanet/rusty-kaspa works
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: services.rs Consensus engine · src/service.rs RPC service · src/service.rs gRPC and wRPC servers · processor.rs Body validation
Components 23
Node runtime
Native daemon composition and shared lifecycle.
- kaspad daemon · Assembles and supervises native node services.
kaspad/src/daemon.rs - Service runtime · Shared task, service, and signal lifecycle.
core/src/task/runtime.rs - Consensus wiring · Constructs consensus and its service layer.
consensus/src/consensus/factory.rs
Ledger and mining
Consensus state transition, storage, and block production.
- Consensus engine · Authoritative DAG, UTXO, PoW, and pruning rules.
consensus/src/consensus/services.rs - Header validation
consensus/src/pipeline/header_processor/processor.rs - Body validation
consensus/src/pipeline/body_processor/processor.rs - Virtual-state update · Updates selected chain, UTXO state, and pruning.
consensus/src/pipeline/virtual_processor/processor.rs - GHOSTDAG and reachability
consensus/src/processes/ghostdag/protocol.rs - Script execution · Executes signatures and covenants.
crypto/txscript/src/engine_context.rs - Consensus stores
consensus/src/consensus/storage.rs - Database backend
database/src/db.rs - Mempool and mining · Admits transactions and builds block templates.
mining/src/manager.rs - Derived indexes · 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 · Manages peers, routing, and handshake.
protocol/p2p/src/core/hub.rs - Sync and relay flows · Performs IBD plus block and transaction relay.
protocol/flows/src/ibd/flow.rs - RPC service · Exposes node, consensus, index, and mining operations.
rpc/service/src/service.rs - gRPC and wRPC servers · Serves gRPC and WebSocket-framed JSON/Borsh RPC.
rpc/grpc/server/src/service.rs - Notifications · Decouples state-change producers from subscribers.
notify/src/notifier.rs
Clients and tools
User-facing and integration runtimes.
- Wallet SDK · Maintains local account state and syncs UTXOs over RPC.
wallet/core/src/wallet/mod.rs - CLI and wallet terminal · Dispatches node RPC and wallet commands.
cli/src/main.rs - Stratum bridge · Connects miners to a Kaspa RPC client.
bridge/src/main.rs - WASM SDKs · Exports Node.js and browser-compatible APIs.
wasm/src/lib.rs - DAG simulator · Runs in-process network simulations.
simpa/src/main.rs
Connections 27
- 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