bitcoin-rs

Build on Bitcoin. Inside Rust.

A Bitcoin full-node project for developers exploring typed Rust integration, node-owned indexing, and familiar Bitcoin interfaces.

Getting started · Documentation · Contributing · Benchmarks and limitations

Why bitcoin-rs

Bitcoin Core is the most successful implementation of Bitcoin. Its conservatism, stability, and compatibility discipline are major reasons for that success. Over time, however, those safeguards also shape which changes are practical: existing boundaries accumulate dependencies, and implementation choices harden into assumptions that Bitcoin consensus does not require.

bitcoin-rs asks a simple question:

If a Bitcoin full node were designed again today, what would we keep, and what would we change?

Why now?

Bitcoin is unusually well suited to independent implementation because its behavior can be checked against Bitcoin Core, libbitcoinkernel, historical chain data, consensus test vectors, fuzzing, and differential tests.

Bitcoin Core prioritizes stability, compatibility, and minimizing change risk. Those properties are essential for the reference implementation, but they also make large architectural changes difficult to explore within the same codebase.

That is why we built bitcoin-rs: to preserve Bitcoin's consensus while making architectural experimentation practical—build alternatives, verify them against reproducible evidence, and keep iterating on the implementation.

What can be improved

• Performance is a first-class requirement. bitcoin-rs is not aiming for parity with Bitcoin Core simply by changing languages. Synchronization, storage, memory ownership, concurrency, caching, I/O, and indexing can all be reconsidered. Improvements must be demonstrated with matched whole-node benchmarks against Core.
• The UTXO set is the node's authoritative coin state. Much of the Bitcoin application ecosystem grew by rebuilding or duplicating wallet-, Electrum-, and explorer-specific views around the same chain data. bitcoin-rs simplifies that boundary: the node owns the canonical UTXO set used for validation and an integrated script index exposed through Esplora-compatible APIs. Wallet-specific keys, policies, and metadata remain outside the node.
• Modularity keeps the core isolated and components composable. Clear dependency and failure boundaries keep extensions from destabilizing validation or chainstate while allowing components to be reused independently.
• Rust-native integration is a primary path. Applications and extensions in the Rust Bitcoin ecosystem can attach to the node as typed, in-process components instead of routing through serialized RPC or separate processes.

Bitcoin is not defined by the continued preservation of one codebase. The code can change; consensus is what must remain. bitcoin-rs aims to provide an independently designed implementation that can be compared against Bitcoin Core and other implementations through reproducible evidence.

Quick start

Build and run the kernel-free default binary with the quick-start profile. Consult Getting started for build lanes and prerequisites before choosing features:

cargo build --profile quickstart -p bitcoin-rs
./target/quickstart/bitcoin-rs --data-dir .bitcoin-rs

Use the quickstart profile for initial exploration. For sustained IBD or benchmarking, use cargo build --release -p bitcoin-rs and record the exact profile and feature set with the result. No build-time ratio is claimed here.

This starts a mainnet node storing state in .bitcoin-rs and listening for JSON-RPC on 127.0.0.1:8332.

Verify the node is responding and syncing:

curl -s --user bitcoin-rs:bitcoin-rs \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"1.0","id":"1","method":"getblockchaininfo","params":[]}' \
  http://127.0.0.1:8332/

Kernel oracle build

To route script verification through libbitcoinkernel instead of the native interpreter, install C++ dependencies (cmake and libboost-dev on Debian/Ubuntu), build with --features kernel (compiles kernel support in), and select the engine at runtime with --validation-engine kernel:

cargo build --release -p bitcoin-rs --features kernel
./target/release/bitcoin-rs --data-dir .bitcoin-rs --validation-engine kernel

Benchmark status

End-to-end synchronization evidence is the owner of methodology, measurements, artifact custody, and limitations. It retains historical bounded results from superseded engines, including both faster local replays and slower daemon IBD results. Those figures are not current end-state proof or a general speed comparison with Bitcoin Core.

The owner's end-state cells are marked planned_not_executed. Historical raw JSON was retired by #224; retained digests can identify an external copy, but are not a replacement for the raw evidence. This README makes no current performance-superiority claim. Consult the owner document for the status of each workload before quoting a result.

Architecture

Surfaces:      bin/bitcoin-rs, crates/rpc
Capabilities:  crates/index, crates/mining, crates/mempool
Node services: crates/node, crates/p2p, crates/storage
Core & domain: crates/consensus, crates/script, crates/utxo, crates/chain, crates/primitives

• Validation: script execution runs in parallel across rayon workers, with sighash midstate reuse per transaction. The native interpreter covers every consensus spend class. With the kernel feature, libbitcoinkernel support is compiled in and validation.engine selects the verifier at runtime (native by default, kernel to route script checks through libbitcoinkernel).
• Kernel boundary: crates/consensus/src/kernel.rs contains all libbitcoinkernel types behind #[cfg(feature = "kernel")]. Kernel types never leak into node state or apply logic. The kernel feature is a capability; validation.engine is the selection.
• Storage: crates/storage provides backend abstraction. The active engine is configured at startup (fjall, redb, or rocksdb).
• Indexing: txindex runs as an independent consumer, advancing its cursor and rollback metadata atomically.

Default posture

Setting	Default
Storage backend	fjall
Validation engine	Native Rust interpreter (validation.engine = "native", the code default in every build); libbitcoinkernel when selected at runtime with validation.engine = "kernel" on a --features kernel build. The released Docker image presets validation_engine = "kernel" via its shipped /etc/bitcoin-rs/default.toml, overridable by env, config file, or CLI
Kernel feature	Off by default in every crate; --features kernel compiles in libbitcoinkernel support without selecting it
Database cache	450 MiB (--dbcache-mb, split 80/20 when txindex is enabled)
Multi-peer download	On (10 outbound peers: 8 full-relay, 2 block-relay-only; 256-block window)
Transaction index	Off
Script index	Off
Pruning	Off

Mainnet defaults to skipping historical script verification up to the pinned assume-valid anchor. Pass --assume-valid-height 0 to verify all scripts from genesis.

Build and test

# Build default binary (kernel-free)
cargo build --release -p bitcoin-rs

# Run workspace unit and integration tests
cargo test --workspace

# Lint all targets
cargo clippy --workspace --all-targets -- -D warnings

External compatibility

Compatibility claims are tied to external evidence, not only to in-tree implementation status. The ecosystem compatibility contract states the strategy — Core-compatible protocol/API boundaries, independent internals, black-box evidence from real ecosystem consumers — and the evidence matrix records per surface what has actually been exercised by an external consumer. A surface is called externally verified only when a real external consumer has run against it; everything else is reported honestly as implemented or weaker.

Today the one real external-consumer lane is live interoperability with an unmodified Bitcoin Core peer (Core differential contract): black-box handshake, sync, relay, and chain identity. JSON-RPC, REST, ZMQ, GBT/mining, and the Core-compatible USDT probes are implemented and covered by in-tree tests, but not yet externally verified; the matrix names the evidence and the planned representative consumers.

Contributing

Contributions are welcome. See CONTRIBUTING.md for local verification commands, CI workflows, and crate architecture conventions.

Documentation

• docs/getting-started.md — Node setup and configuration
• docs/README.md — Documentation index
• docs/contracts/ — Normative architecture and protocol contracts
• docs/contracts/ecosystem-compatibility.md — External ecosystem compatibility strategy
• docs/api/ecosystem-compat.toml — External compatibility evidence matrix
• CONCEPTS.md — Domain terminology and concepts

License

Licensed under Apache-2.0.