@gvnrdao/dh-sdk 0.0.307 → 0.0.309

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) {
@@ -6413,7 +6426,7 @@ async function generateExtendAuthorization(positionId, newTerm, chainId, signerO
 import { hexlify, randomBytes } from "ethers";
 function buildLoginDomain(chainId) {
   return {
-    name: "Diamond Hands lit-ops-server",
+    name: "Diamond Hands",
     version: "1",
     chainId
   };
@@ -6528,6 +6541,8 @@ function createDefaultSessionStore() {
 
 // src/utils/server-session.ts
 var REFRESH_LEEWAY_SECONDS = 30;
+var LOGIN_RETRY_BASE_MS = 3e4;
+var LOGIN_RETRY_MAX_MS = 5 * 6e4;
 var ServerLoginError = class extends Error {
   constructor(message, status) {
     super(message);
@@ -6548,6 +6563,11 @@ var ServerSession = class {
   fetchImpl;
   cached = null;
   inFlight = null;
+  /**
+   * Set when a prompted login failed; suppresses further prompts until `until`.
+   * `error` is replayed to callers so they still see the real failure reason.
+   */
+  promptBackoff = null;
   /**
    * Bumped by `clearPersisted()` (logout / disconnect). An in-flight
    * `getOrRefresh()` captures this at start and refuses to write its freshly
@@ -6622,6 +6642,7 @@ var ServerSession = class {
     this.generation += 1;
     this.cached = null;
     this.inFlight = null;
+    this.promptBackoff = null;
     if (!this.store)
       return;
     try {
@@ -6718,19 +6739,39 @@ var ServerSession = class {
     this.inFlight = (async () => {
       try {
         const existing = await this.tryResolveSilently(gen);
-        if (existing)
+        if (existing) {
+          this.promptBackoff = null;
           return existing;
+        }
+        if (this.promptBackoff && this.now() * 1e3 < this.promptBackoff.until) {
+          throw this.promptBackoff.error;
+        }
         this.onSignaturePrompt?.();
-        const payload = await buildSignedLoginPayload(
-          this.signer,
-          this.chainId,
-          this.serviceEndpoint
-        );
-        const session = await this.login(payload);
-        if (notCleared()) {
-          this.persist(payload, session);
-          this.cached = session;
+        let session;
+        try {
+          const payload = await buildSignedLoginPayload(
+            this.signer,
+            this.chainId,
+            this.serviceEndpoint
+          );
+          session = await this.login(payload);
+          if (notCleared()) {
+            this.persist(payload, session);
+            this.cached = session;
+          }
+        } catch (error) {
+          const failures = (this.promptBackoff?.failures ?? 0) + 1;
+          this.promptBackoff = {
+            failures,
+            error,
+            until: this.now() * 1e3 + Math.min(
+              LOGIN_RETRY_BASE_MS * 2 ** (failures - 1),
+              LOGIN_RETRY_MAX_MS
+            )
+          };
+          throw error;
         }
+        this.promptBackoff = null;
         return session;
       } finally {
         if (notCleared())
@@ -7068,10 +7109,87 @@ async function reconcileAuthorizedSpend(spend, esploraBaseUrl, httpGetJson = def
   };
 }
 
-// src/utils/btc-withdrawal-message.ts
-import { keccak256 as keccak2563, toUtf8Bytes as toUtf8Bytes3, solidityPackedKeccak256 as solidityPackedKeccak2563, getBytes as getBytes3, zeroPadValue } from "ethers";
+// 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");
@@ -7100,7 +7218,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 {
@@ -7134,26 +7252,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
@@ -7186,7 +7304,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,
@@ -7250,7 +7368,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";
@@ -8834,7 +8952,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;
@@ -9164,7 +9282,7 @@ var LoanCreator = class {
     try {
       const mainnetVaultAddress = bitcoinAddresses.mainnet;
       const regtestVaultAddress = bitcoinAddresses.regtest;
-      const pkpIdBytes32 = zeroPadValue3(
+      const pkpIdBytes32 = zeroPadValue4(
         toBeHex(BigInt(pkpData.tokenId)),
         32
       );
@@ -9345,7 +9463,7 @@ var LoanCreator = class {
         }
       }
       if (this.config.debug) {
-        const pkpIdBytes32Check = zeroPadValue3(
+        const pkpIdBytes32Check = zeroPadValue4(
           toBeHex(BigInt(pkpData.tokenId)),
           32
         );
@@ -10108,7 +10226,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;
@@ -10143,7 +10261,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
@@ -17592,8 +17710,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,
@@ -17670,7 +17788,7 @@ var DiamondHandsSDK = class _DiamondHandsSDK {
         const currentPosition = await positionCore["getPositionDetails"](
           positionIdBytes32
         );
-        const currentDebtHash = keccak2565(
+        const currentDebtHash = keccak2566(
           AbiCoder2.defaultAbiCoder().encode(
             ["uint256"],
             [currentPosition.ucdDebt]
@@ -21406,7 +21524,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();
@@ -21438,7 +21556,7 @@ 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)]
       )
@@ -21451,11 +21569,15 @@ Message: ${causeMessage}${quantumContext}${mintDebtDiagnostics}`
    * 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.
-   * - SPENT_MISMATCH  → unexecutable; offer cancelPendingWithdrawal.
+   * - 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); offer Cancel &
-   *                     re-request — Execute can only die at the signer guard.
+   *                     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 opts.esploraBaseUrl Esplora API base (e.g. the api proxy
@@ -21479,18 +21601,13 @@ Message: ${causeMessage}${quantumContext}${mintDebtDiagnostics}`
       spends.map((spend) => reconcileAuthorizedSpend(spend, esploraBaseUrl))
     );
   }
-  /**
-   * 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.
-   *
-   * @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
-   */
+  // 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.
    *
@@ -21642,6 +21759,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)
    *
@@ -22732,7 +23099,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
@@ -22950,8 +23317,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));
@@ -22976,12 +23343,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" },
@@ -23033,7 +23400,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]
           );
@@ -23354,6 +23721,7 @@ export {
   PKPManager,
   PaymentType,
   PositionStatus,
+  RECOVERY_INVALIDATE_ACTION,
   SDKError,
   SDK_DEFAULTS,
   SEPOLIA_CONTRACTS,
@@ -23366,6 +23734,8 @@ export {
   assertProtocolNotPaused,
   assertSafeServiceEndpoint,
   buildBtcExecuteEnvelope,
+  buildInvalidateMessageHash,
+  buildInvalidateStaleSpendEnvelope,
   collectFailures,
   collectSuccesses,
   combine,