Crate bitcoinkernel

Crate bitcoinkernel 

Source
Expand description

§rust-bitcoinkernel

Rust bindings for the libbitcoinkernel library, providing safe and idiomatic access to Bitcoin’s consensus engine and validation logic.

§Overview

This crate enables Rust applications to leverage Bitcoin Core’s consensus implementation. It provides type-safe wrappers around the C API exposed by libbitcoinkernel.

§Key Features

  • Block Processing: Process and validate blocks against consensus rules
  • Script Verification: Validate transaction scripts
  • Chain Queries: Traverse the chain and read block data
  • Event Notifications: Subscribe to block validation, tip updates, and error events
  • Memory Safety: FFI interactions are wrapped in safe Rust abstractions

§Architecture

The crate is organized into several modules:

  • core: Core Bitcoin primitives (blocks, transactions, scripts)
  • state: Chain state management (chainstate, context, chain parameters)
  • notifications: Event callbacks for validation and synchronization events
  • log: Logging integration with Bitcoin Core’s logging system
  • prelude: Commonly used extension traits for ergonomic API access

§Quick Start

§Basic Block Validation

use bitcoinkernel::{
    Block, ContextBuilder, ChainType, ChainstateManager,
    KernelError, ProcessBlockResult
};

// Create a context for mainnet
let context = ContextBuilder::new()
    .chain_type(ChainType::Mainnet)
    .build()?;

// Initialize chainstate manager
let chainman = ChainstateManager::new(&context, "/path/to/data", "path/to/blocks/")?;

// Process a block
let block_data = vec![0u8; 100]; // placeholder
let block = Block::new(&block_data)?;

match chainman.process_block(&block) {
    ProcessBlockResult::NewBlock => println!("Block validated and written to disk"),
    ProcessBlockResult::Duplicate => println!("Block already known (valid)"),
    ProcessBlockResult::Rejected => println!("Block validation failed"),
}

§Script Verification

use bitcoinkernel::{prelude::*, Transaction, verify, VERIFY_ALL};
let spending_tx_bytes = vec![]; // placeholder
let prev_tx_bytes = vec![]; // placeholder
let spending_tx = Transaction::new(&spending_tx_bytes).unwrap();
let prev_tx = Transaction::new(&prev_tx_bytes).unwrap();
let prev_output = prev_tx.output(0).unwrap();

let result = verify(
    &prev_output.script_pubkey(),
    Some(prev_output.value()),
    &spending_tx,
    0,
    Some(VERIFY_ALL),
    &[prev_output],
);

match result {
    Ok(()) => println!("Script verification passed"),
    Err(e) => println!("Script verification failed: {}", e),
}

§Event Notifications

use bitcoinkernel::{
    Block, BlockValidationStateRef, ChainType, ContextBuilder, KernelError,
    ValidationCallbackRegistry,
};

let context = ContextBuilder::new()
    .chain_type(ChainType::Mainnet)
    .notifications(|registry| {
        registry.register_progress(|title, percent, _resume| {
            println!("{}: {}%", title, percent);
        });
        registry.register_warning_set(|warning, message| {
            eprintln!("Warning: {} - {}", warning, message);
        });
        registry.register_flush_error(|message| {
            eprintln!("Flush error: {}", message);
            // Consider tearing down context and terminating operations
        });
        registry.register_fatal_error(|message| {
            eprintln!("FATAL: {}", message);
            // Tear down context and terminate all operations
            std::process::exit(1);
        });
    })
    .validation(|registry| {
        registry.register_block_checked(|block: Block, _state: BlockValidationStateRef<'_>| {
            println!("Checked block: {}", block.hash());
        });
    })
    .build()?;

Note: System-level errors are surfaced through FatalErrorCallback and FlushErrorCallback. When encountering either error type, it is recommended to tear down the Context and terminate any running tasks using the ChainstateManager.

§Chain Traversal

use bitcoinkernel::{ContextBuilder, ChainType, ChainstateManager, KernelError};

// Create a context for mainnet
let context = ContextBuilder::new()
    .chain_type(ChainType::Mainnet)
    .build()?;

// Initialize chainstate manager
let chainman = ChainstateManager::new(&context, "path/to/data", "path/to/blocks")?;

chainman.import_blocks()?;

// Get the active chain
let chain = chainman.active_chain();

// Traverse the chain
for entry in chain.iter() {
    println!("Block hash {} at height {}", entry.block_hash(), entry.height());
}

§Type System

The crate uses owned and borrowed types extensively:

  • Owned types (e.g., Block, Transaction): Manage C memory lifecycle
  • Borrowed types (e.g., BlockRef, TransactionRef): Zero-copy views into data
  • Extension traits: Provide ergonomic methods (use prelude::* to import)

§Error Handling

The crate provides multiple layers of error handling:

  • Operation Errors: Standard KernelError results for validation failures, serialization errors, and internal library errors
  • System Errors: Critical failures are reported through notification callbacks:

When encountering fatal or flush errors through these callbacks, applications should tear down the Context and terminate any operations using the ChainstateManager.

§Minimum Supported Rust Version (MSRV)

This crate requires Rust 1.71.0 or later.

§Examples

See the examples/ directory for complete working examples including:

  • Silent Payment Scanning

Re-exports§

pub use crate::core::verify;
pub use crate::core::verify;
pub use crate::core::Block;
pub use crate::core::BlockHash;
pub use crate::core::BlockSpentOutputs;
pub use crate::core::BlockSpentOutputsRef;
pub use crate::core::BlockTreeEntry;
pub use crate::core::Coin;
pub use crate::core::CoinRef;
pub use crate::core::ScriptPubkey;
pub use crate::core::ScriptPubkeyRef;
pub use crate::core::ScriptVerifyError;
pub use crate::core::Transaction;
pub use crate::core::TransactionRef;
pub use crate::core::TransactionSpentOutputs;
pub use crate::core::TransactionSpentOutputsRef;
pub use crate::core::TxIn;
pub use crate::core::TxInRef;
pub use crate::core::TxOut;
pub use crate::core::TxOutPoint;
pub use crate::core::TxOutPointRef;
pub use crate::core::TxOutRef;
pub use crate::core::Txid;
pub use crate::core::TxidRef;
pub use crate::log::disable_logging;
pub use crate::log::Log;
pub use crate::log::LogCategory;
pub use crate::log::LogLevel;
pub use crate::log::Logger;
pub use crate::notifications::BlockCheckedCallback;
pub use crate::notifications::BlockTipCallback;
pub use crate::notifications::BlockValidationResult;
pub use crate::notifications::BlockValidationStateRef;
pub use crate::notifications::FatalErrorCallback;
pub use crate::notifications::FlushErrorCallback;
pub use crate::notifications::HeaderTipCallback;
pub use crate::notifications::NotificationCallbackRegistry;
pub use crate::notifications::ProgressCallback;
pub use crate::notifications::SynchronizationState;
pub use crate::notifications::ValidationCallbackRegistry;
pub use crate::notifications::ValidationMode;
pub use crate::notifications::Warning;
pub use crate::notifications::WarningSetCallback;
pub use crate::notifications::WarningUnsetCallback;
pub use crate::state::Chain;
pub use crate::state::ChainParams;
pub use crate::state::ChainType;
pub use crate::state::ChainstateManager;
pub use crate::state::ChainstateManagerBuilder;
pub use crate::state::Context;
pub use crate::state::ContextBuilder;
pub use crate::state::ProcessBlockResult;
pub use crate::core::verify_flags::VERIFY_ALL;
pub use crate::core::verify_flags::VERIFY_ALL_PRE_TAPROOT;
pub use crate::core::verify_flags::VERIFY_CHECKLOCKTIMEVERIFY;
pub use crate::core::verify_flags::VERIFY_CHECKSEQUENCEVERIFY;
pub use crate::core::verify_flags::VERIFY_DERSIG;
pub use crate::core::verify_flags::VERIFY_NONE;
pub use crate::core::verify_flags::VERIFY_NULLDUMMY;
pub use crate::core::verify_flags::VERIFY_P2SH;
pub use crate::core::verify_flags::VERIFY_TAPROOT;
pub use crate::core::verify_flags::VERIFY_WITNESS;

Modules§

core
ffi
log
notifications
prelude
state

Enums§

KernelError
A collection of errors emitted by this library