rbitcoin

Bitcoin full node in Rust aimed at production server-side use: multi-peer IBD, tip follow, block/tx relay (tip mode), optional Core-class JSON-RPC, and in-process Electrum + optional Esplora REST for wallet clients (scripthash index via --shindex, default off; not a graphical block-explorer stack) — built around a libbitcoin-class relational archive and a pure-Rust consensus/script path.

0.x: on-disk format and APIs are unstable until 1.0. Prefer a signet soak before first mainnet cutover; treat early mainnet as high-scrutiny. Security contact and policy: SECURITY.md. Operator notes: docs/experimental-mainnet.md.

License	MIT OR Apache-2.0 (LICENSE-MIT, LICENSE-APACHE)
Version	0.1.0 experimental (CHANGELOG.md)
Platform	Linux first (io_uring + map-free fd store; other OSes unproven)
Security	SECURITY.md
Design	docs/architecture.md — why this node is different

Why this node is different

Most full nodes center a UTXO set + block files (Bitcoin Core). Most Electrum backends are external indexers of another node. rbitcoin does neither: no UTXO set (libbitcoin-class archive), Electrum + txindex in-process.

Operator-order facts (mainnet tip moves; treat as ballpark, not a warranty):

• ~200 GiB hot pin/annotate set after schema 17 (txout + spent + idx + txid + tx.head); ~700 GiB if you keep cold inwit for reconstruct. Optional --shindex is extra. Ballpark, not a warranty — census in SCHEMA.md
• Core-class JSON-RPC subset (default off): docs/rpc.md
• Under ~30 h IBD on a laptop-class host with --milestone 0 (full scripts)
• Modest RAM during sync — no multi‑GiB dbcache, no long “flush the cache” pauses (confirm is lookup → load → scripts → write)
• Segmented tx.head — newer txs resolve hottest (tip-local traffic wins)
• Pure-Rust consensus/scripts on rust-bitcoin (no libbitcoinconsensus)
• Reproducible static musl builds for ordinary Linux hosts

1. On-disk archive — map-free Class A/B/C tables (pread/pwrite + fallocate grow; kernel page cache as L0): split Class A (txout / inwit / spent), keyless tx.head, spend annotations, native scripthash. Historical blocks are reconstructed from the archive; tip serve / reorg uses the in-RAM body queue and peer wire. Confirm/mempool prevouts use the archive (and in-mempool parents), not a separate UTXO hash table. Layout: SCHEMA.md; IO: docs/io-modality.md; concurrency: docs/concurrency.md.
2. Concurrent IBD / IO — fixed writer roles (one Class A appender), allocate-then-publish HWMs (no map epochs), confirm as lookup → load → scripts → write, bulk io_uring where available (pread/pwrite fallback). Linux-shaped IO; porting needs work. Map: docs/concurrency.md.
3. Pure-Rust consensus — structure, connect, and script verification in Rust; only secp256k1 (via rust-bitcoin) as the crypto primitive — no libbitcoinconsensus dual-eval. Tests: docs/consensus-tests.md.

Full narrative and Core / Fulcrum contrasts: docs/architecture.md. Product surface: COMPAT.md.

Status

Core pipelines exist (store, consensus, P2P IBD, tip follow, scripthash, Electrum, Esplora REST, libre mempool) for the server-side / wallet-client backend role. 0.x mainnet is early production: run signet first, then mainnet with monitoring (OPERATOR.md). Finishing any one operator’s first full mainnet sync is not a gate for using or packaging this tree.

Non-goal: powering a graphical block explorer (search boxes, address-prefix autocomplete, explorer-only catalogue APIs). Product surface: COMPAT.md.

Authorship: first-party code is AI-written (Grok / xAI) under Brandon Black (@reardencode) prompting — details in SECURITY.md.

Milestone (default mainnet 840000): at/below --milestone, script/sig checks are skipped on block connect (assumevalid-style speed tradeoff). Prevouts, double-spend, maturity, and fees still run. Use --milestone 0 for full script validation.

# Portable static release (preferred)
nix build .#rbitcoin-musl
install -m 755 result/bin/rbitcoin-node result/bin/rbitcoin-cli target/release/

# Signet lab (time-boxed)
./target/release/rbitcoin-node --datadir ./datadir-signet --network signet \
  --listen 127.0.0.1:38333 --milestone 200000 --max-run-secs 120

Custom Signets are supported with --signetchallenge and --signetblocktime; see the custom Signet example.

Build

Portable static release (recommended)

Pinned nixpkgs + Cargo.lock produce a fully static, portable rbitcoin-node / rbitcoin-cli (musl) that runs on ordinary Linux hosts without Nix or a matching glibc. Byte-identical digests for a given revision + target. Not NixOS-specific — any machine with Nix + flakes:

nix build .#rbitcoin-musl          # default package; fully static
# or: ./scripts/repro-build.sh
install -m 755 result/bin/rbitcoin-node result/bin/rbitcoin-cli target/release/
./scripts/repro-build.sh           # day-to-day musl install (crane-layered)
./scripts/repro-check.sh           # release only: two clean rebuilds; compare digests

Do not use cargo build --release inside nix-shell / nix develop as the operator binary — that links against the Nix store glibc and fails outside the store (No such file or directory at exec). Details: docs/reproducible-builds.md.

Dev / CI path

Requires Rust 1.95 (workspace rust-version, matching Nix/CI). Prefer the same pin as release builds for tests and clippy:

nix develop   # or: nix-shell  (both use flake.lock, not floating <nixpkgs>)
cargo build --workspace
cargo test --workspace
./scripts/coverage.sh   # PR bar (Actions); see CONTRIBUTING.md / AGENTS.md

Agents implement on a worktree branch and let GitHub Actions run the workspace/coverage gates — see AGENTS.md.

Operator binary: always the static install under ./target/release/ (or ./result/bin/). After green master CI, the musl workflow uploads the same pair as an Actions artifact (see OPERATOR.md). Operator knobs: OPERATOR.md. Experimental mainnet: docs/experimental-mainnet.md.

Crate map

Crate	Role
rbitcoin-primitives	Shared types / newtypes
rbitcoin-store	Map-free Class A/B/C tables (fd pread/pwrite), scripthash, bulk IO
rbitcoin-query	Domain API (archive, confirm, reconstruct, Electrum joins)
rbitcoin-consensus	Validation / confirm; pure-Rust scripts; milestone = scripts only
rbitcoin-net	P2P + IBD (modular ibd/), tip follow, relay
rbitcoin-mempool	Cluster graph + libre admission
rbitcoin-electrum	Electrum TCP server
rbitcoin-esplora	Esplora REST + wallet-scoped WS (opt-in)
rbitcoin-log	Leveled stderr logger
rbitcoin-rpc	Documented Core-class JSON-RPC subset (not full Core)
rbitcoin-cli	CLI client
rbitcoin-node	Node binary
rbitcoin-test	High-level test harness

Documentation index

Doc	Audience
docs/architecture.md	Design uniqueness (start here)
docs/heads.md	Which head file (tx / header / scripthash)
docs/experimental-mainnet.md	Lab mainnet runbook
OPERATOR.md	Day-to-day ops, env knobs
SCHEMA.md	On-disk schema
docs/concurrency.md	Writer roles / lock-free publish
COMPAT.md	Intentional differences vs Core / Electrum methods
CONTRIBUTING.md	Dev workflow and coverage bar
docs/quality.md	Living quality roadmap (one Open list + one Completed list)
docs/how-we-plan.md	Red→Green→Refactor planning
SECURITY.md	Vulnerability reporting
CHANGELOG.md	Release notes
docs/reproducible-builds.md	Pinned Nix byte-identical builds

What this is not

• Production multi-tenant Electrum or “drop-in Core”
• Wallet, mining, GUI, or pruning
• Full Core JSON-RPC surface
• A claim of complete mainnet script validation under the default milestone (use --milestone 0 for full scripts)
• A multi-OS port — Linux is the supported IO target today

License

Licensed under either of:

• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions. See CONTRIBUTING.md.