@arkade-os/swap 0.0.9 → 0.0.11

package/dist/index.cjs

@@ -411,12 +411,30 @@ var swapPrograms = {
   wantAsset: import_sdk2.arkade.parseArtifact(swap_want_asset_program_default),
   wantBtc: import_sdk2.arkade.parseArtifact(swap_want_btc_program_default)
 };
+function withExitClosure(program, exit) {
+  if (!exit) return program;
+  return {
+    ...program,
+    // typed params are authoritative: an undeclared `$exitDelay` fails
+    // validateProgram instead of compiling against an unbound value
+    params: [...program.params ?? [], { name: "exitDelay", type: "int" }],
+    functions: {
+      ...program.functions,
+      exit: {
+        tapscript: { signers: ["$user"], csv: { type: exit.type, value: "$exitDelay" } }
+      }
+    }
+  };
+}
 function swapProgramBinding(offer, serverPubkey) {
   if (offer.makerPkScript.length !== FIELDS.makerPkScript.width) {
     throw new Error("makerPkScript is not a 34-byte taproot scriptPubKey");
   }
   return {
-    program: offer.wantAsset ? swapPrograms.wantAsset : swapPrograms.wantBtc,
+    program: withExitClosure(
+      offer.wantAsset ? swapPrograms.wantAsset : swapPrograms.wantBtc,
+      offer.exitDelay
+    ),
     args: {
       makerWP: offer.makerPkScript.subarray(2),
       wantAmount: offer.wantAmount,
@@ -426,7 +444,8 @@ function swapProgramBinding(offer, serverPubkey) {
       ...offer.wantAsset && {
         wantAssetTxid: offer.wantAsset.txid.slice().reverse(),
         wantAssetGroupIndex: offer.wantAsset.groupIndex
-      }
+      },
+      ...offer.exitDelay && { exitDelay: offer.exitDelay.value }
     },
     keys: {
       serverKey: serverPubkey,
@@ -447,9 +466,27 @@ var FIELDS = {
   makerPkScript: { tag: 5, width: 34 },
   makerPublicKey: { tag: 7, width: 32 },
   emulatorPubkey: { tag: 8, width: 32 },
-  offerAsset: { tag: 11, width: void 0 }
+  ratioNum: { tag: 9, width: 8 },
+  ratioDen: { tag: 10, width: 8 },
+  offerAsset: { tag: 11, width: void 0 },
+  exitTimelock: { tag: 12, width: 9 }
 };
+var EXIT_TYPES = ["blocks", "seconds"];
 var NAMES = Object.fromEntries(Object.entries(FIELDS).map(([k, f]) => [f.tag, k]));
+function u64(name, value) {
+  if (value < BigInt(0) || value >> BigInt(64) > BigInt(0)) {
+    throw new Error(`${name} does not fit the offer wire format (u64)`);
+  }
+  const out = new Uint8Array(FIELDS.wantAmount.width);
+  new DataView(out.buffer).setBigUint64(0, value, false);
+  return out;
+}
+var readU64 = (value) => new DataView(value.buffer, value.byteOffset).getBigUint64(0, false);
+var setRatio = (name, value) => {
+  if (value === void 0 || value === BigInt(0)) return void 0;
+  if (value < BigInt(0)) throw new Error(`${name} does not fit the offer wire format (u64)`);
+  return value;
+};
 function tlv(type, value) {
   if (value.length > 65535) throw new Error("TLV value exceeds the u16 length field");
   return (0, import_utils.concatBytes)(Uint8Array.of(type, value.length >> 8 & 255, value.length & 255), value);
@@ -468,24 +505,45 @@ function encodeOffer(offer) {
       throw new Error(`${name} must be ${FIELDS[name].width} bytes`);
     }
   }
-  if (offer.wantAmount < BigInt(0) || offer.wantAmount >> BigInt(64) > BigInt(0)) {
-    throw new Error("wantAmount does not fit the offer wire format (u64)");
+  const ratioNum = setRatio("ratioNum", offer.ratioNum);
+  const ratioDen = setRatio("ratioDen", offer.ratioDen);
+  if (ratioNum === void 0 !== (ratioDen === void 0)) {
+    throw new Error("offer must carry both ratioNum and ratioDen, or neither");
   }
-  const amount = new Uint8Array(FIELDS.wantAmount.width);
-  new DataView(amount.buffer).setBigUint64(0, offer.wantAmount, false);
   const recs = [
     tlv(FIELDS.swapPkScript.tag, offer.swapPkScript),
-    tlv(FIELDS.wantAmount.tag, amount)
+    tlv(FIELDS.wantAmount.tag, u64("wantAmount", offer.wantAmount))
   ];
   if (offer.wantAsset) recs.push(tlv(FIELDS.wantAsset.tag, offer.wantAsset.serialize()));
+  if (ratioNum !== void 0) recs.push(tlv(FIELDS.ratioNum.tag, u64("ratioNum", ratioNum)));
+  if (ratioDen !== void 0) recs.push(tlv(FIELDS.ratioDen.tag, u64("ratioDen", ratioDen)));
   if (offer.offerAsset) recs.push(tlv(FIELDS.offerAsset.tag, offer.offerAsset.serialize()));
   recs.push(
     tlv(FIELDS.makerPkScript.tag, offer.makerPkScript),
     tlv(FIELDS.makerPublicKey.tag, offer.makerPublicKey),
     tlv(FIELDS.emulatorPubkey.tag, offer.emulatorPubkey)
   );
+  if (offer.exitDelay) recs.push(tlv(FIELDS.exitTimelock.tag, encodeExitDelay(offer.exitDelay)));
   return (0, import_utils.concatBytes)(...recs);
 }
+function encodeExitDelay(exit) {
+  return (0, import_utils.concatBytes)(
+    Uint8Array.of(EXIT_TYPES.indexOf(assertExitDelay(exit).type)),
+    u64("exitDelay", exit.value)
+  );
+}
+function assertExitDelay(exit) {
+  if (EXIT_TYPES.indexOf(exit.type) < 0) {
+    throw new Error(`unknown exitDelay locktime type: ${exit.type}`);
+  }
+  if (exit.value <= BigInt(0)) {
+    throw new Error("exitDelay must be a positive relative locktime");
+  }
+  if (exit.value >> BigInt(32) > BigInt(0)) {
+    throw new Error("exitDelay does not fit the locktime field (u32)");
+  }
+  return exit;
+}
 function decodeOffer(data) {
   const fields = {};
   let off = 0;
@@ -505,6 +563,12 @@ function decodeOffer(data) {
   for (const name of ["wantAsset", "offerAsset"]) {
     if (fields[name]?.length === 0) throw new Error(`missing/invalid ${name}`);
   }
+  for (const [name, value] of Object.entries(fields)) {
+    const width = FIELDS[name].width;
+    if (width !== void 0 && value.length !== width) {
+      throw new Error(`missing/invalid ${name}`);
+    }
+  }
   const need = (name) => {
     const v = fields[name];
     const len = FIELDS[name].width;
@@ -516,16 +580,36 @@ function decodeOffer(data) {
   if (Boolean(fields.wantAsset) === Boolean(fields.offerAsset)) {
     throw new Error("offer must carry exactly one of wantAsset or offerAsset");
   }
+  const readRatio = (name) => {
+    const raw = fields[name];
+    if (!raw) return void 0;
+    const value = readU64(raw);
+    if (value === BigInt(0)) throw new Error(`missing/invalid ${name}`);
+    return value;
+  };
+  const ratioNum = readRatio("ratioNum");
+  const ratioDen = readRatio("ratioDen");
+  if (ratioNum === void 0 !== (ratioDen === void 0)) {
+    throw new Error("offer must carry both ratioNum and ratioDen, or neither");
+  }
   return {
     swapPkScript: need("swapPkScript"),
-    wantAmount: new DataView(amount.buffer, amount.byteOffset).getBigUint64(0, false),
+    wantAmount: readU64(amount),
     ...fields.wantAsset && { wantAsset: import_sdk2.asset.AssetId.fromBytes(fields.wantAsset) },
     ...fields.offerAsset && { offerAsset: import_sdk2.asset.AssetId.fromBytes(fields.offerAsset) },
     makerPkScript: need("makerPkScript"),
     makerPublicKey: need("makerPublicKey"),
-    emulatorPubkey: need("emulatorPubkey")
+    emulatorPubkey: need("emulatorPubkey"),
+    ...ratioNum !== void 0 && { ratioNum },
+    ...ratioDen !== void 0 && { ratioDen },
+    ...fields.exitTimelock && { exitDelay: decodeExitDelay(fields.exitTimelock) }
   };
 }
+function decodeExitDelay(value) {
+  const type = EXIT_TYPES[value[0]];
+  if (!type) throw new Error(`unknown exitDelay locktime type: 0x${value[0].toString(16)}`);
+  return { type, value: readU64(value.subarray(1)) };
+}
 var OFFER_CONTRACT_LABEL = "Arkade swap offer";
 var OFFER_CONTRACT_KIND = "asset-swap-offer";
 async function registerOfferContract(wallet, arkServerUrl, network, binding, serverPubkey, expectedPkScript) {
@@ -551,6 +635,14 @@ async function registerOfferContract(wallet, arkServerUrl, network, binding, ser
   });
   await promoteOfferContract(contractManager, import_base2.hex.encode(expectedPkScript));
 }
+function serverExitDelay(delay) {
+  if (typeof delay !== "bigint" || delay <= BigInt(0)) {
+    throw new Error(
+      "the server reports no usable unilateralExitDelay; pass `exitDelay` to set the offer's exit closure explicitly, or `noExit: true` to publish without one"
+    );
+  }
+  return assertExitDelay({ value: delay, type: delay < BigInt(512) ? "blocks" : "seconds" });
+}
 async function createOffer(wallet, arkServerUrl, params) {
   if (Boolean(params.wantAsset) === Boolean(params.offerAsset)) {
     throw new Error("set exactly one of wantAsset (BTC->asset) or offerAsset (asset->BTC)");
@@ -571,7 +663,11 @@ async function createOffer(wallet, arkServerUrl, params) {
     offerAsset: params.offerAsset,
     makerPkScript: import_sdk2.ArkAddress.decode(makerAddress).pkScript,
     makerPublicKey,
-    emulatorPubkey: emuKey
+    emulatorPubkey: emuKey,
+    // checked HERE, before the covenant is derived and registered below:
+    // deferring it to `encodeOffer` leaves a registered contract behind for
+    // an offer that then fails to encode. @see assertExitDelay
+    exitDelay: params.noExit ? void 0 : params.exitDelay ? assertExitDelay(params.exitDelay) : serverExitDelay(info.unilateralExitDelay)
   };
   const script = offerVtxoScript(binding, serverPubKey);
   const offer = { ...binding, swapPkScript: script.pkScript };
@@ -609,8 +705,8 @@ async function cancelOffer(wallet, arkServerUrl, offerHex, opts) {
     // script and the payout script comes from wallet.getAddress(), so the
     // client's network (which only shapes address derivation) is unused here
   });
-  const serverKey = swapAddress ? import_sdk2.ArkAddress.decode(swapAddress).serverPubKey : client.serverKey;
-  const { program, args, keys } = swapProgramBinding(offer, serverKey);
+  const operatorPubkey = swapAddress ? import_sdk2.ArkAddress.decode(swapAddress).serverPubKey : client.serverKey;
+  const { program, args, keys } = swapProgramBinding(offer, operatorPubkey);
   const rebuilt = new import_sdk2.arkade.ArkadeProgramScript(program, args, keys);
   if (import_base2.hex.encode(rebuilt.pkScript) !== import_base2.hex.encode(offer.swapPkScript)) {
     throw new Error(
@@ -1512,7 +1608,9 @@ function classifySpend(offer, serverPubkey, spendTx, deposit) {
     const script = offerVtxoScript(offer, serverPubkey);
     if (import_base6.hex.encode(script.pkScript) !== import_base6.hex.encode(offer.swapPkScript)) return "indeterminate";
     leaves = {
-      cancel: script.functionByName("cancel")?.leafScript,
+      // both routes that hand the deposit back; `exit` is absent on an
+      // offer that carries no exit closure, and drops out here
+      returned: ["cancel", "exit"].map((name) => script.functionByName(name)?.leafScript).filter((leaf) => leaf !== void 0),
       fulfill: script.functionByName("fulfill")?.leafScript
     };
   } catch {
@@ -1524,7 +1622,7 @@ function classifySpend(offer, serverPubkey, spendTx, deposit) {
     if (import_base6.hex.encode(input.txid) !== deposit.txid) continue;
     for (const leaf of input.tapLeafScript ?? []) {
       const spent = import_base6.hex.encode((0, import_sdk6.scriptFromTapLeafScript)(leaf));
-      if (leaves.cancel && spent === import_base6.hex.encode(leaves.cancel)) return "cancelled";
+      if (leaves.returned.some((back) => spent === import_base6.hex.encode(back))) return "cancelled";
       if (leaves.fulfill && spent === import_base6.hex.encode(leaves.fulfill)) return "fulfilled";
     }
   }
@@ -1918,8 +2016,22 @@ var assertPairLength = (pair) => {
 };
 var verifyLockupAddress = (quote, derivedAddress) => {
   const quoted = quote.profile?.lockup_address;
-  if (derivedAddress !== quoted) throw new AddressMismatch(derivedAddress, quoted);
-  return derivedAddress;
+  const candidates = Array.isArray(derivedAddress) ? derivedAddress : [derivedAddress];
+  const matched = candidates.find((address) => address === quoted);
+  if (matched === void 0) throw new AddressMismatch(candidates, quoted);
+  return matched;
+};
+var LOCKUP_SHAPE_VARIANTS = [void 0, "preTimelockedRefund"];
+var matchQuotedLockup = (quote, hrp, serverPubkey, build) => {
+  const candidates = LOCKUP_SHAPE_VARIANTS.map((legacy) => {
+    const script = build(legacy);
+    return { script, address: script.address(hrp, serverPubkey).encode(), legacy };
+  });
+  const matchedAddress = verifyLockupAddress(
+    quote,
+    candidates.map((candidate) => candidate.address)
+  );
+  return candidates.find((candidate) => candidate.address === matchedAddress);
 };
 var assertFundable = (input) => {
   const fail = (reason, message) => {
@@ -2121,13 +2233,11 @@ function lightningSendVtxoScript(params) {
     unilateralRefundWithoutReceiverDelay: seconds(
       unilateralRefundWithoutReceiverDelay(params.claimDelay)
     ),
-    nonInteractiveClaim: {
+    nonInteractiveParameters: {
       receiverPkScript: params.receiverPkScript,
-      emulatorPubkey: params.emulatorPubkey
-    },
-    nonInteractiveRefund: {
       senderPkScript: params.refundPkScript,
-      emulatorPubkey: params.emulatorPubkey
+      emulatorPubkey: params.emulatorPubkey,
+      ...params.legacy !== void 0 && { legacy: params.legacy }
     }
   });
 }
@@ -2135,10 +2245,8 @@ async function requestLightningSend(wallet, arkServerUrl, transport, params) {
   const rfqId = params.rfqId ?? newRfqId();
   const secrets = await (0, import_sdk10.provisionRefundKey)(wallet);
   const senderPubkey = secrets.pubkey;
-  const [info, refundAddress] = await Promise.all([
-    new import_sdk9.RestArkProvider(arkServerUrl).getInfo(),
-    wallet.getAddress()
-  ]);
+  const refundAddress = secrets.address;
+  const info = await new import_sdk9.RestArkProvider(arkServerUrl).getInfo();
   const quote = await transport.requestQuote(
     lightningSendRequest({ rfqId, invoice: params.invoice.raw, refundAddress, senderPubkey })
   );
@@ -2173,11 +2281,20 @@ async function requestLightningSend(wallet, arkServerUrl, transport, params) {
     ),
     senderPubkey,
     receiverPkScript: solverHex(receiverPkScriptHex, "profile.receiver_pk_script"),
-    refundPkScript: import_sdk9.ArkAddress.decode(refundAddress).pkScript
+    refundPkScript: secrets.pkScript
+  };
+  const matched = matchQuotedLockup(
+    quote,
+    network.hrp,
+    serverPubkey,
+    (legacy) => lightningSendVtxoScript({ ...treeParams, ...legacy !== void 0 && { legacy } })
+  );
+  const script = matched.script;
+  const address = matched.address;
+  const matchedTreeParams = {
+    ...treeParams,
+    ...matched.legacy !== void 0 && { legacy: matched.legacy }
   };
-  const script = lightningSendVtxoScript(treeParams);
-  const address = script.address(network.hrp, serverPubkey).encode();
-  verifyLockupAddress(quote, address);
   assertFundable({
     quote,
     invoiceExpiresAt: params.invoice.expiresAt,
@@ -2196,7 +2313,7 @@ async function requestLightningSend(wallet, arkServerUrl, transport, params) {
     refundAddress,
     senderPubkey,
     secrets,
-    treeParams
+    treeParams: matchedTreeParams
   };
 }
 var offerTermsFromQuote = (quote, assets) => {
@@ -2261,7 +2378,7 @@ function deriveOnchainSend(input) {
   if (refundLocktime === void 0 || htlcPubkey === void 0 || htlcLocktime === void 0 || minConfirmations === void 0 || receiverPkScriptHex === void 0) {
     throw new Error("onchain-send quote is missing a binding field");
   }
-  const script = lightningSendVtxoScript({
+  const treeParams = {
     solverPubkey: (0, import_sdk9.toXOnly)(import_base10.hex.decode(quote.solver_pubkey), "solver key"),
     refundLocktime,
     serverPubkey: input.serverPubkey,
@@ -2271,9 +2388,13 @@ function deriveOnchainSend(input) {
     senderPubkey: input.senderPubkey,
     receiverPkScript: solverHex(receiverPkScriptHex, "profile.receiver_pk_script"),
     refundPkScript: import_sdk9.ArkAddress.decode(input.refundAddress).pkScript
-  });
-  const address = script.address(input.hrp, input.serverPubkey).encode();
-  verifyLockupAddress(quote, address);
+  };
+  const { script, address } = matchQuotedLockup(
+    quote,
+    input.hrp,
+    input.serverPubkey,
+    (legacy) => lightningSendVtxoScript({ ...treeParams, ...legacy !== void 0 && { legacy } })
+  );
   const htlcParams = {
     paymentHash: input.paymentHash,
     claimKey: input.payoutPubkey,
@@ -2448,13 +2569,11 @@ function receiveVtxoScript(params) {
     unilateralRefundWithoutReceiverDelay: seconds(
       unilateralRefundWithoutReceiverDelay(params.claimDelay)
     ),
-    nonInteractiveClaim: {
+    nonInteractiveParameters: {
       receiverPkScript: params.payoutPkScript,
-      emulatorPubkey: params.emulatorPubkey
-    },
-    nonInteractiveRefund: {
       senderPkScript: params.solverRefundPkScript,
-      emulatorPubkey: params.emulatorPubkey
+      emulatorPubkey: params.emulatorPubkey,
+      ...params.legacy !== void 0 && { legacy: params.legacy }
     }
   });
 }
@@ -2478,10 +2597,23 @@ function deriveLightningReceive(input) {
     payoutPubkey: input.payoutPubkey,
     payoutPkScript: import_sdk9.ArkAddress.decode(input.payoutAddress).pkScript
   };
-  const script = receiveVtxoScript(treeParams);
-  const address = script.address(input.hrp, input.serverPubkey).encode();
-  verifyLockupAddress(quote, address);
-  return { address, swapPkScript: script.pkScript, script, invoice, refundLocktime, treeParams };
+  const matched = matchQuotedLockup(
+    quote,
+    input.hrp,
+    input.serverPubkey,
+    (legacy) => receiveVtxoScript({ ...treeParams, ...legacy !== void 0 && { legacy } })
+  );
+  return {
+    address: matched.address,
+    swapPkScript: matched.script.pkScript,
+    script: matched.script,
+    invoice,
+    refundLocktime,
+    treeParams: {
+      ...treeParams,
+      ...matched.legacy !== void 0 && { legacy: matched.legacy }
+    }
+  };
 }
 async function requestLightningReceive(wallet, arkServerUrl, transport, params) {
   const rfqId = params.rfqId ?? newRfqId();
@@ -2569,7 +2701,7 @@ function deriveOnchainReceive(input) {
   if (refundLocktime === void 0 || claimPubkey === void 0 || htlcLocktime === void 0 || minConfirmations === void 0 || solverRefundPkScriptHex === void 0) {
     throw new Error("onchain-receive quote is missing a binding field");
   }
-  const script = receiveVtxoScript({
+  const treeParams = {
     solverPubkey: (0, import_sdk9.toXOnly)(import_base10.hex.decode(quote.solver_pubkey), "solver key"),
     refundLocktime,
     serverPubkey: input.serverPubkey,
@@ -2579,9 +2711,13 @@ function deriveOnchainReceive(input) {
     solverRefundPkScript: solverHex(solverRefundPkScriptHex, "profile.solver_refund_pk_script"),
     payoutPubkey: input.payoutPubkey,
     payoutPkScript: import_sdk9.ArkAddress.decode(input.payoutAddress).pkScript
-  });
-  const address = script.address(input.hrp, input.serverPubkey).encode();
-  verifyLockupAddress(quote, address);
+  };
+  const { script, address } = matchQuotedLockup(
+    quote,
+    input.hrp,
+    input.serverPubkey,
+    (legacy) => receiveVtxoScript({ ...treeParams, ...legacy !== void 0 && { legacy } })
+  );
   const htlc = onchainHtlcScript(
     {
       paymentHash: input.paymentHash,
@@ -2747,6 +2883,7 @@ async function findLockupVtxos(indexer, swapPkScript) {
     [recoverable.vtxos ?? [], true]
   ]) {
     for (const vtxo of vtxos) {
+      if (vtxo.isUnrolled) continue;
       const key = `${vtxo.txid}:${vtxo.vout}`;
       if (seen.has(key)) continue;
       seen.add(key);
@@ -2769,10 +2906,17 @@ async function readLockupFate(indexer, input) {
   const { vtxos } = await indexer.getVtxos({ scripts: [import_base11.hex.encode(input.swapPkScript)] });
   const all = vtxos ?? [];
   if (all.length === 0) return { fate: "unknown" };
+  const exited = all.filter((vtxo) => vtxo.isUnrolled && !(0, import_sdk11.hasTerminalSpend)(vtxo));
+  if (exited.length > 0) {
+    return {
+      fate: "exited",
+      outpoints: exited.map((vtxo) => ({ txid: vtxo.txid, vout: vtxo.vout }))
+    };
+  }
   const spentBy = /* @__PURE__ */ new Map();
   let everySpendNamed = true;
   for (const vtxo of all) {
-    if (!vtxo.isSpent && !vtxo.spentBy && !vtxo.settledBy) return { fate: "open" };
+    if (!(0, import_sdk11.hasTerminalSpend)(vtxo)) return { fate: "open" };
     if (vtxo.spentBy)
       spentBy.set(vtxo.spentBy, {
         checkpointTxid: vtxo.spentBy,
@@ -2814,10 +2958,10 @@ async function pushRefundWithoutReceiver(ark, input) {
       input.script.options.refundLocktime
     );
   }
-  const refundPkScript = input.refundPkScript ?? input.script.options.nonInteractiveRefund?.senderPkScript;
+  const refundPkScript = input.refundPkScript ?? input.script.options.nonInteractiveParameters?.senderPkScript;
   if (!refundPkScript) {
     throw new Error(
-      "no refund destination: the contract carries no nonInteractiveRefund leaf, so pass refundPkScript explicitly"
+      "no refund destination: the contract carries no emulator covenant suite, so pass refundPkScript explicitly"
     );
   }
   const info = await ark.getInfo();
@@ -2869,6 +3013,21 @@ async function refundIfUnresolved(transport, ark, indexer, input) {
     const status = await transport.status(input.rfqId);
     if (status && isResolved(status.state)) return { outcome: "resolved", status };
     if (now() >= input.refundLocktime) {
+      let fate = { fate: "unknown" };
+      try {
+        fate = await readLockupFate(indexer, {
+          swapPkScript: input.script.pkScript,
+          paymentHash: input.paymentHash
+        });
+      } catch {
+      }
+      if (fate.fate === "exited") {
+        return {
+          outcome: "exited",
+          outpoints: fate.outpoints.map((o) => `${o.txid}:${o.vout}`),
+          status
+        };
+      }
       const vtxos = await findLockupVtxos(indexer, input.script.pkScript);
       if (vtxos.length === 0) return { outcome: "nothing_to_refund", status };
       try {
@@ -3660,12 +3819,36 @@ var RfqSwapManager = class {
       this.setState(swap, fate.fate === "claimed" ? "settled" : "refunded");
       return;
     }
-    if (swap.kind === "lightning_receive") return this.driveReceiveClaim(swap);
+    if (swap.kind === "lightning_receive") {
+      return fate.fate === "exited" ? this.blockExitedLockup(swap, fate) : this.driveReceiveClaim(swap);
+    }
     if (swap.kind === "onchain_send" && swap.state !== "claimed") {
       if (await this.driveOnchain(swap) === "handled") return;
     }
+    if (fate.fate === "exited") {
+      const claiming = swap.state === "claimable" || swap.state === "claimed";
+      if (this.config.now() < swap.refundLocktime && claiming) return;
+      return this.blockExitedLockup(swap, fate);
+    }
     await this.driveArkadeRefund(swap);
   }
+  /**
+   * The lockup was unilaterally exited: its outputs sit onchain under the
+   * VHTLC script, where no offchain claim or refund can reach them.
+   *
+   * `needs_counterparty` rather than a terminal state, because the money still
+   * needs action and the swap can still end either way — an onchain claim can
+   * reveal the preimage, an onchain refund can return it — and that state is
+   * documented as re-checked every pass. It must be set from HERE and not from
+   * inside `driveArkadeRefund`, whose two `unblock` calls would lift it again
+   * on the very next pass.
+   */
+  blockExitedLockup(swap, fate) {
+    this.block(
+      swap,
+      `the lockup was unilaterally exited (${fate.outpoints.length} output(s) onchain), so no offchain spend can move it \u2014 complete the unroll and spend it onchain`
+    );
+  }
   /**
    * The receive leg's whole state machine: claim the solver-funded lockup
    * while the window is open, and recognise the shapes in which it can be

package/dist/index.d.cts

@@ -1,9 +1,9 @@
-import { ProvisionedKey, ProvisionedClaimSecret, asset, IWallet, arkade, RestIndexerProvider, Transaction, IContractManager, VHTLC, Identity, ActivityResolver } from '@arkade-os/sdk';
-import { S as SwapSecretsProjection, R as RfqSwapRecord, A as AssetSwapRepository, a as AssetSwap, M as MarketsCacheEntry, b as RefundArkProvider, c as RefundIndexer, L as LockupVtxo, d as RfqSwap, e as ArkadeRefundResult, f as LockupSpendIndexer, g as RfqSwapState } from './repository-DEHLtD9l.cjs';
-export { h as AssetSwapStatus, i as AvailableRfqSwapManagerCallbacks, B as BTC_ASSET_ID, I as InMemoryAssetSwapRepository, j as LightningReceiveSwap, k as LightningSendSwap, l as LockupFate, m as LockupNeedsRecoveryError, n as LockupParams, o as LockupSpend, O as OnchainSendAction, p as OnchainSendSwap, P as PersistableRfqSwap, q as PreimageBlockedReason, r as PreimageNotRecoverableError, s as REFUND_MTP_LAG_SECONDS, t as RFQ_RESOLVED_STATES, u as RFQ_SWAP_RETENTION_SECONDS, v as RFQ_SWAP_TERMINAL_STATES, w as RefundOutcome, x as RfqRestoreFailure, y as RfqRestoreOptions, z as RfqRestoreResult, C as RfqSwapActionName, D as RfqSwapLockup, E as RfqSwapManager, F as RfqSwapManagerCallbacks, G as RfqSwapManagerConfig, H as RfqSwapManagerDeps, J as RfqSwapManagerEvents, K as RfqSwapOrigin, N as RfqSwapOriginRequired, Q as RfqSwapOutcome, T as RfqSwapRecordStore, U as SwapContractRegistry, V as addAssetSwap, W as awaitRfqResolution, X as createRfqSwapRecord, Y as findLockupVtxos, Z as getAssetSwaps, _ as getAssetSwapsOrThrow, $ as isRfqSwapTerminal, a0 as isRfqTerminal, a1 as nextOnchainAction, a2 as preimageForSwapRecord, a3 as pushRefundWithoutReceiver, a4 as readLockupFate, a5 as rebuildRfqSwap, a6 as refundIfUnresolved, a7 as rfqSwapOriginOf, a8 as shouldRetainRfqSwap, a9 as swapSecretsToRecord, aa as updateAssetSwap, ab as updateAssetSwapBestEffort, ac as updateRfqSwapRecord } from './repository-DEHLtD9l.cjs';
+import { ProvisionedKey, ProvisionedClaimSecret, asset, RelativeTimelock, IWallet, arkade, RestIndexerProvider, Transaction, IContractManager, VHTLC, Identity, ActivityResolver } from '@arkade-os/sdk';
+import { S as SwapSecretsProjection, R as RfqSwapRecord, A as AssetSwapRepository, a as AssetSwap, M as MarketsCacheEntry, b as RefundArkProvider, c as RefundIndexer, L as LockupVtxo, d as RfqSwap, e as ArkadeRefundResult, f as LockupSpendIndexer, g as RfqSwapState } from './repository-B02vsgcV.cjs';
+export { h as AssetSwapStatus, i as AvailableRfqSwapManagerCallbacks, B as BTC_ASSET_ID, I as InMemoryAssetSwapRepository, j as LightningReceiveSwap, k as LightningSendSwap, l as LockupFate, m as LockupNeedsRecoveryError, n as LockupParams, o as LockupSpend, O as OnchainSendAction, p as OnchainSendSwap, P as PersistableRfqSwap, q as PreimageBlockedReason, r as PreimageNotRecoverableError, s as REFUND_MTP_LAG_SECONDS, t as RFQ_RESOLVED_STATES, u as RFQ_SWAP_RETENTION_SECONDS, v as RFQ_SWAP_TERMINAL_STATES, w as RefundOutcome, x as RfqRestoreFailure, y as RfqRestoreOptions, z as RfqRestoreResult, C as RfqSwapActionName, D as RfqSwapLockup, E as RfqSwapManager, F as RfqSwapManagerCallbacks, G as RfqSwapManagerConfig, H as RfqSwapManagerDeps, J as RfqSwapManagerEvents, K as RfqSwapOrigin, N as RfqSwapOriginRequired, Q as RfqSwapOutcome, T as RfqSwapRecordStore, U as SwapContractRegistry, V as addAssetSwap, W as awaitRfqResolution, X as createRfqSwapRecord, Y as findLockupVtxos, Z as getAssetSwaps, _ as getAssetSwapsOrThrow, $ as isRfqSwapTerminal, a0 as isRfqTerminal, a1 as nextOnchainAction, a2 as preimageForSwapRecord, a3 as pushRefundWithoutReceiver, a4 as readLockupFate, a5 as rebuildRfqSwap, a6 as refundIfUnresolved, a7 as rfqSwapOriginOf, a8 as shouldRetainRfqSwap, a9 as swapSecretsToRecord, aa as updateAssetSwap, ab as updateAssetSwapBestEffort, ac as updateRfqSwapRecord } from './repository-B02vsgcV.cjs';
 import { Network, LocalCardInput, DiscoveredMarket, Side, OfferPlan } from '@arkade-os/solver-discovery';
-import { O as OnchainNetwork, a as OnchainHtlc, b as OnchainHtlcParams } from './rfq-hbzhTWHT.cjs';
-export { A as ARKADE_ASSET, c as ARKADE_BTC, d as AddressMismatch, C as ChainSource, e as ChainUtxo, H as HtlcUtxo, I as InvoiceFacts, L as LIGHTNING_BTC, f as LIGHTNING_RECEIVE_PAIR, g as LIGHTNING_SEND_PAIR, h as LOCKTIME_THRESHOLD, i as LightningReceiveTreeParams, j as LightningSendTreeParams, M as MAX_MIN_CONFIRMATIONS, k as MIN_CLAIM_WINDOW_SECONDS, l as MIN_HEADROOM_SECONDS, m as ONCHAIN_BTC, n as ONCHAIN_CLAIM_MARGIN_SECONDS, o as ONCHAIN_DUST_SATS, p as ONCHAIN_ORDER_MARGIN_SECONDS, q as ONCHAIN_RECEIVE_PAIR, r as ONCHAIN_SECONDS_PER_BLOCK, s as ONCHAIN_SEND_PAIR, t as OnchainHtlcPhase, R as RFQ_TERMINAL_STATES, u as RelaySocket, v as RfqQuote, w as RfqRefusalReason, x as RfqStatus, y as RfqTransport, S as SOLO_REFUND_HEADROOM_SECONDS, z as SwapRefusal, B as arkadeAssetLeg, D as arkadeSwapRequest, E as assertFundable, F as assertReceivable, G as awaitOnchainFill, J as buildHtlcClaim, K as buildHtlcRefund, N as claimOnchainFill, P as classifyOnchainHtlc, Q as deriveLightningReceive, T as deriveOnchainReceive, U as deriveOnchainSend, V as extractPreimage, W as httpTransport, X as lightningReceiveRequest, Y as lightningSendRequest, Z as lightningSendVtxoScript, _ as newPreimage, $ as newRfqId, a0 as offerTermsFromQuote, a1 as onchainHtlcScript, a2 as onchainReceiveRequest, a3 as onchainSendRequest, a4 as paymentHashOf, a5 as receiveVtxoScript, a6 as relayTransport, a7 as requestLightningReceive, a8 as requestLightningSend, a9 as requestOnchainReceive, aa as requestOnchainSend, ab as rfqPair, ac as unilateralClaimDelay, ad as unilateralRefundDelay, ae as unilateralRefundWithoutReceiverDelay, af as verifyLockupAddress, ag as verifyReceiveInvoice } from './rfq-hbzhTWHT.cjs';
+import { O as OnchainNetwork, a as OnchainHtlc, b as OnchainHtlcParams } from './rfq-DkckzRKK.cjs';
+export { A as ARKADE_ASSET, c as ARKADE_BTC, d as AddressMismatch, C as ChainSource, e as ChainUtxo, H as HtlcUtxo, I as InvoiceFacts, L as LIGHTNING_BTC, f as LIGHTNING_RECEIVE_PAIR, g as LIGHTNING_SEND_PAIR, h as LOCKTIME_THRESHOLD, i as LightningReceiveTreeParams, j as LightningSendTreeParams, M as MAX_MIN_CONFIRMATIONS, k as MIN_CLAIM_WINDOW_SECONDS, l as MIN_HEADROOM_SECONDS, m as ONCHAIN_BTC, n as ONCHAIN_CLAIM_MARGIN_SECONDS, o as ONCHAIN_DUST_SATS, p as ONCHAIN_ORDER_MARGIN_SECONDS, q as ONCHAIN_RECEIVE_PAIR, r as ONCHAIN_SECONDS_PER_BLOCK, s as ONCHAIN_SEND_PAIR, t as OnchainHtlcPhase, R as RFQ_TERMINAL_STATES, u as RelaySocket, v as RfqQuote, w as RfqRefusalReason, x as RfqStatus, y as RfqTransport, S as SOLO_REFUND_HEADROOM_SECONDS, z as SwapRefusal, B as arkadeAssetLeg, D as arkadeSwapRequest, E as assertFundable, F as assertReceivable, G as awaitOnchainFill, J as buildHtlcClaim, K as buildHtlcRefund, N as claimOnchainFill, P as classifyOnchainHtlc, Q as deriveLightningReceive, T as deriveOnchainReceive, U as deriveOnchainSend, V as extractPreimage, W as httpTransport, X as lightningReceiveRequest, Y as lightningSendRequest, Z as lightningSendVtxoScript, _ as newPreimage, $ as newRfqId, a0 as offerTermsFromQuote, a1 as onchainHtlcScript, a2 as onchainReceiveRequest, a3 as onchainSendRequest, a4 as paymentHashOf, a5 as receiveVtxoScript, a6 as relayTransport, a7 as requestLightningReceive, a8 as requestLightningSend, a9 as requestOnchainReceive, aa as requestOnchainSend, ab as rfqPair, ac as unilateralClaimDelay, ad as unilateralRefundDelay, ae as unilateralRefundWithoutReceiverDelay, af as verifyLockupAddress, ag as verifyReceiveInvoice } from './rfq-DkckzRKK.cjs';
 
 /**
  * Which wallet key signs this leg. Stored at `profile.signer`.
@@ -182,7 +182,18 @@ declare function onchainSendProfile(result: {
     minConfirmations: number;
 }): Omit<OnchainSendProfile, "signer" | "hashlock">;
 
-/** The contracts — pure data, shared verbatim with any other implementation. */
+/**
+ * The contracts, one per WANT side — pure data, shared verbatim with any other
+ * implementation.
+ *
+ * **These are the base: an offer carrying an exit delay compiles to a third
+ * closure that is not in either file.** The tree is not fixed-shape — the
+ * protocol defines the exit as `iff ExitDelay`, and solverd appends it the same
+ * way (`pkg/swap/contract/offer.go`, `VtxoScript`) — so it cannot be a function
+ * in a static artifact without splitting these into one file per exit variant.
+ * {@link withExitClosure} owns that step, and the golden in `offer.test.ts`
+ * pins the artifact it produces so the whole contract is still readable as data.
+ */
 declare const swapPrograms: Record<"wantAsset" | "wantBtc", ReturnType<typeof arkade.parseArtifact>>;
 /** A full-fill offer. Exactly one field names an asset: `wantAsset` set = the
  * fill must deliver that asset (the deposit may be BTC or another asset,
@@ -203,6 +214,14 @@ interface Offer {
     makerPublicKey: Uint8Array;
     /** Covenant co-signer (emulator) x-only key (32 bytes). */
     emulatorPubkey: Uint8Array;
+    /** Partial-fill numerator. Reserved wire space in V1: carried through the
+     * codec so an offer that sets it decodes, never interpreted here. */
+    ratioNum?: bigint;
+    /** Partial-fill denominator. Set with {@link Offer.ratioNum} or not at all. */
+    ratioDen?: bigint;
+    /** The maker's unilateral exit path. Present adds a third closure to the
+     * taproot tree, so it changes `swapPkScript` — see {@link offerVtxoScript}. */
+    exitDelay?: RelativeTimelock;
 }
 /** Compile the offer's contract: program + args -> taproot tree. */
 declare function offerVtxoScript(offer: Omit<Offer, "swapPkScript">, serverPubkey: Uint8Array): InstanceType<typeof arkade.ArkadeProgramScript>;
@@ -233,6 +252,14 @@ declare function decodeOffer(data: Uint8Array): Offer;
  * funding rather than after: nothing is at stake yet, so a failure can throw
  * and be retried, where the same failure after `wallet.send` would leave a
  * funded deposit unwatched with no way to notice.
+ *
+ * **The maker's unilateral exit closure is built by default**, at the server's
+ * own `unilateralExitDelay` — the same thing solverd does. Without it `cancel`
+ * is the only way back out, and `cancel` needs the server's signature: a server
+ * that will not co-sign leaves the deposit stuck at the swap address until the
+ * VTXO expires and the operator sweeps it. An offer has no expiry of its own,
+ * so that exposure has no end. `noExit` opts out for a caller who wants the
+ * smaller tree and accepts the dependency.
  */
 declare function createOffer(wallet: IWallet, arkServerUrl: string, params: {
     wantAmount: bigint;
@@ -241,6 +268,12 @@ declare function createOffer(wallet: IWallet, arkServerUrl: string, params: {
     /** Co-signer key override (33-byte compressed hex); see
      * {@link resolveEmulatorPubkey}. */
     emulatorPubkey?: string;
+    /** Override the exit closure's delay. Defaults to the server's own
+     * `unilateralExitDelay`, which is the delay solverd uses too. */
+    exitDelay?: RelativeTimelock;
+    /** Publish without the exit closure, leaving `cancel` — which needs the
+     * server — as the only way back out. See the note on this function. */
+    noExit?: boolean;
 }): Promise<{
     /** The encoded offer, hex. **Persist this** — it is the only input
      * `cancelOffer` needs to rebuild the covenant, and the restore scan reads
@@ -263,19 +296,23 @@ declare function createOffer(wallet: IWallet, arkServerUrl: string, params: {
 /**
  * Cancel an offer: spend the swap VTXO back to the user. Returns the ark txid.
  *
- * This is the refund path — how a user takes back a deposit no solver filled.
- * **Neither program carries a timelock**, so an unfilled deposit keeps its
- * place at the swap address rather than expiring: no deadline to miss and no
- * "expired" state to unwind, at the cost of the refund being something the
+ * This is the cooperative refund path — how a user takes back a deposit no
+ * solver filled. **No path here is on a deadline**, so an unfilled deposit
+ * keeps its place at the swap address rather than expiring: nothing to miss and
+ * no "expired" state to unwind, at the cost of the refund being something the
  * user asks for rather than something a clock delivers.
  *
- * Both paths out of the covenant are deliberately asymmetric:
+ * The routes out of the covenant are deliberately asymmetric:
  *   - `fulfill` is signed by the **server alone**, but the covenant constrains
  *     it to pay output 0 to `makerWP` for at least `wantAmount` — a solver
  *     cannot take the deposit without delivering.
  *   - `cancel` is a **2-of-2 of the user and the server**, so cancelling is
  *     cooperative: the server co-signs. No solver signature is involved, so the
  *     refund never depends on the counterparty being reachable.
+ *   - `exit` is the user **alone** after a relative timelock, present unless the
+ *     offer was created with `noExit`. It is the route that survives a server
+ *     that will not co-sign this one, and it is reached by unrolling the VTXO
+ *     onchain rather than through this function.
  *
  * Cancel therefore races a fill rather than pre-empting it. An offer the solver
  * is filling in the same moment may be spent by `fulfill` first, in which case
@@ -451,10 +488,19 @@ type SpendKind = "cancelled" | "fulfilled" | "indeterminate";
 /**
  * Classify a spend by the covenant leaf it took.
  *
- * The covenant's whole vocabulary is two leaves: `cancel` returns the deposit
- * to the user, `fulfill` is the solver paying for it. A submitted ark tx keeps
- * each input's `tapLeafScript`, so the spend *states* which one it used — this
- * reads an answer rather than inferring one.
+ * The vocabulary is what became of the deposit, not which key moved it:
+ * `fulfill` is the solver paying for it, and everything else returns it to the
+ * user. A submitted ark tx keeps each input's `tapLeafScript`, so the spend
+ * *states* which one it used — this reads an answer rather than inferring one.
+ *
+ * **`exit` reports `cancelled`, like `cancel` does.** The two differ in who had
+ * to agree — `cancel` is cooperative with the signer, `exit` is the maker alone
+ * after a delay — but not in outcome: the deposit went back unfilled either
+ * way, which is the question this answers. Reporting the exit leaf as
+ * `indeterminate` instead would be worse than imprecise: no status is written,
+ * so the swap stays `pending`, `restoreAssetSwaps` re-queues it on every scan,
+ * and `retireOfferContract` never runs — leaving a dead script in the
+ * subscription and the failsafe poll for the life of the wallet.
  *
  * **Hand it the transaction that actually spends the deposit outpoint, which is
  * the checkpoint, not the ark tx.** A spend is two linked transactions: the