kaccy-bitcoin

Comprehensive Bitcoin integration for Kaccy Protocol.

Overview

This crate provides a complete Bitcoin integration solution including Bitcoin Core RPC client, HD wallet management, transaction monitoring, Lightning Network support, Layer 2 integrations, privacy features, and advanced Bitcoin functionalities.

Core Modules

client

Bitcoin Core RPC client with automatic reconnection:

• BitcoinClient - Connection to Bitcoin Core node with exponential backoff retry
• Network info and blockchain queries (get_network_info, get_block_height)
• Transaction broadcasting and mempool operations
• Fee estimation (estimate_smart_fee)
• Address validation and monitoring
• Health checking and node status

hd_wallet

HD wallet and address generation (BIP32/BIP84):

• HdWallet - BIP84 native SegWit hierarchical deterministic wallet
• Unique deposit address generation per order
• Derivation path: m/84'/0'/0'/0/{order_index}
• External and internal chain support
• Address caching to avoid regeneration
• XPUB validation and address book management

monitor

Payment monitoring and confirmation tracking:

• PaymentMonitor - Watches for incoming transactions via polling
• ConfirmationTracker - Multi-level confirmation tracking (1, 3, 6 confirmations)
• TransactionMatcher - Match incoming transactions to orders by address
• Payment status tracking (Pending, Seen, Confirming, Confirmed, Failed)
• Underpayment/overpayment detection and notifications
• RBF (Replace-By-Fee) transaction handling

lightning

Lightning Network integration:

• LndClient - REST client for LND integration
• LightningProvider - Trait abstraction for multiple implementations
• LightningPaymentManager - Invoice creation and payment monitoring
• Channel management (open, close, list, balance monitoring)
• Invoice generation with customizable expiry
• Real-time payment status updates

Advanced Features

Transaction Management

psbt

PSBT (Partially Signed Bitcoin Transactions):

• PsbtBuilder - Generate unsigned transactions
• PsbtManager - Withdrawal and payout management
• Hardware wallet support via external signing
• PSBT combining and finalization
• Batch withdrawal support
• Dynamic fee estimation (fast/medium/slow)

multisig

Multi-signature wallet support:

• MultisigWallet - M-of-N multi-signature configurations
• CustodyManager - Tiered custody based on balance thresholds
• P2WSH native SegWit multisig addresses
• PSBT-based transaction signing
• SignatureCoordinator - Collect signatures from multiple parties
• Platform + User + Cold storage arrangements

taproot

Taproot integration (BIP 341/342):

• TaprootManager - Key pair generation and management
• Key-path spending for enhanced privacy
• Script-path spending with Taproot script tree
• P2TR address creation and validation
• Enhanced efficiency over legacy formats

descriptor

Output descriptor wallet support:

• DescriptorWallet - Modern Bitcoin Core descriptor integration
• Multiple descriptor types (PKH, WPKH, SH-WPKH, TR, Multi, SortedMulti)
• Descriptor import and range derivation
• Checksum validation
• WPKH, Taproot, and Multisig descriptor creation

Privacy Features

payjoin

PayJoin support (BIP 78):

• PayJoinCoordinator - Sender and receiver coordination
• PSBT enhancement with receiver inputs
• PayJoin URI builder (BIP 21 extension)
• Proposal validation and response handling
• Enhanced transaction privacy

coinjoin

CoinJoin integration:

• CoinJoinCoordinator - Multi-participant session management
• Equal denomination outputs for maximum privacy
• Input/output collection and shuffling
• Signature coordination across participants
• Client participation interface

Layer 2 Integrations

stacks

Stacks (STX) integration:

• StacksClient - Mainnet/testnet support
• Smart contract deployment (Clarity contracts)
• ContractDeploymentManager - Contract lifecycle management
• StacksTokenBridge - BTC <-> STX token bridging
• Bridge transaction monitoring
• Address validation and network checks

rsk

RSK integration:

• RskClient - Mainnet/testnet/regtest support
• PegManager - BTC-pegged token (rBTC) management
• Peg-in operations (BTC -> rBTC)
• Peg-out operations (rBTC -> BTC)
• Confirmation tracking for peg operations
• Ethereum-compatible address handling
• Smart contract deployment support

Advanced Bitcoin Features

timelock

Time-locked transactions and HTLCs:

• HtlcManager - Hash Time-Locked Contracts
• Multiple timelock types (BlockHeight, Timestamp, RelativeBlocks, RelativeTime)
• HTLC script builder with IF/ELSE paths
• Payment hash generation and verification
• HTLC status tracking (Pending, Active, Claimed, Refunded, Expired)
• OP_CLTV and OP_CSV support

atomic_swap

Atomic swap protocol:

• AtomicSwapManager - Trustless cross-chain exchange
• Initiator and Participant role support
• Swap status tracking (Initiated, Locked, Completed, Refunded, Cancelled)
• Preimage generation and management
• Configurable timelock periods
• Full swap lifecycle management

Monitoring & Security

mempool

Mempool and reorganization monitoring:

• MempoolMonitor - Track unconfirmed transactions
• AddressWatcher - Detect incoming unconfirmed payments
• ReorgTracker - Chain reorganization detection
• Immediate pending status notification
• Mempool statistics and analysis

activity_monitor

Suspicious activity detection:

• ActivityMonitor - Large transaction detection
• Rapid transaction succession monitoring
• Velocity limits (amount per hour)
• Risk scoring system (0-100)
• Alert broadcasting for suspicious patterns

tx_limits

Transaction limit enforcement:

• LimitEnforcer - Per-user and platform-wide limits
• Multiple limit periods (hourly, daily, weekly, monthly)
• Single transaction maximum
• Usage tracking and enforcement
• Limit violation notifications

notifications

Admin notification system:

• AdminNotificationService - Broadcast channel for alerts
• NotificationPriority - Levels (Low/Medium/High/Critical)
• Underpayment/overpayment notifications
• RBF replacement alerts
• Large transaction alerts

Scaling & Optimization

batch_optimizer

Batched withdrawal optimization:

• BatchOptimizer - Aggregate multiple user withdrawals
• Multiple strategies (MinimizeTransactions, MinimizeFees, Balanced, Priority)
• Efficiency analysis and fee savings calculation
• Reduced on-chain fees through batching

utxo

UTXO management and optimization:

• UtxoManager - UTXO listing and filtering
• Consolidation during low-fee periods
• Optimal input selection strategies (LargestFirst, SmallestFirst, BranchAndBound, FirstFit)
• Transaction fee estimation
• Consolidation recommendations

Utilities

tx_parser

Transaction parsing and analysis:

• TransactionParser - Parse incoming transactions
• ParsedTransaction - Full transaction details
• Sender address extraction for refunds
• Confidence levels for sender identification
• Transaction issue analysis

rbf

Replace-By-Fee tracking:

• RbfTracker - Monitor transaction replacements
• RBF event notifications
• Transaction conflict detection
• Status tracking for replaced transactions

transaction_manager

Integrated transaction management:

• TransactionManager - Combines limits, UTXO, and activity monitoring
• Transaction statistics and analytics
• User and platform usage tracking
• Consolidation recommendations
• Alert subscriptions

error

Comprehensive Bitcoin-specific error types with detailed error handling.

Usage Examples

Basic Payment Monitoring

use kaccy_bitcoin::{BitcoinClient, HdWallet, PaymentMonitor, MonitorConfig};
use std::sync::Arc;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Connect to Bitcoin Core with automatic reconnection
    let client = Arc::new(BitcoinClient::new(
        "http://localhost:8332",
        "rpcuser",
        "rpcpassword",
    )?);

    // Initialize HD wallet (BIP84 native SegWit)
    let wallet = HdWallet::new(&std::env::var("WALLET_XPUB")?)?;

    // Generate unique address for order
    let order_id = uuid::Uuid::new_v4();
    let address = wallet.derive_address(order_id)?;
    println!("Deposit to: {}", address);

    // Start payment monitoring with confirmation tracking
    let config = MonitorConfig::default();
    let monitor = PaymentMonitor::new(client, config);
    monitor.start().await?;

    Ok(())
}

Lightning Network Invoice

use kaccy_bitcoin::{LndClient, InvoiceRequest, LightningPaymentManager};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let lnd = LndClient::new("https://localhost:8080", "macaroon_hex").await?;

    // Create invoice for order
    let invoice_req = InvoiceRequest {
        amount_sats: 50_000,
        description: "Order #12345".to_string(),
        expiry_secs: Some(3600),
    };

    let invoice = lnd.create_invoice(invoice_req).await?;
    println!("Pay invoice: {}", invoice.payment_request);

    // Monitor payment status
    let payment_mgr = LightningPaymentManager::new(lnd);
    let status = payment_mgr.check_payment(&invoice.payment_hash).await?;

    Ok(())
}

Multi-Signature Wallet

use kaccy_bitcoin::{MultisigWallet, MultisigConfig, CustodyManager};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create 2-of-3 multisig configuration
    let config = MultisigConfig {
        required_signatures: 2,
        total_keys: 3,
        network: bitcoin::Network::Bitcoin,
    };

    let pubkeys = vec![
        "platform_pubkey".to_string(),
        "user_pubkey".to_string(),
        "cold_storage_pubkey".to_string(),
    ];

    let multisig = MultisigWallet::new(config, pubkeys)?;
    let address = multisig.get_address()?;

    // Tiered custody management
    let custody_mgr = CustodyManager::new(config);
    let level = custody_mgr.determine_custody_level(1_000_000)?;

    Ok(())
}

PSBT Withdrawal

use kaccy_bitcoin::{PsbtManager, WithdrawalRequest, FeeEstimation};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let psbt_mgr = PsbtManager::new(client, wallet);

    // Create withdrawal transaction
    let request = WithdrawalRequest {
        user_id: uuid::Uuid::new_v4(),
        destination: "bc1q...".to_string(),
        amount: 100_000,
        fee_rate: FeeEstimation::Medium,
    };

    let psbt = psbt_mgr.create_withdrawal(request).await?;

    // Sign with hardware wallet and broadcast
    let signed = psbt_mgr.finalize_and_extract(psbt).await?;

    Ok(())
}

Taproot Address

use kaccy_bitcoin::{TaprootManager, TaprootConfig};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let config = TaprootConfig::default();
    let taproot_mgr = TaprootManager::new(config);

    // Generate Taproot key pair
    let keypair = taproot_mgr.generate_keypair()?;

    // Create key-path address (most efficient and private)
    let address = taproot_mgr.create_key_path_address(&keypair)?;
    println!("Taproot address: {}", address);

    Ok(())
}

Atomic Swap

use kaccy_bitcoin::{AtomicSwapManager, AtomicSwapConfig, SwapRole};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let config = AtomicSwapConfig::default();
    let swap_mgr = AtomicSwapManager::new(config);

    // Initiate atomic swap
    let swap = swap_mgr.initiate_swap(
        "counterparty_pubkey",
        100_000, // amount in sats
        "refund_address",
    ).await?;

    println!("Swap ID: {}", swap.swap_id);
    println!("Payment hash: {}", hex::encode(&swap.payment_hash));

    Ok(())
}

Batch Withdrawals

use kaccy_bitcoin::{BatchOptimizer, BatchStrategy, BatchWithdrawal};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let optimizer = BatchOptimizer::new();

    let withdrawals = vec![
        BatchWithdrawal {
            user_id: uuid::Uuid::new_v4(),
            address: "bc1q...".to_string(),
            amount: 50_000,
            priority: false,
        },
        // ... more withdrawals
    ];

    // Optimize batch for minimum fees
    let batch = optimizer.optimize(withdrawals, BatchStrategy::MinimizeFees)?;
    println!("Fee savings: {} sats", batch.efficiency.fee_savings);

    Ok(())
}

Configuration

Environment Variables

Core configuration:

• BITCOIN_RPC_URL - Bitcoin Core RPC endpoint (default: http://localhost:8332)
• BITCOIN_RPC_USER - RPC username
• BITCOIN_RPC_PASSWORD - RPC password
• BITCOIN_NETWORK - Network type (mainnet, testnet, regtest, signet)
• WALLET_XPUB - Extended public key for address derivation (BIP84)

Lightning Network:

• LND_REST_URL - LND REST API endpoint
• LND_MACAROON - LND macaroon hex string
• LND_TLS_CERT_PATH - Path to LND TLS certificate

Layer 2:

• STACKS_API_URL - Stacks API endpoint
• RSK_RPC_URL - RSK node RPC endpoint

Configuration Structs

Most modules provide configuration structs with sensible defaults:

// Monitor configuration
let config = MonitorConfig {
    poll_interval_secs: 30,
    min_confirmations: 6,
    ..Default::default()
};

// Reconnection configuration
let reconnect_config = ReconnectConfig {
    max_retries: 5,
    initial_delay_ms: 1000,
    max_delay_ms: 60000,
};

// HTLC configuration
let htlc_config = HtlcConfig {
    default_timelock_blocks: 144,
    min_timelock_blocks: 6,
    max_timelock_blocks: 2016,
};

Architecture

kaccy-bitcoin/
├── src/
│   ├── lib.rs                    # Crate root with public exports
│   │
│   ├── Core Modules
│   ├── client.rs                 # Bitcoin Core RPC client
│   ├── hd_wallet.rs              # BIP84 HD wallet
│   ├── wallet.rs                 # Wallet manager
│   ├── monitor.rs                # Payment monitoring
│   ├── confirmation.rs           # Confirmation tracking
│   ├── matcher.rs                # Transaction matching
│   ├── connection_pool.rs        # RPC connection pooling
│   ├── cache.rs                  # Transaction/UTXO/block caching
│   │
│   ├── Transaction Management
│   ├── psbt.rs                   # PSBT building and signing
│   ├── multisig.rs               # Multi-signature wallets
│   ├── taproot.rs                # Taproot addresses
│   ├── descriptor.rs             # Output descriptors
│   ├── tx_parser.rs              # Transaction parsing
│   ├── rbf.rs                    # Replace-By-Fee tracking
│   ├── advanced_rbf.rs           # Advanced RBF with batching
│   ├── fee_bumping.rs            # CPFP and RBF fee bumping
│   │
│   ├── Advanced Features
│   ├── lightning.rs              # Lightning Network
│   ├── timelock.rs               # HTLCs and timelocks
│   ├── atomic_swap.rs            # Atomic swaps
│   ├── submarine_swaps.rs        # Lightning-onchain swaps
│   ├── payjoin.rs                # PayJoin privacy
│   ├── coinjoin.rs               # CoinJoin privacy
│   ├── dlc.rs                    # Discreet Log Contracts
│   ├── miniscript_support.rs    # Miniscript policies
│   │
│   ├── Wallet Features
│   ├── coin_control.rs           # Manual UTXO selection
│   ├── gap_limit.rs              # BIP44 gap limit tracking
│   ├── transaction_history.rs    # Transaction history & export
│   ├── hwi.rs                    # Hardware wallet integration
│   ├── key_management.rs         # Key rotation & recovery
│   │
│   ├── Layer 2
│   ├── stacks.rs                 # Stacks integration
│   ├── rsk.rs                    # RSK integration
│   │
│   ├── Network Support
│   ├── p2p.rs                    # P2P protocol integration
│   ├── compact_filters.rs        # BIP 157/158 filters
│   ├── signet.rs                 # Signet support
│   ├── testnet4.rs               # Testnet4 support
│   │
│   ├── Monitoring & Security
│   ├── mempool.rs                # Mempool monitoring
│   ├── activity_monitor.rs       # Suspicious activity
│   ├── tx_limits.rs              # Transaction limits
│   ├── notifications.rs          # Admin notifications
│   ├── health.rs                 # Health check system
│   ├── audit.rs                  # Audit logging
│   │
│   ├── Optimization
│   ├── utxo.rs                   # UTXO management
│   ├── batch_optimizer.rs        # Batch withdrawals
│   ├── transaction_manager.rs    # Integrated management
│   │
│   ├── Observability
│   ├── metrics.rs                # Prometheus metrics
│   ├── structured_logging.rs     # Request/response logging
│   │
│   ├── Testing
│   ├── testing.rs                # Test helpers & utilities
│   │
│   └── error.rs                  # Error types
│
└── Cargo.toml

Payment Flows

On-Chain Payment Flow

1. User initiates purchase
   └─> Generate unique BTC address (HD wallet BIP84 derivation)
   └─> Display address to user
   └─> Cache address for future lookups

2. User sends BTC to address
   └─> MempoolMonitor detects unconfirmed transaction
   └─> Mark order as "pending" immediately
   └─> TransactionMatcher validates amount
   └─> Detect underpayment/overpayment
   └─> Send admin notification if discrepancy

3. Wait for confirmations (ConfirmationTracker)
   └─> 1 confirmation: Mark order as "confirming"
   └─> 3 confirmations: Update confidence level
   └─> 6 confirmations: Mark order as "confirmed"
   └─> Broadcast confirmation events

4. Execute trade
   └─> Update token supply
   └─> Credit user balance
   └─> Create trade record
   └─> Store transaction ID

Lightning Network Payment Flow

1. User requests Lightning payment
   └─> Generate invoice with amount and expiry
   └─> Return payment request to user

2. User pays invoice
   └─> LightningPaymentManager monitors invoice status
   └─> Detect payment immediately upon receipt
   └─> No confirmations needed (instant finality)

3. Execute trade
   └─> Credit user balance instantly
   └─> Create trade record
   └─> Store payment hash

Multi-Signature Withdrawal Flow

1. User requests withdrawal
   └─> CustodyManager determines required custody level
   └─> Check withdrawal limits (LimitEnforcer)
   └─> ActivityMonitor checks for suspicious patterns

2. Create PSBT
   └─> PsbtBuilder creates unsigned transaction
   └─> Select optimal UTXOs (UtxoManager)
   └─> Estimate fees based on target confirmation

3. Collect signatures
   └─> SignatureCoordinator manages signature collection
   └─> Platform signs first
   └─> User/hardware wallet signs
   └─> Cold storage signs if required (high-value)

4. Broadcast transaction
   └─> Finalize PSBT
   └─> Extract signed transaction
   └─> Broadcast to Bitcoin network
   └─> Monitor confirmation status

Dependencies

Core Bitcoin libraries:

• bitcoincore-rpc - Bitcoin Core RPC client
• bitcoin - Bitcoin primitives and transaction handling
• tokio - Async runtime
• serde / serde_json - Serialization

Additional dependencies:

• reqwest - HTTP client for Lightning/L2 APIs
• uuid - Unique identifiers
• chrono - Timestamp handling
• thiserror - Error type derivation
• tracing - Structured logging
• async-trait - Async trait support
• base64 / hex - Encoding utilities
• rand - Random number generation

Security Considerations

General Security

• Never store private keys - Use watch-only wallet (xpub only)
• Hardware wallet support - PSBT enables external signing
• Multi-signature - Distributed key management for high-value funds
• Cold storage - Automatic sweep to cold wallet above threshold
• Network isolation - Keep Bitcoin Core behind firewall
• TLS encryption - Use TLS for RPC connections in production

Transaction Security

• Transaction limits - Per-user and platform-wide limits enforced
• Activity monitoring - Detect suspicious patterns and high-risk transactions
• Confirmation tracking - Wait for sufficient confirmations (6 for high-value)
• RBF protection - Track transaction replacements and detect conflicts
• Mempool monitoring - Detect reorg attacks and double-spends early

Privacy Features

• Address reuse prevention - Unique address per order via HD derivation
• PayJoin support - Break common input ownership heuristic
• CoinJoin support - Enhanced privacy for withdrawals
• Taproot - Improved privacy and efficiency

Operational Security

• Automatic reconnection - Exponential backoff prevents denial of service
• Health checks - Regular node status monitoring
• Admin notifications - Alert on anomalies (underpayment, large transactions, RBF)
• Audit trail - All transactions logged with full details
• Rate limiting - Prevent abuse via velocity limits

Testing

Unit Tests

# Run all tests
cargo test -p kaccy-bitcoin

# Run specific module tests
cargo test -p kaccy-bitcoin --test taproot
cargo test -p kaccy-bitcoin --test atomic_swap

# Run with output
cargo test -p kaccy-bitcoin -- --nocapture

Integration Tests

Requires running Bitcoin Core in regtest mode:

# Start Bitcoin Core regtest
bitcoind -regtest -daemon \
  -rpcuser=rpcuser \
  -rpcpassword=rpcpassword \
  -fallbackfee=0.00001

# Create wallet
bitcoin-cli -regtest -rpcuser=rpcuser -rpcpassword=rpcpassword createwallet "test"

# Run tests
BITCOIN_NETWORK=regtest \
BITCOIN_RPC_URL=http://localhost:18443 \
BITCOIN_RPC_USER=rpcuser \
BITCOIN_RPC_PASSWORD=rpcpassword \
cargo test -p kaccy-bitcoin

Coverage

Current test coverage: 254 tests across all modules

• Core modules: Client, HD Wallet, Monitor, Connection Pool, Cache
• Transaction management: PSBT, Multisig, Taproot, Descriptors, Fee Bumping, Advanced RBF
• Advanced features: Lightning, Timelock, Atomic Swap, Submarine Swaps, DLC, Miniscript
• Wallet features: Coin Control, Gap Limit, Transaction History, Hardware Wallets, Key Management
• Privacy: PayJoin, CoinJoin
• L2: Stacks, RSK
• Network: P2P, Compact Filters, Signet, Testnet4
• Monitoring: Mempool, Activity, Limits, Health Checks, Audit Logging
• Optimization: UTXO, Batch optimizer, Transaction Manager
• Observability: Metrics, Structured Logging
• Testing utilities: Fuzz helpers, Property tests, Integration helpers, Load tests

Performance Considerations

• Address caching - Avoid repeated derivation
• UTXO management - Consolidate during low-fee periods
• Batch withdrawals - Reduce transaction count and fees
• Connection pooling - Reuse RPC connections
• Efficient polling - Configurable poll intervals (default 30s)

License

Licensed under the same terms as the Kaccy Protocol project.