@smartledger/bsv 4.1.0 → 4.4.0

package/docs/COVENANT_DEVELOPMENT_RESOLVED.md

@@ -136,9 +136,9 @@ node custom_script_signature_test.js
 ## 📦 Installation
 
 ```bash
-npm install smartledger-bsv@4.1.0
+npm install smartledger-bsv@4.2.1
 # or
-npm install @smartledger/bsv@4.1.0
+npm install @smartledger/bsv@4.2.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@4.1.0/bsv-shamir.min.js`
+- **CDN**: `unpkg.com/@smartledger/bsv@4.2.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@4.1.0/bsv-gdaf.min.js`
+- **CDN**: `unpkg.com/@smartledger/bsv@4.2.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@4.1.0/bsv-ltp.min.js`
+- **CDN**: `unpkg.com/@smartledger/bsv@4.2.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@4.1.0/bsv.min.js` |
-| **bsv.bundle.js** | 937KB | Everything in one file | `unpkg.com/@smartledger/bsv@4.1.0/bsv.bundle.js` |
-| **bsv-smartcontract.min.js** | 937KB | Covenant development | `unpkg.com/@smartledger/bsv@4.1.0/bsv-smartcontract.min.js` |
-| **bsv-covenant.min.js** | 913KB | Covenant operations | `unpkg.com/@smartledger/bsv@4.1.0/bsv-covenant.min.js` |
-| **bsv-script-helper.min.js** | 26KB | Custom script tools | `unpkg.com/@smartledger/bsv@4.1.0/bsv-script-helper.min.js` |
-| **bsv-security.min.js** | 26KB | Security enhancements (opt-in helpers — see README › Security) | `unpkg.com/@smartledger/bsv@4.1.0/bsv-security.min.js` |
-| **bsv-ecies.min.js** | 71KB | Encryption | `unpkg.com/@smartledger/bsv@4.1.0/bsv-ecies.min.js` |
-| **bsv-message.min.js** | 26KB | Message signing | `unpkg.com/@smartledger/bsv@4.1.0/bsv-message.min.js` |
-| **bsv-mnemonic.min.js** | 681KB | HD wallets | `unpkg.com/@smartledger/bsv@4.1.0/bsv-mnemonic.min.js` |
-| **🆕 bsv-shamir.min.js** | 432KB | **Secret sharing** | `unpkg.com/@smartledger/bsv@4.1.0/bsv-shamir.min.js` |
-| **🆕 bsv-gdaf.min.js** | 1184KB | **Digital attestation** | `unpkg.com/@smartledger/bsv@4.1.0/bsv-gdaf.min.js` |
-| **🆕 bsv-ltp.min.js** | 1184KB | **Legal tokens** | `unpkg.com/@smartledger/bsv@4.1.0/bsv-ltp.min.js` |
+| **bsv.min.js** | 937KB | Core BSV + SmartContract | `unpkg.com/@smartledger/bsv@4.2.1/bsv.min.js` |
+| **bsv.bundle.js** | 937KB | Everything in one file | `unpkg.com/@smartledger/bsv@4.2.1/bsv.bundle.js` |
+| **bsv-smartcontract.min.js** | 937KB | Covenant development | `unpkg.com/@smartledger/bsv@4.2.1/bsv-smartcontract.min.js` |
+| **bsv-covenant.min.js** | 913KB | Covenant operations | `unpkg.com/@smartledger/bsv@4.2.1/bsv-covenant.min.js` |
+| **bsv-script-helper.min.js** | 26KB | Custom script tools | `unpkg.com/@smartledger/bsv@4.2.1/bsv-script-helper.min.js` |
+| **bsv-security.min.js** | 26KB | Security enhancements (opt-in helpers — see README › Security) | `unpkg.com/@smartledger/bsv@4.2.1/bsv-security.min.js` |
+| **bsv-ecies.min.js** | 71KB | Encryption | `unpkg.com/@smartledger/bsv@4.2.1/bsv-ecies.min.js` |
+| **bsv-message.min.js** | 26KB | Message signing | `unpkg.com/@smartledger/bsv@4.2.1/bsv-message.min.js` |
+| **bsv-mnemonic.min.js** | 681KB | HD wallets | `unpkg.com/@smartledger/bsv@4.2.1/bsv-mnemonic.min.js` |
+| **🆕 bsv-shamir.min.js** | 432KB | **Secret sharing** | `unpkg.com/@smartledger/bsv@4.2.1/bsv-shamir.min.js` |
+| **🆕 bsv-gdaf.min.js** | 1184KB | **Digital attestation** | `unpkg.com/@smartledger/bsv@4.2.1/bsv-gdaf.min.js` |
+| **🆕 bsv-ltp.min.js** | 1184KB | **Legal tokens** | `unpkg.com/@smartledger/bsv@4.2.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@4.1.0/bsv.min.js"></script>
-<script src="https://unpkg.com/@smartledger/bsv@4.1.0/bsv-script-helper.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@4.2.1/bsv.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@4.2.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@4.1.0/bsv.min.js"></script>
-<script src="https://unpkg.com/@smartledger/bsv@4.1.0/bsv-covenant.min.js"></script>
-<script src="https://unpkg.com/@smartledger/bsv@4.1.0/bsv-smartcontract.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@4.2.1/bsv.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@4.2.1/bsv-covenant.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@4.2.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@4.1.0/bsv.min.js"></script>
-<script src="https://unpkg.com/@smartledger/bsv@4.1.0/bsv-ltp.min.js"></script>
-<script src="https://unpkg.com/@smartledger/bsv@4.1.0/bsv-gdaf.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@4.2.1/bsv.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@4.2.1/bsv-ltp.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@4.2.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@4.1.0/bsv.min.js"></script>
-<script src="https://unpkg.com/@smartledger/bsv@4.1.0/bsv-security.min.js"></script>
-<script src="https://unpkg.com/@smartledger/bsv@4.1.0/bsv-shamir.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@4.2.1/bsv.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@4.2.1/bsv-security.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@4.2.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@4.1.0/bsv.bundle.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@4.2.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@4.1.0/bsv.min.js"></script>
+    <script src="https://cdn.jsdelivr.net/npm/@smartledger/bsv@4.2.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@4.1.0
+npm install @smartledger/bsv@4.2.1
 
 # Install with exact version lock
-npm install --save-exact @smartledger/bsv@4.1.0
+npm install --save-exact @smartledger/bsv@4.2.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@4.1.0/bsv.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@4.2.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@4.1.0/bsv.bundle.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@4.2.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@4.1.0/bsv.min.js"></script>
-<script src="https://unpkg.com/@smartledger/bsv@4.1.0/bsv-covenant.min.js"></script>
-<script src="https://unpkg.com/@smartledger/bsv@4.1.0/bsv-smartcontract.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@4.2.1/bsv.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@4.2.1/bsv-covenant.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@4.2.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@4.1.0/bsv.min.js"></script>
-<script src="https://unpkg.com/@smartledger/bsv@4.1.0/bsv-ltp.min.js"></script>
-<script src="https://unpkg.com/@smartledger/bsv@4.1.0/bsv-gdaf.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@4.2.1/bsv.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@4.2.1/bsv-ltp.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@4.2.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@4.1.0/bsv.min.js"></script>
-<script src="https://unpkg.com/@smartledger/bsv@4.1.0/bsv-security.min.js"></script>
-<script src="https://unpkg.com/@smartledger/bsv@4.1.0/bsv-shamir.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@4.2.1/bsv.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@4.2.1/bsv-security.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@4.2.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@4.1.0/bsv.min.js` |
-| **bsv.bundle.js** | 937KB | Everything in one file | `unpkg.com/@smartledger/bsv@4.1.0/bsv.bundle.js` |
-| **bsv-smartcontract.min.js** | 937KB | Complete covenant framework | `unpkg.com/@smartledger/bsv@4.1.0/bsv-smartcontract.min.js` |
-| **bsv-ltp.min.js** | 1184KB | **Legal Token Protocol** | `unpkg.com/@smartledger/bsv@4.1.0/bsv-ltp.min.js` |
-| **bsv-gdaf.min.js** | 1184KB | **Digital Identity & Attestation** | `unpkg.com/@smartledger/bsv@4.1.0/bsv-gdaf.min.js` |
-| **bsv-shamir.min.js** | 432KB | **Threshold Cryptography** | `unpkg.com/@smartledger/bsv@4.1.0/bsv-shamir.min.js` |
-| **bsv-security.min.js** | 26KB | Security enhancements (opt-in helpers — see README › Security) | `unpkg.com/@smartledger/bsv@4.1.0/bsv-security.min.js` |
-| **bsv-mnemonic.min.js** | 681KB | HD wallets | `unpkg.com/@smartledger/bsv@4.1.0/bsv-mnemonic.min.js` |
-| **bsv-ecies.min.js** | 71KB | Encryption | `unpkg.com/@smartledger/bsv@4.1.0/bsv-ecies.min.js` |
-| **bsv-covenant.min.js** | 913KB | Covenant operations | `unpkg.com/@smartledger/bsv@4.1.0/bsv-covenant.min.js` |
-| **bsv-script-helper.min.js** | 26KB | Custom script tools | `unpkg.com/@smartledger/bsv@4.1.0/bsv-script-helper.min.js` |
-| **bsv-message.min.js** | 26KB | Message signing | `unpkg.com/@smartledger/bsv@4.1.0/bsv-message.min.js` |
+| **bsv.min.js** | 937KB | Core BSV + SmartContract | `unpkg.com/@smartledger/bsv@4.2.1/bsv.min.js` |
+| **bsv.bundle.js** | 937KB | Everything in one file | `unpkg.com/@smartledger/bsv@4.2.1/bsv.bundle.js` |
+| **bsv-smartcontract.min.js** | 937KB | Complete covenant framework | `unpkg.com/@smartledger/bsv@4.2.1/bsv-smartcontract.min.js` |
+| **bsv-ltp.min.js** | 1184KB | **Legal Token Protocol** | `unpkg.com/@smartledger/bsv@4.2.1/bsv-ltp.min.js` |
+| **bsv-gdaf.min.js** | 1184KB | **Digital Identity & Attestation** | `unpkg.com/@smartledger/bsv@4.2.1/bsv-gdaf.min.js` |
+| **bsv-shamir.min.js** | 432KB | **Threshold Cryptography** | `unpkg.com/@smartledger/bsv@4.2.1/bsv-shamir.min.js` |
+| **bsv-security.min.js** | 26KB | Security enhancements (opt-in helpers — see README › Security) | `unpkg.com/@smartledger/bsv@4.2.1/bsv-security.min.js` |
+| **bsv-mnemonic.min.js** | 681KB | HD wallets | `unpkg.com/@smartledger/bsv@4.2.1/bsv-mnemonic.min.js` |
+| **bsv-ecies.min.js** | 71KB | Encryption | `unpkg.com/@smartledger/bsv@4.2.1/bsv-ecies.min.js` |
+| **bsv-covenant.min.js** | 913KB | Covenant operations | `unpkg.com/@smartledger/bsv@4.2.1/bsv-covenant.min.js` |
+| **bsv-script-helper.min.js** | 26KB | Custom script tools | `unpkg.com/@smartledger/bsv@4.2.1/bsv-script-helper.min.js` |
+| **bsv-message.min.js** | 26KB | Message signing | `unpkg.com/@smartledger/bsv@4.2.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@4.1.0/bsv.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@4.2.1/bsv.min.js"></script>
 
 <!-- Everything included (937KB) -->
-<script src="https://unpkg.com/@smartledger/bsv@4.1.0/bsv.bundle.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@4.2.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@4.1.0/bsv.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@4.2.1/bsv.min.js"></script>
 
 <!-- Smart contracts (937KB) -->
-<script src="https://unpkg.com/@smartledger/bsv@4.1.0/bsv-smartcontract.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@4.2.1/bsv-smartcontract.min.js"></script>
 
 <!-- Legal tokens (1.16MB) -->
-<script src="https://unpkg.com/@smartledger/bsv@4.1.0/bsv-ltp.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@4.2.1/bsv-ltp.min.js"></script>
 
 <!-- Digital identity (1.16MB) -->
-<script src="https://unpkg.com/@smartledger/bsv@4.1.0/bsv-gdaf.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@4.2.1/bsv-gdaf.min.js"></script>
 
 <!-- Everything (937KB) -->
-<script src="https://unpkg.com/@smartledger/bsv@4.1.0/bsv.bundle.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@4.2.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@4.1.0/bsv.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@4.2.1/bsv.min.js"></script>
 
 <!-- Add smart contracts when ready -->
-<script src="https://unpkg.com/@smartledger/bsv@4.1.0/bsv-smartcontract.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@4.2.1/bsv-smartcontract.min.js"></script>
 
 <!-- Add advanced features as needed -->
-<script src="https://unpkg.com/@smartledger/bsv@4.1.0/bsv-ltp.min.js"></script>
-<script src="https://unpkg.com/@smartledger/bsv@4.1.0/bsv-gdaf.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@4.2.1/bsv-ltp.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@4.2.1/bsv-gdaf.min.js"></script>
 
 <!-- Everything in one file -->
-<script src="https://unpkg.com/@smartledger/bsv@4.1.0/bsv.bundle.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@4.2.1/bsv.bundle.js"></script>
 ```
 
 ## 🔍 **Testing Your Migration**

package/lib/script/interpreter.js

@@ -701,7 +701,7 @@ Interpreter.prototype.step = function () {
           return true
         }
         break
-        
+
       // Monolith opcodes are now enabled by default in SmartLedger BSV
       // These were activated in May 2018 and are part of standard BSV consensus
       case Opcode.OP_DIV:
@@ -715,7 +715,7 @@ Interpreter.prototype.step = function () {
       case Opcode.OP_NUM2BIN:
         // These opcodes are now always enabled - no flag required
         return false
-        
+
       default:
         break
     }
@@ -1757,6 +1757,56 @@ Interpreter.prototype.step = function () {
         this.stack[this.stack.length - 1] = n1.slice(position)
         break
 
+      case Opcode.OP_LEFT:
+      case Opcode.OP_RIGHT:
+        // (in size -- out)  OP_LEFT keeps the first `size` bytes; OP_RIGHT the last.
+        // Re-enabled string opcodes (BSV Chronicle). Original Satoshi semantics.
+        if (this.stack.length < 2) {
+          this.errstr = 'SCRIPT_ERR_INVALID_STACK_OPERATION'
+          return false
+        }
+        buf1 = stacktop(-2)
+        n = BN.fromScriptNumBuffer(stacktop(-1), fRequireMinimal).toNumber()
+        if (n < 0) {
+          this.errstr = 'SCRIPT_ERR_INVALID_NUMBER_RANGE'
+          return false
+        }
+        if (n > buf1.length) {
+          n = buf1.length
+        }
+        this.stack.pop()
+        if (opcodenum === Opcode.OP_LEFT) {
+          this.stack[this.stack.length - 1] = Buffer.from(buf1).slice(0, n)
+        } else {
+          this.stack[this.stack.length - 1] = Buffer.from(buf1).slice(buf1.length - n)
+        }
+        break
+
+      case Opcode.OP_SUBSTR:
+        // (in begin size -- out)  out = in[begin : begin + size]
+        // Re-enabled string opcode (BSV Chronicle). Original Satoshi semantics.
+        if (this.stack.length < 3) {
+          this.errstr = 'SCRIPT_ERR_INVALID_STACK_OPERATION'
+          return false
+        }
+        buf1 = stacktop(-3)
+        var subSize = BN.fromScriptNumBuffer(stacktop(-1), fRequireMinimal).toNumber()
+        var subBegin = BN.fromScriptNumBuffer(stacktop(-2), fRequireMinimal).toNumber()
+        if (subBegin < 0 || subSize < 0) {
+          this.errstr = 'SCRIPT_ERR_INVALID_NUMBER_RANGE'
+          return false
+        }
+        if (subBegin > buf1.length) {
+          subBegin = buf1.length
+        }
+        if (subBegin + subSize > buf1.length) {
+          subSize = buf1.length - subBegin
+        }
+        this.stack.pop()
+        this.stack.pop()
+        this.stack[this.stack.length - 1] = Buffer.from(buf1).slice(subBegin, subBegin + subSize)
+        break
+
         //
         // Conversion operations
         //

package/lib/smart_contract/covenant_helpers.js

@@ -0,0 +1,119 @@
+'use strict'
+/**
+ * SmartContract covenant helpers
+ * ==============================
+ *
+ * Shared utilities for building and verifying custom locking scripts &
+ * OP_PUSH_TX covenants: a consensus-flag verify() harness, raw BIP-143 preimage
+ * access, signing, and fund/spend scaffolding. Used by ./pushtx, ./pels, ./token
+ * and ./locks.
+ */
+
+var bsv = require('../..')
+var BN = require('../crypto/bn')
+var Hash = require('../crypto/hash')
+var Signature = require('../crypto/signature')
+
+// SIGHASH_ALL | SIGHASH_FORKID — the BSV default these covenants are built for.
+var SIGHASH = Signature.SIGHASH_ALL | Signature.SIGHASH_FORKID // 0x41
+
+// Post-Genesis consensus flags (big numbers, OP_CAT/OP_SPLIT/OP_MUL, FORKID,
+// CLTV/CSV). LOW_S is enforced: the OP_PUSH_TX grind produces a canonical
+// (low-S) in-script signature, so these covenants meet mainnet standardness.
+function flags () {
+  var I = bsv.Script.Interpreter
+  return I.SCRIPT_VERIFY_P2SH |
+    I.SCRIPT_VERIFY_STRICTENC |
+    I.SCRIPT_VERIFY_DERSIG |
+    I.SCRIPT_VERIFY_LOW_S |
+    I.SCRIPT_VERIFY_CHECKLOCKTIMEVERIFY |
+    I.SCRIPT_VERIFY_CHECKSEQUENCEVERIFY |
+    I.SCRIPT_ENABLE_SIGHASH_FORKID |
+    I.SCRIPT_ENABLE_MAGNETIC_OPCODES |
+    I.SCRIPT_ENABLE_MONOLITH_OPCODES
+}
+
+/**
+ * Opt into post-Genesis script limits (needed by OP_PUSH_TX covenants).
+ * Thin wrapper over Interpreter.useGenesisLimits (added in 4.1.0).
+ */
+function enableGenesis (max) {
+  return bsv.Script.Interpreter.useGenesisLimits(max)
+}
+
+/**
+ * Verify an unlocking script against a locking script through the consensus
+ * interpreter. @returns {{ok:boolean, err:string}}
+ */
+function verify (unlockingScript, lockingScript, opts) {
+  opts = opts || {}
+  var interp = new bsv.Script.Interpreter()
+  var ok = interp.verify(
+    unlockingScript,
+    lockingScript,
+    opts.tx || new bsv.Transaction(),
+    opts.inputIndex || 0,
+    opts.flags || flags(),
+    new BN(opts.satoshis || 0)
+  )
+  return { ok: ok, err: interp.errstr || '' }
+}
+
+/** Raw BIP-143 preimage (the serialization that is double-SHA256'd), not the digest. */
+function rawPreimage (tx, inputIndex, lockingScript, satoshis, sighashType) {
+  return bsv.Transaction.sighash.sighashPreimage(
+    tx, sighashType || SIGHASH, inputIndex, lockingScript, new BN(satoshis))
+}
+
+/** Sighash digest = HASH256(rawPreimage) — useful for asserting OP_PUSH_TX linkage in JS. */
+function sighashDigest (tx, inputIndex, lockingScript, satoshis, sighashType) {
+  return Hash.sha256sha256(rawPreimage(tx, inputIndex, lockingScript, satoshis, sighashType))
+}
+
+/** DER+sighash-byte signature over `lockingScript` for `inputIndex`. */
+function signInput (tx, privateKey, inputIndex, lockingScript, satoshis, sighashType) {
+  sighashType = sighashType || SIGHASH
+  var sig = bsv.Transaction.sighash.sign(tx, privateKey, sighashType, inputIndex, lockingScript, new BN(satoshis))
+  return Buffer.concat([sig.toDER(), Buffer.from([sighashType])])
+}
+
+/**
+ * Build a funding tx paying `satoshis` into `lockingScript`, plus a spending tx
+ * consuming it with the supplied outputs. Returns { funding, spend }; the caller
+ * sets spend.inputs[0] script.
+ */
+function fundAndSpend (lockingScript, satoshis, opts) {
+  opts = opts || {}
+  var funding = new bsv.Transaction().addOutput(
+    new bsv.Transaction.Output({ script: lockingScript, satoshis: satoshis }))
+  var spend = new bsv.Transaction()
+  spend.addInput(
+    new bsv.Transaction.Input({ prevTxId: funding.hash, outputIndex: 0, script: bsv.Script.empty() }),
+    lockingScript, satoshis)
+  if (opts.outputs) opts.outputs.forEach(function (o) { spend.addOutput(o) })
+  return { funding: funding, spend: spend }
+}
+
+/** A P2PKH Output object for an address or public key. */
+function p2pkhOutput (addressOrPubKey, satoshis) {
+  var addr = addressOrPubKey.toAddress ? addressOrPubKey.toAddress() : addressOrPubKey
+  return new bsv.Transaction.Output({ script: bsv.Script.buildPublicKeyHashOut(addr), satoshis: satoshis })
+}
+
+/** Minimal little-endian script-number Buffer (push as data to put a number on-stack). */
+function scriptNum (n) {
+  return new BN(n).toScriptNumBuffer()
+}
+
+module.exports = {
+  SIGHASH: SIGHASH,
+  flags: flags,
+  enableGenesis: enableGenesis,
+  verify: verify,
+  rawPreimage: rawPreimage,
+  sighashDigest: sighashDigest,
+  signInput: signInput,
+  fundAndSpend: fundAndSpend,
+  p2pkhOutput: p2pkhOutput,
+  scriptNum: scriptNum
+}

package/lib/smart_contract/index.js

@@ -36,7 +36,36 @@ var SmartContract = {
   OpcodeMap: require('./opcode_map'),
   ScriptUtils: require('./script_utils'),
   StackExaminer: require('./stack_examiner'),
-  ScriptInterpreter: require('./script_interpreter')
+  ScriptInterpreter: require('./script_interpreter'),
+
+  // Interpreter-verified custom locking scripts & OP_PUSH_TX covenants (v4.2.0)
+  CovenantHelpers: require('./covenant_helpers'),
+  Locks: require('./locks'),
+  PushTx: require('./pushtx'),
+  PELS: require('./pels'),
+  Token: require('./token')
+}
+
+// --- Covenant convenience API (v4.2.0) ---
+// Opt into post-Genesis script limits (required by OP_PUSH_TX covenants).
+SmartContract.enableGenesis = function (max) {
+  return SmartContract.CovenantHelpers.enableGenesis(max)
+}
+// Verify an unlocking/locking pair through the consensus interpreter.
+SmartContract.verifyScript = function (unlockingScript, lockingScript, opts) {
+  return SmartContract.CovenantHelpers.verify(unlockingScript, lockingScript, opts)
+}
+// Perpetually Enforcing Locking Script: every spend recreates the same script.
+SmartContract.perpetualCovenant = function (fee) {
+  return SmartContract.PELS.pelsCovenant(fee)
+}
+// Stateful ownership token (NFT) locking script.
+SmartContract.ownershipToken = function (fee, ownerHash) {
+  return SmartContract.Token.ownershipToken(fee, ownerHash)
+}
+// OP_PUSH_TX value/output covenant: coins can only go where the covenant says.
+SmartContract.valueCovenant = function (expectedHashOutputs) {
+  return SmartContract.PushTx.valueCovenant(expectedHashOutputs)
 }
 
 // Convenience constructor methods

package/lib/smart_contract/locks.js

@@ -0,0 +1,101 @@
+'use strict'
+/**
+ * SmartContract.Locks — basic interpreter-verified lock primitives.
+ * Each factory returns { lock: Script, unlock: fn, meta }.
+ */
+
+var bsv = require('../..')
+var Hash = require('../crypto/hash')
+var H = require('./covenant_helpers')
+
+var Script = bsv.Script
+var Opcode = bsv.Opcode
+var signInput = H.signInput
+var n = H.scriptNum
+
+/** Hash-lock: reveal a preimage whose SHA-256 matches a digest. */
+function hashLock (secret) {
+  var digest = Hash.sha256(secret)
+  var lock = new Script().add(Opcode.OP_SHA256).add(digest).add(Opcode.OP_EQUAL)
+  return {
+    lock: lock,
+    meta: { name: 'hash-lock', digest: digest.toString('hex') },
+    unlock: function (_spend, _sats, preimage) { return new Script().add(preimage || secret) }
+  }
+}
+
+/** P2PKH baseline. */
+function p2pkh (privateKey) {
+  var pub = privateKey.toPublicKey()
+  var lock = Script.buildPublicKeyHashOut(pub.toAddress())
+  return {
+    lock: lock,
+    meta: { name: 'p2pkh', address: pub.toAddress().toString() },
+    unlock: function (spend, sats) {
+      return new Script().add(signInput(spend, privateKey, 0, lock, sats)).add(pub.toBuffer())
+    }
+  }
+}
+
+/** CLTV absolute time-lock: <locktime> CLTV DROP <pk> CHECKSIG. */
+function timeLockCLTV (privateKey, locktime) {
+  var pub = privateKey.toPublicKey()
+  var lock = new Script()
+    .add(n(locktime)).add(Opcode.OP_CHECKLOCKTIMEVERIFY).add(Opcode.OP_DROP)
+    .add(pub.toBuffer()).add(Opcode.OP_CHECKSIG)
+  return {
+    lock: lock,
+    meta: { name: 'cltv-timelock', locktime: locktime },
+    // Caller must set spend.nLockTime >= locktime and input sequence < 0xffffffff.
+    unlock: function (spend, sats) { return new Script().add(signInput(spend, privateKey, 0, lock, sats)) }
+  }
+}
+
+/** m-of-n multisig. */
+function multisig (m, privateKeys) {
+  var pubs = privateKeys.map(function (k) { return k.toPublicKey() })
+  var lock = new Script().add(Opcode['OP_' + m])
+  pubs.forEach(function (p) { lock.add(p.toBuffer()) })
+  lock.add(Opcode['OP_' + pubs.length]).add(Opcode.OP_CHECKMULTISIG)
+  return {
+    lock: lock,
+    meta: { name: m + '-of-' + pubs.length + '-multisig' },
+    unlock: function (spend, sats, signWith) {
+      signWith = signWith || privateKeys.slice(0, m)
+      var s = new Script().add(Opcode.OP_0)
+      signWith.forEach(function (k) { s.add(signInput(spend, k, 0, lock, sats)) })
+      return s
+    }
+  }
+}
+
+/** HTLC: hash-OR-timeout. */
+function htlc (opts) {
+  var digest = Hash.sha256(opts.secret)
+  var lock = new Script()
+    .add(Opcode.OP_IF)
+    .add(Opcode.OP_SHA256).add(digest).add(Opcode.OP_EQUALVERIFY)
+    .add(opts.receiver.toPublicKey().toBuffer()).add(Opcode.OP_CHECKSIG)
+    .add(Opcode.OP_ELSE)
+    .add(n(opts.timeout)).add(Opcode.OP_CHECKLOCKTIMEVERIFY).add(Opcode.OP_DROP)
+    .add(opts.sender.toPublicKey().toBuffer()).add(Opcode.OP_CHECKSIG)
+    .add(Opcode.OP_ENDIF)
+  return {
+    lock: lock,
+    meta: { name: 'htlc', digest: digest.toString('hex'), timeout: opts.timeout },
+    unlockClaim: function (spend, sats) {
+      return new Script().add(signInput(spend, opts.receiver, 0, lock, sats)).add(opts.secret).add(Opcode.OP_1)
+    },
+    unlockRefund: function (spend, sats) {
+      return new Script().add(signInput(spend, opts.sender, 0, lock, sats)).add(Opcode.OP_0)
+    }
+  }
+}
+
+module.exports = {
+  hashLock: hashLock,
+  p2pkh: p2pkh,
+  timeLockCLTV: timeLockCLTV,
+  multisig: multisig,
+  htlc: htlc
+}