Bitcoin Module Architecture Update

[AIR-3][AIS-3][BPC-3][AIT-3][RES-3]

This document describes the architectural changes made to the Bitcoin module in version 3.1.2, particularly focusing on the hexagonal architecture implementation and improved BIP implementations.

Overview of Changes

The Bitcoin module has been restructured to follow a clean hexagonal architecture pattern with:

  1. Interface Layer Restructuring: Converted a single interface file to a proper directory structure with dedicated interfaces
  2. BIP Implementation Modules: Added proper implementations of BIP-341 (Taproot) and BIP-342 (Tapscript)
  3. Protocol Modules: Enhanced protocol validation and execution modules
  4. SPV Security Improvements: Added constant-time operations for secure verification
  5. Error Handling: Enhanced error type handling and propagation

Hexagonal Architecture Implementation

The implementation follows the hexagonal (ports and adapters) architecture pattern, providing clean separation between:

  • Core Domain Logic: Business logic in the center
  • Ports/Interfaces: Clean API definitions that the core exposes
  • Adapters: Implementations that connect to external systems

Interface Layer Changes

The interface layer has been restructured as follows:

src/bitcoin/interface/
├── mod.rs             # Module registry and primary interface definitions
├── block.rs           # Block-related interfaces
├── transaction.rs     # Transaction-related interfaces
└── network.rs         # Network-related interfaces

This provides clear separation of concerns with each interface handling a specific aspect of the Bitcoin protocol:

  • Block Interfaces: Handle block structure, headers, and related information
  • Transaction Interfaces: Handle transaction structure, validation, and related information
  • Network Interfaces: Handle network status, connections, and related operations

Protocol Implementation

The protocol module has been enhanced with proper validation, script execution, and address utilities:

src/bitcoin/protocol/
├── mod.rs             # Protocol module registry and primary definitions
├── validation.rs      # Protocol and transaction validation
├── script.rs          # Script execution and verification
└── address.rs         # Address generation and validation

BIP Implementation Modules

A new dedicated BIP implementation module has been created in the core directory:

core/src/bip/
├── mod.rs             # BIP registry and common utilities
├── bip341.rs          # BIP-341 (Taproot) implementation
└── bip342.rs          # BIP-342 (Tapscript) implementation

BIP Registry

The BIP registry provides a central place to track implementation status of various BIPs:

  • Complete: Fully implemented and tested
  • Partial: Partially implemented
  • Planned: Implementation planned but not started
  • NotSupported: Not supported

Currently implemented BIPs:

  • BIP-341 (Taproot)
  • BIP-342 (Tapscript)
  • BIP-174 (PSBT)
  • BIP-370 (PSBT v2)

BIP-341 (Taproot) Implementation

The Taproot implementation provides full support for:

  • Key path spending
  • Script path spending
  • Merkle tree construction
  • Taproot output creation and verification

BIP-342 (Tapscript) Implementation

The Tapscript implementation provides full support for:

  • Tapscript execution
  • Control block verification
  • Leaf validation

SPV Security Improvements

The SPV (Simplified Payment Verification) module has been enhanced with:

  • Constant-time Operations: Added secure, constant-time operations for verification to prevent timing attacks
  • Improved Error Handling: Enhanced error types and propagation
  • Transaction Inclusion Verification: Added comprehensive proof verification

Error Handling

The error handling has been improved with:

  • Comprehensive Error Types: Added specialized error types for each aspect of Bitcoin operations
  • Error Conversion Implementations: Added conversion implementations from various libraries
  • Context-Specific Error Creation: Added helper methods for creating context-specific errors

Validation Tools

A new BIP validation tool has been created to verify the implementation:

src/bin/verify_bip_modules.rs

This tool verifies:

  • Presence of required BIP implementation files
  • Registry entry correctness
  • AI labeling compliance
  • Module structure correctness

Benefits of these Changes

  1. Improved Maintainability: Clean separation of concerns makes the code easier to maintain
  2. Enhanced Testability: Interfaces can be mocked for testing
  3. Better Security: Consistent error handling and constant-time operations
  4. Simplified Extension: New BIPs can be added in a consistent way
  5. Clearer Documentation: Better structure makes the codebase easier to understand

Compatibility

These changes are backward compatible with existing code that used the previous module structure. The main interface module (src/bitcoin/mod.rs) re-exports all the types and functions that were previously available directly.

Next Steps

  1. Complete Implementation: Add implementations for additional BIPs
  2. Enhanced Testing: Add comprehensive tests for all BIP implementations
  3. Documentation: Add detailed documentation for each module
  4. Security Auditing: Conduct security audit of the implementation

Last updated: May 1, 2025