@smartledger/bsv 4.0.0 → 4.0.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 (19) hide show
  1. package/CHANGELOG.md +62 -0
  2. package/README.md +40 -40
  3. package/SECURITY.md +6 -3
  4. package/bsv-covenant.min.js +7 -7
  5. package/bsv-gdaf.min.js +8 -8
  6. package/bsv-ltp.min.js +8 -8
  7. package/bsv-smartcontract.min.js +8 -8
  8. package/bsv.bundle.js +8 -8
  9. package/bsv.min.js +7 -7
  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/index.js +29 -1
  17. package/lib/smart_contract/utxo_generator.js +9 -4
  18. package/lib/smartutxo.js +44 -17
  19. package/package.json +1 -1
package/CHANGELOG.md CHANGED
@@ -5,6 +5,68 @@ All notable changes to SmartLedger-BSV will be documented in this file.
5
5
  The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
6
6
  and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7
7
 
8
+ ## [4.0.1] - 2026-05-31
9
+
10
+ ### Deprecated
11
+
12
+ - **`bsv.SmartUTXO` is now soft-deprecated and will be removed in v5.0.0.**
13
+ `lib/smartutxo.js` is a development-only file-backed UTXO simulator —
14
+ it writes to `<package-root>/utilities/blockchain-state.json` (a path
15
+ inside `node_modules`), has no concurrency controls, ships with an
16
+ empty seed (the 3.3 MB dev fixture is `.npmignore`d), and was exposed
17
+ on the main `bsv.*` namespace where it looked like a production UTXO
18
+ manager. That conflation is the same class of footgun as the v4.0.0
19
+ `wallet.json` leak — dev fixtures don't belong on the production
20
+ surface.
21
+
22
+ The symbol is preserved (no semver break) but access now logs a
23
+ one-shot deprecation warning. Set `BSV_HIDE_DEPRECATIONS=1` to
24
+ silence. The supported import path is unchanged for users who
25
+ legitimately need the simulator:
26
+
27
+ ```js
28
+ const SmartUTXO = require('@smartledger/bsv/lib/smartutxo')
29
+ ```
30
+
31
+ All internal callers (`lib/smart_contract/utxo_generator.js`) and
32
+ in-repo demos/examples were migrated to the direct require so they
33
+ don't trigger the warning. `bsv.SmartMiner` and `bsv.CustomScriptHelper`
34
+ are unchanged in this release.
35
+
36
+ ### Fixed
37
+
38
+ - **`SmartUTXOManager.createMockUTXOs(address, ...)` produces correct
39
+ mocks.** Two bugs in one method:
40
+ 1. The P2PKH script encoded a *random* 20-byte hash rather than the
41
+ hash of the provided `address`, so the mock claimed to belong to
42
+ `address` but its locking script committed to a different address.
43
+ Anyone who attempted to sign these mocks with the private key for
44
+ `address` got a signature that wouldn't verify.
45
+ 2. It called Node's `crypto.randomBytes(...)` unconditionally, which
46
+ throws in browser bundles where `crypto` is undefined.
47
+
48
+ Both fixed: the script now derives from
49
+ `bsv.Script.buildPublicKeyHashOut(bsv.Address.fromString(address))`,
50
+ and randomness uses `bsv.crypto.Random.getRandomBuffer(32)` which
51
+ works in both Node and browser builds.
52
+
53
+ ### Documentation
54
+
55
+ - Added a clear "DEVELOPMENT ONLY" header block to `lib/smartutxo.js`
56
+ spelling out the supported import path, the deprecation status, and
57
+ why it shouldn't be used in production.
58
+ - Bumped CDN/install refs from `@4.0.0` to `@4.0.1` across README +
59
+ 6 docs files. SECURITY.md is unchanged (4.x is still the only
60
+ supported line, 3.4.x still flagged as vulnerable).
61
+
62
+ ### Semver note
63
+
64
+ This release deliberately stops short of a hard removal. Removing
65
+ `bsv.SmartUTXO` outright would be a major-version break, and v4.0.0
66
+ shipped less than 24 hours ago — bumping to v5.0.0 now would churn
67
+ consumers who are still digesting the v4.0.0 credential-verification
68
+ changes. The hard removal is queued for v5.0.0.
69
+
8
70
  ## [4.0.0] - 2026-05-31
9
71
 
10
72
  ### Security
package/README.md CHANGED
@@ -2,7 +2,7 @@
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-3.4.5-blue.svg)](https://www.npmjs.com/package/@smartledger/bsv)
5
+ [![Version](https://img.shields.io/badge/version-4.0.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)
@@ -25,8 +25,8 @@ The most comprehensive and flexible Bitcoin SV library available. **In v3.4.x**:
25
25
  ### **Quick Start - Issue Your First Verifiable Credential**
26
26
 
27
27
  ```bash
28
- # Install SmartLedger BSV v3.4.5
29
- npm install @smartledger/bsv@3.4.5
28
+ # Install SmartLedger BSV v4.0.1
29
+ npm install @smartledger/bsv@4.0.1
30
30
 
31
31
  # Initialize DID:web issuer (generates ES256 keys)
32
32
  npx smartledger-bsv didweb init --domain example.com --alg ES256
@@ -135,42 +135,42 @@ console.log('Status:', status) // 'revoked'
135
135
  ### **Core Modules**
136
136
  | Module | Size | Use Case | CDN |
137
137
  |--------|------|----------|-----|
138
- | **bsv.min.js** | 937KB | Core BSV + SmartContract | `unpkg.com/@smartledger/bsv@3.4.5/bsv.min.js` |
139
- | **bsv.bundle.js** | 937KB | Everything in one file | `unpkg.com/@smartledger/bsv@3.4.5/bsv.bundle.js` |
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` |
140
140
 
141
141
  ### **🆕 W3C Verifiable Credentials (v3.4.x)**
142
142
  | Module | Size | Use Case | CDN |
143
143
  |--------|------|----------|-----|
144
- | **🟢 bsv-didweb.min.js** | 419KB | **DID:web generation** | `unpkg.com/@smartledger/bsv@3.4.5/bsv-didweb.min.js` |
145
- | **🟢 bsv-vcjwt.min.js** | 419KB | **VC-JWT issue/verify** | `unpkg.com/@smartledger/bsv@3.4.5/bsv-vcjwt.min.js` |
146
- | **🟢 bsv-statuslist.min.js** | 487KB | **StatusList2021 revocation** | `unpkg.com/@smartledger/bsv@3.4.5/bsv-statuslist.min.js` |
147
- | **🟢 bsv-anchor.min.js** | 418KB | **BSV anchoring (hash-only)** | `unpkg.com/@smartledger/bsv@3.4.5/bsv-anchor.min.js` |
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` |
148
148
 
149
149
  ### **Smart Contract & Development**
150
150
  | Module | Size | Use Case | CDN |
151
151
  |--------|------|----------|-----|
152
- | **bsv-smartcontract.min.js** | 937KB | Complete covenant framework | `unpkg.com/@smartledger/bsv@3.4.5/bsv-smartcontract.min.js` |
153
- | **bsv-covenant.min.js** | 913KB | Covenant operations | `unpkg.com/@smartledger/bsv@3.4.5/bsv-covenant.min.js` |
154
- | **bsv-script-helper.min.js** | 26KB | Custom script tools | `unpkg.com/@smartledger/bsv@3.4.5/bsv-script-helper.min.js` |
155
- | **bsv-security.min.js** | 26KB | Security enhancements | `unpkg.com/@smartledger/bsv@3.4.5/bsv-security.min.js` |
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` |
156
156
 
157
157
  ### **Legal & Compliance**
158
158
  | Module | Size | Use Case | CDN |
159
159
  |--------|------|----------|-----|
160
- | **bsv-ltp.min.js** | 1184KB | Legal Token Protocol | `unpkg.com/@smartledger/bsv@3.4.5/bsv-ltp.min.js` |
161
- | **bsv-gdaf.min.js** | 1184KB | Digital Identity & Attestation | `unpkg.com/@smartledger/bsv@3.4.5/bsv-gdaf.min.js` |
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` |
162
162
 
163
163
  ### **Advanced Cryptography**
164
164
  | Module | Size | Use Case | CDN |
165
165
  |--------|------|----------|-----|
166
- | **bsv-shamir.min.js** | 432KB | Threshold Cryptography | `unpkg.com/@smartledger/bsv@3.4.5/bsv-shamir.min.js` |
166
+ | **bsv-shamir.min.js** | 432KB | Threshold Cryptography | `unpkg.com/@smartledger/bsv@4.0.1/bsv-shamir.min.js` |
167
167
 
168
168
  ### **Utilities**
169
169
  | Module | Size | Use Case | CDN |
170
170
  |--------|------|----------|-----|
171
- | **bsv-ecies.min.js** | 71KB | Encryption | `unpkg.com/@smartledger/bsv@3.4.5/bsv-ecies.min.js` |
172
- | **bsv-message.min.js** | 26KB | Message signing | `unpkg.com/@smartledger/bsv@3.4.5/bsv-message.min.js` |
173
- | **bsv-mnemonic.min.js** | 681KB | HD wallets | `unpkg.com/@smartledger/bsv@3.4.5/bsv-mnemonic.min.js` |
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` |
174
174
 
175
175
  ## ⚡ **2-Minute Quick Start**
176
176
 
@@ -181,7 +181,7 @@ Get started with Bitcoin SV development in under 2 minutes:
181
181
  npm install @smartledger/bsv
182
182
 
183
183
  # Or include in HTML
184
- <script src="https://unpkg.com/@smartledger/bsv@3.4.5/bsv.min.js"></script>
184
+ <script src="https://unpkg.com/@smartledger/bsv@4.0.1/bsv.min.js"></script>
185
185
  ```
186
186
 
187
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.
@@ -276,8 +276,8 @@ const covenant = bsv.SmartContract.createCovenantBuilder()
276
276
 
277
277
  ### 🔧 **Basic Development** (~963KB total)
278
278
  ```html
279
- <script src="https://unpkg.com/@smartledger/bsv@3.4.5/bsv.min.js"></script>
280
- <script src="https://unpkg.com/@smartledger/bsv@3.4.5/bsv-script-helper.min.js"></script>
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>
281
281
  <script>
282
282
  const privateKey = new bsv.PrivateKey();
283
283
  const utxos = new bsv.SmartContract.UTXOGenerator().createRealUTXOs(2, 100000);
@@ -286,9 +286,9 @@ const covenant = bsv.SmartContract.createCovenantBuilder()
286
286
 
287
287
  ### 🔒 **Smart Contract Development** (~2.7MB total — each bundle re-embeds core BSV)
288
288
  ```html
289
- <script src="https://unpkg.com/@smartledger/bsv@3.4.5/bsv.min.js"></script>
290
- <script src="https://unpkg.com/@smartledger/bsv@3.4.5/bsv-covenant.min.js"></script>
291
- <script src="https://unpkg.com/@smartledger/bsv@3.4.5/bsv-smartcontract.min.js"></script>
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>
292
292
  <script>
293
293
  const covenant = bsv.SmartContract.createCovenantBuilder()
294
294
  .extractField('amount').push(50000).greaterThanOrEqual().verify().build();
@@ -298,9 +298,9 @@ const covenant = bsv.SmartContract.createCovenantBuilder()
298
298
 
299
299
  ### 🆕 **Legal & Identity Development** (~3.2MB total — each bundle re-embeds core BSV)
300
300
  ```html
301
- <script src="https://unpkg.com/@smartledger/bsv@3.4.5/bsv.min.js"></script>
302
- <script src="https://unpkg.com/@smartledger/bsv@3.4.5/bsv-ltp.min.js"></script>
303
- <script src="https://unpkg.com/@smartledger/bsv@3.4.5/bsv-gdaf.min.js"></script>
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>
304
304
  <script>
305
305
  // Legal Token Protocol
306
306
  const propertyToken = bsv.createPropertyToken({
@@ -314,9 +314,9 @@ const covenant = bsv.SmartContract.createCovenantBuilder()
314
314
 
315
315
  ### 🆕 **Security & Cryptography** (~1.4MB total)
316
316
  ```html
317
- <script src="https://unpkg.com/@smartledger/bsv@3.4.5/bsv.min.js"></script>
318
- <script src="https://unpkg.com/@smartledger/bsv@3.4.5/bsv-security.min.js"></script>
319
- <script src="https://unpkg.com/@smartledger/bsv@3.4.5/bsv-shamir.min.js"></script>
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>
320
320
  <script>
321
321
  // Threshold Cryptography
322
322
  const shares = bsv.splitSecret('my_secret_key', 5, 3); // 5 shares, 3 needed
@@ -328,7 +328,7 @@ const covenant = bsv.SmartContract.createCovenantBuilder()
328
328
 
329
329
  ### 🎯 **Everything Bundle** (937KB)
330
330
  ```html
331
- <script src="https://unpkg.com/@smartledger/bsv@3.4.5/bsv.bundle.js"></script>
331
+ <script src="https://unpkg.com/@smartledger/bsv@4.0.1/bsv.bundle.js"></script>
332
332
  <script>
333
333
  // Everything available immediately
334
334
  const shares = bsv.splitSecret('secret', 5, 3); // Shamir Secret Sharing
@@ -408,8 +408,8 @@ const contractTx = covenant.createCovenantTransaction({
408
408
 
409
409
  #### 1. **Minimal Setup** - Core + Script Helper (~963KB)
410
410
  ```html
411
- <script src="https://unpkg.com/@smartledger/bsv@3.4.5/bsv.min.js"></script>
412
- <script src="https://unpkg.com/@smartledger/bsv@3.4.5/bsv-script-helper.min.js"></script>
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>
413
413
  <script>
414
414
  const tx = new bsv.Transaction();
415
415
  const sig = bsvScriptHelper.createSignature(tx, privateKey, 0, script, satoshis);
@@ -418,9 +418,9 @@ const contractTx = covenant.createCovenantTransaction({
418
418
 
419
419
  #### 2. **DeFi Development** - Core + Covenants + Debug (~2.7MB — each bundle re-embeds core BSV)
420
420
  ```html
421
- <script src="https://unpkg.com/@smartledger/bsv@3.4.5/bsv.min.js"></script>
422
- <script src="https://unpkg.com/@smartledger/bsv@3.4.5/bsv-covenant.min.js"></script>
423
- <script src="https://unpkg.com/@smartledger/bsv@3.4.5/bsv-smartcontract.min.js"></script>
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>
424
424
  <script>
425
425
  const covenant = new bsvCovenant.CovenantInterface();
426
426
  const debugInfo = SmartContract.interpretScript(script);
@@ -430,8 +430,8 @@ const contractTx = covenant.createCovenantTransaction({
430
430
 
431
431
  #### 3. **Security First** - Core + Enhanced Security (~963KB)
432
432
  ```html
433
- <script src="https://unpkg.com/@smartledger/bsv@3.4.5/bsv.min.js"></script>
434
- <script src="https://unpkg.com/@smartledger/bsv@3.4.5/bsv-security.min.js"></script>
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>
435
435
  <script>
436
436
  const verified = bsvSecurity.SmartVerify.verify(signature, hash, publicKey);
437
437
  const enhanced = bsvSecurity.EllipticFixed.createSignature(privateKey, hash);
@@ -440,7 +440,7 @@ const contractTx = covenant.createCovenantTransaction({
440
440
 
441
441
  #### 4. **Everything Bundle** - One File Solution (937KB)
442
442
  ```html
443
- <script src="https://unpkg.com/@smartledger/bsv@3.4.5/bsv.bundle.js"></script>
443
+ <script src="https://unpkg.com/@smartledger/bsv@4.0.1/bsv.bundle.js"></script>
444
444
  <script>
445
445
  // Everything available under bsv namespace
446
446
  const keys = bsv.SmartLedgerBundle.generateKeys();
package/SECURITY.md CHANGED
@@ -4,12 +4,15 @@ Thank you for helping keep `@smartledger/bsv` and its users safe.
4
4
 
5
5
  ## Supported Versions
6
6
 
7
- Security fixes are applied to the latest minor release line. Earlier releases
8
- are not patched; please upgrade.
7
+ Security fixes are applied to the latest major release line. Earlier releases
8
+ are not patched; please upgrade. **Versions ≤ 3.4.5 contain three known,
9
+ exploitable vulnerabilities in the GDAF credential verification path (see
10
+ CHANGELOG `## [4.0.0]`); upgrade to 4.x is strongly recommended.**
9
11
 
10
12
  | Version | Supported |
11
13
  | ------- | ------------------ |
12
- | 3.4.x | :white_check_mark: |
14
+ | 4.x | :white_check_mark: |
15
+ | 3.4.x | :x: (contains known credential-verification vulnerabilities; upgrade to 4.x) |
13
16
  | < 3.4 | :x: |
14
17
 
15
18
  ## Reporting a Vulnerability