@kasufinance/kasu-sdk 2.11.0 → 2.13.0

package/dist/bundle.esm.js

@@ -1,5 +1,5 @@
-import { formatUnits, parseUnits, formatEther, defaultAbiCoder, parseEther } from 'ethers/lib/utils';
-import { utils as utils$2, Contract, BigNumber, ethers, constants, Signer, providers } from 'ethers';
+import { utils as utils$2, Contract, BigNumber, providers, ethers, constants, Signer } from 'ethers';
+import { Interface, formatUnits, isAddress, parseUnits, formatEther, defaultAbiCoder, parseEther } from 'ethers/lib/utils';
 
 const defaultJsonSerializer = JSON;
 
@@ -15479,6 +15479,28 @@ class KasuPoolExternalTVLAbi__factory {
 }
 KasuPoolExternalTVLAbi__factory.abi = _abi;
 
+/**
+ * A pool's TVL — the total lent into it by everyone — and the shape of its
+ * history. Pure: the reads live in `services/DataService/tvl-history.ts`.
+ */
+/**
+ * The ONE definition of a pool's TVL: what lenders have lent on chain
+ * (`lendingPool.balance` in the subgraph) plus the off-chain amount the
+ * pool's `ExternalTVL` contract records (`externalTVLOfPool`).
+ *
+ * Both inputs, and the result, are in DISPLAY units of the deployment's own
+ * stable token (USDC on Base and XDC USDC, AUDD on XDC AUDD) — `'1.5'` is
+ * one and a half tokens, not 1.5 minor units. Convert before formatting as
+ * USD.
+ *
+ * `getPoolOverview` (its `totalValueLocked.total`) and `getPoolTvlHistory`
+ * (every point) both call this, so the chart and the figure above it cannot
+ * be computed two ways.
+ */
+function poolTvl(onChainBalance, offChainTvl) {
+    return parseFloat(onChainBalance) + parseFloat(offChainTvl);
+}
+
 /**
  * Epochs in a year — the single source of truth for every rate conversion in
  * the SDK and in every consumer that undoes one.
@@ -15718,6 +15740,36 @@ function filterArray(array, id_in) {
         });
     }
 }
+/**
+ * A GraphQL VALIDATION error naming an entity, field or argument this
+ * deployment's subgraph does not have. A network error, a timeout or an
+ * indexing error is not one.
+ */
+function isMissingEntityError(error) {
+    if (typeof error !== 'object' || error === null)
+        return false;
+    const response = error.response;
+    const errors = response === null || response === void 0 ? void 0 : response.errors;
+    if (!Array.isArray(errors) || errors.length === 0)
+        return false;
+    return errors.every((e) => {
+        const message = e === null || e === void 0 ? void 0 : e.message;
+        return (typeof message === 'string' &&
+            /has no field|cannot query field|unknown (type|field|argument)|no such (type|field)/i.test(message));
+    });
+}
+/**
+ * The only failure a history read (`getYieldHistory`, `getPoolTvlHistory`)
+ * turns into `[]`: a missing-schema error
+ * on a LITE deployment, whose subgraph may predate the entities. On a full
+ * deployment the entities are part of the schema, so the same error means a
+ * broken query or subgraph and THROWS — an empty chart there would hide it.
+ * Everything else (network, timeout, indexing) throws on every deployment, so
+ * a consumer can tell "no history here" from "history unavailable".
+ */
+function isEmptyHistoryError(error, liteDeployment) {
+    return liteDeployment && isMissingEntityError(error);
+}
 
 /**
  * The error a CMS-only call raises on a deployment configured without
@@ -15907,11 +15959,569 @@ const getLendingPoolWithdrawalAndDepositsQuery = gql `
     }
 `;
 
+/** Clearings per subgraph page (the subgraph's own row cap). */
+const TVL_HISTORY_PAGE_SIZE = 1000;
+/**
+ * A runaway guard on the clearings pagination, not a working limit: a pool
+ * clears once per epoch, so 20 pages would be twenty thousand cycles.
+ */
+const TVL_HISTORY_MAX_PAGES = 20;
+/**
+ * How many past blocks one time-travel request reads, as GraphQL aliases. A
+ * pool with ~120 clearings costs two such requests.
+ */
+const TVL_HISTORY_BLOCKS_PER_REQUEST = 100;
+/** At most this many past-state RPC reads are in flight at once. */
+const TVL_HISTORY_RPC_CONCURRENCY = 8;
+/** Attempts per past-state RPC read (each over every history RPC in turn). */
+const TVL_HISTORY_RPC_ATTEMPTS = 3;
+/** Back-off before the second attempt; doubled for each one after. */
+const TVL_HISTORY_RPC_RETRY_DELAY_MS = 500;
+/** Per-call timeout of the history providers the SDK builds itself. */
+const TVL_HISTORY_RPC_TIMEOUT_MS = 10000;
+/** Default `timeoutMs` of a whole `getPoolTvlHistory` call. */
+const TVL_HISTORY_DEFAULT_TIMEOUT_MS = 30000;
+/**
+ * Blocks at least this far below the subgraph's head are treated as final
+ * and their reads are cached; nearer ones are read again every time.
+ */
+const TVL_HISTORY_CACHE_DEPTH = 64;
+/** Entries per SDK instance before the cache starts again from empty. */
+const TVL_HISTORY_CACHE_LIMIT = 20000;
+/** `getPoolTvlHistory` took longer than its `timeoutMs`. */
+class PoolTvlHistoryTimeoutError extends Error {
+    constructor(timeoutMs) {
+        super(`getPoolTvlHistory: timed out after ${String(timeoutMs)} ms`);
+        this.timeoutMs = timeoutMs;
+        this.name = 'PoolTvlHistoryTimeoutError';
+    }
+}
+/** `getPoolTvlHistory` was abandoned through its `signal`. */
+class PoolTvlHistoryAbortedError extends Error {
+    constructor() {
+        super('getPoolTvlHistory: aborted');
+        this.name = 'PoolTvlHistoryAbortedError';
+    }
+}
+/**
+ * A history provider answered a past block as if nothing were deployed — no
+ * code even for the pool, which cleared in that very block. A pruned node
+ * does that; trusting it would draw the off-chain TVL as 0.
+ */
+class PastStateUnavailableError extends Error {
+    constructor(block) {
+        super(`getPoolTvlHistory: history provider does not serve past state (no code for the pool at block ${String(block)}, where it cleared)`);
+        this.block = block;
+        this.name = 'PastStateUnavailableError';
+    }
+}
+/**
+ * Throws `RangeError` / `TypeError` on a malformed option.
+ * `getPoolTvlHistory` calls it ONCE, BEFORE any network read;
+ * `resolvePoolTvlHistoryWindow` assumes it has run.
+ */
+function validatePoolTvlHistoryOptions(options) {
+    const { fromEpoch, count, timeoutMs, signal } = options;
+    if (fromEpoch !== undefined &&
+        (!Number.isSafeInteger(fromEpoch) || fromEpoch < 0)) {
+        throw new RangeError(`getPoolTvlHistory: fromEpoch must be a non-negative integer, got ${String(fromEpoch)}`);
+    }
+    if (count !== undefined && (!Number.isSafeInteger(count) || count < 1)) {
+        throw new RangeError(`getPoolTvlHistory: count must be a positive integer, got ${String(count)}`);
+    }
+    if (timeoutMs !== undefined &&
+        (typeof timeoutMs !== 'number' ||
+            !Number.isFinite(timeoutMs) ||
+            timeoutMs <= 0)) {
+        throw new RangeError(`getPoolTvlHistory: timeoutMs must be a positive number, got ${String(timeoutMs)}`);
+    }
+    if (signal !== undefined &&
+        (typeof signal !== 'object' ||
+            typeof signal.aborted !== 'boolean')) {
+        throw new TypeError('getPoolTvlHistory: signal must be an AbortSignal');
+    }
+}
+/** The epoch window. Options must already have passed validation. */
+function resolvePoolTvlHistoryWindow(options, currentEpoch) {
+    const { fromEpoch, count } = options;
+    let from;
+    let to = currentEpoch;
+    if (fromEpoch !== undefined) {
+        from = fromEpoch;
+        if (count !== undefined) {
+            to = Math.min(currentEpoch, fromEpoch + count - 1);
+        }
+    }
+    else {
+        from = count !== undefined ? Math.max(0, currentEpoch - count + 1) : 0;
+    }
+    return from > to ? null : { fromEpoch: from, toEpoch: to };
+}
+/**
+ * Runs `work` under a deadline and an optional caller signal. Whichever comes
+ * first rejects the returned promise with its typed error at once, aborts
+ * `cancellation.signal` (cancelling in-flight subgraph requests) and makes
+ * every later `throwIfCancelled()` throw, so no new read starts. An RPC call
+ * already sent cannot be recalled; its answer is dropped.
+ */
+function runCancellable(timeoutMs, external, work) {
+    return __awaiter(this, void 0, void 0, function* () {
+        if (external === null || external === void 0 ? void 0 : external.aborted)
+            throw new PoolTvlHistoryAbortedError();
+        const controller = new AbortController();
+        let reason;
+        let rejectCancelled = () => undefined;
+        const cancelled = new Promise((_, reject) => {
+            rejectCancelled = reject;
+        });
+        const cancel = (error) => {
+            if (reason)
+                return;
+            reason = error;
+            controller.abort();
+            rejectCancelled(error);
+        };
+        const timer = setTimeout(() => {
+            cancel(new PoolTvlHistoryTimeoutError(timeoutMs));
+        }, timeoutMs);
+        const onAbort = () => {
+            cancel(new PoolTvlHistoryAbortedError());
+        };
+        external === null || external === void 0 ? void 0 : external.addEventListener('abort', onAbort);
+        const cancellation = {
+            signal: controller.signal,
+            throwIfCancelled: () => {
+                if (reason)
+                    throw reason;
+            },
+        };
+        try {
+            const running = work(cancellation);
+            // The losing side must never surface as an unhandled rejection.
+            running.catch(() => undefined);
+            return yield Promise.race([running, cancelled]);
+        }
+        finally {
+            clearTimeout(timer);
+            external === null || external === void 0 ? void 0 : external.removeEventListener('abort', onAbort);
+        }
+    });
+}
+// ---------------------------------------------------------------------------
+// Subgraph reads
+// ---------------------------------------------------------------------------
+/** Above any epoch number: "no upper bound" for the clearings query. */
+const NO_EPOCH_BOUND = '1000000000000';
+/**
+ * The pool's FINISHED clearings, plus — on the first page only — its balance
+ * now and the subgraph's latest block.
+ *
+ * Two modes over one document: ascending from `$epochGte` (a `fromEpoch`
+ * window, or everything), or descending below `$epochLt` (the newest N, for
+ * a `count`-only window, so it never pages through the whole history).
+ */
+const poolTvlClearingsQuery = gql `
+    query PoolTvlClearings(
+        $poolId: ID!
+        $pool: String!
+        $epochGte: BigInt!
+        $epochLt: BigInt!
+        $direction: OrderDirection!
+        $first: Int!
+        $withSnapshot: Boolean!
+    ) {
+        clearings: lendingPoolClearings(
+            first: $first
+            orderBy: epochId
+            orderDirection: $direction
+            where: {
+                lendingPool: $pool
+                isFinished: true
+                epochId_gte: $epochGte
+                epochId_lt: $epochLt
+            }
+        ) {
+            epochId
+            endBlockNumber
+            endTimestamp
+        }
+        pool: lendingPool(id: $poolId) @include(if: $withSnapshot) {
+            balance
+        }
+        meta: _meta @include(if: $withSnapshot) {
+            block {
+                number
+                timestamp
+            }
+        }
+    }
+`;
+/** The time-travel alias for one block: `b<block>`. */
+function blockAlias(block) {
+    return `b${String(block)}`;
+}
+/**
+ * One time-travel request: the pool's balance at the END of each block, one
+ * alias per block. Block numbers are written into the document, so each must
+ * be a positive safe integer — anything else throws rather than reaching the
+ * query text. The pool id travels as a variable.
+ */
+function poolBalancesAtBlocksQuery(blocks) {
+    const fields = blocks.map((block) => {
+        if (!Number.isSafeInteger(block) || block <= 0) {
+            throw new Error(`getPoolTvlHistory: refusing block number ${String(block)}`);
+        }
+        return `${blockAlias(block)}: lendingPool(id: $poolId, block: { number: ${String(block)} }) { balance }`;
+    });
+    return `query PoolTvlAtBlocks($poolId: ID!) { ${fields.join(' ')} }`;
+}
+function parseClearing(row) {
+    const clearing = {
+        epochId: Number(row.epochId),
+        block: Number(row.endBlockNumber),
+        timestamp: Number(row.endTimestamp),
+    };
+    if (!Number.isSafeInteger(clearing.epochId) ||
+        clearing.epochId < 0 ||
+        !Number.isSafeInteger(clearing.block) ||
+        clearing.block <= 0 ||
+        !Number.isSafeInteger(clearing.timestamp) ||
+        clearing.timestamp <= 0) {
+        throw new Error(`getPoolTvlHistory: malformed clearing row ${JSON.stringify(row)}`);
+    }
+    return clearing;
+}
+/**
+ * The scope's finished clearings, ascending by epoch, and the snapshot from
+ * the first page. Normally ONE request.
+ */
+function fetchPoolClearings(request, poolId, scope, cancellation) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const clearings = [];
+        let snapshot = {};
+        let gte = scope.kind === 'from' ? scope.fromEpoch : 0;
+        let lt;
+        let requests = 0;
+        for (;;) {
+            cancellation.throwIfCancelled();
+            if (requests >= TVL_HISTORY_MAX_PAGES) {
+                throw new Error(`getPoolTvlHistory: more than ${String(TVL_HISTORY_MAX_PAGES)} pages of clearings for one pool`);
+            }
+            const first = requests === 0;
+            const remaining = scope.kind === 'newest'
+                ? scope.count - clearings.length
+                : TVL_HISTORY_PAGE_SIZE;
+            const pageSize = Math.min(TVL_HISTORY_PAGE_SIZE, remaining);
+            const page = yield request(poolTvlClearingsQuery, {
+                poolId,
+                pool: poolId,
+                epochGte: String(gte),
+                epochLt: lt === undefined ? NO_EPOCH_BOUND : String(lt),
+                direction: scope.kind === 'newest' ? 'desc' : 'asc',
+                first: pageSize,
+                withSnapshot: first,
+            }, cancellation.signal);
+            requests += 1;
+            if (first)
+                snapshot = { pool: page.pool, meta: page.meta };
+            const rows = page.clearings.map(parseClearing);
+            clearings.push(...rows);
+            const last = rows.at(-1);
+            if (rows.length < pageSize || last === undefined)
+                break;
+            if (scope.kind === 'newest') {
+                if (clearings.length >= scope.count)
+                    break;
+                if (lt !== undefined && last.epochId >= lt) {
+                    throw new Error('getPoolTvlHistory: the clearings cursor did not advance');
+                }
+                lt = last.epochId;
+            }
+            else {
+                if (last.epochId < gte) {
+                    throw new Error('getPoolTvlHistory: the clearings cursor did not advance');
+                }
+                gte = last.epochId + 1;
+            }
+        }
+        clearings.sort((a, b) => a.epochId - b.epochId);
+        return { clearings, snapshot, requests };
+    });
+}
+/**
+ * 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
+ * at which the subgraph has no such pool THROWS: a finished clearing of the
+ * pool happened in it, so a missing pool means a broken read, not a zero.
+ */
+function fetchPoolBalancesAtBlocks(request, poolId, blocks, cancellation) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const chunks = [];
+        for (let i = 0; i < blocks.length; i += TVL_HISTORY_BLOCKS_PER_REQUEST) {
+            chunks.push(blocks.slice(i, i + TVL_HISTORY_BLOCKS_PER_REQUEST));
+        }
+        cancellation.throwIfCancelled();
+        const pages = yield Promise.all(chunks.map((chunk) => request(poolBalancesAtBlocksQuery(chunk), { poolId }, cancellation.signal).then((page) => ({ chunk, page }))));
+        const balances = new Map();
+        for (const { chunk, page } of pages) {
+            for (const block of chunk) {
+                const state = page[blockAlias(block)];
+                if (!state) {
+                    throw new Error(`getPoolTvlHistory: the subgraph has no state for the pool at block ${String(block)}`);
+                }
+                balances.set(block, state.balance);
+            }
+        }
+        return { balances, requests: chunks.length };
+    });
+}
+const EXTERNAL_TVL_INTERFACE = new Interface(KasuPoolExternalTVLAbi__factory.abi);
+function hasCode(code) {
+    if (typeof code !== 'string' || !/^0x[0-9a-fA-F]*$/.test(code)) {
+        throw new Error(`getPoolTvlHistory: getCode returned ${String(code)}, not hex`);
+    }
+    return code !== '0x';
+}
+/**
+ * The real reader: each read goes to the history RPCs IN ORDER until one
+ * answers, and the whole chain is retried `attempts` times with back-off.
+ * After the last attempt the last error propagates — never a value. Each
+ * attempt first checks the cancellation, so a timed-out call stops here.
+ */
+function createOffChainTvlReader({ externalTvl, pool, rpcs, cancellation, attempts = TVL_HISTORY_RPC_ATTEMPTS, delayMs = TVL_HISTORY_RPC_RETRY_DELAY_MS, sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)), }) {
+    if (rpcs.length === 0) {
+        throw new Error('getPoolTvlHistory: no history RPC to read from');
+    }
+    const data = EXTERNAL_TVL_INTERFACE.encodeFunctionData('externalTVLOfPool', [pool]);
+    const read = (op) => __awaiter(this, void 0, void 0, function* () {
+        let lastError;
+        for (let attempt = 1; attempt <= attempts; attempt++) {
+            for (const rpc of rpcs) {
+                cancellation.throwIfCancelled();
+                try {
+                    return yield op(rpc);
+                }
+                catch (error) {
+                    lastError = error;
+                }
+            }
+            if (attempt < attempts) {
+                yield sleep(delayMs * Math.pow(2, (attempt - 1)));
+            }
+        }
+        cancellation.throwIfCancelled();
+        throw lastError;
+    });
+    return {
+        readAt: (block) => read((rpc) => __awaiter(this, void 0, void 0, function* () {
+            const result = yield rpc.call({ to: externalTvl, data }, block);
+            const [value] = EXTERNAL_TVL_INTERFACE.decodeFunctionResult('externalTVLOfPool', result);
+            return value;
+        })),
+        hasCodeAt: (block) => read((rpc) => __awaiter(this, void 0, void 0, function* () { return hasCode(yield rpc.getCode(externalTvl, block)); })),
+        poolHasCodeAt: (block) => read((rpc) => __awaiter(this, void 0, void 0, function* () { return hasCode(yield rpc.getCode(pool, block)); })),
+    };
+}
+/**
+ * Index of the first block (of `blocks`, ascending) at which the contract has
+ * code; `blocks.length` when it has code at none. A deployed contract keeps
+ * its code (it is a proxy, never self-destructed), so the answer is a single
+ * boundary and a binary search finds it: ONE `getCode` when the contract
+ * already existed at the oldest clearing, about log2(n) otherwise.
+ */
+function firstBlockWithCode(blocks, hasCodeAt) {
+    return __awaiter(this, void 0, void 0, function* () {
+        if (blocks.length === 0)
+            return 0;
+        if (yield hasCodeAt(blocks[0]))
+            return 0;
+        const last = blocks.length - 1;
+        if (!(yield hasCodeAt(blocks[last])))
+            return blocks.length;
+        let lo = 0; // no code
+        let hi = last; // code
+        while (hi - lo > 1) {
+            const mid = Math.floor((lo + hi) / 2);
+            if (yield hasCodeAt(blocks[mid]))
+                hi = mid;
+            else
+                lo = mid;
+        }
+        return hi;
+    });
+}
+/**
+ * `fn` over `items`, at most `limit` in flight; rejects on the first failure
+ * and starts nothing after it (or after `beforeEach` throws).
+ */
+function mapWithConcurrency(items_1, limit_1, fn_1) {
+    return __awaiter(this, arguments, void 0, function* (items, limit, fn, beforeEach = () => undefined) {
+        const results = new Array(items.length);
+        let next = 0;
+        let failed = false;
+        const worker = () => __awaiter(this, void 0, void 0, function* () {
+            while (!failed && next < items.length) {
+                const index = next++;
+                try {
+                    beforeEach();
+                    results[index] = yield fn(items[index]);
+                }
+                catch (error) {
+                    failed = true;
+                    throw error;
+                }
+            }
+        });
+        yield Promise.all(Array.from({ length: Math.min(limit, items.length) }, worker));
+        return results;
+    });
+}
+/**
+ * Immutable past-block reads, per SDK instance. Keys carry the contract (or
+ * subgraph), the pool and the block, so two deployments never collide.
+ */
+class PastBlockCache {
+    constructor() {
+        this._entries = new Map();
+    }
+    get(key) {
+        return this._entries.get(key);
+    }
+    set(key, value) {
+        if (this._entries.size >= TVL_HISTORY_CACHE_LIMIT) {
+            this._entries.clear();
+        }
+        this._entries.set(key, value);
+    }
+    get size() {
+        return this._entries.size;
+    }
+}
+/**
+ * The off-chain TVL (BASE units) at each block, and — with `withLatest` — at
+ * the latest block, all inside ONE bounded pool of reads.
+ *
+ * Before the contract existed there was nothing to record, so those blocks
+ * are 0 — decided by `getCode`, never by catching a revert: an RPC that
+ * refuses past state can surface that refusal as a "call exception". And a
+ * "no code" answer is believed only if the same provider DOES show code for
+ * the pool at the oldest and newest such block (it cleared there); otherwise
+ * `PastStateUnavailableError`. Every other failed read throws.
+ *
+ * `cached` blocks (final, below the head) are answered from `cache` and
+ * stored there after a successful read.
+ */
+function fetchOffChainTvlAtBlocks(reader_1, blocks_1, _a) {
+    return __awaiter(this, arguments, void 0, function* (reader, blocks, { withLatest = false, cancellation, cache, cacheKey, cacheable = () => false, }) {
+        let rpcReads = 0;
+        const cached = (kind, block, load) => {
+            const key = cache && cacheKey && cacheable(block)
+                ? cacheKey(kind, block)
+                : undefined;
+            const hit = key === undefined ? undefined : cache === null || cache === void 0 ? void 0 : cache.get(key);
+            if (hit !== undefined)
+                return Promise.resolve(hit);
+            cancellation.throwIfCancelled();
+            rpcReads += 1;
+            return load().then((value) => {
+                if (key !== undefined)
+                    cache === null || cache === void 0 ? void 0 : cache.set(key, value);
+                return value;
+            });
+        };
+        const deployedFrom = yield firstBlockWithCode(blocks, (block) => cached('code', block, () => reader.hasCodeAt(block)));
+        if (deployedFrom > 0) {
+            for (const block of new Set([blocks[0], blocks[deployedFrom - 1]])) {
+                const poolDeployed = yield cached('pool', block, () => reader.poolHasCodeAt(block));
+                if (!poolDeployed)
+                    throw new PastStateUnavailableError(block);
+            }
+        }
+        const offChain = new Map();
+        for (const block of blocks.slice(0, deployedFrom)) {
+            offChain.set(block, BigNumber.from(0));
+        }
+        const targets = [...blocks.slice(deployedFrom)];
+        if (withLatest)
+            targets.push('latest');
+        const values = yield mapWithConcurrency(targets, TVL_HISTORY_RPC_CONCURRENCY, (block) => {
+            if (block !== 'latest') {
+                return cached('tvl', block, () => reader.readAt(block));
+            }
+            // Never cached: "latest" moves.
+            rpcReads += 1;
+            return reader.readAt('latest');
+        }, () => {
+            cancellation.throwIfCancelled();
+        });
+        let latest = null;
+        targets.forEach((block, i) => {
+            if (block === 'latest')
+                latest = values[i];
+            else
+                offChain.set(block, values[i]);
+        });
+        return { offChain, latest, rpcReads };
+    });
+}
+/**
+ * Pure: the reads → the history. One `clearing` point per clearing, ordered by
+ * the block it finished in (then by epoch, for clearings that shared a block),
+ * so the series is ascending in TIME even where epoch numbers jump; then the
+ * `current` point. Each point is `poolTvl(onChain, offChain)` — the same
+ * function `getPoolOverview` uses for `totalValueLocked.total`.
+ */
+function buildPoolTvlHistory(read) {
+    const offChainDisplay = (value) => formatUnits(value, read.decimals);
+    const entries = [...read.clearings]
+        .sort((a, b) => a.block - b.block || a.epochId - b.epochId)
+        .map((clearing) => {
+        const balance = read.balances.get(clearing.block);
+        const offChain = read.offChain.get(clearing.block);
+        if (balance === undefined || offChain === undefined) {
+            throw new Error(`getPoolTvlHistory: no reading at block ${String(clearing.block)}`);
+        }
+        return {
+            epochId: clearing.epochId,
+            timestamp: clearing.timestamp,
+            tvl: poolTvl(balance, offChainDisplay(offChain)),
+            kind: 'clearing',
+        };
+    });
+    if (read.current) {
+        entries.push({
+            epochId: read.current.epochId,
+            timestamp: read.current.timestamp,
+            tvl: poolTvl(read.current.balance, offChainDisplay(read.current.offChain)),
+            kind: 'current',
+        });
+    }
+    return entries;
+}
+/** Ascending, de-duplicated clearing blocks: each past block is read ONCE. */
+function distinctBlocks(clearings) {
+    return [...new Set(clearings.map((c) => c.block))].sort((a, b) => a - b);
+}
+
+/** Thrown by `getPoolTvlHistory` when no provider that serves past state is configured. */
+const NO_HISTORY_PROVIDER_MESSAGE = 'getPoolTvlHistory: no history provider; pass historyProvider or set historyRpcUrls to RPCs that serve past state';
 class DataService {
-    constructor(_kasuConfig, signerOrProvider) {
+    /**
+     * @param historyProvider - a provider that SERVES PAST STATE (an archive
+     * RPC), used only by `getPoolTvlHistory` for the off-chain TVL at old
+     * blocks. Without one, providers are built on `SdkConfig.historyRpcUrls`
+     * (tried in order); with neither, that one call throws
+     * `NO_HISTORY_PROVIDER_MESSAGE`. Never the default provider: a pruned
+     * node refuses old blocks.
+     */
+    constructor(_kasuConfig, signerOrProvider, historyProvider) {
         this._kasuConfig = _kasuConfig;
+        /** Immutable past-block reads, kept for the life of this instance. */
+        this._tvlHistoryCache = new PastBlockCache();
         this._externalTvlAbi = KasuPoolExternalTVLAbi__factory.connect(_kasuConfig.contracts.ExternalTVL, signerOrProvider);
+        this._systemVariablesAbi = ISystemVariablesAbi__factory.connect(_kasuConfig.contracts.SystemVariables, signerOrProvider);
         this._graph = new GraphQLClient(_kasuConfig.subgraphUrl);
+        this._explicitHistoryProvider = historyProvider;
         this._directus = createDirectusClient(_kasuConfig.directusUrl);
     }
     getUrlFromFile(fileName) {
@@ -15991,6 +16601,194 @@ class DataService {
             return tvlMap;
         });
     }
+    /**
+     * The pool's TVL — the total lent into it by everyone — at every cycle
+     * boundary, then as of now: the data behind a TVL chart.
+     *
+     * One `clearing` point per FINISHED clearing, read at the block it
+     * finished in (`LendingPoolClearing.endBlockNumber`), then one `current`
+     * point. Every point is `poolTvl(onChain, offChain)`, the definition
+     * `getPoolOverview` uses for `totalValueLocked.total`:
+     *
+     * - on-chain: `lendingPool.balance` from the subgraph, read with
+     *   time-travel queries (`block: { number }`);
+     * - off-chain: `ExternalTVL.externalTVLOfPool(pool)` at the same block,
+     *   through the HISTORY providers (see the constructor). 0 before the
+     *   contract was deployed (decided by `getCode`, and only if the same
+     *   provider shows the pool's own code there); any failed read throws.
+     *
+     * The `current` point mixes two sources: the subgraph's latest balance
+     * (and its latest block time) and `externalTVLOfPool` at `latest` on the
+     * history provider. `getPoolOverview` reads the same two, the off-chain
+     * one on the default provider, so the last point equals
+     * `totalValueLocked.total` when both reads succeed. They can differ when
+     * `getPoolOverview`'s off-chain read FAILS — it then falls back to 0 —
+     * or when the figure moves between the two calls.
+     *
+     * Units: `tvl` in display units of the deployment's own stable token
+     * (USDC on Base and XDC USDC, AUDD on XDC AUDD); `timestamp` in unix
+     * seconds. Ascending in time. See `PoolTvlHistoryEntry`.
+     *
+     * Cost: one subgraph request for the clearings (per thousand), one per
+     * hundred distinct uncached clearing blocks, a `currentEpochNumber` read;
+     * then, on the history providers, one `externalTVLOfPool` per distinct
+     * uncached block plus the latest, and one to about log2(n) `getCode`s —
+     * at most `TVL_HISTORY_RPC_CONCURRENCY` in flight. Final blocks are
+     * cached on this instance, so a second call reads only what is new.
+     * `timeoutMs` (default 30 s) bounds the whole call.
+     *
+     * `[]` for a pool the subgraph does not know, for a window with no epoch
+     * in it, and on a LITE deployment whose subgraph lacks the entities. On a
+     * full deployment that schema error throws, like every network, indexing
+     * or past-state failure.
+     *
+     * @throws RangeError / TypeError on a malformed option or a pool id that
+     * is not an address, and `NO_HISTORY_PROVIDER_MESSAGE` when the
+     * deployment has an `ExternalTVL` contract but no history provider — all
+     * before any network read. `PoolTvlHistoryTimeoutError` /
+     * `PoolTvlHistoryAbortedError` on the deadline or the signal,
+     * `PastStateUnavailableError` from a pruned history provider.
+     */
+    getPoolTvlHistory(poolId_1) {
+        return __awaiter(this, arguments, void 0, function* (poolId, options = {}) {
+            var _a;
+            validatePoolTvlHistoryOptions(options);
+            if (!isAddress(poolId)) {
+                throw new TypeError(`getPoolTvlHistory: poolId must be an address, got ${String(poolId)}`);
+            }
+            const pool = poolId.toLowerCase();
+            const externalTvl = this._externalTvlAddress();
+            const rpcs = externalTvl ? this._historyRpcs() : [];
+            if (externalTvl && rpcs.length === 0) {
+                throw new Error(NO_HISTORY_PROVIDER_MESSAGE);
+            }
+            return yield runCancellable((_a = options.timeoutMs) !== null && _a !== void 0 ? _a : TVL_HISTORY_DEFAULT_TIMEOUT_MS, options.signal, (cancellation) => this._readPoolTvlHistory(pool, options, externalTvl
+                ? this._createOffChainTvlReader({
+                    externalTvl,
+                    pool,
+                    rpcs,
+                    cancellation,
+                })
+                : null, externalTvl !== null && externalTvl !== void 0 ? externalTvl : '', cancellation));
+        });
+    }
+    _readPoolTvlHistory(pool, options, reader, externalTvl, cancellation) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a, _b, _c;
+            const graph = (document, variables, signal) => this._graph.request({ document, variables, signal });
+            const scope = options.fromEpoch === undefined && options.count !== undefined
+                ? { kind: 'newest', count: options.count }
+                : { kind: 'from', fromEpoch: (_a = options.fromEpoch) !== null && _a !== void 0 ? _a : 0 };
+            try {
+                const [currentEpochNumber, { clearings, snapshot }] = yield Promise.all([
+                    this._systemVariablesAbi.currentEpochNumber(),
+                    fetchPoolClearings(graph, pool, scope, cancellation),
+                ]);
+                const currentEpoch = currentEpochNumber.toNumber();
+                const window = resolvePoolTvlHistoryWindow(options, currentEpoch);
+                const poolNow = snapshot.pool;
+                if (!window || !poolNow)
+                    return [];
+                const head = (_b = snapshot.meta) === null || _b === void 0 ? void 0 : _b.block;
+                if (!head || typeof head.timestamp !== 'number') {
+                    throw new Error('getPoolTvlHistory: the subgraph returned no latest block time');
+                }
+                const inWindow = clearings.filter((c) => c.epochId >= window.fromEpoch &&
+                    c.epochId <= window.toEpoch);
+                const blocks = distinctBlocks(inWindow);
+                const withCurrent = window.toEpoch >= currentEpoch;
+                const cacheable = (block) => block <= head.number - TVL_HISTORY_CACHE_DEPTH;
+                const [balances, offChainRead] = yield Promise.all([
+                    this._balancesAtBlocks(graph, pool, blocks, cacheable, cancellation),
+                    reader
+                        ? fetchOffChainTvlAtBlocks(reader, blocks, {
+                            withLatest: withCurrent,
+                            cancellation,
+                            cache: this._tvlHistoryCache,
+                            cacheKey: (kind, block) => `${kind}|${externalTvl}|${pool}|${String(block)}`,
+                            cacheable,
+                        })
+                        : {
+                            offChain: new Map(blocks.map((b) => [b, BigNumber.from(0)])),
+                            latest: null,
+                        },
+                ]);
+                return buildPoolTvlHistory({
+                    clearings: inWindow,
+                    balances,
+                    offChain: offChainRead.offChain,
+                    current: withCurrent
+                        ? {
+                            epochId: currentEpoch,
+                            timestamp: head.timestamp,
+                            balance: poolNow.balance,
+                            offChain: (_c = offChainRead.latest) !== null && _c !== void 0 ? _c : BigNumber.from(0),
+                        }
+                        : null,
+                    decimals: this._kasuConfig.stableAssetDecimals,
+                });
+            }
+            catch (error) {
+                if (isEmptyHistoryError(error, this._kasuConfig.isLiteDeployment)) {
+                    return [];
+                }
+                throw error;
+            }
+        });
+    }
+    /** The pool's balance at each block: cached final blocks, then one batch. */
+    _balancesAtBlocks(graph, pool, blocks, cacheable, cancellation) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const key = (block) => `balance|${this._kasuConfig.subgraphUrl}|${pool}|${String(block)}`;
+            const balances = new Map();
+            const missing = [];
+            for (const block of blocks) {
+                const hit = cacheable(block)
+                    ? this._tvlHistoryCache.get(key(block))
+                    : undefined;
+                if (hit === undefined)
+                    missing.push(block);
+                else
+                    balances.set(block, hit);
+            }
+            if (missing.length > 0) {
+                const read = yield fetchPoolBalancesAtBlocks(graph, pool, missing, cancellation);
+                for (const [block, balance] of read.balances) {
+                    balances.set(block, balance);
+                    if (cacheable(block))
+                        this._tvlHistoryCache.set(key(block), balance);
+                }
+            }
+            return balances;
+        });
+    }
+    /** `null` when the deployment has no `ExternalTVL` contract. */
+    _externalTvlAddress() {
+        const address = this._kasuConfig.contracts.ExternalTVL;
+        if (!address || /^0x0{40}$/i.test(address))
+            return null;
+        return address.toLowerCase();
+    }
+    /** Seam for tests: the real reader over the history RPCs. */
+    _createOffChainTvlReader(args) {
+        return createOffChainTvlReader(args);
+    }
+    /**
+     * The history RPCs, in fallback order: the explicit provider, else ONE
+     * provider per `historyRpcUrls` entry — built here and nowhere else,
+     * pinned to `SdkConfig.chainId` when known, each with a per-call timeout.
+     * Built once per instance.
+     */
+    _historyRpcs() {
+        if (this._explicitHistoryProvider)
+            return [this._explicitHistoryProvider];
+        if (!this._builtHistoryProviders) {
+            // Through the `ethers` namespace, so the consumer's own build
+            // (Node or browser) is used — see `defaultProvider` in the facade.
+            this._builtHistoryProviders = this._kasuConfig.historyRpcUrls.map((url) => new providers.StaticJsonRpcProvider({ url, timeout: TVL_HISTORY_RPC_TIMEOUT_MS }, this._kasuConfig.chainId));
+        }
+        return this._builtHistoryProviders;
+    }
     getPoolOverview(epochId, id_in) {
         return __awaiter(this, void 0, void 0, function* () {
             var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p, _q, _r, _s;
@@ -16131,8 +16929,8 @@ class DataService {
                     subheading: lendingPoolDirectus === null || lendingPoolDirectus === void 0 ? void 0 : lendingPoolDirectus.subheading,
                     operatingSince: lendingPoolDirectus === null || lendingPoolDirectus === void 0 ? void 0 : lendingPoolDirectus.operatingSince,
                     totalValueLocked: {
-                        total: (parseFloat(lendingPoolSubgraph.balance) +
-                            parseFloat(offChainTvl)).toString(),
+                        // The one TVL definition, shared with getPoolTvlHistory.
+                        total: poolTvl(lendingPoolSubgraph.balance, offChainTvl).toString(),
                         offchain: offChainTvl,
                     },
                     loansUnderManagement: (_q = lendingPoolDirectus === null || lendingPoolDirectus === void 0 ? void 0 : lendingPoolDirectus.loansUnderManagement) !== null && _q !== void 0 ? _q : '0',
@@ -16941,6 +17739,101 @@ class KSULocking {
     }
 }
 
+/**
+ * Settled interest per cycle (epoch): what a lender was credited at each close,
+ * per pool and tranche, and the one formula that turns a tranche's credited
+ * interest into one lender's share of it.
+ *
+ * **The figures are NET, and only net.** `LendingPool._applyTrancheInterest`
+ * takes the performance fee off first and emits `InterestApplied` with the
+ * lender side only (`interest × (1 − performanceFee)`); a fixed-term top-up
+ * (`_applyFixedRateInterests`) is net of the fee the same way. So the figure
+ * this module computes from those records IS what the lender was credited —
+ * never take the fee off it again. No gross is offered: the subgraph keeps
+ * only TODAY's fee, so a historical gross would be a guess.
+ *
+ * Units: amounts are display units of the DEPLOYMENT'S OWN stable token (USDC
+ * on Base and XDC USDC, AUDD on XDC AUDD) — never converted to USD here;
+ * shares are display units of tranche shares, as the subgraph's BigDecimals.
+ */
+/**
+ * The ONE per-epoch formula. `Portfolio.getPortfolioLendingData` runs it for
+ * the last settled epoch and `getYieldHistory` for every epoch of a window, so
+ * the two figures cannot drift apart.
+ *
+ * ```
+ * base     = epochInterest × userShares / trancheShares
+ * lockBase = base × lock.sharesBeforeEpoch / userShares          (active locks)
+ * topUp    = (lock.sharesAtEpoch − lock.sharesBeforeEpoch) × trancheBalanceNow / trancheSharesNow
+ * variable = base − Σ lockBase
+ * total    = variable + Σ (lockBase + topUp)
+ * ```
+ *
+ * A zero denominator contributes 0 (a tranche or a lender with no shares
+ * earned nothing at that close), never `NaN`.
+ */
+function epochTrancheYield(input) {
+    const base = input.trancheShares === 0
+        ? 0
+        : (input.epochInterest * input.userShares) / input.trancheShares;
+    let variable = base;
+    const locks = input.locks.map((lock) => {
+        if (!lock.active)
+            return 0;
+        const topUp = input.trancheSharesNow === 0
+            ? 0
+            : ((lock.sharesAtEpoch - lock.sharesBeforeEpoch) *
+                input.trancheBalanceNow) /
+                input.trancheSharesNow;
+        const lockBase = input.userShares === 0
+            ? 0
+            : (base * lock.sharesBeforeEpoch) / input.userShares;
+        variable -= lockBase;
+        return lockBase + topUp;
+    });
+    const total = locks.reduce((sum, lockYield) => sum + lockYield, variable);
+    return { total, variable, locks };
+}
+/**
+ * Pool/tranche entries → one point per epoch, ascending by `epochId`. With no
+ * filter it sums every strategy (the Lend tab's bars); with `poolId` it is one
+ * strategy (a strategy page's bars).
+ *
+ * An epoch appears only if a kept entry has it — there is no zero padding, so
+ * an empty input (a new lender) is an empty output.
+ *
+ * For a fixed-term lock holder the bars can sum to slightly MORE than the
+ * lender's lifetime interest (up to about 0.2 %): each top-up is valued at the
+ * tranche's CURRENT share price, which has grown since. Show "earned to date"
+ * from the lifetime figure, never from this sum.
+ */
+function aggregateYieldHistory(entries, filter = {}) {
+    var _a, _b;
+    const poolId = (_a = filter.poolId) === null || _a === void 0 ? void 0 : _a.toLowerCase();
+    const trancheId = (_b = filter.trancheId) === null || _b === void 0 ? void 0 : _b.toLowerCase();
+    const byEpoch = new Map();
+    for (const entry of entries) {
+        if (poolId !== undefined && entry.poolId.toLowerCase() !== poolId) {
+            continue;
+        }
+        if (trancheId !== undefined &&
+            entry.trancheId.toLowerCase() !== trancheId) {
+            continue;
+        }
+        const point = byEpoch.get(entry.epochId);
+        if (point) {
+            point.netYield += entry.netYield;
+            continue;
+        }
+        byEpoch.set(entry.epochId, {
+            epochId: entry.epochId,
+            epochEnd: entry.epochEnd,
+            netYield: entry.netYield,
+        });
+    }
+    return [...byEpoch.values()].sort((a, b) => a.epochId - b.epochId);
+}
+
 /**
  * Check if the SDK is configured for a Lite deployment.
  * Lite deployments don't have KSU token, locking, or loyalty features.
@@ -17724,9 +18617,11 @@ const lendingPortfolioQuery = gql `
         $epochId: BigInt!
         $lastEpochId: BigInt!
         $unusedPools: [String!]!
+        $first: Int!
     ) {
         user(id: $userAddress) {
             lendingPoolUserDetails(
+                first: $first
                 where: { lendingPool_not_in: $unusedPools }
             ) {
                 id
@@ -17734,11 +18629,11 @@ const lendingPortfolioQuery = gql `
                     id
                     name
                     balance
-                    tranches {
+                    tranches(first: $first) {
                         shares
                     }
                 }
-                lendingPoolTrancheUserDetails {
+                lendingPoolTrancheUserDetails(first: $first) {
                     shares
                     lendingPoolTrancheUserEpochSharesUpdates(
                         orderDirection: desc
@@ -17748,7 +18643,7 @@ const lendingPortfolioQuery = gql `
                     ) {
                         shares
                     }
-                    userLendingPoolTrancheFixedTermDepositLocks {
+                    userLendingPoolTrancheFixedTermDepositLocks(first: $first) {
                         isLocked
                         unlockAmount
                         initialAmount
@@ -17772,6 +18667,14 @@ const lendingPortfolioQuery = gql `
                         ) {
                             shares
                         }
+                        lockSharesAtLastEpoch: userLendingPoolTrancheFixedTermDepositLockShareUpdate(
+                            orderBy: shareUpdatesIndex
+                            orderDirection: desc
+                            first: 1
+                            where: { epochId_lt: $epochId }
+                        ) {
+                            shares
+                        }
                     }
                     tranche {
                         id
@@ -17798,6 +18701,7 @@ const lendingPortfolioQuery = gql `
             }
         }
         userRequests(
+            first: $first
             where: {
                 user: $userAddress
                 userRequestEvents_: {
@@ -17813,6 +18717,7 @@ const lendingPortfolioQuery = gql `
             }
             fixedTermConfigId
             userRequestEvents(
+                first: $first
                 where: { type_in: [DepositInitiated, DepositIncreased] }
             ) {
                 id
@@ -17822,6 +18727,371 @@ const lendingPortfolioQuery = gql `
     }
 `;
 
+/** The subgraph returns at most this many rows per collection per request. */
+const YIELD_HISTORY_PAGE_SIZE = 1000;
+/**
+ * A runaway guard, not a working limit: a collection this many pages long
+ * (`MAX × PAGE_SIZE` rows for one lender) is a broken response, not a history.
+ */
+const YIELD_HISTORY_MAX_PAGES = 100;
+/**
+ * Throws `RangeError` on a malformed `fromEpoch` / `count`. `getYieldHistory`
+ * calls it BEFORE any network read.
+ */
+function validateYieldHistoryOptions(options) {
+    const { fromEpoch, count } = options;
+    if (fromEpoch !== undefined &&
+        (!Number.isSafeInteger(fromEpoch) || fromEpoch < 0)) {
+        throw new RangeError(`getYieldHistory: fromEpoch must be a non-negative integer, got ${String(fromEpoch)}`);
+    }
+    if (count !== undefined && (!Number.isSafeInteger(count) || count < 1)) {
+        throw new RangeError(`getYieldHistory: count must be a positive integer, got ${String(count)}`);
+    }
+}
+function resolveYieldHistoryWindow(options, currentEpoch) {
+    validateYieldHistoryOptions(options);
+    const { fromEpoch, count } = options;
+    const newest = currentEpoch - 1;
+    if (newest < 0)
+        return null;
+    let from;
+    let to = newest;
+    if (fromEpoch !== undefined) {
+        from = fromEpoch;
+        if (count !== undefined)
+            to = Math.min(newest, fromEpoch + count - 1);
+    }
+    else {
+        from = count !== undefined ? Math.max(0, newest - count + 1) : 0;
+    }
+    return from > to ? null : { fromEpoch: from, toEpoch: to };
+}
+// ---------------------------------------------------------------------------
+// Subgraph reads
+// ---------------------------------------------------------------------------
+/**
+ * Round trip 1: the lender's tranche positions and fixed-term locks. Same
+ * pool exclusion and the same nested-list size (`$first`) as
+ * `lendingPortfolioQuery`, so both read the same lock set.
+ */
+const yieldHistoryPositionsQuery = gql `
+    query YieldHistoryPositions(
+        $userAddress: ID!
+        $unusedPools: [String!]!
+        $first: Int!
+    ) {
+        user(id: $userAddress) {
+            lendingPoolUserDetails(
+                first: $first
+                where: { lendingPool_not_in: $unusedPools }
+            ) {
+                lendingPool {
+                    id
+                }
+                lendingPoolTrancheUserDetails(first: $first) {
+                    id
+                    tranche {
+                        id
+                        balance
+                        shares
+                    }
+                    userLendingPoolTrancheFixedTermDepositLocks(first: $first) {
+                        id
+                        epochLockStart
+                        epochLockEnd
+                        initialTrancheShares
+                    }
+                }
+            }
+        }
+    }
+`;
+/**
+ * Round trip 2 onwards: the four per-epoch series, one page of each per
+ * request, cursor-paginated by `id`. A series that is exhausted is skipped with
+ * `@include`, so a history costs as many requests as its LONGEST series has
+ * pages — normally one — never one per epoch.
+ *
+ * Share snapshots are read up to the window's end with no lower bound: the
+ * value AS OF the first epoch may come from an update long before it.
+ */
+const yieldHistoryPageQuery = gql `
+    query YieldHistoryPage(
+        $tranches: [String!]!
+        $userTranches: [String!]!
+        $locks: [String!]!
+        $fromEpoch: BigInt!
+        $toEpoch: BigInt!
+        $interestCursor: ID!
+        $trancheSharesCursor: ID!
+        $userSharesCursor: ID!
+        $lockSharesCursor: ID!
+        $withInterest: Boolean!
+        $withTrancheShares: Boolean!
+        $withUserShares: Boolean!
+        $withLockShares: Boolean!
+        $first: Int!
+    ) {
+        interest: lendingPoolTrancheEpochInterests(
+            first: $first
+            orderBy: id
+            orderDirection: asc
+            where: {
+                id_gt: $interestCursor
+                lendingPoolTranche_in: $tranches
+                epochId_gte: $fromEpoch
+                epochId_lte: $toEpoch
+            }
+        ) @include(if: $withInterest) {
+            id
+            epochId
+            epochInterestAmount
+            lendingPoolTranche {
+                id
+            }
+        }
+        trancheShares: lendingPoolTrancheShareUpdates(
+            first: $first
+            orderBy: id
+            orderDirection: asc
+            where: {
+                id_gt: $trancheSharesCursor
+                lendingPoolTranche_in: $tranches
+                epochId_lte: $toEpoch
+            }
+        ) @include(if: $withTrancheShares) {
+            id
+            epochId
+            shareUpdatesIndex
+            shares
+            lendingPoolTranche {
+                id
+            }
+        }
+        userShares: lendingPoolTrancheUserEpochSharesUpdates(
+            first: $first
+            orderBy: id
+            orderDirection: asc
+            where: {
+                id_gt: $userSharesCursor
+                lendingPoolTrancheUserDetails_in: $userTranches
+                epochId_lte: $toEpoch
+            }
+        ) @include(if: $withUserShares) {
+            id
+            epochId
+            shareUpdatesIndex
+            shares
+            lendingPoolTrancheUserDetails {
+                id
+            }
+        }
+        lockShares: userLendingPoolTrancheFtdLockShareUpdates(
+            first: $first
+            orderBy: id
+            orderDirection: asc
+            where: {
+                id_gt: $lockSharesCursor
+                userLendingPoolTrancheFixedTermDepositLock_in: $locks
+                epochId_lte: $toEpoch
+            }
+        ) @include(if: $withLockShares) {
+            id
+            epochId
+            shareUpdatesIndex
+            shares
+            userLendingPoolTrancheFixedTermDepositLock {
+                id
+            }
+        }
+    }
+`;
+/**
+ * Fetch the four series for the window, paginating each by `id` until a short
+ * page. Returns the rows and how many requests it took.
+ */
+function fetchYieldHistorySeries(request, ids, window) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a;
+        const rows = {
+            interest: [],
+            trancheShares: [],
+            userShares: [],
+            lockShares: [],
+        };
+        const series = [
+            { key: 'interest', flag: 'withInterest', cursor: 'interestCursor' },
+            {
+                key: 'trancheShares',
+                flag: 'withTrancheShares',
+                cursor: 'trancheSharesCursor',
+            },
+            {
+                key: 'userShares',
+                flag: 'withUserShares',
+                cursor: 'userSharesCursor',
+            },
+            {
+                key: 'lockShares',
+                flag: 'withLockShares',
+                cursor: 'lockSharesCursor',
+            },
+        ];
+        const cursors = {
+            interest: '',
+            trancheShares: '',
+            userShares: '',
+            lockShares: '',
+        };
+        const open = {
+            interest: ids.tranches.length > 0,
+            trancheShares: ids.tranches.length > 0,
+            userShares: ids.userTranches.length > 0,
+            lockShares: ids.locks.length > 0,
+        };
+        let requests = 0;
+        while (series.some(({ key }) => open[key])) {
+            if (requests >= YIELD_HISTORY_MAX_PAGES) {
+                throw new Error(`getYieldHistory: more than ${String(YIELD_HISTORY_MAX_PAGES)} pages for one lender`);
+            }
+            const variables = {
+                tranches: ids.tranches,
+                userTranches: ids.userTranches,
+                locks: ids.locks,
+                fromEpoch: String(window.fromEpoch),
+                toEpoch: String(window.toEpoch),
+                first: YIELD_HISTORY_PAGE_SIZE,
+            };
+            for (const { key, flag, cursor } of series) {
+                variables[flag] = open[key];
+                variables[cursor] = cursors[key];
+            }
+            const page = yield request(variables);
+            requests += 1;
+            for (const { key } of series) {
+                if (!open[key])
+                    continue;
+                const got = (_a = page[key]) !== null && _a !== void 0 ? _a : [];
+                rows[key].push(...got);
+                const last = got.at(-1);
+                if (got.length < YIELD_HISTORY_PAGE_SIZE || last === undefined) {
+                    open[key] = false;
+                    continue;
+                }
+                if (last.id <= cursors[key]) {
+                    throw new Error(`getYieldHistory: the ${key} cursor did not advance`);
+                }
+                cursors[key] = last.id;
+            }
+        }
+        return { rows, requests };
+    });
+}
+/**
+ * The snapshot in force at `epoch`: among updates with `epochId ≤ epoch`, the
+ * one with the highest `shareUpdatesIndex` — exactly what
+ * `lendingPortfolioQuery` selects with `orderBy: shareUpdatesIndex, desc,
+ * first: 1, where: { epochId_lt: epoch + 1 }`. `undefined` when none.
+ */
+function sharesAsOf(updates, epoch) {
+    let found;
+    for (const update of updates) {
+        if (Number(update.epochId) > epoch)
+            continue;
+        if (!found || update.shareUpdatesIndex > found.shareUpdatesIndex) {
+            found = update;
+        }
+    }
+    return found;
+}
+function groupBy(rows, key) {
+    const map = new Map();
+    for (const row of rows) {
+        const k = key(row);
+        const list = map.get(k);
+        if (list)
+            list.push(row);
+        else
+            map.set(k, [row]);
+    }
+    return map;
+}
+/**
+ * Pure: the fetched series → one entry per pool, tranche and settled epoch in
+ * which the lender held shares (or a lock earned a top-up). Each entry runs the
+ * same `epochTrancheYield` as the portfolio's last-epoch figure, with the same
+ * share selection, so the newest entry equals that figure.
+ *
+ * Sorted by `epochId`, then `poolId`, then `trancheId`.
+ */
+function buildYieldHistory(read, window, clock) {
+    var _a, _b, _c, _d, _e, _f;
+    const user = read.positions.user;
+    if (!user)
+        return [];
+    const interestByTranche = groupBy(read.interest, (row) => row.lendingPoolTranche.id);
+    const trancheSharesByTranche = groupBy(read.trancheShares, (row) => row.lendingPoolTranche.id);
+    const userSharesByPosition = groupBy(read.userShares, (row) => row.lendingPoolTrancheUserDetails.id);
+    const lockSharesByLock = groupBy(read.lockShares, (row) => row.userLendingPoolTrancheFixedTermDepositLock.id);
+    const entries = [];
+    for (const pool of user.lendingPoolUserDetails) {
+        for (const position of pool.lendingPoolTrancheUserDetails) {
+            const trancheId = position.tranche.id;
+            const trancheUpdates = (_a = trancheSharesByTranche.get(trancheId)) !== null && _a !== void 0 ? _a : [];
+            const userUpdates = (_b = userSharesByPosition.get(position.id)) !== null && _b !== void 0 ? _b : [];
+            const trancheBalanceNow = parseFloat(position.tranche.balance);
+            const trancheSharesNow = parseFloat(position.tranche.shares);
+            for (const record of (_c = interestByTranche.get(trancheId)) !== null && _c !== void 0 ? _c : []) {
+                const epoch = Number(record.epochId);
+                if (epoch < window.fromEpoch || epoch > window.toEpoch) {
+                    continue;
+                }
+                const userSnapshot = sharesAsOf(userUpdates, epoch);
+                const userShares = parseFloat((_d = userSnapshot === null || userSnapshot === void 0 ? void 0 : userSnapshot.shares) !== null && _d !== void 0 ? _d : '0');
+                const locks = position.userLendingPoolTrancheFixedTermDepositLocks.map((lock) => {
+                    var _a, _b, _c, _d, _e;
+                    const lockUpdates = (_a = lockSharesByLock.get(lock.id)) !== null && _a !== void 0 ? _a : [];
+                    return {
+                        active: parseFloat(lock.epochLockStart) < epoch &&
+                            parseFloat(lock.epochLockEnd) >= epoch &&
+                            userSnapshot !== undefined,
+                        // No snapshot yet = the lock's opening
+                        // shares: a lock made after clearing E
+                        // starts at E but its first update is
+                        // tagged E + 1, and reading that gap as 0
+                        // would book its principal as a top-up.
+                        sharesAtEpoch: parseFloat((_c = (_b = sharesAsOf(lockUpdates, epoch)) === null || _b === void 0 ? void 0 : _b.shares) !== null && _c !== void 0 ? _c : lock.initialTrancheShares),
+                        sharesBeforeEpoch: parseFloat((_e = (_d = sharesAsOf(lockUpdates, epoch - 1)) === null || _d === void 0 ? void 0 : _d.shares) !== null && _e !== void 0 ? _e : lock.initialTrancheShares),
+                    };
+                });
+                const { total } = epochTrancheYield({
+                    epochInterest: parseFloat(record.epochInterestAmount),
+                    userShares,
+                    trancheShares: parseFloat((_f = (_e = sharesAsOf(trancheUpdates, epoch)) === null || _e === void 0 ? void 0 : _e.shares) !== null && _f !== void 0 ? _f : '0'),
+                    trancheBalanceNow,
+                    trancheSharesNow,
+                    locks,
+                });
+                // Nothing held and nothing topped up: not part of this
+                // lender's history (a new lender's history is empty).
+                if (userShares <= 0 && total === 0)
+                    continue;
+                entries.push({
+                    epochId: epoch,
+                    epochEnd: clock.epochZeroStart +
+                        (epoch + 1) * clock.epochDuration,
+                    poolId: pool.lendingPool.id,
+                    trancheId,
+                    netYield: total,
+                });
+            }
+        }
+    }
+    return entries.sort((a, b) => a.epochId - b.epochId ||
+        a.poolId.localeCompare(b.poolId) ||
+        a.trancheId.localeCompare(b.trancheId));
+}
+
 class Portfolio {
     constructor(_kasuConfig, signerOrProvider) {
         this._kasuConfig = _kasuConfig;
@@ -17922,7 +19192,7 @@ class Portfolio {
                     performanceFee *
                     ecosystemFeeRate;
         }
-        return ((totalWeeklyEcosystemFees * userRKsuAmount) / totalRKsuAmount);
+        return (totalWeeklyEcosystemFees * userRKsuAmount) / totalRKsuAmount;
     }
     /**
      * Calculate the user's weekly KASU bonus rewards (KASU) based on current deposits,
@@ -17930,7 +19200,7 @@ class Portfolio {
      */
     calculateWeeklyKsuBonusRewards(params) {
         return __awaiter(this, void 0, void 0, function* () {
-            const { userAddress, userRksuAmount, userDepositAmounts, ksuEpochPrice } = params;
+            const { userAddress, userRksuAmount, userDepositAmounts, ksuEpochPrice, } = params;
             const totalUserDeposits = userDepositAmounts[0].add(userDepositAmounts[1]);
             if (totalUserDeposits.isZero())
                 return 0;
@@ -18039,7 +19309,7 @@ class Portfolio {
     }
     getPortfolioLendingData(userAddress, poolOverviews, currentEpoch, provider) {
         return __awaiter(this, void 0, void 0, function* () {
-            var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l;
+            var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m;
             const SECONDS_PER_EPOCH = 604800; // seconds in a week
             const portfolioLendingPoolsPromise = [];
             const previousEpoch = BigNumber.from(currentEpoch).sub(BigNumber.from(1));
@@ -18049,6 +19319,7 @@ class Portfolio {
                     epochId: parseFloat(currentEpoch),
                     lastEpochId: previousEpoch.toNumber(),
                     unusedPools: this._kasuConfig.UNUSED_LENDING_POOL_IDS,
+                    first: YIELD_HISTORY_PAGE_SIZE,
                 }),
                 this._userLendingService.getPortfolioUserTrancheBalances(userAddress),
                 this._userLendingService.getUserPoolBalance(userAddress, poolOverviews.map(({ id }) => id), provider),
@@ -18086,7 +19357,6 @@ class Portfolio {
                 }
             }
             let totalInvestments = BigNumber.from(0);
-            let totalYieldEarnedLastEpoch = 0;
             for (const poolOverview of poolOverviews) {
                 const userPoolBalance = userPoolBalances.find(({ poolId }) => poolId === poolOverview.id);
                 if (!userPoolBalance) {
@@ -18094,6 +19364,7 @@ class Portfolio {
                 }
                 totalInvestments = userPoolBalance.balance.add(totalInvestments);
                 const tranches = [];
+                let poolYieldEarnedLastEpoch = 0;
                 const lendingPoolUserDetails = lastEpochData.user.lendingPoolUserDetails.find(({ lendingPool }) => lendingPool.id === poolOverview.id);
                 if (!lendingPoolUserDetails)
                     continue;
@@ -18112,18 +19383,42 @@ class Portfolio {
                             }, depositDetails, fixedLoans: [] }));
                         continue;
                     }
-                    const lastEpochTotalYield = parseFloat((_e = (_d = (_c = lastEpochUserTrancheDetails.tranche
-                        .lendingPoolTrancheEpochInterest) === null || _c === void 0 ? void 0 : _c[0]) === null || _d === void 0 ? void 0 : _d.epochInterestAmount) !== null && _e !== void 0 ? _e : '0');
-                    const lastEpochUserShares = parseFloat((_h = (_g = (_f = lastEpochUserTrancheDetails
-                        .lendingPoolTrancheUserEpochSharesUpdates) === null || _f === void 0 ? void 0 : _f[0]) === null || _g === void 0 ? void 0 : _g.shares) !== null && _h !== void 0 ? _h : '0');
-                    const lastEpochTotalShares = parseFloat((_l = (_k = (_j = lastEpochUserTrancheDetails.tranche
-                        .lendingPoolTrancheShareUpdates) === null || _j === void 0 ? void 0 : _j[0]) === null || _k === void 0 ? void 0 : _k.shares) !== null && _l !== void 0 ? _l : '0');
-                    const currentTotalAmount = parseFloat(lastEpochUserTrancheDetails.tranche.balance);
-                    const currentTotalShares = parseFloat(lastEpochUserTrancheDetails.tranche.shares);
-                    const lastEpochTotalBaseYield = lastEpochTotalShares === 0
-                        ? 0
-                        : (lastEpochTotalYield * lastEpochUserShares) /
-                            lastEpochTotalShares;
+                    const lastEpoch = previousEpoch.toNumber();
+                    const userHasLastEpochShares = Boolean((_c = lastEpochUserTrancheDetails
+                        .lendingPoolTrancheUserEpochSharesUpdates) === null || _c === void 0 ? void 0 : _c.length);
+                    const fixedTermDeposits = lastEpochUserTrancheDetails.userLendingPoolTrancheFixedTermDepositLocks;
+                    // The one per-epoch formula `getYieldHistory` runs too, with
+                    // the same share selection — so the last bar of a history
+                    // equals these figures.
+                    const lastEpochYield = epochTrancheYield({
+                        epochInterest: parseFloat((_f = (_e = (_d = lastEpochUserTrancheDetails.tranche
+                            .lendingPoolTrancheEpochInterest) === null || _d === void 0 ? void 0 : _d[0]) === null || _e === void 0 ? void 0 : _e.epochInterestAmount) !== null && _f !== void 0 ? _f : '0'),
+                        userShares: parseFloat((_j = (_h = (_g = lastEpochUserTrancheDetails
+                            .lendingPoolTrancheUserEpochSharesUpdates) === null || _g === void 0 ? void 0 : _g[0]) === null || _h === void 0 ? void 0 : _h.shares) !== null && _j !== void 0 ? _j : '0'),
+                        trancheShares: parseFloat((_m = (_l = (_k = lastEpochUserTrancheDetails.tranche
+                            .lendingPoolTrancheShareUpdates) === null || _k === void 0 ? void 0 : _k[0]) === null || _l === void 0 ? void 0 : _l.shares) !== null && _m !== void 0 ? _m : '0'),
+                        trancheBalanceNow: parseFloat(lastEpochUserTrancheDetails.tranche.balance),
+                        trancheSharesNow: parseFloat(lastEpochUserTrancheDetails.tranche.shares),
+                        locks: fixedTermDeposits.map((fixedTermDeposit) => {
+                            var _a, _b, _c, _d, _e, _f;
+                            return ({
+                                active: parseFloat(fixedTermDeposit.epochLockStart) <
+                                    lastEpoch &&
+                                    parseFloat(fixedTermDeposit.epochLockEnd) >=
+                                        lastEpoch &&
+                                    userHasLastEpochShares,
+                                // No snapshot = the lock's opening shares, exactly
+                                // as `getYieldHistory` reads it: a lock made after
+                                // clearing E starts at E with its first update
+                                // tagged E + 1. Never the CURRENT shares, which
+                                // would carry a top-up from a clearing that ran
+                                // after the last settled epoch.
+                                sharesAtEpoch: parseFloat((_c = (_b = (_a = fixedTermDeposit.lockSharesAtLastEpoch) === null || _a === void 0 ? void 0 : _a[0]) === null || _b === void 0 ? void 0 : _b.shares) !== null && _c !== void 0 ? _c : fixedTermDeposit.initialTrancheShares),
+                                sharesBeforeEpoch: parseFloat((_f = (_e = (_d = fixedTermDeposit
+                                    .userLendingPoolTrancheFixedTermDepositLockShareUpdate) === null || _d === void 0 ? void 0 : _d[0]) === null || _e === void 0 ? void 0 : _e.shares) !== null && _f !== void 0 ? _f : fixedTermDeposit.initialTrancheShares),
+                            });
+                        }),
+                    });
                     const userTrancheBalance = {
                         balance: '0',
                         yieldEarned: 0,
@@ -18138,47 +19433,20 @@ class Portfolio {
                         }
                     }
                     let totalLifetimeFtdYield = 0;
-                    let lastEpochVariableBaseYield = lastEpochTotalBaseYield;
-                    const fixedLoans = lastEpochUserTrancheDetails.userLendingPoolTrancheFixedTermDepositLocks.map((fixedTermDeposit) => {
-                        var _a, _b, _c, _d, _e;
+                    const fixedLoans = fixedTermDeposits.map((fixedTermDeposit, lockIndex) => {
+                        var _a, _b;
                         const fixedLoanDepositDetails = (_a = userRequest === null || userRequest === void 0 ? void 0 : userRequest[fixedTermDeposit
-                            .lendingPoolTrancheFixedTermConfig
-                            .configId]) !== null && _a !== void 0 ? _a : [];
-                        let lastEpochYieldEarned = 0;
-                        let lifetimeYieldEarned = 0;
-                        if (parseFloat(fixedTermDeposit.epochLockStart) <
-                            previousEpoch.toNumber() &&
-                            parseFloat(fixedTermDeposit.epochLockEnd) >=
-                                previousEpoch.toNumber() &&
-                            Boolean((_b = lastEpochUserTrancheDetails
-                                .lendingPoolTrancheUserEpochSharesUpdates) === null || _b === void 0 ? void 0 : _b.length)) {
-                            const currentEpochFtdShares = parseFloat(fixedTermDeposit.trancheShares);
-                            const lastEpochFtdShares = parseFloat((_e = (_d = (_c = fixedTermDeposit
-                                .userLendingPoolTrancheFixedTermDepositLockShareUpdate) === null || _c === void 0 ? void 0 : _c[0]) === null || _d === void 0 ? void 0 : _d.shares) !== null && _e !== void 0 ? _e : '0');
-                            const additionalFtdYield = ((currentEpochFtdShares -
-                                lastEpochFtdShares) *
-                                currentTotalAmount) /
-                                currentTotalShares;
-                            const lastEpochFtdBaseYield = (lastEpochTotalBaseYield *
-                                lastEpochFtdShares) /
-                                lastEpochUserShares;
-                            lastEpochVariableBaseYield -=
-                                lastEpochFtdBaseYield;
-                            lastEpochYieldEarned =
-                                lastEpochFtdBaseYield + additionalFtdYield;
-                        }
-                        lifetimeYieldEarned =
-                            this.calculateFixedTermDepositEarnings(fixedTermDeposit, lastEpochUserTrancheDetails.tranche.balance, lastEpochUserTrancheDetails.tranche.shares);
+                            .lendingPoolTrancheFixedTermConfig.configId]) !== null && _a !== void 0 ? _a : [];
+                        const lastEpochYieldEarned = (_b = lastEpochYield.locks[lockIndex]) !== null && _b !== void 0 ? _b : 0;
+                        const lifetimeYieldEarned = this.calculateFixedTermDepositEarnings(fixedTermDeposit, lastEpochUserTrancheDetails.tranche.balance, lastEpochUserTrancheDetails.tranche.shares);
                         totalLifetimeFtdYield += lifetimeYieldEarned;
-                        totalYieldEarnedLastEpoch += lastEpochYieldEarned;
                         const lockDuration = parseFloat(fixedTermDeposit
                             .lendingPoolTrancheFixedTermConfig
                             .epochLockDuration) * SECONDS_PER_EPOCH;
                         return {
                             lockId: fixedTermDeposit.lockId,
                             configId: fixedTermDeposit
-                                .lendingPoolTrancheFixedTermConfig
-                                .configId,
+                                .lendingPoolTrancheFixedTermConfig.configId,
                             epochLockDuration: fixedTermDeposit
                                 .lendingPoolTrancheFixedTermConfig
                                 .epochLockDuration,
@@ -18188,9 +19456,7 @@ class Portfolio {
                                 .epochInterestRate,
                             epochLockStart: fixedTermDeposit.epochLockStart,
                             amount: this._userLendingService
-                                .convertSharesToAssets(fixedTermDeposit.trancheShares, lastEpochUserTrancheDetails.tranche
-                                .balance, lastEpochUserTrancheDetails.tranche
-                                .shares)
+                                .convertSharesToAssets(fixedTermDeposit.trancheShares, lastEpochUserTrancheDetails.tranche.balance, lastEpochUserTrancheDetails.tranche.shares)
                                 .toString(),
                             endTime: parseInt(fixedTermDeposit.createdOn) +
                                 lockDuration,
@@ -18198,20 +19464,22 @@ class Portfolio {
                             isWithdrawalRequested: fixedTermDeposit.isWithdrawalRequested,
                             startTime: parseInt(fixedTermDeposit.createdOn),
                             yieldEarnings: {
-                                lastEpoch: lastEpochYieldEarned.toString(),
+                                lastEpoch: this.precisionToString(lastEpochYieldEarned),
                                 lifetime: this.precisionToString(lifetimeYieldEarned),
                             },
                             depositDetails: fixedLoanDepositDetails,
                         };
                     });
-                    totalYieldEarnedLastEpoch += lastEpochTotalBaseYield;
+                    // This POOL's last-epoch total: the tranche totals summed, the
+                    // locks counted once (inside `total`).
+                    poolYieldEarnedLastEpoch += lastEpochYield.total;
                     tranches.push(Object.assign(Object.assign({}, tranche), { investedAmount: userTrancheBalance, yieldEarnings: {
-                            lastEpoch: lastEpochVariableBaseYield.toString(),
+                            lastEpoch: this.precisionToString(lastEpochYield.variable),
                             lifetime: this.precisionToString(totalLifetimeFtdYield), // passing in total FTD yield to be subtracted by total trache lifetime later down
                         }, fixedLoans,
                         depositDetails }));
                 }
-                portfolioLendingPoolsPromise.push(Object.assign(Object.assign({}, poolOverview), { totalYieldEarningsLastEpoch: totalYieldEarnedLastEpoch.toString(), totalInvestedAmount: userPoolBalance.balance.toString(), totalYieldEarningsLifetime: userPoolBalance.yieldEarned.toString(), tranches }));
+                portfolioLendingPoolsPromise.push(Object.assign(Object.assign({}, poolOverview), { totalYieldEarningsLastEpoch: this.precisionToString(poolYieldEarnedLastEpoch), totalInvestedAmount: userPoolBalance.balance.toString(), totalYieldEarningsLifetime: userPoolBalance.yieldEarned.toString(), tranches }));
             }
             const portfolioLendingPools = portfolioLendingPoolsPromise.map((pool) => (Object.assign(Object.assign({}, pool), { tranches: pool.tranches.map((tranche) => {
                     const trancheBalance = tranche.investedAmount;
@@ -18229,7 +19497,87 @@ class Portfolio {
                 !parseUnits(pool.totalYieldEarningsLifetime).isZero());
         });
     }
+    /**
+     * The lender's settled yield per cycle (epoch), per pool and tranche —
+     * what the chain credited at each close, NET of the performance fee
+     * (`domain/yield-history.ts`), in the deployment's own stable token. Each
+     * entry runs the same `epochTrancheYield` as `getPortfolioLendingData`'s
+     * last-epoch figures: a tranche's `yieldEarnings.lastEpoch` plus its
+     * locks' equals its entry for the epoch of the tranche's most recently
+     * APPLIED interest (older than the last cycle for a pool that has not
+     * cleared since; no entry, and a figure of 0, when the lender held
+     * nothing at that epoch).
+     *
+     * Sum entries with `aggregateYieldHistory` (all strategies, or one with
+     * `{ poolId }`). Only epochs in which the lender held shares appear — a
+     * new lender gets `[]`. Pools in `UNUSED_LENDING_POOL_IDS` are left out,
+     * as in `lendingPortfolioQuery`; Directus enablement is NOT applied.
+     *
+     * Cost: three parallel `SystemVariables` reads and the positions query in
+     * one round, then one subgraph request per page of the longest series
+     * (1000 rows a page) — normally two subgraph round trips in all, never one
+     * per epoch.
+     *
+     * On a LITE deployment, a subgraph that lacks the entities (a validation
+     * error naming them) yields `[]`; on a full deployment that error throws,
+     * like every other failure (`isEmptyHistoryError`).
+     *
+     * @throws RangeError on a malformed `fromEpoch` / `count`, before any
+     * network read.
+     */
+    getYieldHistory(userAddress_1) {
+        return __awaiter(this, arguments, void 0, function* (userAddress, options = {}) {
+            validateYieldHistoryOptions(options);
+            try {
+                const [currentEpoch, epochZeroStart, epochDuration, positions] = yield Promise.all([
+                    this._systemVariablesAbi.currentEpochNumber(),
+                    this._systemVariablesAbi.epochStartTimestamp(0),
+                    this._systemVariablesAbi.epochDuration(),
+                    this._graph.request(yieldHistoryPositionsQuery, {
+                        userAddress: userAddress.toLowerCase(),
+                        unusedPools: this._kasuConfig.UNUSED_LENDING_POOL_IDS,
+                        first: YIELD_HISTORY_PAGE_SIZE,
+                    }),
+                ]);
+                const window = resolveYieldHistoryWindow(options, currentEpoch.toNumber());
+                if (!window || !positions.user)
+                    return [];
+                const userTranches = [];
+                const tranches = new Set();
+                const locks = [];
+                for (const pool of positions.user.lendingPoolUserDetails) {
+                    for (const position of pool.lendingPoolTrancheUserDetails) {
+                        userTranches.push(position.id);
+                        tranches.add(position.tranche.id);
+                        for (const lock of position.userLendingPoolTrancheFixedTermDepositLocks) {
+                            locks.push(lock.id);
+                        }
+                    }
+                }
+                if (userTranches.length === 0)
+                    return [];
+                const { rows } = yield fetchYieldHistorySeries((variables) => this._graph.request(yieldHistoryPageQuery, variables), { tranches: [...tranches], userTranches, locks }, window);
+                return buildYieldHistory(Object.assign({ positions }, rows), window, {
+                    epochZeroStart: epochZeroStart.toNumber(),
+                    epochDuration: epochDuration.toNumber(),
+                });
+            }
+            catch (error) {
+                if (isEmptyHistoryError(error, this._isLiteDeployment))
+                    return [];
+                throw error;
+            }
+        });
+    }
+    /**
+     * A money figure as a plain decimal string. Below a millionth of a token
+     * (the stable asset's own precision) is float noise, never money, so it
+     * is `'0'` — not `'1e-7'`, which `parseUnits` rejects, nor `'-3e-12'`. A
+     * small negative remainder (above −0.0001) is `'0'` as well.
+     */
     precisionToString(val) {
+        if (Math.abs(val) < 1e-6)
+            return '0';
         if (val < 0 && val > -1e-4) {
             return '0';
         }
@@ -24186,11 +25534,11 @@ class Swapper {
 }
 
 class KasuSdk {
-    constructor(config, signerOrProvider) {
+    constructor(config, signerOrProvider, options = {}) {
         this._graphClient = new GraphQLClient(config.subgraphUrl);
         this.Locking = new KSULocking(config, signerOrProvider);
         this.UserLending = new UserLending(config, signerOrProvider);
-        this.DataService = new DataService(config, signerOrProvider);
+        this.DataService = new DataService(config, signerOrProvider, options.historyProvider);
         this.Portfolio = new Portfolio(config, signerOrProvider);
         this.Swapper = new Swapper();
     }
@@ -24198,7 +25546,7 @@ class KasuSdk {
 
 class SdkConfig {
     constructor(options) {
-        var _a, _b, _c, _d;
+        var _a, _b, _c, _d, _e;
         this.subgraphUrl = options.subgraphUrl;
         this.contracts = options.contracts;
         this.directusUrl = (_a = options.directusUrl) !== null && _a !== void 0 ? _a : '';
@@ -24213,6 +25561,8 @@ class SdkConfig {
         this.isLiteDeployment = (_b = options.isLiteDeployment) !== null && _b !== void 0 ? _b : false;
         this.poolMetadataMapping = (_c = options.poolMetadataMapping) !== null && _c !== void 0 ? _c : {};
         this.stableAssetDecimals = (_d = options.stableAssetDecimals) !== null && _d !== void 0 ? _d : 6;
+        this.historyRpcUrls = [...((_e = options.historyRpcUrls) !== null && _e !== void 0 ? _e : [])];
+        this.chainId = options.chainId;
     }
 }
 
@@ -24519,6 +25869,27 @@ const XDC_RPC_URLS = [
     'https://rpc.xinfin.network',
     'https://rpc.primenumbers.xyz/',
 ];
+/**
+ * XDC RPCs that serve PAST state, for `getPoolTvlHistory` (each verified
+ * with `externalTVLOfPool` at old blocks, CORS `*`), in fallback order. Not
+ * `rpc.xdcrpc.com`, which refuses older blocks, and never `rpc.xdc.org` /
+ * `erpc.xdc.org`. Public and rate-limited.
+ */
+const XDC_HISTORY_RPC_URLS = [
+    'https://rpc.primenumbers.xyz/',
+    'https://rpc.ankr.com/xdc',
+];
+/**
+ * Base RPCs that serve PAST state, in fallback order (each verified with
+ * `externalTVLOfPool` at old blocks; all answer CORS). Not
+ * `base-rpc.publicnode.com`, the default read RPC, which refuses old state.
+ * Public and rate-limited.
+ */
+const BASE_HISTORY_RPC_URLS = [
+    'https://mainnet.base.org',
+    'https://base.drpc.org',
+    'https://1rpc.io/base',
+];
 /**
  * Built-in chain configurations for Kasu-supported networks.
  *
@@ -24562,6 +25933,7 @@ const CHAIN_CONFIGS = {
             'https://base-rpc.publicnode.com',
             'https://mainnet.base.org',
         ],
+        historyRpcUrls: BASE_HISTORY_RPC_URLS,
         blockExplorerUrl: 'https://basescan.org',
     },
     xdc: {
@@ -24598,6 +25970,7 @@ const CHAIN_CONFIGS = {
             currencyCode: 'AUD',
         },
         rpcUrls: XDC_RPC_URLS,
+        historyRpcUrls: XDC_HISTORY_RPC_URLS,
         blockExplorerUrl: 'https://xdcscan.com',
     },
     'xdc-usdc': {
@@ -24630,6 +26003,7 @@ const CHAIN_CONFIGS = {
             currencyCode: 'USD',
         },
         rpcUrls: XDC_RPC_URLS,
+        historyRpcUrls: XDC_HISTORY_RPC_URLS,
         blockExplorerUrl: 'https://xdcscan.com',
     },
     plume: {
@@ -27741,6 +29115,28 @@ class StrategiesFacade {
             return yield this._dataService.getPerformanceFee();
         });
     }
+    /**
+     * The strategy's TVL (total lent by everyone) at every cycle boundary,
+     * then as of now — the data behind a TVL chart. Ascending in time; the
+     * last point (`kind: 'current'`) equals `strategy.tvl.total` when both
+     * calls' reads succeed (see `PoolTvlHistoryEntry`).
+     *
+     * `tvl` is in display units of the deployment's OWN stable token (USDC on
+     * Base and XDC USDC, AUDD on XDC AUDD); `timestamp` is unix SECONDS.
+     * `{ count }` = the newest `count` epochs, `{ fromEpoch }` = from that
+     * epoch on; `timeoutMs` (default 30 s) and `signal` bound the call. A
+     * malformed option throws before any network read. See
+     * `DataService.getPoolTvlHistory` for the reads, the cost and the errors.
+     *
+     * ```ts
+     * const points = await kasu.strategies.getPoolTvlHistory(poolId, { count: 52 });
+     * ```
+     */
+    getPoolTvlHistory(poolId_1) {
+        return __awaiter(this, arguments, void 0, function* (poolId, options = {}) {
+            return yield this._dataService.getPoolTvlHistory(poolId, options);
+        });
+    }
     /**
      * Fetch a single strategy by pool ID. Returns `null` if not found.
      */
@@ -28252,6 +29648,40 @@ class PortfolioFacade {
             return { pools, summary };
         });
     }
+    /**
+     * The lender's settled yield per cycle, per pool and tranche: what each
+     * close credited them, NET of the performance fee (the chain credits it
+     * net), in display units of the deployment's own stable token (AUDD on
+     * XDC AUDD). `epochEnd` is unix seconds. Net only — no gross is offered.
+     *
+     * Validates `options` before any read (`RangeError` on a malformed one).
+     *
+     * ```ts
+     * const entries = await kasu.portfolio.getYieldHistory('0xUser...', { count: 52 });
+     * const allStrategies = aggregateYieldHistory(entries);
+     * const oneStrategy = aggregateYieldHistory(entries, { poolId });
+     * ```
+     *
+     * `getPositions`' `totalYieldEarningsLastEpoch` for a pool equals that
+     * pool's bar for the epoch of its most recently APPLIED interest — which
+     * is older than the last cycle for a pool that has not cleared since (the
+     * bar carries that older `epochId`). A lender who held nothing at that
+     * epoch has no bar there and a figure of 0; their newest bar is from
+     * when they last held shares.
+     *
+     * For a fixed-term lock holder the bars can sum to slightly more than the
+     * lifetime interest (up to about 0.2 %), because each top-up is valued at
+     * today's share price — show "earned to date" from the lifetime figure,
+     * never from the sum of the bars.
+     *
+     * `[]` for a lender with no history, and on a LITE deployment whose
+     * subgraph lacks the entities; on a full deployment that error throws.
+     */
+    getYieldHistory(userAddress, options) {
+        return __awaiter(this, void 0, void 0, function* () {
+            return yield this._portfolio.getYieldHistory(userAddress, options);
+        });
+    }
     /**
      * Fetch a user's full transaction history (deposits, withdrawals, cancellations).
      */
@@ -28308,12 +29738,13 @@ class PortfolioFacade {
  * ```
  */
 class Kasu {
-    constructor(sdk, chainConfig, signerOrProvider, configOverrides) {
+    constructor(sdk, chainConfig, signerOrProvider, configOverrides, historyProvider) {
         var _a, _b;
         this._sdk = sdk;
         this._chainConfig = chainConfig;
         this._signerOrProvider = signerOrProvider;
         this._configOverrides = configOverrides;
+        this._historyProvider = historyProvider;
         this.strategies = new StrategiesFacade(sdk.DataService, sdk.UserLending, normaliseMapping((_a = configOverrides.poolMetadataMapping) !== null && _a !== void 0 ? _a : chainConfig.poolMetadataMapping));
         // Derived ONCE and handed to every facade that needs it. Each of them
         // re-deriving `Signer.isSigner` is how two facades come to disagree
@@ -28351,7 +29782,7 @@ class Kasu {
      * ```
      */
     static create(options) {
-        var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k;
+        var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m;
         const chainConfig = resolveChainConfig(options.chain);
         const overrides = (_a = options.configOverrides) !== null && _a !== void 0 ? _a : {};
         const sdkConfig = new SdkConfig({
@@ -28366,12 +29797,18 @@ class Kasu {
             // of 6. Every live deployment happens to be 6dp today, so the
             // default was right by luck; the next one need not be.
             stableAssetDecimals: (_h = overrides.stableAssetDecimals) !== null && _h !== void 0 ? _h : (_j = stableAssetOf(chainConfig)) === null || _j === void 0 ? void 0 : _j.decimals,
+            historyRpcUrls: (_k = overrides.historyRpcUrls) !== null && _k !== void 0 ? _k : chainConfig.historyRpcUrls,
+            chainId: (_l = overrides.chainId) !== null && _l !== void 0 ? _l : chainConfig.chainId,
         });
-        const signerOrProvider = (_k = options.signerOrProvider) !== null && _k !== void 0 ? _k : defaultProvider(chainConfig, typeof options.chain === 'string'
+        const signerOrProvider = (_m = options.signerOrProvider) !== null && _m !== void 0 ? _m : defaultProvider(chainConfig, typeof options.chain === 'string'
             ? options.chain
             : chainConfig.name);
-        const sdk = new KasuSdk(sdkConfig, signerOrProvider);
-        return new Kasu(sdk, chainConfig, signerOrProvider, overrides);
+        // An explicit history provider wins; otherwise DataService builds
+        // them from `historyRpcUrls`, pinned to `chainId` (the one place).
+        const sdk = new KasuSdk(sdkConfig, signerOrProvider, {
+            historyProvider: options.historyProvider,
+        });
+        return new Kasu(sdk, chainConfig, signerOrProvider, overrides, options.historyProvider);
     }
     /**
      * A NEW instance bound to `signer`, with the same chain config and the same
@@ -28391,6 +29828,7 @@ class Kasu {
             chain: this._chainConfig,
             signerOrProvider: signer,
             configOverrides: this._configOverrides,
+            historyProvider: this._historyProvider,
         });
     }
     /**
@@ -29170,4 +30608,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_KYC_PARAMS_MESSAGE, NO_SPENDER_MESSAGE, NO_WITHDRAWAL_ENCODER_MESSAGE, PortfolioFacade, READ_ONLY_MESSAGE, RIXON_CAPITAL, SECONDS_PER_WEEK, SPONSORED_CALL_KINDS, SPONSORED_CALL_SELECTORS, SdkConfig, SponsoredCallInputError, StrategiesFacade, UPPER_MEZZANINE, WithdrawFlow, accruedInterest, 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, 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, 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, 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 };