@smartledger/bsv 8.2.0 → 8.3.1

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 (36) hide show
  1. package/CHANGELOG.md +126 -0
  2. package/README.md +349 -207
  3. package/bsv-ecies.min.js +1 -1
  4. package/bsv-gdaf.min.js +62 -62
  5. package/bsv-ltp.min.js +48 -48
  6. package/bsv-smartcontract.min.js +1 -1
  7. package/bsv.bundle.js +62 -62
  8. package/bsv.min.js +62 -62
  9. package/docs/AUDIT_SCOPE.md +8 -8
  10. package/docs/BRC220_BATCH_LEAF_AMENDMENT.md +119 -0
  11. package/docs/BRC220_ENCODING_AMENDMENT.md +100 -0
  12. package/docs/BRC220_PLAN.md +233 -0
  13. package/docs/MODULE_REFERENCE_COMPLETE.md +27 -27
  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 +5 -0
  19. package/index.mjs +1 -0
  20. package/lib/gdaf/attestation-signer.js +2 -38
  21. package/lib/notaryhash/certificate.js +282 -0
  22. package/lib/notaryhash/encoding.js +150 -0
  23. package/lib/notaryhash/index.js +354 -0
  24. package/lib/notaryhash/merkle.js +217 -0
  25. package/lib/notaryhash/script.js +261 -0
  26. package/lib/notaryhash/suites.js +172 -0
  27. package/lib/util/jcs.js +75 -0
  28. package/package.json +9 -6
  29. package/test/notaryhash/batch_leaf.js +140 -0
  30. package/test/notaryhash/certificate.js +249 -0
  31. package/test/notaryhash/encoding.js +186 -0
  32. package/test/notaryhash/interop.js +112 -0
  33. package/test/notaryhash/merkle.js +181 -0
  34. package/test/notaryhash/script.js +270 -0
  35. package/test/notaryhash/verify.js +342 -0
  36. package/version.js +1 -1
package/README.md CHANGED
@@ -2,37 +2,44 @@
2
2
 
3
3
  **🚀 Complete Bitcoin SV Development Framework with W3C Verifiable Credentials, DID:web, Legal Compliance, and 16 Flexible Loading Options**
4
4
 
5
- [![Version](https://img.shields.io/badge/version-5.4.0-blue.svg)](https://www.npmjs.com/package/@smartledger/bsv)
5
+ [![Version](https://img.shields.io/badge/version-8.3.1-blue.svg)](https://www.npmjs.com/package/@smartledger/bsv)
6
6
  [![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
7
7
  [![BSV](https://img.shields.io/badge/BSV-Compatible-orange.svg)](https://bitcoinsv.com/)
8
8
  [![Modular](https://img.shields.io/badge/Loading-Modular-purple.svg)](#-16-loading-options---choose-your-approach)
9
9
  [![W3C](https://img.shields.io/badge/W3C-Compliant-blueviolet.svg)](#-legally-recognizable-credentials-v34x)
10
10
 
11
- The most comprehensive and flexible Bitcoin SV library available. **In v5.x**:
12
- all secp256k1 cryptography runs on the audited, constant-time
13
- [`@noble`](https://github.com/paulmillr/noble-curves) suite (ECDSA, ECIES, key
14
- derivation) with `elliptic` removed; Shamir secret sharing on a vetted GF(2⁸)
15
- engine; JOSE-compliant VC-JWT — on top of the v4.x interpreter-verified covenant
16
- stack (OP_PUSH_TX, PELS, ownership tokens), legally-recognizable DID:web + VC-JWT
17
- toolkit, and 16 distribution methods. **v5.x is the only supported line — see
18
- [Upgrading to v5.0.0](#upgrading-to-v500-breaking-changes) when moving from 4.x.**
19
-
20
- > **v5.4.0 (latest)**: all secp256k1 crypto on the audited `@noble` suite, with
21
- > `elliptic` now gone from the bundles too (`bsv.min.js` ~1.1MB, ~120–140KB
22
- > smaller per bundle); browser Shamir fixed and guarded by a headless-Chrome CI
23
- > check. See [CHANGELOG](./CHANGELOG.md).
11
+ A comprehensive Bitcoin SV library whose **defaults describe BSV as the network
12
+ actually runs it**. Since 8.0.0 the script interpreter is measured against the
13
+ reference node's own consensus vectors — 1483/1483, with zero false accepts —
14
+ rather than against the Bitcoin Core vectors inherited from the upstream fork.
15
+ All secp256k1 cryptography runs on the audited, constant-time
16
+ [`@noble`](https://github.com/paulmillr/noble-curves) suite with `elliptic`
17
+ removed, on top of the interpreter-verified covenant stack (OP_PUSH_TX, PELS,
18
+ ownership tokens), a legally-recognizable DID:web + VC-JWT toolkit, and 16
19
+ distribution methods.
20
+
21
+ > **8.3.0 (latest)**: BRC-220 **NotaryHash** — privacy-preserving signed-hash
22
+ > notarization with SPV-verifiable certificates, including RFC 6962 Merkle trees
23
+ > for batch mode. See [NotaryHash](#-notaryhash-brc-220) and the
24
+ > [CHANGELOG](./CHANGELOG.md).
25
+ >
26
+ > **8.0.0 was a breaking release.** `verify()` with no flags now means BSV
27
+ > mainnet rather than "no rules", and two flag constants changed value. Read
28
+ > [Upgrading to v8.0.0](#upgrading-to-v800-breaking-changes) before moving from
29
+ > 7.x or earlier.
24
30
 
25
31
  ## **Interpreter-Verified Covenants**
26
32
 
27
- The full covenant stack now lives at `bsv.SmartContract`, builds on the
28
- post-Genesis script limits added in 4.1.0, and verifies end-to-end through
29
- `Script.Interpreter`. Every locking script has both a positive (must-accept)
30
- and negative (must-reject) test.
33
+ The full covenant stack lives at `bsv.SmartContract` and verifies end-to-end
34
+ through `Script.Interpreter`. Every locking script has both a positive
35
+ (must-accept) and negative (must-reject) test.
31
36
 
32
37
  ```javascript
33
38
  const bsv = require('@smartledger/bsv')
34
39
  const SC = bsv.SmartContract
35
- SC.enableGenesis() // post-Genesis limits (OP_PUSH_TX needs them)
40
+ SC.enableGenesis() // OP_PUSH_TX needs the lifted element cap — but note this is
41
+ // process-wide and weakens pre-Genesis validation. See
42
+ // "Consensus defaults" below before calling it in an app.
36
43
 
37
44
  // Self-replicating covenant — every spend recreates the same script (value − fee).
38
45
  const lock = SC.perpetualCovenant(500)
@@ -44,8 +51,9 @@ const token = SC.ownershipToken(500, ownerHash) // ownerHash = SC.Token.ownerId(
44
51
  // Value covenant — forces spend outputs to match a specific hashOutputs.
45
52
  const vlock = SC.valueCovenant(SC.PushTx.hashOutputs(requiredOutputs))
46
53
 
47
- // Verify any locking script end-to-end through Script.Interpreter
48
- const ok = SC.verifyScript(unlockScript, lockingScript, tx, inputIndex, satoshis)
54
+ // Verify any locking script end-to-end through Script.Interpreter.
55
+ // Returns { ok, err } — `err` names the interpreter error when ok is false.
56
+ const { ok, err } = SC.verifyScript(unlockScript, lockingScript, { tx, inputIndex, satoshis })
49
57
  ```
50
58
 
51
59
  **Available primitives under `bsv.SmartContract`:**
@@ -63,6 +71,94 @@ const ok = SC.verifyScript(unlockScript, lockingScript, tx, inputIndex, satoshis
63
71
  > is the intentionally public `a=k=1` construction, and low-S malleability is
64
72
  > left unenforced for the in-script signature.
65
73
 
74
+ ## 🔏 NotaryHash (BRC-220)
75
+
76
+ [BRC-220](https://github.com/bitcoin-sv/BRCs/blob/master/apps/0220.md) notarizes a
77
+ document by publishing a signed hash of it. The document itself never leaves your
78
+ hands — what goes on chain is an `OP_FALSE OP_RETURN` record, and what a verifier
79
+ receives is a certificate they can check offline plus an SPV proof they can check
80
+ against block headers obtained independently.
81
+
82
+ Available as `bsv.NotaryHash`, or `require('@smartledger/bsv/lib/notaryhash')`.
83
+
84
+ ```javascript
85
+ const bsv = require('@smartledger/bsv')
86
+ const NotaryHash = bsv.NotaryHash
87
+
88
+ // 1. Hash the document. Only the hash is ever published.
89
+ const payloadHash = bsv.crypto.Hash.sha256(Buffer.from(documentBytes))
90
+
91
+ // 2. Sign the payloadHash DIRECTLY — no second hash, no Bitcoin sighash, and no
92
+ // `endian` option. The 32-byte digest is the scalar, big-endian, which is what
93
+ // every other ECDSA implementation does. Passing `endian: 'little'` here is
94
+ // Bitcoin's message-signing convention and produces a signature no conformant
95
+ // BRC-220 verifier will accept.
96
+ const ecdsa = bsv.crypto.ECDSA().set({ hashbuf: payloadHash, privkey: key })
97
+ ecdsa.sign()
98
+ const signatureBuffer = Buffer.concat([ // 64 raw bytes, r || s
99
+ ecdsa.sig.r.toArrayLike(Buffer, 'be', 32),
100
+ ecdsa.sig.s.toArrayLike(Buffer, 'be', 32)
101
+ ])
102
+ const publicKeyBuffer = key.toPublicKey().toBuffer()
103
+
104
+ // 3. Build the certificate. `build` computes proofHash over
105
+ // the canonical bytes — the protocol prefix, version and timestamp are inside
106
+ // proofHash but never on chain, so the record alone cannot reconstruct it.
107
+ const certificate = NotaryHash.Certificate.build({
108
+ mode: NotaryHash.MODE.FULL,
109
+ algorithm: 'ECDSA-secp256k1',
110
+ hashAlgorithm: 'SHA-256',
111
+ payloadHash: payloadHash,
112
+ publicKey: publicKeyBuffer,
113
+ signature: signatureBuffer,
114
+ createdAt: new Date().toISOString(),
115
+ anchor: { txid: txid, blockHeight: height }
116
+ })
117
+
118
+ // 4. The output that goes on chain.
119
+ const script = NotaryHash.Script.build({
120
+ mode: NotaryHash.MODE.FULL,
121
+ algorithm: 'ECDSA-secp256k1',
122
+ hashAlgorithm: 'SHA-256',
123
+ payloadHash: payloadHash,
124
+ proofHash: Buffer.from(certificate.proofHash, 'hex'),
125
+ publicKey: publicKeyBuffer,
126
+ signature: signatureBuffer
127
+ })
128
+
129
+ // 5. Checks. Every verify entry point returns a STRICT boolean.
130
+ NotaryHash.Certificate.proofHashMatches(certificate) // proof integrity, offline
131
+ NotaryHash.Script.isNotaryHash(script) // is this a NotaryHash output
132
+ NotaryHash.isValid(certificate, options) // all three spec checks
133
+ ```
134
+
135
+ **Three modes**, chosen by how much you can afford on chain:
136
+
137
+ | Mode | On chain | Use when |
138
+ |---|---|---|
139
+ | `MODE.FULL` | public key and signature in full | ECDSA, where both are small |
140
+ | `MODE.HYBRID` | `sha256` of each instead | post-quantum signatures, which run to tens of KB |
141
+ | `MODE.BATCH` | a 32-byte Merkle root and a `u32be` leaf count | notarizing many documents in one output |
142
+
143
+ Batch mode uses **RFC 6962** Merkle trees — domain-separated leaves
144
+ (`sha256(0x00‖d)`), internal nodes (`sha256(0x01‖L‖R)`), and a rightmost leaf that
145
+ is *never* duplicated. This is deliberately not the Bitcoin tree in `lib/spv` nor
146
+ the one in `lib/gdaf`; reusing either would produce a root no other BRC-220
147
+ implementation computes. The batch leaf is a certificate's `proofHash` — see
148
+ [`docs/BRC220_BATCH_LEAF_AMENDMENT.md`](./docs/BRC220_BATCH_LEAF_AMENDMENT.md).
149
+
150
+ **Post-quantum signatures are supported but not bundled.** `ECDSA-secp256k1` is
151
+ registered by default; ML-DSA and SLH-DSA are reached by registering a suite, so
152
+ callers who do not need them pay nothing in bundle size or audit surface:
153
+
154
+ ```javascript
155
+ NotaryHash.registerSuite('ML-DSA-65', {
156
+ verify: function (payloadHash, signature, publicKey) { /* ... */ }
157
+ })
158
+ ```
159
+
160
+ An unregistered `algorithm` fails; it never falls through to a default suite.
161
+
66
162
  ## 🆕 **Legally-Recognizable Credentials (v3.4.x+)**
67
163
 
68
164
  ### **Why This Matters**
@@ -76,8 +172,8 @@ const ok = SC.verifyScript(unlockScript, lockingScript, tx, inputIndex, satoshis
76
172
  ### **Quick Start - Issue Your First Verifiable Credential**
77
173
 
78
174
  ```bash
79
- # Install SmartLedger BSV v5.0.0
80
- npm install @smartledger/bsv@5.4.0
175
+ # Install SmartLedger BSV
176
+ npm install @smartledger/bsv
81
177
 
82
178
  # Initialize DID:web issuer (generates ES256 keys)
83
179
  npx smartledger-bsv didweb init --domain example.com --alg ES256
@@ -186,42 +282,42 @@ console.log('Status:', status) // 'revoked'
186
282
  ### **Core Modules**
187
283
  | Module | Size | Use Case | CDN |
188
284
  |--------|------|----------|-----|
189
- | **bsv.min.js** | 1149KB | Core BSV + SmartContract | `unpkg.com/@smartledger/bsv@8.2.0/bsv.min.js` |
190
- | **bsv.bundle.js** | 1149KB | Everything in one file | `unpkg.com/@smartledger/bsv@8.2.0/bsv.bundle.js` |
285
+ | **bsv.min.js** | 1039KB | Core BSV + SmartContract | `unpkg.com/@smartledger/bsv@8.3.1/bsv.min.js` |
286
+ | **bsv.bundle.js** | 1039KB | Everything in one file | `unpkg.com/@smartledger/bsv@8.3.1/bsv.bundle.js` |
191
287
 
192
288
  ### **W3C Verifiable Credentials**
193
289
  | Module | Size | Use Case | CDN |
194
290
  |--------|------|----------|-----|
195
- | **🟢 bsv-didweb.min.js** | 315KB | **DID:web generation** | `unpkg.com/@smartledger/bsv@8.2.0/bsv-didweb.min.js` |
196
- | **🟢 bsv-vcjwt.min.js** | 315KB | **VC-JWT issue/verify** | `unpkg.com/@smartledger/bsv@8.2.0/bsv-vcjwt.min.js` |
197
- | **🟢 bsv-statuslist.min.js** | 415KB | **StatusList2021 revocation** | `unpkg.com/@smartledger/bsv@8.2.0/bsv-statuslist.min.js` |
198
- | **🟢 bsv-anchor.min.js** | 314KB | **BSV anchoring (hash-only)** | `unpkg.com/@smartledger/bsv@8.2.0/bsv-anchor.min.js` |
291
+ | **🟢 bsv-didweb.min.js** | 166KB | **DID:web generation** | `unpkg.com/@smartledger/bsv@8.3.1/bsv-didweb.min.js` |
292
+ | **🟢 bsv-vcjwt.min.js** | 166KB | **VC-JWT issue/verify** | `unpkg.com/@smartledger/bsv@8.3.1/bsv-vcjwt.min.js` |
293
+ | **🟢 bsv-statuslist.min.js** | 256KB | **StatusList2021 revocation** | `unpkg.com/@smartledger/bsv@8.3.1/bsv-statuslist.min.js` |
294
+ | **🟢 bsv-anchor.min.js** | 164KB | **BSV anchoring (hash-only)** | `unpkg.com/@smartledger/bsv@8.3.1/bsv-anchor.min.js` |
199
295
 
200
296
  ### **Smart Contract & Development**
201
297
  | Module | Size | Use Case | CDN |
202
298
  |--------|------|----------|-----|
203
- | **bsv-smartcontract.min.js** | 873KB | Complete covenant framework | `unpkg.com/@smartledger/bsv@8.2.0/bsv-smartcontract.min.js` |
204
- | **bsv-covenant.min.js** | 873KB | Covenant operations | `unpkg.com/@smartledger/bsv@8.2.0/bsv-covenant.min.js` |
205
- | **bsv-script-helper.min.js** | 30KB | Custom script tools | `unpkg.com/@smartledger/bsv@8.2.0/bsv-script-helper.min.js` |
206
- | **bsv-security.min.js** | 30KB | Security enhancements | `unpkg.com/@smartledger/bsv@8.2.0/bsv-security.min.js` |
299
+ | **bsv-smartcontract.min.js** | 140KB | Complete covenant framework | `unpkg.com/@smartledger/bsv@8.3.1/bsv-smartcontract.min.js` |
300
+ | **bsv-covenant.min.js** | 35KB | Covenant operations | `unpkg.com/@smartledger/bsv@8.3.1/bsv-covenant.min.js` |
301
+ | **bsv-script-helper.min.js** | 33KB | Custom script tools | `unpkg.com/@smartledger/bsv@8.3.1/bsv-script-helper.min.js` |
302
+ | **bsv-security.min.js** | 32KB | Security enhancements | `unpkg.com/@smartledger/bsv@8.3.1/bsv-security.min.js` |
207
303
 
208
304
  ### **Legal & Compliance**
209
305
  | Module | Size | Use Case | CDN |
210
306
  |--------|------|----------|-----|
211
- | **bsv-ltp.min.js** | 1149KB | Legal Token Protocol | `unpkg.com/@smartledger/bsv@8.2.0/bsv-ltp.min.js` |
212
- | **bsv-gdaf.min.js** | 1149KB | Digital Identity & Attestation | `unpkg.com/@smartledger/bsv@8.2.0/bsv-gdaf.min.js` |
307
+ | **bsv-ltp.min.js** | 534KB | Legal Token Protocol | `unpkg.com/@smartledger/bsv@8.3.1/bsv-ltp.min.js` |
308
+ | **bsv-gdaf.min.js** | 1039KB | Digital Identity & Attestation | `unpkg.com/@smartledger/bsv@8.3.1/bsv-gdaf.min.js` |
213
309
 
214
310
  ### **Advanced Cryptography**
215
311
  | Module | Size | Use Case | CDN |
216
312
  |--------|------|----------|-----|
217
- | **bsv-shamir.min.js** | 353KB | Threshold Cryptography | `unpkg.com/@smartledger/bsv@8.2.0/bsv-shamir.min.js` |
313
+ | **bsv-shamir.min.js** | 177KB | Threshold Cryptography | `unpkg.com/@smartledger/bsv@8.3.1/bsv-shamir.min.js` |
218
314
 
219
315
  ### **Utilities**
220
316
  | Module | Size | Use Case | CDN |
221
317
  |--------|------|----------|-----|
222
- | **bsv-ecies.min.js** | 79KB | Encryption | `unpkg.com/@smartledger/bsv@8.2.0/bsv-ecies.min.js` |
223
- | **bsv-message.min.js** | 30KB | Message signing | `unpkg.com/@smartledger/bsv@8.2.0/bsv-message.min.js` |
224
- | **bsv-mnemonic.min.js** | 592KB | HD wallets | `unpkg.com/@smartledger/bsv@8.2.0/bsv-mnemonic.min.js` |
318
+ | **bsv-ecies.min.js** | 137KB | Encryption | `unpkg.com/@smartledger/bsv@8.3.1/bsv-ecies.min.js` |
319
+ | **bsv-message.min.js** | 34KB | Message signing | `unpkg.com/@smartledger/bsv@8.3.1/bsv-message.min.js` |
320
+ | **bsv-mnemonic.min.js** | 320KB | HD wallets | `unpkg.com/@smartledger/bsv@8.3.1/bsv-mnemonic.min.js` |
225
321
 
226
322
  ## ⚡ **2-Minute Quick Start**
227
323
 
@@ -232,15 +328,14 @@ Get started with Bitcoin SV development in under 2 minutes:
232
328
  npm install @smartledger/bsv
233
329
 
234
330
  # Or include in HTML
235
- <script src="https://unpkg.com/@smartledger/bsv@8.2.0/bsv.min.js"></script>
331
+ <script src="https://unpkg.com/@smartledger/bsv@8.3.1/bsv.min.js"></script>
236
332
  ```
237
333
 
238
- > **🔒 v5.0.0 (production hardening — has breaking changes):** Shamir secret
239
- > sharing now runs on a vetted GF(2⁸) engine with authenticated shares; VC-JWT
240
- > signatures are now JOSE-compliant (IEEE P1363); VC-JWT verification pins the
241
- > algorithm; ECDSA low-S preserves `recoveryParam`; ECIES MAC check is
242
- > constant-time. **If you are upgrading from 4.x, read [Upgrading to v5.0.0](#upgrading-to-v500-breaking-changes) below.** Builds on the v4.x covenant,
243
- > DID:web + VC-JWT, StatusList2021, and BSV-anchoring toolkit. See CHANGELOG.
334
+ > **🔒 Upgrading?** 8.0.0 changed what `verify()` means with no flags, and moved
335
+ > two flag constants. Read [Upgrading to v8.0.0](#upgrading-to-v800-breaking-changes)
336
+ > before moving from 7.x or earlier; the older
337
+ > [v5.0.0 notes](#upgrading-to-v500-breaking-changes) still apply if you are coming
338
+ > from 4.x.
244
339
 
245
340
  **Basic Transaction (30 seconds):**
246
341
  ```javascript
@@ -263,21 +358,22 @@ console.log('Transaction ID:', tx.id);
263
358
 
264
359
  **🆕 Legal Token Development (60 seconds):**
265
360
  ```javascript
266
- // Create legal property token
267
- const propertyToken = bsv.createPropertyToken({
268
- propertyType: 'real_estate',
269
- jurisdiction: 'us_delaware',
270
- legalDescription: 'Lot 15, Block 3, Subdivision ABC',
271
- ownerIdentity: ownerDID
272
- });
361
+ // Create a legal property-title token
362
+ const result = bsv.LTP.createRightToken({
363
+ type: bsv.LTP.Right.RightTypes.PROPERTY_TITLE,
364
+ owner: ownerDID,
365
+ jurisdiction: 'us_delaware',
366
+ legalDescription: 'Lot 15, Block 3, Subdivision ABC'
367
+ }, issuerPrivateKey);
368
+ console.log(result.success, result.token.tokenHash);
273
369
 
274
370
  // Generate W3C Verifiable Credential
275
371
  const credential = bsv.createEmailCredential(
276
372
  issuerDID, subjectDID, 'user@example.com', issuerPrivateKey
277
373
  );
278
374
 
279
- // Threshold cryptography for secure key management
280
- const shares = bsv.splitSecret('private_key_backup', 5, 3); // 5 shares, 3 needed
375
+ // Threshold cryptography — split(secret, threshold, shares)
376
+ const shares = bsv.Shamir.split('private_key_backup', 3, 5); // 3 of 5 needed
281
377
  ```
282
378
 
283
379
  **🆕 Smart Contract Development (90 seconds):**
@@ -300,11 +396,11 @@ const covenant = bsv.SmartContract.createCovenantBuilder()
300
396
  ```
301
397
 
302
398
  **Next Steps:**
303
- - 📖 [SmartContract Guide](docs/SMART_CONTRACT_GUIDE.md)
304
- - ⚖️ [Legal Token Protocol Guide](docs/LTP_LEGAL_TOKENS_GUIDE.md)
305
- - 🌐 [Digital Identity Guide](docs/GDAF_DIGITAL_ATTESTATION_GUIDE.md)
306
- - � [Threshold Cryptography Guide](docs/SHAMIR_SECRET_SHARING_GUIDE.md)
307
- - �️ [UTXO Manager Guide](docs/UTXO_MANAGER_GUIDE.md)
399
+ - 📖 [SmartContract Guide](docs/advanced/SMART_CONTRACT_GUIDE.md)
400
+ - ⚖️ [Legal Token Protocol Guide](docs/advanced/LEGAL_TOKEN_PROTOCOL.md)
401
+ - 🌐 [Digital Identity Guide](docs/technical/GDAF_DEVELOPER_INTERFACE.md)
402
+ - 🔐 [Threshold Cryptography Guide](docs/technical/SHAMIR_INTEGRATION_SUMMARY.md)
403
+ - 🗃️ [UTXO Manager Guide](docs/advanced/UTXO_MANAGER_GUIDE.md)
308
404
  - 💡 [Examples Directory](https://github.com/codenlighten/smartledger-bsv/tree/main/examples)
309
405
 
310
406
  ## 🔧 **API Reference**
@@ -314,37 +410,37 @@ const covenant = bsv.SmartContract.createCovenantBuilder()
314
410
  | **Core** | `new PrivateKey()` | Generate private key | `const key = new bsv.PrivateKey()` |
315
411
  | | `new Transaction()` | Create transaction | `const tx = new bsv.Transaction()` |
316
412
  | | `Script.fromASM()` | Parse script | `const script = bsv.Script.fromASM('OP_DUP')` |
317
- | **Covenant** | `CovenantInterface()` | Covenant development | `const covenant = new bsv.CovenantInterface()` |
318
- | | `createCovenantTransaction()` | Covenant transaction | `covenant.createCovenantTransaction(config)` |
319
- | | `getPreimage()` | BIP143 preimage | `covenant.getPreimage(tx, 0, script, sats)` |
320
- | **Custom Scripts** | `CustomScriptHelper()` | Script utilities | `const helper = new bsv.CustomScriptHelper()` |
321
- | | `createSignature()` | Manual signature | `helper.createSignature(tx, key, 0, script, sats)` |
322
- | | `createMultisigScript()` | Multi-signature | `helper.createMultisigScript([pk1, pk2], 2)` |
413
+ | **Covenant** | `SmartContract.perpetualCovenant()` | Self-replicating covenant | `SC.perpetualCovenant(500)` |
414
+ | | `SmartContract.verifyScript()` | Verify a script pair; returns `{ ok, err }` | `SC.verifyScript(unlock, lock, { tx, satoshis })` |
415
+ | | `CustomScriptHelper.getPreimage()` | BIP143 preimage | `bsv.CustomScriptHelper.getPreimage(tx, 0, script, sats)` |
416
+ | **Custom Scripts** | `CustomScriptHelper` | Script utilities — **all methods are static**, do not instantiate | `bsv.CustomScriptHelper.createDataScript(data)` |
417
+ | | `createSignature()` | Manual signature | `bsv.CustomScriptHelper.createSignature(tx, key, 0, script, sats)` |
418
+ | | `createMultisigScript()` | Multi-signature | `bsv.CustomScriptHelper.createMultisigScript(2, [pk1, pk2])` |
323
419
  | **Debug Tools** | `SmartContract.examineStack()` | Analyze script | `SmartContract.examineStack(script)` |
324
420
  | | `interpretScript()` | Execute script | `SmartContract.interpretScript(script)` |
325
421
  | | `getScriptMetrics()` | Performance data | `SmartContract.getScriptMetrics(script)` |
326
- | **Security (opt-in)** | `SmartVerify.verify()` | Hardened verify with strict input validation — call explicitly; default `signature.verify()` does NOT route through this | `SmartVerify.verify(sig, hash, pubkey)` |
327
- | | `EllipticFixed.sign()` | Canonicalized signing wrapper around elliptic | `EllipticFixed.sign(hash, privateKey)` |
422
+ | **Security (opt-in)** | `SmartVerify.smartVerify()` | Hardened verify with strict input validation — call explicitly; default `signature.verify()` does NOT route through this | `bsv.SmartVerify.smartVerify(msgHash, sig, pubkey)` |
423
+ | | `EllipticFixed.sign()` | Canonicalized signing wrapper over the `@noble` secp256k1 backend | `bsv.EllipticFixed.sign(hash, privateKey)` |
328
424
 
329
425
  > 💡 **Tip:** All methods include comprehensive error handling and validation. See [documentation links](#documentation) for detailed guides.
330
426
 
331
427
  ## 📚 **Quick Start Examples**
332
428
 
333
- ### 🔧 **Basic Development** (~1.2MB total)
429
+ ### 🔧 **Basic Development** (~1.05MB total)
334
430
  ```html
335
- <script src="https://unpkg.com/@smartledger/bsv@8.2.0/bsv.min.js"></script>
336
- <script src="https://unpkg.com/@smartledger/bsv@8.2.0/bsv-script-helper.min.js"></script>
431
+ <script src="https://unpkg.com/@smartledger/bsv@8.3.1/bsv.min.js"></script>
432
+ <script src="https://unpkg.com/@smartledger/bsv@8.3.1/bsv-script-helper.min.js"></script>
337
433
  <script>
338
434
  const privateKey = new bsv.PrivateKey();
339
435
  const utxos = new bsv.SmartContract.UTXOGenerator().createRealUTXOs(2, 100000);
340
436
  </script>
341
437
  ```
342
438
 
343
- ### 🔒 **Smart Contract Development** (~2.8MB total — each bundle re-embeds core BSV)
439
+ ### 🔒 **Smart Contract Development** (~1.2MB total — each bundle re-embeds core BSV)
344
440
  ```html
345
- <script src="https://unpkg.com/@smartledger/bsv@8.2.0/bsv.min.js"></script>
346
- <script src="https://unpkg.com/@smartledger/bsv@8.2.0/bsv-covenant.min.js"></script>
347
- <script src="https://unpkg.com/@smartledger/bsv@8.2.0/bsv-smartcontract.min.js"></script>
441
+ <script src="https://unpkg.com/@smartledger/bsv@8.3.1/bsv.min.js"></script>
442
+ <script src="https://unpkg.com/@smartledger/bsv@8.3.1/bsv-covenant.min.js"></script>
443
+ <script src="https://unpkg.com/@smartledger/bsv@8.3.1/bsv-smartcontract.min.js"></script>
348
444
  <script>
349
445
  const covenant = bsv.SmartContract.createCovenantBuilder()
350
446
  .extractField('amount').push(50000).greaterThanOrEqual().verify().build();
@@ -352,44 +448,45 @@ const covenant = bsv.SmartContract.createCovenantBuilder()
352
448
  </script>
353
449
  ```
354
450
 
355
- ### 🆕 **Legal & Identity Development** (~3.4MB total — each bundle re-embeds core BSV)
451
+ ### 🆕 **Legal & Identity Development** (~2.55MB total — each bundle re-embeds core BSV)
356
452
  ```html
357
- <script src="https://unpkg.com/@smartledger/bsv@8.2.0/bsv.min.js"></script>
358
- <script src="https://unpkg.com/@smartledger/bsv@8.2.0/bsv-ltp.min.js"></script>
359
- <script src="https://unpkg.com/@smartledger/bsv@8.2.0/bsv-gdaf.min.js"></script>
453
+ <script src="https://unpkg.com/@smartledger/bsv@8.3.1/bsv.min.js"></script>
454
+ <script src="https://unpkg.com/@smartledger/bsv@8.3.1/bsv-ltp.min.js"></script>
455
+ <script src="https://unpkg.com/@smartledger/bsv@8.3.1/bsv-gdaf.min.js"></script>
360
456
  <script>
361
457
  // Legal Token Protocol
362
- const propertyToken = bsv.createPropertyToken({
363
- propertyType: 'real_estate', jurisdiction: 'us_delaware'
364
- });
458
+ const result = bsv.LTP.createRightToken({
459
+ type: bsv.LTP.Right.RightTypes.PROPERTY_TITLE,
460
+ owner: ownerDID, jurisdiction: 'us_delaware'
461
+ }, key);
365
462
 
366
463
  // Digital Identity
367
464
  const credential = bsv.createEmailCredential(issuerDID, subjectDID, 'user@example.com', key);
368
465
  </script>
369
466
  ```
370
467
 
371
- ### 🆕 **Security & Cryptography** (~1.5MB total)
468
+ ### 🆕 **Security & Cryptography** (~1.22MB total)
372
469
  ```html
373
- <script src="https://unpkg.com/@smartledger/bsv@8.2.0/bsv.min.js"></script>
374
- <script src="https://unpkg.com/@smartledger/bsv@8.2.0/bsv-security.min.js"></script>
375
- <script src="https://unpkg.com/@smartledger/bsv@8.2.0/bsv-shamir.min.js"></script>
470
+ <script src="https://unpkg.com/@smartledger/bsv@8.3.1/bsv.min.js"></script>
471
+ <script src="https://unpkg.com/@smartledger/bsv@8.3.1/bsv-security.min.js"></script>
472
+ <script src="https://unpkg.com/@smartledger/bsv@8.3.1/bsv-shamir.min.js"></script>
376
473
  <script>
377
474
  // Threshold Cryptography
378
- const shares = bsv.splitSecret('my_secret_key', 5, 3); // 5 shares, 3 needed
475
+ const shares = bsv.Shamir.split('my_secret_key', 3, 5); // 5 shares, any 3 recover
379
476
 
380
477
  // Enhanced Security
381
- const verified = bsvSecurity.SmartVerify.verify(signature, hash, publicKey);
478
+ const verified = bsvSecurity.SmartVerify.smartVerify(hash, signature, publicKey);
382
479
  </script>
383
480
  ```
384
481
 
385
- ### 🎯 **Everything Bundle** (~1.1MB)
482
+ ### 🎯 **Everything Bundle** (~1.02MB)
386
483
  ```html
387
- <script src="https://unpkg.com/@smartledger/bsv@8.2.0/bsv.bundle.js"></script>
484
+ <script src="https://unpkg.com/@smartledger/bsv@8.3.1/bsv.bundle.js"></script>
388
485
  <script>
389
486
  // Everything available immediately
390
- const shares = bsv.splitSecret('secret', 5, 3); // Shamir Secret Sharing
391
- const credential = bsv.createDID(publicKey); // Digital Identity
392
- const propertyToken = bsv.createPropertyToken({...}); // Legal Tokens
487
+ const shares = bsv.Shamir.split('secret', 3, 5); // Shamir Secret Sharing
488
+ const did = bsv.createDID(publicKey); // Digital Identity
489
+ const token = bsv.LTP.createRightToken({ /* ... */ }, key); // Legal Tokens
393
490
  const covenant = bsv.SmartContract.createCovenantBuilder(); // Smart Contracts
394
491
  </script>
395
492
  ```
@@ -397,10 +494,10 @@ const covenant = bsv.SmartContract.createCovenantBuilder()
397
494
  ## 🎯 **Key Features**
398
495
 
399
496
  ### 🚀 **Unique Capabilities** (Only Bitcoin Library with These Features)
400
- - ✅ **Legal Token Protocol**: Compliant tokenization of real-world assets → [Legal Guide](docs/LTP_LEGAL_TOKENS_GUIDE.md)
401
- - ✅ **Digital Identity Framework**: W3C Verifiable Credentials and DIDs → [Identity Guide](docs/GDAF_DIGITAL_ATTESTATION_GUIDE.md)
402
- - ✅ **Threshold Cryptography**: Shamir Secret Sharing for secure key management → [Cryptography Guide](docs/SHAMIR_SECRET_SHARING_GUIDE.md)
403
- - ✅ **Complete Smart Contract Suite**: 23+ production-ready covenant features → [SmartContract Guide](docs/SMART_CONTRACT_GUIDE.md)
497
+ - ✅ **Legal Token Protocol**: Compliant tokenization of real-world assets → [Legal Guide](docs/advanced/LEGAL_TOKEN_PROTOCOL.md)
498
+ - ✅ **Digital Identity Framework**: W3C Verifiable Credentials and DIDs → [Identity Guide](docs/technical/GDAF_DEVELOPER_INTERFACE.md)
499
+ - ✅ **Threshold Cryptography**: Shamir Secret Sharing for secure key management → [Cryptography Guide](docs/technical/SHAMIR_INTEGRATION_SUMMARY.md)
500
+ - ✅ **Complete Smart Contract Suite**: 23+ production-ready covenant features → [SmartContract Guide](docs/advanced/SMART_CONTRACT_GUIDE.md)
404
501
 
405
502
  ### 💼 **Core Library Excellence**
406
503
  - ✅ **Complete BSV API**: Full Bitcoin SV blockchain operations → [API Reference](#-api-reference)
@@ -410,14 +507,14 @@ const covenant = bsv.SmartContract.createCovenantBuilder()
410
507
  - ✅ **Ultra-Low Fees**: 0.01 sats/byte configuration (91% fee reduction)
411
508
 
412
509
  ### 🛠️ **Advanced Development Tools**
413
- - 🔧 **JavaScript-to-Script**: High-level covenant development with 121 opcode mapping → [Covenant Guide](docs/ADVANCED_COVENANT_DEVELOPMENT.md)
414
- - 🔧 **UTXO Generator**: Create authentic test UTXOs for development → [UTXO Guide](docs/UTXO_MANAGER_GUIDE.md)
510
+ - 🔧 **JavaScript-to-Script**: High-level covenant development with 121 opcode mapping → [Covenant Guide](docs/advanced/ADVANCED_COVENANT_DEVELOPMENT.md)
511
+ - 🔧 **UTXO Generator**: Create authentic test UTXOs for development → [UTXO Guide](docs/advanced/UTXO_MANAGER_GUIDE.md)
415
512
  - 🔧 **Preimage Parser**: Complete BIP-143 field extraction and manipulation → [Preimage Tools](https://github.com/codenlighten/smartledger-bsv/tree/main/examples/preimage)
416
- - � **Debug Framework**: Script interpreter, stack examiner, and optimizer → [Debug Examples](https://github.com/codenlighten/smartledger-bsv/blob/main/tests/smartcontract-test.html)
417
- - � **PUSHTX Integration**: nChain techniques for advanced covenant patterns → [PUSHTX Insights](docs/pushtx-key-insights.md)
513
+ - 🔧 **Debug Framework**: Script interpreter, stack examiner, and optimizer → [Debug Examples](https://github.com/codenlighten/smartledger-bsv/blob/main/tests/smartcontract-test.html)
514
+ - 🔧 **PUSHTX Integration**: nChain techniques for advanced covenant patterns → [PUSHTX Insights](docs/pushtx-key-insights.md)
418
515
 
419
516
  ### 📦 **Flexible Architecture**
420
- - 📦 **16 Modular Options**: Load only what you need (30KB to 1149KB) → [Loading Strategy](#-16-loading-options---choose-your-approach)
517
+ - 📦 **16 Modular Options**: Load only what you need (32KB to 1039KB) → [Loading Strategy](#-16-loading-options---choose-your-approach)
421
518
  - 📦 **Standalone Modules**: Independent legal, identity, and crypto modules → [Standalone Test](https://github.com/codenlighten/smartledger-bsv/blob/main/tests/standalone-modules-test.html)
422
519
  - 📦 **Complete Bundle**: Everything in one file for convenience → [Bundle Demo](https://github.com/codenlighten/smartledger-bsv/blob/main/tests/bundle-demo.html)
423
520
  - 📦 **CDN Ready**: All modules available via unpkg and jsDelivr
@@ -429,15 +526,45 @@ const covenant = bsv.SmartContract.createCovenantBuilder()
429
526
 
430
527
  ### NPM Installation
431
528
  ```bash
432
- # Main package
433
529
  npm install @smartledger/bsv
434
-
435
- # Alternative package name (legacy)
436
- npm install smartledger-bsv
437
530
  ```
438
531
 
439
532
  > 📖 **Next Steps**: After installation, see [Loading Options](#-16-loading-options---choose-your-approach) to choose your distribution method
440
533
 
534
+ ### Upgrading to v8.0.0 (Breaking Changes)
535
+
536
+ 8.0.0 moved the defaults onto BSV as the network actually runs it. Two changes
537
+ need action.
538
+
539
+ **1. `verify()` with no flags now means BSV mainnet, not "no rules".**
540
+
541
+ ```javascript
542
+ interp.verify(sig, pubkey, tx, nin) // was: Bitcoin 2015; now: current mainnet
543
+ interp.verify(sig, pubkey, tx, nin, 0) // the old behaviour, stated explicitly
544
+
545
+ // Spending a pre-Chronicle output — state the era of the output being spent,
546
+ // because that is the input the caller knows and the library cannot infer.
547
+ bsv.Script.Interpreter.mainnetFlags({ afterChronicle: false })
548
+ ```
549
+
550
+ **2. Two flag constants changed numeric value.** The node assigns `1<<18` and
551
+ `1<<19` to `SCRIPT_GENESIS` and `SCRIPT_UTXO_AFTER_GENESIS`, so ours had to move:
552
+
553
+ ```
554
+ SCRIPT_ENABLE_MONOLITH_OPCODES 1<<18 → 1<<11
555
+ SCRIPT_ENABLE_MAGNETIC_OPCODES 1<<19 → 1<<12
556
+ ```
557
+
558
+ Code using the **named constants** is unaffected. Code that **persisted or
559
+ hardcoded the numbers** must be updated: `262144` no longer means "Monolith
560
+ opcodes", it now means `SCRIPT_GENESIS`, so a stored value silently selects a
561
+ different era model.
562
+
563
+ Also in 8.0.0: a signature carrying `SIGHASH_CHRONICLE` outside Chronicle is
564
+ rejected rather than reinterpreted, and `MAX_OPS_PER_SCRIPT` is BSV's 500 rather
565
+ than Bitcoin Core's 201. Full details in the
566
+ [CHANGELOG](./CHANGELOG.md#800---2026-08-13).
567
+
441
568
  ### Upgrading to v5.0.0 (Breaking Changes)
442
569
 
443
570
  v5.0.0 hardens the cryptography. Most apps need **no code changes** — the
@@ -462,9 +589,9 @@ breaking changes only affect data produced by older versions:
462
589
  outside `['ES256','ES256K']` (override via `opts.allowedAlgs`) and binds the
463
590
  key's curve to the algorithm — defense against alg-substitution attacks.
464
591
  - **Browser bundles changed size.** The full bundles ship a real `crypto`
465
- polyfill so Shamir can source a CSPRNG (`bsv.min.js` ~937KB → ~1.1MB; it grew
466
- in 5.0.0 then shrank again in 5.4.0 once `elliptic` was dropped from the
467
- bundles). The dedicated single-feature module bundles are unaffected.
592
+ polyfill so Shamir can source a CSPRNG. Sizes have moved since; `bsv.min.js` is
593
+ ~1039KB at 8.3.0, after the ~20% reduction in 8.0.0. The dedicated
594
+ single-feature module bundles are unaffected.
468
595
 
469
596
  Full details in the [CHANGELOG](./CHANGELOG.md#500---2026-06-13).
470
597
 
@@ -482,57 +609,57 @@ const script = bsv.Script.fromASM('OP_1 OP_2 OP_ADD OP_3 OP_EQUAL');
482
609
  const metrics = bsv.SmartContract.getScriptMetrics(script);
483
610
  const stackInfo = bsv.SmartContract.examineStack(script);
484
611
 
485
- // Covenant development
486
- const covenant = new bsv.CovenantInterface();
487
- const contractTx = covenant.createCovenantTransaction({
488
- inputs: [...],
489
- outputs: [...]
490
- });
612
+ // Covenant development — see bsv.SmartContract for the covenant stack
613
+ const lock = bsv.SmartContract.perpetualCovenant(500);
614
+ const { ok, err } = bsv.SmartContract.verifyScript(unlockScript, lock, { tx, satoshis });
491
615
  ```
492
616
 
493
617
  ### Browser CDN (Choose Your Loading Strategy)
494
618
 
495
- #### 1. **Minimal Setup** - Core + Script Helper (~1.2MB)
619
+ #### 1. **Minimal Setup** - Core + Script Helper (~1.05MB)
496
620
  ```html
497
- <script src="https://unpkg.com/@smartledger/bsv@8.2.0/bsv.min.js"></script>
498
- <script src="https://unpkg.com/@smartledger/bsv@8.2.0/bsv-script-helper.min.js"></script>
621
+ <script src="https://unpkg.com/@smartledger/bsv@8.3.1/bsv.min.js"></script>
622
+ <script src="https://unpkg.com/@smartledger/bsv@8.3.1/bsv-script-helper.min.js"></script>
499
623
  <script>
500
624
  const tx = new bsv.Transaction();
501
625
  const sig = bsvScriptHelper.createSignature(tx, privateKey, 0, script, satoshis);
502
626
  </script>
503
627
  ```
504
628
 
505
- #### 2. **DeFi Development** - Core + Covenants + Debug (~2.8MB — each bundle re-embeds core BSV)
629
+ #### 2. **DeFi Development** - Core + Covenants + Debug (~1.2MB — each bundle re-embeds core BSV)
506
630
  ```html
507
- <script src="https://unpkg.com/@smartledger/bsv@8.2.0/bsv.min.js"></script>
508
- <script src="https://unpkg.com/@smartledger/bsv@8.2.0/bsv-covenant.min.js"></script>
509
- <script src="https://unpkg.com/@smartledger/bsv@8.2.0/bsv-smartcontract.min.js"></script>
631
+ <script src="https://unpkg.com/@smartledger/bsv@8.3.1/bsv.min.js"></script>
632
+ <script src="https://unpkg.com/@smartledger/bsv@8.3.1/bsv-covenant.min.js"></script>
633
+ <script src="https://unpkg.com/@smartledger/bsv@8.3.1/bsv-smartcontract.min.js"></script>
510
634
  <script>
511
- const covenant = new bsvCovenant.CovenantInterface();
512
- const debugInfo = SmartContract.interpretScript(script);
513
- const optimized = SmartContract.optimizeScript(script);
635
+ const lock = bsv.SmartContract.perpetualCovenant(500);
636
+ const debugInfo = bsv.SmartContract.interpretScript(script);
637
+ const optimized = bsv.SmartContract.optimizeScript(script);
514
638
  </script>
515
639
  ```
516
640
 
517
- #### 3. **Security First** - Core + Enhanced Security (~1.2MB)
641
+ #### 3. **Security First** - Core + Enhanced Security (~1.05MB)
518
642
  ```html
519
- <script src="https://unpkg.com/@smartledger/bsv@8.2.0/bsv.min.js"></script>
520
- <script src="https://unpkg.com/@smartledger/bsv@8.2.0/bsv-security.min.js"></script>
643
+ <script src="https://unpkg.com/@smartledger/bsv@8.3.1/bsv.min.js"></script>
644
+ <script src="https://unpkg.com/@smartledger/bsv@8.3.1/bsv-security.min.js"></script>
521
645
  <script>
522
- const verified = bsvSecurity.SmartVerify.verify(signature, hash, publicKey);
523
- const enhanced = bsvSecurity.EllipticFixed.createSignature(privateKey, hash);
646
+ const verified = bsvSecurity.SmartVerify.smartVerify(hash, signature, publicKey);
647
+ const enhanced = bsvSecurity.EllipticFixed.sign(hash, privateKey);
524
648
  </script>
525
649
  ```
526
650
 
527
- #### 4. **Everything Bundle** - One File Solution (~1.1MB)
651
+ #### 4. **Everything Bundle** - One File Solution (~1.02MB)
528
652
  ```html
529
- <script src="https://unpkg.com/@smartledger/bsv@8.2.0/bsv.bundle.js"></script>
653
+ <script src="https://unpkg.com/@smartledger/bsv@8.3.1/bsv.bundle.js"></script>
530
654
  <script>
531
- // Everything available under bsv namespace
532
- const keys = bsv.SmartLedgerBundle.generateKeys();
533
- const covenant = new bsv.CovenantInterface();
655
+ // Everything available under the bsv namespace
656
+ const key = bsv.PrivateKey.fromRandom();
657
+ const lock = bsv.SmartContract.perpetualCovenant(500);
534
658
  const message = new bsv.Message('Hello BSV');
535
- const encrypted = bsv.ECIES.encrypt('secret', publicKey);
659
+ const encrypted = new bsv.ECIES()
660
+ .privateKey(key)
661
+ .publicKey(recipientPublicKey)
662
+ .encrypt('secret');
536
663
  </script>
537
664
  ```
538
665
 
@@ -581,27 +708,30 @@ const utxoManager = {
581
708
  ```javascript
582
709
  const bsv = require('@smartledger/bsv');
583
710
 
584
- // Create property rights token
585
- const propertyToken = bsv.createPropertyToken({
586
- propertyType: 'real_estate',
711
+ // Create a property-rights token. `type` must be one of LTP.Right.RightTypes —
712
+ // an unrecognized type is rejected rather than silently accepted.
713
+ const result = bsv.LTP.createRightToken({
714
+ type: bsv.LTP.Right.RightTypes.PROPERTY_TITLE,
715
+ owner: ownerDID,
587
716
  jurisdiction: 'us_delaware',
588
- legalDescription: 'Lot 15, Block 3, Subdivision ABC',
589
- ownerIdentity: ownerDID,
590
- attestations: [titleAttestation, valuationAttestation]
591
- });
717
+ legalDescription: 'Lot 15, Block 3, Subdivision ABC'
718
+ }, issuerPrivateKey);
592
719
 
593
- // Create obligation token
594
- const obligation = bsv.createObligationToken({
720
+ console.log(result.success); // true
721
+ console.log(result.token.tokenHash); // hash committed by the token's proof
722
+
723
+ // Obligation tokens
724
+ const obligation = bsv.LTP.Obligation.prepareObligationToken({
595
725
  obligationType: 'payment',
596
726
  amount: 100000, // satoshis
597
- dueDate: '2025-12-31',
727
+ dueDate: '2026-12-31',
598
728
  creditor: creditorDID,
599
729
  debtor: debtorDID
600
730
  });
601
731
 
602
- // Validate legal compliance
603
- const compliance = bsv.validateLegalCompliance(propertyToken, 'us_delaware');
604
- console.log('Legally compliant:', compliance.isValid);
732
+ // Validate claim data against a registered schema
733
+ // (schema names come from bsv.LTP.Claim.getSchemaNames())
734
+ const validation = bsv.validateLegalClaim(claimData, schemaType);
605
735
  ```
606
736
 
607
737
  ### 🌐 Global Digital Attestation Framework (GDAF)
@@ -634,23 +764,20 @@ const gdaf = new bsv.GDAF({
634
764
 
635
765
  ### 🔐 Shamir Secret Sharing
636
766
  ```javascript
637
- // Split secret into threshold shares
767
+ // Split a secret into threshold shares.
768
+ // Signature is split(secret, threshold, shares) — THRESHOLD FIRST.
638
769
  const secret = 'my_private_key_backup';
639
- const shares = bsv.splitSecret(secret, 5, 3); // 5 shares, need 3 to reconstruct
770
+ const shares = bsv.Shamir.split(secret, 3, 5); // 5 shares, any 3 reconstruct
640
771
 
641
772
  console.log('Generated', shares.length, 'shares');
642
- shares.forEach((share, i) => {
643
- console.log(`Share ${i + 1}:`, share);
644
- });
645
773
 
646
- // Reconstruct secret from any 3 shares
647
- const reconstructed = bsv.reconstructSecret([shares[0], shares[2], shares[4]]);
648
- console.log('Secret recovered:', reconstructed === secret);
774
+ // Reconstruct from any 3 shares
775
+ const reconstructed = bsv.Shamir.combine([shares[0], shares[2], shares[4]]);
776
+ console.log('Secret recovered:', reconstructed === secret); // true
649
777
 
650
778
  // Validate share integrity
651
779
  shares.forEach((share, i) => {
652
- const isValid = bsv.validateShare(share);
653
- console.log(`Share ${i + 1} valid:`, isValid);
780
+ console.log(`Share ${i + 1} valid:`, bsv.Shamir.verifyShare(share));
654
781
  });
655
782
 
656
783
  // Use cases: Key backup, multi-party security, recovery systems
@@ -677,7 +804,7 @@ const custom = new CovenantBuilder()
677
804
  .push(1);
678
805
  ```
679
806
 
680
- ### Complete Opcode Mapping (121 Opcodes)
807
+ ### Complete Opcode Mapping (116 Opcodes)
681
808
  ```javascript
682
809
  const SmartContract = require('@smartledger/bsv/lib/smart_contract');
683
810
 
@@ -687,7 +814,7 @@ console.log(result.finalStack); // ['01'] - TRUE
687
814
 
688
815
  // Get comprehensive opcode information
689
816
  const opcodes = SmartContract.getOpcodeMap();
690
- console.log(Object.keys(opcodes).length); // 121 opcodes mapped
817
+ console.log(Object.keys(opcodes).length); // 116 opcodes mapped
691
818
  ```
692
819
 
693
820
  ### BIP143 Preimage Parsing
@@ -702,7 +829,7 @@ console.log('Amount:', preimage.amountValue); // BigInt accessor
702
829
  console.log('Valid structure:', preimage.isValid); // Boolean validation
703
830
  ```
704
831
 
705
- ### PUSHTX Covenants (nChain WP1605) — v4.2.0 API
832
+ ### PUSHTX Covenants (nChain WP1605)
706
833
  ```javascript
707
834
  const bsv = require('@smartledger/bsv')
708
835
  const SC = bsv.SmartContract
@@ -720,7 +847,7 @@ const requiredOutputs = [/* bsv.Transaction.Output objects */]
720
847
  const valueLock = SC.PushTx.valueCovenant(SC.PushTx.hashOutputs(requiredOutputs))
721
848
  ```
722
849
 
723
- ### Perpetually Enforcing Locking Scripts (PELS) — v4.2.0 API
850
+ ### Perpetually Enforcing Locking Scripts (PELS)
724
851
  ```javascript
725
852
  // Self-replicating covenant: every spend must recreate the same script
726
853
  // (value − fee), reading its own code out of the authenticated preimage's
@@ -728,7 +855,7 @@ const valueLock = SC.PushTx.valueCovenant(SC.PushTx.hashOutputs(requiredOutputs)
728
855
  const pels = SC.perpetualCovenant(500) // fee in satoshis deducted each hop
729
856
  ```
730
857
 
731
- ### Ownership Tokens (NFT) — v4.2.0 API
858
+ ### Ownership Tokens (NFT)
732
859
  ```javascript
733
860
  // Stateful ownership token. Owner is carried as on-chain state (HASH160 of the
734
861
  // owner's public key); transfer requires the current owner's ECDSA SIGNATURE over
@@ -764,36 +891,47 @@ const multi = SC.Token.ownershipTokenMulti(ownerHash)
764
891
  const ok = SC.verifyScript(unlockScript, lockingScript, tx, inputIndex, satoshis)
765
892
  ```
766
893
 
767
- ### Evaluating covenants locally — `Interpreter.useGenesisLimits()` (v4.1.0+)
894
+ ### Consensus defaults — BSV mainnet, no flags required (8.0.0+)
768
895
 
769
- The bundled `Script.Interpreter` defaults to **pre-Genesis** BSV consensus
770
- caps — 520-byte stack elements, 4-byte script numbers, 201 opcodes per
771
- script — which BSV removed at the Genesis upgrade (Feb 2020). Those caps
772
- make it impossible to evaluate this library's own flagship features:
773
- OP_PUSH_TX covenants push a ~585-byte preimage, do 32-byte modular
774
- arithmetic, and run a few hundred opcodes.
775
-
776
- Opt into post-Genesis rules with a single call at app startup:
896
+ **Since 8.0.0 you do not opt in to BSV.** `verify()` with no flags means
897
+ current BSV mainnet consensus, and `MAX_OPS_PER_SCRIPT` is BSV's 500 rather
898
+ than Bitcoin Core's 201. Earlier versions defaulted to a 2015-era Bitcoin
899
+ rule set and required an explicit call to reach post-Genesis behaviour; that
900
+ is no longer the case.
777
901
 
778
902
  ```javascript
779
903
  const bsv = require('@smartledger/bsv');
904
+ const interp = new bsv.Script.Interpreter();
905
+
906
+ // Current BSV mainnet — this is the default.
907
+ const ok = interp.verify(unlockScript, lockScript, tx, 0, undefined, satoshisBN);
780
908
 
781
- // Default: bound the limits to a safe ceiling (covers every covenant
782
- // pattern seen in production, blocks oversized-push memory DoS).
783
- bsv.Script.Interpreter.useGenesisLimits(64 * 1024);
909
+ // Spending a pre-Chronicle output: state the era of the output you are spending,
910
+ // because the library cannot infer it.
911
+ const flags = bsv.Script.Interpreter.mainnetFlags({ afterChronicle: false });
912
+ const ok2 = interp.verify(unlockScript, lockScript, tx, 0, flags, satoshisBN);
784
913
 
785
- // Or, for fully unbounded (~2 GB) — only safe for trusted scripts:
786
- // bsv.Script.Interpreter.useGenesisLimits();
914
+ // The pre-8.0.0 "no rules" behaviour, if you genuinely want it, is now explicit:
915
+ const ok3 = interp.verify(unlockScript, lockScript, tx, 0, 0, satoshisBN);
916
+ ```
917
+
918
+ **Covenants need no special setup.** The element and script-number caps are
919
+ derived from the era flags, not from the `MAX_SCRIPT_ELEMENT_SIZE` static — which
920
+ still reads 520 because it is only the pre-Genesis fallback. An OP_PUSH_TX
921
+ covenant pushing a ~585-byte preimage verifies under the defaults:
787
922
 
788
- // Now OP_PUSH_TX covenants verify locally:
923
+ ```javascript
789
924
  const interp = new bsv.Script.Interpreter();
790
- const ok = interp.verify(unlockScript, lockScript, tx, 0, flags, satoshisBN);
925
+ const ok = interp.verify(unlockScript, lockScript, tx, 0, undefined, satoshisBN);
791
926
  ```
792
927
 
793
- This is a **process-wide** setting — once called, every subsequent
794
- `new Interpreter()` runs with lifted caps. Defaults are unchanged out of
795
- the box; if you don't call `useGenesisLimits()`, behavior is identical
796
- to pre-v4.1.0.
928
+ > ⚠️ **`Interpreter.useGenesisLimits()` is legacy and should not be used to enable
929
+ > covenants.** It cannot enable post-Genesis arithmetic — that comes from the era
930
+ > flags — and because it mutates process-wide statics it *weakens* pre-Genesis
931
+ > validation: raising `MAXIMUM_ELEMENT_SIZE` turns 15 of the reference node's 22
932
+ > `SCRIPTNUM_OVERFLOW` vectors into false accepts. If you must call it, capture
933
+ > and restore the caps around it with `Interpreter.getLimits()` /
934
+ > `Interpreter.setLimits()`.
797
935
 
798
936
  ## 🛠️ Custom Scripts
799
937
 
@@ -834,7 +972,7 @@ const timelockScript = helper.createTimelockScript(
834
972
 
835
973
  See the **[16 Loading Options](#-16-loading-options---choose-your-approach)**
836
974
  table near the top for the full list of bundles with current sizes and
837
- canonical `unpkg.com/@smartledger/bsv@8.2.0/...` URLs.
975
+ canonical `unpkg.com/@smartledger/bsv@8.3.1/...` URLs.
838
976
 
839
977
  ## 🔐 Security
840
978
 
@@ -842,10 +980,10 @@ canonical `unpkg.com/@smartledger/bsv@8.2.0/...` URLs.
842
980
 
843
981
  | Surface | Status | Notes |
844
982
  |---------|--------|-------|
845
- | `elliptic@6.6.1` (pinned) | upstream-patched | All known CVEs through 6.6.1 are fixed by elliptic itself. SmartLedger does not patch elliptic's source. |
983
+ | secp256k1 primitives | `@noble/curves` | `elliptic` was removed entirely — it is not a dependency and is not in the bundles. The Noble suite carries a published Cure53 audit. |
846
984
  | Default `transaction.verify()` / `signature.verify()` / `Message().verify()` | uses BSV's own `lib/crypto/ecdsa.js` | This path does **not** import elliptic and is **not** routed through `SmartVerify` or `EllipticFixed`. |
847
985
  | `bsv.SmartVerify` (opt-in helper) | available | Hardened standalone verify: rejects `r=0`, `s=0`, `r≥n`, `s≥n`; canonicalizes `s` to low half. Built on BSV's own `BN`/`ECDSA`. You must call it explicitly. |
848
- | `bsv.EllipticFixed` (opt-in helper) | available | Wraps the elliptic `secp256k1` instance with the same input checks + low-`s` on sign. Only matters if you use elliptic directly. |
986
+ | `bsv.EllipticFixed` (opt-in helper) | available | An elliptic-*compatible* secp256k1 surface — the name is kept for API compatibility, but it is backed by `@noble/curves`. Adds the same input checks plus low-`s` on sign. |
849
987
  | `signature.validate()` / `isCanonical()` / `toCanonical()` | available | Real methods on `bsv.Signature`. |
850
988
  | DER canonicalization on TX signing | available | BSV's signature path produces low-`s` DER by default. |
851
989
  | BIP143 preimage utilities | available | `lib/smart_contract/preimage.js` and `examples/preimage/`. |
@@ -864,8 +1002,8 @@ const okDefault = bsv.crypto.ECDSA.verify(msgHashBuffer, signature, publicKey)
864
1002
 
865
1003
  ### What this library does **not** claim
866
1004
 
867
- - It does not silently route every `verify()` call through `SmartVerify`. If you want the strict input validation on every verification, call `SmartVerify` explicitly or wrap `bsv.Signature.prototype.verify`.
868
- - It does not patch the elliptic library's source — the patches in `lib/crypto/elliptic-fixed.js` add input validation on top of an already-upstream-patched `elliptic@6.6.1`.
1005
+ - It does not silently route every `verify()` call through `SmartVerify`. If you want the strict input validation on every verification, call `SmartVerify` explicitly or wrap `bsv.crypto.ECDSA.prototype.verify`.
1006
+ - It no longer depends on `elliptic` at all. `lib/crypto/elliptic-fixed.js` keeps the name for API compatibility but is backed by `@noble/curves`; it adds input validation and low-`s` canonicalization on top of that.
869
1007
  - It does not turn `bsv.isHardened = true` into an automatic guarantee. That property indicates the hardening helpers ship; whether they're used is up to your code.
870
1008
 
871
1009
  v4.0.0 fixed three critical, exploitable vulnerabilities in the GDAF
@@ -881,23 +1019,27 @@ and [SECURITY.md](./SECURITY.md) for the supported-versions policy.
881
1019
  ## 📝 Changelog
882
1020
 
883
1021
  The authoritative version history lives in [CHANGELOG.md](./CHANGELOG.md).
884
- Highlights of the v4.x line:
885
-
886
- - **[4.2.0](./CHANGELOG.md#420---2026-06-07)** — first-class
887
- interpreter-verified covenants (`SmartContract.PushTx`, `PELS`,
888
- `Token`, `Locks`, `verifyScript`) with positive + negative test coverage.
889
- - **[4.1.0](./CHANGELOG.md#410---2026-06-07)** — `Interpreter.useGenesisLimits()`
890
- one-call opt-in for post-Genesis BSV consensus; latent
891
- `MAXIMUM_ELEMENT_SIZE` bug fixed.
892
- - **[4.0.1](./CHANGELOG.md#401---2026-05-31)** — soft-deprecated
893
- `bsv.SmartUTXO` (dev-only simulator on production surface);
894
- `createMockUTXOs` bug fixes.
895
- - **[4.0.0](./CHANGELOG.md#400---2026-05-31)** — **security release.** Fixes
896
- three exploitable credential-verification flaws in GDAF/VC-JWT and
897
- removes a live mainnet WIF that shipped inside prior versions. All
898
- ≤ 3.4.5 should be considered untrustworthy.
899
-
900
- Earlier 3.x changelog entries are preserved in `CHANGELOG.md`.
1022
+ Highlights of the current line:
1023
+
1024
+ - **[8.3.0](./CHANGELOG.md#830---2026-08-16)** — BRC-220 **NotaryHash**:
1025
+ signed-hash notarization, SPV-verifiable certificates, a pluggable signature
1026
+ suite registry, and RFC 6962 Merkle trees for batch mode.
1027
+ - **[8.2.0](./CHANGELOG.md#820---2026-08-15)** — RFC 8785 (JCS) canonical JSON
1028
+ extracted to `lib/util/jcs.js`, so GDAF signatures verify under other
1029
+ implementations.
1030
+ - **[8.1.0](./CHANGELOG.md#810---2026-08-13)** — `useGenesisLimits()` edge-case
1031
+ fix.
1032
+ - **[8.0.0](./CHANGELOG.md#800---2026-08-13)** — **breaking.** Measured against
1033
+ the reference node's own consensus vectors (1483/1483, from an initial
1034
+ 1426/1483 with 21 false accepts). `verify()` with no flags now means BSV
1035
+ mainnet; `SCRIPT_ENABLE_MONOLITH_OPCODES` and `SCRIPT_ENABLE_MAGNETIC_OPCODES`
1036
+ changed numeric value. See [Upgrading](#upgrading-to-v800-breaking-changes).
1037
+ - **[4.0.0](./CHANGELOG.md#400---2026-05-31)** — **security release.** Fixed
1038
+ three exploitable credential-verification flaws in GDAF/VC-JWT and removed a
1039
+ live mainnet WIF that shipped inside prior versions. All ≤ 3.4.5 should be
1040
+ considered untrustworthy.
1041
+
1042
+ Earlier entries are preserved in `CHANGELOG.md`.
901
1043
 
902
1044
  ---
903
1045
 
@@ -975,6 +1117,6 @@ For security vulnerabilities, follow the disclosure process in
975
1117
 
976
1118
  ---
977
1119
 
978
- **SmartLedger-BSV v4.2.1** — *Complete Bitcoin SV Development Framework*
1120
+ **SmartLedger-BSV v8.3.1** — *Complete Bitcoin SV Development Framework*
979
1121
 
980
1122
  Built with ❤️ for the Bitcoin SV ecosystem • 16 Loading Options • Interpreter-Verified Covenants