@kasufinance/kasu-sdk 2.14.0 → 2.16.0

package/dist/services/Portfolio/portfolio.js

@@ -8,18 +8,69 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
     });
 };
 import { BigNumber } from 'ethers';
-import { formatEther, parseEther, parseUnits } from 'ethers/lib/utils';
+import { formatEther, formatUnits, parseEther, parseUnits, } from 'ethers/lib/utils';
 import { GraphQLClient } from 'graphql-request';
 import { IKasuNFTsAbi__factory, ISystemVariablesAbi__factory, IUserLoyaltyRewardsAbi__factory, } from '../../contracts';
-import { epochTrancheYield, } from '../../domain/yield-history';
 import { isLiteDeployment } from '../../utils/deployment-mode';
 import { DataService } from '../DataService/data-service';
 import { getAllTrancheConfigurationsQuery, getAllTranchesQuery, } from '../DataService/queries';
 import { KSULocking } from '../Locking/locking';
 import { getSystemVariablesQuery, lockingSummariesQuery, } from '../Locking/queries';
+import { isBlockUnavailableError } from '../shared';
 import { UserLending } from '../UserLending/user-lending';
 import { lendingPortfolioQuery } from './queries';
-import { buildYieldHistory, fetchYieldHistorySeries, isEmptyHistoryError, resolveYieldHistoryWindow, validateYieldHistoryOptions, YIELD_HISTORY_PAGE_SIZE, yieldHistoryPageQuery, yieldHistoryPositionsQuery, } from './yield-history';
+import { buildYieldHistory, clearingStarts, fetchYieldHistorySeries, isEmptyHistoryError, positionEpochYield, positionSeriesFrom, resolveYieldHistoryWindow, validateYieldHistoryOptions, YIELD_HISTORY_PAGE_SIZE, yieldHistoryPageQuery, yieldHistoryPositionsQuery, } from './yield-history';
+/**
+ * How many epochs back the portfolio read pairs a tranche's newest interest
+ * with the shares in force at its clearing (`lendingPortfolioQuery`): the last
+ * six settled epochs, so a pool whose clearings run late or lag a few weeks
+ * behind the others (Base has one) is paired too. A pool whose newest
+ * interest is older (pools clear independently; some only when the
+ * originator repays) is priced from a history read of its own, at that
+ * epoch. The extra rows are a few per lender and tranche.
+ */
+const RECENT_PAIRING_EPOCHS = 6;
+/**
+ * The ledger (subgraph) and the chain agree on a balance AT THE SAME BLOCK
+ * within a cent, or a millionth of it — the rounding of two share-price
+ * conversions.
+ */
+const BALANCE_RECONCILE_TOLERANCE = 0.01;
+const BALANCE_RECONCILE_RELATIVE = 1e-6;
+function ledgerAgrees(ledger, chain) {
+    return (Math.abs(ledger - chain) <=
+        Math.max(BALANCE_RECONCILE_TOLERANCE, Math.abs(chain) * BALANCE_RECONCILE_RELATIVE));
+}
+/**
+ * A list read with `first: $first` that comes back FULL may have been cut:
+ * refuse it rather than price from a truncated read.
+ */
+function refuseTruncated(data) {
+    var _a, _b;
+    const full = (rows) => { var _a; return ((_a = rows === null || rows === void 0 ? void 0 : rows.length) !== null && _a !== void 0 ? _a : 0) >= YIELD_HISTORY_PAGE_SIZE; };
+    const lists = [
+        ['lendingPoolClearings', full(data.lendingPoolClearings)],
+        ['recentWithdrawalsAccepted', full(data.recentWithdrawalsAccepted)],
+    ];
+    for (const pool of (_b = (_a = data.user) === null || _a === void 0 ? void 0 : _a.lendingPoolUserDetails) !== null && _b !== void 0 ? _b : []) {
+        for (const position of pool.lendingPoolTrancheUserDetails) {
+            lists.push([
+                'recentUserShareUpdates',
+                full(position.recentUserShareUpdates),
+            ], [
+                'recentTrancheShareUpdates',
+                full(position.tranche.recentTrancheShareUpdates),
+            ], ...position.userLendingPoolTrancheFixedTermDepositLocks.map((lock) => [
+                'lockSharesRecent',
+                full(lock.lockSharesRecent),
+            ]));
+        }
+    }
+    const cut = lists.find(([, isFull]) => isFull);
+    if (cut) {
+        throw new Error(`getPortfolioLendingData: ${cut[0]} reached ${String(YIELD_HISTORY_PAGE_SIZE)} rows; refusing a possibly truncated read`);
+    }
+}
 export class Portfolio {
     constructor(_kasuConfig, signerOrProvider) {
         this._kasuConfig = _kasuConfig;
@@ -237,23 +288,52 @@ export class Portfolio {
     }
     getPortfolioLendingData(userAddress, poolOverviews, currentEpoch, provider) {
         return __awaiter(this, void 0, void 0, function* () {
-            var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m;
+            var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p, _q, _r;
             const SECONDS_PER_EPOCH = 604800; // seconds in a week
             const portfolioLendingPoolsPromise = [];
             const previousEpoch = BigNumber.from(currentEpoch).sub(BigNumber.from(1));
-            const [lastEpochData, portfolioUserTrancheBalances, userPoolBalances] = yield Promise.all([
-                this._graph.request(lendingPortfolioQuery, {
-                    userAddress: userAddress.toLowerCase(),
-                    epochId: parseFloat(currentEpoch),
-                    lastEpochId: previousEpoch.toNumber(),
-                    unusedPools: this._kasuConfig.UNUSED_LENDING_POOL_IDS,
-                    first: YIELD_HISTORY_PAGE_SIZE,
-                }),
-                this._userLendingService.getPortfolioUserTrancheBalances(userAddress),
-                this._userLendingService.getUserPoolBalance(userAddress, poolOverviews.map(({ id }) => id), provider),
-            ]);
+            const recentEpoch = Math.max(0, previousEpoch.toNumber() - (RECENT_PAIRING_EPOCHS - 1));
+            const unused = new Set(this._kasuConfig.UNUSED_LENDING_POOL_IDS.map((id) => id.toLowerCase()));
+            const listedPools = poolOverviews.filter(({ id }) => !unused.has(id.toLowerCase()));
+            const lastEpochData = yield this._graph.request(lendingPortfolioQuery, {
+                userAddress: userAddress.toLowerCase(),
+                epochId: parseFloat(currentEpoch),
+                lastEpochId: previousEpoch.toNumber(),
+                recentEpoch,
+                lockRecentEpoch: Math.max(0, recentEpoch - 1),
+                unusedPools: this._kasuConfig.UNUSED_LENDING_POOL_IDS,
+                poolIds: listedPools.map(({ id }) => id.toLowerCase()),
+                trancheIds: listedPools.flatMap(({ tranches }) => tranches.map(({ id }) => id.toLowerCase())),
+                first: YIELD_HISTORY_PAGE_SIZE,
+            });
             if (!lastEpochData.user)
                 return [];
+            refuseTruncated(lastEpochData);
+            // The pools the lender has a ledger in AND that are listed: the only
+            // ones read on chain, and the only ones reported.
+            const userPools = listedPools.flatMap((overview) => {
+                var _a;
+                const details = (_a = lastEpochData.user) === null || _a === void 0 ? void 0 : _a.lendingPoolUserDetails.find(({ lendingPool }) => lendingPool.id.toLowerCase() === overview.id.toLowerCase());
+                return details ? [{ overview, details }] : [];
+            });
+            const recentStarts = clearingStarts(lastEpochData.lendingPoolClearings);
+            const recentExits = new Map();
+            for (const exit of lastEpochData.recentWithdrawalsAccepted) {
+                const list = (_a = recentExits.get(exit.tranche.id)) !== null && _a !== void 0 ? _a : [];
+                list.push(exit);
+                recentExits.set(exit.tranche.id, list);
+            }
+            const [chain, staleYields] = yield Promise.all([
+                this.readChainAt((_b = lastEpochData._meta) === null || _b === void 0 ? void 0 : _b.block.number, (blockTag) => this._userLendingService.getUserPoolBalancesAt(userAddress, userPools.map(({ overview }) => overview.id), provider, blockTag)),
+                this.staleLastEpochYields(userPools.flatMap(({ overview, details }) => details.lendingPoolTrancheUserDetails.map((position) => ({
+                    poolId: overview.id,
+                    position,
+                }))), recentEpoch),
+            ]);
+            const reconciled = yield Promise.all(userPools.map(({ overview, details }, index) => {
+                var _a;
+                return this.reconcilePool(userAddress, overview, details, (_a = chain.values[index]) !== null && _a !== void 0 ? _a : BigNumber.from(0), chain.blockTag, provider);
+            }));
             const userRequestsMap = new Map();
             for (const userRequest of lastEpochData.userRequests) {
                 const trancheId = userRequest.tranche.id;
@@ -279,28 +359,22 @@ export class Portfolio {
                         continue;
                     }
                     userRequestsMap.set(trancheId, Object.assign(Object.assign({}, mappedUserRequest), { [ftdId]: [
-                            ...((_a = mappedUserRequest[ftdId]) !== null && _a !== void 0 ? _a : []),
+                            ...((_c = mappedUserRequest[ftdId]) !== null && _c !== void 0 ? _c : []),
                             userRequestFtdItem,
                         ] }));
                 }
             }
-            let totalInvestments = BigNumber.from(0);
-            for (const poolOverview of poolOverviews) {
-                const userPoolBalance = userPoolBalances.find(({ poolId }) => poolId === poolOverview.id);
-                if (!userPoolBalance) {
-                    continue;
-                }
-                totalInvestments = userPoolBalance.balance.add(totalInvestments);
+            for (const [poolIndex, { overview: poolOverview, details },] of userPools.entries()) {
+                const pool = reconciled[poolIndex];
                 const tranches = [];
                 let poolYieldEarnedLastEpoch = 0;
-                const lendingPoolUserDetails = lastEpochData.user.lendingPoolUserDetails.find(({ lendingPool }) => lendingPool.id === poolOverview.id);
-                if (!lendingPoolUserDetails)
-                    continue;
-                const portfolioUserTrancheBalance = portfolioUserTrancheBalances.get(poolOverview.id);
+                // A ledger crediting shares the wallet does not hold earns
+                // nothing we can vouch for: its last-cycle figures are withheld.
+                const withheld = ((_d = pool.mismatch) === null || _d === void 0 ? void 0 : _d.kind) === 'ledger-exceeds-chain';
                 for (const tranche of poolOverview.tranches) {
-                    const lastEpochUserTrancheDetails = lendingPoolUserDetails.lendingPoolTrancheUserDetails.find((lendingPool) => lendingPool.tranche.id === tranche.id);
+                    const lastEpochUserTrancheDetails = details.lendingPoolTrancheUserDetails.find((lendingPool) => lendingPool.tranche.id === tranche.id);
                     const userRequest = userRequestsMap.get(tranche.id);
-                    const depositDetails = (_b = userRequest === null || userRequest === void 0 ? void 0 : userRequest['0']) !== null && _b !== void 0 ? _b : [];
+                    const depositDetails = (_e = userRequest === null || userRequest === void 0 ? void 0 : userRequest['0']) !== null && _e !== void 0 ? _e : [];
                     if (!lastEpochUserTrancheDetails) {
                         tranches.push(Object.assign(Object.assign({}, tranche), { investedAmount: {
                                 balance: '0',
@@ -311,55 +385,61 @@ export class Portfolio {
                             }, depositDetails, fixedLoans: [] }));
                         continue;
                     }
-                    const lastEpoch = previousEpoch.toNumber();
-                    const userHasLastEpochShares = Boolean((_c = lastEpochUserTrancheDetails
-                        .lendingPoolTrancheUserEpochSharesUpdates) === null || _c === void 0 ? void 0 : _c.length);
+                    // The tranche's newest interest (epoch E), priced with the
+                    // shares in force when clearing E applied it — the one
+                    // selection `getYieldHistory` makes (`positionEpochYield`).
+                    // Inside the recent window the candidates below are complete.
+                    // An older E (a pool that clears rarely — some only when the
+                    // originator repays) is priced from a history read of its own,
+                    // and is 0 for a lender who has left the tranche.
+                    const newestInterest = (_f = lastEpochUserTrancheDetails.tranche
+                        .lendingPoolTrancheEpochInterest) === null || _f === void 0 ? void 0 : _f[0];
+                    const interestEpoch = (newestInterest === null || newestInterest === void 0 ? void 0 : newestInterest.epochId) === undefined
+                        ? undefined
+                        : Number(newestInterest.epochId);
                     const fixedTermDeposits = lastEpochUserTrancheDetails.userLendingPoolTrancheFixedTermDepositLocks;
-                    // The one per-epoch formula `getYieldHistory` runs too, with
-                    // the same share selection — so the last bar of a history
-                    // equals these figures.
-                    const lastEpochYield = epochTrancheYield({
-                        epochInterest: parseFloat((_f = (_e = (_d = lastEpochUserTrancheDetails.tranche
-                            .lendingPoolTrancheEpochInterest) === null || _d === void 0 ? void 0 : _d[0]) === null || _e === void 0 ? void 0 : _e.epochInterestAmount) !== null && _f !== void 0 ? _f : '0'),
-                        userShares: parseFloat((_j = (_h = (_g = lastEpochUserTrancheDetails
-                            .lendingPoolTrancheUserEpochSharesUpdates) === null || _g === void 0 ? void 0 : _g[0]) === null || _h === void 0 ? void 0 : _h.shares) !== null && _j !== void 0 ? _j : '0'),
-                        trancheShares: parseFloat((_m = (_l = (_k = lastEpochUserTrancheDetails.tranche
-                            .lendingPoolTrancheShareUpdates) === null || _k === void 0 ? void 0 : _k[0]) === null || _l === void 0 ? void 0 : _l.shares) !== null && _m !== void 0 ? _m : '0'),
-                        trancheBalanceNow: parseFloat(lastEpochUserTrancheDetails.tranche.balance),
-                        trancheSharesNow: parseFloat(lastEpochUserTrancheDetails.tranche.shares),
-                        locks: fixedTermDeposits.map((fixedTermDeposit) => {
-                            var _a, _b, _c, _d, _e, _f;
-                            return ({
-                                active: parseFloat(fixedTermDeposit.epochLockStart) <
-                                    lastEpoch &&
-                                    parseFloat(fixedTermDeposit.epochLockEnd) >=
-                                        lastEpoch &&
-                                    userHasLastEpochShares,
-                                // No snapshot = the lock's opening shares, exactly
-                                // as `getYieldHistory` reads it: a lock made after
-                                // clearing E starts at E with its first update
-                                // tagged E + 1. Never the CURRENT shares, which
-                                // would carry a top-up from a clearing that ran
-                                // after the last settled epoch.
-                                sharesAtEpoch: parseFloat((_c = (_b = (_a = fixedTermDeposit.lockSharesAtLastEpoch) === null || _a === void 0 ? void 0 : _a[0]) === null || _b === void 0 ? void 0 : _b.shares) !== null && _c !== void 0 ? _c : fixedTermDeposit.initialTrancheShares),
-                                sharesBeforeEpoch: parseFloat((_f = (_e = (_d = fixedTermDeposit
-                                    .userLendingPoolTrancheFixedTermDepositLockShareUpdate) === null || _d === void 0 ? void 0 : _d[0]) === null || _e === void 0 ? void 0 : _e.shares) !== null && _f !== void 0 ? _f : fixedTermDeposit.initialTrancheShares),
-                            });
-                        }),
-                    });
-                    const userTrancheBalance = {
-                        balance: '0',
-                        yieldEarned: 0,
+                    const noYield = {
+                        total: 0,
+                        variable: 0,
+                        locks: fixedTermDeposits.map(() => 0),
                     };
-                    if (portfolioUserTrancheBalance) {
-                        const portfolioUserTranche = portfolioUserTrancheBalance.find(({ trancheId }) => trancheId === tranche.id);
-                        if (portfolioUserTranche) {
-                            userTrancheBalance.balance =
-                                portfolioUserTranche.userBalance;
-                            userTrancheBalance.yieldEarned =
-                                portfolioUserTranche.yieldEarned;
-                        }
+                    let lastEpochYield = noYield;
+                    if (interestEpoch !== undefined &&
+                        interestEpoch < recentEpoch &&
+                        !withheld) {
+                        lastEpochYield =
+                            (_g = staleYields.get(lastEpochUserTrancheDetails.id)) !== null && _g !== void 0 ? _g : noYield;
+                    }
+                    else if (interestEpoch !== undefined && !withheld) {
+                        lastEpochYield = positionEpochYield({
+                            trancheBalanceNow: parseFloat(lastEpochUserTrancheDetails.tranche.balance),
+                            trancheSharesNow: parseFloat(lastEpochUserTrancheDetails.tranche.shares),
+                            userUpdates: [
+                                ...((_h = lastEpochUserTrancheDetails.lendingPoolTrancheUserEpochSharesUpdates) !== null && _h !== void 0 ? _h : []),
+                                ...((_j = lastEpochUserTrancheDetails.recentUserShareUpdates) !== null && _j !== void 0 ? _j : []),
+                            ],
+                            trancheUpdates: [
+                                ...((_k = lastEpochUserTrancheDetails.tranche
+                                    .lendingPoolTrancheShareUpdates) !== null && _k !== void 0 ? _k : []),
+                                ...((_l = lastEpochUserTrancheDetails.tranche
+                                    .recentTrancheShareUpdates) !== null && _l !== void 0 ? _l : []),
+                            ],
+                            exits: (_m = recentExits.get(tranche.id)) !== null && _m !== void 0 ? _m : [],
+                            locks: fixedTermDeposits.map((lock) => {
+                                var _a, _b;
+                                return (Object.assign(Object.assign({}, lock), { updates: [
+                                        ...((_a = lock.lockSharesBase) !== null && _a !== void 0 ? _a : []),
+                                        ...((_b = lock.lockSharesRecent) !== null && _b !== void 0 ? _b : []),
+                                    ] }));
+                            }),
+                        }, interestEpoch, parseFloat((_o = newestInterest === null || newestInterest === void 0 ? void 0 : newestInterest.epochInterestAmount) !== null && _o !== void 0 ? _o : '0'), (_p = recentStarts
+                            .get(poolOverview.id.toLowerCase())) === null || _p === void 0 ? void 0 : _p.get(interestEpoch)).yield;
                     }
+                    const ledger = pool.tranches.get(tranche.id);
+                    const userTrancheBalance = {
+                        balance: (_q = ledger === null || ledger === void 0 ? void 0 : ledger.balance) !== null && _q !== void 0 ? _q : '0',
+                        yieldEarned: (_r = ledger === null || ledger === void 0 ? void 0 : ledger.yieldEarned) !== null && _r !== void 0 ? _r : 0,
+                    };
                     let totalLifetimeFtdYield = 0;
                     const fixedLoans = fixedTermDeposits.map((fixedTermDeposit, lockIndex) => {
                         var _a, _b;
@@ -407,7 +487,9 @@ export class Portfolio {
                         }, fixedLoans,
                         depositDetails }));
                 }
-                portfolioLendingPoolsPromise.push(Object.assign(Object.assign({}, poolOverview), { totalYieldEarningsLastEpoch: this.precisionToString(poolYieldEarnedLastEpoch), totalInvestedAmount: userPoolBalance.balance.toString(), totalYieldEarningsLifetime: userPoolBalance.yieldEarned.toString(), tranches }));
+                portfolioLendingPoolsPromise.push(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign({}, poolOverview), { totalYieldEarningsLastEpoch: this.precisionToString(poolYieldEarnedLastEpoch), totalInvestedAmount: pool.chainBalance.toString(), totalYieldEarningsLifetime: pool.lifetime.toString() }), (pool.mismatch ? { ledgerMismatch: pool.mismatch } : {})), (chain.blockTag === undefined
+                    ? { chainPinned: false }
+                    : {})), { tranches }));
             }
             const portfolioLendingPools = portfolioLendingPoolsPromise.map((pool) => (Object.assign(Object.assign({}, pool), { tranches: pool.tranches.map((tranche) => {
                     const trancheBalance = tranche.investedAmount;
@@ -418,7 +500,14 @@ export class Portfolio {
                     }, BigNumber.from(0));
                     const totalTrancheYieldEarned = trancheBalance.yieldEarned.toFixed(6);
                     const totalTrancheFtdYieldEarned = parseFloat(tranche.yieldEarnings.lifetime).toFixed(6);
-                    return Object.assign(Object.assign({}, tranche), { investedAmount: formatEther(parseEther(trancheBalance.balance).sub(lockedAmount)), yieldEarnings: Object.assign(Object.assign({}, tranche.yieldEarnings), { lifetime: this.precisionToString(parseFloat(totalTrancheYieldEarned) -
+                    // Never negative: a variable balance below the locked
+                    // amount is a ledger the chain does not back (the pool
+                    // carries `ledgerMismatch`), not money owed — flagged.
+                    const variableBalance = parseEther(trancheBalance.balance).sub(lockedAmount);
+                    const floored = variableBalance.isNegative();
+                    return Object.assign(Object.assign(Object.assign(Object.assign({}, tranche), { investedAmount: formatEther(floored ? BigNumber.from(0) : variableBalance) }), (floored
+                        ? { investedAmountFloored: true }
+                        : {})), { yieldEarnings: Object.assign(Object.assign({}, tranche.yieldEarnings), { lifetime: this.precisionToString(parseFloat(totalTrancheYieldEarned) -
                                 parseFloat(totalTrancheFtdYieldEarned)) }) });
                 }) })));
             return portfolioLendingPools.filter((pool) => !parseUnits(pool.totalInvestedAmount).isZero() ||
@@ -444,7 +533,12 @@ export class Portfolio {
      * Cost: three parallel `SystemVariables` reads and the positions query in
      * one round, then one subgraph request per page of the longest series
      * (1000 rows a page) — normally two subgraph round trips in all, never one
-     * per epoch.
+     * per epoch — alongside one `LendingPool.userBalance` call per pool at
+     * the subgraph's block. A pool whose ledger credits more than the wallet
+     * holds at that block (shares moved away outside a withdrawal) is left
+     * out; if the node says it cannot serve that block, `latest` is read
+     * and nothing is. Any other failure of those reads (a rate limit, a
+     * network error) THROWS: the history needs a working RPC.
      *
      * On a LITE deployment, a subgraph that lacks the entities (a validation
      * error naming them) yields `[]`; on a full deployment that error throws,
@@ -455,6 +549,7 @@ export class Portfolio {
      */
     getYieldHistory(userAddress_1) {
         return __awaiter(this, arguments, void 0, function* (userAddress, options = {}) {
+            var _a;
             validateYieldHistoryOptions(options);
             try {
                 const [currentEpoch, epochZeroStart, epochDuration, positions] = yield Promise.all([
@@ -473,7 +568,9 @@ export class Portfolio {
                 const userTranches = [];
                 const tranches = new Set();
                 const locks = [];
+                const pools = [];
                 for (const pool of positions.user.lendingPoolUserDetails) {
+                    pools.push(pool.lendingPool.id);
                     for (const position of pool.lendingPoolTrancheUserDetails) {
                         userTranches.push(position.id);
                         tranches.add(position.tranche.id);
@@ -484,11 +581,33 @@ export class Portfolio {
                 }
                 if (userTranches.length === 0)
                     return [];
-                const { rows } = yield fetchYieldHistorySeries((variables) => this._graph.request(yieldHistoryPageQuery, variables), { tranches: [...tranches], userTranches, locks }, window);
+                const [{ rows }, chain] = yield Promise.all([
+                    fetchYieldHistorySeries((variables) => this._graph.request(yieldHistoryPageQuery, variables), { pools, tranches: [...tranches], userTranches, locks }, window),
+                    this.readChainAt((_a = positions._meta) === null || _a === void 0 ? void 0 : _a.block.number, (blockTag) => this._userLendingService.getUserPoolBalancesAt(userAddress, pools, undefined, blockTag)),
+                ]);
+                // A pool whose ledger credits shares the wallet does not hold at
+                // the same block (shares moved away outside a withdrawal) has no
+                // history we can vouch for: it is left out. Unpinned, nothing is.
+                const decimals = this._kasuConfig.stableAssetDecimals;
+                const withheld = new Set();
+                if (chain.blockTag !== undefined) {
+                    positions.user.lendingPoolUserDetails.forEach((pool, index) => {
+                        var _a;
+                        const ledger = pool.lendingPoolTrancheUserDetails.reduce((sum, position) => {
+                            var _a;
+                            return sum +
+                                parseFloat(this._userLendingService.convertSharesToAssets((_a = position.shares) !== null && _a !== void 0 ? _a : '0', position.tranche.balance, position.tranche.shares));
+                        }, 0);
+                        const held = parseFloat(formatUnits((_a = chain.values[index]) !== null && _a !== void 0 ? _a : BigNumber.from(0), decimals));
+                        if (ledger > held && !ledgerAgrees(ledger, held)) {
+                            withheld.add(pool.lendingPool.id.toLowerCase());
+                        }
+                    });
+                }
                 return buildYieldHistory(Object.assign({ positions }, rows), window, {
                     epochZeroStart: epochZeroStart.toNumber(),
                     epochDuration: epochDuration.toNumber(),
-                });
+                }).filter((entry) => !withheld.has(entry.poolId.toLowerCase()));
             }
             catch (error) {
                 if (isEmptyHistoryError(error, this._isLiteDeployment))
@@ -497,6 +616,164 @@ export class Portfolio {
             }
         });
     }
+    /**
+     * Read the chain at the subgraph's block, so the chain and the ledger
+     * describe the same state: after every clearing the subgraph runs a few
+     * blocks behind, and a `latest` read would then disagree with an
+     * honest ledger (interest moved every balance, deposits were accepted)
+     * and book that difference as a ledger fault.
+     *
+     * Only when the node says it cannot serve that block (pruned, or behind
+     * the subgraph: `isBlockUnavailableError`) does it fall back to `latest`,
+     * and it says so (`blockTag: undefined`): unpinned figures are never
+     * compared with the ledger, and `getPortfolioLendingData` marks the pools
+     * `chainPinned: false`. Any other failure — a rate limit, a timeout, a
+     * network error — is thrown, never turned into an unpinned read.
+     */
+    readChainAt(block, read) {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (block !== undefined) {
+                try {
+                    return { values: yield read(block), blockTag: block };
+                }
+                catch (error) {
+                    if (!isBlockUnavailableError(error))
+                        throw error;
+                }
+            }
+            return { values: yield read(undefined), blockTag: undefined };
+        });
+    }
+    /**
+     * One pool's balances: the ledger's (the subgraph counts a lender's
+     * shares as accepted deposits − accepted withdrawals ± top-ups) checked
+     * against the chain's `LendingPool.userBalance` at the SAME block.
+     *
+     * The ledger does not follow shares that move between wallets any other
+     * way (an administrative move of a position is the case seen on chain):
+     * the receiving wallet goes negative as it withdraws, the sending one
+     * keeps shares it no longer holds. Where the two disagree at that block —
+     * or any ledger balance is negative — the tranche balances are read from
+     * the chain at that block (`userActiveAssets`, one call per tranche), the
+     * tranche's ledger `yieldEarned` moves by the same difference, and the
+     * pool carries `ledgerMismatch`. Unpinned (the node could not serve the
+     * block), only a negative ledger balance is corrected. A pool that agrees
+     * — every ordinary lender — costs nothing extra.
+     *
+     * Lifetime figures stay ledger figures: they cannot tell moved principal
+     * from interest.
+     */
+    reconcilePool(userAddress, overview, details, chainBalance, blockTag, provider) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a, _b, _c;
+            const decimals = this._kasuConfig.stableAssetDecimals;
+            const chainTotal = parseFloat(formatUnits(chainBalance, decimals));
+            const lifetime = chainTotal -
+                parseFloat(details.totalAcceptedDeposits) +
+                parseFloat(details.totalAcceptedWithdrawnAmount);
+            const tranches = new Map();
+            for (const position of details.lendingPoolTrancheUserDetails) {
+                const balance = this._userLendingService.convertSharesToAssets(position.shares, position.tranche.balance, position.tranche.shares);
+                tranches.set(position.tranche.id, {
+                    balance,
+                    yieldEarned: parseFloat(balance) -
+                        parseFloat(position.totalAcceptedDeposits) +
+                        parseFloat(position.totalAcceptedWithdrawnAmount),
+                });
+            }
+            const ledgerTotal = [...tranches.values()].reduce((sum, { balance }) => sum + parseFloat(balance), 0);
+            const negative = [...tranches.values()].some(({ balance }) => parseFloat(balance) < 0);
+            const disagrees = blockTag !== undefined && !ledgerAgrees(ledgerTotal, chainTotal);
+            if (!negative && !disagrees) {
+                return { chainBalance, lifetime, tranches };
+            }
+            const trancheIds = [
+                ...new Set([
+                    ...overview.tranches.map(({ id }) => id),
+                    ...tranches.keys(),
+                ]),
+            ];
+            const onChain = yield this._userLendingService.getUserTrancheActiveAssets(userAddress, trancheIds, provider, blockTag);
+            let phantom = false;
+            const reconciled = new Map();
+            for (const [index, trancheId] of trancheIds.entries()) {
+                const fromLedger = tranches.get(trancheId);
+                const ledgerBalance = parseFloat((_a = fromLedger === null || fromLedger === void 0 ? void 0 : fromLedger.balance) !== null && _a !== void 0 ? _a : '0');
+                const balance = formatUnits((_b = onChain[index]) !== null && _b !== void 0 ? _b : BigNumber.from(0), decimals);
+                if (blockTag !== undefined &&
+                    ledgerBalance > parseFloat(balance) &&
+                    !ledgerAgrees(ledgerBalance, parseFloat(balance))) {
+                    phantom = true;
+                }
+                reconciled.set(trancheId, {
+                    balance,
+                    yieldEarned: ((_c = fromLedger === null || fromLedger === void 0 ? void 0 : fromLedger.yieldEarned) !== null && _c !== void 0 ? _c : 0) +
+                        parseFloat(balance) -
+                        ledgerBalance,
+                });
+            }
+            return {
+                chainBalance,
+                lifetime,
+                tranches: reconciled,
+                mismatch: {
+                    kind: phantom ? 'ledger-exceeds-chain' : 'chain-exceeds-ledger',
+                    ledgerBalance: String(ledgerTotal),
+                    chainBalance: String(chainTotal),
+                },
+            };
+        });
+    }
+    /**
+     * The last-epoch figures of positions whose newest interest is OLDER than
+     * the recent window. Pools clear independently, and some clear only when
+     * the originator repays, so a pool's last cycle can be weeks back: it is
+     * priced at THAT epoch, from a history read of just those positions over
+     * just those epochs, through the same `positionEpochYield` — so it equals
+     * the history's newest bar.
+     *
+     * A lender who has since left the tranche (no ledger shares now) gets no
+     * figure: an old pool's last cycle is not theirs to show. Costs nothing
+     * when no position qualifies.
+     */
+    staleLastEpochYields(positions, recentEpoch) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            const stale = positions.flatMap(({ poolId, position }) => {
+                var _a;
+                const interest = (_a = position.tranche.lendingPoolTrancheEpochInterest) === null || _a === void 0 ? void 0 : _a[0];
+                if ((interest === null || interest === void 0 ? void 0 : interest.epochId) === undefined)
+                    return [];
+                if (!(parseFloat(position.shares) > 0))
+                    return [];
+                const epoch = Number(interest.epochId);
+                return epoch < recentEpoch
+                    ? [{ poolId, position, epoch, interest }]
+                    : [];
+            });
+            const yields = new Map();
+            if (stale.length === 0)
+                return yields;
+            const lockId = (poolId, lock) => { var _a; return (_a = lock.id) !== null && _a !== void 0 ? _a : `${poolId.toLowerCase()}-${lock.lockId}`; };
+            const { rows } = yield fetchYieldHistorySeries((variables) => this._graph.request(yieldHistoryPageQuery, variables), {
+                pools: [...new Set(stale.map(({ poolId }) => poolId))].map((id) => id.toLowerCase()),
+                tranches: [
+                    ...new Set(stale.map(({ position }) => position.tranche.id)),
+                ],
+                userTranches: stale.map(({ position }) => position.id),
+                locks: stale.flatMap(({ poolId, position }) => position.userLendingPoolTrancheFixedTermDepositLocks.map((lock) => lockId(poolId, lock))),
+            }, {
+                fromEpoch: Math.min(...stale.map(({ epoch }) => epoch)),
+                toEpoch: Math.max(...stale.map(({ epoch }) => epoch)),
+            });
+            const starts = clearingStarts(rows.clearings);
+            for (const { poolId, position, epoch, interest } of stale) {
+                const series = positionSeriesFrom(rows, Object.assign(Object.assign({}, position), { userLendingPoolTrancheFixedTermDepositLocks: position.userLendingPoolTrancheFixedTermDepositLocks.map((lock) => (Object.assign(Object.assign({}, lock), { id: lockId(poolId, lock) }))) }));
+                yields.set(position.id, positionEpochYield(series, epoch, parseFloat(interest.epochInterestAmount), (_a = starts.get(poolId.toLowerCase())) === null || _a === void 0 ? void 0 : _a.get(epoch)).yield);
+            }
+            return yields;
+        });
+    }
     /**
      * A money figure as a plain decimal string. Below a millionth of a token
      * (the stable asset's own precision) is float noise, never money, so it