@kasufinance/kasu-sdk 2.13.0 → 2.14.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

package/src/services/UserLending/queries.ts

@@ -160,14 +160,13 @@ export const currentEpochFtdAmountQuery = gql`
                 user: $userId
                 lendingPool_in: $poolIds
                 epochId: $currentEpoch
+                type: DepositRequest
             }
         ) {
             fixedTermConfigId
             amountRequested
             tranche {
                 id
-                balance
-                shares
             }
         }
     }
@@ -183,11 +182,7 @@ export const currentFtdBalanceQuery = gql`
                 configId
                 lendingPoolTranche {
                     id
-                }
-            }
-            lendingPool {
-                balance
-                tranches {
+                    balance
                     shares
                 }
             }

package/src/services/UserLending/subgraph-types.ts

@@ -77,8 +77,6 @@ export interface CurrentEpochFtdAmountSubgraph {
         amountRequested: string;
         tranche: {
             id: string;
-            balance: string;
-            shares: string;
         };
     }[];
 }
@@ -161,13 +159,9 @@ export interface CurrentFtdBalanceSubgraph {
             configId: string;
             lendingPoolTranche: {
                 id: string;
-            };
-        };
-        lendingPool: {
-            balance: string;
-            tranches: {
+                balance: string;
                 shares: string;
-            }[];
+            };
         };
     }[];
 }

package/src/services/UserLending/types.ts

@@ -39,8 +39,18 @@ export interface UserRequest {
     requestType: 'Deposit' | 'Withdrawal';
     trancheId: string;
     trancheName: string;
+    /**
+     * The amount still OUTSTANDING on the request, in assets (the
+     * deployment's stable token, display units) — not the amount first asked
+     * for: the subgraph takes accepted and rejected amounts off it, and a
+     * cancellation zeroes it. A deposit's figure is the asset amount as the
+     * subgraph holds it (top-ups included); a withdrawal's is its remaining
+     * tranche shares at the tranche's current share price.
+     */
     requestedAmount: string;
+    /** Assets accepted so far — deposited, or paid out for a withdrawal. */
     acceptedAmount: string;
+    /** Assets rejected and returned — deposits only; 0 for a withdrawal. */
     rejectedAmount: string;
     timestamp: EpochTimeStamp;
     status: UserRequestStatus;

package/src/services/UserLending/user-lending.ts

@@ -8,13 +8,7 @@ import {
     ethers,
     Signer,
 } from 'ethers';
-import {
-    defaultAbiCoder,
-    formatEther,
-    formatUnits,
-    parseEther,
-    parseUnits,
-} from 'ethers/lib/utils';
+import { defaultAbiCoder, formatUnits, parseUnits } from 'ethers/lib/utils';
 import { GraphQLClient } from 'graphql-request';
 
 import {
@@ -70,6 +64,20 @@ import {
     UserTrancheBalance,
 } from './types';
 
+/** Thrown when the subgraph reports a request type with no known unit. */
+export const UNKNOWN_REQUEST_TYPE_MESSAGE =
+    'UserLending: unknown request type, its amount unit is unknown';
+
+const KNOWN_REQUEST_TYPES: readonly string[] = [
+    'DepositRequest',
+    'WithdrawalRequest',
+];
+
+const isKnownRequestType = (
+    type: unknown,
+): type is UserRequestsSubgraph['userRequests'][number]['type'] =>
+    typeof type === 'string' && KNOWN_REQUEST_TYPES.includes(type);
+
 export class UserLending {
     private readonly _graph: GraphQLClient;
 
@@ -406,6 +414,17 @@ export class UserLending {
         const retn: UserRequest[] = [];
 
         for (const userRequest of subgraphResult.userRequests) {
+            // A request type this SDK does not know has no known amount unit
+            // (the schema also declares types no live deployment emits yet).
+            // Skip that ONE row before anything is priced or read on chain,
+            // rather than failing — and blanking — the lender's whole list.
+            if (!isKnownRequestType(userRequest.type)) {
+                console.error(
+                    `${UNKNOWN_REQUEST_TYPE_MESSAGE}: ${String(userRequest.type)} (request ${userRequest.id}); row skipped`,
+                );
+                continue;
+            }
+
             const directusPool = directusResult.find(
                 ({ id }) => id === userRequest.lendingPool.id,
             );
@@ -552,13 +571,7 @@ export class UserLending {
                         : 'Withdrawal',
                 trancheName: trancheName,
                 trancheId: userRequest.tranche.id,
-                requestedAmount: parseUnits(userRequest.tranche.shares).isZero()
-                    ? userRequest.amountRequested
-                    : this.convertSharesToAssets(
-                          userRequest.amountRequested,
-                          userRequest.tranche.balance,
-                          userRequest.tranche.shares,
-                      ).toString(),
+                requestedAmount: this.requestedAmountInAssets(userRequest),
                 acceptedAmount: userRequest.amountAccepted,
                 rejectedAmount: userRequest.amountRejected,
                 status: userRequest.status,
@@ -606,15 +619,16 @@ export class UserLending {
             const trancheID =
                 userFTD.lendingPoolTrancheFixedTermConfig.lendingPoolTranche.id.toLowerCase();
 
-            const totalSupply = userFTD.lendingPool.tranches.reduce(
-                (total, cur) => total.add(parseEther(cur.shares)),
-                BigNumber.from(0),
-            );
+            // The lock holds shares of ONE tranche, so they are worth that
+            // tranche's share price — not the pool's average across tranches,
+            // which differs whenever the tranches have earned differently.
+            const lockTranche =
+                userFTD.lendingPoolTrancheFixedTermConfig.lendingPoolTranche;
 
             const amount = this.convertSharesToAssets(
                 userFTD.trancheShares,
-                userFTD.lendingPool.balance,
-                formatEther(totalSupply),
+                lockTranche.balance,
+                lockTranche.shares,
             );
 
             const item = trancheMap.get(trancheID) ?? [];
@@ -643,33 +657,43 @@ export class UserLending {
                 currentEpoch: parseFloat(currentEpoch),
             });
 
-        const currentEpochFtdAmounts = new Map<string, string[]>();
+        // Deposit requests only (the query filters on type): a deposit's
+        // `amountRequested` is already an ASSET amount, so it is summed as it
+        // is — never put through a share price. Summed, not assigned: a
+        // cancelled request and its replacement share a tranche and a config
+        // in one epoch, and the cancelled one's 0 must not overwrite the live
+        // amount.
+        const totals = new Map<string, Map<number, BigNumber>>();
 
         for (const userRequest of currentEpochFtdAmountRes.userRequests) {
             const ftdID = parseFloat(userRequest.fixedTermConfigId);
-
-            const item = currentEpochFtdAmounts.get(userRequest.tranche.id);
-
-            const amountRequested = this.convertSharesToAssets(
-                userRequest.amountRequested,
-                userRequest.tranche.balance,
-                userRequest.tranche.shares,
+            if (!Number.isInteger(ftdID) || ftdID < 0) continue;
+
+            const perConfig =
+                totals.get(userRequest.tranche.id) ??
+                new Map<number, BigNumber>();
+            perConfig.set(
+                ftdID,
+                (perConfig.get(ftdID) ?? BigNumber.from(0)).add(
+                    parseUnits(userRequest.amountRequested),
+                ),
             );
+            totals.set(userRequest.tranche.id, perConfig);
+        }
 
-            if (item) {
-                const clonedItem = [...item];
-
-                clonedItem[ftdID] = amountRequested;
-
-                currentEpochFtdAmounts.set(userRequest.tranche.id, clonedItem);
+        // A slot whose total is zero is left out — `'0.0'` is a truthy
+        // string, and a caller testing the slot would read it as an amount.
+        // A tranche with no non-zero slot is left out entirely.
+        const currentEpochFtdAmounts = new Map<string, string[]>();
 
-                continue;
-            }
+        for (const [trancheId, perConfig] of totals) {
             const ftdAmounts: string[] = [];
-
-            ftdAmounts[ftdID] = amountRequested;
-
-            currentEpochFtdAmounts.set(userRequest.tranche.id, ftdAmounts);
+            for (const [ftdID, total] of perConfig) {
+                if (total.gt(0)) ftdAmounts[ftdID] = formatUnits(total);
+            }
+            if (ftdAmounts.length) {
+                currentEpochFtdAmounts.set(trancheId, ftdAmounts);
+            }
         }
 
         return currentEpochFtdAmounts;
@@ -708,6 +732,40 @@ export class UserLending {
         return amountMap;
     }
 
+    /**
+     * A request's outstanding amount in ASSETS (the deployment's stable token).
+     *
+     * The subgraph's `UserRequest.amountRequested` is denominated by request
+     * type. A DEPOSIT request holds assets: the deposit NFT's `assetAmount`,
+     * top-ups added, accepted and rejected amounts taken off. A WITHDRAWAL
+     * request holds tranche SHARES: the withdrawal NFT's `sharesAmount`,
+     * accepted shares taken off. So only a withdrawal is converted, at the
+     * tranche's current share price; a deposit passes through unchanged —
+     * pricing it as shares overstated it by the share price.
+     */
+    private requestedAmountInAssets(
+        userRequest: UserRequestsSubgraph['userRequests'][number],
+    ): string {
+        switch (userRequest.type) {
+            case 'DepositRequest':
+                return userRequest.amountRequested;
+            case 'WithdrawalRequest':
+                return this.convertSharesToAssets(
+                    userRequest.amountRequested,
+                    userRequest.tranche.balance,
+                    userRequest.tranche.shares,
+                );
+            default: {
+                // Fail closed: a type this SDK does not know has no known
+                // unit, and pricing it either way would print a wrong figure.
+                const unknownType: string = userRequest.type;
+                throw new Error(
+                    `${UNKNOWN_REQUEST_TYPE_MESSAGE}: ${unknownType}`,
+                );
+            }
+        }
+    }
+
     convertSharesToAssets(
         sharesAmount: string,
         totalAssets: string,