@kasufinance/kasu-sdk 2.13.1 → 2.14.0

package/dist/domain/pool-tvl.d.ts

@@ -60,3 +60,107 @@ export interface PoolTvlHistoryEntry {
     /** `'clearing'` for a cycle boundary; `'current'` for the closing point. */
     kind: 'clearing' | 'current';
 }
+/**
+ * One deployment's share of a strategy's history, for `combineTvlHistories`:
+ * that pool's `getPoolTvlHistoryWindow` result (`{ entries, opening }`) as it
+ * came back, and what one unit of the deployment's stable token is worth in
+ * USD (`1` for USDC; today's AUD→USD for AUDD). The SDK fetches no exchange
+ * rate: the caller passes it.
+ */
+export interface TvlHistoryLeg {
+    /** At least one point: a real pool always returns its `current` point. */
+    entries: readonly PoolTvlHistoryEntry[];
+    /** USD per unit of the leg's stable token. Finite and above 0. */
+    usdRate: number;
+    /**
+     * The leg's step BEFORE its first entry: the newest clearing before the
+     * window, as `getPoolTvlHistoryWindow` read it at its own block. It
+     * counts from its own `timestamp` on, and the leg is 0 before that — no
+     * value is carried back to a time before it existed. A `'clearing'`
+     * point no later than the first entry; it is never drawn. `null` or
+     * absent: the pool has no clearing before the window (it started lending
+     * later, say) and counts 0 before its first entry.
+     */
+    opening?: PoolTvlHistoryEntry | null;
+}
+/**
+ * One point of a strategy's TVL summed across its deployments.
+ *
+ * There is no `epochId`: each chain clears at its own blocks and times, so a
+ * merged point belongs to no single epoch. Plot by `timestamp`.
+ */
+export interface StrategyTvlHistoryEntry {
+    /** Unix SECONDS. Strictly ascending across the series. */
+    timestamp: number;
+    /** The sum over legs of each leg's TVL then, times its `usdRate`. */
+    tvlUsd: number;
+    /** `'clearing'` for a cycle boundary on any leg; `'current'` for the closing point. */
+    kind: 'clearing' | 'current';
+}
+/**
+ * What `combineTvlHistories` refuses, as a code:
+ *
+ * - `legs` — not a non-empty array (or one with holes);
+ * - `leg` — a leg that is not an object;
+ * - `usd-rate` — a rate that is not a finite number above 0;
+ * - `opening` — an opening that is not a well-formed `'clearing'` point at
+ *   or before the leg's first entry (or `null`, or absent);
+ * - `entries` — a leg's `entries` is not an array;
+ * - `empty-leg` — a leg with no entries: pass only the legs you have;
+ * - `entry` — an entry that is not an object (or a hole);
+ * - `timestamp` / `tvl` — not a finite number at or above 0;
+ * - `kind` — neither `'clearing'` nor `'current'`;
+ * - `order` — timestamps going backwards within a leg;
+ * - `current` — a `current` point that is not the leg's last, or some legs
+ *   ending in one and others not;
+ * - `overflow` — a sum too large to be a finite number.
+ */
+export type TvlHistoryInputErrorCode = 'legs' | 'leg' | 'usd-rate' | 'opening' | 'entries' | 'empty-leg' | 'entry' | 'timestamp' | 'tvl' | 'kind' | 'order' | 'current' | 'overflow';
+/**
+ * What `combineTvlHistories` throws instead of returning a number it cannot
+ * stand behind. `leg` and `entry` are the zero-based position of the
+ * offending input, when there is one.
+ */
+export declare class TvlHistoryInputError extends Error {
+    readonly code: TvlHistoryInputErrorCode;
+    readonly leg: number | undefined;
+    readonly entry: number | undefined;
+    constructor(code: TvlHistoryInputErrorCode, leg?: number, entry?: number);
+}
+/**
+ * A strategy's TVL in USD over time, from its deployments' histories — Tax
+ * Pay runs on Base (USDC) and on XDC (AUDD), and its total lent is both.
+ * Pure: the caller fetches each leg (`strategyDeployments` names them) and
+ * passes the exchange rates.
+ *
+ * A step merge by time. At every distinct timestamp where any leg has a
+ * clearing, the value is the sum over legs of that leg's latest point at or
+ * before then, times its `usdRate`. A leg's `opening` — what it held just
+ * before the window — is one more step: it counts from its own timestamp
+ * until the leg's first entry, and the leg is 0 before it (or throughout,
+ * before its first entry, without one).
+ * Points that share a timestamp — clearings run in one block, or two chains
+ * clearing in the same second — are one output point. The series ends with
+ * one `current` point at the latest of the legs' `current` timestamps, equal
+ * to the sum of their `current` values. Every leg must end in a `current`
+ * point, or none may.
+ *
+ * The window is the union of the legs' windows: the series starts at the
+ * earliest first entry of any leg. An `opening` is a value, never a point.
+ * Without it, two windows cut at offset clearing times would count the
+ * later-starting leg 0 at the left edge and draw a false step up; with it,
+ * only a genuine late start (`opening: null`) counts 0.
+ *
+ * Every leg and entry is validated first: a bad input — an empty leg
+ * included — throws `TvlHistoryInputError` (its `code` says why), so the
+ * result never holds `NaN` or `Infinity`. The inputs are not modified.
+ *
+ * ```ts
+ * const window = { count: 52 };
+ * const points = combineTvlHistories([
+ *     { ...(await base.strategies.getPoolTvlHistoryWindow(basePool, window)), usdRate: 1 },
+ *     { ...(await xdc.strategies.getPoolTvlHistoryWindow(xdcPool, window)), usdRate: audToUsd },
+ * ]);
+ * ```
+ */
+export declare function combineTvlHistories(legs: readonly TvlHistoryLeg[]): StrategyTvlHistoryEntry[];

package/dist/facade/index.d.ts

@@ -8,5 +8,7 @@ export type { RequestWithdrawalCallParams } from './calls';
 export type { DepositFlowPortOverrides, WithdrawFlowPortOverrides, } from './flows';
 export { READ_ONLY_MESSAGE } from './read-only';
 export { CHAIN_CONFIGS } from './chain-configs';
+export { StrategyDeploymentInputError, strategyDeployments, } from './strategy-deployments';
+export type { StrategyDeployment, StrategyDeploymentInputErrorCode, } from './strategy-deployments';
 export { fetchUnusedPoolIds } from './unused-pool-ids';
 export type { SupportedChain, ChainConfigEntry, StableAsset, KasuOptions, Strategy, StrategyTranche, FixedTermOption, DepositParams, WithdrawParams, DepositLimits, KycParams, UserPositions, PlatformStats, StrategyRiskPerformance, } from './types';

package/dist/facade/strategies.d.ts

@@ -1,6 +1,6 @@
 import { PoolTvlHistoryEntry } from '../domain/pool-tvl';
 import { DataService } from '../services/DataService/data-service';
-import { PoolTvlHistoryOptions } from '../services/DataService/tvl-history';
+import { PoolTvlHistoryOptions, PoolTvlHistoryResult } from '../services/DataService/tvl-history';
 import { PoolDelegateProfileAndHistory } from '../services/DataService/types';
 import { UserLending } from '../services/UserLending/user-lending';
 import { DepositLimits, PlatformStats, Strategy, StrategyRiskPerformance, StrategyTranche } from './types';
@@ -104,6 +104,22 @@ export declare class StrategiesFacade {
      * ```
      */
     getPoolTvlHistory(poolId: string, options?: PoolTvlHistoryOptions): Promise<PoolTvlHistoryEntry[]>;
+    /**
+     * `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 }
+     * ```
+     */
+    getPoolTvlHistoryWindow(poolId: string, options?: PoolTvlHistoryOptions): Promise<PoolTvlHistoryResult>;
     /**
      * Fetch a single strategy by pool ID. Returns `null` if not found.
      */

package/dist/facade/strategy-deployments.d.ts

@@ -0,0 +1,65 @@
+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 declare class StrategyDeploymentInputError extends Error {
+    readonly code: StrategyDeploymentInputErrorCode;
+    constructor(code: StrategyDeploymentInputErrorCode);
+}
+type MappingConfigs = Readonly<Record<SupportedChain, Pick<ChainConfigEntry, 'poolMetadataMapping'>>>;
+/**
+ * `strategyDeployments` over any configs — the export reads `CHAIN_CONFIGS`;
+ * the spec passes its own to cover shapes the built-in mapping lacks.
+ */
+export declare function resolveStrategyDeployments(configs: MappingConfigs, poolId: string, chain: SupportedChain): StrategyDeployment[];
+/**
+ * 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 declare function strategyDeployments(poolId: string, chain: SupportedChain): StrategyDeployment[];
+export {};

package/dist/index.d.ts

@@ -6,7 +6,7 @@ export type { PoolOverview, TrancheData, LendingTotals, PoolRepayment, RiskManag
 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 type { PoolTvlHistoryOptions, PoolTvlHistoryResult, } 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';

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

@@ -4,7 +4,7 @@ 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 { PoolTvlHistoryOptions, PoolTvlHistoryResult } 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";
@@ -100,6 +100,34 @@ export declare class DataService {
      * `PastStateUnavailableError` from a pruned history provider.
      */
     getPoolTvlHistory(poolId: string, options?: PoolTvlHistoryOptions): Promise<PoolTvlHistoryEntry[]>;
+    /**
+     * `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
+     * `[]`.
+     */
+    getPoolTvlHistoryWindow(poolId: string, options?: PoolTvlHistoryOptions): Promise<PoolTvlHistoryResult>;
+    private _poolTvlHistory;
     private _readPoolTvlHistory;
     /** The pool's balance at each block: cached final blocks, then one batch. */
     private _balancesAtBlocks;

package/dist/services/DataService/tvl-history.d.ts

@@ -31,6 +31,21 @@ 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;
@@ -171,6 +186,40 @@ export declare function fetchPoolClearings(request: GraphRequest, poolId: string
     snapshot: PoolTvlSnapshot;
     requests: number;
 }>;
+/**
+ * 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 declare function pickOpeningClearing(before: readonly Clearing[], inWindow: readonly Clearing[]): Clearing | null;
+/**
+ * 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 declare function needsClearingBeforeBlock(before: readonly Clearing[], opening: Clearing | null): boolean;
+/**
+ * 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 declare const poolTvlClearingBeforeBlockQuery: string;
+export declare function fetchClearingBeforeBlock(request: GraphRequest, poolId: string, blockLt: number, cancellation: Cancellation): Promise<Clearing | null>;
+/**
+ * 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 declare function fetchClearingBefore(request: GraphRequest, poolId: string, beforeEpoch: number, cancellation: Cancellation): Promise<Clearing | null>;
 /**
  * The pool's balance (display units, the subgraph's decimal string) at the end
  * of each block, `TVL_HISTORY_BLOCKS_PER_REQUEST` blocks per request. A block

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@kasufinance/kasu-sdk",
-    "version": "2.13.1",
+    "version": "2.14.0",
     "description": "TypeScript SDK for the Kasu Finance protocol — pool data, portfolio analytics, and KYC-gated deposits and withdrawals on Base and XDC",
     "keywords": [
         "kasu",

package/src/domain/index.ts

@@ -188,8 +188,13 @@ export {
 } from './wallet-errors';
 export type { WalletFailure } from './wallet-errors';
 
-export { poolTvl } from './pool-tvl';
-export type { PoolTvlHistoryEntry } from './pool-tvl';
+export { combineTvlHistories, poolTvl, TvlHistoryInputError } from './pool-tvl';
+export type {
+    PoolTvlHistoryEntry,
+    StrategyTvlHistoryEntry,
+    TvlHistoryInputErrorCode,
+    TvlHistoryLeg,
+} from './pool-tvl';
 
 export { aggregateYieldHistory, epochTrancheYield } from './yield-history';
 export type {

package/src/domain/pool-tvl.ts

@@ -64,3 +64,284 @@ export interface PoolTvlHistoryEntry {
     /** `'clearing'` for a cycle boundary; `'current'` for the closing point. */
     kind: 'clearing' | 'current';
 }
+
+/**
+ * One deployment's share of a strategy's history, for `combineTvlHistories`:
+ * that pool's `getPoolTvlHistoryWindow` result (`{ entries, opening }`) as it
+ * came back, and what one unit of the deployment's stable token is worth in
+ * USD (`1` for USDC; today's AUD→USD for AUDD). The SDK fetches no exchange
+ * rate: the caller passes it.
+ */
+export interface TvlHistoryLeg {
+    /** At least one point: a real pool always returns its `current` point. */
+    entries: readonly PoolTvlHistoryEntry[];
+    /** USD per unit of the leg's stable token. Finite and above 0. */
+    usdRate: number;
+    /**
+     * The leg's step BEFORE its first entry: the newest clearing before the
+     * window, as `getPoolTvlHistoryWindow` read it at its own block. It
+     * counts from its own `timestamp` on, and the leg is 0 before that — no
+     * value is carried back to a time before it existed. A `'clearing'`
+     * point no later than the first entry; it is never drawn. `null` or
+     * absent: the pool has no clearing before the window (it started lending
+     * later, say) and counts 0 before its first entry.
+     */
+    opening?: PoolTvlHistoryEntry | null;
+}
+
+/**
+ * One point of a strategy's TVL summed across its deployments.
+ *
+ * There is no `epochId`: each chain clears at its own blocks and times, so a
+ * merged point belongs to no single epoch. Plot by `timestamp`.
+ */
+export interface StrategyTvlHistoryEntry {
+    /** Unix SECONDS. Strictly ascending across the series. */
+    timestamp: number;
+    /** The sum over legs of each leg's TVL then, times its `usdRate`. */
+    tvlUsd: number;
+    /** `'clearing'` for a cycle boundary on any leg; `'current'` for the closing point. */
+    kind: 'clearing' | 'current';
+}
+
+/**
+ * What `combineTvlHistories` refuses, as a code:
+ *
+ * - `legs` — not a non-empty array (or one with holes);
+ * - `leg` — a leg that is not an object;
+ * - `usd-rate` — a rate that is not a finite number above 0;
+ * - `opening` — an opening that is not a well-formed `'clearing'` point at
+ *   or before the leg's first entry (or `null`, or absent);
+ * - `entries` — a leg's `entries` is not an array;
+ * - `empty-leg` — a leg with no entries: pass only the legs you have;
+ * - `entry` — an entry that is not an object (or a hole);
+ * - `timestamp` / `tvl` — not a finite number at or above 0;
+ * - `kind` — neither `'clearing'` nor `'current'`;
+ * - `order` — timestamps going backwards within a leg;
+ * - `current` — a `current` point that is not the leg's last, or some legs
+ *   ending in one and others not;
+ * - `overflow` — a sum too large to be a finite number.
+ */
+export type TvlHistoryInputErrorCode =
+    | 'legs'
+    | 'leg'
+    | 'usd-rate'
+    | 'opening'
+    | 'entries'
+    | 'empty-leg'
+    | 'entry'
+    | 'timestamp'
+    | 'tvl'
+    | 'kind'
+    | 'order'
+    | 'current'
+    | 'overflow';
+
+/**
+ * What `combineTvlHistories` throws instead of returning a number it cannot
+ * stand behind. `leg` and `entry` are the zero-based position of the
+ * offending input, when there is one.
+ */
+export class TvlHistoryInputError extends Error {
+    readonly code: TvlHistoryInputErrorCode;
+    readonly leg: number | undefined;
+    readonly entry: number | undefined;
+
+    constructor(code: TvlHistoryInputErrorCode, leg?: number, entry?: number) {
+        const at = [
+            leg === undefined ? '' : ` at leg ${String(leg)}`,
+            entry === undefined ? '' : `, entry ${String(entry)}`,
+        ].join('');
+        super(`combineTvlHistories: input refused (${code})${at}`);
+        this.name = 'TvlHistoryInputError';
+        this.code = code;
+        this.leg = leg;
+        this.entry = entry;
+        Object.setPrototypeOf(this, TvlHistoryInputError.prototype);
+    }
+}
+
+function isNonNegativeFinite(value: unknown): value is number {
+    return typeof value === 'number' && Number.isFinite(value) && value >= 0;
+}
+
+/**
+ * Throws unless the leg is well formed. Index loops, not `forEach`: a hole in
+ * a sparse array is skipped by the array methods and would surface later as
+ * a raw `TypeError` instead of a refusal.
+ */
+function validateLeg(leg: unknown, legIndex: number): TvlHistoryLeg {
+    if (typeof leg !== 'object' || leg === null) {
+        throw new TvlHistoryInputError('leg', legIndex);
+    }
+    const { entries, usdRate, opening } = leg as Partial<TvlHistoryLeg>;
+    if (
+        typeof usdRate !== 'number' ||
+        !Number.isFinite(usdRate) ||
+        usdRate <= 0
+    ) {
+        throw new TvlHistoryInputError('usd-rate', legIndex);
+    }
+    if (!Array.isArray(entries as unknown)) {
+        throw new TvlHistoryInputError('entries', legIndex);
+    }
+    const list = entries as readonly unknown[];
+    if (list.length === 0) {
+        throw new TvlHistoryInputError('empty-leg', legIndex);
+    }
+    let previous = -Infinity;
+    for (let index = 0; index < list.length; index += 1) {
+        const entry = list[index];
+        if (typeof entry !== 'object' || entry === null) {
+            throw new TvlHistoryInputError('entry', legIndex, index);
+        }
+        const { timestamp, tvl, kind } = entry as Partial<PoolTvlHistoryEntry>;
+        if (!isNonNegativeFinite(timestamp)) {
+            throw new TvlHistoryInputError('timestamp', legIndex, index);
+        }
+        if (!isNonNegativeFinite(tvl)) {
+            throw new TvlHistoryInputError('tvl', legIndex, index);
+        }
+        if (kind !== 'clearing' && kind !== 'current') {
+            throw new TvlHistoryInputError('kind', legIndex, index);
+        }
+        if (kind === 'current' && index !== list.length - 1) {
+            throw new TvlHistoryInputError('current', legIndex, index);
+        }
+        if (timestamp < previous) {
+            throw new TvlHistoryInputError('order', legIndex, index);
+        }
+        previous = timestamp;
+    }
+    if (opening !== undefined && opening !== null) {
+        const first = list[0] as PoolTvlHistoryEntry;
+        const { timestamp, tvl, kind } = (
+            typeof opening === 'object' ? opening : {}
+        ) as Partial<PoolTvlHistoryEntry>;
+        if (
+            !isNonNegativeFinite(timestamp) ||
+            !isNonNegativeFinite(tvl) ||
+            kind !== 'clearing' ||
+            timestamp > first.timestamp
+        ) {
+            throw new TvlHistoryInputError('opening', legIndex);
+        }
+    }
+    return leg as TvlHistoryLeg;
+}
+
+/**
+ * A strategy's TVL in USD over time, from its deployments' histories — Tax
+ * Pay runs on Base (USDC) and on XDC (AUDD), and its total lent is both.
+ * Pure: the caller fetches each leg (`strategyDeployments` names them) and
+ * passes the exchange rates.
+ *
+ * A step merge by time. At every distinct timestamp where any leg has a
+ * clearing, the value is the sum over legs of that leg's latest point at or
+ * before then, times its `usdRate`. A leg's `opening` — what it held just
+ * before the window — is one more step: it counts from its own timestamp
+ * until the leg's first entry, and the leg is 0 before it (or throughout,
+ * before its first entry, without one).
+ * Points that share a timestamp — clearings run in one block, or two chains
+ * clearing in the same second — are one output point. The series ends with
+ * one `current` point at the latest of the legs' `current` timestamps, equal
+ * to the sum of their `current` values. Every leg must end in a `current`
+ * point, or none may.
+ *
+ * The window is the union of the legs' windows: the series starts at the
+ * earliest first entry of any leg. An `opening` is a value, never a point.
+ * Without it, two windows cut at offset clearing times would count the
+ * later-starting leg 0 at the left edge and draw a false step up; with it,
+ * only a genuine late start (`opening: null`) counts 0.
+ *
+ * Every leg and entry is validated first: a bad input — an empty leg
+ * included — throws `TvlHistoryInputError` (its `code` says why), so the
+ * result never holds `NaN` or `Infinity`. The inputs are not modified.
+ *
+ * ```ts
+ * const window = { count: 52 };
+ * const points = combineTvlHistories([
+ *     { ...(await base.strategies.getPoolTvlHistoryWindow(basePool, window)), usdRate: 1 },
+ *     { ...(await xdc.strategies.getPoolTvlHistoryWindow(xdcPool, window)), usdRate: audToUsd },
+ * ]);
+ * ```
+ */
+export function combineTvlHistories(
+    legs: readonly TvlHistoryLeg[],
+): StrategyTvlHistoryEntry[] {
+    if (!Array.isArray(legs as unknown) || legs.length === 0) {
+        throw new TvlHistoryInputError('legs');
+    }
+    const valid: TvlHistoryLeg[] = [];
+    for (let index = 0; index < legs.length; index += 1) {
+        valid.push(validateLeg(legs[index], index));
+    }
+    const endsInCurrent = valid.map(
+        (leg) => leg.entries[leg.entries.length - 1].kind === 'current',
+    );
+    const odd = endsInCurrent.findIndex((ends) => ends !== endsInCurrent[0]);
+    if (odd !== -1) throw new TvlHistoryInputError('current', odd);
+
+    const finalTimestamp = endsInCurrent[0]
+        ? Math.max(
+              ...valid.map(
+                  (leg) => leg.entries[leg.entries.length - 1].timestamp,
+              ),
+          )
+        : undefined;
+    const clearingTimes = [
+        ...new Set(
+            valid.flatMap((leg) =>
+                leg.entries
+                    .filter((entry) => entry.kind === 'clearing')
+                    .map((entry) => entry.timestamp),
+            ),
+        ),
+    ]
+        .filter((t) => finalTimestamp === undefined || t < finalTimestamp)
+        .sort((a, b) => a - b);
+
+    // One cursor per leg: the times ascend, so each leg is walked once. A
+    // leg's `current` point is a step like any other, which keeps a chain
+    // whose subgraph lags behind the other's last clearing at its own latest.
+    const cursors = valid.map(() => -1);
+    const sumAt = (t: number): number => {
+        let sum = 0;
+        valid.forEach((leg, index) => {
+            let cursor = cursors[index];
+            while (
+                cursor + 1 < leg.entries.length &&
+                leg.entries[cursor + 1].timestamp <= t
+            ) {
+                cursor += 1;
+            }
+            cursors[index] = cursor;
+            // Before the first entry, the opening is the step — from its
+            // own time on, never earlier.
+            const opening = leg.opening;
+            const value =
+                cursor >= 0
+                    ? leg.entries[cursor].tvl
+                    : opening && opening.timestamp <= t
+                      ? opening.tvl
+                      : 0;
+            sum += value * leg.usdRate;
+        });
+        if (!Number.isFinite(sum)) throw new TvlHistoryInputError('overflow');
+        return sum;
+    };
+
+    const combined: StrategyTvlHistoryEntry[] = clearingTimes.map((t) => ({
+        timestamp: t,
+        tvlUsd: sumAt(t),
+        kind: 'clearing' as const,
+    }));
+    if (finalTimestamp !== undefined) {
+        combined.push({
+            timestamp: finalTimestamp,
+            tvlUsd: sumAt(finalTimestamp),
+            kind: 'current',
+        });
+    }
+    return combined;
+}

package/src/facade/index.ts

@@ -19,6 +19,16 @@ export { READ_ONLY_MESSAGE } from './read-only';
 // Chain configurations
 export { CHAIN_CONFIGS } from './chain-configs';
 
+// Strategy ↔ deployment resolution (pure, over CHAIN_CONFIGS)
+export {
+    StrategyDeploymentInputError,
+    strategyDeployments,
+} from './strategy-deployments';
+export type {
+    StrategyDeployment,
+    StrategyDeploymentInputErrorCode,
+} from './strategy-deployments';
+
 // Directus-backed helpers (I/O — not part of `domain/`)
 export { fetchUnusedPoolIds } from './unused-pool-ids';