did-beta-bch 2.0.1 → 3.1.0

package/PROTOCOL.md

@@ -1,75 +1,55 @@
 # Cashlet DID Protocol Specification
 
-Version: `2.0.0`
-Status: Draft
+Version: `3.0.0`  
+Status: Final
 
-This is the normative specification for Cashlet DID v2. V2 is a breaking
-signature-format update: conforming verifiers MUST reject v1 proof tags and
-signatures. Existing v1 bindings must be re-created and re-published.
-
----
+Cashlet DID v3 is a breaking protocol update. Conforming verifiers MUST reject
+v1 and v2 binding records. Existing identities must be rebound and republished.
 
 ## 1. Identifiers
 
 | Constant | Value |
 |---|---|
 | Protocol ID | `cashlet-did` |
-| Protocol version | `2.0.0` |
-| Binding event kind | `30078` (NIP-78 addressable data) |
+| Protocol version | `3.0.0` |
+| Binding event kind | `30078` |
+| Rotation authorization kind | `30080` |
 | Credential event kind | `30085` |
 | Revocation event kind | `5` (NIP-09) |
+| Dual-key challenge kind | `27235` (NIP-98 event format) |
 | Nostr derivation path | `m/44'/1237'/<account>'/0/0` (NIP-06) |
 
-## 2. Canonical binding record
+## 2. Binding and BCH ownership proof
 
 A binding record has recursively sorted object keys, no whitespace, and omits
 undefined/absent fields:
 
 ```json
 {
-  "bch": {
-    "address": "<prefixed-cashaddr>",
-    "network": "mainnet" | "testnet" | "chipnet",
-    "paymentCode": "<BIP47 payment code>"   // optional
-  },
-  "createdAt": <unix seconds>,
+  "bch": { "address": "<prefixed-cashaddr>", "network": "mainnet|testnet|chipnet" },
+  "createdAt": 0,
   "nostr": { "pubkey": "<32-byte lowercase hex>" },
   "nonce": "<64 lowercase hex chars>",
-  "previousBindingId": "<64 lowercase hex chars>", // optional
   "protocol": "cashlet-did",
-  "purpose": "identity-binding-v2",
-  "version": "2.0.0"
+  "purpose": "identity-binding-v3",
+  "version": "3.0.0"
 }
 ```
 
-**Binding ID** = lowercase hex `SHA-256(canonicalize(record_without_bindingId))`.
-Arrays preserve order. `mainnet` addresses use the `bitcoincash:` prefix;
-`testnet` and `chipnet` use `bchtest:`.
-
-## 3. BCH signing payload and wallet contract
+Optional fields are `bch.paymentCode` and `previousBindingId`. The binding ID
+is lowercase hex `SHA-256(canonicalize(record_without_bindingId))`. Arrays
+preserve order. Mainnet addresses use `bitcoincash:`; testnet and chipnet use
+`bchtest:`.
 
-The exact UTF-8 message text supplied to a wallet is:
+The exact UTF-8 message supplied to the BCH wallet is:
 
 ```text
-cashlet-did/bch-proof/v2.0.0\n<canonicalized subset>
-```
-
-The subset contains exactly these keys:
-
-```json
-{
-  "bchAddress": "<prefixed-cashaddr>",
-  "bchNetwork": "mainnet" | "testnet" | "chipnet",
-  "bindingId": "<64 lowercase hex chars>",
-  "createdAt": <unix seconds>,
-  "nonce": "<64 lowercase hex chars>",
-  "nostrPubkey": "<32-byte lowercase hex>",
-  "purpose": "identity-binding-v2"
-}
+cashlet-did/bch-proof/v3.0.0\n<canonicalized subset>
 ```
 
-Pass this exact message string to the wallet's message-signing method. Do not
-pre-hash, add a Bitcoin prefix, or otherwise transform it in the adapter. The
+The subset contains exactly `bindingId`, `bchAddress`, `bchNetwork`,
+`nostrPubkey`, `nonce`, `purpose`, and `createdAt`. Pass this exact text to the
+wallet; do not pre-hash, add a Bitcoin prefix, or otherwise transform it. The
 wallet computes:
 
 ```text
@@ -77,168 +57,150 @@ SHA256d(0x18 || "Bitcoin Signed Message:\n" ||
        CompactSize(UTF8(message).length) || UTF8(message))
 ```
 
-`CompactSize` uses Bitcoin's little-endian encodings: one byte below `0xfd`,
-`fd` plus 2 bytes through `0xffff`, `fe` plus 4 bytes through `0xffffffff`,
-then `ff` plus 8 bytes.
+The response MUST be canonical padded Base64 for exactly 65 bytes:
+`[header 31–34] || [32-byte r] || [32-byte s]`. The header selects a compressed
+public key and recovery ID 0–3. Raw hex, 64-byte signatures, uncompressed
+headers, non-canonical Base64, and v1/v2 proof formats are rejected.
 
-The wallet response is standard padded Base64 encoding of exactly 65 bytes:
+## 3. Binding Nostr event
 
-```text
-[header byte 31–34] || [32-byte r] || [32-byte s]
-```
-
-The header is `27 + 4 + recovery_id`; recovery IDs are `0–3`, and `+4`
-specifies a compressed public key. V2 accepts only this compressed-key form.
-Verifiers decode Base64, subtract 31 from the header, recover the compressed
-public key, and derive its prefixed BCH CashAddr. Raw hex, 64-byte signatures,
-uncompressed headers, non-canonical Base64, and v1 signatures are rejected.
-
-### Wallet interoperability evidence
-
-Paytaca's WalletConnect implementation signs the supplied message with the
-Bitcoin message prefix, `bigIntToCompactUint`, double-SHA256, and recoverable
-compact ECDSA; it adds `31` for compressed keys and returns Base64:
-[Paytaca source](https://github.com/Paytaca/paytaca-app/blob/41c785b9f48dee337d2da3f33e082e5210d462d0/src/wallet/walletconnect2/index.js).
-The BCH WalletConnect BCR also specifies Electron Cash-compatible signed
-messages: [BCR](https://github.com/mainnet-pat/wc2-bch-bcr/blob/55e3e37142ddc7b30ad63c7330ef8df252fec715/README.md).
-The library keeps this contract transport-neutral; validate each wallet
-release's response in integration tests before advertising support.
-
-## 4. Nostr event (kind 30078)
-
-The event timestamp MUST equal the binding's `createdAt`. Required tags:
+Publish a kind `30078` event whose timestamp equals `binding.createdAt`.
+Required tags:
 
 ```json
 [
   ["d", "<bindingId>"],
   ["bch", "<cashaddr>", "<network>"],
-  ["protocol", "cashlet-did", "2.0.0"],
+  ["protocol", "cashlet-did", "3.0.0"],
   ["t", "cashlet-did"],
   ["bch-proof", "bitcoin-message/compact-base64", "<exact message>", "<signature Base64>"]
 ]
 ```
 
-Optional tags:
-
-```json
-["bch-payment-code", "<BIP47 code>"]       // must equal content.bch.paymentCode
-["supersedes", "<previous bindingId>"]     // must equal content.previousBindingId
-["bch-anchor", "<txid>", "<claimed height>"] // unverified chain claim
-```
+Optional tags are `bch-payment-code`, `supersedes`, `rotation-proof`, and
+`bch-anchor`. Content is canonical JSON with `protocol`, `version`,
+`bindingId`, `bch`, `nonce`, and `createdAt`, plus optional `previousBindingId`
+and embedded `rotationAuthorization`. The Nostr event signature covers all
+tags and content. A `bch-anchor` tag is an untrusted claim until independently
+verified under §8.
 
-`content` is the canonicalized JSON object containing `protocol`, `version`,
-`bindingId`, `bch`, `nonce`, `createdAt`, and optional `previousBindingId`.
-`bch` contains `address`, `network`, and optional `paymentCode`. Nostr event
-signatures protect all event tags and content.
+## 4. Discovery, revocation, and verification
 
-## 5. Discovery and revocation
-
-Discover v2 records with this NIP-01 filter:
+Discover v3 bindings with:
 
 ```json
 { "kinds": [30078], "authors": ["<pubkey hex>"], "#t": ["cashlet-did"] }
 ```
 
 Revocations are kind `5` events from the same author with `["e", "<event id>"]`
-tags. Filter revoked records before selecting the newest v2 binding.
+tags. Filter revoked records before selecting the newest binding.
 
-## 6. Verification algorithm
+A verifier MUST:
 
 1. Verify the NIP-01 event signature and require kind `30078`.
 2. Require exactly one correctly shaped `d`, `bch`, `protocol`, `t`, and
-   `bch-proof` tag. The proof tag MUST have exactly four elements and the v2
-   format marker. Check optional payment-code and supersedes tags against
-   content; reject duplicate or malformed known tags.
-3. Parse content and require its canonical serialization, exact v2 fields,
-   event timestamp, `d`, `bch`, protocol/version tags, and resolved identity
-   (`npub`, Nostr pubkey, address, network, and binding ID) to agree.
-4. Recompute the binding ID and reconstruct the exact v2 BCH signing payload.
-   The proof tag's message must be byte-for-byte identical.
-5. Decode the canonical 65-byte Base64 compact signature, recover the
-   compressed public key from the Bitcoin signed-message hash, and derive
-   the network-appropriate BCH CashAddr. It must equal the bound address.
+   `bch-proof` tag; validate all known optional tags and reject duplicates.
+3. Require canonical content with the exact v3 fields, timestamp, binding ID,
+   event tags, and resolved identity to agree.
+4. Recompute the binding ID and exact v3 BCH signing payload.
+5. Recover the compressed BCH public key from the canonical compact signature
+   and require its CashAddr to equal the bound address.
 6. Report `verified` only when both the Nostr and BCH signatures are valid.
 
-V1 tags do not satisfy the v2 proof-tag structure and MUST NOT be accepted as
-fallbacks.
+V1 and v2 bindings MUST NOT be accepted as fallbacks.
 
-## 7. Challenge-response authentication
+## 5. Cross-key rotation
 
-The exact v2 message is either:
+A successor sets `previousBindingId` and includes the matching `supersedes`
+tag. Resolvers MUST verify every event in the chain and fail closed if a
+predecessor is missing, revoked, or invalid.
 
-```text
-cashlet-did/challenge/v2.0.0\n<nonce>
-```
+When the Nostr key changes, the successor MUST embed a kind `30080`
+authorization event signed by the previous Nostr key. Its canonical content
+names the previous binding ID/key and the exact successor binding ID/key,
+BCH address/network, and creation time. The successor includes
+`["rotation-proof", "<authorization event id>", "<old pubkey>"]`. A resolver
+MUST verify the old-key event signature and match every field and tag to the
+successor. Same-key succession does not need this extra signature. Lost-key
+recovery is out of scope; without old-key authorization, cross-key rotation is
+rejected.
 
-or, with an audience:
+## 6. Dual-key challenge-response authentication
+
+The BCH-signed payload is either:
 
 ```text
-cashlet-did/challenge/v2.0.0\n<nonce>\n<audience>
+cashlet-did/challenge/v3.0.0\n<nonce>
+cashlet-did/challenge/v3.0.0\n<nonce>\n<audience>
 ```
 
-The no-audience form has exactly two lines; the audience form has exactly three.
-No extra lines or trailing newline are allowed. The nonce and optional audience
-are single-line strings. The BCH wallet signs the exact text using §3's Bitcoin
-signed-message hash and 65-byte Base64 signature.
-`bchChallengePayload(nonce, audience?)` constructs the payload;
-`verifyChallengeProof` checks exact equality, signature, address, and—when
-`issuedAt` is provided—a 5-minute TTL. Applications must issue and consume
-one-time challenges and separately verify Nostr control if required.
-
-## 8. Key rotation
+The audience form has exactly three lines; no extra line or trailing newline
+is allowed. The Nostr key also signs a kind `27235` event with exactly one each
+of these tags: `u` (verification endpoint), `method` (`POST`), `audience`,
+`challenge`, and `expiration`. Its content is the exact BCH payload above.
+Both proofs MUST match the same verified binding's BCH address and Nostr
+pubkey, nonce, audience, endpoint, issue time, and expiration.
 
-Set `previousBindingId` in the new binding and add the matching
-`["supersedes", "<previousBindingId>"]` tag. Resolvers can follow references
-backwards, but must independently verify each referenced binding and fail
-closed if a predecessor is unavailable or invalid. A supersedes tag authored
-by the new key does not prove that the previous Nostr key authorized rotation.
+The server MUST issue an unpredictable, one-time challenge, persist it, and
+atomically consume it only after validating both signatures. Browser-local
+challenge state alone is not server-enforced authentication.
+`verifyDualChallengeProof` checks cryptographic and context binding; the
+application is responsible for durable single-use challenge state.
 
-## 9. Selective disclosure
+## 7. NIP-05 and NIP-98
 
-The library's selective-disclosure helper commits each attribute using an
-independent random 32-byte salt:
-
-```text
-SHA-256("cashlet-did/attr/v2\n" + JSON([key, value, salt]))
-```
+NIP-05 resolution is `user@domain` → `GET
+https://domain/.well-known/nostr.json?name=user` → extract pubkey → resolve
+and verify the v3 binding. A registration endpoint MUST verify the candidate
+event's Nostr signature and BCH ownership proof before reserving a handle.
 
-Keep salts private until revealing their associated values; include the value
-and salt in each reveal so a verifier can recompute the commitment. The helper
-does not publish commitments or attach them to a binding event automatically.
+NIP-98 uses kind `27235`. The `verifyBch: true` option additionally resolves
+the signer's v3 Cashlet DID binding. The server verifier must receive the
+actual request body (`null` when absent), compare its SHA-256 hash with the
+`payload` tag, reject missing/duplicate/mismatched hashes, and enforce the
+documented 60-second event window.
 
-## 10. On-chain commitment (OP_RETURN)
+## 8. BCH transaction anchor
 
-Embed the binding ID in a BCH transaction output:
+The OP_RETURN output commits to:
 
 ```text
 OP_RETURN <"cashlet-did:" + bindingId>
 ```
 
-The library can construct an anchor transaction, but it does not broadcast the
-transaction or verify its inclusion in a confirmed block. A `bch-anchor` event
-tag is only an issuer-provided claim; applications that need confirmed
-anchoring must independently verify the transaction and block inclusion.
+`buildAnchorTx` constructs a transaction but does not broadcast it. A binding's
+`anchor` field and `bch-anchor` tag only identify a claimed transaction and
+height; they do not prove inclusion. `verifyBchAnchorProof` checks the exact
+zero-value commitment, txid, Merkle inclusion, BCH ASERT difficulty, proof of
+work, median-time-past, future-time bound, and confirmation depth for a header
+chain extending from an application-trusted checkpoint.
 
-## 11. NIP-05 handle resolution
+The exported `BCH_MAINNET_CHECKPOINT` is a fixed mainnet trust root. The result
+is **checkpointed SPV**, not full-node validation: proof sources are untrusted,
+the checkpoint must not be fetched from the same endpoint, and the proof does
+not establish that a supplied branch is the globally highest-work branch.
+There is no chipnet checkpoint or proof-fetch adapter in this package, so
+chipnet anchors remain unverifiable unless an application supplies an
+independently reviewed checkpoint and consensus configuration.
 
-`user@domain` → `GET https://domain/.well-known/nostr.json?name=user` →
-extract `pubkey` → resolve the v2 binding via §5.
+## 9. Other helpers
 
-## 12. NIP-98 HTTP Auth
+Selective disclosure commits each attribute using an independent random
+32-byte salt:
 
-Build a kind `27235` event per NIP-98. The `verifyBch: true` option on the
-server additionally resolves the signer's v2 Cashlet DID binding. The verifier
-must receive the actual request body (`null` when absent) and compare its
-SHA-256 hash with the event's `payload` tag. Reject missing, duplicate, or
-mismatched payload hashes and enforce the documented 60-second event window.
+```text
+SHA-256("cashlet-did/attr/v2\n" + JSON([key, value, salt]))
+```
 
-## 13. Credentials
+Keep salts private until revealing their associated values; include the value
+and salt in each reveal so a verifier can recompute the commitment. The helper
+does not publish commitments or attach them to a binding event automatically.
 
-Credential events use kind `30085`. A resolver must verify the Nostr event
+Credential events use kind `30085`. A resolver must verify the issuer's Nostr
 signature, require the event's `p` tag and credential payload subject to match
 the requested pubkey, and require the `credential-type` tag to match the
-payload type. `issuedAt` must match the event timestamp. If `expiry` is present,
-reject the credential once that Unix timestamp has passed. A revocation is
-effective only when a valid kind `5` event from the credential's issuer
-references that credential event ID. Cryptographic validity does not establish
-that an issuer is trusted; trust policy is application-specific.
+payload type. `issuedAt` must match the event timestamp. If `expiry` is
+present, reject the credential once that Unix timestamp has passed. A
+revocation is effective only when a valid kind `5` event from the issuer
+references that credential event. Cryptographic validity does not establish
+issuer trust; that policy is application-specific.

package/README.md

@@ -4,8 +4,9 @@ A standalone, framework-agnostic library implementing the **Cashlet DID protocol
 
 Any BCH wallet or Nostr client can use this library to publish, resolve, and verify BCH–Nostr identity bindings without depending on the Cashlet extension.
 
-This release is Cashlet DID v2.0.0, a breaking proof-format update. V2 verifiers
-do not accept v1 bindings; existing identities must be rebound and republished.
+This release is Cashlet DID v3.0.0, a breaking protocol update. V3 verifiers
+do not accept v1 or v2 bindings; existing identities must be rebound and
+republished.
 
 ## Real-world use cases
 
@@ -13,9 +14,9 @@ do not accept v1 bindings; existing identities must be rebound and republished.
 
 **Nostr client** — call `verifyIdentity` when rendering a profile to show a cryptographically-proven "verified BCH address" badge. No issuing authority — the proof is in the signature.
 
-**Merchant checkout** — call `resolveByNip05('alice@shop.com')` at payment time to resolve the current NIP-05 pubkey and its verified binding. Cross-key rotation continuity is not established by this library, so merchants must update their NIP-05 record and clients must not assume a new key is authorized by the old one.
+**Merchant checkout** — call `resolveByNip05('alice@shop.com')` at payment time to resolve the current NIP-05 pubkey and its verified binding. The v3 resolver checks old-key authorization when following a cross-key rotation.
 
-**Passwordless login** — use `verifyHttpAuth` in a server with a NIP-07 signer. The server verifies the signed Nostr request and can optionally resolve the signer's BCH binding; it still needs application-specific authorization and replay policy.
+**Passwordless login** — issue a server-side one-time challenge, collect BCH and Nostr signatures, and verify them with `verifyDualChallengeProof`. The application must atomically consume challenges and apply its own authorization policy. `verifyHttpAuth` remains available for NIP-98 requests.
 
 ## Install
 
@@ -110,35 +111,53 @@ const social = deriveNostrKeypair(mnemonic, 1)
 ### Challenge-response authentication
 
 ```ts
-import { bchChallengePayload, signBchMessage, verifyChallengeProof } from 'did-beta-bch'
+import {
+  bchChallengePayload, nostrChallengeTemplate, verifyDualChallengeProof,
+} from 'did-beta-bch'
 
 const payload = bchChallengePayload(nonce, audience)
-const signature = await signBchMessage(walletSigner, payload)
-// issuedAt enforces 5-minute TTL
-const valid = verifyChallengeProof(
-  { signature, payload, address },
-  nonce,
-  audience,
-  issuedAt, // unix seconds — optional, rejects if > 5 min old
+const nostrTemplate = nostrChallengeTemplate(
+  nonce, audience, 'https://app.example/api/auth/verify', issuedAt,
+)
+// Collect the BCH signature over `payload` and Nostr signature over `nostrTemplate`.
+const valid = verifyDualChallengeProof(
+  { signature, payload, address, nostrEvent },
+  {
+    nonce,
+    audience,
+    endpoint: 'https://app.example/api/auth/verify',
+    issuedAt,
+    address,
+    pubkey,
+  },
 )
 ```
 
+Challenge issuance and one-time consumption belong on a server with durable,
+atomic storage. Do not treat browser-only challenge state as authentication.
+
 ### Key rotation
 
 ```ts
-import { buildBinding, resolveIdentityChain } from 'did-beta-bch'
+import {
+  buildBinding, rotationAuthorizationTemplate, nostrEventTemplate,
+  resolveIdentityChain,
+} from 'did-beta-bch'
 
-// Rotate: reference the old binding
+// For a changed Nostr key, have the old key sign this authorization event.
 const newBinding = await buildBinding(newAddress, 'mainnet', newNostrPub, undefined, oldBindingId)
+const authorizationTemplate = rotationAuthorizationTemplate(oldBinding, newBinding)
+const oldKeyAuthorization = finalizeEvent(authorizationTemplate, oldNostrPrivkey)
+// Publish the successor with its BCH proof and the old-key authorization.
+const successorTemplate = nostrEventTemplate(newBinding, bchProof, oldKeyAuthorization)
 
 // Resolve linked, individually verified binding events, newest first
 const chain = await resolveIdentityChain('npub1...')
 ```
 
-The resolver verifies each event and requires every `supersedes` target to be
-present, unrevoked, and valid. A reference signed only by the new key does not
-prove that the previous Nostr key authorized the rotation; do not treat this
-chain alone as proof of cross-key continuity.
+For cross-key rotation, the resolver verifies the old-key authorization and
+requires every `supersedes` target to be present, unrevoked, and valid. Lost-key
+recovery is not supported.
 
 ### Verifiable credentials + reputation
 
@@ -178,16 +197,52 @@ commitments or attach them to a binding event automatically.
 ### BCH-anchored identity commitment
 
 ```ts
-import { buildAnchorTx } from 'did-beta-bch'
+import {
+  buildAnchorTx, verifyBchAnchorProof,
+  BCH_MAINNET_CHECKPOINT, BCH_MAINNET_ASERT_PARAMETERS,
+  BCH_CHIPNET_CHECKPOINT, BCH_CHIPNET_ASERT_PARAMETERS,
+  broadcastAnchorTx, fetchAnchorProof, wsTransport,
+  ELECTRUM_MAINNET_WS,
+} from 'did-beta-bch'
 
-// Embed bindingId in an OP_RETURN transaction for on-chain commitment
+// Build and broadcast
 const { txHex } = await buildAnchorTx(bindingId, { txid, vout, valueSats, lockingBytecode, privateKey })
+const transport = wsTransport(ELECTRUM_MAINNET_WS)
+const txid = await broadcastAnchorTx(txHex, transport)
+
+// Fetch proof and verify (after confirmation)
+const proof = await fetchAnchorProof(txid, BCH_MAINNET_CHECKPOINT.height, wsTransport(ELECTRUM_MAINNET_WS))
+const result = verifyBchAnchorProof(proof, bindingId, {
+  checkpoint: BCH_MAINNET_CHECKPOINT,
+  asert: BCH_MAINNET_ASERT_PARAMETERS,
+  minConfirmations: 6,
+})
+```
+
+`wsTransport` works in both browser and Node.js (Node 22+ has native WebSocket). For Node < 22 or TCP, implement the three-method `ElectrumTransport` interface.
+
+Chipnet uses `BCH_CHIPNET_CHECKPOINT` and `BCH_CHIPNET_ASERT_PARAMETERS`. Note chipnet is a test network that may reset; the checkpoint is valid for the current chain instance only.
+
+### BIP47 payment code address derivation
+
+```ts
+import { parsePaymentCode, derivePaymentAddress } from 'did-beta-bch'
+import { deriveHdPrivateNodeFromBip39Mnemonic, deriveHdPath, deriveHdPublicNode } from '@bitauth/libauth'
+
+// Decode a recipient's payment code
+const { publicKey, chainCode } = parsePaymentCode('PM8T...')
+
+// Derive the recipient's HD public node from their payment code
+// (or supply it directly if you have it from your own derivation)
+const recipientNode = deriveHdPublicNode(deriveHdPath(recipientRoot, "m/47'/0'/0'"))
+
+// Sender: derive the nth payment address to send to
+const senderScanPrivkey = deriveHdPath(senderRoot, "m/47'/0'/0'/0").privateKey
+const address = await derivePaymentAddress(senderScanPrivkey, recipientNode, 0)
+wallet.sendTo(address, amount)
 ```
 
-This builds transaction hex from the supplied UTXO; it
-does not broadcast the transaction or verify its confirmation. A `bch-anchor`
-tag is only a claim until an application independently verifies the transaction
-and its block inclusion.
+`derivePaymentAddress` implements BIP47 v1 ECDH address derivation. Notification transactions and spending-side key derivation are wallet-specific and out of scope for this library.
 
 ### NIP-05 handle resolution
 
@@ -246,17 +301,15 @@ Bindings are published as Nostr events of kind `30078` (NIP-78 addressable data)
 | `supersedes` | previous binding ID (key rotation) |
 | `t` | `cashlet-did` |
 
-The wallet receives the exact UTF-8 v2 message text and applies the Bitcoin
+The wallet receives the exact UTF-8 v3 message text and applies the Bitcoin
 Signed Message prefix, CompactSize byte length, and double-SHA256. Its response
 is standard padded Base64 for a 65-byte compact signature: header 31–34
-(compressed key plus recovery ID 0–3), followed by 64-byte `r || s`. V2
-verifiers strictly reject v1 hex/raw signature encodings. Revocation uses
+(compressed key plus recovery ID 0–3), followed by 64-byte `r || s`. V3
+verifiers strictly reject v1/v2 and hex/raw signature encodings. Revocation uses
 NIP-09 kind `5` deletion events.
 
 The local demo previews and verifies a binding but does **not** publish or query
-Nostr relays. Its separate HTTP verifier demo demonstrates challenge issue,
-verification, and replay rejection locally; `/resolve` needs a published
-binding and relay access.
+Nostr relays; `/resolve` needs a published binding and relay access.
 
 ## Relays
 

package/dist/anchor-client.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Electrum client helpers for broadcasting anchor transactions and fetching
+ * SPV proofs. Works in Node.js (TCP) and browsers (WebSocket) via a pluggable
+ * transport. Default transports are provided for each environment.
+ */
+import type { BchAnchorProof } from "./anchor-verification.js";
+export declare const ELECTRUM_MAINNET_TCP = "electroncash.dk:50001";
+export declare const ELECTRUM_MAINNET_WS = "wss://electroncash.dk:50004";
+export declare const ELECTRUM_CHIPNET_TCP = "chipnet.imaginary.cash:50001";
+export declare const ELECTRUM_CHIPNET_WS = "wss://chipnet.imaginary.cash:50004";
+/** Minimal transport interface — send lines, receive lines. */
+export interface ElectrumTransport {
+    send(line: string): void;
+    onLine(handler: (line: string) => void): void;
+    onError(handler: (err: Error) => void): void;
+    close(): void;
+}
+/** WebSocket transport — works in both browser and Node.js (Node 22+ has native WebSocket). */
+export declare function wsTransport(url: string): ElectrumTransport;
+/**
+ * Broadcast a signed anchor transaction hex to an Electrum server.
+ * Returns the txid on success.
+ */
+export declare function broadcastAnchorTx(txHex: string, transport: ElectrumTransport): Promise<string>;
+/**
+ * Fetch a BchAnchorProof for a confirmed transaction.
+ * checkpointHeight must match the checkpoint you intend to verify against —
+ * headers are fetched from checkpointHeight+1 through the confirmation window.
+ */
+export declare function fetchAnchorProof(txid: string, checkpointHeight: number, transport: ElectrumTransport, minConfirmations?: number): Promise<BchAnchorProof>;