@kasufinance/kasu-sdk 2.13.1 → 2.14.0

package/dist/bundle.cjs.js

@@ -15502,6 +15502,185 @@ KasuPoolExternalTVLAbi__factory.abi = _abi;
 function poolTvl(onChainBalance, offChainTvl) {
     return parseFloat(onChainBalance) + parseFloat(offChainTvl);
 }
+/**
+ * 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.
+ */
+class TvlHistoryInputError extends Error {
+    constructor(code, leg, entry) {
+        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) {
+    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, legIndex) {
+    if (typeof leg !== 'object' || leg === null) {
+        throw new TvlHistoryInputError('leg', legIndex);
+    }
+    const { entries, usdRate, opening } = leg;
+    if (typeof usdRate !== 'number' ||
+        !Number.isFinite(usdRate) ||
+        usdRate <= 0) {
+        throw new TvlHistoryInputError('usd-rate', legIndex);
+    }
+    if (!Array.isArray(entries)) {
+        throw new TvlHistoryInputError('entries', legIndex);
+    }
+    const list = entries;
+    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;
+        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];
+        const { timestamp, tvl, kind } = (typeof opening === 'object' ? opening : {});
+        if (!isNonNegativeFinite(timestamp) ||
+            !isNonNegativeFinite(tvl) ||
+            kind !== 'clearing' ||
+            timestamp > first.timestamp) {
+            throw new TvlHistoryInputError('opening', legIndex);
+        }
+    }
+    return leg;
+}
+/**
+ * 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 },
+ * ]);
+ * ```
+ */
+function combineTvlHistories(legs) {
+    if (!Array.isArray(legs) || legs.length === 0) {
+        throw new TvlHistoryInputError('legs');
+    }
+    const valid = [];
+    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) => {
+        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 = clearingTimes.map((t) => ({
+        timestamp: t,
+        tvlUsd: sumAt(t),
+        kind: 'clearing',
+    }));
+    if (finalTimestamp !== undefined) {
+        combined.push({
+            timestamp: finalTimestamp,
+            tvlUsd: sumAt(finalTimestamp),
+            kind: 'current',
+        });
+    }
+    return combined;
+}
 
 /**
  * Epochs in a year — the single source of truth for every rate conversion in
@@ -16250,6 +16429,95 @@ function fetchPoolClearings(request, poolId, scope, cancellation) {
         return { clearings, snapshot, requests };
     });
 }
+/**
+ * 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`.
+ */
+function pickOpeningClearing(before, inWindow) {
+    const firstBlock = Math.min(...inWindow.map((c) => c.block));
+    let opening = null;
+    for (const clearing of before) {
+        if (clearing.block >= firstBlock)
+            continue;
+        if (opening === null ||
+            clearing.block > opening.block ||
+            (clearing.block === opening.block &&
+                clearing.epochId > opening.epochId)) {
+            opening = clearing;
+        }
+    }
+    return opening;
+}
+/**
+ * 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.
+ */
+function needsClearingBeforeBlock(before, opening) {
+    return opening === null && before.length > 0;
+}
+/**
+ * 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.
+ */
+const poolTvlClearingBeforeBlockQuery = gql `
+    query PoolTvlClearingBeforeBlock($pool: String!, $blockLt: BigInt!) {
+        clearings: lendingPoolClearings(
+            first: 1
+            orderBy: endBlockNumber
+            orderDirection: desc
+            where: {
+                lendingPool: $pool
+                isFinished: true
+                endBlockNumber_lt: $blockLt
+            }
+        ) {
+            epochId
+            endBlockNumber
+            endTimestamp
+        }
+    }
+`;
+function fetchClearingBeforeBlock(request, poolId, blockLt, cancellation) {
+    return __awaiter(this, void 0, void 0, function* () {
+        cancellation.throwIfCancelled();
+        const page = yield request(poolTvlClearingBeforeBlockQuery, { pool: poolId, blockLt: String(blockLt) }, cancellation.signal);
+        const row = page.clearings.at(0);
+        return row === undefined ? null : parseClearing(row);
+    });
+}
+/**
+ * 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.
+ */
+function fetchClearingBefore(request, poolId, beforeEpoch, cancellation) {
+    return __awaiter(this, void 0, void 0, function* () {
+        cancellation.throwIfCancelled();
+        const page = yield request(poolTvlClearingsQuery, {
+            poolId,
+            pool: poolId,
+            epochGte: '0',
+            epochLt: String(beforeEpoch),
+            direction: 'desc',
+            first: 1,
+            withSnapshot: false,
+        }, cancellation.signal);
+        const row = page.clearings.at(0);
+        return row === undefined ? null : parseClearing(row);
+    });
+}
 /**
  * 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
@@ -16653,6 +16921,42 @@ class DataService {
      */
     getPoolTvlHistory(poolId_1) {
         return __awaiter(this, arguments, void 0, function* (poolId, options = {}) {
+            return (yield this._poolTvlHistory(poolId, options, false)).entries;
+        });
+    }
+    /**
+     * `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_1) {
+        return __awaiter(this, arguments, void 0, function* (poolId, options = {}) {
+            return yield this._poolTvlHistory(poolId, options, true);
+        });
+    }
+    _poolTvlHistory(poolId, options, withOpening) {
+        return __awaiter(this, void 0, void 0, function* () {
             var _a;
             validatePoolTvlHistoryOptions(options);
             if (!utils$2.isAddress(poolId)) {
@@ -16671,33 +16975,56 @@ class DataService {
                     rpcs,
                     cancellation,
                 })
-                : null, externalTvl !== null && externalTvl !== void 0 ? externalTvl : '', cancellation));
+                : null, externalTvl !== null && externalTvl !== void 0 ? externalTvl : '', cancellation, withOpening));
         });
     }
-    _readPoolTvlHistory(pool, options, reader, externalTvl, cancellation) {
+    _readPoolTvlHistory(pool, options, reader, externalTvl, cancellation, withOpening) {
         return __awaiter(this, void 0, void 0, function* () {
             var _a, _b, _c;
+            const nothing = { entries: [], opening: null };
             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: 'newest',
+                    // One past the window: the opening, when there is one.
+                    count: options.count + (withOpening ? 1 : 0),
+                }
                 : { kind: 'from', fromEpoch: (_a = options.fromEpoch) !== null && _a !== void 0 ? _a : 0 };
             try {
-                const [currentEpochNumber, { clearings, snapshot }] = yield Promise.all([
+                const [currentEpochNumber, { clearings, snapshot }, before] = yield Promise.all([
                     this._systemVariablesAbi.currentEpochNumber(),
                     fetchPoolClearings(graph, pool, scope, cancellation),
+                    withOpening && scope.kind === 'from' && scope.fromEpoch > 0
+                        ? fetchClearingBefore(graph, pool, scope.fromEpoch, cancellation)
+                        : Promise.resolve(null),
                 ]);
                 const currentEpoch = currentEpochNumber.toNumber();
                 const window = resolvePoolTvlHistoryWindow(options, currentEpoch);
                 const poolNow = snapshot.pool;
                 if (!window || !poolNow)
-                    return [];
+                    return nothing;
                 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);
+                // Clearings the window left out, older by epoch: the extra row of
+                // a count fetch, or the one-row read below `fromEpoch`.
+                const older = scope.kind === 'newest'
+                    ? clearings.filter((c) => c.epochId < window.fromEpoch)
+                    : before === null
+                        ? []
+                        : [before];
+                let opening = withOpening
+                    ? pickOpeningClearing(older, inWindow)
+                    : null;
+                // The left-out clearings all sat in the first in-window block (a
+                // catch-up block): ask for the newest one before it, by block.
+                if (withOpening && needsClearingBeforeBlock(older, opening)) {
+                    opening = yield fetchClearingBeforeBlock(graph, pool, Math.min(...inWindow.map((c) => c.block)), cancellation);
+                }
+                const blocks = distinctBlocks(opening ? [...inWindow, opening] : inWindow);
                 const withCurrent = window.toEpoch >= currentEpoch;
                 const cacheable = (block) => block <= head.number - TVL_HISTORY_CACHE_DEPTH;
                 const [balances, offChainRead] = yield Promise.all([
@@ -16715,7 +17042,7 @@ class DataService {
                             latest: null,
                         },
                 ]);
-                return buildPoolTvlHistory({
+                const entries = buildPoolTvlHistory({
                     clearings: inWindow,
                     balances,
                     offChain: offChainRead.offChain,
@@ -16729,10 +17056,22 @@ class DataService {
                         : null,
                     decimals: this._kasuConfig.stableAssetDecimals,
                 });
+                // The same function as every other point, so the opening cannot
+                // be computed another way.
+                const [openingEntry] = opening
+                    ? buildPoolTvlHistory({
+                        clearings: [opening],
+                        balances,
+                        offChain: offChainRead.offChain,
+                        current: null,
+                        decimals: this._kasuConfig.stableAssetDecimals,
+                    })
+                    : [null];
+                return { entries, opening: openingEntry };
             }
             catch (error) {
                 if (isEmptyHistoryError(error, this._kasuConfig.isLiteDeployment)) {
-                    return [];
+                    return nothing;
                 }
                 throw error;
             }
@@ -25699,9 +26038,9 @@ class SponsoredCallInputError extends Error {
         Object.setPrototypeOf(this, SponsoredCallInputError.prototype);
     }
 }
-const ADDRESS_RE$2 = /^0x[0-9a-fA-F]{40}$/;
+const ADDRESS_RE$3 = /^0x[0-9a-fA-F]{40}$/;
 function assertAddress(value, code) {
-    if (typeof value !== 'string' || !ADDRESS_RE$2.test(value)) {
+    if (typeof value !== 'string' || !ADDRESS_RE$3.test(value)) {
         throw new SponsoredCallInputError(code);
     }
 }
@@ -25830,7 +26169,7 @@ function encodeStableTransfer(input) {
     };
 }
 
-const ADDRESS_RE$1 = /^0x[0-9a-fA-F]{40}$/;
+const ADDRESS_RE$2 = /^0x[0-9a-fA-F]{40}$/;
 /**
  * Encoded, ready-to-sponsor `LendingPoolManager` calls — read, then encode,
  * NEVER send. Each returns `{ kind, call }`: post `kind` and `[call]` to a
@@ -25867,13 +26206,13 @@ class CallsFacade {
     requestWithdrawal(params) {
         return __awaiter(this, void 0, void 0, function* () {
             const { poolId, trancheId, amount, userAddress } = params;
-            if (typeof userAddress !== 'string' || !ADDRESS_RE$1.test(userAddress)) {
+            if (typeof userAddress !== 'string' || !ADDRESS_RE$2.test(userAddress)) {
                 throw new SponsoredCallInputError('user');
             }
-            if (typeof poolId !== 'string' || !ADDRESS_RE$1.test(poolId)) {
+            if (typeof poolId !== 'string' || !ADDRESS_RE$2.test(poolId)) {
                 throw new SponsoredCallInputError('pool');
             }
-            if (typeof trancheId !== 'string' || !ADDRESS_RE$1.test(trancheId)) {
+            if (typeof trancheId !== 'string' || !ADDRESS_RE$2.test(trancheId)) {
                 throw new SponsoredCallInputError('tranche');
             }
             let shares;
@@ -26525,7 +26864,7 @@ const BEFORE_EXECUTION = ENTRY_POINT_EVENTS.getEventTopic('BeforeExecution');
 const DEPOSIT_REQUESTED = PENDING_POOL_EVENTS.getEventTopic('DepositRequested');
 const ERC20$1 = IERC20MetadataAbi__factory.createInterface();
 const LENDING_POOL_MANAGER$1 = ILendingPoolManagerAbi__factory.createInterface();
-const ADDRESS_RE = /^0x[0-9a-fA-F]{40}$/;
+const ADDRESS_RE$1 = /^0x[0-9a-fA-F]{40}$/;
 /**
  * Case-insensitive address equality; `false` for anything that is not a
  * 20-byte hex address. Checksums are not enforced — an all-lowercase address
@@ -26534,8 +26873,8 @@ const ADDRESS_RE = /^0x[0-9a-fA-F]{40}$/;
 function sameAddress(a, b) {
     return (typeof a === 'string' &&
         typeof b === 'string' &&
-        ADDRESS_RE.test(a) &&
-        ADDRESS_RE.test(b) &&
+        ADDRESS_RE$1.test(a) &&
+        ADDRESS_RE$1.test(b) &&
         a.toLowerCase() === b.toLowerCase());
 }
 function isHexData(value) {
@@ -26561,7 +26900,7 @@ function isCallShape(call) {
     if (call === null || typeof call !== 'object')
         return false;
     const { to, data } = call;
-    return typeof to === 'string' && ADDRESS_RE.test(to) && isHexData(data);
+    return typeof to === 'string' && ADDRESS_RE$1.test(to) && isHexData(data);
 }
 function isZeroValue(value) {
     if (value === undefined)
@@ -29190,6 +29529,26 @@ class StrategiesFacade {
             return yield 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 }
+     * ```
+     */
+    getPoolTvlHistoryWindow(poolId_1) {
+        return __awaiter(this, arguments, void 0, function* (poolId, options = {}) {
+            return yield this._dataService.getPoolTvlHistoryWindow(poolId, options);
+        });
+    }
     /**
      * Fetch a single strategy by pool ID. Returns `null` if not found.
      */
@@ -30019,6 +30378,102 @@ function normaliseMapping(mapping) {
     return out;
 }
 
+/** What `strategyDeployments` throws for an id it cannot place. */
+class StrategyDeploymentInputError extends Error {
+    constructor(code) {
+        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 = 'base';
+const ADDRESS_RE = /^0x[0-9a-f]{40}$/;
+/** The deployment's mapping with both sides lowercased; Base never has one. */
+function mappingOf(configs, chain) {
+    var _a;
+    if (chain === CANONICAL_CHAIN)
+        return [];
+    return Object.entries((_a = configs[chain].poolMetadataMapping) !== null && _a !== void 0 ? _a : {}).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.
+ */
+function resolveStrategyDeployments(configs, poolId, chain) {
+    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);
+    const mappings = chains.map((c) => [c, mappingOf(configs, c)]);
+    const isLocalElsewhere = mappings.some(([c, mapping]) => c !== chain && mapping.some(([local]) => local === id));
+    let canonical;
+    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 = [
+        { 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…' }]
+ * ```
+ */
+function strategyDeployments(poolId, chain) {
+    return resolveStrategyDeployments(CHAIN_CONFIGS, poolId, chain);
+}
+
 /** Directus instance holding Kasu's pool editorial content. */
 const DEFAULT_DIRECTUS_URL = 'https://kasu-finance.directus.app/';
 /**
@@ -30719,6 +31174,8 @@ exports.SPONSORED_CALL_SELECTORS = SPONSORED_CALL_SELECTORS;
 exports.SdkConfig = SdkConfig;
 exports.SponsoredCallInputError = SponsoredCallInputError;
 exports.StrategiesFacade = StrategiesFacade;
+exports.StrategyDeploymentInputError = StrategyDeploymentInputError;
+exports.TvlHistoryInputError = TvlHistoryInputError;
 exports.UPPER_MEZZANINE = UPPER_MEZZANINE;
 exports.WithdrawFlow = WithdrawFlow;
 exports.accruedInterest = accruedInterest;
@@ -30738,6 +31195,7 @@ exports.ceilToCents = ceilToCents;
 exports.checkBatchOutcome = checkBatchOutcome;
 exports.checkSponsoredCallOutcome = checkSponsoredCallOutcome;
 exports.classifyWalletFailure = classifyWalletFailure;
+exports.combineTvlHistories = combineTvlHistories;
 exports.compareTrancheSeniority = compareTrancheSeniority;
 exports.computeSettlementWindow = computeSettlementWindow;
 exports.countSubmissions = countSubmissions;
@@ -30795,6 +31253,7 @@ exports.proveUserOperationInReceipt = proveUserOperationInReceipt;
 exports.resolveBoundShortcuts = resolveBoundShortcuts;
 exports.resolveDepositBounds = resolveDepositBounds;
 exports.selectVisiblePools = selectVisiblePools;
+exports.strategyDeployments = strategyDeployments;
 exports.submissionEvents = submissionEvents;
 exports.submitBatch = submitBatch;
 exports.submitSponsoredCall = submitSponsoredCall;