@gvnrdao/dh-sdk 0.0.306 → 0.0.308

package/dist/index.mjs

@@ -1514,6 +1514,19 @@ var require_pkg_src = __commonJS({
           publicKey: "0x046da0ad6da7dd4a0063cbeac6f2bdb6a9889c2178b23470833356a8ee5630f7f0eee0db348d9d9aaaadd23eccf0063c8f68ee5e446abe30b882bf1de4c932bc21",
           ethAddress: "0xc7e1588Db94Bbe92Ab209B833235144Fc5b97607"
         }
+      },
+      btcUtxoInvalidator: {
+        cid: "QmRue1EAjuJwCDTtTH4czdkkmDEfNpT7iudvwtjaRs6AdA",
+        authorizedCidHex: cidToHex(
+          "QmRue1EAjuJwCDTtTH4czdkkmDEfNpT7iudvwtjaRs6AdA"
+        ),
+        name: "Btc Utxo Invalidator",
+        description: "Production Btc Utxo Invalidator",
+        version: "1.0.0",
+        deployed: true,
+        deployedAt: 1784801043540,
+        size: 60717,
+        hash: "2ca9736edf3d54bba7445491920cba28429029c32a2f2830cad831a37a3cb310"
       }
     };
     function getDeploymentsForNetwork(network) {
@@ -2259,7 +2272,7 @@ ${errorReport}`);
     }
     init_debug_logger();
     init_session_signature_cache();
-    var import_ethers16 = __require("ethers");
+    var import_ethers17 = __require("ethers");
     var EXPIRED_LOAN_MIN_LIQUIDATION_THRESHOLD_BPS = 11e3;
     var GRACE_PERIOD_DAYS = 30;
     var SATOSHIS_PER_BITCOIN = 100000000n;
@@ -5089,12 +5102,12 @@ ${auth.clientId}`;
     }
     async function executeVaultSnapshot(params) {
       global.ethers = {
-        ...import_ethers16.ethers,
+        ...import_ethers17.ethers,
         providers: {
-          StaticJsonRpcProvider: import_ethers16.ethers.JsonRpcProvider
+          StaticJsonRpcProvider: import_ethers17.ethers.JsonRpcProvider
         },
-        Contract: import_ethers16.ethers.Contract,
-        utils: import_ethers16.ethers
+        Contract: import_ethers17.ethers.Contract,
+        utils: import_ethers17.ethers
         // v6 moved utils to top level
       };
       global.Lit = {
@@ -5552,7 +5565,7 @@ var init_network_configs = __esm({
 });
 
 // src/modules/diamond-hands-sdk.ts
-import { Contract as Contract6, Interface as Interface4, JsonRpcProvider, AbiCoder as AbiCoder2, keccak256 as keccak2565, solidityPackedKeccak256 as solidityPackedKeccak2564, toUtf8Bytes as toUtf8Bytes5, getBytes as getBytes4, zeroPadValue as zeroPadValue4, toBeHex as toBeHex2, parseEther, formatEther, formatUnits, computeAddress, Signature, ZeroHash, ZeroAddress as ZeroAddress3, MaxUint256 } from "ethers";
+import { Contract as Contract6, Interface as Interface4, JsonRpcProvider, AbiCoder as AbiCoder2, keccak256 as keccak2566, solidityPackedKeccak256 as solidityPackedKeccak2565, toUtf8Bytes as toUtf8Bytes6, getBytes as getBytes5, zeroPadValue as zeroPadValue5, toBeHex as toBeHex2, parseEther, formatEther, formatUnits, computeAddress, Signature, ZeroHash, ZeroAddress as ZeroAddress3, MaxUint256 } from "ethers";
 
 // src/types/result.ts
 function success(value) {
@@ -6952,10 +6965,203 @@ async function isLaneGuardActiveOnProvider(provider) {
   }
 }
 
-// src/utils/btc-withdrawal-message.ts
-import { keccak256 as keccak2563, toUtf8Bytes as toUtf8Bytes3, solidityPackedKeccak256 as solidityPackedKeccak2563, getBytes as getBytes3, zeroPadValue } from "ethers";
+// src/utils/withdrawal-reconciliation.utils.ts
+var defaultHttpGetJson = async (url) => {
+  const res = await fetch(url, { headers: { accept: "application/json" } });
+  let body = null;
+  try {
+    body = await res.json();
+  } catch {
+    body = null;
+  }
+  return { status: res.status, body };
+};
+async function reconcileAuthorizedSpend(spend, esploraBaseUrl, httpGetJson = defaultHttpGetJson) {
+  const base = esploraBaseUrl.replace(/\/+$/, "");
+  const fundingRes = await httpGetJson(`${base}/tx/${spend.txid}`);
+  if (fundingRes.status === 404) {
+    return {
+      spend,
+      status: "UNFUNDED",
+      reason: `Funding tx ${spend.txid} not found on the network`
+    };
+  }
+  if (fundingRes.status !== 200) {
+    throw new Error(
+      `Withdrawal reconciliation: esplora /tx/${spend.txid} returned HTTP ${fundingRes.status}`
+    );
+  }
+  const funding = fundingRes.body;
+  if (!funding?.status?.confirmed) {
+    return {
+      spend,
+      status: "UNFUNDED",
+      reason: `Funding tx ${spend.txid} is not confirmed yet`
+    };
+  }
+  const output = funding.vout?.[spend.vout];
+  if (!output || typeof output.value !== "number") {
+    return {
+      spend,
+      status: "CORRUPT",
+      reason: `Authorized vout ${spend.vout} does not exist on tx ${spend.txid} (${funding.vout?.length ?? 0} outputs)`
+    };
+  }
+  const onChainOutputValue = output.value;
+  if (onChainOutputValue !== spend.satoshis) {
+    return {
+      spend,
+      status: "CORRUPT",
+      onChainOutputValue,
+      reason: `Authorization declares ${spend.satoshis} sats for ${spend.txid}:${spend.vout} but the on-chain output is ${onChainOutputValue} sats`
+    };
+  }
+  if (spend.targetAmount > onChainOutputValue) {
+    return {
+      spend,
+      status: "CORRUPT",
+      onChainOutputValue,
+      reason: `Authorized targetAmount ${spend.targetAmount} sats exceeds the ${onChainOutputValue}-sat output it is authorized against`
+    };
+  }
+  const outspendRes = await httpGetJson(
+    `${base}/tx/${spend.txid}/outspend/${spend.vout}`
+  );
+  if (outspendRes.status !== 200) {
+    throw new Error(
+      `Withdrawal reconciliation: esplora outspend for ${spend.txid}:${spend.vout} returned HTTP ${outspendRes.status}`
+    );
+  }
+  const outspend = outspendRes.body;
+  if (outspend?.spent) {
+    const spendingTxid = typeof outspend.txid === "string" && outspend.txid ? outspend.txid : null;
+    if (spendingTxid) {
+      const spendingRes = await httpGetJson(`${base}/tx/${spendingTxid}`);
+      if (spendingRes.status === 200) {
+        const spendingTx = spendingRes.body;
+        const includesOutpoint = (spendingTx.vin ?? []).some(
+          (v) => v.txid === spend.txid && Number(v.vout) === spend.vout
+        );
+        if (includesOutpoint) {
+          const paidToTargetSats = (spendingTx.vout ?? []).filter(
+            (o) => (o.scriptpubkey_address ?? "").toLowerCase() === spend.targetAddress.toLowerCase()
+          ).reduce((sum, o) => sum + (o.value ?? 0), 0);
+          if (paidToTargetSats > 0) {
+            return {
+              spend,
+              status: "EXECUTED",
+              spendingTxid,
+              paidToTargetSats,
+              onChainOutputValue,
+              reason: `Outpoint spent by ${spendingTxid}, paying ${paidToTargetSats} sats to the authorized target \u2014 withdrawal complete`
+            };
+          }
+          return {
+            spend,
+            status: "SPENT_MISMATCH",
+            spendingTxid,
+            onChainOutputValue,
+            reason: `Outpoint spent by ${spendingTxid} which pays the authorized target nothing \u2014 authorization is unexecutable`
+          };
+        }
+      }
+    }
+    return {
+      spend,
+      status: "EXECUTABLE",
+      onChainOutputValue,
+      reason: "Esplora claims the outpoint is spent but no spending tx provably includes it (known regtest-faucet artifact) \u2014 treated as unspent"
+    };
+  }
+  return {
+    spend,
+    status: "EXECUTABLE",
+    onChainOutputValue,
+    reason: "Outpoint confirmed, unspent, and coherent with the authorization"
+  };
+}
+
+// src/utils/stale-spend-invalidate-message.ts
+import {
+  keccak256 as keccak2563,
+  toUtf8Bytes as toUtf8Bytes3,
+  solidityPackedKeccak256 as solidityPackedKeccak2563,
+  getBytes as getBytes3,
+  zeroPadValue
+} from "ethers";
+var RECOVERY_INVALIDATE_ACTION = "btc-utxo-invalidator";
 var QUANTUM_SECONDS = 60;
 var QUANTUM_SAFE_THRESHOLD = 40;
+function buildInvalidateMessageHash(params) {
+  const positionIdBytes32 = zeroPadValue(
+    params.positionId.startsWith("0x") ? params.positionId : `0x${params.positionId}`,
+    32
+  );
+  const actionHash = keccak2563(toUtf8Bytes3(RECOVERY_INVALIDATE_ACTION));
+  return solidityPackedKeccak2563(
+    [
+      "bytes32",
+      // positionId
+      "uint256",
+      // timestamp
+      "uint256",
+      // chainId
+      "string",
+      // utxoTxid (display order)
+      "uint32",
+      // utxoVout
+      "bytes32"
+      // actionHash
+    ],
+    [
+      positionIdBytes32,
+      params.timestamp,
+      params.chainId,
+      params.utxoTxid,
+      params.utxoVout,
+      actionHash
+    ]
+  );
+}
+async function buildInvalidateStaleSpendEnvelope(params) {
+  const { positionId, utxoTxid, utxoVout, chainId, signer } = params;
+  const nowSec = Date.now() / 1e3;
+  const currentQuantumStart = Math.floor(nowSec / QUANTUM_SECONDS) * QUANTUM_SECONDS;
+  const secsIntoQuantum = nowSec - currentQuantumStart;
+  let timestamp;
+  if (secsIntoQuantum > QUANTUM_SAFE_THRESHOLD) {
+    const nextQuantumStart = currentQuantumStart + QUANTUM_SECONDS;
+    const waitMs = Math.max(0, (nextQuantumStart - nowSec) * 1e3 + 500);
+    await new Promise((r) => setTimeout(r, waitMs));
+    timestamp = nextQuantumStart;
+  } else {
+    timestamp = currentQuantumStart;
+  }
+  const messageHash = buildInvalidateMessageHash({
+    positionId,
+    timestamp,
+    chainId,
+    utxoTxid,
+    utxoVout
+  });
+  const signature = await signer.signMessage(getBytes3(messageHash));
+  const borrowerAddress = await signer.getAddress();
+  return {
+    positionId,
+    utxoTxid,
+    utxoVout,
+    timestamp,
+    chainId,
+    action: RECOVERY_INVALIDATE_ACTION,
+    signature,
+    borrowerAddress
+  };
+}
+
+// src/utils/btc-withdrawal-message.ts
+import { keccak256 as keccak2564, toUtf8Bytes as toUtf8Bytes4, solidityPackedKeccak256 as solidityPackedKeccak2564, getBytes as getBytes4, zeroPadValue as zeroPadValue2 } from "ethers";
+var QUANTUM_SECONDS2 = 60;
+var QUANTUM_SAFE_THRESHOLD2 = 40;
 function hashBtcInputSet(utxos) {
   if (!Array.isArray(utxos) || utxos.length === 0) {
     throw new Error("hashBtcInputSet: at least one input is required");
@@ -6984,7 +7190,7 @@ function hashBtcInputSet(utxos) {
     seen.add(key);
   }
   const canonical = normalized.sort((a, b) => a.txid < b.txid ? -1 : a.txid > b.txid ? 1 : a.vout - b.vout).map((u) => `${u.txid}:${u.vout}:${u.value}`).join("|");
-  return keccak2563(toUtf8Bytes3(canonical));
+  return keccak2564(toUtf8Bytes4(canonical));
 }
 async function buildBtcExecuteEnvelope(params) {
   const {
@@ -7018,26 +7224,26 @@ async function buildBtcExecuteEnvelope(params) {
   }
   const utxosHash = hashBtcInputSet(utxos);
   const nowSec = Date.now() / 1e3;
-  const currentQuantumStart = Math.floor(nowSec / QUANTUM_SECONDS) * QUANTUM_SECONDS;
+  const currentQuantumStart = Math.floor(nowSec / QUANTUM_SECONDS2) * QUANTUM_SECONDS2;
   const secsIntoQuantum = nowSec - currentQuantumStart;
   let timestamp;
-  if (secsIntoQuantum > QUANTUM_SAFE_THRESHOLD) {
-    const nextQuantumStart = currentQuantumStart + QUANTUM_SECONDS;
+  if (secsIntoQuantum > QUANTUM_SAFE_THRESHOLD2) {
+    const nextQuantumStart = currentQuantumStart + QUANTUM_SECONDS2;
     const waitMs = Math.max(0, (nextQuantumStart - nowSec) * 1e3 + 500);
     await new Promise((r) => setTimeout(r, waitMs));
     timestamp = nextQuantumStart;
   } else {
     timestamp = currentQuantumStart;
   }
-  const actionHash = keccak2563(
-    toUtf8Bytes3("execute-btc-withdrawal")
+  const actionHash = keccak2564(
+    toUtf8Bytes4("execute-btc-withdrawal")
   );
   const utxoIdentifier = `${txid}:${vout}`;
-  const positionIdBytes32 = zeroPadValue(
+  const positionIdBytes32 = zeroPadValue2(
     positionId.startsWith("0x") ? positionId : `0x${positionId}`,
     32
   );
-  const messageHash = solidityPackedKeccak2563(
+  const messageHash = solidityPackedKeccak2564(
     [
       "bytes32",
       // positionId
@@ -7070,7 +7276,7 @@ async function buildBtcExecuteEnvelope(params) {
       actionHash
     ]
   );
-  const userSignature = await signer.signMessage(getBytes3(messageHash));
+  const userSignature = await signer.signMessage(getBytes4(messageHash));
   const borrowerAddress = await signer.getAddress();
   return {
     positionId,
@@ -7134,7 +7340,7 @@ function maybeTemperSignature(signature, shouldTemper, operationName) {
 }
 
 // src/utils/address-conversion.utils.ts
-import { zeroPadValue as zeroPadValue2 } from "ethers";
+import { zeroPadValue as zeroPadValue3 } from "ethers";
 
 // src/utils/chunks/bitcoin-utils.ts
 import { sha256 as nobleSha256 } from "@noble/hashes/sha256";
@@ -8718,7 +8924,7 @@ function createPKPManager(config) {
 }
 
 // src/modules/loan/loan-creator.module.ts
-import { Interface as Interface2, zeroPadValue as zeroPadValue3, toBeHex, SigningKey } from "ethers";
+import { Interface as Interface2, zeroPadValue as zeroPadValue4, toBeHex, SigningKey } from "ethers";
 var import_dh_lit_actions = __toESM(require_pkg_src());
 var LoanCreator = class {
   config;
@@ -9048,7 +9254,7 @@ var LoanCreator = class {
     try {
       const mainnetVaultAddress = bitcoinAddresses.mainnet;
       const regtestVaultAddress = bitcoinAddresses.regtest;
-      const pkpIdBytes32 = zeroPadValue3(
+      const pkpIdBytes32 = zeroPadValue4(
         toBeHex(BigInt(pkpData.tokenId)),
         32
       );
@@ -9229,7 +9435,7 @@ var LoanCreator = class {
         }
       }
       if (this.config.debug) {
-        const pkpIdBytes32Check = zeroPadValue3(
+        const pkpIdBytes32Check = zeroPadValue4(
           toBeHex(BigInt(pkpData.tokenId)),
           32
         );
@@ -9992,7 +10198,7 @@ function createLoanQuery(config) {
 }
 
 // src/modules/withdrawal-address/withdrawal-address.module.ts
-import { keccak256 as keccak2564, toUtf8Bytes as toUtf8Bytes4, ZeroAddress as ZeroAddress2 } from "ethers";
+import { keccak256 as keccak2565, toUtf8Bytes as toUtf8Bytes5, ZeroAddress as ZeroAddress2 } from "ethers";
 var WithdrawalAddressModule = class {
   config;
   graphClient;
@@ -10027,7 +10233,7 @@ var WithdrawalAddressModule = class {
   }
   /** keccak256 of the canonicalized address — matches the on-chain key. */
   static addressHash(btcAddress) {
-    return keccak2564(toUtf8Bytes4(normalizeBitcoinAddress(btcAddress)));
+    return keccak2565(toUtf8Bytes5(normalizeBitcoinAddress(btcAddress)));
   }
   /**
    * Add a Bitcoin address to the caller's allowlist. It becomes usable only
@@ -17476,8 +17682,8 @@ var DiamondHandsSDK = class _DiamondHandsSDK {
         throw new Error(`Position not found: ${request.positionId}`);
       }
       const currentDebt = position.ucdDebt.toString();
-      const ucdDebtHash = keccak2565(AbiCoder2.defaultAbiCoder().encode(["uint256"], [currentDebt]));
-      const contractHash = keccak2565(AbiCoder2.defaultAbiCoder().encode(
+      const ucdDebtHash = keccak2566(AbiCoder2.defaultAbiCoder().encode(["uint256"], [currentDebt]));
+      const contractHash = keccak2566(AbiCoder2.defaultAbiCoder().encode(
         ["address", "address", "address", "address"],
         [
           positionManagerAddress,
@@ -17554,7 +17760,7 @@ var DiamondHandsSDK = class _DiamondHandsSDK {
         const currentPosition = await positionCore["getPositionDetails"](
           positionIdBytes32
         );
-        const currentDebtHash = keccak2565(
+        const currentDebtHash = keccak2566(
           AbiCoder2.defaultAbiCoder().encode(
             ["uint256"],
             [currentPosition.ucdDebt]
@@ -21290,7 +21496,7 @@ Message: ${causeMessage}${quantumContext}${mintDebtDiagnostics}`
    * been broadcast to the Bitcoin network. An empty array means no pending withdrawals.
    *
    * @param positionId - Position identifier
-   * @returns Array of pending withdrawals, each including a pre-computed utxoKey for use with cancelPendingWithdrawal
+   * @returns Array of pending withdrawals, each including a pre-computed utxoKey (the key recoverStaleSpend and the admin clearing path operate on)
    */
   async getPendingWithdrawals(positionId) {
     this.ensureInitialized();
@@ -21322,24 +21528,58 @@ Message: ${causeMessage}${quantumContext}${mintDebtDiagnostics}`
       targetAddress: spend.targetAddress,
       targetAmount: Number(spend.targetAmount),
       authorizedAt: Number(spend.authorizedAt),
-      utxoKey: solidityPackedKeccak2564(
+      utxoKey: solidityPackedKeccak2565(
         ["string", "uint32"],
         [spend.txid, Number(spend.vout)]
       )
     }));
   }
   /**
-   * Cancel a pending BTC withdrawal
-   *
-   * Removes a stale authorized spend from BTCSpendAuthorizer, unlocking the UTXO
-   * and allowing the borrower to retry the withdrawal from scratch.
-   * Only the position's borrower may call this — requires a connected signer.
+   * Reconcile every pending withdrawal against BITCOIN truth (incident
+   * 2026-07-22): `getPendingWithdrawals` only reflects on-chain
+   * authorizations, and the contract can never know whether the Phase-2 BTC
+   * broadcast happened. Callers MUST use the returned `status` to decide what
+   * to offer:
+   * - EXECUTABLE      → offer Execute (the only status that may).
+   * - EXECUTED        → auto-clear; `spendingTxid` is the completion proof —
+   *                     feed it to recoverStaleSpend to clear the reservation.
+   * - SPENT_MISMATCH  → unexecutable; recoverStaleSpend with the spending txid
+   *                     as invalidator clears the reservation.
+   * - CORRUPT         → authorization contradicts the chain (e.g. declared
+   *                     satoshis ≠ real output value); Execute can only die at
+   *                     the signer guard, and no borrower-side cancel exists
+   *                     (audit #62210) — clearing needs the AdminModule
+   *                     cancelStaleSpendByAdmin operator override.
+   * - UNFUNDED        → funding tx unknown/unconfirmed; wait.
    *
-   * @param positionId - Position identifier
-   * @param txid - Bitcoin UTXO transaction ID (from getPendingWithdrawals)
-   * @param vout - Output index (from getPendingWithdrawals)
-   * @returns Transaction hash of the cancellation EVM transaction
+   * @param opts.esploraBaseUrl Esplora API base (e.g. the api proxy
+   *   `/v1/proxy/esplora/<network>`). Falls back to
+   *   `config.bitcoinProviders[0].url`; throws when neither is configured.
    */
+  async reconcilePendingWithdrawals(positionId, opts) {
+    this.ensureInitialized();
+    const esploraBaseUrl = opts?.esploraBaseUrl ?? this.config.bitcoinProviders?.[0]?.url;
+    if (!esploraBaseUrl) {
+      throw new SDKError({
+        code: "SDK_ESPLORA_NOT_CONFIGURED",
+        message: "reconcilePendingWithdrawals requires opts.esploraBaseUrl or config.bitcoinProviders[0].url",
+        category: "CONFIGURATION" /* CONFIGURATION */,
+        severity: "HIGH" /* HIGH */,
+        originalError: new Error("esplora base URL not configured")
+      });
+    }
+    const spends = await this.getPendingWithdrawals(positionId);
+    return Promise.all(
+      spends.map((spend) => reconcileAuthorizedSpend(spend, esploraBaseUrl))
+    );
+  }
+  // NOTE: there is deliberately no cancelPendingWithdrawal. Borrower-callable
+  // cleanup was permanently disabled by audit #62210 (markSpentByOwner /
+  // cancelStaleSpendByOwner revert with BorrowerBTCSpendMutationDisabled — a
+  // borrower cancel could be replayed to mint UCD against the same UTXO).
+  // Reservations clear via recoverStaleSpend below (trustless attestation once
+  // the UTXO is provably consumed) or the AdminModule-timelocked
+  // cancelStaleSpendByAdmin operator override.
   /**
    * Recover (clear) a stale BTC reservation via LIT-attested proof.
    *
@@ -21491,6 +21731,256 @@ Message: ${causeMessage}${quantumContext}${mintDebtDiagnostics}`
       };
     }
   }
+  /**
+   * Sign + broadcast the PKP vault→vault self-spend that invalidates one
+   * stuck authorized outpoint (btc-utxo-invalidator 1.0.0). Once the returned
+   * `invalidatorTxid` reaches >=6 Bitcoin confirmations, `recoverStaleSpend`
+   * clears the on-chain reservation — the trustless replacement for the
+   * AdminModule cancelStaleSpendByAdmin path on unspent stuck/corrupt
+   * reservations (incident 2026-07-22). Requires the borrower (or position
+   * delegate) signer; the signature is scoped to exactly this outpoint.
+   */
+  async invalidateStaleSpend(params) {
+    this.ensureInitialized();
+    const chainId = this.config.chainId ?? this.config.networkOverride?.chainId;
+    if (!chainId) {
+      return {
+        success: false,
+        failedStep: "config",
+        error: "chainId required for invalidateStaleSpend"
+      };
+    }
+    const signer = this.getSignerOrThrow();
+    const envelope = await buildInvalidateStaleSpendEnvelope({
+      positionId: params.positionId,
+      utxoTxid: params.utxoTxid,
+      utxoVout: params.utxoVout,
+      chainId,
+      signer
+    });
+    if (this.config.mode === "service" && this.config.serviceEndpoint) {
+      const headers = {
+        "Content-Type": "application/json",
+        ...await this.getAuthHeader()
+      };
+      const resp = await fetch(
+        `${this.config.serviceEndpoint}/api/lit/stale-spend/invalidate`,
+        {
+          method: "POST",
+          headers,
+          body: JSON.stringify({
+            positionId: this.toBytes32(params.positionId),
+            utxoTxid: params.utxoTxid,
+            utxoVout: params.utxoVout,
+            chainId,
+            auth: {
+              timestamp: envelope.timestamp,
+              action: envelope.action,
+              signature: envelope.signature
+            }
+          })
+        }
+      );
+      const json = await resp.json();
+      return json.data ?? {
+        success: false,
+        error: json.error ?? "stale-spend invalidate request failed"
+      };
+    }
+    const rpcUrl = params.rpcUrl ?? this.config.ethRpcUrl;
+    if (!rpcUrl) {
+      return {
+        success: false,
+        failedStep: "config",
+        error: "ethRpcUrl required for invalidateStaleSpend \u2014 set DiamondHandsSDKConfig.ethRpcUrl or pass rpcUrl"
+      };
+    }
+    const positionDetails = await this.getPositionDetailsView(
+      params.positionId
+    );
+    if (!positionDetails?.pkpId || positionDetails.pkpId === ZeroHash) {
+      return { success: false, error: "Position has no PKP" };
+    }
+    const pkpCache = this.cacheManager.getCache("pkp-data", {
+      maxSize: 500,
+      ttlMs: 24 * 60 * 60 * 1e3
+    });
+    let publicKey = pkpCache.get(params.positionId)?.publicKey;
+    if (!publicKey) {
+      const derived = await this.litOps.deriveDiamondHandsLoanPkpPublicKey({
+        pkpId: positionDetails.pkpId
+      });
+      publicKey = derived.publicKey;
+    }
+    if (!publicKey) {
+      return { success: false, error: "Failed to resolve PKP public key" };
+    }
+    const chipotlePkpAddress = computeAddress(publicKey);
+    const dc = this.config.contractAddresses || {};
+    const chainName = chainId === 1 ? "ethereum" : chainId === 11155111 ? "sepolia" : chainId === 1337 || chainId === 31337 ? "hardhat" : void 0;
+    if (!chainName) {
+      return {
+        success: false,
+        error: `Unsupported chainId ${chainId} for invalidateStaleSpend (supported: 1, 11155111, 1337, 31337)`
+      };
+    }
+    const signResult = await this.litOps.signBtcUtxoInvalidator({
+      auth: {
+        positionId: this.toBytes32(params.positionId),
+        utxoTxid: params.utxoTxid,
+        utxoVout: params.utxoVout,
+        timestamp: envelope.timestamp,
+        chainId,
+        action: envelope.action,
+        signature: envelope.signature
+      },
+      publicKey,
+      pkpId: chipotlePkpAddress,
+      chain: chainName,
+      rpcUrl,
+      ...this.config.bitcoinProviders?.[0]?.url && (chainId === 1337 || chainId === 31337) ? { devBitcoinProviderUrl: this.config.bitcoinProviders[0].url } : {},
+      contractAddresses: {
+        PositionManager: dc.positionManager ?? "",
+        BTCSpendAuthorizer: dc.btcSpendAuthorizer ?? "",
+        ...dc.bitcoinProviderRegistry ? { BitcoinProviderRegistry: dc.bitcoinProviderRegistry } : {},
+        ...dc.positionDelegateRegistry ? { PositionDelegateRegistry: dc.positionDelegateRegistry } : {}
+      }
+    });
+    if (!signResult.success) {
+      return {
+        success: false,
+        error: signResult.error ?? "btc-utxo-invalidator signing failed",
+        failedStep: signResult.failedStep
+      };
+    }
+    if (signResult.alreadySpent && typeof signResult.alreadySpent === "object") {
+      return {
+        success: true,
+        alreadySpent: { spendingTxid: signResult.alreadySpent.spendingTxid }
+      };
+    }
+    if (!signResult.signatures?.length || !signResult.utxo || !signResult.pkpBtcAddress || typeof signResult.invalidatorAmount !== "number") {
+      return {
+        success: false,
+        error: "btc-utxo-invalidator returned incomplete data (signatures/utxo/pkpBtcAddress/invalidatorAmount)"
+      };
+    }
+    const broadcastUrl = this.config.bitcoinProviders?.[0]?.url;
+    if (!broadcastUrl) {
+      return {
+        success: false,
+        error: "invalidateStaleSpend broadcast requires config.bitcoinProviders[0].url (esplora base)"
+      };
+    }
+    const { txid: invalidatorTxid } = await broadcastSignedBitcoinTransaction({
+      signatures: signResult.signatures,
+      utxos: [signResult.utxo],
+      pkpPublicKey: signResult.pkpPublicKey ?? publicKey,
+      destination: signResult.pkpBtcAddress,
+      userReceivesAmount: signResult.invalidatorAmount,
+      changeAmount: 0,
+      pkpBtcAddress: signResult.pkpBtcAddress,
+      bitcoinNetwork: chainId === 1 ? "mainnet" : "regtest",
+      bitcoinRpcUrl: broadcastUrl
+    });
+    return {
+      success: true,
+      invalidatorTxid,
+      invalidatorAmount: signResult.invalidatorAmount,
+      networkFee: signResult.networkFee,
+      valueMismatch: signResult.valueMismatch
+    };
+  }
+  /**
+   * Resumable, stateless clearing state machine for one stuck reservation —
+   * Bitcoin itself is the state store, so every call either advances the flow
+   * one step or reports where it stands (survives reloads and the multi-day
+   * 6-confirmation wait; no internal polling).
+   *
+   *  (a) reservation gone            → phase "cleared"
+   *  (b) outpoint spent, >=6 confs   → recoverStaleSpend → "cleared"/"failed"
+   *      outpoint spent, <6 confs    → "awaiting-confirmations" (x/6)
+   *  (c) outpoint unspent            → invalidateStaleSpend → "invalidator-broadcast"
+   */
+  async clearStuckReservation(params) {
+    this.ensureInitialized();
+    const REQUIRED_CONFS = 6;
+    const esploraBaseUrl = params.esploraBaseUrl ?? this.config.bitcoinProviders?.[0]?.url;
+    const reconciled = await this.reconcilePendingWithdrawals(
+      params.positionId,
+      esploraBaseUrl ? { esploraBaseUrl } : void 0
+    );
+    const row = reconciled.find(
+      (r) => r.spend.txid.toLowerCase() === params.utxoTxid.toLowerCase() && r.spend.vout === params.utxoVout
+    );
+    if (!row) {
+      return { phase: "cleared" };
+    }
+    if (row.spendingTxid && esploraBaseUrl) {
+      const base = esploraBaseUrl.replace(/\/+$/, "");
+      const txRes = await fetch(`${base}/tx/${row.spendingTxid}`);
+      const tipRes = await fetch(`${base}/blocks/tip/height`);
+      let confirmations = 0;
+      if (txRes.ok && tipRes.ok) {
+        const tx = await txRes.json();
+        const tip = Number(await tipRes.text());
+        if (tx.status?.confirmed && typeof tx.status.block_height === "number" && Number.isFinite(tip)) {
+          confirmations = Math.max(0, tip - tx.status.block_height + 1);
+        }
+      }
+      if (confirmations < REQUIRED_CONFS) {
+        return {
+          phase: "awaiting-confirmations",
+          invalidatorTxid: row.spendingTxid,
+          confirmations,
+          required: REQUIRED_CONFS
+        };
+      }
+      const recovery = await this.recoverStaleSpend({
+        positionId: params.positionId,
+        utxoTxid: params.utxoTxid,
+        utxoVout: params.utxoVout,
+        invalidatorTxid: row.spendingTxid
+      });
+      if (recovery.success) {
+        return {
+          phase: "cleared",
+          invalidatorTxid: row.spendingTxid,
+          transactionHash: recovery.transactionHash,
+          classification: recovery.classification
+        };
+      }
+      return {
+        phase: "failed",
+        invalidatorTxid: row.spendingTxid,
+        error: recovery.error ?? "stale-spend recovery failed"
+      };
+    }
+    const invalidation = await this.invalidateStaleSpend({
+      positionId: params.positionId,
+      utxoTxid: params.utxoTxid,
+      utxoVout: params.utxoVout
+    });
+    if (!invalidation.success) {
+      return {
+        phase: "failed",
+        error: invalidation.error ?? "invalidator signing/broadcast failed"
+      };
+    }
+    if (invalidation.alreadySpent) {
+      return {
+        phase: "awaiting-confirmations",
+        invalidatorTxid: invalidation.alreadySpent.spendingTxid,
+        confirmations: 0,
+        required: REQUIRED_CONFS
+      };
+    }
+    return {
+      phase: "invalidator-broadcast",
+      invalidatorTxid: invalidation.invalidatorTxid,
+      valueMismatch: invalidation.valueMismatch
+    };
+  }
   /**
    * Withdraw BTC and execute transfer (Complete Flow)
    *
@@ -22581,7 +23071,7 @@ Message: ${causeMessage}${quantumContext}${mintDebtDiagnostics}`
    * Convert decimal position ID to bytes32 format
    */
   toBytes32(value) {
-    return zeroPadValue4(toBeHex2(BigInt(value)), 32);
+    return zeroPadValue5(toBeHex2(BigInt(value)), 32);
   }
   /**
    * Check if an error indicates a technical failure vs business logic rejection
@@ -22799,8 +23289,8 @@ Message: ${causeMessage}${quantumContext}${mintDebtDiagnostics}`
     const MIN_REVEAL_DELAY = 60;
     const MAX_RANDOM_DELAY = 240;
     const entropyInput = positionId + quantumTimestamp.toString();
-    const hash = keccak2565(
-      toUtf8Bytes5(entropyInput)
+    const hash = keccak2566(
+      toUtf8Bytes6(entropyInput)
     );
     const randomValue = BigInt(hash);
     const randomDelay = Number(randomValue % BigInt(MAX_RANDOM_DELAY));
@@ -22825,12 +23315,12 @@ Message: ${causeMessage}${quantumContext}${mintDebtDiagnostics}`
     const rawPositionId = /^0x/i.test(params.positionId.trim()) ? params.positionId.trim().slice(2) : params.positionId.trim();
     const canonicalPositionId = "0x" + rawPositionId.padStart(64, "0").toLowerCase();
     const intentTimestamp = Math.floor(Date.now() / 1e3);
-    const intentActionHash = keccak2565(toUtf8Bytes5("liquidate-position"));
-    const intentHash = solidityPackedKeccak2564(
+    const intentActionHash = keccak2566(toUtf8Bytes6("liquidate-position"));
+    const intentHash = solidityPackedKeccak2565(
       ["bytes32", "uint256", "uint256", "address", "bytes32"],
       [canonicalPositionId, intentTimestamp, chainId, intentSigner, intentActionHash]
     );
-    const intentSignature = await signer.signMessage(getBytes4(intentHash));
+    const intentSignature = await signer.signMessage(getBytes5(intentHash));
     const response = await fetch(endpoint, {
       method: "POST",
       headers: { "Content-Type": "application/json" },
@@ -22882,7 +23372,7 @@ Message: ${causeMessage}${quantumContext}${mintDebtDiagnostics}`
         const vrfSeedRaw = await lmResult.value["vrfSeeds"](positionId);
         const vrfSeed = BigInt(vrfSeedRaw.toString());
         if (vrfSeed !== 0n) {
-          const finalEntropy = solidityPackedKeccak2564(
+          const finalEntropy = solidityPackedKeccak2565(
             ["uint256", "uint256", "bytes32"],
             [vrfSeed, BigInt(quantumTimestamp.toString()), positionId]
           );
@@ -23203,6 +23693,7 @@ export {
   PKPManager,
   PaymentType,
   PositionStatus,
+  RECOVERY_INVALIDATE_ACTION,
   SDKError,
   SDK_DEFAULTS,
   SEPOLIA_CONTRACTS,
@@ -23215,6 +23706,8 @@ export {
   assertProtocolNotPaused,
   assertSafeServiceEndpoint,
   buildBtcExecuteEnvelope,
+  buildInvalidateMessageHash,
+  buildInvalidateStaleSpendEnvelope,
   collectFailures,
   collectSuccesses,
   combine,
@@ -23226,6 +23719,7 @@ export {
   createPKPManager,
   createWithdrawalAddressModule,
   DiamondHandsSDK as default,
+  defaultHttpGetJson,
   failure,
   fetchProtocolPauseStatus,
   firstSuccess,
@@ -23249,6 +23743,7 @@ export {
   mapError,
   match,
   numericToPositionStatus,
+  reconcileAuthorizedSpend,
   setPositionDelegate,
   success,
   toPromise,