@smartledger/bsv 9.8.0 → 9.10.0

package/docs/AUDIT_SCOPE.md

@@ -34,14 +34,14 @@ module sounds. That is a deliberate revision: an earlier version of this documen
 scoped Tier 1 as "the cryptographic core" and would have excluded four of the six real
 defects this codebase has produced. See §2.1.
 
-### Tier 1 — 11,384 lines
+### Tier 1 — 11,976 lines
 
 | Module | Lines | Why it matters |
 | --- | ---: | --- |
 | `lib/transaction/` | 2,779 | Sighash construction and signing — both BIP-143 and the Original Transaction Digest Algorithm. |
 | `lib/script/interpreter.js` | 2,821 | **Scoped to the flag and era surface, not opcode execution.** Consensus-flag selection and defaults, era derivation (Genesis/Chronicle), the limits derived from them, and the semantics of the exported `verify()`. Opcode execution is excluded — see §2.2. |
 | `lib/crypto/` | 2,519 | ECDSA, nonce derivation, signature encoding, the script-number type. **Scope this for an architectural judgement as well as for bugs** — see §2.3. |
-| `lib/notaryhash/` | 1,436 | BRC-220 signing and verification. Publicly reachable and relied on downstream. |
+| `lib/notaryhash/` | 2,028 | BRC-220 signing and verification. Publicly reachable and relied on downstream. |
 | `lib/privatekey.js`, `lib/publickey.js` | 843 | Key construction, serialisation, WIF. Recent defects here produced a *different* key without error. |
 | `lib/smart_contract/` (targeted) | 472 | `locks.js` and the covenant-facing entrypoints in `index.js`: CLTV and HTLC locking semantics, flag plumbing, and any wrapper claiming mainnet-equivalent verification. Not the whole 6,908-line module. |
 | `lib/covenant/` | 409 | The verification harness. Its flag word is what made covenants verify under 2019 rules while claiming to mirror mainnet. |
@@ -150,14 +150,14 @@ this repository.
 | `lib/address.js`, `lib/networks.js`, `lib/opcode.js`, `lib/hdprivatekey.js`, `lib/hdpublickey.js` (2,391 lines) | Cut to pay for §2.1 | Formatting, network constants and BIP-32 derivation. No defect has originated here, and `networks.js` in particular defines addressing constants — pubkey hashes, xpub prefixes, ports, DNS seeds — and contains **no consensus-flag logic at all**. |
 | The rest of the application layer — `lib/gdaf/`, `lib/ltp/`, `lib/ordinals/`, `lib/block/`, `lib/didweb/`, `lib/vcjwt/`, `lib/statuslist/`, most of `lib/smart_contract/`, plus assorted top-level files | Excluded | ~26,000 lines. Worth a separate engagement; including it here would blur the question in §1. Note the parts of it with a demonstrated defect history have been pulled *into* Tier 1 rather than left here — see §2.1. |
 
-Totals reconcile against `lib/`, which is 39,068 lines across 131 files:
+Totals reconcile against `lib/`, which is 39,660 lines across 131 files:
 
 ```
-tier 1      11,384
+tier 1      11,976
 tier 2       1,607
 excluded    26,077
             ------
-total       39,068
+total       39,660
 ```
 
 Measured 2026-08-29 at `a954c27`. These figures drift as the library changes — an
@@ -228,7 +228,7 @@ seeking a quote for an independent security review.
 
 Scope, and we would like these priced separately:
 
-  Tier 1 — 11,384 lines. Sighash construction and signing; ECDSA, nonce
+  Tier 1 — 11,976 lines. Sighash construction and signing; ECDSA, nonce
   derivation and signature encoding; the consensus-flag and era-derivation
   surface of the script interpreter; BRC-220 signing and verification;
   key construction and serialisation; the covenant verification harness and

package/docs/BRC220_BATCH_LEAF_AMENDMENT.md

@@ -3,8 +3,18 @@
 §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).
+Prepared 2026-08-17 while implementing BRC-220 in `@smartledger/bsv`.
+
+**Status: filed** as [bsv-blockchain/BRCs#246](https://github.com/bsv-blockchain/BRCs/pull/246)
+on 2026-09-11, together with a clarification of the ECDSA digest convention. Its review
+asked that `leafIndex` be stated as counted from 0 and that the vector say how `i` is
+written; both are in #246 and below. Before filing
+it was checked against the BRC-220 reference implementation, whose batcher uses exactly
+this leaf (`leaves = batch.map(e => e.proofHash)`), and the vector below was rebuilt
+without any of this library's code — the root from the reference's own RFC 6962 tree.
+
+A companion draft on the `encoding` field was **wrong and has been withdrawn**; see
+[BRC220_ENCODING_AMENDMENT.md](BRC220_ENCODING_AMENDMENT.md).
 
 ---
 
@@ -56,7 +66,7 @@ Insert into **§On-chain record**, replacing the batch bullet's parenthetical.
 >   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
+>   `leafIndex` in the certificate's `merkle` object is that position, counted from 0. The tree splits at
 >   the largest power of two `< n` and the last leaf is never duplicated, per RFC 6962
 >   §2.1.
 >
@@ -104,9 +114,10 @@ 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.
+The reference implementation uses the same reading, so certificates its service has
+issued in batch mode already conform. An implementation that chose `d = canonicalBytes`
+built against an ambiguous sentence and would need to reissue; the second root published
+below makes that diagnosable in one line.
 
 ---
 
@@ -126,10 +137,14 @@ up in the audit-path lengths: `[3, 3, 3, 3, 1]`.
 Every input is derived from a labelled preimage rather than chosen, so the file
 regenerates byte-identically and any implementation can rebuild it from scratch:
 
-- private key `i` = `SHA-256("BRC-220/batch-vector/key/" + i)`
+- private key `i` = `SHA-256("BRC-220/batch-vector/key/" + i)`, read as a big-endian integer
 - `payloadHash` `i` = `SHA-256("BRC-220/batch-vector/payload/" + i)`
 - `createdAt` `i` = `2026-01-0(i+1)T00:00:00.000Z`
-- `algorithm` = `ECDSA-secp256k1`, `hashAlgorithm` = `SHA-256`, `encoding` = `"raw"`
+- `algorithm` = `ECDSA-secp256k1`, `hashAlgorithm` = `SHA-256`, a 64-byte `r ‖ s`
+  signature normalised to low-S, and a 33-byte compressed public key
+
+where `i` is written as one ASCII decimal digit, `"0"` to `"4"`, so the first key's
+preimage is the 26-byte string `BRC-220/batch-vector/key/0`.
 
 **Signing.** The signer signs the 32-byte `payloadHash` directly — the digest *is* the
 scalar, big-endian. RFC 6979 makes the nonce deterministic, so the signatures, and every

package/docs/BRC220_CERTIFICATE_FIELDS_AMENDMENT.md

@@ -0,0 +1,246 @@
+# Proposed BRC-220 amendment: define the certificate's field values
+
+§Certificate names the twelve fields a certificate must carry and says it is JSON. It
+defines none of their values. This proposes the values the BRC-220 reference
+implementation writes, and two rules for reading them. With both, any implementation
+produces certificates the reference verifies, and reads certificates the way the reference
+does.
+
+Prepared 2026-09-11, with the open points decided [below](#decisions). **Status: filed**
+as [bsv-blockchain/BRCs#247](https://github.com/bsv-blockchain/BRCs/pull/247) on 2026-09-11. It is meant to be a separate pull request from
+[bsv-blockchain/BRCs#246](https://github.com/bsv-blockchain/BRCs/pull/246), which is under
+review and deliberately narrow; this text builds on it for the batch leaf datum.
+
+---
+
+## Why it matters
+
+Two implementations of BRC-220 filled the gap differently. `@smartledger/bsv` 8.3.0–9.8.0
+and the reference implementation computed identical `proofHash` values, signature digests,
+Merkle trees and on-chain records, and **could not verify a single one of each other's
+certificates**:
+
+| field | `@smartledger/bsv` 8.3.0–9.8.0 | reference implementation |
+| --- | --- | --- |
+| `version` | `1` | `"1.0"` |
+| `mode` | `0` / `1` / `2` | `"full"` / `"hybrid"` |
+| a batch | `mode: 2` | `anchor.type: "batch"` |
+| `encoding` | `"raw"` / `"der"` — the signature's byte form | `"hex"` / `"base64"` — how two fields are written |
+| `anchor` | `{ txid, blockHeight }` | `{ type, network, txid, vout, blockHeight, blockTime }` |
+| `merkle.path` | bare hashes | `{ hash, side }` |
+
+Every reading on the left is defensible from the current text. None of it is defined there.
+The cryptography is fully specified and the object carrying it is not, so two conformant
+implementations fail each other silently, on the field names a verifier reads first.
+
+## Where the values come from
+
+Every value below is what the reference implementation writes, read from its source at
+commit `b926e3b`: the certificate assembly, the batcher, the confirmation poller that adds
+the SPV envelope, and its request schema. They agree with the reference's own protocol
+document, whose §5 carries the same example shapes.
+
+The two reader rules go further than the reference's verifier did at `b926e3b`. It accepted
+a certificate of any `version`, and decoded base64 by skipping whatever it did not
+recognise. The reference implementation adopts both rules, and `@smartledger/bsv` applies
+both, so the spec does not state a rule its own reference breaks.
+
+The two examples are certificates the reference's own code produced, reproduced in
+`test/data/notaryhash-reference-certs.json`, where each was accepted by the reference's
+schema and verifier. `test/notaryhash/fields_amendment.js` reads them out of this document
+and checks them against that fixture, so the examples cannot drift from what the reference
+actually wrote.
+
+---
+
+## What the spec currently says
+
+§Certificate, in full:
+
+> A self-contained JSON object, canonicalised via RFC 8785 (JCS) for hashing and transport.
+> Required fields: `protocol`, `version`, `mode`, `algorithm`, `hashAlgorithm`,
+> `payloadHash`, `publicKey`, `signature`, `encoding`, `proofHash`, `createdAt`, `anchor`.
+> A batched certificate additionally carries a `merkle` inclusion proof
+> `{root, leafIndex, leafCount, path[]}` whose folding (leaf → root) must equal the
+> on-chain batch root.
+
+That leaves undefined:
+
+- `version`: a string or a number, and which one. The canonical bytes carry `u8(version=1)`
+  and the domain separator `"NotaryHash/1.0"`, which invite both.
+- `mode`: the on-chain byte (`0`/`1`/`2`) or a name. The on-chain record also has a `kind = 2`
+  for batches, which invites treating batch as a third mode.
+- `encoding`: whether it names the bytes' format (raw, DER) or their spelling in JSON.
+- how `payloadHash`, `proofHash`, `publicKey` and `signature` are written.
+- the format of `createdAt`, and how it relates to `createdAtUnix` in the canonical bytes.
+- every member of `anchor`. The spec never lists them.
+- the elements of `merkle.path`. With bare hashes a verifier needs `leafIndex` and
+  `leafCount` to fold; with sides it does not.
+- the byte order of `txid`, `spv.blockHash` and `spv.merkleProof.nodes`.
+- what a verifier does with a `version` it does not know, or a field that does not decode.
+
+---
+
+## Proposed text
+
+Generated from the text as committed for filing, so the two cannot differ. The ECDSA
+byte forms sit in §Certificate, under the fields they describe, rather than in
+§Algorithms, which #246 edits; a trial merge of #246 on top of this change is clean.
+
+### 1. §Certificate — replace the paragraph
+
+> ### Certificate
+>
+> A self-contained JSON object, canonicalised via [RFC 8785 (JCS)](https://www.rfc-editor.org/rfc/rfc8785) for hashing and transport, carrying the twelve required fields below. Hex is written **lowercase, without a `0x` prefix**; a reader MAY accept upper case and the prefix. Numbers are JSON integers. Verifiers ignore members they do not recognise, which is how the SPV envelope is added to a certificate already issued.
+>
+> | field | value |
+> |-------|-------|
+> | `protocol` | the string `"NotaryHash"` |
+> | `version` | the string `"1.0"`: the certificate format version. It corresponds to `u8(version=1)` in the canonical proof bytes and the on-chain record, and to the domain separator `"NotaryHash/1.0"`, but is written as a string. A verifier MUST reject a certificate whose `version` it does not implement. |
+> | `mode` | `"full"` or `"hybrid"`: how the proof is recorded on chain, corresponding to the on-chain `mode` byte `0` or `1`. Batching is marked by `anchor.type`, not by `mode`. |
+> | `algorithm` | an identifier from §Algorithms, e.g. `"ECDSA-secp256k1"` |
+> | `hashAlgorithm` | `"SHA-256"` |
+> | `payloadHash` | the 32-byte payload hash, hex |
+> | `publicKey` | the **full** public key in every mode (hybrid puts only its SHA-256 on chain), written per `encoding` |
+> | `signature` | the **full** signature, as the signer produced it, in every mode, written per `encoding` |
+> | `encoding` | how `publicKey` and `signature` are written: `"hex"`, or `"base64"` (RFC 4648 §4: standard alphabet, padded). It applies to those two fields only, and says nothing about the format of the bytes themselves. A reader MUST reject a value that is not valid in its encoding rather than decode what remains of it — for base64, a character outside the RFC 4648 §4 and §5 alphabets, padding anywhere but the end, or a length no byte string encodes. A reader MAY accept the §5 (URL-safe) alphabet and missing padding. |
+> | `proofHash` | the 32-byte `SHA-256(canonicalBytes)`, hex |
+> | `createdAt` | `createdAtUnix` as an ISO 8601 UTC timestamp with milliseconds, e.g. `"2026-01-01T00:00:00.000Z"`. The milliseconds are always `000`, because only whole seconds enter the canonical bytes; a verifier recovers `createdAtUnix` as the whole seconds the timestamp denotes. Advisory only — see §Verification. |
+> | `anchor` | the object below |
+>
+> For `ECDSA-secp256k1`, `publicKey` is 33 bytes (compressed) or 65 (uncompressed), and `signature` is 64 bytes (`r ‖ s`, each a 32-byte big-endian integer) or DER. A verifier tells them apart by the bytes: DER begins with `0x30` and is not 64 bytes long. `S` is not normalised: the certificate commits, through `proofHash`, to the exact bytes the signer produced, so the malleated form of a signature is a different certificate rather than a forgery of this one.
+>
+> `anchor` locates the on-chain record:
+>
+> | member | value |
+> |--------|-------|
+> | `type` | `"direct"` if the record carries this proof (`mode` `0` or `1`); `"batch"` if it carries a Merkle root (`kind = 2`) |
+> | `network` | the chain the anchoring transaction is on: `"bsv-mainnet"` for BSV mainnet, `"bsv-testnet"` for BSV testnet. Other values are not interoperable. The field is descriptive: which chain the anchor is on is established by the block header the verifier obtains, not by this value. |
+> | `txid` | the anchoring transaction's id, hex, in display order: `reverse(SHA256(SHA256(rawTx)))` |
+> | `vout` | the index of the `OP_RETURN` output within that transaction |
+> | `blockHeight` | the height of the block that mined the transaction, or `null` until it is mined |
+> | `blockTime` | that block's timestamp in Unix seconds, or `null` until it is mined |
+>
+> A batched certificate (`anchor.type` `"batch"`) additionally carries `merkle`, the proof that this proof is one of the batch's leaves:
+>
+> | member | value |
+> |--------|-------|
+> | `root` | the 32-byte batch root, hex; equal to `merkleRoot` in the on-chain batch record |
+> | `leafIndex` | this proof's position in the batch, from `0` |
+> | `leafCount` | the number of proofs in the batch; equal to `leafCount` in the on-chain batch record |
+> | `path` | the audit path, leaf → root, as an array of `{ "hash": <32-byte hex>, "side": "left" or "right" }`. `side` is the sibling's position relative to the running hash. Starting from `SHA256(0x00 ‖ proofHash)`, a `"left"` sibling folds as `SHA256(0x01 ‖ hash ‖ running)` and a `"right"` one as `SHA256(0x01 ‖ running ‖ hash)`. The result must equal `root`. |
+>
+> In a batched certificate `mode` is not checked against the chain: the batch record carries neither the proof nor a mode byte.
+>
+> A direct-anchored ECDSA certificate, before its SPV envelope is attached:
+>
+> <!-- fixture: certificates.fullHex -->
+> ```json
+> {
+>   "protocol": "NotaryHash",
+>   "version": "1.0",
+>   "mode": "full",
+>   "algorithm": "ECDSA-secp256k1",
+>   "hashAlgorithm": "SHA-256",
+>   "payloadHash": "97ef50e782e55cfbfbfb0c6199b96837836b7f7b0fcae76f79a65e2466dc596b",
+>   "publicKey": "02375ac16df62a74475844721d6a180927f29314c3455eaa699f7dcf5237c36e52",
+>   "signature": "e65171edb82a702a8390fb90f005ba3d4e174ab945ab0bcaf5f1f8d18c3547426ca419ea252b142e863d2eeebdfc787a624bed5a06d23a671959b07b5cb12ba3",
+>   "encoding": "hex",
+>   "proofHash": "1b34fbeb640e63b366751a279aa749e4f279cfb7e1add1a96150d7fd7c2ff05d",
+>   "createdAt": "2026-01-01T00:00:00.000Z",
+>   "anchor": {
+>     "type": "direct",
+>     "network": "bsv-mainnet",
+>     "txid": "460d19b875036e41d6dea392bfcb84508120e7b573080c45869eedbae39dec6a",
+>     "vout": 0,
+>     "blockHeight": 900000,
+>     "blockTime": 1767225600
+>   }
+> }
+> ```
+>
+> The `merkle` member of the last certificate in a five-proof batch:
+>
+> <!-- fixture: batch.certificates[4].merkle -->
+> ```json
+> {
+>   "root": "abb53eb3b2e3530d51685c6813bb85c85892d2f214c2dc504029d071434ac074",
+>   "leafIndex": 4,
+>   "leafCount": 5,
+>   "path": [
+>     { "hash": "060ca4e4bbcb647ab0162bb027cd8f08c1577aaa7069166dd629a3df7e57befd", "side": "left" }
+>   ]
+> }
+> ```
+>
+> The anchoring transactions and blocks in these examples are test fixtures, not mainnet data. Everything else in them verifies: the signature, `proofHash`, the on-chain record in the transaction, and the batch inclusion.
+
+### 2. §SPV envelope — add at the end of the section
+
+> `rawTx` is hex, and `blockHash` is hex in display order, like `txid`. In the `"TSC"` format the entries of `merkleProof.nodes` are hex in display order too, and an entry of `"*"` means "duplicate the working hash", the TSC convention for a missing right sibling. The verifier checks that the header it obtained has hash `spv.blockHash` and height `spv.blockHeight`.
+
+---
+
+## What this changes
+
+**For writers, nothing.** Every certificate the reference implementation has issued already
+conforms. The text makes explicit what it writes, so that other implementations can write
+the same.
+
+**For readers, two rules tighten.** A verifier that accepted a certificate of another
+version, or decoded base64 by skipping what it did not recognise, refuses instead. Neither
+rule refuses anything a conformant writer produces.
+
+The canonical proof bytes, `proofHash`, the on-chain record and the verification steps are
+untouched.
+
+---
+
+## Decisions
+
+The first draft left six points to the author. Each is decided here, with the reason.
+
+1. **A verifier refuses a `version` it does not implement.** This is in the proposed text.
+   The reference wrote `"1.0"` and read anything: a certificate saying `"2.0"` passed its
+   schema, its offline verifier, its SPV check and its anchor match. Reading a future
+   format with v1 rules gives a verdict about the wrong thing, and a spec that says nothing
+   lets every verifier do that. The reference implementation adopts the rule;
+   `@smartledger/bsv` has applied it since 9.9.0.
+2. **A reader refuses base64 that is not base64.** This is in the proposed text. The
+   reference decoded with Node's `Buffer.from`, which skips characters outside the alphabet
+   and truncates an impossible length, so a corrupted field became different bytes rather
+   than an error. That happened at the reference's own request intake too: a notarize
+   request with junk spliced into its base64 key was anchored with the junk dropped. The
+   URL-safe alphabet and missing padding stay acceptable, because both are unambiguous and
+   refusing them would gain nothing. The reference implementation adopts the rule;
+   `@smartledger/bsv` has refused bad characters since 9.9.0, and impossible lengths since
+   9.10.0.
+3. **Hex is written lowercase and unprefixed; upper case and `0x` MAY be read.** This is in
+   the proposed text. Both forms are unambiguous, and the reference already reads them.
+4. **`network` has two defined names and is descriptive.** This is in the proposed text.
+   `"bsv-mainnet"` is what the reference writes. `"bsv-testnet"` is reserved, so that
+   testnet certificates do not acquire ad-hoc names. It is not a closed set a verifier must
+   enforce. The block header the verifier obtains already fixes which chain the anchor is
+   on, so a mislabelled `network` cannot make a certificate verify anywhere it is not
+   anchored.
+5. **Certificates already issued in other shapes stay out of the spec.** The table above
+   is one implementation's history. That implementation's readers handle it:
+   `@smartledger/bsv` reads those certificates and reports them as legacy. A clause in the
+   spec would bind every other implementation to the same history.
+6. **High-S ECDSA is accepted.** This is in the proposed text, as the reference behaves.
+   Requiring low-S would reject certificates the reference has already issued, and
+   `proofHash` already stops the malleated form from being passed off as the same
+   certificate.
+
+---
+
+## Checking the claims
+
+```
+npx mocha test/notaryhash/fields_amendment.js test/notaryhash/reference_certs.js
+```
+
+The first reads the examples out of this document and checks them against the reference's
+own certificates. It also checks that `@smartledger/bsv` applies the reader rules the text
+states. The second verifies all ten reference certificates and rebuilds each one byte for
+byte from its proof fields, using the values defined here.

package/docs/BRC220_ENCODING_AMENDMENT.md

@@ -1,100 +1,40 @@
-# 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.
+# Withdrawn: proposed BRC-220 `encoding` amendment
+
+**This proposal was wrong and has been withdrawn. It was never filed.**
+
+It proposed defining the certificate's `encoding` field as `"raw"` or `"der"` — the
+signature's byte format — and requiring ECDSA signatures to be low-S, with a 33-byte
+compressed public key. It was written from this library's implementation alone.
+
+Checked against the BRC-220 reference implementation before filing, it contradicted
+it on every point:
+
+| | this proposal | reference implementation |
+| --- | --- | --- |
+| `encoding` means | the signature's byte format | how `publicKey` and `signature` are written into the JSON |
+| `encoding` values | `"raw"`, `"der"` | `"hex"`, `"base64"` |
+| signature bytes | 64-byte `r ‖ s` only, DER discouraged | 64-byte `r ‖ s` or DER, told apart by the bytes |
+| high-S signatures | rejected | accepted, deliberately |
+| public keys | 33-byte compressed | 33-byte compressed or 65-byte uncompressed |
+
+Every certificate the reference service has issued uses `"hex"` or `"base64"`. Filing
+this would have proposed a spec change incompatible with all of them.
+
+It also exposed that `@smartledger/bsv` 8.3.0–9.8.0 could not verify a single
+certificate the reference issued: its `version`, `mode`, `encoding`, `anchor` and batch
+`path` fields all differed. The library now reads both formats, and
+writes the reference one given `format: 'reference'` — the default from 10.0.0. See
+`lib/notaryhash/certificate.js`.
+
+## What is still true
+
+The gap this draft set out to close is real: BRC-220 lists `encoding` as a required field
+and never enumerates its values, and says nothing about the JSON form of `version`,
+`mode`, `anchor` or the batch `path`. A clarification defining those fields **as the
+reference writes them** is a separate proposal, drafted in
+[BRC220_CERTIFICATE_FIELDS_AMENDMENT.md](BRC220_CERTIFICATE_FIELDS_AMENDMENT.md).
+
+The batch-leaf clarification written alongside this one was correct, and was confirmed
+against the reference implementation: it was filed as
+[bsv-blockchain/BRCs#246](https://github.com/bsv-blockchain/BRCs/pull/246). See
+[BRC220_BATCH_LEAF_AMENDMENT.md](BRC220_BATCH_LEAF_AMENDMENT.md).

package/docs/BRC220_PLAN.md

@@ -173,45 +173,44 @@ summarising rather than anything in the document.
 - **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`.
+- **The batch Merkle leaf is NOT settled by the spec.** §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`; so does the reference implementation's batcher, and given the same five
+  proofs it builds the same root. Reading it as `canonicalBytes` is equally sound and
+  produces a different root, so the two do not interoperate. Filed upstream as
+  [bsv-blockchain/BRCs#246](https://github.com/bsv-blockchain/BRCs/pull/246); see
+  [BRC220_BATCH_LEAF_AMENDMENT.md](BRC220_BATCH_LEAF_AMENDMENT.md), enforced in
+  `test/notaryhash/batch_leaf.js`.
 - **`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:
+Decided here, then reversed against the reference implementation:
 
-- **`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`.
+- **`encoding` was defined as `"raw"` — the signature's byte format — and low-S was
+  required.** Both were wrong. The spec requires the field without enumerating its values,
+  and 8.3.0–9.8.0 filled that gap from this library's own reasoning: raw `r ‖ s` because DER
+  is not canonical, low-S because `s` and `n − s` both verify and hash differently.
 
-  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 reference implementation, which is what issued certificates are checked against,
+  decided otherwise on every point. `encoding` is `"hex"` or `"base64"` — how `publicKey`
+  and `signature` are written into the JSON, not what their bytes are. A signature may be
+  64-byte `r ‖ s` or DER, told apart by the bytes. A public key may be compressed or
+  uncompressed. High-S is accepted deliberately.
 
-  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`.
+  The reasoning behind the reversal holds: `proofHash` covers the signature bytes exactly
+  as the signer produced them, so a DER or malleated form is a *different* certificate,
+  not a forgery of this one. What the original argument protected against — two
+  certificates for one signing act — is real, but it is the issuer's choice to make, and
+  every certificate still commits to exactly one form.
 
-  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 library now reads both formats and writes the reference one given
+  `format: 'reference'`. Per STABILITY.md the default stays the old format through 9.x,
+  with a one-time notice, and becomes 'reference' in 10.0.0. The proposed amendment
+  (`docs/BRC220_ENCODING_AMENDMENT.md`) was withdrawn before filing.
 
 ### The reference implementation
 
@@ -220,10 +219,16 @@ Decided, and proposed back to the spec:
 `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.
+Those vectors are worth more than anything in §6. 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.
+
+That is exactly how it went. Until the reference was checked, every test here passed and
+this library could not verify one certificate the reference had issued: the cryptography
+agreed and the JSON did not. `test/notaryhash/reference_certs.js` now verifies certificates
+the reference produced — full and hybrid, hex and base64, DER, high-S, an uncompressed key,
+and a five-leaf batch — and rebuilds each one byte for byte.
 
 ## 8. Not in scope