bsv-wallet-cli CLAUDE.md

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).