[HLR] Cross-SDK Compatibility and Interoperability

[sgbett]

Problem

The BSV SDK ecosystem defines a vendor-neutral wallet interface (BRC-100) and wire protocol that should enable any conformant implementation to interoperate with any other. In practice, interoperability is aspirational — there is no automated way to verify that our Ruby SDK produces the same outputs, accepts the same inputs, and behaves identically to the TypeScript, Go, and Python reference implementations.

As we build beyond the core SDK into wallet infrastructure (UTXO pools, broadcast queues, storage adapters), the surface area for subtle divergence grows. A transaction created by the Ruby wallet must be indistinguishable from one created by the TS wallet when observed by a counterparty, an ARC endpoint, or a verification tool.

Scope

Cross-SDK testing and validation — ensuring our implementation matches the reference SDKs at every protocol boundary.

1. Wire protocol conformance

The BRC-100 ABI specification defines a binary wire protocol for wallet-to-application communication. Our Wire::Serializer must produce byte-identical frames for the same logical operations. This needs:

• Cross-SDK test vectors (known inputs → expected binary output)
• Round-trip tests: serialise in Ruby, deserialise in TS (and vice versa)
• Fuzz testing against the TS SDK's WalletWireProcessor

2. Transaction compatibility

Transactions (including BEEF format) created by the Ruby SDK must be accepted by TS SDK verification and vice versa. This needs:

• Shared test vectors for common transaction types (P2PKH, multi-output, OP_RETURN, auto-funded with change)
• BEEF serialisation/deserialisation cross-validation
• Merkle proof format compatibility (BRC-74 BUMP)

3. Key derivation compatibility

BRC-42/43 key derivation must produce identical keys across all SDKs for the same inputs. This needs:

• Static test vectors: (root key, protocol ID, key ID, counterparty) → derived public key
• BRC-29 payment key derivation cross-validation
• Certificate field encryption/decryption interoperability

4. Divergence analysis tooling

Automated comparison of our SDK against the reference implementations:

• Feature coverage matrix (which BRCs are implemented, partially implemented, or missing)
• API surface comparison (method signatures, parameter names, return types)
• The /divergence-analysis skill provides a starting point but needs to be formalised

Acceptance criteria

• Sub-issues created for each initiative above
• Automated cross-SDK validation running in CI for at least one category (transactions, keys, or wire protocol)
• Static test vectors published and shared (potentially upstream to bitcoin-sv/BRCs as a test vector BRC)

Context

• The README commits to "faithful adherence to BRC specifications and cross-SDK compatibility"
• BRC-104 (HTTP Transport for Mutual Authentication) defines the HTTP layer for wallet communication
• /divergence-analysis skill exists for manual comparison; this HLR formalises and automates it

Related

• BRC-100: Wallet Interface (the contract we're conforming to)
• BRC-104: HTTP Transport for BRC-103 Mutual Authentication
• [HLR] SPV Wallet Node — Self-Validating Wallet Architecture #602: SPV Wallet Node (the engine these tests validate)