@smartledger/bsv 4.6.0 → 5.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 (26) hide show
  1. package/CHANGELOG.md +111 -0
  2. package/README.md +91 -71
  3. package/bsv-covenant.min.js +8 -5
  4. package/bsv-ecies.min.js +1 -1
  5. package/bsv-gdaf.min.js +9 -6
  6. package/bsv-ltp.min.js +9 -6
  7. package/bsv-shamir.min.js +5 -2
  8. package/bsv-smartcontract.min.js +9 -6
  9. package/bsv-statuslist.min.js +1 -1
  10. package/bsv-vcjwt.min.js +3 -3
  11. package/bsv.bundle.js +13 -10
  12. package/bsv.min.js +13 -10
  13. package/build/webpack.bundle.config.js +3 -2
  14. package/build/webpack.config.js +3 -1
  15. package/build/webpack.security.config.js +2 -1
  16. package/docs/MODULE_REFERENCE_COMPLETE.md +27 -27
  17. package/docs/advanced/UTXO_MANAGER_GUIDE.md +1 -1
  18. package/docs/getting-started/INSTALLATION.md +23 -23
  19. package/docs/getting-started/QUICK_START.md +7 -7
  20. package/docs/migration/FROM_BSV_1_5_6.md +5 -5
  21. package/index.js +2 -2
  22. package/lib/crypto/elliptic-fixed.js +30 -37
  23. package/lib/crypto/shamir.js +239 -238
  24. package/lib/ecies/bitcore-ecies.js +16 -5
  25. package/lib/vcjwt/index.js +83 -22
  26. package/package.json +3 -9
package/CHANGELOG.md CHANGED
@@ -5,6 +5,117 @@ 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.0.1] - 2026-06-14
9
+
10
+ Patch release. Documentation corrections for the v5.0.0 release (which were
11
+ committed to `main` after the 5.0.0 npm publish), plus one user-facing message
12
+ fix. No API or behavioral changes; functionally identical to 5.0.0.
13
+
14
+ ### Fixed
15
+
16
+ - **`bsv.SmartUTXO` deprecation warning gave the wrong removal version.** The
17
+ runtime warning said the symbol "will be removed in v5.0.0", but removal was
18
+ deferred to v6.0.0 in 5.0.0 (the adjacent code comment was updated then; the
19
+ warning string was missed). Corrected to v6.0.0. Bundles regenerated.
20
+
21
+ ### Documentation
22
+
23
+ - **README bundle size table** updated to the actual v5.0.0 bundle sizes (the
24
+ full bundles grew because they now ship a real `crypto` polyfill for the
25
+ vetted Shamir engine, e.g. `bsv.min.js` 937KB → 1207KB). (#13)
26
+ - **Install instructions updated for v5.0.0** (#14):
27
+ - bumped a stale `@smartledger/bsv@4.2.1` install command;
28
+ - replaced the v4.x highlights callout with a v5.0.0 breaking-change summary;
29
+ - added an **"Upgrading to v5.0.0 (Breaking Changes)"** section covering the
30
+ Shamir v2 share format (with legacy auto-recovery), JOSE-compliant VC-JWT
31
+ signatures + the `allowLegacyDER` migration flag, algorithm pinning, and the
32
+ larger browser bundles;
33
+ - corrected the bundle-size totals in the Quick Start / CDN examples.
34
+ - **Removed an orphaned `@latest/dist/*` script block** after the "Everything
35
+ Bundle" example — it was malformed markdown pointing at paths that don't exist
36
+ in the published package (bundles ship at the package root, not under
37
+ `dist/`). (#15)
38
+ - **Fixed broken in-page anchor links** (#16): the `Upgrading to v5.0.0` heading
39
+ emoji left a stray variation-selector byte in its GitHub slug, and six
40
+ pre-existing TOC/badge anchors pointed at slugs GitHub never generated; all now
41
+ resolve. Also bumped a stale module-size range (`1184KB` → `1208KB`).
42
+ - CDN/install references in the README and docs bumped `@5.0.0` → `@5.0.1`.
43
+
44
+ ## [5.0.0] - 2026-06-13
45
+
46
+ ### BREAKING — Shamir Secret Sharing now uses a vetted GF(2⁸) engine
47
+
48
+ `crypto.Shamir` previously used a hand-rolled finite-field implementation over a
49
+ 31-bit prime, with no authentication of shares. It is now backed by
50
+ `secrets.js-grempe` (a vetted GF(2⁸) implementation), with two safety additions:
51
+ a per-split nonce (`splitId`) so shares from different splits can't be silently
52
+ mixed, and an integrity `checksum` so a tampered/mismatched share set is rejected
53
+ at combine time instead of returning garbage.
54
+
55
+ - **New share format (v2).** `split()` returns objects shaped
56
+ `{ v, id, threshold, shares, length, splitId, share, checksum }` instead of the
57
+ old `{ id, threshold, shares, length, bytes:[{x,y}] }`.
58
+ - **Old shares remain recoverable.** `combine()` and `verifyShare()` detect and
59
+ accept legacy (≤ 4.x) shares for recovery; you do not need the old version to
60
+ reconstruct previously-split secrets.
61
+ - Randomness is sourced from the library's own `crypto.Random` (Node CSPRNG /
62
+ `window.crypto`) via `secrets.setRNG`, and `secrets` is loaded lazily so simply
63
+ importing the library never triggers its init.
64
+ - New coverage in `test/crypto/shamir.js` (round-trips, threshold subsets,
65
+ leading-zero/Buffer secrets, tamper detection, split isolation, legacy
66
+ recovery).
67
+
68
+ Browser bundles that bundle the full library no longer mock node `crypto` as
69
+ empty (`bsv.min.js`, `bsv.bundle.js`, `bsv-security.min.js`); webpack's default
70
+ `crypto` polyfill is used so Shamir can obtain a CSPRNG. This increases the size
71
+ of the full bundles (e.g. `bsv.min.js` ~951 KB → ~1.2 MB); the dedicated
72
+ non-Shamir module bundles are unaffected.
73
+
74
+ ### BREAKING — VC-JWT signatures are now JOSE-compliant (IEEE P1363)
75
+
76
+ Up to and including 4.6.0, `VcJwt.issueVcJwt` signed with Node's default
77
+ ECDSA output, which is **DER-encoded**. The JOSE specs (RFC 7515/7518, and
78
+ RFC 8812 for ES256K) require ECDSA JWS signatures to be the raw `r||s`
79
+ concatenation (**IEEE P1363**). As a result, tokens issued by older versions
80
+ **did not verify in any standards-compliant library** (`jose`, `jsonwebtoken`,
81
+ etc.), and this library could not verify standard tokens from other issuers.
82
+ This also affected `StatusList`, which issues its lists via `VcJwt`.
83
+
84
+ - **`VcJwt.issueVcJwt`** now emits P1363 signatures and is verifiable by `jose`.
85
+ - **`VcJwt.verifyVcJwt`** now decodes P1363 signatures.
86
+ - **Migration:** tokens issued by ≤ 4.6.0 carry DER signatures and will fail
87
+ verification by default. Pass `{ allowLegacyDER: true }` to `verifyVcJwt` to
88
+ accept them while you re-issue. New tokens require no flag.
89
+ - Round-trip interoperability with `jose` (both directions, ES256 + ES256K) is
90
+ now covered by `test/vcjwt/interop.js`.
91
+
92
+ ### Security
93
+
94
+ - **VC-JWT algorithm pinning.** `verifyVcJwt` now rejects any token whose
95
+ `alg` is not in the allowed set (default `['ES256','ES256K']`, overridable via
96
+ `opts.allowedAlgs`) **before** verifying — closing the classic JWT algorithm
97
+ substitution hole. It also binds the resolved key's curve to the algorithm
98
+ (an ES256K signature can no longer be checked against a P-256 key), and
99
+ `issueVcJwt` refuses to sign when the key curve and `alg` disagree.
100
+ - **`crypto/elliptic-fixed` low-S now preserves `recoveryParam`.** The previous
101
+ manual `s → n-s` flip did not update the recovery id, so public-key recovery
102
+ returned the wrong key for ~50% of signatures. Canonicalization now uses
103
+ elliptic's own `{ canonical: true }`, which keeps `recoveryParam` consistent.
104
+ - **ECIES MAC check is now constant-time** (portable comparison; no early-out
105
+ on the first differing byte).
106
+
107
+ ### Fixed
108
+
109
+ - **Removed the self-referential dependency.** `package.json` listed
110
+ `@smartledger/bsv` as one of its own `dependencies`, causing npm to install a
111
+ nested older copy of the package and triggering the "More than one instance of
112
+ bsv" guard. Removed.
113
+
114
+ ### Changed
115
+
116
+ - Deduplicated `package.json` keywords (86 → 79).
117
+ - `bsv.SmartUTXO` removal pushed from v5.0.0 to v6.0.0 (still soft-deprecated).
118
+
8
119
  ## [4.6.0] - 2026-06-09
9
120
 
10
121
  ### Fixed — covenants are now mainnet-relayable (MINIMALDATA)
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.0.1
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@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` |
184
+ | **bsv.min.js** | 1207KB | Core BSV + SmartContract | `unpkg.com/@smartledger/bsv@5.0.1/bsv.min.js` |
185
+ | **bsv.bundle.js** | 1207KB | Everything in one file | `unpkg.com/@smartledger/bsv@5.0.1/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@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` |
190
+ | **🟢 bsv-didweb.min.js** | 419KB | **DID:web generation** | `unpkg.com/@smartledger/bsv@5.0.1/bsv-didweb.min.js` |
191
+ | **🟢 bsv-vcjwt.min.js** | 420KB | **VC-JWT issue/verify** | `unpkg.com/@smartledger/bsv@5.0.1/bsv-vcjwt.min.js` |
192
+ | **🟢 bsv-statuslist.min.js** | 487KB | **StatusList2021 revocation** | `unpkg.com/@smartledger/bsv@5.0.1/bsv-statuslist.min.js` |
193
+ | **🟢 bsv-anchor.min.js** | 418KB | **BSV anchoring (hash-only)** | `unpkg.com/@smartledger/bsv@5.0.1/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@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` |
198
+ | **bsv-smartcontract.min.js** | 961KB | Complete covenant framework | `unpkg.com/@smartledger/bsv@5.0.1/bsv-smartcontract.min.js` |
199
+ | **bsv-covenant.min.js** | 937KB | Covenant operations | `unpkg.com/@smartledger/bsv@5.0.1/bsv-covenant.min.js` |
200
+ | **bsv-script-helper.min.js** | 26KB | Custom script tools | `unpkg.com/@smartledger/bsv@5.0.1/bsv-script-helper.min.js` |
201
+ | **bsv-security.min.js** | 26KB | Security enhancements | `unpkg.com/@smartledger/bsv@5.0.1/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@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` |
206
+ | **bsv-ltp.min.js** | 1208KB | Legal Token Protocol | `unpkg.com/@smartledger/bsv@5.0.1/bsv-ltp.min.js` |
207
+ | **bsv-gdaf.min.js** | 1208KB | Digital Identity & Attestation | `unpkg.com/@smartledger/bsv@5.0.1/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@4.2.1/bsv-shamir.min.js` |
212
+ | **bsv-shamir.min.js** | 442KB | Threshold Cryptography | `unpkg.com/@smartledger/bsv@5.0.1/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@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` |
217
+ | **bsv-ecies.min.js** | 72KB | Encryption | `unpkg.com/@smartledger/bsv@5.0.1/bsv-ecies.min.js` |
218
+ | **bsv-message.min.js** | 26KB | Message signing | `unpkg.com/@smartledger/bsv@5.0.1/bsv-message.min.js` |
219
+ | **bsv-mnemonic.min.js** | 681KB | HD wallets | `unpkg.com/@smartledger/bsv@5.0.1/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@4.2.1/bsv.min.js"></script>
230
+ <script src="https://unpkg.com/@smartledger/bsv@5.0.1/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.2MB total)
327
329
  ```html
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>
330
+ <script src="https://unpkg.com/@smartledger/bsv@5.0.1/bsv.min.js"></script>
331
+ <script src="https://unpkg.com/@smartledger/bsv@5.0.1/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.0MB total — each bundle re-embeds core BSV)
337
339
  ```html
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>
340
+ <script src="https://unpkg.com/@smartledger/bsv@5.0.1/bsv.min.js"></script>
341
+ <script src="https://unpkg.com/@smartledger/bsv@5.0.1/bsv-covenant.min.js"></script>
342
+ <script src="https://unpkg.com/@smartledger/bsv@5.0.1/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.5MB total — each bundle re-embeds core BSV)
349
351
  ```html
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>
352
+ <script src="https://unpkg.com/@smartledger/bsv@5.0.1/bsv.min.js"></script>
353
+ <script src="https://unpkg.com/@smartledger/bsv@5.0.1/bsv-ltp.min.js"></script>
354
+ <script src="https://unpkg.com/@smartledger/bsv@5.0.1/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.6MB total)
365
367
  ```html
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>
368
+ <script src="https://unpkg.com/@smartledger/bsv@5.0.1/bsv.min.js"></script>
369
+ <script src="https://unpkg.com/@smartledger/bsv@5.0.1/bsv-security.min.js"></script>
370
+ <script src="https://unpkg.com/@smartledger/bsv@5.0.1/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.2MB)
379
381
  ```html
380
- <script src="https://unpkg.com/@smartledger/bsv@4.2.1/bsv.bundle.js"></script>
382
+ <script src="https://unpkg.com/@smartledger/bsv@5.0.1/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 (26KB to 1208KB) → [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.2MB). 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.2MB)
459
490
  ```html
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>
491
+ <script src="https://unpkg.com/@smartledger/bsv@5.0.1/bsv.min.js"></script>
492
+ <script src="https://unpkg.com/@smartledger/bsv@5.0.1/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.0MB — each bundle re-embeds core BSV)
469
500
  ```html
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>
501
+ <script src="https://unpkg.com/@smartledger/bsv@5.0.1/bsv.min.js"></script>
502
+ <script src="https://unpkg.com/@smartledger/bsv@5.0.1/bsv-covenant.min.js"></script>
503
+ <script src="https://unpkg.com/@smartledger/bsv@5.0.1/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.2MB)
481
512
  ```html
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>
513
+ <script src="https://unpkg.com/@smartledger/bsv@5.0.1/bsv.min.js"></script>
514
+ <script src="https://unpkg.com/@smartledger/bsv@5.0.1/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.2MB)
491
522
  ```html
492
- <script src="https://unpkg.com/@smartledger/bsv@4.2.1/bsv.bundle.js"></script>
523
+ <script src="https://unpkg.com/@smartledger/bsv@5.0.1/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@4.2.1/...` URLs.
812
+ canonical `unpkg.com/@smartledger/bsv@5.0.1/...` URLs.
793
813
 
794
814
  ## 🔐 Security
795
815