@gvnrdao/dh-sdk 0.0.324 → 0.0.328

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 = {
@@ -1393,7 +1369,7 @@ var require_pkg_src = __commonJS({
         description: "Production Btc Transaction Signer",
         version: "1.1.1",
         deployed: true,
-        deployedAt: 1786113907707,
+        deployedAt: 1786465606156,
         size: 67999,
         hash: "83f3644c68819215e05ba8db3225571354a009458fc1437f606df6cb9142d3f9"
       },
@@ -1406,7 +1382,7 @@ var require_pkg_src = __commonJS({
         description: "Production Ucd Mint Validator",
         version: "1.2.1",
         deployed: true,
-        deployedAt: 1786113908489,
+        deployedAt: 1786465627201,
         size: 82739,
         hash: "2bdd9aebdaad58a43a4731d5b7284f2531b7a9caaf8caf5719d891c4ed33cb2e",
         validatorWalletAddress: "0x82DB9F515957aA380B596C6eA2Bd30CEF181f236",
@@ -1424,7 +1400,7 @@ var require_pkg_src = __commonJS({
         description: "Production Process Payment Validator",
         version: "1.2.1",
         deployed: true,
-        deployedAt: 1786113909138,
+        deployedAt: 1786465654796,
         size: 78736,
         hash: "17191ecc9c009e0fa5ab52c876330beb2a9a75d30cccb92e7c0c04f169df088b",
         validatorWalletAddress: "0x82DB9F515957aA380B596C6eA2Bd30CEF181f236",
@@ -1442,7 +1418,7 @@ var require_pkg_src = __commonJS({
         description: "Production Extend Position Validator",
         version: "1.2.1",
         deployed: true,
-        deployedAt: 1786113909872,
+        deployedAt: 1786465681874,
         size: 76515,
         hash: "1d4e085335af80f194a663a577876902c83015177e95906a0b461fa93bd5da08",
         validatorWalletAddress: "0x82DB9F515957aA380B596C6eA2Bd30CEF181f236",
@@ -1452,21 +1428,17 @@ var require_pkg_src = __commonJS({
         }
       },
       btcWithdrawal: {
-        cid: "QmZuR3qSBajutXfRd91ffpyFrRMgmaMh7fDEHRiQQF8Ljp",
+        cid: "QmRYVoTTDxk2McvBqxSm9M7YcaBGdTqjnZGPX4Y191DaZh",
         authorizedCidHex: cidToHex(
-          "QmZuR3qSBajutXfRd91ffpyFrRMgmaMh7fDEHRiQQF8Ljp"
+          "QmRYVoTTDxk2McvBqxSm9M7YcaBGdTqjnZGPX4Y191DaZh"
         ),
         name: "Btc Withdrawal",
         description: "Production Btc Withdrawal",
-        // Monotonic per action, NOT a shared release train — the EIP-1271 rotation
-        // stamped its cohort 1.2.1, but this action was already at 1.2.3 from the vout
-        // canonicalization fix. Reusing the cohort stamp made a newer CID read as older
-        // than the one it replaced, which a rotation ceremony would treat as a rollback.
-        version: "1.2.4",
+        version: "1.2.7",
         deployed: true,
-        deployedAt: 1786113910531,
-        size: 95313,
-        hash: "ce12f11e3b5469953bc919586e4f3b8b5d594224b58b799dd9a3b60e3749559c",
+        deployedAt: 1786446046614,
+        size: 97456,
+        hash: "3cae8250861832f91ee3c573abeb50ff27b9acd34148176071cbfbabb359fc91",
         validatorWalletAddress: "0x82DB9F515957aA380B596C6eA2Bd30CEF181f236",
         pkp: {
           publicKey: "0x043616787c5432415c24378c4ef48de2bcd6bb7b575b837e3cff09171802662da7105d79586c7659677a0ecbaddac4cce06cb2a11f69a16fa0c4d7002ac7d51a4d",
@@ -1578,19 +1550,17 @@ var require_pkg_src = __commonJS({
         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",
+        cid: "QmdhC18wF7PFGMQ8aThdPsEVSpuDewA27dFvbA3bG6kVDQ",
         authorizedCidHex: cidToHex(
-          "QmVgjGXUuxoGf8XyddW8a7btaazT9yEotpKoBgb65oPvcF"
+          "QmdhC18wF7PFGMQ8aThdPsEVSpuDewA27dFvbA3bG6kVDQ"
         ),
         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",
+        description: "Production Agent Module Executor",
+        version: "1.1.1",
         deployed: true,
-        size: 11785,
-        hash: "fa294e164273c2158f9ef11a0ccfd735c343c0e3759fcb4b37e0f8a5d1ab0d29"
+        deployedAt: 1786446108348,
+        size: 11655,
+        hash: "d4e2149f843d6c2699fc61114d54b268ba4ed2c46ebdaee1145e0f101ec2a1ec"
       },
       staleSpendRecoveryValidator: {
         cid: "QmXQWT8V4wjuvH8BbC7xrkYxsVu5AKfvfWcS7jnYfrexYm",
@@ -1619,7 +1589,7 @@ var require_pkg_src = __commonJS({
         description: "Production Btc Utxo Invalidator",
         version: "1.0.0",
         deployed: true,
-        deployedAt: 1786113911948,
+        deployedAt: 1786465704240,
         size: 62553,
         hash: "1dcea2b49e545c423195be22e072dc5e3039ed1c95a8490b23505956029f5b33"
       }
@@ -5528,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
@@ -6326,7 +6302,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 +6312,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 +6565,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 +20010,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 +21614,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 +21708,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 +21980,8 @@ Message: ${causeMessage}${quantumContext}${mintDebtDiagnostics}`
         positionId,
         selectedTerm,
         request.rpcUrl,
-        request.customBitcoinRpcUrl
+        request.customBitcoinRpcUrl,
+        request.authorizationProvider
       );
       let newExpiryAt;
       try {
@@ -22479,11 +22509,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 +23034,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 +23249,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 +24337,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 +24354,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 +24399,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) {
@@ -24355,6 +24430,13 @@ Message: ${causeMessage}${quantumContext}${mintDebtDiagnostics}`
             error: "ethRpcUrl required for recoverStaleSpend \u2014 set DiamondHandsSDKConfig.ethRpcUrl or pass rpcUrl"
           };
         }
+        if (!this.config.contractSigner) {
+          return {
+            success: false,
+            failedStep: "config",
+            error: "Contract signer not configured \u2014 recoverStaleSpend submits its own recovery transaction in direct mode. Set DiamondHandsSDKConfig.contractSigner, or use service mode, where the server relays and pays for it."
+          };
+        }
         const sdkBitcoinProviderUrl = this.config.bitcoinProviders?.[0]?.url;
         attRes = await this.litOps.requestStaleSpendRecoveryAttestation({
           chainId,
@@ -24395,7 +24477,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 +25285,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 +25342,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 +25535,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 +25622,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