@gvnrdao/dh-sdk 0.0.324 → 0.0.327

package/dist/index.mjs

@@ -360,7 +360,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"
       }
     };
@@ -630,7 +630,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",
@@ -650,30 +650,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 = {
@@ -5528,8 +5504,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
@@ -6326,7 +6308,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}`);
   }
@@ -6336,6 +6318,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}`);
@@ -6577,6 +6571,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
 import { hexlify, randomBytes } from "ethers";
 function buildLoginDomain(chainId) {
@@ -20002,11 +20016,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})`, {});
@@ -21597,7 +21620,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}`);
@@ -21691,11 +21714,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", {
@@ -21951,7 +21986,8 @@ Message: ${causeMessage}${quantumContext}${mintDebtDiagnostics}`
         positionId,
         selectedTerm,
         request.rpcUrl,
-        request.customBitcoinRpcUrl
+        request.customBitcoinRpcUrl,
+        request.authorizationProvider
       );
       let newExpiryAt;
       try {
@@ -22479,11 +22515,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")) {
@@ -22995,7 +23040,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) {
@@ -23210,11 +23255,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
           );
@@ -24288,6 +24343,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
@@ -24300,7 +24360,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) {
@@ -24346,6 +24405,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) {
@@ -24395,7 +24476,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,
@@ -25203,10 +25284,22 @@ Message: ${causeMessage}${quantumContext}${mintDebtDiagnostics}`
       "getLoanGrant",
       data
     );
+    const raw = getBytes5(data);
+    const withdrawScopeSupported = raw.length >= 128;
+    const minWithdrawRatioBps = withdrawScopeSupported ? Number(
+      AbiCoder2.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
     };
   }
   /**
@@ -25248,10 +25341,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,
@@ -25437,8 +25534,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`,
@@ -25449,7 +25621,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 */
       });

package/dist/interfaces/chunks/loan-operations.i.d.ts

@@ -2,6 +2,7 @@
  * Loan Operations Interfaces
  */
 import { LoanStatus } from "../../types/loanStatus";
+import type { AuthorizationProvider } from "../../utils/authorization-provider.utils";
 export type BitcoinAddresses = {
     mainnet: string;
     testnet: string;
@@ -176,6 +177,18 @@ export interface UCDMintRequest {
         stubbedAvailableBtcSats?: string;
         stubbedAuthorizedSpendsHash?: string;
     };
+    /**
+     * Supplies the borrower authorization envelope instead of the connected
+     * signer — the seam a delegated Safe uses so its agent signs instantly
+     * rather than the SDK asking for an owner quorum inside a quantum window.
+     *
+     * Omit it and nothing changes: the SDK signs with the connected signer
+     * exactly as before, which is what every EOA borrower does.
+     *
+     * See `utils/authorization-provider.utils.ts` for why this is a callback and
+     * not a `{ timestamp, signature }` value.
+     */
+    authorizationProvider?: AuthorizationProvider;
 }
 /**
  * UCD Mint Result Interface
@@ -213,6 +226,18 @@ export interface RenewPositionResult {
 export interface RenewPositionRequest {
     positionId: string;
     selectedTerm: number;
+    /**
+     * Supplies the borrower authorization envelope instead of the connected
+     * signer — the seam a delegated Safe uses so its agent signs instantly
+     * rather than the SDK asking for an owner quorum inside a quantum window.
+     *
+     * Omit it and nothing changes: the SDK signs with the connected signer
+     * exactly as before, which is what every EOA borrower does.
+     *
+     * See `utils/authorization-provider.utils.ts` for why this is a callback and
+     * not a `{ timestamp, signature }` value.
+     */
+    authorizationProvider?: AuthorizationProvider;
 }
 /**
  * BTC Withdrawal Result Interface
@@ -282,6 +307,18 @@ export interface PartialPaymentRequest {
     positionId: string;
     paymentAmount: number;
     rpcUrl?: string;
+    /**
+     * Supplies the borrower authorization envelope instead of the connected
+     * signer — the seam a delegated Safe uses so its agent signs instantly
+     * rather than the SDK asking for an owner quorum inside a quantum window.
+     *
+     * Omit it and nothing changes: the SDK signs with the connected signer
+     * exactly as before, which is what every EOA borrower does.
+     *
+     * See `utils/authorization-provider.utils.ts` for why this is a callback and
+     * not a `{ timestamp, signature }` value.
+     */
+    authorizationProvider?: AuthorizationProvider;
 }
 /**
  * Confirm Balance Result Interface

package/dist/modules/diamond-hands-sdk.d.ts

@@ -18,6 +18,7 @@ import { SDKError } from "../utils/error-handler";
 import type { CreateLoanRequest, CreateLoanResult, LoanDataDetail, UCDMintRequest, UCDMintResult, PartialPaymentRequest, PartialPaymentResult, BTCWithdrawalResult, RenewPositionRequest, RenewPositionResult, LiquidationRequest, LiquidationResult, ConfirmBalanceRequest, ConfirmBalanceResult, TermsWithFeesResult } from "../interfaces/chunks/loan-operations.i";
 import type { DiamondHandsSDKConfig } from "../interfaces/chunks/config.i";
 import type { PKPData } from "../interfaces/chunks/pkp-integration.i";
+import { type AuthorizationProvider } from "../utils/authorization-provider.utils";
 import type { DhServerLoginPayload } from "../utils/eip712-login";
 import { type ReconciledWithdrawal } from "../utils/withdrawal-reconciliation.utils";
 import { ContractManager } from "./contract/contract-manager.module";
@@ -581,7 +582,15 @@ export declare class DiamondHandsSDK {
      * @param customBitcoinRpcUrl - Optional custom Bitcoin RPC URL (for local testing)
      * @returns Withdrawal result with transaction details
      */
-    withdrawBTC(positionId: string, withdrawalAddress: string, withdrawalAmount: number): Promise<BTCWithdrawalResult>;
+    withdrawBTC(positionId: string, withdrawalAddress: string, withdrawalAmount: number, 
+    /**
+     * An options bag rather than a fifth positional argument: this method is
+     * already three positional strings/numbers deep, and the next caller to
+     * add one would have to guess the order.
+     */
+    options?: {
+        authorizationProvider?: AuthorizationProvider;
+    }): Promise<BTCWithdrawalResult>;
     /**
      * TEMPORARY (multi-UTXO withdrawal fix, Phase A): fetch the vault's confirmed
      * UTXO set from lit-ops-server (`GET /api/lit/vault-utxos`) so the caller can
@@ -739,6 +748,11 @@ export declare class DiamondHandsSDK {
      *      (`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
@@ -1071,6 +1085,16 @@ export declare class DiamondHandsSDK {
         agentActive: boolean | null;
         /** Agent expiry (unix seconds) — the ONLY time bound on every grant. Null without `user`. */
         agentValidUntil: number | null;
+        /** SCOPE_WITHDRAW granted. Always false where the registry predates v2.1.0. */
+        withdrawEnabled: boolean;
+        /** Does the DEPLOYED registry honour SCOPE_WITHDRAW at all (v2.1.0+)? */
+        withdrawScopeSupported: boolean;
+        /**
+         * Grant's post-withdrawal collateral floor in bps; 0 when WITHDRAW is not granted.
+         * INERT AT ZERO DEBT — a ratio cannot bound a withdrawal once debt is 0. Never present this
+         * as a cap on how much an agent may withdraw.
+         */
+        minWithdrawRatioBps: number;
     }>;
     /** Governance floor-of-floors for agent mints (bps). The UI's minimum for the floor editor. */
     getAgentMintFloorMinBps(): Promise<number>;
@@ -1161,7 +1185,56 @@ export declare class DiamondHandsSDK {
         hash: string;
         blockNumber: number;
     }>;
-    /** Pre-flight the registry's `FloorBelowProtocolMin` guard with a message a user can act on. */
+    /**
+     * 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.
+     */
+    enableAutoWithdraw(positionId: string, minWithdrawRatioBps: number, options?: {
+        agentValiditySeconds?: number;
+    }): Promise<{
+        hash: string;
+        blockNumber: number;
+        agentAddress?: string;
+    }>;
+    /**
+     * 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.
+     */
+    disableAutoWithdraw(positionId: string): Promise<{
+        hash: string;
+        blockNumber: number;
+    }>;
+    /**
+     * 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.
+     */
+    private assertBorrowerIsContractWallet;
+    /**
+     * 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.
+     */
     private assertMintFloorAtOrAboveProtocolMin;
     /**
      * Get Bitcoin balance for an address

package/dist/safe-delegation.js

@@ -326,7 +326,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"
   }
 };
@@ -538,7 +538,7 @@ var MAINNET_DEPLOYMENT = {
 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",
@@ -558,30 +558,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 ALL_DEPLOYMENTS = {