@gvnrdao/dh-sdk 0.0.338 → 0.0.340

package/dist/index.mjs

@@ -2357,7 +2357,7 @@ ${errorReport}`);
     }
     init_debug_logger();
     init_session_signature_cache();
-    var import_ethers19 = __require("ethers");
+    var import_ethers23 = __require("ethers");
     var EXPIRED_LOAN_MIN_LIQUIDATION_THRESHOLD_BPS = 11e3;
     var GRACE_PERIOD_DAYS = 30;
     var SATOSHIS_PER_BITCOIN = 100000000n;
@@ -5285,12 +5285,12 @@ ${auth.clientId}`;
     }
     async function executeVaultSnapshot(params) {
       global.ethers = {
-        ...import_ethers19.ethers,
+        ...import_ethers23.ethers,
         providers: {
-          StaticJsonRpcProvider: import_ethers19.ethers.JsonRpcProvider
+          StaticJsonRpcProvider: import_ethers23.ethers.JsonRpcProvider
         },
-        Contract: import_ethers19.ethers.Contract,
-        utils: import_ethers19.ethers
+        Contract: import_ethers23.ethers.Contract,
+        utils: import_ethers23.ethers
         // v6 moved utils to top level
       };
       global.Lit = {
@@ -5546,8 +5546,8 @@ function getSepoliaConfig() {
       positionManagerCore: SEPOLIA_CONTRACTS.PositionManagerCoreModule || "",
       positionManagerViews: SEPOLIA_CONTRACTS.PositionManagerViews || "",
       simplePsmV2: SEPOLIA_CONTRACTS.SimplePSMV2 || "",
-      mockUsdcToken: SEPOLIA_CONTRACTS["MockUSDC"] || "",
-      mockUsdtToken: SEPOLIA_CONTRACTS["MockUSDT"] || "",
+      mockUsdcToken: SEPOLIA_CONTRACTS.mockUsdcToken || "",
+      mockUsdtToken: SEPOLIA_CONTRACTS.mockUsdtToken || "",
       loanOperationsManager: SEPOLIA_CONTRACTS.LoanOperationsManagerModule || "",
       termManager: SEPOLIA_CONTRACTS.TermManagerModule || "",
       circuitBreaker: SEPOLIA_CONTRACTS.CircuitBreakerModule || "",
@@ -5623,14 +5623,17 @@ 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"
+      // The MAINNET subgraph on The Graph's decentralized network — the same id
+      // lit-ops-server's ETHEREUM_SUBGRAPH_URL points at (infra/terraform). The path segment is
+      // the subgraph's PUBLIC ID, not a credential. This used to be a SEPOLIA id under a
+      // chainId-1 config: unusable as shipped, but a caller who added their own key would have
+      // read Sepolia data as mainnet.
+      //
+      // The gateway needs an `Authorization: Bearer <query key>` the SDK does not (and must
+      // not) hold, so this URL only works for a standalone caller supplying their own key.
+      // Service mode never uses it — queries go through the lit-ops-server proxy, which adds
+      // the key server-side. Same rule as rpcUrls above: never ship a keyed URL in a client config.
+      diamondHandsUrl: "https://gateway.thegraph.com/api/subgraphs/id/8Gt9zaSCgkxxSiLMGaKVj7qU3ds1heGVGxgWcXXpwbPd"
     },
     litNetwork: "chipotle",
     debug: false
@@ -5771,7 +5774,7 @@ var init_network_configs = __esm({
 });
 
 // src/modules/diamond-hands-sdk.ts
-import { Contract as Contract9, Interface as Interface5, JsonRpcProvider, AbiCoder as AbiCoder2, keccak256 as keccak2565, solidityPackedKeccak256 as solidityPackedKeccak2564, toUtf8Bytes as toUtf8Bytes5, getBytes as getBytes4, zeroPadValue as zeroPadValue5, toBeHex as toBeHex2, parseEther, formatEther, formatUnits, computeAddress, Signature, ZeroHash, ZeroAddress as ZeroAddress3, MaxUint256 } from "ethers";
+import { Contract as Contract9, Interface as Interface5, JsonRpcProvider, AbiCoder as AbiCoder2, keccak256 as keccak2565, solidityPackedKeccak256 as solidityPackedKeccak2564, toUtf8Bytes as toUtf8Bytes5, getBytes as getBytes4, zeroPadValue as zeroPadValue5, toBeHex as toBeHex2, parseEther, formatEther, formatUnits, computeAddress, Signature, ZeroHash, ZeroAddress as ZeroAddress3 } from "ethers";
 
 // src/types/result.ts
 function success(value) {
@@ -6774,6 +6777,41 @@ async function resolveAuthorizationInput(provider, signer, ctx) {
   return { timestamp: result.timestamp, signature: result.signature };
 }
 
+// src/utils/loan-helpers.utils.ts
+function baseMintFeeWei(mintAmountWei, originationFeeBps) {
+  if (mintAmountWei < 0n)
+    throw new Error("baseMintFeeWei: mintAmountWei cannot be negative");
+  if (!Number.isInteger(originationFeeBps) || originationFeeBps < 0 || originationFeeBps > 1e4) {
+    throw new Error(
+      `baseMintFeeWei: originationFeeBps must be an integer in [0, 10000] (got ${String(originationFeeBps)})`
+    );
+  }
+  return mintAmountWei * BigInt(originationFeeBps) / 10000n;
+}
+function debtAfterMintExceedsLoanCap(params) {
+  const { currentDebtWei, mintAmountWei, mintFeeWei, maxLoanWei } = params;
+  for (const [name, v] of Object.entries(params)) {
+    if (v < 0n)
+      throw new Error(`debtAfterMintExceedsLoanCap: ${name} cannot be negative`);
+  }
+  return currentDebtWei + mintAmountWei + mintFeeWei > maxLoanWei;
+}
+function maxPrincipalWithinLoanCap(params) {
+  const { maxLoanWei, currentDebtWei, originationFeeBps } = params;
+  if (maxLoanWei < 0n || currentDebtWei < 0n) {
+    throw new Error("maxPrincipalWithinLoanCap: amounts cannot be negative");
+  }
+  if (!Number.isInteger(originationFeeBps) || originationFeeBps < 0 || originationFeeBps > 1e4) {
+    throw new Error(
+      `maxPrincipalWithinLoanCap: originationFeeBps must be an integer in [0, 10000] (got ${String(originationFeeBps)})`
+    );
+  }
+  const room = maxLoanWei - currentDebtWei;
+  if (room <= 0n)
+    return 0n;
+  return room * 10000n / (10000n + BigInt(originationFeeBps));
+}
+
 // src/utils/eip712-login.ts
 import { hexlify, randomBytes } from "ethers";
 function buildLoginDomain(chainId) {
@@ -8223,23 +8261,37 @@ var BitcoinUtils = class {
 };
 
 // src/utils/address-conversion.utils.ts
-function safeValidateBitcoinAddress(address, network = "regtest") {
+function networksOfValidAddress(address) {
+  const lower2 = address.toLowerCase();
+  if (lower2.startsWith("bcrt1"))
+    return ["regtest"];
+  if (lower2.startsWith("bc1"))
+    return ["mainnet"];
+  if (lower2.startsWith("tb1"))
+    return ["testnet"];
+  if (address.startsWith("1") || address.startsWith("3"))
+    return ["mainnet"];
+  return ["testnet", "regtest"];
+}
+function safeValidateBitcoinAddress(address, network) {
   if (!address || typeof address !== "string") {
     throw new Error(`Invalid Bitcoin address: must be a non-empty string`);
   }
-  const base58Pattern = /^[123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz]+$/;
-  const bech32Pattern = /^(bc1|tb1|bcrt1)[a-z0-9]+$/;
-  if (!base58Pattern.test(address) && !bech32Pattern.test(address)) {
-    throw new Error(`Invalid Bitcoin address format: ${address}`);
+  if (network !== "mainnet" && network !== "testnet" && network !== "regtest") {
+    throw new Error(
+      `Bitcoin network is required to validate an address (got ${JSON.stringify(network)})`
+    );
   }
-  if (network === "regtest" || network === "testnet") {
-    if (!address.startsWith("m") && !address.startsWith("n") && !address.startsWith("2") && !address.startsWith("tb1") && !address.startsWith("bcrt1")) {
-      throw new Error(`Invalid ${network} Bitcoin address: ${address} (must start with m, n, 2, tb1, or bcrt1)`);
-    }
-  } else if (network === "mainnet") {
-    if (!address.startsWith("1") && !address.startsWith("3") && !address.startsWith("bc1")) {
-      throw new Error(`Invalid mainnet Bitcoin address: ${address} (must start with 1, 3, or bc1)`);
-    }
+  if (!BitcoinUtils.validateAddress(address)) {
+    throw new Error(
+      `Invalid Bitcoin address: ${address} (malformed or failed its checksum \u2014 check for a typo)`
+    );
+  }
+  const belongsTo = networksOfValidAddress(address);
+  if (!belongsTo.includes(network)) {
+    throw new Error(
+      `Bitcoin address ${address} is not a ${network} address \u2014 it is a ${belongsTo.join("/")} address. Sending across networks would lose the funds.`
+    );
   }
   return address;
 }
@@ -10382,7 +10434,102 @@ var LoanStatus = /* @__PURE__ */ ((LoanStatus2) => {
 })(LoanStatus || {});
 
 // src/modules/loan/loan-query.module.ts
-import { Contract as Contract4 } from "ethers";
+import { Contract as Contract4, isAddress as isAddress2 } from "ethers";
+
+// src/constants/chunks/sdk-limits.ts
+var THE_GRAPH_MAX_BATCH_SIZE = 1e3;
+
+// src/utils/borrower-ucd-debt-summary.ts
+var BORROWER_DEBT_ROWS_PAGE_SIZE = THE_GRAPH_MAX_BATCH_SIZE;
+var BORROWER_DEBT_ROWS_MAX_PAGES = 10;
+async function collectBorrowerDebtRows(fetchPage) {
+  const pageSize = BORROWER_DEBT_ROWS_PAGE_SIZE;
+  const rows = [];
+  for (let page = 0; page < BORROWER_DEBT_ROWS_MAX_PAGES; page++) {
+    const batch = await fetchPage(page * pageSize, pageSize);
+    if (batch.length > pageSize) {
+      throw new Error(
+        `Borrower debt page ${page} returned ${batch.length} rows for first: ${pageSize}`
+      );
+    }
+    rows.push(...batch);
+    if (batch.length < pageSize) {
+      return rows;
+    }
+  }
+  throw new Error(
+    `Borrower debt rows exceeded ${BORROWER_DEBT_ROWS_MAX_PAGES} pages of ${pageSize} (${rows.length} rows so far); refusing to return a partial total`
+  );
+}
+function parseSubgraphLoanStatus(label) {
+  if (typeof label !== "string") {
+    throw new Error(`Subgraph loan status is not a string: ${String(label)}`);
+  }
+  const value = LoanStatus[label];
+  if (typeof value !== "number") {
+    throw new Error(`Unknown subgraph loan status label: "${label}"`);
+  }
+  return value;
+}
+function parseSubgraphWei(row) {
+  const raw = row.ucdDebt || "0";
+  if (typeof raw !== "string") {
+    throw new Error(
+      `ucdDebt on position ${row.id} is not a string: ${String(raw)}`
+    );
+  }
+  let wei;
+  try {
+    wei = BigInt(raw);
+  } catch (error) {
+    throw new Error(
+      `ucdDebt on position ${row.id} is not an integer wei string: "${raw}"`,
+      { cause: error }
+    );
+  }
+  if (wei < 0n) {
+    throw new Error(`Negative ucdDebt on position ${row.id}: ${raw}`);
+  }
+  return wei;
+}
+var WEI_PER_UCD = 10n ** 18n;
+function weiToHumanUcdString(wei) {
+  if (wei < 0n) {
+    throw new Error(`Cannot render negative wei: ${wei}`);
+  }
+  const whole = wei / WEI_PER_UCD;
+  const frac = (wei % WEI_PER_UCD).toString().padStart(18, "0").replace(/0+$/, "");
+  return frac.length > 0 ? `${whole}.${frac}` : `${whole}`;
+}
+var STATUS_ORDINALS = Object.values(LoanStatus).filter((v) => typeof v === "number").sort((a, b) => a - b);
+function buildBorrowerUcdDebtSummary(borrower, rows, fetchedAt = Date.now()) {
+  let totalWei = 0n;
+  const counts = /* @__PURE__ */ new Map();
+  for (const row of rows) {
+    totalWei += parseSubgraphWei(row);
+    const status = parseSubgraphLoanStatus(row.status);
+    counts.set(status, (counts.get(status) ?? 0) + 1);
+  }
+  const byStatus = [];
+  for (const status of STATUS_ORDINALS) {
+    const count = counts.get(status);
+    if (count === void 0) {
+      continue;
+    }
+    byStatus.push({ status, statusLabel: LoanStatus[status], count });
+  }
+  return {
+    borrower: borrower.toLowerCase(),
+    loanCount: rows.length,
+    totalUcdDebt: totalWei.toString(),
+    totalUcdDebtHuman: weiToHumanUcdString(totalWei),
+    byStatus,
+    source: "subgraph",
+    fetchedAt
+  };
+}
+
+// src/modules/loan/loan-query.module.ts
 var POSITION_CORE_ABI = [
   "function getPositionDetails(bytes32) view returns (tuple(bytes32 positionId, bytes32 pkpId, uint256 ucdDebt, string vaultAddress, address borrower, uint40 createdAt, uint40 lastUpdated, uint16 selectedTerm, uint40 expiryAt, uint8 status, uint40 previousExpiryAt, uint16 totalTerm))"
 ];
@@ -10775,6 +10922,43 @@ var LoanQuery = class {
   async getLoansByBorrower(borrower, pagination, orderBy, orderDirection) {
     return this.getLoans({ borrower, orderBy, orderDirection }, pagination);
   }
+  /**
+   * Combined UCD debt + by-status counts for a borrower from ONE pass over the
+   * subgraph's raw rows (`graphClient.getBorrowerDebtRows`): BigInt wei sum, strict
+   * status labels, `source: "subgraph"`.
+   *
+   * INDEXED figure, not a transaction input — the subgraph lags writes. Anything that
+   * sizes a repayment reads the chain (`getPositionDetailsView`). Fails loud: a page
+   * failure or the page cap is a SUBGRAPH-category failure carrying the cause; there
+   * is no partial total.
+   */
+  async getBorrowerUcdDebtSummary(borrower) {
+    const trimmed = typeof borrower === "string" ? borrower.trim() : "";
+    if (!isAddress2(trimmed)) {
+      return failure(
+        new SDKError({
+          message: `Borrower must be an EVM address for a UCD debt summary, got "${trimmed}"`,
+          category: "VALIDATION" /* VALIDATION */,
+          severity: "LOW" /* LOW */,
+          context: { borrower: trimmed }
+        })
+      );
+    }
+    return tryCatchAsync(
+      async () => {
+        const rows = await this.config.graphClient.getBorrowerDebtRows(trimmed);
+        return buildBorrowerUcdDebtSummary(trimmed, rows);
+      },
+      (error) => error instanceof SDKError ? error : new SDKError({
+        message: `Borrower UCD debt summary failed for ${trimmed}: ${error instanceof Error ? error.message : String(error)}`,
+        category: "SUBGRAPH" /* SUBGRAPH */,
+        severity: "MEDIUM" /* MEDIUM */,
+        originalError: error instanceof Error ? error : void 0,
+        cause: error,
+        context: { borrower: trimmed }
+      })
+    );
+  }
   /**
    * Get active loans (status = ACTIVE)
    *
@@ -12309,10 +12493,36 @@ var GraphClient = class {
   }
 };
 
-// src/constants/chunks/sdk-limits.ts
-var THE_GRAPH_MAX_BATCH_SIZE = 1e3;
-
 // src/graphs/diamond-hands.ts
+var GET_USER_POSITIONS_DOCUMENT = `
+      query GetUserPositions($borrower: Bytes!, $first: Int, $skip: Int, $orderBy: Position_orderBy, $orderDirection: OrderDirection) {
+        user(id: $borrower) {
+          id
+          positions(first: $first, skip: $skip, orderBy: $orderBy, orderDirection: $orderDirection) {
+            id
+            pkpId
+            borrower {
+              createdAt
+              id
+            }
+            # btcAmount removed - balance is now queried on-chain via lit-actions with signature validation
+            ucdMinted
+            ucdPaid
+            ucdDebt
+            collateralRatio
+            requestedCollateralRatio
+            selectedTerm
+            status
+            createdAt
+            createdAtBlock
+            lastUpdated
+            originalTerm
+            remainingDebt
+            expiryAt
+          }
+        }
+      }
+    `;
 function normalizePkpId2(pkpId) {
   const raw = pkpId.startsWith("0x") ? pkpId.slice(2) : pkpId;
   if (raw.length === 64 && raw.startsWith("000000000000000000000000") && raw !== "0".repeat(64)) {
@@ -12630,35 +12840,7 @@ var DiamondHandsGraph = class {
    * Get user positions from subgraph
    */
   async getUserPositionsOnly(userAddress, first, skip, orderBy, orderDirection) {
-    const query = `
-      query GetUserPositions($borrower: Bytes!, $first: Int, $skip: Int, $orderBy: Position_orderBy, $orderDirection: OrderDirection) {
-        user(id: $borrower) {
-          id
-          positions(first: $first, skip: $skip, orderBy: $orderBy, orderDirection: $orderDirection) {
-            id
-            pkpId
-            borrower {
-              createdAt
-              id
-            }
-            # btcAmount removed - balance is now queried on-chain via lit-actions with signature validation
-            ucdMinted
-            ucdPaid
-            ucdDebt
-            collateralRatio
-            requestedCollateralRatio
-            selectedTerm
-            status
-            createdAt
-            createdAtBlock
-            lastUpdated
-            originalTerm
-            remainingDebt
-            expiryAt
-          }
-        }
-      }
-    `;
+    const query = GET_USER_POSITIONS_DOCUMENT;
     const variables = {
       borrower: userAddress.toLowerCase(),
       first: first || void 0,
@@ -12676,6 +12858,45 @@ var DiamondHandsGraph = class {
     }
     return positions;
   }
+  /**
+   * Raw `{ id, status, ucdDebt }` for EVERY position of a borrower: one round trip per
+   * 1000 positions, no count walk, no vault RPCs, and no `LoanData` transform (which
+   * coerces wei to a float and leaves `status` a string cast to the numeric enum).
+   *
+   * Deliberately issues the `GetUserPositions` document rather than a leaner one: the
+   * lit-ops graph proxy only passes allowlisted documents (graph-document-policy.ts),
+   * and that one is already listed, so this needs no server change. The extra fields
+   * cost bytes, not round trips.
+   *
+   * Throws past `BORROWER_DEBT_ROWS_MAX_PAGES` — never a partial set.
+   */
+  async getBorrowerDebtRows(borrower) {
+    const borrowerId = borrower.toLowerCase();
+    return collectBorrowerDebtRows(async (skip, first) => {
+      const result = await this.client.execute(GET_USER_POSITIONS_DOCUMENT, {
+        borrower: borrowerId,
+        first,
+        skip,
+        orderBy: "id",
+        orderDirection: "asc"
+      });
+      if (result?.user == null) {
+        if (skip > 0) {
+          throw new Error(
+            `getBorrowerDebtRows: user ${borrowerId} vanished from the subgraph at skip ${skip}`
+          );
+        }
+        return [];
+      }
+      const positions = result.user.positions;
+      if (!Array.isArray(positions)) {
+        throw new Error(
+          `getBorrowerDebtRows: subgraph returned no positions array for ${borrowerId} at skip ${skip}`
+        );
+      }
+      return positions.filter((p) => p != null);
+    });
+  }
   /**
    * Get user positions, plus an accurate total count.
    *
@@ -18896,6 +19117,625 @@ async function mintAgentPkp(params) {
     clearTimeout(timeout);
   }
 }
+var AGENT_STATUS = { None: 0, Active: 1, Revoked: 2 };
+function planAgentBinding(params) {
+  const { isActive, record, nowSeconds } = params;
+  if (isActive)
+    return { kind: "reuse", agent: record.agent };
+  const status = Number(record.status);
+  if (status === AGENT_STATUS.None || status === AGENT_STATUS.Revoked) {
+    return { kind: "register" };
+  }
+  if (status !== AGENT_STATUS.Active) {
+    throw new Error(`Unknown agent status ${status} in AgentDelegationRegistry`);
+  }
+  if (Number(record.validUntil) > nowSeconds) {
+    throw new Error(
+      "AgentDelegationRegistry reports an unexpired agent as inactive \u2014 the registry is paused. Agent delegation cannot be changed until it is unpaused."
+    );
+  }
+  return { kind: "rotate" };
+}
+
+// src/utils/assert-provider-chain.ts
+async function describeProviderChainMismatch(provider, chainId) {
+  const actual = Number((await provider.getNetwork()).chainId);
+  if (actual === chainId)
+    return null;
+  return `Network mismatch: the SDK was configured for chainId ${chainId}, but the provider is connected to chainId ${actual}. Switch the wallet/RPC to chainId ${chainId}, or configure the SDK for chainId ${actual}. Nothing was signed.`;
+}
+
+// src/utils/sign-guard/psm-exchange.ts
+import { ethers as ethers5 } from "ethers";
+
+// src/utils/sign-guard/errors.ts
+var TxValidationError = class extends Error {
+  /**
+   * @param subject What is being refused. Defaults to the server-returned transaction the
+   *   validator exists for; client-built flows (the PSM exchange) name themselves instead.
+   */
+  constructor(msg, subject = "server-returned transaction") {
+    super(`Refusing to sign ${subject}: ${msg}`);
+    this.name = "TxValidationError";
+  }
+};
+
+// src/utils/sign-guard/signable-functions.ts
+import { ethers as ethers2 } from "ethers";
+var SIGNABLE_FUNCTIONS = [
+  "function mintUCD(bytes32 positionId, uint256 mintAmount, uint256 mintFee, uint256 newDebt, uint256 newCollateral, uint256 btcPrice, bytes32 authorizedSpendsHash, bytes32 ucdDebtHash, bytes32 contractHash, uint256 quantumTimestamp, bytes calldata mintValidatorSignature) external returns (bool)",
+  // `makePayment` is the ONLY repayment entry point. A `repayPosition` entry
+  // used to sit here; it is not a function on any deployed contract — the
+  // compiled PositionManager ABI has no `repay*` function at all, and the name
+  // survives only in `archive/` prototypes. Nothing in lit-ops-server, the
+  // lit-actions, or the SDK ever emitted it, and AgentModule never whitelisted
+  // it. A signable-function whitelist should not carry calldata shapes the
+  // protocol cannot execute.
+  "function makePayment(bytes32 positionId, uint256 paymentAmount, uint256 quantumTimestamp, uint256 btcPrice, bytes calldata paymentValidatorSignature) external returns (bool)",
+  "function extendPosition(bytes32 positionId, uint256 selectedTerm, uint256 quantumTimestamp, uint256 btcPrice, uint256 availableBTCBalance, uint256 proRataRenewalFee, bytes calldata extensionValidatorSignature) external returns (bool)",
+  "function extendPosition(bytes32 positionId, uint256 selectedTerm, uint256 quantumTimestamp, uint256 btcPrice, uint256 availableBTCBalance, bytes calldata extensionValidatorSignature) external returns (bool)",
+  // Struct-version: matches the actual on-chain function signature and the
+  // SDK's calldata builder. An earlier 3-arg declaration was stale and would
+  // silently fail to decode real `withdrawBTC` calldata. networkFee is NOT a
+  // contract param — it is an off-chain Phase-2 BTC tx fee, validated elsewhere.
+  "function withdrawBTC((bytes32 positionId, bytes32 actionHash, bytes32 authorizedSpendsHash, bytes32 ucdDebtHash, bytes32 contractBundleHash, string withdrawalAddress, uint256 totalDeduction, uint256 newCollateral, uint256 quantumTimestamp, uint256 btcPrice, string utxoTxid, uint32 utxoVout) params, bytes withdrawalValidatorSignature, bytes btcSpendAuthSignature) external returns (bool)",
+  // `cancelStaleSpendByOwner` removed in audit #62210 follow-up — the on-chain
+  // function reverts permanently. The trustless replacement
+  // (`cancelStaleSpendWithProof` on BTCSpendAuthorizer) lands via a separate
+  // entry when its LIT Action ships.
+  "function approve(address spender, uint256 amount) external returns (bool)",
+  "function setPositionDelegate(bytes32 positionId, address newDelegate) external",
+  // Position creation. Signed opaquely by the SDK (like withdrawBTC), so
+  // without an entry here it decoded as "<unparseable>" and the CLI's
+  // WithdrawGuard waved it through — the flow that locks the user's BTC
+  // collateral had no client-side pin at all.
+  "function createPosition(bytes32 pkpId, bytes calldata validatorSignature, string mainnetVaultAddress, string regtestVaultAddress, uint256 selectedTermMonths, uint256 validatorVersion, bytes calldata pkpPublicKey) external returns (bytes32 positionId)",
+  // SimplePSMV2 — the PSM exchange pair. Direct EOA calls, never routed through
+  // AgentModule; the parity test documents them as client-only.
+  "function swap(address stablecoin, uint256 amountIn, uint256 minUcdOut) external returns (uint256)",
+  "function redeem(address stablecoin, uint256 ucdAmount, uint256 minStablecoinOut) external returns (uint256)",
+  // BitcoinWithdrawalAddressRegistry — `msg.sender` must be the borrower, so
+  // this too is client-only and never module-whitelisted.
+  "function addAddress(string btcAddress) external"
+];
+var IFACE = new ethers2.Interface(SIGNABLE_FUNCTIONS);
+function encodeSignable(fn, args) {
+  return IFACE.encodeFunctionData(fn, args);
+}
+function decodeSignable(data) {
+  try {
+    const parsed = IFACE.parseTransaction({ data });
+    if (!parsed) {
+      throw new TxValidationError(
+        `unsignedTx.data does not decode against the signable-function whitelist`
+      );
+    }
+    return { name: parsed.name, args: parsed.args };
+  } catch (e) {
+    if (e instanceof TxValidationError)
+      throw e;
+    throw new TxValidationError(
+      `unsignedTx.data does not decode against the signable-function whitelist: ${e.message}`
+    );
+  }
+}
+
+// src/utils/sign-guard/tx-validator.ts
+import { ethers as ethers4 } from "ethers";
+
+// src/utils/sign-guard/fee-ceiling.ts
+import { ethers as ethers3 } from "ethers";
+var MAX_GAS_LIMIT = 5000000n;
+var MAX_FEE_PER_GAS_WEI = 2000000000000n;
+var DEFAULT_MAX_TX_FEE_WEI = 250000000000000000n;
+var DEFAULT_FEE_CEILING = {
+  maxGasLimit: MAX_GAS_LIMIT,
+  maxFeePerGasWei: MAX_FEE_PER_GAS_WEI,
+  maxTxFeeWei: DEFAULT_MAX_TX_FEE_WEI
+};
+function fmtEth(wei) {
+  return `${ethers3.formatEther(wei)} ETH`;
+}
+function fmtGwei(wei) {
+  return `${ethers3.formatUnits(wei, "gwei")} gwei`;
+}
+function worstCaseFeeWei(gasLimit, maxFeePerGas) {
+  if (gasLimit == null || maxFeePerGas == null)
+    return null;
+  return gasLimit * maxFeePerGas;
+}
+function assertFeeCeiling(gasLimit, maxFeePerGas, raise, ceiling = DEFAULT_FEE_CEILING) {
+  if (gasLimit != null && gasLimit > ceiling.maxGasLimit) {
+    raise(`gasLimit ${gasLimit} exceeds the signing ceiling of ${ceiling.maxGasLimit}`);
+  }
+  if (maxFeePerGas != null && maxFeePerGas > ceiling.maxFeePerGasWei) {
+    raise(
+      `maxFeePerGas ${fmtGwei(maxFeePerGas)} exceeds the signing ceiling of ${fmtGwei(ceiling.maxFeePerGasWei)}`
+    );
+  }
+  const worst = worstCaseFeeWei(gasLimit, maxFeePerGas);
+  if (worst != null && worst > ceiling.maxTxFeeWei) {
+    raise(
+      `worst-case transaction fee ${fmtEth(worst)} (gasLimit ${gasLimit} \xD7 ${fmtGwei(maxFeePerGas)}) exceeds the signing ceiling of ${fmtEth(ceiling.maxTxFeeWei)}.${ceiling.raiseHint ? ` ${ceiling.raiseHint}` : ""}`
+    );
+  }
+}
+
+// src/utils/sign-guard/tx-validator.ts
+function eqAddr(a, b) {
+  if (!a || !b)
+    return false;
+  try {
+    return ethers4.getAddress(a) === ethers4.getAddress(b);
+  } catch {
+    return false;
+  }
+}
+function readToAddress(tx) {
+  const to = tx["to"];
+  if (typeof to !== "string") {
+    throw new TxValidationError(`unsignedTx.to is missing or not a string`);
+  }
+  return to;
+}
+function readData(tx) {
+  const data = tx["data"];
+  if (typeof data !== "string" || !data.startsWith("0x")) {
+    throw new TxValidationError(`unsignedTx.data missing or malformed`);
+  }
+  return data;
+}
+function readChainId(tx) {
+  const c = tx["chainId"];
+  if (c == null)
+    return null;
+  if (typeof c === "number")
+    return c;
+  if (typeof c === "string")
+    return parseInt(c.startsWith("0x") ? c.slice(2) : c, c.startsWith("0x") ? 16 : 10);
+  if (typeof c === "bigint")
+    return Number(c);
+  return null;
+}
+function readOptionalBigInt(tx, key) {
+  const v = tx[key];
+  if (v == null)
+    return null;
+  try {
+    if (typeof v === "bigint")
+      return v;
+    if (typeof v === "number")
+      return BigInt(v);
+    if (typeof v === "string")
+      return BigInt(v);
+    return BigInt(v.toString());
+  } catch {
+    throw new TxValidationError(`unsignedTx.${key} is present but not a valid integer`);
+  }
+}
+function readValue(tx) {
+  const v = tx["value"];
+  if (v == null)
+    return 0n;
+  if (typeof v === "string")
+    return BigInt(v);
+  if (typeof v === "number")
+    return BigInt(v);
+  if (typeof v === "bigint")
+    return v;
+  const maybe = v;
+  if (typeof maybe.toBigInt === "function")
+    return maybe.toBigInt();
+  if (typeof maybe.toString === "function")
+    return BigInt(maybe.toString());
+  throw new TxValidationError(`unsignedTx.value has unrecognized type`);
+}
+function normalizePositionId(id) {
+  const hex = id.startsWith("0x") ? id : `0x${id}`;
+  return ethers4.zeroPadValue(hex, 32).toLowerCase();
+}
+function requirePositionId(actual, expected) {
+  const txPositionId = String(actual).toLowerCase();
+  if (txPositionId !== normalizePositionId(expected)) {
+    throw new TxValidationError(
+      `positionId mismatch \u2014 tx ${txPositionId}, expected ${normalizePositionId(expected)}`
+    );
+  }
+}
+function validateUnsignedTx(unsignedTx, expected, vctx) {
+  const txChainId = readChainId(unsignedTx);
+  if (txChainId == null) {
+    throw new TxValidationError(
+      `unsignedTx.chainId is missing \u2014 refusing to sign a transaction with no chain binding (client is on ${vctx.chainId})`
+    );
+  }
+  if (txChainId !== vctx.chainId) {
+    throw new TxValidationError(
+      `chainId mismatch \u2014 tx says ${txChainId}, client is on ${vctx.chainId}`
+    );
+  }
+  const value = readValue(unsignedTx);
+  if (value !== 0n) {
+    throw new TxValidationError(
+      `unsignedTx.value is non-zero (${value}); none of the protocol functions accept ETH`
+    );
+  }
+  assertFeeCeiling(
+    readOptionalBigInt(unsignedTx, "gasLimit"),
+    readOptionalBigInt(unsignedTx, "maxFeePerGas") ?? readOptionalBigInt(unsignedTx, "gasPrice"),
+    (msg) => {
+      throw new TxValidationError(msg);
+    },
+    vctx.feeCeiling
+  );
+  const to = readToAddress(unsignedTx);
+  const data = readData(unsignedTx);
+  const { name, args } = decodeSignable(data);
+  const pm = vctx.contracts.PositionManager;
+  switch (expected.kind) {
+    case "mint": {
+      if (name !== "mintUCD") {
+        throw new TxValidationError(`expected mintUCD, server returned ${name}`);
+      }
+      if (!eqAddr(to, pm)) {
+        throw new TxValidationError(`mintUCD must target PositionManager (${pm}), got ${to}`);
+      }
+      requirePositionId(args[0], expected.positionId);
+      const txMintAmount = BigInt(String(args[1]));
+      if (txMintAmount.toString() !== expected.amountWei) {
+        throw new TxValidationError(`mintAmount mismatch \u2014 tx ${txMintAmount}, expected ${expected.amountWei}`);
+      }
+      const txMintFee = BigInt(String(args[2]));
+      if (txMintFee.toString() !== expected.mintFeeWei) {
+        throw new TxValidationError(`mintFee mismatch \u2014 tx ${txMintFee}, expected ${expected.mintFeeWei}`);
+      }
+      break;
+    }
+    case "repay": {
+      if (name !== "makePayment") {
+        throw new TxValidationError(`expected makePayment, server returned ${name}`);
+      }
+      if (!eqAddr(to, pm)) {
+        throw new TxValidationError(`${name} must target PositionManager (${pm}), got ${to}`);
+      }
+      requirePositionId(args[0], expected.positionId);
+      const txAmount = BigInt(String(args[1]));
+      if (txAmount.toString() !== expected.amountWei) {
+        throw new TxValidationError(`paymentAmount mismatch \u2014 tx ${txAmount}, expected ${expected.amountWei}`);
+      }
+      break;
+    }
+    case "extend": {
+      if (name !== "extendPosition") {
+        throw new TxValidationError(`expected extendPosition, server returned ${name}`);
+      }
+      if (!eqAddr(to, pm)) {
+        throw new TxValidationError(`extendPosition must target PositionManager (${pm}), got ${to}`);
+      }
+      requirePositionId(args[0], expected.positionId);
+      const txTerm = Number(args[1]);
+      if (txTerm !== expected.selectedTerm) {
+        throw new TxValidationError(`selectedTerm mismatch \u2014 tx ${txTerm}, expected ${expected.selectedTerm}`);
+      }
+      if (expected.upperBoundProRataFeeWei != null && args.length >= 7) {
+        const txFee = BigInt(String(args[5]));
+        const upper = BigInt(expected.upperBoundProRataFeeWei);
+        if (txFee > upper) {
+          throw new TxValidationError(
+            `proRataRenewalFee=${txFee} exceeds upper bound=${upper}. A compromised validator could otherwise inflate the fee to drain UCD.`
+          );
+        }
+      }
+      break;
+    }
+    case "withdraw-btc": {
+      if (name !== "withdrawBTC") {
+        throw new TxValidationError(`expected withdrawBTC, server returned ${name}`);
+      }
+      if (!eqAddr(to, pm)) {
+        throw new TxValidationError(`withdrawBTC must target PositionManager (${pm}), got ${to}`);
+      }
+      const paramsTuple = args[0];
+      requirePositionId(paramsTuple[0], expected.positionId);
+      const txWithdrawalAddress = String(paramsTuple[5]);
+      if (txWithdrawalAddress !== expected.btcAddress) {
+        throw new TxValidationError(`btcAddress mismatch \u2014 tx '${txWithdrawalAddress}', expected '${expected.btcAddress}'`);
+      }
+      if (expected.upperBoundTotalDeduction != null) {
+        const txDeduction = BigInt(String(paramsTuple[6]));
+        const upper = BigInt(expected.upperBoundTotalDeduction);
+        if (txDeduction > upper) {
+          throw new TxValidationError(
+            `totalDeduction=${txDeduction} exceeds approved upper bound=${upper}. A compromised validator could otherwise drain collateral beyond the approved amount.`
+          );
+        }
+      }
+      break;
+    }
+    case "ucd-approve": {
+      if (name !== "approve") {
+        throw new TxValidationError(`expected ERC-20 approve, server returned ${name}`);
+      }
+      const ucd = vctx.contracts.UCDToken;
+      if (!eqAddr(to, ucd)) {
+        throw new TxValidationError(`approve must target UCDToken (${ucd}), got ${to}`);
+      }
+      const spender = String(args[0]);
+      const ok = expected.spenderCandidates.some((s) => eqAddr(spender, s));
+      if (!ok) {
+        throw new TxValidationError(
+          `approve spender ${spender} not in expected set ${expected.spenderCandidates.join(", ")}`
+        );
+      }
+      const amt = BigInt(String(args[1]));
+      const min = BigInt(expected.minAmountWei);
+      if (amt < min) {
+        throw new TxValidationError(`approve amount ${amt} is less than required ${min}`);
+      }
+      const SANITY_MAX = min * 1000n;
+      if (amt > SANITY_MAX) {
+        throw new TxValidationError(`approve amount ${amt} exceeds sanity cap ${SANITY_MAX} (1000x requested)`);
+      }
+      break;
+    }
+    case "create-position": {
+      if (name !== "createPosition") {
+        throw new TxValidationError(`expected createPosition, server returned ${name}`);
+      }
+      if (!eqAddr(to, pm)) {
+        throw new TxValidationError(`createPosition must target PositionManager (${pm}), got ${to}`);
+      }
+      const txTerm = BigInt(String(args[4]));
+      if (txTerm !== BigInt(expected.selectedTerm)) {
+        throw new TxValidationError(`selectedTerm mismatch \u2014 tx ${txTerm}, expected ${expected.selectedTerm}`);
+      }
+      break;
+    }
+    case "set-position-delegate": {
+      if (name !== "setPositionDelegate") {
+        throw new TxValidationError(`expected setPositionDelegate, server returned ${name}`);
+      }
+      if (!eqAddr(to, expected.registryAddress)) {
+        throw new TxValidationError(
+          `setPositionDelegate must target PositionDelegateRegistry (${expected.registryAddress}), got ${to}`
+        );
+      }
+      requirePositionId(args[0], expected.positionId);
+      const txDelegate = String(args[1]);
+      if (!eqAddr(txDelegate, expected.delegate)) {
+        throw new TxValidationError(`delegate mismatch \u2014 tx ${txDelegate}, expected ${expected.delegate}`);
+      }
+      break;
+    }
+    case "bwar-add-address": {
+      if (name !== "addAddress") {
+        throw new TxValidationError(`expected addAddress, decoded ${name}`);
+      }
+      if (!eqAddr(to, expected.registryAddress)) {
+        throw new TxValidationError(
+          `addAddress must target the BitcoinWithdrawalAddressRegistry (${expected.registryAddress}), got ${to}`
+        );
+      }
+      if (String(args[0]) !== expected.btcAddress) {
+        throw new TxValidationError(
+          `btcAddress mismatch \u2014 tx says '${String(args[0])}', user asked for '${expected.btcAddress}'`
+        );
+      }
+      break;
+    }
+    case "stablecoin-approve": {
+      if (name !== "approve") {
+        throw new TxValidationError(`expected ERC-20 approve, server returned ${name}`);
+      }
+      if (!eqAddr(to, expected.tokenAddress)) {
+        throw new TxValidationError(`approve must target the stablecoin token (${expected.tokenAddress}), got ${to}`);
+      }
+      if (!eqAddr(String(args[0]), expected.spender)) {
+        throw new TxValidationError(`approve spender must be the PSM (${expected.spender}), got ${String(args[0])}`);
+      }
+      if (BigInt(String(args[1])).toString() !== expected.amountUnits) {
+        throw new TxValidationError(
+          `approve amount must be EXACTLY ${expected.amountUnits} (exact-amount rule), got ${BigInt(String(args[1]))}`
+        );
+      }
+      break;
+    }
+    case "ucd-approve-controller": {
+      if (name !== "approve") {
+        throw new TxValidationError(`expected ERC-20 approve, server returned ${name}`);
+      }
+      if (!eqAddr(to, expected.ucdTokenAddress)) {
+        throw new TxValidationError(`approve must target UCDToken (${expected.ucdTokenAddress}), got ${to}`);
+      }
+      if (!eqAddr(String(args[0]), expected.spender)) {
+        throw new TxValidationError(`approve spender must be the UCDController (${expected.spender}), got ${String(args[0])}`);
+      }
+      if (BigInt(String(args[1])).toString() !== expected.amountWei) {
+        throw new TxValidationError(
+          `approve amount must be EXACTLY ${expected.amountWei} (exact-amount rule), got ${BigInt(String(args[1]))}`
+        );
+      }
+      break;
+    }
+    case "psm-swap": {
+      if (name !== "swap")
+        throw new TxValidationError(`expected swap, server returned ${name}`);
+      if (!eqAddr(to, expected.psmAddress)) {
+        throw new TxValidationError(`swap must target the PSM (${expected.psmAddress}), got ${to}`);
+      }
+      if (!eqAddr(String(args[0]), expected.stablecoin))
+        throw new TxValidationError(`swap stablecoin mismatch`);
+      if (BigInt(String(args[1])).toString() !== expected.amountIn)
+        throw new TxValidationError(`swap amountIn mismatch`);
+      if (BigInt(String(args[2])).toString() !== expected.minOut)
+        throw new TxValidationError(`swap minUcdOut mismatch`);
+      if (BigInt(expected.minOut) === 0n) {
+        throw new TxValidationError(`swap minUcdOut is 0 \u2014 a slippage floor is mandatory (SlippageProtectionRequired)`);
+      }
+      break;
+    }
+    case "psm-redeem": {
+      if (name !== "redeem")
+        throw new TxValidationError(`expected redeem, server returned ${name}`);
+      if (!eqAddr(to, expected.psmAddress)) {
+        throw new TxValidationError(`redeem must target the PSM (${expected.psmAddress}), got ${to}`);
+      }
+      if (!eqAddr(String(args[0]), expected.stablecoin))
+        throw new TxValidationError(`redeem stablecoin mismatch`);
+      if (BigInt(String(args[1])).toString() !== expected.amountUcdWei)
+        throw new TxValidationError(`redeem ucdAmount mismatch`);
+      if (BigInt(String(args[2])).toString() !== expected.minOut)
+        throw new TxValidationError(`redeem minStablecoinOut mismatch`);
+      if (BigInt(expected.minOut) === 0n) {
+        throw new TxValidationError(`redeem minStablecoinOut is 0 \u2014 a slippage floor is mandatory (SlippageProtectionRequired)`);
+      }
+      break;
+    }
+    default: {
+      const _exhaustive = expected;
+      throw new TxValidationError(`unhandled expected action kind: ${JSON.stringify(_exhaustive)}`);
+    }
+  }
+}
+
+// src/utils/sign-guard/psm-exchange.ts
+function buildPsmApproveTx(p) {
+  return {
+    to: p.token,
+    data: encodeSignable("approve", [p.spender, p.amount]),
+    value: "0x0",
+    chainId: p.chainId
+  };
+}
+function buildPsmSwapTx(p) {
+  return {
+    to: p.psm,
+    data: encodeSignable("swap", [p.stablecoin, p.amountIn, p.minOut]),
+    value: "0x0",
+    chainId: p.chainId
+  };
+}
+function buildPsmRedeemTx(p) {
+  return {
+    to: p.psm,
+    data: encodeSignable("redeem", [p.stablecoin, p.ucdAmount, p.minOut]),
+    value: "0x0",
+    chainId: p.chainId
+  };
+}
+var PSM_READS_ABI = ["function supportedStablecoins(address) view returns (bool)"];
+var ERC20_READS_ABI = ["function allowance(address owner, address spender) view returns (uint256)"];
+function psmExchangeReadsFromProvider(provider, psmAddress) {
+  const psm = new ethers5.Contract(psmAddress, PSM_READS_ABI, provider);
+  return {
+    isStablecoinSupported: async (stablecoin) => await psm.getFunction("supportedStablecoins")(stablecoin),
+    allowance: async (token, owner, spender) => await new ethers5.Contract(token, ERC20_READS_ABI, provider).getFunction("allowance")(owner, spender)
+  };
+}
+var refuse = (direction, msg) => new TxValidationError(msg, `PSM ${direction}`);
+function requireAddress(direction, label, value) {
+  if (!value || !ethers5.isAddress(value)) {
+    throw refuse(direction, `${label} address is missing or invalid (${String(value)})`);
+  }
+  return ethers5.getAddress(value);
+}
+async function planPsmExchange(params) {
+  const { direction, amountIn, minOut, vctx, reads } = params;
+  const chainId = vctx.chainId;
+  if (amountIn <= 0n) {
+    throw refuse(direction, `amount must be greater than zero (got ${amountIn})`);
+  }
+  if (minOut <= 0n) {
+    throw refuse(direction, `minimum-out floor must be greater than zero (got ${minOut}) \u2014 a zero floor is refused on-chain`);
+  }
+  const owner = requireAddress(direction, "owner", params.owner);
+  const psm = requireAddress(direction, "SimplePSMV2", params.addresses.psm);
+  const stablecoin = requireAddress(direction, "stablecoin", params.addresses.stablecoin);
+  const isSwap = direction === "swap";
+  const token = isSwap ? stablecoin : requireAddress(direction, "UCDToken", params.addresses.ucdToken);
+  const spender = isSwap ? psm : requireAddress(direction, "UCDController", params.addresses.ucdController);
+  if (!await reads.isStablecoinSupported(stablecoin)) {
+    throw refuse(direction, `stablecoin ${stablecoin} is not supported by the PSM at ${psm}`);
+  }
+  const approveExpected = (amount) => isSwap ? { kind: "stablecoin-approve", tokenAddress: token, spender, amountUnits: amount.toString() } : { kind: "ucd-approve-controller", ucdTokenAddress: token, spender, amountWei: amount.toString() };
+  const allowanceBefore = await reads.allowance(token, owner, spender);
+  const approvals = [];
+  if (allowanceBefore < amountIn) {
+    if (allowanceBefore > 0n) {
+      approvals.push({
+        step: "reset-approve",
+        tx: buildPsmApproveTx({ token, spender, amount: 0n, chainId }),
+        expected: approveExpected(0n)
+      });
+    }
+    approvals.push({
+      step: "approve",
+      tx: buildPsmApproveTx({ token, spender, amount: amountIn, chainId }),
+      expected: approveExpected(amountIn)
+    });
+  }
+  const exec = isSwap ? {
+    step: "swap",
+    tx: buildPsmSwapTx({ psm, stablecoin, amountIn, minOut, chainId }),
+    expected: { kind: "psm-swap", psmAddress: psm, stablecoin, amountIn: amountIn.toString(), minOut: minOut.toString() }
+  } : {
+    step: "redeem",
+    tx: buildPsmRedeemTx({ psm, stablecoin, ucdAmount: amountIn, minOut, chainId }),
+    expected: {
+      kind: "psm-redeem",
+      psmAddress: psm,
+      stablecoin,
+      amountUcdWei: amountIn.toString(),
+      minOut: minOut.toString()
+    }
+  };
+  for (const leg of [...approvals, exec]) {
+    validateUnsignedTx({ ...leg.tx }, leg.expected, vctx);
+  }
+  return { direction, owner, token, spender, amountIn, minOut, allowanceBefore, approvals, exec };
+}
+async function executePsmPlan(plan, signer, vctx) {
+  const approvalHashes = [];
+  const residual = () => approvalHashes.length === 0 ? "" : ` An approval already landed (tx ${approvalHashes[approvalHashes.length - 1]}): an allowance of exactly ${plan.amountIn} to ${plan.spender} stands. It authorizes only that amount; the next exchange uses or replaces it.`;
+  const sendLeg = async (leg) => {
+    const request = { to: leg.tx.to, data: leg.tx.data, value: 0n, chainId: leg.tx.chainId };
+    validateUnsignedTx({ ...request }, leg.expected, vctx);
+    const sent = await signer.sendTransaction(request);
+    const receipt = await sent.wait();
+    if (!receipt)
+      throw new Error(`PSM ${leg.step} tx ${sent.hash} returned no receipt`);
+    if (receipt.status !== 1)
+      throw new Error(`PSM ${leg.step} tx ${sent.hash} reverted`);
+    return { hash: sent.hash, blockNumber: receipt.blockNumber };
+  };
+  for (const leg of plan.approvals) {
+    const landed = await sendLeg(leg).catch((e) => {
+      throw new Error(`PSM ${leg.step} failed: ${e instanceof Error ? e.message : String(e)}.${residual()}`);
+    });
+    approvalHashes.push(landed.hash);
+  }
+  const exec = await sendLeg(plan.exec).catch((e) => {
+    throw new Error(`PSM ${plan.exec.step} failed: ${e instanceof Error ? e.message : String(e)}.${residual()}`);
+  });
+  return { ...exec, approvalHashes };
+}
+
+// src/utils/lit-action-chain-name.ts
+var LIT_ACTION_CHAIN_NAMES = Object.freeze({
+  1: "ethereum",
+  11155111: "sepolia",
+  1337: "hardhat",
+  31337: "hardhat"
+});
+function litActionChainNameForChainId(chainId) {
+  const name = LIT_ACTION_CHAIN_NAMES[Number(chainId)];
+  if (!name) {
+    throw new Error(
+      `Unsupported chainId ${String(chainId)} for a Lit Action (supported: ${Object.keys(LIT_ACTION_CHAIN_NAMES).join(", ")})`
+    );
+  }
+  return name;
+}
 
 // src/modules/mock/mock-token-manager.module.ts
 var MockTokenManager = class {
@@ -19880,6 +20720,18 @@ var DiamondHandsSDK = class _DiamondHandsSDK {
    */
   static async create(config) {
     const userProvidedServiceEndpoint = config.serviceEndpoint;
+    if (typeof config.chainId === "number" && config.provider) {
+      const mismatch = await describeProviderChainMismatch(config.provider, config.chainId);
+      if (mismatch) {
+        return failure(
+          new SDKError({
+            message: mismatch,
+            category: "CONFIGURATION" /* CONFIGURATION */,
+            severity: "HIGH" /* HIGH */
+          })
+        );
+      }
+    }
     const enrichedConfig = await _DiamondHandsSDK.enrichConfigWithNetworkDefaults(config);
     if (userProvidedServiceEndpoint) {
       enrichedConfig.serviceEndpoint = userProvidedServiceEndpoint;
@@ -20520,6 +21372,53 @@ var DiamondHandsSDK = class _DiamondHandsSDK {
         if (this.config.debug) {
           log.info(`   Position PKP ID: ${position2.pkpId}`);
         }
+        const termsResult = await this.getTermsWithFees();
+        if (!termsResult.success) {
+          return {
+            success: false,
+            error: `Cannot verify the loan cap before minting: ${termsResult.error.message}`
+          };
+        }
+        const positionTermMonths = Number(position2.selectedTerm);
+        const positionTerm = termsResult.value.terms.find(
+          (term) => term.termMonths === positionTermMonths
+        );
+        if (!positionTerm) {
+          return {
+            success: false,
+            error: `Cannot verify the loan cap before minting: TermManager has no fee entry for the position's ${positionTermMonths}-month term`
+          };
+        }
+        const currentDebtWei = BigInt(position2.ucdDebt);
+        const baseFeeWei = baseMintFeeWei(
+          requestAmountWei,
+          positionTerm.originationFeeBps
+        );
+        if (debtAfterMintExceedsLoanCap({
+          currentDebtWei,
+          mintAmountWei: requestAmountWei,
+          mintFeeWei: baseFeeWei,
+          maxLoanWei: maxLoanValueWei
+        })) {
+          const debtAfterWei = currentDebtWei + requestAmountWei + baseFeeWei;
+          const maxPrincipalUcd = Number(
+            maxPrincipalWithinLoanCap({
+              maxLoanWei: maxLoanValueWei,
+              currentDebtWei,
+              originationFeeBps: positionTerm.originationFeeBps
+            }) / BigInt(10 ** 18)
+          );
+          return {
+            success: false,
+            error: `Amount ${request.amount} UCD plus the ${positionTerm.originationFeeBps / 100}% origination fee (${formatEther(baseFeeWei)} UCD) would take this loan's debt to ${formatEther(debtAfterWei)} UCD, above the protocol maximum of ${formatEther(maxLoanValueWei)} UCD. The largest amount you can mint now is ${maxPrincipalUcd} UCD.`
+          };
+        }
+        if (this.config.debug) {
+          log.info(
+            `\u2705 Fee-inclusive loan cap check passed: ${formatEther(currentDebtWei + requestAmountWei + baseFeeWei)} UCD <= ${formatEther(maxLoanValueWei)} UCD`,
+            {}
+          );
+        }
         let pkpPublicKey;
         let pkpEthAddress;
         const pkpCache = this.cacheManager.getCache("pkp-data", {
@@ -20609,7 +21508,7 @@ var DiamondHandsSDK = class _DiamondHandsSDK {
             `     UCDController: ${contracts?.UCDController || "MISSING"}`
           );
         }
-        const chain = this.config.chain || (Number(network.chainId) === 1 ? "ethereum" : "sepolia");
+        const chain = this.config.chain || litActionChainNameForChainId(network.chainId);
         const devBitcoinProviderUrl = request.customBitcoinRpcUrl || this.config.bitcoinProviders?.[0]?.url;
         if (this.config.debug) {
           log.info(`   Network: ${chain} (chainId: ${network.chainId})`);
@@ -21209,6 +22108,25 @@ Error data: none`
         }
         const selector = simError.selector;
         const errorName = simError.errorName ?? (selector ? `Unknown error ${selector}` : "unknown");
+        const MINT_GUARD_CODES = {
+          "1": "MINT_GUARD_LOAN_MAX_EXCEEDED \u2014 the position's total debt after this mint (existing debt + principal + fee) exceeds maximumLoanValueUcd",
+          "2": "MINT_GUARD_CIRCUIT_BREAKER_EXCEEDED \u2014 exceeds CircuitBreaker maxSingleLoanValue",
+          "3": "MINT_GUARD_PSM_DAILY_EXCEEDED \u2014 exceeds the PSM daily mint limit"
+        };
+        let loanCapDiagnostics = "";
+        if (selector === "0xe6dd4d41") {
+          const guardCode = BigInt(
+            "0x" + String(simError.data).slice(10).padStart(64, "0")
+          ).toString();
+          const guardMeaning = MINT_GUARD_CODES[guardCode] ?? `unknown MintGuardFailed code ${guardCode}`;
+          loanCapDiagnostics = `
+
+MintGuardFailed(${guardCode}): ${guardMeaning}
+  Lit mintAmount: ${validationResponse.mintAmount}
+  Lit mintFee: ${validationResponse.mintFee}
+  Lit newDebt: ${validationResponse.newDebt}
+  Protocol maximum: ${formatEther(maxLoanValueWei)} UCD (fee-inclusive)`;
+        }
         const mintDebtDiagnostics = selector === "0xb9d419a7" || // DebtUpdateVerificationFailed()
         selector === "0xc7e20553" || // DebtUpdateVerificationFailedDetailed(...)
         selector === "0x0cfd2a97" || // MintVerificationMismatch(uint256,uint256)
@@ -21254,7 +22172,7 @@ Quantum Timing Analysis:
 Error selector: ${selector}
 Error data: ${simError.data}
 Call path: mintUCD -> mintUCDWithAuthorization -> increaseDebtFromMint -> finalizeMintDebtIncrease
-Message: ${causeMessage}${quantumContext}${mintDebtDiagnostics}`
+Message: ${causeMessage}${quantumContext}${loanCapDiagnostics}${mintDebtDiagnostics}`
         );
       }
       const tx = await sendEip1559Transaction({
@@ -23851,7 +24769,7 @@ Message: ${causeMessage}${quantumContext}${mintDebtDiagnostics}`
             `     BTCSpendAuthorizer: ${contracts.BTCSpendAuthorizer || "MISSING"}`
           );
         }
-        const chain = this.config.chain || (Number(network.chainId) === 1 ? "ethereum" : "sepolia");
+        const chain = this.config.chain || litActionChainNameForChainId(network.chainId);
         const devBitcoinProviderUrl = this.config.bitcoinProviders?.[0]?.url;
         if (this.config.debug) {
           log.info(`   Network: ${chain} (chainId: ${network.chainId})`);
@@ -24406,13 +25324,7 @@ Message: ${causeMessage}${quantumContext}${mintDebtDiagnostics}`
       return { success: false, error: "Failed to resolve PKP public key" };
     }
     const chipotlePkpAddress = computeAddress(publicKey);
-    const STANDALONE_CHAIN_NAMES = {
-      1: "ethereum",
-      11155111: "sepolia",
-      1337: "hardhat",
-      31337: "hardhat"
-    };
-    const chainName = STANDALONE_CHAIN_NAMES[chainId];
+    const chainName = LIT_ACTION_CHAIN_NAMES[chainId];
     if (!chainName) {
       return {
         success: false,
@@ -25634,6 +26546,18 @@ Message: ${causeMessage}${quantumContext}${mintDebtDiagnostics}`
   async getLoansByBorrower(borrower, pagination, orderBy, orderDirection) {
     return this.loanQuery.getLoansByBorrower(borrower, pagination, orderBy, orderDirection);
   }
+  /**
+   * Combined UCD debt (canonical wei string + display string) and by-status loan
+   * counts for a borrower, from one pass over the subgraph. `source: "subgraph"` —
+   * an INDEXED, informational figure that lags writes; never size a transaction
+   * from it (repayments read the chain via `getPositionDetailsView`).
+   *
+   * Fails loud with a SUBGRAPH-category `SDKError` (cause attached) on any page
+   * failure or past 10,000 positions; never returns a partial total.
+   */
+  async getBorrowerUcdDebtSummary(borrower) {
+    return this.loanQuery.getBorrowerUcdDebtSummary(borrower);
+  }
   /**
    * Get all active loans
    *
@@ -25759,11 +26683,12 @@ Message: ${causeMessage}${quantumContext}${mintDebtDiagnostics}`
   }
   /**
    * Execute a PSM stablecoin → UCD swap.
-   * Handles stablecoin approval to the PSM contract if the current allowance is insufficient.
+   * Approves EXACTLY `amountWei` to the PSM when the current allowance is short (resetting a
+   * partial allowance to zero first); every leg is validated by the sign-guard before it is sent.
    *
    * @param params.stablecoinAddress - ERC-20 address of the stablecoin to swap in
    * @param params.amountWei - Stablecoin amount in native decimals (bigint)
-   * @param params.minUcdOutWei - Minimum UCD to receive; reverts if below this (1% slippage guard)
+   * @param params.minUcdOutWei - Minimum UCD to receive; must be > 0 (reverts on-chain if below)
    * @param params.signer - Connected signer for the approval and swap transactions
    */
   async psmSwap(params) {
@@ -25773,32 +26698,23 @@ Message: ${causeMessage}${quantumContext}${mintDebtDiagnostics}`
         "SimplePSMV2 address not configured \u2014 provide contractAddresses.simplePsmV2"
       );
     }
-    const signerAddress = await params.signer.getAddress();
-    const erc20Abi = [
-      "function allowance(address owner, address spender) view returns (uint256)",
-      "function approve(address spender, uint256 amount) returns (bool)"
-    ];
-    const stablecoin = new Contract9(params.stablecoinAddress, erc20Abi, params.signer);
-    const allowance = await stablecoin.allowance(signerAddress, psmAddress);
-    if (allowance < params.amountWei) {
-      const approveTx = await stablecoin.approve(psmAddress, MaxUint256);
-      await approveTx.wait();
-    }
-    const psm = SimplePSMV2__factory.connect(psmAddress, params.signer);
-    const tx = await psm.swap(params.stablecoinAddress, params.amountWei, params.minUcdOutWei);
-    const receipt = await tx.wait();
-    if (!receipt)
-      throw new Error("PSM swap transaction receipt unavailable");
-    return { hash: tx.hash, blockNumber: receipt.blockNumber };
+    return this.runPsmExchange({
+      direction: "swap",
+      signer: params.signer,
+      addresses: { psm: psmAddress, stablecoin: params.stablecoinAddress },
+      amountIn: params.amountWei,
+      minOut: params.minUcdOutWei
+    });
   }
   /**
    * Execute a PSM UCD → stablecoin redeem.
-   * Handles UCD approval to UCDController (not PSM) to satisfy the M-4 burn allowance guard:
-   * UCDToken.burn(from, amount) calls _spendAllowance(from, msg.sender=ucdController, amount).
+   * Approves EXACTLY `ucdAmountWei` of UCD to the UCDController (not the PSM) to satisfy the
+   * M-4 burn allowance guard: UCDToken.burn(from, amount) calls
+   * _spendAllowance(from, msg.sender=ucdController, amount).
    *
    * @param params.stablecoinAddress - ERC-20 address of the stablecoin to receive
    * @param params.ucdAmountWei - UCD amount to redeem (18 decimals, bigint)
-   * @param params.minStablecoinOutWei - Minimum stablecoin to receive (slippage guard)
+   * @param params.minStablecoinOutWei - Minimum stablecoin to receive; must be > 0
    * @param params.signer - Connected signer
    */
   async psmRedeem(params) {
@@ -25811,23 +26727,51 @@ Message: ${causeMessage}${quantumContext}${mintDebtDiagnostics}`
       throw new Error("UCDToken address not configured \u2014 provide contractAddresses.ucdToken");
     if (!ucdControllerAddress)
       throw new Error("UCDController address not configured \u2014 provide contractAddresses.ucdController");
-    const signerAddress = await params.signer.getAddress();
-    const erc20Abi = [
-      "function allowance(address owner, address spender) view returns (uint256)",
-      "function approve(address spender, uint256 amount) returns (bool)"
-    ];
-    const ucdToken = new Contract9(ucdAddress, erc20Abi, params.signer);
-    const allowance = await ucdToken.allowance(signerAddress, ucdControllerAddress);
-    if (allowance < params.ucdAmountWei) {
-      const approveTx = await ucdToken.approve(ucdControllerAddress, MaxUint256);
-      await approveTx.wait();
-    }
-    const psm = SimplePSMV2__factory.connect(psmAddress, params.signer);
-    const tx = await psm.redeem(params.stablecoinAddress, params.ucdAmountWei, params.minStablecoinOutWei);
-    const receipt = await tx.wait();
-    if (!receipt)
-      throw new Error("PSM redeem transaction receipt unavailable");
-    return { hash: tx.hash, blockNumber: receipt.blockNumber };
+    return this.runPsmExchange({
+      direction: "redeem",
+      signer: params.signer,
+      addresses: {
+        psm: psmAddress,
+        stablecoin: params.stablecoinAddress,
+        ucdToken: ucdAddress,
+        ucdController: ucdControllerAddress
+      },
+      amountIn: params.ucdAmountWei,
+      minOut: params.minStablecoinOutWei
+    });
+  }
+  /**
+   * Shared PSM path: plan + validate every leg against the chain the SIGNER is on, then send.
+   * The signer's chain must match the SDK's configured chain — the addresses came from it.
+   */
+  async runPsmExchange(params) {
+    const provider = params.signer.provider;
+    if (!provider) {
+      throw new Error(`PSM ${params.direction} needs a signer connected to a provider`);
+    }
+    const configuredChainId = this.config.chainId ?? this.config.networkOverride?.chainId;
+    if (typeof configuredChainId !== "number") {
+      throw new Error(`PSM ${params.direction} needs the SDK's chainId \u2014 configure chainId`);
+    }
+    const mismatch = await describeProviderChainMismatch(provider, configuredChainId);
+    if (mismatch)
+      throw new Error(mismatch);
+    const vctx = {
+      chainId: configuredChainId,
+      network: String(configuredChainId),
+      contracts: {}
+    };
+    const plan = await planPsmExchange({
+      direction: params.direction,
+      owner: await params.signer.getAddress(),
+      addresses: params.addresses,
+      amountIn: params.amountIn,
+      minOut: params.minOut,
+      vctx,
+      reads: psmExchangeReadsFromProvider(provider, params.addresses.psm)
+    });
+    const { hash, blockNumber } = await executePsmPlan(plan, params.signer, vctx);
+    return { hash, blockNumber };
   }
   /**
    * Wait for the subgraph to index up to (and including) the given block number.
@@ -26005,18 +26949,30 @@ Message: ${causeMessage}${quantumContext}${mintDebtDiagnostics}`
     const user = await signer.getAddress();
     const registry = AgentDelegationRegistry__factory.connect(addr, signer);
     let agentAddress;
-    const hasActiveAgent = await registry.isAgentActive(user);
-    if (hasActiveAgent) {
-      agentAddress = (await registry.agentOf(user)).agent;
+    const [isActive, record, latestBlock] = await Promise.all([
+      registry.isAgentActive(user),
+      registry.agentOf(user),
+      this.getProviderOrThrow().getBlock("latest")
+    ]);
+    if (!latestBlock) {
+      throw new SDKError({
+        message: "Could not read the latest block to check the agent registration's expiry",
+        category: "NETWORK" /* NETWORK */,
+        severity: "HIGH" /* HIGH */
+      });
+    }
+    const plan = planAgentBinding({ isActive, record, nowSeconds: latestBlock.timestamp });
+    if (plan.kind === "reuse") {
+      agentAddress = plan.agent;
     } else {
       agentAddress = await mintAgentPkp({
         serviceEndpoint: this.config.serviceEndpoint,
         authHeader: this.serverSession ? () => this.serverSession.getAuthHeader() : void 0
       });
       const validitySeconds = options?.agentValiditySeconds ?? 90 * 24 * 60 * 60;
-      const validUntil = Math.floor(Date.now() / 1e3) + validitySeconds;
-      const regTx = await registry.registerAgent(user, agentAddress, validUntil);
-      await regTx.wait();
+      const validUntil = latestBlock.timestamp + validitySeconds;
+      const bindTx = plan.kind === "rotate" ? await registry.rotateAgent(user, agentAddress, validUntil) : await registry.registerAgent(user, agentAddress, validUntil);
+      await bindTx.wait();
     }
     const currentDelegate = await getPositionDelegate(pid, signer, pdrAddr).catch(
       () => null