@smartledger/bsv 5.5.3 → 6.0.1

package/lib/ltp/obligation.js

@@ -3,9 +3,35 @@
 var bsv = require('../../')
 var Hash = bsv.crypto.Hash
 var ECDSA = bsv.crypto.ECDSA
+var Signature = bsv.crypto.Signature
 var PrivateKey = bsv.PrivateKey
 var $ = bsv.util.preconditions
 
+/**
+ * Resolve the AUTHORITATIVE signer public key for a token: the issuer's key,
+ * bound to identity (never a key named inside the token's own proof, which a
+ * forger controls). did:smartledger embeds the pubkey in the DID itself. Callers
+ * may override with options.issuerPublicKey. Returns null when unresolvable —
+ * callers MUST fail closed on null.
+ */
+function _resolveIssuerPublicKey (token, options) {
+  options = options || {}
+  if (options.issuerPublicKey) {
+    return options.issuerPublicKey instanceof bsv.PublicKey
+      ? options.issuerPublicKey
+      : bsv.PublicKey.fromString(options.issuerPublicKey)
+  }
+  var did = token && token.issuer
+  if (typeof did !== 'string') return null
+  try {
+    var identifier = did.split('#')[0].split(':')[2] // did:method:<identifier>[:...]
+    if (!identifier) return null
+    return bsv.PublicKey.fromString(identifier)
+  } catch (e) {
+    return null
+  }
+}
+
 /**
  * Legal Token Protocol - Obligation Creation Primitives
  * 
@@ -216,7 +242,7 @@ var ObligationToken = {
       this._validateTokenStructure(token, errors)
       
       // Signature verification
-      this._verifyTokenSignature(token, errors)
+      this._verifyTokenSignature(token, errors, options)
       
       // Temporal validation
       this._validateTokenTemporal(token, errors, warnings)
@@ -807,26 +833,48 @@ var ObligationToken = {
    * Verify token signature
    * @private
    */
-  _verifyTokenSignature: function(token, errors) {
+  _verifyTokenSignature: function(token, errors, options) {
     try {
       if (!token.proof || !token.proof.jws) {
         errors.push('Missing signature proof')
         return
       }
-      
+
       // Recreate canonical hash
       var canonicalToken = this._canonicalizeToken(token)
       var expectedHash = Hash.sha256(Buffer.from(canonicalToken))
-      
+
       // Compare with stored hash if available
       if (token.tokenHash && token.tokenHash !== expectedHash.toString('hex')) {
         errors.push('Token hash mismatch')
         return
       }
-      
-      // TODO: Verify JWS signature with issuer's public key
-      // This would require DID resolution to get the public key
-      
+
+      // Verify the JWS signature against the issuer's key — the real security
+      // check. Fail CLOSED: unresolvable key or bad signature => error, never a
+      // silent pass.
+      var pubKey = _resolveIssuerPublicKey(token, options)
+      if (!pubKey) {
+        errors.push('Signature not verified: issuer public key could not be ' +
+          'resolved from token.issuer; pass options.issuerPublicKey')
+        return
+      }
+
+      var parts = token.proof.jws.split('.')
+      if (parts.length !== 3 || !parts[2]) {
+        errors.push('Malformed JWS')
+        return
+      }
+      var signature = Signature.fromDER(Buffer.from(parts[2], 'base64url'))
+
+      var ecdsa = new ECDSA()
+      ecdsa.hashbuf = expectedHash
+      ecdsa.sig = signature
+      ecdsa.pubkey = pubKey
+      // .verify() returns the instance (truthy); the boolean is on .verified.
+      if (ecdsa.verify().verified !== true) {
+        errors.push('Signature verification failed')
+      }
     } catch (error) {
       errors.push('Signature verification failed: ' + error.message)
     }

package/lib/ltp/proof.js

@@ -131,8 +131,10 @@ var LTPProof = {
       ecdsa.sig = signature
       ecdsa.pubkey = bsv.PublicKey.fromString(publicKey)
       
-      var isValid = ecdsa.verify()
-      
+      // ECDSA.prototype.verify() returns the instance (always truthy) and stashes
+      // the real result on .verified — read the boolean, never the instance.
+      var isValid = ecdsa.verify().verified === true
+
       return {
         success: true,
         verification: {

package/lib/ltp/right.js

@@ -8,6 +8,33 @@ var PrivateKey = bsv.PrivateKey
 var $ = bsv.util.preconditions
 var _ = require('../util/_')
 
+/**
+ * Resolve the AUTHORITATIVE signer public key for a token: the issuer's key.
+ *
+ * The key is bound to the issuer's identity, never taken from a key named inside
+ * the token's own proof (which a forger controls). did:smartledger embeds the
+ * public key in the DID itself (did:<method>:<pubkeyHex>[:...]), so the issuer DID
+ * IS the key. Callers may override with options.issuerPublicKey. Returns null when
+ * no key can be resolved — callers MUST fail closed on null.
+ */
+function _resolveIssuerPublicKey (token, options) {
+  options = options || {}
+  if (options.issuerPublicKey) {
+    return options.issuerPublicKey instanceof bsv.PublicKey
+      ? options.issuerPublicKey
+      : bsv.PublicKey.fromString(options.issuerPublicKey)
+  }
+  var did = token && token.issuer
+  if (typeof did !== 'string') return null
+  try {
+    var identifier = did.split('#')[0].split(':')[2] // did:method:<identifier>[:...]
+    if (!identifier) return null
+    return bsv.PublicKey.fromString(identifier)
+  } catch (e) {
+    return null
+  }
+}
+
 /**
  * Legal Token Protocol - Right Creation Primitives
  * 
@@ -199,11 +226,11 @@ var RightToken = {
       this._validateTokenStructure(token, errors)
       
       // Signature verification
-      this._verifyTokenSignature(token, errors)
-      
+      this._verifyTokenSignature(token, errors, options)
+
       // Temporal validation
       this._validateTokenTemporal(token, errors, warnings)
-      
+
       // Type validation
       this._validateRightType(token, errors)
       
@@ -299,7 +326,32 @@ var RightToken = {
           error: 'Token is not transferable'
         }
       }
-      
+
+      // AUTHORIZATION: bind the signing key to the CURRENT owner. Verifying the
+      // token above only proves the ISSUER signed it — NOT that the caller holds
+      // it. Without this, prepareRightTokenTransfer(victimToken, attackerDID,
+      // attackerKey) would mint a "valid" transfer of a token the attacker does
+      // not own. The current owner is token.credentialSubject.id, whose DID embeds
+      // the owner's public key (did:key / did:smartledger).
+      var ownerDid = token.credentialSubject && token.credentialSubject.id
+      var ownerPubKey = _resolveIssuerPublicKey(
+        { issuer: ownerDid },
+        { issuerPublicKey: options.currentOwnerPublicKey }
+      )
+      if (!ownerPubKey) {
+        return {
+          success: false,
+          error: 'Cannot resolve current owner public key from token.credentialSubject.id; ' +
+            'pass options.currentOwnerPublicKey'
+        }
+      }
+      if (currentOwnerKey.toPublicKey().toString() !== ownerPubKey.toString()) {
+        return {
+          success: false,
+          error: 'Unauthorized transfer: signing key does not match the current owner'
+        }
+      }
+
       // Create transfer record
       var transfer = {
         '@context': [
@@ -761,26 +813,49 @@ var RightToken = {
    * Verify token signature
    * @private
    */
-  _verifyTokenSignature: function(token, errors) {
+  _verifyTokenSignature: function(token, errors, options) {
     try {
       if (!token.proof || !token.proof.jws) {
         errors.push('Missing signature proof')
         return
       }
-      
+
       // Recreate canonical hash
       var canonicalToken = this._canonicalizeToken(token)
       var expectedHash = Hash.sha256(Buffer.from(canonicalToken))
-      
+
       // Compare with stored hash if available
       if (token.tokenHash && token.tokenHash !== expectedHash.toString('hex')) {
         errors.push('Token hash mismatch')
         return
       }
-      
-      // TODO: Verify JWS signature with issuer's public key
-      // This would require DID resolution to get the public key
-      
+
+      // Verify the JWS signature against the issuer's key. This is the actual
+      // security check — the hash comparison above only guards integrity of a
+      // caller-supplied field. Fail CLOSED: an unresolvable key or a bad signature
+      // must produce an error, never a silent pass.
+      var pubKey = _resolveIssuerPublicKey(token, options)
+      if (!pubKey) {
+        errors.push('Signature not verified: issuer public key could not be ' +
+          'resolved from token.issuer; pass options.issuerPublicKey')
+        return
+      }
+
+      var parts = token.proof.jws.split('.')
+      if (parts.length !== 3 || !parts[2]) {
+        errors.push('Malformed JWS')
+        return
+      }
+      var signature = Signature.fromDER(Buffer.from(parts[2], 'base64url'))
+
+      var ecdsa = new ECDSA()
+      ecdsa.hashbuf = expectedHash
+      ecdsa.sig = signature
+      ecdsa.pubkey = pubKey
+      // .verify() returns the instance (truthy); the boolean is on .verified.
+      if (ecdsa.verify().verified !== true) {
+        errors.push('Signature verification failed')
+      }
     } catch (error) {
       errors.push('Signature verification failed: ' + error.message)
     }

package/lib/ordinals/README.md

@@ -0,0 +1,170 @@
+# `bsv.Ordinals` — 1Sat Ordinals inscriptions + trustless marketplace
+
+Build and parse [1Sat Ordinals](https://docs.1satordinals.com/) inscriptions, and list,
+buy, or cancel them behind a trustless **OrdLock** "pay the seller or cancel" covenant —
+built on the audited configurable-SIGHASH `OP_PUSH_TX` core (`bsv.SmartContract.PushTx`).
+
+Every locking/unlocking script this module emits is exercised through the consensus
+interpreter in `test/ordinals/`, including adversarial spends asserted to be **rejected**.
+
+> Covenant scripts need post-Genesis limits. Call `bsv.SmartContract.enableGenesis()`
+> once before building/verifying OrdLock scripts.
+
+## Inscriptions
+
+An inscription is content (a content-type + a body) carried on a 1-satoshi output behind
+an inert `OP_FALSE OP_IF "ord" … OP_ENDIF` envelope, appended to a normal locking script
+(P2PKH by default). The envelope never executes, so spending is controlled entirely by the
+base lock while the inscription rides on the satoshi.
+
+```js
+var bsv = require('@smartledger/bsv')
+var Ord = bsv.Ordinals
+
+// Build an inscription locking script (P2PKH owner) and the 1-sat output.
+var script = Ord.buildInscription({
+  address: ownerAddress,
+  contentType: 'text/plain',
+  content: 'hello ordinals'
+})
+var output = Ord.createInscriptionOutput({ address: ownerAddress, contentType: 'image/png', content: pngBuffer })
+
+// Parse it back.
+var insc = Ord.parseInscription(script)      // { contentType, content, contentText, lock }
+Ord.isInscription(script)                    // true
+
+// Batch many inscriptions into one transaction.
+var outs = Ord.batchInscriptionOutputs([
+  { address: a, contentType: 'text/plain', content: 'a' },
+  { address: b, contentType: 'text/plain', content: 'b' }
+])
+```
+
+## Marketplace: the OrdLock covenant
+
+A listing locks the 1-sat ordinal behind a script with two spend paths:
+
+- **PURCHASE** — anyone may take the ordinal, but only by recreating the required payment
+  output(s) byte-for-byte. Under `SIGHASH_ALL|ANYONECANPAY` the buyer supplies the
+  surrounding outputs and adds funding inputs / change freely; the one thing they cannot do
+  is take the ordinal without paying.
+- **CANCEL** — the seller reclaims the listing any time with an ECDSA signature over their key.
+
+Payments can be **multi-output** — a seller payment plus royalty and marketplace-fee
+outputs — so a purchase atomically pays every party or fails.
+
+### List (sell side)
+
+```js
+bsv.SmartContract.enableGenesis()
+
+// Move a P2PKH ordinal into a listing, fee paid from a separate funding coin.
+var listed = Ord.buildListingTx({
+  ordinal: { txid: ordTxid, outputIndex: 0, script: ownerP2PKH, satoshis: 1, privateKey: ownerKey },
+  seller: ownerAddress,
+  price: 100000,                                             // paid to the seller
+  royalties: [{ address: creatorAddress, satoshis: 5000 }], // + optional royalty / fee outputs
+  funding: [{ txid: feeTxid, outputIndex: 0, script: feeP2PKH, satoshis: 20000, privateKey: feeKey }],
+  fee: 500
+})
+// listed.tx            -> the fully-signed listing transaction (broadcast it)
+// listed.listingScript -> the OrdLock locking script
+// listed.listingOutpoint = { txid, outputIndex }  -> where the listing now lives
+```
+
+Prefer the raw pieces? `Ord.buildOrdLock({ seller, price, royalties })` returns just the
+locking script and `Ord.listInscriptionOutput({...})` the 1-sat output.
+
+### Read a listing (indexer / wallet / UI)
+
+Listings are self-describing — recover their terms straight off-chain:
+
+```js
+Ord.isOrdLock(script)          // true for an OrdLock listing
+var terms = Ord.parseOrdLock(script)
+// {
+//   seller:      { pubKeyHash, address },
+//   payOutputs:  [ { satoshis, script, address }, ... ],   // seller, royalty, fee, ...
+//   totalPrice:  105000,
+//   inscription: { contentType, content, contentText } | null
+// }
+```
+
+### Buy (purchase side)
+
+```js
+// The buyer needs only the listing UTXO — the required payments are read off its script.
+var buyTx = Ord.buildPurchaseTx({
+  listing: { txid: listed.listingOutpoint.txid, outputIndex: 0, script: listed.listingScript, satoshis: 1 },
+  ordinalDestination: buyerAddress,
+  funding: [{ txid: coinTxid, outputIndex: 0, script: buyerP2PKH, satoshis: 200000, privateKey: buyerKey }],
+  fee: 500
+})
+// Output layout: [ ordinal -> buyer, <pinned payments>, change -> buyer ].
+// buyTx is fully signed (covenant input + funding inputs). Broadcast it.
+```
+
+### Cancel
+
+```js
+var reclaim = new bsv.Transaction()
+reclaim.addInput(new bsv.Transaction.Input({
+  prevTxId: listed.listingOutpoint.txid, outputIndex: 0, script: bsv.Script.empty()
+}), listed.listingScript, 1)
+reclaim.addOutput(new bsv.Transaction.Output({ script: sellerP2PKH, satoshis: 1 }))
+Ord.cancelOrdLock({ privateKey: ownerKey, spend: reclaim, lockingScript: listed.listingScript, satoshis: 1 })
+```
+
+## Lower-level unlock builders
+
+`Ord.purchaseOrdLock({ spend, lockingScript })` and `Ord.cancelOrdLock({ privateKey, spend, lockingScript })`
+build (and assign) the unlocking script when you are assembling the spend transaction
+yourself. `purchaseOrdLock` grinds the OP_PUSH_TX signature into `nLockTime`, so call it
+**before** signing any funding inputs the buyer adds.
+
+## BSV-20 / BSV-21 fungible tokens
+
+Fungible tokens are a JSON payload (`application/bsv-20`) inside an inscription on a 1-sat
+output. Two eras: **v1** is ticker-based (`tick`, 1–4 bytes); **v2 / BSV-21** is id-based
+(`deploy+mint`, then transfer by `id` = the deploy `<txid>_<vout>`). Amounts are **integer
+strings** — they routinely exceed 2^53, so they are never coerced to JS numbers.
+
+```js
+var B = bsv.Ordinals.BSV20
+
+// v1: deploy a ticker, mint, transfer.
+B.buildDeploy({ address: owner, tick: 'ORDI', max: '21000000', lim: '1000', dec: 18 })
+B.buildMint({ address: owner, tick: 'ORDI', amt: '1000' })
+B.buildTransfer({ address: newOwner, tick: 'ORDI', amt: '250' })
+
+// v2 / BSV-21: deploy+mint a supply, transfer by id.
+B.buildDeployMint({ address: owner, amt: '1000000', dec: 8, sym: 'XYZ' })
+B.buildTransfer({ address: newOwner, id: deployTxid + '_0', amt: '5' })
+
+// 1-sat outputs and parsing.
+var out = B.createMintOutput({ address: owner, tick: 'ORDI', amt: '1' })
+B.isBsv20(out.script)                 // true
+B.parseBsv20(script)                  // { p:'bsv-20', op:'mint', tick:'ORDI', amt:'1000' } | null
+B.parseBsv20('{"p":"bsv-20","op":"mint","tick":"ORDI","amt":"1"}')  // also accepts JSON / objects
+```
+
+Builders validate their inputs (ticker ≤ 4 bytes, non-negative integer amounts, `dec` 0–18,
+well-formed BSV-21 `id`) and throw on bad data. Balance tracking is an indexer concern —
+this module builds and reads the on-chain payloads.
+
+## API
+
+| Function | Purpose |
+| --- | --- |
+| `buildInscription`, `createInscriptionOutput`, `batchInscriptionOutputs` | build inscription scripts / outputs |
+| `parseInscription`, `isInscription` | read an inscription back |
+| `buildOrdLock`, `listInscriptionOutput` | build an OrdLock listing script / 1-sat output |
+| `parseOrdLock`, `isOrdLock` | recover a listing's seller, payments, price, inscription |
+| `buildListingTx` | assemble a signed listing tx (P2PKH ordinal → OrdLock) |
+| `buildPurchaseTx` | assemble a signed purchase tx from a listing UTXO + buyer coins |
+| `purchaseOrdLock`, `cancelOrdLock` | build unlock scripts for a spend you assemble |
+| `payOutputFor` | build a P2PKH payment output |
+| `ORDLOCK_SIGHASH` | `SIGHASH_ALL\|ANYONECANPAY\|FORKID` (0xc1) |
+| `BSV20.buildDeploy` / `buildMint` / `buildTransfer` / `buildDeployMint` | build BSV-20/21 token inscriptions |
+| `BSV20.create*Output` | 1-sat token outputs |
+| `BSV20.parseBsv20`, `BSV20.isBsv20` | read a token payload back |

package/lib/ordinals/bsv20.js

@@ -0,0 +1,185 @@
+'use strict'
+/**
+ * BSV-20 / BSV-21 fungible-token inscriptions.
+ *
+ * A BSV-20 token is a JSON payload (content-type `application/bsv-20`) carried inside an
+ * ordinary 1Sat Ordinals inscription envelope on a 1-satoshi output. The token amount is
+ * per-UTXO; an indexer tracks balances by replaying deploy / mint / transfer operations.
+ * This module builds and parses those payloads — the on-chain plumbing is just an
+ * inscription (see ./inscription), so a token output is a normal P2PKH-owned 1-sat output.
+ *
+ * Two protocol eras are supported:
+ *   v1  (ticker-based)  deploy / mint / transfer keyed by a 1–4 byte `tick`.
+ *   v2 / BSV-21 (id-based)  `deploy+mint` a supply in one step; transfer by `id`
+ *                           (the deploy outpoint, `<txid>_<vout>`).
+ *
+ * Amounts (`amt`, `max`, `lim`) are INTEGER STRINGS — they routinely exceed 2^53, so they
+ * are never coerced to JS numbers. `dec` (decimals, 0–18) scales display only.
+ */
+var inscription = require('./inscription')
+
+var CONTENT_TYPE = 'application/bsv-20'
+var MAX_DEC = 18
+
+/** A non-negative integer string (no sign, no decimal point). */
+function isIntString (v) { return typeof v === 'string' && /^\d+$/.test(v) }
+
+/** Normalize an amount-like field to a CANONICAL non-negative integer string (no leading zeros). */
+function normInt (v, name) {
+  if (typeof v === 'number') {
+    if (!Number.isInteger(v) || v < 0) throw new Error(name + ' must be a non-negative integer')
+    return String(v)
+  }
+  // Strip leading zeros ("007" -> "7", "000" -> "0") so the emitted payload is canonical
+  // and not rejected by indexers that expect canonical decimal integers.
+  if (isIntString(v)) return v.replace(/^0+(?=\d)/, '')
+  throw new Error(name + ' must be a non-negative integer (string or number)')
+}
+
+/** Normalize a strictly-positive amount (mint/transfer/supply must move > 0). */
+function normPositive (v, name) {
+  var s = normInt(v, name)
+  if (!/[1-9]/.test(s)) throw new Error(name + ' must be greater than zero')
+  return s
+}
+
+/** Validate a v1 ticker: 1–4 UTF-8 bytes. */
+function assertTick (tick) {
+  if (typeof tick !== 'string' || !tick.length) throw new Error('tick is required')
+  if (Buffer.byteLength(tick, 'utf8') > 4) throw new Error('tick must be 1–4 UTF-8 bytes')
+  return tick
+}
+
+/** Normalize `dec` (decimals) to a string in 0…18. */
+function normDec (dec) {
+  var d = typeof dec === 'string' ? Number(dec) : dec
+  if (!Number.isInteger(d) || d < 0 || d > MAX_DEC) throw new Error('dec must be an integer 0…' + MAX_DEC)
+  return String(d)
+}
+
+/** Validate a BSV-21 token id: `<64-hex-txid>_<vout>`. */
+function assertId (id) {
+  if (typeof id !== 'string' || !/^[0-9a-fA-F]{64}_\d+$/.test(id)) {
+    throw new Error('id must be "<txid>_<vout>" (64-hex txid, underscore, output index)')
+  }
+  return id
+}
+
+/** Wrap a BSV-20 JSON payload in an inscription locking script (P2PKH owner by default). */
+function buildBsv20 (payload, params) {
+  params = params || {}
+  return inscription.buildInscription({
+    lock: params.lock,
+    address: params.address,
+    contentType: params.contentType || CONTENT_TYPE,
+    content: JSON.stringify(payload)
+  })
+}
+
+/**
+ * Deploy a v1 (ticker) token: fix its ticker, max supply, per-mint limit, and decimals.
+ * @param {object} params { tick, max, lim?, dec?, address|lock, contentType? }
+ * @returns {Script}
+ */
+function buildDeploy (params) {
+  params = params || {}
+  var p = { p: 'bsv-20', op: 'deploy', tick: assertTick(params.tick), max: normPositive(params.max, 'max') }
+  if (params.lim != null) p.lim = normPositive(params.lim, 'lim')
+  if (params.dec != null) p.dec = normDec(params.dec)
+  return buildBsv20(p, params)
+}
+
+/**
+ * Mint an amount of a v1 (ticker) token.
+ * @param {object} params { tick, amt, address|lock, contentType? }
+ * @returns {Script}
+ */
+function buildMint (params) {
+  params = params || {}
+  var p = { p: 'bsv-20', op: 'mint', tick: assertTick(params.tick), amt: normPositive(params.amt, 'amt') }
+  return buildBsv20(p, params)
+}
+
+/**
+ * Transfer an amount of a token. Provide `tick` (v1) OR `id` (v2 / BSV-21).
+ * @param {object} params { tick?|id?, amt, address|lock, contentType? }
+ * @returns {Script}
+ */
+function buildTransfer (params) {
+  params = params || {}
+  var p = { p: 'bsv-20', op: 'transfer', amt: normPositive(params.amt, 'amt') }
+  if (params.id != null) p.id = assertId(params.id)
+  else p.tick = assertTick(params.tick)
+  return buildBsv20(p, params)
+}
+
+/**
+ * Deploy + mint a BSV-21 (id-based) token supply in one operation.
+ * @param {object} params { amt, dec?, sym?, icon?, address|lock, contentType? }
+ * @returns {Script}
+ */
+function buildDeployMint (params) {
+  params = params || {}
+  var p = { p: 'bsv-20', op: 'deploy+mint', amt: normPositive(params.amt, 'amt') }
+  if (params.dec != null) p.dec = normDec(params.dec)
+  if (params.sym != null) p.sym = String(params.sym)
+  if (params.icon != null) p.icon = String(params.icon)
+  return buildBsv20(p, params)
+}
+
+function outputFor (script, satoshis) {
+  var bsv = require('../..')
+  return new bsv.Transaction.Output({ script: script, satoshis: satoshis != null ? satoshis : 1 })
+}
+
+/** 1-sat Output helpers mirroring the builders. */
+function createDeployOutput (params) { return outputFor(buildDeploy(params), params && params.satoshis) }
+function createMintOutput (params) { return outputFor(buildMint(params), params && params.satoshis) }
+function createTransferOutput (params) { return outputFor(buildTransfer(params), params && params.satoshis) }
+function createDeployMintOutput (params) { return outputFor(buildDeployMint(params), params && params.satoshis) }
+
+/** Extract the JSON body from a locking script, a JSON string, a Buffer, or an object. */
+function bodyOf (input) {
+  var bsv = require('../..')
+  if (input && typeof input === 'object' && !Buffer.isBuffer(input) && !(input instanceof bsv.Script)) {
+    return input // already a parsed object
+  }
+  if (typeof input === 'string' && input.trim()[0] === '{') return input // raw JSON string
+  var insc = inscription.parseInscription(input) // Script / Buffer / hex script
+  return insc ? insc.contentText : null
+}
+
+/**
+ * Parse a BSV-20 payload from a locking script (Script/Buffer/hex), a JSON string, or an
+ * already-parsed object. Returns the payload object (with `p:'bsv-20'`) or null if the
+ * input carries no valid BSV-20 inscription.
+ * @returns {null|{ p:'bsv-20', op:string, tick?:string, id?:string, amt?:string, max?:string, lim?:string, dec?:string, sym?:string, icon?:string }}
+ */
+function parseBsv20 (input) {
+  try {
+    var body = bodyOf(input)
+    if (body == null) return null
+    var obj = (typeof body === 'object') ? body : JSON.parse(body)
+    if (!obj || obj.p !== 'bsv-20' || typeof obj.op !== 'string') return null
+    return obj
+  } catch (e) {
+    return null
+  }
+}
+
+/** True if the input carries a valid BSV-20 inscription. */
+function isBsv20 (input) { return parseBsv20(input) !== null }
+
+module.exports = {
+  CONTENT_TYPE: CONTENT_TYPE,
+  buildDeploy: buildDeploy,
+  buildMint: buildMint,
+  buildTransfer: buildTransfer,
+  buildDeployMint: buildDeployMint,
+  createDeployOutput: createDeployOutput,
+  createMintOutput: createMintOutput,
+  createTransferOutput: createTransferOutput,
+  createDeployMintOutput: createDeployMintOutput,
+  parseBsv20: parseBsv20,
+  isBsv20: isBsv20
+}

package/lib/ordinals/index.js

@@ -0,0 +1,49 @@
+'use strict'
+/**
+ * Ordinals — 1Sat Ordinals inscriptions for BSV.
+ *
+ * Build/parse inscription scripts, create the 1-sat inscription output, batch many
+ * inscriptions into one transaction, and (see ./ordlock) list an ordinal for sale
+ * behind an OP_PUSH_TX "pay the seller or cancel" covenant.
+ */
+var inscription = require('./inscription')
+var ordlock = require('./ordlock')
+var bsv20 = require('./bsv20')
+
+/**
+ * Build the 1-sat output(s) for one or more inscriptions.
+ * @param {Array<object>} items  each: { contentType, content, address|lock, satoshis? }
+ * @returns {Transaction.Output[]}
+ */
+function batchInscriptionOutputs (items) {
+  if (!Array.isArray(items) || !items.length) {
+    throw new Error('batchInscriptionOutputs requires a non-empty array of items')
+  }
+  return items.map(function (it) { return inscription.createInscriptionOutput(it) })
+}
+
+module.exports = {
+  buildInscription: inscription.buildInscription,
+  parseInscription: inscription.parseInscription,
+  isInscription: inscription.isInscription,
+  createInscriptionOutput: inscription.createInscriptionOutput,
+  batchInscriptionOutputs: batchInscriptionOutputs,
+
+  // Marketplace: list an ordinal for sale behind a "pay the seller or cancel" covenant.
+  // Payments may be multi-output (seller + royalties + marketplace fee), and a listing is
+  // self-describing — parseOrdLock recovers its terms and buildPurchaseTx assembles a
+  // complete signed purchase from just the listing UTXO and the buyer's coins.
+  ORDLOCK_SIGHASH: ordlock.ORDLOCK_SIGHASH,
+  buildOrdLock: ordlock.buildOrdLock,
+  parseOrdLock: ordlock.parseOrdLock,
+  isOrdLock: ordlock.isOrdLock,
+  listInscriptionOutput: ordlock.listInscriptionOutput,
+  payOutputFor: ordlock.payOutputFor,
+  purchaseOrdLock: ordlock.purchase,
+  cancelOrdLock: ordlock.cancel,
+  buildListingTx: ordlock.buildListingTx,
+  buildPurchaseTx: ordlock.buildPurchaseTx,
+
+  // BSV-20 / BSV-21 fungible-token inscriptions (deploy / mint / transfer + parse).
+  BSV20: bsv20
+}