@kasufinance/kasu-sdk 2.13.0 → 2.14.0

package/dist/bundle.esm.js

@@ -15500,6 +15500,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
@@ -16248,6 +16427,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
@@ -16651,6 +16919,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 (!isAddress(poolId)) {
@@ -16669,33 +16973,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([
@@ -16713,7 +17040,7 @@ class DataService {
                             latest: null,
                         },
                 ]);
-                return buildPoolTvlHistory({
+                const entries = buildPoolTvlHistory({
                     clearings: inWindow,
                     balances,
                     offChain: offChainRead.offChain,
@@ -16727,10 +17054,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;
             }
@@ -18013,14 +18352,13 @@ const currentEpochFtdAmountQuery = gql `
                 user: $userId
                 lendingPool_in: $poolIds
                 epochId: $currentEpoch
+                type: DepositRequest
             }
         ) {
             fixedTermConfigId
             amountRequested
             tranche {
                 id
-                balance
-                shares
             }
         }
     }
@@ -18035,11 +18373,7 @@ const currentFtdBalanceQuery = gql `
                 configId
                 lendingPoolTranche {
                     id
-                }
-            }
-            lendingPool {
-                balance
-                tranches {
+                    balance
                     shares
                 }
             }
@@ -18047,6 +18381,13 @@ const currentFtdBalanceQuery = gql `
     }
 `;
 
+/** Thrown when the subgraph reports a request type with no known unit. */
+const UNKNOWN_REQUEST_TYPE_MESSAGE = 'UserLending: unknown request type, its amount unit is unknown';
+const KNOWN_REQUEST_TYPES = [
+    'DepositRequest',
+    'WithdrawalRequest',
+];
+const isKnownRequestType = (type) => typeof type === 'string' && KNOWN_REQUEST_TYPES.includes(type);
 class UserLending {
     constructor(_kasuConfig, signerOrProvider) {
         this._kasuConfig = _kasuConfig;
@@ -18208,6 +18549,14 @@ class UserLending {
             ]);
             const retn = [];
             for (const userRequest of subgraphResult.userRequests) {
+                // A request type this SDK does not know has no known amount unit
+                // (the schema also declares types no live deployment emits yet).
+                // Skip that ONE row before anything is priced or read on chain,
+                // rather than failing — and blanking — the lender's whole list.
+                if (!isKnownRequestType(userRequest.type)) {
+                    console.error(`${UNKNOWN_REQUEST_TYPE_MESSAGE}: ${String(userRequest.type)} (request ${userRequest.id}); row skipped`);
+                    continue;
+                }
                 const directusPool = directusResult.find(({ id }) => id === userRequest.lendingPool.id);
                 const trancheName = trancheNames[userRequest.lendingPool.tranches.length - 1][parseInt(userRequest.tranche.orderId)];
                 const events = [];
@@ -18303,9 +18652,7 @@ class UserLending {
                         : 'Withdrawal',
                     trancheName: trancheName,
                     trancheId: userRequest.tranche.id,
-                    requestedAmount: parseUnits(userRequest.tranche.shares).isZero()
-                        ? userRequest.amountRequested
-                        : this.convertSharesToAssets(userRequest.amountRequested, userRequest.tranche.balance, userRequest.tranche.shares).toString(),
+                    requestedAmount: this.requestedAmountInAssets(userRequest),
                     acceptedAmount: userRequest.amountAccepted,
                     rejectedAmount: userRequest.amountRejected,
                     status: userRequest.status,
@@ -18338,8 +18685,11 @@ class UserLending {
             for (const userFTD of currentFtdBalance.userLendingPoolTrancheFixedTermDepositLocks) {
                 const ftdID = parseFloat(userFTD.lendingPoolTrancheFixedTermConfig.configId);
                 const trancheID = userFTD.lendingPoolTrancheFixedTermConfig.lendingPoolTranche.id.toLowerCase();
-                const totalSupply = userFTD.lendingPool.tranches.reduce((total, cur) => total.add(parseEther(cur.shares)), BigNumber.from(0));
-                const amount = this.convertSharesToAssets(userFTD.trancheShares, userFTD.lendingPool.balance, formatEther(totalSupply));
+                // The lock holds shares of ONE tranche, so they are worth that
+                // tranche's share price — not the pool's average across tranches,
+                // which differs whenever the tranches have earned differently.
+                const lockTranche = userFTD.lendingPoolTrancheFixedTermConfig.lendingPoolTranche;
+                const amount = this.convertSharesToAssets(userFTD.trancheShares, lockTranche.balance, lockTranche.shares);
                 const item = (_a = trancheMap.get(trancheID)) !== null && _a !== void 0 ? _a : [];
                 if (item[ftdID]) {
                     item[ftdID] += parseFloat(amount);
@@ -18354,25 +18704,40 @@ class UserLending {
     }
     getCurrentEpochFtdAmount(poolIds, userId, currentEpoch) {
         return __awaiter(this, void 0, void 0, function* () {
+            var _a, _b;
             const currentEpochFtdAmountRes = yield this._graph.request(currentEpochFtdAmountQuery, {
                 userId: userId.toLowerCase(),
                 poolIds: poolIds.map((id) => id.toLowerCase()),
                 currentEpoch: parseFloat(currentEpoch),
             });
-            const currentEpochFtdAmounts = new Map();
+            // Deposit requests only (the query filters on type): a deposit's
+            // `amountRequested` is already an ASSET amount, so it is summed as it
+            // is — never put through a share price. Summed, not assigned: a
+            // cancelled request and its replacement share a tranche and a config
+            // in one epoch, and the cancelled one's 0 must not overwrite the live
+            // amount.
+            const totals = new Map();
             for (const userRequest of currentEpochFtdAmountRes.userRequests) {
                 const ftdID = parseFloat(userRequest.fixedTermConfigId);
-                const item = currentEpochFtdAmounts.get(userRequest.tranche.id);
-                const amountRequested = this.convertSharesToAssets(userRequest.amountRequested, userRequest.tranche.balance, userRequest.tranche.shares);
-                if (item) {
-                    const clonedItem = [...item];
-                    clonedItem[ftdID] = amountRequested;
-                    currentEpochFtdAmounts.set(userRequest.tranche.id, clonedItem);
+                if (!Number.isInteger(ftdID) || ftdID < 0)
                     continue;
-                }
+                const perConfig = (_a = totals.get(userRequest.tranche.id)) !== null && _a !== void 0 ? _a : new Map();
+                perConfig.set(ftdID, ((_b = perConfig.get(ftdID)) !== null && _b !== void 0 ? _b : BigNumber.from(0)).add(parseUnits(userRequest.amountRequested)));
+                totals.set(userRequest.tranche.id, perConfig);
+            }
+            // A slot whose total is zero is left out — `'0.0'` is a truthy
+            // string, and a caller testing the slot would read it as an amount.
+            // A tranche with no non-zero slot is left out entirely.
+            const currentEpochFtdAmounts = new Map();
+            for (const [trancheId, perConfig] of totals) {
                 const ftdAmounts = [];
-                ftdAmounts[ftdID] = amountRequested;
-                currentEpochFtdAmounts.set(userRequest.tranche.id, ftdAmounts);
+                for (const [ftdID, total] of perConfig) {
+                    if (total.gt(0))
+                        ftdAmounts[ftdID] = formatUnits(total);
+                }
+                if (ftdAmounts.length) {
+                    currentEpochFtdAmounts.set(trancheId, ftdAmounts);
+                }
             }
             return currentEpochFtdAmounts;
         });
@@ -18393,6 +18758,31 @@ class UserLending {
             return amountMap;
         });
     }
+    /**
+     * A request's outstanding amount in ASSETS (the deployment's stable token).
+     *
+     * The subgraph's `UserRequest.amountRequested` is denominated by request
+     * type. A DEPOSIT request holds assets: the deposit NFT's `assetAmount`,
+     * top-ups added, accepted and rejected amounts taken off. A WITHDRAWAL
+     * request holds tranche SHARES: the withdrawal NFT's `sharesAmount`,
+     * accepted shares taken off. So only a withdrawal is converted, at the
+     * tranche's current share price; a deposit passes through unchanged —
+     * pricing it as shares overstated it by the share price.
+     */
+    requestedAmountInAssets(userRequest) {
+        switch (userRequest.type) {
+            case 'DepositRequest':
+                return userRequest.amountRequested;
+            case 'WithdrawalRequest':
+                return this.convertSharesToAssets(userRequest.amountRequested, userRequest.tranche.balance, userRequest.tranche.shares);
+            default: {
+                // Fail closed: a type this SDK does not know has no known
+                // unit, and pricing it either way would print a wrong figure.
+                const unknownType = userRequest.type;
+                throw new Error(`${UNKNOWN_REQUEST_TYPE_MESSAGE}: ${unknownType}`);
+            }
+        }
+    }
     convertSharesToAssets(sharesAmount, totalAssets, totalSupply) {
         if (parseUnits(totalSupply).isZero())
             return '0';
@@ -25646,9 +26036,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);
     }
 }
@@ -25777,7 +26167,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
@@ -25814,13 +26204,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;
@@ -26472,7 +26862,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
@@ -26481,8 +26871,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) {
@@ -26508,7 +26898,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)
@@ -29137,6 +29527,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.
      */
@@ -29461,17 +29871,24 @@ function cancelDeadline(request, nextEpochStart, nowSeconds) {
 const isCancelled = (events) => events.some((e) => e.requestType === 'Cancelled');
 const isForced = (events) => events.some((e) => e.requestType === 'Forced');
 const initiatedEvent = (events) => events.find((e) => e.requestType === 'Initiated');
-/**
- * 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.
- */
+/** `assetAmount` of the `Initiated` event, or 0 when there is none. */
 const initiatedAmountOf = (events) => {
     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 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 cancelledAmountOf = (events) => {
+    const cancelledEvent = events.find((e) => e.requestType === 'Cancelled');
+    return num(cancelledEvent === null || cancelledEvent === void 0 ? void 0 : cancelledEvent.assetAmount) || initiatedAmountOf(events);
+};
 /**
  * A deposit is REALLOCATED when the timeline carries a `Reallocated` event, or
  * an `Accepted` event into a tranche other than the one requested.
@@ -29496,17 +29913,15 @@ const numOrNull = (str) => {
  * 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
@@ -29534,10 +29949,10 @@ function deriveRequestState(request) {
     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);
@@ -29588,18 +30003,23 @@ function deriveRequestState(request) {
     }
     // 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 Object.assign(Object.assign({}, base), { kind: 'outflow', amount: -accepted, statusCode: 'partial' });
     }
     // 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 Object.assign(Object.assign({}, base), { kind: 'outflow', amount: -accepted, statusCode: partly ? 'partial' : 'complete' });
+            return Object.assign(Object.assign({}, base), { kind: 'outflow', amount: -accepted, statusCode: 'complete' });
         }
         // Deposit: full reject vs partial vs full accept.
         if (accepted === 0) {
@@ -29956,6 +30376,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/';
 /**
@@ -30608,4 +31124,4 @@ function weightedAverageApy(slices) {
     return weighted / totalBalance;
 }
 
-export { APXIUM, AU_ALPHA3, AU_MIN_CUMULATIVE_BY_STABLE, BatchPendingError, BatchRevertedError, BatchSubmissionError, CHAIN_CONFIGS, CLEARING_WINDOW_SECONDS, CONTRACT_TTL_MS, CallsFacade, DAYS_PER_EPOCH, DAYS_PER_MONTH, DEFAULT_BATCH_POLLING_POLICY, DepositBatchMismatchError, DepositFlow, DepositsFacade, ENTRY_POINT_V07, EPOCHS_IN_YEAR, Flow, FlowStore, FlowsFacade, INVALID_ACCEPTANCE_SIGNATURE_MESSAGE, INVALID_AUTH_SIGNATURE_MESSAGE, INVOICEMATE, Kasu, KasuSdk, MAX_LENDING_AMOUNT_FALLBACK, MIN_DAYS_FOR_MONTHS, MIN_LENDING_AMOUNT_FALLBACK, MIN_TRANCHE_CAPACITY, NOT_A_WITHDRAWAL_CALL_MESSAGE, NO_DIRECTUS_URL_MESSAGE, NO_HISTORY_PROVIDER_MESSAGE, NO_KYC_PARAMS_MESSAGE, NO_SPENDER_MESSAGE, NO_WITHDRAWAL_ENCODER_MESSAGE, PastStateUnavailableError, PoolTvlHistoryAbortedError, PoolTvlHistoryTimeoutError, PortfolioFacade, READ_ONLY_MESSAGE, RIXON_CAPITAL, SECONDS_PER_WEEK, SPONSORED_CALL_KINDS, SPONSORED_CALL_SELECTORS, SdkConfig, SponsoredCallInputError, StrategiesFacade, UPPER_MEZZANINE, WithdrawFlow, accruedInterest, aggregateYieldHistory, apyToEpochRate, asContractType, auMinimumRemaining, auThresholdFor, availableFixedTermConfigs, batchOutcomeOf, buildContractVersionType, buildFullNameRequestMessage, buildLegacyContractRequestMessage, buildLoanAgreementSignMessage, cancelDeadline, ceilToCents, checkBatchOutcome, checkSponsoredCallOutcome, classifyWalletFailure, compareTrancheSeniority, computeSettlementWindow, countSubmissions, dailyInterest, decodeRevert, deriveCycleDates, derivePoolStatus, deriveRequestState, encodeCancelDepositCall, encodeCancelWithdrawalCall, encodeDepositData, encodeRequestWithdrawalCall, encodeStableTransfer, encodeWithdrawAtExpiryCall, epochRateToApy, epochTrancheYield, explorerAddressUrl, explorerTxUrl, extractRevertData, fetchUnusedPoolIds, firstSubmissionTimestamp, floorToCents, formatSignTimestampUtc, getCreditOriginator, getInstitutionalLender, getStrategyRegion, getTrancheDisplayName, isAuMinimumExempt, isAustralianKyc, isBelowMinimumCapacity, isCycleClosed, isDefinitivelyNotSubmitted, isFixedTermConfigId, isUnpredictableGas, isUserRejected, lastEventTimestamp, lockDurationDays, lockDurationMonths, maxNetRateCeiling, netEffectiveApy, netTrancheApyBounds, nextCycleBoundary, parseFormattedMessage, parseMinorUnits, parseTrancheBound, pickDefaultTrancheId, pickHighestYieldTranche, pickShortDescription, poolAllTranchesFull, poolMaxApy, poolTvl, projectedAnnualEarnings, proveDepositInReceipt, proveUserOperationInReceipt, resolveBoundShortcuts, resolveDepositBounds, selectVisiblePools, submissionEvents, submitBatch, submitSponsoredCall, trancheApyBounds, trancheHasCapacity, trancheRiskRank, validateDepositBatchCalls, weeklyInterest, weightedAverageApy };
+export { APXIUM, AU_ALPHA3, AU_MIN_CUMULATIVE_BY_STABLE, BatchPendingError, BatchRevertedError, BatchSubmissionError, CHAIN_CONFIGS, CLEARING_WINDOW_SECONDS, CONTRACT_TTL_MS, CallsFacade, DAYS_PER_EPOCH, DAYS_PER_MONTH, DEFAULT_BATCH_POLLING_POLICY, DepositBatchMismatchError, DepositFlow, DepositsFacade, ENTRY_POINT_V07, EPOCHS_IN_YEAR, Flow, FlowStore, FlowsFacade, INVALID_ACCEPTANCE_SIGNATURE_MESSAGE, INVALID_AUTH_SIGNATURE_MESSAGE, INVOICEMATE, Kasu, KasuSdk, MAX_LENDING_AMOUNT_FALLBACK, MIN_DAYS_FOR_MONTHS, MIN_LENDING_AMOUNT_FALLBACK, MIN_TRANCHE_CAPACITY, NOT_A_WITHDRAWAL_CALL_MESSAGE, NO_DIRECTUS_URL_MESSAGE, NO_HISTORY_PROVIDER_MESSAGE, NO_KYC_PARAMS_MESSAGE, NO_SPENDER_MESSAGE, NO_WITHDRAWAL_ENCODER_MESSAGE, PastStateUnavailableError, PoolTvlHistoryAbortedError, PoolTvlHistoryTimeoutError, PortfolioFacade, READ_ONLY_MESSAGE, RIXON_CAPITAL, SECONDS_PER_WEEK, SPONSORED_CALL_KINDS, SPONSORED_CALL_SELECTORS, SdkConfig, SponsoredCallInputError, StrategiesFacade, StrategyDeploymentInputError, TvlHistoryInputError, UPPER_MEZZANINE, WithdrawFlow, accruedInterest, aggregateYieldHistory, apyToEpochRate, asContractType, auMinimumRemaining, auThresholdFor, availableFixedTermConfigs, batchOutcomeOf, buildContractVersionType, buildFullNameRequestMessage, buildLegacyContractRequestMessage, buildLoanAgreementSignMessage, cancelDeadline, ceilToCents, checkBatchOutcome, checkSponsoredCallOutcome, classifyWalletFailure, combineTvlHistories, compareTrancheSeniority, computeSettlementWindow, countSubmissions, dailyInterest, decodeRevert, deriveCycleDates, derivePoolStatus, deriveRequestState, encodeCancelDepositCall, encodeCancelWithdrawalCall, encodeDepositData, encodeRequestWithdrawalCall, encodeStableTransfer, encodeWithdrawAtExpiryCall, epochRateToApy, epochTrancheYield, explorerAddressUrl, explorerTxUrl, extractRevertData, fetchUnusedPoolIds, firstSubmissionTimestamp, floorToCents, formatSignTimestampUtc, getCreditOriginator, getInstitutionalLender, getStrategyRegion, getTrancheDisplayName, isAuMinimumExempt, isAustralianKyc, isBelowMinimumCapacity, isCycleClosed, isDefinitivelyNotSubmitted, isFixedTermConfigId, isUnpredictableGas, isUserRejected, lastEventTimestamp, lockDurationDays, lockDurationMonths, maxNetRateCeiling, netEffectiveApy, netTrancheApyBounds, nextCycleBoundary, parseFormattedMessage, parseMinorUnits, parseTrancheBound, pickDefaultTrancheId, pickHighestYieldTranche, pickShortDescription, poolAllTranchesFull, poolMaxApy, poolTvl, projectedAnnualEarnings, proveDepositInReceipt, proveUserOperationInReceipt, resolveBoundShortcuts, resolveDepositBounds, selectVisiblePools, strategyDeployments, submissionEvents, submitBatch, submitSponsoredCall, trancheApyBounds, trancheHasCapacity, trancheRiskRank, validateDepositBatchCalls, weeklyInterest, weightedAverageApy };