brk/crates/brk_error/README.md

# 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

```rust
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

```rust
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

```rust
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

```rust
// 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:

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

This allows for clean function signatures throughout BRK:

```rust
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*