@bsv/templates 1.8.0 → 1.9.0

package/src/Bsv21Token.ts

@@ -0,0 +1,197 @@
+import { LockingScript, Utils } from '@bsv/sdk'
+
+/**
+ * Bsv21Token — decoder for BSV-21 (1Sat ordinals-style fungible token)
+ * locking scripts. The token is an ord-inscription envelope carrying a
+ * BSV-20 JSON payload, followed by a standard P2PKH owner lock:
+ *
+ *   OP_FALSE OP_IF "ord" OP_1 "application/bsv-20" OP_0 <json> OP_ENDIF
+ *   OP_DUP OP_HASH160 <owner_pkh:20> OP_EQUALVERIFY OP_CHECKSIG
+ *
+ * JSON: {"p":"bsv-20","op":"transfer"|"deploy+mint","id":"<txid_vout>","amt":"<int>",...}
+ *
+ * BSV-21 amounts are divisible bigints carried as strings; ownership is plain
+ * P2PKH. Decode-only — building transfers is the wallet's job (see the 1sat
+ * inscription builder). Mirrors the wallet's `parseBsv21LockingScript`.
+ */
+
+const ORD_TAG_HEX = '6f7264' // "ord"
+const CONTENT_TYPE = 'application/bsv-20'
+const OP_FALSE_HEX = '00'
+const OP_IF_HEX = '63'
+const OP_ENDIF_HEX = '68'
+const OP_DUP_HEX = '76'
+const OP_HASH160_HEX = 'a9'
+const OP_EQUALVERIFY_HEX = '88'
+const OP_CHECKSIG_HEX = 'ac'
+const PKH_PUSH_LEN_HEX = '14'
+
+export interface Bsv21TokenDecoded {
+  /** Token id `<txid>_<vout>` of the deploy+mint (empty for the mint output itself). */
+  id: string
+  /** Raw token amount as a stringified bigint. */
+  amt: string
+  /** Decimals (deploy+mint only). */
+  dec?: number
+  /** Symbol / ticker. */
+  sym?: string
+  /** Icon outpoint / URL. */
+  icon?: string
+  /** True when this is the deploy+mint output (no id in payload). */
+  isMint: boolean
+  /** Trailing P2PKH owner hash160 (hex). */
+  ownerHash160: string
+}
+
+class HexReader {
+  pos = 0
+  constructor (public readonly hex: string) {}
+  readByteHex (): string | null {
+    if (this.pos + 2 > this.hex.length) return null
+    const b = this.hex.substring(this.pos, this.pos + 2)
+    this.pos += 2
+    return b
+  }
+
+  readBytesHex (n: number): string | null {
+    if (this.pos + n * 2 > this.hex.length) return null
+    const out = this.hex.substring(this.pos, this.pos + n * 2)
+    this.pos += n * 2
+    return out
+  }
+
+  readPushHex (): string | null {
+    const op = this.readByteHex()
+    if (op === null) return null
+    const code = Number.parseInt(op, 16)
+    if (code === 0) return ''
+    if (code >= 0x01 && code <= 0x4b) return this.readBytesHex(code)
+    if (code === 0x4c) {
+      const lenHex = this.readByteHex()
+      if (lenHex === null) return null
+      return this.readBytesHex(Number.parseInt(lenHex, 16))
+    }
+    if (code === 0x4d) {
+      const b1 = this.readByteHex(); const b2 = this.readByteHex()
+      if (b1 === null || b2 === null) return null
+      return this.readBytesHex(Number.parseInt(b2 + b1, 16))
+    }
+    if (code === 0x4e) {
+      const b1 = this.readByteHex(); const b2 = this.readByteHex()
+      const b3 = this.readByteHex(); const b4 = this.readByteHex()
+      if (b1 === null || b2 === null || b3 === null || b4 === null) return null
+      return this.readBytesHex(Number.parseInt(b4 + b3 + b2 + b1, 16))
+    }
+    return null
+  }
+}
+
+function hexToUtf8 (hex: string): string {
+  if (hex === '') return ''
+  try {
+    return Utils.toUTF8(Utils.toArray(hex, 'hex'))
+  } catch {
+    return ''
+  }
+}
+
+/** Reads the ord-inscription envelope up to and including OP_ENDIF, returning its JSON payload. */
+function readOrdEnvelope (r: HexReader): any {
+  if (r.readPushHex() !== ORD_TAG_HEX) throw new Error('not a BSV-21 script: missing "ord" tag')
+
+  // Content-type field id: accept canonical OP_1 (0x51) or non-minimal push-of-0x01.
+  const peek = r.hex.substring(r.pos, r.pos + 2)
+  if (peek === '51') {
+    r.pos += 2
+  } else if (r.readPushHex() !== '01') {
+    throw new Error('not a BSV-21 script: bad content-type field id')
+  }
+
+  const ctHex = r.readPushHex()
+  if (ctHex === null || hexToUtf8(ctHex) !== CONTENT_TYPE) throw new Error('not a BSV-21 script: wrong content-type')
+
+  if (r.readByteHex() !== '00') throw new Error('not a BSV-21 script: missing OP_0 separator')
+
+  const contentHex = r.readPushHex()
+  if (contentHex === null) throw new Error('not a BSV-21 script: missing JSON payload')
+  let payload: any
+  try {
+    payload = JSON.parse(hexToUtf8(contentHex))
+  } catch {
+    throw new Error('not a BSV-21 script: invalid JSON payload')
+  }
+  if (payload?.p !== 'bsv-20') throw new Error('not a BSV-21 script: not bsv-20')
+
+  if (r.readByteHex() !== OP_ENDIF_HEX) throw new Error('not a BSV-21 script: missing OP_ENDIF')
+  return payload
+}
+
+/** Reads the trailing standard P2PKH owner lock, returning the owner hash160 (hex). */
+function readP2pkhOwner (r: HexReader): string {
+  const dup = r.readByteHex()
+  const hash160Op = r.readByteHex()
+  const pushLen = r.readByteHex()
+  if (dup !== OP_DUP_HEX || hash160Op !== OP_HASH160_HEX || pushLen !== PKH_PUSH_LEN_HEX) {
+    throw new Error('not a BSV-21 script: bad P2PKH owner lock')
+  }
+  const ownerHash160 = r.readBytesHex(20)
+  if (ownerHash160 === null) throw new Error('not a BSV-21 script: truncated owner hash')
+  if (r.readByteHex() !== OP_EQUALVERIFY_HEX || r.readByteHex() !== OP_CHECKSIG_HEX) {
+    throw new Error('not a BSV-21 script: bad P2PKH tail')
+  }
+  return ownerHash160
+}
+
+/** Parses the optional `dec` field, accepted as a number or a digit string in [0, 18]. */
+function parseDecimals (payload: any): number | undefined {
+  if (typeof payload.dec === 'number' && Number.isFinite(payload.dec)) return payload.dec
+  if (typeof payload.dec === 'string' && /^\d+$/.test(payload.dec)) {
+    const n = Number.parseInt(payload.dec, 10)
+    if (n >= 0 && n <= 18) return n
+  }
+  return undefined
+}
+
+export class Bsv21Token {
+  static isBsv21 (script: LockingScript): boolean {
+    try {
+      Bsv21Token.decode(script)
+      return true
+    } catch {
+      return false
+    }
+  }
+
+  /**
+   * Decodes a BSV-21 locking script.
+   * @throws if the script is not a recognisable BSV-21 output.
+   */
+  static decode (script: LockingScript): Bsv21TokenDecoded {
+    const lower = script.toHex().toLowerCase()
+    if (lower.length < 60) throw new Error('not a BSV-21 script: too short')
+    if (!lower.startsWith(OP_FALSE_HEX + OP_IF_HEX)) throw new Error('not a BSV-21 script: missing OP_FALSE OP_IF')
+
+    const r = new HexReader(lower)
+    r.pos = 4 // past OP_FALSE OP_IF
+
+    const payload = readOrdEnvelope(r)
+    const ownerHash160 = readP2pkhOwner(r)
+
+    const amt: string | undefined = payload.amt
+    if (typeof amt !== 'string' || !/^\d+$/.test(amt)) throw new Error('not a BSV-21 script: bad amount')
+
+    const isMint = payload.op === 'deploy+mint'
+    const dec = parseDecimals(payload)
+    const id = !isMint && typeof payload.id === 'string' ? payload.id : ''
+
+    return {
+      id,
+      amt,
+      dec,
+      sym: typeof payload.sym === 'string' ? payload.sym : undefined,
+      icon: typeof payload.icon === 'string' ? payload.icon : undefined,
+      isMint,
+      ownerHash160
+    }
+  }
+}

package/src/DstasToken.ts

@@ -0,0 +1,105 @@
+import { LockingScript } from '@bsv/sdk'
+
+/**
+ * DstasToken — decoder for DSTAS (Divisible STAS / STAS 3.0) locking scripts.
+ *
+ * DSTAS uses the dxs-bsv-token-sdk template:
+ *
+ *   <owner pkh:20> <action data> [ENGINE ~2.9KB] OP_RETURN
+ *     <redemption/protoID pkh:20 = tokenId> <flags> <service field per flag> <optional data...>
+ *
+ * Unlike the dxs SDK's full `LockingScriptReader` (which template-matches the
+ * whole body), this is a minimal *structural* recogniser sufficient for an
+ * overlay indexer: it extracts the owner, the tokenId (redemption pkh), the
+ * flags, and the frozen marker. DSTAS is satoshi-denominated, so the token
+ * amount is the containing output's satoshi value (read by the caller).
+ *
+ * Recognition signals (validated against real dxs SDK output):
+ *  - the script opens with a 20-byte push (the owner) — `14 <20 bytes>`;
+ *  - the body is large (the ~2.9KB engine);
+ *  - `6a 14 <20 bytes>` (OP_RETURN + redemption push) appears once, near the
+ *    end — the engine body contains no `6a14`.
+ *
+ * Decode-only; building DSTAS scripts is the dxs SDK's job.
+ */
+
+export interface DstasTokenDecoded {
+  /** Token identity for indexing + conservation — the redemption/protoID pkh. */
+  assetId: string
+  /** Same value as assetId; the redemption (protoID) pkh, hex. */
+  tokenId: string
+  /** Owner public-key hash (20-byte hex). */
+  ownerHash160: string
+  /** Flags byte(s), hex (bit 0x01 = freezable, 0x02 = confiscatable). */
+  flagsHex: string
+  freezeEnabled: boolean
+  confiscationEnabled: boolean
+  /** True when the action-data marker indicates a frozen UTXO. */
+  frozen: boolean
+}
+
+const OWNER_PUSH_OP = '14' // push 20 bytes
+// DSTAS scripts carry the ~2.9KB engine; anything smaller is not DSTAS.
+const MIN_HEX_LEN = 4000
+
+function isSinglePush (op: string): boolean {
+  const code = Number.parseInt(op, 16)
+  return code >= 0x01 && code <= 0x4b
+}
+
+export class DstasToken {
+  static isDstas (script: LockingScript): boolean {
+    try {
+      DstasToken.decode(script)
+      return true
+    } catch {
+      return false
+    }
+  }
+
+  /**
+   * Decodes a DSTAS locking script's identity fields.
+   * @throws if the script is not a recognisable DSTAS script.
+   */
+  static decode (script: LockingScript): DstasTokenDecoded {
+    const hex = script.toHex().toLowerCase()
+    if (hex.length < MIN_HEX_LEN) throw new Error('not a DSTAS script: too short')
+    if (!hex.startsWith(OWNER_PUSH_OP)) throw new Error('not a DSTAS script: missing 20-byte owner push')
+
+    const ownerHash160 = hex.substring(2, 42)
+
+    // OP_RETURN (0x6a) + redemption push (0x14) — unique in a DSTAS body.
+    const ri = hex.lastIndexOf('6a14')
+    if (ri < 0) throw new Error('not a DSTAS script: missing OP_RETURN + redemption')
+    const tokenId = hex.substring(ri + 4, ri + 44)
+    if (tokenId.length !== 40) throw new Error('not a DSTAS script: truncated redemption')
+
+    // Flags push immediately follows the redemption push.
+    let flagsHex = ''
+    const flagsLenOp = hex.substring(ri + 44, ri + 46)
+    if (isSinglePush(flagsLenOp)) {
+      const len = Number.parseInt(flagsLenOp, 16)
+      flagsHex = hex.substring(ri + 46, ri + 46 + len * 2)
+    }
+    const flagsByte = flagsHex.length >= 2 ? Number.parseInt(flagsHex.substring(0, 2), 16) : 0
+    const freezeEnabled = (flagsByte & 0x01) !== 0
+    const confiscationEnabled = (flagsByte & 0x02) !== 0
+
+    // Action-data marker sits right after the owner push:
+    //   OP_0 (00) = neutral; OP_2 (52) = frozen; push prefixed 0x02 = frozen.
+    const actionOp = hex.substring(42, 44)
+    const frozen =
+      actionOp === '52' ||
+      (isSinglePush(actionOp) && hex.substring(44, 46) === '02')
+
+    return {
+      assetId: tokenId,
+      tokenId,
+      ownerHash160,
+      flagsHex,
+      freezeEnabled,
+      confiscationEnabled,
+      frozen
+    }
+  }
+}

package/src/MandalaAdmin.ts

@@ -9,7 +9,7 @@ import { createMinimallyEncodedScriptChunk } from './mandala-encoding.js'
 export interface AssetMetadata { label: string, ticker?: string, decimals?: number, [k: string]: unknown }
 
 export type MandalaActionKind =
-  | 'register' | 'issue' | 'redeem' | 'recover'
+  | 'register' | 'issue' | 'redeem'
   | 'pause' | 'unpause'
   | 'blockIdentity' | 'unblockIdentity'
   | 'allowIdentity' | 'unallowIdentity'

package/src/StasToken.ts

@@ -0,0 +1,136 @@
+import { LockingScript, Utils } from '@bsv/sdk'
+
+/**
+ * StasToken — decoder for **classic STAS** (legacy P2STAS / STAS 1.0) locking
+ * scripts. Unlike {@link MandalaToken}, classic STAS is satoshi-denominated:
+ * the token amount IS the output's satoshi value, so this template only
+ * recovers the on-chain *identity* fields (owner PKH + symbol). The amount is
+ * read from the containing output by the caller.
+ *
+ * Script shape produced by stas-js CreateContract:
+ *
+ *   76a914 <owner_pkh:20> 88ac69 <engine ~2.9KB> 6a <flags> <symbol> <data...>
+ *
+ * The owner hash160 sits at the well-known P2PKH-like prefix. The engine body
+ * is large and opaque (and may contain incidental `6a` bytes), so the OP_RETURN
+ * trailer is located by scanning from the end, matching the wallet's
+ * `parseClassicStasMetadata` source of truth.
+ *
+ * Building/unlocking classic STAS scripts is the stas-js engine's job; this
+ * template is decode-only.
+ */
+
+export interface StasTokenDecoded {
+  /** Token identity used for indexing + conservation grouping (the symbol). */
+  assetId: string
+  /** Token symbol parsed from the OP_RETURN trailer, or null if absent. */
+  symbol: string | null
+  /** Owner public-key hash (20-byte hex) from the P2PKH-like prefix. */
+  ownerHash160: string
+  /** Flags byte (hex) from the OP_RETURN trailer, or null if absent. */
+  flagsHex: string | null
+}
+
+const P2PKH_PREFIX = '76a914'
+const STAS_MARKER = '88ac69'
+
+interface PushLength { len: number, dataStart: number }
+
+/** Resolves a push opcode's payload length + data offset, or null for a non-push opcode. */
+function pushDataLength (scriptHex: string, opcode: number, pos: number): PushLength | null {
+  if (opcode >= 0x01 && opcode <= 0x4b) return { len: opcode, dataStart: pos }
+  if (opcode === 0x4c) {
+    if (pos + 2 > scriptHex.length) return null
+    return { len: Number.parseInt(scriptHex.substring(pos, pos + 2), 16), dataStart: pos + 2 }
+  }
+  if (opcode === 0x4d) {
+    if (pos + 4 > scriptHex.length) return null
+    const b1 = scriptHex.substring(pos, pos + 2)
+    const b2 = scriptHex.substring(pos + 2, pos + 4)
+    return { len: Number.parseInt(b2 + b1, 16), dataStart: pos + 4 }
+  }
+  if (opcode === 0x4e) {
+    if (pos + 8 > scriptHex.length) return null
+    const b1 = scriptHex.substring(pos, pos + 2)
+    const b2 = scriptHex.substring(pos + 2, pos + 4)
+    const b3 = scriptHex.substring(pos + 4, pos + 6)
+    const b4 = scriptHex.substring(pos + 6, pos + 8)
+    return { len: Number.parseInt(b4 + b3 + b2 + b1, 16), dataStart: pos + 8 }
+  }
+  return null
+}
+
+/** Reads push-data slots starting at a hex offset (after OP_RETURN). */
+function readPushes (scriptHex: string, startPos: number, max = 8): string[] {
+  const pushes: string[] = []
+  let pos = startPos
+  while (pos < scriptHex.length && pushes.length < max) {
+    if (pos + 2 > scriptHex.length) break
+    const opcode = Number.parseInt(scriptHex.substring(pos, pos + 2), 16)
+    if (Number.isNaN(opcode)) break
+    pos += 2
+    if (opcode === 0) {
+      pushes.push('')
+      continue
+    }
+    const push = pushDataLength(scriptHex, opcode, pos)
+    if (push === null) break // non-push opcode (or truncated length) after OP_RETURN — stop
+    pushes.push(scriptHex.substring(push.dataStart, push.dataStart + push.len * 2))
+    pos = push.dataStart + push.len * 2
+  }
+  return pushes
+}
+
+function hexToUtf8 (hex: string): string {
+  if (hex === '') return ''
+  try {
+    return Utils.toUTF8(Utils.toArray(hex, 'hex'))
+  } catch {
+    return ''
+  }
+}
+
+export class StasToken {
+  /** True if the script carries the classic STAS prefix + marker. */
+  static isStas (script: LockingScript): boolean {
+    const hex = script.toHex()
+    return hex.startsWith(P2PKH_PREFIX) && hex.substring(46, 52) === STAS_MARKER
+  }
+
+  /**
+   * Decodes a classic STAS locking script into its identity fields.
+   * @throws if the script is not a classic STAS script.
+   */
+  static decode (script: LockingScript): StasTokenDecoded {
+    const hex = script.toHex()
+    if (hex.length < 56) throw new Error('not a STAS script: too short')
+    if (!hex.startsWith(P2PKH_PREFIX)) throw new Error('not a STAS script: missing P2PKH prefix')
+    if (hex.substring(46, 52) !== STAS_MARKER) throw new Error('not a STAS script: missing STAS marker')
+
+    const ownerHash160 = hex.substring(6, 46)
+
+    // OP_RETURN (0x6a) is placed by CreateContract as the last opcode before
+    // the data region. The engine body may contain incidental 0x6a bytes, so
+    // scan from the back.
+    const opReturnIdx = hex.lastIndexOf('6a')
+    let symbol: string | null = null
+    let flagsHex: string | null = null
+    if (opReturnIdx >= 0) {
+      const pushes = readPushes(hex, opReturnIdx + 2)
+      // Layout after OP_RETURN: [flagsByte, symbol, data, ...].
+      flagsHex = pushes[0]?.length === 2 ? pushes[0] : null
+      const symbolHex = pushes[1] ?? null
+      symbol = (symbolHex != null && symbolHex !== '')
+        ? (hexToUtf8(symbolHex).replace(/[\x00- ]/g, '').trim() || null)
+        : null
+    }
+
+    // assetId groups inputs/outputs of the same token for conservation. The
+    // symbol is the only identity carried in a classic STAS script; tokens
+    // with no symbol fall back to the owner-agnostic script tail hash so the
+    // grouping is still stable within a single transfer.
+    const assetId = symbol ?? `stas:${hex.substring(52, 68)}`
+
+    return { assetId, symbol, ownerHash160, flagsHex }
+  }
+}

package/src/__tests/Bsv21Token.test.ts

@@ -0,0 +1,56 @@
+import { Bsv21Token } from '../Bsv21Token'
+import { LockingScript, Utils } from '@bsv/sdk'
+
+const OWNER = 'ab'.repeat(20)
+
+function utf8ToHex (s: string): string {
+  return Utils.toArray(s, 'utf8').map(b => b.toString(16).padStart(2, '0')).join('')
+}
+function push (bytesHex: string): string {
+  const len = bytesHex.length / 2
+  if (len === 0) return '00'
+  if (len <= 0x4b) return len.toString(16).padStart(2, '0') + bytesHex
+  if (len <= 0xff) return '4c' + len.toString(16).padStart(2, '0') + bytesHex
+  const lo = len & 0xff; const hi = (len >> 8) & 0xff
+  return '4d' + lo.toString(16).padStart(2, '0') + hi.toString(16).padStart(2, '0') + bytesHex
+}
+
+// Build a BSV-21 envelope with the given JSON payload + P2PKH owner tail.
+function bsv21Script (payload: Record<string, string>, owner = OWNER): LockingScript {
+  const json = utf8ToHex(JSON.stringify(payload))
+  const envelope =
+    '00' + '63' + // OP_FALSE OP_IF
+    push(utf8ToHex('ord')) +
+    '51' + // OP_1 content-type tag
+    push(utf8ToHex('application/bsv-20')) +
+    '00' + // OP_0 separator
+    push(json) +
+    '68' // OP_ENDIF
+  const p2pkh = '76a914' + owner + '88ac'
+  return LockingScript.fromHex(envelope + p2pkh)
+}
+
+describe('Bsv21Token.decode', () => {
+  it('decodes a transfer output', () => {
+    const id = `${'cd'.repeat(32)}_0`
+    const d = Bsv21Token.decode(bsv21Script({ p: 'bsv-20', op: 'transfer', id, amt: '500' }))
+    expect(d).toMatchObject({ id, amt: '500', isMint: false, ownerHash160: OWNER })
+  })
+
+  it('decodes a deploy+mint output (no id in payload)', () => {
+    const d = Bsv21Token.decode(bsv21Script({ p: 'bsv-20', op: 'deploy+mint', amt: '21000000', dec: '8', sym: 'TIK' }))
+    expect(d).toMatchObject({ id: '', amt: '21000000', dec: 8, sym: 'TIK', isMint: true })
+  })
+
+  it('isBsv21 is false for plain P2PKH', () => {
+    expect(Bsv21Token.isBsv21(LockingScript.fromHex(`76a914${OWNER}88ac`))).toBe(false)
+  })
+
+  it('throws on a non-bsv-20 inscription protocol', () => {
+    expect(() => Bsv21Token.decode(bsv21Script({ p: 'bsv-21', op: 'transfer', id: 'x', amt: '1' }))).toThrow(/bsv-20/)
+  })
+
+  it('throws on a missing/invalid amount', () => {
+    expect(() => Bsv21Token.decode(bsv21Script({ p: 'bsv-20', op: 'transfer', id: 'x' } as any))).toThrow(/amount/)
+  })
+})

package/src/__tests/DstasToken.test.ts

@@ -0,0 +1,33 @@
+import { DstasToken } from '../DstasToken'
+import { LockingScript } from '@bsv/sdk'
+import { DSTAS_PLAIN_HEX, DSTAS_FROZEN_HEX, DSTAS_OWNER, DSTAS_TOKEN_ID } from './dstas-fixtures'
+
+describe('DstasToken.decode (against real dxs-bsv-token-sdk output)', () => {
+  it('recovers owner, tokenId, flags from a real DSTAS script', () => {
+    const d = DstasToken.decode(LockingScript.fromHex(DSTAS_PLAIN_HEX))
+    expect(d.ownerHash160).toBe(DSTAS_OWNER)
+    expect(d.tokenId).toBe(DSTAS_TOKEN_ID)
+    expect(d.assetId).toBe(DSTAS_TOKEN_ID)
+    expect(d.flagsHex).toBe('03')
+    expect(d.freezeEnabled).toBe(true)
+    expect(d.confiscationEnabled).toBe(true)
+    expect(d.frozen).toBe(false)
+  })
+
+  it('detects the frozen marker (OP_2 action data)', () => {
+    const d = DstasToken.decode(LockingScript.fromHex(DSTAS_FROZEN_HEX))
+    expect(d.frozen).toBe(true)
+    expect(d.tokenId).toBe(DSTAS_TOKEN_ID)
+  })
+
+  it('isDstas is true for DSTAS, false for plain P2PKH and classic STAS', () => {
+    expect(DstasToken.isDstas(LockingScript.fromHex(DSTAS_PLAIN_HEX))).toBe(true)
+    expect(DstasToken.isDstas(LockingScript.fromHex(`76a914${DSTAS_OWNER}88ac`))).toBe(false)
+    // classic STAS prefix is 76a914… not a 20-byte owner push, and short.
+    expect(DstasToken.isDstas(LockingScript.fromHex(`76a914${DSTAS_OWNER}88ac69` + 'ac'.repeat(8)))).toBe(false)
+  })
+
+  it('throws on a short / non-DSTAS script', () => {
+    expect(() => DstasToken.decode(LockingScript.fromHex(`14${DSTAS_OWNER}00`))).toThrow(/DSTAS/)
+  })
+})

package/src/__tests/StasToken.test.ts

@@ -0,0 +1,44 @@
+import { StasToken } from '../StasToken'
+import { LockingScript } from '@bsv/sdk'
+
+// Build a synthetic classic STAS script matching stas-js CreateContract shape:
+//   76a914 <owner_pkh:20> 88ac69 <engine> 6a <flags push> <symbol push> <data>
+const ownerHash160 = 'ab'.repeat(20)
+const engine = 'ac'.repeat(8) // opaque filler, deliberately free of 0x6a bytes
+const flagsPush = '0100' // push 1 byte: flags = 0x00
+const symbolPush = '04' + '54455354' // push 4 bytes: "TEST"
+const stasHex = `76a914${ownerHash160}88ac69${engine}6a${flagsPush}${symbolPush}`
+
+describe('StasToken.decode', () => {
+  it('recovers owner, symbol, flags, and assetId from a classic STAS script', () => {
+    const decoded = StasToken.decode(LockingScript.fromHex(stasHex))
+    expect(decoded.ownerHash160).toBe(ownerHash160)
+    expect(decoded.symbol).toBe('TEST')
+    expect(decoded.assetId).toBe('TEST')
+    expect(decoded.flagsHex).toBe('00')
+  })
+
+  it('isStas is true for a STAS script and false for plain P2PKH', () => {
+    const p2pkh = `76a914${ownerHash160}88ac`
+    expect(StasToken.isStas(LockingScript.fromHex(stasHex))).toBe(true)
+    expect(StasToken.isStas(LockingScript.fromHex(p2pkh))).toBe(false)
+  })
+
+  it('throws when the STAS marker is absent (long P2PKH-like script)', () => {
+    // ≥56 hex chars, starts with the P2PKH prefix but lacks the 88ac69 marker.
+    const notStas = `76a914${ownerHash160}88accccccccccc`
+    expect(() => StasToken.decode(LockingScript.fromHex(notStas))).toThrow(/STAS marker/)
+  })
+
+  it('throws when the P2PKH prefix is absent', () => {
+    expect(() => StasToken.decode(LockingScript.fromHex('6a0048656c6c6f'))).toThrow(/STAS/)
+  })
+
+  it('falls back to a script-derived assetId when no symbol is present', () => {
+    // OP_RETURN with only a flags push, no symbol slot.
+    const noSymbol = `76a914${ownerHash160}88ac69${engine}6a${flagsPush}`
+    const decoded = StasToken.decode(LockingScript.fromHex(noSymbol))
+    expect(decoded.symbol).toBeNull()
+    expect(decoded.assetId).toMatch(/^stas:/)
+  })
+})

package/src/__tests/dstas-fixtures.ts

@@ -0,0 +1,6 @@
+// Real DSTAS locking scripts generated by dxs-bsv-token-sdk (buildDstasLockingScript).
+// owner=2f2ec98d… redemption(tokenId)=b4ab0fff… flags=0x03 (freeze+confiscation).
+export const DSTAS_PLAIN_HEX = '142f2ec98dfa6429a028536a6c9451f702daa3a333006d82736301218763007b7b517c6e5667766b517f786b517f73637c7f68517f73637c7f68517f73637c7f68517f73637c7f68517f73637c7f68766c936c7c5493686751687652937a76aa607f5f7f7c5e7f7c5d7f7c5c7f7c5b7f7c5a7f7c597f7c587f7c577f7c567f7c557f7c547f7c537f7c527f7c517f7c7e7e7e7e7e7e7e7e7e7e7e7e7e7e7e7c5f7f7c5e7f7c5d7f7c5c7f7c5b7f7c5a7f7c597f7c587f7c577f7c567f7c557f7c547f7c537f7c527f7c517f7c7e7e7e7e7e7e7e7e7e7e7e7e7e7e7e7e011f7f7d7e01007e8111414136d08c5ed2bf3ba048afe6dcaebafe01005f80837e01007e7652967b537a7601ff877c0100879b7d648b6752799368537a7d9776547aa06394677768263044022079be667ef9dcbbac55a06295ce870b07029bfcdb2dce28d959f2815b16f8179802207c607f5f7f7c5e7f7c5d7f7c5c7f7c5b7f7c5a7f7c597f7c587f7c577f7c567f7c557f7c547f7c537f7c527f7c517f7c7e7e7e7e7e7e7e7e7e7e7e7e7e7e7e7c5f7f7c5e7f7c5d7f7c5c7f7c5b7f7c5a7f7c597f7c587f7c577f7c567f7c557f7c547f7c537f7c527f7c517f7c7e7e7e7e7e7e7e7e7e7e7e7e7e7e7e7e7e01417e7c6421038ff83d8cf12121491609c4939dc11c4aa35503508fe432dc5a5c1905608b92186721023635954789a02e39fb7e54440b6f528d53efd65635ddad7f3c4085f97fdbdc4868ad547f7701207f01207f7701247f517f7801007e02fd00a063546752687f7801007e817f727e7b517f7c01147d887f517f7c01007e817601619f6976014ea063517c7b6776014ba06376014da063755467014d9c6352675168687f7c01007e81687f007b7b687602540b7f7701147f7c5579876b826475020100686b587a5893766b7a765155a569005379736382013ca07c517f7c51877b9a6352795487637101007c7e717101207f01147f7577776775785387646c766b8b8b7951886868677568686c6c7c6b517f7c817f788273638c7f776775010068518463517f7c01147d887f547952876372777c717c767663517f756852875779766352790152879a689b63517f77567a7567527c7681014f0161a5587a9a63015094687e68746c766b5c9388748c76795879888c8c7978886777717c567a5679538764780152879a787663517f756852879b745394768b797663517f756852877c6c766b5c936ea0637c8c768b797663517f75685287726b9b7c6c686ea0637c5394768b797663517f75685287726b9b7c6c686ea063755494797663517f756852879b676d689b63006968677568687c717167567a7568788273638c7f776775010068528463517f7c01147d887f547953876372777c677768686d6c75787653877c52879b636c75006b687c518763755279685879a9886b6b6b6b6b6b6b827763af686c6c6c6c6c6c6c547a577a7664577a577a587a597a786354807e7e676d68aa8800677b7c7651876375577a7c587a67007c68765258a569765187645294597a53795b7a7e7e78637c8c7c53797e5a7a7e6878637c8c7c53797e5a7a7e6878637c8c7c53797e5a7a7e6878637c8c7c53797e5a7a7e6878637c8c7c53797e5a7a7e68687276647572677772755168537a76aa5a7a7d54807e597a5b7a5c7a786354807e6f7e7eaa727c7e676d6e7eaa7c687b7eaa5a7a7d877663516752687c72879b69537a6491687c7b547f77517f7853a0916901247f77517f7c01007e817602fc00a06302fd00a063546752687f7c01007e816854937f77788c6301247f77517f7c01007e817602fc00a06302fd00a063546752687f7c01007e816854937f777852946301247f77517f7c01007e817602fc00a06302fd00a063546752687f7c01007e816854937f77686877517f7c52797d8b9f7c53a09b91697c76638c7c587f77517f7c01007e817602fc00a06302fd00a063546752687f7c01007e81687f777c6876638c7c587f77517f7c01007e817602fc00a06302fd00a063546752687f7c01007e81687f777c6863587f77517f7c01007e817602fc00a06302fd00a063546752687f7c01007e81687f7768587f517f7801007e817602fc00a06302fd00a063546752687f7801007e81727e7b7b687f75517f7c01147d887f517f7c01007e817601619f6976014ea0637c6776014ba06376014da063755467014d9c6352675168687f7c01007e81687f68557964577988756d67716881687863567a677b68587f7c8153796353795287637b6b537a6b717c6b6b537a6b676b577a6b597a6b587a6b577a6b7c68677b93687c547f7701207f75748c7a7669765880044676a914780114748c7a76727b748c7a768291788251877c764f877c81510111a59b9a9b648276014ba1647602ff00a16351014c677603ffff00a16352014d6754014e68687b7b7f757e687c7e67736301509367010068685c795c79636c766b7363517f7c51876301207f7c5279a8877c011c7f5579877c01147f755679879a9a6967756868687e777e7e827602fc00a0637603ffff00a06301fe7c82546701fd7c8252687da0637f756780687e67517f75687c7e7e0a888201218763ac67517f07517f73637c7f6876767e767e7e02ae687e7e7c557a00740111a063005a79646b7c748c7a76697d937b7b58807e6c91677c748c7a7d58807e6c6c6c557a680114748c7a748c7a768291788251877c764f877c81510111a59b9a9b648276014ba1647602ff00a16351014c677603ffff00a16352014d6754014e68687b7b7f757e687c7e67736301509367010068685479635f79676c766b0115797363517f7c51876301207f7c5279a8877c011c7f5579877c01147f755679879a9a6967756868687e777e7e827602fc00a0637603ffff00a06301fe7c82546701fd7c8252687da0637f756780687e67517f75687c7e7c637e677c6b7c6b7c6b7e7c6b68685979636c6c766b786b7363517f7c51876301347f77547f547f75786352797b01007e81957c01007e81965379a169676d68677568685c797363517f7c51876301347f77547f547f75786354797b01007e81957c01007e819678a169676d68677568687568740111a063748c7a76697d58807e00005c79635e79768263517f756851876c6c766b7c6b768263517f756851877b6e9b63789c6375745294797b78877b7b877d9b69637c917c689167745294797c638777637c917c91686777876391677c917c686868676d6d68687863537a6c936c6c6c567a567a54795479587a676b72937b7b5c795e796c68748c7a748c7a7b636e717b7b877b7b879a6967726d6801147b7e7c8291788251877c764f877c81510111a59b9a9b648276014ba1647602ff00a16351014c677603ffff00a16352014d6754014e68687b7b7f757e687c7e67736301509367010068687e7c636c766b7e726b6b726b6b675b797e68827602fc00a0637603ffff00a06301fe7c82546701fd7c8252687da0637f756780687e67517f75687c7e7e68740111a063748c7a76697d58807e00005c79635e79768263517f756851876c6c766b7c6b768263517f756851877b6e9b63789c6375745294797b78877b7b877d9b69637c917c689167745294797c638777637c917c91686777876391677c917c686868676d6d68687863537a6c936c6c6c567a567a54795479587a676b72937b7b5c795e796c68748c7a748c7a7b636e717b7b877b7b879a6967726d6801147b7e7c8291788251877c764f877c81510111a59b9a9b648276014ba1647602ff00a16351014c677603ffff00a16352014d6754014e68687b7b7f757e687c7e67736301509367010068687e7c636c766b7e726b6b726b6b675b797e68827602fc00a0637603ffff00a06301fe7c82546701fd7c8252687da0637f756780687e67517f75687c7e7e68597a636c6c6c6d6c6c6d6c9d687c587a9d7d7e5c79635d795880041976a9145e797e0288ac7e7e6700687d7e5c7a766302006a7c7e827602fc00a06301fd7c7e536751687f757c7e0058807c7e687d7eaa6b7e7e7e7e7e7eaa78877c6c877c6c9a9b726d726d77776a14b4ab0fffa02223a8a40d9e7f7823e61b3862538201031400112233445566778899aabbccddeeff00112233148899aabbccddeeff00112233445566778899aabb'
+export const DSTAS_FROZEN_HEX = '142f2ec98dfa6429a028536a6c9451f702daa3a333526d82736301218763007b7b517c6e5667766b517f786b517f73637c7f68517f73637c7f68517f73637c7f68517f73637c7f68517f73637c7f68766c936c7c5493686751687652937a76aa607f5f7f7c5e7f7c5d7f7c5c7f7c5b7f7c5a7f7c597f7c587f7c577f7c567f7c557f7c547f7c537f7c527f7c517f7c7e7e7e7e7e7e7e7e7e7e7e7e7e7e7e7c5f7f7c5e7f7c5d7f7c5c7f7c5b7f7c5a7f7c597f7c587f7c577f7c567f7c557f7c547f7c537f7c527f7c517f7c7e7e7e7e7e7e7e7e7e7e7e7e7e7e7e7e011f7f7d7e01007e8111414136d08c5ed2bf3ba048afe6dcaebafe01005f80837e01007e7652967b537a7601ff877c0100879b7d648b6752799368537a7d9776547aa06394677768263044022079be667ef9dcbbac55a06295ce870b07029bfcdb2dce28d959f2815b16f8179802207c607f5f7f7c5e7f7c5d7f7c5c7f7c5b7f7c5a7f7c597f7c587f7c577f7c567f7c557f7c547f7c537f7c527f7c517f7c7e7e7e7e7e7e7e7e7e7e7e7e7e7e7e7c5f7f7c5e7f7c5d7f7c5c7f7c5b7f7c5a7f7c597f7c587f7c577f7c567f7c557f7c547f7c537f7c527f7c517f7c7e7e7e7e7e7e7e7e7e7e7e7e7e7e7e7e7e01417e7c6421038ff83d8cf12121491609c4939dc11c4aa35503508fe432dc5a5c1905608b92186721023635954789a02e39fb7e54440b6f528d53efd65635ddad7f3c4085f97fdbdc4868ad547f7701207f01207f7701247f517f7801007e02fd00a063546752687f7801007e817f727e7b517f7c01147d887f517f7c01007e817601619f6976014ea063517c7b6776014ba06376014da063755467014d9c6352675168687f7c01007e81687f007b7b687602540b7f7701147f7c5579876b826475020100686b587a5893766b7a765155a569005379736382013ca07c517f7c51877b9a6352795487637101007c7e717101207f01147f7577776775785387646c766b8b8b7951886868677568686c6c7c6b517f7c817f788273638c7f776775010068518463517f7c01147d887f547952876372777c717c767663517f756852875779766352790152879a689b63517f77567a7567527c7681014f0161a5587a9a63015094687e68746c766b5c9388748c76795879888c8c7978886777717c567a5679538764780152879a787663517f756852879b745394768b797663517f756852877c6c766b5c936ea0637c8c768b797663517f75685287726b9b7c6c686ea0637c5394768b797663517f75685287726b9b7c6c686ea063755494797663517f756852879b676d689b63006968677568687c717167567a7568788273638c7f776775010068528463517f7c01147d887f547953876372777c677768686d6c75787653877c52879b636c75006b687c518763755279685879a9886b6b6b6b6b6b6b827763af686c6c6c6c6c6c6c547a577a7664577a577a587a597a786354807e7e676d68aa8800677b7c7651876375577a7c587a67007c68765258a569765187645294597a53795b7a7e7e78637c8c7c53797e5a7a7e6878637c8c7c53797e5a7a7e6878637c8c7c53797e5a7a7e6878637c8c7c53797e5a7a7e6878637c8c7c53797e5a7a7e68687276647572677772755168537a76aa5a7a7d54807e597a5b7a5c7a786354807e6f7e7eaa727c7e676d6e7eaa7c687b7eaa5a7a7d877663516752687c72879b69537a6491687c7b547f77517f7853a0916901247f77517f7c01007e817602fc00a06302fd00a063546752687f7c01007e816854937f77788c6301247f77517f7c01007e817602fc00a06302fd00a063546752687f7c01007e816854937f777852946301247f77517f7c01007e817602fc00a06302fd00a063546752687f7c01007e816854937f77686877517f7c52797d8b9f7c53a09b91697c76638c7c587f77517f7c01007e817602fc00a06302fd00a063546752687f7c01007e81687f777c6876638c7c587f77517f7c01007e817602fc00a06302fd00a063546752687f7c01007e81687f777c6863587f77517f7c01007e817602fc00a06302fd00a063546752687f7c01007e81687f7768587f517f7801007e817602fc00a06302fd00a063546752687f7801007e81727e7b7b687f75517f7c01147d887f517f7c01007e817601619f6976014ea0637c6776014ba06376014da063755467014d9c6352675168687f7c01007e81687f68557964577988756d67716881687863567a677b68587f7c8153796353795287637b6b537a6b717c6b6b537a6b676b577a6b597a6b587a6b577a6b7c68677b93687c547f7701207f75748c7a7669765880044676a914780114748c7a76727b748c7a768291788251877c764f877c81510111a59b9a9b648276014ba1647602ff00a16351014c677603ffff00a16352014d6754014e68687b7b7f757e687c7e67736301509367010068685c795c79636c766b7363517f7c51876301207f7c5279a8877c011c7f5579877c01147f755679879a9a6967756868687e777e7e827602fc00a0637603ffff00a06301fe7c82546701fd7c8252687da0637f756780687e67517f75687c7e7e0a888201218763ac67517f07517f73637c7f6876767e767e7e02ae687e7e7c557a00740111a063005a79646b7c748c7a76697d937b7b58807e6c91677c748c7a7d58807e6c6c6c557a680114748c7a748c7a768291788251877c764f877c81510111a59b9a9b648276014ba1647602ff00a16351014c677603ffff00a16352014d6754014e68687b7b7f757e687c7e67736301509367010068685479635f79676c766b0115797363517f7c51876301207f7c5279a8877c011c7f5579877c01147f755679879a9a6967756868687e777e7e827602fc00a0637603ffff00a06301fe7c82546701fd7c8252687da0637f756780687e67517f75687c7e7c637e677c6b7c6b7c6b7e7c6b68685979636c6c766b786b7363517f7c51876301347f77547f547f75786352797b01007e81957c01007e81965379a169676d68677568685c797363517f7c51876301347f77547f547f75786354797b01007e81957c01007e819678a169676d68677568687568740111a063748c7a76697d58807e00005c79635e79768263517f756851876c6c766b7c6b768263517f756851877b6e9b63789c6375745294797b78877b7b877d9b69637c917c689167745294797c638777637c917c91686777876391677c917c686868676d6d68687863537a6c936c6c6c567a567a54795479587a676b72937b7b5c795e796c68748c7a748c7a7b636e717b7b877b7b879a6967726d6801147b7e7c8291788251877c764f877c81510111a59b9a9b648276014ba1647602ff00a16351014c677603ffff00a16352014d6754014e68687b7b7f757e687c7e67736301509367010068687e7c636c766b7e726b6b726b6b675b797e68827602fc00a0637603ffff00a06301fe7c82546701fd7c8252687da0637f756780687e67517f75687c7e7e68740111a063748c7a76697d58807e00005c79635e79768263517f756851876c6c766b7c6b768263517f756851877b6e9b63789c6375745294797b78877b7b877d9b69637c917c689167745294797c638777637c917c91686777876391677c917c686868676d6d68687863537a6c936c6c6c567a567a54795479587a676b72937b7b5c795e796c68748c7a748c7a7b636e717b7b877b7b879a6967726d6801147b7e7c8291788251877c764f877c81510111a59b9a9b648276014ba1647602ff00a16351014c677603ffff00a16352014d6754014e68687b7b7f757e687c7e67736301509367010068687e7c636c766b7e726b6b726b6b675b797e68827602fc00a0637603ffff00a06301fe7c82546701fd7c8252687da0637f756780687e67517f75687c7e7e68597a636c6c6c6d6c6c6d6c9d687c587a9d7d7e5c79635d795880041976a9145e797e0288ac7e7e6700687d7e5c7a766302006a7c7e827602fc00a06301fd7c7e536751687f757c7e0058807c7e687d7eaa6b7e7e7e7e7e7eaa78877c6c877c6c9a9b726d726d77776a14b4ab0fffa02223a8a40d9e7f7823e61b3862538201031400112233445566778899aabbccddeeff00112233148899aabbccddeeff00112233445566778899aabb'
+export const DSTAS_OWNER = '2f2ec98dfa6429a028536a6c9451f702daa3a333'
+export const DSTAS_TOKEN_ID = 'b4ab0fffa02223a8a40d9e7f7823e61b38625382'