@gvnrdao/dh-sdk 0.0.338 → 0.0.339

package/dist/graphs/diamond-hands.d.ts

@@ -3,6 +3,7 @@ import type { LoanData } from "../interfaces";
 import type { GraphPositionWithBorrowerDTO } from "../types/graph-dtos";
 import type { LoanEvents, LoanEventsFilter } from "../types/event-types";
 import type { BitcoinOperations, EnrichedBitcoinBalance } from "../modules/bitcoin/bitcoin-operations.module";
+import { type BorrowerDebtRow } from "../utils/borrower-ucd-debt-summary";
 export interface DiamondHandsGraphConfig {
     endpoint: string;
     requestTimeoutMs?: number;
@@ -321,6 +322,19 @@ export declare class DiamondHandsGraph {
      * Get user positions from subgraph
      */
     private getUserPositionsOnly;
+    /**
+     * 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.
+     */
+    getBorrowerDebtRows(borrower: string): Promise<BorrowerDebtRow[]>;
     /**
      * Get user positions, plus an accurate total count.
      *

package/dist/index.d.ts

@@ -41,7 +41,7 @@ export type { DhServerLoginMessage, DhServerLoginPayload, } from './utils/eip712
 export { DEFAULT_LIT_NETWORK, VALID_LIT_NETWORKS, SDK_DEFAULTS, } from './constants/chunks/sdk-config';
 export { ALL_CONTRACTS, ALL_DEPLOYMENTS, getContractsByNetwork, getDeploymentByNetwork, LOCALHOST_CONTRACTS, SEPOLIA_CONTRACTS, } from './constants/chunks/deployment-addresses';
 export type { DeploymentContracts, DeploymentData, DeploymentLatestEnv, } from './constants/chunks/deployment-addresses';
-export type { CreateLoanRequest, CreateLoanResult, LoanData, LoanDataDetail, PaginatedLoansResponse, PKPValidationData, BitcoinAddresses, } from './interfaces/chunks/loan-operations.i';
+export type { CreateLoanRequest, CreateLoanResult, LoanData, LoanDataDetail, PaginatedLoansResponse, BorrowerUcdDebtSummary, BorrowerUcdDebtStatusCount, PKPValidationData, BitcoinAddresses, } from './interfaces/chunks/loan-operations.i';
 export type { DiamondHandsSDKConfig, SDKMode, ContractAddresses, BitcoinProviderConfig, } from './interfaces/chunks/config.i';
 export type { PKPData, PKPCreationRequest, PKPCreationResult, PKPValidationResult, } from './interfaces/chunks/pkp-integration.i';
 export type { AuthorizationRequest, AuthorizationResult, BTCDepositRequest, BTCDepositResult, } from './interfaces/chunks/requests.i';

package/dist/index.js

@@ -10465,6 +10465,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 +10952,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 +12523,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 +12870,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 +12888,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.
    *
@@ -25708,6 +25877,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
    *

package/dist/index.mjs

@@ -10382,7 +10382,102 @@ var LoanStatus = /* @__PURE__ */ ((LoanStatus2) => {
 })(LoanStatus || {});
 
 // src/modules/loan/loan-query.module.ts
-import { Contract as Contract4 } from "ethers";
+import { Contract as Contract4, isAddress as isAddress2 } from "ethers";
+
+// src/constants/chunks/sdk-limits.ts
+var THE_GRAPH_MAX_BATCH_SIZE = 1e3;
+
+// src/utils/borrower-ucd-debt-summary.ts
+var BORROWER_DEBT_ROWS_PAGE_SIZE = THE_GRAPH_MAX_BATCH_SIZE;
+var BORROWER_DEBT_ROWS_MAX_PAGES = 10;
+async function collectBorrowerDebtRows(fetchPage) {
+  const pageSize = BORROWER_DEBT_ROWS_PAGE_SIZE;
+  const rows = [];
+  for (let page = 0; page < BORROWER_DEBT_ROWS_MAX_PAGES; page++) {
+    const batch = await fetchPage(page * pageSize, pageSize);
+    if (batch.length > pageSize) {
+      throw new Error(
+        `Borrower debt page ${page} returned ${batch.length} rows for first: ${pageSize}`
+      );
+    }
+    rows.push(...batch);
+    if (batch.length < pageSize) {
+      return rows;
+    }
+  }
+  throw new Error(
+    `Borrower debt rows exceeded ${BORROWER_DEBT_ROWS_MAX_PAGES} pages of ${pageSize} (${rows.length} rows so far); refusing to return a partial total`
+  );
+}
+function parseSubgraphLoanStatus(label) {
+  if (typeof label !== "string") {
+    throw new Error(`Subgraph loan status is not a string: ${String(label)}`);
+  }
+  const value = LoanStatus[label];
+  if (typeof value !== "number") {
+    throw new Error(`Unknown subgraph loan status label: "${label}"`);
+  }
+  return value;
+}
+function parseSubgraphWei(row) {
+  const raw = row.ucdDebt || "0";
+  if (typeof raw !== "string") {
+    throw new Error(
+      `ucdDebt on position ${row.id} is not a string: ${String(raw)}`
+    );
+  }
+  let wei;
+  try {
+    wei = BigInt(raw);
+  } catch (error) {
+    throw new Error(
+      `ucdDebt on position ${row.id} is not an integer wei string: "${raw}"`,
+      { cause: error }
+    );
+  }
+  if (wei < 0n) {
+    throw new Error(`Negative ucdDebt on position ${row.id}: ${raw}`);
+  }
+  return wei;
+}
+var WEI_PER_UCD = 10n ** 18n;
+function weiToHumanUcdString(wei) {
+  if (wei < 0n) {
+    throw new Error(`Cannot render negative wei: ${wei}`);
+  }
+  const whole = wei / WEI_PER_UCD;
+  const frac = (wei % WEI_PER_UCD).toString().padStart(18, "0").replace(/0+$/, "");
+  return frac.length > 0 ? `${whole}.${frac}` : `${whole}`;
+}
+var STATUS_ORDINALS = Object.values(LoanStatus).filter((v) => typeof v === "number").sort((a, b) => a - b);
+function buildBorrowerUcdDebtSummary(borrower, rows, fetchedAt = Date.now()) {
+  let totalWei = 0n;
+  const counts = /* @__PURE__ */ new Map();
+  for (const row of rows) {
+    totalWei += parseSubgraphWei(row);
+    const status = parseSubgraphLoanStatus(row.status);
+    counts.set(status, (counts.get(status) ?? 0) + 1);
+  }
+  const byStatus = [];
+  for (const status of STATUS_ORDINALS) {
+    const count = counts.get(status);
+    if (count === void 0) {
+      continue;
+    }
+    byStatus.push({ status, statusLabel: LoanStatus[status], count });
+  }
+  return {
+    borrower: borrower.toLowerCase(),
+    loanCount: rows.length,
+    totalUcdDebt: totalWei.toString(),
+    totalUcdDebtHuman: weiToHumanUcdString(totalWei),
+    byStatus,
+    source: "subgraph",
+    fetchedAt
+  };
+}
+
+// src/modules/loan/loan-query.module.ts
 var POSITION_CORE_ABI = [
   "function getPositionDetails(bytes32) view returns (tuple(bytes32 positionId, bytes32 pkpId, uint256 ucdDebt, string vaultAddress, address borrower, uint40 createdAt, uint40 lastUpdated, uint16 selectedTerm, uint40 expiryAt, uint8 status, uint40 previousExpiryAt, uint16 totalTerm))"
 ];
@@ -10775,6 +10870,43 @@ var LoanQuery = class {
   async getLoansByBorrower(borrower, pagination, orderBy, orderDirection) {
     return this.getLoans({ borrower, orderBy, orderDirection }, pagination);
   }
+  /**
+   * Combined UCD debt + by-status counts for a borrower from ONE pass over the
+   * subgraph's raw rows (`graphClient.getBorrowerDebtRows`): BigInt wei sum, strict
+   * status labels, `source: "subgraph"`.
+   *
+   * INDEXED figure, not a transaction input — the subgraph lags writes. Anything that
+   * sizes a repayment reads the chain (`getPositionDetailsView`). Fails loud: a page
+   * failure or the page cap is a SUBGRAPH-category failure carrying the cause; there
+   * is no partial total.
+   */
+  async getBorrowerUcdDebtSummary(borrower) {
+    const trimmed = typeof borrower === "string" ? borrower.trim() : "";
+    if (!isAddress2(trimmed)) {
+      return failure(
+        new SDKError({
+          message: `Borrower must be an EVM address for a UCD debt summary, got "${trimmed}"`,
+          category: "VALIDATION" /* VALIDATION */,
+          severity: "LOW" /* LOW */,
+          context: { borrower: trimmed }
+        })
+      );
+    }
+    return tryCatchAsync(
+      async () => {
+        const rows = await this.config.graphClient.getBorrowerDebtRows(trimmed);
+        return buildBorrowerUcdDebtSummary(trimmed, rows);
+      },
+      (error) => error instanceof SDKError ? error : new SDKError({
+        message: `Borrower UCD debt summary failed for ${trimmed}: ${error instanceof Error ? error.message : String(error)}`,
+        category: "SUBGRAPH" /* SUBGRAPH */,
+        severity: "MEDIUM" /* MEDIUM */,
+        originalError: error instanceof Error ? error : void 0,
+        cause: error,
+        context: { borrower: trimmed }
+      })
+    );
+  }
   /**
    * Get active loans (status = ACTIVE)
    *
@@ -12309,10 +12441,36 @@ var GraphClient = class {
   }
 };
 
-// src/constants/chunks/sdk-limits.ts
-var THE_GRAPH_MAX_BATCH_SIZE = 1e3;
-
 // src/graphs/diamond-hands.ts
+var GET_USER_POSITIONS_DOCUMENT = `
+      query GetUserPositions($borrower: Bytes!, $first: Int, $skip: Int, $orderBy: Position_orderBy, $orderDirection: OrderDirection) {
+        user(id: $borrower) {
+          id
+          positions(first: $first, skip: $skip, orderBy: $orderBy, orderDirection: $orderDirection) {
+            id
+            pkpId
+            borrower {
+              createdAt
+              id
+            }
+            # btcAmount removed - balance is now queried on-chain via lit-actions with signature validation
+            ucdMinted
+            ucdPaid
+            ucdDebt
+            collateralRatio
+            requestedCollateralRatio
+            selectedTerm
+            status
+            createdAt
+            createdAtBlock
+            lastUpdated
+            originalTerm
+            remainingDebt
+            expiryAt
+          }
+        }
+      }
+    `;
 function normalizePkpId2(pkpId) {
   const raw = pkpId.startsWith("0x") ? pkpId.slice(2) : pkpId;
   if (raw.length === 64 && raw.startsWith("000000000000000000000000") && raw !== "0".repeat(64)) {
@@ -12630,35 +12788,7 @@ var DiamondHandsGraph = class {
    * Get user positions from subgraph
    */
   async getUserPositionsOnly(userAddress, first, skip, orderBy, orderDirection) {
-    const query = `
-      query GetUserPositions($borrower: Bytes!, $first: Int, $skip: Int, $orderBy: Position_orderBy, $orderDirection: OrderDirection) {
-        user(id: $borrower) {
-          id
-          positions(first: $first, skip: $skip, orderBy: $orderBy, orderDirection: $orderDirection) {
-            id
-            pkpId
-            borrower {
-              createdAt
-              id
-            }
-            # btcAmount removed - balance is now queried on-chain via lit-actions with signature validation
-            ucdMinted
-            ucdPaid
-            ucdDebt
-            collateralRatio
-            requestedCollateralRatio
-            selectedTerm
-            status
-            createdAt
-            createdAtBlock
-            lastUpdated
-            originalTerm
-            remainingDebt
-            expiryAt
-          }
-        }
-      }
-    `;
+    const query = GET_USER_POSITIONS_DOCUMENT;
     const variables = {
       borrower: userAddress.toLowerCase(),
       first: first || void 0,
@@ -12676,6 +12806,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.
    *
@@ -25634,6 +25803,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
    *

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
      *