@kasufinance/kasu-sdk 2.12.0 → 2.13.0

package/dist/bundle.cjs.js

@@ -1,7 +1,7 @@
 'use strict';
 
-var utils$2 = require('ethers/lib/utils');
 var ethers = require('ethers');
+var utils$2 = require('ethers/lib/utils');
 
 const defaultJsonSerializer = JSON;
 
@@ -15481,6 +15481,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.
@@ -15720,6 +15742,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
@@ -15909,11 +15961,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 utils$2.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, ethers.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) => utils$2.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) {
@@ -15993,6 +16603,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 (!utils$2.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, ethers.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 : ethers.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 ethers.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;
@@ -16133,8 +16931,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',
@@ -18295,35 +19093,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) {
@@ -24767,11 +25536,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();
     }
@@ -24779,7 +25548,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 : '';
@@ -24794,6 +25563,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;
     }
 }
 
@@ -25100,6 +25871,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.
  *
@@ -25143,6 +25935,7 @@ const CHAIN_CONFIGS = {
             'https://base-rpc.publicnode.com',
             'https://mainnet.base.org',
         ],
+        historyRpcUrls: BASE_HISTORY_RPC_URLS,
         blockExplorerUrl: 'https://basescan.org',
     },
     xdc: {
@@ -25179,6 +25972,7 @@ const CHAIN_CONFIGS = {
             currencyCode: 'AUD',
         },
         rpcUrls: XDC_RPC_URLS,
+        historyRpcUrls: XDC_HISTORY_RPC_URLS,
         blockExplorerUrl: 'https://xdcscan.com',
     },
     'xdc-usdc': {
@@ -25211,6 +26005,7 @@ const CHAIN_CONFIGS = {
             currencyCode: 'USD',
         },
         rpcUrls: XDC_RPC_URLS,
+        historyRpcUrls: XDC_HISTORY_RPC_URLS,
         blockExplorerUrl: 'https://xdcscan.com',
     },
     plume: {
@@ -28322,6 +29117,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.
      */
@@ -28923,12 +29740,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
@@ -28966,7 +29784,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({
@@ -28981,12 +29799,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
@@ -29006,6 +29830,7 @@ class Kasu {
             chain: this._chainConfig,
             signerOrProvider: signer,
             configOverrides: this._configOverrides,
+            historyProvider: this._historyProvider,
         });
     }
     /**
@@ -29817,9 +30642,13 @@ exports.MIN_LENDING_AMOUNT_FALLBACK = MIN_LENDING_AMOUNT_FALLBACK;
 exports.MIN_TRANCHE_CAPACITY = MIN_TRANCHE_CAPACITY;
 exports.NOT_A_WITHDRAWAL_CALL_MESSAGE = NOT_A_WITHDRAWAL_CALL_MESSAGE;
 exports.NO_DIRECTUS_URL_MESSAGE = NO_DIRECTUS_URL_MESSAGE;
+exports.NO_HISTORY_PROVIDER_MESSAGE = NO_HISTORY_PROVIDER_MESSAGE;
 exports.NO_KYC_PARAMS_MESSAGE = NO_KYC_PARAMS_MESSAGE;
 exports.NO_SPENDER_MESSAGE = NO_SPENDER_MESSAGE;
 exports.NO_WITHDRAWAL_ENCODER_MESSAGE = NO_WITHDRAWAL_ENCODER_MESSAGE;
+exports.PastStateUnavailableError = PastStateUnavailableError;
+exports.PoolTvlHistoryAbortedError = PoolTvlHistoryAbortedError;
+exports.PoolTvlHistoryTimeoutError = PoolTvlHistoryTimeoutError;
 exports.PortfolioFacade = PortfolioFacade;
 exports.READ_ONLY_MESSAGE = READ_ONLY_MESSAGE;
 exports.RIXON_CAPITAL = RIXON_CAPITAL;
@@ -29898,6 +30727,7 @@ exports.pickHighestYieldTranche = pickHighestYieldTranche;
 exports.pickShortDescription = pickShortDescription;
 exports.poolAllTranchesFull = poolAllTranchesFull;
 exports.poolMaxApy = poolMaxApy;
+exports.poolTvl = poolTvl;
 exports.projectedAnnualEarnings = projectedAnnualEarnings;
 exports.proveDepositInReceipt = proveDepositInReceipt;
 exports.proveUserOperationInReceipt = proveUserOperationInReceipt;