@smartledger/bsv 8.3.0 → 9.0.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 (47) hide show
  1. package/CHANGELOG.md +133 -0
  2. package/README.md +374 -222
  3. package/bsv-gdaf.min.js +49 -49
  4. package/bsv-script-helper.min.js +1 -1
  5. package/bsv-smartcontract.min.js +21 -21
  6. package/bsv.bundle.js +49 -49
  7. package/bsv.d.ts +0 -4
  8. package/bsv.min.js +49 -49
  9. package/docs/BRC220_BATCH_LEAF_AMENDMENT.md +194 -0
  10. package/docs/BRC220_PLAN.md +9 -0
  11. package/docs/MODULE_REFERENCE_COMPLETE.md +27 -27
  12. package/docs/README.md +2 -1
  13. package/docs/THREAT_MODEL.md +10 -2
  14. package/docs/advanced/UTXO_MANAGER_GUIDE.md +1 -1
  15. package/docs/getting-started/INSTALLATION.md +23 -23
  16. package/docs/getting-started/QUICK_START.md +7 -7
  17. package/docs/migration/FROM_BSV_1_5_6.md +5 -5
  18. package/index.js +10 -26
  19. package/lib/covenant/helpers.js +34 -35
  20. package/lib/covenant/pushtx.js +2 -2
  21. package/lib/custom-script-helper.js +0 -16
  22. package/lib/notaryhash/index.js +20 -0
  23. package/lib/notaryhash/merkle.js +8 -0
  24. package/lib/notaryhash/suites.js +17 -1
  25. package/lib/ordinals/ordlock.js +1 -1
  26. package/lib/smart_contract/debugger.js +2 -2
  27. package/lib/smart_contract/dsl.js +2 -2
  28. package/lib/smart_contract/index.js +0 -3
  29. package/lib/smart_contract/locks.js +1 -41
  30. package/lib/smart_contract/pels.js +1 -1
  31. package/lib/smart_contract/token.js +1 -1
  32. package/package.json +3 -2
  33. package/test/build/esm_wrapper.js +32 -8
  34. package/test/data/brc220-batch-vector.json +129 -0
  35. package/test/notaryhash/batch_leaf.js +140 -0
  36. package/test/notaryhash/batch_vector.js +282 -0
  37. package/test/notaryhash/interop.js +112 -0
  38. package/test/notaryhash/verify.js +5 -2
  39. package/test/ordinals/inscription.js +24 -14
  40. package/test/ordinals/ordlock.js +0 -46
  41. package/test/smart_contract/covenants.js +0 -38
  42. package/test/smart_contract/dsl_debugger.js +0 -9
  43. package/test/smart_contract/ordinal_transfer.js +0 -10
  44. package/test/smart_contract/sighash_marketplace.js +0 -10
  45. package/test/smart_contract/token_generalized.js +0 -10
  46. package/tools/gen-brc220-batch-vector.js +205 -0
  47. package/version.js +1 -1
package/docs/BRC220_BATCH_LEAF_AMENDMENT.md ADDED
@@ -0,0 +1,194 @@
1
+ # Proposed BRC-220 amendment: define the batch Merkle leaf
2
+
3
+ §On-chain record specifies *which* Merkle tree batch mode uses, but never says what goes
4
+ in a leaf. This proposes the definition, with the reasoning that led to it.
5
+
6
+ Prepared 2026-08-17 while implementing BRC-220 in `@smartledger/bsv`. The second gap of
7
+ this kind, after `encoding` — see [BRC220_ENCODING_AMENDMENT.md](BRC220_ENCODING_AMENDMENT.md).
8
+
9
+ ---
10
+
11
+ ## What the spec currently says
12
+
13
+ §On-chain record, batch (`kind = 2`):
14
+
15
+ > One transaction anchors many proofs under an RFC 6962 Merkle root, domain-separated
16
+ > (`leaf = SHA256(0x00 ‖ d)`, `node = SHA256(0x01 ‖ l ‖ r)`, split at the largest power of
17
+ > two `< n`, last leaf never duplicated).
18
+
19
+ That parenthetical identifies the **tree construction**: domain separation, the split
20
+ rule, and the no-duplication rule that separate RFC 6962 from Bitcoin's tree. `d`, `l` and
21
+ `r` are RFC 6962's own generic symbols — §2.1 of that RFC writes
22
+ `MTH({d(0)}) = SHA-256(0x00 || d(0))` — so the sentence is naming the tree, not defining
23
+ its contents.
24
+
25
+ **`d` is never bound to a value.** The word `canonicalBytes` occurs once in the entire
26
+ document, in the `proofHash` definition in §Canonical proof bytes; it does not appear in
27
+ the batch text. Neither does `proofHash`.
28
+
29
+ So this is an ambiguity, not a disagreement between spec and implementation. Two
30
+ good-faith implementers reading the same sentence can and did reach different answers:
31
+
32
+ | reading | leaf hash |
33
+ | --- | --- |
34
+ | `d` = the canonical proof bytes | `SHA-256(0x00 ‖ canonicalBytes)` |
35
+ | `d` = the proof's identifier | `SHA-256(0x00 ‖ proofHash)` = `SHA-256(0x00 ‖ SHA-256(canonicalBytes))` |
36
+
37
+ Both are second-preimage resistant, and the domain separation that gives RFC 6962 that
38
+ property is unaffected by which one is chosen. **They are equal in strength and produce
39
+ different roots.** A certificate built under one reading fails inclusion under the other,
40
+ with no error that points at the cause — the fold simply does not reach the root.
41
+
42
+ The published test vectors do not settle it: they cover a certificate-with-SPV-envelope
43
+ golden vector, `txidFromRawTx` against the Bitcoin genesis coinbase, and the SPV Merkle
44
+ fold against block 170. **None of them is a batch-mode vector**, so there is nothing to
45
+ conform to by example.
46
+
47
+ ---
48
+
49
+ ## Proposed text
50
+
51
+ Insert into **§On-chain record**, replacing the batch bullet's parenthetical.
52
+
53
+ > - **batch** (`kind = 2`): `"NOTARYHASH" | u8(1) | u8(2) | merkleRoot(32) | u32be(leafCount)`.
54
+ > One transaction anchors many proofs under an RFC 6962 Merkle root.
55
+ >
56
+ > The leaf datum `d` for a proof is its **`proofHash`** — the 32 bytes defined in
57
+ > §Canonical proof bytes — so a leaf is `SHA-256(0x00 ‖ proofHash)` and an internal node
58
+ > is `SHA-256(0x01 ‖ l ‖ r)`. Leaves are ordered as the batch was assembled, and
59
+ > `leafIndex` in the certificate's `merkle` object is that position. The tree splits at
60
+ > the largest power of two `< n` and the last leaf is never duplicated, per RFC 6962
61
+ > §2.1.
62
+ >
63
+ > Note that `d` is the **hash**, not the canonical bytes: a leaf is therefore
64
+ > `SHA-256(0x00 ‖ SHA-256(canonicalBytes))`. The two readings are equally sound
65
+ > cryptographically but produce different roots, so this is stated explicitly rather
66
+ > than left to RFC 6962's generic `d`.
67
+
68
+ ---
69
+
70
+ ## Why `proofHash` rather than the canonical bytes
71
+
72
+ Both are sound. The choice is on other grounds.
73
+
74
+ **A verifier already holds it.** `proofHash` is a required certificate field. A verifier
75
+ checking batch inclusion reads it directly and folds. Under the other reading it must
76
+ first reconstruct `canonicalBytes` — re-serialising `publicKey`, `signature`,
77
+ `createdAtUnix` and the rest with the exact length-prefix framing — before it can begin.
78
+ That is the whole `proofHash` computation, performed again, as a precondition for a check
79
+ that is supposed to be independent of it. The spec advertises a "dependency-light
80
+ standalone verifier"; this keeps the batch path genuinely light.
81
+
82
+ **It is what a batch anchors.** §On-chain record says a batch transaction "anchors many
83
+ proofs". `proofHash` *is* the proof's identity — it is the integrity root, the value the
84
+ full and hybrid records place on-chain, and the value §Verification checks a certificate
85
+ against. Batching identifiers rather than re-serialised bodies keeps batch mode
86
+ consistent with the other two modes rather than introducing a second notion of what
87
+ represents a proof.
88
+
89
+ **It matches the mode it exists alongside.** Hybrid mode already establishes that BRC-220
90
+ puts hashes on-chain where blobs would be large. Fixed 32-byte leaves keep batch memory
91
+ and proof sizes independent of signature scheme — which matters precisely for the
92
+ post-quantum algorithms §Motivation names, where `canonicalBytes` runs to kilobytes per
93
+ proof.
94
+
95
+ **The extra hash costs nothing.** One SHA-256 over 32 bytes per leaf, against a
96
+ re-serialisation per leaf under the alternative.
97
+
98
+ ---
99
+
100
+ ## Compatibility
101
+
102
+ `@smartledger/bsv` implements the `proofHash` reading as of 8.3.0, and from this change
103
+ states it in `lib/notaryhash/index.js` and enforces it in
104
+ `test/notaryhash/batch_leaf.js` — including a test that a tree built over `canonicalBytes`
105
+ is rejected, so the choice is checked rather than merely intended.
106
+
107
+ No deployed batch certificates are known to use the other reading. If any exist, they were
108
+ built against an ambiguous sentence and would need reissuing; batch mode is the least-used
109
+ of the three and this is the moment to fix it, before that stops being true.
110
+
111
+ ---
112
+
113
+ ## The golden vector, ready to publish
114
+
115
+ Prose does not reliably close this: two implementers read the same sentence and chose
116
+ differently. A vector does. This one is generated by
117
+ `tools/gen-brc220-batch-vector.js`, lives at `test/data/brc220-batch-vector.json`, and is
118
+ checked by `test/notaryhash/batch_vector.js`.
119
+
120
+ **Five leaves, not four.** RFC 6962 splits at the largest power of two *below* `n`, so
121
+ `n = 5` splits 4/1 — a midpoint split would give 2/3 and a different root — and an odd
122
+ count exercises the rule that the last leaf is never duplicated. Those are the two places
123
+ implementations of this tree go wrong, and a power-of-two vector catches neither. It shows
124
+ up in the audit-path lengths: `[3, 3, 3, 3, 1]`.
125
+
126
+ Every input is derived from a labelled preimage rather than chosen, so the file
127
+ regenerates byte-identically and any implementation can rebuild it from scratch:
128
+
129
+ - private key `i` = `SHA-256("BRC-220/batch-vector/key/" + i)`
130
+ - `payloadHash` `i` = `SHA-256("BRC-220/batch-vector/payload/" + i)`
131
+ - `createdAt` `i` = `2026-01-0(i+1)T00:00:00.000Z`
132
+ - `algorithm` = `ECDSA-secp256k1`, `hashAlgorithm` = `SHA-256`, `encoding` = `"raw"`
133
+
134
+ **Signing.** The signer signs the 32-byte `payloadHash` directly — the digest *is* the
135
+ scalar, big-endian. RFC 6979 makes the nonce deterministic, so the signatures, and every
136
+ hash derived from them, reproduce exactly.
137
+
138
+ This matters more than it looks. The signature is inside `canonicalBytes`, which is inside
139
+ `proofHash`, which is the leaf — so the signing convention determines the root. An earlier
140
+ draft of this vector was generated against the byte-reversed convention that
141
+ `@smartledger/bsv` 8.3.0 used when verifying, and produced five signatures that no
142
+ conformant implementation could check (0/5 under `@noble/curves`), together with a root
143
+ nobody else would compute. It was never published. The values below were generated at
144
+ **8.3.1**, and `test/notaryhash/batch_vector.js` now verifies every signature under
145
+ `@noble/curves` as well as under this library, because a generator and a checker that
146
+ share a signer agree with each other whether or not they are right.
147
+
148
+ The five `proofHash` values that result:
149
+
150
+ | leafIndex | proofHash |
151
+ | ---: | --- |
152
+ | 0 | `83f3f73ebc5146b96cce1ee0b6ed4fd251a933a5332fbe5e5ab80da7920fe2c9` |
153
+ | 1 | `29fca10808a3653efbe38abd5f0b926aa09f13bff7847475139a422869729e77` |
154
+ | 2 | `3c44828bea3ca01dfcd5305a839ce02cc1e855f5a7c7028bb4931d42dea3aa2b` |
155
+ | 3 | `0692e22da9b68634e5384bb012324c140c676d2301e078a67f17e335661a9565` |
156
+ | 4 | `1a9c6bc1a6cf8319344ca8c30ca9e9eef8ab3df732748f6be2c824bb84ec0ca9` |
157
+
158
+ **Merkle root (`d = proofHash`, this amendment):**
159
+
160
+ ```
161
+ abb53eb3b2e3530d51685c6813bb85c85892d2f214c2dc504029d071434ac074
162
+ ```
163
+
164
+ The on-chain record tail is therefore `merkleRoot` above followed by
165
+ `u32be(5) = 00000005`. The audit path for leaf 4 — the lone right-hand leaf, and the
166
+ cheapest single value to check a split rule against — is one node:
167
+
168
+ ```
169
+ 060ca4e4bbcb647ab0162bb027cd8f08c1577aaa7069166dd629a3df7e57befd
170
+ ```
171
+
172
+ **Merkle root under the rejected reading (`d = canonicalBytes`):**
173
+
174
+ ```
175
+ 4a59ade74941e4d6ca4b7c9f610e0a01a0c3f24cfa94efe816e53ef85f99e324
176
+ ```
177
+
178
+ That second root is published deliberately. An implementation computing it has made the
179
+ other reading of `d` — which is a sound choice against an ambiguous sentence, not a bug in
180
+ their code — and printing both turns a silent non-interoperability into a one-line
181
+ diagnosis.
182
+
183
+ The stored vector records `canonicalBytes`, `proofHash` and the leaf hash under *both*
184
+ readings for every proof, so an implementer can find which step diverges rather than only
185
+ that the roots differ.
186
+
187
+ ### What this vector is not
188
+
189
+ It is a conformance target produced by `@smartledger/bsv`, not external validation, and it
190
+ does not prove this reading is the one originally intended — the spec does not say. What
191
+ makes it load-bearing is that the tree beneath it is independently anchored: the RFC 6962
192
+ construction is verified against the published Certificate Transparency roots in
193
+ `test/notaryhash/merkle.js`. Given a tree that provably matches RFC 6962, the vector fixes
194
+ the single thing left open.
package/docs/BRC220_PLAN.md CHANGED
@@ -173,6 +173,15 @@ summarising rather than anything in the document.
173
173
  - **The service is a role, not a requirement.** §What a certificate proves: "any party
174
174
  holding a valid (hash, signature, publicKey) triple may re-anchor it; the attestation
175
175
  remains valid". A self-notarizing caller producing its own certificate is conformant.
176
+ - **The batch Merkle leaf is NOT settled by the spec — it is a choice this
177
+ implementation made.** §On-chain record writes `leaf = SHA256(0x00 ‖ d)`, but that is
178
+ RFC 6962's own generic notation for the construction and `d` is never bound to a value.
179
+ `canonicalBytes` appears once in the whole document, in the `proofHash` definition, and
180
+ nowhere in the batch text. We read `d` as `proofHash`; reading it as `canonicalBytes` is
181
+ equally sound and produces a different root, so the two do not interoperate. Recorded as
182
+ an ambiguity rather than a settled question, with proposed spec text in
183
+ [BRC220_BATCH_LEAF_AMENDMENT.md](BRC220_BATCH_LEAF_AMENDMENT.md) and enforcement in
184
+ `test/notaryhash/batch_leaf.js`. This is the second gap of the kind, after `encoding`.
176
185
  - **`createdAt` is advisory for trust but load-bearing for the hash.** §Verification calls
177
186
  it "an advisory client field only" — meaning proof-of-existence time comes from the
178
187
  block, not from this field. It is still inside the canonical bytes as `createdAtUnix`,
package/docs/MODULE_REFERENCE_COMPLETE.md CHANGED
@@ -55,19 +55,19 @@ Three advanced modules totaling **~2.7MB** of functionality:
55
55
  - **Purpose**: Threshold cryptography for secure secret distribution
56
56
  - **Use Cases**: Backup keys, multi-party security, key recovery
57
57
  - **Features**: Split secrets into N shares, require M to reconstruct
58
- - **CDN**: `unpkg.com/@smartledger/bsv@8.3.0/bsv-shamir.min.js`
58
+ - **CDN**: `unpkg.com/@smartledger/bsv@9.0.0/bsv-shamir.min.js`
59
59
 
60
60
  #### **🌐 Global Digital Attestation Framework - GDAF (1184KB)**
61
61
  - **Purpose**: W3C Verifiable Credentials and decentralized identity
62
62
  - **Use Cases**: Identity verification, attestations, zero-knowledge proofs
63
63
  - **Features**: DID creation, credential issuance, selective disclosure
64
- - **CDN**: `unpkg.com/@smartledger/bsv@8.3.0/bsv-gdaf.min.js`
64
+ - **CDN**: `unpkg.com/@smartledger/bsv@9.0.0/bsv-gdaf.min.js`
65
65
 
66
66
  #### **⚖️ Legal Token Protocol - LTP (1184KB)**
67
67
  - **Purpose**: Legal compliance framework for tokenized assets
68
68
  - **Use Cases**: Property rights, obligations, compliant tokenization
69
69
  - **Features**: Legal primitives, compliance checking, attestation anchoring
70
- - **CDN**: `unpkg.com/@smartledger/bsv@8.3.0/bsv-ltp.min.js`
70
+ - **CDN**: `unpkg.com/@smartledger/bsv@9.0.0/bsv-ltp.min.js`
71
71
 
72
72
  ### **2. Incorrect File Sizes in Documentation**
73
73
 
@@ -81,18 +81,18 @@ Three advanced modules totaling **~2.7MB** of functionality:
81
81
 
82
82
  | Module | Size | Use Case | CDN Link |
83
83
  |--------|------|----------|----------|
84
- | **bsv.min.js** | 937KB | Core BSV + SmartContract | `unpkg.com/@smartledger/bsv@8.3.0/bsv.min.js` |
85
- | **bsv.bundle.js** | 937KB | Everything in one file | `unpkg.com/@smartledger/bsv@8.3.0/bsv.bundle.js` |
86
- | **bsv-smartcontract.min.js** | 937KB | Covenant development | `unpkg.com/@smartledger/bsv@8.3.0/bsv-smartcontract.min.js` |
87
- | **bsv-covenant.min.js** | 913KB | Covenant operations | `unpkg.com/@smartledger/bsv@8.3.0/bsv-covenant.min.js` |
88
- | **bsv-script-helper.min.js** | 26KB | Custom script tools | `unpkg.com/@smartledger/bsv@8.3.0/bsv-script-helper.min.js` |
89
- | **bsv-security.min.js** | 26KB | Security enhancements (opt-in helpers — see README › Security) | `unpkg.com/@smartledger/bsv@8.3.0/bsv-security.min.js` |
90
- | **bsv-ecies.min.js** | 71KB | Encryption | `unpkg.com/@smartledger/bsv@8.3.0/bsv-ecies.min.js` |
91
- | **bsv-message.min.js** | 26KB | Message signing | `unpkg.com/@smartledger/bsv@8.3.0/bsv-message.min.js` |
92
- | **bsv-mnemonic.min.js** | 681KB | HD wallets | `unpkg.com/@smartledger/bsv@8.3.0/bsv-mnemonic.min.js` |
93
- | **🆕 bsv-shamir.min.js** | 432KB | **Secret sharing** | `unpkg.com/@smartledger/bsv@8.3.0/bsv-shamir.min.js` |
94
- | **🆕 bsv-gdaf.min.js** | 1184KB | **Digital attestation** | `unpkg.com/@smartledger/bsv@8.3.0/bsv-gdaf.min.js` |
95
- | **🆕 bsv-ltp.min.js** | 1184KB | **Legal tokens** | `unpkg.com/@smartledger/bsv@8.3.0/bsv-ltp.min.js` |
84
+ | **bsv.min.js** | 937KB | Core BSV + SmartContract | `unpkg.com/@smartledger/bsv@9.0.0/bsv.min.js` |
85
+ | **bsv.bundle.js** | 937KB | Everything in one file | `unpkg.com/@smartledger/bsv@9.0.0/bsv.bundle.js` |
86
+ | **bsv-smartcontract.min.js** | 937KB | Covenant development | `unpkg.com/@smartledger/bsv@9.0.0/bsv-smartcontract.min.js` |
87
+ | **bsv-covenant.min.js** | 913KB | Covenant operations | `unpkg.com/@smartledger/bsv@9.0.0/bsv-covenant.min.js` |
88
+ | **bsv-script-helper.min.js** | 26KB | Custom script tools | `unpkg.com/@smartledger/bsv@9.0.0/bsv-script-helper.min.js` |
89
+ | **bsv-security.min.js** | 26KB | Security enhancements (opt-in helpers — see README › Security) | `unpkg.com/@smartledger/bsv@9.0.0/bsv-security.min.js` |
90
+ | **bsv-ecies.min.js** | 71KB | Encryption | `unpkg.com/@smartledger/bsv@9.0.0/bsv-ecies.min.js` |
91
+ | **bsv-message.min.js** | 26KB | Message signing | `unpkg.com/@smartledger/bsv@9.0.0/bsv-message.min.js` |
92
+ | **bsv-mnemonic.min.js** | 681KB | HD wallets | `unpkg.com/@smartledger/bsv@9.0.0/bsv-mnemonic.min.js` |
93
+ | **🆕 bsv-shamir.min.js** | 432KB | **Secret sharing** | `unpkg.com/@smartledger/bsv@9.0.0/bsv-shamir.min.js` |
94
+ | **🆕 bsv-gdaf.min.js** | 1184KB | **Digital attestation** | `unpkg.com/@smartledger/bsv@9.0.0/bsv-gdaf.min.js` |
95
+ | **🆕 bsv-ltp.min.js** | 1184KB | **Legal tokens** | `unpkg.com/@smartledger/bsv@9.0.0/bsv-ltp.min.js` |
96
96
 
97
97
  ## 🎯 **Updated Usage Examples**
98
98
 
@@ -100,22 +100,22 @@ Three advanced modules totaling **~2.7MB** of functionality:
100
100
 
101
101
  #### **1. Basic Development (~963KB)**
102
102
  ```html
103
- <script src="https://unpkg.com/@smartledger/bsv@8.3.0/bsv.min.js"></script>
104
- <script src="https://unpkg.com/@smartledger/bsv@8.3.0/bsv-script-helper.min.js"></script>
103
+ <script src="https://unpkg.com/@smartledger/bsv@9.0.0/bsv.min.js"></script>
104
+ <script src="https://unpkg.com/@smartledger/bsv@9.0.0/bsv-script-helper.min.js"></script>
105
105
  ```
106
106
 
107
107
  #### **2. Smart Contract Development (~2.7MB — each bundle re-embeds core BSV)**
108
108
  ```html
109
- <script src="https://unpkg.com/@smartledger/bsv@8.3.0/bsv.min.js"></script>
110
- <script src="https://unpkg.com/@smartledger/bsv@8.3.0/bsv-covenant.min.js"></script>
111
- <script src="https://unpkg.com/@smartledger/bsv@8.3.0/bsv-smartcontract.min.js"></script>
109
+ <script src="https://unpkg.com/@smartledger/bsv@9.0.0/bsv.min.js"></script>
110
+ <script src="https://unpkg.com/@smartledger/bsv@9.0.0/bsv-covenant.min.js"></script>
111
+ <script src="https://unpkg.com/@smartledger/bsv@9.0.0/bsv-smartcontract.min.js"></script>
112
112
  ```
113
113
 
114
114
  #### **3. 🆕 Legal & Compliance Development (~3.2MB — each bundle re-embeds core BSV)**
115
115
  ```html
116
- <script src="https://unpkg.com/@smartledger/bsv@8.3.0/bsv.min.js"></script>
117
- <script src="https://unpkg.com/@smartledger/bsv@8.3.0/bsv-ltp.min.js"></script>
118
- <script src="https://unpkg.com/@smartledger/bsv@8.3.0/bsv-gdaf.min.js"></script>
116
+ <script src="https://unpkg.com/@smartledger/bsv@9.0.0/bsv.min.js"></script>
117
+ <script src="https://unpkg.com/@smartledger/bsv@9.0.0/bsv-ltp.min.js"></script>
118
+ <script src="https://unpkg.com/@smartledger/bsv@9.0.0/bsv-gdaf.min.js"></script>
119
119
  <script>
120
120
  // Legal Token Protocol
121
121
  const legalToken = bsv.createLegalToken({
@@ -132,9 +132,9 @@ Three advanced modules totaling **~2.7MB** of functionality:
132
132
 
133
133
  #### **4. 🆕 Security & Cryptography (~1.4MB)**
134
134
  ```html
135
- <script src="https://unpkg.com/@smartledger/bsv@8.3.0/bsv.min.js"></script>
136
- <script src="https://unpkg.com/@smartledger/bsv@8.3.0/bsv-security.min.js"></script>
137
- <script src="https://unpkg.com/@smartledger/bsv@8.3.0/bsv-shamir.min.js"></script>
135
+ <script src="https://unpkg.com/@smartledger/bsv@9.0.0/bsv.min.js"></script>
136
+ <script src="https://unpkg.com/@smartledger/bsv@9.0.0/bsv-security.min.js"></script>
137
+ <script src="https://unpkg.com/@smartledger/bsv@9.0.0/bsv-shamir.min.js"></script>
138
138
  <script>
139
139
  // Shamir Secret Sharing
140
140
  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:
146
146
 
147
147
  #### **5. Everything Bundle (937KB)**
148
148
  ```html
149
- <script src="https://unpkg.com/@smartledger/bsv@8.3.0/bsv.bundle.js"></script>
149
+ <script src="https://unpkg.com/@smartledger/bsv@9.0.0/bsv.bundle.js"></script>
150
150
  <script>
151
151
  // Everything available immediately
152
152
  const shares = bsv.splitSecret('secret', 5, 3);
package/docs/README.md CHANGED
@@ -138,7 +138,8 @@ const helper = new CustomScriptHelper();
138
138
  const multisig = helper.createMultisigScript([pk1, pk2, pk3], 2);
139
139
 
140
140
  // Timelock script
141
- const timelock = helper.createTimelockScript(publicKey, 750000, 'block');
141
+ // REMOVED in 9.0.0 — OP_CHECKLOCKTIMEVERIFY is a NOP after Genesis, so this
142
+ // enforced nothing on mainnet. There is no supported time-lock primitive.
142
143
  ```
143
144
 
144
145
  ### 📊 BIP143 Preimage Analysis
package/docs/THREAT_MODEL.md CHANGED
@@ -108,8 +108,16 @@ Node, or hostile browser extension is out of scope — see `SECURITY.md`).
108
108
  - **No published provenance yet.** Bundles are a reproducible build of source (see §4) but
109
109
  npm provenance attestation is pending a trusted-publisher registration (2FA-gated). This is
110
110
  a *supply-chain verifiability* gap, not a code vulnerability.
111
- - **Genesis limits.** Covenant scripts require post-Genesis limits (`SmartContract.enableGenesis()`);
112
- the guarantees assume a post-Genesis BSV node.
111
+ - **CLTV time locks removed (9.0.0).** `Locks.timeLockCLTV`, `Locks.htlc` and
112
+ `CustomScriptHelper.createTimelockScript` were gated by `OP_CHECKLOCKTIMEVERIFY`,
113
+ which Genesis reverted to an upgradable NOP for outputs created after it. They
114
+ enforced **nothing** on mainnet — the coins were spendable immediately — yet the
115
+ library's own tests asserted the lock held, because the covenant harness verified
116
+ under flags missing the era bits. That is the §1 failure mode found in our own code,
117
+ and the reason the API was deleted rather than documented: a time lock that does not
118
+ lock has no safe use. There is no supported time-lock primitive in this library.
119
+ - **Consensus era.** Covenant guarantees assume current BSV mainnet; the harness verifies
120
+ under `Interpreter.mainnetFlags()` with no opt-in required (8.4.0+).
113
121
 
114
122
  ## 4. Supply chain / reproducible builds
115
123
 
package/docs/advanced/UTXO_MANAGER_GUIDE.md CHANGED
@@ -722,7 +722,7 @@ interface UTXO {
722
722
  <html>
723
723
  <head>
724
724
  <title>UTXO Manager Demo</title>
725
- <script src="https://cdn.jsdelivr.net/npm/@smartledger/bsv@8.3.0/bsv.min.js"></script>
725
+ <script src="https://cdn.jsdelivr.net/npm/@smartledger/bsv@9.0.0/bsv.min.js"></script>
726
726
  </head>
727
727
  <body>
728
728
  <script>
package/docs/getting-started/INSTALLATION.md CHANGED
@@ -48,7 +48,7 @@ const tx: Transaction = new Transaction();
48
48
  #### **Core Library Only (937KB)**
49
49
  For basic Bitcoin SV operations:
50
50
  ```html
51
- <script src="https://unpkg.com/@smartledger/bsv@8.3.0/bsv.min.js"></script>
51
+ <script src="https://unpkg.com/@smartledger/bsv@9.0.0/bsv.min.js"></script>
52
52
  <script>
53
53
  const privateKey = new bsv.PrivateKey();
54
54
  const address = privateKey.toAddress();
@@ -58,7 +58,7 @@ For basic Bitcoin SV operations:
58
58
  #### **Complete Bundle (937KB)**
59
59
  Everything in one file:
60
60
  ```html
61
- <script src="https://unpkg.com/@smartledger/bsv@8.3.0/bsv.bundle.js"></script>
61
+ <script src="https://unpkg.com/@smartledger/bsv@9.0.0/bsv.bundle.js"></script>
62
62
  <script>
63
63
  // All features available immediately
64
64
  const shares = bsv.splitSecret('secret', 5, 3);
@@ -71,9 +71,9 @@ Everything in one file:
71
71
 
72
72
  #### **Smart Contract Development (~2.7MB total — each bundle is self-contained and re-embeds core BSV)**
73
73
  ```html
74
- <script src="https://unpkg.com/@smartledger/bsv@8.3.0/bsv.min.js"></script>
75
- <script src="https://unpkg.com/@smartledger/bsv@8.3.0/bsv-covenant.min.js"></script>
76
- <script src="https://unpkg.com/@smartledger/bsv@8.3.0/bsv-smartcontract.min.js"></script>
74
+ <script src="https://unpkg.com/@smartledger/bsv@9.0.0/bsv.min.js"></script>
75
+ <script src="https://unpkg.com/@smartledger/bsv@9.0.0/bsv-covenant.min.js"></script>
76
+ <script src="https://unpkg.com/@smartledger/bsv@9.0.0/bsv-smartcontract.min.js"></script>
77
77
  <script>
78
78
  const covenant = bsv.SmartContract.createCovenantBuilder()
79
79
  .extractField('amount').push(50000).greaterThanOrEqual().build();
@@ -82,9 +82,9 @@ Everything in one file:
82
82
 
83
83
  #### **Legal & Identity Development (~3.2MB total — each bundle is self-contained and re-embeds core BSV)**
84
84
  ```html
85
- <script src="https://unpkg.com/@smartledger/bsv@8.3.0/bsv.min.js"></script>
86
- <script src="https://unpkg.com/@smartledger/bsv@8.3.0/bsv-ltp.min.js"></script>
87
- <script src="https://unpkg.com/@smartledger/bsv@8.3.0/bsv-gdaf.min.js"></script>
85
+ <script src="https://unpkg.com/@smartledger/bsv@9.0.0/bsv.min.js"></script>
86
+ <script src="https://unpkg.com/@smartledger/bsv@9.0.0/bsv-ltp.min.js"></script>
87
+ <script src="https://unpkg.com/@smartledger/bsv@9.0.0/bsv-gdaf.min.js"></script>
88
88
  <script>
89
89
  // Legal Token Protocol
90
90
  const propertyToken = bsv.createPropertyToken({
@@ -98,9 +98,9 @@ Everything in one file:
98
98
 
99
99
  #### **Security & Cryptography (~1.4MB total — each bundle is self-contained and re-embeds core BSV)**
100
100
  ```html
101
- <script src="https://unpkg.com/@smartledger/bsv@8.3.0/bsv.min.js"></script>
102
- <script src="https://unpkg.com/@smartledger/bsv@8.3.0/bsv-security.min.js"></script>
103
- <script src="https://unpkg.com/@smartledger/bsv@8.3.0/bsv-shamir.min.js"></script>
101
+ <script src="https://unpkg.com/@smartledger/bsv@9.0.0/bsv.min.js"></script>
102
+ <script src="https://unpkg.com/@smartledger/bsv@9.0.0/bsv-security.min.js"></script>
103
+ <script src="https://unpkg.com/@smartledger/bsv@9.0.0/bsv-shamir.min.js"></script>
104
104
  <script>
105
105
  // Threshold Cryptography
106
106
  const shares = bsv.splitSecret('my_secret_key', 5, 3);
@@ -114,18 +114,18 @@ Everything in one file:
114
114
 
115
115
  | Module | Size | Purpose | CDN Link |
116
116
  |--------|------|---------|----------|
117
- | **bsv.min.js** | 937KB | Core BSV + SmartContract | `unpkg.com/@smartledger/bsv@8.3.0/bsv.min.js` |
118
- | **bsv.bundle.js** | 937KB | Everything in one file | `unpkg.com/@smartledger/bsv@8.3.0/bsv.bundle.js` |
119
- | **bsv-smartcontract.min.js** | 937KB | Complete covenant framework | `unpkg.com/@smartledger/bsv@8.3.0/bsv-smartcontract.min.js` |
120
- | **bsv-ltp.min.js** | 1184KB | **Legal Token Protocol** | `unpkg.com/@smartledger/bsv@8.3.0/bsv-ltp.min.js` |
121
- | **bsv-gdaf.min.js** | 1184KB | **Digital Identity & Attestation** | `unpkg.com/@smartledger/bsv@8.3.0/bsv-gdaf.min.js` |
122
- | **bsv-shamir.min.js** | 432KB | **Threshold Cryptography** | `unpkg.com/@smartledger/bsv@8.3.0/bsv-shamir.min.js` |
123
- | **bsv-security.min.js** | 26KB | Security enhancements (opt-in helpers — see README › Security) | `unpkg.com/@smartledger/bsv@8.3.0/bsv-security.min.js` |
124
- | **bsv-mnemonic.min.js** | 681KB | HD wallets | `unpkg.com/@smartledger/bsv@8.3.0/bsv-mnemonic.min.js` |
125
- | **bsv-ecies.min.js** | 71KB | Encryption | `unpkg.com/@smartledger/bsv@8.3.0/bsv-ecies.min.js` |
126
- | **bsv-covenant.min.js** | 913KB | Covenant operations | `unpkg.com/@smartledger/bsv@8.3.0/bsv-covenant.min.js` |
127
- | **bsv-script-helper.min.js** | 26KB | Custom script tools | `unpkg.com/@smartledger/bsv@8.3.0/bsv-script-helper.min.js` |
128
- | **bsv-message.min.js** | 26KB | Message signing | `unpkg.com/@smartledger/bsv@8.3.0/bsv-message.min.js` |
117
+ | **bsv.min.js** | 937KB | Core BSV + SmartContract | `unpkg.com/@smartledger/bsv@9.0.0/bsv.min.js` |
118
+ | **bsv.bundle.js** | 937KB | Everything in one file | `unpkg.com/@smartledger/bsv@9.0.0/bsv.bundle.js` |
119
+ | **bsv-smartcontract.min.js** | 937KB | Complete covenant framework | `unpkg.com/@smartledger/bsv@9.0.0/bsv-smartcontract.min.js` |
120
+ | **bsv-ltp.min.js** | 1184KB | **Legal Token Protocol** | `unpkg.com/@smartledger/bsv@9.0.0/bsv-ltp.min.js` |
121
+ | **bsv-gdaf.min.js** | 1184KB | **Digital Identity & Attestation** | `unpkg.com/@smartledger/bsv@9.0.0/bsv-gdaf.min.js` |
122
+ | **bsv-shamir.min.js** | 432KB | **Threshold Cryptography** | `unpkg.com/@smartledger/bsv@9.0.0/bsv-shamir.min.js` |
123
+ | **bsv-security.min.js** | 26KB | Security enhancements (opt-in helpers — see README › Security) | `unpkg.com/@smartledger/bsv@9.0.0/bsv-security.min.js` |
124
+ | **bsv-mnemonic.min.js** | 681KB | HD wallets | `unpkg.com/@smartledger/bsv@9.0.0/bsv-mnemonic.min.js` |
125
+ | **bsv-ecies.min.js** | 71KB | Encryption | `unpkg.com/@smartledger/bsv@9.0.0/bsv-ecies.min.js` |
126
+ | **bsv-covenant.min.js** | 913KB | Covenant operations | `unpkg.com/@smartledger/bsv@9.0.0/bsv-covenant.min.js` |
127
+ | **bsv-script-helper.min.js** | 26KB | Custom script tools | `unpkg.com/@smartledger/bsv@9.0.0/bsv-script-helper.min.js` |
128
+ | **bsv-message.min.js** | 26KB | Message signing | `unpkg.com/@smartledger/bsv@9.0.0/bsv-message.min.js` |
129
129
 
130
130
  ## ⚙️ **Development Environment Setup**
131
131
 
package/docs/getting-started/QUICK_START.md CHANGED
@@ -14,10 +14,10 @@ npm install @smartledger/bsv
14
14
  ### Browser CDN (Instant)
15
15
  ```html
16
16
  <!-- Core library (937KB) -->
17
- <script src="https://unpkg.com/@smartledger/bsv@8.3.0/bsv.min.js"></script>
17
+ <script src="https://unpkg.com/@smartledger/bsv@9.0.0/bsv.min.js"></script>
18
18
 
19
19
  <!-- Everything included (937KB) -->
20
- <script src="https://unpkg.com/@smartledger/bsv@8.3.0/bsv.bundle.js"></script>
20
+ <script src="https://unpkg.com/@smartledger/bsv@9.0.0/bsv.bundle.js"></script>
21
21
  ```
22
22
 
23
23
  ## 💰 **Your First Transaction (60 seconds)**
@@ -127,19 +127,19 @@ SmartLedger-BSV offers 12 different loading options - use only what you need:
127
127
 
128
128
  ```html
129
129
  <!-- Core BSV only (937KB) -->
130
- <script src="https://unpkg.com/@smartledger/bsv@8.3.0/bsv.min.js"></script>
130
+ <script src="https://unpkg.com/@smartledger/bsv@9.0.0/bsv.min.js"></script>
131
131
 
132
132
  <!-- Smart contracts (937KB) -->
133
- <script src="https://unpkg.com/@smartledger/bsv@8.3.0/bsv-smartcontract.min.js"></script>
133
+ <script src="https://unpkg.com/@smartledger/bsv@9.0.0/bsv-smartcontract.min.js"></script>
134
134
 
135
135
  <!-- Legal tokens (1.16MB) -->
136
- <script src="https://unpkg.com/@smartledger/bsv@8.3.0/bsv-ltp.min.js"></script>
136
+ <script src="https://unpkg.com/@smartledger/bsv@9.0.0/bsv-ltp.min.js"></script>
137
137
 
138
138
  <!-- Digital identity (1.16MB) -->
139
- <script src="https://unpkg.com/@smartledger/bsv@8.3.0/bsv-gdaf.min.js"></script>
139
+ <script src="https://unpkg.com/@smartledger/bsv@9.0.0/bsv-gdaf.min.js"></script>
140
140
 
141
141
  <!-- Everything (937KB) -->
142
- <script src="https://unpkg.com/@smartledger/bsv@8.3.0/bsv.bundle.js"></script>
142
+ <script src="https://unpkg.com/@smartledger/bsv@9.0.0/bsv.bundle.js"></script>
143
143
  ```
144
144
 
145
145
  ## ⚡ **Key Advantages**
package/docs/migration/FROM_BSV_1_5_6.md CHANGED
@@ -159,17 +159,17 @@ const recovered = bsv.reconstructSecret([shares[0], shares[2], shares[4]]);
159
159
  ### **New Modular Options**
160
160
  ```html
161
161
  <!-- Core compatibility (same size as bsv@1.5.6) -->
162
- <script src="https://unpkg.com/@smartledger/bsv@8.3.0/bsv.min.js"></script>
162
+ <script src="https://unpkg.com/@smartledger/bsv@9.0.0/bsv.min.js"></script>
163
163
 
164
164
  <!-- Add smart contracts when ready -->
165
- <script src="https://unpkg.com/@smartledger/bsv@8.3.0/bsv-smartcontract.min.js"></script>
165
+ <script src="https://unpkg.com/@smartledger/bsv@9.0.0/bsv-smartcontract.min.js"></script>
166
166
 
167
167
  <!-- Add advanced features as needed -->
168
- <script src="https://unpkg.com/@smartledger/bsv@8.3.0/bsv-ltp.min.js"></script>
169
- <script src="https://unpkg.com/@smartledger/bsv@8.3.0/bsv-gdaf.min.js"></script>
168
+ <script src="https://unpkg.com/@smartledger/bsv@9.0.0/bsv-ltp.min.js"></script>
169
+ <script src="https://unpkg.com/@smartledger/bsv@9.0.0/bsv-gdaf.min.js"></script>
170
170
 
171
171
  <!-- Everything in one file -->
172
- <script src="https://unpkg.com/@smartledger/bsv@8.3.0/bsv.bundle.js"></script>
172
+ <script src="https://unpkg.com/@smartledger/bsv@9.0.0/bsv.bundle.js"></script>
173
173
  ```
174
174
 
175
175
  ## 🔍 **Testing Your Migration**
package/index.js CHANGED
@@ -172,34 +172,18 @@ try {
172
172
  // Node.js specific tools (advanced development tools)
173
173
  if (typeof window === 'undefined' && typeof require === 'function') {
174
174
  try {
175
- // bsv.SmartUTXO is a development-only file-backed UTXO simulator.
176
- // It writes to node_modules/@smartledger/bsv/utilities/blockchain-state.json,
177
- // races on shared filesystem state across processes, and only ships with
178
- // an empty seed (the 3.3 MB dev fixture is npmignored). Exposing it on
179
- // the main `bsv` namespace creates a real footgun for anyone who assumes
180
- // a production UTXO manager.
175
+ // bsv.SmartUTXO was REMOVED in 9.0.0. It is a development-only file-backed UTXO
176
+ // simulator: it writes to node_modules/@smartledger/bsv/utilities/blockchain-state.json,
177
+ // races on shared filesystem state across processes, and ships with an empty seed.
178
+ // On the main namespace it read as a production UTXO manager, which it never was.
179
+ //
180
+ // Soft-deprecated in 4.0.1 with removal promised for 6.0.0, then shipped through
181
+ // 6.x, 7.x and 8.x still warning about a removal that never came. The module itself
182
+ // is unchanged and still available by direct import:
181
183
  //
182
- // Soft-deprecated in v4.0.1: the symbol is preserved (no semver break)
183
- // but access surfaces a one-shot warning. Direct import remains:
184
184
  // require('@smartledger/bsv/lib/smartutxo')
185
- // The symbol will be removed in v6.0.0.
186
- var _SmartUTXO
187
- var _SmartUTXOWarned = false
188
- Object.defineProperty(bsv, 'SmartUTXO', {
189
- configurable: true,
190
- enumerable: true,
191
- get: function () {
192
- if (!_SmartUTXOWarned && !(process.env && process.env.BSV_HIDE_DEPRECATIONS)) {
193
- _SmartUTXOWarned = true
194
- console.warn('[bsv] bsv.SmartUTXO is a development-only simulator and is deprecated; ' +
195
- 'it will be removed in v6.0.0. Import directly: ' +
196
- "require('@smartledger/bsv/lib/smartutxo'). " +
197
- 'Set BSV_HIDE_DEPRECATIONS=1 to silence this warning.')
198
- }
199
- if (!_SmartUTXO) _SmartUTXO = require('./lib/smartutxo')
200
- return _SmartUTXO
201
- }
202
- })
185
+ //
186
+ // which is exactly what the deprecation warning told callers to do since 4.0.1.
203
187
 
204
188
  bsv.SmartMiner = require('./lib/smartminer')
205
189
  bsv.CustomScriptHelper = require('./lib/custom-script-helper')