@kasufinance/kasu-sdk 2.11.0 → 2.13.0

package/dist/services/Portfolio/yield-history.js

@@ -0,0 +1,378 @@
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+import { gql } from 'graphql-request';
+import { epochTrancheYield, } from '../../domain/yield-history';
+/** The subgraph returns at most this many rows per collection per request. */
+export const YIELD_HISTORY_PAGE_SIZE = 1000;
+/**
+ * A runaway guard, not a working limit: a collection this many pages long
+ * (`MAX × PAGE_SIZE` rows for one lender) is a broken response, not a history.
+ */
+export const YIELD_HISTORY_MAX_PAGES = 100;
+/**
+ * Throws `RangeError` on a malformed `fromEpoch` / `count`. `getYieldHistory`
+ * calls it BEFORE any network read.
+ */
+export function validateYieldHistoryOptions(options) {
+    const { fromEpoch, count } = options;
+    if (fromEpoch !== undefined &&
+        (!Number.isSafeInteger(fromEpoch) || fromEpoch < 0)) {
+        throw new RangeError(`getYieldHistory: fromEpoch must be a non-negative integer, got ${String(fromEpoch)}`);
+    }
+    if (count !== undefined && (!Number.isSafeInteger(count) || count < 1)) {
+        throw new RangeError(`getYieldHistory: count must be a positive integer, got ${String(count)}`);
+    }
+}
+export function resolveYieldHistoryWindow(options, currentEpoch) {
+    validateYieldHistoryOptions(options);
+    const { fromEpoch, count } = options;
+    const newest = currentEpoch - 1;
+    if (newest < 0)
+        return null;
+    let from;
+    let to = newest;
+    if (fromEpoch !== undefined) {
+        from = fromEpoch;
+        if (count !== undefined)
+            to = Math.min(newest, fromEpoch + count - 1);
+    }
+    else {
+        from = count !== undefined ? Math.max(0, newest - count + 1) : 0;
+    }
+    return from > to ? null : { fromEpoch: from, toEpoch: to };
+}
+// ---------------------------------------------------------------------------
+// Subgraph reads
+// ---------------------------------------------------------------------------
+/**
+ * Round trip 1: the lender's tranche positions and fixed-term locks. Same
+ * pool exclusion and the same nested-list size (`$first`) as
+ * `lendingPortfolioQuery`, so both read the same lock set.
+ */
+export const yieldHistoryPositionsQuery = gql `
+    query YieldHistoryPositions(
+        $userAddress: ID!
+        $unusedPools: [String!]!
+        $first: Int!
+    ) {
+        user(id: $userAddress) {
+            lendingPoolUserDetails(
+                first: $first
+                where: { lendingPool_not_in: $unusedPools }
+            ) {
+                lendingPool {
+                    id
+                }
+                lendingPoolTrancheUserDetails(first: $first) {
+                    id
+                    tranche {
+                        id
+                        balance
+                        shares
+                    }
+                    userLendingPoolTrancheFixedTermDepositLocks(first: $first) {
+                        id
+                        epochLockStart
+                        epochLockEnd
+                        initialTrancheShares
+                    }
+                }
+            }
+        }
+    }
+`;
+/**
+ * Round trip 2 onwards: the four per-epoch series, one page of each per
+ * request, cursor-paginated by `id`. A series that is exhausted is skipped with
+ * `@include`, so a history costs as many requests as its LONGEST series has
+ * pages — normally one — never one per epoch.
+ *
+ * Share snapshots are read up to the window's end with no lower bound: the
+ * value AS OF the first epoch may come from an update long before it.
+ */
+export const yieldHistoryPageQuery = gql `
+    query YieldHistoryPage(
+        $tranches: [String!]!
+        $userTranches: [String!]!
+        $locks: [String!]!
+        $fromEpoch: BigInt!
+        $toEpoch: BigInt!
+        $interestCursor: ID!
+        $trancheSharesCursor: ID!
+        $userSharesCursor: ID!
+        $lockSharesCursor: ID!
+        $withInterest: Boolean!
+        $withTrancheShares: Boolean!
+        $withUserShares: Boolean!
+        $withLockShares: Boolean!
+        $first: Int!
+    ) {
+        interest: lendingPoolTrancheEpochInterests(
+            first: $first
+            orderBy: id
+            orderDirection: asc
+            where: {
+                id_gt: $interestCursor
+                lendingPoolTranche_in: $tranches
+                epochId_gte: $fromEpoch
+                epochId_lte: $toEpoch
+            }
+        ) @include(if: $withInterest) {
+            id
+            epochId
+            epochInterestAmount
+            lendingPoolTranche {
+                id
+            }
+        }
+        trancheShares: lendingPoolTrancheShareUpdates(
+            first: $first
+            orderBy: id
+            orderDirection: asc
+            where: {
+                id_gt: $trancheSharesCursor
+                lendingPoolTranche_in: $tranches
+                epochId_lte: $toEpoch
+            }
+        ) @include(if: $withTrancheShares) {
+            id
+            epochId
+            shareUpdatesIndex
+            shares
+            lendingPoolTranche {
+                id
+            }
+        }
+        userShares: lendingPoolTrancheUserEpochSharesUpdates(
+            first: $first
+            orderBy: id
+            orderDirection: asc
+            where: {
+                id_gt: $userSharesCursor
+                lendingPoolTrancheUserDetails_in: $userTranches
+                epochId_lte: $toEpoch
+            }
+        ) @include(if: $withUserShares) {
+            id
+            epochId
+            shareUpdatesIndex
+            shares
+            lendingPoolTrancheUserDetails {
+                id
+            }
+        }
+        lockShares: userLendingPoolTrancheFtdLockShareUpdates(
+            first: $first
+            orderBy: id
+            orderDirection: asc
+            where: {
+                id_gt: $lockSharesCursor
+                userLendingPoolTrancheFixedTermDepositLock_in: $locks
+                epochId_lte: $toEpoch
+            }
+        ) @include(if: $withLockShares) {
+            id
+            epochId
+            shareUpdatesIndex
+            shares
+            userLendingPoolTrancheFixedTermDepositLock {
+                id
+            }
+        }
+    }
+`;
+/**
+ * Fetch the four series for the window, paginating each by `id` until a short
+ * page. Returns the rows and how many requests it took.
+ */
+export function fetchYieldHistorySeries(request, ids, window) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a;
+        const rows = {
+            interest: [],
+            trancheShares: [],
+            userShares: [],
+            lockShares: [],
+        };
+        const series = [
+            { key: 'interest', flag: 'withInterest', cursor: 'interestCursor' },
+            {
+                key: 'trancheShares',
+                flag: 'withTrancheShares',
+                cursor: 'trancheSharesCursor',
+            },
+            {
+                key: 'userShares',
+                flag: 'withUserShares',
+                cursor: 'userSharesCursor',
+            },
+            {
+                key: 'lockShares',
+                flag: 'withLockShares',
+                cursor: 'lockSharesCursor',
+            },
+        ];
+        const cursors = {
+            interest: '',
+            trancheShares: '',
+            userShares: '',
+            lockShares: '',
+        };
+        const open = {
+            interest: ids.tranches.length > 0,
+            trancheShares: ids.tranches.length > 0,
+            userShares: ids.userTranches.length > 0,
+            lockShares: ids.locks.length > 0,
+        };
+        let requests = 0;
+        while (series.some(({ key }) => open[key])) {
+            if (requests >= YIELD_HISTORY_MAX_PAGES) {
+                throw new Error(`getYieldHistory: more than ${String(YIELD_HISTORY_MAX_PAGES)} pages for one lender`);
+            }
+            const variables = {
+                tranches: ids.tranches,
+                userTranches: ids.userTranches,
+                locks: ids.locks,
+                fromEpoch: String(window.fromEpoch),
+                toEpoch: String(window.toEpoch),
+                first: YIELD_HISTORY_PAGE_SIZE,
+            };
+            for (const { key, flag, cursor } of series) {
+                variables[flag] = open[key];
+                variables[cursor] = cursors[key];
+            }
+            const page = yield request(variables);
+            requests += 1;
+            for (const { key } of series) {
+                if (!open[key])
+                    continue;
+                const got = (_a = page[key]) !== null && _a !== void 0 ? _a : [];
+                rows[key].push(...got);
+                const last = got.at(-1);
+                if (got.length < YIELD_HISTORY_PAGE_SIZE || last === undefined) {
+                    open[key] = false;
+                    continue;
+                }
+                if (last.id <= cursors[key]) {
+                    throw new Error(`getYieldHistory: the ${key} cursor did not advance`);
+                }
+                cursors[key] = last.id;
+            }
+        }
+        return { rows, requests };
+    });
+}
+/**
+ * The snapshot in force at `epoch`: among updates with `epochId ≤ epoch`, the
+ * one with the highest `shareUpdatesIndex` — exactly what
+ * `lendingPortfolioQuery` selects with `orderBy: shareUpdatesIndex, desc,
+ * first: 1, where: { epochId_lt: epoch + 1 }`. `undefined` when none.
+ */
+export function sharesAsOf(updates, epoch) {
+    let found;
+    for (const update of updates) {
+        if (Number(update.epochId) > epoch)
+            continue;
+        if (!found || update.shareUpdatesIndex > found.shareUpdatesIndex) {
+            found = update;
+        }
+    }
+    return found;
+}
+function groupBy(rows, key) {
+    const map = new Map();
+    for (const row of rows) {
+        const k = key(row);
+        const list = map.get(k);
+        if (list)
+            list.push(row);
+        else
+            map.set(k, [row]);
+    }
+    return map;
+}
+/**
+ * Pure: the fetched series → one entry per pool, tranche and settled epoch in
+ * which the lender held shares (or a lock earned a top-up). Each entry runs the
+ * same `epochTrancheYield` as the portfolio's last-epoch figure, with the same
+ * share selection, so the newest entry equals that figure.
+ *
+ * Sorted by `epochId`, then `poolId`, then `trancheId`.
+ */
+export function buildYieldHistory(read, window, clock) {
+    var _a, _b, _c, _d, _e, _f;
+    const user = read.positions.user;
+    if (!user)
+        return [];
+    const interestByTranche = groupBy(read.interest, (row) => row.lendingPoolTranche.id);
+    const trancheSharesByTranche = groupBy(read.trancheShares, (row) => row.lendingPoolTranche.id);
+    const userSharesByPosition = groupBy(read.userShares, (row) => row.lendingPoolTrancheUserDetails.id);
+    const lockSharesByLock = groupBy(read.lockShares, (row) => row.userLendingPoolTrancheFixedTermDepositLock.id);
+    const entries = [];
+    for (const pool of user.lendingPoolUserDetails) {
+        for (const position of pool.lendingPoolTrancheUserDetails) {
+            const trancheId = position.tranche.id;
+            const trancheUpdates = (_a = trancheSharesByTranche.get(trancheId)) !== null && _a !== void 0 ? _a : [];
+            const userUpdates = (_b = userSharesByPosition.get(position.id)) !== null && _b !== void 0 ? _b : [];
+            const trancheBalanceNow = parseFloat(position.tranche.balance);
+            const trancheSharesNow = parseFloat(position.tranche.shares);
+            for (const record of (_c = interestByTranche.get(trancheId)) !== null && _c !== void 0 ? _c : []) {
+                const epoch = Number(record.epochId);
+                if (epoch < window.fromEpoch || epoch > window.toEpoch) {
+                    continue;
+                }
+                const userSnapshot = sharesAsOf(userUpdates, epoch);
+                const userShares = parseFloat((_d = userSnapshot === null || userSnapshot === void 0 ? void 0 : userSnapshot.shares) !== null && _d !== void 0 ? _d : '0');
+                const locks = position.userLendingPoolTrancheFixedTermDepositLocks.map((lock) => {
+                    var _a, _b, _c, _d, _e;
+                    const lockUpdates = (_a = lockSharesByLock.get(lock.id)) !== null && _a !== void 0 ? _a : [];
+                    return {
+                        active: parseFloat(lock.epochLockStart) < epoch &&
+                            parseFloat(lock.epochLockEnd) >= epoch &&
+                            userSnapshot !== undefined,
+                        // No snapshot yet = the lock's opening
+                        // shares: a lock made after clearing E
+                        // starts at E but its first update is
+                        // tagged E + 1, and reading that gap as 0
+                        // would book its principal as a top-up.
+                        sharesAtEpoch: parseFloat((_c = (_b = sharesAsOf(lockUpdates, epoch)) === null || _b === void 0 ? void 0 : _b.shares) !== null && _c !== void 0 ? _c : lock.initialTrancheShares),
+                        sharesBeforeEpoch: parseFloat((_e = (_d = sharesAsOf(lockUpdates, epoch - 1)) === null || _d === void 0 ? void 0 : _d.shares) !== null && _e !== void 0 ? _e : lock.initialTrancheShares),
+                    };
+                });
+                const { total } = epochTrancheYield({
+                    epochInterest: parseFloat(record.epochInterestAmount),
+                    userShares,
+                    trancheShares: parseFloat((_f = (_e = sharesAsOf(trancheUpdates, epoch)) === null || _e === void 0 ? void 0 : _e.shares) !== null && _f !== void 0 ? _f : '0'),
+                    trancheBalanceNow,
+                    trancheSharesNow,
+                    locks,
+                });
+                // Nothing held and nothing topped up: not part of this
+                // lender's history (a new lender's history is empty).
+                if (userShares <= 0 && total === 0)
+                    continue;
+                entries.push({
+                    epochId: epoch,
+                    epochEnd: clock.epochZeroStart +
+                        (epoch + 1) * clock.epochDuration,
+                    poolId: pool.lendingPool.id,
+                    trancheId,
+                    netYield: total,
+                });
+            }
+        }
+    }
+    return entries.sort((a, b) => a.epochId - b.epochId ||
+        a.poolId.localeCompare(b.poolId) ||
+        a.trancheId.localeCompare(b.trancheId));
+}
+// Shared with `getPoolTvlHistory`: one Lite-vs-full rule for every history.
+export { isEmptyHistoryError, isMissingEntityError } from '../shared';
+//# sourceMappingURL=yield-history.js.map

package/dist/services/Portfolio/yield-history.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"yield-history.js","sourceRoot":"","sources":["../../../src/services/Portfolio/yield-history.ts"],"names":[],"mappings":"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"}

package/dist/services/shared.d.ts

@@ -1 +1,17 @@
 export declare function filterArray<T>(array: T[], id_in?: string[]): T[];
+/**
+ * A GraphQL VALIDATION error naming an entity, field or argument this
+ * deployment's subgraph does not have. A network error, a timeout or an
+ * indexing error is not one.
+ */
+export declare function isMissingEntityError(error: unknown): boolean;
+/**
+ * The only failure a history read (`getYieldHistory`, `getPoolTvlHistory`)
+ * turns into `[]`: a missing-schema error
+ * on a LITE deployment, whose subgraph may predate the entities. On a full
+ * deployment the entities are part of the schema, so the same error means a
+ * broken query or subgraph and THROWS — an empty chart there would hide it.
+ * Everything else (network, timeout, indexing) throws on every deployment, so
+ * a consumer can tell "no history here" from "history unavailable".
+ */
+export declare function isEmptyHistoryError(error: unknown, liteDeployment: boolean): boolean;

package/dist/services/shared.js

@@ -9,4 +9,34 @@ export function filterArray(array, id_in) {
         });
     }
 }
+/**
+ * A GraphQL VALIDATION error naming an entity, field or argument this
+ * deployment's subgraph does not have. A network error, a timeout or an
+ * indexing error is not one.
+ */
+export function isMissingEntityError(error) {
+    if (typeof error !== 'object' || error === null)
+        return false;
+    const response = error.response;
+    const errors = response === null || response === void 0 ? void 0 : response.errors;
+    if (!Array.isArray(errors) || errors.length === 0)
+        return false;
+    return errors.every((e) => {
+        const message = e === null || e === void 0 ? void 0 : e.message;
+        return (typeof message === 'string' &&
+            /has no field|cannot query field|unknown (type|field|argument)|no such (type|field)/i.test(message));
+    });
+}
+/**
+ * The only failure a history read (`getYieldHistory`, `getPoolTvlHistory`)
+ * turns into `[]`: a missing-schema error
+ * on a LITE deployment, whose subgraph may predate the entities. On a full
+ * deployment the entities are part of the schema, so the same error means a
+ * broken query or subgraph and THROWS — an empty chart there would hide it.
+ * Everything else (network, timeout, indexing) throws on every deployment, so
+ * a consumer can tell "no history here" from "history unavailable".
+ */
+export function isEmptyHistoryError(error, liteDeployment) {
+    return liteDeployment && isMissingEntityError(error);
+}
 //# sourceMappingURL=shared.js.map

package/dist/services/shared.js.map

@@ -1 +1 @@
-{"version":3,"file":"shared.js","sourceRoot":"","sources":["../../src/services/shared.ts"],"names":[],"mappings":"AAAA,MAAM,UAAU,WAAW,CAAI,KAAU,EAAE,KAAgB;IACvD,IAAG,CAAC,KAAK,EAAC,CAAC;QACP,OAAO,KAAK,CAAC;IACjB,CAAC;SACG,CAAC;QACD,OAAO,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE;YACvB,MAAM,EAAE,EAAE,EAAE,GAAG,IAAsB,CAAC;YACtC,OAAO,KAAK,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;QAC9B,CAAC,CAAC,CAAC;IACP,CAAC;AACL,CAAC"}
+{"version":3,"file":"shared.js","sourceRoot":"","sources":["../../src/services/shared.ts"],"names":[],"mappings":"AAAA,MAAM,UAAU,WAAW,CAAI,KAAU,EAAE,KAAgB;IACvD,IAAG,CAAC,KAAK,EAAC,CAAC;QACP,OAAO,KAAK,CAAC;IACjB,CAAC;SACG,CAAC;QACD,OAAO,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE;YACvB,MAAM,EAAE,EAAE,EAAE,GAAG,IAAsB,CAAC;YACtC,OAAO,KAAK,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;QAC9B,CAAC,CAAC,CAAC;IACP,CAAC;AACL,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,oBAAoB,CAAC,KAAc;IAC/C,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC;IAC9D,MAAM,QAAQ,GAAI,KAA6C,CAAC,QAAQ,CAAC;IACzE,MAAM,MAAM,GAAG,QAAQ,aAAR,QAAQ,uBAAR,QAAQ,CAAE,MAAM,CAAC;IAChC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IAChE,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC,CAAU,EAAE,EAAE;QAC/B,MAAM,OAAO,GAAI,CAAkC,aAAlC,CAAC,uBAAD,CAAC,CAAmC,OAAO,CAAC;QAC7D,OAAO,CACH,OAAO,OAAO,KAAK,QAAQ;YAC3B,qFAAqF,CAAC,IAAI,CACtF,OAAO,CACV,CACJ,CAAC;IACN,CAAC,CAAC,CAAC;AACP,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,mBAAmB,CAC/B,KAAc,EACd,cAAuB;IAEvB,OAAO,cAAc,IAAI,oBAAoB,CAAC,KAAK,CAAC,CAAC;AACzD,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@kasufinance/kasu-sdk",
-    "version": "2.11.0",
+    "version": "2.13.0",
     "description": "TypeScript SDK for the Kasu Finance protocol — pool data, portfolio analytics, and KYC-gated deposits and withdrawals on Base and XDC",
     "keywords": [
         "kasu",

package/src/domain/index.ts

@@ -134,11 +134,7 @@ export {
     lastEventTimestamp,
     submissionEvents,
 } from './requests';
-export type {
-    RequestKind,
-    RequestState,
-    RequestStatusCode,
-} from './requests';
+export type { RequestKind, RequestState, RequestStatusCode } from './requests';
 
 export { decodeRevert, extractRevertData } from './revert-errors';
 export type { DecodedRevert, RevertFamily } from './revert-errors';
@@ -183,11 +179,7 @@ export {
     trancheHasCapacity,
     trancheRiskRank,
 } from './tranches';
-export type {
-    ApyBounds,
-    PoolStatus,
-    TrancheCapacitySignal,
-} from './tranches';
+export type { ApyBounds, PoolStatus, TrancheCapacitySignal } from './tranches';
 
 export {
     classifyWalletFailure,
@@ -196,6 +188,19 @@ export {
 } from './wallet-errors';
 export type { WalletFailure } from './wallet-errors';
 
+export { poolTvl } from './pool-tvl';
+export type { PoolTvlHistoryEntry } from './pool-tvl';
+
+export { aggregateYieldHistory, epochTrancheYield } from './yield-history';
+export type {
+    EpochLockShares,
+    EpochTrancheYield,
+    EpochTrancheYieldInput,
+    YieldHistoryEntry,
+    YieldHistoryFilter,
+    YieldHistoryPoint,
+} from './yield-history';
+
 export {
     accruedInterest,
     dailyInterest,

package/src/domain/pool-tvl.ts

@@ -0,0 +1,66 @@
+/**
+ * A pool's TVL — the total lent into it by everyone — and the shape of its
+ * history. Pure: the reads live in `services/DataService/tvl-history.ts`.
+ */
+
+/**
+ * The ONE definition of a pool's TVL: what lenders have lent on chain
+ * (`lendingPool.balance` in the subgraph) plus the off-chain amount the
+ * pool's `ExternalTVL` contract records (`externalTVLOfPool`).
+ *
+ * Both inputs, and the result, are in DISPLAY units of the deployment's own
+ * stable token (USDC on Base and XDC USDC, AUDD on XDC AUDD) — `'1.5'` is
+ * one and a half tokens, not 1.5 minor units. Convert before formatting as
+ * USD.
+ *
+ * `getPoolOverview` (its `totalValueLocked.total`) and `getPoolTvlHistory`
+ * (every point) both call this, so the chart and the figure above it cannot
+ * be computed two ways.
+ */
+export function poolTvl(onChainBalance: string, offChainTvl: string): number {
+    return parseFloat(onChainBalance) + parseFloat(offChainTvl);
+}
+
+/**
+ * One point of a pool's TVL history.
+ *
+ * - `kind: 'clearing'` — the TVL as it stood at the end of the block in which
+ *   that epoch's clearing finished (`LendingPoolClearing.endBlockNumber`):
+ *   accepted deposits and withdrawals and the applied interest included.
+ * - `kind: 'current'` — the closing "as of now" point, from two sources: the
+ *   subgraph's latest balance (and its latest block time) and
+ *   `externalTVLOfPool` at `latest` on the history provider. It equals
+ *   today's `PoolOverview.totalValueLocked.total` when both that call's reads
+ *   and these succeed; `getPoolOverview` falls back to an off-chain 0 when its
+ *   own read fails, and the figure can move between the two calls.
+ */
+export interface PoolTvlHistoryEntry {
+    /**
+     * The epoch (cycle) number, in the chain's numbering
+     * (`SystemVariables.currentEpochNumber`).
+     *
+     * A clearing point carries the epoch that clearing closed. The `current`
+     * point carries the CURRENT epoch — which may equal the newest clearing's
+     * epoch, because a clearing runs before its epoch rolls over. Epoch
+     * numbers can jump (a pool that did not clear for a while, or a
+     * deployment whose first clearing is numbered far below the next one), so
+     * plot by `timestamp`, never by `epochId`.
+     */
+    epochId: number;
+    /**
+     * Unix SECONDS. A clearing point: the time of the block its clearing
+     * finished in (`endTimestamp`). The `current` point: the time of the
+     * subgraph's latest indexed block. Clearings that finished in the same
+     * block (a pool catching up several epochs at once) share a timestamp and
+     * a `tvl`.
+     */
+    timestamp: number;
+    /**
+     * TVL in DISPLAY units of the deployment's own stable token (USDC on Base
+     * and XDC USDC, AUDD on XDC AUDD): `poolTvl(onChain, offChain)` at that
+     * block. Convert before formatting as USD.
+     */
+    tvl: number;
+    /** `'clearing'` for a cycle boundary; `'current'` for the closing point. */
+    kind: 'clearing' | 'current';
+}