@smartledger/bsv 4.0.1 → 4.2.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 (23) hide show
  1. package/CHANGELOG.md +137 -0
  2. package/README.md +248 -205
  3. package/bsv-covenant.min.js +8 -8
  4. package/bsv-gdaf.min.js +9 -9
  5. package/bsv-ltp.min.js +9 -9
  6. package/bsv-smartcontract.min.js +9 -9
  7. package/bsv.bundle.js +9 -9
  8. package/bsv.d.ts +15 -0
  9. package/bsv.min.js +8 -8
  10. package/docs/COVENANT_DEVELOPMENT_RESOLVED.md +2 -2
  11. package/docs/MODULE_REFERENCE_COMPLETE.md +27 -27
  12. package/docs/advanced/UTXO_MANAGER_GUIDE.md +1 -1
  13. package/docs/getting-started/INSTALLATION.md +25 -25
  14. package/docs/getting-started/QUICK_START.md +7 -7
  15. package/docs/migration/FROM_BSV_1_5_6.md +5 -5
  16. package/lib/script/interpreter.js +41 -7
  17. package/lib/smart_contract/covenant_helpers.js +118 -0
  18. package/lib/smart_contract/index.js +30 -1
  19. package/lib/smart_contract/locks.js +101 -0
  20. package/lib/smart_contract/pels.js +62 -0
  21. package/lib/smart_contract/pushtx.js +138 -0
  22. package/lib/smart_contract/token.js +95 -0
  23. package/package.json +1 -1
package/README.md CHANGED
@@ -2,17 +2,63 @@
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-4.0.1-blue.svg)](https://www.npmjs.com/package/@smartledger/bsv)
5
+ [![Version](https://img.shields.io/badge/version-4.2.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)](#loading-options)
9
9
  [![W3C](https://img.shields.io/badge/W3C-Compliant-blueviolet.svg)](#verifiable-credentials)
10
10
 
11
- The most comprehensive and flexible Bitcoin SV library available. **In v3.4.x**: Legally-recognizable DID:web + VC-JWT toolkit with ES256/ES256K support, StatusList2021 revocation, and BSV anchoring. Choose from 16 different distribution methods: standalone modules, complete bundle, or mix-and-match approach.
11
+ The most comprehensive and flexible Bitcoin SV library available. **In v4.x**:
12
+ first-class interpreter-verified covenants (OP_PUSH_TX, PELS, ownership tokens),
13
+ post-Genesis script limits via a one-call opt-in, fixed credential-verification
14
+ flaws in GDAF/VC-JWT, legally-recognizable DID:web + VC-JWT toolkit, and 16
15
+ distribution methods. **v4.x is the only supported line — upgrade from 3.4.x.**
12
16
 
13
- > **v3.4.1 (bugfix)**: credential bundles now actually ship to npm consumers, `prepublishOnly` builds the full set, and `Transaction.shuffleOutputs()` uses a CSPRNG. See [CHANGELOG](./CHANGELOG.md#341---2026-05-18).
17
+ > **v4.2.0 (latest)**: first-class interpreter-verified covenants — `SmartContract.PushTx`,
18
+ > `PELS`, `Token`, `Locks`, all evaluated end-to-end through `Script.Interpreter`
19
+ > with positive **and** negative test coverage. See [CHANGELOG](./CHANGELOG.md#420---2026-06-07).
14
20
 
15
- ## 🆕 **v3.4.x - Legally-Recognizable Credentials**
21
+ ## 🆕 **v4.2.0 — Interpreter-Verified Covenants**
22
+
23
+ The full covenant stack now lives at `bsv.SmartContract`, builds on the
24
+ post-Genesis script limits added in 4.1.0, and verifies end-to-end through
25
+ `Script.Interpreter`. Every locking script has both a positive (must-accept)
26
+ and negative (must-reject) test.
27
+
28
+ ```javascript
29
+ const bsv = require('@smartledger/bsv')
30
+ const SC = bsv.SmartContract
31
+ SC.enableGenesis() // post-Genesis limits (OP_PUSH_TX needs them)
32
+
33
+ // Self-replicating covenant — every spend recreates the same script (value − fee).
34
+ const lock = SC.perpetualCovenant(500)
35
+
36
+ // Stateful ownership token (NFT) — transfer requires the owner's secret,
37
+ // rewrites state, perpetuates the token code.
38
+ const token = SC.ownershipToken(500, ownerHash)
39
+
40
+ // Value covenant — forces spend outputs to match a specific hashOutputs.
41
+ const vlock = SC.valueCovenant(SC.PushTx.hashOutputs(requiredOutputs))
42
+
43
+ // Verify any locking script end-to-end through Script.Interpreter
44
+ const ok = SC.verifyScript(unlockScript, lockingScript, tx, inputIndex, satoshis)
45
+ ```
46
+
47
+ **Available primitives under `bsv.SmartContract`:**
48
+
49
+ | Namespace | Purpose |
50
+ |---|---|
51
+ | `PushTx` | nChain WP1605 OP_PUSH_TX — `authenticator()`, `valueCovenant()`, `hashOutputs()`, `extractHashOutputs()`, `grind()` |
52
+ | `PELS` | Perpetually Enforcing Locking Scripts — `perpetualCovenant(fee)` |
53
+ | `Token` | Stateful ownership token (NFT) — `ownershipToken(fee, ownerHash)` |
54
+ | `Locks` | Hash-lock, P2PKH, CLTV time-lock, m-of-n multisig, HTLC |
55
+ | `CovenantHelpers` | Consensus-flag `verify()` harness, raw BIP-143 preimage, signing, fund/spend scaffolding |
56
+
57
+ > ⚠️ Research-grade. Review carefully before mainnet value: the OP_PUSH_TX key
58
+ > is the intentionally public `a=k=1` construction, and low-S malleability is
59
+ > left unenforced for the in-script signature.
60
+
61
+ ## 🆕 **Legally-Recognizable Credentials (v3.4.x+)**
16
62
 
17
63
  ### **Why This Matters**
18
64
  - ✅ **W3C Standards**: Full VC-JWT and DID:web compliance for legal recognition
@@ -25,8 +71,8 @@ The most comprehensive and flexible Bitcoin SV library available. **In v3.4.x**:
25
71
  ### **Quick Start - Issue Your First Verifiable Credential**
26
72
 
27
73
  ```bash
28
- # Install SmartLedger BSV v4.0.1
29
- npm install @smartledger/bsv@4.0.1
74
+ # Install SmartLedger BSV v4.2.1
75
+ npm install @smartledger/bsv@4.2.1
30
76
 
31
77
  # Initialize DID:web issuer (generates ES256 keys)
32
78
  npx smartledger-bsv didweb init --domain example.com --alg ES256
@@ -135,42 +181,42 @@ console.log('Status:', status) // 'revoked'
135
181
  ### **Core Modules**
136
182
  | Module | Size | Use Case | CDN |
137
183
  |--------|------|----------|-----|
138
- | **bsv.min.js** | 937KB | Core BSV + SmartContract | `unpkg.com/@smartledger/bsv@4.0.1/bsv.min.js` |
139
- | **bsv.bundle.js** | 937KB | Everything in one file | `unpkg.com/@smartledger/bsv@4.0.1/bsv.bundle.js` |
184
+ | **bsv.min.js** | 937KB | Core BSV + SmartContract | `unpkg.com/@smartledger/bsv@4.2.1/bsv.min.js` |
185
+ | **bsv.bundle.js** | 937KB | Everything in one file | `unpkg.com/@smartledger/bsv@4.2.1/bsv.bundle.js` |
140
186
 
141
- ### **🆕 W3C Verifiable Credentials (v3.4.x)**
187
+ ### **W3C Verifiable Credentials**
142
188
  | Module | Size | Use Case | CDN |
143
189
  |--------|------|----------|-----|
144
- | **🟢 bsv-didweb.min.js** | 419KB | **DID:web generation** | `unpkg.com/@smartledger/bsv@4.0.1/bsv-didweb.min.js` |
145
- | **🟢 bsv-vcjwt.min.js** | 419KB | **VC-JWT issue/verify** | `unpkg.com/@smartledger/bsv@4.0.1/bsv-vcjwt.min.js` |
146
- | **🟢 bsv-statuslist.min.js** | 487KB | **StatusList2021 revocation** | `unpkg.com/@smartledger/bsv@4.0.1/bsv-statuslist.min.js` |
147
- | **🟢 bsv-anchor.min.js** | 418KB | **BSV anchoring (hash-only)** | `unpkg.com/@smartledger/bsv@4.0.1/bsv-anchor.min.js` |
190
+ | **🟢 bsv-didweb.min.js** | 419KB | **DID:web generation** | `unpkg.com/@smartledger/bsv@4.2.1/bsv-didweb.min.js` |
191
+ | **🟢 bsv-vcjwt.min.js** | 419KB | **VC-JWT issue/verify** | `unpkg.com/@smartledger/bsv@4.2.1/bsv-vcjwt.min.js` |
192
+ | **🟢 bsv-statuslist.min.js** | 487KB | **StatusList2021 revocation** | `unpkg.com/@smartledger/bsv@4.2.1/bsv-statuslist.min.js` |
193
+ | **🟢 bsv-anchor.min.js** | 418KB | **BSV anchoring (hash-only)** | `unpkg.com/@smartledger/bsv@4.2.1/bsv-anchor.min.js` |
148
194
 
149
195
  ### **Smart Contract & Development**
150
196
  | Module | Size | Use Case | CDN |
151
197
  |--------|------|----------|-----|
152
- | **bsv-smartcontract.min.js** | 937KB | Complete covenant framework | `unpkg.com/@smartledger/bsv@4.0.1/bsv-smartcontract.min.js` |
153
- | **bsv-covenant.min.js** | 913KB | Covenant operations | `unpkg.com/@smartledger/bsv@4.0.1/bsv-covenant.min.js` |
154
- | **bsv-script-helper.min.js** | 26KB | Custom script tools | `unpkg.com/@smartledger/bsv@4.0.1/bsv-script-helper.min.js` |
155
- | **bsv-security.min.js** | 26KB | Security enhancements | `unpkg.com/@smartledger/bsv@4.0.1/bsv-security.min.js` |
198
+ | **bsv-smartcontract.min.js** | 937KB | Complete covenant framework | `unpkg.com/@smartledger/bsv@4.2.1/bsv-smartcontract.min.js` |
199
+ | **bsv-covenant.min.js** | 913KB | Covenant operations | `unpkg.com/@smartledger/bsv@4.2.1/bsv-covenant.min.js` |
200
+ | **bsv-script-helper.min.js** | 26KB | Custom script tools | `unpkg.com/@smartledger/bsv@4.2.1/bsv-script-helper.min.js` |
201
+ | **bsv-security.min.js** | 26KB | Security enhancements | `unpkg.com/@smartledger/bsv@4.2.1/bsv-security.min.js` |
156
202
 
157
203
  ### **Legal & Compliance**
158
204
  | Module | Size | Use Case | CDN |
159
205
  |--------|------|----------|-----|
160
- | **bsv-ltp.min.js** | 1184KB | Legal Token Protocol | `unpkg.com/@smartledger/bsv@4.0.1/bsv-ltp.min.js` |
161
- | **bsv-gdaf.min.js** | 1184KB | Digital Identity & Attestation | `unpkg.com/@smartledger/bsv@4.0.1/bsv-gdaf.min.js` |
206
+ | **bsv-ltp.min.js** | 1184KB | Legal Token Protocol | `unpkg.com/@smartledger/bsv@4.2.1/bsv-ltp.min.js` |
207
+ | **bsv-gdaf.min.js** | 1184KB | Digital Identity & Attestation | `unpkg.com/@smartledger/bsv@4.2.1/bsv-gdaf.min.js` |
162
208
 
163
209
  ### **Advanced Cryptography**
164
210
  | Module | Size | Use Case | CDN |
165
211
  |--------|------|----------|-----|
166
- | **bsv-shamir.min.js** | 432KB | Threshold Cryptography | `unpkg.com/@smartledger/bsv@4.0.1/bsv-shamir.min.js` |
212
+ | **bsv-shamir.min.js** | 432KB | Threshold Cryptography | `unpkg.com/@smartledger/bsv@4.2.1/bsv-shamir.min.js` |
167
213
 
168
214
  ### **Utilities**
169
215
  | Module | Size | Use Case | CDN |
170
216
  |--------|------|----------|-----|
171
- | **bsv-ecies.min.js** | 71KB | Encryption | `unpkg.com/@smartledger/bsv@4.0.1/bsv-ecies.min.js` |
172
- | **bsv-message.min.js** | 26KB | Message signing | `unpkg.com/@smartledger/bsv@4.0.1/bsv-message.min.js` |
173
- | **bsv-mnemonic.min.js** | 681KB | HD wallets | `unpkg.com/@smartledger/bsv@4.0.1/bsv-mnemonic.min.js` |
217
+ | **bsv-ecies.min.js** | 71KB | Encryption | `unpkg.com/@smartledger/bsv@4.2.1/bsv-ecies.min.js` |
218
+ | **bsv-message.min.js** | 26KB | Message signing | `unpkg.com/@smartledger/bsv@4.2.1/bsv-message.min.js` |
219
+ | **bsv-mnemonic.min.js** | 681KB | HD wallets | `unpkg.com/@smartledger/bsv@4.2.1/bsv-mnemonic.min.js` |
174
220
 
175
221
  ## ⚡ **2-Minute Quick Start**
176
222
 
@@ -181,10 +227,13 @@ Get started with Bitcoin SV development in under 2 minutes:
181
227
  npm install @smartledger/bsv
182
228
 
183
229
  # Or include in HTML
184
- <script src="https://unpkg.com/@smartledger/bsv@4.0.1/bsv.min.js"></script>
230
+ <script src="https://unpkg.com/@smartledger/bsv@4.2.1/bsv.min.js"></script>
185
231
  ```
186
232
 
187
- > **🔧 v3.4.x:** Legally-recognizable W3C Verifiable Credentials with DID:web + VC-JWT toolkit. ES256/ES256K support, StatusList2021 revocation, and privacy-preserving BSV anchoring. Complete CLI tooling included! v3.4.1 ensures these bundles ship to npm consumers; see CHANGELOG.
233
+ > **🔧 v4.x:** First-class interpreter-verified covenants (4.2.0), post-Genesis
234
+ > script limits opt-in (4.1.0), fixed GDAF credential-verification flaws (4.0.0),
235
+ > legally-recognizable DID:web + VC-JWT toolkit, StatusList2021 revocation, and
236
+ > privacy-preserving BSV anchoring. Complete CLI tooling included. See CHANGELOG.
188
237
 
189
238
  **Basic Transaction (30 seconds):**
190
239
  ```javascript
@@ -276,8 +325,8 @@ const covenant = bsv.SmartContract.createCovenantBuilder()
276
325
 
277
326
  ### 🔧 **Basic Development** (~963KB total)
278
327
  ```html
279
- <script src="https://unpkg.com/@smartledger/bsv@4.0.1/bsv.min.js"></script>
280
- <script src="https://unpkg.com/@smartledger/bsv@4.0.1/bsv-script-helper.min.js"></script>
328
+ <script src="https://unpkg.com/@smartledger/bsv@4.2.1/bsv.min.js"></script>
329
+ <script src="https://unpkg.com/@smartledger/bsv@4.2.1/bsv-script-helper.min.js"></script>
281
330
  <script>
282
331
  const privateKey = new bsv.PrivateKey();
283
332
  const utxos = new bsv.SmartContract.UTXOGenerator().createRealUTXOs(2, 100000);
@@ -286,9 +335,9 @@ const covenant = bsv.SmartContract.createCovenantBuilder()
286
335
 
287
336
  ### 🔒 **Smart Contract Development** (~2.7MB total — each bundle re-embeds core BSV)
288
337
  ```html
289
- <script src="https://unpkg.com/@smartledger/bsv@4.0.1/bsv.min.js"></script>
290
- <script src="https://unpkg.com/@smartledger/bsv@4.0.1/bsv-covenant.min.js"></script>
291
- <script src="https://unpkg.com/@smartledger/bsv@4.0.1/bsv-smartcontract.min.js"></script>
338
+ <script src="https://unpkg.com/@smartledger/bsv@4.2.1/bsv.min.js"></script>
339
+ <script src="https://unpkg.com/@smartledger/bsv@4.2.1/bsv-covenant.min.js"></script>
340
+ <script src="https://unpkg.com/@smartledger/bsv@4.2.1/bsv-smartcontract.min.js"></script>
292
341
  <script>
293
342
  const covenant = bsv.SmartContract.createCovenantBuilder()
294
343
  .extractField('amount').push(50000).greaterThanOrEqual().verify().build();
@@ -298,9 +347,9 @@ const covenant = bsv.SmartContract.createCovenantBuilder()
298
347
 
299
348
  ### 🆕 **Legal & Identity Development** (~3.2MB total — each bundle re-embeds core BSV)
300
349
  ```html
301
- <script src="https://unpkg.com/@smartledger/bsv@4.0.1/bsv.min.js"></script>
302
- <script src="https://unpkg.com/@smartledger/bsv@4.0.1/bsv-ltp.min.js"></script>
303
- <script src="https://unpkg.com/@smartledger/bsv@4.0.1/bsv-gdaf.min.js"></script>
350
+ <script src="https://unpkg.com/@smartledger/bsv@4.2.1/bsv.min.js"></script>
351
+ <script src="https://unpkg.com/@smartledger/bsv@4.2.1/bsv-ltp.min.js"></script>
352
+ <script src="https://unpkg.com/@smartledger/bsv@4.2.1/bsv-gdaf.min.js"></script>
304
353
  <script>
305
354
  // Legal Token Protocol
306
355
  const propertyToken = bsv.createPropertyToken({
@@ -314,9 +363,9 @@ const covenant = bsv.SmartContract.createCovenantBuilder()
314
363
 
315
364
  ### 🆕 **Security & Cryptography** (~1.4MB total)
316
365
  ```html
317
- <script src="https://unpkg.com/@smartledger/bsv@4.0.1/bsv.min.js"></script>
318
- <script src="https://unpkg.com/@smartledger/bsv@4.0.1/bsv-security.min.js"></script>
319
- <script src="https://unpkg.com/@smartledger/bsv@4.0.1/bsv-shamir.min.js"></script>
366
+ <script src="https://unpkg.com/@smartledger/bsv@4.2.1/bsv.min.js"></script>
367
+ <script src="https://unpkg.com/@smartledger/bsv@4.2.1/bsv-security.min.js"></script>
368
+ <script src="https://unpkg.com/@smartledger/bsv@4.2.1/bsv-shamir.min.js"></script>
320
369
  <script>
321
370
  // Threshold Cryptography
322
371
  const shares = bsv.splitSecret('my_secret_key', 5, 3); // 5 shares, 3 needed
@@ -328,7 +377,7 @@ const covenant = bsv.SmartContract.createCovenantBuilder()
328
377
 
329
378
  ### 🎯 **Everything Bundle** (937KB)
330
379
  ```html
331
- <script src="https://unpkg.com/@smartledger/bsv@4.0.1/bsv.bundle.js"></script>
380
+ <script src="https://unpkg.com/@smartledger/bsv@4.2.1/bsv.bundle.js"></script>
332
381
  <script>
333
382
  // Everything available immediately
334
383
  const shares = bsv.splitSecret('secret', 5, 3); // Shamir Secret Sharing
@@ -408,8 +457,8 @@ const contractTx = covenant.createCovenantTransaction({
408
457
 
409
458
  #### 1. **Minimal Setup** - Core + Script Helper (~963KB)
410
459
  ```html
411
- <script src="https://unpkg.com/@smartledger/bsv@4.0.1/bsv.min.js"></script>
412
- <script src="https://unpkg.com/@smartledger/bsv@4.0.1/bsv-script-helper.min.js"></script>
460
+ <script src="https://unpkg.com/@smartledger/bsv@4.2.1/bsv.min.js"></script>
461
+ <script src="https://unpkg.com/@smartledger/bsv@4.2.1/bsv-script-helper.min.js"></script>
413
462
  <script>
414
463
  const tx = new bsv.Transaction();
415
464
  const sig = bsvScriptHelper.createSignature(tx, privateKey, 0, script, satoshis);
@@ -418,9 +467,9 @@ const contractTx = covenant.createCovenantTransaction({
418
467
 
419
468
  #### 2. **DeFi Development** - Core + Covenants + Debug (~2.7MB — each bundle re-embeds core BSV)
420
469
  ```html
421
- <script src="https://unpkg.com/@smartledger/bsv@4.0.1/bsv.min.js"></script>
422
- <script src="https://unpkg.com/@smartledger/bsv@4.0.1/bsv-covenant.min.js"></script>
423
- <script src="https://unpkg.com/@smartledger/bsv@4.0.1/bsv-smartcontract.min.js"></script>
470
+ <script src="https://unpkg.com/@smartledger/bsv@4.2.1/bsv.min.js"></script>
471
+ <script src="https://unpkg.com/@smartledger/bsv@4.2.1/bsv-covenant.min.js"></script>
472
+ <script src="https://unpkg.com/@smartledger/bsv@4.2.1/bsv-smartcontract.min.js"></script>
424
473
  <script>
425
474
  const covenant = new bsvCovenant.CovenantInterface();
426
475
  const debugInfo = SmartContract.interpretScript(script);
@@ -430,8 +479,8 @@ const contractTx = covenant.createCovenantTransaction({
430
479
 
431
480
  #### 3. **Security First** - Core + Enhanced Security (~963KB)
432
481
  ```html
433
- <script src="https://unpkg.com/@smartledger/bsv@4.0.1/bsv.min.js"></script>
434
- <script src="https://unpkg.com/@smartledger/bsv@4.0.1/bsv-security.min.js"></script>
482
+ <script src="https://unpkg.com/@smartledger/bsv@4.2.1/bsv.min.js"></script>
483
+ <script src="https://unpkg.com/@smartledger/bsv@4.2.1/bsv-security.min.js"></script>
435
484
  <script>
436
485
  const verified = bsvSecurity.SmartVerify.verify(signature, hash, publicKey);
437
486
  const enhanced = bsvSecurity.EllipticFixed.createSignature(privateKey, hash);
@@ -440,7 +489,7 @@ const contractTx = covenant.createCovenantTransaction({
440
489
 
441
490
  #### 4. **Everything Bundle** - One File Solution (937KB)
442
491
  ```html
443
- <script src="https://unpkg.com/@smartledger/bsv@4.0.1/bsv.bundle.js"></script>
492
+ <script src="https://unpkg.com/@smartledger/bsv@4.2.1/bsv.bundle.js"></script>
444
493
  <script>
445
494
  // Everything available under bsv namespace
446
495
  const keys = bsv.SmartLedgerBundle.generateKeys();
@@ -627,30 +676,80 @@ console.log('Amount:', preimage.amountValue); // BigInt accessor
627
676
  console.log('Valid structure:', preimage.isValid); // Boolean validation
628
677
  ```
629
678
 
630
- ### PUSHTX Covenants (nChain WP1605)
679
+ ### PUSHTX Covenants (nChain WP1605) — v4.2.0 API
631
680
  ```javascript
632
- const { CovenantInterface } = require('@smartledger/bsv/lib/covenant-interface');
633
- const covenant = new CovenantInterface();
634
-
635
- // Create PUSHTX covenant with in-script signature generation
636
- const pushtxCovenant = covenant.createAdvancedCovenant('pushtx', {
637
- publicKey: '0279be667ef9dcbbac55a06295ce870b07029bfcdb2dce28d959f2815b16f81798',
638
- enforceOutputs: true,
639
- sighashType: 0x41
640
- });
681
+ const bsv = require('@smartledger/bsv')
682
+ const SC = bsv.SmartContract
683
+ SC.enableGenesis() // OP_PUSH_TX needs post-Genesis limits
684
+
685
+ // Bare OP_PUSH_TX authenticator: unlocks only with the (grindable) preimage of
686
+ // THIS transaction. Built from the nChain `a=k=1` public-key construction —
687
+ // the script generates an ECDSA signature in-script from the pushed preimage
688
+ // (r=Gx, s=(e+Gx) mod n) and verifies it with OP_CHECKSIG, which only passes
689
+ // if the preimage matches this very spend.
690
+ const authLock = SC.PushTx.authenticator()
691
+
692
+ // Value covenant — force spend outputs to match a specific hashOutputs.
693
+ const requiredOutputs = [/* bsv.Transaction.Output objects */]
694
+ const valueLock = SC.PushTx.valueCovenant(SC.PushTx.hashOutputs(requiredOutputs))
641
695
  ```
642
696
 
643
- ### Perpetually Enforcing Locking Scripts (PELS)
697
+ ### Perpetually Enforcing Locking Scripts (PELS) — v4.2.0 API
644
698
  ```javascript
645
- // Create perpetual covenant that enforces rules across all future transactions
646
- const pels = covenant.createAdvancedCovenant('perpetual', {
647
- publicKeyHash: '751e76e8199196d454941c45d1b3a323f1433bd6',
648
- feeDeduction: 512,
649
- enforceScript: true,
650
- enforceValue: true
651
- });
699
+ // Self-replicating covenant: every spend must recreate the same script
700
+ // (value − fee), reading its own code out of the authenticated preimage's
701
+ // scriptCode field. No self-hash circularity.
702
+ const pels = SC.perpetualCovenant(500) // fee in satoshis deducted each hop
703
+ ```
704
+
705
+ ### Ownership Tokens (NFT) — v4.2.0 API
706
+ ```javascript
707
+ // Stateful ownership token. Owner is carried as on-chain state; transfer
708
+ // requires the current owner's secret and rewrites state, perpetuating
709
+ // the token code across the chain of spends.
710
+ const ownerHash = bsv.crypto.Hash.sha256ripemd160(currentOwnerPubKey.toBuffer())
711
+ const token = SC.ownershipToken(500, ownerHash)
652
712
  ```
653
713
 
714
+ ### End-to-end verification
715
+
716
+ ```javascript
717
+ // Any locking script can be verified end-to-end through Script.Interpreter,
718
+ // with the consensus flags this library was tested against.
719
+ const ok = SC.verifyScript(unlockScript, lockingScript, tx, inputIndex, satoshis)
720
+ ```
721
+
722
+ ### Evaluating covenants locally — `Interpreter.useGenesisLimits()` (v4.1.0+)
723
+
724
+ The bundled `Script.Interpreter` defaults to **pre-Genesis** BSV consensus
725
+ caps — 520-byte stack elements, 4-byte script numbers, 201 opcodes per
726
+ script — which BSV removed at the Genesis upgrade (Feb 2020). Those caps
727
+ make it impossible to evaluate this library's own flagship features:
728
+ OP_PUSH_TX covenants push a ~585-byte preimage, do 32-byte modular
729
+ arithmetic, and run a few hundred opcodes.
730
+
731
+ Opt into post-Genesis rules with a single call at app startup:
732
+
733
+ ```javascript
734
+ const bsv = require('@smartledger/bsv');
735
+
736
+ // Default: bound the limits to a safe ceiling (covers every covenant
737
+ // pattern seen in production, blocks oversized-push memory DoS).
738
+ bsv.Script.Interpreter.useGenesisLimits(64 * 1024);
739
+
740
+ // Or, for fully unbounded (~2 GB) — only safe for trusted scripts:
741
+ // bsv.Script.Interpreter.useGenesisLimits();
742
+
743
+ // Now OP_PUSH_TX covenants verify locally:
744
+ const interp = new bsv.Script.Interpreter();
745
+ const ok = interp.verify(unlockScript, lockScript, tx, 0, flags, satoshisBN);
746
+ ```
747
+
748
+ This is a **process-wide** setting — once called, every subsequent
749
+ `new Interpreter()` runs with lifted caps. Defaults are unchanged out of
750
+ the box; if you don't call `useGenesisLimits()`, behavior is identical
751
+ to pre-v4.1.0.
752
+
654
753
  ## 🛠️ Custom Scripts
655
754
 
656
755
  ### Multi-signature Scripts
@@ -674,7 +773,7 @@ const timelockScript = helper.createTimelockScript(
674
773
  );
675
774
  ```
676
775
 
677
- ## � Examples
776
+ ## 📁 Examples
678
777
 
679
778
  ### Basic Examples
680
779
  - **[Advanced Covenant Demo](advanced_covenant_demo.js)**: Complete covenant showcase
@@ -688,13 +787,9 @@ const timelockScript = helper.createTimelockScript(
688
787
 
689
788
  ## 🔧 CDN Bundles
690
789
 
691
- | Bundle | Size | Description |
692
- |--------|------|-------------|
693
- | `bsv.bundle.js` | 684KB | Complete library with all features |
694
- | `bsv.min.js` | 364KB | Minified production version |
695
- | `bsv-ecies.min.js` | 145KB | ECIES encryption only |
696
- | `bsv-message.min.js` | 120KB | Message signing only |
697
- | `bsv-mnemonic.min.js` | 98KB | Mnemonic handling only |
790
+ See the **[16 Loading Options](#-16-loading-options---choose-your-approach)**
791
+ table near the top for the full list of bundles with current sizes and
792
+ canonical `unpkg.com/@smartledger/bsv@4.2.1/...` URLs.
698
793
 
699
794
  ## 🔐 Security
700
795
 
@@ -728,165 +823,113 @@ const okDefault = bsv.crypto.ECDSA.verify(msgHashBuffer, signature, publicKey)
728
823
  - 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`.
729
824
  - 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.
730
825
 
731
- A planned 3.5.0 will offer an opt-in flag to route the default verify path through `SmartVerify` so the protection is on by default for new users.
826
+ v4.0.0 fixed three critical, exploitable vulnerabilities in the GDAF
827
+ credential-verification path (`_canonicalizeJSON` excluded nested claims
828
+ from the signed hash; `_verifySignature` always returned truthy regardless
829
+ of validity; `verificationMethod` was not bound to the credential issuer)
830
+ and removed a live mainnet WIF that had been shipping inside the
831
+ package. **All ≤ 3.4.5 releases should be considered untrustworthy for
832
+ credential verification and must be upgraded to 4.x.** See
833
+ [CHANGELOG `## [4.0.0]`](./CHANGELOG.md#400---2026-05-31) for details
834
+ and [SECURITY.md](./SECURITY.md) for the supported-versions policy.
732
835
 
733
836
  ## 📝 Changelog
734
837
 
735
- ### v3.2.0 - JavaScript-to-Bitcoin Script Framework
736
- - ✅ Complete JavaScript-to-Bitcoin Script translation system
737
- - ✅ 121 Bitcoin Script opcodes mapped to JavaScript functions
738
- - ✅ High-level CovenantBuilder API for rapid development
739
- - ✅ Real-time script simulation and debugging capabilities
740
- - ✅ Template-based covenant patterns library
741
- - ✅ Automatic ASM generation from JavaScript operations
742
- - ✅ Enhanced documentation and comprehensive examples
743
-
744
- ### v3.1.1 - Advanced Covenant Framework
745
- - ✅ Enhanced covenant interface with BIP143 + PUSHTX support
746
- - ✅ Perpetually Enforcing Locking Scripts (PELS) implementation
747
- - ✅ Transaction introspection with preimage analysis
748
- - ✅ Comprehensive documentation and examples
749
-
750
- ### v3.0.2 - Custom Script Framework
751
- - ✅ Complete custom script development API
752
- - ✅ Multi-signature, timelock, and conditional script support
753
- - ✅ Transaction signature API gap resolution
754
-
755
- ### v3.0.1 - Ultra-Low Fee System
756
- - ✅ 0.01 sats/byte fee configuration (91% reduction)
757
- - ✅ Advanced UTXO state management
758
- - ✅ Change output optimization
759
-
760
- ## 📄 License
838
+ The authoritative version history lives in [CHANGELOG.md](./CHANGELOG.md).
839
+ Highlights of the v4.x line:
840
+
841
+ - **[4.2.0](./CHANGELOG.md#420---2026-06-07)** — first-class
842
+ interpreter-verified covenants (`SmartContract.PushTx`, `PELS`,
843
+ `Token`, `Locks`, `verifyScript`) with positive + negative test coverage.
844
+ - **[4.1.0](./CHANGELOG.md#410---2026-06-07)** — `Interpreter.useGenesisLimits()`
845
+ one-call opt-in for post-Genesis BSV consensus; latent
846
+ `MAXIMUM_ELEMENT_SIZE` bug fixed.
847
+ - **[4.0.1](./CHANGELOG.md#401---2026-05-31)** — soft-deprecated
848
+ `bsv.SmartUTXO` (dev-only simulator on production surface);
849
+ `createMockUTXOs` bug fixes.
850
+ - **[4.0.0](./CHANGELOG.md#400---2026-05-31)** — **security release.** Fixes
851
+ three exploitable credential-verification flaws in GDAF/VC-JWT and
852
+ removes a live mainnet WIF that shipped inside prior versions. All
853
+ ≤ 3.4.5 should be considered untrustworthy.
854
+
855
+ Earlier 3.x changelog entries are preserved in `CHANGELOG.md`.
761
856
 
762
857
  ---
763
858
 
764
859
  ## 📚 **Complete Documentation**
765
860
 
766
- ### 🚀 **Getting Started**
767
- - **[2-Minute Quick Start](#2-minute-quick-start)** - Get up and running fast
768
- - **[Loading Options](#9-loading-options--choose-your-approach)** - Choose your distribution method
769
- - **[API Reference](#api-reference)** - Quick method lookup
770
- - **[Installation Guide](#installation)** - npm, CDN, and browser setup
771
-
772
- ### 🎯 **Development Guides**
773
- - **[Advanced Covenant Development](docs/ADVANCED_COVENANT_DEVELOPMENT.md)** - Complete BIP143 + PUSHTX guide
774
- - **[Custom Script Development](docs/CUSTOM_SCRIPT_DEVELOPMENT.md)** - Multi-sig, timelock, and custom patterns
775
- - **[Covenant Development Resolved](docs/COVENANT_DEVELOPMENT_RESOLVED.md)** - Solutions to common issues
776
- - **[PUSHTX Key Insights](docs/pushtx-key-insights.md)** - nChain research implementation
777
-
778
- ### 🔧 **Technical Resources**
779
- - **[SmartContract Integration](SMARTCONTRACT_INTEGRATION.md)** - Debug tools and analysis
780
- - **[Examples Directory](https://github.com/codenlighten/smartledger-bsv/tree/main/examples)** - Working code samples
781
- - **[Test Suite](https://github.com/codenlighten/smartledger-bsv/tree/main/tests)** - Comprehensive testing examples
782
- - **[Build System](build/)** - Webpack configurations
783
-
784
- ### 🌐 **Loading Strategy Examples**
785
-
786
- | **Use Case** | **Recommended Load** | **Size** | **Features** |
787
- |--------------|---------------------|----------|--------------|
788
- | **Simple Transactions** | `bsv.min.js` | 937KB | Core BSV + SmartContract |
789
- | **DeFi Development** | Core + Covenant + Debug | ~2.7MB | Advanced contracts + tools (bundles re-embed core BSV) |
790
- | **Enterprise Apps** | `bsv.bundle.js` | 937KB | Everything included |
791
- | **Mobile/Lightweight** | Core + Script Helper | ~963KB | Essential tools only |
792
- | **Research/Analysis** | Core + SmartContract | 900KB | Full debug capabilities |
793
-
794
- ### 🔗 **Cross-References**
795
-
796
- **From Quick Start → Deep Dive:**
797
- - [Basic Transaction](#2-minute-quick-start) → [Transaction API](docs/transaction.md)
798
- - [Covenant Example](#2-minute-quick-start) → [Advanced Covenant Guide](docs/ADVANCED_COVENANT_DEVELOPMENT.md)
799
- - [API Reference](#api-reference) → [Method Documentation](docs/)
800
-
801
- **From Examples → Implementation:**
802
- - [Covenant Examples](https://github.com/codenlighten/smartledger-bsv/tree/main/examples/covenants) → [Production Guide](docs/ADVANCED_COVENANT_DEVELOPMENT.md#production-guidelines)
803
- - [Script Examples](https://github.com/codenlighten/smartledger-bsv/tree/main/examples/scripts) → [Custom Script Guide](docs/CUSTOM_SCRIPT_DEVELOPMENT.md)
804
- - [Test Files](https://github.com/codenlighten/smartledger-bsv/tree/main/tests) → [Integration Examples](https://github.com/codenlighten/smartledger-bsv/tree/main/examples)
805
-
806
- **From Concepts → Code:**
807
- - [PUSHTX Theory](docs/pushtx-key-insights.md) → [Covenant Implementation](https://github.com/codenlighten/smartledger-bsv/blob/main/examples/covenants/advanced_covenant_demo.js)
808
- - [Security Features](#smart-security) → [Implementation](lib/crypto/smartledger_verify.js)
809
- - [Debug Tools](#debug-tools) → [Usage Examples](https://github.com/codenlighten/smartledger-bsv/blob/main/tests/smartcontract-test.html)
810
-
811
- ### 🎓 **Learning Path**
812
-
813
- 1. **Start**: [2-Minute Quick Start](#2-minute-quick-start)
814
- 2. **Practice**: [Examples Directory](https://github.com/codenlighten/smartledger-bsv/tree/main/examples)
815
- 3. **Build**: [Custom Script Guide](docs/CUSTOM_SCRIPT_DEVELOPMENT.md)
816
- 4. **Advanced**: [Covenant Development](docs/ADVANCED_COVENANT_DEVELOPMENT.md)
817
- 5. **Deploy**: [Production Guidelines](docs/ADVANCED_COVENANT_DEVELOPMENT.md#production-guidelines)
861
+ ### 🚀 Getting Started
862
+ - **[2-Minute Quick Start](#-2-minute-quick-start)** — npm, CDN, browser setup
863
+ - **[16 Loading Options](#-16-loading-options---choose-your-approach)** — pick the bundles you need
864
+ - **[API Reference](#-api-reference)** — quick method lookup
865
+ - **[CHANGELOG](./CHANGELOG.md)** — version history (current line: 4.x)
866
+ - **[SECURITY.md](./SECURITY.md)** — supported-versions policy + how to report
867
+
868
+ ### 🔒 Smart Contracts & Covenants
869
+ - **[Smart Contract Guide](docs/advanced/SMART_CONTRACT_GUIDE.md)** — comprehensive covenant development
870
+ - **[Advanced Covenant Development](docs/advanced/ADVANCED_COVENANT_DEVELOPMENT.md)** — full BIP-143 + OP_PUSH_TX guide
871
+ - **[Custom Script Development](docs/advanced/CUSTOM_SCRIPT_DEVELOPMENT.md)** — multi-sig, timelock, conditional patterns
872
+ - **[UTXO Manager Guide](docs/advanced/UTXO_MANAGER_GUIDE.md)** — UTXO management + mock generation
873
+ - **[Covenant Development Resolved](docs/COVENANT_DEVELOPMENT_RESOLVED.md)** — solutions to common issues
874
+ - **[PUSHTX Key Insights](docs/pushtx-key-insights.md)** — nChain WP1605 implementation notes
875
+ - **[SmartContract Development Guide](docs/SMART_CONTRACT_DEVELOPMENT_GUIDE.md)** — end-to-end workflow
876
+
877
+ ### 🆕 Advanced Features
878
+ - **[Legal Token Protocol](docs/advanced/LEGAL_TOKEN_PROTOCOL.md)** — property rights & obligation tokens (LTP)
879
+ - **[GDAF Developer Interface](docs/technical/GDAF_DEVELOPER_INTERFACE.md)** — Global Digital Attestation Framework
880
+ - **[Shamir Integration Summary](docs/technical/SHAMIR_INTEGRATION_SUMMARY.md)** — threshold cryptography & key backup
881
+
882
+ ### 📊 Technical References
883
+ - **[Module Reference](docs/MODULE_REFERENCE_COMPLETE.md)** — every shipped module
884
+ - **[Documentation Review Report](docs/DOCUMENTATION_REVIEW_REPORT.md)** — internal doc audit (historical)
885
+ - **[API Reference (docs/api/)](https://github.com/codenlighten/smartledger-bsv/tree/main/docs/api)** — per-module API docs
886
+
887
+ ### 📋 Examples & Demos
888
+ - **[Examples Directory](https://github.com/codenlighten/smartledger-bsv/tree/main/examples)** — runnable code samples
889
+ - **[Demos Directory](https://github.com/codenlighten/smartledger-bsv/tree/main/demos)** — interactive HTML & Node demos
890
+ - **[Test Suite](https://github.com/codenlighten/smartledger-bsv/tree/main/test)** — covenant verification specs, CLI smoke, full mocha suite
891
+
892
+ > **Note:** `examples/` and `demos/` live in the repo but are not shipped
893
+ > in the npm tarball (as of v3.4.4). Browse them on GitHub.
818
894
 
819
- ---
820
-
821
- ## � **Complete Documentation**
822
-
823
- ### 📚 **Getting Started Guides**
824
- - [📋 **UTXO Manager Guide**](docs/UTXO_MANAGER_GUIDE.md) - Complete UTXO management and mock generation
825
- - [🔒 **Smart Contract Guide**](docs/SMART_CONTRACT_GUIDE.md) - Comprehensive covenant development
826
- - [🛠️ **Custom Script Development**](docs/CUSTOM_SCRIPT_DEVELOPMENT.md) - Build custom Bitcoin scripts
827
- - [🚀 **Advanced Covenant Development**](docs/ADVANCED_COVENANT_DEVELOPMENT.md) - Production-ready covenants
828
-
829
- ### 🆕 **Advanced Features Documentation**
830
- - [⚖️ **Legal Token Protocol Guide**](docs/LTP_LEGAL_TOKENS_GUIDE.md) - Property rights & obligation tokens
831
- - [🌐 **Digital Attestation Guide**](docs/GDAF_DIGITAL_ATTESTATION_GUIDE.md) - DIDs & verifiable credentials
832
- - [🔐 **Shamir Secret Sharing Guide**](docs/SHAMIR_SECRET_SHARING_GUIDE.md) - Threshold cryptography & key backup
833
- - [🛡️ **Security Features**](SECURITY_SUMMARY.md) - Enhanced validation & smart verification
834
-
835
- ### 📊 **Technical References**
836
- - [📝 **Module Reference**](docs/MODULE_REFERENCE_COMPLETE.md) - All 12 modules explained
837
- - [🔍 **Documentation Review Report**](docs/DOCUMENTATION_REVIEW_REPORT.md) - Comprehensive analysis
838
- - [📋 **API Reference**](docs/api/) - Complete API documentation
839
- - [🔧 **Integration Guide**](SMARTCONTRACT_INTEGRATION.md) - Smart contract integration
840
-
841
- ### 📋 **Examples & Demos**
842
- - [� **Interactive Demos**](https://github.com/codenlighten/smartledger-bsv/tree/main/demos) - **NEW!** HTML & Node.js smart contract demos
843
- - [�📁 **Examples Directory**](https://github.com/codenlighten/smartledger-bsv/tree/main/examples) - Working code examples
844
- - [🎯 **Basic Examples**](https://github.com/codenlighten/smartledger-bsv/tree/main/examples/basic) - Simple transactions & addresses
845
- - [🔒 **Covenant Examples**](https://github.com/codenlighten/smartledger-bsv/tree/main/examples/covenants) - Smart contract patterns
846
- - [📊 **Advanced Examples**](https://github.com/codenlighten/smartledger-bsv/tree/main/examples/covenants2) - Production patterns
847
-
848
- **🎮 Try the Interactive Demos:**
849
895
  ```bash
850
- # Terminal-based interactive demo
851
- npm run demo
852
-
853
- # Or run specific features
854
- npm run demo:basics # Library basics & tests
855
- npm run demo:covenant # Covenant builder
856
- npm run demo:preimage # BIP-143 preimage parser
857
- npm run demo:utxo # UTXO generator
858
- npm run demo:scripts # Script tools
859
-
860
- # Web-based demo (open in browser)
861
- npm run demo:web
896
+ # Try the interactive demo:
897
+ npm run demo # terminal walkthrough
898
+ npm run demo:web # open demos/smart_contract_demo.html
899
+ npm run demo:covenant # covenant builder example
862
900
  ```
863
901
 
864
- ### 🔍 **Troubleshooting & Support**
865
- - [📚 **Complete Documentation**](docs/README.md) - Organized documentation hub
866
- - [❓ **Issues & Solutions**](https://github.com/codenlighten/smartledger-bsv/issues) - Community support
867
- - [📈 **Status Reports**](SMARTLEDGER_V302_STATUS_REPORT.md) - Latest updates
868
- - [🔒 **Security Policy**](SECURITY.md) - Security guidelines
869
- - [📝 **Changelog**](CHANGELOG.md) - Version history
902
+ ### 🔗 Recommended learning path
903
+
904
+ 1. **Start** — [2-Minute Quick Start](#-2-minute-quick-start)
905
+ 2. **Practice** — [Examples Directory](https://github.com/codenlighten/smartledger-bsv/tree/main/examples)
906
+ 3. **Build** — [Custom Script Development](docs/advanced/CUSTOM_SCRIPT_DEVELOPMENT.md)
907
+ 4. **Advanced** — [Advanced Covenant Development](docs/advanced/ADVANCED_COVENANT_DEVELOPMENT.md)
908
+ 5. **Production** — [SECURITY.md](./SECURITY.md) + [v4.0.0 CHANGELOG](./CHANGELOG.md#400---2026-05-31) (mandatory read before mainnet credentials)
870
909
 
871
910
  ---
872
911
 
873
- ## �📄 **License**
912
+ ## 📄 **License**
874
913
 
875
- This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
914
+ This project is licensed under the MIT License — see the [LICENSE](LICENSE) file for details.
876
915
 
877
916
  ## 🤝 **Contributing**
878
917
 
879
- We welcome contributions to SmartLedger-BSV! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
918
+ Issues, PRs, and security reports welcome at
919
+ [github.com/codenlighten/smartledger-bsv](https://github.com/codenlighten/smartledger-bsv).
920
+ For security vulnerabilities, follow the disclosure process in
921
+ [SECURITY.md](./SECURITY.md) rather than opening a public issue.
880
922
 
881
923
  ## 🏢 **Enterprise Support**
882
924
 
883
925
  - **GitHub**: [github.com/codenlighten/smartledger-bsv](https://github.com/codenlighten/smartledger-bsv)
884
- - **NPM**: [@smartledger/bsv](https://www.npmjs.com/package/@smartledger/bsv)
926
+ - **NPM (scoped)**: [@smartledger/bsv](https://www.npmjs.com/package/@smartledger/bsv)
927
+ - **NPM (unscoped)**: [smartledger-bsv](https://www.npmjs.com/package/smartledger-bsv)
885
928
  - **Issues**: [GitHub Issues](https://github.com/codenlighten/smartledger-bsv/issues)
886
- - **Documentation**: [Complete Docs](#complete-documentation)
929
+ - **Security**: [SECURITY.md](./SECURITY.md)
887
930
 
888
931
  ---
889
932
 
890
- **SmartLedger-BSV v3.3.4** - *Complete Bitcoin SV Development Framework*
933
+ **SmartLedger-BSV v4.2.1** — *Complete Bitcoin SV Development Framework*
891
934
 
892
- Built with ❤️ for the Bitcoin SV ecosystem • 9 Loading Options • Enterprise Ready
935
+ Built with ❤️ for the Bitcoin SV ecosystem • 16 Loading Options • Interpreter-Verified Covenants