@smartledger/bsv 4.1.0 → 4.4.0

package/lib/smart_contract/pels.js

@@ -0,0 +1,61 @@
+'use strict'
+/**
+ * SmartContract.PELS — a Perpetually Enforcing Locking Script (nChain WP1605).
+ *
+ * A covenant that forces every spend to recreate itself: the single output must
+ * pay (inputValue - fee) back into the SAME locking script. Coins never leave
+ * the covenant — they flow forward through identical UTXOs, shrinking by the fee.
+ *
+ * It avoids self-hash circularity by reading its own script out of the
+ * authenticated BIP-143 preimage's `scriptCode` field. With layout
+ *   version(4) hashPrevouts(32) hashSequence(32) outpoint(36) = 104
+ *   scriptCode(varint||script)
+ *   value(8) nSequence(4) hashOutputs(32) nLockTime(4) sighash(4) = 52 (tail)
+ * 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()).
+ */
+
+var bsv = require('../..')
+var P = require('./pushtx')
+var H = require('./covenant_helpers')
+
+var Script = bsv.Script
+var Opcode = bsv.Opcode
+var n = H.scriptNum
+
+/**
+ * @param {number} fee satoshis deducted at each hop.
+ * @returns {Script} the perpetual locking script.
+ */
+function pelsCovenant (fee) {
+  var s = new Script()
+
+  // 1. authenticate the pushed preimage
+  s.add(Opcode.OP_DUP)
+  P.pushTxCore(s)
+  s.add(Opcode.OP_VERIFY) // stack: [preimage]
+
+  // 2. scriptChunk = preimage[104 : len-52]
+  s.add(Opcode.OP_DUP)
+  s.add(n(104)).add(Opcode.OP_SPLIT).add(Opcode.OP_NIP)
+  s.add(Opcode.OP_SIZE).add(n(52)).add(Opcode.OP_SUB).add(Opcode.OP_SPLIT).add(Opcode.OP_DROP)
+
+  // 3. value (8B @ offsetFromEnd 52); newValue = value - fee, as 8-byte LE
+  s.add(Opcode.OP_OVER)
+  s.add(n(52)).add(Opcode.OP_RIGHT).add(n(8)).add(Opcode.OP_LEFT) // last 52 bytes, first 8 = value
+  s.add(Opcode.OP_BIN2NUM).add(n(fee)).add(Opcode.OP_SUB)
+  s.add(n(8)).add(Opcode.OP_NUM2BIN)
+
+  // 4. nextOutput = newValue8 || scriptChunk ; require HASH256(it) == hashOutputs
+  s.add(Opcode.OP_SWAP).add(Opcode.OP_CAT)
+  s.add(Opcode.OP_HASH256)
+  s.add(Opcode.OP_SWAP)
+  P.extractHashOutputs(s)
+  s.add(Opcode.OP_EQUAL)
+
+  return s
+}
+
+module.exports = { pelsCovenant: pelsCovenant }

package/lib/smart_contract/pushtx.js

@@ -0,0 +1,155 @@
+'use strict'
+/**
+ * SmartContract.PushTx — a correct, interpreter-verified OP_PUSH_TX (nChain
+ * WP1605) for Bitcoin SV.
+ *
+ * The locking script GENERATES an ECDSA signature in-script from a preimage the
+ * spender pushed, then OP_CHECKSIG verifies it against a fixed public key.
+ * OP_CHECKSIG only passes if the message it derives internally (the genuine
+ * BIP-143 sighash of THIS spend) equals HASH256(preimage) — so a passing check
+ * proves the pushed preimage IS this transaction, letting a script read and
+ * constrain its own spending transaction.
+ *
+ * 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.
+ */
+
+var bsv = require('../..')
+var BN = require('../crypto/bn')
+var Hash = require('../crypto/hash')
+var H = require('./covenant_helpers')
+
+var Script = bsv.Script
+var Opcode = bsv.Opcode
+var SIGHASH = H.SIGHASH
+var scriptNum = H.scriptNum
+
+// secp256k1 constants (big-endian)
+var Gx = Buffer.from('79be667ef9dcbbac55a06295ce870b07029bfcdb2dce28d959f2815b16f81798', 'hex')
+var N = new BN('fffffffffffffffffffffffffffffffebaaedce6af48a03bbfd25e8cd0364141', 16)
+var PUBKEY = Buffer.concat([Buffer.from([0x02]), Gx]) // compressed P = G (y even)
+
+// script-number (little-endian) forms
+var gxLe = Buffer.from(Gx).reverse() // 32B, top 0x79 => positive
+var N_LE = Buffer.concat([Buffer.from(N.toBuffer()).reverse(), Buffer.from([0x00])]) // 33B positive
+
+// 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) {
+  var i
+  for (i = 0; i < n - 1; i++) script.add(Opcode.OP_1).add(Opcode.OP_SPLIT)
+  for (i = 0; i < n - 1; i++) script.add(Opcode.OP_SWAP).add(Opcode.OP_CAT)
+  return script
+}
+
+/**
+ * Append the in-script signature generator + verifier ("PUSH_TX core").
+ * Pre:  top of stack = preimage. Post: top = OP_CHECKSIG result.
+ */
+function pushTxCore (script) {
+  script.add(Opcode.OP_HASH256) // z = HASH256(preimage), 32B BE
+  reverseBytes(script, 32) // -> little-endian
+  script.add(Buffer.from([0x00])).add(Opcode.OP_CAT).add(Opcode.OP_BIN2NUM) // e (positive)
+  script.add(gxLe).add(Opcode.OP_ADD) // e + Gx
+  script.add(N_LE).add(Opcode.OP_MOD) // s = (e + Gx) mod n
+  script.add(scriptNum(32)).add(Opcode.OP_NUM2BIN) // s -> 32-byte LE
+  reverseBytes(script, 32) // -> big-endian (DER INTEGER body) ; stack: [s_be]
+  // Build the DER signature and the pubkey from a SINGLE Gx push (Gx is both the
+  // r-value inside the DER prefix and the body of the 02||Gx pubkey). Sharing it
+  // via the altstack saves a 32-byte constant vs. embedding Gx twice.
+  script.add(Gx).add(Opcode.OP_DUP) // [s_be, Gx, Gx]
+  script.add(Buffer.from([0x02])).add(Opcode.OP_SWAP).add(Opcode.OP_CAT) // pubkey = 02||Gx
+  script.add(Opcode.OP_TOALTSTACK) // park pubkey ; [s_be, Gx]
+  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(Opcode.OP_FROMALTSTACK).add(Opcode.OP_CHECKSIG) // pubkey ; verify against P = G
+  return script
+}
+
+/** Bare authenticator script: unlock with the (grindable) preimage. */
+function authenticator () {
+  return pushTxCore(new Script())
+}
+
+/** Extract the committed hashOutputs (item 9, offsetFromEnd 40, len 32) from a preimage on-stack. */
+function extractHashOutputs (script) {
+  // last 40 bytes, then the first 32 of those = hashOutputs. (BSV string opcodes.)
+  script.add(scriptNum(40)).add(Opcode.OP_RIGHT).add(scriptNum(32)).add(Opcode.OP_LEFT)
+  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() }))
+  return Hash.sha256sha256(ser)
+}
+
+/**
+ * Value/output covenant: the spend is valid only if its outputs hash to
+ * `expectedHashOutputs` — coins can only go where the covenant says.
+ */
+function valueCovenant (expectedHashOutputs) {
+  var script = new Script().add(Opcode.OP_DUP)
+  pushTxCore(script)
+  script.add(Opcode.OP_VERIFY)
+  extractHashOutputs(script)
+  script.add(Buffer.from(expectedHashOutputs)).add(Opcode.OP_EQUAL)
+  return script
+}
+
+// floor(n/2) — the canonical low-S boundary (matches Signature.hasLowS()).
+var HALF_N = new BN('7FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF5D576E7357A4501DDFE92F46681B20A0', 'hex')
+
+/**
+ * Compute s = (HASH256(preimage)+Gx) mod n; return its 32-byte BE form, or null
+ * if the resulting signature would not be a clean, CANONICAL (low-S) DER.
+ * Requiring s <= n/2 makes the in-script signature non-malleable and standard,
+ * so it passes nodes enforcing SCRIPT_VERIFY_LOW_S — at zero script-size cost
+ * (the burden is on the spender's grind, not extra opcodes).
+ */
+function sFromPreimage (preimage) {
+  var z = Hash.sha256sha256(preimage)
+  var s = new BN(z).add(new BN(Gx)).mod(N)
+  if (s.gt(HALF_N)) return null // enforce low-S (canonical / non-malleable)
+  var sBE = s.toBuffer('be', 32)
+  return (sBE[0] >= 0x01) ? sBE : null // s <= n/2 already guarantees sBE[0] <= 0x7f
+}
+
+/**
+ * Grind the spend tx (vary nLockTime) until the in-script signature is a clean
+ * fixed-length DER. Mutates spend.nLockTime; returns { preimage, tries }.
+ */
+function grind (spend, inputIndex, lockingScript, satoshis, maxTries) {
+  maxTries = maxTries || 5000
+  for (var t = 0; t < maxTries; t++) {
+    spend.nLockTime = t
+    var preimage = H.rawPreimage(spend, inputIndex, lockingScript, satoshis)
+    if (sFromPreimage(preimage)) return { preimage: preimage, tries: t + 1 }
+  }
+  throw new Error('OP_PUSH_TX grind failed after ' + maxTries + ' tries')
+}
+
+module.exports = {
+  Gx: Gx,
+  N: N,
+  PUBKEY: PUBKEY,
+  gxLe: gxLe,
+  N_LE: N_LE,
+  DER_PREFIX: DER_PREFIX,
+  reverseBytes: reverseBytes,
+  pushTxCore: pushTxCore,
+  authenticator: authenticator,
+  extractHashOutputs: extractHashOutputs,
+  hashOutputs: hashOutputs,
+  valueCovenant: valueCovenant,
+  sFromPreimage: sFromPreimage,
+  grind: grind
+}

package/lib/smart_contract/token.js

@@ -0,0 +1,93 @@
+'use strict'
+/**
+ * SmartContract.Token — a stateful ownership token (NFT) covenant.
+ *
+ * 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.
+ *
+ * Layout: <ownerHash:32> 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)
+ * A transfer rebuilds the chunk as prefix || newOwnerHash || suffix.
+ *
+ * Unlocking script: <ownerSecret> <newOwnerHash> <preimage>.
+ * Requires post-Genesis limits (SmartContract.enableGenesis()).
+ */
+
+var bsv = require('../..')
+var Hash = require('../crypto/hash')
+var P = require('./pushtx')
+var H = require('./covenant_helpers')
+
+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)
+
+  // CODE — stack at entry: [ownerSecret, newOwnerHash, preimage]
+  s.add(Opcode.OP_DUP); P.pushTxCore(s); s.add(Opcode.OP_VERIFY) // authenticate
+
+  // park value (8B @ offsetFromEnd 52) and hashOutputs (32B @ offsetFromEnd 40)
+  s.add(Opcode.OP_DUP)
+    .add(n(52)).add(Opcode.OP_RIGHT).add(n(8)).add(Opcode.OP_LEFT).add(Opcode.OP_TOALTSTACK) // alt:[value8]
+  s.add(Opcode.OP_DUP); P.extractHashOutputs(s); s.add(Opcode.OP_TOALTSTACK) // alt:[value8, hashOutputs]
+
+  // scriptChunk = preimage[104 : len-52] (consumes preimage)
+  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]
+
+  // 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_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
+
+  // newValue = value - fee (8B LE); nextOutput = newValue || nextChunk
+  s.add(Opcode.OP_FROMALTSTACK) // hashOutputs
+  s.add(Opcode.OP_SWAP)
+  s.add(Opcode.OP_FROMALTSTACK) // value8
+  s.add(Opcode.OP_BIN2NUM).add(n(fee)).add(Opcode.OP_SUB).add(n(8)).add(Opcode.OP_NUM2BIN)
+  s.add(Opcode.OP_SWAP).add(Opcode.OP_CAT)
+  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
+}
+
+/** Owner identifier from a secret. */
+function ownerId (secret) { return Hash.sha256(secret) }
+
+/** 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))
+}
+
+module.exports = {
+  ownershipToken: ownershipToken,
+  ownerId: ownerId,
+  unlockTransfer: unlockTransfer
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@smartledger/bsv",
-  "version": "4.1.0",
+  "version": "4.4.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.",
   "author": "SmartLedger Technology <hello@smartledger.technology> (https://smartledger.technology)",
   "homepage": "https://github.com/codenlighten/smartledger-bsv#readme",