@smartledger/bsv 9.0.0 → 9.1.0

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.0",
+  "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.0'

package/.mocharc.json

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