@smartledger/bsv 5.5.3 → 6.0.1

package/lib/smart_contract/covenant.js

@@ -1,15 +1,27 @@
 /**
  * SmartContract.Covenant Class
  * ============================
- * 
- * Production-ready covenant framework with:
- * - Complete P2PKH → Covenant → Spending workflow
- * - Local UTXO storage and portfolio management  
- * - WhatsOnChain API integration ready
- * - BIP-143 preimage validation
- * - Script.Interpreter compliance
- * 
- * Based on examples/covenants2/preimage_covenant_utils.js
+ *
+ * ⚠️ NON-ENFORCING BY DESIGN — NOT A REAL COVENANT. The locking script this class
+ * builds is:
+ *
+ *     OP_DUP OP_HASH256 <creationPreimageHash> OP_EQUALVERIFY OP_DROP <pubkey> OP_CHECKSIG
+ *
+ * `creationPreimageHash` is a CONSTANT baked in at creation time, and the spend
+ * simply re-pushes the stored creation preimage to satisfy it before OP_DROP throws
+ * it away. Nothing binds the SPENDING transaction's outputs or value — the script
+ * reduces to plain P2PK. It does NOT "constrain where coins can go" the way a
+ * covenant must.
+ *
+ * For real, spend-binding covenants use the OP_PUSH_TX primitives, which generate
+ * the signature in-script from the pushed preimage so a passing OP_CHECKSIG proves
+ * the preimage IS this spend:
+ *   - SmartContract.PushTx.valueCovenant(expectedHashOutputs) — bind outputs.
+ *   - SmartContract.Token.ownershipToken / perpetualCovenant       — stateful NFT.
+ *
+ * This class is retained only as a workflow/storage demo. createFromP2PKH() throws
+ * unless you pass { allowNonEnforcing: true } to the constructor, acknowledging the
+ * script enforces no spend constraint.
  */
 
 'use strict'
@@ -54,7 +66,13 @@ function Covenant(privateKey, options) {
   this.covenantUtxoPath = path.join(this.storageDir, 'covenant_utxos.json')
   
   this.sighashType = bsv.crypto.Signature.SIGHASH_ALL | bsv.crypto.Signature.SIGHASH_FORKID
-  
+
+  // The locking script this class builds does NOT constrain the spend (see the
+  // class doc). Require explicit acknowledgement so no one ships it as a real
+  // covenant. Use SmartContract.PushTx.valueCovenant / SmartContract.Token for
+  // genuine spend-binding covenants.
+  this.allowNonEnforcing = options.allowNonEnforcing === true
+
   // Ensure storage directory exists (Node.js only)
   if (fs) {
     this._ensureStorageDir()
@@ -67,6 +85,15 @@ function Covenant(privateKey, options) {
  * @returns {Object} Creation result with transaction and covenant UTXO
  */
 Covenant.prototype.createFromP2PKH = function(utxo) {
+  if (!this.allowNonEnforcing) {
+    throw new Error(
+      'SmartContract.Covenant builds a NON-ENFORCING script that reduces to plain ' +
+      'P2PK — it does not constrain the spend. Use SmartContract.PushTx.valueCovenant ' +
+      '(output binding) or SmartContract.Token / perpetualCovenant (stateful covenants) ' +
+      'for real covenants. To use this demo anyway, construct with ' +
+      '{ allowNonEnforcing: true }.'
+    )
+  }
   // Reconstruct P2PKH script if not provided
   if (!utxo.script) {
     utxo.script = Covenant.reconstructP2pkhScript(this.address)

package/lib/smart_contract/covenant_builder.js

@@ -70,6 +70,9 @@ class CovenantBuilder {
    */
   dup() { this.operations.push('OP_DUP'); return this }
   drop() { this.operations.push('OP_DROP'); return this }
+  // OP_NIP removes the SECOND item, keeping the top. After `OP_SPLIT` the RIGHT
+  // part is on top, so keeping it (dropping the left) requires OP_NIP, not OP_DROP.
+  nip() { this.operations.push('OP_NIP'); return this }
   swap() { this.operations.push('OP_SWAP'); return this }
   over() { this.operations.push('OP_OVER'); return this }
   rot() { this.operations.push('OP_ROT'); return this }
@@ -186,21 +189,20 @@ class CovenantBuilder {
         .push(field.offsetFromEnd)
         .sub()
         .split()
-        .drop() // Drop left part
+        .nip() // OP_SPLIT leaves the RIGHT part on top; drop the LEFT with OP_NIP
         .push(field.length)
         .split()
-        .drop() // Drop remaining, keep field
+        .drop() // field is now the LEFT part; drop the trailing remainder
     } else if (field.strategy === 'DYNAMIC') {
       if (fieldName === 'scriptLen') {
         // Extract scriptLen (varint after outpoint)
         this.push(104) // Fixed left part (4+32+32+36)
           .split()
-          .drop() // Drop left part
+          .nip() // keep the RIGHT part (tail from offset 104); OP_NIP not OP_DROP
           // For now, assume 1-byte varint
           .push(1)
           .split()
-          .swap()
-          .drop() // Keep just the length byte
+          .drop() // length byte is the LEFT part; drop the trailing remainder
       } else {
         throw new Error(`Dynamic extraction for ${fieldName} not implemented`)
       }

package/lib/smart_contract/index.js

@@ -2,22 +2,27 @@
  * SmartContract Module
  * ===================
  *
- * Production-ready covenant functionality for Bitcoin SV (BSV).
- * Implements BIP-143 transaction preimage parsing and covenant operations
- * with comprehensive SIGHASH flag support and error handling.
+ * Covenant functionality for Bitcoin SV (BSV): BIP-143 preimage parsing and
+ * OP_PUSH_TX covenants that constrain a transaction's own spend.
  *
- * Classes:
- * - Covenant: Core covenant creation and spending logic
- * - Preimage: BIP-143 preimage parsing and validation with field extraction
- * - SIGHASH: SIGHASH flag detection and analysis
- * - Builder: High-level covenant construction utilities
- * - UTXOGenerator: Real BSV UTXO generation for authentic testing
- * - ScriptTester: Local script execution and debugging capabilities
- * - CovenantBuilder: JavaScript-to-Bitcoin Script covenant generator
- * - OpcodeMap: Comprehensive Bitcoin Script opcode mapping
- * - ScriptUtils: Script analysis, conversion, and optimization utilities
- * - StackExaminer: Stack state examination and step-by-step execution debugging
- * - ScriptInterpreter: Interactive script debugging with full verification support
+ * ── ENFORCING COVENANT API (canonical — these actually bind the spend) ──
+ * - PushTx: the audited OP_PUSH_TX core (in-script sig gen + OP_CHECKSIG). Now
+ *   supports configurable SIGHASH (pushTxCore({sighashType}), assertSighashType).
+ * - policy() / DSL: declarative covenant DSL that compiles to a verified OP_PUSH_TX
+ *   locking script — the recommended high-level entry point.
+ * - Token: stateful ownership-token (NFT) covenants + ordinals (ordinalLock,
+ *   transferOrdinal). Authorizers: pluggable single-key / multisig / predicate.
+ * - valueCovenant / perpetualCovenant / PELS / Locks: purpose-built primitives.
+ * - CovenantHelpers: rawPreimage, verify, fundAndSpend, sighash helpers.
+ *
+ * ── DEPRECATED, NON-ENFORCING (do NOT use for real covenants) ──
+ * - Covenant, Builder: build a constant hash-lock that reduces to plain P2PK and
+ *   binds nothing about the spend. Both throw unless constructed with
+ *   { allowNonEnforcing: true }. Retained only as workflow/demo scaffolding.
+ *
+ * ── TOOLING (analysis / debugging, not covenant logic) ──
+ * - Preimage, SIGHASH, CovenantBuilder (low-level JS→ASM), OpcodeMap, ScriptUtils,
+ *   StackExaminer, ScriptInterpreter, ScriptTester, UTXOGenerator, Debugger.
  */
 
 'use strict'
@@ -82,6 +87,14 @@ SmartContract.ownershipToken = function (fee, ownerPubKeyHash) {
 SmartContract.valueCovenant = function (expectedHashOutputs) {
   return SmartContract.PushTx.valueCovenant(expectedHashOutputs)
 }
+// Ordinal covenant locking script (value-preserving; safe for 1-sat ordinals).
+SmartContract.ordinalLock = function (owner, auth) {
+  return SmartContract.Token.ordinalLock(owner, auth)
+}
+// Transfer a 1-sat (or N-sat) ordinal without burning it — see Token.transferOrdinal.
+SmartContract.transferOrdinal = function (signer, newOwnerHash, spend, ordinalSats, lockingScript, opts) {
+  return SmartContract.Token.transferOrdinal(signer, newOwnerHash, spend, ordinalSats, lockingScript, opts)
+}
 
 // Convenience constructor methods
 SmartContract.createCovenant = function (privateKey, options) {

package/lib/smart_contract/preimage.js

@@ -529,8 +529,8 @@ Preimage.prototype._generateRightExtractionASM = function(fieldName, includeComm
     instructions = instructions.concat([
       splitPoint + ' OP_SUB     # Calculate split point: [preimage, split_point]',
       'OP_SPLIT                  # Split: [left_part, right_part]',
-      'OP_DROP                   # Drop left: [right_part]',
-      targetLen + ' OP_SPLIT             # Extract field: [remaining, ' + fieldName + ']',
+      'OP_NIP                    # Drop left (OP_SPLIT leaves right on top): [right_part]',
+      targetLen + ' OP_SPLIT             # Extract field: [' + fieldName + ', remaining]',
       'OP_DROP                   # Clean up: [' + fieldName + ']',
       '# ✅ Result: ' + fieldName + ' is now on top of stack'
     ])
@@ -538,7 +538,7 @@ Preimage.prototype._generateRightExtractionASM = function(fieldName, includeComm
     instructions = instructions.concat([
       splitPoint + ' OP_SUB',
       'OP_SPLIT',
-      'OP_DROP',
+      'OP_NIP',
       targetLen + ' OP_SPLIT',
       'OP_DROP'
     ])
@@ -569,7 +569,7 @@ Preimage.prototype._generateLeftExtractionASM = function(fieldName, includeComme
     instructions = [
       '# 🔄 Extract ' + fieldName + ' from LEFT side (bidirectional strategy)',
       fieldInfo.offset + ' OP_SPLIT           # Skip to field: [prefix, remainder]',
-      'OP_DROP                   # Drop prefix: [remainder]',
+      'OP_NIP                    # Drop prefix (OP_SPLIT leaves remainder on top): [remainder]',
       fieldInfo.len + ' OP_SPLIT             # Extract field: [' + fieldName + ', suffix]',
       'OP_DROP                   # Clean up: [' + fieldName + ']',
       '# ✅ Result: ' + fieldName + ' is now on top of stack'
@@ -577,7 +577,7 @@ Preimage.prototype._generateLeftExtractionASM = function(fieldName, includeComme
   } else {
     instructions = [
       fieldInfo.offset + ' OP_SPLIT',
-      'OP_DROP',
+      'OP_NIP',
       fieldInfo.len + ' OP_SPLIT',
       'OP_DROP'
     ]
@@ -596,7 +596,7 @@ Preimage.prototype._generateDynamicExtractionASM = function(parsed, includeComme
   return [
     '# 🎯 Extract scriptCode DYNAMICALLY with CompactSize varint support',
     leftZone + ' OP_SPLIT            # Skip left zone + scriptLen varint: [left_zone, remainder]',
-    'OP_DROP                   # Drop left: [remainder]',
+    'OP_NIP                    # Drop left (OP_SPLIT leaves remainder on top): [remainder]',
     parsed.scriptLen + ' OP_SPLIT             # Extract scriptCode: [scriptCode, right_zone]',
     'OP_DROP                   # Clean up: [scriptCode]',
     '# ✅ Result: scriptCode extracted with ' + parsed.scriptLenSize + '-byte varint awareness'
@@ -611,7 +611,7 @@ Preimage.prototype._generateScriptLenExtractionASM = function(parsed, includeCom
   return [
     '# 🎯 Extract scriptLen CompactSize varint (' + parsed.scriptLenSize + ' bytes)',
     '104 OP_SPLIT            # Skip left fixed fields: [left_zone, remainder]',
-    'OP_DROP                   # Drop left: [remainder]',
+    'OP_NIP                    # Drop left (OP_SPLIT leaves remainder on top): [remainder]',
     parsed.scriptLenSize + ' OP_SPLIT             # Extract varint: [scriptLen_varint, suffix]',
     'OP_DROP                   # Clean up: [scriptLen_varint]',
     '# ✅ Result: CompactSize varint (decode off-chain to get ' + parsed.scriptLen + ')'

package/lib/smart_contract/pushtx.js

@@ -38,7 +38,6 @@ var N_LE = Buffer.concat([Buffer.from(N.toBuffer()).reverse(), Buffer.from([0x00
 
 // fixed DER prefix: SEQUENCE(0x44) INTEGER(0x20) r=Gx INTEGER(0x20)
 var DER_PREFIX = Buffer.concat([Buffer.from([0x30, 0x44, 0x02, 0x20]), Gx, Buffer.from([0x02, 0x20])])
-var SIGHASH_BYTE = Buffer.from([SIGHASH]) // 0x41
 
 /** Reverse a fixed n-byte buffer on top of the stack (big-endian <-> little-endian). */
 function reverseBytes (script, n) {
@@ -48,11 +47,36 @@ function reverseBytes (script, n) {
   return script
 }
 
+// Common SIGHASH flag combinations (all include FORKID, required on BSV). The
+// marketplace/partially-signed pattern uses SINGLE|ANYONECANPAY: the signer commits
+// only to its own input and its own output (the output at the same index), leaving
+// a counterparty free to add funding inputs and change outputs without invalidating
+// the signature.
+var Signature = bsv.crypto.Signature
+var SIGHASH_ALL_FORKID = Signature.SIGHASH_ALL | Signature.SIGHASH_FORKID // 0x41
+var SIGHASH_SINGLE_FORKID = Signature.SIGHASH_SINGLE | Signature.SIGHASH_FORKID // 0x43
+var SIGHASH_SINGLE_ANYONECANPAY_FORKID =
+  Signature.SIGHASH_SINGLE | Signature.SIGHASH_ANYONECANPAY | Signature.SIGHASH_FORKID // 0xc3
+// ALL|ANYONECANPAY commits to ALL outputs (so the covenant can pin the FULL output
+// set) while leaving inputs open for a counterparty to add funding. This is the flag
+// the 1Sat Ordinals OrdLock uses: the buyer supplies the surrounding outputs and the
+// covenant binds the seller's payment output into the committed hashOutputs.
+var SIGHASH_ALL_ANYONECANPAY_FORKID =
+  Signature.SIGHASH_ALL | Signature.SIGHASH_ANYONECANPAY | Signature.SIGHASH_FORKID // 0xc1
+
 /**
  * Append the in-script signature generator + verifier ("PUSH_TX core").
  * Pre:  top of stack = preimage. Post: top = OP_CHECKSIG result.
+ *
+ * @param {Script} script
+ * @param {object} [opts]
+ * @param {number} [opts.sighashType=0x41] the SIGHASH flag byte baked into the
+ *   synthetic signature. OP_CHECKSIG derives the spend's sighash using THIS flag,
+ *   so the spender must push the matching BIP-143 preimage (grind with the same
+ *   sighashType). Defaults to SIGHASH_ALL|FORKID — existing covenants are unchanged.
  */
-function pushTxCore (script) {
+function pushTxCore (script, opts) {
+  var sighashType = (opts && opts.sighashType) || SIGHASH
   script.add(Opcode.OP_HASH256) // z = HASH256(preimage), 32B BE
   reverseBytes(script, 32) // -> little-endian = e. The grind guarantees e is
   // already positive and minimally encoded (z[0] in 0x01..0x7f), so NO 0x00 sign
@@ -70,7 +94,7 @@ function pushTxCore (script) {
   script.add(Buffer.from([0x30, 0x44, 0x02, 0x20])).add(Opcode.OP_SWAP).add(Opcode.OP_CAT) // 30440220||Gx
   script.add(Buffer.from([0x02, 0x20])).add(Opcode.OP_CAT) // ||0220  => DER prefix
   script.add(Opcode.OP_SWAP).add(Opcode.OP_CAT) // DER prefix || s_be
-  script.add(SIGHASH_BYTE).add(Opcode.OP_CAT) // || sighash flag => full DER sig
+  script.add(Buffer.from([sighashType])).add(Opcode.OP_CAT) // || sighash flag => full DER sig
   script.add(Opcode.OP_FROMALTSTACK).add(Opcode.OP_CHECKSIG) // pubkey ; verify against P = G
   return script
 }
@@ -88,8 +112,7 @@ function extractHashOutputs (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])
+// FORKID that word is 0x41 00 00 00. assertSighashType builds this word per flag.
 
 /**
  * Assert the spend is SIGHASH_ALL|FORKID (0x41). Pre/Post: top of stack = preimage
@@ -104,8 +127,19 @@ var SIGHASH_WORD = Buffer.from([SIGHASH, 0x00, 0x00, 0x00])
  * flag assumption explicit and fails fast — and survives any refactor of the core.
  */
 function assertSighashAll (script) {
+  return assertSighashType(script, SIGHASH)
+}
+
+/**
+ * Assert the spend uses a specific SIGHASH flag. Pre/Post: top of stack = preimage
+ * (left untouched). The BIP-143 preimage's trailing 4-byte LE nHashType word must
+ * equal `sighashType`. Use with pushTxCore({ sighashType }) + grind({ sighashType })
+ * to build covenants under SIGHASH_SINGLE|ANYONECANPAY (marketplace) etc.
+ */
+function assertSighashType (script, sighashType) {
+  var word = Buffer.from([sighashType & 0xff, 0x00, 0x00, 0x00])
   script.add(Opcode.OP_DUP).add(scriptNum(4)).add(Opcode.OP_RIGHT)
-    .add(SIGHASH_WORD).add(Opcode.OP_EQUALVERIFY)
+    .add(word).add(Opcode.OP_EQUALVERIFY)
   return script
 }
 
@@ -171,6 +205,7 @@ function grind (spend, inputIndex, lockingScript, satoshis, opts) {
   var maxTries = opts.maxTries || 5000
   var start = opts.start || 0
   var field = opts.field || 'nLockTime'
+  var sighashType = opts.sighashType || SIGHASH
   if (field !== 'nLockTime' && field !== 'sequence') {
     throw new Error("grind field must be 'nLockTime' or 'sequence'")
   }
@@ -179,7 +214,7 @@ function grind (spend, inputIndex, lockingScript, satoshis, opts) {
     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)
+    var preimage = H.rawPreimage(spend, inputIndex, lockingScript, satoshis, sighashType)
     if (sFromPreimage(preimage)) return { preimage: preimage, tries: i + 1, field: field, nonce: nonce }
   }
   throw new Error('OP_PUSH_TX grind failed after ' + maxTries + ' tries')
@@ -197,6 +232,11 @@ module.exports = {
   authenticator: authenticator,
   extractHashOutputs: extractHashOutputs,
   assertSighashAll: assertSighashAll,
+  assertSighashType: assertSighashType,
+  SIGHASH_ALL_FORKID: SIGHASH_ALL_FORKID,
+  SIGHASH_SINGLE_FORKID: SIGHASH_SINGLE_FORKID,
+  SIGHASH_SINGLE_ANYONECANPAY_FORKID: SIGHASH_SINGLE_ANYONECANPAY_FORKID,
+  SIGHASH_ALL_ANYONECANPAY_FORKID: SIGHASH_ALL_ANYONECANPAY_FORKID,
   hashOutputs: hashOutputs,
   valueCovenant: valueCovenant,
   sFromPreimage: sFromPreimage,

package/lib/smart_contract/token.js

@@ -190,6 +190,16 @@ function unlockTransfer (signer, newOwnerHash, spend, satoshis, lockingScript, o
   var auth = opts.auth || A.singleKey()
   var inputIndex = opts.inputIndex || 0
   if (newOwnerHash.length !== 20) throw new Error('newOwnerHash must be 20 bytes (HASH160)')
+  // Guardrail: the single-output form forces the recreated output value to
+  // (input - fee), so a 1-sat UTXO — e.g. a 1-sat ordinal — cannot survive any
+  // fee: the satoshi carrying the inscription is burned. Refuse it and point to
+  // the value-preserving path. Opt out with { allowLowValue: true } if you really
+  // mean a single-output, fee-absorbing token on a tiny UTXO.
+  if (satoshis <= 1 && !opts.allowLowValue) {
+    throw new Error('unlockTransfer: single-output token sets output = input - fee, ' +
+      'which burns a ' + satoshis + '-sat UTXO (e.g. a 1-sat ordinal). Use ' +
+      'Token.transferOrdinal / ownershipTokenMulti to preserve the satoshi.')
+  }
   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)
@@ -228,10 +238,68 @@ function unlockTransferMulti (signer, newOwnerHash, spend, satoshis, lockingScri
   return us
 }
 
+/**
+ * Locking script for a transferable ordinal held in a covenant. This is exactly
+ * the multi-output token (the single-output form burns 1-sat UTXOs), named for
+ * intent: the token output carries its OWN value, so the ordinal's satoshi is
+ * preserved while fees are paid from separate funding inputs/outputs.
+ */
+function ordinalLock (owner, auth) { return ownershipTokenMulti(owner, auth) }
+
+/**
+ * Transfer a 1-sat (or N-sat) ordinal held under an ordinalLock/ownershipTokenMulti
+ * covenant WITHOUT burning it. Derives the multi-output layout from the spend the
+ * caller has already built, and enforces that the recreated token output carries
+ * EXACTLY the ordinal's satoshis so the inscribed sat survives.
+ *
+ * The caller builds `spend` with the ordinal covenant input at `opts.inputIndex`
+ * (default 0), the recreated token output at `opts.tokenIndex` (default 0, so the
+ * ordinal's first sat maps to the token output's first sat under ordinal FIFO),
+ * funding input(s) for the fee, and a change output. Fees come from the funding,
+ * never from the ordinal.
+ *
+ * @param {*}            signer        authorizer signer (PrivateKey for single-key).
+ * @param {Buffer}       newOwnerHash  20-byte commitment of the next owner.
+ * @param {Transaction}  spend         the spend tx (already carrying the outputs).
+ * @param {number}       ordinalSats   satoshis on the ordinal UTXO (default 1).
+ * @param {Script}       lockingScript the ordinal covenant script being spent.
+ * @param {object}       [opts]        { auth, inputIndex=0, tokenIndex=0, grind }.
+ * @returns {Script} the unlocking script for the ordinal input.
+ */
+function transferOrdinal (signer, newOwnerHash, spend, ordinalSats, lockingScript, opts) {
+  opts = opts || {}
+  if (ordinalSats == null) ordinalSats = 1
+  var tokenIndex = opts.tokenIndex || 0
+  var outs = spend.outputs || []
+  var tokenOut = outs[tokenIndex]
+  if (!tokenOut) {
+    throw new Error('transferOrdinal: spend has no output at tokenIndex ' + tokenIndex)
+  }
+  // Anti-burn: the recreated token output must carry EXACTLY the ordinal's value.
+  if (tokenOut.satoshis !== ordinalSats) {
+    throw new Error('transferOrdinal: token output value (' + tokenOut.satoshis +
+      ' sat) must equal the ordinal value (' + ordinalSats + ' sat) to avoid ' +
+      'burning the inscription')
+  }
+  // Derive the covenant layout: serialized outputs before/after the token output.
+  function ser (o) { return o.toBufferWriter().toBuffer() }
+  var before = Buffer.concat(outs.slice(0, tokenIndex).map(ser))
+  var after = Buffer.concat(outs.slice(tokenIndex + 1).map(ser))
+  var tokenValue = new bsv.crypto.BN(ordinalSats).toBuffer({ endian: 'little', size: 8 })
+
+  return unlockTransferMulti(signer, newOwnerHash, spend, ordinalSats, lockingScript, {
+    before: before,
+    after: after,
+    tokenValue: tokenValue
+  }, opts)
+}
+
 module.exports = {
   ownershipToken: ownershipToken,
   ownershipTokenMulti: ownershipTokenMulti,
+  ordinalLock: ordinalLock,
   ownerId: ownerId,
   unlockTransfer: unlockTransfer,
-  unlockTransferMulti: unlockTransferMulti
+  unlockTransferMulti: unlockTransferMulti,
+  transferOrdinal: transferOrdinal
 }

package/lib/spv/headerchain.js

@@ -0,0 +1,77 @@
+'use strict'
+/**
+ * SPV block-header chain verification — the confirmations half of the SPV story.
+ *
+ * verifyTxInclusion proves a tx is in a SUPPLIED header; this proves that header is
+ * buried under real work by verifying a chain of consecutive headers: each links to
+ * the previous (prevHash), each meets its own proof-of-work target, and (optionally)
+ * the chain is anchored at a hash the caller independently trusts.
+ *
+ * TRUST MODEL — read this. It validates linkage + PER-HEADER proof-of-work, but NOT
+ * the difficulty-retargeting schedule. A determined attacker can mine cheap headers
+ * at an artificially easy `bits`, so PoW-per-header alone is not sufficient in an
+ * adversarial setting. For real assurance pass `opts.trustedHash` — a block hash you
+ * already trust (from your own node, or a hardcoded checkpoint) that the chain's tip
+ * (or anchor) must match; the headers around it are then real work extending a block
+ * you trust. Full difficulty-retarget validation is intentionally out of scope here.
+ */
+var bsv = require('../..')
+
+function rev (b) { return Buffer.from(b).reverse() }
+
+function toHeader (h) {
+  if (h && typeof h.validProofOfWork === 'function') return h
+  if (Buffer.isBuffer(h)) return bsv.BlockHeader.fromBuffer(h)
+  if (typeof h === 'string') return bsv.BlockHeader.fromBuffer(Buffer.from(h, 'hex'))
+  throw new Error('each header must be a BlockHeader, an 80-byte Buffer, or hex')
+}
+
+/**
+ * @param {Array} headers  consecutive headers, oldest→newest (BlockHeader/Buffer/hex).
+ * @param {object} [opts]
+ *   requirePow {boolean=true}  verify each header meets its bits target.
+ *   trustedHash {string}       a block hash the chain's tip or anchor must equal.
+ * @returns {{ valid, reason?, count, anchorHash, tipHash, work }}
+ */
+function verifyHeaderChain (headers, opts) {
+  opts = opts || {}
+  if (!Array.isArray(headers) || headers.length === 0) {
+    throw new Error('headers must be a non-empty array')
+  }
+  var hs = headers.map(toHeader)
+  var requirePow = opts.requirePow !== false
+  var work = 0
+
+  for (var i = 0; i < hs.length; i++) {
+    if (requirePow && !hs[i].validProofOfWork()) {
+      return { valid: false, reason: 'invalid proof-of-work at index ' + i, count: hs.length }
+    }
+    work += hs[i].getDifficulty()
+    if (i > 0) {
+      var linkOk = rev(hs[i].prevHash).toString('hex').toLowerCase() === hs[i - 1].id.toLowerCase()
+      if (!linkOk) {
+        return { valid: false, reason: 'broken link at index ' + i, count: hs.length }
+      }
+    }
+  }
+
+  var anchorHash = hs[0].id
+  var tipHash = hs[hs.length - 1].id
+
+  if (opts.trustedHash) {
+    var t = String(opts.trustedHash).toLowerCase()
+    if (t !== tipHash.toLowerCase() && t !== anchorHash.toLowerCase()) {
+      return {
+        valid: false,
+        reason: 'chain is not anchored at the trusted hash',
+        count: hs.length,
+        anchorHash: anchorHash,
+        tipHash: tipHash
+      }
+    }
+  }
+
+  return { valid: true, count: hs.length, anchorHash: anchorHash, tipHash: tipHash, work: work }
+}
+
+module.exports = { verifyHeaderChain: verifyHeaderChain }

package/lib/spv/index.js

@@ -0,0 +1,16 @@
+'use strict'
+/**
+ * SPV — trustless Simplified Payment Verification helpers.
+ *
+ * Currently: Merkle inclusion proofs (verify a tx is in a PoW-backed block without
+ * a full node). Built on the fork's BlockHeader / MerkleBlock primitives.
+ */
+var merkleproof = require('./merkleproof')
+var headerchain = require('./headerchain')
+
+module.exports = {
+  merkleRootFromBranch: merkleproof.merkleRootFromBranch,
+  verifyMerkleProof: merkleproof.verifyMerkleProof,
+  verifyTxInclusion: merkleproof.verifyTxInclusion,
+  verifyHeaderChain: headerchain.verifyHeaderChain
+}

package/lib/spv/merkleproof.js

@@ -0,0 +1,108 @@
+'use strict'
+/**
+ * SPV Merkle inclusion proofs.
+ *
+ * Trustlessly verify that a transaction is included in a block, given a Merkle
+ * branch proof and a trusted block header — no full node and no trust in the data
+ * provider. This is the real inclusion check that replaces the "trust the caller's
+ * txData" anchor stubs: a provider (explorer / node) can lie about a tx being mined,
+ * but it cannot forge a Merkle branch that hashes to a proof-of-work-backed header's
+ * merkle root.
+ *
+ * Byte order: `txid`, branch `nodes` and `merkleRoot` are DISPLAY-order hex (big
+ * endian, as block explorers show them). Bitcoin hashes internally in little-endian,
+ * so we reverse on the way in/out. Nodes are combined with double-SHA256, matching
+ * lib/block/{block,merkleblock}.js. A node of '*' (or '' / null) means "duplicate the
+ * working hash" — Bitcoin's odd-node rule, per the TSC Merkle Proof standard.
+ */
+var bsv = require('../..')
+var Hash = bsv.crypto.Hash
+
+var HEX32 = /^[0-9a-fA-F]{64}$/
+
+function rev (buf) { return Buffer.from(buf).reverse() }
+function toInternal (hex) { return rev(Buffer.from(hex, 'hex')) } // display -> internal LE
+function toDisplay (buf) { return rev(buf).toString('hex') }      // internal LE -> display
+
+/**
+ * Recompute the Merkle root from a branch proof.
+ * @param {string} txid       display-order txid hex (64 hex chars)
+ * @param {number} index      0-based position of the tx within the block
+ * @param {Array<string>} nodes sibling hashes, leaf->root (display hex; '*' = duplicate)
+ * @returns {string} the computed merkle root (display-order hex)
+ */
+function merkleRootFromBranch (txid, index, nodes) {
+  if (!HEX32.test(String(txid))) throw new Error('txid must be 32-byte hex')
+  if (!Number.isInteger(index) || index < 0) throw new Error('index must be a non-negative integer')
+  nodes = nodes || []
+  var cur = toInternal(txid)
+  var idx = index
+  for (var i = 0; i < nodes.length; i++) {
+    var node = nodes[i]
+    var sib
+    if (node === '*' || node === '' || node == null) {
+      sib = cur // odd-node: the working hash is duplicated
+    } else {
+      if (!HEX32.test(String(node))) throw new Error('proof node ' + i + ' must be 32-byte hex or "*"')
+      sib = toInternal(node)
+    }
+    // idx even -> current is the LEFT child; idx odd -> current is the RIGHT child.
+    cur = (idx & 1)
+      ? Hash.sha256sha256(Buffer.concat([sib, cur]))
+      : Hash.sha256sha256(Buffer.concat([cur, sib]))
+    idx = Math.floor(idx / 2)
+  }
+  return toDisplay(cur)
+}
+
+/**
+ * Verify a Merkle branch proof against an expected root.
+ * @param {object} proof { txid, index, nodes, merkleRoot } (all display-order hex)
+ * @returns {boolean}
+ */
+function verifyMerkleProof (proof) {
+  if (!proof || !proof.merkleRoot) throw new Error('proof.merkleRoot is required')
+  var computed = merkleRootFromBranch(proof.txid, proof.index, proof.nodes)
+  return computed.toLowerCase() === String(proof.merkleRoot).toLowerCase()
+}
+
+/**
+ * Verify a transaction is included in a block: branch -> root, root ==
+ * header.merkleRoot, and (unless disabled) the header meets its PoW target.
+ *
+ * NOTE: this proves inclusion in the SUPPLIED header. Confirming that header is on
+ * the honest chain (height / confirmations) requires a trusted header chain, which
+ * the caller supplies out of band.
+ *
+ * @param {object} params { txid, index, nodes, header, requirePow=true }
+ *   header: a bsv.BlockHeader, an 80-byte Buffer, or 80-byte hex.
+ * @returns {{ valid:boolean, rootMatches:boolean, powValid:boolean, merkleRoot:string, blockHash:string }}
+ */
+function verifyTxInclusion (params) {
+  var header = params.header
+  if (Buffer.isBuffer(header) || typeof header === 'string') {
+    header = bsv.BlockHeader.fromBuffer(Buffer.isBuffer(header) ? header : Buffer.from(header, 'hex'))
+  }
+  if (!header || !header.merkleRoot) throw new Error('a valid block header is required')
+
+  var headerRoot = toDisplay(header.merkleRoot) // header stores the root internal-LE
+  var computed = merkleRootFromBranch(params.txid, params.index, params.nodes)
+  var rootMatches = computed.toLowerCase() === headerRoot.toLowerCase()
+
+  var requirePow = params.requirePow !== false
+  var powValid = header.validProofOfWork()
+
+  return {
+    valid: rootMatches && (!requirePow || powValid),
+    rootMatches: rootMatches,
+    powValid: powValid,
+    merkleRoot: computed,
+    blockHash: header.id
+  }
+}
+
+module.exports = {
+  merkleRootFromBranch: merkleRootFromBranch,
+  verifyMerkleProof: verifyMerkleProof,
+  verifyTxInclusion: verifyTxInclusion
+}