@smartledger/bsv 8.3.1 → 9.1.0

package/lib/covenant/helpers.js

@@ -23,42 +23,42 @@ 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 + STANDARD RELAY flags — what mainnet miners actually
-// enforce. Includes SCRIPT_VERIFY_MINIMALDATA (every push must be minimal) and
-// SCRIPT_VERIFY_LOW_S (canonical signatures). Verifying with these flags locally
-// mirrors mainnet relay/consensus policy, so a covenant that passes here is
-// expected to be accepted on broadcast — catch non-relayable scripts before then.
-function flags () {
-  var I = Interpreter
-  return I.SCRIPT_VERIFY_P2SH |
-    I.SCRIPT_VERIFY_STRICTENC |
-    I.SCRIPT_VERIFY_DERSIG |
-    I.SCRIPT_VERIFY_LOW_S |
-    I.SCRIPT_VERIFY_MINIMALDATA |
-    I.SCRIPT_VERIFY_CHECKLOCKTIMEVERIFY |
-    I.SCRIPT_VERIFY_CHECKSEQUENCEVERIFY |
-    I.SCRIPT_ENABLE_SIGHASH_FORKID |
-    I.SCRIPT_ENABLE_MAGNETIC_OPCODES |
-    I.SCRIPT_ENABLE_MONOLITH_OPCODES |
-    // REQUIRED, not optional. pushTxCore emits OP_RIGHT/OP_LEFT — see
-    // extractHashOutputs and assertSighashType — and those bytes (180/181) are
-    // upgradable NOPs on the network until Chronicle activates. Without this
-    // flag the interpreter treats them as no-ops, exactly as a pre-Chronicle
-    // node does, and the covenant does not verify.
-    //
-    // Stated plainly: OP_PUSH_TX covenants built by this library DEPEND on
-    // Chronicle and cannot be spent on a pre-Chronicle chain. That was
-    // previously invisible because the interpreter ran the string opcodes
-    // unconditionally — more permissively than the network.
-    I.SCRIPT_ENABLE_CHRONICLE
-}
-
 /**
- * Opt into post-Genesis script limits (needed by OP_PUSH_TX covenants).
- * Thin wrapper over Interpreter.useGenesisLimits (added in 4.1.0).
+ * Current BSV mainnet consensus + standard relay flags — what miners actually
+ * enforce. A covenant that verifies here is expected to be accepted on broadcast.
+ *
+ * This DELEGATES to Interpreter.mainnetFlags() rather than assembling a list, and
+ * that is the whole point. Until 8.4.0 it was hand-assembled, and the hand-written
+ * list omitted the three UTXO-ERA flags — SCRIPT_GENESIS, SCRIPT_UTXO_AFTER_GENESIS
+ * and SCRIPT_UTXO_AFTER_CHRONICLE. It carried SCRIPT_ENABLE_CHRONICLE, which enables
+ * the string opcodes, so the omission was easy to miss: the opcodes ran, and only the
+ * *limits* were wrong.
+ *
+ * The era flags are what the interpreter derives its data limits from. Without them
+ * every covenant was verified under PRE-GENESIS rules — a 520-byte element cap that
+ * BSV removed in February 2020. An OP_PUSH_TX preimage is ~585 bytes, so this
+ * library's flagship feature could not verify against its own harness, and
+ * `enableGenesis()` existed to paper over it by raising process-wide statics. That
+ * was treating the symptom: raising the statics cannot enable post-Genesis
+ * arithmetic (only the era flags can) and it weakens pre-Genesis validation, turning
+ * 15 of the reference node's 22 SCRIPTNUM_OVERFLOW vectors into false accepts.
+ *
+ * Delegating also means the covenant path tracks consensus automatically instead of
+ * drifting the next time an era activates. `mainnetFlags()` is the same function the
+ * Interpreter uses for a no-flags verify(), so "verify locally" and "what the network
+ * does" cannot diverge again without both moving together.
+ *
+ * Two flags in the old list are deliberately gone: SCRIPT_VERIFY_CHECKLOCKTIMEVERIFY
+ * and SCRIPT_VERIFY_CHECKSEQUENCEVERIFY. Genesis reverted OP_CLTV/OP_CSV to
+ * upgradable NOPs for outputs created after it (see interpreter.js, the
+ * `isAfterGenesis()` short-circuit), so once the era flags are present these two
+ * change nothing. Keeping them would have implied a time-lock guarantee mainnet does
+ * not provide, which is why the CLTV-based locks were removed in 9.0.0.
+ *
+ * NULLFAIL is gained, which is strictly stricter.
  */
-function enableGenesis (max) {
-  return Interpreter.useGenesisLimits(max)
+function flags () {
+  return Interpreter.mainnetFlags()
 }
 
 /**
@@ -135,7 +135,6 @@ function scriptNum (n) {
 module.exports = {
   SIGHASH: SIGHASH,
   flags: flags,
-  enableGenesis: enableGenesis,
   verify: verify,
   rawPreimage: rawPreimage,
   sighashDigest: sighashDigest,

package/lib/covenant/pushtx.js

@@ -13,8 +13,8 @@
  * Optimal parameters: private key a = 1, ephemeral k = 1  =>  r = Gx,
  *   s = (e + Gx) mod n,  pubkey P = 02||Gx,  e = HASH256(preimage).
  *
- * Requires post-Genesis limits — call SmartContract.enableGenesis() (a.k.a
- * Interpreter.useGenesisLimits()) before verifying these scripts.
+ * Verifies under mainnet consensus flags with no opt-in (8.4.0+). Earlier versions
+ * required SmartContract.enableGenesis() first; that call is now a deprecated no-op.
  */
 
 var Script = require('../script')

package/lib/custom-script-helper.js

@@ -71,22 +71,6 @@ class CustomScriptHelper {
     return script;
   }
 
-  /**
-   * Create a time-locked script (CHECKLOCKTIMEVERIFY)
-   * @param {number} lockTime - Block height or timestamp
-   * @param {Script} baseScript - Base script to execute after time lock
-   * @returns {Script} Time-locked script
-   */
-  static createTimelockScript(lockTime, baseScript) {
-    const lockTimeBuffer = Buffer.from(lockTime.toString(16).padStart(8, '0'), 'hex').reverse();
-    
-    return new Script()
-      .add(lockTimeBuffer)
-      .add(Opcode.OP_CHECKLOCKTIMEVERIFY)
-      .add(Opcode.OP_DROP)
-      .add(baseScript.toBuffer());
-  }
-
   /**
    * Create a conditional script (IF/ELSE/ENDIF)
    * @param {Script} ifScript - Script to execute if condition is true

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/ordinals/ordlock.js

@@ -35,7 +35,7 @@
  *   OP_ENDIF
  *   [OP_FALSE OP_IF "ord" … OP_ENDIF]   // optional inert inscription envelope
  *
- * Requires post-Genesis limits: call SmartContract.enableGenesis() before verifying.
+ * Verifies under mainnet consensus flags with no opt-in (8.4.0+).
  */
 var P = require('../covenant/pushtx')
 var H = require('../covenant/helpers')

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/smart_contract/debugger.js

@@ -5,8 +5,8 @@
  * Step-traces a locking/unlocking pair through Script.Interpreter and records the
  * stack + alt-stack after every opcode, so you can watch an OP_PUSH_TX covenant
  * build its signature and enforce its constraints. Uses the interpreter's
- * stepListener hook. Call SmartContract.enableGenesis() first for OP_PUSH_TX
- * covenants (their preimage element / opcode count exceed pre-Genesis limits).
+ * stepListener hook. No opt-in is needed since 8.4.0: covenants verify under mainnet
+ * consensus flags, whose era bits lift the pre-Genesis element and opcode caps.
  */
 
 var Interpreter = require('../script/interpreter')

package/lib/smart_contract/dsl.js

@@ -14,8 +14,8 @@
  *   // c.unlock(spendTx, satoshis) -> grinds + returns the preimage unlock Script
  *
  * Each clause compiles to one preimage-field check on top of a single OP_PUSH_TX
- * authentication; clauses AND together. Requires post-Genesis limits at verify
- * time (SmartContract.enableGenesis()).
+ * authentication; clauses AND together. Verifies under mainnet consensus flags with
+ * no opt-in (8.4.0+).
  */
 
 var PushTx = require('../covenant/pushtx')

package/lib/smart_contract/index.js

@@ -70,9 +70,6 @@ SmartContract.trace = function (unlockingScript, lockingScript, opts) {
 
 // --- 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)

package/lib/smart_contract/locks.js

@@ -10,7 +10,6 @@ var H = require('../covenant/helpers')
 var Script = require('../script')
 var Opcode = require('../opcode')
 var signInput = H.signInput
-var n = H.scriptNum
 
 /** Hash-lock: reveal a preimage whose SHA-256 matches a digest. */
 function hashLock (secret) {
@@ -36,20 +35,6 @@ function p2pkh (privateKey) {
   }
 }
 
-/** 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() })
@@ -68,33 +53,8 @@ function multisig (m, privateKeys) {
   }
 }
 
-/** 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
+  multisig: multisig
 }

package/lib/smart_contract/pels.js

@@ -14,7 +14,7 @@
  * the slice preimage[104 : len-52] is exactly the `scriptlen||script` half of a
  * TxOut, so the next output is `<newValue:8-LE> || preimage[104:len-52]`.
  *
- * Requires post-Genesis limits (SmartContract.enableGenesis()).
+ * Verifies under mainnet consensus flags with no opt-in (8.4.0+).
  */
 
 var P = require('../covenant/pushtx')

package/lib/smart_contract/token.js

@@ -36,7 +36,7 @@
  *       surrounding output bytes and the token's value; the covenant binds them
  *       into the committed hashOutputs. Value conservation is left to the network.
  *
- * Requires post-Genesis limits (SmartContract.enableGenesis()).
+ * Verifies under mainnet consensus flags with no opt-in (8.4.0+).
  */
 
 var BN = require('../crypto/bn')

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