bsv-wallet-cli: Instructions file for Claude Code

bsv-wallet-cli

Single Rust binary providing both a CLI wallet and an HTTP server that implements all 28 BRC WalletInterface endpoints, wire-compatible with the MetaNet Client.

Architecture

The binary has two modes: CLI commands for interactive wallet use, and an HTTP server (port 3322) that is wire-compatible with MetaNet Client.

src/
  main.rs          — CLI entrypoint, routes clap subcommands
  context.rs       — WalletContext: loads ROOT_KEY, opens SQLite, configures services
  cli.rs           — Clap argument definitions
  commands/        — One file per CLI command (init, send, daemon, serve, split, etc.)
  server/
    mod.rs         — Axum router setup, CORS, auth middleware, SpendingLock
    handlers.rs    — All 28 endpoint handlers, each translating MetaNet JSON ↔ SDK types
    types.rs       — MetaNet Client JSON request/response structs (the translation layer)

Dependency chain: bsv-wallet-cli → bsv-wallet-toolbox-rs (wallet engine, SQLite storage, signing, broadcasting) → bsv-rs (WalletInterface trait, crypto primitives). Both are published on crates.io.

Conventions

• MetaNet Client wire compatibility is the top constraint. The HTTP server must produce identical JSON to the MetaNet Client so existing tools (x402 skill, BRC-31 auth) work without modification.
• Translation layer (server/types.rs): MetaNet Client uses different JSON shapes than the Rust SDK. Key differences:
  • protocolID: mixed array [2, "name"] vs SDK's Protocol { security_level, protocol_name }
  • counterparty: hex string vs Counterparty::Other(PublicKey)
  • Binary data (tx, signature): JSON number arrays [0,1,2,...] vs hex strings
  • Field names: MetaNet Client uses protocolID / keyID (capital D). Use #[serde(alias = "protocolID")] since rename_all = "camelCase" produces lowercase d.
• SpendingLock: A FIFO mutex serializes createAction calls. With limited UTXOs, concurrent spending races on SQLite's write lock. Non-spending endpoints (crypto, queries) run fully concurrent.
• Daemon vs Serve: daemon = Monitor (background sync tasks) + HTTP server. serve = HTTP server only (dev mode, no background sync).
• The explorer ladder (0.17.0, #50; the owner's word of 2026-10-22): each chain scanner has its own rate limits, so when one fails we go to the next. Every chain question that leaves the wallet asks WhatsOnChain, BananaBlocks and Bitails as each other's fallbacks: the toolbox's ladders (=0.13.1: get_raw_tx, get_merkle_path, get_utxo_status, get_status_for_txids, is_utxo; is_utxo_with_spender for the spend probe (0.18.2, #196: one ladder pass per outpoint, four explorer requests in the bound-spender witness with or without the header service, plus a proof and header when needed; without the header service this is four rather than 0.13.0's two. Bytes alone name the bound spender unconfirmed; an unreadable or unbound name is (Unknown, None), never unspent, toolbox #96); get_utxo_leads for sync's discovery, where one explorer's list is a lead and each lead is verified before it is received) and the CLI's own rungs in src/explorers.rs (receive's couriers: WoC /beef, then BananaBlocks /hex with the services' checked proof, then get_beef) and broadcast_verify's chain indexes (WoC, Bitails, BananaBlocks). A fault (a 429, a timeout, a 5xx, a malformed body, bytes that do not hash to the txid) is "could not look": it moves to the next rung at once and is never "unspent" or "absent". A negative needs a second provider's clean answer (BananaBlocks' 404 is a gap, never a vote). No rung sleeps on a 429: the rung is skipped without a request until its Retry-After passes (the toolbox's RateGate). Every explorer call logs explorer_call at info with provider, call, status, ms. The spend gate and the tracker read the wallet's own proof records, never an explorer. The broadcaster is not an explorer rung: postBeef's ladder in Arcade mode is ArcadeV2, TaalArcBeef (the toolbox's, unauthenticated, until toolbox #317), Bitails, WhatsOnChain, all four in that order (#300); GorillaPool's ARC is never a rung.