feat: BSV mechanism for the x402 exact scheme (BRC-121/BRC-29)

[sirdeggen]

What

Adds BSV as an x402 payment mechanism for the exact scheme, for internal discussion before anything goes to the x402 Foundation. New package @x402/bsv, a protocol spec, example wiring, and a WhatsOnChain USD price feed — built on the BRC-121 / BRC-29 flow already shipped in @bsv/402-pay.

How it maps BRC-121 onto x402

• payTo = the recipient wallet's BRC-100 identity public key (never appears on chain — every payment pays a fresh BRC-42-derived key)
• Payload = a BRC-29 remittance: { transaction (base64 BEEF), derivationPrefix, derivationSuffix, senderIdentityKey, outputIndex }; the suffix decodes to a Unix-ms timestamp (BRC-121 freshness)
• The client's BRC-100 wallet funds, fees, and signs the transaction via createAction — no gas sponsorship
• The facilitator is the recipient's own wallet. BRC-42 destinations are ECDH-derived, so a third party cannot take custody, and cannot verify the destination unilaterally (either counterparty can disclose a BRC-69 key linkage, verifiable via BRC-94 Schnorr ZKP — see the spec's auditability appendix, and the discussion point below). verify checks structure, wallet-chain agreement, freshness, exact amount, and the derived destination; settle = internalizeAction, with a txid dedup cache + isMerge for replay defense
• Networks bsv:mainnet / bsv:testnet — a bsv CAIP-2 namespace now proposed at ChainAgnostic/namespaces#190 (human-readable network names, casper precedent; note bip122 can also represent BSV via its fork-block hash, as it does for Bitcoin Cash)

What's in the PR

@x402/bsv package (typescript/packages/mechanisms/bsv), modeled on the Concordium mechanism:

• exact/client — derives the per-payment key and builds the funded BEEF payment
• exact/facilitator — verifies and settles into the recipient wallet
• exact/server — builds PaymentRequirements, satoshi price parsing (8 decimals)
• createWhatsOnChainMoneyParser — converts USD route prices ("$0.001") to satoshis via the WhatsOnChain exchange-rate API (60 s cache, single-flight refresh, bounded stale fallback)
• constants / types, README, package/tsup/tsconfig/vitest config, changeset, and an npm publish workflow

Spec: specs/schemes/exact/scheme_exact_bsv.md (full exact-on-BSV spec incl. a Key Linkage Revelation & Auditability appendix) + BSV safety invariants in the shared scheme_exact.md appendix.

Examples: all three all_networks examples wired —

• client: BSV_WALLET=true + a running BRC-100 wallet (e.g. BSV Desktop)
• facilitator: BSV_SERVER_PRIVATE_KEY + BSV_WALLET_STORAGE_URL via @bsv/simple ServerWallet
• server: BSV_IDENTITY_KEY, priced in USD through the money parser

Hardening (adversarial review)

A multi-lens review (interface correctness, security, @bsv/sdk fidelity, spec consistency, conventions) surfaced 24 confirmed findings, all fixed on this branch:

• Free-work exploit — verify now derives the BRC-42 destination (getPublicKey forSelf) and matches it against the P2PKH script, so unfundable/mispaid BEEFs fail before any resource work
• Decoy-tx divergence — subject tx resolved via Atomic BEEF atomicTxid, matching what the wallet internalizes
• Settlement expiry — settle extends the freshness window by maxTimeoutSeconds, so slow handlers don't void valid payments
• Replay — isMerge is a wallet-toolbox extension (not core BRC-100), so a facilitator-side txid dedup cache backs it up
• Chain agreement — facilitator checks getNetwork() against the requested network
• Plus: transaction: "" on all failures per core v2, non-BSV assets rejected at config time, case-insensitive payee comparison

Testing

• 103 unit tests (pnpm test in the package) — payload construction, verify/settle rules, Atomic BEEF subject resolution, replay paths, timestamp windows, and the rate-feed parser (cache / stale / error paths)
• Live smoke: money parser against the real WhatsOnChain API ($0.001 → 7,440 sats at $13.44/BSV)
• Live wallet round trip: BSV_INTEGRATION=true pnpm test:integration with BSV Desktop running (create → verify → settle → replay-reject) — not yet run, needs a funded wallet
• Deferred: e2e-harness wiring, Go/Python ports (upstream wants the TS reference first)

Points to discuss before a Foundation PR

1. Namespace: the bsv namespace is now up for review at ChainAgnostic/namespaces#190 — please review/comment there. Open question: keep the name-based bsv:mainnet/bsv:testnet scheme, or fall back to bip122:<fork-block-hash> if the editors prefer it (would mean reworking the network IDs here).
2. Facilitator trust model: recipient-wallet facilitator is honest to BRC-29 but unusual for x402. Two extension paths for shared/third-party facilitators: a plain-P2PKH addressing variant (loses the privacy model), or a key-linkage-proof flow (revealSpecificKeyLinkage, BRC-69/BRC-94) enabling destination verification without custody — also the auditability path for regulated assets like BSV stablecoins.
3. Strict amount equality (x402 exact) vs BRC-121's overpay-tolerant check — the spec documents the divergence.
4. Upstream process is spec-PR-first with a prior issue; the spec commit is separable for that.

🤖 Generated with Claude Code

https://claude.ai/code/session_01U8iaxitVKXh9EZR5HzAYfg

[github-actions]

Thanks for your contribution @sirdeggen!
Note that we require commit signing, please rebase and verify your commits.

See here for instructions: https://docs.github.com/en/authentication/managing-commit-signature-verification/about-commit-signature-verification

The team will not review this PR before ALL commits have been verified and it will be closed after 1 week of inactivity.

Unverified commits:

• b7f97f4: unsigned

[sirdeggen]

Filed the CAIP-2 namespace registration upstream: ChainAgnostic/namespaces#190 (ChainAgnostic/namespaces#190). It proposes bsv:mainnet / bsv:testnet as a bsv namespace using human-readable network names (following the casper precedent). The rationale is upfront that bip122 could instead represent BSV via its fork-block hash (as it does for Bitcoin Cash) — so if we'd rather go that route, now's the time to say so before the editors weigh in. Review and comments welcome on either PR.