@smartledger/bsv 4.0.0 → 4.0.1

package/docs/COVENANT_DEVELOPMENT_RESOLVED.md

@@ -136,9 +136,9 @@ node custom_script_signature_test.js
 ## 📦 Installation
 
 ```bash
-npm install smartledger-bsv@3.4.5
+npm install smartledger-bsv@4.0.1
 # or
-npm install @smartledger/bsv@3.4.5
+npm install @smartledger/bsv@4.0.1
 ```
 
 ## ✅ Verification Results

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@3.4.5/bsv-shamir.min.js`
+- **CDN**: `unpkg.com/@smartledger/bsv@4.0.1/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@3.4.5/bsv-gdaf.min.js`
+- **CDN**: `unpkg.com/@smartledger/bsv@4.0.1/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@3.4.5/bsv-ltp.min.js`
+- **CDN**: `unpkg.com/@smartledger/bsv@4.0.1/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@3.4.5/bsv.min.js` |
-| **bsv.bundle.js** | 937KB | Everything in one file | `unpkg.com/@smartledger/bsv@3.4.5/bsv.bundle.js` |
-| **bsv-smartcontract.min.js** | 937KB | Covenant development | `unpkg.com/@smartledger/bsv@3.4.5/bsv-smartcontract.min.js` |
-| **bsv-covenant.min.js** | 913KB | Covenant operations | `unpkg.com/@smartledger/bsv@3.4.5/bsv-covenant.min.js` |
-| **bsv-script-helper.min.js** | 26KB | Custom script tools | `unpkg.com/@smartledger/bsv@3.4.5/bsv-script-helper.min.js` |
-| **bsv-security.min.js** | 26KB | Security enhancements (opt-in helpers — see README › Security) | `unpkg.com/@smartledger/bsv@3.4.5/bsv-security.min.js` |
-| **bsv-ecies.min.js** | 71KB | Encryption | `unpkg.com/@smartledger/bsv@3.4.5/bsv-ecies.min.js` |
-| **bsv-message.min.js** | 26KB | Message signing | `unpkg.com/@smartledger/bsv@3.4.5/bsv-message.min.js` |
-| **bsv-mnemonic.min.js** | 681KB | HD wallets | `unpkg.com/@smartledger/bsv@3.4.5/bsv-mnemonic.min.js` |
-| **🆕 bsv-shamir.min.js** | 432KB | **Secret sharing** | `unpkg.com/@smartledger/bsv@3.4.5/bsv-shamir.min.js` |
-| **🆕 bsv-gdaf.min.js** | 1184KB | **Digital attestation** | `unpkg.com/@smartledger/bsv@3.4.5/bsv-gdaf.min.js` |
-| **🆕 bsv-ltp.min.js** | 1184KB | **Legal tokens** | `unpkg.com/@smartledger/bsv@3.4.5/bsv-ltp.min.js` |
+| **bsv.min.js** | 937KB | Core BSV + SmartContract | `unpkg.com/@smartledger/bsv@4.0.1/bsv.min.js` |
+| **bsv.bundle.js** | 937KB | Everything in one file | `unpkg.com/@smartledger/bsv@4.0.1/bsv.bundle.js` |
+| **bsv-smartcontract.min.js** | 937KB | Covenant development | `unpkg.com/@smartledger/bsv@4.0.1/bsv-smartcontract.min.js` |
+| **bsv-covenant.min.js** | 913KB | Covenant operations | `unpkg.com/@smartledger/bsv@4.0.1/bsv-covenant.min.js` |
+| **bsv-script-helper.min.js** | 26KB | Custom script tools | `unpkg.com/@smartledger/bsv@4.0.1/bsv-script-helper.min.js` |
+| **bsv-security.min.js** | 26KB | Security enhancements (opt-in helpers — see README › Security) | `unpkg.com/@smartledger/bsv@4.0.1/bsv-security.min.js` |
+| **bsv-ecies.min.js** | 71KB | Encryption | `unpkg.com/@smartledger/bsv@4.0.1/bsv-ecies.min.js` |
+| **bsv-message.min.js** | 26KB | Message signing | `unpkg.com/@smartledger/bsv@4.0.1/bsv-message.min.js` |
+| **bsv-mnemonic.min.js** | 681KB | HD wallets | `unpkg.com/@smartledger/bsv@4.0.1/bsv-mnemonic.min.js` |
+| **🆕 bsv-shamir.min.js** | 432KB | **Secret sharing** | `unpkg.com/@smartledger/bsv@4.0.1/bsv-shamir.min.js` |
+| **🆕 bsv-gdaf.min.js** | 1184KB | **Digital attestation** | `unpkg.com/@smartledger/bsv@4.0.1/bsv-gdaf.min.js` |
+| **🆕 bsv-ltp.min.js** | 1184KB | **Legal tokens** | `unpkg.com/@smartledger/bsv@4.0.1/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@3.4.5/bsv.min.js"></script>
-<script src="https://unpkg.com/@smartledger/bsv@3.4.5/bsv-script-helper.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@4.0.1/bsv.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@4.0.1/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@3.4.5/bsv.min.js"></script>
-<script src="https://unpkg.com/@smartledger/bsv@3.4.5/bsv-covenant.min.js"></script>
-<script src="https://unpkg.com/@smartledger/bsv@3.4.5/bsv-smartcontract.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@4.0.1/bsv.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@4.0.1/bsv-covenant.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@4.0.1/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@3.4.5/bsv.min.js"></script>
-<script src="https://unpkg.com/@smartledger/bsv@3.4.5/bsv-ltp.min.js"></script>
-<script src="https://unpkg.com/@smartledger/bsv@3.4.5/bsv-gdaf.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@4.0.1/bsv.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@4.0.1/bsv-ltp.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@4.0.1/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@3.4.5/bsv.min.js"></script>
-<script src="https://unpkg.com/@smartledger/bsv@3.4.5/bsv-security.min.js"></script>
-<script src="https://unpkg.com/@smartledger/bsv@3.4.5/bsv-shamir.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@4.0.1/bsv.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@4.0.1/bsv-security.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@4.0.1/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@3.4.5/bsv.bundle.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@4.0.1/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@3.4.5/bsv.min.js"></script>
+    <script src="https://cdn.jsdelivr.net/npm/@smartledger/bsv@4.0.1/bsv.min.js"></script>
 </head>
 <body>
     <script>

package/docs/getting-started/INSTALLATION.md

@@ -12,10 +12,10 @@ SmartLedger-BSV offers multiple installation methods to suit different developme
 npm install @smartledger/bsv
 
 # Install specific version
-npm install @smartledger/bsv@3.4.5
+npm install @smartledger/bsv@4.0.1
 
 # Install with exact version lock
-npm install --save-exact @smartledger/bsv@3.4.5
+npm install --save-exact @smartledger/bsv@4.0.1
 ```
 
 ### **Usage in Node.js**
@@ -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@3.4.5/bsv.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@4.0.1/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@3.4.5/bsv.bundle.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@4.0.1/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@3.4.5/bsv.min.js"></script>
-<script src="https://unpkg.com/@smartledger/bsv@3.4.5/bsv-covenant.min.js"></script>
-<script src="https://unpkg.com/@smartledger/bsv@3.4.5/bsv-smartcontract.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@4.0.1/bsv.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@4.0.1/bsv-covenant.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@4.0.1/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@3.4.5/bsv.min.js"></script>
-<script src="https://unpkg.com/@smartledger/bsv@3.4.5/bsv-ltp.min.js"></script>
-<script src="https://unpkg.com/@smartledger/bsv@3.4.5/bsv-gdaf.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@4.0.1/bsv.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@4.0.1/bsv-ltp.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@4.0.1/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@3.4.5/bsv.min.js"></script>
-<script src="https://unpkg.com/@smartledger/bsv@3.4.5/bsv-security.min.js"></script>
-<script src="https://unpkg.com/@smartledger/bsv@3.4.5/bsv-shamir.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@4.0.1/bsv.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@4.0.1/bsv-security.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@4.0.1/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@3.4.5/bsv.min.js` |
-| **bsv.bundle.js** | 937KB | Everything in one file | `unpkg.com/@smartledger/bsv@3.4.5/bsv.bundle.js` |
-| **bsv-smartcontract.min.js** | 937KB | Complete covenant framework | `unpkg.com/@smartledger/bsv@3.4.5/bsv-smartcontract.min.js` |
-| **bsv-ltp.min.js** | 1184KB | **Legal Token Protocol** | `unpkg.com/@smartledger/bsv@3.4.5/bsv-ltp.min.js` |
-| **bsv-gdaf.min.js** | 1184KB | **Digital Identity & Attestation** | `unpkg.com/@smartledger/bsv@3.4.5/bsv-gdaf.min.js` |
-| **bsv-shamir.min.js** | 432KB | **Threshold Cryptography** | `unpkg.com/@smartledger/bsv@3.4.5/bsv-shamir.min.js` |
-| **bsv-security.min.js** | 26KB | Security enhancements (opt-in helpers — see README › Security) | `unpkg.com/@smartledger/bsv@3.4.5/bsv-security.min.js` |
-| **bsv-mnemonic.min.js** | 681KB | HD wallets | `unpkg.com/@smartledger/bsv@3.4.5/bsv-mnemonic.min.js` |
-| **bsv-ecies.min.js** | 71KB | Encryption | `unpkg.com/@smartledger/bsv@3.4.5/bsv-ecies.min.js` |
-| **bsv-covenant.min.js** | 913KB | Covenant operations | `unpkg.com/@smartledger/bsv@3.4.5/bsv-covenant.min.js` |
-| **bsv-script-helper.min.js** | 26KB | Custom script tools | `unpkg.com/@smartledger/bsv@3.4.5/bsv-script-helper.min.js` |
-| **bsv-message.min.js** | 26KB | Message signing | `unpkg.com/@smartledger/bsv@3.4.5/bsv-message.min.js` |
+| **bsv.min.js** | 937KB | Core BSV + SmartContract | `unpkg.com/@smartledger/bsv@4.0.1/bsv.min.js` |
+| **bsv.bundle.js** | 937KB | Everything in one file | `unpkg.com/@smartledger/bsv@4.0.1/bsv.bundle.js` |
+| **bsv-smartcontract.min.js** | 937KB | Complete covenant framework | `unpkg.com/@smartledger/bsv@4.0.1/bsv-smartcontract.min.js` |
+| **bsv-ltp.min.js** | 1184KB | **Legal Token Protocol** | `unpkg.com/@smartledger/bsv@4.0.1/bsv-ltp.min.js` |
+| **bsv-gdaf.min.js** | 1184KB | **Digital Identity & Attestation** | `unpkg.com/@smartledger/bsv@4.0.1/bsv-gdaf.min.js` |
+| **bsv-shamir.min.js** | 432KB | **Threshold Cryptography** | `unpkg.com/@smartledger/bsv@4.0.1/bsv-shamir.min.js` |
+| **bsv-security.min.js** | 26KB | Security enhancements (opt-in helpers — see README › Security) | `unpkg.com/@smartledger/bsv@4.0.1/bsv-security.min.js` |
+| **bsv-mnemonic.min.js** | 681KB | HD wallets | `unpkg.com/@smartledger/bsv@4.0.1/bsv-mnemonic.min.js` |
+| **bsv-ecies.min.js** | 71KB | Encryption | `unpkg.com/@smartledger/bsv@4.0.1/bsv-ecies.min.js` |
+| **bsv-covenant.min.js** | 913KB | Covenant operations | `unpkg.com/@smartledger/bsv@4.0.1/bsv-covenant.min.js` |
+| **bsv-script-helper.min.js** | 26KB | Custom script tools | `unpkg.com/@smartledger/bsv@4.0.1/bsv-script-helper.min.js` |
+| **bsv-message.min.js** | 26KB | Message signing | `unpkg.com/@smartledger/bsv@4.0.1/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@3.4.5/bsv.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@4.0.1/bsv.min.js"></script>
 
 <!-- Everything included (937KB) -->
-<script src="https://unpkg.com/@smartledger/bsv@3.4.5/bsv.bundle.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@4.0.1/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@3.4.5/bsv.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@4.0.1/bsv.min.js"></script>
 
 <!-- Smart contracts (937KB) -->
-<script src="https://unpkg.com/@smartledger/bsv@3.4.5/bsv-smartcontract.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@4.0.1/bsv-smartcontract.min.js"></script>
 
 <!-- Legal tokens (1.16MB) -->
-<script src="https://unpkg.com/@smartledger/bsv@3.4.5/bsv-ltp.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@4.0.1/bsv-ltp.min.js"></script>
 
 <!-- Digital identity (1.16MB) -->
-<script src="https://unpkg.com/@smartledger/bsv@3.4.5/bsv-gdaf.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@4.0.1/bsv-gdaf.min.js"></script>
 
 <!-- Everything (937KB) -->
-<script src="https://unpkg.com/@smartledger/bsv@3.4.5/bsv.bundle.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@4.0.1/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@3.4.5/bsv.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@4.0.1/bsv.min.js"></script>
 
 <!-- Add smart contracts when ready -->
-<script src="https://unpkg.com/@smartledger/bsv@3.4.5/bsv-smartcontract.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@4.0.1/bsv-smartcontract.min.js"></script>
 
 <!-- Add advanced features as needed -->
-<script src="https://unpkg.com/@smartledger/bsv@3.4.5/bsv-ltp.min.js"></script>
-<script src="https://unpkg.com/@smartledger/bsv@3.4.5/bsv-gdaf.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@4.0.1/bsv-ltp.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@4.0.1/bsv-gdaf.min.js"></script>
 
 <!-- Everything in one file -->
-<script src="https://unpkg.com/@smartledger/bsv@3.4.5/bsv.bundle.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@4.0.1/bsv.bundle.js"></script>
 ```
 
 ## 🔍 **Testing Your Migration**

package/index.js

@@ -148,7 +148,35 @@ try {
 // Node.js specific tools (advanced development tools)
 if (typeof window === 'undefined' && typeof require === 'function') {
   try {
-    bsv.SmartUTXO = require('./lib/smartutxo')
+    // bsv.SmartUTXO is a development-only file-backed UTXO simulator.
+    // It writes to node_modules/@smartledger/bsv/utilities/blockchain-state.json,
+    // races on shared filesystem state across processes, and only ships with
+    // an empty seed (the 3.3 MB dev fixture is npmignored). Exposing it on
+    // the main `bsv` namespace creates a real footgun for anyone who assumes
+    // a production UTXO manager.
+    //
+    // Soft-deprecated in v4.0.1: the symbol is preserved (no semver break)
+    // but access surfaces a one-shot warning. Direct import remains:
+    //   require('@smartledger/bsv/lib/smartutxo')
+    // The symbol will be removed in v5.0.0.
+    var _SmartUTXO
+    var _SmartUTXOWarned = false
+    Object.defineProperty(bsv, 'SmartUTXO', {
+      configurable: true,
+      enumerable: true,
+      get: function () {
+        if (!_SmartUTXOWarned && !(process.env && process.env.BSV_HIDE_DEPRECATIONS)) {
+          _SmartUTXOWarned = true
+          console.warn('[bsv] bsv.SmartUTXO is a development-only simulator and is deprecated; ' +
+            'it will be removed in v5.0.0. Import directly: ' +
+            "require('@smartledger/bsv/lib/smartutxo'). " +
+            'Set BSV_HIDE_DEPRECATIONS=1 to silence this warning.')
+        }
+        if (!_SmartUTXO) _SmartUTXO = require('./lib/smartutxo')
+        return _SmartUTXO
+      }
+    })
+
     bsv.SmartMiner = require('./lib/smartminer')
     bsv.CustomScriptHelper = require('./lib/custom-script-helper')
   } catch (e) {

package/lib/smart_contract/utxo_generator.js

@@ -32,10 +32,15 @@ function UTXOGenerator(options) {
   this.keyRing = {} // Store generated keys
   this.utxoPool = [] // Store generated UTXOs
   
-  // Initialize with SmartUTXO integration
-  if (typeof bsv.SmartUTXO !== 'undefined') {
-    this.smartUTXO = new bsv.SmartUTXO(this.options)
-  }
+  // Initialize with SmartUTXO integration via direct require so that
+  // touching this internal integration path doesn't surface the
+  // bsv.SmartUTXO deprecation warning (the warning is for downstream
+  // consumers who reach for bsv.SmartUTXO themselves, not for our own
+  // internal coupling). Try/catch because smartutxo is Node-only.
+  try {
+    var SmartUTXO = require('../smartutxo')
+    this.smartUTXO = new SmartUTXO(this.options)
+  } catch (e) { /* browser context; SmartUTXO unavailable */ }
 }
 
 /**

package/lib/smartutxo.js

@@ -1,8 +1,29 @@
 'use strict'
 
 /**
- * SmartLedger UTXO Management System
- * Provides blockchain state management and UTXO tracking for testing and development
+ * SmartLedger UTXO Management System — DEVELOPMENT ONLY
+ * =====================================================
+ *
+ * `SmartUTXOManager` is a file-backed wallet/UTXO simulator intended for
+ * local testing and example scripts. It persists state to
+ * `<package-root>/utilities/blockchain-state.json`, has no concurrency
+ * controls (multiple processes will race on the same file), and ships
+ * with an empty seed for npm consumers (the 3.3 MB development fixture
+ * is `.npmignore`d). Do NOT use it as a production UTXO manager —
+ * production wallets should track UTXOs themselves and never rely on a
+ * shared file inside `node_modules`.
+ *
+ * Supported import path (works in any consumer):
+ *
+ *   const SmartUTXO = require('@smartledger/bsv/lib/smartutxo')
+ *
+ * Or, from within the smartledger-bsv repo:
+ *
+ *   const SmartUTXO = require('./lib/smartutxo')
+ *
+ * The legacy `bsv.SmartUTXO` namespace export was soft-deprecated in
+ * v4.0.1 (logs a one-shot warning on access) and will be removed in
+ * v5.0.0.
  */
 
 // Set BSV_DEBUG=1 (Node) or window.BSV_DEBUG = true (browser) to surface
@@ -119,31 +140,37 @@ class SmartUTXOManager {
   }
 
   /**
-   * Create mock UTXOs for testing
-   * @param {string} address - Target address
+   * Create mock UTXOs for testing. Each mock has a fresh random txid and
+   * a P2PKH locking script that actually encodes the provided address
+   * (so any private key for `address` can sign against the resulting
+   * `script` via the high-level API).
+   *
+   * This is a pure factory — the returned UTXOs are NOT added to the
+   * simulator state. Call `.addUTXO(...)` on each one to persist them.
+   *
+   * @param {string} address - Target address (livenet or testnet)
    * @param {number} count - Number of UTXOs to create
    * @param {number} satoshis - Satoshis per UTXO
    * @returns {Array} Array of created UTXOs
    */
   createMockUTXOs(address, count = 5, satoshis = 100000) {
+    // Use bsv's own RNG so this works in both Node and browser builds
+    // (the Node `crypto` import above is undefined in browser context).
+    const bsv = require('../')
+    const lockingScriptHex = bsv.Script.buildPublicKeyHashOut(
+      bsv.Address.fromString(address)
+    ).toHex()
+
     const mockUTXOs = []
-    
     for (let i = 0; i < count; i++) {
-      const txid = crypto.randomBytes(32).toString('hex')
-      const vout = i
-      const script = `76a914${crypto.randomBytes(20).toString('hex')}88ac` // Mock P2PKH script
-      
-      const utxo = {
-        txid,
-        vout,
+      mockUTXOs.push({
+        txid: bsv.crypto.Random.getRandomBuffer(32).toString('hex'),
+        vout: i,
         address,
         satoshis,
-        script
-      }
-      
-      mockUTXOs.push(utxo)
+        script: lockingScriptHex
+      })
     }
-    
     return mockUTXOs
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@smartledger/bsv",
-  "version": "4.0.0",
+  "version": "4.0.1",
   "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",