Add Bitcoin Blockchain Integration (Basic)

[kelly-musk]

Overview

This issue involves adding basic Bitcoin blockchain support to enable operations like connecting to a Bitcoin node, validating addresses, checking balances, and broadcasting transactions. This is part of the multi-chain expansion, allowing Aframp to handle Bitcoin alongside Stellar and Ethereum for broader crypto support. Focus on core RPC interactions without advanced features like multi-sig or Lightning. This will integrate into the unified blockchain service (Issue #15) and support future onramp/offramp for BTC.

Use a reliable Bitcoin RPC client to interact with nodes (testnet/mainnet), ensuring compatibility with AFRI if bridged to Bitcoin in the future. Emphasize security, efficiency, and error handling to prevent issues like invalid transactions or network failures. This complements Ethereum integration (Issue #13) and builds on Phase 1 infrastructure.

Key Requirements

• Language/Tech Stack: Rust with a Bitcoin RPC crate (e.g., bitcoin-rpc or bitcoincore-rpc). Use async for RPC calls. Configure via env vars (Issue Good First Issue: Setup Project Configuration and Health Check Endpoint #1) for node URLs, auth credentials, and network (testnet/mainnet).
• Modular Design: Develop in a dedicated module (e.g., src/services/bitcoin_rpc.rs) with a BitcoinService struct. Align methods with the common trait in Issue Implement Ethereum RPC Integration #15 for chain-agnostic use.
• Error Handling: Custom errors (e.g., BtcError::InvalidAddress, BtcError::BroadcastFailed) linked to Issue Implement Redis Caching Layer #8's system. Handle RPC-specific issues like connection timeouts.
• Testing: Unit tests for each function (expanded in Issue Implement POST /api/onramp/quote Endpoint #50), using testnet or mock RPC servers.
• Security: Validate all inputs (e.g., Bech32/Base58 addresses); avoid exposing private keys in this basic integration.
• Dependencies: Core config (Issue Good First Issue: Setup Project Configuration and Health Check Endpoint #1), Redis for caching (Issue Initialize Stellar Smart Contracts for AFRI Stablecoin #7). Can proceed in parallel with Build AFRI Trustline Management System #13.

Detailed Tasks

1. Bitcoin RPC Connection:

   • Function: async fn init_client(url: &str, auth: &Auth) -> Result<BitcoinClient, BtcError>
   • Set up RPC client with username/password or cookie auth.
   • Health check: Call getblockchaininfo to verify connection and network.
   • Support testnet (e.g., signet/regtest for dev).

2. Address Validation:

   • Function: fn validate_address(address: &str) -> Result<bool, BtcError>
   • Check if address is valid for the network (P2PKH, P2SH, Bech32/SegWit).
   • Use crate utilities or regex for format; optionally query RPC for validateaddress.

3. Balance Checking:

   • Function: async fn get_balance(address: &str) -> Result<Satoshi, BtcError>
   • Scan UTXOs or use getreceivedbyaddress if wallet-enabled; for non-custodial, prefer scantxoutset or external indexing if needed.
   • Convert to BTC decimals; cache in Redis with TTL (e.g., 1 minute).

4. Transaction Broadcasting:

   • Function: async fn broadcast_tx(raw_tx: &str) -> Result<TxId, BtcError>
   • Send raw hex transaction via sendrawtransaction.
   • Validate tx format before broadcast; handle errors like low fee or double-spend.

Acceptance Criteria

• Connect to a Bitcoin testnet node, validate a sample address, fetch its balance, and broadcast a mock/test transaction.
• Handle errors: Invalid address (false/error), no connection (retry/fail), broadcast rejection (e.g., insufficient fee).
• Performance: RPC calls <1s; efficient for high-volume checks.
• Logs: Structured entries, e.g., "Bitcoin balance [amount] BTC for address [addr]; tx [id] broadcasted".
• Documentation: Inline code comments; update multi-chain guide in Issue Implement POST /api/offramp/initiate Endpoint #62.

Estimated Effort

4-5 hours: 1h connection/setup, 1h validation/balance, 1h broadcasting, 1h testing/debugging.

Related Issues

• Blocked by: None directly, but aligns with Build AFRI Trustline Management System #13 (Ethereum).
• Blocks: Implement Ethereum RPC Integration #15 (Unified Interface).
• Good First Issue? No, requires Bitcoin RPC knowledge—refer to Bitcoin Core docs: https://bitcoin.org/en/developer-reference#remote-procedure-calls-rpcs.

[Bigdaddyobamo]

@Bigdaddyobamo has applied to work on this issue as part of the Stellar Wave Program's 7th wave.

Hello, Big Boss, please let me work on this issue.

ℹ️ Repo Maintainers: To accept this application, review their application or assign @Bigdaddyobamo to this issue.

[boss572]

@boss572 has applied to work on this issue as part of the Stellar Wave Program's 7th wave.

Hello maintainer please I will like to work on this issue

ℹ️ Repo Maintainers: To accept this application, review their application or assign @boss572 to this issue.