@arkade-os/sdk 0.5.0-rc.2 → 0.5.0-rc.21

package/dist/{chunk-3R476TDV.js → chunk-CXHJGED6.js}

@@ -1,42 +1,25 @@
-import { VtxoScript, MultisigTapscript, CSVMultisigTapscript, timelockToSequence, sequenceToTimelock, ConditionMultisigTapscript, CLTVMultisigTapscript, ConditionCSVMultisigTapscript, SCRIPT_QUERY_CHUNK_SIZE, getNormalizedVtxos, DEFAULT_PAGE_SIZE } from './chunk-ISO4TI5J.js';
-import { __export } from './chunk-NSBPE2FW.js';
+import { __export, VtxoScript, MultisigTapscript, CSVMultisigTapscript, timelockToSequence, sequenceToTimelock, ConditionMultisigTapscript, CLTVMultisigTapscript, ConditionCSVMultisigTapscript, SCRIPT_QUERY_CHUNK_SIZE, getNormalizedVtxos, DEFAULT_PAGE_SIZE, sequenceToCanonicalTimelock } from './chunk-4FDNOLBO.js';
 import { hex } from '@scure/base';
 import { networks, expand } from '@bitcoinerlab/descriptors-scure';
 import { ScriptNum, OP, Script } from '@scure/btc-signer';
+import * as P from 'micro-packed';
 import { schnorr, secp256k1 } from '@noble/curves/secp256k1.js';
 import { bytesToNumberBE } from '@noble/curves/utils.js';
 
 // src/contracts/handlers/registry.ts
 var ContractHandlerRegistry = class {
   handlers = /* @__PURE__ */ new Map();
-  /**
-   * Register a contract handler.
-   *
-   * @param handler - The handler to register
-   * @throws If a handler for this type is already registered
-   */
+  /** @throws If a handler for this type is already registered */
   register(handler) {
     if (this.handlers.has(handler.type)) {
       throw new Error(`Contract handler for type '${handler.type}' is already registered`);
     }
     this.handlers.set(handler.type, handler);
   }
-  /**
-   * Get a handler by type.
-   *
-   * @param type - The contract type
-   * @returns The handler, or undefined if not found
-   */
   get(type) {
     return this.handlers.get(type);
   }
-  /**
-   * Get a handler by type, throwing if not found.
-   *
-   * @param type - The contract type
-   * @returns The handler
-   * @throws If no handler is registered for this type
-   */
+  /** @throws If no handler is registered for this type */
   getOrThrow(type) {
     const handler = this.get(type);
     if (!handler) {
@@ -44,29 +27,17 @@ var ContractHandlerRegistry = class {
     }
     return handler;
   }
-  /**
-   * Check if a handler is registered.
-   *
-   * @param type - The contract type
-   */
   has(type) {
     return this.handlers.has(type);
   }
-  /**
-   * Get all registered types.
-   */
   getRegisteredTypes() {
     return Array.from(this.handlers.keys());
   }
-  /**
-   * Unregister a handler (mainly for testing).
-   */
+  /** Unregister a handler (mainly for testing). */
   unregister(type) {
     return this.handlers.delete(type);
   }
-  /**
-   * Clear all handlers (mainly for testing).
-   */
+  /** Clear all handlers (mainly for testing). */
   clear() {
     this.handlers.clear();
   }
@@ -266,21 +237,8 @@ function resolveRole(contract, context) {
     }
     return void 0;
   };
-  if (context.walletDescriptor) {
-    const walletDescriptorKey = extractRawPubKey(context.walletDescriptor);
-    const matchedRole = matchRole(walletDescriptorKey);
-    if (matchedRole) {
-      return matchedRole;
-    }
-    if (!walletDescriptorKey && context.walletPubKey) {
-      return matchRole(extractRawPubKey(context.walletPubKey));
-    }
-    return void 0;
-  }
-  if (context.walletPubKey) {
-    return matchRole(extractRawPubKey(context.walletPubKey));
-  }
-  return void 0;
+  if (!context.walletDescriptor) return void 0;
+  return matchRole(extractRawPubKey(context.walletDescriptor));
 }
 function extractPubKeyBytes(value) {
   return hex.decode(extractPubKey(normalizeToDescriptor(value)));
@@ -325,6 +283,135 @@ function assertVhtlcSpendableNow(contract, context) {
     `vhtlc ${contract.script} cannot be spent yet: its refund path opens at ${matures}, now ${now}. Until then the lockup is the receiver's to claim, and the server rejects a spend of it. Retry after ${matures}, or wait for the receiver to claim it with the preimage.`
   );
 }
+function selectVhtlcPath(script, contract, context) {
+  const role = resolveRole(contract, context);
+  const preimage = contract.params?.preimage;
+  const refundLocktime = BigInt(contract.params.refundLocktime);
+  if (!role) {
+    return null;
+  }
+  if (context.collaborative) {
+    if (role === "receiver" && preimage) {
+      return {
+        leaf: script.claim(),
+        extraWitness: [hex.decode(preimage)]
+      };
+    }
+    if (role === "sender" && isCltvSatisfied(context, refundLocktime)) {
+      return {
+        leaf: script.refundWithoutReceiver()
+      };
+    }
+    return null;
+  }
+  if (role === "receiver" && preimage) {
+    const sequence = Number(contract.params.claimDelay);
+    if (!isCsvSpendable(context, sequence)) return null;
+    return {
+      leaf: script.unilateralClaim(),
+      extraWitness: [hex.decode(preimage)],
+      sequence
+    };
+  }
+  if (role === "sender") {
+    const sequence = Number(contract.params.refundNoReceiverDelay);
+    if (!isCsvSpendable(context, sequence)) return null;
+    return {
+      leaf: script.unilateralRefundWithoutReceiver(),
+      sequence
+    };
+  }
+  return null;
+}
+function vhtlcAllSpendingPaths(script, contract, context) {
+  const role = resolveRole(contract, context);
+  const paths = [];
+  if (!role) {
+    return paths;
+  }
+  const preimage = contract.params?.preimage;
+  if (context.collaborative) {
+    if (role === "receiver" && preimage) {
+      paths.push({
+        leaf: script.claim(),
+        extraWitness: [hex.decode(preimage)]
+      });
+    }
+    if (role === "sender") {
+      paths.push({
+        leaf: script.refundWithoutReceiver()
+      });
+    }
+  } else {
+    if (role === "receiver" && preimage) {
+      const sequence = Number(contract.params.claimDelay);
+      paths.push({
+        leaf: script.unilateralClaim(),
+        extraWitness: [hex.decode(preimage)],
+        sequence
+      });
+    }
+    if (role === "sender") {
+      const sequence = Number(contract.params.refundNoReceiverDelay);
+      paths.push({
+        leaf: script.unilateralRefundWithoutReceiver(),
+        sequence
+      });
+    }
+  }
+  return paths;
+}
+function vhtlcSpendablePaths(script, contract, context) {
+  const role = resolveRole(contract, context);
+  const paths = [];
+  if (!role) {
+    return paths;
+  }
+  const preimage = contract.params?.preimage;
+  const refundLocktime = BigInt(contract.params.refundLocktime);
+  if (context.collaborative) {
+    if (role === "receiver" && preimage) {
+      paths.push({
+        leaf: script.claim(),
+        extraWitness: [hex.decode(preimage)]
+      });
+    }
+    if (role === "sender" && isCltvSatisfied(context, refundLocktime)) {
+      paths.push({
+        leaf: script.refundWithoutReceiver()
+      });
+    }
+    return paths;
+  }
+  if (role === "receiver" && preimage) {
+    const sequence = Number(contract.params.claimDelay);
+    if (isCsvSpendable(context, sequence)) {
+      paths.push({
+        leaf: script.unilateralClaim(),
+        extraWitness: [hex.decode(preimage)],
+        sequence
+      });
+    }
+  }
+  if (role === "sender") {
+    const sequence = Number(contract.params.refundNoReceiverDelay);
+    if (isCsvSpendable(context, sequence)) {
+      paths.push({
+        leaf: script.unilateralRefundWithoutReceiver(),
+        sequence
+      });
+    }
+  }
+  return paths;
+}
+function deriveVhtlcTapscripts(script) {
+  const leaf = script.refundWithoutReceiver();
+  return {
+    forfeitTapLeafScript: leaf,
+    intentTapLeafScript: leaf,
+    tapTree: script.encode()
+  };
+}
 function isCsvSpendable(context, sequence) {
   if (sequence === void 0) return true;
   if (!context.vtxo) return false;
@@ -493,11 +580,7 @@ function defaultCandidatesAt(_index, descriptor, deps) {
     (opts) => new DefaultVtxo.Script(opts)
   ).map((c) => ({
     type: "default",
-    params: {
-      pubKey: hex.encode(c.pubKey),
-      serverPubKey: hex.encode(c.serverPubKey),
-      csvTimelock: timelockToSequence(c.csvTimelock).toString()
-    },
+    params: DefaultContractHandler.serializeParams(c),
     script: c.scriptHex,
     address: c.script.address(deps.network.hrp, c.serverPubKey).encode()
   }));
@@ -596,12 +679,7 @@ function delegateCandidatesAt(_index, descriptor, deps) {
     (opts) => new DelegateVtxo.Script({ ...opts, delegatePubKey })
   ).map((c) => ({
     type: "delegate",
-    params: {
-      pubKey: hex.encode(c.pubKey),
-      serverPubKey: hex.encode(c.serverPubKey),
-      delegatePubKey: hex.encode(delegatePubKey),
-      csvTimelock: timelockToSequence(c.csvTimelock).toString()
-    },
+    params: DelegateContractHandler.serializeParams({ ...c, delegatePubKey }),
     script: c.scriptHex,
     address: c.script.address(deps.network.hrp, c.serverPubKey).encode()
   }));
@@ -617,515 +695,10 @@ function discoverDelegateRange(entries, deps) {
     (c, index, descriptor) => ({ ...c, ...rotatedReceiveMetadata(index, descriptor) })
   );
 }
-function equalBytes(a, b) {
-  if (a.length !== b.length)
-    return false;
-  for (let i = 0; i < a.length; i++)
-    if (a[i] !== b[i])
-      return false;
-  return true;
-}
-function isBytes(a) {
-  return a instanceof Uint8Array || ArrayBuffer.isView(a) && a.constructor.name === "Uint8Array";
-}
-var createView = (arr) => new DataView(arr.buffer, arr.byteOffset, arr.byteLength);
-function isPlainObject(obj) {
-  return Object.prototype.toString.call(obj) === "[object Object]";
-}
-function isNum(num) {
-  return Number.isSafeInteger(num);
-}
-var Bitset = {
-  BITS: 32,
-  FULL_MASK: -1 >>> 0,
-  // 1<<32 will overflow
-  len: (len) => Math.ceil(len / 32),
-  create: (len) => new Uint32Array(Bitset.len(len)),
-  clean: (bs) => bs.fill(0),
-  debug: (bs) => Array.from(bs).map((i) => (i >>> 0).toString(2).padStart(32, "0")),
-  checkLen: (bs, len) => {
-    if (Bitset.len(len) === bs.length)
-      return;
-    throw new Error(`wrong length=${bs.length}. Expected: ${Bitset.len(len)}`);
-  },
-  chunkLen: (bsLen, pos, len) => {
-    if (pos < 0)
-      throw new Error(`wrong pos=${pos}`);
-    if (pos + len > bsLen)
-      throw new Error(`wrong range=${pos}/${len} of ${bsLen}`);
-  },
-  set: (bs, chunk, value, allowRewrite = true) => {
-    if (!allowRewrite && (bs[chunk] & value) !== 0)
-      return false;
-    bs[chunk] |= value;
-    return true;
-  },
-  pos: (pos, i) => ({
-    chunk: Math.floor((pos + i) / 32),
-    mask: 1 << 32 - (pos + i) % 32 - 1
-  }),
-  indices: (bs, len, invert = false) => {
-    Bitset.checkLen(bs, len);
-    const { FULL_MASK, BITS } = Bitset;
-    const left = BITS - len % BITS;
-    const lastMask = left ? FULL_MASK >>> left << left : FULL_MASK;
-    const res = [];
-    for (let i = 0; i < bs.length; i++) {
-      let c = bs[i];
-      if (invert)
-        c = ~c;
-      if (i === bs.length - 1)
-        c &= lastMask;
-      if (c === 0)
-        continue;
-      for (let j = 0; j < BITS; j++) {
-        const m = 1 << BITS - j - 1;
-        if (c & m)
-          res.push(i * BITS + j);
-      }
-    }
-    return res;
-  },
-  range: (arr) => {
-    const res = [];
-    let cur;
-    for (const i of arr) {
-      if (cur === void 0 || i !== cur.pos + cur.length)
-        res.push(cur = { pos: i, length: 1 });
-      else
-        cur.length += 1;
-    }
-    return res;
-  },
-  rangeDebug: (bs, len, invert = false) => `[${Bitset.range(Bitset.indices(bs, len, invert)).map((i) => `(${i.pos}/${i.length})`).join(", ")}]`,
-  setRange: (bs, bsLen, pos, len, allowRewrite = true) => {
-    Bitset.chunkLen(bsLen, pos, len);
-    const { FULL_MASK, BITS } = Bitset;
-    const first = pos % BITS ? Math.floor(pos / BITS) : void 0;
-    const lastPos = pos + len;
-    const last = lastPos % BITS ? Math.floor(lastPos / BITS) : void 0;
-    if (first !== void 0 && first === last)
-      return Bitset.set(bs, first, FULL_MASK >>> BITS - len << BITS - len - pos, allowRewrite);
-    if (first !== void 0) {
-      if (!Bitset.set(bs, first, FULL_MASK >>> pos % BITS, allowRewrite))
-        return false;
-    }
-    const start = first !== void 0 ? first + 1 : pos / BITS;
-    const end = last !== void 0 ? last : lastPos / BITS;
-    for (let i = start; i < end; i++)
-      if (!Bitset.set(bs, i, FULL_MASK, allowRewrite))
-        return false;
-    if (last !== void 0 && first !== last) {
-      if (!Bitset.set(bs, last, FULL_MASK << BITS - lastPos % BITS, allowRewrite))
-        return false;
-    }
-    return true;
-  }
-};
-var Path = {
-  /**
-   * Internal method for handling stack of paths (debug, errors, dynamic fields via path)
-   * This is looks ugly (callback), but allows us to force stack cleaning by construction (.pop always after function).
-   * Also, this makes impossible:
-   * - pushing field when stack is empty
-   * - pushing field inside of field (real bug)
-   * NOTE: we don't want to do '.pop' on error!
-   */
-  pushObj: (stack, obj, objFn) => {
-    const last = { obj };
-    stack.push(last);
-    objFn((field, fieldFn) => {
-      last.field = field;
-      fieldFn();
-      last.field = void 0;
-    });
-    stack.pop();
-  },
-  path: (stack) => {
-    const res = [];
-    for (const i of stack)
-      if (i.field !== void 0)
-        res.push(i.field);
-    return res.join("/");
-  },
-  err: (name, stack, msg) => {
-    const err = new Error(`${name}(${Path.path(stack)}): ${typeof msg === "string" ? msg : msg.message}`);
-    if (msg instanceof Error && msg.stack)
-      err.stack = msg.stack;
-    return err;
-  },
-  resolve: (stack, path) => {
-    const parts = path.split("/");
-    const objPath = stack.map((i2) => i2.obj);
-    let i = 0;
-    for (; i < parts.length; i++) {
-      if (parts[i] === "..")
-        objPath.pop();
-      else
-        break;
-    }
-    let cur = objPath.pop();
-    for (; i < parts.length; i++) {
-      if (!cur || cur[parts[i]] === void 0)
-        return void 0;
-      cur = cur[parts[i]];
-    }
-    return cur;
-  }
-};
-var _Reader = class __Reader {
-  pos = 0;
-  data;
-  opts;
-  stack;
-  parent;
-  parentOffset;
-  bitBuf = 0;
-  bitPos = 0;
-  bs;
-  // bitset
-  view;
-  constructor(data, opts = {}, stack = [], parent = void 0, parentOffset = 0) {
-    this.data = data;
-    this.opts = opts;
-    this.stack = stack;
-    this.parent = parent;
-    this.parentOffset = parentOffset;
-    this.view = createView(data);
-  }
-  /** Internal method for pointers. */
-  _enablePointers() {
-    if (this.parent)
-      return this.parent._enablePointers();
-    if (this.bs)
-      return;
-    this.bs = Bitset.create(this.data.length);
-    Bitset.setRange(this.bs, this.data.length, 0, this.pos, this.opts.allowMultipleReads);
-  }
-  markBytesBS(pos, len) {
-    if (this.parent)
-      return this.parent.markBytesBS(this.parentOffset + pos, len);
-    if (!len)
-      return true;
-    if (!this.bs)
-      return true;
-    return Bitset.setRange(this.bs, this.data.length, pos, len, false);
-  }
-  markBytes(len) {
-    const pos = this.pos;
-    this.pos += len;
-    const res = this.markBytesBS(pos, len);
-    if (!this.opts.allowMultipleReads && !res)
-      throw this.err(`multiple read pos=${this.pos} len=${len}`);
-    return res;
-  }
-  pushObj(obj, objFn) {
-    return Path.pushObj(this.stack, obj, objFn);
-  }
-  readView(n, fn) {
-    if (!Number.isFinite(n))
-      throw this.err(`readView: wrong length=${n}`);
-    if (this.pos + n > this.data.length)
-      throw this.err("readView: Unexpected end of buffer");
-    const res = fn(this.view, this.pos);
-    this.markBytes(n);
-    return res;
-  }
-  // read bytes by absolute offset
-  absBytes(n) {
-    if (n > this.data.length)
-      throw new Error("Unexpected end of buffer");
-    return this.data.subarray(n);
-  }
-  finish() {
-    if (this.opts.allowUnreadBytes)
-      return;
-    if (this.bitPos) {
-      throw this.err(`${this.bitPos} bits left after unpack: ${hex.encode(this.data.slice(this.pos))}`);
-    }
-    if (this.bs && !this.parent) {
-      const notRead = Bitset.indices(this.bs, this.data.length, true);
-      if (notRead.length) {
-        const formatted = Bitset.range(notRead).map(({ pos, length }) => `(${pos}/${length})[${hex.encode(this.data.subarray(pos, pos + length))}]`).join(", ");
-        throw this.err(`unread byte ranges: ${formatted} (total=${this.data.length})`);
-      } else
-        return;
-    }
-    if (!this.isEnd()) {
-      throw this.err(`${this.leftBytes} bytes ${this.bitPos} bits left after unpack: ${hex.encode(this.data.slice(this.pos))}`);
-    }
-  }
-  // User methods
-  err(msg) {
-    return Path.err("Reader", this.stack, msg);
-  }
-  offsetReader(n) {
-    if (n > this.data.length)
-      throw this.err("offsetReader: Unexpected end of buffer");
-    return new __Reader(this.absBytes(n), this.opts, this.stack, this, n);
-  }
-  bytes(n, peek = false) {
-    if (this.bitPos)
-      throw this.err("readBytes: bitPos not empty");
-    if (!Number.isFinite(n))
-      throw this.err(`readBytes: wrong length=${n}`);
-    if (this.pos + n > this.data.length)
-      throw this.err("readBytes: Unexpected end of buffer");
-    const slice = this.data.subarray(this.pos, this.pos + n);
-    if (!peek)
-      this.markBytes(n);
-    return slice;
-  }
-  byte(peek = false) {
-    if (this.bitPos)
-      throw this.err("readByte: bitPos not empty");
-    if (this.pos + 1 > this.data.length)
-      throw this.err("readBytes: Unexpected end of buffer");
-    const data = this.data[this.pos];
-    if (!peek)
-      this.markBytes(1);
-    return data;
-  }
-  get leftBytes() {
-    return this.data.length - this.pos;
-  }
-  get totalBytes() {
-    return this.data.length;
-  }
-  isEnd() {
-    return this.pos >= this.data.length && !this.bitPos;
-  }
-  // bits are read in BE mode (left to right): (0b1000_0000).readBits(1) == 1
-  bits(bits) {
-    if (bits > 32)
-      throw this.err("BitReader: cannot read more than 32 bits in single call");
-    let out = 0;
-    while (bits) {
-      if (!this.bitPos) {
-        this.bitBuf = this.byte();
-        this.bitPos = 8;
-      }
-      const take = Math.min(bits, this.bitPos);
-      this.bitPos -= take;
-      out = out << take | this.bitBuf >> this.bitPos & 2 ** take - 1;
-      this.bitBuf &= 2 ** this.bitPos - 1;
-      bits -= take;
-    }
-    return out >>> 0;
-  }
-  find(needle, pos = this.pos) {
-    if (!isBytes(needle))
-      throw this.err(`find: needle is not bytes! ${needle}`);
-    if (this.bitPos)
-      throw this.err("findByte: bitPos not empty");
-    if (!needle.length)
-      throw this.err(`find: needle is empty`);
-    for (let idx = pos; (idx = this.data.indexOf(needle[0], idx)) !== -1; idx++) {
-      if (idx === -1)
-        return;
-      const leftBytes = this.data.length - idx;
-      if (leftBytes < needle.length)
-        return;
-      if (equalBytes(needle, this.data.subarray(idx, idx + needle.length)))
-        return idx;
-    }
-    return;
-  }
-};
-var _Writer = class {
-  pos = 0;
-  stack;
-  // We could have a single buffer here and re-alloc it with
-  // x1.5-2 size each time it full, but it will be slower:
-  // basic/encode bench: 395ns -> 560ns
-  buffers = [];
-  ptrs = [];
-  bitBuf = 0;
-  bitPos = 0;
-  viewBuf = new Uint8Array(8);
-  view;
-  finished = false;
-  constructor(stack = []) {
-    this.stack = stack;
-    this.view = createView(this.viewBuf);
-  }
-  pushObj(obj, objFn) {
-    return Path.pushObj(this.stack, obj, objFn);
-  }
-  writeView(len, fn) {
-    if (this.finished)
-      throw this.err("buffer: finished");
-    if (!isNum(len) || len > 8)
-      throw new Error(`wrong writeView length=${len}`);
-    fn(this.view);
-    this.bytes(this.viewBuf.slice(0, len));
-    this.viewBuf.fill(0);
-  }
-  // User methods
-  err(msg) {
-    if (this.finished)
-      throw this.err("buffer: finished");
-    return Path.err("Reader", this.stack, msg);
-  }
-  bytes(b) {
-    if (this.finished)
-      throw this.err("buffer: finished");
-    if (this.bitPos)
-      throw this.err("writeBytes: ends with non-empty bit buffer");
-    this.buffers.push(b);
-    this.pos += b.length;
-  }
-  byte(b) {
-    if (this.finished)
-      throw this.err("buffer: finished");
-    if (this.bitPos)
-      throw this.err("writeByte: ends with non-empty bit buffer");
-    this.buffers.push(new Uint8Array([b]));
-    this.pos++;
-  }
-  finish(clean = true) {
-    if (this.finished)
-      throw this.err("buffer: finished");
-    if (this.bitPos)
-      throw this.err("buffer: ends with non-empty bit buffer");
-    const buffers = this.buffers.concat(this.ptrs.map((i) => i.buffer));
-    const sum = buffers.map((b) => b.length).reduce((a, b) => a + b, 0);
-    const buf = new Uint8Array(sum);
-    for (let i = 0, pad = 0; i < buffers.length; i++) {
-      const a = buffers[i];
-      buf.set(a, pad);
-      pad += a.length;
-    }
-    for (let pos = this.pos, i = 0; i < this.ptrs.length; i++) {
-      const ptr = this.ptrs[i];
-      buf.set(ptr.ptr.encode(pos), ptr.pos);
-      pos += ptr.buffer.length;
-    }
-    if (clean) {
-      this.buffers = [];
-      for (const p of this.ptrs)
-        p.buffer.fill(0);
-      this.ptrs = [];
-      this.finished = true;
-      this.bitBuf = 0;
-    }
-    return buf;
-  }
-  bits(value, bits) {
-    if (bits > 32)
-      throw this.err("writeBits: cannot write more than 32 bits in single call");
-    if (value >= 2 ** bits)
-      throw this.err(`writeBits: value (${value}) >= 2**bits (${bits})`);
-    while (bits) {
-      const take = Math.min(bits, 8 - this.bitPos);
-      this.bitBuf = this.bitBuf << take | value >> bits - take;
-      this.bitPos += take;
-      bits -= take;
-      value &= 2 ** bits - 1;
-      if (this.bitPos === 8) {
-        this.bitPos = 0;
-        this.buffers.push(new Uint8Array([this.bitBuf]));
-        this.pos++;
-      }
-    }
-  }
-};
-function _wrap(inner) {
-  return {
-    // NOTE: we cannot export validate here, since it is likely mistake.
-    encodeStream: inner.encodeStream,
-    decodeStream: inner.decodeStream,
-    size: inner.size,
-    encode: (value) => {
-      const w = new _Writer();
-      inner.encodeStream(w, value);
-      return w.finish();
-    },
-    decode: (data, opts = {}) => {
-      const r = new _Reader(data, opts);
-      const res = inner.decodeStream(r);
-      r.finish();
-      return res;
-    }
-  };
-}
-function validate(inner, fn) {
-  if (!isCoder(inner))
-    throw new Error(`validate: invalid inner value ${inner}`);
-  if (typeof fn !== "function")
-    throw new Error("validate: fn should be function");
-  return _wrap({
-    size: inner.size,
-    encodeStream: (w, value) => {
-      let res;
-      try {
-        res = fn(value);
-      } catch (e) {
-        throw w.err(e);
-      }
-      inner.encodeStream(w, res);
-    },
-    decodeStream: (r) => {
-      const res = inner.decodeStream(r);
-      try {
-        return fn(res);
-      } catch (e) {
-        throw r.err(e);
-      }
-    }
-  });
-}
-var wrap = (inner) => {
-  const res = _wrap(inner);
-  return inner.validate ? validate(res, inner.validate) : res;
-};
-var isBaseCoder = (elm) => isPlainObject(elm) && typeof elm.decode === "function" && typeof elm.encode === "function";
-function isCoder(elm) {
-  return isPlainObject(elm) && isBaseCoder(elm) && typeof elm.encodeStream === "function" && typeof elm.decodeStream === "function" && (elm.size === void 0 || isNum(elm.size));
-}
-var view = (len, opts) => wrap({
-  size: len,
-  encodeStream: (w, value) => w.writeView(len, (view2) => opts.write(view2, value)),
-  decodeStream: (r) => r.readView(len, opts.read),
-  validate: (value) => {
-    if (typeof value !== "number")
-      throw new Error(`viewCoder: expected number, got ${typeof value}`);
-    if (opts.validate)
-      opts.validate(value);
-    return value;
-  }
-});
-var intView = (len, signed, opts) => {
-  const bits = len * 8;
-  const maxVal = 2 ** bits;
-  const validateUnsigned = (value) => {
-    if (!isNum(value))
-      throw new Error(`uintView: value is not safe integer: ${value}`);
-    if (0 > value || value >= maxVal) {
-      throw new Error(`uintView: value out of bounds. Expected 0 <= ${value} < ${maxVal}`);
-    }
-  };
-  return view(len, {
-    write: opts.write,
-    read: opts.read,
-    validate: validateUnsigned
-  });
-};
-var U32LE = /* @__PURE__ */ intView(4, false, {
-  read: (view2, pos) => view2.getUint32(pos, true),
-  write: (view2, value) => view2.setUint32(0, value, true)
-});
-var U16LE = /* @__PURE__ */ intView(2, false, {
-  read: (view2, pos) => view2.getUint16(pos, true),
-  write: (view2, value) => view2.setUint16(0, value, true)
-});
-var U8 = /* @__PURE__ */ intView(1, false, {
-  read: (view2, pos) => view2.getUint8(pos),
-  write: (view2, value) => view2.setUint8(0, value)
-});
 var ARKADE_OP = {
   // Merkle Branch Verification (0xb3 — repurposed NOP4 slot)
   MERKLEBRANCHVERIFY: 179,
+  PUT: 187,
   // Digest (0xc3)
   DIGEST: 195,
   // SHA256 Streaming (0xc4-0xc6)
@@ -1157,7 +730,10 @@ var ARKADE_OP = {
   BIN2NUM: 216,
   REVERSEBYTES: 217,
   MODEXP: 218,
-  // 0xdb-0xdf are unassigned (OP_UNKNOWN219-223)
+  // VTXO Expiry & Emulator Clock (0xdb-0xdc)
+  PUSHEXPIRY: 219,
+  CHECKTIME: 220,
+  // 0xdd-0xdf are unassigned (OP_UNKNOWN221-223)
   // EC Operations (0xe0-0xe2)
   ECADD: 224,
   ECMUL: 225,
@@ -1186,7 +762,10 @@ var ARKADE_OP = {
   INSPECTPACKET: 244,
   INSPECTINPUTPACKET: 245,
   // Signature Hash (0xf6)
-  SIGHASH: 246
+  SIGHASH: 246,
+  // Continuation & Intent Introspection (0xf7-0xf8)
+  TUNNEL: 247,
+  INSPECTINTENTMESSAGE: 248
 };
 var ARKADE_OPCODES = Object.values(ARKADE_OP);
 var ARKADE_OPCODE_NAMES = Object.fromEntries(
@@ -1282,7 +861,7 @@ var ArkadeOPNames = {};
 for (const [k, v] of Object.entries(ARKADE_OPS)) {
   if (typeof v === "number") ArkadeOPNames[v] = k;
 }
-var ArkadeScript = wrap({
+var ArkadeScript = P.wrap({
   encodeStream: (w, value) => {
     for (let o of value) {
       if (typeof o === "string") {
@@ -1308,10 +887,10 @@ var ArkadeScript = wrap({
         w.byte(len);
       } else if (len <= 65535) {
         w.byte(OP.PUSHDATA2);
-        w.bytes(U16LE.encode(len));
+        w.bytes(P.U16LE.encode(len));
       } else {
         w.byte(OP.PUSHDATA4);
-        w.bytes(U32LE.encode(len));
+        w.bytes(P.U32LE.encode(len));
       }
       w.bytes(o);
     }
@@ -1323,9 +902,9 @@ var ArkadeScript = wrap({
       if (OP.OP_0 < cur && cur <= OP.PUSHDATA4) {
         let len;
         if (cur < OP.PUSHDATA1) len = cur;
-        else if (cur === OP.PUSHDATA1) len = U8.decodeStream(r);
-        else if (cur === OP.PUSHDATA2) len = U16LE.decodeStream(r);
-        else if (cur === OP.PUSHDATA4) len = U32LE.decodeStream(r);
+        else if (cur === OP.PUSHDATA1) len = P.U8.decodeStream(r);
+        else if (cur === OP.PUSHDATA2) len = P.U16LE.decodeStream(r);
+        else if (cur === OP.PUSHDATA4) len = P.U32LE.decodeStream(r);
         else throw new Error("Should be not possible");
         out.push(r.bytes(len));
       } else if (cur === 0) {
@@ -1607,54 +1186,19 @@ var VHTLC;
     /**
      * Return the timelocked non-interactive refund tapleaf and its ArkadeScript.
      *
-     * SPENDING THIS LEAF, CONCRETELY — confirmed from this SDK's own
-     * emulator client and covenant-spend builder ({@link
-     * EmulatorProvider} in `src/providers/emulator.ts`, and {@link
-     * ArkadeTransactionBuilder} in `src/arkade/contract.ts`), which is
-     * the general machinery every covenant leaf in this file goes
-     * through:
-     *
-     *  1. Build the ark tx spending this leaf (this method's {@link
-     *     TapLeafScript} as `tapLeafScript`, this script's {@link
-     *     VtxoScript.encode} as `tapTree`), plus its checkpoint tx.
-     *  2. Attach the ArkadeScript this method returns to the spent
-     *     input via an `EmulatorPacket` (type 1) — `{ vin, script:
-     *     <this ArkadeScript>, witness: <empty> }`, empty because the
-     *     script pushes its own input/output index with
-     *     `PUSHCURRENTINPUTINDEX` rather than reading one from the
-     *     witness — wrapped in an `Extension` OP_RETURN output on the
-     *     ark tx.
-     *  3. Attach the spent input's OWN creating ark tx as `PrevArkTx` on
-     *     input 0 — required so the emulator can resolve that input's
-     *     prevout pkScript/value; it does not otherwise have them.
-     *  4. POST the (base64-PSBT) ark tx and checkpoint(s) as `{ arkTx,
-     *     checkpointTxs }` to the emulator's `POST /v1/tx`.
+     * Spent through the generic covenant path ({@link EmulatorProvider},
+     * {@link ArkadeTransactionBuilder}): build the ark tx on this leaf plus its checkpoint;
+     * attach this ArkadeScript to the input in an `EmulatorPacket` (type 1, empty witness:
+     * the script pushes its own index with `PUSHCURRENTINPUTINDEX`) inside an `Extension`
+     * OP_RETURN; attach the input's creating ark tx as `PrevArkTx` (the emulator can't
+     * otherwise resolve its prevout); POST to the emulator's `/v1/tx`. The emulator co-signs
+     * for `nirCosigner` only if `enforcePayTo(senderPkScript)` holds, and finalizes with arkd.
+     * `server`'s signature is still required at consensus level, outside the covenant.
      *
-     * THE COVENANT CHECK the emulator runs against that ArkadeScript —
-     * `enforcePayTo(senderPkScript)`, see that function above — is: the
-     * output at this SAME input's index is a v1 P2TR output paying
-     * `senderPkScript`, with a value at least the input's. Only on that
-     * check passing does the emulator sign for `nirCosigner` (the
-     * `emulatorPubkey` tweaked by this ArkadeScript's hash); the
-     * response carries the fully co-signed `signedArkTx` and
-     * `signedCheckpointTxs` — `ArkadeTransactionBuilder.send()`'s own
-     * comment on this path: "the emulator executes the arkade script
-     * and finalizes with arkd" — no separate call to arkd is made by
-     * this SDK for a covenant spend.
-     * Neither `server` nor `receiver` play any part in that check: this
-     * leaf's tapscript still requires `server`'s own signature
-     * alongside `nirCosigner`'s (see the class doc above), but that is
-     * consensus-level multisig, not something the covenant enforces.
-     *
-     * NOT SPENDABLE UNTIL `refundLocktime` MATURES — the tapscript's
-     * `OP_CHECKLOCKTIMEVERIFY` is arkd's concern, not the emulator's;
-     * the emulator will happily co-sign an immature spend and arkd will
-     * then refuse it. A block-height-typed `refundLocktime` (below the
-     * standard height/timestamp boundary this SDK names
-     * `CLTV_HEIGHT_THRESHOLD`, 500,000,000, in
-     * `src/contracts/handlers/helpers.ts`) is refused by arkd for a
-     * forfeit-eligible leaf independent of maturity — use a
-     * seconds-typed (absolute Unix timestamp) value.
+     * The emulator does not check `refundLocktime`: it co-signs an immature spend and arkd's
+     * CLTV refuses it. arkd also refuses a block-height `refundLocktime`
+     * (< `CLTV_HEIGHT_THRESHOLD`, 500,000,000) on a forfeit-eligible leaf regardless of
+     * maturity: use a seconds-typed (Unix timestamp) value.
      */
     nonInteractiveRefundWithoutReceiver() {
       if (!this.nonInteractiveRefundWithoutReceiverScript || !this.nonInteractiveRefundWithoutReceiverArkadeScript) {
@@ -1797,10 +1341,7 @@ function enforcePayToAsset(destinationPkScript, asset) {
   }
   const inspectionTxid = Uint8Array.from(asset.txid).reverse();
   return ArkadeScript.encode([
-    // The output carries at least as much of the asset as the input did.
-    // Output index is the input's -- the same index alignment the sat
-    // covenant relies on, and the same liveness obligation on whoever
-    // assembles the spend.
+    // The output at the input's index carries at least the input's amount of the asset.
     "PUSHCURRENTINPUTINDEX",
     inspectionTxid,
     asset.groupIndex,
@@ -1864,139 +1405,18 @@ var VHTLCContractHandler = {
     };
   },
   /**
-   * Select spending path based on context.
-   *
-   * Role is determined from `context.role` or by matching
-   * `context.walletDescriptor` (preferred) / `context.walletPubKey`
-   * against sender/receiver in contract params.
+   * Select spending path based on context. Role comes from `context.role` or from matching
+   * `context.walletDescriptor` against sender/receiver.
    */
   selectPath(script, contract, context) {
-    const role = resolveRole(contract, context);
-    const preimage = contract.params?.preimage;
-    const refundLocktime = BigInt(contract.params.refundLocktime);
-    if (!role) {
-      return null;
-    }
-    if (context.collaborative) {
-      if (role === "receiver" && preimage) {
-        return {
-          leaf: script.claim(),
-          extraWitness: [hex.decode(preimage)]
-        };
-      }
-      if (role === "sender" && isCltvSatisfied(context, refundLocktime)) {
-        return {
-          leaf: script.refundWithoutReceiver()
-        };
-      }
-      return null;
-    }
-    if (role === "receiver" && preimage) {
-      const sequence = Number(contract.params.claimDelay);
-      if (!isCsvSpendable(context, sequence)) return null;
-      return {
-        leaf: script.unilateralClaim(),
-        extraWitness: [hex.decode(preimage)],
-        sequence
-      };
-    }
-    if (role === "sender") {
-      const sequence = Number(contract.params.refundNoReceiverDelay);
-      if (!isCsvSpendable(context, sequence)) return null;
-      return {
-        leaf: script.unilateralRefundWithoutReceiver(),
-        sequence
-      };
-    }
-    return null;
+    return selectVhtlcPath(script, contract, context);
   },
-  /**
-   * Get all possible spending paths (no timelock checks).
-   *
-   * Role is determined from `context.role` or by matching
-   * `context.walletDescriptor` (preferred) / `context.walletPubKey`
-   * against sender/receiver in contract params.
-   */
+  /** All possible spending paths (no timelock checks); role as in {@link selectPath}. */
   getAllSpendingPaths(script, contract, context) {
-    const role = resolveRole(contract, context);
-    const paths = [];
-    if (!role) {
-      return paths;
-    }
-    const preimage = contract.params?.preimage;
-    if (context.collaborative) {
-      if (role === "receiver" && preimage) {
-        paths.push({
-          leaf: script.claim(),
-          extraWitness: [hex.decode(preimage)]
-        });
-      }
-      if (role === "sender") {
-        paths.push({
-          leaf: script.refundWithoutReceiver()
-        });
-      }
-    } else {
-      if (role === "receiver" && preimage) {
-        const sequence = Number(contract.params.claimDelay);
-        paths.push({
-          leaf: script.unilateralClaim(),
-          extraWitness: [hex.decode(preimage)],
-          sequence
-        });
-      }
-      if (role === "sender") {
-        const sequence = Number(contract.params.refundNoReceiverDelay);
-        paths.push({
-          leaf: script.unilateralRefundWithoutReceiver(),
-          sequence
-        });
-      }
-    }
-    return paths;
+    return vhtlcAllSpendingPaths(script, contract, context);
   },
   getSpendablePaths(script, contract, context) {
-    const role = resolveRole(contract, context);
-    const paths = [];
-    if (!role) {
-      return paths;
-    }
-    const preimage = contract.params?.preimage;
-    const refundLocktime = BigInt(contract.params.refundLocktime);
-    if (context.collaborative) {
-      if (role === "receiver" && preimage) {
-        paths.push({
-          leaf: script.claim(),
-          extraWitness: [hex.decode(preimage)]
-        });
-      }
-      if (role === "sender" && isCltvSatisfied(context, refundLocktime)) {
-        paths.push({
-          leaf: script.refundWithoutReceiver()
-        });
-      }
-      return paths;
-    }
-    if (role === "receiver" && preimage) {
-      const sequence = Number(contract.params.claimDelay);
-      if (isCsvSpendable(context, sequence)) {
-        paths.push({
-          leaf: script.unilateralClaim(),
-          extraWitness: [hex.decode(preimage)],
-          sequence
-        });
-      }
-    }
-    if (role === "sender") {
-      const sequence = Number(contract.params.refundNoReceiverDelay);
-      if (isCsvSpendable(context, sequence)) {
-        paths.push({
-          leaf: script.unilateralRefundWithoutReceiver(),
-          sequence
-        });
-      }
-    }
-    return paths;
+    return vhtlcSpendablePaths(script, contract, context);
   },
   /**
    * Refuse an explicit spend of a lockup whose refund path has not opened.
@@ -2007,70 +1427,38 @@ var VHTLCContractHandler = {
     assertVhtlcSpendableNow(contract, context);
   },
   /**
-   * Never. A live VHTLC is escrow: the counterparty's claim leaf is armed,
-   * and generic selection — send, settle, renewal, offboard — would move the
-   * lockup out from under a swap the counterparty is still entitled to
-   * complete, or race a claim already in flight.
-   *
-   * Two narrow reasons, and neither is "spending this would destroy the
-   * VTXO". It would not: the leaf {@link deriveTapscripts} stamps is
-   * `refundWithoutReceiver` — `CLTV[sender, server]`, the sender's OWN
-   * refund, which the server rejects until `refundLocktime` matures. The
-   * reasons are that an escrowed lockup must not count toward the
-   * `available` balance bucket, and that generic RENEWAL must not silently
-   * execute a refund the caller never asked for — `runPeriodicSettle` selects
-   * through `getSpendableVtxos`, which this gate filters, and it runs
-   * unprompted whenever a wallet is built without an explicit
-   * `settlementConfig`.
+   * Never. A live VHTLC is escrow: generic selection (send, settle, renewal, offboard) would
+   * move the lockup out from under a swap the counterparty may still complete, or race a claim.
    *
-   * **Inseparable from {@link deriveTapscripts}.** Deriving the leaf without
-   * closing the gate hands generic renewal an escrow it had never been
-   * offered before; before that method existed the answer here was
-   * unobservable, so the two only ever made sense together.
+   * The stamped leaf is the sender's own CLTV refund, so this is not about destroying the
+   * VTXO: an escrowed lockup must not count toward the `available` balance, and generic
+   * renewal (`runPeriodicSettle`, unprompted without an explicit `settlementConfig`) must not
+   * silently execute a refund nobody asked for.
    *
-   * Recovery is filtered on {@link assertSpendableNow}, not on this: the gate
-   * is permanent, and applying it there would strand a matured lockup.
+   * **Inseparable from {@link deriveTapscripts}**: deriving the leaf without closing this gate
+   * hands renewal an escrow. Recovery filters on {@link assertSpendableNow} instead; this
+   * permanent gate would strand a matured lockup.
    */
   isGenericallySpendable: () => false,
   /**
    * The annotation leaf stamped onto every VTXO locked to this contract.
    *
-   * **Without this the contract is unusable, not merely unoptimized.**
-   * `deriveContractTapscripts` falls back to `script.forfeit()` for any
-   * handler that does not implement {@link TapscriptDeriving}, and no VHTLC
-   * script version has a `forfeit()` — `VtxoScript` does not define one and
-   * `VHTLC.BaseScript` does not add one. The fallback therefore threw
-   * `legacy.forfeit is not a function`, `annotatableIn` caught it, and
-   * `fetchContractVtxosBulk` dropped this contract's VTXOs before they were
-   * persisted. The row existed and was watched while its balance stayed
-   * permanently invisible, and `getSyncState()` reported `degraded` forever.
+   * **Required, not an optimization.** Without it `deriveContractTapscripts` falls back to
+   * `script.forfeit()`, which no VHTLC script has, so the contract's VTXOs are dropped before
+   * persisting: balance invisible, `getSyncState()` degraded forever.
    *
-   * `refundWithoutReceiver` is the leaf, for both roles the annotation
-   * serves, because it is the only collaborative path this wallet can
-   * actually satisfy as the sender — the same conclusion `selectPath`
-   * reaches, kept in step with it deliberately. The claim leaves belong to
-   * the receiver and need a preimage the sender does not have; `refund` and
-   * `unilateralRefund` both need the counterparty's signature, which this
-   * protocol has no message to ask for. V1 has no covenant leaves at all.
+   * `refundWithoutReceiver` is the only collaborative path this wallet can satisfy as sender
+   * (kept in step with `selectPath`): the claim leaves need the preimage, and `refund` /
+   * `unilateralRefund` need a counterparty signature the protocol can't request. V1 has no
+   * covenant leaves.
    *
-   * **It carries a CLTV, and callers must respect it.** A settlement built
-   * on this leaf is only valid once `refundLocktime` has matured, so a
-   * recovery round that sweeps this VTXO early is rejected by the server.
-   * Nothing in this handler can enforce that, because the annotation is
-   * derived per contract and knows no clock; `recoverVtxos` filters on
-   * {@link assertSpendableNow} for it.
-   *
-   * **Role-blind.** A receiver's row gets the same leaf, which names keys that
-   * wallet does not hold, so it is satisfiable only by the wallet holding the
-   * lockup's `sender` key and fails at intent registration for anyone else.
+   * **It carries a CLTV**: a settlement on it is rejected until `refundLocktime` matures, and
+   * the per-contract annotation knows no clock, so `recoverVtxos` filters on
+   * {@link assertSpendableNow}. **Role-blind**: a receiver's row gets the same leaf, satisfiable
+   * only by the `sender` key holder; anyone else fails at intent registration.
    */
   deriveTapscripts(script) {
-    const leaf = script.refundWithoutReceiver();
-    return {
-      forfeitTapLeafScript: leaf,
-      intentTapLeafScript: leaf,
-      tapTree: script.encode()
-    };
+    return deriveVhtlcTapscripts(script);
   }
 };
 var parseGroupIndex = (raw) => {
@@ -2109,43 +1497,21 @@ var VHTLCV2ContractHandler = {
       refundNoReceiverDelay: timelockToSequence(
         params.unilateralRefundWithoutReceiverDelay
       ).toString(),
-      // The on-disk keys keep their per-leaf names even though the typed
-      // param is ONE group: rows written by older SDKs carry exactly
-      // these keys, and changing the storage encoding would orphan them.
-      // The group maps onto them without loss — one emulator key serves
-      // both covenant destinations by construction (see the option's doc
-      // on VHTLC.Options), so the two emulator-key columns always hold
-      // the same value on a row written from here.
-      //
-      // Spread rather than written as `undefined`: a `Record<string,
-      // string>` round-tripped through a repository must not gain keys
-      // whose value is the string "undefined".
+      // Per-leaf on-disk keys predate the grouped param and older rows carry exactly these;
+      // both emulator columns hold the same key. Spread, not `undefined`, so a repository
+      // round-trip never gains "undefined" string values.
       ...covenants && {
         nonInteractiveClaimReceiverPkScript: hex.encode(covenants.receiverPkScript),
         nonInteractiveClaimEmulatorPubkey: hex.encode(covenants.emulatorPubkey),
         nonInteractiveRefundSenderPkScript: hex.encode(covenants.senderPkScript),
         nonInteractiveRefundEmulatorPubkey: hex.encode(covenants.emulatorPubkey),
-        // The legacy marker is precisely the ABSENCE of this key: a
-        // row carrying it re-derives the full suite (nine leaves), a
-        // row lacking it the pre-timelocked-refund eight — the same
-        // encoding older SDKs wrote for eight-leaf rows, so those rows
-        // read back unchanged. Spread rather than a "false"/"undefined"
-        // string: a dropped flag re-derives the EIGHT-leaf script, a
-        // different pkScript, and registration dies at
-        // `upsertContractRow` with an opaque `Script mismatch`.
+        // The legacy (eight-leaf) marker is this key's ABSENCE, as older SDKs wrote it.
         ...covenants.legacy === void 0 && {
           nonInteractiveRefundWithoutReceiver: "1"
         }
       },
-      // The asset must round-trip, and its absence here used to be silent
-      // in the worst way. `ContractManager` re-derives a contract from
-      // these params; dropping the asset derives the SAT-ONLY script, so
-      // registration died at `upsertContractRow` with a `Script mismatch`
-      // naming two hex strings and no cause. Same silent-drop class
-      // `validateOptions` refuses one layer up.
-      //
-      // Two keys rather than one blob, mirroring the script's own view of
-      // an Asset ID as a (txid, groupIndex) pair.
+      // Must round-trip: dropping the asset re-derives the sat-only script and registration
+      // dies at `upsertContractRow` with an opaque `Script mismatch`.
       ...params.asset && {
         assetTxid: hex.encode(params.asset.txid),
         assetGroupIndex: params.asset.groupIndex.toString()
@@ -2216,8 +1582,6 @@ var VHTLCV2ContractHandler = {
           receiverPkScript: claim.destination,
           senderPkScript: refund.destination,
           emulatorPubkey: claim.emulatorPubkey,
-          // Absence of the flag IS the legacy marker — the same
-          // encoding older SDKs wrote for eight-leaf rows.
           ...params.nonInteractiveRefundWithoutReceiver !== "1" && {
             legacy: "preTimelockedRefund"
           }
@@ -2226,139 +1590,18 @@ var VHTLCV2ContractHandler = {
     };
   },
   /**
-   * Select spending path based on context.
-   *
-   * Role is determined from `context.role` or by matching
-   * `context.walletDescriptor` (preferred) / `context.walletPubKey`
-   * against sender/receiver in contract params.
+   * Select spending path based on context. Role comes from `context.role` or by matching
+   * `context.walletDescriptor` against sender/receiver.
    */
   selectPath(script, contract, context) {
-    const role = resolveRole(contract, context);
-    const preimage = contract.params?.preimage;
-    const refundLocktime = BigInt(contract.params.refundLocktime);
-    if (!role) {
-      return null;
-    }
-    if (context.collaborative) {
-      if (role === "receiver" && preimage) {
-        return {
-          leaf: script.claim(),
-          extraWitness: [hex.decode(preimage)]
-        };
-      }
-      if (role === "sender" && isCltvSatisfied(context, refundLocktime)) {
-        return {
-          leaf: script.refundWithoutReceiver()
-        };
-      }
-      return null;
-    }
-    if (role === "receiver" && preimage) {
-      const sequence = Number(contract.params.claimDelay);
-      if (!isCsvSpendable(context, sequence)) return null;
-      return {
-        leaf: script.unilateralClaim(),
-        extraWitness: [hex.decode(preimage)],
-        sequence
-      };
-    }
-    if (role === "sender") {
-      const sequence = Number(contract.params.refundNoReceiverDelay);
-      if (!isCsvSpendable(context, sequence)) return null;
-      return {
-        leaf: script.unilateralRefundWithoutReceiver(),
-        sequence
-      };
-    }
-    return null;
+    return selectVhtlcPath(script, contract, context);
   },
-  /**
-   * Get all possible spending paths (no timelock checks).
-   *
-   * Role is determined from `context.role` or by matching
-   * `context.walletDescriptor` (preferred) / `context.walletPubKey`
-   * against sender/receiver in contract params.
-   */
+  /** Get all possible spending paths (no timelock checks); role resolved as in `selectPath`. */
   getAllSpendingPaths(script, contract, context) {
-    const role = resolveRole(contract, context);
-    const paths = [];
-    if (!role) {
-      return paths;
-    }
-    const preimage = contract.params?.preimage;
-    if (context.collaborative) {
-      if (role === "receiver" && preimage) {
-        paths.push({
-          leaf: script.claim(),
-          extraWitness: [hex.decode(preimage)]
-        });
-      }
-      if (role === "sender") {
-        paths.push({
-          leaf: script.refundWithoutReceiver()
-        });
-      }
-    } else {
-      if (role === "receiver" && preimage) {
-        const sequence = Number(contract.params.claimDelay);
-        paths.push({
-          leaf: script.unilateralClaim(),
-          extraWitness: [hex.decode(preimage)],
-          sequence
-        });
-      }
-      if (role === "sender") {
-        const sequence = Number(contract.params.refundNoReceiverDelay);
-        paths.push({
-          leaf: script.unilateralRefundWithoutReceiver(),
-          sequence
-        });
-      }
-    }
-    return paths;
+    return vhtlcAllSpendingPaths(script, contract, context);
   },
   getSpendablePaths(script, contract, context) {
-    const role = resolveRole(contract, context);
-    const paths = [];
-    if (!role) {
-      return paths;
-    }
-    const preimage = contract.params?.preimage;
-    const refundLocktime = BigInt(contract.params.refundLocktime);
-    if (context.collaborative) {
-      if (role === "receiver" && preimage) {
-        paths.push({
-          leaf: script.claim(),
-          extraWitness: [hex.decode(preimage)]
-        });
-      }
-      if (role === "sender" && isCltvSatisfied(context, refundLocktime)) {
-        paths.push({
-          leaf: script.refundWithoutReceiver()
-        });
-      }
-      return paths;
-    }
-    if (role === "receiver" && preimage) {
-      const sequence = Number(contract.params.claimDelay);
-      if (isCsvSpendable(context, sequence)) {
-        paths.push({
-          leaf: script.unilateralClaim(),
-          extraWitness: [hex.decode(preimage)],
-          sequence
-        });
-      }
-    }
-    if (role === "sender") {
-      const sequence = Number(contract.params.refundNoReceiverDelay);
-      if (isCsvSpendable(context, sequence)) {
-        paths.push({
-          leaf: script.unilateralRefundWithoutReceiver(),
-          sequence
-        });
-      }
-    }
-    return paths;
+    return vhtlcSpendablePaths(script, contract, context);
   },
   /**
    * Refuse an explicit spend of a lockup whose refund path has not opened.
@@ -2368,62 +1611,28 @@ var VHTLCV2ContractHandler = {
     assertVhtlcSpendableNow(contract, context);
   },
   /**
-   * Never. A live VHTLC is escrow: the counterparty's claim leaf is armed,
-   * and generic selection — send, settle, RENEWAL, offboard — would move the
-   * lockup out from under a swap the counterparty is still entitled to
-   * complete, or race a claim already in flight. The `vhtlc` handler now
-   * answers the same, for the same reason.
-   *
-   * The gate covers `available` and renewal. Recovery is generic and names
-   * nothing, so it is not covered here: `recoverVtxos` filters on
-   * {@link assertSpendableNow} instead, which drops a lockup only while its
-   * refund path is shut rather than forever. The explicit routes out —
-   * `settle({ inputs })`, or `@arkade-os/swap`'s `pushRefundWithoutReceiver`
-   * over `findLockupVtxos`' outpoints — are unaffected either way.
+   * Never. A live VHTLC is escrow with the counterparty's claim leaf armed; generic selection
+   * (send, settle, renewal, offboard) would move it out from under the swap or race a claim.
+   * Recovery isn't covered by this gate: `recoverVtxos` filters on {@link assertSpendableNow},
+   * dropping a lockup only while its refund path is shut. Explicit routes (`settle({ inputs })`,
+   * `pushRefundWithoutReceiver`) are unaffected.
    */
   isGenericallySpendable: () => false,
   /**
    * The annotation leaf stamped onto every VTXO locked to this contract.
    *
-   * **Without this the contract is unusable, not merely unoptimized.**
-   * `deriveContractTapscripts` falls back to `script.forfeit()` for any
-   * handler that does not implement {@link TapscriptDeriving}, and no VHTLC
-   * script version has a `forfeit()` — `VtxoScript` does not define one and
-   * `VHTLC.BaseScript` does not add one. The fallback therefore throws
-   * `legacy.forfeit is not a function`, `annotatableIn` catches it, and
-   * `fetchContractVtxosBulk` drops this contract's VTXOs before they are
-   * persisted. The row would exist and be watched while its balance stayed
-   * permanently invisible, and `getSyncState()` would report `degraded`
-   * forever. (The `vhtlc` handler had the same gap and now closes it the same
-   * way; nothing registers V1 rows through `ContractManager` in this repo, so
-   * it was never hit here.)
+   * Required, not an optimization: without {@link TapscriptDeriving} the fallback calls
+   * `script.forfeit()`, which no VHTLC version has, so the VTXOs are silently dropped before
+   * persisting and `getSyncState()` stays `degraded`.
    *
-   * `refundWithoutReceiver` is the leaf, for both roles the annotation
-   * serves, because it is the only collaborative path this wallet can
-   * actually satisfy as the sender — the same conclusion `selectPath`
-   * reaches, kept in step with it deliberately. The claim leaves belong to
-   * the receiver and need a preimage the sender does not have; `refund` and
-   * `unilateralRefund` need the counterparty; the covenant leaves are the
-   * emulator's.
-   *
-   * **It carries a CLTV, and callers must respect it.** A settlement built on
-   * this leaf is only valid once `refundLocktime` has matured, so a recovery
-   * round that sweeps this VTXO early is rejected by the server. Nothing in
-   * this handler can enforce it, because the annotation is derived per
-   * contract and knows no clock. `recoverVtxos` filters on
-   * {@link assertSpendableNow} for it.
-   *
-   * **Role-blind.** A receiver's row gets the same leaf, which names keys that
-   * wallet does not hold, so it is satisfiable only by the wallet holding the
-   * lockup's `sender` key and fails at intent registration for anyone else.
+   * `refundWithoutReceiver` is used (in step with `selectPath`) as the only collaborative leaf
+   * the sender can satisfy. It carries a CLTV: settling on it before `refundLocktime` matures is
+   * rejected, and this handler has no clock, so `recoverVtxos` filters on
+   * {@link assertSpendableNow}. Role-blind: a receiver's row gets the same leaf and fails at
+   * intent registration.
    */
   deriveTapscripts(script) {
-    const leaf = script.refundWithoutReceiver();
-    return {
-      forfeitTapLeafScript: leaf,
-      intentTapLeafScript: leaf,
-      tapTree: script.encode()
-    };
+    return deriveVhtlcTapscripts(script);
   }
 };
 var BoardingContractHandler = {
@@ -2449,24 +1658,10 @@ var BoardingContractHandler = {
   /** Preserves today's settle/board behaviour. */
   isGenericallySpendable: () => true,
   /**
-   * Probe the on-chain UTXO set for a boarding output at this HD index.
-   *
-   * Boarding's source of truth is the **current** on-chain coin set
-   * (`OnchainProvider.getCoins`), not the Ark indexer: a boarded (spent)
-   * boarding output becomes an L2 VTXO at the receive index, so the
-   * indexer probe already keeps the gap window open for it; only an
-   * *unspent* boarding output needs the on-chain probe (see plan §2).
-   *
-   * No-ops (returns `[]`) when boarding discovery is not plumbed — i.e.
-   * `deps.boardingTimelock` or `deps.onchainNetwork` is absent — so the
-   * scanner unit harness (which sets neither) is unaffected.
-   *
-   * Always emits `type: "boarding"`, even in the degenerate equal-delay case
-   * where the boarding script is byte-identical to a `default` script at this
-   * index (`boardingExitDelay === unilateralExitDelay`). The collision is no
-   * longer pre-judged in discovery; it is tolerated FIRST-WINS at the
-   * persistence layer ({@link ContractManager.upsertContract}). `deps.csvTimelocks`
-   * is intentionally not read here.
+   * Probe the **current** on-chain coin set for a boarding output at this HD index. Only an
+   * unspent boarding output needs this: a boarded one became an L2 VTXO at the receive index,
+   * which the indexer probe already covers. Always emits `type: "boarding"` (see the handler
+   * doc on collisions); `deps.csvTimelocks` is intentionally not read.
    */
   async discoverAt(index, descriptor, deps) {
     if (!deps.boardingTimelock || !deps.onchainNetwork) return [];
@@ -2480,26 +1675,19 @@ var BoardingContractHandler = {
     const coins = await deps.onchainProvider.getCoins(onchainAddress);
     if (coins.length === 0) return [];
     const scriptHex = hex.encode(script.pkScript);
-    const boardingSeq = timelockToSequence(deps.boardingTimelock);
     return [
       {
         type: "boarding",
-        params: {
-          pubKey: hex.encode(pubKey),
-          serverPubKey: hex.encode(deps.serverPubKey),
-          csvTimelock: boardingSeq.toString()
-        },
+        params: BoardingContractHandler.serializeParams({
+          pubKey,
+          serverPubKey: deps.serverPubKey,
+          csvTimelock: deps.boardingTimelock
+        }),
         script: scriptHex,
-        // The persisted row's `address` is the *Ark* address (not the
-        // on-chain P2TR), matching the row registered at init so the
-        // ContractWatcher keeps monitoring the same L2 script and the
-        // VTXO repository bucket lines up (plan §6-I.4). The P2TR is
-        // recomputed from params only for the `getCoins` probe.
+        // The Ark address, not the P2TR: must match the row registered at init so the
+        // watcher monitors the same L2 script and the VTXO repository bucket lines up.
         address: script.address(deps.network.hrp, deps.serverPubKey).encode(),
-        // Tag rotated rows (index > 0) so boot resolution can find the
-        // newest boarding address and descriptor-aware signing can
-        // recover the per-index key (plan §6-II/§6-III.3). The index-0
-        // baseline stays untagged, matching `default`/`delegate`.
+        // Tag rotated rows (index > 0) for boot resolution and per-index signing.
         ...rotatedReceiveMetadata(index, descriptor)
       }
     ];
@@ -2526,6 +1714,17 @@ function resolveTimelockValue(value, args) {
     `invalid timelock value '${value}' \u2014 expected a bigint or a '$param' reference`
   );
 }
+function resolveCsvTimelock(csv, args) {
+  const value = resolveTimelockValue(csv.value, args);
+  if (csv.type !== "sequence") return { type: csv.type, value };
+  const timelock = sequenceToCanonicalTimelock(value);
+  if (!timelock) {
+    throw new Error(
+      `csv '${csv.value}' resolved to ${value}, which is not a canonical BIP68 sequence`
+    );
+  }
+  return timelock;
+}
 function resolveAsm(asm, bind) {
   const tokens = asm.map((t) => {
     if (typeof t === "string" && t.startsWith("$")) {
@@ -2574,6 +1773,7 @@ function collectParamRefs(program) {
   const collect = (items) => {
     for (const t of items ?? []) {
       if (typeof t === "string" && t.startsWith("$")) refs.add(t.slice(1));
+      else if (isTweakedSigner(t) && t.tweak.startsWith("$")) refs.add(t.tweak.slice(1));
     }
   };
   for (const fn of Object.values(program.functions)) {
@@ -2626,10 +1826,15 @@ function validateProgram(program, args) {
     if (typeof p !== "string") validateParamValue(p, args[p.name]);
   }
 }
+function isTweakedSigner(ref) {
+  if (typeof ref !== "object" || ref === null || ref instanceof Uint8Array) return false;
+  const { tweak, fn } = ref;
+  return typeof tweak === "string" && typeof fn === "string";
+}
 function resolveSigner(ref, args) {
   if (ref instanceof Uint8Array) return ref;
-  if (!ref.startsWith("$")) {
-    throw new Error(`unknown signer reference '${ref}' \u2014 use '$${ref}'`);
+  if (typeof ref !== "string" || !ref.startsWith("$")) {
+    throw new Error(`unknown signer reference '${ref}' \u2014 use a '$param' or key bytes`);
   }
   const v = bindValue(args, ref.slice(1));
   if (!(v instanceof Uint8Array)) {
@@ -2639,7 +1844,7 @@ function resolveSigner(ref, args) {
 }
 function encodeTapscriptSegment(seg, pubkeys, args) {
   if (seg.csv) {
-    const timelock = { type: seg.csv.type, value: resolveTimelockValue(seg.csv.value, args) };
+    const timelock = resolveCsvTimelock(seg.csv, args);
     if (seg.asm) {
       return ConditionCSVMultisigTapscript.encode({
         conditionScript: resolveAsm(seg.asm, args),
@@ -2684,9 +1889,21 @@ function compileFunctions(program, args, keys) {
   }
   return defs.map((def, i) => {
     validateTapscript(def.tapscript);
-    const pubkeys = def.tapscript.signers.map((s) => resolveSigner(s, args));
+    const pubkeys = def.tapscript.signers.map((signer) => {
+      if (!isTweakedSigner(signer)) return resolveSigner(signer, args);
+      const asm = functions[signer.fn]?.arkadeScript?.asm;
+      if (!asm) {
+        throw new Error(
+          `ArkadeContract: function '${names[i]}' tweaks '${signer.fn}', which has no arkade script`
+        );
+      }
+      return computeArkadeScriptPublicKey(
+        resolveSigner(signer.tweak, args),
+        resolveAsm(asm, args)
+      );
+    });
     const arkadeScript = def.arkadeScript ? resolveAsm(def.arkadeScript.asm, args) : void 0;
-    const leafPubkeys = arkadeScript ? [...pubkeys, computeArkadeScriptPublicKey(keys.emulatorKey, arkadeScript)] : pubkeys;
+    const leafPubkeys = arkadeScript && def.tapscript.emulator !== null ? [...pubkeys, computeArkadeScriptPublicKey(keys.emulatorKey, arkadeScript)] : pubkeys;
     const leafScript = encodeTapscriptSegment(def.tapscript, leafPubkeys, args).script;
     return { name: names[i], def, leafScript, arkadeScript, signerKeys: pubkeys };
   });
@@ -2714,17 +1931,31 @@ var ArkadeProgramScript = class extends VtxoScript {
   }
 };
 function parseArtifact(artifact) {
+  if (Array.isArray(artifact.functions)) {
+    throw new Error(
+      "parseArtifact: `functions` is an array, which is the arkadec artifact shape, not an SDK program \u2014 read it with programFromArtifact instead"
+    );
+  }
+  if (typeof artifact.functions !== "object" || artifact.functions === null) {
+    throw new Error("parseArtifact: `functions` must be an object keyed by function name");
+  }
   const hexToken = (t) => typeof t === "string" && t.startsWith("0x") ? hex.decode(t.slice(2)) : t;
+  const signerRef = (s) => {
+    if (s instanceof Uint8Array || typeof s === "string") return hexToken(s);
+    if (isTweakedSigner(s)) return { tweak: s.tweak, fn: s.fn };
+    throw new Error("parseArtifact: a tweaked signer needs string `tweak` and `fn`");
+  };
   const timelockValue = (v) => typeof v === "string" && v.startsWith("$") ? v : BigInt(v);
   const functions = {};
   for (const [name, fn] of Object.entries(artifact.functions)) {
     const tap = fn.tapscript ?? {};
     const tapscript = {
-      signers: (tap.signers ?? []).map(hexToken),
+      signers: (tap.signers ?? []).map(signerRef),
       ...tap.asm ? { asm: tap.asm.map(hexToken) } : {},
       ...tap.witness ? { witness: tap.witness.map(hexToken) } : {},
       ...tap.csv ? { csv: { type: tap.csv.type, value: timelockValue(tap.csv.value) } } : {},
-      ...tap.cltv !== void 0 ? { cltv: timelockValue(tap.cltv) } : {}
+      ...tap.cltv !== void 0 ? { cltv: timelockValue(tap.cltv) } : {},
+      ..."emulator" in tap ? { emulator: tap.emulator } : {}
     };
     const arkadeScript = fn.arkadeScript ? {
       asm: fn.arkadeScript.asm.map(hexToken),
@@ -2764,7 +1995,8 @@ function stringifyArtifact(program) {
         ...tap.asm ? { asm: tap.asm.map(token) } : {},
         ...tap.witness ? { witness: tap.witness.map(token) } : {},
         ...tap.csv ? { csv: { type: tap.csv.type, value: tap.csv.value.toString() } } : {},
-        ...tap.cltv !== void 0 ? { cltv: tap.cltv.toString() } : {}
+        ...tap.cltv !== void 0 ? { cltv: tap.cltv.toString() } : {},
+        ...tap.emulator !== void 0 ? { emulator: tap.emulator } : {}
       },
       ...fn.arkadeScript ? {
         arkadeScript: {
@@ -2850,22 +2082,12 @@ function deserializeArkadeContractParams(params) {
 
 // src/contracts/handlers/arkade.ts
 function walletKeyFrom(context) {
-  const extract = (value) => {
-    if (!isDescriptor(value)) return value.toLowerCase();
-    try {
-      return extractPubKey(value).toLowerCase();
-    } catch {
-      return void 0;
-    }
-  };
-  if (context.walletDescriptor) {
-    const key = extract(context.walletDescriptor);
-    if (key) return key;
-  }
-  if (context.walletPubKey) {
-    return extract(context.walletPubKey);
+  if (!context.walletDescriptor) return void 0;
+  try {
+    return extractPubKey(context.walletDescriptor).toLowerCase();
+  } catch {
+    return void 0;
   }
-  return void 0;
 }
 function staticWitness(fn, script) {
   const refs = fn.def.tapscript.witness ?? [];
@@ -2890,7 +2112,7 @@ function pathsFor(script, context, opts) {
       continue;
     }
     const csvDef = fn.def.tapscript.csv;
-    const csv = csvDef ? { type: csvDef.type, value: resolveTimelockValue(csvDef.value, script.args) } : void 0;
+    const csv = csvDef ? resolveCsvTimelock(csvDef, script.args) : void 0;
     const cltv = fn.def.tapscript.cltv !== void 0 ? resolveTimelockValue(fn.def.tapscript.cltv, script.args) : void 0;
     if (context.collaborative) {
       if (csv) continue;
@@ -2986,6 +2208,6 @@ contractHandlers.register(VHTLCV2ContractHandler);
 contractHandlers.register(BoardingContractHandler);
 contractHandlers.register(ArkadeContractHandler);
 
-export { ARKADE_OP, ARKADE_OPCODES, ARKADE_OPCODE_NAMES, ARKADE_OPCODE_VALUES, ARKADE_OPS, ArkadeContractHandler, ArkadeProgramScript, ArkadeScript, BoardingContractHandler, DefaultContractHandler, DefaultVtxo, DelegateContractHandler, DelegateVtxo, OPCODE_NAMES, OPCODE_VALUES, SUPPORTED_PROGRAM_VERSION, VHTLC, VHTLCContractHandler, VHTLCV2ContractHandler, WALLET_RECEIVE_SOURCE, arkadeScriptHash, arkadeWitnessHash, asmToBytes, bignum_exports, bytesToASM, computeArkadeScriptPublicKey, contractHandlers, deriveDescriptorLeafCompressedPubKey, deriveDescriptorLeafPubKey, descriptorIsOurs, deserializeArkadeContractParams, fromASM, getOpcodeName, getOpcodeValue, identityDescriptor, inputName, isCltvSatisfied, isCsvSpendable, isMainnetDescriptor, normalizeToDescriptor, parseArtifact, parseHDDescriptor, resolveAsm, serializeArkadeContractParams, speculativeReceiveMetadata, stringifyArtifact, toASM, toXOnly, validateProgram, witnessRefToBytes };
-//# sourceMappingURL=chunk-3R476TDV.js.map
-//# sourceMappingURL=chunk-3R476TDV.js.map
+export { ARKADE_OP, ARKADE_OPCODES, ARKADE_OPCODE_NAMES, ARKADE_OPCODE_VALUES, ARKADE_OPS, ArkadeContractHandler, ArkadeProgramScript, ArkadeScript, BoardingContractHandler, DefaultContractHandler, DefaultVtxo, DelegateContractHandler, DelegateVtxo, OPCODE_NAMES, OPCODE_VALUES, SUPPORTED_PROGRAM_VERSION, VHTLC, VHTLCContractHandler, VHTLCV2ContractHandler, WALLET_RECEIVE_SOURCE, arkadeScriptHash, arkadeWitnessHash, asmToBytes, bignum_exports, bytesToASM, computeArkadeScriptPublicKey, contractHandlers, deriveDescriptorLeafCompressedPubKey, deriveDescriptorLeafPubKey, descriptorIsOurs, deserializeArkadeContractParams, extractPubKey, fromASM, getOpcodeName, getOpcodeValue, identityDescriptor, inputName, isCltvSatisfied, isCsvSpendable, isMainnetDescriptor, normalizeToDescriptor, parseArtifact, parseHDDescriptor, resolveAsm, serializeArkadeContractParams, speculativeReceiveMetadata, stringifyArtifact, toASM, toXOnly, validateProgram, witnessRefToBytes };
+//# sourceMappingURL=chunk-CXHJGED6.js.map
+//# sourceMappingURL=chunk-CXHJGED6.js.map