@kasufinance/kasu-sdk 2.11.0 → 2.13.0

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

@@ -1,18 +1,21 @@
 import { readItems, readSingleton } from '@directus/sdk';
 import { Provider } from '@ethersproject/abstract-provider';
-import { Signer } from 'ethers';
-import { formatUnits } from 'ethers/lib/utils';
+import { BigNumber, providers, Signer } from 'ethers';
+import { formatUnits, isAddress } from 'ethers/lib/utils';
 import { GraphQLClient } from 'graphql-request';
 
 import {
+    ISystemVariablesAbi,
+    ISystemVariablesAbi__factory,
     KasuPoolExternalTVLAbi,
     KasuPoolExternalTVLAbi__factory,
 } from '../../contracts';
+import { poolTvl, PoolTvlHistoryEntry } from '../../domain/pool-tvl';
 import { epochRateToApy } from '../../domain/rates';
 import { SdkConfig } from '../../sdk-config';
 import { getSystemVariablesQuery } from '../Locking/queries';
 import { SystemVariables } from '../Locking/types';
-import { filterArray } from '../shared';
+import { filterArray, isEmptyHistoryError } from '../shared';
 
 import {
     createDirectusClient,
@@ -44,6 +47,26 @@ import {
     TrancheConfigurationSubgraphResult,
     TrancheSubgraphResult,
 } from './subgraph-types';
+import {
+    buildPoolTvlHistory,
+    Cancellation,
+    ClearingsScope,
+    createOffChainTvlReader,
+    distinctBlocks,
+    fetchOffChainTvlAtBlocks,
+    fetchPoolBalancesAtBlocks,
+    fetchPoolClearings,
+    GraphRequest,
+    OffChainTvlReader,
+    PastBlockCache,
+    PoolTvlHistoryOptions,
+    resolvePoolTvlHistoryWindow,
+    runCancellable,
+    TVL_HISTORY_CACHE_DEPTH,
+    TVL_HISTORY_DEFAULT_TIMEOUT_MS,
+    TVL_HISTORY_RPC_TIMEOUT_MS,
+    validatePoolTvlHistoryOptions,
+} from './tvl-history';
 import {
     BadAndDoubtfulDebts,
     FinancialReportingDocuments,
@@ -58,21 +81,44 @@ import {
     TrancheData,
 } from './types';
 
+/** Thrown by `getPoolTvlHistory` when no provider that serves past state is configured. */
+export const NO_HISTORY_PROVIDER_MESSAGE =
+    'getPoolTvlHistory: no history provider; pass historyProvider or set historyRpcUrls to RPCs that serve past state';
+
 export class DataService {
     private readonly _graph: GraphQLClient;
     private readonly _externalTvlAbi: KasuPoolExternalTVLAbi;
+    private readonly _systemVariablesAbi: ISystemVariablesAbi;
     private readonly _directus: KasuDirectusClient;
     private _directusPoolOverview: PoolOverviewDirectus[] | undefined;
+    private readonly _explicitHistoryProvider: Provider | undefined;
+    private _builtHistoryProviders: Provider[] | undefined;
+    /** Immutable past-block reads, kept for the life of this instance. */
+    private readonly _tvlHistoryCache = new PastBlockCache();
 
+    /**
+     * @param historyProvider - a provider that SERVES PAST STATE (an archive
+     * RPC), used only by `getPoolTvlHistory` for the off-chain TVL at old
+     * blocks. Without one, providers are built on `SdkConfig.historyRpcUrls`
+     * (tried in order); with neither, that one call throws
+     * `NO_HISTORY_PROVIDER_MESSAGE`. Never the default provider: a pruned
+     * node refuses old blocks.
+     */
     constructor(
         private _kasuConfig: SdkConfig,
         signerOrProvider: Signer | Provider,
+        historyProvider?: Provider,
     ) {
         this._externalTvlAbi = KasuPoolExternalTVLAbi__factory.connect(
             _kasuConfig.contracts.ExternalTVL,
             signerOrProvider,
         );
+        this._systemVariablesAbi = ISystemVariablesAbi__factory.connect(
+            _kasuConfig.contracts.SystemVariables,
+            signerOrProvider,
+        );
         this._graph = new GraphQLClient(_kasuConfig.subgraphUrl);
+        this._explicitHistoryProvider = historyProvider;
 
         this._directus = createDirectusClient(_kasuConfig.directusUrl);
     }
@@ -196,6 +242,249 @@ export class DataService {
         return tvlMap;
     }
 
+    /**
+     * The pool's TVL — the total lent into it by everyone — at every cycle
+     * boundary, then as of now: the data behind a TVL chart.
+     *
+     * One `clearing` point per FINISHED clearing, read at the block it
+     * finished in (`LendingPoolClearing.endBlockNumber`), then one `current`
+     * point. Every point is `poolTvl(onChain, offChain)`, the definition
+     * `getPoolOverview` uses for `totalValueLocked.total`:
+     *
+     * - on-chain: `lendingPool.balance` from the subgraph, read with
+     *   time-travel queries (`block: { number }`);
+     * - off-chain: `ExternalTVL.externalTVLOfPool(pool)` at the same block,
+     *   through the HISTORY providers (see the constructor). 0 before the
+     *   contract was deployed (decided by `getCode`, and only if the same
+     *   provider shows the pool's own code there); any failed read throws.
+     *
+     * The `current` point mixes two sources: the subgraph's latest balance
+     * (and its latest block time) and `externalTVLOfPool` at `latest` on the
+     * history provider. `getPoolOverview` reads the same two, the off-chain
+     * one on the default provider, so the last point equals
+     * `totalValueLocked.total` when both reads succeed. They can differ when
+     * `getPoolOverview`'s off-chain read FAILS — it then falls back to 0 —
+     * or when the figure moves between the two calls.
+     *
+     * Units: `tvl` in display units of the deployment's own stable token
+     * (USDC on Base and XDC USDC, AUDD on XDC AUDD); `timestamp` in unix
+     * seconds. Ascending in time. See `PoolTvlHistoryEntry`.
+     *
+     * Cost: one subgraph request for the clearings (per thousand), one per
+     * hundred distinct uncached clearing blocks, a `currentEpochNumber` read;
+     * then, on the history providers, one `externalTVLOfPool` per distinct
+     * uncached block plus the latest, and one to about log2(n) `getCode`s —
+     * at most `TVL_HISTORY_RPC_CONCURRENCY` in flight. Final blocks are
+     * cached on this instance, so a second call reads only what is new.
+     * `timeoutMs` (default 30 s) bounds the whole call.
+     *
+     * `[]` for a pool the subgraph does not know, for a window with no epoch
+     * in it, and on a LITE deployment whose subgraph lacks the entities. On a
+     * full deployment that schema error throws, like every network, indexing
+     * or past-state failure.
+     *
+     * @throws RangeError / TypeError on a malformed option or a pool id that
+     * is not an address, and `NO_HISTORY_PROVIDER_MESSAGE` when the
+     * deployment has an `ExternalTVL` contract but no history provider — all
+     * before any network read. `PoolTvlHistoryTimeoutError` /
+     * `PoolTvlHistoryAbortedError` on the deadline or the signal,
+     * `PastStateUnavailableError` from a pruned history provider.
+     */
+    async getPoolTvlHistory(
+        poolId: string,
+        options: PoolTvlHistoryOptions = {},
+    ): Promise<PoolTvlHistoryEntry[]> {
+        validatePoolTvlHistoryOptions(options);
+        if (!isAddress(poolId)) {
+            throw new TypeError(
+                `getPoolTvlHistory: poolId must be an address, got ${String(poolId)}`,
+            );
+        }
+        const pool = poolId.toLowerCase();
+        const externalTvl = this._externalTvlAddress();
+        const rpcs = externalTvl ? this._historyRpcs() : [];
+        if (externalTvl && rpcs.length === 0) {
+            throw new Error(NO_HISTORY_PROVIDER_MESSAGE);
+        }
+
+        return await runCancellable(
+            options.timeoutMs ?? TVL_HISTORY_DEFAULT_TIMEOUT_MS,
+            options.signal,
+            (cancellation) =>
+                this._readPoolTvlHistory(
+                    pool,
+                    options,
+                    externalTvl
+                        ? this._createOffChainTvlReader({
+                              externalTvl,
+                              pool,
+                              rpcs,
+                              cancellation,
+                          })
+                        : null,
+                    externalTvl ?? '',
+                    cancellation,
+                ),
+        );
+    }
+
+    private async _readPoolTvlHistory(
+        pool: string,
+        options: PoolTvlHistoryOptions,
+        reader: OffChainTvlReader | null,
+        externalTvl: string,
+        cancellation: Cancellation,
+    ): Promise<PoolTvlHistoryEntry[]> {
+        const graph: GraphRequest = <T>(
+            document: string,
+            variables: Record<string, unknown>,
+            signal?: AbortSignal,
+        ): Promise<T> =>
+            this._graph.request<T>({ document, variables, signal });
+        const scope: ClearingsScope =
+            options.fromEpoch === undefined && options.count !== undefined
+                ? { kind: 'newest', count: options.count }
+                : { kind: 'from', fromEpoch: options.fromEpoch ?? 0 };
+
+        try {
+            const [currentEpochNumber, { clearings, snapshot }] =
+                await Promise.all([
+                    this._systemVariablesAbi.currentEpochNumber(),
+                    fetchPoolClearings(graph, pool, scope, cancellation),
+                ]);
+            const currentEpoch = currentEpochNumber.toNumber();
+
+            const window = resolvePoolTvlHistoryWindow(options, currentEpoch);
+            const poolNow = snapshot.pool;
+            if (!window || !poolNow) return [];
+            const head = snapshot.meta?.block;
+            if (!head || typeof head.timestamp !== 'number') {
+                throw new Error(
+                    'getPoolTvlHistory: the subgraph returned no latest block time',
+                );
+            }
+
+            const inWindow = clearings.filter(
+                (c) =>
+                    c.epochId >= window.fromEpoch &&
+                    c.epochId <= window.toEpoch,
+            );
+            const blocks = distinctBlocks(inWindow);
+            const withCurrent = window.toEpoch >= currentEpoch;
+            const cacheable = (block: number): boolean =>
+                block <= head.number - TVL_HISTORY_CACHE_DEPTH;
+
+            const [balances, offChainRead] = await Promise.all([
+                this._balancesAtBlocks(graph, pool, blocks, cacheable, cancellation),
+                reader
+                    ? fetchOffChainTvlAtBlocks(reader, blocks, {
+                          withLatest: withCurrent,
+                          cancellation,
+                          cache: this._tvlHistoryCache,
+                          cacheKey: (kind, block) =>
+                              `${kind}|${externalTvl}|${pool}|${String(block)}`,
+                          cacheable,
+                      })
+                    : {
+                          offChain: new Map(
+                              blocks.map((b) => [b, BigNumber.from(0)]),
+                          ),
+                          latest: null,
+                      },
+            ]);
+
+            return buildPoolTvlHistory({
+                clearings: inWindow,
+                balances,
+                offChain: offChainRead.offChain,
+                current: withCurrent
+                    ? {
+                          epochId: currentEpoch,
+                          timestamp: head.timestamp,
+                          balance: poolNow.balance,
+                          offChain: offChainRead.latest ?? BigNumber.from(0),
+                      }
+                    : null,
+                decimals: this._kasuConfig.stableAssetDecimals,
+            });
+        } catch (error) {
+            if (isEmptyHistoryError(error, this._kasuConfig.isLiteDeployment)) {
+                return [];
+            }
+            throw error;
+        }
+    }
+
+    /** The pool's balance at each block: cached final blocks, then one batch. */
+    private async _balancesAtBlocks(
+        graph: GraphRequest,
+        pool: string,
+        blocks: readonly number[],
+        cacheable: (block: number) => boolean,
+        cancellation: Cancellation,
+    ): Promise<Map<number, string>> {
+        const key = (block: number): string =>
+            `balance|${this._kasuConfig.subgraphUrl}|${pool}|${String(block)}`;
+        const balances = new Map<number, string>();
+        const missing: number[] = [];
+        for (const block of blocks) {
+            const hit = cacheable(block)
+                ? this._tvlHistoryCache.get<string>(key(block))
+                : undefined;
+            if (hit === undefined) missing.push(block);
+            else balances.set(block, hit);
+        }
+        if (missing.length > 0) {
+            const read = await fetchPoolBalancesAtBlocks(
+                graph,
+                pool,
+                missing,
+                cancellation,
+            );
+            for (const [block, balance] of read.balances) {
+                balances.set(block, balance);
+                if (cacheable(block)) this._tvlHistoryCache.set(key(block), balance);
+            }
+        }
+        return balances;
+    }
+
+    /** `null` when the deployment has no `ExternalTVL` contract. */
+    private _externalTvlAddress(): string | null {
+        const address = this._kasuConfig.contracts.ExternalTVL;
+        if (!address || /^0x0{40}$/i.test(address)) return null;
+        return address.toLowerCase();
+    }
+
+    /** Seam for tests: the real reader over the history RPCs. */
+    private _createOffChainTvlReader(
+        args: Parameters<typeof createOffChainTvlReader>[0],
+    ): OffChainTvlReader {
+        return createOffChainTvlReader(args);
+    }
+
+    /**
+     * The history RPCs, in fallback order: the explicit provider, else ONE
+     * provider per `historyRpcUrls` entry — built here and nowhere else,
+     * pinned to `SdkConfig.chainId` when known, each with a per-call timeout.
+     * Built once per instance.
+     */
+    private _historyRpcs(): Provider[] {
+        if (this._explicitHistoryProvider) return [this._explicitHistoryProvider];
+        if (!this._builtHistoryProviders) {
+            // Through the `ethers` namespace, so the consumer's own build
+            // (Node or browser) is used — see `defaultProvider` in the facade.
+            this._builtHistoryProviders = this._kasuConfig.historyRpcUrls.map(
+                (url) =>
+                    new providers.StaticJsonRpcProvider(
+                        { url, timeout: TVL_HISTORY_RPC_TIMEOUT_MS },
+                        this._kasuConfig.chainId,
+                    ),
+            );
+        }
+        return this._builtHistoryProviders;
+    }
+
     async getPoolOverview(
         epochId: string,
         id_in?: string[],
@@ -436,9 +725,10 @@ export class DataService {
                 subheading: lendingPoolDirectus?.subheading,
                 operatingSince: lendingPoolDirectus?.operatingSince,
                 totalValueLocked: {
-                    total: (
-                        parseFloat(lendingPoolSubgraph.balance) +
-                        parseFloat(offChainTvl)
+                    // The one TVL definition, shared with getPoolTvlHistory.
+                    total: poolTvl(
+                        lendingPoolSubgraph.balance,
+                        offChainTvl,
                     ).toString(),
                     offchain: offChainTvl,
                 },