@kasufinance/kasu-sdk 2.13.0 → 2.14.0

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/domain/requests.ts

@@ -82,10 +82,13 @@ export interface RequestState {
     statusCode: RequestStatusCode;
     kind: RequestKind;
     /**
-     * The amount originally asked for, always positive. A cancelled request
-     * has its on-request `requestedAmount` zeroed by the subgraph, so the
-     * original is recovered from the `Initiated` event (see
-     * `initiatedAmount`).
+     * `UserRequest.requestedAmount`, in assets: the amount still OUTSTANDING,
+     * which the subgraph reduces as parts are accepted or rejected (0 once a
+     * request is fully resolved). A cancelled request has it zeroed by the
+     * subgraph, so for a cancellation it is the `Cancelled` event's amount —
+     * what was outstanding when cancelled, top-ups included — falling back to
+     * the `Initiated` event (see `initiatedAmount`) only when that event
+     * carries none.
      */
     requestedAmount: number;
     /**
@@ -287,16 +290,24 @@ const initiatedEvent = (
 ): UserRequestEvent | undefined =>
     events.find((e) => e.requestType === 'Initiated');
 
+/** `assetAmount` of the `Initiated` event, or 0 when there is none. */
+const initiatedAmountOf = (events: UserRequestEvent[]): number => {
+    const initiated = initiatedEvent(events);
+    return initiated ? Number(initiated.assetAmount || '0') : 0;
+};
+
 /**
  * Subgraph behaviour: when a request is cancelled, the on-request
  * `requestedAmount` field is reset to 0 (the lender's effective balance is
- * restored). The original amount survives on the `Initiated` event's
- * `assetAmount`. Recover from there so cancelled rows still carry the amount
- * the lender originally asked for.
+ * restored). The amount cancelled survives on the `Cancelled` event's
+ * `assetAmount` — everything still outstanding at the cancel, top-ups
+ * included. Only when that event carries no figure does this fall back to the
+ * `Initiated` event, which holds the FIRST submission alone and so misses
+ * every top-up.
  */
-const initiatedAmountOf = (events: UserRequestEvent[]): number => {
-    const initiated = initiatedEvent(events);
-    return initiated ? Number(initiated.assetAmount || '0') : 0;
+const cancelledAmountOf = (events: UserRequestEvent[]): number => {
+    const cancelledEvent = events.find((e) => e.requestType === 'Cancelled');
+    return num(cancelledEvent?.assetAmount) || initiatedAmountOf(events);
 };
 
 /**
@@ -332,17 +343,15 @@ const numOrNull = (str: string | null | undefined): number | null => {
  * Convert a `UserRequest` into a `RequestState`. Pure — no clock, no network,
  * no copy.
  *
- * BRANCH ORDER (this IS the behaviour; it reproduces kasu-ui's
- * `deriveTransactionView` check for check):
+ * BRANCH ORDER (this IS the behaviour):
  *
  *   1. a `Cancelled` event                      → `cancelled`, neutral, 0
  *   2. a withdrawal with a `Forced` event       → `forced`, outflow, −accepted
  *   3. a reallocated deposit                    → `reallocated`, inflow, +accepted
- *   4. a withdrawal partly filled with a LIVE
- *      remainder (cycle still open)             → `partial`, outflow, −accepted
+ *   4. a withdrawal partly filled (paid > 0) with
+ *      a LIVE remainder (queued > 0, cycle open) → `partial`, outflow, −accepted
  *   5. resolved (`status === 'Processed'`):
- *        withdrawal, partly filled              → `partial`, outflow, −accepted
- *        withdrawal, fully filled               → `complete`, outflow, −accepted
+ *        withdrawal (nothing left queued)       → `complete`, outflow, −accepted
  *        deposit, nothing accepted              → `rejected`, neutral, 0
  *        deposit, part rejected                 → `partial`, inflow, +accepted
  *        deposit, fully accepted                → `complete`, inflow, +accepted
@@ -369,10 +378,10 @@ export function deriveRequestState(request: UserRequest): RequestState {
     const isWithdrawal = request.requestType === 'Withdrawal';
     const cancelled = isCancelled(request.events);
     // Cancelled requests have `requestedAmount` zeroed on the request itself;
-    // pull the original value from the Initiated event so the row still
-    // carries "100 cancelled" instead of "0 cancelled".
+    // take the amount from the Cancelled event so the row still carries
+    // "1500 cancelled" (1000 + a 500 top-up) instead of "0 cancelled".
     const requested = cancelled
-        ? num(request.requestedAmount) || initiatedAmountOf(request.events)
+        ? num(request.requestedAmount) || cancelledAmountOf(request.events)
         : num(request.requestedAmount);
     const accepted = num(request.acceptedAmount);
     const rejected = num(request.rejectedAmount);
@@ -441,11 +450,14 @@ export function deriveRequestState(request: UserRequest): RequestState {
 
     // 4. Withdrawal partly filled with a LIVE remainder: the request returns
     // to the queue with a live Cancel. Checked BEFORE the resolved branch and
-    // via `isCycleClosed`, never via the sticky raw status.
+    // via `isCycleClosed`, never via the sticky raw status. `requested` is
+    // what is still OUTSTANDING, so "partly filled" is "something paid AND
+    // something still queued" — never a comparison of the two, which would
+    // turn on whether more was paid than is left.
     if (
         isWithdrawal &&
         accepted > 0 &&
-        accepted < requested &&
+        requested > 0 &&
         !isCycleClosed(request)
     ) {
         return {
@@ -458,13 +470,15 @@ export function deriveRequestState(request: UserRequest): RequestState {
 
     // 5. Resolved — a rejection IS a resolution.
     if (request.status === UserRequestStatus.PROCESSED) {
+        // A withdrawal is resolved only once nothing is left queued — a
+        // partly filled one returns to the queue (branch 4), and one cancelled
+        // with a remainder is branch 1 — so a resolved withdrawal is complete.
         if (isWithdrawal) {
-            const partly = accepted < requested;
             return {
                 ...base,
                 kind: 'outflow',
                 amount: -accepted,
-                statusCode: partly ? 'partial' : 'complete',
+                statusCode: 'complete',
             };
         }
 

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';
 

package/src/facade/strategies.ts

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

package/src/facade/strategy-deployments.ts

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

package/src/index.ts

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