@gvnrdao/dh-sdk 0.0.338 → 0.0.340

package/dist/index.js

@@ -2351,7 +2351,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;
@@ -5279,12 +5279,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 = {
@@ -5540,8 +5540,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 || "",
@@ -5617,14 +5617,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
@@ -5863,7 +5866,7 @@ __export(src_exports, {
 module.exports = __toCommonJS(src_exports);
 
 // src/modules/diamond-hands-sdk.ts
-var import_ethers17 = require("ethers");
+var import_ethers21 = require("ethers");
 
 // src/types/result.ts
 function success(value) {
@@ -6862,6 +6865,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
 var import_ethers4 = require("ethers");
 function buildLoginDomain(chainId) {
@@ -8305,23 +8343,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;
 }
@@ -10465,6 +10517,101 @@ var LoanStatus = /* @__PURE__ */ ((LoanStatus2) => {
 
 // src/modules/loan/loan-query.module.ts
 var import_ethers12 = require("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))"
 ];
@@ -10857,6 +11004,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 (!(0, import_ethers12.isAddress)(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)
    *
@@ -12391,10 +12575,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)) {
@@ -12712,35 +12922,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,
@@ -12758,6 +12940,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.
    *
@@ -18970,6 +19191,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
+var import_ethers20 = require("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
+var import_ethers17 = require("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 import_ethers17.ethers.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
+var import_ethers19 = require("ethers");
+
+// src/utils/sign-guard/fee-ceiling.ts
+var import_ethers18 = require("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 `${import_ethers18.ethers.formatEther(wei)} ETH`;
+}
+function fmtGwei(wei) {
+  return `${import_ethers18.ethers.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 import_ethers19.ethers.getAddress(a) === import_ethers19.ethers.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 import_ethers19.ethers.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 import_ethers20.ethers.Contract(psmAddress, PSM_READS_ABI, provider);
+  return {
+    isStablecoinSupported: async (stablecoin) => await psm.getFunction("supportedStablecoins")(stablecoin),
+    allowance: async (token, owner, spender) => await new import_ethers20.ethers.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 || !import_ethers20.ethers.isAddress(value)) {
+    throw refuse(direction, `${label} address is missing or invalid (${String(value)})`);
+  }
+  return import_ethers20.ethers.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 {
@@ -19723,7 +20563,7 @@ var DiamondHandsSDK = class _DiamondHandsSDK {
    */
   constructor(config) {
     if (!config.provider && config.ethRpcUrl) {
-      config.provider = new import_ethers17.JsonRpcProvider(config.ethRpcUrl);
+      config.provider = new import_ethers21.JsonRpcProvider(config.ethRpcUrl);
     }
     this.config = config;
     if (config.debug) {
@@ -19954,6 +20794,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;
@@ -20003,7 +20855,7 @@ var DiamondHandsSDK = class _DiamondHandsSDK {
           const network = await config.provider.getNetwork();
           chainId = Number(network.chainId);
         } else if (config.ethRpcUrl) {
-          const tempProvider = new import_ethers17.JsonRpcProvider(
+          const tempProvider = new import_ethers21.JsonRpcProvider(
             config.ethRpcUrl
           );
           const network = await tempProvider.getNetwork();
@@ -20539,7 +21391,7 @@ var DiamondHandsSDK = class _DiamondHandsSDK {
       }
       const loanOps = this.loanOps();
       const protocolConfig = await loanOps.getProtocolConfig();
-      const requestAmountWei = (0, import_ethers17.parseEther)(
+      const requestAmountWei = (0, import_ethers21.parseEther)(
         request.amount.toString()
       );
       const minLoanValueWei = BigInt(protocolConfig.minimumLoanValueWei);
@@ -20594,6 +21446,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 (${(0, import_ethers21.formatEther)(baseFeeWei)} UCD) would take this loan's debt to ${(0, import_ethers21.formatEther)(debtAfterWei)} UCD, above the protocol maximum of ${(0, import_ethers21.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: ${(0, import_ethers21.formatEther)(currentDebtWei + requestAmountWei + baseFeeWei)} UCD <= ${(0, import_ethers21.formatEther)(maxLoanValueWei)} UCD`,
+            {}
+          );
+        }
         let pkpPublicKey;
         let pkpEthAddress;
         const pkpCache = this.cacheManager.getCache("pkp-data", {
@@ -20621,7 +21520,7 @@ var DiamondHandsSDK = class _DiamondHandsSDK {
               pkpNftAddress,
               this.getChipotlePublicKeyFallback()
             );
-            pkpEthAddress = (0, import_ethers17.computeAddress)(pkpPublicKey);
+            pkpEthAddress = (0, import_ethers21.computeAddress)(pkpPublicKey);
             pkpCache.set(request.positionId, {
               publicKey: pkpPublicKey,
               ethAddress: pkpEthAddress,
@@ -20683,7 +21582,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})`);
@@ -20964,8 +21863,8 @@ var DiamondHandsSDK = class _DiamondHandsSDK {
         throw new Error(`Position not found: ${request.positionId}`);
       }
       const currentDebt = position.ucdDebt.toString();
-      const ucdDebtHash = (0, import_ethers17.keccak256)(import_ethers17.AbiCoder.defaultAbiCoder().encode(["uint256"], [currentDebt]));
-      const contractHash = (0, import_ethers17.keccak256)(import_ethers17.AbiCoder.defaultAbiCoder().encode(
+      const ucdDebtHash = (0, import_ethers21.keccak256)(import_ethers21.AbiCoder.defaultAbiCoder().encode(["uint256"], [currentDebt]));
+      const contractHash = (0, import_ethers21.keccak256)(import_ethers21.AbiCoder.defaultAbiCoder().encode(
         ["address", "address", "address", "address"],
         [
           positionManagerAddress,
@@ -21034,7 +21933,7 @@ var DiamondHandsSDK = class _DiamondHandsSDK {
         const coreAbi = [
           "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))"
         ];
-        const positionCore = new import_ethers17.Contract(
+        const positionCore = new import_ethers21.Contract(
           coreAddress,
           coreAbi,
           this.getSignerOrThrow().provider
@@ -21042,8 +21941,8 @@ var DiamondHandsSDK = class _DiamondHandsSDK {
         const currentPosition = await positionCore["getPositionDetails"](
           positionIdBytes32
         );
-        const currentDebtHash = (0, import_ethers17.keccak256)(
-          import_ethers17.AbiCoder.defaultAbiCoder().encode(
+        const currentDebtHash = (0, import_ethers21.keccak256)(
+          import_ethers21.AbiCoder.defaultAbiCoder().encode(
             ["uint256"],
             [currentPosition.ucdDebt]
           )
@@ -21090,7 +21989,7 @@ var DiamondHandsSDK = class _DiamondHandsSDK {
           "function getCurrentQuantum() view returns (uint256)",
           "function isQuantumValid(bytes32,uint256) view returns (bool)"
         ];
-        const registry = new import_ethers17.Contract(
+        const registry = new import_ethers21.Contract(
           registryAddress,
           registryAbi,
           this.getSignerOrThrow().provider
@@ -21206,7 +22105,7 @@ var DiamondHandsSDK = class _DiamondHandsSDK {
         });
       }
       const signatureHexMint = finalSignature.startsWith("0x") ? finalSignature : "0x" + finalSignature;
-      const mintIface = new import_ethers17.Interface(positionManagerAbi);
+      const mintIface = new import_ethers21.Interface(positionManagerAbi);
       const mintCalldata = mintIface.encodeFunctionData("mintUCD", [
         positionIdBytes32,
         validationResponse.mintAmount,
@@ -21242,7 +22141,7 @@ var DiamondHandsSDK = class _DiamondHandsSDK {
           if (viewsAddress) {
             let diagnosis = null;
             try {
-              const views = new import_ethers17.Contract(
+              const views = new import_ethers21.Contract(
                 viewsAddress,
                 [
                   "function diagnoseMintUCD(bytes32,uint256,uint256,uint256,uint256,uint256,bytes32,bytes32,bytes32,uint256,bytes) view returns (string)"
@@ -21283,6 +22182,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: ${(0, import_ethers21.formatEther)(maxLoanValueWei)} UCD (fee-inclusive)`;
+        }
         const mintDebtDiagnostics = selector === "0xb9d419a7" || // DebtUpdateVerificationFailed()
         selector === "0xc7e20553" || // DebtUpdateVerificationFailedDetailed(...)
         selector === "0x0cfd2a97" || // MintVerificationMismatch(uint256,uint256)
@@ -21328,7 +22246,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({
@@ -21353,7 +22271,7 @@ Message: ${causeMessage}${quantumContext}${mintDebtDiagnostics}`
         if (receipt.logs && receipt.logs.length > 0) {
           for (const receiptLog of receipt.logs) {
             if (receiptLog.topics && receiptLog.topics[0] === "0x08c379a0") {
-              const iface = new import_ethers17.Interface([
+              const iface = new import_ethers21.Interface([
                 "error Error(string)"
               ]);
               const decoded = iface.decodeErrorResult("Error", receiptLog.data);
@@ -21370,7 +22288,7 @@ Message: ${causeMessage}${quantumContext}${mintDebtDiagnostics}`
         const minimalAbi = [
           "event UCDMintedWithAuthorization(bytes32 indexed positionId, address indexed borrower, uint256 mintAmount, uint256 mintFee, uint256 newDebt, uint256 newCollateral, uint256 btcPrice, uint256 quantumTimestamp, bytes32 authorizedSpendsHash)"
         ];
-        const iface = new import_ethers17.Interface(minimalAbi);
+        const iface = new import_ethers21.Interface(minimalAbi);
         for (const receiptLog of receipt.logs) {
           const parsed = (() => {
             const logIface = iface;
@@ -21557,7 +22475,7 @@ Message: ${causeMessage}${quantumContext}${mintDebtDiagnostics}`
             pkpNftAddress,
             this.getChipotlePublicKeyFallback()
           );
-          const pkpEthAddress = (0, import_ethers17.computeAddress)(pkpPublicKey);
+          const pkpEthAddress = (0, import_ethers21.computeAddress)(pkpPublicKey);
           pkpData = {
             publicKey: pkpPublicKey,
             ethAddress: pkpEthAddress,
@@ -21959,7 +22877,7 @@ Message: ${causeMessage}${quantumContext}${mintDebtDiagnostics}`
           }
           const loanOpsForUcd = loanOpsForUcdResult.value;
           const ucdTokenAddress = await loanOpsForUcd.ucdToken();
-          const ucdToken = new import_ethers17.Contract(
+          const ucdToken = new import_ethers21.Contract(
             ucdTokenAddress,
             [
               "function balanceOf(address) view returns (uint256)",
@@ -21975,9 +22893,9 @@ Message: ${causeMessage}${quantumContext}${mintDebtDiagnostics}`
           if (ucdBalance < debtWei) {
             return {
               success: false,
-              error: `Insufficient UCD balance for liquidation: ${(0, import_ethers17.formatEther)(
+              error: `Insufficient UCD balance for liquidation: ${(0, import_ethers21.formatEther)(
                 ucdBalance
-              )} UCD (need ${(0, import_ethers17.formatEther)(debtWei)} UCD)`,
+              )} UCD (need ${(0, import_ethers21.formatEther)(debtWei)} UCD)`,
               positionId: request.positionId,
               wasLiquidated: false
             };
@@ -21986,7 +22904,7 @@ Message: ${causeMessage}${quantumContext}${mintDebtDiagnostics}`
             if (request.skipUcdApproval) {
               return {
                 success: false,
-                error: `Insufficient UCD allowance for UCDController: need at least ${(0, import_ethers17.formatEther)(
+                error: `Insufficient UCD allowance for UCDController: need at least ${(0, import_ethers21.formatEther)(
                   debtWei
                 )} UCD, or omit skipUcdApproval to let the SDK submit approve`,
                 positionId: request.positionId,
@@ -22510,7 +23428,7 @@ Message: ${causeMessage}${quantumContext}${mintDebtDiagnostics}`
     if (typeof signatureBytes === "string" && signatureBytes.startsWith("{")) {
       try {
         const parsed = JSON.parse(signatureBytes);
-        signatureBytes = parsed.signature ?? (parsed.r && parsed.s && parsed.v ? import_ethers17.Signature.from({
+        signatureBytes = parsed.signature ?? (parsed.r && parsed.s && parsed.v ? import_ethers21.Signature.from({
           r: parsed.r,
           s: parsed.s,
           v: parsed.v
@@ -22521,7 +23439,7 @@ Message: ${causeMessage}${quantumContext}${mintDebtDiagnostics}`
     if (!signatureBytes.startsWith("0x")) {
       signatureBytes = "0x" + signatureBytes;
     }
-    const extendIface = new import_ethers17.Interface([
+    const extendIface = new import_ethers21.Interface([
       "function extendPosition(bytes32 positionId, uint256 selectedTerm, uint256 quantumTimestamp, uint256 btcPrice, uint256 availableBTCBalance, uint256 proRataRenewalFee, bytes calldata extensionValidatorSignature) external returns (bool)"
     ]);
     const extendCalldata = extendIface.encodeFunctionData("extendPosition", [
@@ -23070,7 +23988,7 @@ Message: ${causeMessage}${quantumContext}${mintDebtDiagnostics}`
           `   Converting payment amount: ${request.paymentAmount} (type: ${typeof request.paymentAmount})`
         );
       }
-      const paymentAmountWei = (0, import_ethers17.parseEther)(
+      const paymentAmountWei = (0, import_ethers21.parseEther)(
         request.paymentAmount.toString()
       );
       if (this.config.debug) {
@@ -23137,7 +24055,7 @@ Message: ${causeMessage}${quantumContext}${mintDebtDiagnostics}`
         };
       }
       const ucdTokenAddress = await loanOps.ucdToken();
-      const ucdToken = new import_ethers17.Contract(
+      const ucdToken = new import_ethers21.Contract(
         ucdTokenAddress,
         [
           "function balanceOf(address) view returns (uint256)",
@@ -23161,14 +24079,14 @@ Message: ${causeMessage}${quantumContext}${mintDebtDiagnostics}`
       ]);
       if (this.config.debug) {
         log.info(`   UCD funds source: ${fundsSource}${isSelfRepay ? " (self)" : " (borrower; agent submitting)"}`);
-        log.info(`   UCD Balance: ${(0, import_ethers17.formatEther)(balance)} UCD`);
-        log.info(`   UCD Allowance: ${(0, import_ethers17.formatEther)(allowance)} UCD`);
+        log.info(`   UCD Balance: ${(0, import_ethers21.formatEther)(balance)} UCD`);
+        log.info(`   UCD Allowance: ${(0, import_ethers21.formatEther)(allowance)} UCD`);
         log.info(`   Required: ${request.paymentAmount} UCD`);
       }
       if (balance < paymentAmountWei) {
         return {
           success: false,
-          error: `Insufficient UCD balance: ${(0, import_ethers17.formatEther)(
+          error: `Insufficient UCD balance: ${(0, import_ethers21.formatEther)(
             balance
           )} UCD (need ${request.paymentAmount} UCD)${isSelfRepay ? "" : ` \u2014 borrower ${fundsSource} lacks funds`}`
         };
@@ -23177,7 +24095,7 @@ Message: ${causeMessage}${quantumContext}${mintDebtDiagnostics}`
         if (!isSelfRepay) {
           return {
             success: false,
-            error: `Borrower ${fundsSource} has insufficient UCD allowance to PositionManager (${(0, import_ethers17.formatEther)(allowance)} UCD, need ${request.paymentAmount}). The borrower must approve PositionManager before a delegated agent can repay.`
+            error: `Borrower ${fundsSource} has insufficient UCD allowance to PositionManager (${(0, import_ethers21.formatEther)(allowance)} UCD, need ${request.paymentAmount}). The borrower must approve PositionManager before a delegated agent can repay.`
           };
         }
         if (this.config.debug) {
@@ -23446,7 +24364,7 @@ Message: ${causeMessage}${quantumContext}${mintDebtDiagnostics}`
       const paymentSigner = this.getSignerOrThrow();
       const paymentFrom = await paymentSigner.getAddress();
       const paymentProvider = contractManager.getProvider();
-      const paymentIface = new import_ethers17.Interface([
+      const paymentIface = new import_ethers21.Interface([
         "function makePayment(bytes32 positionId, uint256 paymentAmount, uint256 quantumTimestamp, uint256 btcPrice, bytes calldata paymentValidatorSignature) external returns (bool)"
       ]);
       const paymentCalldata = paymentIface.encodeFunctionData("makePayment", [
@@ -23795,7 +24713,7 @@ Message: ${causeMessage}${quantumContext}${mintDebtDiagnostics}`
             const pkpId = position.pkpId;
             if (litValidatorAddr && pkpId) {
               try {
-                const litValidator = new import_ethers17.Contract(
+                const litValidator = new import_ethers21.Contract(
                   litValidatorAddr,
                   ["function pkpOwners(bytes32) view returns (address)"],
                   this.getProviderOrThrow()
@@ -23803,7 +24721,7 @@ Message: ${causeMessage}${quantumContext}${mintDebtDiagnostics}`
                 const owner = await litValidator.pkpOwners(
                   pkpId
                 );
-                if (owner && owner !== import_ethers17.ZeroAddress) {
+                if (owner && owner !== import_ethers21.ZeroAddress) {
                   controller = owner;
                 }
               } catch {
@@ -23855,7 +24773,7 @@ Message: ${causeMessage}${quantumContext}${mintDebtDiagnostics}`
               pkpNftAddress,
               this.getChipotlePublicKeyFallback()
             );
-            pkpEthAddress = (0, import_ethers17.computeAddress)(pkpPublicKey);
+            pkpEthAddress = (0, import_ethers21.computeAddress)(pkpPublicKey);
             pkpCache.set(positionId, {
               publicKey: pkpPublicKey,
               ethAddress: pkpEthAddress,
@@ -23925,7 +24843,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})`);
@@ -24228,7 +25146,7 @@ Message: ${causeMessage}${quantumContext}${mintDebtDiagnostics}`
           utxoVout: withdrawalParams.utxoVout
         });
       }
-      const withdrawIface = new import_ethers17.Interface([
+      const withdrawIface = new import_ethers21.Interface([
         "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)"
       ]);
       const withdrawCalldata = withdrawIface.encodeFunctionData("withdrawBTC", [
@@ -24459,7 +25377,7 @@ Message: ${causeMessage}${quantumContext}${mintDebtDiagnostics}`
     }
     const pkpId = positionDetails.pkpId;
     const vaultAddress = positionDetails.vaultAddress;
-    if (!pkpId || pkpId === import_ethers17.ZeroHash) {
+    if (!pkpId || pkpId === import_ethers21.ZeroHash) {
       return { success: false, error: "Position has no PKP" };
     }
     if (!vaultAddress) {
@@ -24479,14 +25397,8 @@ Message: ${causeMessage}${quantumContext}${mintDebtDiagnostics}`
     if (!publicKey) {
       return { success: false, error: "Failed to resolve PKP public key" };
     }
-    const chipotlePkpAddress = (0, import_ethers17.computeAddress)(publicKey);
-    const STANDALONE_CHAIN_NAMES = {
-      1: "ethereum",
-      11155111: "sepolia",
-      1337: "hardhat",
-      31337: "hardhat"
-    };
-    const chainName = STANDALONE_CHAIN_NAMES[chainId];
+    const chipotlePkpAddress = (0, import_ethers21.computeAddress)(publicKey);
+    const chainName = LIT_ACTION_CHAIN_NAMES[chainId];
     if (!chainName) {
       return {
         success: false,
@@ -24858,7 +25770,7 @@ Message: ${causeMessage}${quantumContext}${mintDebtDiagnostics}`
       const btcSpendAuthorizerAbi = [
         "function getAuthorizedSpends(bytes32) view returns (tuple(string txid, uint32 vout, uint256 satoshis, string targetAddress, uint256 targetAmount, uint256 authorizedAt)[])"
       ];
-      const btcSpendAuthorizer = new import_ethers17.Contract(
+      const btcSpendAuthorizer = new import_ethers21.Contract(
         btcSpendAuthorizerAddress,
         btcSpendAuthorizerAbi,
         this.getProviderOrThrow()
@@ -24944,7 +25856,7 @@ Message: ${causeMessage}${quantumContext}${mintDebtDiagnostics}`
     const abi = [
       "function getAuthorizedSpends(bytes32) view returns (tuple(string txid, uint32 vout, uint256 satoshis, string targetAddress, uint256 targetAmount, uint256 authorizedAt)[])"
     ];
-    const contract = new import_ethers17.Contract(
+    const contract = new import_ethers21.Contract(
       btcSpendAuthorizerAddress,
       abi,
       this.getProviderOrThrow()
@@ -24958,7 +25870,7 @@ Message: ${causeMessage}${quantumContext}${mintDebtDiagnostics}`
       targetAddress: spend.targetAddress,
       targetAmount: Number(spend.targetAmount),
       authorizedAt: Number(spend.authorizedAt),
-      utxoKey: (0, import_ethers17.solidityPackedKeccak256)(
+      utxoKey: (0, import_ethers21.solidityPackedKeccak256)(
         ["string", "uint32"],
         [spend.txid, Number(spend.vout)]
       )
@@ -25164,7 +26076,7 @@ Message: ${causeMessage}${quantumContext}${mintDebtDiagnostics}`
           error: attRes.error ?? attRes.reason ?? `LIT recovery attestation rejected${attRes.failedStep ? ` at step ${attRes.failedStep}` : ""}`
         };
       }
-      const btcSpendAuthorizer = new import_ethers17.Contract(
+      const btcSpendAuthorizer = new import_ethers21.Contract(
         btcSpendAuthorizerAddress,
         [
           "function cancelStaleSpendWithProof(bytes32 positionId, bytes32 utxoKey, uint256 authorizedAt, string calldata invalidatorTxid, uint256 attestationTimestamp, bytes calldata litSignature) external"
@@ -25261,7 +26173,7 @@ Message: ${causeMessage}${quantumContext}${mintDebtDiagnostics}`
     const positionDetails = await this.getPositionDetailsView(
       params.positionId
     );
-    if (!positionDetails?.pkpId || positionDetails.pkpId === import_ethers17.ZeroHash) {
+    if (!positionDetails?.pkpId || positionDetails.pkpId === import_ethers21.ZeroHash) {
       return { success: false, error: "Position has no PKP" };
     }
     const pkpCache = this.cacheManager.getCache("pkp-data", {
@@ -25278,7 +26190,7 @@ Message: ${causeMessage}${quantumContext}${mintDebtDiagnostics}`
     if (!publicKey) {
       return { success: false, error: "Failed to resolve PKP public key" };
     }
-    const chipotlePkpAddress = (0, import_ethers17.computeAddress)(publicKey);
+    const chipotlePkpAddress = (0, import_ethers21.computeAddress)(publicKey);
     const dc = this.config.contractAddresses || {};
     const chainName = chainId === 1 ? "ethereum" : chainId === 11155111 ? "sepolia" : chainId === 1337 || chainId === 31337 ? "hardhat" : void 0;
     if (!chainName) {
@@ -25708,6 +26620,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
    *
@@ -25833,11 +26757,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) {
@@ -25847,32 +26772,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 import_ethers17.Contract(params.stablecoinAddress, erc20Abi, params.signer);
-    const allowance = await stablecoin.allowance(signerAddress, psmAddress);
-    if (allowance < params.amountWei) {
-      const approveTx = await stablecoin.approve(psmAddress, import_ethers17.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) {
@@ -25885,23 +26801,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 import_ethers17.Contract(ucdAddress, erc20Abi, params.signer);
-    const allowance = await ucdToken.allowance(signerAddress, ucdControllerAddress);
-    if (allowance < params.ucdAmountWei) {
-      const approveTx = await ucdToken.approve(ucdControllerAddress, import_ethers17.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.
@@ -25945,7 +26889,7 @@ Message: ${causeMessage}${quantumContext}${mintDebtDiagnostics}`
    *
    * Deliberately omits `minWithdrawRatioBps` — see {@link readLoanGrant}.
    */
-  static LOAN_GRANT_PREFIX_IFACE = new import_ethers17.Interface([
+  static LOAN_GRANT_PREFIX_IFACE = new import_ethers21.Interface([
     "function getLoanGrant(bytes32 positionId) view returns (address borrower, uint32 scopeBits, uint32 minCollateralRatioBps)"
   ]);
   /**
@@ -25966,9 +26910,9 @@ Message: ${causeMessage}${quantumContext}${mintDebtDiagnostics}`
       to: registryAddress,
       data: iface.encodeFunctionData("getLoanGrant", [pid])
     });
-    if ((0, import_ethers17.getBytes)(data).length < 96) {
+    if ((0, import_ethers21.getBytes)(data).length < 96) {
       throw new SDKError({
-        message: `AgentDelegationRegistry at ${registryAddress} returned ${(0, import_ethers17.getBytes)(data).length} bytes for getLoanGrant(bytes32) \u2014 expected at least 96. Wrong address, or a registry version this SDK does not support.`,
+        message: `AgentDelegationRegistry at ${registryAddress} returned ${(0, import_ethers21.getBytes)(data).length} bytes for getLoanGrant(bytes32) \u2014 expected at least 96. Wrong address, or a registry version this SDK does not support.`,
         category: "CONTRACT" /* CONTRACT */,
         severity: "HIGH" /* HIGH */
       });
@@ -25977,10 +26921,10 @@ Message: ${causeMessage}${quantumContext}${mintDebtDiagnostics}`
       "getLoanGrant",
       data
     );
-    const raw = (0, import_ethers17.getBytes)(data);
+    const raw = (0, import_ethers21.getBytes)(data);
     const withdrawScopeSupported = raw.length >= 128;
     const minWithdrawRatioBps = withdrawScopeSupported ? Number(
-      import_ethers17.AbiCoder.defaultAbiCoder().decode(["uint32"], raw.slice(96, 128))[0]
+      import_ethers21.AbiCoder.defaultAbiCoder().decode(["uint32"], raw.slice(96, 128))[0]
     ) : 0;
     return {
       borrower,
@@ -26079,18 +27023,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
@@ -26129,7 +27085,7 @@ Message: ${causeMessage}${quantumContext}${mintDebtDiagnostics}`
       getPositionDelegate(pid, signer, pdrAddr),
       registry.agentOf(user).then((a) => a.agent)
     ]);
-    if (currentDelegate !== import_ethers17.ZeroAddress && currentDelegate.toLowerCase() === userAgent.toLowerCase()) {
+    if (currentDelegate !== import_ethers21.ZeroAddress && currentDelegate.toLowerCase() === userAgent.toLowerCase()) {
       const clearTx = await setPositionDelegate(
         pid,
         "0x0000000000000000000000000000000000000000",
@@ -26521,7 +27477,7 @@ Message: ${causeMessage}${quantumContext}${mintDebtDiagnostics}`
       const maxUcdWhole = BigInt(result[3].toString());
       return success({
         liquidationThreshold: result[0].toString(),
-        minimumLoanValueUcd: (0, import_ethers17.formatUnits)(result[2], 18),
+        minimumLoanValueUcd: (0, import_ethers21.formatUnits)(result[2], 18),
         minimumLoanValueWei: result[2].toString(),
         maxSingleLoanValueUcd: maxUcdWhole.toString(),
         maxSingleLoanValueWei: (maxUcdWhole * 10n ** 18n).toString()
@@ -26558,7 +27514,7 @@ Message: ${causeMessage}${quantumContext}${mintDebtDiagnostics}`
       const balanceWei = await provider.getBalance(address);
       return success({
         balanceWei: balanceWei.toString(),
-        balanceEth: (0, import_ethers17.formatEther)(balanceWei)
+        balanceEth: (0, import_ethers21.formatEther)(balanceWei)
       });
     } catch (error) {
       return failure(new SDKError({
@@ -26967,7 +27923,7 @@ Message: ${causeMessage}${quantumContext}${mintDebtDiagnostics}`
    * Convert decimal position ID to bytes32 format
    */
   toBytes32(value) {
-    return (0, import_ethers17.zeroPadValue)((0, import_ethers17.toBeHex)(BigInt(value)), 32);
+    return (0, import_ethers21.zeroPadValue)((0, import_ethers21.toBeHex)(BigInt(value)), 32);
   }
   /**
    * Check if an error indicates a technical failure vs business logic rejection
@@ -27008,7 +27964,7 @@ Message: ${causeMessage}${quantumContext}${mintDebtDiagnostics}`
     const coreModuleAbi = [
       "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))"
     ];
-    const coreModule = new import_ethers17.Contract(
+    const coreModule = new import_ethers21.Contract(
       coreModuleAddress,
       coreModuleAbi,
       provider
@@ -27075,7 +28031,7 @@ Message: ${causeMessage}${quantumContext}${mintDebtDiagnostics}`
     const corePositionAbi = [
       "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))"
     ];
-    const corePositionContract = new import_ethers17.Contract(
+    const corePositionContract = new import_ethers21.Contract(
       coreAddress,
       corePositionAbi,
       provider
@@ -27086,7 +28042,7 @@ Message: ${causeMessage}${quantumContext}${mintDebtDiagnostics}`
           positionIdBytes32
         );
         const positionIdFromCore = corePosition?.positionId || corePosition?.[0] || null;
-        if (positionIdFromCore && positionIdFromCore !== import_ethers17.ZeroHash && positionIdFromCore !== "0x0000000000000000000000000000000000000000000000000000000000000000") {
+        if (positionIdFromCore && positionIdFromCore !== import_ethers21.ZeroHash && positionIdFromCore !== "0x0000000000000000000000000000000000000000000000000000000000000000") {
           if (this.config.debug) {
             log.info("Position exists in core contract", {
               positionId,
@@ -27154,7 +28110,7 @@ Message: ${causeMessage}${quantumContext}${mintDebtDiagnostics}`
       throw new Error("loanOperationsManager address not configured");
     }
     const runner = this.config.contractSigner || this.getProviderOrThrow();
-    const contract = new import_ethers17.Contract(
+    const contract = new import_ethers21.Contract(
       addr.loanOperationsManager,
       [
         "function getProtocolConfig() external view returns (uint256 liquidationThreshold, uint256 minimumLoanValueUcd, uint256 minimumLoanValueWei, uint256 maxSingleLoanValueUcd)"
@@ -27167,7 +28123,7 @@ Message: ${causeMessage}${quantumContext}${mintDebtDiagnostics}`
         const maxUcdWhole = BigInt(result[3].toString());
         return {
           liquidationThreshold: result[0].toString(),
-          minimumLoanValueUcd: (0, import_ethers17.formatUnits)(result[2], 18),
+          minimumLoanValueUcd: (0, import_ethers21.formatUnits)(result[2], 18),
           minimumLoanValueWei: result[2].toString(),
           maxSingleLoanValueUcd: maxUcdWhole.toString(),
           maxSingleLoanValueWei: (maxUcdWhole * 10n ** 18n).toString()
@@ -27185,8 +28141,8 @@ Message: ${causeMessage}${quantumContext}${mintDebtDiagnostics}`
     const MIN_REVEAL_DELAY = 60;
     const MAX_RANDOM_DELAY = 240;
     const entropyInput = positionId + quantumTimestamp.toString();
-    const hash = (0, import_ethers17.keccak256)(
-      (0, import_ethers17.toUtf8Bytes)(entropyInput)
+    const hash = (0, import_ethers21.keccak256)(
+      (0, import_ethers21.toUtf8Bytes)(entropyInput)
     );
     const randomValue = BigInt(hash);
     const randomDelay = Number(randomValue % BigInt(MAX_RANDOM_DELAY));
@@ -27211,12 +28167,12 @@ Message: ${causeMessage}${quantumContext}${mintDebtDiagnostics}`
     const rawPositionId = /^0x/i.test(params.positionId.trim()) ? params.positionId.trim().slice(2) : params.positionId.trim();
     const canonicalPositionId = "0x" + rawPositionId.padStart(64, "0").toLowerCase();
     const intentTimestamp = Math.floor(Date.now() / 1e3);
-    const intentActionHash = (0, import_ethers17.keccak256)((0, import_ethers17.toUtf8Bytes)("liquidate-position"));
-    const intentHash = (0, import_ethers17.solidityPackedKeccak256)(
+    const intentActionHash = (0, import_ethers21.keccak256)((0, import_ethers21.toUtf8Bytes)("liquidate-position"));
+    const intentHash = (0, import_ethers21.solidityPackedKeccak256)(
       ["bytes32", "uint256", "uint256", "address", "bytes32"],
       [canonicalPositionId, intentTimestamp, chainId, intentSigner, intentActionHash]
     );
-    const intentSignature = await signer.signMessage((0, import_ethers17.getBytes)(intentHash));
+    const intentSignature = await signer.signMessage((0, import_ethers21.getBytes)(intentHash));
     const response = await fetch(endpoint, {
       method: "POST",
       headers: { "Content-Type": "application/json" },
@@ -27268,7 +28224,7 @@ Message: ${causeMessage}${quantumContext}${mintDebtDiagnostics}`
         const vrfSeedRaw = await lmResult.value["vrfSeeds"](positionId);
         const vrfSeed = BigInt(vrfSeedRaw.toString());
         if (vrfSeed !== 0n) {
-          const finalEntropy = (0, import_ethers17.solidityPackedKeccak256)(
+          const finalEntropy = (0, import_ethers21.solidityPackedKeccak256)(
             ["uint256", "uint256", "bytes32"],
             [vrfSeed, BigInt(quantumTimestamp.toString()), positionId]
           );
@@ -27546,7 +28502,7 @@ var EventHelpers = {
 };
 
 // src/utils/safe-agent-delegation.utils.ts
-var import_ethers18 = require("ethers");
+var import_ethers22 = require("ethers");
 init_deployment_addresses();
 var SAFE_ABI = [
   "function getModulesPaginated(address start, uint256 pageSize) view returns (address[] modules, address next)"
@@ -27564,7 +28520,7 @@ var MODULE_LIST_SENTINEL = "0x0000000000000000000000000000000000000001";
 var MODULE_PAGE_SIZE = 50;
 var lower = (v) => v.trim().toLowerCase();
 async function classifyModule(provider, moduleAddress, safeAddress, positionManager, factoryAddress) {
-  const module2 = new import_ethers18.Contract(moduleAddress, MODULE_ABI, provider);
+  const module2 = new import_ethers22.Contract(moduleAddress, MODULE_ABI, provider);
   let boundSafe;
   try {
     boundSafe = await module2.safe();
@@ -27584,7 +28540,7 @@ async function classifyModule(provider, moduleAddress, safeAddress, positionMana
   if (!factoryAddress)
     return null;
   try {
-    const factory = new import_ethers18.Contract(factoryAddress, FACTORY_ABI, provider);
+    const factory = new import_ethers22.Contract(factoryAddress, FACTORY_ABI, provider);
     return await factory.isFromFactory(moduleAddress) === true;
   } catch {
     return null;
@@ -27613,7 +28569,7 @@ async function getSafeAgentDelegation(params) {
   let modules;
   let next;
   try {
-    const safe = new import_ethers18.Contract(safeAddress, SAFE_ABI, provider);
+    const safe = new import_ethers22.Contract(safeAddress, SAFE_ABI, provider);
     const page = await safe.getModulesPaginated(
       MODULE_LIST_SENTINEL,
       MODULE_PAGE_SIZE
@@ -27641,7 +28597,7 @@ async function getSafeAgentDelegation(params) {
       continue;
     let agentAddress = null;
     try {
-      agentAddress = await new import_ethers18.Contract(
+      agentAddress = await new import_ethers22.Contract(
         moduleAddress,
         MODULE_ABI,
         provider
@@ -27655,7 +28611,7 @@ async function getSafeAgentDelegation(params) {
     let validUntil;
     let status;
     try {
-      const record = await new import_ethers18.Contract(
+      const record = await new import_ethers22.Contract(
         registryAddress,
         REGISTRY_ABI,
         provider