@kasufinance/kasu-sdk 2.13.1 → 2.14.0

package/src/facade/strategies.ts

@@ -2,7 +2,10 @@ import { PoolTvlHistoryEntry } from '../domain/pool-tvl';
 import { selectVisiblePools } from '../domain/pools';
 import { pickShortDescription } from '../domain/strategy-summary';
 import { DataService } from '../services/DataService/data-service';
-import { PoolTvlHistoryOptions } from '../services/DataService/tvl-history';
+import {
+    PoolTvlHistoryOptions,
+    PoolTvlHistoryResult,
+} from '../services/DataService/tvl-history';
 import {
     PoolDelegateProfileAndHistory,
     PoolOverview,
@@ -175,6 +178,28 @@ export class StrategiesFacade {
         return await this._dataService.getPoolTvlHistory(poolId, options);
     }
 
+    /**
+     * `getPoolTvlHistory` plus `opening` — the newest clearing before the
+     * window, read at its own block like every other point, or `null` when
+     * the pool has none — from the same read. Pass the result to
+     * `combineTvlHistories` as a leg with its `usdRate`: the opening is what
+     * the leg held before its first point, so a window cut at a different
+     * time on another chain does not count it 0. Same options and errors as
+     * `getPoolTvlHistory`; the extra cost is one clearing row (or, for
+     * `fromEpoch`, one small request) and one block.
+     *
+     * ```ts
+     * const leg = await kasu.strategies.getPoolTvlHistoryWindow(poolId, { count: 52 });
+     * // { entries: PoolTvlHistoryEntry[], opening: PoolTvlHistoryEntry | null }
+     * ```
+     */
+    async getPoolTvlHistoryWindow(
+        poolId: string,
+        options: PoolTvlHistoryOptions = {},
+    ): Promise<PoolTvlHistoryResult> {
+        return await this._dataService.getPoolTvlHistoryWindow(poolId, options);
+    }
+
     /**
      * Fetch a single strategy by pool ID. Returns `null` if not found.
      */

package/src/facade/strategy-deployments.ts

@@ -0,0 +1,161 @@
+import { CHAIN_CONFIGS } from './chain-configs';
+import { ChainConfigEntry, SupportedChain } from './types';
+
+/**
+ * Strategy ↔ deployment resolution. A lending strategy is not tied to one
+ * deployment: Tax Pay runs as one pool on Base (USDC) and another on XDC
+ * (AUDD), and the two share one CMS record keyed by the BASE pool id — the
+ * canonical id. Each chain config's `poolMetadataMapping` maps its
+ * chain-local ids to canonical ones; Base, being canonical, has none.
+ *
+ * Pure: it reads only the built-in `CHAIN_CONFIGS`. The same rules as
+ * kasu-ui's counterpart lookup, so both apps sum a strategy over the same
+ * pools.
+ */
+
+/** The pool that represents a strategy on one deployment. */
+export interface StrategyDeployment {
+    chain: SupportedChain;
+    /**
+     * Chain-local pool id, lowercase — what that chain's subgraph is keyed
+     * by.
+     */
+    poolId: string;
+}
+
+/**
+ * What `strategyDeployments` refuses, as a code:
+ *
+ * - `pool-id` — not a `0x` address;
+ * - `chain` — not a `SupportedChain`;
+ * - `wrong-chain` — the mapping places the id on ANOTHER deployment (an XDC
+ *   chain-local id passed as Base, or a Base id passed as XDC). Querying one
+ *   chain with another's address reads nothing, silently.
+ */
+export type StrategyDeploymentInputErrorCode =
+    | 'pool-id'
+    | 'chain'
+    | 'wrong-chain';
+
+/** What `strategyDeployments` throws for an id it cannot place. */
+export class StrategyDeploymentInputError extends Error {
+    readonly code: StrategyDeploymentInputErrorCode;
+
+    constructor(code: StrategyDeploymentInputErrorCode) {
+        super(`strategyDeployments: input refused (${code})`);
+        this.name = 'StrategyDeploymentInputError';
+        this.code = code;
+        Object.setPrototypeOf(this, StrategyDeploymentInputError.prototype);
+    }
+}
+
+/** The canonical deployment: its pool ids ARE the strategies' ids. */
+const CANONICAL_CHAIN: SupportedChain = 'base';
+
+const ADDRESS_RE = /^0x[0-9a-f]{40}$/;
+
+type MappingConfigs = Readonly<
+    Record<SupportedChain, Pick<ChainConfigEntry, 'poolMetadataMapping'>>
+>;
+
+/** The deployment's mapping with both sides lowercased; Base never has one. */
+function mappingOf(
+    configs: MappingConfigs,
+    chain: SupportedChain,
+): [string, string][] {
+    if (chain === CANONICAL_CHAIN) return [];
+    return Object.entries(configs[chain].poolMetadataMapping ?? {}).map(
+        ([local, canonical]) => [local.toLowerCase(), canonical.toLowerCase()],
+    );
+}
+
+/**
+ * `strategyDeployments` over any configs — the export reads `CHAIN_CONFIGS`;
+ * the spec passes its own to cover shapes the built-in mapping lacks.
+ */
+export function resolveStrategyDeployments(
+    configs: MappingConfigs,
+    poolId: string,
+    chain: SupportedChain,
+): StrategyDeployment[] {
+    const id = typeof poolId === 'string' ? poolId.trim().toLowerCase() : '';
+    if (!ADDRESS_RE.test(id)) {
+        throw new StrategyDeploymentInputError('pool-id');
+    }
+    if (
+        typeof chain !== 'string' ||
+        !Object.prototype.hasOwnProperty.call(configs, chain)
+    ) {
+        throw new StrategyDeploymentInputError('chain');
+    }
+    const chains = Object.keys(configs) as SupportedChain[];
+    const mappings = chains.map((c) => [c, mappingOf(configs, c)] as const);
+    const isLocalElsewhere = mappings.some(
+        ([c, mapping]) =>
+            c !== chain && mapping.some(([local]) => local === id),
+    );
+
+    let canonical: string;
+    if (chain === CANONICAL_CHAIN) {
+        // A Base id is its own Base pool — unless the mapping says it is
+        // another deployment's chain-local id, which names no Base pool.
+        if (isLocalElsewhere) {
+            throw new StrategyDeploymentInputError('wrong-chain');
+        }
+        canonical = id;
+    } else {
+        const own = mappingOf(configs, chain).find(([local]) => local === id);
+        if (own) {
+            canonical = own[1];
+        } else {
+            const isCanonical = mappings.some(([, mapping]) =>
+                mapping.some(([, target]) => target === id),
+            );
+            if (isLocalElsewhere || isCanonical) {
+                throw new StrategyDeploymentInputError('wrong-chain');
+            }
+            // Unmapped off Base: a strategy of one on its own chain (every
+            // XDC USDC pool today). Claiming a Base counterpart would read
+            // Base with an XDC address.
+            return [{ chain, poolId: id }];
+        }
+    }
+
+    const found: StrategyDeployment[] = [
+        { chain: CANONICAL_CHAIN, poolId: canonical },
+    ];
+    for (const [c, mapping] of mappings) {
+        for (const [local, target] of mapping) {
+            if (target === canonical) found.push({ chain: c, poolId: local });
+        }
+    }
+    return found;
+}
+
+/**
+ * Every deployment a strategy has a pool on, canonical (Base) first, then the
+ * others in `CHAIN_CONFIGS` order — the legs to fetch and pass to
+ * `combineTvlHistories`. One entry for a strategy that lives on one chain
+ * only (PayFi, on Base).
+ *
+ * `chain` is the deployment `poolId` was read on — required, because an
+ * address alone does not say which chain it belongs to. From either side of
+ * a mapping the answer is the same set: Tax Pay's Base id on `'base'` and
+ * its XDC id on `'xdc'` both return both pools. An id the mapping does not
+ * know is a strategy of one on its own chain. Ids are compared
+ * case-insensitively and returned lowercase.
+ *
+ * Throws `StrategyDeploymentInputError` for a malformed id, an unknown chain,
+ * or an id the mapping places on another deployment (`'wrong-chain'`).
+ *
+ * ```ts
+ * strategyDeployments(strategy.id, 'base');
+ * // [{ chain: 'base', poolId: '0x…' }, { chain: 'xdc', poolId: '0x…' }]
+ * ```
+ */
+export function strategyDeployments(
+    poolId: string,
+    chain: SupportedChain,
+): StrategyDeployment[] {
+    return resolveStrategyDeployments(CHAIN_CONFIGS, poolId, chain);
+}

package/src/index.ts

@@ -45,7 +45,10 @@ export type {
 
 export type { YieldHistoryOptions } from './services/Portfolio/yield-history';
 
-export type { PoolTvlHistoryOptions } from './services/DataService/tvl-history';
+export type {
+    PoolTvlHistoryOptions,
+    PoolTvlHistoryResult,
+} from './services/DataService/tvl-history';
 export {
     PastStateUnavailableError,
     PoolTvlHistoryAbortedError,

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