did-beta-bch 1.3.0 → 2.0.1

package/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 All notable changes to `cashlet-did` will be documented here.
 
+## [2.0.0] — 2026-11-03
+
+### Breaking
+- V2 is the only supported binding protocol; v1 bindings and raw/hex proof signatures are no longer verified.
+- BCH proof tags now use `["bch-proof", "bitcoin-message/compact-base64", message, signatureBase64]`.
+- Wallet signatures must be standard padded Base64 for a 65-byte Bitcoin compact-message signature with compressed-key header 31–34.
+- Binding purpose and BCH proof domain are versioned to `identity-binding-v2` and `cashlet-did/bch-proof/v2.0.0`.
+- Challenge payloads are versioned as `cashlet-did/challenge/v2.0.0\n<nonce>[\n<audience>]`.
+- `nostrEventTemplate` accepts `{ message, signatureBase64 }` and sets event `created_at` to the binding timestamp.
+
+### Added
+- `BCH_PROOF_FORMAT`, `BchMessageSigner`, `normalizeBchMessageSignature`, and `signBchMessage` provide strict transport-independent signing validation.
+- `bchChallengePayload(nonce, audience?)` constructs the exact challenge text expected by `verifyChallengeProof`.
+- Verifier now binds v2 content, proof, tags, event time, Nostr key/npub, BCH address, network, and binding ID; resolution skips v1 events.
+
 ## [1.2.0] — 2026-07-31
 
 ### Fixed
@@ -28,7 +43,7 @@ All notable changes to `cashlet-did` will be documented here.
 
 ### Added
 - `buildAnchorTx(bindingId, utxo)` — build an OP_RETURN BCH transaction anchoring a binding to the chain
-- `issueCredential(subjectNpub, type, issuerPrivkey)` — issue a third-party Nostr attestation (kind 30079)
+- `issueCredential(subjectNpub, type, issuerPrivkey)` — issue a third-party Nostr attestation (kind 30085)
 - `resolveCredentials(npub)` — fetch all credentials issued to an npub from relays
 - `buildDisclosure(attrs)` — commit to a set of attributes with individual SHA-256 hashes
 - `verifyDisclosure(revealed, commitments)` — verify selectively revealed attributes against commitments

package/PROTOCOL.md

@@ -1,11 +1,11 @@
 # Cashlet DID Protocol Specification
 
-Version: `1.0.0`  
+Version: `2.0.0`
 Status: Draft
 
-This document is the normative protocol specification. Any BCH wallet or Nostr
-client can implement compatibility by following this spec — no dependency on the
-`cashlet-did` library is required.
+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.
 
 ---
 
@@ -14,201 +14,231 @@ client can implement compatibility by following this spec — no dependency on t
 | Constant | Value |
 |---|---|
 | Protocol ID | `cashlet-did` |
-| Protocol version | `1.0.0` |
+| Protocol version | `2.0.0` |
 | Binding event kind | `30078` (NIP-78 addressable data) |
 | Credential event kind | `30085` |
 | Revocation event kind | `5` (NIP-09) |
 | Nostr derivation path | `m/44'/1237'/<account>'/0/0` (NIP-06) |
 
----
-
 ## 2. Canonical binding record
 
-A binding record is a JSON object with **sorted keys** (no whitespace) used as
-the input to the binding ID hash. Undefined/absent fields are omitted.
+A binding record has recursively sorted object keys, no whitespace, and omits
+undefined/absent fields:
 
 ```json
 {
   "bch": {
-    "address": "<cashaddr>",
+    "address": "<prefixed-cashaddr>",
     "network": "mainnet" | "testnet" | "chipnet",
     "paymentCode": "<BIP47 payment code>"   // optional
   },
   "createdAt": <unix seconds>,
-  "nostr": { "pubkey": "<32-byte hex>" },
-  "nonce": "<64 hex chars of random bytes>",
-  "previousBindingId": "<hex>",             // optional, key rotation
+  "nostr": { "pubkey": "<32-byte lowercase hex>" },
+  "nonce": "<64 lowercase hex chars>",
+  "previousBindingId": "<64 lowercase hex chars>", // optional
   "protocol": "cashlet-did",
-  "purpose": "identity-binding-v1",
-  "version": "1.0.0"
+  "purpose": "identity-binding-v2",
+  "version": "2.0.0"
 }
 ```
 
-**Binding ID** = `SHA-256(canonicalize(record_without_bindingId))` as lowercase hex.
+**Binding ID** = lowercase hex `SHA-256(canonicalize(record_without_bindingId))`.
+Arrays preserve order. `mainnet` addresses use the `bitcoincash:` prefix;
+`testnet` and `chipnet` use `bchtest:`.
 
-`canonicalize` means: recursively sort object keys alphabetically, no spaces,
-omit keys whose value is `undefined`. Arrays preserve order.
+## 3. BCH signing payload and wallet contract
 
----
+The exact UTF-8 message text supplied to a wallet is:
 
-## 3. BCH signing payload
-
-```
-cashlet-did/bch-proof/v1.0.0\n<canonicalized subset>
+```text
+cashlet-did/bch-proof/v2.0.0\n<canonicalized subset>
 ```
 
-The canonicalized subset contains exactly these keys (sorted):
+The subset contains exactly these keys:
 
 ```json
 {
-  "bchAddress": "<cashaddr>",
+  "bchAddress": "<prefixed-cashaddr>",
   "bchNetwork": "mainnet" | "testnet" | "chipnet",
-  "bindingId": "<hex>",
+  "bindingId": "<64 lowercase hex chars>",
   "createdAt": <unix seconds>,
-  "nonce": "<hex>",
-  "nostrPubkey": "<hex>",
-  "purpose": "identity-binding-v1"
+  "nonce": "<64 lowercase hex chars>",
+  "nostrPubkey": "<32-byte lowercase hex>",
+  "purpose": "identity-binding-v2"
 }
 ```
 
-### BCH signature format
+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
+wallet computes:
 
-Bitcoin signed message format:
-
-```
-SHA256d( "\x18Bitcoin Signed Message:\n" + varint(len(payload_bytes)) + payload_bytes )
+```text
+SHA256d(0x18 || "Bitcoin Signed Message:\n" ||
+       CompactSize(UTF8(message).length) || UTF8(message))
 ```
 
-`varint` is Bitcoin compact-size encoding:
-- `n < 0xfd` → 1 byte `[n]`
-- `0xfd ≤ n ≤ 0xffff` → 3 bytes `[0xfd, n & 0xff, n >> 8]`
+`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 signature is a **65-byte recoverable compact signature**:
-`[recovery_id_byte (0–3)] + [64-byte compact sig]`, hex-encoded.
+The wallet response is standard padded Base64 encoding of exactly 65 bytes:
 
-> ⚠️ Signing payloads are typically ~400 bytes. A single-byte length prefix
-> (truncating to `n & 0xff`) is **wrong** and will produce unverifiable signatures.
+```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:
+
 ```json
-{
-  "kind": 30078,
-  "pubkey": "<nostr pubkey hex>",
-  "created_at": <unix seconds>,
-  "tags": [
-    ["d",              "<bindingId>"],
-    ["bch",            "<cashaddr>", "<network>"],
-    ["bch-proof",      "<signing payload>", "<65-byte sig hex>"],
-    ["protocol",       "cashlet-did", "1.0.0"],
-    ["t",              "cashlet-did"],
-    ["bch-payment-code", "<BIP47 code>"],   // optional
-    ["supersedes",     "<previous bindingId>"],  // optional, key rotation
-    ["bch-anchor",     "<txid>", "<block timestamp unix>"]  // optional
-  ],
-  "content": "<canonicalized binding JSON>",
-  "id": "<NIP-01 event id>",
-  "sig": "<Schnorr sig>"
-}
+[
+  ["d", "<bindingId>"],
+  ["bch", "<cashaddr>", "<network>"],
+  ["protocol", "cashlet-did", "2.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
+```
+
+`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.
+
+## 5. Discovery and revocation
 
-## 5. Discovery (NIP-01 filter)
+Discover v2 records with this NIP-01 filter:
 
 ```json
 { "kinds": [30078], "authors": ["<pubkey hex>"], "#t": ["cashlet-did"] }
 ```
 
-Query any public Nostr relay. Default relays: `wss://nos.lol`,
-`wss://relay.damus.io`, `wss://relay.nostr.band`.
-
 Revocations are kind `5` events from the same author with `["e", "<event id>"]`
-tags. Filter revoked events before selecting the latest binding.
-
----
+tags. Filter revoked records before selecting the newest v2 binding.
 
 ## 6. Verification algorithm
 
-1. Fetch binding event(s) via NIP-01 filter above.
-2. Fetch kind `5` revocations from the same author; discard revoked events.
-3. Select the event with the highest `created_at` among non-revoked results.
-4. Verify the **Nostr event signature** (NIP-01 Schnorr).
-5. Reconstruct the signing payload from the `bch-proof` tag (index 1).
-6. Compute `SHA256d` of the Bitcoin signed message over that payload (§3).
-7. Recover the BCH public key from the 65-byte signature + hash.
-8. Derive the P2PKH address from the recovered key; compare to the `bch` tag.
-9. Status is `verified` iff both signatures are valid.
-
----
+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.
+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.
 
 ## 7. Challenge-response authentication
 
-Payload format:
+The exact v2 message is either:
 
-```
-cashlet-did/challenge\n<nonce>\n<audience>
+```text
+cashlet-did/challenge/v2.0.0\n<nonce>
 ```
 
-- `nonce`: random hex string issued by the verifier
-- `audience`: verifier's URL or identifier (optional but recommended)
+or, with an audience:
 
-The wallet signs this payload using the same Bitcoin signed message format (§3).
-The verifier recovers the BCH address and checks it matches the binding.
+```text
+cashlet-did/challenge/v2.0.0\n<nonce>\n<audience>
+```
 
-Implementations **should** enforce a 5-minute TTL on issued challenges.
-
----
+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
 
-Set `previousBindingId` in the new binding record and add a
-`["supersedes", "<previousBindingId>"]` tag to the Nostr event.
-
-Resolvers can reconstruct the full rotation chain by following `supersedes` tags
-backwards. The newest non-revoked binding is the authoritative identity.
-
----
+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.
 
 ## 9. Selective disclosure
 
-Each attribute is committed as:
+The library's selective-disclosure helper commits each attribute using an
+independent random 32-byte salt:
 
-```
-SHA-256( "cashlet-did/attr/<key>:<value>" )
+```text
+SHA-256("cashlet-did/attr/v2\n" + JSON([key, value, salt]))
 ```
 
-Commitments are published in the binding (e.g. as extra tags or in content).
-To verify a revealed attribute, recompute the hash and compare to the commitment.
-
----
+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.
 
 ## 10. On-chain commitment (OP_RETURN)
 
 Embed the binding ID in a BCH transaction output:
 
-```
+```text
 OP_RETURN <"cashlet-did:" + bindingId>
 ```
 
-The confirmed block's `time` field provides a consensus-enforced timestamp
-accurate to ~1 block (~10 minutes). It cannot be significantly backdated
-(median-time-past rule) and can drift at most 2 hours forward (miner clock
-skew allowance). Prefer `anchoredAt` over the self-reported `createdAt`.
-
----
+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.
 
 ## 11. NIP-05 handle resolution
 
-`user@domain` → `GET https://domain/.well-known/nostr.json?name=user`  
-→ extract `pubkey` → resolve binding via §5.
-
----
+`user@domain` → `GET https://domain/.well-known/nostr.json?name=user` →
+extract `pubkey` → resolve the v2 binding via §5.
 
 ## 12. NIP-98 HTTP Auth
 
 Build a kind `27235` event per NIP-98. The `verifyBch: true` option on the
-server additionally resolves the signer's cashlet-did binding, proving BCH
-address ownership in the same request.
+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.
+
+## 13. Credentials
+
+Credential events use kind `30085`. A resolver must verify the Nostr event
+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.

package/README.md

@@ -4,15 +4,18 @@ 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.
+
 ## Real-world use cases
 
 **BCH wallet** — call `buildBinding` + `publishToRelays` once when a user sets up their identity. Anyone can then pay them by Nostr handle (`resolveAddress('npub1...')`) instead of exchanging addresses. Users never see the protocol.
 
 **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. No QR codes, no address copy-paste. When the merchant rotates keys, all payers automatically resolve the new address.
+**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.
 
-**Passwordless login** — drop `verifyHttpAuth` into any web server. A NIP-07 browser extension (Alby, nos2x) signs the request transparently. The server gets a verified Nostr pubkey + BCH address — no OAuth, no email, no password database.
+**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.
 
 ## Install
 
@@ -28,8 +31,8 @@ npm install did-beta-bch
 import { resolveAddress } from 'did-beta-bch'
 
 const address = await resolveAddress('npub1...')
-// Returns a token-aware bitcoincash:z... address
-// Works for BCH, CashTokens (FT), and NFTs — no conversion needed
+// Returns the BCH address published in the verified binding, or null
+// Token support depends on the bound address and the wallet's payment flow
 if (address) wallet.sendTo(address, amount)
 ```
 
@@ -42,26 +45,58 @@ const identity = await resolveIdentity('npub1...')
 if (identity) {
   const result = await verifyIdentity(identity)
   console.log(result.status) // "verified"
-  console.log(identity.bchAddress) // bitcoincash:z...
+  console.log(identity.bchAddress) // bound BCH address
 }
 ```
 
 ### Build and publish a binding (wallet integration)
 
 ```ts
-import { buildBinding, bchSigningPayload, nostrEventTemplate, publishToRelays, DEFAULT_RELAYS } from 'did-beta-bch'
+import {
+  buildBinding, bchSigningPayload, signBchMessage, nostrEventTemplate,
+  publishToRelays, DEFAULT_RELAYS,
+} from 'did-beta-bch'
 import { finalizeEvent } from 'nostr-tools'
 
 const binding = await buildBinding(bchAddress, 'mainnet', nostrPubkeyHex)
 const message = bchSigningPayload(binding)
 
-// Sign with BCH private key (recoverable compact sig)
-const bchSig = signWithBchKey(message) // your wallet's signing function
+// Pass the exact text to a transport adapter; do not pre-hash or add a prefix.
+const signatureBase64 = await signBchMessage(walletSigner, message)
 
-const event = finalizeEvent(nostrEventTemplate(binding, { message, signature: bchSig }), nostrPrivkey)
+const event = finalizeEvent(
+  nostrEventTemplate(binding, { message, signatureBase64 }),
+  nostrPrivkey,
+)
 await publishToRelays(DEFAULT_RELAYS, event)
 ```
 
+`BchMessageSigner` is transport-neutral:
+
+```ts
+const walletSigner = {
+  signMessage: (message: string) => walletAdapter.signMessage({ message }),
+}
+```
+
+`signBchMessage` passes the exact string to `signMessage` and strictly validates
+the standard 65-byte Bitcoin compact-message signature returned as Base64.
+The response must use a compressed-key header byte from 31 through 34. Paytaca's
+published WalletConnect implementation and the BCH WalletConnect BCR match this
+contract; test each wallet version you integrate. The library does not import
+WalletConnect or WizardConnect and does not provide their transport adapters.
+For WalletConnect, the adapter maps this call to `bch_signMessage` with the
+message in its params. WizardConnect needs a separate wallet-side signing action
+and adapter; neither is implemented in this package.
+
+The signer is supplied by the integrating wallet, so this library does not
+require users to connect to Selene, Paytaca, or any other external wallet. A
+wallet can pass its own non-custodial BCH signer directly. For example, Cashlet
+uses its own BCH keys by default; its optional WalletConnect adapter is only for
+users who choose to bind an address held by another compatible wallet. In either
+case, the BCH key signs the proof while a separate Nostr key signs the published
+event.
+
 ### Key derivation (NIP-06)
 
 ```ts
@@ -75,9 +110,10 @@ const social = deriveNostrKeypair(mnemonic, 1)
 ### Challenge-response authentication
 
 ```ts
-import { verifyChallengeProof } from 'did-beta-bch'
+import { bchChallengePayload, signBchMessage, verifyChallengeProof } from 'did-beta-bch'
 
-// Payload format: `cashlet-did/challenge\n<nonce>\n<audience>`
+const payload = bchChallengePayload(nonce, audience)
+const signature = await signBchMessage(walletSigner, payload)
 // issuedAt enforces 5-minute TTL
 const valid = verifyChallengeProof(
   { signature, payload, address },
@@ -95,10 +131,15 @@ import { buildBinding, resolveIdentityChain } from 'did-beta-bch'
 // Rotate: reference the old binding
 const newBinding = await buildBinding(newAddress, 'mainnet', newNostrPub, undefined, oldBindingId)
 
-// Resolve full rotation history, newest first
+// 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.
+
 ### Verifiable credentials + reputation
 
 ```ts
@@ -112,19 +153,28 @@ const creds = await resolveCredentials('npub1...')
 const score = await scoreReputation('npub1...')
 ```
 
+`resolveCredentials` verifies the issuer's Nostr event signature, the subject
+and credential tags, and any expiry. Applications must still decide which
+issuers and credential types they trust; `scoreReputation` is a heuristic, not
+an objective or Sybil-resistant trust measure.
+
 ### Selective disclosure
 
 ```ts
 import { buildDisclosure, verifyDisclosure } from 'did-beta-bch'
 
-// Commit to attributes — publish commitments in binding
+// Commit to attributes; store commitments with the identity record separately
 const d = await buildDisclosure({ merchant: 'true', country: 'AU', kyc: 'passed' })
 
-// Later: reveal only what's needed
+// Later: reveal selected values and their salts; hidden salts stay private
 const revealed = d.reveal(['merchant'])
 const { verified, failed } = await verifyDisclosure(revealed, d.commitments)
 ```
 
+Commitments use random per-attribute salts to prevent offline guessing of
+low-entropy values until those values are revealed. This helper does not publish
+commitments or attach them to a binding event automatically.
+
 ### BCH-anchored identity commitment
 
 ```ts
@@ -134,6 +184,11 @@ import { buildAnchorTx } from 'did-beta-bch'
 const { txHex } = await buildAnchorTx(bindingId, { txid, vout, valueSats, lockingBytecode, privateKey })
 ```
 
+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.
+
 ### NIP-05 handle resolution
 
 ```ts
@@ -148,16 +203,15 @@ if (address) wallet.sendTo(address, amount)
 
 ```ts
 import { buildHttpAuthEventAsync, verifyHttpAuth } from 'did-beta-bch'
-import { finalizeEvent } from 'nostr-tools'
 
 // Client: build + sign auth event
 const template = await buildHttpAuthEventAsync('https://api.example.com/me', 'GET')
-const event = finalizeEvent(template, nostrPrivkey)
+const event = await window.nostr.signEvent(template) // NIP-07 browser extension
 const header = 'Nostr ' + btoa(JSON.stringify(event))
 // → send as Authorization header
 
 // Server: verify — proves Nostr identity + optionally BCH address ownership
-const result = await verifyHttpAuth(header, 'https://api.example.com/me', 'GET', { verifyBch: true })
+const result = await verifyHttpAuth(header, 'https://api.example.com/me', 'GET', { body: null, verifyBch: true })
 if (result.valid) {
   console.log(result.pubkey)     // verified Nostr pubkey
   console.log(result.bchAddress) // verified BCH address (if verifyBch: true)
@@ -186,13 +240,23 @@ Bindings are published as Nostr events of kind `30078` (NIP-78 addressable data)
 |---|---|
 | `d` | binding ID (SHA-256 of canonical binding JSON) |
 | `bch` | BCH address, network |
-| `bch-proof` | signing payload, 65-byte recoverable compact signature |
-| `bch-payment-code` | BIP47 payment code (optional, enables fresh address per payment) |
+| `bch-proof` | `["bch-proof", "bitcoin-message/compact-base64", message, signatureBase64]` |
+| `bch-payment-code` | Optional BIP47 payment-code metadata; this library does not derive fresh addresses |
 | `protocol` | `cashlet-did`, version |
 | `supersedes` | previous binding ID (key rotation) |
 | `t` | `cashlet-did` |
 
-The BCH signature uses Bitcoin signed message format (`\x18Bitcoin Signed Message:\n`) with a 65-byte recoverable compact signature (recovery ID byte + 64-byte compact sig). Revocation uses NIP-09 kind `5` deletion events.
+The wallet receives the exact UTF-8 v2 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
+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.
 
 ## Relays
 

package/dist/anchor.d.ts

@@ -1,6 +1,6 @@
 /**
  * BCH on-chain identity commitment via OP_RETURN.
- * Anchors a bindingId to a BCH block, providing a tamper-evident timestamp.
+ * Builds a transaction committing to a bindingId; it does not broadcast or verify confirmation.
  */
 export declare const ANCHOR_PREFIX = "cashlet-did:";
 export interface AnchorUtxo {