@smartledger/bsv 9.0.0 → 9.1.1

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 → ' +

package/lib/util/deprecate.js

@@ -0,0 +1,159 @@
+'use strict'
+
+/**
+ * Runtime deprecation notices.
+ *
+ * A semver major is a promise that the consumer's code breaks. Between 4.0.0
+ * (2026-05-31) and 9.0.0 (2026-08-21) this library made that promise six times,
+ * and the mechanism was almost always the same: an API that had become wrong was
+ * changed to `throw`, in the same release that decided it was wrong. Correct
+ * diagnosis, no warning period.
+ *
+ * `MerkleBlock#filterdTxsHash` was one of those and now delegates with a notice.
+ * `HDPrivateKey#derive` still throws deliberately: its replacements return
+ * different keys, so guessing on the caller's behalf risks funds. That is the
+ * narrow exception in STABILITY.md, not a gap in this module.
+ *
+ * The fix is not to keep bad APIs. It is to separate the moment we say "this is
+ * wrong" from the moment we break callers:
+ *
+ *   minor    mark it. Callers see a warning naming the replacement, and keep
+ *            working. `removeIn` states the version that will break them.
+ *   major    remove it, on a schedule announced at least one minor in advance.
+ *
+ * Deprecating is therefore a NON-breaking act and belongs in a minor. That is
+ * what makes a long-lived 9.x possible: correctness fixes ship continuously,
+ * breakage batches into one planned major with a migration path already in the
+ * consumer's logs.
+ *
+ * Nothing here ever throws. A deprecation that throws is just a breaking change
+ * wearing a warning's name.
+ */
+
+var seen = Object.create(null)
+
+/** Every notice fired this process, for tests and for `--audit`-style tooling. */
+var fired = []
+
+/**
+ * Warnings are on unless explicitly silenced. Consumers who have logged the
+ * migration and do not want the noise set BSV_NO_DEPRECATION_WARNINGS=1; the
+ * record in `fired` is kept either way so tooling still sees it.
+ */
+// Guarded like every other process.env read in lib/ (see lib/smartutxo.js,
+// lib/browser-utxo-manager.js). This module is inlined into every feature bundle,
+// and `exports` publishes lib/ subpaths directly, so an unguarded read here is a
+// ReferenceError in any browser bundler that does not shim `process`.
+var enabled = !(typeof process !== 'undefined' && process.env &&
+  process.env.BSV_NO_DEPRECATION_WARNINGS === '1')
+
+/**
+ * `what` is the one field with no sensible default: it is the string the notice is
+ * keyed and deduplicated on. Everything else degrades gracefully.
+ */
+function assertOpts (opts, caller) {
+  if (!opts || typeof opts.what !== 'string' || opts.what === '') {
+    throw new TypeError(caller + '() requires { what: string }')
+  }
+}
+
+function format (opts) {
+  var msg = '[@smartledger/bsv] ' + opts.what + ' is deprecated'
+  if (opts.since) msg += ' since ' + opts.since
+  msg += '.'
+  if (opts.why) msg += ' ' + opts.why.charAt(0).toUpperCase() + opts.why.slice(1) + '.'
+  if (opts.use) msg += ' Use ' + opts.use + ' instead.'
+  msg += opts.removeIn
+    ? ' It will be removed in ' + opts.removeIn + '.'
+    : ' A removal version has not been set; it will not be removed in a 9.x release.'
+  return msg
+}
+
+/**
+ * Emit a deprecation notice at most once per `what` per process.
+ *
+ * @param {object} opts
+ * @param {string} opts.what      the API being deprecated, as a caller writes it
+ * @param {string} [opts.since]   version that deprecated it
+ * @param {string} [opts.removeIn] version that will remove it (a major)
+ * @param {string} [opts.use]     the replacement, as a caller would write it
+ * @param {string} [opts.why]     one clause; why it is wrong, not what to do
+ * @returns {boolean} true if this call emitted (false if already seen)
+ */
+function deprecate (opts) {
+  if (!opts || !opts.what) throw new TypeError('deprecate() requires { what }')
+  if (seen[opts.what]) return false
+  seen[opts.what] = true
+
+  var message = format(opts)
+  fired.push({
+    what: opts.what,
+    since: opts.since || null,
+    removeIn: opts.removeIn || null,
+    use: opts.use || null,
+    message: message
+  })
+  if (enabled) console.warn(message)
+  return true
+}
+
+/**
+ * Wrap a function so calling it warns once, then behaves exactly as before.
+ * Preserves name, arity and `this`, so it is safe on prototype methods.
+ *
+ *   Klass.prototype.old = deprecate.fn(Klass.prototype.old, {
+ *     what: 'Klass#old', since: '9.1.0', removeIn: '10.0.0', use: 'Klass#new'
+ *   })
+ */
+deprecate.fn = function (fn, opts) {
+  if (typeof fn !== 'function') throw new TypeError('deprecate.fn() requires a function')
+  // Validate HERE, not inside the wrapper. Deferring it meant `deprecate.fn(f)` wrapped
+  // cleanly and then threw on every subsequent call — turning a deprecation into the
+  // breaking change this module exists to avoid, at a call site far from the mistake.
+  // Wrapping is a one-time author action; failing there is loud, immediate and cheap.
+  assertOpts(opts, 'deprecate.fn')
+  var wrapper = function () {
+    deprecate(opts)
+    return fn.apply(this, arguments)
+  }
+  Object.defineProperty(wrapper, 'name', { value: fn.name, configurable: true })
+  Object.defineProperty(wrapper, 'length', { value: fn.length, configurable: true })
+  wrapper.__wrapped = fn
+  wrapper.__deprecation = opts
+  return wrapper
+}
+
+/**
+ * Deprecate a property access (an alias namespace, a renamed field).
+ * Warns on first read; the value is computed once and cached.
+ */
+deprecate.property = function (target, name, get, opts) {
+  assertOpts(opts, 'deprecate.property')
+  var cached
+  var loaded = false
+  Object.defineProperty(target, name, {
+    configurable: true,
+    enumerable: true,
+    get: function () {
+      deprecate(opts)
+      if (!loaded) { cached = get(); loaded = true }
+      return cached
+    }
+  })
+  return target
+}
+
+/** Notices fired this process, in order. */
+deprecate.fired = function () { return fired.slice() }
+
+/** Silence output. The `fired` record is still kept. */
+deprecate.setEnabled = function (v) { enabled = !!v }
+deprecate.isEnabled = function () { return enabled }
+
+/** Test hook: forget what has been warned about. */
+deprecate.reset = function () {
+  seen = Object.create(null)
+  fired.length = 0
+}
+
+module.exports = deprecate

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@smartledger/bsv",
-  "version": "9.0.0",
-  "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.",
+  "version": "9.1.1",
+  "description": "Bitcoin SV library with an interpreter-verified script engine: OP_PUSH_TX covenants, BIP-143 preimage tooling, and consensus flags that match what miners actually enforce. Also ships DID:web / W3C VC-JWT credentials and the Legal Token Protocol.",
   "author": "SmartLedger Technology <hello@smartledger.technology> (https://smartledger.technology)",
   "homepage": "https://github.com/codenlighten/smartledger-bsv#readme",
   "bugs": {
@@ -98,10 +98,12 @@
     "test:browser": "echo 'Open tests/standalone-modules-test.html in browser for comprehensive testing'",
     "test:bundle": "echo 'Open tests/bundle-completeness-test.html in browser to verify bundle completeness'",
     "preimage:extract": "node examples/preimage/extract_preimage_bidirectional.js",
-    "prepublishOnly": "npm run build-all && npm run check:readme",
+    "prepublishOnly": "npm run build-all && npm run check:readme && npm run check:api",
     "sync-cdn": "node scripts/sync-cdn-urls.js",
     "version": "node scripts/sync-cdn-urls.js && node scripts/sync-version.js && node scripts/gen-esm-wrapper.js && git add README.md docs version.js index.mjs",
-    "test:browser:ci": "node tests/browser-smoke-runner.js"
+    "test:browser:ci": "node tests/browser-smoke-runner.js",
+    "api:snapshot": "node scripts/api-surface.js",
+    "check:api": "mocha test/api_surface.js --no-config"
   },
   "unpkg": "bsv.min.js",
   "jsdelivr": "bsv.min.js",
@@ -110,8 +112,6 @@
     "index.js",
     "index.mjs",
     "version.js",
-    "test/",
-    ".mocharc.json",
     "lib/",
     "utilities/*.js",
     "utilities/README.md",
@@ -142,88 +142,25 @@
     "LICENSE",
     "README.md",
     "SECURITY.md",
-    "CHANGELOG.md"
+    "CHANGELOG.md",
+    "STABILITY.md"
   ],
   "keywords": [
-    "bitcoin",
     "bitcoin-sv",
     "bsv",
-    "legal-token-protocol",
-    "ltp",
-    "legal-tokens",
-    "primitives-only",
-    "legal-compliance",
-    "property-rights",
-    "obligations",
-    "attestations",
-    "gdaf",
-    "global-digital-attestation",
-    "w3c-credentials",
-    "verifiable-credentials",
-    "decentralized-identity",
-    "shamir-secret-sharing",
-    "threshold-cryptography",
-    "cryptocurrency",
-    "blockchain",
-    "smart-contracts",
-    "defi",
+    "bitcoin-script",
+    "opcode",
     "covenant",
-    "covenants",
-    "script-debugger",
-    "debug-tools",
-    "modular-loading",
-    "standalone-modules",
-    "elliptic-curve-fix",
-    "smartledger",
-    "transaction",
-    "address",
-    "signature",
-    "wallet",
-    "hd-wallet",
-    "mnemonic",
-    "ecies",
-    "encryption",
-    "message-signing",
-    "pushtx",
-    "pels",
+    "op-push-tx",
     "bip143",
     "preimage",
-    "secret-splitting",
-    "did-resolution",
-    "selective-disclosure",
-    "blockchain-anchoring",
-    "attestation-framework",
-    "nchain",
-    "custom-scripts",
-    "multisig",
-    "timelock",
-    "conditional-scripts",
-    "utxo-management",
-    "ultra-low-fees",
-    "javascript-to-script",
-    "opcode-mapping",
-    "covenant-builder",
-    "script-simulation",
-    "bitcoin-script",
-    "asm-generation",
-    "advanced-features",
-    "script-development",
-    "blockchain-simulator",
-    "miner-simulator",
-    "testing-tools",
-    "development-framework",
-    "browser-compatible",
-    "nodejs-compatible",
-    "webpack-ready",
-    "cdn-ready",
-    "typescript-definitions",
-    "drop-in-replacement",
-    "performance-optimized",
-    "bip21",
-    "bip32",
-    "bip37",
-    "bip69",
-    "bip70"
+    "smart-contracts",
+    "script-interpreter",
+    "transaction",
+    "utxo",
+    "verifiable-credentials",
+    "did-web",
+    "legal-token-protocol"
   ],
   "repository": {
     "type": "git",
@@ -246,7 +183,7 @@
     "chai": "6.2.2",
     "create-hash": "^1.2.0",
     "create-hmac": "^1.1.7",
-    "esbuild": "^0.28.1",
+    "esbuild": "^0.28.2",
     "events": "^3.3.0",
     "jose": "^5.10.0",
     "mocha": "^11.8.0",

package/version.js

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

package/.mocharc.json

@@ -1,5 +0,0 @@
-{
-  "recursive": true,
-  "timeout": 8000,
-  "spec": "test/**/*.js"
-}