@gvnrdao/dh-sdk 0.0.324 → 0.0.327

package/dist/deployments.js

@@ -329,7 +329,7 @@ var SEPOLIA_DEPLOYMENT = {
     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"
   }
 };
@@ -599,7 +599,7 @@ var MAINNET_CONTRACTS = {
 var LOCALHOST_DEPLOYMENT = {
   network: "localhost",
   chainId: 1337,
-  timestamp: "2026-07-23T17:13:42.777Z",
+  timestamp: "2026-07-20T19:45:58.514Z",
   deployer: "",
   contracts: {
     MessageHashBuilder: "0xa82fF9aFd8f496c3d6ac40E2a0F282E47488CFc9",
@@ -619,30 +619,6 @@ var LOCALHOST_DEPLOYMENT = {
     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: ""
   }
 };
 var LOCALHOST_CONTRACTS = {

package/dist/deployments.mjs

@@ -296,7 +296,7 @@ var SEPOLIA_DEPLOYMENT = {
     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"
   }
 };
@@ -566,7 +566,7 @@ var MAINNET_CONTRACTS = {
 var LOCALHOST_DEPLOYMENT = {
   network: "localhost",
   chainId: 1337,
-  timestamp: "2026-07-23T17:13:42.777Z",
+  timestamp: "2026-07-20T19:45:58.514Z",
   deployer: "",
   contracts: {
     MessageHashBuilder: "0xa82fF9aFd8f496c3d6ac40E2a0F282E47488CFc9",
@@ -586,30 +586,6 @@ var LOCALHOST_DEPLOYMENT = {
     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: ""
   }
 };
 var LOCALHOST_CONTRACTS = {

package/dist/index.d.ts

@@ -35,6 +35,7 @@ export type { BitcoinOperationsConfig, BitcoinNetwork, EnrichedBitcoinBalance, }
 export type { SupportedStablecoinData } from './graphs/diamond-hands';
 export { validateSDKConfig, validateServiceModeConfig, validateStandaloneModeConfig, isServiceModeConfig, isStandaloneModeConfig, } from './interfaces/chunks/config.i';
 export { assertSafeServiceEndpoint } from './utils/service-endpoint-policy';
+export type { AuthorizationContext, AuthorizationProvider, } from './utils/authorization-provider.utils';
 export { buildLoginDomain, buildSignedLoginPayload, LOGIN_TYPES, LOGIN_TYPES_WITH_AUDIENCE, } from './utils/eip712-login';
 export type { DhServerLoginMessage, DhServerLoginPayload, } from './utils/eip712-login';
 export { DEFAULT_LIT_NETWORK, VALID_LIT_NETWORKS, SDK_DEFAULTS, } from './constants/chunks/sdk-config';

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 = {
@@ -5522,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
@@ -6415,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}`);
   }
@@ -6425,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}`);
@@ -6666,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) {
@@ -20077,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})`, {});
@@ -21672,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}`);
@@ -21766,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", {
@@ -22026,7 +22061,8 @@ Message: ${causeMessage}${quantumContext}${mintDebtDiagnostics}`
         positionId,
         selectedTerm,
         request.rpcUrl,
-        request.customBitcoinRpcUrl
+        request.customBitcoinRpcUrl,
+        request.authorizationProvider
       );
       let newExpiryAt;
       try {
@@ -22554,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")) {
@@ -23070,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) {
@@ -23285,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
           );
@@ -24363,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
@@ -24375,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) {
@@ -24421,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) {
@@ -24470,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,
@@ -25278,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
     };
   }
   /**
@@ -25323,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,
@@ -25512,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`,
@@ -25524,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 */
       });