@smartledger/bsv 9.8.0 → 9.10.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (28) hide show
  1. package/CHANGELOG.md +129 -0
  2. package/README.md +19 -19
  3. package/bsv-gdaf.min.js +59 -59
  4. package/bsv-smartcontract.min.js +1 -1
  5. package/bsv.bundle.js +59 -59
  6. package/bsv.d.ts +345 -0
  7. package/bsv.min.js +59 -59
  8. package/docs/AUDIT_SCOPE.md +6 -6
  9. package/docs/BRC220_BATCH_LEAF_AMENDMENT.md +23 -8
  10. package/docs/BRC220_CERTIFICATE_FIELDS_AMENDMENT.md +246 -0
  11. package/docs/BRC220_ENCODING_AMENDMENT.md +40 -100
  12. package/docs/BRC220_PLAN.md +39 -34
  13. package/docs/MODULE_REFERENCE_COMPLETE.md +27 -27
  14. package/docs/advanced/UTXO_MANAGER_GUIDE.md +1 -1
  15. package/docs/audit-rfq/cure53.txt +1 -1
  16. package/docs/audit-rfq/ncc-group.txt +1 -1
  17. package/docs/audit-rfq/trail-of-bits.txt +1 -1
  18. package/docs/getting-started/INSTALLATION.md +23 -23
  19. package/docs/getting-started/QUICK_START.md +7 -7
  20. package/docs/migration/FROM_BSV_1_5_6.md +5 -5
  21. package/lib/notaryhash/certificate.js +528 -79
  22. package/lib/notaryhash/index.js +110 -71
  23. package/lib/notaryhash/merkle.js +94 -0
  24. package/lib/notaryhash/script.js +8 -1
  25. package/lib/notaryhash/suites.js +17 -14
  26. package/package.json +1 -1
  27. package/tools/gen-brc220-batch-vector.js +7 -3
  28. package/version.js +1 -1
package/CHANGELOG.md CHANGED
@@ -7,6 +7,135 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
7
7
 
8
8
  ## [Unreleased]
9
9
 
10
+ ## [9.10.0] - 2026-09-11
11
+
12
+ **NotaryHash refuses base64 that is not base64, can check a header's height, and its
13
+ certificate fields are proposed for BRC-220.** Everything here is additive or refuses only
14
+ malformed input: nothing that verified in 9.9.0 stops verifying.
15
+
16
+ ### Fixed — NotaryHash reads base64 strictly, and can check a header's height
17
+
18
+ `Certificate.decodeBytes` refuses a base64 length that no byte string encodes, and padding
19
+ anywhere but the end. `Buffer.from` drops a trailing character that cannot complete a byte,
20
+ so `"AAAAA"` decoded to three bytes instead of failing — the same corruption-as-decoding
21
+ that 9.9.0 already refused for characters outside the alphabet. Everything a writer
22
+ produces, in either alphabet and with or without padding, is still accepted.
23
+
24
+ `verify()` and `verifyAnchorSPV()` take an optional `height`. BRC-220 anchors a certificate
25
+ in "the block header for `spv.blockHash` at `spv.blockHeight`", and an 80-byte header does
26
+ not carry its height, so until now the height could not be checked at all. A caller that
27
+ obtained the header at a known height passes it, and a mismatch fails the anchor. It is
28
+ optional because requiring it would break every caller that holds only the header.
29
+
30
+ ### Docs
31
+
32
+ - `docs/BRC220_CERTIFICATE_FIELDS_AMENDMENT.md`: a BRC-220 amendment defining the
33
+ certificate's field values as the reference implementation writes them, and two rules
34
+ for reading them. BRC-220 names the twelve required fields and defines none of their
35
+ values, which is how 8.3.0–9.8.0 and the reference came to be unable to read each
36
+ other's certificates. Filed as
37
+ [bsv-blockchain/BRCs#247](https://github.com/bsv-blockchain/BRCs/pull/247).
38
+ `test/notaryhash/fields_amendment.js` checks its examples against certificates the
39
+ reference produced, and checks that this library does what each reader rule says.
40
+ - `docs/BRC220_BATCH_LEAF_AMENDMENT.md` says that `leafIndex` counts from 0, and how `i`
41
+ is written in the batch vector's preimages. Review of
42
+ [bsv-blockchain/BRCs#246](https://github.com/bsv-blockchain/BRCs/pull/246) asked for
43
+ both, and #246 now carries them too. The vector's values are unchanged.
44
+
45
+ ## [9.9.0] - 2026-09-11
46
+
47
+ **NotaryHash interoperates with the BRC-220 reference implementation, without breaking
48
+ anything in 9.x.** Verification reads both certificate formats. `Certificate.build()`
49
+ writes the reference format given `format: 'reference'`; without it, it still writes
50
+ exactly what 9.8.0 wrote and warns once, as STABILITY.md requires. Against v9.8.0 the
51
+ public API gains 13 names and changes or removes none.
52
+
53
+ ### Fixed — NotaryHash verifies the certificates the BRC-220 reference implementation issues
54
+
55
+ 8.3.0 through 9.8.0 could not verify a single certificate the BRC-220 reference
56
+ implementation issued: `NotaryHash.verify` rejected every one with `unsupported version:
57
+ 1.0`, and the reference could not read this library's either. The cryptography agreed
58
+ throughout — `proofHash`, the signature digest, the RFC 6962 tree and the on-chain record
59
+ are byte-identical — and only the JSON differed. BRC-220 lists a certificate's required
60
+ fields but not their values, and 8.3.0 filled that gap from this implementation alone.
61
+ Every test passed, because every test built its certificates here.
62
+
63
+ | field | 8.3.0–9.8.0 format | reference format |
64
+ | --- | --- | --- |
65
+ | `version` | `1` | `"1.0"` |
66
+ | `mode` | `0` / `1` / `2` | `"full"` / `"hybrid"` |
67
+ | a batch | `mode: 2` | `anchor.type: "batch"`; the mode stays full or hybrid |
68
+ | `encoding` | `"raw"` / `"der"` — the signature's byte form | `"hex"` / `"base64"` — how `publicKey` and `signature` are written |
69
+ | `anchor` | `{ txid, blockHeight }` | `{ type, network, txid, vout, blockHeight, blockTime }` |
70
+ | `merkle.path` | bare hashes | `{ hash, side }`, leaf upward |
71
+
72
+ Verification now reads both formats — `verify()` reports `legacy: true` for the old one —
73
+ and accepts what the reference accepts, each of which 9.8.0 refused:
74
+
75
+ - **High-S ECDSA signatures.** The reference accepts them deliberately. It is safe:
76
+ `proofHash` covers the exact signature bytes, so the malleated form of a signature is a
77
+ *different* certificate, never a forgery of this one — a test asserts exactly that.
78
+ - **DER signatures**, told apart from 64-byte `r ‖ s` by the bytes, and **65-byte
79
+ uncompressed public keys**.
80
+ - **Base64 fields**, including the URL-safe alphabet and missing padding, as the
81
+ reference's `Buffer.from` reads them. Characters outside the alphabet are refused, where
82
+ `Buffer.from` would skip them and decode a corrupted field to different bytes.
83
+ - **A merkle proof on a direct anchor** is checked when present, as the reference checks
84
+ it: accepted if it folds to its stated root, refused if not.
85
+
86
+ One check is added: the supplied header must be the block `spv.blockHash` names. A header
87
+ the proof folds to that is some other block left the certificate's own statement of where
88
+ it was mined unchecked. The reference checks the same. A certificate that passed 9.8.0
89
+ fails it only if its `spv.blockHash` names a different block from the header supplied.
90
+
91
+ ### Deprecated — the default format of `NotaryHash.Certificate.build()`
92
+
93
+ `build()` takes a `format`. `'reference'` (`NotaryHash.Certificate.FORMAT.REFERENCE`)
94
+ writes the reference format; `'legacy'` writes the 8.3.0–9.8.0 one. Omitting it writes the
95
+ legacy format — byte for byte what 9.8.0 wrote, pinned by test against certificates the
96
+ 9.8.0 code itself built — and warns once. **The default becomes `'reference'` in 10.0.0.**
97
+
98
+ ```js
99
+ NotaryHash.Certificate.build({ ...params, format: 'reference' })
100
+ // { version: '1.0', mode: 'full', encoding: 'hex', anchor: { type: 'direct', … }, … }
101
+ ```
102
+
103
+ Per STABILITY.md this is a minor, so what `build()` returns does not change in 9.x, and
104
+ code reading `cert.mode === NotaryHash.MODE.FULL` keeps working. It is the shape of the
105
+ LTP claim canonicalization in 9.2.0, for a similar reason: the default is deterministic and
106
+ agrees with itself, and is not interoperable. The cost here is immediate rather than
107
+ latent — no other BRC-220 verifier can check a default-built certificate — so pass
108
+ `format: 'reference'` for anything issued to someone else. An unrecognised `format` throws
109
+ rather than falling back.
110
+
111
+ `Certificate.VERSION` is still `1`, what the default writes; `Certificate.REFERENCE_VERSION`
112
+ is `'1.0'`. `Certificate.ENCODING` gains `HEX` and `BASE64` beside `RAW` and `DER`.
113
+
114
+ ### Added
115
+
116
+ - `test/notaryhash/reference_certs.js`, over ten certificates produced by the reference
117
+ implementation's own code — full and hybrid, hex and base64, a DER signature, a high-S
118
+ signature, an uncompressed key, and a five-leaf batch. Each verifies here, and each is
119
+ rebuilt byte for byte by `Certificate.build({ format: 'reference' })`. The reference's
120
+ batch is the same tree as the BRC-220 batch vector: same root, same paths.
121
+ - `test/data/notaryhash-9.8.0-certs.json`: certificates built by the 9.8.0 code, which the
122
+ 9.x default must reproduce exactly.
123
+ - `Certificate.FORMAT`, `REFERENCE_VERSION`, `MODE`, `ANCHOR_TYPE`, `DEFAULT_NETWORK`,
124
+ `isLegacy`, `normalize`, `decodeBytes` and `toProofInput`; `Merkle.auditPath`,
125
+ `pathSides`, `rootFromPath` and `verifyAuditPath` for the sided path form.
126
+ - `bsv.d.ts` declares `NotaryHash` in full, with `build()` overloaded on `format`. It was
127
+ 48 of 56 names undeclared, so it could not be used from TypeScript at all; the
128
+ declaration gate now holds it at zero.
129
+
130
+ ### Docs
131
+
132
+ - `docs/BRC220_ENCODING_AMENDMENT.md` is **withdrawn**. It proposed `"raw"`/`"der"` and
133
+ mandatory low-S; the reference contradicts it on every point. It was never filed.
134
+ - `docs/BRC220_BATCH_LEAF_AMENDMENT.md` was confirmed against the reference and filed as
135
+ [bsv-blockchain/BRCs#246](https://github.com/bsv-blockchain/BRCs/pull/246).
136
+ - `test/data/brc220-batch-vector.json` records `encoding: "hex"` and sided paths. The root,
137
+ the rejected-reading root, and every `proofHash` and signature are unchanged.
138
+
10
139
  ## [9.8.0] - 2026-09-08
11
140
 
12
141
  **No runtime change.** `git diff v9.7.0..HEAD -- lib/` is empty. Four bundles do differ,
package/README.md CHANGED
@@ -2,7 +2,7 @@
2
2
 
3
3
  Bitcoin SV library with an interpreter-verified script engine.
4
4
 
5
- [![Version](https://img.shields.io/badge/version-9.8.0-blue.svg)](https://www.npmjs.com/package/@smartledger/bsv)
5
+ [![Version](https://img.shields.io/badge/version-9.10.0-blue.svg)](https://www.npmjs.com/package/@smartledger/bsv)
6
6
  [![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
7
7
  [![Stability](https://img.shields.io/badge/9.x%20stable%20until-2027--09--01-brightgreen.svg)](STABILITY.md)
8
8
 
@@ -155,44 +155,44 @@ const bsv = require('@smartledger/bsv') // 128 modules
155
155
  ### **Core Modules**
156
156
  | Module | Size | Use Case | CDN |
157
157
  |--------|------|----------|-----|
158
- | **bsv.min.js** | 1046KB | Core BSV + SmartContract | `unpkg.com/@smartledger/bsv@9.8.0/bsv.min.js` |
159
- | **bsv.bundle.js** | 1046KB | Everything in one file | `unpkg.com/@smartledger/bsv@9.8.0/bsv.bundle.js` |
158
+ | **bsv.min.js** | 1056KB | Core BSV + SmartContract | `unpkg.com/@smartledger/bsv@9.10.0/bsv.min.js` |
159
+ | **bsv.bundle.js** | 1056KB | Everything in one file | `unpkg.com/@smartledger/bsv@9.10.0/bsv.bundle.js` |
160
160
 
161
161
  ### **W3C Verifiable Credentials**
162
162
  | Module | Size | Use Case | CDN |
163
163
  |--------|------|----------|-----|
164
- | **🟢 bsv-didweb.min.js** | 166KB | **DID:web generation** | `unpkg.com/@smartledger/bsv@9.8.0/bsv-didweb.min.js` |
165
- | **🟢 bsv-vcjwt.min.js** | 166KB | **VC-JWT issue/verify** | `unpkg.com/@smartledger/bsv@9.8.0/bsv-vcjwt.min.js` |
166
- | **🟢 bsv-statuslist.min.js** | 256KB | **StatusList2021 revocation** | `unpkg.com/@smartledger/bsv@9.8.0/bsv-statuslist.min.js` |
167
- | **🟢 bsv-anchor.min.js** | 164KB | **BSV anchoring (hash-only)** | `unpkg.com/@smartledger/bsv@9.8.0/bsv-anchor.min.js` |
164
+ | **🟢 bsv-didweb.min.js** | 166KB | **DID:web generation** | `unpkg.com/@smartledger/bsv@9.10.0/bsv-didweb.min.js` |
165
+ | **🟢 bsv-vcjwt.min.js** | 166KB | **VC-JWT issue/verify** | `unpkg.com/@smartledger/bsv@9.10.0/bsv-vcjwt.min.js` |
166
+ | **🟢 bsv-statuslist.min.js** | 256KB | **StatusList2021 revocation** | `unpkg.com/@smartledger/bsv@9.10.0/bsv-statuslist.min.js` |
167
+ | **🟢 bsv-anchor.min.js** | 164KB | **BSV anchoring (hash-only)** | `unpkg.com/@smartledger/bsv@9.10.0/bsv-anchor.min.js` |
168
168
 
169
169
  ### **Smart Contract & Development**
170
170
  | Module | Size | Use Case | CDN |
171
171
  |--------|------|----------|-----|
172
- | **bsv-smartcontract.min.js** | 141KB | Complete covenant framework | `unpkg.com/@smartledger/bsv@9.8.0/bsv-smartcontract.min.js` |
173
- | **bsv-covenant.min.js** | 35KB | Covenant operations | `unpkg.com/@smartledger/bsv@9.8.0/bsv-covenant.min.js` |
174
- | **bsv-script-helper.min.js** | 33KB | Custom script tools | `unpkg.com/@smartledger/bsv@9.8.0/bsv-script-helper.min.js` |
175
- | **bsv-security.min.js** | 32KB | Security enhancements | `unpkg.com/@smartledger/bsv@9.8.0/bsv-security.min.js` |
172
+ | **bsv-smartcontract.min.js** | 141KB | Complete covenant framework | `unpkg.com/@smartledger/bsv@9.10.0/bsv-smartcontract.min.js` |
173
+ | **bsv-covenant.min.js** | 35KB | Covenant operations | `unpkg.com/@smartledger/bsv@9.10.0/bsv-covenant.min.js` |
174
+ | **bsv-script-helper.min.js** | 33KB | Custom script tools | `unpkg.com/@smartledger/bsv@9.10.0/bsv-script-helper.min.js` |
175
+ | **bsv-security.min.js** | 32KB | Security enhancements | `unpkg.com/@smartledger/bsv@9.10.0/bsv-security.min.js` |
176
176
 
177
177
  ### **Legal & Compliance**
178
178
  | Module | Size | Use Case | CDN |
179
179
  |--------|------|----------|-----|
180
- | **bsv-ltp.min.js** | 540KB | Legal Token Protocol | `unpkg.com/@smartledger/bsv@9.8.0/bsv-ltp.min.js` |
181
- | **bsv-gdaf.min.js** | 1046KB | Digital Identity & Attestation | `unpkg.com/@smartledger/bsv@9.8.0/bsv-gdaf.min.js` |
180
+ | **bsv-ltp.min.js** | 540KB | Legal Token Protocol | `unpkg.com/@smartledger/bsv@9.10.0/bsv-ltp.min.js` |
181
+ | **bsv-gdaf.min.js** | 1056KB | Digital Identity & Attestation | `unpkg.com/@smartledger/bsv@9.10.0/bsv-gdaf.min.js` |
182
182
 
183
183
  ### **Advanced Cryptography**
184
184
  | Module | Size | Use Case | CDN |
185
185
  |--------|------|----------|-----|
186
- | **bsv-shamir.min.js** | 177KB | Threshold Cryptography | `unpkg.com/@smartledger/bsv@9.8.0/bsv-shamir.min.js` |
186
+ | **bsv-shamir.min.js** | 177KB | Threshold Cryptography | `unpkg.com/@smartledger/bsv@9.10.0/bsv-shamir.min.js` |
187
187
 
188
188
  ### **Utilities**
189
189
  | Module | Size | Use Case | CDN |
190
190
  |--------|------|----------|-----|
191
- | **bsv-ecies.min.js** | 137KB | Encryption | `unpkg.com/@smartledger/bsv@9.8.0/bsv-ecies.min.js` |
192
- | **bsv-message.min.js** | 34KB | Message signing | `unpkg.com/@smartledger/bsv@9.8.0/bsv-message.min.js` |
193
- | **bsv-mnemonic.min.js** | 320KB | HD wallets | `unpkg.com/@smartledger/bsv@9.8.0/bsv-mnemonic.min.js` |
191
+ | **bsv-ecies.min.js** | 137KB | Encryption | `unpkg.com/@smartledger/bsv@9.10.0/bsv-ecies.min.js` |
192
+ | **bsv-message.min.js** | 34KB | Message signing | `unpkg.com/@smartledger/bsv@9.10.0/bsv-message.min.js` |
193
+ | **bsv-mnemonic.min.js** | 320KB | HD wallets | `unpkg.com/@smartledger/bsv@9.10.0/bsv-mnemonic.min.js` |
194
194
  ```html
195
- <script src="https://unpkg.com/@smartledger/bsv@9.8.0/bsv.min.js"></script>
195
+ <script src="https://unpkg.com/@smartledger/bsv@9.10.0/bsv.min.js"></script>
196
196
  <script>
197
197
  const key = bsv.PrivateKey.fromRandom()
198
198
  </script>
@@ -240,4 +240,4 @@ MIT
240
240
 
241
241
  ---
242
242
 
243
- **SmartLedger-BSV v9.8.0**
243
+ **SmartLedger-BSV v9.10.0**