smartledger-bsv 4.0.1 → 4.1.0

package/CHANGELOG.md

@@ -5,6 +5,75 @@ All notable changes to SmartLedger-BSV will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [4.1.0] - 2026-06-07
+
+### Added
+
+- **`Interpreter.useGenesisLimits([max])` — one-call opt-in for
+  post-Genesis BSV consensus.** The bundled `Script.Interpreter`
+  hardcoded the *pre-Genesis* consensus caps that BSV removed at the
+  Genesis upgrade (February 2020): 520-byte stack elements, 4-byte
+  script numbers, 201 non-push opcodes per script. Those caps make this
+  library's own flagship features impossible to evaluate — OP_PUSH_TX
+  covenants push a ~585-byte preimage element, do 32-byte modular
+  arithmetic (`OP_ADD`/`OP_MOD`), and run a few hundred opcodes.
+
+  ```js
+  // Default: bound the limits to a safe ceiling.
+  // 64 KB covers every covenant pattern seen in production and blocks
+  // memory-exhaustion via oversized pushes from untrusted scripts.
+  bsv.Script.Interpreter.useGenesisLimits(64 * 1024)
+
+  // Or fully unbounded (~2 GB) — only safe for trusted scripts:
+  // bsv.Script.Interpreter.useGenesisLimits()
+  ```
+
+  Defaults are unchanged out of the box (520 / 4 / 201) — existing
+  consumers see zero behavior change unless they opt in. The call
+  mutates static properties on the `Interpreter` constructor and
+  therefore affects every subsequent `new Interpreter()` in the
+  process; treat it as an app-startup setting, not per-request.
+
+- **`Interpreter.MAX_OPS_PER_SCRIPT`** exposed as a named constant
+  (= 201). Replaces the two hardcoded `> 201` checks in `Interpreter.step`.
+
+- **`bsv.d.ts`** now types `Interpreter.MAX_SCRIPT_ELEMENT_SIZE`,
+  `MAXIMUM_ELEMENT_SIZE`, `MAX_OPS_PER_SCRIPT`, and `useGenesisLimits()`.
+
+### Fixed
+
+- **`Interpreter.MAXIMUM_ELEMENT_SIZE` was a dead knob in the numeric
+  opcodes.** The constant was defined as `4` but never threaded into the
+  `BN.fromScriptNumBuffer(buf, fRequireMinimal, size)` calls in
+  `OP_ADD`/`OP_SUB`/`OP_MUL`/`OP_DIV`/`OP_MOD`/`OP_BOOLAND`/`OP_BOOLOR`/
+  `OP_NUMEQUAL`/`OP_NUMEQUALVERIFY`/`OP_NUMNOTEQUAL`/`OP_LESSTHAN`/
+  `OP_GREATERTHAN`/`OP_LESSTHANOREQUAL`/`OP_GREATERTHANOREQUAL`/`OP_MIN`/
+  `OP_MAX` (binary) and `OP_WITHIN` (ternary). The 3rd `size` argument was
+  always omitted, so BN fell back to its own 4-byte default — raising
+  `Interpreter.MAXIMUM_ELEMENT_SIZE` above 4 had no effect. Now threaded
+  through, so the knob actually does what its name implies.
+
+### Tests
+
+- Added `test/script/genesis_limits.js` (6 tests) covering defaults,
+  the lift, rejection of >4-byte arithmetic and >201 opcodes under
+  defaults, and acceptance of both after `useGenesisLimits()`. Full
+  suite: **4178 passing, 0 failing**.
+
+### Docs
+
+- README §"Evaluating covenants locally" — one-paragraph mention of
+  the new API in the covenant/smart-contract section.
+- JSDoc on `useGenesisLimits` calls out the process-wide-mutation
+  semantics and recommends bounded ceilings for untrusted input.
+- CDN/install refs bumped `@4.0.1` → `@4.1.0` across README + 6 docs
+  files.
+
+### Semver
+
+Minor bump — purely additive: a new public method and a fixed-but-was-
+dead constant. No existing API or default behavior changes.
+
 ## [4.0.1] - 2026-05-31
 
 ### Deprecated

package/README.md

@@ -2,7 +2,7 @@
 
 **🚀 Complete Bitcoin SV Development Framework with W3C Verifiable Credentials, DID:web, Legal Compliance, and 16 Flexible Loading Options**
 
-[![Version](https://img.shields.io/badge/version-4.0.1-blue.svg)](https://www.npmjs.com/package/@smartledger/bsv)
+[![Version](https://img.shields.io/badge/version-4.1.0-blue.svg)](https://www.npmjs.com/package/@smartledger/bsv)
 [![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
 [![BSV](https://img.shields.io/badge/BSV-Compatible-orange.svg)](https://bitcoinsv.com/)
 [![Modular](https://img.shields.io/badge/Loading-Modular-purple.svg)](#loading-options)
@@ -25,8 +25,8 @@ The most comprehensive and flexible Bitcoin SV library available. **In v3.4.x**:
 ### **Quick Start - Issue Your First Verifiable Credential**
 
 ```bash
-# Install SmartLedger BSV v4.0.1
-npm install @smartledger/bsv@4.0.1
+# Install SmartLedger BSV v4.1.0
+npm install @smartledger/bsv@4.1.0
 
 # Initialize DID:web issuer (generates ES256 keys)
 npx smartledger-bsv didweb init --domain example.com --alg ES256
@@ -135,42 +135,42 @@ console.log('Status:', status) // 'revoked'
 ### **Core Modules**
 | Module | Size | Use Case | CDN |
 |--------|------|----------|-----|
-| **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.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` |
 
 ### **🆕 W3C Verifiable Credentials (v3.4.x)**
 | Module | Size | Use Case | CDN |
 |--------|------|----------|-----|
-| **🟢 bsv-didweb.min.js** | 419KB | **DID:web generation** | `unpkg.com/@smartledger/bsv@4.0.1/bsv-didweb.min.js` |
-| **🟢 bsv-vcjwt.min.js** | 419KB | **VC-JWT issue/verify** | `unpkg.com/@smartledger/bsv@4.0.1/bsv-vcjwt.min.js` |
-| **🟢 bsv-statuslist.min.js** | 487KB | **StatusList2021 revocation** | `unpkg.com/@smartledger/bsv@4.0.1/bsv-statuslist.min.js` |
-| **🟢 bsv-anchor.min.js** | 418KB | **BSV anchoring (hash-only)** | `unpkg.com/@smartledger/bsv@4.0.1/bsv-anchor.min.js` |
+| **🟢 bsv-didweb.min.js** | 419KB | **DID:web generation** | `unpkg.com/@smartledger/bsv@4.1.0/bsv-didweb.min.js` |
+| **🟢 bsv-vcjwt.min.js** | 419KB | **VC-JWT issue/verify** | `unpkg.com/@smartledger/bsv@4.1.0/bsv-vcjwt.min.js` |
+| **🟢 bsv-statuslist.min.js** | 487KB | **StatusList2021 revocation** | `unpkg.com/@smartledger/bsv@4.1.0/bsv-statuslist.min.js` |
+| **🟢 bsv-anchor.min.js** | 418KB | **BSV anchoring (hash-only)** | `unpkg.com/@smartledger/bsv@4.1.0/bsv-anchor.min.js` |
 
 ### **Smart Contract & Development**
 | Module | Size | Use Case | CDN |
 |--------|------|----------|-----|
-| **bsv-smartcontract.min.js** | 937KB | Complete covenant framework | `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 | `unpkg.com/@smartledger/bsv@4.0.1/bsv-security.min.js` |
+| **bsv-smartcontract.min.js** | 937KB | Complete covenant framework | `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 | `unpkg.com/@smartledger/bsv@4.1.0/bsv-security.min.js` |
 
 ### **Legal & Compliance**
 | Module | Size | Use Case | CDN |
 |--------|------|----------|-----|
-| **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-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` |
 
 ### **Advanced Cryptography**
 | Module | Size | Use Case | CDN |
 |--------|------|----------|-----|
-| **bsv-shamir.min.js** | 432KB | Threshold Cryptography | `unpkg.com/@smartledger/bsv@4.0.1/bsv-shamir.min.js` |
+| **bsv-shamir.min.js** | 432KB | Threshold Cryptography | `unpkg.com/@smartledger/bsv@4.1.0/bsv-shamir.min.js` |
 
 ### **Utilities**
 | Module | Size | Use Case | CDN |
 |--------|------|----------|-----|
-| **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-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` |
 
 ## ⚡ **2-Minute Quick Start**
 
@@ -181,7 +181,7 @@ Get started with Bitcoin SV development in under 2 minutes:
 npm install @smartledger/bsv
 
 # Or include in HTML
-<script src="https://unpkg.com/@smartledger/bsv@4.0.1/bsv.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@4.1.0/bsv.min.js"></script>
 ```
 
 > **🔧 v3.4.x:** Legally-recognizable W3C Verifiable Credentials with DID:web + VC-JWT toolkit. ES256/ES256K support, StatusList2021 revocation, and privacy-preserving BSV anchoring. Complete CLI tooling included! v3.4.1 ensures these bundles ship to npm consumers; see CHANGELOG.
@@ -276,8 +276,8 @@ const covenant = bsv.SmartContract.createCovenantBuilder()
 
 ### 🔧 **Basic Development** (~963KB total)
 ```html
-<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>
+<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>
   const privateKey = new bsv.PrivateKey();
   const utxos = new bsv.SmartContract.UTXOGenerator().createRealUTXOs(2, 100000);
@@ -286,9 +286,9 @@ const covenant = bsv.SmartContract.createCovenantBuilder()
 
 ### 🔒 **Smart Contract Development** (~2.7MB total — each bundle re-embeds core BSV)
 ```html
-<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 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>
   const covenant = bsv.SmartContract.createCovenantBuilder()
     .extractField('amount').push(50000).greaterThanOrEqual().verify().build();
@@ -298,9 +298,9 @@ const covenant = bsv.SmartContract.createCovenantBuilder()
 
 ### 🆕 **Legal & Identity Development** (~3.2MB total — each bundle re-embeds core BSV)
 ```html
-<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 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>
   // Legal Token Protocol
   const propertyToken = bsv.createPropertyToken({
@@ -314,9 +314,9 @@ const covenant = bsv.SmartContract.createCovenantBuilder()
 
 ### 🆕 **Security & Cryptography** (~1.4MB total)
 ```html
-<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 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>
   // Threshold Cryptography
   const shares = bsv.splitSecret('my_secret_key', 5, 3); // 5 shares, 3 needed
@@ -328,7 +328,7 @@ const covenant = bsv.SmartContract.createCovenantBuilder()
 
 ### 🎯 **Everything Bundle** (937KB)
 ```html
-<script src="https://unpkg.com/@smartledger/bsv@4.0.1/bsv.bundle.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@4.1.0/bsv.bundle.js"></script>
 <script>
   // Everything available immediately
   const shares = bsv.splitSecret('secret', 5, 3);           // Shamir Secret Sharing
@@ -408,8 +408,8 @@ const contractTx = covenant.createCovenantTransaction({
 
 #### 1. **Minimal Setup** - Core + Script Helper (~963KB)
 ```html
-<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>
+<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>
   const tx = new bsv.Transaction();
   const sig = bsvScriptHelper.createSignature(tx, privateKey, 0, script, satoshis);
@@ -418,9 +418,9 @@ const contractTx = covenant.createCovenantTransaction({
 
 #### 2. **DeFi Development** - Core + Covenants + Debug (~2.7MB — each bundle re-embeds core BSV)
 ```html
-<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 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>
   const covenant = new bsvCovenant.CovenantInterface();
   const debugInfo = SmartContract.interpretScript(script);
@@ -430,8 +430,8 @@ const contractTx = covenant.createCovenantTransaction({
 
 #### 3. **Security First** - Core + Enhanced Security (~963KB)
 ```html
-<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.1.0/bsv.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@4.1.0/bsv-security.min.js"></script>
 <script>
   const verified = bsvSecurity.SmartVerify.verify(signature, hash, publicKey);
   const enhanced = bsvSecurity.EllipticFixed.createSignature(privateKey, hash);
@@ -440,7 +440,7 @@ const contractTx = covenant.createCovenantTransaction({
 
 #### 4. **Everything Bundle** - One File Solution (937KB)
 ```html
-<script src="https://unpkg.com/@smartledger/bsv@4.0.1/bsv.bundle.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@4.1.0/bsv.bundle.js"></script>
 <script>
   // Everything available under bsv namespace
   const keys = bsv.SmartLedgerBundle.generateKeys();
@@ -651,6 +651,37 @@ const pels = covenant.createAdvancedCovenant('perpetual', {
 });
 ```
 
+### Evaluating covenants locally — `Interpreter.useGenesisLimits()` (v4.1.0+)
+
+The bundled `Script.Interpreter` defaults to **pre-Genesis** BSV consensus
+caps — 520-byte stack elements, 4-byte script numbers, 201 opcodes per
+script — which BSV removed at the Genesis upgrade (Feb 2020). Those caps
+make it impossible to evaluate this library's own flagship features:
+OP_PUSH_TX covenants push a ~585-byte preimage, do 32-byte modular
+arithmetic, and run a few hundred opcodes.
+
+Opt into post-Genesis rules with a single call at app startup:
+
+```javascript
+const bsv = require('@smartledger/bsv');
+
+// Default: bound the limits to a safe ceiling (covers every covenant
+// pattern seen in production, blocks oversized-push memory DoS).
+bsv.Script.Interpreter.useGenesisLimits(64 * 1024);
+
+// Or, for fully unbounded (~2 GB) — only safe for trusted scripts:
+// bsv.Script.Interpreter.useGenesisLimits();
+
+// Now OP_PUSH_TX covenants verify locally:
+const interp = new bsv.Script.Interpreter();
+const ok = interp.verify(unlockScript, lockScript, tx, 0, flags, satoshisBN);
+```
+
+This is a **process-wide** setting — once called, every subsequent
+`new Interpreter()` runs with lifted caps. Defaults are unchanged out of
+the box; if you don't call `useGenesisLimits()`, behavior is identical
+to pre-v4.1.0.
+
 ## 🛠️ Custom Scripts
 
 ### Multi-signature Scripts