@smartledger/bsv 7.5.4 → 7.5.6

package/docs/BN_JS_V5_REVIEW.md

@@ -0,0 +1,94 @@
+# `bn.js` 4 → 5: semantic review
+
+**Date:** 2026-08-07 · **Versions compared:** 4.12.3 (pinned) vs 5.2.5 · **Verdict: do not upgrade yet — correctness is fine, bundle size is not.**
+
+`bn.js` is the arithmetic layer beneath ECDSA, script numbers, transaction amounts and
+HD derivation, so "the test suite passes" is not sufficient evidence for a major bump.
+This is the review that was required instead.
+
+## Method
+
+Two independent lines of evidence, both run against the **real** `lib/crypto/bn.js`
+wrapper and the consensus paths built on it — not against `bn.js` in isolation.
+
+1. **Targeted differential harness** — 16 hand-picked values (zero, ±1, `n`, `n-1`,
+   2⁵³, 2⁶⁴, high-bit-set, leading-zero-byte, negatives) crossed through every wrapper
+   and arithmetic operation the library uses: `toString(10)`, `toString(16)`,
+   `toString(16, 2)`, `toBuffer`, `toBuffer({size:32})`, little-endian variants,
+   `toSM`/`fromSM`, `toScriptNumBuffer`/`fromScriptNumBuffer`, `add`, `sub`, `mul`,
+   `div`, `mod`, `umod`, `cmp`, `neg`, `abs`, `shrn`, `ushrn`, `ushln`, `invm`, `gcd`,
+   `pow`, `byteLength`, `bitLength`, plus ECDSA signing, WIF, addresses, public keys
+   and HD derivation. **2,271 checks.**
+
+2. **Randomised differential fuzz** — a deterministic sha256-chained PRNG (identical
+   inputs on both runs) over 400 rounds of random 1–32 byte magnitudes, random signs,
+   the same operation set, and a real deterministic ECDSA signature per round.
+   **8,800 checks.**
+
+Both versions were installed into a pristine copy of the repository in the same
+container, and the JSON/line output diffed.
+
+## Result
+
+**11,071 checks. Zero differences.** Identical throw sites with identical messages
+(11 under each — script-number overflow and negative-shift assertions, in both).
+
+Specifically identical: **ECDSA DER signature bytes**, WIF encodings, addresses, public
+keys, script-number serialisation across the interpreter's range, and HD child
+derivation. No signature this library has ever produced would change.
+
+## Documented v5 breaking changes vs. our call sites
+
+| v5 change | Call sites in `lib/` |
+| --- | --- |
+| `.strip()` made internal | **0** |
+| `.modn()` deprecated → `.modrn()` | **0** |
+| negative-number fixes in `imuln`/`modrn`/`idivn` | **0** |
+| `toArrayLike` refactor | **0** |
+| `toBuffer` only defined when `Buffer` exists | **0** — our wrapper *overrides* `toBuffer` entirely |
+| constructor rejects decimal strings | **0** — no decimal string is ever passed |
+| stricter invalid-character parsing | the only one that reached us — see below |
+
+The single `.toArray()` call site is the interpreter's `LSHIFT`/`RSHIFT` path. It is
+covered by 74 bitcoind `script_tests` vectors, which pass identically under both
+versions.
+
+### The one change that reached us
+
+v5 rejects invalid characters instead of silently skipping them. That is what surfaced
+the latent defect fixed in **7.5.5**: `PrivateKey.fromObject` accepted a malformed `bn`
+and returned a different, ~40-bit key rather than throwing. v5's behaviour is strictly
+safer, and our fix is in this library's own validation, so it does not depend on the
+upgrade.
+
+## Why the upgrade is nonetheless declined
+
+The `=4.12.3` pin in `package.json` is load-bearing for **deduplication**:
+
+| root `bn.js` | copies inlined in `bsv.min.js` | size |
+| --- | --- | --- |
+| 4.12.3 (today) | 2 | 1,319,110 |
+| 5.2.5 | 5 | 1,451,156 (**+132 KB, +10 %**) |
+
+At 4.12.3, npm satisfies the transitive `^4` consumers (`asn1.js`, `miller-rabin`,
+`public-encrypt`, `diffie-hellman`) from the hoisted root copy. Moving the root to 5.x
+no longer satisfies `^4`, so each gets its own nested 4.12.5 — and those chains are part
+of `crypto-browserify`, which **is** bundled. (`elliptic`, `browserify-sign` and
+`create-ecdh` are stubbed out by the esbuild config and stay absent either way.)
+
+So the upgrade costs every browser consumer 10 % more bundle for no functional gain:
+there is no advisory against `bn.js` 4.x affecting this library, and no v5 feature it
+needs.
+
+## When to revisit
+
+When the `crypto-browserify` dependency chain moves to `bn.js@^5`, deduplication is
+restored and the upgrade becomes free. At that point this review's correctness findings
+still stand and the bump can be taken directly.
+
+## Reproducing
+
+The harnesses are not committed (they need two conflicting versions of the same
+dependency installed side by side). To rebuild them, run the wrapper surface and a
+deterministic fuzz corpus under each version in a clean container and diff the output;
+the operation list above is the required coverage.

package/docs/MODULE_REFERENCE_COMPLETE.md

@@ -55,19 +55,19 @@ Three advanced modules totaling **~2.7MB** of functionality:
 - **Purpose**: Threshold cryptography for secure secret distribution
 - **Use Cases**: Backup keys, multi-party security, key recovery
 - **Features**: Split secrets into N shares, require M to reconstruct
-- **CDN**: `unpkg.com/@smartledger/bsv@7.5.4/bsv-shamir.min.js`
+- **CDN**: `unpkg.com/@smartledger/bsv@7.5.6/bsv-shamir.min.js`
 
 #### **🌐 Global Digital Attestation Framework - GDAF (1184KB)**  
 - **Purpose**: W3C Verifiable Credentials and decentralized identity
 - **Use Cases**: Identity verification, attestations, zero-knowledge proofs
 - **Features**: DID creation, credential issuance, selective disclosure
-- **CDN**: `unpkg.com/@smartledger/bsv@7.5.4/bsv-gdaf.min.js`
+- **CDN**: `unpkg.com/@smartledger/bsv@7.5.6/bsv-gdaf.min.js`
 
 #### **⚖️ Legal Token Protocol - LTP (1184KB)**
 - **Purpose**: Legal compliance framework for tokenized assets
 - **Use Cases**: Property rights, obligations, compliant tokenization  
 - **Features**: Legal primitives, compliance checking, attestation anchoring
-- **CDN**: `unpkg.com/@smartledger/bsv@7.5.4/bsv-ltp.min.js`
+- **CDN**: `unpkg.com/@smartledger/bsv@7.5.6/bsv-ltp.min.js`
 
 ### **2. Incorrect File Sizes in Documentation**
 
@@ -81,18 +81,18 @@ Three advanced modules totaling **~2.7MB** of functionality:
 
 | Module | Size | Use Case | CDN Link |
 |--------|------|----------|----------|
-| **bsv.min.js** | 937KB | Core BSV + SmartContract | `unpkg.com/@smartledger/bsv@7.5.4/bsv.min.js` |
-| **bsv.bundle.js** | 937KB | Everything in one file | `unpkg.com/@smartledger/bsv@7.5.4/bsv.bundle.js` |
-| **bsv-smartcontract.min.js** | 937KB | Covenant development | `unpkg.com/@smartledger/bsv@7.5.4/bsv-smartcontract.min.js` |
-| **bsv-covenant.min.js** | 913KB | Covenant operations | `unpkg.com/@smartledger/bsv@7.5.4/bsv-covenant.min.js` |
-| **bsv-script-helper.min.js** | 26KB | Custom script tools | `unpkg.com/@smartledger/bsv@7.5.4/bsv-script-helper.min.js` |
-| **bsv-security.min.js** | 26KB | Security enhancements (opt-in helpers — see README › Security) | `unpkg.com/@smartledger/bsv@7.5.4/bsv-security.min.js` |
-| **bsv-ecies.min.js** | 71KB | Encryption | `unpkg.com/@smartledger/bsv@7.5.4/bsv-ecies.min.js` |
-| **bsv-message.min.js** | 26KB | Message signing | `unpkg.com/@smartledger/bsv@7.5.4/bsv-message.min.js` |
-| **bsv-mnemonic.min.js** | 681KB | HD wallets | `unpkg.com/@smartledger/bsv@7.5.4/bsv-mnemonic.min.js` |
-| **🆕 bsv-shamir.min.js** | 432KB | **Secret sharing** | `unpkg.com/@smartledger/bsv@7.5.4/bsv-shamir.min.js` |
-| **🆕 bsv-gdaf.min.js** | 1184KB | **Digital attestation** | `unpkg.com/@smartledger/bsv@7.5.4/bsv-gdaf.min.js` |
-| **🆕 bsv-ltp.min.js** | 1184KB | **Legal tokens** | `unpkg.com/@smartledger/bsv@7.5.4/bsv-ltp.min.js` |
+| **bsv.min.js** | 937KB | Core BSV + SmartContract | `unpkg.com/@smartledger/bsv@7.5.6/bsv.min.js` |
+| **bsv.bundle.js** | 937KB | Everything in one file | `unpkg.com/@smartledger/bsv@7.5.6/bsv.bundle.js` |
+| **bsv-smartcontract.min.js** | 937KB | Covenant development | `unpkg.com/@smartledger/bsv@7.5.6/bsv-smartcontract.min.js` |
+| **bsv-covenant.min.js** | 913KB | Covenant operations | `unpkg.com/@smartledger/bsv@7.5.6/bsv-covenant.min.js` |
+| **bsv-script-helper.min.js** | 26KB | Custom script tools | `unpkg.com/@smartledger/bsv@7.5.6/bsv-script-helper.min.js` |
+| **bsv-security.min.js** | 26KB | Security enhancements (opt-in helpers — see README › Security) | `unpkg.com/@smartledger/bsv@7.5.6/bsv-security.min.js` |
+| **bsv-ecies.min.js** | 71KB | Encryption | `unpkg.com/@smartledger/bsv@7.5.6/bsv-ecies.min.js` |
+| **bsv-message.min.js** | 26KB | Message signing | `unpkg.com/@smartledger/bsv@7.5.6/bsv-message.min.js` |
+| **bsv-mnemonic.min.js** | 681KB | HD wallets | `unpkg.com/@smartledger/bsv@7.5.6/bsv-mnemonic.min.js` |
+| **🆕 bsv-shamir.min.js** | 432KB | **Secret sharing** | `unpkg.com/@smartledger/bsv@7.5.6/bsv-shamir.min.js` |
+| **🆕 bsv-gdaf.min.js** | 1184KB | **Digital attestation** | `unpkg.com/@smartledger/bsv@7.5.6/bsv-gdaf.min.js` |
+| **🆕 bsv-ltp.min.js** | 1184KB | **Legal tokens** | `unpkg.com/@smartledger/bsv@7.5.6/bsv-ltp.min.js` |
 
 ## 🎯 **Updated Usage Examples**
 
@@ -100,22 +100,22 @@ Three advanced modules totaling **~2.7MB** of functionality:
 
 #### **1. Basic Development (~963KB)**
 ```html
-<script src="https://unpkg.com/@smartledger/bsv@7.5.4/bsv.min.js"></script>
-<script src="https://unpkg.com/@smartledger/bsv@7.5.4/bsv-script-helper.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@7.5.6/bsv.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@7.5.6/bsv-script-helper.min.js"></script>
 ```
 
 #### **2. Smart Contract Development (~2.7MB — each bundle re-embeds core BSV)**
 ```html
-<script src="https://unpkg.com/@smartledger/bsv@7.5.4/bsv.min.js"></script>
-<script src="https://unpkg.com/@smartledger/bsv@7.5.4/bsv-covenant.min.js"></script>
-<script src="https://unpkg.com/@smartledger/bsv@7.5.4/bsv-smartcontract.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@7.5.6/bsv.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@7.5.6/bsv-covenant.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@7.5.6/bsv-smartcontract.min.js"></script>
 ```
 
 #### **3. 🆕 Legal & Compliance Development (~3.2MB — each bundle re-embeds core BSV)**
 ```html
-<script src="https://unpkg.com/@smartledger/bsv@7.5.4/bsv.min.js"></script>
-<script src="https://unpkg.com/@smartledger/bsv@7.5.4/bsv-ltp.min.js"></script>
-<script src="https://unpkg.com/@smartledger/bsv@7.5.4/bsv-gdaf.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@7.5.6/bsv.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@7.5.6/bsv-ltp.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@7.5.6/bsv-gdaf.min.js"></script>
 <script>
   // Legal Token Protocol
   const legalToken = bsv.createLegalToken({
@@ -132,9 +132,9 @@ Three advanced modules totaling **~2.7MB** of functionality:
 
 #### **4. 🆕 Security & Cryptography (~1.4MB)**
 ```html
-<script src="https://unpkg.com/@smartledger/bsv@7.5.4/bsv.min.js"></script>
-<script src="https://unpkg.com/@smartledger/bsv@7.5.4/bsv-security.min.js"></script>
-<script src="https://unpkg.com/@smartledger/bsv@7.5.4/bsv-shamir.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@7.5.6/bsv.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@7.5.6/bsv-security.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@7.5.6/bsv-shamir.min.js"></script>
 <script>
   // Shamir Secret Sharing
   const shares = bsv.splitSecret('my_secret_key', 5, 3); // 5 shares, 3 needed
@@ -146,7 +146,7 @@ Three advanced modules totaling **~2.7MB** of functionality:
 
 #### **5. Everything Bundle (937KB)**
 ```html
-<script src="https://unpkg.com/@smartledger/bsv@7.5.4/bsv.bundle.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@7.5.6/bsv.bundle.js"></script>
 <script>
   // Everything available immediately
   const shares = bsv.splitSecret('secret', 5, 3);

package/docs/advanced/UTXO_MANAGER_GUIDE.md

@@ -722,7 +722,7 @@ interface UTXO {
 <html>
 <head>
     <title>UTXO Manager Demo</title>
-    <script src="https://cdn.jsdelivr.net/npm/@smartledger/bsv@7.5.4/bsv.min.js"></script>
+    <script src="https://cdn.jsdelivr.net/npm/@smartledger/bsv@7.5.6/bsv.min.js"></script>
 </head>
 <body>
     <script>

package/docs/getting-started/INSTALLATION.md

@@ -48,7 +48,7 @@ const tx: Transaction = new Transaction();
 #### **Core Library Only (937KB)**
 For basic Bitcoin SV operations:
 ```html
-<script src="https://unpkg.com/@smartledger/bsv@7.5.4/bsv.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@7.5.6/bsv.min.js"></script>
 <script>
   const privateKey = new bsv.PrivateKey();
   const address = privateKey.toAddress();
@@ -58,7 +58,7 @@ For basic Bitcoin SV operations:
 #### **Complete Bundle (937KB)**  
 Everything in one file:
 ```html
-<script src="https://unpkg.com/@smartledger/bsv@7.5.4/bsv.bundle.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@7.5.6/bsv.bundle.js"></script>
 <script>
   // All features available immediately
   const shares = bsv.splitSecret('secret', 5, 3);
@@ -71,9 +71,9 @@ Everything in one file:
 
 #### **Smart Contract Development (~2.7MB total — each bundle is self-contained and re-embeds core BSV)**
 ```html
-<script src="https://unpkg.com/@smartledger/bsv@7.5.4/bsv.min.js"></script>
-<script src="https://unpkg.com/@smartledger/bsv@7.5.4/bsv-covenant.min.js"></script>
-<script src="https://unpkg.com/@smartledger/bsv@7.5.4/bsv-smartcontract.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@7.5.6/bsv.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@7.5.6/bsv-covenant.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@7.5.6/bsv-smartcontract.min.js"></script>
 <script>
   const covenant = bsv.SmartContract.createCovenantBuilder()
     .extractField('amount').push(50000).greaterThanOrEqual().build();
@@ -82,9 +82,9 @@ Everything in one file:
 
 #### **Legal & Identity Development (~3.2MB total — each bundle is self-contained and re-embeds core BSV)**
 ```html
-<script src="https://unpkg.com/@smartledger/bsv@7.5.4/bsv.min.js"></script>
-<script src="https://unpkg.com/@smartledger/bsv@7.5.4/bsv-ltp.min.js"></script>
-<script src="https://unpkg.com/@smartledger/bsv@7.5.4/bsv-gdaf.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@7.5.6/bsv.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@7.5.6/bsv-ltp.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@7.5.6/bsv-gdaf.min.js"></script>
 <script>
   // Legal Token Protocol
   const propertyToken = bsv.createPropertyToken({
@@ -98,9 +98,9 @@ Everything in one file:
 
 #### **Security & Cryptography (~1.4MB total — each bundle is self-contained and re-embeds core BSV)**
 ```html
-<script src="https://unpkg.com/@smartledger/bsv@7.5.4/bsv.min.js"></script>
-<script src="https://unpkg.com/@smartledger/bsv@7.5.4/bsv-security.min.js"></script>
-<script src="https://unpkg.com/@smartledger/bsv@7.5.4/bsv-shamir.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@7.5.6/bsv.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@7.5.6/bsv-security.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@7.5.6/bsv-shamir.min.js"></script>
 <script>
   // Threshold Cryptography
   const shares = bsv.splitSecret('my_secret_key', 5, 3);
@@ -114,18 +114,18 @@ Everything in one file:
 
 | Module | Size | Purpose | CDN Link |
 |--------|------|---------|----------|
-| **bsv.min.js** | 937KB | Core BSV + SmartContract | `unpkg.com/@smartledger/bsv@7.5.4/bsv.min.js` |
-| **bsv.bundle.js** | 937KB | Everything in one file | `unpkg.com/@smartledger/bsv@7.5.4/bsv.bundle.js` |
-| **bsv-smartcontract.min.js** | 937KB | Complete covenant framework | `unpkg.com/@smartledger/bsv@7.5.4/bsv-smartcontract.min.js` |
-| **bsv-ltp.min.js** | 1184KB | **Legal Token Protocol** | `unpkg.com/@smartledger/bsv@7.5.4/bsv-ltp.min.js` |
-| **bsv-gdaf.min.js** | 1184KB | **Digital Identity & Attestation** | `unpkg.com/@smartledger/bsv@7.5.4/bsv-gdaf.min.js` |
-| **bsv-shamir.min.js** | 432KB | **Threshold Cryptography** | `unpkg.com/@smartledger/bsv@7.5.4/bsv-shamir.min.js` |
-| **bsv-security.min.js** | 26KB | Security enhancements (opt-in helpers — see README › Security) | `unpkg.com/@smartledger/bsv@7.5.4/bsv-security.min.js` |
-| **bsv-mnemonic.min.js** | 681KB | HD wallets | `unpkg.com/@smartledger/bsv@7.5.4/bsv-mnemonic.min.js` |
-| **bsv-ecies.min.js** | 71KB | Encryption | `unpkg.com/@smartledger/bsv@7.5.4/bsv-ecies.min.js` |
-| **bsv-covenant.min.js** | 913KB | Covenant operations | `unpkg.com/@smartledger/bsv@7.5.4/bsv-covenant.min.js` |
-| **bsv-script-helper.min.js** | 26KB | Custom script tools | `unpkg.com/@smartledger/bsv@7.5.4/bsv-script-helper.min.js` |
-| **bsv-message.min.js** | 26KB | Message signing | `unpkg.com/@smartledger/bsv@7.5.4/bsv-message.min.js` |
+| **bsv.min.js** | 937KB | Core BSV + SmartContract | `unpkg.com/@smartledger/bsv@7.5.6/bsv.min.js` |
+| **bsv.bundle.js** | 937KB | Everything in one file | `unpkg.com/@smartledger/bsv@7.5.6/bsv.bundle.js` |
+| **bsv-smartcontract.min.js** | 937KB | Complete covenant framework | `unpkg.com/@smartledger/bsv@7.5.6/bsv-smartcontract.min.js` |
+| **bsv-ltp.min.js** | 1184KB | **Legal Token Protocol** | `unpkg.com/@smartledger/bsv@7.5.6/bsv-ltp.min.js` |
+| **bsv-gdaf.min.js** | 1184KB | **Digital Identity & Attestation** | `unpkg.com/@smartledger/bsv@7.5.6/bsv-gdaf.min.js` |
+| **bsv-shamir.min.js** | 432KB | **Threshold Cryptography** | `unpkg.com/@smartledger/bsv@7.5.6/bsv-shamir.min.js` |
+| **bsv-security.min.js** | 26KB | Security enhancements (opt-in helpers — see README › Security) | `unpkg.com/@smartledger/bsv@7.5.6/bsv-security.min.js` |
+| **bsv-mnemonic.min.js** | 681KB | HD wallets | `unpkg.com/@smartledger/bsv@7.5.6/bsv-mnemonic.min.js` |
+| **bsv-ecies.min.js** | 71KB | Encryption | `unpkg.com/@smartledger/bsv@7.5.6/bsv-ecies.min.js` |
+| **bsv-covenant.min.js** | 913KB | Covenant operations | `unpkg.com/@smartledger/bsv@7.5.6/bsv-covenant.min.js` |
+| **bsv-script-helper.min.js** | 26KB | Custom script tools | `unpkg.com/@smartledger/bsv@7.5.6/bsv-script-helper.min.js` |
+| **bsv-message.min.js** | 26KB | Message signing | `unpkg.com/@smartledger/bsv@7.5.6/bsv-message.min.js` |
 
 ## ⚙️ **Development Environment Setup**
 

package/docs/getting-started/QUICK_START.md

@@ -14,10 +14,10 @@ npm install @smartledger/bsv
 ### Browser CDN (Instant)
 ```html
 <!-- Core library (937KB) -->
-<script src="https://unpkg.com/@smartledger/bsv@7.5.4/bsv.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@7.5.6/bsv.min.js"></script>
 
 <!-- Everything included (937KB) -->
-<script src="https://unpkg.com/@smartledger/bsv@7.5.4/bsv.bundle.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@7.5.6/bsv.bundle.js"></script>
 ```
 
 ## 💰 **Your First Transaction (60 seconds)**
@@ -127,19 +127,19 @@ SmartLedger-BSV offers 12 different loading options - use only what you need:
 
 ```html
 <!-- Core BSV only (937KB) -->
-<script src="https://unpkg.com/@smartledger/bsv@7.5.4/bsv.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@7.5.6/bsv.min.js"></script>
 
 <!-- Smart contracts (937KB) -->
-<script src="https://unpkg.com/@smartledger/bsv@7.5.4/bsv-smartcontract.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@7.5.6/bsv-smartcontract.min.js"></script>
 
 <!-- Legal tokens (1.16MB) -->
-<script src="https://unpkg.com/@smartledger/bsv@7.5.4/bsv-ltp.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@7.5.6/bsv-ltp.min.js"></script>
 
 <!-- Digital identity (1.16MB) -->
-<script src="https://unpkg.com/@smartledger/bsv@7.5.4/bsv-gdaf.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@7.5.6/bsv-gdaf.min.js"></script>
 
 <!-- Everything (937KB) -->
-<script src="https://unpkg.com/@smartledger/bsv@7.5.4/bsv.bundle.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@7.5.6/bsv.bundle.js"></script>
 ```
 
 ## ⚡ **Key Advantages**

package/docs/migration/FROM_BSV_1_5_6.md

@@ -159,17 +159,17 @@ const recovered = bsv.reconstructSecret([shares[0], shares[2], shares[4]]);
 ### **New Modular Options** 
 ```html
 <!-- Core compatibility (same size as bsv@1.5.6) -->
-<script src="https://unpkg.com/@smartledger/bsv@7.5.4/bsv.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@7.5.6/bsv.min.js"></script>
 
 <!-- Add smart contracts when ready -->
-<script src="https://unpkg.com/@smartledger/bsv@7.5.4/bsv-smartcontract.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@7.5.6/bsv-smartcontract.min.js"></script>
 
 <!-- Add advanced features as needed -->
-<script src="https://unpkg.com/@smartledger/bsv@7.5.4/bsv-ltp.min.js"></script>
-<script src="https://unpkg.com/@smartledger/bsv@7.5.4/bsv-gdaf.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@7.5.6/bsv-ltp.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@7.5.6/bsv-gdaf.min.js"></script>
 
 <!-- Everything in one file -->
-<script src="https://unpkg.com/@smartledger/bsv@7.5.4/bsv.bundle.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@7.5.6/bsv.bundle.js"></script>
 ```
 
 ## 🔍 **Testing Your Migration**

package/lib/crypto/bn.js

@@ -149,7 +149,9 @@ BN.prototype.toSMBigEndian = function () {
     }
   }
 
-  if (buf.length === 1 & buf[0] === 0) {
+  // `&` here was a bitwise AND between two booleans. It happened to work because
+  // `===` binds tighter than `&` and `true & true` is 1, but the intent is logical.
+  if (buf.length === 1 && buf[0] === 0) {
     buf = Buffer.from([])
   }
   return buf

package/lib/crypto/hash.browser.js

@@ -125,7 +125,12 @@ Hash.hmac = function (hashf, data, key) {
 
   if (key.length > blocksize) {
     key = hashf(key)
-  } else if (key < blocksize) {
+  } else if (key.length < blocksize) {
+    // Was `key < blocksize` — a Buffer compared against a number, which is always
+    // false, so this zero-padding branch never ran. The result was correct anyway:
+    // the XOR loop below indexes past a short key and `x ^ undefined === x ^ 0`,
+    // which is exactly what the padding produces. Fixed so the code says what it
+    // does; HMAC output is unchanged, and the vectors below assert that.
     var fill = Buffer.alloc(blocksize)
     fill.fill(0)
     key.copy(fill)

package/lib/crypto/hash.node.js

@@ -125,7 +125,12 @@ Hash.hmac = function (hashf, data, key) {
 
   if (key.length > blocksize) {
     key = hashf(key)
-  } else if (key < blocksize) {
+  } else if (key.length < blocksize) {
+    // Was `key < blocksize` — a Buffer compared against a number, which is always
+    // false, so this zero-padding branch never ran. The result was correct anyway:
+    // the XOR loop below indexes past a short key and `x ^ undefined === x ^ 0`,
+    // which is exactly what the padding produces. Fixed so the code says what it
+    // does; HMAC output is unchanged, and the vectors below assert that.
     var fill = Buffer.alloc(blocksize)
     fill.fill(0)
     key.copy(fill)

package/lib/networks.js

@@ -330,7 +330,9 @@ Object.defineProperty(testnet, 'cashAddrPrefixArray', {
     if (this.regtestEnabled) {
       return cashAddrPrefixToArray(REGTEST.CASHADDRPREFIX)
     } else if (this.stnEnabled) {
-      return STN.cashAddrPrefixToArray(STN.CASHADDRPREFIX)
+      // STN is a plain data object with no methods; the sibling branches call the
+      // module-level helper, and reaching for it on STN threw a TypeError instead.
+      return cashAddrPrefixToArray(STN.CASHADDRPREFIX)
     } else {
       return cashAddrPrefixToArray(TESTNET.CASHADDRPREFIX)
     }

package/lib/privatekey.js

@@ -11,6 +11,10 @@ var PublicKey = require('./publickey')
 var Random = require('./crypto/random')
 var $ = require('./util/preconditions')
 
+// The marker toJSON() emits in place of the secret. _transformObject rejects it by name
+// so a JSON round-trip fails loudly instead of quietly yielding a different key.
+var REDACTED = '[REDACTED]'
+
 /**
  * Instantiate a PrivateKey from a BN, Buffer or WIF string.
  *
@@ -215,7 +219,37 @@ PrivateKey.fromHex = function (hex, network, compressed) {
  * @private
  */
 PrivateKey._transformObject = function (json) {
+  // bn.js 4 silently SKIPS characters it cannot parse rather than failing, so any
+  // malformed `bn` produced a wrong key instead of an error. The natural round-trip
+  // `fromObject(JSON.parse(JSON.stringify(key)))` fed it the redaction marker that
+  // `toJSON` has emitted since 7.5.1 and got a deterministic ~40-bit key back, with
+  // no indication anything was wrong — funds sent to its address are trivially
+  // recoverable by anyone. Validate before parsing.
+  // This is reached with two different shapes: a deserialised JSON object, whose `bn`
+  // is a hex string, and an internal info object built by _transformBNBuffer, whose
+  // `bn` is already a BN. Only the former needs parsing, and only it can be malformed.
+  if (json.bn instanceof BN) {
+    return {
+      bn: json.bn,
+      network: Networks.get(json.network),
+      compressed: json.compressed
+    }
+  }
+  if (typeof json.bn !== 'string' || !json.bn.length) {
+    throw new TypeError('Invalid private key: `bn` must be a hex string')
+  }
+  if (json.bn === REDACTED) {
+    throw new TypeError('Invalid private key: `bn` is "' + REDACTED + '". ' +
+      'JSON.stringify() redacts the secret on purpose — use toObject() for a ' +
+      'round-trippable export, or toWIF().')
+  }
+  if (!/^[0-9a-fA-F]+$/.test(json.bn)) {
+    throw new TypeError('Invalid private key: `bn` is not hexadecimal')
+  }
   var bn = new BN(json.bn, 'hex')
+  if (bn.isZero() || bn.gte(Point.getN())) {
+    throw new TypeError('Invalid private key: outside the range of valid keys')
+  }
   var network = Networks.get(json.network)
   return {
     bn: bn,
@@ -403,7 +437,7 @@ PrivateKey.prototype.toObject = function toObject () {
  */
 PrivateKey.prototype.toJSON = function toJSON () {
   return {
-    bn: '[REDACTED]',
+    bn: REDACTED,
     compressed: this.compressed,
     network: this.network.toString()
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@smartledger/bsv",
-  "version": "7.5.4",
+  "version": "7.5.6",
   "description": "🚀 Complete Bitcoin SV development framework with legally-recognizable DID:web + W3C VC-JWT toolkit, Legal Token Protocol (LTP), Global Digital Attestation Framework (GDAF), StatusList2021 revocation, and 16 flexible loading options. Standards-based credentials with ES256/ES256K support, on-chain BSV anchoring, and comprehensive Bitcoin SV API. Perfect for legal tokens, verifiable credentials, DeFi, smart contracts, and secure Bitcoin applications.",
   "author": "SmartLedger Technology <hello@smartledger.technology> (https://smartledger.technology)",
   "homepage": "https://github.com/codenlighten/smartledger-bsv#readme",
@@ -228,11 +228,11 @@
     "esbuild": "^0.28.1",
     "events": "^3.3.0",
     "jose": "^5.10.0",
-    "mocha": "^11.7.6",
+    "mocha": "^11.8.0",
     "nyc": "^18.0.0",
     "path-browserify": "^1.0.1",
     "process": "^0.11.10",
-    "sinon": "7.2.3",
+    "sinon": "22.1.0",
     "standard": "12.0.1",
     "stream-browserify": "^3.0.0",
     "typescript": "^5.9.3",
@@ -250,7 +250,9 @@
       "it"
     ],
     "ignore": [
-      "dist/**"
+      "dist/**",
+      "bsv.bundle.js",
+      "*.min.js"
     ]
   }
 }

package/test/networks.js

@@ -159,4 +159,49 @@ describe('Networks', function () {
     var fn = function () { networks.testnet.name = 'livenet' }
     expect(fn).to.throw(TypeError)
   })
+  // The `cashAddrPrefixArray` getter has three branches; only the STN one reached for
+  // the helper on the STN data object instead of the module-level function, so reading
+  // it with STN enabled threw `STN.cashAddrPrefixToArray is not a function`. The tests
+  // above cover `cashAddrPrefix` (the string) but never the array getter, which is why
+  // a live TypeError survived a 4,597-test suite.
+  describe('cashAddrPrefixArray across the regtest/stn toggles', function () {
+    // enableStn/enableRegtest mutate the shared testnet object, so without a reset the
+    // flags leak into every later test in the run.
+    afterEach(function () {
+      networks.disableStn()
+      networks.disableRegtest()
+    })
+
+    function assertPrefixArray (arr) {
+      Array.isArray(arr).should.equal(true)
+      arr.length.should.be.above(0)
+      arr.forEach(function (n) { n.should.be.a('number') })
+    }
+
+    it('works with stn enabled', function () {
+      networks.enableStn()
+      assertPrefixArray(networks.testnet.cashAddrPrefixArray)
+    })
+
+    it('works with regtest enabled', function () {
+      networks.enableRegtest()
+      assertPrefixArray(networks.testnet.cashAddrPrefixArray)
+    })
+
+    it('works with neither enabled', function () {
+      assertPrefixArray(networks.testnet.cashAddrPrefixArray)
+    })
+
+    it('returns a different prefix array per mode', function () {
+      var plain = networks.testnet.cashAddrPrefixArray.join(',')
+      networks.enableStn()
+      var stn = networks.testnet.cashAddrPrefixArray.join(',')
+      networks.disableStn()
+      networks.enableRegtest()
+      var regtest = networks.testnet.cashAddrPrefixArray.join(',')
+      stn.should.not.equal(plain)
+      regtest.should.not.equal(plain)
+      stn.should.not.equal(regtest)
+    })
+  })
 })

package/test/privatekey.js

@@ -253,10 +253,43 @@ describe('PrivateKey', function () {
       }).to.not.throw()
     })
 
-    it('also accepts an object as argument', function () {
+    // This asserted that feeding toJSON() output back into fromObject does NOT throw.
+    // Since 7.5.1 toJSON() redacts the secret, and bn.js 4 silently SKIPS characters it
+    // cannot parse instead of failing — so the round-trip returned a DIFFERENT key
+    // (a deterministic ~40-bit one, trivially recoverable by anyone) with no error at
+    // all. The old expectation encoded that as intended behaviour; it is now inverted.
+    it('refuses to rebuild a key from redacted toJSON() output', function () {
       expect(function () {
         return PrivateKey.fromObject(new PrivateKey().toJSON())
-      }).to.not.throw()
+      }).to.throw(/REDACTED/)
+    })
+
+    it('round-trips exactly through toObject(), which is the real export', function () {
+      var key = new PrivateKey()
+      PrivateKey.fromObject(key.toObject()).toWIF().should.equal(key.toWIF())
+    })
+
+    it('rejects a malformed bn instead of silently deriving another key', function () {
+      // bn.js 4 parses '[REDACTED]' as 768491671261 rather than erroring.
+      var cases = ['zzzz', '[REDACTED]', 'nothex', '12g4']
+      cases.forEach(function (bad) {
+        expect(function () {
+          return PrivateKey.fromObject({ bn: bad, compressed: true, network: 'livenet' })
+        }).to.throw(/Invalid private key/)
+      })
+    })
+
+    it('rejects a bn outside the valid key range', function () {
+      expect(function () {
+        return PrivateKey.fromObject({ bn: '00'.repeat(32), compressed: true, network: 'livenet' })
+      }).to.throw(/outside the range/)
+      expect(function () {
+        return PrivateKey.fromObject({
+          bn: 'FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFEBAAEDCE6AF48A03BBFD25E8CD0364142',
+          compressed: true,
+          network: 'livenet'
+        })
+      }).to.throw(/outside the range/)
     })
   })
 

package/version.js

@@ -1,3 +1,3 @@
 'use strict'
 // GENERATED by scripts/sync-version.js on `npm version` — do not edit.
-module.exports = '7.5.4'
+module.exports = '7.5.6'