brk_error

Centralized error handling for the Bitcoin Research Kit

brk_error provides a unified error type and result system used throughout the BRK ecosystem. It consolidates error handling from multiple external dependencies and adds Bitcoin-specific error variants.

What it provides

• Unified Error Type: Single Error enum that covers all error cases across BRK crates
• Convenient Result Type: Pre-configured Result<T, E = Error> for consistent error handling
• External Error Integration: Automatic conversions from common library errors
• Bitcoin-Specific Errors: Domain-specific error variants for blockchain data processing

Key Features

Centralized Error Management

• Single error type for the entire BRK ecosystem
• Consistent error handling patterns across all crates
• Reduced error type complexity in public APIs

External Library Integration

Automatic From implementations for errors from:

• I/O Operations: std::io::Error
• Bitcoin Core RPC: bitcoincore_rpc::Error
• Database Operations: fjall::Error, vecdb::Error
• Serialization: serde_json::Error
• Time Operations: jiff::Error, SystemTimeError
• HTTP Requests: minreq::Error
• Zero-Copy Operations: zerocopy conversion errors

Bitcoin-Specific Error Variants

• WrongAddressType - Invalid address type for operation
• UnindexableDate - Date before Bitcoin genesis (2009-01-03)
• WrongLength - Invalid data length for Bitcoin structures
• QuickCacheError - Cache operation failures

Usage

Basic Error Handling

use brk_error::{Error, Result};

fn process_block() -> Result<Block> {
    let rpc_client = get_rpc_client()?;  // bitcoincore_rpc::Error -> Error
    let block_data = rpc_client.get_block_info(&hash)?;
    
    // Custom Bitcoin-specific validation
    if block_data.height < 0 {
        return Err(Error::Str("Invalid block height"));
    }
    
    Ok(block_data)
}

Working with External Libraries

use brk_error::Result;

fn save_data(data: &[u8]) -> Result<()> {
    // I/O error automatically converted
    std::fs::write("data.bin", data)?;
    
    // JSON serialization error automatically converted  
    let json = serde_json::to_string(&data)?;
    
    // Database error automatically converted
    database.insert("key", &json)?;
    
    Ok(())
}

Bitcoin-Specific Validation

use brk_error::{Error, Result};

fn validate_date(date: &Date) -> Result<()> {
    if *date < Date::new(2009, 1, 3) {
        return Err(Error::UnindexableDate);
    }
    Ok(())
}

fn validate_address_type(output_type: OutputType) -> Result<()> {
    if !output_type.is_address() {
        return Err(Error::WrongAddressType);
    }
    Ok(())
}

String Errors

// Static string errors (zero allocation)
Err(Error::Str("Invalid configuration"))

// Dynamic string errors
Err(Error::String(format!("Block {} not found", height)))

Result Type

The crate provides a convenient Result type alias:

pub type Result<T, E = Error> = std::result::Result<T, E>;

This allows for clean function signatures throughout BRK:

fn parse_block() -> Result<Block> { /* ... */ }
fn index_transactions() -> Result<Vec<Transaction>> { /* ... */ }

Error Display

All errors implement Display and std::error::Error, providing:

• Formatted error messages for debugging
• Error chain support for nested errors
• Integration with error handling libraries like anyhow

Dependencies

• vecdb - Vector database error types
• bitcoincore-rpc - Bitcoin Core RPC client errors
• fjall - Key-value store errors
• jiff - Date/time operation errors
• minreq - HTTP request errors
• serde_json - JSON serialization errors
• zerocopy - Zero-copy conversion errors

This README was generated by Claude Code