@kasufinance/kasu-sdk 2.11.0 → 2.13.0

package/src/domain/yield-history.ts

@@ -0,0 +1,194 @@
+/**
+ * Settled interest per cycle (epoch): what a lender was credited at each close,
+ * per pool and tranche, and the one formula that turns a tranche's credited
+ * interest into one lender's share of it.
+ *
+ * **The figures are NET, and only net.** `LendingPool._applyTrancheInterest`
+ * takes the performance fee off first and emits `InterestApplied` with the
+ * lender side only (`interest × (1 − performanceFee)`); a fixed-term top-up
+ * (`_applyFixedRateInterests`) is net of the fee the same way. So the figure
+ * this module computes from those records IS what the lender was credited —
+ * never take the fee off it again. No gross is offered: the subgraph keeps
+ * only TODAY's fee, so a historical gross would be a guess.
+ *
+ * Units: amounts are display units of the DEPLOYMENT'S OWN stable token (USDC
+ * on Base and XDC USDC, AUDD on XDC AUDD) — never converted to USD here;
+ * shares are display units of tranche shares, as the subgraph's BigDecimals.
+ */
+
+/** One fixed-term lock inside a tranche position, at one epoch. */
+export interface EpochLockShares {
+    /**
+     * The lock earns in this epoch: it started BEFORE the epoch, ends at or
+     * after it, and the lender has a share snapshot for the tranche at it.
+     */
+    active: boolean;
+    /** The lock's tranche shares as of the epoch (latest update at or before it). */
+    sharesAtEpoch: number;
+    /** The lock's tranche shares as of the epoch BEFORE it. */
+    sharesBeforeEpoch: number;
+}
+
+/** Everything one lender's share of one tranche's credited interest needs. */
+export interface EpochTrancheYieldInput {
+    /** The tranche's interest credited at this epoch's close (net of the fee). */
+    epochInterest: number;
+    /** The lender's tranche shares as of the epoch (fixed-term locks included). */
+    userShares: number;
+    /** The tranche's total shares as of the epoch. */
+    trancheShares: number;
+    /**
+     * The tranche's CURRENT balance and shares: the price a fixed-term top-up
+     * (extra shares) is valued at. The subgraph keeps no per-epoch tranche
+     * balance, so an older top-up is valued at today's price — a second-order
+     * difference, because the top-up is only the fixed rate's excess over the
+     * variable one.
+     */
+    trancheBalanceNow: number;
+    trancheSharesNow: number;
+    locks: readonly EpochLockShares[];
+}
+
+export interface EpochTrancheYield {
+    /** `variable + Σ locks` — the lender's whole yield in the tranche. */
+    total: number;
+    /** The variable residual: the share-weighted base yield minus the locks' part of it. */
+    variable: number;
+    /** Each lock's yield, in the order of `input.locks`: its base part plus its top-up. */
+    locks: number[];
+}
+
+/**
+ * The ONE per-epoch formula. `Portfolio.getPortfolioLendingData` runs it for
+ * the last settled epoch and `getYieldHistory` for every epoch of a window, so
+ * the two figures cannot drift apart.
+ *
+ * ```
+ * base     = epochInterest × userShares / trancheShares
+ * lockBase = base × lock.sharesBeforeEpoch / userShares          (active locks)
+ * topUp    = (lock.sharesAtEpoch − lock.sharesBeforeEpoch) × trancheBalanceNow / trancheSharesNow
+ * variable = base − Σ lockBase
+ * total    = variable + Σ (lockBase + topUp)
+ * ```
+ *
+ * A zero denominator contributes 0 (a tranche or a lender with no shares
+ * earned nothing at that close), never `NaN`.
+ */
+export function epochTrancheYield(
+    input: EpochTrancheYieldInput,
+): EpochTrancheYield {
+    const base =
+        input.trancheShares === 0
+            ? 0
+            : (input.epochInterest * input.userShares) / input.trancheShares;
+
+    let variable = base;
+    const locks = input.locks.map((lock) => {
+        if (!lock.active) return 0;
+
+        const topUp =
+            input.trancheSharesNow === 0
+                ? 0
+                : ((lock.sharesAtEpoch - lock.sharesBeforeEpoch) *
+                      input.trancheBalanceNow) /
+                  input.trancheSharesNow;
+
+        const lockBase =
+            input.userShares === 0
+                ? 0
+                : (base * lock.sharesBeforeEpoch) / input.userShares;
+
+        variable -= lockBase;
+
+        return lockBase + topUp;
+    });
+
+    const total = locks.reduce((sum, lockYield) => sum + lockYield, variable);
+
+    return { total, variable, locks };
+}
+
+/** One lender's settled yield in one tranche at one epoch. */
+export interface YieldHistoryEntry {
+    /** The epoch (cycle) number, in the chain's numbering. */
+    epochId: number;
+    /**
+     * When the epoch ended — the next epoch's start — in unix SECONDS (not
+     * milliseconds).
+     */
+    epochEnd: number;
+    /** Lowercased lending pool address. */
+    poolId: string;
+    /** Lowercased tranche address. */
+    trancheId: string;
+    /**
+     * What the close credited the lender in this tranche, AFTER the
+     * performance fee, in display units of the deployment's own stable token
+     * (AUDD on XDC AUDD — convert before formatting it as USD).
+     */
+    netYield: number;
+}
+
+/** One epoch's yield summed over the entries an aggregation kept. */
+export interface YieldHistoryPoint {
+    /** The epoch (cycle) number. */
+    epochId: number;
+    /** The epoch's end, in unix SECONDS. */
+    epochEnd: number;
+    /** Net yield summed, in the deployment's own stable token. */
+    netYield: number;
+}
+
+export interface YieldHistoryFilter {
+    /** Keep only this pool (case-insensitive). */
+    poolId?: string;
+    /** Keep only this tranche (case-insensitive). */
+    trancheId?: string;
+}
+
+/**
+ * Pool/tranche entries → one point per epoch, ascending by `epochId`. With no
+ * filter it sums every strategy (the Lend tab's bars); with `poolId` it is one
+ * strategy (a strategy page's bars).
+ *
+ * An epoch appears only if a kept entry has it — there is no zero padding, so
+ * an empty input (a new lender) is an empty output.
+ *
+ * For a fixed-term lock holder the bars can sum to slightly MORE than the
+ * lender's lifetime interest (up to about 0.2 %): each top-up is valued at the
+ * tranche's CURRENT share price, which has grown since. Show "earned to date"
+ * from the lifetime figure, never from this sum.
+ */
+export function aggregateYieldHistory(
+    entries: readonly YieldHistoryEntry[],
+    filter: YieldHistoryFilter = {},
+): YieldHistoryPoint[] {
+    const poolId = filter.poolId?.toLowerCase();
+    const trancheId = filter.trancheId?.toLowerCase();
+    const byEpoch = new Map<number, YieldHistoryPoint>();
+
+    for (const entry of entries) {
+        if (poolId !== undefined && entry.poolId.toLowerCase() !== poolId) {
+            continue;
+        }
+        if (
+            trancheId !== undefined &&
+            entry.trancheId.toLowerCase() !== trancheId
+        ) {
+            continue;
+        }
+
+        const point = byEpoch.get(entry.epochId);
+        if (point) {
+            point.netYield += entry.netYield;
+            continue;
+        }
+        byEpoch.set(entry.epochId, {
+            epochId: entry.epochId,
+            epochEnd: entry.epochEnd,
+            netYield: entry.netYield,
+        });
+    }
+
+    return [...byEpoch.values()].sort((a, b) => a.epochId - b.epochId);
+}

package/src/facade/chain-configs.ts

@@ -15,6 +15,29 @@ const XDC_RPC_URLS: string[] = [
     'https://rpc.primenumbers.xyz/',
 ];
 
+/**
+ * XDC RPCs that serve PAST state, for `getPoolTvlHistory` (each verified
+ * with `externalTVLOfPool` at old blocks, CORS `*`), in fallback order. Not
+ * `rpc.xdcrpc.com`, which refuses older blocks, and never `rpc.xdc.org` /
+ * `erpc.xdc.org`. Public and rate-limited.
+ */
+const XDC_HISTORY_RPC_URLS: string[] = [
+    'https://rpc.primenumbers.xyz/',
+    'https://rpc.ankr.com/xdc',
+];
+
+/**
+ * Base RPCs that serve PAST state, in fallback order (each verified with
+ * `externalTVLOfPool` at old blocks; all answer CORS). Not
+ * `base-rpc.publicnode.com`, the default read RPC, which refuses old state.
+ * Public and rate-limited.
+ */
+const BASE_HISTORY_RPC_URLS: string[] = [
+    'https://mainnet.base.org',
+    'https://base.drpc.org',
+    'https://1rpc.io/base',
+];
+
 /**
  * Built-in chain configurations for Kasu-supported networks.
  *
@@ -59,6 +82,7 @@ export const CHAIN_CONFIGS: Record<'base' | 'xdc' | 'xdc-usdc' | 'plume', ChainC
             'https://base-rpc.publicnode.com',
             'https://mainnet.base.org',
         ],
+        historyRpcUrls: BASE_HISTORY_RPC_URLS,
         blockExplorerUrl: 'https://basescan.org',
     },
 
@@ -100,6 +124,7 @@ export const CHAIN_CONFIGS: Record<'base' | 'xdc' | 'xdc-usdc' | 'plume', ChainC
             currencyCode: 'AUD',
         },
         rpcUrls: XDC_RPC_URLS,
+        historyRpcUrls: XDC_HISTORY_RPC_URLS,
         blockExplorerUrl: 'https://xdcscan.com',
     },
 
@@ -134,6 +159,7 @@ export const CHAIN_CONFIGS: Record<'base' | 'xdc' | 'xdc-usdc' | 'plume', ChainC
             currencyCode: 'USD',
         },
         rpcUrls: XDC_RPC_URLS,
+        historyRpcUrls: XDC_HISTORY_RPC_URLS,
         blockExplorerUrl: 'https://xdcscan.com',
     },
 

package/src/facade/kasu.ts

@@ -65,17 +65,21 @@ export class Kasu {
      * of pools than the read-only one it came from.
      */
     private readonly _configOverrides: Partial<SdkConfigOptions>;
+    /** The caller's own history provider, kept so `connect` keeps it too. */
+    private readonly _historyProvider: Provider | undefined;
 
     private constructor(
         sdk: KasuSdk,
         chainConfig: ChainConfigEntry,
         signerOrProvider: Provider | Signer,
         configOverrides: Partial<SdkConfigOptions>,
+        historyProvider: Provider | undefined,
     ) {
         this._sdk = sdk;
         this._chainConfig = chainConfig;
         this._signerOrProvider = signerOrProvider;
         this._configOverrides = configOverrides;
+        this._historyProvider = historyProvider;
 
         this.strategies = new StrategiesFacade(
             sdk.DataService,
@@ -168,6 +172,9 @@ export class Kasu {
             stableAssetDecimals:
                 overrides.stableAssetDecimals ??
                 stableAssetOf(chainConfig)?.decimals,
+            historyRpcUrls:
+                overrides.historyRpcUrls ?? chainConfig.historyRpcUrls,
+            chainId: overrides.chainId ?? chainConfig.chainId,
         });
 
         const signerOrProvider =
@@ -179,8 +186,18 @@ export class Kasu {
                     : chainConfig.name,
             );
 
-        const sdk = new KasuSdk(sdkConfig, signerOrProvider);
-        return new Kasu(sdk, chainConfig, signerOrProvider, overrides);
+        // An explicit history provider wins; otherwise DataService builds
+        // them from `historyRpcUrls`, pinned to `chainId` (the one place).
+        const sdk = new KasuSdk(sdkConfig, signerOrProvider, {
+            historyProvider: options.historyProvider,
+        });
+        return new Kasu(
+            sdk,
+            chainConfig,
+            signerOrProvider,
+            overrides,
+            options.historyProvider,
+        );
     }
 
     /**
@@ -201,6 +218,7 @@ export class Kasu {
             chain: this._chainConfig,
             signerOrProvider: signer,
             configOverrides: this._configOverrides,
+            historyProvider: this._historyProvider,
         });
     }
 

package/src/facade/strategies.ts

@@ -1,6 +1,8 @@
+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 {
     PoolDelegateProfileAndHistory,
     PoolOverview,
@@ -149,6 +151,30 @@ export class StrategiesFacade {
         return await this._dataService.getPerformanceFee();
     }
 
+    /**
+     * The strategy's TVL (total lent by everyone) at every cycle boundary,
+     * then as of now — the data behind a TVL chart. Ascending in time; the
+     * last point (`kind: 'current'`) equals `strategy.tvl.total` when both
+     * calls' reads succeed (see `PoolTvlHistoryEntry`).
+     *
+     * `tvl` is in display units of the deployment's OWN stable token (USDC on
+     * Base and XDC USDC, AUDD on XDC AUDD); `timestamp` is unix SECONDS.
+     * `{ count }` = the newest `count` epochs, `{ fromEpoch }` = from that
+     * epoch on; `timeoutMs` (default 30 s) and `signal` bound the call. A
+     * malformed option throws before any network read. See
+     * `DataService.getPoolTvlHistory` for the reads, the cost and the errors.
+     *
+     * ```ts
+     * const points = await kasu.strategies.getPoolTvlHistory(poolId, { count: 52 });
+     * ```
+     */
+    async getPoolTvlHistory(
+        poolId: string,
+        options: PoolTvlHistoryOptions = {},
+    ): Promise<PoolTvlHistoryEntry[]> {
+        return await this._dataService.getPoolTvlHistory(poolId, options);
+    }
+
     /**
      * Fetch a single strategy by pool ID. Returns `null` if not found.
      */

package/src/facade/types.ts

@@ -70,6 +70,16 @@ export interface ChainConfigEntry {
      * Empty on a retired deployment, which has no read-only default.
      */
     rpcUrls: string[];
+    /**
+     * RPCs that SERVE PAST STATE (archive nodes), tried IN ORDER on failure,
+     * used only by `getPoolTvlHistory` to read the off-chain TVL at old
+     * blocks. Pruned nodes refuse those reads — some answer as if the call
+     * reverted — so these are never `rpcUrls[0]` by assumption. Public and
+     * RATE-LIMITED: an integrator should pass its own archive
+     * `KasuOptions.historyProvider`, which wins over them. Absent on a
+     * retired deployment.
+     */
+    historyRpcUrls?: string[];
     /**
      * Origin of the chain's block explorer, `https://…` with NO trailing
      * slash (`https://basescan.org`). Never append a path to it by hand: build
@@ -101,6 +111,16 @@ export interface KasuOptions {
         | import('@ethersproject/providers').Provider;
     /** Override any default config value. */
     configOverrides?: Partial<SdkConfigOptions>;
+    /**
+     * A provider that SERVES PAST STATE (an archive RPC), for
+     * `kasu.strategies.getPoolTvlHistory`. OPTIONAL: without one, the SDK
+     * builds one `StaticJsonRpcProvider` per
+     * `configOverrides.historyRpcUrls ?? chainConfig.historyRpcUrls` entry
+     * (tried in order, 10 s per call). The built-in URLs are public and
+     * rate-limited, so pass your own archive provider in production. Kept
+     * across `connect(signer)`.
+     */
+    historyProvider?: import('@ethersproject/providers').Provider;
 }
 
 // ---------------------------------------------------------------------------

package/src/facade/user-portfolio.ts

@@ -1,8 +1,10 @@
 import { Provider } from '@ethersproject/providers';
 
 import { deriveRequestState, RequestState } from '../domain/requests';
+import { YieldHistoryEntry } from '../domain/yield-history';
 import { DataService } from '../services/DataService/data-service';
 import { Portfolio } from '../services/Portfolio/portfolio';
+import { YieldHistoryOptions } from '../services/Portfolio/yield-history';
 import { UserRequest } from '../services/UserLending/types';
 import { UserLending } from '../services/UserLending/user-lending';
 
@@ -39,9 +41,8 @@ export class PortfolioFacade {
     ): Promise<UserPositions> {
         const currentEpoch = await this._userLending.getCurrentEpoch();
 
-        const poolOverviews = await this._dataService.getPoolOverview(
-            currentEpoch,
-        );
+        const poolOverviews =
+            await this._dataService.getPoolOverview(currentEpoch);
 
         const pools = await this._portfolio.getPortfolioLendingData(
             userAddress,
@@ -59,6 +60,42 @@ export class PortfolioFacade {
         return { pools, summary };
     }
 
+    /**
+     * The lender's settled yield per cycle, per pool and tranche: what each
+     * close credited them, NET of the performance fee (the chain credits it
+     * net), in display units of the deployment's own stable token (AUDD on
+     * XDC AUDD). `epochEnd` is unix seconds. Net only — no gross is offered.
+     *
+     * Validates `options` before any read (`RangeError` on a malformed one).
+     *
+     * ```ts
+     * const entries = await kasu.portfolio.getYieldHistory('0xUser...', { count: 52 });
+     * const allStrategies = aggregateYieldHistory(entries);
+     * const oneStrategy = aggregateYieldHistory(entries, { poolId });
+     * ```
+     *
+     * `getPositions`' `totalYieldEarningsLastEpoch` for a pool equals that
+     * pool's bar for the epoch of its most recently APPLIED interest — which
+     * is older than the last cycle for a pool that has not cleared since (the
+     * bar carries that older `epochId`). A lender who held nothing at that
+     * epoch has no bar there and a figure of 0; their newest bar is from
+     * when they last held shares.
+     *
+     * For a fixed-term lock holder the bars can sum to slightly more than the
+     * lifetime interest (up to about 0.2 %), because each top-up is valued at
+     * today's share price — show "earned to date" from the lifetime figure,
+     * never from the sum of the bars.
+     *
+     * `[]` for a lender with no history, and on a LITE deployment whose
+     * subgraph lacks the entities; on a full deployment that error throws.
+     */
+    async getYieldHistory(
+        userAddress: string,
+        options?: YieldHistoryOptions,
+    ): Promise<YieldHistoryEntry[]> {
+        return await this._portfolio.getYieldHistory(userAddress, options);
+    }
+
     /**
      * Fetch a user's full transaction history (deposits, withdrawals, cancellations).
      */

package/src/index.ts

@@ -2,6 +2,7 @@
 // Core SDK class (low-level service access)
 // ---------------------------------------------------------------------------
 export { KasuSdk } from './kasu-sdk';
+export type { KasuSdkOptions } from './kasu-sdk';
 
 // ---------------------------------------------------------------------------
 // Re-export config types
@@ -42,6 +43,16 @@ export type {
     PortfolioTrancheDepositDetails,
 } from './services/Portfolio/types';
 
+export type { YieldHistoryOptions } from './services/Portfolio/yield-history';
+
+export type { PoolTvlHistoryOptions } from './services/DataService/tvl-history';
+export {
+    PastStateUnavailableError,
+    PoolTvlHistoryAbortedError,
+    PoolTvlHistoryTimeoutError,
+} from './services/DataService/tvl-history';
+export { NO_HISTORY_PROVIDER_MESSAGE } from './services/DataService/data-service';
+
 export type {
     UserLock,
     UserBonusData,

package/src/kasu-sdk.ts

@@ -9,6 +9,15 @@ import { Portfolio } from './services/Portfolio/portfolio';
 import { Swapper } from './services/Swapper/swapper';
 import { UserLending } from './services/UserLending/user-lending';
 
+/** Optional providers beyond the main signer-or-provider. */
+export interface KasuSdkOptions {
+    /**
+     * A provider that SERVES PAST STATE (an archive RPC), for
+     * `DataService.getPoolTvlHistory`. Wins over `SdkConfig.historyRpcUrls`.
+     */
+    historyProvider?: Provider;
+}
+
 export class KasuSdk {
     private readonly _graphClient: GraphQLClient;
     public readonly Locking: KSULocking;
@@ -16,11 +25,19 @@ export class KasuSdk {
     public readonly UserLending: UserLending;
     public readonly Portfolio: Portfolio;
     public readonly Swapper: Swapper;
-    constructor(config: SdkConfig, signerOrProvider: Provider | Signer) {
+    constructor(
+        config: SdkConfig,
+        signerOrProvider: Provider | Signer,
+        options: KasuSdkOptions = {},
+    ) {
         this._graphClient = new GraphQLClient(config.subgraphUrl);
         this.Locking = new KSULocking(config, signerOrProvider);
         this.UserLending = new UserLending(config, signerOrProvider);
-        this.DataService = new DataService(config, signerOrProvider);
+        this.DataService = new DataService(
+            config,
+            signerOrProvider,
+            options.historyProvider,
+        );
         this.Portfolio = new Portfolio(config, signerOrProvider);
         this.Swapper = new Swapper();
     }

package/src/sdk-config.ts

@@ -50,6 +50,22 @@ export interface SdkConfigOptions {
      * @default 6
      */
     stableAssetDecimals?: number;
+    /**
+     * RPC URLs that SERVE PAST STATE (archive nodes), tried IN ORDER on
+     * failure, used only by `DataService.getPoolTvlHistory` to read the
+     * off-chain TVL at old blocks. A pruned node refuses those reads (some
+     * answer as if the call reverted), so these are never the default read
+     * RPC. An explicit `historyProvider` passed to `KasuSdk` / `Kasu.create`
+     * wins over them. The public defaults are rate-limited: an integrator
+     * should pass its own archive provider.
+     * @default [] — none
+     */
+    historyRpcUrls?: string[];
+    /**
+     * The chain id the history providers are pinned to (no `eth_chainId`
+     * round trip). `Kasu.create` sets it from the chain config.
+     */
+    chainId?: number;
 }
 
 export class SdkConfig {
@@ -61,6 +77,10 @@ export class SdkConfig {
     isLiteDeployment: boolean;
     poolMetadataMapping: Record<string, string>;
     stableAssetDecimals: number;
+    /** See `SdkConfigOptions.historyRpcUrls`. `[]` when none. */
+    historyRpcUrls: string[];
+    /** See `SdkConfigOptions.chainId`. */
+    chainId: number | undefined;
 
     constructor(options: SdkConfigOptions) {
         this.subgraphUrl = options.subgraphUrl;
@@ -77,5 +97,7 @@ export class SdkConfig {
         this.isLiteDeployment = options.isLiteDeployment ?? false;
         this.poolMetadataMapping = options.poolMetadataMapping ?? {};
         this.stableAssetDecimals = options.stableAssetDecimals ?? 6;
+        this.historyRpcUrls = [...(options.historyRpcUrls ?? [])];
+        this.chainId = options.chainId;
     }
 }