@gvnrdao/dh-sdk 0.0.338 → 0.0.340

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

@@ -78,6 +78,40 @@ export interface PaginatedLoansResponse {
     maxRows: number;
     totalLoans: number;
 }
+/**
+ * Per-status row in {@link BorrowerUcdDebtSummary.byStatus}.
+ * Only statuses with count > 0 appear; order follows {@link LoanStatus} ordinals.
+ */
+export interface BorrowerUcdDebtStatusCount {
+    status: LoanStatus;
+    /** Enum key, e.g. "ACTIVE", "PENDING_DEPOSIT". */
+    statusLabel: string;
+    count: number;
+}
+/**
+ * Aggregated UCD debt + status mix for one borrower, from ONE pass over the
+ * subgraph's raw position rows — shared by Butler, MCP, CLI.
+ *
+ * This is the INDEXED view (the subgraph lags writes). It is informational and
+ * must never size a transaction; repayments read the chain
+ * (`getPositionDetailsView`).
+ */
+export interface BorrowerUcdDebtSummary {
+    /** Lower-cased. */
+    borrower: string;
+    /** Positions included in the sum — every status, all pages. */
+    loanCount: number;
+    /** Canonical total debt in wei (18 decimals), as a decimal string (BigInt sum). */
+    totalUcdDebt: string;
+    /** Display only: 18-decimal rendering with trailing zeros trimmed (e.g. "21.93"). */
+    totalUcdDebtHuman: string;
+    /** Only statuses with count > 0, ordered by {@link LoanStatus} ordinal. */
+    byStatus: BorrowerUcdDebtStatusCount[];
+    /** Where the figures came from. Reserved for a future on-chain cross-check ("chain"). */
+    source: "subgraph";
+    /** ms epoch, set by the SDK when the last page landed. */
+    fetchedAt: number;
+}
 /**
  * Detailed Loan Data Interface (used by getLoanById / PKP)
  */

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

@@ -893,6 +893,16 @@ export declare class DiamondHandsSDK {
         page: number;
         pageSize: number;
     }, orderBy?: "createdAt" | "lastUpdatedAt" | "ucdDebt", orderDirection?: "asc" | "desc"): Promise<Result<import("../interfaces/chunks/loan-operations.i").PaginatedLoansResponse, SDKError>>;
+    /**
+     * 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.
+     */
+    getBorrowerUcdDebtSummary(borrower: string): Promise<Result<import("../interfaces/chunks/loan-operations.i").BorrowerUcdDebtSummary, SDKError>>;
     /**
      * Get all active loans
      *
@@ -974,11 +984,12 @@ export declare class DiamondHandsSDK {
     getPSMAvailableReserves(stablecoinAddress: string): Promise<bigint>;
     /**
      * 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
      */
     psmSwap(params: {
@@ -992,12 +1003,13 @@ export declare class DiamondHandsSDK {
     }>;
     /**
      * 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
      */
     psmRedeem(params: {
@@ -1009,6 +1021,11 @@ export declare class DiamondHandsSDK {
         hash: string;
         blockNumber: number;
     }>;
+    /**
+     * 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.
+     */
+    private runPsmExchange;
     /**
      * Wait for the subgraph to index up to (and including) the given block number.
      * Call after on-chain actions (createLoan, mintUCD, etc.) before querying the subgraph.

package/dist/modules/loan/loan-query.module.d.ts

@@ -13,7 +13,7 @@ import { Result } from "../../types/result";
 import { SDKError } from "../../utils/error-handler";
 import type { BitcoinOperations } from "../bitcoin/bitcoin-operations.module";
 import type { Cache } from "../cache/cache-manager.module";
-import type { LoanData, LoanDataDetail, PaginatedLoansResponse } from "../../interfaces/chunks/loan-operations.i";
+import type { BorrowerUcdDebtSummary, LoanData, LoanDataDetail, PaginatedLoansResponse } from "../../interfaces/chunks/loan-operations.i";
 import type { LoanEvents, LoanEventsFilter } from "../../types/event-types";
 import { DiamondHandsGraphClient } from "@graphs/diamond-hands";
 import { type Provider } from "ethers";
@@ -141,6 +141,17 @@ export declare class LoanQuery {
      * @returns Paginated loans for borrower
      */
     getLoansByBorrower(borrower: string, pagination?: PaginationParams, orderBy?: "createdAt" | "lastUpdatedAt" | "ucdDebt", orderDirection?: "asc" | "desc"): Promise<Result<PaginatedLoansResponse, SDKError>>;
+    /**
+     * 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.
+     */
+    getBorrowerUcdDebtSummary(borrower: string): Promise<Result<BorrowerUcdDebtSummary, SDKError>>;
     /**
      * Get active loans (status = ACTIVE)
      *

package/dist/sign-guard.js

@@ -42,17 +42,23 @@ __export(sign_guard_exports, {
   authorizeWithServer: () => authorizeWithServer,
   broadcastSignedTx: () => broadcastSignedTx,
   buildAuthEnvelope: () => buildAuthEnvelope,
+  buildPsmApproveTx: () => buildPsmApproveTx,
+  buildPsmRedeemTx: () => buildPsmRedeemTx,
+  buildPsmSwapTx: () => buildPsmSwapTx,
   buildValidationContext: () => buildValidationContext,
   computeExtendFeeUpperBound: () => computeExtendFeeUpperBound,
   decodeSignable: () => decodeSignable,
   describeUnsignedTx: () => describeUnsignedTx,
   encodeSignable: () => encodeSignable,
+  executePsmPlan: () => executePsmPlan,
   fetchWithTimeout: () => fetchWithTimeout,
   isAuthFresh: () => isAuthFresh,
   isStrictCurrentQuantum: () => isStrictCurrentQuantum,
   modeForChainId: () => modeForChainId,
   nextQuantumTimestamp: () => nextQuantumTimestamp,
+  planPsmExchange: () => planPsmExchange,
   postJson: () => postJson,
+  psmExchangeReadsFromProvider: () => psmExchangeReadsFromProvider,
   randomNonceHex: () => randomNonceHex,
   readTxFeeFields: () => readTxFeeFields,
   signAndBroadcast: () => signAndBroadcast,
@@ -66,8 +72,12 @@ module.exports = __toCommonJS(sign_guard_exports);
 
 // src/utils/sign-guard/errors.ts
 var TxValidationError = class extends Error {
-  constructor(msg) {
-    super(`Refusing to sign server-returned transaction: ${msg}`);
+  /**
+   * @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";
   }
 };
@@ -962,6 +972,129 @@ async function computeExtendFeeUpperBound(provider, contracts, positionId, selec
   const upperBoundFeeWei = ucdDebt * extensionFeeRateBps / 10000n;
   return { ucdDebt, extensionFeeRateBps, upperBoundFeeWei };
 }
+
+// src/utils/sign-guard/psm-exchange.ts
+var import_ethers6 = require("ethers");
+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_ethers6.ethers.Contract(psmAddress, PSM_READS_ABI, provider);
+  return {
+    isStablecoinSupported: async (stablecoin) => await psm.getFunction("supportedStablecoins")(stablecoin),
+    allowance: async (token, owner, spender) => await new import_ethers6.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_ethers6.ethers.isAddress(value)) {
+    throw refuse(direction, `${label} address is missing or invalid (${String(value)})`);
+  }
+  return import_ethers6.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 };
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   AUTH_VALIDITY_WINDOWS,
@@ -986,17 +1119,23 @@ async function computeExtendFeeUpperBound(provider, contracts, positionId, selec
   authorizeWithServer,
   broadcastSignedTx,
   buildAuthEnvelope,
+  buildPsmApproveTx,
+  buildPsmRedeemTx,
+  buildPsmSwapTx,
   buildValidationContext,
   computeExtendFeeUpperBound,
   decodeSignable,
   describeUnsignedTx,
   encodeSignable,
+  executePsmPlan,
   fetchWithTimeout,
   isAuthFresh,
   isStrictCurrentQuantum,
   modeForChainId,
   nextQuantumTimestamp,
+  planPsmExchange,
   postJson,
+  psmExchangeReadsFromProvider,
   randomNonceHex,
   readTxFeeFields,
   signAndBroadcast,

package/dist/sign-guard.mjs

@@ -1,7 +1,11 @@
 // src/utils/sign-guard/errors.ts
 var TxValidationError = class extends Error {
-  constructor(msg) {
-    super(`Refusing to sign server-returned transaction: ${msg}`);
+  /**
+   * @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";
   }
 };
@@ -896,6 +900,129 @@ async function computeExtendFeeUpperBound(provider, contracts, positionId, selec
   const upperBoundFeeWei = ucdDebt * extensionFeeRateBps / 10000n;
   return { ucdDebt, extensionFeeRateBps, upperBoundFeeWei };
 }
+
+// src/utils/sign-guard/psm-exchange.ts
+import { ethers as ethers6 } from "ethers";
+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 ethers6.Contract(psmAddress, PSM_READS_ABI, provider);
+  return {
+    isStablecoinSupported: async (stablecoin) => await psm.getFunction("supportedStablecoins")(stablecoin),
+    allowance: async (token, owner, spender) => await new ethers6.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 || !ethers6.isAddress(value)) {
+    throw refuse(direction, `${label} address is missing or invalid (${String(value)})`);
+  }
+  return ethers6.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 };
+}
 export {
   AUTH_VALIDITY_WINDOWS,
   BROADCAST_PATH,
@@ -919,17 +1046,23 @@ export {
   authorizeWithServer,
   broadcastSignedTx,
   buildAuthEnvelope,
+  buildPsmApproveTx,
+  buildPsmRedeemTx,
+  buildPsmSwapTx,
   buildValidationContext,
   computeExtendFeeUpperBound,
   decodeSignable,
   describeUnsignedTx,
   encodeSignable,
+  executePsmPlan,
   fetchWithTimeout,
   isAuthFresh,
   isStrictCurrentQuantum,
   modeForChainId,
   nextQuantumTimestamp,
+  planPsmExchange,
   postJson,
+  psmExchangeReadsFromProvider,
   randomNonceHex,
   readTxFeeFields,
   signAndBroadcast,

package/dist/utils/address-conversion.utils.d.ts

@@ -22,14 +22,22 @@ export declare function safeGetBitcoinAddressesFromPkp(pkpId: string, maxRetries
     testnet: string;
     regtest: string;
 }>;
+type BitcoinAddressNetwork = 'mainnet' | 'testnet' | 'regtest';
 /**
- * Safely validate and format a Bitcoin address
- * @param address Bitcoin address to validate
- * @param network Network type for validation
- * @returns Validated address
- * @throws Clear error message if validation fails
+ * Validate a Bitcoin address for the network the caller is operating on.
+ *
+ * Runs on the BTC withdrawal path before any Lit Action, authorization or signature, so
+ * it verifies the CHECKSUM (base58check / bech32 / bech32m, via `BitcoinUtils`) and then
+ * the network. BTC sent to a mistyped or wrong-network address is unrecoverable; the
+ * previous implementation checked the prefix only, so a one-character typo passed.
+ *
+ * `network` is required. It used to default to 'regtest', which would have validated a
+ * mainnet caller's address against the wrong chain without saying so.
+ *
+ * @returns the address unchanged
+ * @throws if the address is malformed, fails its checksum, or is not on `network`
  */
-export declare function safeValidateBitcoinAddress(address: string, network?: 'mainnet' | 'testnet' | 'regtest'): string;
+export declare function safeValidateBitcoinAddress(address: string, network: BitcoinAddressNetwork): string;
 /**
  * Canonicalize a Bitcoin address so that the SAME string is used on both the
  * approve path (registry.addAddress) and the withdraw path. The on-chain
@@ -49,3 +57,4 @@ export declare function normalizeBitcoinAddress(address: string): string;
  * @throws Clear error message if validation fails
  */
 export declare function safeValidatePositionId(positionId: string): string;
+export {};

package/dist/utils/agent-delegation.utils.d.ts

@@ -18,3 +18,42 @@ export declare function mintAgentPkp(params: {
     authHeader?: () => Promise<Record<string, string>> | Record<string, string>;
     timeoutMs?: number;
 }): Promise<string>;
+/** `AgentStatus` in `IAgentDelegateRegistryBase.sol`. */
+export declare const AGENT_STATUS: {
+    readonly None: 0;
+    readonly Active: 1;
+    readonly Revoked: 2;
+};
+/** How the enable-path binds the borrower's agent. `reuse` needs no mint and no tx. */
+export type AgentBindingPlan = {
+    kind: "reuse";
+    agent: string;
+} | {
+    kind: "register";
+} | {
+    kind: "rotate";
+};
+/**
+ * Decide which registry call binds a borrower's agent — BEFORE a PKP is minted.
+ *
+ * The registry does not change `status` on expiry: an expired agent is still
+ * `status == Active`, only `validUntil` has passed. So `isAgentActive()` is false, yet
+ * `registerAgent` reverts `AgentIsActiveUseRotate()` — rotation is the renewal path, and it
+ * needs a NEW agent address (AR-1 burns an address on first bind). Treating "not active" as
+ * "register" minted a billed PKP and then reverted, on every attempt, once an agent expired.
+ *
+ * `isAgentActive` also folds in the registry's pause. An UNEXPIRED `Active` record that reads
+ * inactive means paused: both `registerAgent` and `rotateAgent` are `whenNotPaused`, so this
+ * throws rather than let the caller mint a PKP for a transaction that cannot land.
+ *
+ * @param nowSeconds chain time (latest block timestamp), not the local clock
+ */
+export declare function planAgentBinding(params: {
+    isActive: boolean;
+    record: {
+        agent: string;
+        validUntil: bigint | number;
+        status: bigint | number;
+    };
+    nowSeconds: number;
+}): AgentBindingPlan;

package/dist/utils/assert-provider-chain.d.ts

@@ -0,0 +1,16 @@
+/**
+ * An explicit `chainId` is a claim until the provider confirms it.
+ *
+ * The SDK resolves its contract addresses, validators and subgraph from `chainId`. If the
+ * provider (the wallet) is actually on another chain, every address it is about to call or
+ * sign for belongs to the wrong network. So the claim is checked once, at initialisation.
+ *
+ * Returns the mismatch as a message (for the caller's `Result`), or `null` when the provider
+ * agrees. A provider that cannot report its network is NOT waved through: its error
+ * propagates unchanged, so the caller sees the real cause and no SDK exists to sign with.
+ */
+export declare function describeProviderChainMismatch(provider: {
+    getNetwork(): Promise<{
+        chainId: bigint | number;
+    }>;
+}, chainId: number): Promise<string | null>;

package/dist/utils/borrower-ucd-debt-summary.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Pure helpers behind `getBorrowerUcdDebtSummary`.
+ *
+ * Kept free of the graph client so the arithmetic and the pagination loop are
+ * unit-testable without a subgraph: the loop takes a page fetcher, the builder
+ * takes rows. Nothing here reads the chain — every figure is the INDEXED view
+ * (the subgraph lags writes), which is why the summary carries `source: "subgraph"`
+ * and must never size a transaction.
+ */
+import { LoanStatus } from "../types/loanStatus";
+import type { BorrowerUcdDebtSummary } from "../interfaces/chunks/loan-operations.i";
+/** The subgraph fields a debt summary needs, exactly as the indexer serialises them. */
+export interface BorrowerDebtRow {
+    id: string;
+    /** Subgraph enum label, e.g. "ACTIVE" — NOT the numeric LoanStatus. */
+    status: string;
+    /** Wei (18 decimals) as the subgraph's BigInt decimal string. */
+    ucdDebt: string;
+}
+/** One page per round trip at The Graph's ceiling; nothing to tune. */
+export declare const BORROWER_DEBT_ROWS_PAGE_SIZE = 1000;
+/** 10 × 1000 = 10_000 positions. Past this the loop THROWS — never a partial total. */
+export declare const BORROWER_DEBT_ROWS_MAX_PAGES = 10;
+export type BorrowerDebtPageFetcher = (skip: number, first: number) => Promise<BorrowerDebtRow[]>;
+/**
+ * Page `fetchPage` from skip 0 in `BORROWER_DEBT_ROWS_PAGE_SIZE` steps until a
+ * short page. A page failure propagates untouched (the caller wraps it with the
+ * cause); the page cap throws rather than returning what was collected so far.
+ */
+export declare function collectBorrowerDebtRows(fetchPage: BorrowerDebtPageFetcher): Promise<BorrowerDebtRow[]>;
+/**
+ * Subgraph `Position.status` is the enum LABEL ("ACTIVE"). Convert it explicitly
+ * and throw on anything else — the `as LoanStatus` cast elsewhere in the SDK only
+ * pretends the string is a number.
+ */
+export declare function parseSubgraphLoanStatus(label: unknown): LoanStatus;
+/** Exact 18-decimal rendering with trailing zeros trimmed: "5", "21.93", "0". */
+export declare function weiToHumanUcdString(wei: bigint): string;
+/**
+ * Sum every row regardless of status (terminal rows are expected to carry 0; a
+ * non-zero terminal row is an indexer defect that should show up in the total,
+ * not be filtered away) and histogram the statuses.
+ */
+export declare function buildBorrowerUcdDebtSummary(borrower: string, rows: ReadonlyArray<BorrowerDebtRow>, fetchedAt?: number): BorrowerUcdDebtSummary;