@smartledger/bsv 8.2.0 → 8.3.1

package/docs/AUDIT_SCOPE.md

@@ -5,7 +5,7 @@ cryptographic core, and carries the enquiry text to send to vendors. It exists s
 every vendor prices the *same* thing, and so that the reasoning behind the scope
 boundary survives past the engagement that prompted it.
 
-Measured against **v8.2.0**, 2026-08-15. Re-measure before sending if the version has
+Measured against **v8.3.0**, 2026-08-16. Re-measure before sending if the version has
 moved (`docs/AUDIT_SCOPE.md` is not covered by a drift gate).
 
 ## 1. The question we are asking
@@ -58,16 +58,16 @@ is not.
 | Component | Status | Reason |
 | --- | --- | --- |
 | `@noble/curves`, `@noble/hashes`, `@noble/ciphers` | Already audited | The primitives come from the Noble libraries, which **Cure53 has audited and published on**. We do not implement curve or hash arithmetic ourselves. State this explicitly to vendors — otherwise they price work we do not need. |
-| `lib/smart_contract/`, `lib/ltp/`, `lib/gdaf/`, `lib/ordinals/`, `lib/block/`, plus 9 further directories and 6 top-level files | Excluded | Application layer, 23,016 lines — 18,636 in the five named modules and 4,380 in the remainder. Written in-house and covered by adversarial tests. Worth a separate engagement; including it here would blur the question in §1. |
+| `lib/smart_contract/`, `lib/ltp/`, `lib/gdaf/`, `lib/ordinals/`, `lib/block/`, plus 9 further directories and 6 top-level files | Excluded | Application layer, 24,447 lines — 18,600 in the five named modules and 5,847 in the remainder. Written in-house and covered by adversarial tests. Worth a separate engagement; including it here would blur the question in §1. |
 
-Totals reconcile against `lib/`, which is 36,891 lines across 123 files:
+Totals reconcile against `lib/`, which is 38,322 lines across 130 files:
 
 ```
 tier 1      12,268
 tier 2       1,607
-excluded    23,016
+excluded    24,447
             ------
-total       36,891
+total       38,322
 ```
 
 Core + optional = 13,875.
@@ -94,7 +94,7 @@ Each of these should *reduce* the quote — they remove discovery work.
 - **`npm run conformance`** — 452 cases across 13 suites, freezing observable behaviour
   so any change surfaces as a diff. A second, independently written implementation
   (`smartledger-bsv-core`, the TypeScript port) agrees on all 452.
-- **4,503 passing tests**, plus a reproducible-bundle gate, a require-cycle gate, and a
+- **4,626 passing tests**, plus a reproducible-bundle gate, a require-cycle gate, and a
   type-drift gate that parses the published types against the runtime.
 - **`SECURITY.md`** — a published advisory (GHSA-gw63-x79h-mhjc) and a changelog of
   security fixes with the reasoning for each.
@@ -143,7 +143,7 @@ Scope, and we would like these priced separately:
 JavaScript (CommonJS), Node >= 20.19. The code is public.
 
 Explicitly out of scope: elliptic-curve and hash primitives, which are supplied
-by the Noble libraries and already audited; and our 23,016-line application
+by the Noble libraries and already audited; and our 24,447-line application
 layer (credentials, tokens, ordinals), which we would treat as a separate
 engagement.
 
@@ -171,7 +171,7 @@ SmartLedger Technology
 Every figure in this document, including the excluded total, must come out of this
 script. **Derive the excluded count as the complement — never by subtracting tier 1
 alone.** The first draft did exactly that, double-counted tier 2, and published parts
-summing to 37,430 against a 36,891 whole; §7 could not catch it because it reproduced
+summing to 37,430 against a 38,322 whole; §7 could not catch it because it reproduced
 every figure except the wrong one.
 
 ```sh

package/docs/BRC220_BATCH_LEAF_AMENDMENT.md

@@ -0,0 +1,119 @@
+# Proposed BRC-220 amendment: define the batch Merkle leaf
+
+§On-chain record specifies *which* Merkle tree batch mode uses, but never says what goes
+in a leaf. This proposes the definition, with the reasoning that led to it.
+
+Prepared 2026-08-17 while implementing BRC-220 in `@smartledger/bsv`. The second gap of
+this kind, after `encoding` — see [BRC220_ENCODING_AMENDMENT.md](BRC220_ENCODING_AMENDMENT.md).
+
+---
+
+## What the spec currently says
+
+§On-chain record, batch (`kind = 2`):
+
+> One transaction anchors many proofs under an RFC 6962 Merkle root, domain-separated
+> (`leaf = SHA256(0x00 ‖ d)`, `node = SHA256(0x01 ‖ l ‖ r)`, split at the largest power of
+> two `< n`, last leaf never duplicated).
+
+That parenthetical identifies the **tree construction**: domain separation, the split
+rule, and the no-duplication rule that separate RFC 6962 from Bitcoin's tree. `d`, `l` and
+`r` are RFC 6962's own generic symbols — §2.1 of that RFC writes
+`MTH({d(0)}) = SHA-256(0x00 || d(0))` — so the sentence is naming the tree, not defining
+its contents.
+
+**`d` is never bound to a value.** The word `canonicalBytes` occurs once in the entire
+document, in the `proofHash` definition in §Canonical proof bytes; it does not appear in
+the batch text. Neither does `proofHash`.
+
+So this is an ambiguity, not a disagreement between spec and implementation. Two
+good-faith implementers reading the same sentence can and did reach different answers:
+
+| reading | leaf hash |
+| --- | --- |
+| `d` = the canonical proof bytes | `SHA-256(0x00 ‖ canonicalBytes)` |
+| `d` = the proof's identifier | `SHA-256(0x00 ‖ proofHash)` = `SHA-256(0x00 ‖ SHA-256(canonicalBytes))` |
+
+Both are second-preimage resistant, and the domain separation that gives RFC 6962 that
+property is unaffected by which one is chosen. **They are equal in strength and produce
+different roots.** A certificate built under one reading fails inclusion under the other,
+with no error that points at the cause — the fold simply does not reach the root.
+
+The published test vectors do not settle it: they cover a certificate-with-SPV-envelope
+golden vector, `txidFromRawTx` against the Bitcoin genesis coinbase, and the SPV Merkle
+fold against block 170. **None of them is a batch-mode vector**, so there is nothing to
+conform to by example.
+
+---
+
+## Proposed text
+
+Insert into **§On-chain record**, replacing the batch bullet's parenthetical.
+
+> - **batch** (`kind = 2`): `"NOTARYHASH" | u8(1) | u8(2) | merkleRoot(32) | u32be(leafCount)`.
+>   One transaction anchors many proofs under an RFC 6962 Merkle root.
+>
+>   The leaf datum `d` for a proof is its **`proofHash`** — the 32 bytes defined in
+>   §Canonical proof bytes — so a leaf is `SHA-256(0x00 ‖ proofHash)` and an internal node
+>   is `SHA-256(0x01 ‖ l ‖ r)`. Leaves are ordered as the batch was assembled, and
+>   `leafIndex` in the certificate's `merkle` object is that position. The tree splits at
+>   the largest power of two `< n` and the last leaf is never duplicated, per RFC 6962
+>   §2.1.
+>
+>   Note that `d` is the **hash**, not the canonical bytes: a leaf is therefore
+>   `SHA-256(0x00 ‖ SHA-256(canonicalBytes))`. The two readings are equally sound
+>   cryptographically but produce different roots, so this is stated explicitly rather
+>   than left to RFC 6962's generic `d`.
+
+---
+
+## Why `proofHash` rather than the canonical bytes
+
+Both are sound. The choice is on other grounds.
+
+**A verifier already holds it.** `proofHash` is a required certificate field. A verifier
+checking batch inclusion reads it directly and folds. Under the other reading it must
+first reconstruct `canonicalBytes` — re-serialising `publicKey`, `signature`,
+`createdAtUnix` and the rest with the exact length-prefix framing — before it can begin.
+That is the whole `proofHash` computation, performed again, as a precondition for a check
+that is supposed to be independent of it. The spec advertises a "dependency-light
+standalone verifier"; this keeps the batch path genuinely light.
+
+**It is what a batch anchors.** §On-chain record says a batch transaction "anchors many
+proofs". `proofHash` *is* the proof's identity — it is the integrity root, the value the
+full and hybrid records place on-chain, and the value §Verification checks a certificate
+against. Batching identifiers rather than re-serialised bodies keeps batch mode
+consistent with the other two modes rather than introducing a second notion of what
+represents a proof.
+
+**It matches the mode it exists alongside.** Hybrid mode already establishes that BRC-220
+puts hashes on-chain where blobs would be large. Fixed 32-byte leaves keep batch memory
+and proof sizes independent of signature scheme — which matters precisely for the
+post-quantum algorithms §Motivation names, where `canonicalBytes` runs to kilobytes per
+proof.
+
+**The extra hash costs nothing.** One SHA-256 over 32 bytes per leaf, against a
+re-serialisation per leaf under the alternative.
+
+---
+
+## Compatibility
+
+`@smartledger/bsv` implements the `proofHash` reading as of 8.3.0, and from this change
+states it in `lib/notaryhash/index.js` and enforces it in
+`test/notaryhash/batch_leaf.js` — including a test that a tree built over `canonicalBytes`
+is rejected, so the choice is checked rather than merely intended.
+
+No deployed batch certificates are known to use the other reading. If any exist, they were
+built against an ambiguous sentence and would need reissuing; batch mode is the least-used
+of the three and this is the moment to fix it, before that stops being true.
+
+---
+
+## Recommended alongside
+
+Publish a **batch-mode golden vector** with the other test vectors: a small tree — four
+proofs, say — with the four `proofHash` values, the resulting root, and the inclusion path
+for one leaf. One such vector removes this entire class of ambiguity for every future
+implementer, in a way that no amount of prose reliably does. Its absence is why this
+document is necessary.

package/docs/BRC220_ENCODING_AMENDMENT.md

@@ -0,0 +1,100 @@
+# Proposed BRC-220 amendment: define the `encoding` field
+
+`encoding` is listed among the certificate's required fields, but its values are never
+enumerated. This proposes the definition, with the reasoning that led to it.
+
+Prepared 2026-08-16 while implementing BRC-220 in `@smartledger/bsv`. The gap surfaced
+because an implementation cannot emit a required field whose values are undefined.
+
+---
+
+## Proposed text
+
+Insert into **§Certificate**, after the sentence listing the required fields.
+
+> #### `encoding`
+>
+> `encoding` names the byte representation of `publicKey` and `signature` as they appear
+> in the certificate and in the canonical proof bytes.
+>
+> Implementations **MUST** support `"raw"` and **SHOULD** emit it:
+>
+> - **`"raw"`** — the scheme's native fixed-length byte string.
+>   - For `ECDSA-secp256k1`, a signature is exactly **64 bytes**: `r ‖ s`, each a 32-byte
+>     big-endian unsigned integer, zero-padded on the left. A public key is the 33-byte
+>     compressed SEC1 form.
+>   - For `ML-DSA-*` and `SLH-DSA-*`, the signature and public key are the byte strings the
+>     scheme itself defines (FIPS 204, FIPS 205). No further framing is applied.
+> - **`"der"`** — ECDSA signatures in ASN.1 DER, as produced by Bitcoin tooling.
+>   Accepted for compatibility with existing Bitcoin-native signers; **SHOULD NOT** be
+>   emitted by new implementations, for the reason given below. Undefined for post-quantum
+>   algorithms, which have no DER form.
+>
+> For `ECDSA-secp256k1`, `s` **MUST** be in the lower half of the curve order
+> (`s ≤ n/2`). A signature with a high `s` **MUST** be rejected rather than normalised on
+> receipt: normalising changes the signature bytes, and the signature bytes are inside
+> `proofHash`.
+
+---
+
+## Why `"raw"` rather than DER
+
+### 1. DER is not canonical, and `proofHash` covers the signature bytes
+
+The canonical proof bytes include `lp(signature)`, so the signature's exact byte
+representation determines `proofHash`. DER does not have one representation per signature.
+Measured over 200 signatures from a single key with `@smartledger/bsv`:
+
+```
+DER lengths:  { "69": 1, "70": 108, "71": 91 }
+raw lengths:  { "64": 200 }
+```
+
+The variance is ordinary leading-zero handling in the two INTEGERs, and it is entirely
+legal DER. But it means the same signing act can yield different `proofHash` values
+depending on which library encoded it — and a certificate re-encoded in transit no longer
+matches its own integrity root.
+
+That is the property §Motivation names first: *"any implementation in any language
+reproduces identical bytes"*, and the reason the spec already rejects `JSON.stringify`.
+A non-canonical signature encoding reintroduces exactly the problem the binary encoding was
+chosen to avoid.
+
+### 2. Every other algorithm in the spec is already raw
+
+ML-DSA-65 signatures are 3,309 bytes; SLH-DSA-SHA2-128s are 7,856. Both are fixed-length
+byte strings with no DER form. With ECDSA on DER and the post-quantum schemes on raw,
+every verifier needs per-algorithm branching on `encoding`. With ECDSA on raw, all sixteen
+algorithm identifiers share one representation and the branch disappears.
+
+### 3. It matches what the signature actually is
+
+§Algorithms specifies that the signer signs the 32-byte `payloadHash` **directly**. This is
+a detached signature over a digest, not a Bitcoin script signature — the case ES256K
+(RFC 7515) and WebCrypto both address, and both use `r ‖ s`, not DER.
+
+### 4. Low-S is a separate malleability, and raw does not fix it
+
+For any ECDSA signature, `s` and `n − s` both verify. They are different bytes, so they
+produce different `proofHash` values. Without a normative rule, two valid certificates
+exist for one signing act — an ambiguity a notarization protocol should not carry.
+
+Requiring low-S at signing, and **rejecting** rather than normalising on receipt, keeps
+`proofHash` a function of the certificate as issued.
+
+---
+
+## Note on `toCompact`
+
+Some Bitcoin libraries expose a 65-byte "compact" signature. That is not this format: it
+carries a leading recovery byte for public-key recovery. `"raw"` is the bare 64 bytes,
+with no recovery byte, because the public key is already a certificate field.
+
+---
+
+## Impact on existing certificates
+
+None, if no certificate has yet been issued with `encoding: "der"`. If any have, they
+remain valid — `"der"` stays an accepted value, and the SPV envelope and `proofHash`
+semantics are untouched. This amendment defines a field that was previously unspecified;
+it does not change any field that was.

package/docs/BRC220_PLAN.md

@@ -0,0 +1,233 @@
+# BRC-220 (NotaryHash) — implementation plan
+
+Plan for implementing [BRC-220](https://github.com/bitcoin-sv/BRCs/blob/master/apps/0220.md),
+*NotaryHash: Privacy-Preserving Signed-Hash Notarization with SPV-Verifiable Certificates*,
+in `@smartledger/bsv`.
+
+Drafted against the spec on 2026-08-16, at v8.2.0. Nothing here is implemented yet.
+
+## 1. Why this library
+
+BRC-220 is a notarization protocol, not a signature scheme. It needs a signer, an
+`OP_FALSE OP_RETURN` output, a canonical JSON certificate, an SPV proof, and a Merkle
+tree. Four of those five already exist here:
+
+| BRC-220 needs | Already present |
+| --- | --- |
+| RFC 8785 canonical certificate | `AttestationSigner._canonicalizeJCS` (8.2.0) |
+| SPV inclusion proof, TSC format | `lib/spv/merkleproof.js`, `lib/spv/headerchain.js` |
+| Independent block headers, never the provider's word | `verifyHeaderChain`, already the documented stance |
+| `OP_FALSE OP_RETURN` safe data output | `lib/transaction`, `lib/custom-script-helper.js` |
+| Length-prefixed binary | `lib/encoding/bufferwriter.js` |
+| ECDSA-secp256k1 signing | `lib/crypto/ecdsa.js` |
+
+The JCS work landed in 8.2.0 for an unrelated reason — GDAF signatures had to be
+verifiable by other implementations — and BRC-220 requires exactly that encoding for its
+certificates. That is the single strongest argument that this belongs here rather than in
+a separate package.
+
+## 2. Post-quantum stays OUT of the dependency tree
+
+The spec names ML-DSA (3 parameter sets) and SLH-DSA (12), but `ECDSA-secp256k1` is a
+first-class algorithm alongside them. A conformant implementation can support ECDSA only.
+
+`@noble/post-quantum` should NOT become a dependency of this library:
+
+- **It is the one unaudited Noble package.** Its README states plainly: *"The library has
+  not been independently audited yet"* — a self-audit at 0.6.1 only. `@noble/curves`,
+  `@noble/hashes` and `@noble/ciphers` carry a published Cure53 audit, which is why
+  `docs/AUDIT_SCOPE.md` can tell a vendor not to price the primitive layer. Adding an
+  unaudited implementation trades that away and has to be disclosed.
+- It is **0.x**, so the API is not stable.
+- It does **not claim constant-time execution**, which its README calls out as mattering
+  most when an attacker can measure signing.
+- 669 KB unpacked, against bundles this project cut 20% in 8.0.0.
+
+**Instead: a suite registry.** `algorithm` is a string in both the certificate and the
+on-chain record, so it maps naturally onto a lookup:
+
+```js
+NotaryHash.registerSuite('ML-DSA-65', {
+  verify: function (payloadHash, signature, publicKey) { /* … */ },
+  sign: function (payloadHash, privateKey) { /* … */ }
+})
+```
+
+`ECDSA-secp256k1` is registered by default and needs nothing new. Everything else is
+supplied by the caller — most obviously from **`@smartledger/keys`**, which already wraps
+`@noble/post-quantum` for ML-DSA-44/65/87. That keeps one PQ dependency in the ecosystem
+rather than two, and callers who do not need it pay nothing in bundle size or audit
+surface.
+
+Note `@smartledger/keys@2.0.0` is currently 8 months stale and behind on all three of its
+crypto dependencies, including a full major on `@noble/hashes` (1.8.0 against 2.3.0).
+Refreshing it is a prerequisite for recommending it as the PQ path, and is separate work.
+
+## 3. The trap: three different Merkle trees
+
+BRC-220 batch mode uses **RFC 6962** trees. This library already contains two Merkle
+implementations, and **neither is RFC 6962**:
+
+| Tree | Leaf | Internal | Odd node |
+| --- | --- | --- | --- |
+| Bitcoin (`lib/spv/merkleproof.js`) | txid | `sha256d(L‖R)` | rightmost **duplicated** |
+| `lib/gdaf/zk-prover.js` | salted field hash | `sha256(L‖R)` | duplicated |
+| **RFC 6962 (BRC-220 needs)** | `sha256(0x00‖d)` | `sha256(0x01‖L‖R)` | **never duplicated** |
+
+Domain separation and the no-duplication rule are what make RFC 6962 resistant to the
+second-preimage attack Bitcoin's tree is famously vulnerable to. Reusing either existing
+implementation would be silently wrong: it would produce a root that no other BRC-220
+implementation computes, and the failure would only appear when someone else verified a
+batch certificate.
+
+RFC 6962 splits at the **largest power of two less than the leaf count**, not the middle.
+That must be tested against published RFC 6962 vectors, not against our own output.
+
+## 4. Module layout
+
+```
+lib/notaryhash/
+  index.js        NotaryHash.create / verify / registerSuite
+  encoding.js     lp(), canonical bytes, proofHash
+  script.js       OP_FALSE OP_RETURN builder + parser, all three modes
+  certificate.js  build, JCS-canonicalize, validate shape
+  merkle.js       RFC 6962 — NOT the Bitcoin or zk-prover trees
+  suites.js       registry; ECDSA-secp256k1 registered by default
+```
+
+Exposed as `bsv.NotaryHash`, with a `notaryhash-entry.js` and its own bundle, matching how
+`gdaf`, `ltp` and `didweb` are already packaged.
+
+## 5. What gets built, in order
+
+**Phase 1 — encoding and proofHash.** `lp(x) = u32be(len(x)) || x`, and the canonical byte
+string:
+
+```
+lp("NotaryHash/1.0") || u8(version) || lp(algorithm) || lp(hashAlgorithm) ||
+lp(payloadHash) || lp(publicKey) || lp(signature) || u64be(createdAtUnix)
+```
+
+The protocol prefix, version and timestamp are in `proofHash` but never on chain — so the
+on-chain record alone cannot reconstruct it, and a verifier needs the certificate. Worth a
+test that states this, because it looks like an omission otherwise.
+
+**Phase 2 — the OP_RETURN record**, all three modes, builder and parser, round-tripping.
+Full mode carries the key and signature; hybrid carries `sha256` of each, which is what
+makes PQ signatures affordable on chain; batch carries only a 32-byte root and a `u32be`
+leaf count.
+
+**Phase 3 — certificate**, built on the existing `_canonicalizeJCS`. The SPV envelope is
+additive and must not change `proofHash` — a test should add an envelope to a finished
+certificate and assert the hash is unchanged.
+
+**Phase 4 — verification**, the three checks the spec requires, each returning a strict
+boolean and failing closed:
+
+1. signature verifies over `payloadHash` under the registered suite — offline;
+2. `proofHash` recomputes from canonical bytes and matches — offline;
+3. anchor confirmed, SPV preferred: `txid = reverse(sha256d(rawTx))`, the `OP_RETURN`
+   fields match the certificate, and the TSC Merkle proof folds to a root matching a
+   block header **obtained independently**.
+
+**Phase 5 — batch mode** and RFC 6962, last because it is the piece most likely to be got
+wrong and benefits from everything else being settled.
+
+## 6. Testing stance
+
+Given what the last two reviews found in `zk-prover.js` — a range proof that verified
+nothing and a selective-disclosure scheme that leaked every withheld field, under 4,469
+passing tests — this module starts with adversarial tests rather than acquiring them
+later:
+
+- Every `verify` returns a **strict boolean** or throws. Never a truthy result object.
+  This is the defect class that has recurred most in this codebase.
+- Each of the three validity checks has a test that **defeats it in isolation**: a valid
+  signature with a tampered `proofHash`; a correct `proofHash` with a forged signature; a
+  well-formed certificate anchored to a transaction that is not in the block it claims.
+- An unregistered `algorithm` must **fail**, not fall through to a default suite.
+- RFC 6962 vectors from the RFC, not from our own implementation, and a test that a
+  Bitcoin-style tree over the same leaves produces a *different* root — that failure is
+  the one that would otherwise ship silently.
+- Round-trip the on-chain record for all three modes, and assert hybrid's pushes are
+  32 bytes where full's are variable.
+
+## 7. Questions, settled against the full text
+
+The spec is 8,514 bytes. These were resolved by reading all of it rather than querying it
+piecemeal — which is also how the first of them turned out to be an artifact of my own
+summarising rather than anything in the document.
+
+- **Push 0 is `"NOTARYHASH"`, 10 ASCII bytes** (`4e4f5441525948415348`). The spec states no
+  byte count for it anywhere; the "9 bytes" this section previously flagged came from a
+  summarisation step, not the normative text. Verified by fetching the raw file and
+  grepping it directly.
+- **`hashAlgorithm` is SHA-256** for every algorithm the spec lists — the Algorithms table
+  gives one hash for all three families. It is not stated to be closed, so the field stays
+  a string rather than an enum, but SHA-256 is the only conformant value in v1.
+- **The signer signs the 32-byte `payloadHash` directly** (§Algorithms): "post-quantum
+  schemes apply their own internal hashing". So ECDSA signs the digest as-is, with no
+  second hash. Getting this wrong produces signatures nothing else verifies.
+- **Batch certificates carry BOTH `anchor` and `merkle`** — the spec says a batched
+  certificate "additionally carries" the inclusion proof.
+- **The service is a role, not a requirement.** §What a certificate proves: "any party
+  holding a valid (hash, signature, publicKey) triple may re-anchor it; the attestation
+  remains valid". A self-notarizing caller producing its own certificate is conformant.
+- **The batch Merkle leaf is NOT settled by the spec — it is a choice this
+  implementation made.** §On-chain record writes `leaf = SHA256(0x00 ‖ d)`, but that is
+  RFC 6962's own generic notation for the construction and `d` is never bound to a value.
+  `canonicalBytes` appears once in the whole document, in the `proofHash` definition, and
+  nowhere in the batch text. We read `d` as `proofHash`; reading it as `canonicalBytes` is
+  equally sound and produces a different root, so the two do not interoperate. Recorded as
+  an ambiguity rather than a settled question, with proposed spec text in
+  [BRC220_BATCH_LEAF_AMENDMENT.md](BRC220_BATCH_LEAF_AMENDMENT.md) and enforcement in
+  `test/notaryhash/batch_leaf.js`. This is the second gap of the kind, after `encoding`.
+- **`createdAt` is advisory for trust but load-bearing for the hash.** §Verification calls
+  it "an advisory client field only" — meaning proof-of-existence time comes from the
+  block, not from this field. It is still inside the canonical bytes as `createdAtUnix`,
+  so it cannot be altered after issuance.
+
+Decided, and proposed back to the spec:
+
+- **`encoding` is `"raw"`.** The field is required by the spec but its values were never
+  enumerated, so this library defines them and proposes the definition upstream — see
+  `docs/BRC220_ENCODING_AMENDMENT.md`.
+
+  For `ECDSA-secp256k1` that is 64 bytes, `r ‖ s`, each a 32-byte big-endian integer, with
+  a 33-byte compressed public key. NOT DER, and not the 65-byte `toCompact` form, which
+  carries a recovery byte the certificate does not need because it already has the key.
+
+  The deciding argument is that `proofHash` covers `lp(signature)`, and **DER is not
+  canonical**. Measured over 200 signatures from one key: DER came out at 69, 70 and 71
+  bytes depending on leading-zero handling, all of it legal. Raw was 64 bytes every time.
+  The same signing act producing different `proofHash` values is precisely the failure the
+  binary encoding exists to prevent — it is why the spec already refuses `JSON.stringify`.
+
+  Two supporting reasons: ML-DSA and SLH-DSA have no DER form, so raw makes `encoding`
+  uniform across all sixteen algorithm identifiers instead of forcing per-algorithm
+  branching in every verifier; and the signature is detached over a digest rather than a
+  Bitcoin script signature, which is the ES256K/WebCrypto case, and both use `r ‖ s`.
+
+  **Low-S is required and must be rejected, not normalised.** `s` and `n − s` both verify
+  and hash differently, so without the rule two valid certificates exist for one signing
+  act. Normalising on receipt would change the signature bytes, which are inside
+  `proofHash`. This library already emits low-S and has `Signature.toCanonical()`.
+
+### The reference implementation
+
+§Implementations describes a reference service, client SDK and standalone verifier, with
+**published test vectors**: a complete certificate-with-SPV-envelope golden vector,
+`txidFromRawTx` against the Bitcoin genesis coinbase, and the Merkle fold against the real
+block-170 two-transaction proof.
+
+Those vectors are worth more than anything in §6, and should be wired in as gates before
+Phase 2 goes far. This module's characteristic failure is being self-consistent and wrong
+— every local test green, no other implementation agreeing — and a golden vector from a
+second implementation is the only thing that actually rules it out. Our own tests cannot.
+
+## 8. Not in scope
+
+- Post-quantum suites themselves — supplied by the caller, see §2.
+- The notary *service*. This library builds and verifies records and certificates; it does
+  not run the submission endpoint the spec describes.
+- Broadcasting. Existing transaction plumbing covers it.

package/docs/MODULE_REFERENCE_COMPLETE.md

@@ -55,19 +55,19 @@ Three advanced modules totaling **~2.7MB** of functionality:
 - **Purpose**: Threshold cryptography for secure secret distribution
 - **Use Cases**: Backup keys, multi-party security, key recovery
 - **Features**: Split secrets into N shares, require M to reconstruct
-- **CDN**: `unpkg.com/@smartledger/bsv@8.2.0/bsv-shamir.min.js`
+- **CDN**: `unpkg.com/@smartledger/bsv@8.3.1/bsv-shamir.min.js`
 
 #### **🌐 Global Digital Attestation Framework - GDAF (1184KB)**  
 - **Purpose**: W3C Verifiable Credentials and decentralized identity
 - **Use Cases**: Identity verification, attestations, zero-knowledge proofs
 - **Features**: DID creation, credential issuance, selective disclosure
-- **CDN**: `unpkg.com/@smartledger/bsv@8.2.0/bsv-gdaf.min.js`
+- **CDN**: `unpkg.com/@smartledger/bsv@8.3.1/bsv-gdaf.min.js`
 
 #### **⚖️ Legal Token Protocol - LTP (1184KB)**
 - **Purpose**: Legal compliance framework for tokenized assets
 - **Use Cases**: Property rights, obligations, compliant tokenization  
 - **Features**: Legal primitives, compliance checking, attestation anchoring
-- **CDN**: `unpkg.com/@smartledger/bsv@8.2.0/bsv-ltp.min.js`
+- **CDN**: `unpkg.com/@smartledger/bsv@8.3.1/bsv-ltp.min.js`
 
 ### **2. Incorrect File Sizes in Documentation**
 
@@ -81,18 +81,18 @@ Three advanced modules totaling **~2.7MB** of functionality:
 
 | Module | Size | Use Case | CDN Link |
 |--------|------|----------|----------|
-| **bsv.min.js** | 937KB | Core BSV + SmartContract | `unpkg.com/@smartledger/bsv@8.2.0/bsv.min.js` |
-| **bsv.bundle.js** | 937KB | Everything in one file | `unpkg.com/@smartledger/bsv@8.2.0/bsv.bundle.js` |
-| **bsv-smartcontract.min.js** | 937KB | Covenant development | `unpkg.com/@smartledger/bsv@8.2.0/bsv-smartcontract.min.js` |
-| **bsv-covenant.min.js** | 913KB | Covenant operations | `unpkg.com/@smartledger/bsv@8.2.0/bsv-covenant.min.js` |
-| **bsv-script-helper.min.js** | 26KB | Custom script tools | `unpkg.com/@smartledger/bsv@8.2.0/bsv-script-helper.min.js` |
-| **bsv-security.min.js** | 26KB | Security enhancements (opt-in helpers — see README › Security) | `unpkg.com/@smartledger/bsv@8.2.0/bsv-security.min.js` |
-| **bsv-ecies.min.js** | 71KB | Encryption | `unpkg.com/@smartledger/bsv@8.2.0/bsv-ecies.min.js` |
-| **bsv-message.min.js** | 26KB | Message signing | `unpkg.com/@smartledger/bsv@8.2.0/bsv-message.min.js` |
-| **bsv-mnemonic.min.js** | 681KB | HD wallets | `unpkg.com/@smartledger/bsv@8.2.0/bsv-mnemonic.min.js` |
-| **🆕 bsv-shamir.min.js** | 432KB | **Secret sharing** | `unpkg.com/@smartledger/bsv@8.2.0/bsv-shamir.min.js` |
-| **🆕 bsv-gdaf.min.js** | 1184KB | **Digital attestation** | `unpkg.com/@smartledger/bsv@8.2.0/bsv-gdaf.min.js` |
-| **🆕 bsv-ltp.min.js** | 1184KB | **Legal tokens** | `unpkg.com/@smartledger/bsv@8.2.0/bsv-ltp.min.js` |
+| **bsv.min.js** | 937KB | Core BSV + SmartContract | `unpkg.com/@smartledger/bsv@8.3.1/bsv.min.js` |
+| **bsv.bundle.js** | 937KB | Everything in one file | `unpkg.com/@smartledger/bsv@8.3.1/bsv.bundle.js` |
+| **bsv-smartcontract.min.js** | 937KB | Covenant development | `unpkg.com/@smartledger/bsv@8.3.1/bsv-smartcontract.min.js` |
+| **bsv-covenant.min.js** | 913KB | Covenant operations | `unpkg.com/@smartledger/bsv@8.3.1/bsv-covenant.min.js` |
+| **bsv-script-helper.min.js** | 26KB | Custom script tools | `unpkg.com/@smartledger/bsv@8.3.1/bsv-script-helper.min.js` |
+| **bsv-security.min.js** | 26KB | Security enhancements (opt-in helpers — see README › Security) | `unpkg.com/@smartledger/bsv@8.3.1/bsv-security.min.js` |
+| **bsv-ecies.min.js** | 71KB | Encryption | `unpkg.com/@smartledger/bsv@8.3.1/bsv-ecies.min.js` |
+| **bsv-message.min.js** | 26KB | Message signing | `unpkg.com/@smartledger/bsv@8.3.1/bsv-message.min.js` |
+| **bsv-mnemonic.min.js** | 681KB | HD wallets | `unpkg.com/@smartledger/bsv@8.3.1/bsv-mnemonic.min.js` |
+| **🆕 bsv-shamir.min.js** | 432KB | **Secret sharing** | `unpkg.com/@smartledger/bsv@8.3.1/bsv-shamir.min.js` |
+| **🆕 bsv-gdaf.min.js** | 1184KB | **Digital attestation** | `unpkg.com/@smartledger/bsv@8.3.1/bsv-gdaf.min.js` |
+| **🆕 bsv-ltp.min.js** | 1184KB | **Legal tokens** | `unpkg.com/@smartledger/bsv@8.3.1/bsv-ltp.min.js` |
 
 ## 🎯 **Updated Usage Examples**
 
@@ -100,22 +100,22 @@ Three advanced modules totaling **~2.7MB** of functionality:
 
 #### **1. Basic Development (~963KB)**
 ```html
-<script src="https://unpkg.com/@smartledger/bsv@8.2.0/bsv.min.js"></script>
-<script src="https://unpkg.com/@smartledger/bsv@8.2.0/bsv-script-helper.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@8.3.1/bsv.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@8.3.1/bsv-script-helper.min.js"></script>
 ```
 
 #### **2. Smart Contract Development (~2.7MB — each bundle re-embeds core BSV)**
 ```html
-<script src="https://unpkg.com/@smartledger/bsv@8.2.0/bsv.min.js"></script>
-<script src="https://unpkg.com/@smartledger/bsv@8.2.0/bsv-covenant.min.js"></script>
-<script src="https://unpkg.com/@smartledger/bsv@8.2.0/bsv-smartcontract.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@8.3.1/bsv.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@8.3.1/bsv-covenant.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@8.3.1/bsv-smartcontract.min.js"></script>
 ```
 
 #### **3. 🆕 Legal & Compliance Development (~3.2MB — each bundle re-embeds core BSV)**
 ```html
-<script src="https://unpkg.com/@smartledger/bsv@8.2.0/bsv.min.js"></script>
-<script src="https://unpkg.com/@smartledger/bsv@8.2.0/bsv-ltp.min.js"></script>
-<script src="https://unpkg.com/@smartledger/bsv@8.2.0/bsv-gdaf.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@8.3.1/bsv.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@8.3.1/bsv-ltp.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@8.3.1/bsv-gdaf.min.js"></script>
 <script>
   // Legal Token Protocol
   const legalToken = bsv.createLegalToken({
@@ -132,9 +132,9 @@ Three advanced modules totaling **~2.7MB** of functionality:
 
 #### **4. 🆕 Security & Cryptography (~1.4MB)**
 ```html
-<script src="https://unpkg.com/@smartledger/bsv@8.2.0/bsv.min.js"></script>
-<script src="https://unpkg.com/@smartledger/bsv@8.2.0/bsv-security.min.js"></script>
-<script src="https://unpkg.com/@smartledger/bsv@8.2.0/bsv-shamir.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@8.3.1/bsv.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@8.3.1/bsv-security.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@8.3.1/bsv-shamir.min.js"></script>
 <script>
   // Shamir Secret Sharing
   const shares = bsv.splitSecret('my_secret_key', 5, 3); // 5 shares, 3 needed
@@ -146,7 +146,7 @@ Three advanced modules totaling **~2.7MB** of functionality:
 
 #### **5. Everything Bundle (937KB)**
 ```html
-<script src="https://unpkg.com/@smartledger/bsv@8.2.0/bsv.bundle.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@8.3.1/bsv.bundle.js"></script>
 <script>
   // Everything available immediately
   const shares = bsv.splitSecret('secret', 5, 3);

package/docs/advanced/UTXO_MANAGER_GUIDE.md

@@ -722,7 +722,7 @@ interface UTXO {
 <html>
 <head>
     <title>UTXO Manager Demo</title>
-    <script src="https://cdn.jsdelivr.net/npm/@smartledger/bsv@8.2.0/bsv.min.js"></script>
+    <script src="https://cdn.jsdelivr.net/npm/@smartledger/bsv@8.3.1/bsv.min.js"></script>
 </head>
 <body>
     <script>