@smartledger/bsv 9.0.0 → 9.1.0

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

package/docs/proposals/10.0.0-package-split.md

@@ -0,0 +1,131 @@
+# Proposal: split the package for 10.0.0
+
+Status: draft, for discussion. Nothing here ships in 9.x.
+
+## The problem, measured
+
+`@smartledger/bsv` is currently a Bitcoin library, a W3C VC-JWT toolkit, a
+DID:web resolver, a legal-token protocol and an attestation framework in one
+install. The cost is paid by everyone, including the majority who want one of
+those things.
+
+Requiring the root to get `Script`:
+
+| | modules | time | heap |
+|---|---|---|---|
+| `require('@smartledger/bsv')` | 129 | 270ms | 12.7MB |
+| `require('@smartledger/bsv/lib/script')` | 24 | 106ms | — |
+
+Per subsystem, loaded alone:
+
+| subsystem | modules |
+|---|---|
+| `lib/script` | 24 |
+| `lib/transaction` | 40 |
+| `lib/covenant` | 43 |
+| `lib/ltp` | 48 |
+| `lib/smart_contract` | 62 |
+| `lib/gdaf` | 65 |
+
+Two things make this worse than the numbers suggest:
+
+1. **Nothing tree-shakes.** `index.mjs` is a named-export wrapper over the CJS
+   build, so a bundler that sees `import { Script }` still pulls GDAF and LTP
+   into the browser bundle. The subpaths in `exports` are the only escape, and
+   they are not what the README teaches.
+2. **The npm listing has to describe all of it.** A BSV script developer
+   searching npm reads a description that leads with legal tokens and
+   credentials. The audience most likely to adopt is the one least addressed.
+
+The subpath exports already work and already carry the fix. What is missing is
+that the *default* path is the expensive one.
+
+## Shape
+
+Five packages, one repository, published together.
+
+| package | contains | approx modules |
+|---|---|---|
+| `@smartledger/bsv-core` | keys, addresses, script, transaction, block, SPV, crypto, encoding | ~45 |
+| `@smartledger/bsv-script` | `SmartContract`, covenants, OP_PUSH_TX, PELS, ordinals, NotaryHash, script helper | ~62 |
+| `@smartledger/bsv-crypto` | ECIES, Message, Mnemonic, Shamir | ~30 |
+| `@smartledger/bsv-vc` | DID:web, VC-JWT, StatusList, GDAF, Anchor | ~65 |
+| `@smartledger/bsv-ltp` | Legal Token Protocol | ~48 |
+| `@smartledger/bsv` | **meta-package**: depends on all five, re-exports everything | unchanged |
+
+The meta-package is the whole compatibility story. `require('@smartledger/bsv')`
+keeps returning exactly what it returns today, including the ~74 flat
+convenience functions (`createDID`, `prepareRightToken`, …) that currently sit
+at top level. Nobody's install moves.
+
+## Sequencing
+
+The split is a breaking change for anyone who deep-requires `lib/**`, and it
+cannot share a release with a stability promise. It also must not become the
+seventh major in a year. So:
+
+**9.x (now → 2027-09-01)** — nothing changes. Optionally, the new packages are
+published *additively* during this window: `bsv-core` and `bsv-script` go out as
+real packages, `@smartledger/bsv` starts depending on them internally, and its
+public surface is unchanged. Consumers who want the small thing can adopt early;
+consumers who do nothing notice nothing. The API surface guard
+(`test/api_surface.js`) proves the surface held.
+
+**10.0.0 (2027-09 or later)** — the meta-package remains and keeps working. What
+breaks is only:
+
+- deep requires past the declared `exports` (already excluded by STABILITY.md)
+- the three near-duplicate ~1041KB bundles, if they are dropped in the same
+  release
+
+**Never** — removing the meta-package. It costs almost nothing to maintain once
+the split exists, and removing it would strand every existing install for no
+benefit.
+
+## What this fixes that subpaths alone do not
+
+Subpath exports already let a careful consumer load 24 modules instead of 129.
+Three things they cannot fix:
+
+1. **The default.** Most consumers write `require('@smartledger/bsv')` because
+   that is what the README shows. Making the small package a separate install
+   makes the cheap path the obvious one.
+2. **npm positioning.** A package can only have one description and one keyword
+   set. `bsv-script` can say "OP_PUSH_TX covenants and an interpreter-verified
+   script engine" without competing with credentials for the same 15 keywords.
+3. **Tree-shaking.** Separate packages can ship real ESM with `sideEffects:
+   false`, which the current CJS-wrapper cannot.
+
+## Open questions
+
+- **Do `bsv-core` and `bsv-script` merge?** The script engine is the
+  differentiator and splitting it from `Transaction` may be an artificial line —
+  a covenant author needs both. Merging gives one ~62-module package that is
+  still less than half the current root. I lean toward merging.
+- **Version alignment.** Lockstep versioning across all six is simplest to
+  reason about and wastes version numbers on packages that did not change.
+  Independent versioning is more honest and much harder to support. Lockstep
+  is probably right for a team this size.
+- **The three ~1041KB bundles.** `bsv.min.js`, `bsv.bundle.js` and
+  `bsv-gdaf.min.js` are byte-comparable supersets. They are documented CDN
+  entries, so removing them breaks floating `@latest` URLs — which is why they
+  survive 9.x untouched. 10.0.0 is the moment to consolidate, with the old names
+  kept as redirects for one major if the CDN allows it.
+- **Does the credential CLI move?** `bin/cli.js` is mostly credential
+  workflows. It probably belongs with `bsv-vc`, which means the meta-package
+  either loses the `smartledger-bsv` binary or keeps a thin shim.
+
+## What would make this a bad idea
+
+Worth stating plainly, because the answer might be no.
+
+Six packages is six release processes, six changelogs and a lockfile matrix, for
+a maintainer count in the low single digits. If the credentials and LTP
+subsystems have real users who install the root package deliberately — not
+incidentally — then the current arrangement is serving them and the only genuine
+problem is npm positioning, which a rewritten description already improved.
+
+Before committing to this, the number worth having is **how many installs use
+only the Bitcoin surface**. If that is most of them, split. If the install base
+is genuinely using credentials alongside Bitcoin primitives, keep one package,
+fix the ESM wrapper so it tree-shakes, and stop there.

package/index.js

@@ -105,6 +105,11 @@ bsv.encoding.Varint = require('./lib/encoding/varint')
 bsv.util = {}
 bsv.util.js = require('./lib/util/js')
 bsv.util.preconditions = require('./lib/util/preconditions')
+// Exposed so the deprecation notices have an off switch that does not require an
+// environment variable. STABILITY.md documents BSV_NO_DEPRECATION_WARNINGS=1, which a
+// browser consumer cannot set; without a programmatic control they had no way to
+// silence a notice at all. `fired()` also lets tooling read what a run triggered.
+bsv.util.deprecate = require('./lib/util/deprecate')
 
 // errors thrown by the library
 bsv.errors = require('./lib/errors')

package/lib/block/merkleblock.js

@@ -8,6 +8,7 @@ var Hash = require('../crypto/hash')
 var Transaction = require('../transaction')
 var errors = require('../errors')
 var $ = require('../util/preconditions')
+var deprecate = require('../util/deprecate')
 
 /**
  * Instantiate a MerkleBlock from a Buffer, JSON object, or Object with
@@ -148,14 +149,27 @@ MerkleBlock.prototype.validMerkleTree = function validMerkleTree () {
 }
 
 /**
- * WARNING: This method is deprecated. Use filteredTxsHash instead.
+ * @deprecated Misspelling of `filteredTxsHash` (the `e` is missing). Identical
+ * behaviour; this delegates.
+ *
+ * It threw rather than delegating, which made a typo fix a breaking change for
+ * anyone who had written the typo. Restoring it costs nothing: the name is
+ * unambiguous, there is exactly one thing it can mean, and no caller can be
+ * harmed by getting what they asked for. Contrast `HDPrivateKey#derive`, which
+ * keeps throwing because its replacements return DIFFERENT keys.
  *
- * Return a list of all the txs hash that match the filter
  * @returns {Array} - txs hash that match the filter
  */
-MerkleBlock.prototype.filterdTxsHash = function filterdTxsHash () {
-  throw new Error('filterdTxsHash has been deprecated. use filteredTxsHash.')
-}
+MerkleBlock.prototype.filterdTxsHash = deprecate.fn(
+  function filterdTxsHash () { return this.filteredTxsHash() },
+  {
+    what: 'MerkleBlock#filterdTxsHash',
+    since: '9.1.0',
+    removeIn: '10.0.0',
+    use: 'MerkleBlock#filteredTxsHash',
+    why: 'the name is a misspelling'
+  }
+)
 
 /**
  * Return a list of all the txs hash that match the filter

package/lib/hdprivatekey.js

@@ -133,6 +133,21 @@ HDPrivateKey._getDerivationIndexes = function (path) {
 /**
  * WARNING: This method is deprecated. Use deriveChild or deriveNonCompliantChild instead. This is not BIP32 compliant
  *
+ * This one keeps THROWING rather than warning and delegating, and the reason is
+ * worth stating because it is the exception STABILITY.md carves out rather than
+ * an oversight.
+ *
+ * `derive` is ambiguous. Its two replacements return DIFFERENT KEYS:
+ * `deriveChild` is BIP32-compliant, `deriveNonCompliantChild` reproduces the old
+ * behaviour. Picking one here would silently hand roughly half of all callers
+ * keys they did not ask for — and a wrong derivation path means addresses whose
+ * funds cannot be recovered with the key the caller believes they hold. There is
+ * no default that is safe for everyone, so the caller has to choose, and the
+ * error names both options.
+ *
+ * A deprecation warning is the right tool when the replacement is obvious (see
+ * `MerkleBlock#filterdTxsHash`, a misspelling that now delegates). It is the
+ * wrong tool when guessing costs money.
  *
  * Get a derived child based on a string or number.
  *

package/lib/script/interpreter.js

@@ -65,7 +65,7 @@ var Interpreter = function Interpreter (obj) {
  *
  * Translated from bitcoind's VerifyScript
  */
-Interpreter.prototype.verify = function (scriptSig, scriptPubkey, tx, nin, flags, satoshisBN) {
+Interpreter.prototype._verifyCore = function (scriptSig, scriptPubkey, tx, nin, flags, satoshisBN) {
   var Transaction = require('../transaction')
 
   if (_.isUndefined(tx)) {
@@ -506,6 +506,114 @@ Interpreter.SCRIPT_UTXO_AFTER_CHRONICLE = (1 << 21)
  */
 Interpreter.CHRONICLE_ACTIVATION_HEIGHT = 943816
 
+/**
+ * Flags and *limits* are separate mechanisms. The era bits below are what the
+ * interpreter derives its element-size, script-size, opcode-count and
+ * script-number caps from — so a caller who hand-assembles a flag word out of
+ * named constants gets the feature opcodes they asked for while silently keeping
+ * the pre-Genesis caps. The script runs, which is what makes it hard to see;
+ * nothing looks wrong until a large push is rejected and the error names the
+ * push rather than the flags.
+ *
+ * Warning on every era-less verify() is not an option. Pre-Genesis validation is
+ * legitimate and common: the reference script_tests.json vectors are era-less by
+ * construction, and roughly three quarters of this library's own verify() calls
+ * are era-less for that reason. So the notice fires only on the intersection of
+ * two facts — an explicit era-less flag word AND a failure whose threshold is
+ * era-derived. Measured across the suite that combination accounts for ~5% of
+ * era-less failures, all of them genuine pre-Genesis vectors, and it is exactly
+ * the state a covenant author who guessed at flags ends up in.
+ */
+/**
+ * Failures whose threshold moved with an era: the cap that moved, and the flag
+ * that ACTUALLY lifts it.
+ *
+ * `lifts` is per-error on purpose. An earlier version tested a single ERA_FLAGS
+ * word containing all four era bits, which silenced the notice for the most likely
+ * form of the mistake: `SCRIPT_GENESIS` is the constant a hand-assembling caller
+ * reaches for — it is the one named "GENESIS" — but the size caps read
+ * `isAfterGenesis()`, which tests SCRIPT_UTXO_AFTER_GENESIS and nothing else. A
+ * flag word carrying SCRIPT_GENESIS alone still gets the 520-byte cap, still fails
+ * with PUSH_SIZE, and got no explanation.
+ *
+ * Each entry therefore names the bit its own cap is derived from:
+ *   maxScriptElementSize/maxScriptSize/maxOpsPerScript -> isAfterGenesis()
+ *   maxScriptNumLength                                 -> isAfterChronicle(), then isAfterGenesis()
+ */
+Interpreter.ERA_SENSITIVE_ERRORS = {
+  SCRIPT_ERR_PUSH_SIZE: {
+    cap: 'stack element size (capped at 520 bytes pre-Genesis, unbounded after)',
+    lifts: Interpreter.SCRIPT_UTXO_AFTER_GENESIS
+  },
+  SCRIPT_ERR_SCRIPT_SIZE: {
+    cap: 'total script size (capped at 10,000 bytes pre-Genesis, unbounded after)',
+    lifts: Interpreter.SCRIPT_UTXO_AFTER_GENESIS
+  },
+  SCRIPT_ERR_OP_COUNT: {
+    cap: 'opcode count (capped at 201 pre-Genesis, unbounded after)',
+    lifts: Interpreter.SCRIPT_UTXO_AFTER_GENESIS
+  },
+  SCRIPT_ERR_SCRIPTNUM_OVERFLOW: {
+    cap: 'script number width (4 bytes pre-Genesis, 750,000 after Genesis, 32,000,000 after Chronicle)',
+    lifts: Interpreter.SCRIPT_UTXO_AFTER_GENESIS | Interpreter.SCRIPT_UTXO_AFTER_CHRONICLE
+  }
+}
+
+/**
+ * Every era bit, kept for callers that want to ask "is this flag word era-aware at
+ * all". NOT used to gate the diagnostic — see ERA_SENSITIVE_ERRORS.lifts.
+ */
+Interpreter.ERA_FLAGS =
+  Interpreter.SCRIPT_GENESIS |
+  Interpreter.SCRIPT_UTXO_AFTER_GENESIS |
+  Interpreter.SCRIPT_ENABLE_CHRONICLE |
+  Interpreter.SCRIPT_UTXO_AFTER_CHRONICLE
+
+/** Set false to silence the notice. `eraHint` is still populated. */
+Interpreter.eraDiagnostics =
+  !(typeof process !== 'undefined' && process.env && process.env.BSV_NO_ERA_HINT === '1')
+
+var eraWarned = false
+
+Interpreter.prototype._eraDiagnose = function (flags) {
+  // Only an EXPLICIT flag word can be wrong this way; omitting flags already
+  // resolves to current mainnet via currentConsensusFlags().
+  if (flags === undefined) return
+  var entry = Interpreter.ERA_SENSITIVE_ERRORS[this.errstr]
+  if (!entry) return
+  // Gate on the bit that lifts THIS cap, not on any era bit being present.
+  if ((flags & entry.lifts) !== 0) return
+  var cap = entry.cap
+
+  this.eraHint =
+    this.errstr + ' was produced under PRE-GENESIS limits: ' + cap + '.\n' +
+    'The flags passed to verify() (0x' + (flags >>> 0).toString(16) + ') carry no era bit, ' +
+    'so those caps applied regardless of which feature opcodes were enabled.\n' +
+    'To validate against BSV as it is today, omit the flags argument or pass ' +
+    'Interpreter.mainnetFlags(). If you are deliberately testing pre-Genesis ' +
+    'consensus this failure is correct — set Interpreter.eraDiagnostics = false ' +
+    '(or BSV_NO_ERA_HINT=1) to silence this.'
+
+  if (Interpreter.eraDiagnostics && !eraWarned) {
+    eraWarned = true
+    console.warn('\n[@smartledger/bsv] ' + this.eraHint + '\n(shown once per process)\n')
+  }
+}
+
+/**
+ * Verify, then explain an era-caused failure if that is what happened.
+ * Wraps _verifyCore rather than editing its ten-odd early returns.
+ */
+Interpreter.prototype.verify = function (scriptSig, scriptPubkey, tx, nin, flags, satoshisBN) {
+  this.eraHint = null
+  var ok = this._verifyCore(scriptSig, scriptPubkey, tx, nin, flags, satoshisBN)
+  if (!ok) this._eraDiagnose(flags)
+  return ok
+}
+
+/** Test hook: forget that the notice has been shown. */
+Interpreter._resetEraWarning = function () { eraWarned = false }
+
 /**
  * The script-verification flags matching BSV mainnet consensus.
  *

package/lib/smart_contract/builder.js

@@ -20,6 +20,7 @@ var Hash = require('../crypto/hash')
 var BN = require('../crypto/bn')
 var Transaction = require('../transaction')
 var Script = require('../script')
+var deprecate = require('../util/deprecate')
 
 /**
  * @deprecated NON-ENFORCING. `buildLockingScript` / `createCovenant` emit
@@ -57,6 +58,19 @@ function Builder(privateKey, options) {
 // The scripts this class builds are non-enforcing (see the class @deprecated note).
 // Refuse to hand one back as if it were a real covenant unless explicitly acknowledged.
 Builder.prototype._assertEnforcingAllowed = function () {
+  if (this.allowNonEnforcing) {
+    // Opting in is legitimate (demos, tests, the docs' worked examples) but it
+    // is not permanent. Say so once, and here rather than at construction, so the
+    // notice fires only for callers actually taking a script away with them.
+    deprecate({
+      what: 'SmartContract.Builder ({ allowNonEnforcing: true })',
+      since: '9.1.0',
+      removeIn: '10.0.0',
+      use: 'SmartContract.policy(), or SmartContract.PushTx / Token / valueCovenant',
+      why: 'the scripts it emits reduce to plain P2PK and constrain nothing about the spend'
+    })
+    return
+  }
   if (!this.allowNonEnforcing) {
     throw new Error(
       'SmartContract.Builder produces a NON-ENFORCING script (constant hash-lock → ' +