@kasufinance/kasu-sdk 2.13.1 → 2.15.0

package/src/services/DataService/data-service.ts

@@ -53,13 +53,18 @@ import {
     ClearingsScope,
     createOffChainTvlReader,
     distinctBlocks,
+    fetchClearingBefore,
+    fetchClearingBeforeBlock,
     fetchOffChainTvlAtBlocks,
     fetchPoolBalancesAtBlocks,
     fetchPoolClearings,
     GraphRequest,
+    needsClearingBeforeBlock,
     OffChainTvlReader,
     PastBlockCache,
+    pickOpeningClearing,
     PoolTvlHistoryOptions,
+    PoolTvlHistoryResult,
     resolvePoolTvlHistoryWindow,
     runCancellable,
     TVL_HISTORY_CACHE_DEPTH,
@@ -294,6 +299,47 @@ export class DataService {
         poolId: string,
         options: PoolTvlHistoryOptions = {},
     ): Promise<PoolTvlHistoryEntry[]> {
+        return (await this._poolTvlHistory(poolId, options, false)).entries;
+    }
+
+    /**
+     * `getPoolTvlHistory` — the same options, errors and `entries` — plus
+     * `opening`: the pool's value just before the window, so a strategy
+     * summed across deployments (`combineTvlHistories`) knows what each leg
+     * held before its first point instead of counting it 0.
+     *
+     * `opening` is the newest finished clearing STRICTLY before the window's
+     * first block (by `pickOpeningClearing`), read at its own block exactly
+     * like every other point and through the same past-block cache; `null`
+     * when the pool has no clearing before the window. Extra cost over
+     * `getPoolTvlHistory`:
+     *
+     * - `count` only: one more clearing row in the same request (`count + 1`,
+     *   which always reaches past the window when older history exists);
+     * - `fromEpoch` above 0: one more one-row subgraph request, in parallel
+     *   with the clearings;
+     * - only when every left-out clearing finished in the window's first
+     *   block (a catch-up block that closed several epochs at once): one
+     *   more one-row request by block (`fetchClearingBeforeBlock`), after
+     *   the clearings — the common case never makes it;
+     * - either way, the opening's block in the same batched time-travel read
+     *   and one more `externalTVLOfPool` read (cached once final).
+     *
+     * `{ entries: [], opening: null }` wherever `getPoolTvlHistory` returns
+     * `[]`.
+     */
+    async getPoolTvlHistoryWindow(
+        poolId: string,
+        options: PoolTvlHistoryOptions = {},
+    ): Promise<PoolTvlHistoryResult> {
+        return await this._poolTvlHistory(poolId, options, true);
+    }
+
+    private async _poolTvlHistory(
+        poolId: string,
+        options: PoolTvlHistoryOptions,
+        withOpening: boolean,
+    ): Promise<PoolTvlHistoryResult> {
         validatePoolTvlHistoryOptions(options);
         if (!isAddress(poolId)) {
             throw new TypeError(
@@ -324,6 +370,7 @@ export class DataService {
                         : null,
                     externalTvl ?? '',
                     cancellation,
+                    withOpening,
                 ),
         );
     }
@@ -334,7 +381,9 @@ export class DataService {
         reader: OffChainTvlReader | null,
         externalTvl: string,
         cancellation: Cancellation,
-    ): Promise<PoolTvlHistoryEntry[]> {
+        withOpening: boolean,
+    ): Promise<PoolTvlHistoryResult> {
+        const nothing: PoolTvlHistoryResult = { entries: [], opening: null };
         const graph: GraphRequest = <T>(
             document: string,
             variables: Record<string, unknown>,
@@ -343,20 +392,32 @@ export class DataService {
             this._graph.request<T>({ document, variables, signal });
         const scope: ClearingsScope =
             options.fromEpoch === undefined && options.count !== undefined
-                ? { kind: 'newest', count: options.count }
+                ? {
+                      kind: 'newest',
+                      // One past the window: the opening, when there is one.
+                      count: options.count + (withOpening ? 1 : 0),
+                  }
                 : { kind: 'from', fromEpoch: options.fromEpoch ?? 0 };
 
         try {
-            const [currentEpochNumber, { clearings, snapshot }] =
+            const [currentEpochNumber, { clearings, snapshot }, before] =
                 await Promise.all([
                     this._systemVariablesAbi.currentEpochNumber(),
                     fetchPoolClearings(graph, pool, scope, cancellation),
+                    withOpening && scope.kind === 'from' && scope.fromEpoch > 0
+                        ? fetchClearingBefore(
+                              graph,
+                              pool,
+                              scope.fromEpoch,
+                              cancellation,
+                          )
+                        : Promise.resolve(null),
                 ]);
             const currentEpoch = currentEpochNumber.toNumber();
 
             const window = resolvePoolTvlHistoryWindow(options, currentEpoch);
             const poolNow = snapshot.pool;
-            if (!window || !poolNow) return [];
+            if (!window || !poolNow) return nothing;
             const head = snapshot.meta?.block;
             if (!head || typeof head.timestamp !== 'number') {
                 throw new Error(
@@ -369,7 +430,30 @@ export class DataService {
                     c.epochId >= window.fromEpoch &&
                     c.epochId <= window.toEpoch,
             );
-            const blocks = distinctBlocks(inWindow);
+            // Clearings the window left out, older by epoch: the extra row of
+            // a count fetch, or the one-row read below `fromEpoch`.
+            const older =
+                scope.kind === 'newest'
+                    ? clearings.filter((c) => c.epochId < window.fromEpoch)
+                    : before === null
+                      ? []
+                      : [before];
+            let opening = withOpening
+                ? pickOpeningClearing(older, inWindow)
+                : null;
+            // The left-out clearings all sat in the first in-window block (a
+            // catch-up block): ask for the newest one before it, by block.
+            if (withOpening && needsClearingBeforeBlock(older, opening)) {
+                opening = await fetchClearingBeforeBlock(
+                    graph,
+                    pool,
+                    Math.min(...inWindow.map((c) => c.block)),
+                    cancellation,
+                );
+            }
+            const blocks = distinctBlocks(
+                opening ? [...inWindow, opening] : inWindow,
+            );
             const withCurrent = window.toEpoch >= currentEpoch;
             const cacheable = (block: number): boolean =>
                 block <= head.number - TVL_HISTORY_CACHE_DEPTH;
@@ -393,7 +477,7 @@ export class DataService {
                       },
             ]);
 
-            return buildPoolTvlHistory({
+            const entries = buildPoolTvlHistory({
                 clearings: inWindow,
                 balances,
                 offChain: offChainRead.offChain,
@@ -407,9 +491,21 @@ export class DataService {
                     : null,
                 decimals: this._kasuConfig.stableAssetDecimals,
             });
+            // The same function as every other point, so the opening cannot
+            // be computed another way.
+            const [openingEntry] = opening
+                ? buildPoolTvlHistory({
+                      clearings: [opening],
+                      balances,
+                      offChain: offChainRead.offChain,
+                      current: null,
+                      decimals: this._kasuConfig.stableAssetDecimals,
+                  })
+                : [null];
+            return { entries, opening: openingEntry };
         } catch (error) {
             if (isEmptyHistoryError(error, this._kasuConfig.isLiteDeployment)) {
-                return [];
+                return nothing;
             }
             throw error;
         }

package/src/services/DataService/tvl-history.ts

@@ -37,6 +37,22 @@ export interface PoolTvlHistoryOptions {
     signal?: AbortSignal;
 }
 
+/**
+ * `getPoolTvlHistoryWindow`'s answer: the same entries `getPoolTvlHistory`
+ * returns, and the pool's value just before them. Pass it to
+ * `combineTvlHistories` as a leg (`{ ...result, usdRate }`).
+ */
+export interface PoolTvlHistoryResult {
+    entries: PoolTvlHistoryEntry[];
+    /**
+     * The newest finished clearing BEFORE the window, in a block strictly
+     * before the first entry's, read at its own block like every other point
+     * (`kind: 'clearing'`). `null` when the pool has no clearing before the
+     * window — its whole history is in `entries`. See `pickOpeningClearing`.
+     */
+    opening: PoolTvlHistoryEntry | null;
+}
+
 /** The resolved, inclusive epoch range; `null` when it is empty. */
 export interface PoolTvlHistoryWindow {
     fromEpoch: number;
@@ -449,6 +465,121 @@ export async function fetchPoolClearings(
     return { clearings, snapshot, requests };
 }
 
+/**
+ * Pure: the opening clearing — the newest of `before` (finished clearings the
+ * window left out, older by epoch) that finished STRICTLY before the first
+ * in-window clearing's block. Newest by block, then epoch, so a clearing
+ * numbered out of order (XDC AUDD's epoch 1, a week before epoch 88) is
+ * placed by when it happened. A clearing in the first in-window block itself
+ * (a catch-up block that finished several epochs at once) is not an opening:
+ * it holds the first entry's own value, not the one before it. `null` when
+ * there is none — see `needsClearingBeforeBlock`.
+ */
+export function pickOpeningClearing(
+    before: readonly Clearing[],
+    inWindow: readonly Clearing[],
+): Clearing | null {
+    const firstBlock = Math.min(...inWindow.map((c) => c.block));
+    let opening: Clearing | null = null;
+    for (const clearing of before) {
+        if (clearing.block >= firstBlock) continue;
+        if (
+            opening === null ||
+            clearing.block > opening.block ||
+            (clearing.block === opening.block &&
+                clearing.epochId > opening.epochId)
+        ) {
+            opening = clearing;
+        }
+    }
+    return opening;
+}
+
+/**
+ * Pure: whether the opening needs `fetchClearingBefore`'s by-block read.
+ * Only when the window left clearings out but every one of them finished in
+ * or after the first in-window block — the extra rows sat in a catch-up
+ * block — so an older one, if any, was not fetched. Otherwise the opening
+ * (or its absence) is already known and nothing more is read.
+ */
+export function needsClearingBeforeBlock(
+    before: readonly Clearing[],
+    opening: Clearing | null,
+): boolean {
+    return opening === null && before.length > 0;
+}
+
+/**
+ * The newest finished clearing in a block below `blockLt`, by block: the
+ * opening when every clearing the window left out shares its first block.
+ * ONE extra request for one row, no snapshot. Clearings that share that
+ * older block share its time and balance, so which one comes back does not
+ * change the value.
+ */
+export const poolTvlClearingBeforeBlockQuery = gql`
+    query PoolTvlClearingBeforeBlock($pool: String!, $blockLt: BigInt!) {
+        clearings: lendingPoolClearings(
+            first: 1
+            orderBy: endBlockNumber
+            orderDirection: desc
+            where: {
+                lendingPool: $pool
+                isFinished: true
+                endBlockNumber_lt: $blockLt
+            }
+        ) {
+            epochId
+            endBlockNumber
+            endTimestamp
+        }
+    }
+`;
+
+export async function fetchClearingBeforeBlock(
+    request: GraphRequest,
+    poolId: string,
+    blockLt: number,
+    cancellation: Cancellation,
+): Promise<Clearing | null> {
+    cancellation.throwIfCancelled();
+    const page = await request<{ clearings: ClearingRow[] }>(
+        poolTvlClearingBeforeBlockQuery,
+        { pool: poolId, blockLt: String(blockLt) },
+        cancellation.signal,
+    );
+    const row = page.clearings.at(0);
+    return row === undefined ? null : parseClearing(row);
+}
+
+/**
+ * The newest finished clearing numbered below `beforeEpoch`: the opening
+ * candidate of a `fromEpoch` window, whose own fetch never reads that far
+ * back. ONE extra request for one row, no snapshot.
+ */
+export async function fetchClearingBefore(
+    request: GraphRequest,
+    poolId: string,
+    beforeEpoch: number,
+    cancellation: Cancellation,
+): Promise<Clearing | null> {
+    cancellation.throwIfCancelled();
+    const page = await request<PoolTvlClearingsResult>(
+        poolTvlClearingsQuery,
+        {
+            poolId,
+            pool: poolId,
+            epochGte: '0',
+            epochLt: String(beforeEpoch),
+            direction: 'desc',
+            first: 1,
+            withSnapshot: false,
+        },
+        cancellation.signal,
+    );
+    const row = page.clearings.at(0);
+    return row === undefined ? null : parseClearing(row);
+}
+
 /**
  * The pool's balance (display units, the subgraph's decimal string) at the end
  * of each block, `TVL_HISTORY_BLOCKS_PER_REQUEST` blocks per request. A block