@gvnrdao/dh-sdk 0.0.323 → 0.0.327

package/dist/index.js

@@ -354,7 +354,7 @@ var init_deployment_addresses = __esm({
         CARRY_AGENT_REGISTRY: "0x5595CB538D44E6Cf179D20364fD631D0477e69f7",
         CARRY_AGENT_REGISTRY_IMPL: "0x1b11a3D5e46F3672E643c997f0d569DFf0b64a01",
         AGENT_DELEGATION_REGISTRY: "0x6AE7fc6bE0925126b9D25b1B7Ce5AD5d127ec025",
-        AGENT_DELEGATION_REGISTRY_IMPL: "0x80C47350274513688e348D02506477A96B4afCCb",
+        AGENT_DELEGATION_REGISTRY_IMPL: "0xE931E4b9ceF2A48Ac7D57192da4B523756cFC310",
         DH_AGENT_DELEGATE: "0xa5A14489ae883960df6E1463A41a47aBE9Ecc5AF"
       }
     };
@@ -624,7 +624,7 @@ var init_deployment_addresses = __esm({
     LOCALHOST_DEPLOYMENT = {
       network: "localhost",
       chainId: 1337,
-      timestamp: "2026-07-23T17:13:42.777Z",
+      timestamp: "2026-07-20T19:45:58.514Z",
       deployer: "",
       contracts: {
         MessageHashBuilder: "0xa82fF9aFd8f496c3d6ac40E2a0F282E47488CFc9",
@@ -644,30 +644,6 @@ var init_deployment_addresses = __esm({
         PositionManager: "0x851356ae760d987E095750cCeb3bC6014560891C",
         OperationAuthorizationRegistry: "0xc96304e3c037f81dA488ed9dEa1D8F2a48278a75",
         PKPValidation: "0xD0141E899a65C95a556fE2B27e5982A6DE7fDD7A"
-      },
-      latestEnv: {
-        UCD_TOKEN: "0xe7f1725E7734CE288F8367e1Bb143E90bb3F0512",
-        UCD_CONTROLLER: "0xCf7Ed3AccA5a467e9e704C703E8D87F634fB0Fc9",
-        POSITION_MANAGER: "0x851356ae760d987E095750cCeb3bC6014560891C",
-        PKP_VALIDATION_REGISTRY: "0xD0141E899a65C95a556fE2B27e5982A6DE7fDD7A",
-        PKP_VALIDATION_CID_V1: "0x12203af2054b0ab6e18d898ddfc7985593439fb82d22336133387c1169f98d3702ab",
-        PKP_VALIDATION_CID_V3: "0x12203af2054b0ab6e18d898ddfc7985593439fb82d22336133387c1169f98d3702ab",
-        PKP_ETH_ADDRESS: "0x406f6a9855de2f5577b1525f0600461f02859bd0",
-        OPERATION_AUTHORIZATION_REGISTRY: "0xc96304e3c037f81dA488ed9dEa1D8F2a48278a75",
-        UCD_MINT_VALIDATOR_ADDRESS: "0x406f6a9855de2f5577b1525f0600461f02859bd0",
-        UCD_MINT_VALIDATOR_VERSION: 1,
-        BTC_WITHDRAWAL_VALIDATOR_ADDRESS: "0x406f6a9855de2f5577b1525f0600461f02859bd0",
-        BTC_WITHDRAWAL_VALIDATOR_VERSION: 3,
-        UPDATE_BALANCE_VALIDATOR_ADDRESS: "0x406f6a9855de2f5577b1525f0600461f02859bd0",
-        UPDATE_BALANCE_VALIDATOR_VERSION: 1,
-        PROCESS_PAYMENT_VALIDATOR_ADDRESS: "0x406f6a9855de2f5577b1525f0600461f02859bd0",
-        PROCESS_PAYMENT_VALIDATOR_VERSION: 1,
-        EXTEND_POSITION_VALIDATOR_ADDRESS: "0x406f6a9855de2f5577b1525f0600461f02859bd0",
-        EXTEND_POSITION_VALIDATOR_VERSION: 1,
-        POSITION_MANAGER_CORE_MODULE: "0xB7f8BC63BbcaD18155201308C8f3540b07f84F5e",
-        LOAN_OPERATIONS_MANAGER_MODULE: "0x68B1D87F95878fE05B998F19b66F4baba5De1aed",
-        TERM_MANAGER_MODULE: "0x0DCd1Bf9A1b36cE34237eEaFef220932846BCD82",
-        COMMUNITY_MANAGER_MODULE: ""
       }
     };
     LOCALHOST_CONTRACTS = {
@@ -1379,30 +1355,30 @@ var require_pkg_src = __commonJS({
         }
       },
       btcTransactionSigner: {
-        cid: "QmPncBUbxN9giWntJcvBMFW9GDAgA3DwgAkUAHxSsY67ic",
+        cid: "QmakWzTce8NH1Jkgv1xwg83Bg9WmF2UG1Mq76pDYDSwwUp",
         authorizedCidHex: cidToHex(
-          "QmPncBUbxN9giWntJcvBMFW9GDAgA3DwgAkUAHxSsY67ic"
+          "QmakWzTce8NH1Jkgv1xwg83Bg9WmF2UG1Mq76pDYDSwwUp"
         ),
         name: "Btc Transaction Signer",
         description: "Production Btc Transaction Signer",
         version: "1.1.1",
         deployed: true,
-        deployedAt: 1785226367707,
-        size: 66624,
-        hash: "9e0d9909519d5133bab03a9491566870b08d8b42c80e2d768bd24f02946cc781"
+        deployedAt: 1786113907707,
+        size: 67999,
+        hash: "83f3644c68819215e05ba8db3225571354a009458fc1437f606df6cb9142d3f9"
       },
       ucdMintValidator: {
-        cid: "QmPRLCfseSWCAS4PpvQWt9aEd6rXqWYG4JyGTn26KYk6xc",
+        cid: "Qmd8jgKRceLvf5aoTtwdXG2JqMoBK5cRJwrvEtQkgvbFbx",
         authorizedCidHex: cidToHex(
-          "QmPRLCfseSWCAS4PpvQWt9aEd6rXqWYG4JyGTn26KYk6xc"
+          "Qmd8jgKRceLvf5aoTtwdXG2JqMoBK5cRJwrvEtQkgvbFbx"
         ),
         name: "Ucd Mint Validator",
         description: "Production Ucd Mint Validator",
         version: "1.2.1",
         deployed: true,
-        deployedAt: 1785226381631,
-        size: 81658,
-        hash: "d8ea21622885c3d26fdb64e2ba9d2f9460753a5cd7934b2928858899537443eb",
+        deployedAt: 1786113908489,
+        size: 82739,
+        hash: "2bdd9aebdaad58a43a4731d5b7284f2531b7a9caaf8caf5719d891c4ed33cb2e",
         validatorWalletAddress: "0x82DB9F515957aA380B596C6eA2Bd30CEF181f236",
         pkp: {
           publicKey: "0x041ab17cd91fc5c0b761eea6092d032807561b621b82c488826776e04a9158d61ba64d809a4729f0501289d980732cb06d8dfd06999dd9c8efd2f495dad78b31bb",
@@ -1410,17 +1386,17 @@ var require_pkg_src = __commonJS({
         }
       },
       processPaymentValidator: {
-        cid: "QmNUzmHQHsaKThGkfZiD3xZrN64qZfn4P6J4MqWgvkeEsX",
+        cid: "QmNXVdysXDhCaQ1uNE2Vgjbuzy6yUEnnVgHzmDfNKXMU6z",
         authorizedCidHex: cidToHex(
-          "QmNUzmHQHsaKThGkfZiD3xZrN64qZfn4P6J4MqWgvkeEsX"
+          "QmNXVdysXDhCaQ1uNE2Vgjbuzy6yUEnnVgHzmDfNKXMU6z"
         ),
         name: "Process Payment Validator",
         description: "Production Process Payment Validator",
         version: "1.2.1",
         deployed: true,
-        deployedAt: 1785226385509,
-        size: 77655,
-        hash: "3c2af3c3e62e8e606d35f81fd7e6f4943f8516a9bef74f4150c8c1767cbd316f",
+        deployedAt: 1786113909138,
+        size: 78736,
+        hash: "17191ecc9c009e0fa5ab52c876330beb2a9a75d30cccb92e7c0c04f169df088b",
         validatorWalletAddress: "0x82DB9F515957aA380B596C6eA2Bd30CEF181f236",
         pkp: {
           publicKey: "0x04cfccb9b6c7addc79469c0e9fafebef4c70801302c62cdb26b610723a9b8527d23f98a40158c7340d83fd0e62d02b5ec74c12f7a86d98e8c6973b4811110f19ad",
@@ -1428,17 +1404,17 @@ var require_pkg_src = __commonJS({
         }
       },
       extendPositionValidator: {
-        cid: "QmY2t41w1maaoDmdRPx6wTfciHPQAydSpLSKwKVFSS2DPM",
+        cid: "QmYwBsyrhGfHWyRKx549G4tKHxsBLAuRUHcecigeUCkFav",
         authorizedCidHex: cidToHex(
-          "QmY2t41w1maaoDmdRPx6wTfciHPQAydSpLSKwKVFSS2DPM"
+          "QmYwBsyrhGfHWyRKx549G4tKHxsBLAuRUHcecigeUCkFav"
         ),
         name: "Extend Position Validator",
         description: "Production Extend Position Validator",
         version: "1.2.1",
         deployed: true,
-        deployedAt: 1785226398291,
-        size: 75434,
-        hash: "ba55532fbeaf6e65d180b869fd69ee06393d574daa0ace524a9e831d846539a5",
+        deployedAt: 1786113909872,
+        size: 76515,
+        hash: "1d4e085335af80f194a663a577876902c83015177e95906a0b461fa93bd5da08",
         validatorWalletAddress: "0x82DB9F515957aA380B596C6eA2Bd30CEF181f236",
         pkp: {
           publicKey: "0x04e52338f6a0c3362800f1a94c4c8f08be5030dde0fa217388c53d1c1a4790f4443c9f2886b2d2d8f4b75a9a156e9b028011b1a1cf7648da0e556aa980ec692836",
@@ -1446,9 +1422,9 @@ var require_pkg_src = __commonJS({
         }
       },
       btcWithdrawal: {
-        cid: "QmcBg8vPXsCmiKDk28bJVTqDpTrwCzSYAGu5V6ABVVPuK5",
+        cid: "QmZuR3qSBajutXfRd91ffpyFrRMgmaMh7fDEHRiQQF8Ljp",
         authorizedCidHex: cidToHex(
-          "QmcBg8vPXsCmiKDk28bJVTqDpTrwCzSYAGu5V6ABVVPuK5"
+          "QmZuR3qSBajutXfRd91ffpyFrRMgmaMh7fDEHRiQQF8Ljp"
         ),
         name: "Btc Withdrawal",
         description: "Production Btc Withdrawal",
@@ -1458,9 +1434,9 @@ var require_pkg_src = __commonJS({
         // than the one it replaced, which a rotation ceremony would treat as a rollback.
         version: "1.2.4",
         deployed: true,
-        deployedAt: 1785226412397,
-        size: 92754,
-        hash: "d3a8ec62e0b1e6d0566a154a884bf7ee4e25ef6dc2dd84fde98211d25c1dede5",
+        deployedAt: 1786113910531,
+        size: 95313,
+        hash: "ce12f11e3b5469953bc919586e4f3b8b5d594224b58b799dd9a3b60e3749559c",
         validatorWalletAddress: "0x82DB9F515957aA380B596C6eA2Bd30CEF181f236",
         pkp: {
           publicKey: "0x043616787c5432415c24378c4ef48de2bcd6bb7b575b837e3cff09171802662da7105d79586c7659677a0ecbaddac4cce06cb2a11f69a16fa0c4d7002ac7d51a4d",
@@ -1571,6 +1547,21 @@ var require_pkg_src = __commonJS({
         size: 1046,
         hash: "03ee5be239c91c735d2c95db89a0d1b77e602cfc18af8eb64b3281fddcd90a72"
       },
+      agentModuleExecutor: {
+        // Bound to the isolated Sepolia agent group 7 ("DH-Agent-Sepolia"), which
+        // holds this action and no PKPs until an agent is minted into it. NOT yet
+        // bound on mainnet — the Base `DH-Agent-Mainnet` group is created at rollout.
+        cid: "QmVgjGXUuxoGf8XyddW8a7btaazT9yEotpKoBgb65oPvcF",
+        authorizedCidHex: cidToHex(
+          "QmVgjGXUuxoGf8XyddW8a7btaazT9yEotpKoBgb65oPvcF"
+        ),
+        name: "Agent Module Executor",
+        description: "Capability gate for multi-sig Safe agent delegation: binds the agent PKP to the AgentDelegationRegistry record before signing (authorize | execute modes)",
+        version: "1.0.0",
+        deployed: true,
+        size: 11785,
+        hash: "fa294e164273c2158f9ef11a0ccfd735c343c0e3759fcb4b37e0f8a5d1ab0d29"
+      },
       staleSpendRecoveryValidator: {
         cid: "QmXQWT8V4wjuvH8BbC7xrkYxsVu5AKfvfWcS7jnYfrexYm",
         authorizedCidHex: cidToHex(
@@ -1590,17 +1581,17 @@ var require_pkg_src = __commonJS({
         }
       },
       btcUtxoInvalidator: {
-        cid: "QmZE422cZsEjYN8pE6AmpkgFoZCK4UAfdDuzoVRRsMJbwm",
+        cid: "Qmf4Ze8yhnQhHbnX5RPgJrC7Jw1aA3gbpfpd52kFg7fd1m",
         authorizedCidHex: cidToHex(
-          "QmZE422cZsEjYN8pE6AmpkgFoZCK4UAfdDuzoVRRsMJbwm"
+          "Qmf4Ze8yhnQhHbnX5RPgJrC7Jw1aA3gbpfpd52kFg7fd1m"
         ),
         name: "Btc Utxo Invalidator",
         description: "Production Btc Utxo Invalidator",
         version: "1.0.0",
         deployed: true,
-        deployedAt: 1785226423791,
-        size: 61472,
-        hash: "75eca528d8ac30ae8f21caaae206ccab162a83a048d622868e60f645f0c475e2"
+        deployedAt: 1786113911948,
+        size: 62553,
+        hash: "1dcea2b49e545c423195be22e072dc5e3039ed1c95a8490b23505956029f5b33"
       }
     };
     function getDeploymentsForNetwork(network) {
@@ -5507,8 +5498,14 @@ function getMainnetConfig() {
       agentModuleFactory: MAINNET_CONTRACTS.AgentModuleFactory || ""
     },
     subgraphs: {
+      // KNOWN-WRONG placeholder (see GOAL-PLAN step 2 / dogfood F-CLI-4): this is a
+      // SEPOLIA subgraph id in a mainnet (chainId 1) config, and this gateway host
+      // needs an Authorization key the SDK does not (and must not) hold — so the
+      // URL is doubly unusable. The `CCTPsd…` path segment is the subgraph's
+      // PUBLIC ID, not a credential. The fix is a chain-correct SERVER-side proxy
+      // (see mcp/docs/SUBGRAPH-PROXY-PLAN.md) — same rule as rpcUrls above:
+      // never ship an API-keyed URL in a client config.
       diamondHandsUrl: "https://gateway-arbitrum.network.thegraph.com/api/subgraphs/id/CCTPsdYqco2jChDLLBQTbdJWwoukVoMt1cXeR9ti6r9A"
-      // Published Sepolia subgraph on Arbitrum One
     },
     litNetwork: "chipotle",
     debug: false
@@ -6253,7 +6250,10 @@ var import_ethers2 = require("ethers");
 // src/utils/quantum-timing.ts
 var QUANTUM_WINDOW_SECONDS = 60;
 var DEAD_ZONE_SECONDS = 8;
-var INCLUSION_LATENCY_BUDGET = 16;
+var SLOT_SECONDS = 12;
+var INCLUSION_SLOT_TOLERANCE = 3;
+var INCLUSION_LATENCY_BUDGET = SLOT_SECONDS * INCLUSION_SLOT_TOLERANCE;
+var MAX_GATE_POLLS = 12;
 var POST_BOUNDARY_SKEW_MARGIN = 3;
 function calculateNextQuantumTimestamp() {
   const now = Math.floor(Date.now() / 1e3);
@@ -6286,8 +6286,17 @@ function validateQuantumTiming(signedTimestamp, _bufferSeconds = 30) {
 async function awaitSafeSubmissionWindow(quantumTimestamp, opts = {}) {
   const now = opts.now ?? (() => Math.floor(Date.now() / 1e3));
   const sleep = opts.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
-  const nowSec = now();
   const signatureQuantum = Math.floor(quantumTimestamp / QUANTUM_WINDOW_SECONDS) * QUANTUM_WINDOW_SECONDS;
+  if (opts.chainNow) {
+    const chainResult = await awaitSafeSubmissionWindowOnChain(
+      signatureQuantum,
+      opts.chainNow,
+      sleep
+    );
+    if (chainResult)
+      return chainResult;
+  }
+  const nowSec = now();
   const currentQuantum = Math.floor(nowSec / QUANTUM_WINDOW_SECONDS) * QUANTUM_WINDOW_SECONDS;
   const secsToBoundary = QUANTUM_WINDOW_SECONDS - nowSec % QUANTUM_WINDOW_SECONDS;
   const isNextQuantumSig = signatureQuantum === currentQuantum + QUANTUM_WINDOW_SECONDS;
@@ -6304,6 +6313,44 @@ async function awaitSafeSubmissionWindow(quantumTimestamp, opts = {}) {
   }
   return { waited: false, waitedSeconds: 0 };
 }
+async function awaitSafeSubmissionWindowOnChain(signatureQuantum, chainNow, sleep) {
+  let waitedSeconds = 0;
+  for (let poll = 0; poll < MAX_GATE_POLLS; poll++) {
+    let head;
+    try {
+      head = await chainNow();
+    } catch {
+      head = null;
+    }
+    if (head === null || !Number.isFinite(head)) {
+      return waitedSeconds > 0 ? { waited: true, waitedSeconds } : null;
+    }
+    const chainQuantum = Math.floor(head / QUANTUM_WINDOW_SECONDS) * QUANTUM_WINDOW_SECONDS;
+    if (signatureQuantum <= chainQuantum) {
+      return { waited: waitedSeconds > 0, waitedSeconds };
+    }
+    const earliestMine = head + SLOT_SECONDS;
+    const latestMine = head + SLOT_SECONDS * INCLUSION_SLOT_TOLERANCE;
+    const safeBeforeDeadZone = latestMine < signatureQuantum - DEAD_ZONE_SECONDS;
+    const safeAfterBoundary = earliestMine >= signatureQuantum;
+    if (safeBeforeDeadZone || safeAfterBoundary) {
+      return { waited: waitedSeconds > 0, waitedSeconds };
+    }
+    const sleepSeconds = Math.max(
+      1,
+      Math.min(SLOT_SECONDS, signatureQuantum - head)
+    );
+    log.debug(
+      `[Quantum Timing] \u23F3 Deferring send ${sleepSeconds}s to clear the quantum dead zone (sig quantum ${signatureQuantum}, chain head ${head}, insured mine window [${earliestMine}, ${latestMine}])`
+    );
+    await sleep(sleepSeconds * 1e3);
+    waitedSeconds += sleepSeconds;
+  }
+  log.debug(
+    `[Quantum Timing] \u26A0\uFE0F  Dead-zone gate exhausted ${MAX_GATE_POLLS} chain polls (sig quantum ${signatureQuantum}) \u2014 proceeding`
+  );
+  return { waited: waitedSeconds > 0, waitedSeconds };
+}
 
 // src/utils/mint-authorization.utils.ts
 var PKP_NFT_ABI = [
@@ -6350,7 +6397,7 @@ async function generateMintAuthorization(positionId, amount, chainId, signerOrPr
     signature
   };
 }
-async function generatePaymentAuthorization(positionId, amount, chainId, signer) {
+async function generatePaymentAuthorization(positionId, amount, chainId, signerOrPrecomputed) {
   if (typeof positionId !== "string") {
     throw new Error(`positionId must be a string, got ${typeof positionId}`);
   }
@@ -6360,6 +6407,18 @@ async function generatePaymentAuthorization(positionId, amount, chainId, signer)
   if (typeof chainId !== "number") {
     throw new Error(`chainId must be a number, got ${typeof chainId}`);
   }
+  if (typeof signerOrPrecomputed === "object" && "signature" in signerOrPrecomputed && !("signMessage" in signerOrPrecomputed)) {
+    const { timestamp: timestamp2, signature: signature2 } = signerOrPrecomputed;
+    return {
+      positionId,
+      timestamp: timestamp2,
+      chainId,
+      amount: amount.toString(),
+      action: "make-payment",
+      signature: signature2
+    };
+  }
+  const signer = signerOrPrecomputed;
   const timestamp = await calculateNextQuantumTimestamp();
   if (typeof timestamp !== "number") {
     throw new Error(`timestamp must be a number, got ${typeof timestamp}`);
@@ -6601,6 +6660,26 @@ async function generateExtendAuthorization(positionId, newTerm, chainId, signerO
   };
 }
 
+// src/utils/authorization-provider.utils.ts
+async function resolveAuthorizationInput(provider, signer, ctx) {
+  if (!provider)
+    return signer;
+  const result = await provider(ctx);
+  if (!result || typeof result.signature !== "string" || result.signature.length === 0) {
+    throw new Error(
+      "authorizationProvider returned no signature \u2014 refusing to fall back to the connected signer, which would prompt for the owner quorum this provider exists to avoid"
+    );
+  }
+  if (!Number.isInteger(result.timestamp)) {
+    throw new Error(
+      `authorizationProvider returned a non-integer timestamp (${String(
+        result.timestamp
+      )}) \u2014 the protocol call must carry the same value the envelope was signed over`
+    );
+  }
+  return { timestamp: result.timestamp, signature: result.signature };
+}
+
 // src/utils/eip712-login.ts
 var import_ethers4 = require("ethers");
 function buildLoginDomain(chainId) {
@@ -7260,6 +7339,20 @@ function decodeQuantumRevert(e) {
   }
   return { data, selector, name };
 }
+var RETRYABLE_QUANTUM_ERROR_NAMES = [
+  "DeadZoneViolation",
+  "QuantumOutsideWindow",
+  "QuantumAlreadyUsed",
+  "QuantumExpired"
+];
+function isRetryableQuantumFailure(message) {
+  if (!message)
+    return false;
+  if (message.includes("Transaction timeout") || message.includes("Transaction confirmation failed") || message.includes("Transaction receipt not found")) {
+    return false;
+  }
+  return RETRYABLE_QUANTUM_ERROR_NAMES.some((name) => message.includes(name)) || message.includes("Transaction reverted");
+}
 
 // src/utils/quantum-submission.utils.ts
 var MAX_DEADZONE_RESIMULATIONS = 3;
@@ -7281,9 +7374,14 @@ async function assertSafeQuantumSubmission(opts) {
   const now = opts.now ?? (() => Math.floor(Date.now() / 1e3));
   const onDebug = opts.onDebug ?? (() => {
   });
+  const chainNow = opts.chainNow ?? (typeof provider.getBlock === "function" ? async () => {
+    const block = await provider.getBlock("latest");
+    return typeof block?.timestamp === "number" ? block.timestamp : null;
+  } : void 0);
   const gateOpts = {
     now,
-    ...opts.sleep ? { sleep: opts.sleep } : {}
+    ...opts.sleep ? { sleep: opts.sleep } : {},
+    ...chainNow ? { chainNow } : {}
   };
   await awaitSafeSubmissionWindow(quantumTimestamp, gateOpts);
   const SAME_BLOCK_INTERACTION_SELECTOR = "0x3b53d1db";
@@ -19993,11 +20091,20 @@ var DiamondHandsSDK = class _DiamondHandsSDK {
               {}
             );
           }
+          const mintAuthInput = await resolveAuthorizationInput(
+            request.authorizationProvider,
+            signer2,
+            {
+              positionId: request.positionId,
+              timestamp: calculateNextQuantumTimestamp(),
+              amount: requestAmountWei.toString()
+            }
+          );
           const auth = await generateMintAuthorization(
             request.positionId,
             BigInt(requestAmountWei.toString()),
             chainId,
-            signer2
+            mintAuthInput
           );
           if (this.config.debug) {
             log.info(`   Authorization generated (attempt ${attempt})`, {});
@@ -21588,7 +21695,7 @@ Message: ${causeMessage}${quantumContext}${mintDebtDiagnostics}`
    * @param _selectedTerm - Extension term in months
    * @returns Transaction receipt
    */
-  async extendPosition(_positionId, _selectedTerm, _rpcUrl, _bitcoinRpcUrl) {
+  async extendPosition(_positionId, _selectedTerm, _rpcUrl, _bitcoinRpcUrl, _authorizationProvider) {
     this.ensureInitialized();
     if (typeof _positionId !== "string") {
       throw new Error(`positionId must be a string, got ${typeof _positionId}`);
@@ -21682,11 +21789,23 @@ Message: ${causeMessage}${quantumContext}${mintDebtDiagnostics}`
       }
     }
     const signer = this.getSignerOrThrow();
+    const extendAuthInput = await resolveAuthorizationInput(
+      _authorizationProvider,
+      signer,
+      {
+        positionId: _positionId,
+        timestamp: calculateNextQuantumTimestamp(),
+        // The extend envelope binds the TERM, not an amount. Carried as "0" so
+        // the context shape stays uniform across the four operations.
+        amount: "0",
+        selectedTerm: _selectedTerm
+      }
+    );
     const auth = await generateExtendAuthorization(
       _positionId,
       _selectedTerm,
       chainId,
-      signer
+      extendAuthInput
     );
     if (this.config.debug) {
       log.info("   Extend authorization generated", {
@@ -21942,7 +22061,8 @@ Message: ${causeMessage}${quantumContext}${mintDebtDiagnostics}`
         positionId,
         selectedTerm,
         request.rpcUrl,
-        request.customBitcoinRpcUrl
+        request.customBitcoinRpcUrl,
+        request.authorizationProvider
       );
       let newExpiryAt;
       try {
@@ -22293,10 +22413,7 @@ Message: ${causeMessage}${quantumContext}${mintDebtDiagnostics}`
   isRetryablePaymentQuantumFailure(result) {
     if (result.success || !result.error)
       return false;
-    const e = result.error;
-    if (e.includes("Transaction timeout"))
-      return false;
-    return e.includes("DeadZoneViolation") || e.includes("QuantumOutsideWindow") || e.includes("QuantumAlreadyUsed") || e.includes("QuantumExpired") || e === "Transaction reverted";
+    return isRetryableQuantumFailure(result.error);
   }
   /**
    * One payment attempt: user auth → Lit Action authorization → dead-zone gate →
@@ -22473,11 +22590,20 @@ Message: ${causeMessage}${quantumContext}${mintDebtDiagnostics}`
       }
       let auth;
       try {
+        const paymentAuthInput = await resolveAuthorizationInput(
+          request.authorizationProvider,
+          signer,
+          {
+            positionId: request.positionId,
+            timestamp: calculateNextQuantumTimestamp(),
+            amount: paymentAmountWei.toString()
+          }
+        );
         auth = await generatePaymentAuthorization(
           request.positionId,
           paymentAmountWei,
           chainId,
-          signer
+          paymentAuthInput
         );
       } catch (authError) {
         if (authError.message && authError.message.includes("BigNumber")) {
@@ -22935,6 +23061,37 @@ Message: ${causeMessage}${quantumContext}${mintDebtDiagnostics}`
     }
     return this.withdrawalAddressModule.getEntries(target);
   }
+  /**
+   * Recover the revert reason of an already-mined, already-reverted transaction.
+   *
+   * A status-0 receipt carries no revert data, and ethers does not re-fetch it, so
+   * the reason has to be recovered by replaying the exact calldata as an `eth_call`
+   * pinned to the block that mined it — the only block whose `block.timestamp`
+   * reproduces a timing-dependent revert such as `DeadZoneViolation()`.
+   *
+   * Caveat: the replay runs against end-of-block state rather than the state at the
+   * transaction's own index, so for a state-dependent revert the recovered name is
+   * diagnostic, not proof. Timing reverts (the case this exists for) are unaffected —
+   * they depend only on the block timestamp.
+   *
+   * @returns the decoded error name, its raw selector if unknown, or `null` when the
+   *          replay yields no revert data at all (never throws — a failed diagnosis
+   *          must not mask the underlying failure).
+   */
+  async decodeMinedRevert(params) {
+    try {
+      await this.getProviderOrThrow().call({
+        to: params.to,
+        from: params.from,
+        data: params.data,
+        blockTag: params.blockNumber
+      });
+      return null;
+    } catch (replayError) {
+      const decoded = decodeQuantumRevert(replayError);
+      return decoded.name ?? decoded.selector ?? null;
+    }
+  }
   /**
    * Withdraw Bitcoin from a position
    *
@@ -22958,7 +23115,7 @@ Message: ${causeMessage}${quantumContext}${mintDebtDiagnostics}`
    * @param customBitcoinRpcUrl - Optional custom Bitcoin RPC URL (for local testing)
    * @returns Withdrawal result with transaction details
    */
-  async withdrawBTC(positionId, withdrawalAddress, withdrawalAmount) {
+  async withdrawBTC(positionId, withdrawalAddress, withdrawalAmount, options) {
     this.ensureInitialized();
     try {
       if (this.config.debug) {
@@ -23173,11 +23330,21 @@ Message: ${causeMessage}${quantumContext}${mintDebtDiagnostics}`
               {}
             );
           }
+          const withdrawAuthInput = await resolveAuthorizationInput(
+            options?.authorizationProvider,
+            signer,
+            {
+              positionId,
+              timestamp: calculateNextQuantumTimestamp(),
+              amount: BigInt(withdrawalAmount).toString(),
+              destinationAddress: withdrawalAddress
+            }
+          );
           const auth = await generateWithdrawAuthorization(
             positionId,
             BigInt(withdrawalAmount),
             chainId,
-            signer,
+            withdrawAuthInput,
             withdrawalAddress
             // Pass destination address for message hash
           );
@@ -23508,9 +23675,23 @@ Message: ${causeMessage}${quantumContext}${mintDebtDiagnostics}`
           txHash: tx.hash
         });
       }
+      const withdrawProvider = this.getProviderOrThrow();
+      const withdrawTimeoutMs = this.config.transactionTimeoutMs || 3e5;
       let receipt;
       try {
-        receipt = await tx.wait();
+        receipt = await Promise.race([
+          withdrawProvider.waitForTransaction(tx.hash, 1),
+          new Promise(
+            (_, reject) => setTimeout(
+              () => reject(
+                new Error(
+                  `Transaction timeout after ${withdrawTimeoutMs}ms. Hash: ${tx.hash}`
+                )
+              ),
+              withdrawTimeoutMs
+            )
+          )
+        ]);
       } catch (waitError) {
         const waitErrorMsg = waitError instanceof Error ? waitError.message : String(waitError);
         if (this.config.debug) {
@@ -23527,7 +23708,26 @@ Message: ${causeMessage}${quantumContext}${mintDebtDiagnostics}`
       if (!receipt) {
         return {
           success: false,
-          error: `Transaction confirmation returned no receipt. Hash: ${tx.hash}`
+          error: `Transaction receipt not found for hash: ${tx.hash}`
+        };
+      }
+      if (receipt.status === 0) {
+        const revertName = await this.decodeMinedRevert({
+          to: positionManagerAddress,
+          from: await withdrawSigner.getAddress(),
+          data: withdrawCalldata,
+          blockNumber: receipt.blockNumber
+        });
+        if (this.config.debug) {
+          log.error("\u274C withdrawBTC reverted on-chain", {
+            txHash: receipt.hash,
+            blockNumber: receipt.blockNumber,
+            revert: revertName ?? "undecodable"
+          });
+        }
+        return {
+          success: false,
+          error: `Transaction reverted: ${revertName ?? "unknown reason"} (tx: ${receipt.hash})`
         };
       }
       if (this.config.debug) {
@@ -24218,6 +24418,11 @@ Message: ${causeMessage}${quantumContext}${mintDebtDiagnostics}`
    *      (`MAX_ATTESTATION_AGE = 1 hour`) and replay-protects via
    *      `authorizedAt` binding.
    *
+   * WHO PAYS: in **service mode** lit-ops-server performs BOTH steps and its
+   * relayer funds the transaction — the borrower is never prompted, because the
+   * Bitcoin withdrawal this cleans up after has already settled. In **direct
+   * mode** (CLI / tests / hardhat) the SDK's own signer submits step 2.
+   *
    * `invalidatorTxid` is either:
    *   - the borrower's own authorized broadcast (classified "consumed-as-authorized"
    *     by the LIT validator), once it has ≥6 confirmations on the BTC
@@ -24230,7 +24435,6 @@ Message: ${causeMessage}${quantumContext}${mintDebtDiagnostics}`
   async recoverStaleSpend(params) {
     this.ensureInitialized();
     try {
-      const signer = this.getSignerOrThrow();
       const contractAddresses = this.getContractAddressesOrThrow();
       const btcSpendAuthorizerAddress = contractAddresses.btcSpendAuthorizer;
       if (!btcSpendAuthorizerAddress) {
@@ -24276,6 +24480,28 @@ Message: ${causeMessage}${quantumContext}${mintDebtDiagnostics}`
           success: false,
           error: json.error ?? "stale-spend recovery request failed"
         };
+        if (!attRes.success || !attRes.attestation) {
+          return {
+            success: false,
+            failedStep: "attestation",
+            error: attRes.error ?? attRes.reason ?? `LIT recovery attestation rejected${attRes.failedStep ? ` at step ${attRes.failedStep}` : ""}`
+          };
+        }
+        if (!attRes.transactionHash && !attRes.alreadyCleared) {
+          return {
+            success: false,
+            failedStep: "submit",
+            error: "lit-ops-server returned a stale-spend attestation but did not submit it. The server is on a build without the recovery relayer, or its STALE_SPEND_RELAYER_PRIVATE_KEY is unset."
+          };
+        }
+        return {
+          success: true,
+          ...attRes.transactionHash && {
+            transactionHash: attRes.transactionHash
+          },
+          ...attRes.classification && { classification: attRes.classification },
+          attestation: attRes.attestation
+        };
       } else {
         const rpcUrl = params.rpcUrl ?? this.config.ethRpcUrl;
         if (!rpcUrl) {
@@ -24325,7 +24551,7 @@ Message: ${causeMessage}${quantumContext}${mintDebtDiagnostics}`
         [
           "function cancelStaleSpendWithProof(bytes32 positionId, bytes32 utxoKey, uint256 authorizedAt, string calldata invalidatorTxid, uint256 attestationTimestamp, bytes calldata litSignature) external"
         ],
-        signer
+        this.getSignerOrThrow()
       );
       const tx = await btcSpendAuthorizer["cancelStaleSpendWithProof"](
         attRes.attestation.positionId,
@@ -24655,13 +24881,11 @@ Message: ${causeMessage}${quantumContext}${mintDebtDiagnostics}`
         if (authResult.success) {
           break;
         }
-        const isQuantumError = authResult.error?.includes(
-          "QuantumOutsideWindow"
-        );
+        const isQuantumError = isRetryableQuantumFailure(authResult.error);
         if (isQuantumError && wAttempt < MAX_WITHDRAWAL_QUANTUM_RETRIES) {
           if (this.config.debug) {
             log.warn(
-              `\u26A0\uFE0F  Phase 1 QuantumOutsideWindow (attempt ${wAttempt}/${MAX_WITHDRAWAL_QUANTUM_RETRIES}). LIT action took too long. Retrying with fresh quantum...`
+              `\u26A0\uFE0F  Phase 1 quantum-timing failure (attempt ${wAttempt}/${MAX_WITHDRAWAL_QUANTUM_RETRIES}): ${authResult.error}. Retrying with a fresh quantum...`
             );
           }
           await new Promise((resolve) => setTimeout(resolve, 2e3));
@@ -25135,10 +25359,22 @@ Message: ${causeMessage}${quantumContext}${mintDebtDiagnostics}`
       "getLoanGrant",
       data
     );
+    const raw = (0, import_ethers17.getBytes)(data);
+    const withdrawScopeSupported = raw.length >= 128;
+    const minWithdrawRatioBps = withdrawScopeSupported ? Number(
+      import_ethers17.AbiCoder.defaultAbiCoder().decode(["uint32"], raw.slice(96, 128))[0]
+    ) : 0;
     return {
       borrower,
       scopeBits: Number(scopeBits),
-      minCollateralRatioBps: Number(minCollateralRatioBps)
+      minCollateralRatioBps: Number(minCollateralRatioBps),
+      minWithdrawRatioBps,
+      /**
+       * True when the deployed registry is v2.1.0+ and therefore honours `SCOPE_WITHDRAW`. The
+       * frontend gates its Withdrawal control on this so the control is absent — not disabled,
+       * not "coming soon" — on a chain whose registry cannot support it.
+       */
+      withdrawScopeSupported
     };
   }
   /**
@@ -25180,10 +25416,14 @@ Message: ${causeMessage}${quantumContext}${mintDebtDiagnostics}`
     const mintEnabled = hasGrant && (scopes & 4) !== 0;
     const floor = grant.minCollateralRatioBps;
     const agent = user ? await registry.agentOf(user) : null;
+    const withdrawEnabled = hasGrant && grant.withdrawScopeSupported && (scopes & 8) !== 0;
     return {
       renewEnabled: hasGrant && (scopes & 1) !== 0,
       repayEnabled: hasGrant && (scopes & 2) !== 0,
       mintEnabled,
+      withdrawEnabled,
+      withdrawScopeSupported: grant.withdrawScopeSupported,
+      minWithdrawRatioBps: withdrawEnabled ? grant.minWithdrawRatioBps : 0,
       minCollateralRatioBps: mintEnabled ? floor : 0,
       effectiveMintFloorBps: mintEnabled ? Math.max(floor, protocolMin) : 0,
       protocolMinFloorBps: protocolMin,
@@ -25369,8 +25609,83 @@ Message: ${causeMessage}${quantumContext}${mintDebtDiagnostics}`
     const receipt = await tx.wait();
     return { hash: tx.hash, blockNumber: receipt?.blockNumber ?? 0 };
   }
-  /** Pre-flight the registry's `FloorBelowProtocolMin` guard with a message a user can act on. */
-  async assertMintFloorAtOrAboveProtocolMin(floorBps) {
+  /**
+   * Grant the agent the WITHDRAW scope for a position (registry v2.1.0+). Borrower-signed.
+   *
+   * CONTRACT WALLETS ONLY, and this is enforced here rather than on-chain. The withdrawal
+   * validator's only non-borrower arm is `checkSafeAgentWithdrawAuthorization`, which requires a
+   * factory-provenanced `AgentModule` whose `safe()` is the borrower — something an EOA cannot
+   * have. The registry deliberately does NOT check wallet type ("Callable by any borrower (this
+   * function does not itself require a Safe)"), so an EOA can record a grant that no code path
+   * will ever satisfy. Refusing here keeps the supported path from writing a dead record.
+   *
+   * That refusal is ergonomics, NOT enforcement — `enableAutoWithdraw` is `external` and reachable
+   * from any wallet. The real reason delegated withdrawal is closed to EOAs is that they can sign
+   * inside the ~44s window themselves, so delegating buys them nothing and only adds risk.
+   *
+   * @param minWithdrawRatioBps Post-withdrawal collateral-ratio floor for AGENT withdrawals.
+   *        Clamped by the same governance minimum as the mint floor. **Inert at zero debt** — it
+   *        is a ratio, and the post-withdrawal ratio is infinite for any amount once debt is 0.
+   *        The operative bound there is the quorum-gated destination allowlist. Do not surface
+   *        this to users as a cap on how much an agent may withdraw.
+   *        There is no in-place raise: changing it means disable-then-re-enable, deliberately —
+   *        on the one scope that moves custodied BTC, incident response can only disable outright.
+   */
+  async enableAutoWithdraw(positionId, minWithdrawRatioBps, options) {
+    const pid = this.toBytes32(positionId);
+    await this.assertBorrowerIsContractWallet(pid);
+    await this.assertMintFloorAtOrAboveProtocolMin(minWithdrawRatioBps, "withdraw");
+    const { registry, agentAddress } = await this.prepareAgentDelegation(pid, options);
+    const tx = await registry.enableAutoWithdraw(pid, minWithdrawRatioBps);
+    const receipt = await tx.wait();
+    return { hash: tx.hash, blockNumber: receipt?.blockNumber ?? 0, agentAddress };
+  }
+  /**
+   * Revoke the WITHDRAW scope for a position (also zeroes its withdraw floor). Borrower-signed.
+   *
+   * No wallet-type check: revoking is the safe direction, and an EOA that recorded a grant before
+   * this guard existed must be able to clear it.
+   */
+  async disableAutoWithdraw(positionId) {
+    const addr = this.agentDelegationRegistryOrThrow();
+    const signer = this.getSignerOrThrow();
+    const registry = AgentDelegationRegistry__factory.connect(addr, signer);
+    const pid = this.toBytes32(positionId);
+    const tx = await registry.disableAutoWithdraw(pid);
+    const receipt = await tx.wait();
+    await this.clearGate1IfNoScopesRemain(pid);
+    return { hash: tx.hash, blockNumber: receipt?.blockNumber ?? 0 };
+  }
+  /**
+   * Layer 2 of the withdrawal-delegation gating: refuse to write a grant that could never be
+   * satisfied. See `enableAutoWithdraw` for why this lives here and not in the registry.
+   */
+  async assertBorrowerIsContractWallet(pid) {
+    const details = await this.getPositionDetailsView(pid);
+    const borrower = details?.borrower;
+    if (!borrower) {
+      throw new SDKError({
+        message: `Could not resolve the borrower for position ${pid} \u2014 refusing to write a delegation grant against an unverified position`,
+        category: "VALIDATION" /* VALIDATION */,
+        severity: "HIGH" /* HIGH */
+      });
+    }
+    const code = await this.getProviderOrThrow().getCode(borrower);
+    if (!code || code === "0x") {
+      throw new SDKError({
+        message: `Withdrawal delegation is only available to contract wallets. Borrower ${borrower} is an EOA, and the withdrawal validator has no delegate arm for one \u2014 an EOA can sign inside the withdrawal quantum window itself, so the grant would be recorded on-chain and never honoured.`,
+        category: "VALIDATION" /* VALIDATION */,
+        severity: "MEDIUM" /* MEDIUM */
+      });
+    }
+  }
+  /**
+   * Pre-flight the registry's `FloorBelowProtocolMin` guard with a message a user can act on.
+   *
+   * `agentMintFloorMinBps` is the governance floor-of-floors for BOTH the mint and withdraw
+   * grants — one lever, one invariant — so `scope` only shapes the message.
+   */
+  async assertMintFloorAtOrAboveProtocolMin(floorBps, scope = "mint") {
     if (!Number.isInteger(floorBps) || floorBps <= 0) {
       throw new SDKError({
         message: `Invalid collateral floor: ${floorBps} bps \u2014 must be a positive integer`,
@@ -25381,7 +25696,7 @@ Message: ${causeMessage}${quantumContext}${mintDebtDiagnostics}`
     const protocolMin = await this.getAgentMintFloorMinBps();
     if (protocolMin === 0) {
       throw new SDKError({
-        message: "Agent minting is not configured on this network (agentMintFloorMinBps is 0) \u2014 the registry would reject every mint grant",
+        message: `Agent ${scope === "mint" ? "minting" : "withdrawal"} is not configured on this network (agentMintFloorMinBps is 0) \u2014 the registry would reject every ${scope} grant`,
         category: "CONFIGURATION" /* CONFIGURATION */,
         severity: "HIGH" /* HIGH */
       });