A Bitcoin full-node project for developers exploring typed Rust integration, node-owned indexing, and familiar Bitcoin interfaces.
Run locally. Inspect the contracts. Share one reproducible result.
Getting started · Documentation · Contributing · Benchmarks and limitations
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?
AI is changing how software is built. Work that once required large teams and
long development cycles can now be attempted by much smaller teams with far
faster iteration. Bitcoin is unusually well suited to this model because
implementations can be checked against Bitcoin Core, libbitcoinkernel,
historical chain data, consensus test vectors, fuzzing, and differential tests.
Bitcoin is well suited to AI-native development; Bitcoin Core's development culture is not. Its review process prioritizes minimizing change risk, rewarding incrementalism, entrenching existing boundaries, and making radical architectural experimentation prohibitively expensive.
That is why we built bitcoin-rs: to preserve Bitcoin's consensus while
making bold architectural experimentation practical—build alternatives,
verify them against reproducible evidence, and keep iterating until better
designs emerge.
- Performance is a first-class requirement. bitcoin-rsis 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-rssimplifies that boundary: the node owns the canonical UTXO set used for validation and an integrated script index exposed through Esplora-compatible APIs. This eliminates the need for a separate Electrum server with its own duplicate chain state and ingestion pipeline. Wallet-specific keys, policies, and metadata remain outside the node. Consumers build on node state; they do not redefine where Bitcoin's coin state lives.
- 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. Extensions own their state and lifecycle and may build on core capabilities, but they do not become dependencies of the core.
- 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. This improves runtime efficiency and simplifies integration and deployment, making the full node a native, composable part of the ecosystem.
Bitcoin is not defined by the continued preservation of one codebase. The code
can change; consensus is what must remain. bitcoin-rs aims to challenge
Bitcoin Core and build a better Bitcoin implementation. That challenge
strengthens the Bitcoin ecosystem: a separately designed codebase cross-checks
consensus interpretation, increases implementation diversity, and reduces the
risk of correlated implementation failures.
- Consensus validation: the native Rust interpreter verifies Legacy, SegWit v0,
and Taproot key-path and script-path spends. Core's committed script_tests,tx_valid, andtx_invalidvectors pin zero native mismatches. Script checks run in parallel across rayon workers with sighash midstate reuse per transaction.--features kernelroutes the same checks throughlibbitcoinkernel(Bitcoin Core's C++ engine) as an independent oracle.
- Kernel feature: --features kernelenableslibbitcoinkernel. Thecrates/consensusandcrates/nodelibrary crates still default tokernel; thebin/bitcoin-rsbinary defaults to["fjall", "redb", "zmq"](no kernel) and does not linklibbitcoinkernel. Issue #213 keeps that split until native wins the signed-spend and full-replay gates; see the validation-default contract.
- Pure-Rust storage defaults: LSM-tree storage backed by fjallby default, withredbcompiled in androcksdbavailable through an optional Cargo feature.
- Sharded UTXO cache: a 256-shard in-memory UTXO set (hashbrown::HashTableof compact records behindparking_lot::RwLock) with checkpoint-based crash recovery and effective--dbcache-mbbudget allocation.
- Asynchronous index consumer: txindexreconciles over a monotonic chain snapshot and event hint channel without blocking block validation.
- Integrated ScriptIndex and Esplora APIs: address and scripthash UTXO indexing and confirmed transaction history served directly over HTTP.
- Mempool mutation gateway: centralized mutation tracking publishing ordered
accept and remove events over ZMQ pubsequence.
- Block template assembly: mining candidate generation via getblocktemplate.
- Core-compatible RPC and typed embedding: synchronous HTTP JSON-RPC using Core
method names and wire formats (walletless, no private keys), plus a typed
async Nodeembedding API for in-process Rust integrations.
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-rsUse 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/To route script verification through libbitcoinkernel instead of the native
interpreter, install C++ dependencies (cmake and libboost-dev on
Debian/Ubuntu), then pass --features kernel:
cargo build --release -p bitcoin-rs --features kernel
./target/release/bitcoin-rs --data-dir .bitcoin-rsEnd-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.
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. Under the kernelfeature,libbitcoinkernelis the verifier instead.
- Kernel boundary: crates/consensus/src/kernel.rscontains alllibbitcoinkerneltypes behind#[cfg(feature = "kernel")]. Kernel types never leak into node state or apply logic.
- Storage: crates/storageprovides backend abstraction. The active engine is configured at startup (fjall,redb, orrocksdb).
- Indexing: txindexruns as an independent consumer, advancing its cursor and rollback metadata atomically.
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 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 warningsContributions are welcome. See CONTRIBUTING.md for local verification commands, CI workflows, and crate architecture conventions.
- docs/getting-started.md — Node setup and configuration
- docs/README.md — Documentation index
- docs/contracts/ — Normative architecture and protocol contracts
- CONCEPTS.md — Domain terminology and concepts
Licensed under Apache-2.0.