@kasufinance/kasu-sdk 2.11.0 → 2.13.0

package/dist/facade/user-portfolio.d.ts

@@ -1,7 +1,9 @@
 import { Provider } from '@ethersproject/providers';
 import { 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';
 import { UserPositions } from './types';
@@ -29,6 +31,36 @@ export declare class PortfolioFacade {
      *                      SDK was initialised with a Signer but you need a read-only provider).
      */
     getPositions(userAddress: string, provider?: Provider): Promise<UserPositions>;
+    /**
+     * 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.
+     */
+    getYieldHistory(userAddress: string, options?: YieldHistoryOptions): Promise<YieldHistoryEntry[]>;
     /**
      * Fetch a user's full transaction history (deposits, withdrawals, cancellations).
      */

package/dist/facade/user-portfolio.js

@@ -41,6 +41,40 @@ 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.
+     */
+    getYieldHistory(userAddress, options) {
+        return __awaiter(this, void 0, void 0, function* () {
+            return yield this._portfolio.getYieldHistory(userAddress, options);
+        });
+    }
     /**
      * Fetch a user's full transaction history (deposits, withdrawals, cancellations).
      */

package/dist/facade/user-portfolio.js.map

@@ -1 +1 @@
-{"version":3,"file":"user-portfolio.js","sourceRoot":"","sources":["../../src/facade/user-portfolio.ts"],"names":[],"mappings":";;;;;;;;;AAEA,OAAO,EAAE,kBAAkB,EAAgB,MAAM,oBAAoB,CAAC;AAQtE;;;;;GAKG;AACH,MAAM,OAAO,eAAe;IACxB,YACY,YAAyB,EACzB,YAAyB,EACzB,UAAqB;QAFrB,iBAAY,GAAZ,YAAY,CAAa;QACzB,iBAAY,GAAZ,YAAY,CAAa;QACzB,eAAU,GAAV,UAAU,CAAW;IAC9B,CAAC;IAEJ;;;;;;;;;;;OAWG;IACG,YAAY,CACd,WAAmB,EACnB,QAAmB;;YAEnB,MAAM,YAAY,GAAG,MAAM,IAAI,CAAC,YAAY,CAAC,eAAe,EAAE,CAAC;YAE/D,MAAM,aAAa,GAAG,MAAM,IAAI,CAAC,YAAY,CAAC,eAAe,CACzD,YAAY,CACf,CAAC;YAEF,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,UAAU,CAAC,uBAAuB,CACvD,WAAW,EACX,aAAa,EACb,YAAY,EACZ,QAAQ,CACX,CAAC;YAEF,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,UAAU,CAAC,mBAAmB,CACrD,WAAW,EACX,KAAK,EACL,YAAY,CACf,CAAC;YAEF,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC;QAC9B,CAAC;KAAA;IAED;;OAEG;IACG,qBAAqB,CACvB,WAA0B;;YAE1B,MAAM,YAAY,GAAG,MAAM,IAAI,CAAC,YAAY,CAAC,eAAe,EAAE,CAAC;YAC/D,OAAO,MAAM,IAAI,CAAC,YAAY,CAAC,eAAe,CAC1C,WAAW,EACX,YAAY,CACf,CAAC;QACN,CAAC;KAAA;IAED;;;;;;;;;;;;;;;OAeG;IACG,gBAAgB,CAClB,WAA0B;;YAE1B,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,qBAAqB,CAAC,WAAW,CAAC,CAAC;YAC/D,OAAO,QAAQ,CAAC,GAAG,CAAC,kBAAkB,CAAC,CAAC;QAC5C,CAAC;KAAA;CACJ"}
+{"version":3,"file":"user-portfolio.js","sourceRoot":"","sources":["../../src/facade/user-portfolio.ts"],"names":[],"mappings":";;;;;;;;;AAEA,OAAO,EAAE,kBAAkB,EAAgB,MAAM,oBAAoB,CAAC;AAUtE;;;;;GAKG;AACH,MAAM,OAAO,eAAe;IACxB,YACY,YAAyB,EACzB,YAAyB,EACzB,UAAqB;QAFrB,iBAAY,GAAZ,YAAY,CAAa;QACzB,iBAAY,GAAZ,YAAY,CAAa;QACzB,eAAU,GAAV,UAAU,CAAW;IAC9B,CAAC;IAEJ;;;;;;;;;;;OAWG;IACG,YAAY,CACd,WAAmB,EACnB,QAAmB;;YAEnB,MAAM,YAAY,GAAG,MAAM,IAAI,CAAC,YAAY,CAAC,eAAe,EAAE,CAAC;YAE/D,MAAM,aAAa,GACf,MAAM,IAAI,CAAC,YAAY,CAAC,eAAe,CAAC,YAAY,CAAC,CAAC;YAE1D,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,UAAU,CAAC,uBAAuB,CACvD,WAAW,EACX,aAAa,EACb,YAAY,EACZ,QAAQ,CACX,CAAC;YAEF,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,UAAU,CAAC,mBAAmB,CACrD,WAAW,EACX,KAAK,EACL,YAAY,CACf,CAAC;YAEF,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC;QAC9B,CAAC;KAAA;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;IACG,eAAe,CACjB,WAAmB,EACnB,OAA6B;;YAE7B,OAAO,MAAM,IAAI,CAAC,UAAU,CAAC,eAAe,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;QACvE,CAAC;KAAA;IAED;;OAEG;IACG,qBAAqB,CACvB,WAA0B;;YAE1B,MAAM,YAAY,GAAG,MAAM,IAAI,CAAC,YAAY,CAAC,eAAe,EAAE,CAAC;YAC/D,OAAO,MAAM,IAAI,CAAC,YAAY,CAAC,eAAe,CAC1C,WAAW,EACX,YAAY,CACf,CAAC;QACN,CAAC;KAAA;IAED;;;;;;;;;;;;;;;OAeG;IACG,gBAAgB,CAClB,WAA0B;;YAE1B,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,qBAAqB,CAAC,WAAW,CAAC,CAAC;YAC/D,OAAO,QAAQ,CAAC,GAAG,CAAC,kBAAkB,CAAC,CAAC;QAC5C,CAAC;KAAA;CACJ"}

package/dist/index.d.ts

@@ -1,9 +1,14 @@
 export { KasuSdk } from './kasu-sdk';
+export type { KasuSdkOptions } from './kasu-sdk';
 export type { ContractAddresses, SdkConfigOptions } from './sdk-config';
 export { SdkConfig } from './sdk-config';
 export type { PoolOverview, TrancheData, LendingTotals, PoolRepayment, RiskManagement, PoolDelegateProfileAndHistory, PoolTranche, PoolCreditMetrics, BadAndDoubtfulDebts, FinancialReportingDocuments, } from './services/DataService/types';
 export type { UserRequest, UserRequestEvent, UserTrancheBalance, UserPoolBalance, UserApyBonus, PortfolioUserTrancheBalance, } from './services/UserLending/types';
 export type { PortfolioSummary, PortfolioLendingPool, PortfolioTranche, PortfolioRewards, 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, LockPeriod, GQLGetLockingPeriods, SystemVariables, } from './services/Locking/types';
 export type { PoolOverviewDirectus, PlatformOverviewDirectus, } from './services/DataService/directus-types';
 export { NO_DIRECTUS_URL_MESSAGE } from './services/DataService/directus-client';

package/dist/index.js

@@ -3,6 +3,8 @@
 // ---------------------------------------------------------------------------
 export { KasuSdk } from './kasu-sdk';
 export { SdkConfig } from './sdk-config';
+export { PastStateUnavailableError, PoolTvlHistoryAbortedError, PoolTvlHistoryTimeoutError, } from './services/DataService/tvl-history';
+export { NO_HISTORY_PROVIDER_MESSAGE } from './services/DataService/data-service';
 export { NO_DIRECTUS_URL_MESSAGE } from './services/DataService/directus-client';
 // ---------------------------------------------------------------------------
 // Re-export facade (high-level integrator API)

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,4CAA4C;AAC5C,8EAA8E;AAC9E,OAAO,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAMrC,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAgDzC,OAAO,EAAE,uBAAuB,EAAE,MAAM,wCAAwC,CAAC;AAEjF,8EAA8E;AAC9E,+CAA+C;AAC/C,8EAA8E;AAC9E,cAAc,UAAU,CAAC;AAEzB,8EAA8E;AAC9E,6EAA6E;AAC7E,uDAAuD;AACvD,8EAA8E;AAC9E,cAAc,UAAU,CAAC;AAEzB,8EAA8E;AAC9E,6EAA6E;AAC7E,uEAAuE;AACvE,wDAAwD;AACxD,8EAA8E;AAC9E,cAAc,SAAS,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,4CAA4C;AAC5C,8EAA8E;AAC9E,OAAO,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAOrC,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAsCzC,OAAO,EACH,yBAAyB,EACzB,0BAA0B,EAC1B,0BAA0B,GAC7B,MAAM,oCAAoC,CAAC;AAC5C,OAAO,EAAE,2BAA2B,EAAE,MAAM,qCAAqC,CAAC;AAelF,OAAO,EAAE,uBAAuB,EAAE,MAAM,wCAAwC,CAAC;AAEjF,8EAA8E;AAC9E,+CAA+C;AAC/C,8EAA8E;AAC9E,cAAc,UAAU,CAAC;AAEzB,8EAA8E;AAC9E,6EAA6E;AAC7E,uDAAuD;AACvD,8EAA8E;AAC9E,cAAc,UAAU,CAAC;AAEzB,8EAA8E;AAC9E,6EAA6E;AAC7E,uEAAuE;AACvE,wDAAwD;AACxD,8EAA8E;AAC9E,cAAc,SAAS,CAAC"}

package/dist/kasu-sdk.d.ts

@@ -6,6 +6,14 @@ import { KSULocking } from './services/Locking/locking';
 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 declare class KasuSdk {
     private readonly _graphClient;
     readonly Locking: KSULocking;
@@ -13,5 +21,5 @@ export declare class KasuSdk {
     readonly UserLending: UserLending;
     readonly Portfolio: Portfolio;
     readonly Swapper: Swapper;
-    constructor(config: SdkConfig, signerOrProvider: Provider | Signer);
+    constructor(config: SdkConfig, signerOrProvider: Provider | Signer, options?: KasuSdkOptions);
 }

package/dist/kasu-sdk.js

@@ -5,11 +5,11 @@ import { Portfolio } from './services/Portfolio/portfolio';
 import { Swapper } from './services/Swapper/swapper';
 import { UserLending } from './services/UserLending/user-lending';
 export class KasuSdk {
-    constructor(config, signerOrProvider) {
+    constructor(config, signerOrProvider, options = {}) {
         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/dist/kasu-sdk.js.map

@@ -1 +1 @@
-{"version":3,"file":"kasu-sdk.js","sourceRoot":"","sources":["../src/kasu-sdk.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAGhD,OAAO,EAAE,WAAW,EAAE,MAAM,qCAAqC,CAAC;AAClE,OAAO,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AACxD,OAAO,EAAE,SAAS,EAAE,MAAM,gCAAgC,CAAC;AAC3D,OAAO,EAAE,OAAO,EAAE,MAAM,4BAA4B,CAAC;AACrD,OAAO,EAAE,WAAW,EAAE,MAAM,qCAAqC,CAAC;AAElE,MAAM,OAAO,OAAO;IAOhB,YAAY,MAAiB,EAAE,gBAAmC;QAC9D,IAAI,CAAC,YAAY,GAAG,IAAI,aAAa,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC;QAC1D,IAAI,CAAC,OAAO,GAAG,IAAI,UAAU,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;QACxD,IAAI,CAAC,WAAW,GAAG,IAAI,WAAW,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;QAC7D,IAAI,CAAC,WAAW,GAAG,IAAI,WAAW,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;QAC7D,IAAI,CAAC,SAAS,GAAG,IAAI,SAAS,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;QACzD,IAAI,CAAC,OAAO,GAAG,IAAI,OAAO,EAAE,CAAC;IACjC,CAAC;CACJ"}
+{"version":3,"file":"kasu-sdk.js","sourceRoot":"","sources":["../src/kasu-sdk.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAGhD,OAAO,EAAE,WAAW,EAAE,MAAM,qCAAqC,CAAC;AAClE,OAAO,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AACxD,OAAO,EAAE,SAAS,EAAE,MAAM,gCAAgC,CAAC;AAC3D,OAAO,EAAE,OAAO,EAAE,MAAM,4BAA4B,CAAC;AACrD,OAAO,EAAE,WAAW,EAAE,MAAM,qCAAqC,CAAC;AAWlE,MAAM,OAAO,OAAO;IAOhB,YACI,MAAiB,EACjB,gBAAmC,EACnC,UAA0B,EAAE;QAE5B,IAAI,CAAC,YAAY,GAAG,IAAI,aAAa,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC;QAC1D,IAAI,CAAC,OAAO,GAAG,IAAI,UAAU,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;QACxD,IAAI,CAAC,WAAW,GAAG,IAAI,WAAW,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;QAC7D,IAAI,CAAC,WAAW,GAAG,IAAI,WAAW,CAC9B,MAAM,EACN,gBAAgB,EAChB,OAAO,CAAC,eAAe,CAC1B,CAAC;QACF,IAAI,CAAC,SAAS,GAAG,IAAI,SAAS,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;QACzD,IAAI,CAAC,OAAO,GAAG,IAAI,OAAO,EAAE,CAAC;IACjC,CAAC;CACJ"}

package/dist/sdk-config.d.ts

@@ -49,6 +49,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 declare class SdkConfig {
     subgraphUrl: string;
@@ -59,5 +75,9 @@ export declare 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);
 }

package/dist/sdk-config.js

@@ -1,6 +1,6 @@
 export class SdkConfig {
     constructor(options) {
-        var _a, _b, _c, _d;
+        var _a, _b, _c, _d, _e;
         this.subgraphUrl = options.subgraphUrl;
         this.contracts = options.contracts;
         this.directusUrl = (_a = options.directusUrl) !== null && _a !== void 0 ? _a : '';
@@ -15,6 +15,8 @@ export class SdkConfig {
         this.isLiteDeployment = (_b = options.isLiteDeployment) !== null && _b !== void 0 ? _b : false;
         this.poolMetadataMapping = (_c = options.poolMetadataMapping) !== null && _c !== void 0 ? _c : {};
         this.stableAssetDecimals = (_d = options.stableAssetDecimals) !== null && _d !== void 0 ? _d : 6;
+        this.historyRpcUrls = [...((_e = options.historyRpcUrls) !== null && _e !== void 0 ? _e : [])];
+        this.chainId = options.chainId;
     }
 }
 //# sourceMappingURL=sdk-config.js.map

package/dist/sdk-config.js.map

@@ -1 +1 @@
-{"version":3,"file":"sdk-config.js","sourceRoot":"","sources":["../src/sdk-config.ts"],"names":[],"mappings":"AAsDA,MAAM,OAAO,SAAS;IAUlB,YAAY,OAAyB;;QACjC,IAAI,CAAC,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC;QACvC,IAAI,CAAC,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC;QACnC,IAAI,CAAC,WAAW,GAAG,MAAA,OAAO,CAAC,WAAW,mCAAI,EAAE,CAAC;QAC7C,+DAA+D;QAC/D,qEAAqE;QACrE,uEAAuE;QACvE,0DAA0D;QAC1D,IAAI,CAAC,uBAAuB;YACxB,OAAO,CAAC,uBAAuB,CAAC,MAAM,GAAG,CAAC;gBACtC,CAAC,CAAC,OAAO,CAAC,uBAAuB;gBACjC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;QACf,IAAI,CAAC,gBAAgB,GAAG,MAAA,OAAO,CAAC,gBAAgB,mCAAI,KAAK,CAAC;QAC1D,IAAI,CAAC,mBAAmB,GAAG,MAAA,OAAO,CAAC,mBAAmB,mCAAI,EAAE,CAAC;QAC7D,IAAI,CAAC,mBAAmB,GAAG,MAAA,OAAO,CAAC,mBAAmB,mCAAI,CAAC,CAAC;IAChE,CAAC;CACJ"}
+{"version":3,"file":"sdk-config.js","sourceRoot":"","sources":["../src/sdk-config.ts"],"names":[],"mappings":"AAsEA,MAAM,OAAO,SAAS;IAclB,YAAY,OAAyB;;QACjC,IAAI,CAAC,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC;QACvC,IAAI,CAAC,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC;QACnC,IAAI,CAAC,WAAW,GAAG,MAAA,OAAO,CAAC,WAAW,mCAAI,EAAE,CAAC;QAC7C,+DAA+D;QAC/D,qEAAqE;QACrE,uEAAuE;QACvE,0DAA0D;QAC1D,IAAI,CAAC,uBAAuB;YACxB,OAAO,CAAC,uBAAuB,CAAC,MAAM,GAAG,CAAC;gBACtC,CAAC,CAAC,OAAO,CAAC,uBAAuB;gBACjC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;QACf,IAAI,CAAC,gBAAgB,GAAG,MAAA,OAAO,CAAC,gBAAgB,mCAAI,KAAK,CAAC;QAC1D,IAAI,CAAC,mBAAmB,GAAG,MAAA,OAAO,CAAC,mBAAmB,mCAAI,EAAE,CAAC;QAC7D,IAAI,CAAC,mBAAmB,GAAG,MAAA,OAAO,CAAC,mBAAmB,mCAAI,CAAC,CAAC;QAC5D,IAAI,CAAC,cAAc,GAAG,CAAC,GAAG,CAAC,MAAA,OAAO,CAAC,cAAc,mCAAI,EAAE,CAAC,CAAC,CAAC;QAC1D,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;IACnC,CAAC;CACJ"}

package/dist/services/DataService/data-service.d.ts

@@ -1,16 +1,33 @@
 import { Provider } from '@ethersproject/abstract-provider';
 import { Signer } from 'ethers';
+import { PoolTvlHistoryEntry } from '../../domain/pool-tvl';
 import { SdkConfig } from '../../sdk-config';
 import { NftBoostDirectus, PlatformOverviewDirectus } from './directus-types';
 import { LendingPoolConfigurationSubgraph, LendingPoolSubgraph } from './subgraph-types';
+import { PoolTvlHistoryOptions } from './tvl-history';
 import { BadAndDoubtfulDebts, FinancialReportingDocuments, LendingTotals, PoolCreditMetrics, PoolDelegateProfileAndHistory, PoolOverview, PoolRepayment, PoolTranche, RiskManagement } from './types';
+/** Thrown by `getPoolTvlHistory` when no provider that serves past state is configured. */
+export declare const NO_HISTORY_PROVIDER_MESSAGE = "getPoolTvlHistory: no history provider; pass historyProvider or set historyRpcUrls to RPCs that serve past state";
 export declare class DataService {
     private _kasuConfig;
     private readonly _graph;
     private readonly _externalTvlAbi;
+    private readonly _systemVariablesAbi;
     private readonly _directus;
     private _directusPoolOverview;
-    constructor(_kasuConfig: SdkConfig, signerOrProvider: Signer | Provider);
+    private readonly _explicitHistoryProvider;
+    private _builtHistoryProviders;
+    /** Immutable past-block reads, kept for the life of this instance. */
+    private readonly _tvlHistoryCache;
+    /**
+     * @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(_kasuConfig: SdkConfig, signerOrProvider: Signer | Provider, historyProvider?: Provider);
     private getUrlFromFile;
     /**
      * Maps a pool ID to its metadata source pool ID.
@@ -34,6 +51,69 @@ export declare class DataService {
     getPlatformOverview(): Promise<PlatformOverviewDirectus>;
     getNftBoost(): Promise<Omit<NftBoostDirectus, 'id'>>;
     getOffChainTvl(poolIds: string[]): Promise<Map<string, string>>;
+    /**
+     * 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.
+     */
+    getPoolTvlHistory(poolId: string, options?: PoolTvlHistoryOptions): Promise<PoolTvlHistoryEntry[]>;
+    private _readPoolTvlHistory;
+    /** The pool's balance at each block: cached final blocks, then one batch. */
+    private _balancesAtBlocks;
+    /** `null` when the deployment has no `ExternalTVL` contract. */
+    private _externalTvlAddress;
+    /** Seam for tests: the real reader over the history RPCs. */
+    private _createOffChainTvlReader;
+    /**
+     * 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;
     getPoolOverview(epochId: string, id_in?: string[]): Promise<PoolOverview[]>;
     getPerformanceFee(): Promise<number>;
     getRiskManagement(id_in?: string[]): Promise<RiskManagement[]>;

package/dist/services/DataService/data-service.js

@@ -19,19 +19,36 @@ var __rest = (this && this.__rest) || function (s, e) {
     return t;
 };
 import { readItems, readSingleton } from '@directus/sdk';
-import { formatUnits } from 'ethers/lib/utils';
+import { BigNumber, providers } from 'ethers';
+import { formatUnits, isAddress } from 'ethers/lib/utils';
 import { GraphQLClient } from 'graphql-request';
-import { KasuPoolExternalTVLAbi__factory, } from '../../contracts';
+import { ISystemVariablesAbi__factory, KasuPoolExternalTVLAbi__factory, } from '../../contracts';
+import { poolTvl } from '../../domain/pool-tvl';
 import { epochRateToApy } from '../../domain/rates';
 import { getSystemVariablesQuery } from '../Locking/queries';
-import { filterArray } from '../shared';
+import { filterArray, isEmptyHistoryError } from '../shared';
 import { createDirectusClient, } from './directus-client';
 import { getAllTrancheConfigurationsQuery, getAllTranchesQuery, getLendingPoolWithdrawalAndDepositsQuery, getPoolNameQuery, getPoolOverviewQuery, } from './queries';
+import { buildPoolTvlHistory, createOffChainTvlReader, distinctBlocks, fetchOffChainTvlAtBlocks, fetchPoolBalancesAtBlocks, fetchPoolClearings, PastBlockCache, resolvePoolTvlHistoryWindow, runCancellable, TVL_HISTORY_CACHE_DEPTH, TVL_HISTORY_DEFAULT_TIMEOUT_MS, TVL_HISTORY_RPC_TIMEOUT_MS, validatePoolTvlHistoryOptions, } from './tvl-history';
+/** 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 {
-    constructor(_kasuConfig, signerOrProvider) {
+    /**
+     * @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(_kasuConfig, signerOrProvider, historyProvider) {
         this._kasuConfig = _kasuConfig;
+        /** Immutable past-block reads, kept for the life of this instance. */
+        this._tvlHistoryCache = new PastBlockCache();
         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);
     }
     getUrlFromFile(fileName) {
@@ -111,6 +128,194 @@ 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.
+     */
+    getPoolTvlHistory(poolId_1) {
+        return __awaiter(this, arguments, void 0, function* (poolId, options = {}) {
+            var _a;
+            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 yield runCancellable((_a = options.timeoutMs) !== null && _a !== void 0 ? _a : TVL_HISTORY_DEFAULT_TIMEOUT_MS, options.signal, (cancellation) => this._readPoolTvlHistory(pool, options, externalTvl
+                ? this._createOffChainTvlReader({
+                    externalTvl,
+                    pool,
+                    rpcs,
+                    cancellation,
+                })
+                : null, externalTvl !== null && externalTvl !== void 0 ? externalTvl : '', cancellation));
+        });
+    }
+    _readPoolTvlHistory(pool, options, reader, externalTvl, cancellation) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a, _b, _c;
+            const graph = (document, variables, signal) => this._graph.request({ document, variables, signal });
+            const scope = options.fromEpoch === undefined && options.count !== undefined
+                ? { kind: 'newest', count: options.count }
+                : { kind: 'from', fromEpoch: (_a = options.fromEpoch) !== null && _a !== void 0 ? _a : 0 };
+            try {
+                const [currentEpochNumber, { clearings, snapshot }] = yield 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 = (_b = snapshot.meta) === null || _b === void 0 ? void 0 : _b.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) => block <= head.number - TVL_HISTORY_CACHE_DEPTH;
+                const [balances, offChainRead] = yield 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: (_c = offChainRead.latest) !== null && _c !== void 0 ? _c : 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. */
+    _balancesAtBlocks(graph, pool, blocks, cacheable, cancellation) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const key = (block) => `balance|${this._kasuConfig.subgraphUrl}|${pool}|${String(block)}`;
+            const balances = new Map();
+            const missing = [];
+            for (const block of blocks) {
+                const hit = cacheable(block)
+                    ? this._tvlHistoryCache.get(key(block))
+                    : undefined;
+                if (hit === undefined)
+                    missing.push(block);
+                else
+                    balances.set(block, hit);
+            }
+            if (missing.length > 0) {
+                const read = yield 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. */
+    _externalTvlAddress() {
+        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. */
+    _createOffChainTvlReader(args) {
+        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.
+     */
+    _historyRpcs() {
+        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;
+    }
     getPoolOverview(epochId, id_in) {
         return __awaiter(this, void 0, void 0, function* () {
             var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p, _q, _r, _s;
@@ -251,8 +456,8 @@ export class DataService {
                     subheading: lendingPoolDirectus === null || lendingPoolDirectus === void 0 ? void 0 : lendingPoolDirectus.subheading,
                     operatingSince: lendingPoolDirectus === null || lendingPoolDirectus === void 0 ? void 0 : lendingPoolDirectus.operatingSince,
                     totalValueLocked: {
-                        total: (parseFloat(lendingPoolSubgraph.balance) +
-                            parseFloat(offChainTvl)).toString(),
+                        // The one TVL definition, shared with getPoolTvlHistory.
+                        total: poolTvl(lendingPoolSubgraph.balance, offChainTvl).toString(),
                         offchain: offChainTvl,
                     },
                     loansUnderManagement: (_q = lendingPoolDirectus === null || lendingPoolDirectus === void 0 ? void 0 : lendingPoolDirectus.loansUnderManagement) !== null && _q !== void 0 ? _q : '0',