@smartledger/bsv 5.0.0 → 5.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (43) hide show
  1. package/CHANGELOG.md +71 -0
  2. package/README.md +91 -71
  3. package/bsv-anchor.min.js +6 -7
  4. package/bsv-covenant.min.js +22 -18
  5. package/bsv-didweb.min.js +6 -7
  6. package/bsv-ecies.min.js +6 -6
  7. package/bsv-gdaf.min.js +19 -21
  8. package/bsv-ltp.min.js +19 -21
  9. package/bsv-message.min.js +4 -4
  10. package/bsv-mnemonic.min.js +6 -7
  11. package/bsv-script-helper.min.js +4 -4
  12. package/bsv-security.min.js +4 -4
  13. package/bsv-shamir.min.js +7 -8
  14. package/bsv-smartcontract.min.js +19 -21
  15. package/bsv-statuslist.min.js +8 -9
  16. package/bsv-vcjwt.min.js +6 -7
  17. package/bsv.bundle.js +19 -21
  18. package/bsv.min.js +19 -21
  19. package/build/webpack.anchor.config.js +4 -6
  20. package/build/webpack.base.js +99 -0
  21. package/build/webpack.bundle.config.js +6 -14
  22. package/build/webpack.config.js +7 -10
  23. package/build/webpack.covenant.config.js +5 -15
  24. package/build/webpack.didweb.config.js +4 -6
  25. package/build/webpack.ecies.config.js +15 -0
  26. package/build/webpack.gdaf.config.js +4 -6
  27. package/build/webpack.ltp.config.js +4 -6
  28. package/build/webpack.message.config.js +15 -0
  29. package/build/webpack.mnemonic.config.js +15 -0
  30. package/build/webpack.script-helper.config.js +5 -15
  31. package/build/webpack.security.config.js +7 -16
  32. package/build/webpack.shamir.config.js +15 -0
  33. package/build/webpack.smartcontract.config.js +5 -12
  34. package/build/webpack.statuslist.config.js +4 -6
  35. package/build/webpack.vcjwt.config.js +4 -6
  36. package/docs/MODULE_REFERENCE_COMPLETE.md +27 -27
  37. package/docs/advanced/UTXO_MANAGER_GUIDE.md +1 -1
  38. package/docs/getting-started/INSTALLATION.md +23 -23
  39. package/docs/getting-started/QUICK_START.md +7 -7
  40. package/docs/migration/FROM_BSV_1_5_6.md +5 -5
  41. package/index.js +1 -1
  42. package/package.json +29 -19
  43. package/build/webpack.subproject.config.js +0 -6
package/CHANGELOG.md CHANGED
@@ -5,6 +5,77 @@ 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
+ ## [5.1.0] - 2026-06-15
9
+
10
+ Build-tooling modernization. **No source or API changes** — the published
11
+ JavaScript API and all bundle formats/globals are identical to 5.0.1. This is a
12
+ foundational release that unblocks migrating bsv's cryptography to the audited,
13
+ BigInt-based `@noble` suite (webpack 4 cannot parse BigInt; webpack 5 can).
14
+
15
+ ### Changed
16
+
17
+ - **Bundler migrated from webpack 4 to webpack 5** (`webpack` 4.29 → 5.107,
18
+ `webpack-cli` 5). All 13 build configs were ported to a shared
19
+ `build/webpack.base.js`:
20
+ - webpack 5 dropped automatic Node-core polyfills; they are now declared
21
+ explicitly via `resolve.fallback` + `ProvidePlugin` (real
22
+ `crypto-browserify`/`stream`/`buffer` for bundles that embed bsv's crypto so
23
+ Shamir/secrets.js still gets a browser CSPRNG; empty stubs for extern-bsv
24
+ bundles). `Buffer`/`process` globals are preserved everywhere.
25
+ - `ecies`/`message`/`mnemonic`/`shamir` now build from dedicated config files
26
+ (webpack-cli 5 dropped the `-o`/`--output-library` flags the old shared
27
+ `webpack.subproject.config.js` relied on).
28
+ - TerserPlugin is pinned with `extractComments:false` so no `*.LICENSE.txt`
29
+ sidecars are emitted; the published file list is unchanged.
30
+ - Build scripts no longer need `NODE_OPTIONS=--openssl-legacy-provider`.
31
+ - **Browser bundle sizes shifted slightly** from the webpack 5 runtime + the
32
+ now-explicit `process`/`buffer` shims (e.g. `bsv.min.js` 1207KB → 1266KB).
33
+ README size table refreshed accordingly. The dependency tree is leaner
34
+ (`package-lock.json` shrank substantially).
35
+
36
+ ### Notes
37
+
38
+ - Polyfill packages that were transitive under webpack 4 (`crypto-browserify`,
39
+ `stream-browserify`, `buffer`, `process`, `assert`, `util`, `path-browserify`,
40
+ `browserify-zlib`, `vm-browserify`) are now explicit devDependencies, as
41
+ webpack 5 requires.
42
+
43
+ ## [5.0.1] - 2026-06-14
44
+
45
+ Patch release. Documentation corrections for the v5.0.0 release (which were
46
+ committed to `main` after the 5.0.0 npm publish), plus one user-facing message
47
+ fix. No API or behavioral changes; functionally identical to 5.0.0.
48
+
49
+ ### Fixed
50
+
51
+ - **`bsv.SmartUTXO` deprecation warning gave the wrong removal version.** The
52
+ runtime warning said the symbol "will be removed in v5.0.0", but removal was
53
+ deferred to v6.0.0 in 5.0.0 (the adjacent code comment was updated then; the
54
+ warning string was missed). Corrected to v6.0.0. Bundles regenerated.
55
+
56
+ ### Documentation
57
+
58
+ - **README bundle size table** updated to the actual v5.0.0 bundle sizes (the
59
+ full bundles grew because they now ship a real `crypto` polyfill for the
60
+ vetted Shamir engine, e.g. `bsv.min.js` 937KB → 1207KB). (#13)
61
+ - **Install instructions updated for v5.0.0** (#14):
62
+ - bumped a stale `@smartledger/bsv@4.2.1` install command;
63
+ - replaced the v4.x highlights callout with a v5.0.0 breaking-change summary;
64
+ - added an **"Upgrading to v5.0.0 (Breaking Changes)"** section covering the
65
+ Shamir v2 share format (with legacy auto-recovery), JOSE-compliant VC-JWT
66
+ signatures + the `allowLegacyDER` migration flag, algorithm pinning, and the
67
+ larger browser bundles;
68
+ - corrected the bundle-size totals in the Quick Start / CDN examples.
69
+ - **Removed an orphaned `@latest/dist/*` script block** after the "Everything
70
+ Bundle" example — it was malformed markdown pointing at paths that don't exist
71
+ in the published package (bundles ship at the package root, not under
72
+ `dist/`). (#15)
73
+ - **Fixed broken in-page anchor links** (#16): the `Upgrading to v5.0.0` heading
74
+ emoji left a stray variation-selector byte in its GitHub slug, and six
75
+ pre-existing TOC/badge anchors pointed at slugs GitHub never generated; all now
76
+ resolve. Also bumped a stale module-size range (`1184KB` → `1208KB`).
77
+ - CDN/install references in the README and docs bumped `@5.0.0` → `@5.0.1`.
78
+
8
79
  ## [5.0.0] - 2026-06-13
9
80
 
10
81
  ### BREAKING — Shamir Secret Sharing now uses a vetted GF(2⁸) engine
package/README.md CHANGED
@@ -5,8 +5,8 @@
5
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
- [![Modular](https://img.shields.io/badge/Loading-Modular-purple.svg)](#loading-options)
9
- [![W3C](https://img.shields.io/badge/W3C-Compliant-blueviolet.svg)](#verifiable-credentials)
8
+ [![Modular](https://img.shields.io/badge/Loading-Modular-purple.svg)](#-16-loading-options---choose-your-approach)
9
+ [![W3C](https://img.shields.io/badge/W3C-Compliant-blueviolet.svg)](#-legally-recognizable-credentials-v34x)
10
10
 
11
11
  The most comprehensive and flexible Bitcoin SV library available. **In v4.x**:
12
12
  first-class interpreter-verified covenants (OP_PUSH_TX, PELS, ownership tokens),
@@ -71,8 +71,8 @@ const ok = SC.verifyScript(unlockScript, lockingScript, tx, inputIndex, satoshis
71
71
  ### **Quick Start - Issue Your First Verifiable Credential**
72
72
 
73
73
  ```bash
74
- # Install SmartLedger BSV v4.2.1
75
- npm install @smartledger/bsv@4.2.1
74
+ # Install SmartLedger BSV v5.0.0
75
+ npm install @smartledger/bsv@5.1.0
76
76
 
77
77
  # Initialize DID:web issuer (generates ES256 keys)
78
78
  npx smartledger-bsv didweb init --domain example.com --alg ES256
@@ -181,42 +181,42 @@ console.log('Status:', status) // 'revoked'
181
181
  ### **Core Modules**
182
182
  | Module | Size | Use Case | CDN |
183
183
  |--------|------|----------|-----|
184
- | **bsv.min.js** | 937KB | Core BSV + SmartContract | `unpkg.com/@smartledger/bsv@5.0.0/bsv.min.js` |
185
- | **bsv.bundle.js** | 937KB | Everything in one file | `unpkg.com/@smartledger/bsv@5.0.0/bsv.bundle.js` |
184
+ | **bsv.min.js** | 1266KB | Core BSV + SmartContract | `unpkg.com/@smartledger/bsv@5.1.0/bsv.min.js` |
185
+ | **bsv.bundle.js** | 1266KB | Everything in one file | `unpkg.com/@smartledger/bsv@5.1.0/bsv.bundle.js` |
186
186
 
187
187
  ### **W3C Verifiable Credentials**
188
188
  | Module | Size | Use Case | CDN |
189
189
  |--------|------|----------|-----|
190
- | **🟢 bsv-didweb.min.js** | 419KB | **DID:web generation** | `unpkg.com/@smartledger/bsv@5.0.0/bsv-didweb.min.js` |
191
- | **🟢 bsv-vcjwt.min.js** | 419KB | **VC-JWT issue/verify** | `unpkg.com/@smartledger/bsv@5.0.0/bsv-vcjwt.min.js` |
192
- | **🟢 bsv-statuslist.min.js** | 487KB | **StatusList2021 revocation** | `unpkg.com/@smartledger/bsv@5.0.0/bsv-statuslist.min.js` |
193
- | **🟢 bsv-anchor.min.js** | 418KB | **BSV anchoring (hash-only)** | `unpkg.com/@smartledger/bsv@5.0.0/bsv-anchor.min.js` |
190
+ | **🟢 bsv-didweb.min.js** | 453KB | **DID:web generation** | `unpkg.com/@smartledger/bsv@5.1.0/bsv-didweb.min.js` |
191
+ | **🟢 bsv-vcjwt.min.js** | 454KB | **VC-JWT issue/verify** | `unpkg.com/@smartledger/bsv@5.1.0/bsv-vcjwt.min.js` |
192
+ | **🟢 bsv-statuslist.min.js** | 553KB | **StatusList2021 revocation** | `unpkg.com/@smartledger/bsv@5.1.0/bsv-statuslist.min.js` |
193
+ | **🟢 bsv-anchor.min.js** | 452KB | **BSV anchoring (hash-only)** | `unpkg.com/@smartledger/bsv@5.1.0/bsv-anchor.min.js` |
194
194
 
195
195
  ### **Smart Contract & Development**
196
196
  | Module | Size | Use Case | CDN |
197
197
  |--------|------|----------|-----|
198
- | **bsv-smartcontract.min.js** | 937KB | Complete covenant framework | `unpkg.com/@smartledger/bsv@5.0.0/bsv-smartcontract.min.js` |
199
- | **bsv-covenant.min.js** | 913KB | Covenant operations | `unpkg.com/@smartledger/bsv@5.0.0/bsv-covenant.min.js` |
200
- | **bsv-script-helper.min.js** | 26KB | Custom script tools | `unpkg.com/@smartledger/bsv@5.0.0/bsv-script-helper.min.js` |
201
- | **bsv-security.min.js** | 26KB | Security enhancements | `unpkg.com/@smartledger/bsv@5.0.0/bsv-security.min.js` |
198
+ | **bsv-smartcontract.min.js** | 939KB | Complete covenant framework | `unpkg.com/@smartledger/bsv@5.1.0/bsv-smartcontract.min.js` |
199
+ | **bsv-covenant.min.js** | 939KB | Covenant operations | `unpkg.com/@smartledger/bsv@5.1.0/bsv-covenant.min.js` |
200
+ | **bsv-script-helper.min.js** | 30KB | Custom script tools | `unpkg.com/@smartledger/bsv@5.1.0/bsv-script-helper.min.js` |
201
+ | **bsv-security.min.js** | 30KB | Security enhancements | `unpkg.com/@smartledger/bsv@5.1.0/bsv-security.min.js` |
202
202
 
203
203
  ### **Legal & Compliance**
204
204
  | Module | Size | Use Case | CDN |
205
205
  |--------|------|----------|-----|
206
- | **bsv-ltp.min.js** | 1184KB | Legal Token Protocol | `unpkg.com/@smartledger/bsv@5.0.0/bsv-ltp.min.js` |
207
- | **bsv-gdaf.min.js** | 1184KB | Digital Identity & Attestation | `unpkg.com/@smartledger/bsv@5.0.0/bsv-gdaf.min.js` |
206
+ | **bsv-ltp.min.js** | 1266KB | Legal Token Protocol | `unpkg.com/@smartledger/bsv@5.1.0/bsv-ltp.min.js` |
207
+ | **bsv-gdaf.min.js** | 1266KB | Digital Identity & Attestation | `unpkg.com/@smartledger/bsv@5.1.0/bsv-gdaf.min.js` |
208
208
 
209
209
  ### **Advanced Cryptography**
210
210
  | Module | Size | Use Case | CDN |
211
211
  |--------|------|----------|-----|
212
- | **bsv-shamir.min.js** | 432KB | Threshold Cryptography | `unpkg.com/@smartledger/bsv@5.0.0/bsv-shamir.min.js` |
212
+ | **bsv-shamir.min.js** | 476KB | Threshold Cryptography | `unpkg.com/@smartledger/bsv@5.1.0/bsv-shamir.min.js` |
213
213
 
214
214
  ### **Utilities**
215
215
  | Module | Size | Use Case | CDN |
216
216
  |--------|------|----------|-----|
217
- | **bsv-ecies.min.js** | 71KB | Encryption | `unpkg.com/@smartledger/bsv@5.0.0/bsv-ecies.min.js` |
218
- | **bsv-message.min.js** | 26KB | Message signing | `unpkg.com/@smartledger/bsv@5.0.0/bsv-message.min.js` |
219
- | **bsv-mnemonic.min.js** | 681KB | HD wallets | `unpkg.com/@smartledger/bsv@5.0.0/bsv-mnemonic.min.js` |
217
+ | **bsv-ecies.min.js** | 76KB | Encryption | `unpkg.com/@smartledger/bsv@5.1.0/bsv-ecies.min.js` |
218
+ | **bsv-message.min.js** | 30KB | Message signing | `unpkg.com/@smartledger/bsv@5.1.0/bsv-message.min.js` |
219
+ | **bsv-mnemonic.min.js** | 715KB | HD wallets | `unpkg.com/@smartledger/bsv@5.1.0/bsv-mnemonic.min.js` |
220
220
 
221
221
  ## ⚡ **2-Minute Quick Start**
222
222
 
@@ -227,13 +227,15 @@ Get started with Bitcoin SV development in under 2 minutes:
227
227
  npm install @smartledger/bsv
228
228
 
229
229
  # Or include in HTML
230
- <script src="https://unpkg.com/@smartledger/bsv@5.0.0/bsv.min.js"></script>
230
+ <script src="https://unpkg.com/@smartledger/bsv@5.1.0/bsv.min.js"></script>
231
231
  ```
232
232
 
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.
233
+ > **🔒 v5.0.0 (production hardening — has breaking changes):** Shamir secret
234
+ > sharing now runs on a vetted GF(2⁸) engine with authenticated shares; VC-JWT
235
+ > signatures are now JOSE-compliant (IEEE P1363); VC-JWT verification pins the
236
+ > algorithm; ECDSA low-S preserves `recoveryParam`; ECIES MAC check is
237
+ > constant-time. **If you are upgrading from 4.x, read [Upgrading to v5.0.0](#upgrading-to-v500-breaking-changes) below.** Builds on the v4.x covenant,
238
+ > DID:web + VC-JWT, StatusList2021, and BSV-anchoring toolkit. See CHANGELOG.
237
239
 
238
240
  **Basic Transaction (30 seconds):**
239
241
  ```javascript
@@ -323,21 +325,21 @@ const covenant = bsv.SmartContract.createCovenantBuilder()
323
325
 
324
326
  ## 📚 **Quick Start Examples**
325
327
 
326
- ### 🔧 **Basic Development** (~963KB total)
328
+ ### 🔧 **Basic Development** (~1.3MB total)
327
329
  ```html
328
- <script src="https://unpkg.com/@smartledger/bsv@5.0.0/bsv.min.js"></script>
329
- <script src="https://unpkg.com/@smartledger/bsv@5.0.0/bsv-script-helper.min.js"></script>
330
+ <script src="https://unpkg.com/@smartledger/bsv@5.1.0/bsv.min.js"></script>
331
+ <script src="https://unpkg.com/@smartledger/bsv@5.1.0/bsv-script-helper.min.js"></script>
330
332
  <script>
331
333
  const privateKey = new bsv.PrivateKey();
332
334
  const utxos = new bsv.SmartContract.UTXOGenerator().createRealUTXOs(2, 100000);
333
335
  </script>
334
336
  ```
335
337
 
336
- ### 🔒 **Smart Contract Development** (~2.7MB total — each bundle re-embeds core BSV)
338
+ ### 🔒 **Smart Contract Development** (~3.1MB total — each bundle re-embeds core BSV)
337
339
  ```html
338
- <script src="https://unpkg.com/@smartledger/bsv@5.0.0/bsv.min.js"></script>
339
- <script src="https://unpkg.com/@smartledger/bsv@5.0.0/bsv-covenant.min.js"></script>
340
- <script src="https://unpkg.com/@smartledger/bsv@5.0.0/bsv-smartcontract.min.js"></script>
340
+ <script src="https://unpkg.com/@smartledger/bsv@5.1.0/bsv.min.js"></script>
341
+ <script src="https://unpkg.com/@smartledger/bsv@5.1.0/bsv-covenant.min.js"></script>
342
+ <script src="https://unpkg.com/@smartledger/bsv@5.1.0/bsv-smartcontract.min.js"></script>
341
343
  <script>
342
344
  const covenant = bsv.SmartContract.createCovenantBuilder()
343
345
  .extractField('amount').push(50000).greaterThanOrEqual().verify().build();
@@ -345,11 +347,11 @@ const covenant = bsv.SmartContract.createCovenantBuilder()
345
347
  </script>
346
348
  ```
347
349
 
348
- ### 🆕 **Legal & Identity Development** (~3.2MB total — each bundle re-embeds core BSV)
350
+ ### 🆕 **Legal & Identity Development** (~3.7MB total — each bundle re-embeds core BSV)
349
351
  ```html
350
- <script src="https://unpkg.com/@smartledger/bsv@5.0.0/bsv.min.js"></script>
351
- <script src="https://unpkg.com/@smartledger/bsv@5.0.0/bsv-ltp.min.js"></script>
352
- <script src="https://unpkg.com/@smartledger/bsv@5.0.0/bsv-gdaf.min.js"></script>
352
+ <script src="https://unpkg.com/@smartledger/bsv@5.1.0/bsv.min.js"></script>
353
+ <script src="https://unpkg.com/@smartledger/bsv@5.1.0/bsv-ltp.min.js"></script>
354
+ <script src="https://unpkg.com/@smartledger/bsv@5.1.0/bsv-gdaf.min.js"></script>
353
355
  <script>
354
356
  // Legal Token Protocol
355
357
  const propertyToken = bsv.createPropertyToken({
@@ -361,11 +363,11 @@ const covenant = bsv.SmartContract.createCovenantBuilder()
361
363
  </script>
362
364
  ```
363
365
 
364
- ### 🆕 **Security & Cryptography** (~1.4MB total)
366
+ ### 🆕 **Security & Cryptography** (~1.7MB total)
365
367
  ```html
366
- <script src="https://unpkg.com/@smartledger/bsv@5.0.0/bsv.min.js"></script>
367
- <script src="https://unpkg.com/@smartledger/bsv@5.0.0/bsv-security.min.js"></script>
368
- <script src="https://unpkg.com/@smartledger/bsv@5.0.0/bsv-shamir.min.js"></script>
368
+ <script src="https://unpkg.com/@smartledger/bsv@5.1.0/bsv.min.js"></script>
369
+ <script src="https://unpkg.com/@smartledger/bsv@5.1.0/bsv-security.min.js"></script>
370
+ <script src="https://unpkg.com/@smartledger/bsv@5.1.0/bsv-shamir.min.js"></script>
369
371
  <script>
370
372
  // Threshold Cryptography
371
373
  const shares = bsv.splitSecret('my_secret_key', 5, 3); // 5 shares, 3 needed
@@ -375,9 +377,9 @@ const covenant = bsv.SmartContract.createCovenantBuilder()
375
377
  </script>
376
378
  ```
377
379
 
378
- ### 🎯 **Everything Bundle** (937KB)
380
+ ### 🎯 **Everything Bundle** (~1.3MB)
379
381
  ```html
380
- <script src="https://unpkg.com/@smartledger/bsv@5.0.0/bsv.bundle.js"></script>
382
+ <script src="https://unpkg.com/@smartledger/bsv@5.1.0/bsv.bundle.js"></script>
381
383
  <script>
382
384
  // Everything available immediately
383
385
  const shares = bsv.splitSecret('secret', 5, 3); // Shamir Secret Sharing
@@ -396,9 +398,9 @@ const covenant = bsv.SmartContract.createCovenantBuilder()
396
398
  - ✅ **Complete Smart Contract Suite**: 23+ production-ready covenant features → [SmartContract Guide](docs/SMART_CONTRACT_GUIDE.md)
397
399
 
398
400
  ### 💼 **Core Library Excellence**
399
- - ✅ **Complete BSV API**: Full Bitcoin SV blockchain operations → [API Reference](#api-reference)
401
+ - ✅ **Complete BSV API**: Full Bitcoin SV blockchain operations → [API Reference](#-api-reference)
400
402
  - ✅ **Opt-in security helpers**: `bsv.SmartVerify` and `bsv.EllipticFixed` add input validation and low-`s` canonicalization on top of standard verification — **not on the default verify path**, see [Security](#-security)
401
- - ✅ **Browser + Node.js**: Universal compatibility with proper polyfills → [Loading Options](#12-loading-options--choose-your-approach)
403
+ - ✅ **Browser + Node.js**: Universal compatibility with proper polyfills → [Loading Options](#-16-loading-options---choose-your-approach)
402
404
  - ✅ **TypeScript Ready**: Complete type definitions included
403
405
  - ✅ **Ultra-Low Fees**: 0.01 sats/byte configuration (91% fee reduction)
404
406
 
@@ -410,7 +412,7 @@ const covenant = bsv.SmartContract.createCovenantBuilder()
410
412
  - � **PUSHTX Integration**: nChain techniques for advanced covenant patterns → [PUSHTX Insights](docs/pushtx-key-insights.md)
411
413
 
412
414
  ### 📦 **Flexible Architecture**
413
- - 📦 **16 Modular Options**: Load only what you need (26KB to 1184KB) → [Loading Strategy](#loading-strategy-examples)
415
+ - 📦 **16 Modular Options**: Load only what you need (30KB to 1266KB) → [Loading Strategy](#-16-loading-options---choose-your-approach)
414
416
  - 📦 **Standalone Modules**: Independent legal, identity, and crypto modules → [Standalone Test](https://github.com/codenlighten/smartledger-bsv/blob/main/tests/standalone-modules-test.html)
415
417
  - 📦 **Complete Bundle**: Everything in one file for convenience → [Bundle Demo](https://github.com/codenlighten/smartledger-bsv/blob/main/tests/bundle-demo.html)
416
418
  - 📦 **CDN Ready**: All modules available via unpkg and jsDelivr
@@ -418,7 +420,7 @@ const covenant = bsv.SmartContract.createCovenantBuilder()
418
420
 
419
421
  ## ⚡ **Installation & Usage**
420
422
 
421
- > 💡 **Quick Start**: Jump to [2-Minute Quick Start](#2-minute-quick-start) for instant setup examples
423
+ > 💡 **Quick Start**: Jump to [2-Minute Quick Start](#-2-minute-quick-start) for instant setup examples
422
424
 
423
425
  ### NPM Installation
424
426
  ```bash
@@ -429,7 +431,36 @@ npm install @smartledger/bsv
429
431
  npm install smartledger-bsv
430
432
  ```
431
433
 
432
- > 📖 **Next Steps**: After installation, see [Loading Options](#9-loading-options--choose-your-approach) to choose your distribution method
434
+ > 📖 **Next Steps**: After installation, see [Loading Options](#-16-loading-options---choose-your-approach) to choose your distribution method
435
+
436
+ ### Upgrading to v5.0.0 (Breaking Changes)
437
+
438
+ v5.0.0 hardens the cryptography. Most apps need **no code changes** — the
439
+ breaking changes only affect data produced by older versions:
440
+
441
+ - **Shamir shares.** `Shamir.split()` now returns the **v2 share format**
442
+ (backed by a vetted GF(2⁸) engine). Shares created with ≤ 4.x still
443
+ reconstruct — `Shamir.combine()` and `Shamir.verifyShare()` auto-detect and
444
+ accept legacy shares for recovery. No flag needed.
445
+ - **VC-JWT signatures.** Tokens are now signed and verified as JOSE-standard
446
+ **IEEE P1363** (`r||s`) instead of DER, so they interoperate with `jose`,
447
+ `jsonwebtoken`, etc. Tokens **issued by ≤ 4.6.0 are DER-encoded** and will
448
+ fail verification by default — pass `{ allowLegacyDER: true }` while you
449
+ re-issue:
450
+ ```javascript
451
+ const result = await bsv.VcJwt.verifyVcJwt(oldToken, {
452
+ didResolver,
453
+ allowLegacyDER: true // accept ≤ 4.6.0 DER-signed tokens during migration
454
+ });
455
+ ```
456
+ - **VC-JWT algorithm pinning.** `verifyVcJwt` rejects any token whose `alg` is
457
+ outside `['ES256','ES256K']` (override via `opts.allowedAlgs`) and binds the
458
+ key's curve to the algorithm — defense against alg-substitution attacks.
459
+ - **Browser bundles are larger.** The full bundles now ship a real `crypto`
460
+ polyfill so Shamir can source a CSPRNG (`bsv.min.js` ~937KB → ~1.3MB). The
461
+ dedicated single-feature module bundles are unaffected.
462
+
463
+ Full details in the [CHANGELOG](./CHANGELOG.md#500---2026-06-13).
433
464
 
434
465
  ### Node.js Usage
435
466
  ```javascript
@@ -455,21 +486,21 @@ const contractTx = covenant.createCovenantTransaction({
455
486
 
456
487
  ### Browser CDN (Choose Your Loading Strategy)
457
488
 
458
- #### 1. **Minimal Setup** - Core + Script Helper (~963KB)
489
+ #### 1. **Minimal Setup** - Core + Script Helper (~1.3MB)
459
490
  ```html
460
- <script src="https://unpkg.com/@smartledger/bsv@5.0.0/bsv.min.js"></script>
461
- <script src="https://unpkg.com/@smartledger/bsv@5.0.0/bsv-script-helper.min.js"></script>
491
+ <script src="https://unpkg.com/@smartledger/bsv@5.1.0/bsv.min.js"></script>
492
+ <script src="https://unpkg.com/@smartledger/bsv@5.1.0/bsv-script-helper.min.js"></script>
462
493
  <script>
463
494
  const tx = new bsv.Transaction();
464
495
  const sig = bsvScriptHelper.createSignature(tx, privateKey, 0, script, satoshis);
465
496
  </script>
466
497
  ```
467
498
 
468
- #### 2. **DeFi Development** - Core + Covenants + Debug (~2.7MB — each bundle re-embeds core BSV)
499
+ #### 2. **DeFi Development** - Core + Covenants + Debug (~3.1MB — each bundle re-embeds core BSV)
469
500
  ```html
470
- <script src="https://unpkg.com/@smartledger/bsv@5.0.0/bsv.min.js"></script>
471
- <script src="https://unpkg.com/@smartledger/bsv@5.0.0/bsv-covenant.min.js"></script>
472
- <script src="https://unpkg.com/@smartledger/bsv@5.0.0/bsv-smartcontract.min.js"></script>
501
+ <script src="https://unpkg.com/@smartledger/bsv@5.1.0/bsv.min.js"></script>
502
+ <script src="https://unpkg.com/@smartledger/bsv@5.1.0/bsv-covenant.min.js"></script>
503
+ <script src="https://unpkg.com/@smartledger/bsv@5.1.0/bsv-smartcontract.min.js"></script>
473
504
  <script>
474
505
  const covenant = new bsvCovenant.CovenantInterface();
475
506
  const debugInfo = SmartContract.interpretScript(script);
@@ -477,19 +508,19 @@ const contractTx = covenant.createCovenantTransaction({
477
508
  </script>
478
509
  ```
479
510
 
480
- #### 3. **Security First** - Core + Enhanced Security (~963KB)
511
+ #### 3. **Security First** - Core + Enhanced Security (~1.3MB)
481
512
  ```html
482
- <script src="https://unpkg.com/@smartledger/bsv@5.0.0/bsv.min.js"></script>
483
- <script src="https://unpkg.com/@smartledger/bsv@5.0.0/bsv-security.min.js"></script>
513
+ <script src="https://unpkg.com/@smartledger/bsv@5.1.0/bsv.min.js"></script>
514
+ <script src="https://unpkg.com/@smartledger/bsv@5.1.0/bsv-security.min.js"></script>
484
515
  <script>
485
516
  const verified = bsvSecurity.SmartVerify.verify(signature, hash, publicKey);
486
517
  const enhanced = bsvSecurity.EllipticFixed.createSignature(privateKey, hash);
487
518
  </script>
488
519
  ```
489
520
 
490
- #### 4. **Everything Bundle** - One File Solution (937KB)
521
+ #### 4. **Everything Bundle** - One File Solution (~1.3MB)
491
522
  ```html
492
- <script src="https://unpkg.com/@smartledger/bsv@5.0.0/bsv.bundle.js"></script>
523
+ <script src="https://unpkg.com/@smartledger/bsv@5.1.0/bsv.bundle.js"></script>
493
524
  <script>
494
525
  // Everything available under bsv namespace
495
526
  const keys = bsv.SmartLedgerBundle.generateKeys();
@@ -498,17 +529,6 @@ const contractTx = covenant.createCovenantTransaction({
498
529
  const encrypted = bsv.ECIES.encrypt('secret', publicKey);
499
530
  </script>
500
531
  ```
501
- <!-- Main library -->
502
- <script src="https://unpkg.com/@smartledger/bsv@latest/dist/bsv.bundle.js"></script>
503
-
504
- <!-- Minified version -->
505
- <script src="https://unpkg.com/@smartledger/bsv@latest/dist/bsv.min.js"></script>
506
-
507
- <!-- Specialized modules -->
508
- <script src="https://unpkg.com/@smartledger/bsv@latest/dist/bsv-ecies.min.js"></script>
509
- <script src="https://unpkg.com/@smartledger/bsv@latest/dist/bsv-message.min.js"></script>
510
- <script src="https://unpkg.com/@smartledger/bsv@latest/dist/bsv-mnemonic.min.js"></script>
511
- ```
512
532
 
513
533
  ## 🔨 Basic Usage
514
534
 
@@ -789,7 +809,7 @@ const timelockScript = helper.createTimelockScript(
789
809
 
790
810
  See the **[16 Loading Options](#-16-loading-options---choose-your-approach)**
791
811
  table near the top for the full list of bundles with current sizes and
792
- canonical `unpkg.com/@smartledger/bsv@5.0.0/...` URLs.
812
+ canonical `unpkg.com/@smartledger/bsv@5.1.0/...` URLs.
793
813
 
794
814
  ## 🔐 Security
795
815