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

brk_error 0.0.105