@smartledger/bsv 9.7.0 → 9.9.0

package/CHANGELOG.md

@@ -7,6 +7,223 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [9.9.0] - 2026-09-11
+
+**NotaryHash interoperates with the BRC-220 reference implementation, without breaking
+anything in 9.x.** Verification reads both certificate formats. `Certificate.build()`
+writes the reference format given `format: 'reference'`; without it, it still writes
+exactly what 9.8.0 wrote and warns once, as STABILITY.md requires. Against v9.8.0 the
+public API gains 13 names and changes or removes none.
+
+### Fixed — NotaryHash verifies the certificates the BRC-220 reference implementation issues
+
+8.3.0 through 9.8.0 could not verify a single certificate the BRC-220 reference
+implementation issued: `NotaryHash.verify` rejected every one with `unsupported version:
+1.0`, and the reference could not read this library's either. The cryptography agreed
+throughout — `proofHash`, the signature digest, the RFC 6962 tree and the on-chain record
+are byte-identical — and only the JSON differed. BRC-220 lists a certificate's required
+fields but not their values, and 8.3.0 filled that gap from this implementation alone.
+Every test passed, because every test built its certificates here.
+
+| field | 8.3.0–9.8.0 format | reference format |
+| --- | --- | --- |
+| `version` | `1` | `"1.0"` |
+| `mode` | `0` / `1` / `2` | `"full"` / `"hybrid"` |
+| a batch | `mode: 2` | `anchor.type: "batch"`; the mode stays full or hybrid |
+| `encoding` | `"raw"` / `"der"` — the signature's byte form | `"hex"` / `"base64"` — how `publicKey` and `signature` are written |
+| `anchor` | `{ txid, blockHeight }` | `{ type, network, txid, vout, blockHeight, blockTime }` |
+| `merkle.path` | bare hashes | `{ hash, side }`, leaf upward |
+
+Verification now reads both formats — `verify()` reports `legacy: true` for the old one —
+and accepts what the reference accepts, each of which 9.8.0 refused:
+
+- **High-S ECDSA signatures.** The reference accepts them deliberately. It is safe:
+  `proofHash` covers the exact signature bytes, so the malleated form of a signature is a
+  *different* certificate, never a forgery of this one — a test asserts exactly that.
+- **DER signatures**, told apart from 64-byte `r ‖ s` by the bytes, and **65-byte
+  uncompressed public keys**.
+- **Base64 fields**, including the URL-safe alphabet and missing padding, as the
+  reference's `Buffer.from` reads them. Characters outside the alphabet are refused, where
+  `Buffer.from` would skip them and decode a corrupted field to different bytes.
+- **A merkle proof on a direct anchor** is checked when present, as the reference checks
+  it: accepted if it folds to its stated root, refused if not.
+
+One check is added: the supplied header must be the block `spv.blockHash` names. A header
+the proof folds to that is some other block left the certificate's own statement of where
+it was mined unchecked. The reference checks the same. A certificate that passed 9.8.0
+fails it only if its `spv.blockHash` names a different block from the header supplied.
+
+### Deprecated — the default format of `NotaryHash.Certificate.build()`
+
+`build()` takes a `format`. `'reference'` (`NotaryHash.Certificate.FORMAT.REFERENCE`)
+writes the reference format; `'legacy'` writes the 8.3.0–9.8.0 one. Omitting it writes the
+legacy format — byte for byte what 9.8.0 wrote, pinned by test against certificates the
+9.8.0 code itself built — and warns once. **The default becomes `'reference'` in 10.0.0.**
+
+```js
+NotaryHash.Certificate.build({ ...params, format: 'reference' })
+// { version: '1.0', mode: 'full', encoding: 'hex', anchor: { type: 'direct', … }, … }
+```
+
+Per STABILITY.md this is a minor, so what `build()` returns does not change in 9.x, and
+code reading `cert.mode === NotaryHash.MODE.FULL` keeps working. It is the shape of the
+LTP claim canonicalization in 9.2.0, for a similar reason: the default is deterministic and
+agrees with itself, and is not interoperable. The cost here is immediate rather than
+latent — no other BRC-220 verifier can check a default-built certificate — so pass
+`format: 'reference'` for anything issued to someone else. An unrecognised `format` throws
+rather than falling back.
+
+`Certificate.VERSION` is still `1`, what the default writes; `Certificate.REFERENCE_VERSION`
+is `'1.0'`. `Certificate.ENCODING` gains `HEX` and `BASE64` beside `RAW` and `DER`.
+
+### Added
+
+- `test/notaryhash/reference_certs.js`, over ten certificates produced by the reference
+  implementation's own code — full and hybrid, hex and base64, a DER signature, a high-S
+  signature, an uncompressed key, and a five-leaf batch. Each verifies here, and each is
+  rebuilt byte for byte by `Certificate.build({ format: 'reference' })`. The reference's
+  batch is the same tree as the BRC-220 batch vector: same root, same paths.
+- `test/data/notaryhash-9.8.0-certs.json`: certificates built by the 9.8.0 code, which the
+  9.x default must reproduce exactly.
+- `Certificate.FORMAT`, `REFERENCE_VERSION`, `MODE`, `ANCHOR_TYPE`, `DEFAULT_NETWORK`,
+  `isLegacy`, `normalize`, `decodeBytes` and `toProofInput`; `Merkle.auditPath`,
+  `pathSides`, `rootFromPath` and `verifyAuditPath` for the sided path form.
+- `bsv.d.ts` declares `NotaryHash` in full, with `build()` overloaded on `format`. It was
+  48 of 56 names undeclared, so it could not be used from TypeScript at all; the
+  declaration gate now holds it at zero.
+
+### Docs
+
+- `docs/BRC220_ENCODING_AMENDMENT.md` is **withdrawn**. It proposed `"raw"`/`"der"` and
+  mandatory low-S; the reference contradicts it on every point. It was never filed.
+- `docs/BRC220_BATCH_LEAF_AMENDMENT.md` was confirmed against the reference and filed as
+  [bsv-blockchain/BRCs#246](https://github.com/bsv-blockchain/BRCs/pull/246).
+- `test/data/brc220-batch-vector.json` records `encoding: "hex"` and sided paths. The root,
+  the rejected-reading root, and every `proofHash` and signature are unchanged.
+
+## [9.8.0] - 2026-09-08
+
+**No runtime change.** `git diff v9.7.0..HEAD -- lib/` is empty. Four bundles do differ,
+which looks like a contradiction and is not: reverting `version.js` alone and rebuilding
+reproduces all four **byte-identical to the v9.7.0 release**, so the embedded version
+string is the only changed input and the shifted minifier identifiers are a
+deterministic consequence of it.
+
+This release exists because the two things it corrects both ship in the tarball and
+reach nobody until they are published. `bsv.d.ts` is the package's `types` entry, and
+`docs/` is in `files[]`. On 9.7.0 this is a compile error in three places:
+
+```ts
+const i = new bsv.Script.Interpreter()          // TS7009: no construct signature
+const w = i.maxScriptNumLength()
+const f = I.mainnetFlags() | I.SCRIPT_UTXO_AFTER_GENESIS   // TS2339: does not exist
+const n = new bsv.crypto.BN(0)                  // TS2554: expected 0 arguments
+```
+
+### Fixed — `docs/preimage.md` was wrong in ways that cost money
+
+The page ships in the npm tarball and is linked from the README, and people build
+covenants from it. It gave the preimage as **~108 bytes** when it is 182 — 156 fixed
+plus a length-prefixed `scriptCode` — and its own arithmetic said 181 because it
+counted a 25-byte script without the varint that precedes it.
+
+Every byte offset from the txid onward was wrong. `outpoint.txid` was labelled 32
+bytes over a 28-byte range, and everything after it shifted by three or four:
+`hashOutputs` was given as starting at 139 when it starts at 142.
+
+**Four of its seven Script fragments did not work**, run against a real preimage:
+
+| fragment | result |
+| --- | --- |
+| `hashPrevouts`: `4 OP_SPLIT OP_DROP 32 OP_SPLIT OP_DROP` | `SCRIPT_ERR_INVALID_SPLIT_RANGE` — `OP_DROP` keeps the wrong half |
+| `hashOutputs`: `<len-44>` | reads `nSequence` and the first 28 bytes of the hash |
+| `amount`: `40 OP_SPLIT` | a literal offset landing inside `hashPrevouts` |
+| `nSequence`: `12 OP_SPLIT` | likewise |
+
+It showed `hashSequence` as `00…00` for an ordinary `0x41` signature. It is only zero
+under `ANYONECANPAY`, `NONE` or `SINGLE`, and the page now carries the measured table
+for all five combinations — which matters, because a covenant reading `hashOutputs`
+without pinning the sighash type is checking 32 zero bytes.
+
+And it recommended `OP_BIN2NUM` on `amount`, `nSequence` and `nLockTime`, which are
+**unsigned**. That is the defect fixed in 9.4.0, recommended as practice:
+
+```
+nLockTime  ffffffff  ->  -2147483647   should be 4294967295 (year 2106)
+           01000080  ->           -1   should be 2147483649
+           00000080  ->            0   should be 2147483648 (19 Jan 2038)
+```
+
+`nSequence` is `0xffffffff` more often than not, so that one is wrong today rather
+than in 2038.
+
+Two things the page said that were not merely inaccurate but backwards:
+
+- **"Re-hash the preimage (`OP_HASH256`) to verify it matches what was signed."** It
+  does not. `OP_HASH256` yields a hash and nothing else; a spender can supply any 182
+  well-formed bytes, satisfy every field check, and spend on a different transaction.
+  The binding comes from `OP_CHECKSIG` over a signature constructed from the preimage
+  hash — which is what `OP_PUSH_TX` does and what the page now describes.
+- **The 32-byte hashes were called "big-endian"**, inviting someone to reverse them.
+  They are the bytes `HASH256()` returns. The only reversed field is the txid inside
+  the outpoint.
+
+Also: `scriptCode` is not "usually `scriptPubKey`" — it is variable, `OP_CODESEPARATOR`
+moves it, and covenant scripts make it hundreds of bytes, which is why every extraction
+this library ships reads from the END of the preimage rather than by absolute offset.
+The page now says so and gives the from-end offsets: `amount` 52, `nSequence` 44,
+`hashOutputs` 40, `nLockTime` 8, `sighashType` 4.
+
+It opens with the Chronicle caveat, since BIP-143 is no longer the only digest
+algorithm on this chain.
+
+**`test/covenant/preimage_doc.js` asserts the page** — 24 cases covering every offset,
+every fragment, the zero-hash table, the `OP_BIN2NUM` figures and the authentication
+claim, all against a preimage the library actually produces. Reintroducing the old
+`hashOutputs` offset of 44 fails it.
+
+### Fixed — the consensus API was uncallable from TypeScript
+
+Everything added across 9.4.0 to 9.7.0 shipped with no declaration. `bsv.d.ts` said
+one thing about the interpreter — a `verify()` returning boolean — so
+`interp.maxScriptNumLength()` was a compile error, the instance had no `errstr` and
+no `stack`, and not one of the era flags existed as a name.
+
+`crypto.BN` was worse: `class BN { }`, an empty declaration. `new BN(0)` did not
+compile and every satoshi amount in the public API widened to `{}`, which is what
+made the interpreter unusable rather than merely undocumented.
+
+Both are now declared in full: the interpreter's twenty instance members and
+fifty-four statics, and BN's constructor, comparisons, arithmetic and the Bitcoin
+codecs (`fromScriptNumBuffer`, `toScriptNumBuffer`, `fromSM`, `toSM`). bn.js's own
+internals — the `red`/`mont` modular-arithmetic family, the in-place `i*` mutators —
+are deliberately left out: they are inherited, not this library's contract.
+
+The declarations are exercised, not just written. `types-test/positive.ts` now
+constructs an interpreter both ways, reads every era method and moves the stack
+ceiling; `negative.ts` gained five cases that must fail, including calling an
+instance method on the constructor and assigning `checkStackLimits()` to a boolean.
+A declaration that quietly degrades to `any` makes those errors vanish.
+
+### Added — `npm run check:dts`, a declaration-coverage ratchet
+
+`check:types` proves the declarations that exist are correct. Nothing measured the
+surface that was never declared at all, which is how four consecutive releases
+shipped an API no TypeScript consumer could call.
+
+`scripts/check-dts-coverage.js` compares `test/fixtures/api-surface.json` against
+`bsv.d.ts` and fails when a name is added to the runtime with no declaration, when a
+name is declared but still sits in the baseline (the ratchet only turns one way), or
+when a namespace listed as COMPLETE develops a gap. `bsv.Script.Interpreter` is the
+first entry in that list, at zero.
+
+Coverage is **934 of 1,946 names, 48.0%**. The remaining 1,012 are recorded in
+`test/fixtures/dts-coverage-baseline.json` so the number is visible rather than
+implied — `bsv.Opcode` and its 110 constants are the largest block left.
+
+The gate's first act was to reject a claim of mine: I listed `crypto.BN` as complete
+and it named the 69 bn.js internals I had not declared.
+
 ## [9.7.0] - 2026-09-05
 
 ### Fixed — the stack limits diverged from the node in both directions

package/README.md

@@ -2,7 +2,7 @@
 
 Bitcoin SV library with an interpreter-verified script engine.
 
-[![Version](https://img.shields.io/badge/version-9.7.0-blue.svg)](https://www.npmjs.com/package/@smartledger/bsv)
+[![Version](https://img.shields.io/badge/version-9.9.0-blue.svg)](https://www.npmjs.com/package/@smartledger/bsv)
 [![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
 [![Stability](https://img.shields.io/badge/9.x%20stable%20until-2027--09--01-brightgreen.svg)](STABILITY.md)
 
@@ -155,44 +155,44 @@ const bsv = require('@smartledger/bsv')                 // 128 modules
 ### **Core Modules**
 | Module | Size | Use Case | CDN |
 |--------|------|----------|-----|
-| **bsv.min.js** | 1046KB | Core BSV + SmartContract | `unpkg.com/@smartledger/bsv@9.7.0/bsv.min.js` |
-| **bsv.bundle.js** | 1046KB | Everything in one file | `unpkg.com/@smartledger/bsv@9.7.0/bsv.bundle.js` |
+| **bsv.min.js** | 1056KB | Core BSV + SmartContract | `unpkg.com/@smartledger/bsv@9.9.0/bsv.min.js` |
+| **bsv.bundle.js** | 1056KB | Everything in one file | `unpkg.com/@smartledger/bsv@9.9.0/bsv.bundle.js` |
 
 ### **W3C Verifiable Credentials**
 | Module | Size | Use Case | CDN |
 |--------|------|----------|-----|
-| **🟢 bsv-didweb.min.js** | 166KB | **DID:web generation** | `unpkg.com/@smartledger/bsv@9.7.0/bsv-didweb.min.js` |
-| **🟢 bsv-vcjwt.min.js** | 166KB | **VC-JWT issue/verify** | `unpkg.com/@smartledger/bsv@9.7.0/bsv-vcjwt.min.js` |
-| **🟢 bsv-statuslist.min.js** | 256KB | **StatusList2021 revocation** | `unpkg.com/@smartledger/bsv@9.7.0/bsv-statuslist.min.js` |
-| **🟢 bsv-anchor.min.js** | 164KB | **BSV anchoring (hash-only)** | `unpkg.com/@smartledger/bsv@9.7.0/bsv-anchor.min.js` |
+| **🟢 bsv-didweb.min.js** | 166KB | **DID:web generation** | `unpkg.com/@smartledger/bsv@9.9.0/bsv-didweb.min.js` |
+| **🟢 bsv-vcjwt.min.js** | 166KB | **VC-JWT issue/verify** | `unpkg.com/@smartledger/bsv@9.9.0/bsv-vcjwt.min.js` |
+| **🟢 bsv-statuslist.min.js** | 256KB | **StatusList2021 revocation** | `unpkg.com/@smartledger/bsv@9.9.0/bsv-statuslist.min.js` |
+| **🟢 bsv-anchor.min.js** | 164KB | **BSV anchoring (hash-only)** | `unpkg.com/@smartledger/bsv@9.9.0/bsv-anchor.min.js` |
 
 ### **Smart Contract & Development**
 | Module | Size | Use Case | CDN |
 |--------|------|----------|-----|
-| **bsv-smartcontract.min.js** | 141KB | Complete covenant framework | `unpkg.com/@smartledger/bsv@9.7.0/bsv-smartcontract.min.js` |
-| **bsv-covenant.min.js** | 35KB | Covenant operations | `unpkg.com/@smartledger/bsv@9.7.0/bsv-covenant.min.js` |
-| **bsv-script-helper.min.js** | 33KB | Custom script tools | `unpkg.com/@smartledger/bsv@9.7.0/bsv-script-helper.min.js` |
-| **bsv-security.min.js** | 32KB | Security enhancements | `unpkg.com/@smartledger/bsv@9.7.0/bsv-security.min.js` |
+| **bsv-smartcontract.min.js** | 141KB | Complete covenant framework | `unpkg.com/@smartledger/bsv@9.9.0/bsv-smartcontract.min.js` |
+| **bsv-covenant.min.js** | 35KB | Covenant operations | `unpkg.com/@smartledger/bsv@9.9.0/bsv-covenant.min.js` |
+| **bsv-script-helper.min.js** | 33KB | Custom script tools | `unpkg.com/@smartledger/bsv@9.9.0/bsv-script-helper.min.js` |
+| **bsv-security.min.js** | 32KB | Security enhancements | `unpkg.com/@smartledger/bsv@9.9.0/bsv-security.min.js` |
 
 ### **Legal & Compliance**
 | Module | Size | Use Case | CDN |
 |--------|------|----------|-----|
-| **bsv-ltp.min.js** | 540KB | Legal Token Protocol | `unpkg.com/@smartledger/bsv@9.7.0/bsv-ltp.min.js` |
-| **bsv-gdaf.min.js** | 1046KB | Digital Identity & Attestation | `unpkg.com/@smartledger/bsv@9.7.0/bsv-gdaf.min.js` |
+| **bsv-ltp.min.js** | 540KB | Legal Token Protocol | `unpkg.com/@smartledger/bsv@9.9.0/bsv-ltp.min.js` |
+| **bsv-gdaf.min.js** | 1056KB | Digital Identity & Attestation | `unpkg.com/@smartledger/bsv@9.9.0/bsv-gdaf.min.js` |
 
 ### **Advanced Cryptography**
 | Module | Size | Use Case | CDN |
 |--------|------|----------|-----|
-| **bsv-shamir.min.js** | 177KB | Threshold Cryptography | `unpkg.com/@smartledger/bsv@9.7.0/bsv-shamir.min.js` |
+| **bsv-shamir.min.js** | 177KB | Threshold Cryptography | `unpkg.com/@smartledger/bsv@9.9.0/bsv-shamir.min.js` |
 
 ### **Utilities**
 | Module | Size | Use Case | CDN |
 |--------|------|----------|-----|
-| **bsv-ecies.min.js** | 137KB | Encryption | `unpkg.com/@smartledger/bsv@9.7.0/bsv-ecies.min.js` |
-| **bsv-message.min.js** | 34KB | Message signing | `unpkg.com/@smartledger/bsv@9.7.0/bsv-message.min.js` |
-| **bsv-mnemonic.min.js** | 320KB | HD wallets | `unpkg.com/@smartledger/bsv@9.7.0/bsv-mnemonic.min.js` |
+| **bsv-ecies.min.js** | 137KB | Encryption | `unpkg.com/@smartledger/bsv@9.9.0/bsv-ecies.min.js` |
+| **bsv-message.min.js** | 34KB | Message signing | `unpkg.com/@smartledger/bsv@9.9.0/bsv-message.min.js` |
+| **bsv-mnemonic.min.js** | 320KB | HD wallets | `unpkg.com/@smartledger/bsv@9.9.0/bsv-mnemonic.min.js` |
 ```html
-<script src="https://unpkg.com/@smartledger/bsv@9.7.0/bsv.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@9.9.0/bsv.min.js"></script>
 <script>
   const key = bsv.PrivateKey.fromRandom()
 </script>
@@ -240,4 +240,4 @@ MIT
 
 ---
 
-**SmartLedger-BSV v9.7.0**
+**SmartLedger-BSV v9.9.0**