Crate blvm_consensus

Expand description

§Consensus-Proof

Direct mathematical implementation of Bitcoin consensus rules from the Orange Paper.

This crate provides pure, side-effect-free functions that implement the mathematical specifications defined in the Orange Paper. It serves as the mathematical foundation for Bitcoin consensus validation.

§Architecture

The system follows a layered architecture:

Orange Paper (mathematical specifications)
Consensus Proof (this crate - direct implementation)
Reference Node (minimal Bitcoin implementation)
Developer SDK (developer-friendly interface)

§Design Principles

Pure Functions: All functions are deterministic and side-effect-free
Mathematical Accuracy: Direct implementation of Orange Paper specifications
Exact Version Pinning: All consensus-critical dependencies pinned to exact versions
No Consensus Rule Interpretation: Only mathematical implementation

§Usage

use blvm_consensus::transaction::check_transaction;
use blvm_consensus::types::*;

let transaction = Transaction {
    version: 1,
    inputs: vec![].into(),
    outputs: vec![TransactionOutput {
        value: 1000,
        script_pubkey: vec![0x51],
    }]
    .into(),
    lock_time: 0,
};
let result = check_transaction(&transaction).unwrap();

Re-exports§

pub use config::reset_assume_valid_height;
pub use config::set_assume_valid_height;
pub use script::batch_verify_signatures;
pub use script::clear_all_caches;
pub use script::clear_hash_cache;
pub use script::clear_script_cache;
pub use script::clear_stack_pool;
pub use script::disable_caching;
pub use script::reset_benchmarking_state;
pub use transaction_hash::clear_sighash_templates;

Modules§

activation: Unified fork activation: table and trait for “is fork X active at height H?”.
bip113: BIP113: Median Time-Past
bip119: BIP119: OP_CHECKTEMPLATEVERIFY (CTV)
bip348: BIP348: OP_CHECKSIGFROMSTACK (CSFS)
bip_validation: BIP Validation Rules
block: Block validation functions from Orange Paper Section 5.3 Section 5.3
checkqueue: Script verification queue: dedicated N-1 worker threads plus master as Nth.
config: Configuration for blvm-consensus
constants: Bitcoin consensus constants from Orange Paper
crypto: Cryptographic hash functions with CPU feature detection and optimizations
economic: Economic model functions from Orange Paper Section 7 Section 6
error: Error types for consensus validation
locktime: Shared locktime validation logic for BIP65 (CLTV) and BIP112 (CSV)
mempool: Mempool validation functions from Orange Paper Section 9
mining: Mining and block creation functions from Orange Paper Section 10.1
opcodes: Bitcoin Script Opcode Constants
optimizations: BLVM Runtime Optimization Passes
orange_paper_constants: Orange Paper Section 4 symbols (C, H, M_MAX, etc.) — re-export from primitives constants.
pow: Proof of Work functions from Orange Paper Section 8 Section 7
profile_log: Non-blocking profile logging for IBD and consensus hot paths.
reorganization: Chain reorganization functions from Orange Paper Section 10.3
script: Script execution engine from Orange Paper Section 5.2
script_profile: Script sub-timing for IBD profiling (sighash, interpreter, multisig, P2PKH fast path). Used by block.rs to extend [PERF] with breakdown when profile feature is enabled.
secp256k1_backend: Secp256k1 backend abstraction.
segwit: Segregated Witness (SegWit) functions from Orange Paper Section 11.1
sequence_locks: Sequence lock calculation functions (BIP68)
serialization: Bitcoin wire format serialization/deserialization
sigop: Signature operation counting functions
smallvec: Small vectors in various sizes. These store a certain number of elements inline, and fall back to the heap for larger allocations. This can be a useful optimization for improving cache locality and reducing allocator traffic for workloads that fit within the inline buffer.
taproot: Taproot functions from Orange Paper Section 11.2
test_utils: Property test strategies and shared test fixtures.
transaction: Transaction validation functions from Orange Paper Section 5.1
transaction_hash: Transaction hash calculation for signature verification
types: Essential Bitcoin types for consensus validation
utxo_overlay: Zero-Copy UTXO Overlay
version_bits: BIP9-style version bits activation.
witness: Unified witness validation framework for SegWit (BIP141) and Taproot (BIP340/341/342)

Macros§

hot_inline: Inlining hints for hot functions
profile_log: Log a profile message without blocking. Drops the message if the channel is full.
tx_inputs: Helper macro to create Transaction inputs/outputs that works with both Vec and SmallVec
tx_outputs

Structs§

Bip54BoundaryTimestamps: BIP54 timewarp: timestamps of boundary blocks for period-boundary checks.
Block: Block: ℬ = ℋ × 𝒯𝒳*
BlockContext: Block validation context
BlockHash: Block hash: newtype wrapper for type safety
BlockHeader: Block Header: ℋ = ℤ × ℍ × ℍ × ℕ × ℕ × ℕ
BlockHeight: Block height: newtype wrapper for type safety
ConsensusProof: Consensus Proof - wrapper struct for consensus validation functions
OutPoint: OutPoint: 𝒪 = ℍ × ℕ
ScriptContext: Script execution context
SharedByteString: Shareable script_pubkey for UTXO: small scripts use inline storage; longer use Arc<[u8]>. Clone is cheap (inline copies up to 64 bytes, shared is Arc::clone). Serde matches ByteString.
TimeContext: Time context for consensus validation
Transaction: Transaction: 𝒯𝒳 = ℕ × ℐ* × 𝒯* × ℕ
TransactionInput: Transaction Input: ℐ = 𝒪 × 𝕊 × ℕ
TransactionOutput: Transaction Output: 𝒯 = ℤ × 𝕊
UTXO: UTXO: 𝒰 = ℤ × 𝕊 × ℕ

Enums§

ConsensusError
ForkId: Stable identifier for each consensus-affecting fork (BIP or soft-fork bundle).
Network: Network type for consensus validation
ValidationResult: Validation result

Constants§

BIP16_P2SH_ACTIVATION_MAINNET: BIP16: P2SH (Pay-to-Script-Hash) - Mainnet activation height
BIP16_P2SH_ACTIVATION_REGTEST: BIP16: P2SH (Pay-to-Script-Hash) - Regtest activation height
BIP16_P2SH_ACTIVATION_TESTNET: BIP16: P2SH (Pay-to-Script-Hash) - Testnet activation height
BIP30_DEACTIVATION_MAINNET: BIP30: Duplicate Coinbase Prevention - Mainnet deactivation height
BIP30_DEACTIVATION_REGTEST: BIP30: Duplicate Coinbase Prevention - Regtest deactivation height
BIP30_DEACTIVATION_TESTNET: BIP30: Duplicate Coinbase Prevention - Testnet deactivation height
BIP34_ACTIVATION_MAINNET: BIP34: Block Height in Coinbase - Mainnet activation height
BIP34_ACTIVATION_REGTEST: BIP34: Block Height in Coinbase - Regtest activation height
BIP34_ACTIVATION_TESTNET: BIP34: Block Height in Coinbase - Testnet activation height
BIP54_ACTIVATION_MAINNET: BIP54: Consensus Cleanup - Mainnet activation height
BIP54_ACTIVATION_REGTEST: BIP54: Consensus Cleanup - Regtest activation height
BIP54_ACTIVATION_TESTNET: BIP54: Consensus Cleanup - Testnet activation height
BIP54_MAX_SIGOPS_PER_TX: BIP54: Maximum sigop count per transaction (Consensus Cleanup). Transactions with total sigop count > this are invalid after BIP54 activation.
BIP65_ACTIVATION_MAINNET: BIP65: OP_CHECKLOCKTIMEVERIFY (CLTV) - Mainnet activation height
BIP65_ACTIVATION_TESTNET: BIP65: OP_CHECKLOCKTIMEVERIFY (CLTV) - Testnet activation height
BIP66_ACTIVATION_MAINNET: BIP66: Strict DER Signatures - Mainnet activation height
BIP66_ACTIVATION_REGTEST: BIP66: Strict DER Signatures - Regtest activation height
BIP66_ACTIVATION_TESTNET: BIP66: Strict DER Signatures - Testnet activation height
BIP112_CSV_ACTIVATION_MAINNET: BIP112/BIP113: CHECKSEQUENCEVERIFY (CSV) - Mainnet activation height
BIP112_CSV_ACTIVATION_REGTEST: BIP112/BIP113: CSV - Regtest (active from genesis for typical regtest chains)
BIP112_CSV_ACTIVATION_TESTNET: BIP112/BIP113: CSV - Testnet activation height (Bitcoin Core testnet3)
BIP147_ACTIVATION_MAINNET: BIP147: NULLDUMMY Enforcement - Mainnet activation height
BIP147_ACTIVATION_TESTNET: BIP147: NULLDUMMY Enforcement - Testnet activation height
C: satoshis per BTC (Orange Paper C)
COINBASE_MATURITY: Coinbase maturity requirement: 100 blocks
CSFS_ACTIVATION_MAINNET: CSFS (BIP348) - Mainnet activation height
CSFS_ACTIVATION_REGTEST: CSFS (BIP348) - Regtest activation height
CSFS_ACTIVATION_TESTNET: CSFS (BIP348) - Testnet activation height
CTV_ACTIVATION_MAINNET: CTV (BIP119) - Mainnet activation height
CTV_ACTIVATION_REGTEST: CTV (BIP119) - Regtest activation height
CTV_ACTIVATION_TESTNET: CTV (BIP119) - Testnet activation height
DIFFICULTY_ADJUSTMENT_INTERVAL: Difficulty adjustment interval: 2016 blocks
GENESIS_BLOCK_HASH: Genesis block hash (mainnet)
GENESIS_BLOCK_HASH_INTERNAL: Genesis block hash in internal / wire byte order.
GENESIS_BLOCK_MERKLE_ROOT: Genesis block merkle root
GENESIS_BLOCK_NONCE: Genesis block nonce
GENESIS_BLOCK_TIMESTAMP: Genesis block timestamp (Unix timestamp)
H: halving interval (Orange Paper H)
HALVING_INTERVAL: Halving interval: 210,000 blocks
INITIAL_SUBSIDY: Initial block subsidy: 50 BTC
LOCKTIME_THRESHOLD: Lock time threshold: transactions with lock time < this are block height
L_ELEMENT: maximum element size (Orange Paper L_ELEMENT)
L_OPS: maximum operations per script (Orange Paper L_OPS)
L_SCRIPT: maximum script length (Orange Paper L_SCRIPT)
L_STACK: maximum stack size (Orange Paper L_STACK)
MAX_BLOCK_SERIALIZED_SIZE: Maximum block serialized size in bytes (network rule) This is the maximum size of a block when serialized without witness data
MAX_BLOCK_SIGOPS_COST: Maximum block sigop cost (network rule)
MAX_BLOCK_SIZEDeprecated: Maximum block size (deprecated - use MAX_BLOCK_WEIGHT for SegWit blocks) Kept for backward compatibility
MAX_BLOCK_WEIGHT: Maximum block weight in weight units (network rule, BIP141) Weight = (stripped_size × 4) + witness_size This is the primary limit for SegWit blocks
MAX_FUTURE_BLOCK_TIME: Maximum future block time tolerance: 2 hours (7200 seconds)
MAX_INPUTS: Maximum number of inputs per transaction
MAX_MONEY: Maximum money supply: 21,000,000 BTC in satoshis
MAX_OUTPUTS: Maximum number of outputs per transaction
MAX_SCRIPT_ELEMENT_SIZE: Maximum script element size (BIP141: witness elements can be up to 520 bytes)
MAX_SCRIPT_OPS: Maximum number of operations in script
MAX_SCRIPT_SIZE: Maximum script length
MAX_STACK_SIZE: Maximum stack size during script execution
MAX_TARGET: Maximum target (minimum difficulty)
MAX_TRANSACTIONS_PER_BLOCK: Upper bound on the number of transactions in any consensus-valid block.
MAX_TX_SIZE: Maximum transaction size: 1MB
MIN_RELAY_FEE: Minimum relay fee for RBF replacement (BIP125)
MIN_TARGET: Minimum target (maximum difficulty) - Bitcoin’s genesis target
M_MAX: maximum money supply (Orange Paper M_MAX)
R: coinbase maturity (Orange Paper R)
SATOSHIS_PER_BTC: Satoshis per BTC
SEGWIT_ACTIVATION_MAINNET: SegWit (BIP141) - Mainnet activation height
SEGWIT_ACTIVATION_TESTNET: SegWit (BIP141) - Testnet activation height (Bitcoin Core testnet3 consensus.SegwitHeight)
SEGWIT_P2WPKH_LENGTH: SegWit witness program lengths (BIP141)
SEGWIT_P2WSH_LENGTH
SEQUENCE_FINAL: Sequence number for final transaction
SEQUENCE_RBF: Sequence number for RBF
S_MAX: maximum sigops per block (Orange Paper S_MAX)
TAPROOT_ACTIVATION_MAINNET: Taproot (BIP341) - Mainnet activation height
TAPROOT_ACTIVATION_TESTNET: Taproot (BIP341) - Testnet activation height (Bitcoin Core testnet3)
TAPROOT_PROGRAM_LENGTH: Taproot program hash length (BIP341)
TAPROOT_SCRIPT_LENGTH: Taproot script length (BIP341)
TARGET_TIME_PER_BLOCK: Target time per block: 10 minutes
WITNESS_COMMITMENT_HASH_LENGTH: Witness commitment hash length (BIP141)
WITNESS_COMMITMENT_SCRIPT_LENGTH: Witness commitment script length (BIP141)
W_MAX: maximum block weight (Orange Paper W_MAX)

Functions§

utxo_set_insert: Insert owned UTXO into UtxoSet (wraps in Arc). Convenience for tests and one-off inserts.
utxo_set_with_capacity: Pre-allocate a UtxoSet for n entries. Avoids costly reallocation spikes when loading large checkpoints (at 50M entries the HashMap table alone is ~2.5 GB; a growth-triggered realloc temporarily doubles that).

Type Aliases§

ByteString: Byte string type
Hash: Hash type: 256-bit hash
Integer: Integer type
Natural: Natural number type
UtxoSet: UTXO Set: 𝒰𝒮 = 𝒪 → 𝒰
Witness: Witness data: stack of witness elements (SegWit/Taproot)

Crate blvm_consensus

Crate blvm_consensus Copy item path

§Consensus-Proof

§Architecture

§Design Principles

§Usage

Re-exports§

Modules§

Macros§

Structs§

Enums§

Constants§

Functions§

Type Aliases§

Crate blvm_consensus