@smartledger/bsv 4.1.0 → 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 (21) hide show
  1. package/CHANGELOG.md +68 -0
  2. package/README.md +217 -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.min.js +8 -8
  9. package/docs/COVENANT_DEVELOPMENT_RESOLVED.md +2 -2
  10. package/docs/MODULE_REFERENCE_COMPLETE.md +27 -27
  11. package/docs/advanced/UTXO_MANAGER_GUIDE.md +1 -1
  12. package/docs/getting-started/INSTALLATION.md +25 -25
  13. package/docs/getting-started/QUICK_START.md +7 -7
  14. package/docs/migration/FROM_BSV_1_5_6.md +5 -5
  15. package/lib/smart_contract/covenant_helpers.js +118 -0
  16. package/lib/smart_contract/index.js +30 -1
  17. package/lib/smart_contract/locks.js +101 -0
  18. package/lib/smart_contract/pels.js +62 -0
  19. package/lib/smart_contract/pushtx.js +138 -0
  20. package/lib/smart_contract/token.js +95 -0
  21. 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.1.0-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.1.0
29
- npm install @smartledger/bsv@4.1.0
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.1.0/bsv.min.js` |
139
- | **bsv.bundle.js** | 937KB | Everything in one file | `unpkg.com/@smartledger/bsv@4.1.0/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.1.0/bsv-didweb.min.js` |
145
- | **🟢 bsv-vcjwt.min.js** | 419KB | **VC-JWT issue/verify** | `unpkg.com/@smartledger/bsv@4.1.0/bsv-vcjwt.min.js` |
146
- | **🟢 bsv-statuslist.min.js** | 487KB | **StatusList2021 revocation** | `unpkg.com/@smartledger/bsv@4.1.0/bsv-statuslist.min.js` |
147
- | **🟢 bsv-anchor.min.js** | 418KB | **BSV anchoring (hash-only)** | `unpkg.com/@smartledger/bsv@4.1.0/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.1.0/bsv-smartcontract.min.js` |
153
- | **bsv-covenant.min.js** | 913KB | Covenant operations | `unpkg.com/@smartledger/bsv@4.1.0/bsv-covenant.min.js` |
154
- | **bsv-script-helper.min.js** | 26KB | Custom script tools | `unpkg.com/@smartledger/bsv@4.1.0/bsv-script-helper.min.js` |
155
- | **bsv-security.min.js** | 26KB | Security enhancements | `unpkg.com/@smartledger/bsv@4.1.0/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.1.0/bsv-ltp.min.js` |
161
- | **bsv-gdaf.min.js** | 1184KB | Digital Identity & Attestation | `unpkg.com/@smartledger/bsv@4.1.0/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.1.0/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.1.0/bsv-ecies.min.js` |
172
- | **bsv-message.min.js** | 26KB | Message signing | `unpkg.com/@smartledger/bsv@4.1.0/bsv-message.min.js` |
173
- | **bsv-mnemonic.min.js** | 681KB | HD wallets | `unpkg.com/@smartledger/bsv@4.1.0/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.1.0/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.1.0/bsv.min.js"></script>
280
- <script src="https://unpkg.com/@smartledger/bsv@4.1.0/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.1.0/bsv.min.js"></script>
290
- <script src="https://unpkg.com/@smartledger/bsv@4.1.0/bsv-covenant.min.js"></script>
291
- <script src="https://unpkg.com/@smartledger/bsv@4.1.0/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.1.0/bsv.min.js"></script>
302
- <script src="https://unpkg.com/@smartledger/bsv@4.1.0/bsv-ltp.min.js"></script>
303
- <script src="https://unpkg.com/@smartledger/bsv@4.1.0/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.1.0/bsv.min.js"></script>
318
- <script src="https://unpkg.com/@smartledger/bsv@4.1.0/bsv-security.min.js"></script>
319
- <script src="https://unpkg.com/@smartledger/bsv@4.1.0/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.1.0/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.1.0/bsv.min.js"></script>
412
- <script src="https://unpkg.com/@smartledger/bsv@4.1.0/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.1.0/bsv.min.js"></script>
422
- <script src="https://unpkg.com/@smartledger/bsv@4.1.0/bsv-covenant.min.js"></script>
423
- <script src="https://unpkg.com/@smartledger/bsv@4.1.0/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.1.0/bsv.min.js"></script>
434
- <script src="https://unpkg.com/@smartledger/bsv@4.1.0/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.1.0/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,28 +676,47 @@ 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)
712
+ ```
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)
652
720
  ```
653
721
 
654
722
  ### Evaluating covenants locally — `Interpreter.useGenesisLimits()` (v4.1.0+)
@@ -705,7 +773,7 @@ const timelockScript = helper.createTimelockScript(
705
773
  );
706
774
  ```
707
775
 
708
- ## � Examples
776
+ ## 📁 Examples
709
777
 
710
778
  ### Basic Examples
711
779
  - **[Advanced Covenant Demo](advanced_covenant_demo.js)**: Complete covenant showcase
@@ -719,13 +787,9 @@ const timelockScript = helper.createTimelockScript(
719
787
 
720
788
  ## 🔧 CDN Bundles
721
789
 
722
- | Bundle | Size | Description |
723
- |--------|------|-------------|
724
- | `bsv.bundle.js` | 684KB | Complete library with all features |
725
- | `bsv.min.js` | 364KB | Minified production version |
726
- | `bsv-ecies.min.js` | 145KB | ECIES encryption only |
727
- | `bsv-message.min.js` | 120KB | Message signing only |
728
- | `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.
729
793
 
730
794
  ## 🔐 Security
731
795
 
@@ -759,165 +823,113 @@ const okDefault = bsv.crypto.ECDSA.verify(msgHashBuffer, signature, publicKey)
759
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`.
760
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.
761
825
 
762
- 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.
763
835
 
764
836
  ## 📝 Changelog
765
837
 
766
- ### v3.2.0 - JavaScript-to-Bitcoin Script Framework
767
- - ✅ Complete JavaScript-to-Bitcoin Script translation system
768
- - ✅ 121 Bitcoin Script opcodes mapped to JavaScript functions
769
- - ✅ High-level CovenantBuilder API for rapid development
770
- - ✅ Real-time script simulation and debugging capabilities
771
- - ✅ Template-based covenant patterns library
772
- - ✅ Automatic ASM generation from JavaScript operations
773
- - ✅ Enhanced documentation and comprehensive examples
774
-
775
- ### v3.1.1 - Advanced Covenant Framework
776
- - ✅ Enhanced covenant interface with BIP143 + PUSHTX support
777
- - ✅ Perpetually Enforcing Locking Scripts (PELS) implementation
778
- - ✅ Transaction introspection with preimage analysis
779
- - ✅ Comprehensive documentation and examples
780
-
781
- ### v3.0.2 - Custom Script Framework
782
- - ✅ Complete custom script development API
783
- - ✅ Multi-signature, timelock, and conditional script support
784
- - ✅ Transaction signature API gap resolution
785
-
786
- ### v3.0.1 - Ultra-Low Fee System
787
- - ✅ 0.01 sats/byte fee configuration (91% reduction)
788
- - ✅ Advanced UTXO state management
789
- - ✅ Change output optimization
790
-
791
- ## 📄 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`.
792
856
 
793
857
  ---
794
858
 
795
859
  ## 📚 **Complete Documentation**
796
860
 
797
- ### 🚀 **Getting Started**
798
- - **[2-Minute Quick Start](#2-minute-quick-start)** - Get up and running fast
799
- - **[Loading Options](#9-loading-options--choose-your-approach)** - Choose your distribution method
800
- - **[API Reference](#api-reference)** - Quick method lookup
801
- - **[Installation Guide](#installation)** - npm, CDN, and browser setup
802
-
803
- ### 🎯 **Development Guides**
804
- - **[Advanced Covenant Development](docs/ADVANCED_COVENANT_DEVELOPMENT.md)** - Complete BIP143 + PUSHTX guide
805
- - **[Custom Script Development](docs/CUSTOM_SCRIPT_DEVELOPMENT.md)** - Multi-sig, timelock, and custom patterns
806
- - **[Covenant Development Resolved](docs/COVENANT_DEVELOPMENT_RESOLVED.md)** - Solutions to common issues
807
- - **[PUSHTX Key Insights](docs/pushtx-key-insights.md)** - nChain research implementation
808
-
809
- ### 🔧 **Technical Resources**
810
- - **[SmartContract Integration](SMARTCONTRACT_INTEGRATION.md)** - Debug tools and analysis
811
- - **[Examples Directory](https://github.com/codenlighten/smartledger-bsv/tree/main/examples)** - Working code samples
812
- - **[Test Suite](https://github.com/codenlighten/smartledger-bsv/tree/main/tests)** - Comprehensive testing examples
813
- - **[Build System](build/)** - Webpack configurations
814
-
815
- ### 🌐 **Loading Strategy Examples**
816
-
817
- | **Use Case** | **Recommended Load** | **Size** | **Features** |
818
- |--------------|---------------------|----------|--------------|
819
- | **Simple Transactions** | `bsv.min.js` | 937KB | Core BSV + SmartContract |
820
- | **DeFi Development** | Core + Covenant + Debug | ~2.7MB | Advanced contracts + tools (bundles re-embed core BSV) |
821
- | **Enterprise Apps** | `bsv.bundle.js` | 937KB | Everything included |
822
- | **Mobile/Lightweight** | Core + Script Helper | ~963KB | Essential tools only |
823
- | **Research/Analysis** | Core + SmartContract | 900KB | Full debug capabilities |
824
-
825
- ### 🔗 **Cross-References**
826
-
827
- **From Quick Start → Deep Dive:**
828
- - [Basic Transaction](#2-minute-quick-start) → [Transaction API](docs/transaction.md)
829
- - [Covenant Example](#2-minute-quick-start) → [Advanced Covenant Guide](docs/ADVANCED_COVENANT_DEVELOPMENT.md)
830
- - [API Reference](#api-reference) → [Method Documentation](docs/)
831
-
832
- **From Examples → Implementation:**
833
- - [Covenant Examples](https://github.com/codenlighten/smartledger-bsv/tree/main/examples/covenants) → [Production Guide](docs/ADVANCED_COVENANT_DEVELOPMENT.md#production-guidelines)
834
- - [Script Examples](https://github.com/codenlighten/smartledger-bsv/tree/main/examples/scripts) → [Custom Script Guide](docs/CUSTOM_SCRIPT_DEVELOPMENT.md)
835
- - [Test Files](https://github.com/codenlighten/smartledger-bsv/tree/main/tests) → [Integration Examples](https://github.com/codenlighten/smartledger-bsv/tree/main/examples)
836
-
837
- **From Concepts → Code:**
838
- - [PUSHTX Theory](docs/pushtx-key-insights.md) → [Covenant Implementation](https://github.com/codenlighten/smartledger-bsv/blob/main/examples/covenants/advanced_covenant_demo.js)
839
- - [Security Features](#smart-security) → [Implementation](lib/crypto/smartledger_verify.js)
840
- - [Debug Tools](#debug-tools) → [Usage Examples](https://github.com/codenlighten/smartledger-bsv/blob/main/tests/smartcontract-test.html)
841
-
842
- ### 🎓 **Learning Path**
843
-
844
- 1. **Start**: [2-Minute Quick Start](#2-minute-quick-start)
845
- 2. **Practice**: [Examples Directory](https://github.com/codenlighten/smartledger-bsv/tree/main/examples)
846
- 3. **Build**: [Custom Script Guide](docs/CUSTOM_SCRIPT_DEVELOPMENT.md)
847
- 4. **Advanced**: [Covenant Development](docs/ADVANCED_COVENANT_DEVELOPMENT.md)
848
- 5. **Deploy**: [Production Guidelines](docs/ADVANCED_COVENANT_DEVELOPMENT.md#production-guidelines)
849
-
850
- ---
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.
851
894
 
852
- ## � **Complete Documentation**
853
-
854
- ### 📚 **Getting Started Guides**
855
- - [📋 **UTXO Manager Guide**](docs/UTXO_MANAGER_GUIDE.md) - Complete UTXO management and mock generation
856
- - [🔒 **Smart Contract Guide**](docs/SMART_CONTRACT_GUIDE.md) - Comprehensive covenant development
857
- - [🛠️ **Custom Script Development**](docs/CUSTOM_SCRIPT_DEVELOPMENT.md) - Build custom Bitcoin scripts
858
- - [🚀 **Advanced Covenant Development**](docs/ADVANCED_COVENANT_DEVELOPMENT.md) - Production-ready covenants
859
-
860
- ### 🆕 **Advanced Features Documentation**
861
- - [⚖️ **Legal Token Protocol Guide**](docs/LTP_LEGAL_TOKENS_GUIDE.md) - Property rights & obligation tokens
862
- - [🌐 **Digital Attestation Guide**](docs/GDAF_DIGITAL_ATTESTATION_GUIDE.md) - DIDs & verifiable credentials
863
- - [🔐 **Shamir Secret Sharing Guide**](docs/SHAMIR_SECRET_SHARING_GUIDE.md) - Threshold cryptography & key backup
864
- - [🛡️ **Security Features**](SECURITY_SUMMARY.md) - Enhanced validation & smart verification
865
-
866
- ### 📊 **Technical References**
867
- - [📝 **Module Reference**](docs/MODULE_REFERENCE_COMPLETE.md) - All 12 modules explained
868
- - [🔍 **Documentation Review Report**](docs/DOCUMENTATION_REVIEW_REPORT.md) - Comprehensive analysis
869
- - [📋 **API Reference**](docs/api/) - Complete API documentation
870
- - [🔧 **Integration Guide**](SMARTCONTRACT_INTEGRATION.md) - Smart contract integration
871
-
872
- ### 📋 **Examples & Demos**
873
- - [� **Interactive Demos**](https://github.com/codenlighten/smartledger-bsv/tree/main/demos) - **NEW!** HTML & Node.js smart contract demos
874
- - [�📁 **Examples Directory**](https://github.com/codenlighten/smartledger-bsv/tree/main/examples) - Working code examples
875
- - [🎯 **Basic Examples**](https://github.com/codenlighten/smartledger-bsv/tree/main/examples/basic) - Simple transactions & addresses
876
- - [🔒 **Covenant Examples**](https://github.com/codenlighten/smartledger-bsv/tree/main/examples/covenants) - Smart contract patterns
877
- - [📊 **Advanced Examples**](https://github.com/codenlighten/smartledger-bsv/tree/main/examples/covenants2) - Production patterns
878
-
879
- **🎮 Try the Interactive Demos:**
880
895
  ```bash
881
- # Terminal-based interactive demo
882
- npm run demo
883
-
884
- # Or run specific features
885
- npm run demo:basics # Library basics & tests
886
- npm run demo:covenant # Covenant builder
887
- npm run demo:preimage # BIP-143 preimage parser
888
- npm run demo:utxo # UTXO generator
889
- npm run demo:scripts # Script tools
890
-
891
- # Web-based demo (open in browser)
892
- 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
893
900
  ```
894
901
 
895
- ### 🔍 **Troubleshooting & Support**
896
- - [📚 **Complete Documentation**](docs/README.md) - Organized documentation hub
897
- - [❓ **Issues & Solutions**](https://github.com/codenlighten/smartledger-bsv/issues) - Community support
898
- - [📈 **Status Reports**](SMARTLEDGER_V302_STATUS_REPORT.md) - Latest updates
899
- - [🔒 **Security Policy**](SECURITY.md) - Security guidelines
900
- - [📝 **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)
901
909
 
902
910
  ---
903
911
 
904
- ## �📄 **License**
912
+ ## 📄 **License**
905
913
 
906
- 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.
907
915
 
908
916
  ## 🤝 **Contributing**
909
917
 
910
- 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.
911
922
 
912
923
  ## 🏢 **Enterprise Support**
913
924
 
914
925
  - **GitHub**: [github.com/codenlighten/smartledger-bsv](https://github.com/codenlighten/smartledger-bsv)
915
- - **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)
916
928
  - **Issues**: [GitHub Issues](https://github.com/codenlighten/smartledger-bsv/issues)
917
- - **Documentation**: [Complete Docs](#complete-documentation)
929
+ - **Security**: [SECURITY.md](./SECURITY.md)
918
930
 
919
931
  ---
920
932
 
921
- **SmartLedger-BSV v3.3.4** - *Complete Bitcoin SV Development Framework*
933
+ **SmartLedger-BSV v4.2.1** — *Complete Bitcoin SV Development Framework*
922
934
 
923
- 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