Skip to main content

agentic_bitcoin/
lib.rs

1//! # agentic-bitcoin
2//!
3//! A from-scratch reimplementation of the Bitcoin protocol in Rust, built using
4//! hexagonal (ports-and-adapters) architecture.
5//!
6//! > **WARNING: EXPERIMENTAL SOFTWARE — NOT FOR PRODUCTION USE**
7//! >
8//! > This project is an educational and research implementation. It has not been audited,
9//! > fuzzed at scale, or battle-tested against adversarial inputs. Do not use this software
10//! > to operate a Bitcoin node, manage real funds, or for any purpose involving real money.
11//!
12//! ## Overview
13//!
14//! agentic-bitcoin is a clean-room Rust implementation of Bitcoin's core subsystems —
15//! consensus rules, script interpreter, transaction signing, wallet operations, P2P networking,
16//! and block validation — structured as a modular workspace of five crates. The domain logic
17//! contains zero infrastructure dependencies, making it straightforward to test, reason about,
18//! and extend.
19//!
20//! ## Architecture
21//!
22//! The project follows hexagonal (ports-and-adapters) architecture, organized as five crates
23//! from innermost (pure logic) to outermost (wiring and I/O):
24//!
25//! ```text
26//! ┌─────────────────────────────────────────────────────┐
27//! │              abtc-infrastructure                     │
28//! │            (Node wiring, composition)                │
29//! ├──────────────────────┬──────────────────────────────┤
30//! │   abtc-application   │       abtc-adapters           │
31//! │  (Services, use      │  (In-memory implementations   │
32//! │   cases, handlers)   │   of port traits)             │
33//! ├──────────────────────┴──────────────────────────────┤
34//! │                   abtc-ports                          │
35//! │           (Trait interfaces only)                     │
36//! ├─────────────────────────────────────────────────────┤
37//! │                   abtc-domain                         │
38//! │  (Pure domain logic: primitives, consensus, script,  │
39//! │   crypto, wallet — zero infrastructure deps)         │
40//! └─────────────────────────────────────────────────────┘
41//! ```
42//!
43//! ## Workspace Crates
44//!
45//! ### [`abtc_domain`] — Domain Layer (innermost)
46//!
47//! Pure domain logic with zero infrastructure dependencies. Contains:
48//!
49//! - **Primitives**: [`Block`](abtc_domain::Block), [`Transaction`](abtc_domain::Transaction),
50//!   [`Amount`](abtc_domain::Amount), [`BlockHeader`](abtc_domain::BlockHeader), and all core types
51//! - **Consensus**: validation rules, network parameters, block connection/disconnection, signet support
52//! - **Script**: full interpreter with all opcodes including SegWit v0/v1, Taproot (BIP341/342),
53//!   and Miniscript support
54//! - **Crypto**: SHA-256, RIPEMD-160, secp256k1, Schnorr/BIP340, tagged hashes, sighash computation
55//! - **Wallet**: HD keys (BIP32/44), PSBT (BIP174), coin selection, transaction builder,
56//!   bech32/bech32m address encoding
57//! - **Filters**: BIP158 Golomb-coded set (GCS) compact block filters
58//! - **Covenants**: OP_VAULT (BIP345) experimental support
59//!
60//! ### [`abtc_ports`] — Ports Layer
61//!
62//! Trait definitions (interfaces) that sit between the domain and adapters. Defines
63//! contracts for storage, mempool, wallet, mining, network, and RPC — with no concrete
64//! implementations.
65//!
66//! ### [`abtc_adapters`] — Adapter Layer
67//!
68//! Concrete implementations of the port traits:
69//!
70//! - [`InMemoryBlockStore`](abtc_adapters::InMemoryBlockStore) /
71//!   [`InMemoryChainStateStore`](abtc_adapters::InMemoryChainStateStore) — hash-map-backed storage
72//! - [`InMemoryMempool`](abtc_adapters::InMemoryMempool) — full mempool with ancestor/descendant
73//!   tracking, RBF (BIP125), and CPFP
74//! - [`InMemoryWallet`](abtc_adapters::InMemoryWallet) /
75//!   [`PersistentWallet`](abtc_adapters::PersistentWallet) — wallet implementations
76//! - [`TcpPeerManager`](abtc_adapters::TcpPeerManager) — real TCP P2P networking
77//! - [`JsonRpcServer`](abtc_adapters::JsonRpcServer) — JSON-RPC server
78//! - [`SimpleMiner`](abtc_adapters::SimpleMiner) — block template creation and mining
79//!
80//! ### [`abtc_application`] — Application Layer
81//!
82//! Services and use cases that orchestrate domain logic through the ports:
83//!
84//! - **Chain state**: block connection/disconnection with automatic reorg handling
85//! - **Mempool acceptance**: transaction validation against consensus rules and policy
86//! - **P2P sync**: version handshake, block download scheduling, header-first sync,
87//!   compact blocks (BIP152)
88//! - **Mining**: block template assembly with fee-maximizing transaction selection
89//! - **Fee estimation**: sliding-window median fee rate tracking
90//! - **RPC handlers**: JSON-RPC dispatch for `getblock`, `getrawtransaction`,
91//!   `estimatesmartfee`, `sendrawtransaction`, and more
92//! - **Peer scoring**: misbehavior tracking with automatic banning
93//! - **Package relay**: BIP331 transaction package support
94//!
95//! ### [`abtc_infrastructure`] — Infrastructure Layer (outermost)
96//!
97//! Composition root that wires all crates together into a running Bitcoin node.
98//! Handles CLI argument parsing, dependency injection, background task management,
99//! and graceful shutdown via SIGINT/SIGTERM.
100//!
101//! ## What's Implemented
102//!
103//! - Full script interpreter with all standard opcodes, SegWit v0 (P2WPKH, P2WSH),
104//!   and SegWit v1 (P2TR key-path and script-path)
105//! - Taproot (BIP341/BIP342) — TapTree construction, script-path sighash,
106//!   OP_CHECKSIGADD, control blocks
107//! - Schnorr signatures (BIP340) — sign, verify, key tweaking, x-only pubkeys
108//! - HD wallets (BIP32/BIP44) — master key derivation, hardened/normal child keys,
109//!   xprv/xpub serialization
110//! - PSBT (BIP174) — create, sign, combine, finalize, extract
111//! - Coin selection — largest-first, smallest-first, closest-match strategies
112//! - Address encoding — P2PKH, P2SH, P2WPKH (bech32), P2TR (bech32m)
113//! - Block validation — full UTXO-set-based connection/disconnection
114//! - P2P networking — version handshake, peer discovery, block/transaction relay
115//! - Compact blocks (BIP152) — SipHash short txids, mempool reconstruction
116//! - Mempool — ancestor/descendant tracking, RBF (BIP125), CPFP, eviction
117//! - Fee estimation — sliding window of block median fee rates
118//! - Peer scoring — misbehavior tracking with cumulative scoring and auto-banning
119//! - Chain events — publish/subscribe notification bus
120//! - JSON-RPC handler framework
121//!
122//! ## Quick Start
123//!
124//! ```bash,ignore
125//! # Build the project
126//! cargo build --workspace
127//!
128//! # Run all tests
129//! cargo test --workspace
130//!
131//! # Start a regtest node
132//! cargo run -- --network regtest
133//!
134//! # Generate API documentation
135//! cargo doc --no-deps --workspace --open
136//! ```
137//!
138//! ## License
139//!
140//! MIT — see the LICENSE-MIT file for details.