@smartledger/bsv 5.4.2 → 5.5.1

package/lib/smart_contract/authorizers.js

@@ -0,0 +1,159 @@
+'use strict'
+/**
+ * SmartContract.Authorizers — pluggable ownership-authorization schemes for the
+ * stateful Token covenant.
+ *
+ * A token carries a single 20-byte owner commitment in its scriptCode. By
+ * factoring out ONLY the block that proves "the spender is the committed owner of
+ * THIS spend", the same covenant can be owned by a single key, an m-of-n group, or
+ * any future custom predicate — with the state-rebuild plumbing (read commit =
+ * chunk[4:24], rewrite with the next owner's 20-byte commit) identical for every
+ * scheme.
+ *
+ * An Authorizer is `{ name, commit, emit, unlockArgs }`:
+ *   - commit(descriptor) -> Buffer(20)
+ *       the 20-byte owner id for an owner descriptor (a key, a key set, ...).
+ *   - emit(script)
+ *       the in-script proof. At entry the stack is  [ ...authArgs, ownerCommit ]
+ *       (ownerCommit on top). The block MUST consume authArgs + ownerCommit and
+ *       VERIFY authorization over this spend (use *VERIFY opcodes — it must not
+ *       leave a fall-through boolean), leaving whatever sits below authArgs
+ *       (the next-owner hash) untouched. It must also leave the altstack as it
+ *       found it.
+ *   - unlockArgs(spend, inputIndex, lock, sats, signer) -> Array<Buffer|opcode>
+ *       the authArgs pushed (deepest-first) in the unlock script, which the Token
+ *       slots as  <newOwnerHash> <...authArgs> <preimage>.
+ *
+ * All schemes commit to a fixed 20-byte hash, so a transfer's chosen next owner is
+ * always just a 20-byte value the covenant splices into the recreated scriptCode.
+ */
+
+var bsv = require('../..')
+var Hash = require('../crypto/hash')
+var H = require('./covenant_helpers')
+
+var Opcode = bsv.Opcode
+var n = H.scriptNum
+
+function pubBuffer (key) {
+  if (key instanceof bsv.PrivateKey) return key.toPublicKey().toBuffer()
+  if (key instanceof bsv.PublicKey) return key.toBuffer()
+  return key // already a Buffer
+}
+
+/* -------------------------------------------------------------------------- */
+/* single-key: owner is one key; authorize with its signature over the spend.  */
+/* -------------------------------------------------------------------------- */
+function singleKey () {
+  return {
+    name: 'single-key',
+    commit: function (key) { return Hash.sha256ripemd160(pubBuffer(key)) },
+    emit: function (s) {
+      // stack: [.., sig, pubkey, ownerCommit]
+      s.add(Opcode.OP_OVER).add(Opcode.OP_HASH160).add(Opcode.OP_EQUALVERIFY) // HASH160(pubkey) == ownerCommit
+      s.add(Opcode.OP_CHECKSIGVERIFY) // ECDSA signature over THIS spend
+      return s
+    },
+    unlockArgs: function (spend, inputIndex, lock, sats, ownerKey) {
+      var sig = H.signInput(spend, ownerKey, inputIndex, lock, sats)
+      return [sig, ownerKey.toPublicKey().toBuffer()] // deepest-first: sig, then pubkey
+    }
+  }
+}
+
+/* -------------------------------------------------------------------------- */
+/* multisig: owner is an m-of-n key set, committed by hashing the canonical     */
+/* multisig redeem script. The set is revealed at spend, bound to the           */
+/* commitment, and checked with OP_CHECKMULTISIG.                               */
+/* -------------------------------------------------------------------------- */
+
+/** Canonical m-of-n redeem-script bytes: OP_m <33||pk>..<33||pk> OP_n OP_CHECKMULTISIG. */
+function redeemScript (m, pubkeys) {
+  var nn = pubkeys.length
+  if (m < 1 || m > nn || nn < 1 || nn > 16) throw new Error('multisig requires 1 <= m <= n <= 16')
+  var s = new bsv.Script().add(Opcode['OP_' + m])
+  pubkeys.forEach(function (p) { s.add(Buffer.from(p)) }) // each emitted as 0x21||pk (33-byte push)
+  s.add(Opcode['OP_' + nn]).add(Opcode.OP_CHECKMULTISIG)
+  return s.toBuffer()
+}
+
+function multisig (m, nKeys) {
+  if (m < 1 || m > nKeys || nKeys < 1 || nKeys > 16) throw new Error('multisig requires 1 <= m <= n <= 16')
+  return {
+    name: m + '-of-' + nKeys + '-multisig',
+    m: m,
+    n: nKeys,
+    /** descriptor: an ordered array of n public keys (PublicKey|PrivateKey|Buffer). */
+    commit: function (keys) {
+      if (keys.length !== nKeys) throw new Error('expected ' + nKeys + ' public keys')
+      return Hash.sha256ripemd160(redeemScript(m, keys.map(pubBuffer)))
+    },
+    emit: function (s) {
+      // stack: [.., dummy, sig_1..sig_m, redeem, ownerCommit]   (redeem = canonical bytes)
+      s.add(Opcode.OP_OVER).add(Opcode.OP_HASH160).add(Opcode.OP_EQUALVERIFY) // HASH160(redeem) == ownerCommit
+      // strip the leading OP_m byte and the trailing OP_n OP_CHECKMULTISIG (2 bytes),
+      // leaving body = (0x21||pubkey) repeated n times.
+      s.add(n(1)).add(Opcode.OP_SPLIT).add(Opcode.OP_NIP)
+      s.add(Opcode.OP_SIZE).add(n(2)).add(Opcode.OP_SUB).add(Opcode.OP_SPLIT).add(Opcode.OP_DROP)
+      // peel each 34-byte (0x21||pubkey) unit, drop the push opcode, park the pubkey.
+      // Parking pushes pk1..pkn onto the altstack (pkn on top), so popping them back
+      // yields pkn..pk1 — the pubkey just under OP_n is pk1. CHECKMULTISIG therefore
+      // encounters keys pk1, pk2, ... pkn; the unlock provides sigs in the matching
+      // (descending key-index) order, see unlockArgs.
+      for (var i = 0; i < this.n; i++) {
+        s.add(n(34)).add(Opcode.OP_SPLIT) // [.., unit34, rest]
+        s.add(Opcode.OP_SWAP).add(n(1)).add(Opcode.OP_SPLIT).add(Opcode.OP_NIP) // [.., rest, pubkey]
+        s.add(Opcode.OP_TOALTSTACK)
+      }
+      s.add(Opcode.OP_DROP) // the now-empty remainder
+      // rebuild the CHECKMULTISIG stack: [.., dummy, sigs.., m, pkn..pk1, n]
+      s.add(n(this.m))
+      for (i = 0; i < this.n; i++) s.add(Opcode.OP_FROMALTSTACK)
+      s.add(n(this.n))
+      s.add(Opcode.OP_CHECKMULTISIGVERIFY)
+      return s
+    },
+    unlockArgs: function (spend, inputIndex, lock, sats, signer) {
+      // signer: { keys: [n ordered pubkeys], signWith: [>= m private keys] }
+      var keys = signer.keys
+      if (keys.length !== nKeys) throw new Error('expected ' + nKeys + ' public keys in signer.keys')
+      var redeem = redeemScript(m, keys.map(pubBuffer))
+      // emit() encounters keys pk1..pkn, so the m signatures must be pushed in
+      // descending key-index order (topmost sig = smallest-index signer).
+      var keyHex = keys.map(pubBuffer).map(function (b) { return b.toString('hex') })
+      var indexed = signer.signWith.map(function (priv) {
+        var idx = keyHex.indexOf(priv.toPublicKey().toBuffer().toString('hex'))
+        if (idx < 0) throw new Error('signWith key is not in the committed key set')
+        return { idx: idx, priv: priv }
+      }).sort(function (a, b) { return b.idx - a.idx }).slice(0, m)
+      if (indexed.length < m) throw new Error('need at least ' + m + ' signing keys')
+      var sigs = indexed.map(function (e) { return H.signInput(spend, e.priv, inputIndex, lock, sats) })
+      // deepest-first: dummy, then the m sigs (descending key index), then redeem.
+      return [Opcode.OP_0].concat(sigs).concat([redeem])
+    }
+  }
+}
+
+/* -------------------------------------------------------------------------- */
+/* predicate: escape hatch for arbitrary ownership schemes. Supply your own     */
+/* { commit, emit, unlockArgs } honoring the Authorizer contract above.         */
+/* -------------------------------------------------------------------------- */
+function predicate (spec) {
+  if (!spec || typeof spec.emit !== 'function' || typeof spec.unlockArgs !== 'function' ||
+      typeof spec.commit !== 'function') {
+    throw new Error('predicate authorizer needs { commit, emit, unlockArgs } functions')
+  }
+  return {
+    name: spec.name || 'predicate',
+    commit: spec.commit,
+    emit: spec.emit,
+    unlockArgs: spec.unlockArgs
+  }
+}
+
+module.exports = {
+  singleKey: singleKey,
+  multisig: multisig,
+  predicate: predicate,
+  redeemScript: redeemScript
+}

package/lib/smart_contract/covenant_helpers.js

@@ -19,9 +19,9 @@ 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 locally
-// catches non-relayable covenants BEFORE broadcast — covenants verified here
-// have been deployed and spent on BSV mainnet.
+// 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 = bsv.Script.Interpreter
   return I.SCRIPT_VERIFY_P2SH |

package/lib/smart_contract/dsl.js

@@ -124,6 +124,6 @@ function policy () { return new Policy() }
 
 // Terminal shortcuts for the non-composable whole-covenant patterns.
 policy.perpetual = function (fee) { return PELS.pelsCovenant(fee) }
-policy.token = function (fee, ownerHash) { return Token.ownershipToken(fee, ownerHash) }
+policy.token = function (fee, ownerPubKeyHash) { return Token.ownershipToken(fee, ownerPubKeyHash) }
 
 module.exports = { policy: policy, Policy: Policy }

package/lib/smart_contract/index.js

@@ -44,6 +44,7 @@ var SmartContract = {
   PushTx: require('./pushtx'),
   PELS: require('./pels'),
   Token: require('./token'),
+  Authorizers: require('./authorizers'),
 
   // Declarative covenant DSL + stack debugger (v4.5.0)
   DSL: require('./dsl'),
@@ -72,9 +73,10 @@ SmartContract.verifyScript = function (unlockingScript, lockingScript, opts) {
 SmartContract.perpetualCovenant = function (fee) {
   return SmartContract.PELS.pelsCovenant(fee)
 }
-// Stateful ownership token (NFT) locking script.
-SmartContract.ownershipToken = function (fee, ownerHash) {
-  return SmartContract.Token.ownershipToken(fee, ownerHash)
+// Stateful ownership token (NFT) locking script. ownerPubKeyHash = HASH160 of the
+// owner's public key (SmartContract.Token.ownerId); transfers are ECDSA-authorized.
+SmartContract.ownershipToken = function (fee, ownerPubKeyHash) {
+  return SmartContract.Token.ownershipToken(fee, ownerPubKeyHash)
 }
 // OP_PUSH_TX value/output covenant: coins can only go where the covenant says.
 SmartContract.valueCovenant = function (expectedHashOutputs) {
@@ -358,9 +360,9 @@ SmartContract.utils.decodeCompactSize = function (buffer, offset) {
   return SmartContract.Preimage.decodeCompactSize(buffer, offset)
 }
 
-// Version information
-SmartContract.version = 'v1.0.0'
-SmartContract.description = 'Enterprise Smart Contract Framework for Bitcoin SV'
+// Version information — tracks the package version so the two never drift.
+SmartContract.version = require('../../package.json').version
+SmartContract.description = 'Smart Contract Framework for Bitcoin SV'
 
 // Feature flags
 SmartContract.features = {
@@ -385,8 +387,7 @@ SmartContract.features = {
   STACK_EXAMINATION: true,
   SCRIPT_DEBUGGING: true,
   STEP_BY_STEP_EXECUTION: true,
-  INTERACTIVE_DEBUGGING: true,
-  PRODUCTION_READY: true
+  INTERACTIVE_DEBUGGING: true
 }
 
 // Standard debug method aliases for compatibility

package/lib/smart_contract/pels.js

@@ -36,6 +36,7 @@ function pelsCovenant (fee) {
   s.add(Opcode.OP_DUP)
   P.pushTxCore(s)
   s.add(Opcode.OP_VERIFY) // stack: [preimage]
+  P.assertSighashAll(s) // fail fast unless this spend is SIGHASH_ALL|FORKID (0x41)
 
   // 2. scriptChunk = preimage[104 : len-52]
   s.add(Opcode.OP_DUP)

package/lib/smart_contract/pushtx.js

@@ -87,6 +87,28 @@ function extractHashOutputs (script) {
   return script
 }
 
+// The BIP-143 preimage ends with nHashType as a 4-byte LE word; for SIGHASH_ALL|
+// FORKID that word is 0x41 00 00 00.
+var SIGHASH_WORD = Buffer.from([SIGHASH, 0x00, 0x00, 0x00])
+
+/**
+ * Assert the spend is SIGHASH_ALL|FORKID (0x41). Pre/Post: top of stack = preimage
+ * (left untouched). These covenants read fixed offsets (104 / 52 / 40) that are
+ * meaningful only for the 0x41 layout, and the OP_PUSH_TX core already pins the
+ * flag implicitly (its synthetic sig carries 0x41, so OP_CHECKSIG only accepts a
+ * preimage hashing to the 0x41 sighash). Note the offsets themselves are invariant
+ * in the number of INPUTS — hashPrevouts/hashSequence are digests of all inputs,
+ * so the preimage is the same length for 1 or N inputs; the covenant simply does
+ * not constrain sibling inputs, by design. What it does assume is a single
+ * recreated OUTPUT (HASH256(nextOutput) == hashOutputs). This guard makes the
+ * flag assumption explicit and fails fast — and survives any refactor of the core.
+ */
+function assertSighashAll (script) {
+  script.add(Opcode.OP_DUP).add(scriptNum(4)).add(Opcode.OP_RIGHT)
+    .add(SIGHASH_WORD).add(Opcode.OP_EQUALVERIFY)
+  return script
+}
+
 /** BIP-143 hashOutputs (SIGHASH_ALL) for a set of Transaction.Output objects. */
 function hashOutputs (outputs) {
   var ser = Buffer.concat(outputs.map(function (o) { return o.toBufferWriter().toBuffer() }))
@@ -129,15 +151,36 @@ function sFromPreimage (preimage) {
 }
 
 /**
- * Grind the spend tx (vary nLockTime) until the in-script signature is a clean
- * fixed-length DER. Mutates spend.nLockTime; returns { preimage, tries }.
+ * Grind a malleable field of the spend until the in-script OP_PUSH_TX signature
+ * is a clean, canonical (low-S) fixed-length DER. Returns { preimage, tries,
+ * field, nonce }; mutates the chosen field on `spend`.
+ *
+ * @param {object} [opts] grind options (a bare number is accepted as legacy maxTries):
+ *   - maxTries {number}  attempts before giving up (default 5000).
+ *   - start    {number}  first nonce value to try (default 0).
+ *   - field    {'nLockTime'|'sequence'}  which field carries the grind nonce
+ *       (default 'nLockTime'). Use 'sequence' when the covenant pins nLockTime for
+ *       a real CLTV absolute timelock: the input's sequence is swept down from
+ *       0xfffffffe (kept non-final, so CLTV still triggers) instead of clobbering
+ *       nLockTime. (Not for CSV/relative-locktime covenants, which encode meaning
+ *       in the sequence number itself.)
  */
-function grind (spend, inputIndex, lockingScript, satoshis, maxTries) {
-  maxTries = maxTries || 5000
-  for (var t = 0; t < maxTries; t++) {
-    spend.nLockTime = t
+function grind (spend, inputIndex, lockingScript, satoshis, opts) {
+  if (typeof opts === 'number') opts = { maxTries: opts } // back-compat: legacy maxTries arg
+  opts = opts || {}
+  var maxTries = opts.maxTries || 5000
+  var start = opts.start || 0
+  var field = opts.field || 'nLockTime'
+  if (field !== 'nLockTime' && field !== 'sequence') {
+    throw new Error("grind field must be 'nLockTime' or 'sequence'")
+  }
+  var input = spend.inputs[inputIndex]
+  for (var i = 0; i < maxTries; i++) {
+    var nonce = start + i
+    if (field === 'nLockTime') spend.nLockTime = nonce
+    else input.sequenceNumber = 0xfffffffe - nonce // stay < 0xffffffff (non-final)
     var preimage = H.rawPreimage(spend, inputIndex, lockingScript, satoshis)
-    if (sFromPreimage(preimage)) return { preimage: preimage, tries: t + 1 }
+    if (sFromPreimage(preimage)) return { preimage: preimage, tries: i + 1, field: field, nonce: nonce }
   }
   throw new Error('OP_PUSH_TX grind failed after ' + maxTries + ' tries')
 }
@@ -153,6 +196,7 @@ module.exports = {
   pushTxCore: pushTxCore,
   authenticator: authenticator,
   extractHashOutputs: extractHashOutputs,
+  assertSighashAll: assertSighashAll,
   hashOutputs: hashOutputs,
   valueCovenant: valueCovenant,
   sFromPreimage: sFromPreimage,

package/lib/smart_contract/token.js

@@ -4,40 +4,69 @@
  *
  * Carries mutable STATE in its own locking script and enforces a STATE-
  * TRANSITION rule on every spend.
- *   State          : 32-byte owner id = SHA256(ownerSecret).
- *   Transition rule: to spend, the owner reveals `ownerSecret`; the spend must
- *                    recreate the SAME token code with a (possibly new) owner,
- *                    paying value-fee forward. A transferable, perpetual NFT.
+ *   State          : 20-byte owner id (an Authorizer commitment — by default the
+ *                    HASH160 of the owner's public key).
+ *   Transition rule: to spend, the current owner proves authorization over THIS
+ *                    spend (an ECDSA signature, an m-of-n multisig, or any custom
+ *                    predicate), and the spend must recreate the SAME token code
+ *                    with a (possibly new) owner. A transferable, perpetual NFT.
  *
- * Layout: <ownerHash:32> OP_DROP <CODE>. The leading push embeds the state so it
+ * Why authorization is a proof over the spend, not a revealed secret. An earlier
+ * design gated the spend on revealing `ownerSecret` with SHA256(ownerSecret)==
+ * ownerHash — a hash-lock. The secret is exposed in the mempool on the first
+ * spend, and because the spender freely chooses the next owner, a watcher can lift
+ * the revealed secret and broadcast a competing spend redirecting the token to
+ * themselves (front-running theft). Binding authorization to a signature over the
+ * spend fixes this: the signature commits (via SIGHASH_ALL hashOutputs) to the
+ * exact recreated output, including the chosen next owner, so a third party who
+ * alters the destination invalidates the proof. See ./authorizers.
+ *
+ * Layout: <ownerCommit:20> OP_DROP <CODE>. The leading push embeds the state so it
  * rides inside `scriptCode`; OP_DROP discards the runtime copy because CODE reads
  * the authoritative state from the authenticated preimage. Within the scriptCode
  * chunk (varint||script, 3-byte varint for ~480B scripts):
- *   [0:4] = varint||0x20 (prefix), [4:36] = ownerHash, [36:] = 0x75||CODE (suffix)
+ *   [0:4] = varint||0x14 (prefix), [4:24] = ownerCommit, [24:] = 0x75||CODE
  * A transfer rebuilds the chunk as prefix || newOwnerHash || suffix.
  *
- * Unlocking script: <ownerSecret> <newOwnerHash> <preimage>.
+ * Two output shapes:
+ *   ownershipToken(fee, owner[, auth])        — single recreated output, value
+ *       forwarded as (input - fee). The classic perpetual NFT.
+ *   ownershipTokenMulti(owner[, auth])        — the recreated token output may sit
+ *       among other outputs (payments, change, data). The spender reveals the
+ *       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()).
  */
 
 var bsv = require('../..')
-var Hash = require('../crypto/hash')
 var P = require('./pushtx')
 var H = require('./covenant_helpers')
+var A = require('./authorizers')
 
 var Script = bsv.Script
 var Opcode = bsv.Opcode
 var n = H.scriptNum
 
-/** Build the token locking script for a given owner and per-hop fee. */
-function ownershipToken (fee, ownerHash) {
-  if (ownerHash.length !== 32) throw new Error('ownerHash must be 32 bytes (SHA256)')
-  var s = new Script()
-  s.add(Buffer.from(ownerHash)) // <ownerHash:32>
-  s.add(Opcode.OP_DROP)
+function resolveCommit (owner, auth) {
+  var commit = Buffer.isBuffer(owner) ? owner : auth.commit(owner)
+  if (commit.length !== 20) throw new Error('owner commitment must be 20 bytes (HASH160)')
+  return commit
+}
+
+/** Push a possibly-empty buffer MINIMALDATA-cleanly (empty => OP_0). */
+function pushData (s, buf) { return buf.length ? s.add(Buffer.from(buf)) : s.add(Opcode.OP_0) }
 
-  // CODE — stack at entry: [ownerSecret, newOwnerHash, preimage]
+/**
+ * Authenticated head shared by both output shapes. Pre: top of stack = preimage,
+ * with the scheme's authArgs and the next-owner hash beneath it. Post: consumes
+ * the preimage + authArgs, verifies owner authorization, and leaves the next-owner
+ * hash (and any lower unlock items) with the scriptChunk on top; altstack carries
+ * [value8, hashOutputs].
+ */
+function emitAuthHead (s, auth) {
   s.add(Opcode.OP_DUP); P.pushTxCore(s); s.add(Opcode.OP_VERIFY) // authenticate
+  P.assertSighashAll(s) // fail fast unless this spend is SIGHASH_ALL|FORKID (0x41)
 
   // park value (8B @ offsetFromEnd 52) and hashOutputs (32B @ offsetFromEnd 40)
   s.add(Opcode.OP_DUP)
@@ -48,16 +77,53 @@ function ownershipToken (fee, ownerHash) {
   s.add(n(104)).add(Opcode.OP_SPLIT).add(Opcode.OP_NIP)
     .add(Opcode.OP_SIZE).add(n(52)).add(Opcode.OP_SUB).add(Opcode.OP_SPLIT).add(Opcode.OP_DROP)
 
-  // owner authorization: SHA256(ownerSecret) == ownerHash = chunk[4:36] (OP_SUBSTR)
-  s.add(Opcode.OP_DUP).add(n(4)).add(n(32)).add(Opcode.OP_SUBSTR)
-  s.add(n(3)).add(Opcode.OP_ROLL)
-  s.add(Opcode.OP_SHA256).add(Opcode.OP_EQUALVERIFY) // [newOwnerHash, scriptChunk]
+  // expose the authoritative ownerCommit (= chunk[4:24]) and park the chunk
+  s.add(Opcode.OP_DUP).add(n(4)).add(n(20)).add(Opcode.OP_SUBSTR) // [.., scriptChunk, ownerCommit]
+  s.add(Opcode.OP_SWAP).add(Opcode.OP_TOALTSTACK) // alt:[value8, hashOutputs, scriptChunk]; [.., authArgs, ownerCommit]
+
+  auth.emit(s) // consumes authArgs + ownerCommit, VERIFYs authorization over this spend
 
-  // rebuild chunk with new owner: prefix(4) || newOwnerHash || suffix
-  s.add(n(4)).add(Opcode.OP_SPLIT).add(n(32)).add(Opcode.OP_SPLIT).add(Opcode.OP_NIP)
+  s.add(Opcode.OP_FROMALTSTACK) // restore scriptChunk ; alt:[value8, hashOutputs]
+  return s
+}
+
+/**
+ * Rebuild the scriptChunk with the next owner. Pre: [.., newOwnerHash, scriptChunk].
+ * Post: [.., nextChunk] = prefix(4) || newOwnerHash(20) || suffix.
+ */
+function emitRebuild (s) {
+  s.add(n(4)).add(Opcode.OP_SPLIT).add(n(20)).add(Opcode.OP_SPLIT).add(Opcode.OP_NIP) // [.., newOwnerHash, prefix, suffix]
   s.add(Opcode.OP_TOALTSTACK) // park suffix
   s.add(Opcode.OP_SWAP).add(Opcode.OP_CAT) // prefix || newOwnerHash
   s.add(Opcode.OP_FROMALTSTACK).add(Opcode.OP_CAT) // || suffix => nextChunk
+  return s
+}
+
+function assertVarintLen (s) {
+  var len = s.toBuffer().length
+  if (len <= 252 || len > 0xffff) {
+    throw new Error('token script length must use a 3-byte varint (253..65535); got ' + len)
+  }
+  return s
+}
+
+/**
+ * Single-output perpetual NFT: the spend's one output recreates the token with a
+ * (possibly new) owner and value = (input - fee).
+ *
+ * @param {number} fee     satoshis deducted at each hop.
+ * @param {*}      owner    a 20-byte commitment Buffer, or an owner descriptor the
+ *                          authorizer can commit (a key, a key set, ...).
+ * @param {object} [auth]   an Authorizer (default Authorizers.singleKey()).
+ */
+function ownershipToken (fee, owner, auth) {
+  auth = auth || A.singleKey()
+  var s = new Script()
+  s.add(resolveCommit(owner, auth)) // <ownerCommit:20>
+  s.add(Opcode.OP_DROP)
+
+  emitAuthHead(s, auth) // stack: [newOwnerHash, scriptChunk] ; alt:[value8, hashOutputs]
+  emitRebuild(s) // stack: [nextChunk]
 
   // newValue = value - fee (8B LE); nextOutput = newValue || nextChunk
   s.add(Opcode.OP_FROMALTSTACK) // hashOutputs
@@ -68,26 +134,104 @@ function ownershipToken (fee, ownerHash) {
   s.add(Opcode.OP_HASH256)
   s.add(Opcode.OP_EQUAL)
 
-  var len = s.toBuffer().length
-  if (len <= 252 || len > 0xffff) {
-    throw new Error('token script length must use a 3-byte varint (253..65535); got ' + len)
-  }
-  return s
+  return assertVarintLen(s)
 }
 
-/** Owner identifier from a secret. */
-function ownerId (secret) { return Hash.sha256(secret) }
+/**
+ * Multi-output NFT: the recreated token output may sit among other outputs. The
+ * spender reveals the serialized outputs before and after the token output and the
+ * token output's value; the covenant binds them into the committed hashOutputs.
+ * Value conservation across the whole tx is enforced by the network, not the script.
+ *
+ * @param {*}      owner   commitment Buffer or descriptor (see ownershipToken).
+ * @param {object} [auth]  an Authorizer (default Authorizers.singleKey()).
+ */
+function ownershipTokenMulti (owner, auth) {
+  auth = auth || A.singleKey()
+  var s = new Script()
+  s.add(resolveCommit(owner, auth))
+  s.add(Opcode.OP_DROP)
+
+  emitAuthHead(s, auth)
+  // stack: [before, after, tokenValue8, newOwnerHash, scriptChunk] ; alt:[value8, hashOutputs]
+  emitRebuild(s)
+  // stack: [before, after, tokenValue8, nextChunk]
+
+  s.add(Opcode.OP_CAT) // tokenValue8 || nextChunk => tokenOutput ; [before, after, tokenOutput]
+  s.add(Opcode.OP_SWAP).add(Opcode.OP_CAT) // tokenOutput || after ; [before, tokenOutput||after]
+  s.add(Opcode.OP_CAT) // before || tokenOutput || after => allOutputs
 
-/** Unlocking script for a transfer. */
-function unlockTransfer (ownerSecret, newOwnerHash, preimage) {
-  return new Script()
-    .add(Buffer.from(ownerSecret))
-    .add(Buffer.from(newOwnerHash))
-    .add(Buffer.from(preimage))
+  s.add(Opcode.OP_FROMALTSTACK) // hashOutputs ; alt:[value8]
+  s.add(Opcode.OP_FROMALTSTACK).add(Opcode.OP_DROP) // discard the input value (not used in multi mode)
+  s.add(Opcode.OP_SWAP).add(Opcode.OP_HASH256).add(Opcode.OP_EQUAL) // HASH256(allOutputs) == hashOutputs
+
+  return assertVarintLen(s)
+}
+
+/** Owner identifier from a single key: HASH160(ownerPubKey). For other schemes use the authorizer's commit(). */
+function ownerId (key) { return A.singleKey().commit(key) }
+
+/**
+ * Build the unlocking script for a single-output transfer. Grinds the spend so the
+ * in-script OP_PUSH_TX signature is canonical, THEN proves authorization — the
+ * owner's proof must commit to the final tx (nLockTime + outputs), which is what
+ * binds the chosen `newOwnerHash` and defeats front-running.
+ *
+ * @param {*}        signer        descriptor passed to the authorizer's unlockArgs
+ *                                 (a PrivateKey for single-key; { keys, signWith } for multisig).
+ * @param {Buffer}   newOwnerHash  20-byte commitment of the NEXT owner.
+ * @param {Transaction} spend      the spend tx (its single output recreates the token).
+ * @param {number}   satoshis      value of the token UTXO being spent.
+ * @param {Script}   lockingScript the token script being spent.
+ * @param {object}   [opts]        { auth, inputIndex=0, grind }.
+ */
+function unlockTransfer (signer, newOwnerHash, spend, satoshis, lockingScript, opts) {
+  opts = opts || {}
+  var auth = opts.auth || A.singleKey()
+  var inputIndex = opts.inputIndex || 0
+  if (newOwnerHash.length !== 20) throw new Error('newOwnerHash must be 20 bytes (HASH160)')
+  P.grind(spend, inputIndex, lockingScript, satoshis, opts.grind)
+  var preimage = H.rawPreimage(spend, inputIndex, lockingScript, satoshis)
+  var args = auth.unlockArgs(spend, inputIndex, lockingScript, satoshis, signer)
+  var us = new Script().add(Buffer.from(newOwnerHash))
+  args.forEach(function (a) { us.add(a) })
+  us.add(Buffer.from(preimage))
+  return us
+}
+
+/**
+ * Unlocking script for a multi-output transfer (see ownershipTokenMulti).
+ *
+ * @param {object} layout  { before, after, tokenValue } — `before`/`after` are the
+ *                         serialized Output bytes surrounding the token output, and
+ *                         `tokenValue` is the 8-byte LE value of the token output.
+ *                         The spend tx MUST actually contain those outputs in order.
+ */
+function unlockTransferMulti (signer, newOwnerHash, spend, satoshis, lockingScript, layout, opts) {
+  opts = opts || {}
+  var auth = opts.auth || A.singleKey()
+  var inputIndex = opts.inputIndex || 0
+  if (newOwnerHash.length !== 20) throw new Error('newOwnerHash must be 20 bytes (HASH160)')
+  if (!layout || layout.tokenValue == null || layout.tokenValue.length !== 8) {
+    throw new Error('layout.tokenValue must be the 8-byte LE value of the token output')
+  }
+  P.grind(spend, inputIndex, lockingScript, satoshis, opts.grind)
+  var preimage = H.rawPreimage(spend, inputIndex, lockingScript, satoshis)
+  var args = auth.unlockArgs(spend, inputIndex, lockingScript, satoshis, signer)
+  var us = new Script()
+  pushData(us, layout.before || Buffer.alloc(0))
+  pushData(us, layout.after || Buffer.alloc(0))
+  us.add(Buffer.from(layout.tokenValue))
+  us.add(Buffer.from(newOwnerHash))
+  args.forEach(function (a) { us.add(a) })
+  us.add(Buffer.from(preimage))
+  return us
 }
 
 module.exports = {
   ownershipToken: ownershipToken,
+  ownershipTokenMulti: ownershipTokenMulti,
   ownerId: ownerId,
-  unlockTransfer: unlockTransfer
+  unlockTransfer: unlockTransfer,
+  unlockTransferMulti: unlockTransferMulti
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@smartledger/bsv",
-  "version": "5.4.2",
+  "version": "5.5.1",
   "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.",
   "author": "SmartLedger Technology <hello@smartledger.technology> (https://smartledger.technology)",
   "homepage": "https://github.com/codenlighten/smartledger-bsv#readme",
@@ -72,6 +72,8 @@
   "cdn": "bsv.min.js",
   "files": [
     "index.js",
+    "test/",
+    ".mocharc.json",
     "lib/",
     "utilities/*.js",
     "utilities/README.md",