Bitcoin Commons: Consensus Implementation

Orange Paper–aligned Bitcoin consensus in Rust: deterministic validation, #[spec_locked] checks with blvm-spec-lock, and broad coverage (unit, integration, property, fuzz).

Crate: blvm-consensus · docs.rs

Documentation: docs.thebitcoincommons.org · Sources: blvm-docs.
Ecosystem status: SYSTEM_STATUS.md (BTCDecoded org).

Architecture Position

Tier 2 of the 6-tier Bitcoin Commons architecture (BLVM technology stack):

1. blvm-spec (Orange Paper - mathematical foundation)
2. blvm-consensus (pure math implementation)
3. blvm-protocol (Bitcoin abstraction)
4. blvm-node (full node implementation)
5. blvm-sdk (developer toolkit)
6. blvm-commons (governance enforcement)

Core Functions

Implements all major Bitcoin consensus functions from the Orange Paper:

Transaction Validation

• Transaction structure and limit validation
• Input validation against UTXO set
• Script execution and verification

Block Validation

• Block connection and validation
• Transaction application to UTXO set
• Proof of work verification

Economic Model

• Block reward calculation
• Total supply computation
• Difficulty adjustment

Mempool Protocol

• Transaction mempool validation
• Standard transaction checks
• Transaction replacement (RBF) logic

Mining Protocol

• Block creation from mempool
• Block mining and nonce finding
• Block template generation

Chain Management

• Chain reorganization handling
• P2P network message processing

Advanced Features

• SegWit: Witness data validation and weight calculation
• Taproot: P2TR output validation and key aggregation

Design Principles

1. Pure Functions: All functions are deterministic and side-effect-free
2. Mathematical Accuracy: Direct implementation of Orange Paper specifications
3. Exact Version Pinning: All consensus-critical dependencies pinned to exact versions
4. Comprehensive Testing: Extensive test coverage with integration tests
5. No Consensus Rule Interpretation: Only mathematical implementation
6. Formal Verification: blvm-spec-lock formal verification and property-based testing ensure correctness

See docs/VERIFICATION.md for detailed verification documentation.

Formal Verification

Implements mathematical verification of Bitcoin consensus rules using:

• blvm-spec-lock: Formal verification linking code to Orange Paper specifications
• Property-Based Testing: Randomized testing with proptest to discover edge cases
• Mathematical Specifications: Formal documentation of consensus invariants
• CI Enforcement: Automated verification blocks merge if proofs fail

Verification Commands

# Run all tests and verification
cargo test --all-features

# Example: property-heavy integration targets (see tests/*.rs)
cargo test --test consensus_property_tests
cargo test --test orange_paper_property_tests

Verification Status

Chain Selection: should_reorganize, calculate_chain_work verified
Block Subsidy: get_block_subsidy halving schedule verified
Proof of Work: check_proof_of_work, target expansion verified
Transaction Validation: check_transaction structure rules verified
Block Connection: connect_block UTXO consistency verified

BIP Implementation Status

All critical Bitcoin Improvement Proposals (BIPs) are implemented and integrated:

• BIP30 - Duplicate coinbase prevention (integrated in connect_block())
• BIP34 - Block height in coinbase (integrated in connect_block())
• BIP66 - Strict DER signatures (enforced via script verification with flag 0x04)
• BIP90 - Block version enforcement (integrated in connect_block())
• BIP147 - NULLDUMMY enforcement (enforced via script verification with flag 0x10)

Integration:

• All BIPs integrated into block validation
• BIP66 and BIP147 enforced during script verification (called for all transactions in connect_block())
• Integration tests verify enforcement
• Spec-lock verification for critical BIPs

BIP66 and BIP147 are enforced during script verification, which is called for all transactions in connect_block(). This is the correct approach as these BIPs apply to individual signatures and script execution.

Dependencies

Monorepo vs crates.io: In the BTCDecoded layout, this crate’s Cargo.toml uses path dependencies for sibling blvm-* crates. When you depend on a published release from crates.io, use:

[dependencies]
blvm-consensus = "0.1"

(0.1 matches any **0.1.**z on crates.io; use = + a full version if you need a locked patch for reproducibility.)

Dependency constraints follow the canonical Cargo.toml: many blvm-* crates use pre-1.0 ranges on crates.io; third-party crates use = pins only where the manifest does. Do not treat this README as a second copy of the lockfile—open the manifest (and lockfile if your checkout has one) for the exact graph.

Requirements: satisfy rust-version in Cargo.toml (currently 1.83+).

Performance Optimizations

Profile-Guided Optimization (PGO)

For maximum performance, use Profile-Guided Optimization:

# Automated PGO build (recommended)
./scripts/pgo-build.sh

# Clean and rebuild with PGO
./scripts/pgo-build.sh clean

Expected gain: 1.10-1.15x performance improvement

PGO works by:

1. Building with instrumentation to collect execution profiles
2. Running benchmarks to generate profile data
3. Rebuilding with profile data to optimize hot paths

Production Build

For production builds with all optimizations:

cargo build --release --features production

This enables:

• LTO (Link-Time Optimization)
• Runtime optimizations (caching, context reuse)
• SIMD vectorization
• Memory layout optimizations

Testing

Property-based tests (proptest), differential comparisons where configured, and fuzz targets under fuzz/ (see fuzz/README.md). CI runs cargo test --all-features and a nightly Miri job on selected targets — see docs/MIRI.md for scope and limitations.

# Run all tests and verification
cargo test --all-features

# Run with coverage
cargo tarpaulin --out Html --output-dir coverage

# Run integration tests
cargo test --test integration_tests
cargo test --test integration_opportunities

# Run formal verification (blvm-spec-lock)
cargo spec-lock verify --crate-path .

Spec linkage

Annotated functions carry #[spec_locked] and name an Orange Paper section. CI runs Z3 on those annotations. Three functions are mutation-validated: check_transaction, is_strict_der, and merkle_tree_from_hashes. The other anchors are not formally verified by that gate. Witnesses in spec_witnesses.rs are not the production functions. The inner connect path has no #[spec_locked] attribute. Counts, skip flags, and the command list are in docs/VERIFICATION.md.

Chain of trust:

Orange Paper (spec) → #[spec_locked] on the functions that carry it → implementation

Verification approaches (details and scope: docs/VERIFICATION.md):

• Spec-lock on #[spec_locked] functions against the Orange Paper
• Property tests, integration tests, and optional Bolero-backed tests
• Runtime assertions on selected paths (see feature flags and PROOF_LIMITATIONS.md)
• Coverage-guided fuzzing (Fuzzing (BLVM docs); harnesses under fuzz/)

Orange Paper sections

The top-level sections in PROTOCOL.md are:

• 5: State Transition Functions
• 6: Economic Model
• 7: Proof of Work
• 8: Security Properties
• 9: Mempool Protocol
• 10: Network Protocol
• 11: Advanced Features
• 12: Mining Protocol

An annotated function names one of those sections. That name is not a proof that the section is fully implemented. The mutation gate is in docs/VERIFICATION.md.

Security

Checks on this crate:

• Spec-lock: Z3 on #[spec_locked] functions. A passing verify job is not the mutation gate in docs/VERIFICATION.md.
• Property testing: randomized tests under tests/, including consensus_property_tests.
• CI: the verify job runs unless the commit message contains [skip ci] or [skip_verify], or a workflow dispatch sets skip_tests. OpenTimestamps is not a step in .github/workflows/ci.yml.

See SECURITY.md for security policies and BTCDecoded Security Policy for organization-wide guidelines.

Contributing

See CONTRIBUTING.md and the BTCDecoded Contribution Guide.

Note: Consensus changes are expected to pass the tests and the verify job. A commit message can skip that job. See docs/VERIFICATION.md.

License

MIT License - see LICENSE file for details.