@kasufinance/kasu-sdk 2.12.0 → 2.13.1

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',
@@ -17215,14 +18013,13 @@ const currentEpochFtdAmountQuery = gql `
                 user: $userId
                 lendingPool_in: $poolIds
                 epochId: $currentEpoch
+                type: DepositRequest
             }
         ) {
             fixedTermConfigId
             amountRequested
             tranche {
                 id
-                balance
-                shares
             }
         }
     }
@@ -17237,11 +18034,7 @@ const currentFtdBalanceQuery = gql `
                 configId
                 lendingPoolTranche {
                     id
-                }
-            }
-            lendingPool {
-                balance
-                tranches {
+                    balance
                     shares
                 }
             }
@@ -17249,6 +18042,13 @@ const currentFtdBalanceQuery = gql `
     }
 `;
 
+/** Thrown when the subgraph reports a request type with no known unit. */
+const UNKNOWN_REQUEST_TYPE_MESSAGE = 'UserLending: unknown request type, its amount unit is unknown';
+const KNOWN_REQUEST_TYPES = [
+    'DepositRequest',
+    'WithdrawalRequest',
+];
+const isKnownRequestType = (type) => typeof type === 'string' && KNOWN_REQUEST_TYPES.includes(type);
 class UserLending {
     constructor(_kasuConfig, signerOrProvider) {
         this._kasuConfig = _kasuConfig;
@@ -17410,6 +18210,14 @@ class UserLending {
             ]);
             const retn = [];
             for (const userRequest of subgraphResult.userRequests) {
+                // A request type this SDK does not know has no known amount unit
+                // (the schema also declares types no live deployment emits yet).
+                // Skip that ONE row before anything is priced or read on chain,
+                // rather than failing — and blanking — the lender's whole list.
+                if (!isKnownRequestType(userRequest.type)) {
+                    console.error(`${UNKNOWN_REQUEST_TYPE_MESSAGE}: ${String(userRequest.type)} (request ${userRequest.id}); row skipped`);
+                    continue;
+                }
                 const directusPool = directusResult.find(({ id }) => id === userRequest.lendingPool.id);
                 const trancheName = trancheNames[userRequest.lendingPool.tranches.length - 1][parseInt(userRequest.tranche.orderId)];
                 const events = [];
@@ -17505,9 +18313,7 @@ class UserLending {
                         : 'Withdrawal',
                     trancheName: trancheName,
                     trancheId: userRequest.tranche.id,
-                    requestedAmount: parseUnits(userRequest.tranche.shares).isZero()
-                        ? userRequest.amountRequested
-                        : this.convertSharesToAssets(userRequest.amountRequested, userRequest.tranche.balance, userRequest.tranche.shares).toString(),
+                    requestedAmount: this.requestedAmountInAssets(userRequest),
                     acceptedAmount: userRequest.amountAccepted,
                     rejectedAmount: userRequest.amountRejected,
                     status: userRequest.status,
@@ -17540,8 +18346,11 @@ class UserLending {
             for (const userFTD of currentFtdBalance.userLendingPoolTrancheFixedTermDepositLocks) {
                 const ftdID = parseFloat(userFTD.lendingPoolTrancheFixedTermConfig.configId);
                 const trancheID = userFTD.lendingPoolTrancheFixedTermConfig.lendingPoolTranche.id.toLowerCase();
-                const totalSupply = userFTD.lendingPool.tranches.reduce((total, cur) => total.add(parseEther(cur.shares)), BigNumber.from(0));
-                const amount = this.convertSharesToAssets(userFTD.trancheShares, userFTD.lendingPool.balance, formatEther(totalSupply));
+                // The lock holds shares of ONE tranche, so they are worth that
+                // tranche's share price — not the pool's average across tranches,
+                // which differs whenever the tranches have earned differently.
+                const lockTranche = userFTD.lendingPoolTrancheFixedTermConfig.lendingPoolTranche;
+                const amount = this.convertSharesToAssets(userFTD.trancheShares, lockTranche.balance, lockTranche.shares);
                 const item = (_a = trancheMap.get(trancheID)) !== null && _a !== void 0 ? _a : [];
                 if (item[ftdID]) {
                     item[ftdID] += parseFloat(amount);
@@ -17556,25 +18365,40 @@ class UserLending {
     }
     getCurrentEpochFtdAmount(poolIds, userId, currentEpoch) {
         return __awaiter(this, void 0, void 0, function* () {
+            var _a, _b;
             const currentEpochFtdAmountRes = yield this._graph.request(currentEpochFtdAmountQuery, {
                 userId: userId.toLowerCase(),
                 poolIds: poolIds.map((id) => id.toLowerCase()),
                 currentEpoch: parseFloat(currentEpoch),
             });
-            const currentEpochFtdAmounts = new Map();
+            // Deposit requests only (the query filters on type): a deposit's
+            // `amountRequested` is already an ASSET amount, so it is summed as it
+            // is — never put through a share price. Summed, not assigned: a
+            // cancelled request and its replacement share a tranche and a config
+            // in one epoch, and the cancelled one's 0 must not overwrite the live
+            // amount.
+            const totals = new Map();
             for (const userRequest of currentEpochFtdAmountRes.userRequests) {
                 const ftdID = parseFloat(userRequest.fixedTermConfigId);
-                const item = currentEpochFtdAmounts.get(userRequest.tranche.id);
-                const amountRequested = this.convertSharesToAssets(userRequest.amountRequested, userRequest.tranche.balance, userRequest.tranche.shares);
-                if (item) {
-                    const clonedItem = [...item];
-                    clonedItem[ftdID] = amountRequested;
-                    currentEpochFtdAmounts.set(userRequest.tranche.id, clonedItem);
+                if (!Number.isInteger(ftdID) || ftdID < 0)
                     continue;
-                }
+                const perConfig = (_a = totals.get(userRequest.tranche.id)) !== null && _a !== void 0 ? _a : new Map();
+                perConfig.set(ftdID, ((_b = perConfig.get(ftdID)) !== null && _b !== void 0 ? _b : BigNumber.from(0)).add(parseUnits(userRequest.amountRequested)));
+                totals.set(userRequest.tranche.id, perConfig);
+            }
+            // A slot whose total is zero is left out — `'0.0'` is a truthy
+            // string, and a caller testing the slot would read it as an amount.
+            // A tranche with no non-zero slot is left out entirely.
+            const currentEpochFtdAmounts = new Map();
+            for (const [trancheId, perConfig] of totals) {
                 const ftdAmounts = [];
-                ftdAmounts[ftdID] = amountRequested;
-                currentEpochFtdAmounts.set(userRequest.tranche.id, ftdAmounts);
+                for (const [ftdID, total] of perConfig) {
+                    if (total.gt(0))
+                        ftdAmounts[ftdID] = formatUnits(total);
+                }
+                if (ftdAmounts.length) {
+                    currentEpochFtdAmounts.set(trancheId, ftdAmounts);
+                }
             }
             return currentEpochFtdAmounts;
         });
@@ -17595,6 +18419,31 @@ class UserLending {
             return amountMap;
         });
     }
+    /**
+     * A request's outstanding amount in ASSETS (the deployment's stable token).
+     *
+     * The subgraph's `UserRequest.amountRequested` is denominated by request
+     * type. A DEPOSIT request holds assets: the deposit NFT's `assetAmount`,
+     * top-ups added, accepted and rejected amounts taken off. A WITHDRAWAL
+     * request holds tranche SHARES: the withdrawal NFT's `sharesAmount`,
+     * accepted shares taken off. So only a withdrawal is converted, at the
+     * tranche's current share price; a deposit passes through unchanged —
+     * pricing it as shares overstated it by the share price.
+     */
+    requestedAmountInAssets(userRequest) {
+        switch (userRequest.type) {
+            case 'DepositRequest':
+                return userRequest.amountRequested;
+            case 'WithdrawalRequest':
+                return this.convertSharesToAssets(userRequest.amountRequested, userRequest.tranche.balance, userRequest.tranche.shares);
+            default: {
+                // Fail closed: a type this SDK does not know has no known
+                // unit, and pricing it either way would print a wrong figure.
+                const unknownType = userRequest.type;
+                throw new Error(`${UNKNOWN_REQUEST_TYPE_MESSAGE}: ${unknownType}`);
+            }
+        }
+    }
     convertSharesToAssets(sharesAmount, totalAssets, totalSupply) {
         if (parseUnits(totalSupply).isZero())
             return '0';
@@ -18293,35 +19142,6 @@ function buildYieldHistory(read, window, clock) {
         a.poolId.localeCompare(b.poolId) ||
         a.trancheId.localeCompare(b.trancheId));
 }
-/**
- * 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 `getYieldHistory` 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);
-}
 
 class Portfolio {
     constructor(_kasuConfig, signerOrProvider) {
@@ -24765,11 +25585,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();
     }
@@ -24777,7 +25597,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 : '';
@@ -24792,6 +25612,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;
     }
 }
 
@@ -25098,6 +25920,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.
  *
@@ -25141,6 +25984,7 @@ const CHAIN_CONFIGS = {
             'https://base-rpc.publicnode.com',
             'https://mainnet.base.org',
         ],
+        historyRpcUrls: BASE_HISTORY_RPC_URLS,
         blockExplorerUrl: 'https://basescan.org',
     },
     xdc: {
@@ -25177,6 +26021,7 @@ const CHAIN_CONFIGS = {
             currencyCode: 'AUD',
         },
         rpcUrls: XDC_RPC_URLS,
+        historyRpcUrls: XDC_HISTORY_RPC_URLS,
         blockExplorerUrl: 'https://xdcscan.com',
     },
     'xdc-usdc': {
@@ -25209,6 +26054,7 @@ const CHAIN_CONFIGS = {
             currencyCode: 'USD',
         },
         rpcUrls: XDC_RPC_URLS,
+        historyRpcUrls: XDC_HISTORY_RPC_URLS,
         blockExplorerUrl: 'https://xdcscan.com',
     },
     plume: {
@@ -28320,6 +29166,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.
      */
@@ -28644,17 +29512,24 @@ function cancelDeadline(request, nextEpochStart, nowSeconds) {
 const isCancelled = (events) => events.some((e) => e.requestType === 'Cancelled');
 const isForced = (events) => events.some((e) => e.requestType === 'Forced');
 const initiatedEvent = (events) => events.find((e) => e.requestType === 'Initiated');
-/**
- * Subgraph behaviour: when a request is cancelled, the on-request
- * `requestedAmount` field is reset to 0 (the lender's effective balance is
- * restored). The original amount survives on the `Initiated` event's
- * `assetAmount`. Recover from there so cancelled rows still carry the amount
- * the lender originally asked for.
- */
+/** `assetAmount` of the `Initiated` event, or 0 when there is none. */
 const initiatedAmountOf = (events) => {
     const initiated = initiatedEvent(events);
     return initiated ? Number(initiated.assetAmount || '0') : 0;
 };
+/**
+ * Subgraph behaviour: when a request is cancelled, the on-request
+ * `requestedAmount` field is reset to 0 (the lender's effective balance is
+ * restored). The amount cancelled survives on the `Cancelled` event's
+ * `assetAmount` — everything still outstanding at the cancel, top-ups
+ * included. Only when that event carries no figure does this fall back to the
+ * `Initiated` event, which holds the FIRST submission alone and so misses
+ * every top-up.
+ */
+const cancelledAmountOf = (events) => {
+    const cancelledEvent = events.find((e) => e.requestType === 'Cancelled');
+    return num(cancelledEvent === null || cancelledEvent === void 0 ? void 0 : cancelledEvent.assetAmount) || initiatedAmountOf(events);
+};
 /**
  * A deposit is REALLOCATED when the timeline carries a `Reallocated` event, or
  * an `Accepted` event into a tranche other than the one requested.
@@ -28679,17 +29554,15 @@ const numOrNull = (str) => {
  * Convert a `UserRequest` into a `RequestState`. Pure — no clock, no network,
  * no copy.
  *
- * BRANCH ORDER (this IS the behaviour; it reproduces kasu-ui's
- * `deriveTransactionView` check for check):
+ * BRANCH ORDER (this IS the behaviour):
  *
  *   1. a `Cancelled` event                      → `cancelled`, neutral, 0
  *   2. a withdrawal with a `Forced` event       → `forced`, outflow, −accepted
  *   3. a reallocated deposit                    → `reallocated`, inflow, +accepted
- *   4. a withdrawal partly filled with a LIVE
- *      remainder (cycle still open)             → `partial`, outflow, −accepted
+ *   4. a withdrawal partly filled (paid > 0) with
+ *      a LIVE remainder (queued > 0, cycle open) → `partial`, outflow, −accepted
  *   5. resolved (`status === 'Processed'`):
- *        withdrawal, partly filled              → `partial`, outflow, −accepted
- *        withdrawal, fully filled               → `complete`, outflow, −accepted
+ *        withdrawal (nothing left queued)       → `complete`, outflow, −accepted
  *        deposit, nothing accepted              → `rejected`, neutral, 0
  *        deposit, part rejected                 → `partial`, inflow, +accepted
  *        deposit, fully accepted                → `complete`, inflow, +accepted
@@ -28717,10 +29590,10 @@ function deriveRequestState(request) {
     const isWithdrawal = request.requestType === 'Withdrawal';
     const cancelled = isCancelled(request.events);
     // Cancelled requests have `requestedAmount` zeroed on the request itself;
-    // pull the original value from the Initiated event so the row still
-    // carries "100 cancelled" instead of "0 cancelled".
+    // take the amount from the Cancelled event so the row still carries
+    // "1500 cancelled" (1000 + a 500 top-up) instead of "0 cancelled".
     const requested = cancelled
-        ? num(request.requestedAmount) || initiatedAmountOf(request.events)
+        ? num(request.requestedAmount) || cancelledAmountOf(request.events)
         : num(request.requestedAmount);
     const accepted = num(request.acceptedAmount);
     const rejected = num(request.rejectedAmount);
@@ -28771,18 +29644,23 @@ function deriveRequestState(request) {
     }
     // 4. Withdrawal partly filled with a LIVE remainder: the request returns
     // to the queue with a live Cancel. Checked BEFORE the resolved branch and
-    // via `isCycleClosed`, never via the sticky raw status.
+    // via `isCycleClosed`, never via the sticky raw status. `requested` is
+    // what is still OUTSTANDING, so "partly filled" is "something paid AND
+    // something still queued" — never a comparison of the two, which would
+    // turn on whether more was paid than is left.
     if (isWithdrawal &&
         accepted > 0 &&
-        accepted < requested &&
+        requested > 0 &&
         !isCycleClosed(request)) {
         return Object.assign(Object.assign({}, base), { kind: 'outflow', amount: -accepted, statusCode: 'partial' });
     }
     // 5. Resolved — a rejection IS a resolution.
     if (request.status === UserRequestStatus.PROCESSED) {
+        // A withdrawal is resolved only once nothing is left queued — a
+        // partly filled one returns to the queue (branch 4), and one cancelled
+        // with a remainder is branch 1 — so a resolved withdrawal is complete.
         if (isWithdrawal) {
-            const partly = accepted < requested;
-            return Object.assign(Object.assign({}, base), { kind: 'outflow', amount: -accepted, statusCode: partly ? 'partial' : 'complete' });
+            return Object.assign(Object.assign({}, base), { kind: 'outflow', amount: -accepted, statusCode: 'complete' });
         }
         // Deposit: full reject vs partial vs full accept.
         if (accepted === 0) {
@@ -28921,12 +29799,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
@@ -28964,7 +29843,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({
@@ -28979,12 +29858,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
@@ -29004,6 +29889,7 @@ class Kasu {
             chain: this._chainConfig,
             signerOrProvider: signer,
             configOverrides: this._configOverrides,
+            historyProvider: this._historyProvider,
         });
     }
     /**
@@ -29783,4 +30669,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, 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, 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 };