@bsv/templates 1.4.0 → 1.5.0

package/src/MandalaToken.ts

@@ -0,0 +1,102 @@
+import {
+  ScriptTemplate, ScriptTemplateUnlock, LockingScript, UnlockingScript, OP, Utils,
+  WalletInterface, WalletProtocol, WalletCounterparty, Transaction, Hash,
+  TransactionSignature, PrivateKey
+} from '@bsv/sdk'
+import {
+  createMinimallyEncodedScriptChunk, encodeScriptNum, decodeScriptNum,
+  encodeAssetId, decodeAssetId, MARKER
+} from './mandala-encoding.js'
+import { buildSighashPreimage } from './mandala-signing.js'
+
+// Local helper since Utils.verifyTruthy is not available in @bsv/sdk
+const vt = <T>(v: T | undefined | null): T => {
+  if (v == null) throw new Error('missing chunk data')
+  return v
+}
+
+export interface MandalaTokenDecoded {
+  assetId: string
+  amount: number
+  pubKeyHash: number[]
+}
+
+export class MandalaToken implements ScriptTemplate {
+  wallet?: WalletInterface
+  originator?: string
+
+  constructor (wallet?: WalletInterface, originator?: string) {
+    this.wallet = wallet
+    this.originator = originator
+  }
+
+  async lockBRC29 (
+    assetId: string,
+    amount: number,
+    protocolID: WalletProtocol,
+    keyID: string,
+    counterparty: WalletCounterparty
+  ): Promise<LockingScript> {
+    if (this.wallet == null) throw new Error('lockBRC29 requires a wallet')
+    const { publicKey } = await this.wallet.getPublicKey({ protocolID, keyID, counterparty }, this.originator)
+    const pubKeyHash = Hash.hash160(Utils.toArray(publicKey, 'hex'))
+    return this.lock(assetId, amount, pubKeyHash)
+  }
+
+  lock (assetId: string, amount: number, pubKeyHash: number[]): LockingScript {
+    if (pubKeyHash.length !== 20) throw new Error('pubKeyHash must be 20 bytes')
+    if (!Number.isInteger(amount) || amount < 1) throw new Error('amount must be a positive integer')
+    const assetIdBytes = encodeAssetId(assetId)
+    return new LockingScript([
+      createMinimallyEncodedScriptChunk([MARKER]),
+      createMinimallyEncodedScriptChunk(assetIdBytes),
+      createMinimallyEncodedScriptChunk(encodeScriptNum(amount)),
+      { op: OP.OP_2DROP },
+      { op: OP.OP_DROP },
+      { op: OP.OP_DUP },
+      { op: OP.OP_HASH160 },
+      { op: pubKeyHash.length, data: pubKeyHash },
+      { op: OP.OP_EQUALVERIFY },
+      { op: OP.OP_CHECKSIG }
+    ])
+  }
+
+  unlock (
+    privateKey: PrivateKey,
+    signOutputs: 'all' | 'none' | 'single' = 'all',
+    anyoneCanPay = false
+  ): ScriptTemplateUnlock {
+    return {
+      sign: async (tx: Transaction, inputIndex: number): Promise<UnlockingScript> => {
+        const { preimage, scope } = buildSighashPreimage(tx, inputIndex, signOutputs, anyoneCanPay)
+
+        const rawSignature = privateKey.sign(Hash.sha256(preimage))
+        const sig = new TransactionSignature(rawSignature.r, rawSignature.s, scope)
+        const sigForScript = sig.toChecksigFormat()
+        const pubkeyForScript = privateKey.toPublicKey().encode(true) as number[]
+        return new UnlockingScript([
+          { op: sigForScript.length, data: sigForScript },
+          { op: pubkeyForScript.length, data: pubkeyForScript }
+        ])
+      },
+      estimateLength: async (tx?: Transaction, inputIndex?: number) => 108
+    }
+  }
+
+  static decode (script: LockingScript): MandalaTokenDecoded {
+    const c = script.chunks
+    if (c.length !== 10) throw new Error('not a MandalaToken script: wrong chunk count')
+    const marker = c[0].data ?? []
+    if (c[0].op !== 1 || marker.length !== 1 || marker[0] !== MARKER) throw new Error('not a MandalaToken script: missing marker')
+    if (c[3].op !== OP.OP_2DROP || c[4].op !== OP.OP_DROP) throw new Error('not a MandalaToken script: bad drops')
+    if (c[5].op !== OP.OP_DUP || c[6].op !== OP.OP_HASH160 || c[8].op !== OP.OP_EQUALVERIFY || c[9].op !== OP.OP_CHECKSIG) {
+      throw new Error('not a MandalaToken script: bad P2PKH tail')
+    }
+    const assetId = decodeAssetId(vt(c[1].data))
+    const amount = decodeScriptNum(c[2].data ?? [])
+    if (!Number.isInteger(amount) || amount < 1) throw new Error('not a MandalaToken script: bad amount')
+    const pubKeyHash = vt(c[7].data)
+    if (pubKeyHash.length !== 20) throw new Error('not a MandalaToken script: bad pubKeyHash')
+    return { assetId, amount, pubKeyHash }
+  }
+}

package/src/MultiPushDrop.ts

@@ -12,6 +12,7 @@ import {
   Transaction,
   PubKeyHex
 } from '@bsv/sdk'
+import { createMinimallyEncodedScriptChunk } from './mandala-encoding.js'
 
 // Helper to ensure a value is not null or undefined
 function verifyTruthy<T> (v: T | undefined | null, err?: string): T {
@@ -19,20 +20,6 @@ function verifyTruthy<T> (v: T | undefined | null, err?: string): T {
   return v
 }
 
-// Helper to create minimally encoded script chunks (same as in PushDrop)
-const createMinimallyEncodedScriptChunk = (
-  data: number[]
-): { op: number, data?: number[] } => {
-  if (data.length === 0) return { op: 0 } // OP_0
-  if (data.length === 1 && data[0] === 0) return { op: 0 } // OP_0
-  if (data.length === 1 && data[0] > 0 && data[0] <= 16) return { op: 0x50 + data[0] } // OP_1 to OP_16
-  if (data.length === 1 && data[0] === 0x81) return { op: 0x4f } // OP_1NEGATE
-  if (data.length <= 75) return { op: data.length, data }
-  if (data.length <= 255) return { op: 0x4c, data } // OP_PUSHDATA1
-  if (data.length <= 65535) return { op: 0x4d, data } // OP_PUSHDATA2
-  return { op: 0x4e, data } // OP_PUSHDATA4
-}
-
 /**
  * Represents the decoded structure of a MultiPushDrop locking script.
  */
@@ -173,20 +160,16 @@ export class MultiPushDrop implements ScriptTemplate {
 
     // Pick the value on the stack that's right before the locking script.
     // This should be the index of the key to use in the unlock.
-    lockPart.push(createMinimallyEncodedScriptChunk([nPublicKeys]))
-    lockPart.push({ op: OP.OP_PICK })
+    lockPart.push(createMinimallyEncodedScriptChunk([nPublicKeys]), { op: OP.OP_PICK })
 
     // Now we use the index to get the actual key.
     lockPart.push({ op: OP.OP_PICK })
 
     // We pull the signature from the bottom of the stack, no matter the number of keys.
-    lockPart.push({ op: OP.OP_DEPTH })
-    lockPart.push({ op: OP.OP_1SUB })
-    lockPart.push({ op: OP.OP_PICK })
+    lockPart.push({ op: OP.OP_DEPTH }, { op: OP.OP_1SUB }, { op: OP.OP_PICK })
 
     // We swap the signature and public key so they're in the correct order, then CHECKSIGVERIFY
-    lockPart.push({ op: OP.OP_SWAP })
-    lockPart.push({ op: OP.OP_CHECKSIGVERIFY })
+    lockPart.push({ op: OP.OP_SWAP }, { op: OP.OP_CHECKSIGVERIFY })
 
     // Construct PushDrop Part for fields
     const pushDropPart: Array<{ op: number, data?: number[] }> = []
@@ -302,8 +285,7 @@ export class MultiPushDrop implements ScriptTemplate {
 
         // Create Unlocking Script Chunks: <Signature> <Index>
         const unlockingChunks: Array<{ op: number, data?: number[] }> = []
-        unlockingChunks.push({ op: sigForScript.length, data: sigForScript })
-        unlockingChunks.push(createMinimallyEncodedScriptChunk([unlockerIndex]))
+        unlockingChunks.push({ op: sigForScript.length, data: sigForScript }, createMinimallyEncodedScriptChunk([unlockerIndex]))
         return new UnlockingScript(unlockingChunks)
       },
       // Estimate length: Signature (~71-73 bytes) + Index push (1 byte for 0-15, potentially more)

package/src/P2MSKH.ts

@@ -7,7 +7,7 @@ export interface MultiSigInstructions {
 }
 
 function concatPubkeys (pubkeys: PublicKey[]): number[] {
-  return pubkeys.map((p) => p.toDER() as number[]).reduce((a, b) => a.concat(b), [])
+  return pubkeys.map((p) => p.toDER() as number[]).flat()
 }
 
 function numberFromScriptChunk (chunk: ScriptChunk): number {
@@ -192,7 +192,7 @@ export class P2MSKH implements ScriptTemplate {
         workingUnlockingScript.writeBin(sigForScript)
         const chunkforSig = workingUnlockingScript.chunks.pop() as ScriptChunk
         // add it to the array before the pubkeys, pushing the other content to the right
-        workingUnlockingScript.chunks.splice(workingUnlockingScript.chunks.length - 1, 0, chunkforSig)
+        workingUnlockingScript.chunks.splice(-1, 0, chunkforSig)
         return workingUnlockingScript
       },
 

package/src/__tests/MandalaAdmin.derive.test.ts

@@ -0,0 +1,34 @@
+import { MandalaAdmin } from '../MandalaAdmin.js'
+
+describe('MandalaAdmin canonicalize/commitment', () => {
+  it('is insensitive to key ordering', () => {
+    const a = MandalaAdmin.canonicalize({ kind: 'issue', amount: 5, assetId: 'x.0' } as any)
+    const b = MandalaAdmin.canonicalize({ assetId: 'x.0', kind: 'issue', amount: 5 } as any)
+    expect(a).toBe(b)
+  })
+
+  it('orders nested object keys', () => {
+    const s = MandalaAdmin.canonicalize({ kind: 'issue', meta: { z: 1, a: 2 } } as any)
+    expect(s).toBe('{"kind":"issue","meta":{"a":2,"z":1}}')
+  })
+
+  it('produces a stable 64-hex commitment', () => {
+    const c = MandalaAdmin.commitment({ kind: 'register', assetId: 'x.0' })
+    expect(c).toMatch(/^[0-9a-f]{64}$/)
+    expect(c).toBe(MandalaAdmin.commitment({ assetId: 'x.0', kind: 'register' } as any))
+  })
+
+  it('derives a boundKey via getPublicKey with counterparty anyone', async () => {
+    const calls: any[] = []
+    const wallet: any = {
+      getPublicKey: async (args: any) => { calls.push(args); return { publicKey: '02' + 'a'.repeat(64) } }
+    }
+    const admin = new MandalaAdmin(wallet)
+    const details = { kind: 'issue', assetId: 'x.0', amount: 10 } as const
+    const { boundKey, keyID } = await admin.deriveBoundKey([2, 'mandala admin'], details)
+    expect(boundKey).toBe('02' + 'a'.repeat(64))
+    expect(keyID).toBe(MandalaAdmin.commitment(details))
+    expect(calls[0].counterparty).toBe('anyone')
+    expect(calls[0].keyID).toBe(keyID)
+  })
+})

package/src/__tests/MandalaAdmin.script.test.ts

@@ -0,0 +1,26 @@
+import { MandalaAdmin } from '../MandalaAdmin.js'
+import { PrivateKey, OP } from '@bsv/sdk'
+
+describe('MandalaAdmin lock/decode', () => {
+  it('round-trips the boundKey and has the ! OP_DROP <key> OP_CHECKSIG shape', () => {
+    const boundKey = PrivateKey.fromRandom().toPublicKey().toString()
+    const admin = new MandalaAdmin({} as any)
+    const script = admin.lock(boundKey)
+    const ops = script.chunks.map(c => c.op)
+    expect(script.chunks[0].data).toEqual([0x21])
+    expect(ops[1]).toBe(OP.OP_DROP)
+    expect(ops[3]).toBe(OP.OP_CHECKSIG)
+    expect(MandalaAdmin.decode(script).boundKey).toBe(boundKey)
+  })
+
+  it('decode throws on non-admin scripts', () => {
+    expect(() => MandalaAdmin.decode({ chunks: [{ op: 0x00 }] } as any)).toThrow()
+  })
+
+  it('decode rejects a non-minimal (PUSHDATA1) marker encoding', () => {
+    const boundKey = PrivateKey.fromRandom().toPublicKey().toString()
+    const script = new MandalaAdmin({} as any).lock(boundKey)
+    script.chunks[0] = { op: 0x4c, data: [0x21] }
+    expect(() => MandalaAdmin.decode(script)).toThrow()
+  })
+})

package/src/__tests/MandalaToken.test.ts

@@ -0,0 +1,43 @@
+import { MandalaToken } from '../MandalaToken'
+import { Hash, PrivateKey } from '@bsv/sdk'
+
+describe('MandalaToken lock/decode', () => {
+  const assetId = `${'a'.repeat(64)}.0`
+  const pubKeyHash = Hash.hash160(PrivateKey.fromRandom().toPublicKey().encode(true) as number[])
+
+  it('builds a script that decodes back to its inputs', () => {
+    const script = new MandalaToken().lock(assetId, 1000, pubKeyHash)
+    const decoded = MandalaToken.decode(script)
+    expect(decoded.assetId).toBe(assetId)
+    expect(decoded.amount).toBe(1000)
+    expect(decoded.pubKeyHash).toEqual(pubKeyHash)
+  })
+
+  it('produces a P2PKH tail (OP_DUP OP_HASH160 ... OP_EQUALVERIFY OP_CHECKSIG)', () => {
+    const script = new MandalaToken().lock(assetId, 1, pubKeyHash)
+    const ops = script.chunks.map(c => c.op)
+    expect(ops.slice(-5)).toEqual([0x76, 0xa9, 20, 0x88, 0xac])
+  })
+
+  it('throws when decoding a non-Mandala script', () => {
+    expect(() => MandalaToken.decode({ chunks: [{ op: 0x00 }] } as any)).toThrow()
+  })
+
+  it('decode throws when the amount chunk is empty/zero', () => {
+    const assetId = `${'a'.repeat(64)}.0`
+    const pkh = new Array(20).fill(1)
+    const script = new MandalaToken().lock(assetId, 5, pkh)
+    // Replace the amount push (chunk index 2) with an empty (OP_0) push.
+    script.chunks[2] = { op: 0 }
+    expect(() => MandalaToken.decode(script)).toThrow()
+  })
+
+  it('decode rejects a non-minimal (PUSHDATA1) marker encoding', () => {
+    const assetId = `${'a'.repeat(64)}.0`
+    const pkh = new Array(20).fill(1)
+    const script = new MandalaToken().lock(assetId, 5, pkh)
+    // Re-encode the marker push (chunk 0) as PUSHDATA1 of the same byte.
+    script.chunks[0] = { op: 0x4c, data: [0x21] }
+    expect(() => MandalaToken.decode(script)).toThrow()
+  })
+})

package/src/__tests/MandalaToken.unlock.test.ts

@@ -0,0 +1,31 @@
+import { MandalaToken } from '../MandalaToken'
+import { PrivateKey, Hash, Transaction, P2PKH } from '@bsv/sdk'
+
+describe('MandalaToken unlock', () => {
+  const assetId = `${'b'.repeat(64)}.1`
+
+  it('signs a spend whose script verifies against the source output', async () => {
+    const priv = PrivateKey.fromRandom()
+    const pubKeyHash = Hash.hash160(priv.toPublicKey().encode(true) as number[])
+    const lockingScript = new MandalaToken().lock(assetId, 5, pubKeyHash)
+
+    const sourceTx = new Transaction()
+    sourceTx.addOutput({ lockingScript, satoshis: 1 })
+
+    const spendTx = new Transaction()
+    spendTx.addInput({ sourceTransaction: sourceTx, sourceOutputIndex: 0, sequence: 0xffffffff })
+    spendTx.addOutput({ lockingScript: new P2PKH().lock(pubKeyHash), satoshis: 1 })
+
+    const unlocker = new MandalaToken().unlock(priv)
+    const unlockingScript = await unlocker.sign(spendTx, 0)
+    spendTx.inputs[0].unlockingScript = unlockingScript
+
+    // Two pushes: signature then pubkey.
+    expect(unlockingScript.chunks.length).toBe(2)
+    expect(unlockingScript.chunks[1].data?.length).toBe(33)
+    // estimateLength uses optional parameters to satisfy ScriptTemplateUnlock interface
+    // while supporting no-argument calls for backward compatibility
+    // @ts-expect-error - SDK interface requires params, but implementation has optional params
+    expect(await unlocker.estimateLength()).toBeGreaterThan(100)
+  })
+})

package/src/__tests/exports.test.ts

@@ -0,0 +1,9 @@
+import { MandalaToken, MandalaAdmin } from '../../mod.js'
+
+describe('package exports', () => {
+  it('exposes the Mandala templates from the package entrypoint', () => {
+    expect(typeof MandalaToken).toBe('function')
+    expect(typeof MandalaAdmin).toBe('function')
+    expect(typeof MandalaAdmin.canonicalize).toBe('function')
+  })
+})

package/src/__tests/mandala-encoding.test.ts

@@ -0,0 +1,32 @@
+import {
+  encodeScriptNum, decodeScriptNum, encodeAssetId, decodeAssetId, MARKER
+} from '../mandala-encoding'
+
+describe('mandala-encoding', () => {
+  it('round-trips small and large script numbers', () => {
+    for (const n of [0, 1, 16, 127, 128, 255, 256, 1000, 0x7fffffff]) {
+      expect(decodeScriptNum(encodeScriptNum(n))).toBe(n)
+    }
+  })
+
+  it('encodes zero as an empty array', () => {
+    expect(encodeScriptNum(0)).toEqual([])
+  })
+
+  it('round-trips an assetId outpoint string', () => {
+    const txid = 'a'.repeat(64)
+    const assetId = `${txid}.3`
+    const bytes = encodeAssetId(assetId)
+    expect(bytes.length).toBe(36)
+    expect(decodeAssetId(bytes)).toBe(assetId)
+  })
+
+  it('round-trips an assetId with a high-bit vout (>= 2^31)', () => {
+    const assetId = `${'a'.repeat(64)}.4294967295`
+    expect(decodeAssetId(encodeAssetId(assetId))).toBe(assetId)
+  })
+
+  it('exposes the ! marker', () => {
+    expect(MARKER).toBe(0x21)
+  })
+})

package/src/mandala-encoding.ts

@@ -0,0 +1,64 @@
+import { Utils } from '@bsv/sdk'
+
+export const MARKER = 0x21
+
+export const createMinimallyEncodedScriptChunk = (
+  data: number[]
+): { op: number, data?: number[] } => {
+  if (data.length === 0) return { op: 0 }
+  if (data.length === 1 && data[0] === 0) return { op: 0 }
+  if (data.length === 1 && data[0] > 0 && data[0] <= 16) return { op: 0x50 + data[0] }
+  if (data.length === 1 && data[0] === 0x81) return { op: 0x4f }
+  if (data.length <= 75) return { op: data.length, data }
+  if (data.length <= 255) return { op: 0x4c, data }
+  if (data.length <= 65535) return { op: 0x4d, data }
+  return { op: 0x4e, data }
+}
+
+// Bitcoin script number: minimal little-endian, sign in the high bit of the last byte.
+export const encodeScriptNum = (value: number): number[] => {
+  if (value === 0) return []
+  const negative = value < 0
+  let abs = Math.abs(value)
+  const result: number[] = []
+  while (abs > 0) {
+    result.push(abs & 0xff)
+    abs = Math.floor(abs / 256)
+  }
+  if ((((result.at(-1)) ?? 0) & 0x80) !== 0) {
+    result.push(negative ? 0x80 : 0x00)
+  } else if (negative) {
+    result[result.length - 1] |= 0x80
+  }
+  return result
+}
+
+export const decodeScriptNum = (data: number[]): number => {
+  if (data.length === 0) return 0
+  let result = 0
+  for (let i = 0; i < data.length; i++) {
+    result += (i === data.length - 1 ? (data[i] & 0x7f) : data[i]) * Math.pow(256, i)
+  }
+  if ((((data.at(-1)) ?? 0) & 0x80) !== 0) result = -result
+  return result
+}
+
+export const encodeAssetId = (assetId: string): number[] => {
+  const dot = assetId.lastIndexOf('.')
+  if (dot === -1) throw new Error('assetId must be "<txid>.<vout>"')
+  const txid = assetId.slice(0, dot)
+  const vout = Number(assetId.slice(dot + 1))
+  if (txid.length !== 64) throw new Error('assetId txid must be 32 bytes (64 hex chars)')
+  if (!Number.isInteger(vout) || vout < 0) throw new Error('assetId vout must be a non-negative integer')
+  const txidBytes = Utils.toArray(txid, 'hex')
+  const voutBytes = [vout & 0xff, (vout >> 8) & 0xff, (vout >> 16) & 0xff, (vout >> 24) & 0xff]
+  return [...txidBytes, ...voutBytes]
+}
+
+export const decodeAssetId = (bytes: number[]): string => {
+  if (bytes.length !== 36) throw new Error('assetId bytes must be exactly 36 bytes')
+  const txid = Utils.toHex(bytes.slice(0, 32))
+  const v = bytes.slice(32)
+  const vout = (v[0] + (v[1] << 8) + (v[2] << 16) + (v[3] << 24)) >>> 0
+  return `${txid}.${vout}`
+}

package/src/mandala-signing.ts

@@ -0,0 +1,41 @@
+import { Transaction, TransactionSignature } from '@bsv/sdk'
+
+export type SignOutputs = 'all' | 'none' | 'single'
+
+/**
+ * Builds the BIP143 sighash preimage and scope shared by the Mandala unlock templates.
+ */
+export function buildSighashPreimage (
+  tx: Transaction,
+  inputIndex: number,
+  signOutputs: SignOutputs,
+  anyoneCanPay: boolean
+): { preimage: number[], scope: number } {
+  let scope = TransactionSignature.SIGHASH_FORKID
+  if (signOutputs === 'all') scope |= TransactionSignature.SIGHASH_ALL
+  else if (signOutputs === 'none') scope |= TransactionSignature.SIGHASH_NONE
+  else if (signOutputs === 'single') scope |= TransactionSignature.SIGHASH_SINGLE
+  if (anyoneCanPay) scope |= TransactionSignature.SIGHASH_ANYONECANPAY
+
+  const input = tx.inputs[inputIndex]
+  const sourceTXID = input.sourceTXID ?? input.sourceTransaction?.id('hex')
+  const sourceOutput = input.sourceTransaction?.outputs[input.sourceOutputIndex]
+  if (sourceTXID == null) throw new Error('sourceTXID or sourceTransaction required')
+  if (sourceOutput?.satoshis == null) throw new Error('source satoshis required')
+  if (sourceOutput.lockingScript == null) throw new Error('source lockingScript required')
+
+  const preimage = TransactionSignature.format({
+    sourceTXID,
+    sourceOutputIndex: input.sourceOutputIndex,
+    sourceSatoshis: sourceOutput.satoshis,
+    transactionVersion: tx.version,
+    otherInputs: tx.inputs.filter((_, i) => i !== inputIndex),
+    inputIndex,
+    outputs: tx.outputs,
+    inputSequence: input.sequence ?? 0xffffffff,
+    subscript: sourceOutput.lockingScript,
+    lockTime: tx.lockTime,
+    scope
+  })
+  return { preimage, scope }
+}