@kasufinance/kasu-sdk 2.11.0 → 2.12.0

package/dist/bundle.cjs.js

@@ -16943,6 +16943,101 @@ class KSULocking {
     }
 }
 
+/**
+ * Settled interest per cycle (epoch): what a lender was credited at each close,
+ * per pool and tranche, and the one formula that turns a tranche's credited
+ * interest into one lender's share of it.
+ *
+ * **The figures are NET, and only net.** `LendingPool._applyTrancheInterest`
+ * takes the performance fee off first and emits `InterestApplied` with the
+ * lender side only (`interest × (1 − performanceFee)`); a fixed-term top-up
+ * (`_applyFixedRateInterests`) is net of the fee the same way. So the figure
+ * this module computes from those records IS what the lender was credited —
+ * never take the fee off it again. No gross is offered: the subgraph keeps
+ * only TODAY's fee, so a historical gross would be a guess.
+ *
+ * Units: amounts are display units of the DEPLOYMENT'S OWN stable token (USDC
+ * on Base and XDC USDC, AUDD on XDC AUDD) — never converted to USD here;
+ * shares are display units of tranche shares, as the subgraph's BigDecimals.
+ */
+/**
+ * The ONE per-epoch formula. `Portfolio.getPortfolioLendingData` runs it for
+ * the last settled epoch and `getYieldHistory` for every epoch of a window, so
+ * the two figures cannot drift apart.
+ *
+ * ```
+ * base     = epochInterest × userShares / trancheShares
+ * lockBase = base × lock.sharesBeforeEpoch / userShares          (active locks)
+ * topUp    = (lock.sharesAtEpoch − lock.sharesBeforeEpoch) × trancheBalanceNow / trancheSharesNow
+ * variable = base − Σ lockBase
+ * total    = variable + Σ (lockBase + topUp)
+ * ```
+ *
+ * A zero denominator contributes 0 (a tranche or a lender with no shares
+ * earned nothing at that close), never `NaN`.
+ */
+function epochTrancheYield(input) {
+    const base = input.trancheShares === 0
+        ? 0
+        : (input.epochInterest * input.userShares) / input.trancheShares;
+    let variable = base;
+    const locks = input.locks.map((lock) => {
+        if (!lock.active)
+            return 0;
+        const topUp = input.trancheSharesNow === 0
+            ? 0
+            : ((lock.sharesAtEpoch - lock.sharesBeforeEpoch) *
+                input.trancheBalanceNow) /
+                input.trancheSharesNow;
+        const lockBase = input.userShares === 0
+            ? 0
+            : (base * lock.sharesBeforeEpoch) / input.userShares;
+        variable -= lockBase;
+        return lockBase + topUp;
+    });
+    const total = locks.reduce((sum, lockYield) => sum + lockYield, variable);
+    return { total, variable, locks };
+}
+/**
+ * Pool/tranche entries → one point per epoch, ascending by `epochId`. With no
+ * filter it sums every strategy (the Lend tab's bars); with `poolId` it is one
+ * strategy (a strategy page's bars).
+ *
+ * An epoch appears only if a kept entry has it — there is no zero padding, so
+ * an empty input (a new lender) is an empty output.
+ *
+ * For a fixed-term lock holder the bars can sum to slightly MORE than the
+ * lender's lifetime interest (up to about 0.2 %): each top-up is valued at the
+ * tranche's CURRENT share price, which has grown since. Show "earned to date"
+ * from the lifetime figure, never from this sum.
+ */
+function aggregateYieldHistory(entries, filter = {}) {
+    var _a, _b;
+    const poolId = (_a = filter.poolId) === null || _a === void 0 ? void 0 : _a.toLowerCase();
+    const trancheId = (_b = filter.trancheId) === null || _b === void 0 ? void 0 : _b.toLowerCase();
+    const byEpoch = new Map();
+    for (const entry of entries) {
+        if (poolId !== undefined && entry.poolId.toLowerCase() !== poolId) {
+            continue;
+        }
+        if (trancheId !== undefined &&
+            entry.trancheId.toLowerCase() !== trancheId) {
+            continue;
+        }
+        const point = byEpoch.get(entry.epochId);
+        if (point) {
+            point.netYield += entry.netYield;
+            continue;
+        }
+        byEpoch.set(entry.epochId, {
+            epochId: entry.epochId,
+            epochEnd: entry.epochEnd,
+            netYield: entry.netYield,
+        });
+    }
+    return [...byEpoch.values()].sort((a, b) => a.epochId - b.epochId);
+}
+
 /**
  * Check if the SDK is configured for a Lite deployment.
  * Lite deployments don't have KSU token, locking, or loyalty features.
@@ -17726,9 +17821,11 @@ const lendingPortfolioQuery = gql `
         $epochId: BigInt!
         $lastEpochId: BigInt!
         $unusedPools: [String!]!
+        $first: Int!
     ) {
         user(id: $userAddress) {
             lendingPoolUserDetails(
+                first: $first
                 where: { lendingPool_not_in: $unusedPools }
             ) {
                 id
@@ -17736,11 +17833,11 @@ const lendingPortfolioQuery = gql `
                     id
                     name
                     balance
-                    tranches {
+                    tranches(first: $first) {
                         shares
                     }
                 }
-                lendingPoolTrancheUserDetails {
+                lendingPoolTrancheUserDetails(first: $first) {
                     shares
                     lendingPoolTrancheUserEpochSharesUpdates(
                         orderDirection: desc
@@ -17750,7 +17847,7 @@ const lendingPortfolioQuery = gql `
                     ) {
                         shares
                     }
-                    userLendingPoolTrancheFixedTermDepositLocks {
+                    userLendingPoolTrancheFixedTermDepositLocks(first: $first) {
                         isLocked
                         unlockAmount
                         initialAmount
@@ -17774,6 +17871,14 @@ const lendingPortfolioQuery = gql `
                         ) {
                             shares
                         }
+                        lockSharesAtLastEpoch: userLendingPoolTrancheFixedTermDepositLockShareUpdate(
+                            orderBy: shareUpdatesIndex
+                            orderDirection: desc
+                            first: 1
+                            where: { epochId_lt: $epochId }
+                        ) {
+                            shares
+                        }
                     }
                     tranche {
                         id
@@ -17800,6 +17905,7 @@ const lendingPortfolioQuery = gql `
             }
         }
         userRequests(
+            first: $first
             where: {
                 user: $userAddress
                 userRequestEvents_: {
@@ -17815,6 +17921,7 @@ const lendingPortfolioQuery = gql `
             }
             fixedTermConfigId
             userRequestEvents(
+                first: $first
                 where: { type_in: [DepositInitiated, DepositIncreased] }
             ) {
                 id
@@ -17824,6 +17931,400 @@ const lendingPortfolioQuery = gql `
     }
 `;
 
+/** The subgraph returns at most this many rows per collection per request. */
+const YIELD_HISTORY_PAGE_SIZE = 1000;
+/**
+ * A runaway guard, not a working limit: a collection this many pages long
+ * (`MAX × PAGE_SIZE` rows for one lender) is a broken response, not a history.
+ */
+const YIELD_HISTORY_MAX_PAGES = 100;
+/**
+ * Throws `RangeError` on a malformed `fromEpoch` / `count`. `getYieldHistory`
+ * calls it BEFORE any network read.
+ */
+function validateYieldHistoryOptions(options) {
+    const { fromEpoch, count } = options;
+    if (fromEpoch !== undefined &&
+        (!Number.isSafeInteger(fromEpoch) || fromEpoch < 0)) {
+        throw new RangeError(`getYieldHistory: fromEpoch must be a non-negative integer, got ${String(fromEpoch)}`);
+    }
+    if (count !== undefined && (!Number.isSafeInteger(count) || count < 1)) {
+        throw new RangeError(`getYieldHistory: count must be a positive integer, got ${String(count)}`);
+    }
+}
+function resolveYieldHistoryWindow(options, currentEpoch) {
+    validateYieldHistoryOptions(options);
+    const { fromEpoch, count } = options;
+    const newest = currentEpoch - 1;
+    if (newest < 0)
+        return null;
+    let from;
+    let to = newest;
+    if (fromEpoch !== undefined) {
+        from = fromEpoch;
+        if (count !== undefined)
+            to = Math.min(newest, fromEpoch + count - 1);
+    }
+    else {
+        from = count !== undefined ? Math.max(0, newest - count + 1) : 0;
+    }
+    return from > to ? null : { fromEpoch: from, toEpoch: to };
+}
+// ---------------------------------------------------------------------------
+// Subgraph reads
+// ---------------------------------------------------------------------------
+/**
+ * Round trip 1: the lender's tranche positions and fixed-term locks. Same
+ * pool exclusion and the same nested-list size (`$first`) as
+ * `lendingPortfolioQuery`, so both read the same lock set.
+ */
+const yieldHistoryPositionsQuery = gql `
+    query YieldHistoryPositions(
+        $userAddress: ID!
+        $unusedPools: [String!]!
+        $first: Int!
+    ) {
+        user(id: $userAddress) {
+            lendingPoolUserDetails(
+                first: $first
+                where: { lendingPool_not_in: $unusedPools }
+            ) {
+                lendingPool {
+                    id
+                }
+                lendingPoolTrancheUserDetails(first: $first) {
+                    id
+                    tranche {
+                        id
+                        balance
+                        shares
+                    }
+                    userLendingPoolTrancheFixedTermDepositLocks(first: $first) {
+                        id
+                        epochLockStart
+                        epochLockEnd
+                        initialTrancheShares
+                    }
+                }
+            }
+        }
+    }
+`;
+/**
+ * Round trip 2 onwards: the four per-epoch series, one page of each per
+ * request, cursor-paginated by `id`. A series that is exhausted is skipped with
+ * `@include`, so a history costs as many requests as its LONGEST series has
+ * pages — normally one — never one per epoch.
+ *
+ * Share snapshots are read up to the window's end with no lower bound: the
+ * value AS OF the first epoch may come from an update long before it.
+ */
+const yieldHistoryPageQuery = gql `
+    query YieldHistoryPage(
+        $tranches: [String!]!
+        $userTranches: [String!]!
+        $locks: [String!]!
+        $fromEpoch: BigInt!
+        $toEpoch: BigInt!
+        $interestCursor: ID!
+        $trancheSharesCursor: ID!
+        $userSharesCursor: ID!
+        $lockSharesCursor: ID!
+        $withInterest: Boolean!
+        $withTrancheShares: Boolean!
+        $withUserShares: Boolean!
+        $withLockShares: Boolean!
+        $first: Int!
+    ) {
+        interest: lendingPoolTrancheEpochInterests(
+            first: $first
+            orderBy: id
+            orderDirection: asc
+            where: {
+                id_gt: $interestCursor
+                lendingPoolTranche_in: $tranches
+                epochId_gte: $fromEpoch
+                epochId_lte: $toEpoch
+            }
+        ) @include(if: $withInterest) {
+            id
+            epochId
+            epochInterestAmount
+            lendingPoolTranche {
+                id
+            }
+        }
+        trancheShares: lendingPoolTrancheShareUpdates(
+            first: $first
+            orderBy: id
+            orderDirection: asc
+            where: {
+                id_gt: $trancheSharesCursor
+                lendingPoolTranche_in: $tranches
+                epochId_lte: $toEpoch
+            }
+        ) @include(if: $withTrancheShares) {
+            id
+            epochId
+            shareUpdatesIndex
+            shares
+            lendingPoolTranche {
+                id
+            }
+        }
+        userShares: lendingPoolTrancheUserEpochSharesUpdates(
+            first: $first
+            orderBy: id
+            orderDirection: asc
+            where: {
+                id_gt: $userSharesCursor
+                lendingPoolTrancheUserDetails_in: $userTranches
+                epochId_lte: $toEpoch
+            }
+        ) @include(if: $withUserShares) {
+            id
+            epochId
+            shareUpdatesIndex
+            shares
+            lendingPoolTrancheUserDetails {
+                id
+            }
+        }
+        lockShares: userLendingPoolTrancheFtdLockShareUpdates(
+            first: $first
+            orderBy: id
+            orderDirection: asc
+            where: {
+                id_gt: $lockSharesCursor
+                userLendingPoolTrancheFixedTermDepositLock_in: $locks
+                epochId_lte: $toEpoch
+            }
+        ) @include(if: $withLockShares) {
+            id
+            epochId
+            shareUpdatesIndex
+            shares
+            userLendingPoolTrancheFixedTermDepositLock {
+                id
+            }
+        }
+    }
+`;
+/**
+ * Fetch the four series for the window, paginating each by `id` until a short
+ * page. Returns the rows and how many requests it took.
+ */
+function fetchYieldHistorySeries(request, ids, window) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a;
+        const rows = {
+            interest: [],
+            trancheShares: [],
+            userShares: [],
+            lockShares: [],
+        };
+        const series = [
+            { key: 'interest', flag: 'withInterest', cursor: 'interestCursor' },
+            {
+                key: 'trancheShares',
+                flag: 'withTrancheShares',
+                cursor: 'trancheSharesCursor',
+            },
+            {
+                key: 'userShares',
+                flag: 'withUserShares',
+                cursor: 'userSharesCursor',
+            },
+            {
+                key: 'lockShares',
+                flag: 'withLockShares',
+                cursor: 'lockSharesCursor',
+            },
+        ];
+        const cursors = {
+            interest: '',
+            trancheShares: '',
+            userShares: '',
+            lockShares: '',
+        };
+        const open = {
+            interest: ids.tranches.length > 0,
+            trancheShares: ids.tranches.length > 0,
+            userShares: ids.userTranches.length > 0,
+            lockShares: ids.locks.length > 0,
+        };
+        let requests = 0;
+        while (series.some(({ key }) => open[key])) {
+            if (requests >= YIELD_HISTORY_MAX_PAGES) {
+                throw new Error(`getYieldHistory: more than ${String(YIELD_HISTORY_MAX_PAGES)} pages for one lender`);
+            }
+            const variables = {
+                tranches: ids.tranches,
+                userTranches: ids.userTranches,
+                locks: ids.locks,
+                fromEpoch: String(window.fromEpoch),
+                toEpoch: String(window.toEpoch),
+                first: YIELD_HISTORY_PAGE_SIZE,
+            };
+            for (const { key, flag, cursor } of series) {
+                variables[flag] = open[key];
+                variables[cursor] = cursors[key];
+            }
+            const page = yield request(variables);
+            requests += 1;
+            for (const { key } of series) {
+                if (!open[key])
+                    continue;
+                const got = (_a = page[key]) !== null && _a !== void 0 ? _a : [];
+                rows[key].push(...got);
+                const last = got.at(-1);
+                if (got.length < YIELD_HISTORY_PAGE_SIZE || last === undefined) {
+                    open[key] = false;
+                    continue;
+                }
+                if (last.id <= cursors[key]) {
+                    throw new Error(`getYieldHistory: the ${key} cursor did not advance`);
+                }
+                cursors[key] = last.id;
+            }
+        }
+        return { rows, requests };
+    });
+}
+/**
+ * The snapshot in force at `epoch`: among updates with `epochId ≤ epoch`, the
+ * one with the highest `shareUpdatesIndex` — exactly what
+ * `lendingPortfolioQuery` selects with `orderBy: shareUpdatesIndex, desc,
+ * first: 1, where: { epochId_lt: epoch + 1 }`. `undefined` when none.
+ */
+function sharesAsOf(updates, epoch) {
+    let found;
+    for (const update of updates) {
+        if (Number(update.epochId) > epoch)
+            continue;
+        if (!found || update.shareUpdatesIndex > found.shareUpdatesIndex) {
+            found = update;
+        }
+    }
+    return found;
+}
+function groupBy(rows, key) {
+    const map = new Map();
+    for (const row of rows) {
+        const k = key(row);
+        const list = map.get(k);
+        if (list)
+            list.push(row);
+        else
+            map.set(k, [row]);
+    }
+    return map;
+}
+/**
+ * Pure: the fetched series → one entry per pool, tranche and settled epoch in
+ * which the lender held shares (or a lock earned a top-up). Each entry runs the
+ * same `epochTrancheYield` as the portfolio's last-epoch figure, with the same
+ * share selection, so the newest entry equals that figure.
+ *
+ * Sorted by `epochId`, then `poolId`, then `trancheId`.
+ */
+function buildYieldHistory(read, window, clock) {
+    var _a, _b, _c, _d, _e, _f;
+    const user = read.positions.user;
+    if (!user)
+        return [];
+    const interestByTranche = groupBy(read.interest, (row) => row.lendingPoolTranche.id);
+    const trancheSharesByTranche = groupBy(read.trancheShares, (row) => row.lendingPoolTranche.id);
+    const userSharesByPosition = groupBy(read.userShares, (row) => row.lendingPoolTrancheUserDetails.id);
+    const lockSharesByLock = groupBy(read.lockShares, (row) => row.userLendingPoolTrancheFixedTermDepositLock.id);
+    const entries = [];
+    for (const pool of user.lendingPoolUserDetails) {
+        for (const position of pool.lendingPoolTrancheUserDetails) {
+            const trancheId = position.tranche.id;
+            const trancheUpdates = (_a = trancheSharesByTranche.get(trancheId)) !== null && _a !== void 0 ? _a : [];
+            const userUpdates = (_b = userSharesByPosition.get(position.id)) !== null && _b !== void 0 ? _b : [];
+            const trancheBalanceNow = parseFloat(position.tranche.balance);
+            const trancheSharesNow = parseFloat(position.tranche.shares);
+            for (const record of (_c = interestByTranche.get(trancheId)) !== null && _c !== void 0 ? _c : []) {
+                const epoch = Number(record.epochId);
+                if (epoch < window.fromEpoch || epoch > window.toEpoch) {
+                    continue;
+                }
+                const userSnapshot = sharesAsOf(userUpdates, epoch);
+                const userShares = parseFloat((_d = userSnapshot === null || userSnapshot === void 0 ? void 0 : userSnapshot.shares) !== null && _d !== void 0 ? _d : '0');
+                const locks = position.userLendingPoolTrancheFixedTermDepositLocks.map((lock) => {
+                    var _a, _b, _c, _d, _e;
+                    const lockUpdates = (_a = lockSharesByLock.get(lock.id)) !== null && _a !== void 0 ? _a : [];
+                    return {
+                        active: parseFloat(lock.epochLockStart) < epoch &&
+                            parseFloat(lock.epochLockEnd) >= epoch &&
+                            userSnapshot !== undefined,
+                        // No snapshot yet = the lock's opening
+                        // shares: a lock made after clearing E
+                        // starts at E but its first update is
+                        // tagged E + 1, and reading that gap as 0
+                        // would book its principal as a top-up.
+                        sharesAtEpoch: parseFloat((_c = (_b = sharesAsOf(lockUpdates, epoch)) === null || _b === void 0 ? void 0 : _b.shares) !== null && _c !== void 0 ? _c : lock.initialTrancheShares),
+                        sharesBeforeEpoch: parseFloat((_e = (_d = sharesAsOf(lockUpdates, epoch - 1)) === null || _d === void 0 ? void 0 : _d.shares) !== null && _e !== void 0 ? _e : lock.initialTrancheShares),
+                    };
+                });
+                const { total } = epochTrancheYield({
+                    epochInterest: parseFloat(record.epochInterestAmount),
+                    userShares,
+                    trancheShares: parseFloat((_f = (_e = sharesAsOf(trancheUpdates, epoch)) === null || _e === void 0 ? void 0 : _e.shares) !== null && _f !== void 0 ? _f : '0'),
+                    trancheBalanceNow,
+                    trancheSharesNow,
+                    locks,
+                });
+                // Nothing held and nothing topped up: not part of this
+                // lender's history (a new lender's history is empty).
+                if (userShares <= 0 && total === 0)
+                    continue;
+                entries.push({
+                    epochId: epoch,
+                    epochEnd: clock.epochZeroStart +
+                        (epoch + 1) * clock.epochDuration,
+                    poolId: pool.lendingPool.id,
+                    trancheId,
+                    netYield: total,
+                });
+            }
+        }
+    }
+    return entries.sort((a, b) => a.epochId - b.epochId ||
+        a.poolId.localeCompare(b.poolId) ||
+        a.trancheId.localeCompare(b.trancheId));
+}
+/**
+ * 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) {
         this._kasuConfig = _kasuConfig;
@@ -17924,7 +18425,7 @@ class Portfolio {
                     performanceFee *
                     ecosystemFeeRate;
         }
-        return ((totalWeeklyEcosystemFees * userRKsuAmount) / totalRKsuAmount);
+        return (totalWeeklyEcosystemFees * userRKsuAmount) / totalRKsuAmount;
     }
     /**
      * Calculate the user's weekly KASU bonus rewards (KASU) based on current deposits,
@@ -17932,7 +18433,7 @@ class Portfolio {
      */
     calculateWeeklyKsuBonusRewards(params) {
         return __awaiter(this, void 0, void 0, function* () {
-            const { userAddress, userRksuAmount, userDepositAmounts, ksuEpochPrice } = params;
+            const { userAddress, userRksuAmount, userDepositAmounts, ksuEpochPrice, } = params;
             const totalUserDeposits = userDepositAmounts[0].add(userDepositAmounts[1]);
             if (totalUserDeposits.isZero())
                 return 0;
@@ -18041,7 +18542,7 @@ class Portfolio {
     }
     getPortfolioLendingData(userAddress, poolOverviews, currentEpoch, provider) {
         return __awaiter(this, void 0, void 0, function* () {
-            var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l;
+            var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m;
             const SECONDS_PER_EPOCH = 604800; // seconds in a week
             const portfolioLendingPoolsPromise = [];
             const previousEpoch = ethers.BigNumber.from(currentEpoch).sub(ethers.BigNumber.from(1));
@@ -18051,6 +18552,7 @@ class Portfolio {
                     epochId: parseFloat(currentEpoch),
                     lastEpochId: previousEpoch.toNumber(),
                     unusedPools: this._kasuConfig.UNUSED_LENDING_POOL_IDS,
+                    first: YIELD_HISTORY_PAGE_SIZE,
                 }),
                 this._userLendingService.getPortfolioUserTrancheBalances(userAddress),
                 this._userLendingService.getUserPoolBalance(userAddress, poolOverviews.map(({ id }) => id), provider),
@@ -18088,7 +18590,6 @@ class Portfolio {
                 }
             }
             let totalInvestments = ethers.BigNumber.from(0);
-            let totalYieldEarnedLastEpoch = 0;
             for (const poolOverview of poolOverviews) {
                 const userPoolBalance = userPoolBalances.find(({ poolId }) => poolId === poolOverview.id);
                 if (!userPoolBalance) {
@@ -18096,6 +18597,7 @@ class Portfolio {
                 }
                 totalInvestments = userPoolBalance.balance.add(totalInvestments);
                 const tranches = [];
+                let poolYieldEarnedLastEpoch = 0;
                 const lendingPoolUserDetails = lastEpochData.user.lendingPoolUserDetails.find(({ lendingPool }) => lendingPool.id === poolOverview.id);
                 if (!lendingPoolUserDetails)
                     continue;
@@ -18114,18 +18616,42 @@ class Portfolio {
                             }, depositDetails, fixedLoans: [] }));
                         continue;
                     }
-                    const lastEpochTotalYield = parseFloat((_e = (_d = (_c = lastEpochUserTrancheDetails.tranche
-                        .lendingPoolTrancheEpochInterest) === null || _c === void 0 ? void 0 : _c[0]) === null || _d === void 0 ? void 0 : _d.epochInterestAmount) !== null && _e !== void 0 ? _e : '0');
-                    const lastEpochUserShares = parseFloat((_h = (_g = (_f = lastEpochUserTrancheDetails
-                        .lendingPoolTrancheUserEpochSharesUpdates) === null || _f === void 0 ? void 0 : _f[0]) === null || _g === void 0 ? void 0 : _g.shares) !== null && _h !== void 0 ? _h : '0');
-                    const lastEpochTotalShares = parseFloat((_l = (_k = (_j = lastEpochUserTrancheDetails.tranche
-                        .lendingPoolTrancheShareUpdates) === null || _j === void 0 ? void 0 : _j[0]) === null || _k === void 0 ? void 0 : _k.shares) !== null && _l !== void 0 ? _l : '0');
-                    const currentTotalAmount = parseFloat(lastEpochUserTrancheDetails.tranche.balance);
-                    const currentTotalShares = parseFloat(lastEpochUserTrancheDetails.tranche.shares);
-                    const lastEpochTotalBaseYield = lastEpochTotalShares === 0
-                        ? 0
-                        : (lastEpochTotalYield * lastEpochUserShares) /
-                            lastEpochTotalShares;
+                    const lastEpoch = previousEpoch.toNumber();
+                    const userHasLastEpochShares = Boolean((_c = lastEpochUserTrancheDetails
+                        .lendingPoolTrancheUserEpochSharesUpdates) === null || _c === void 0 ? void 0 : _c.length);
+                    const fixedTermDeposits = lastEpochUserTrancheDetails.userLendingPoolTrancheFixedTermDepositLocks;
+                    // The one per-epoch formula `getYieldHistory` runs too, with
+                    // the same share selection — so the last bar of a history
+                    // equals these figures.
+                    const lastEpochYield = epochTrancheYield({
+                        epochInterest: parseFloat((_f = (_e = (_d = lastEpochUserTrancheDetails.tranche
+                            .lendingPoolTrancheEpochInterest) === null || _d === void 0 ? void 0 : _d[0]) === null || _e === void 0 ? void 0 : _e.epochInterestAmount) !== null && _f !== void 0 ? _f : '0'),
+                        userShares: parseFloat((_j = (_h = (_g = lastEpochUserTrancheDetails
+                            .lendingPoolTrancheUserEpochSharesUpdates) === null || _g === void 0 ? void 0 : _g[0]) === null || _h === void 0 ? void 0 : _h.shares) !== null && _j !== void 0 ? _j : '0'),
+                        trancheShares: parseFloat((_m = (_l = (_k = lastEpochUserTrancheDetails.tranche
+                            .lendingPoolTrancheShareUpdates) === null || _k === void 0 ? void 0 : _k[0]) === null || _l === void 0 ? void 0 : _l.shares) !== null && _m !== void 0 ? _m : '0'),
+                        trancheBalanceNow: parseFloat(lastEpochUserTrancheDetails.tranche.balance),
+                        trancheSharesNow: parseFloat(lastEpochUserTrancheDetails.tranche.shares),
+                        locks: fixedTermDeposits.map((fixedTermDeposit) => {
+                            var _a, _b, _c, _d, _e, _f;
+                            return ({
+                                active: parseFloat(fixedTermDeposit.epochLockStart) <
+                                    lastEpoch &&
+                                    parseFloat(fixedTermDeposit.epochLockEnd) >=
+                                        lastEpoch &&
+                                    userHasLastEpochShares,
+                                // No snapshot = the lock's opening shares, exactly
+                                // as `getYieldHistory` reads it: a lock made after
+                                // clearing E starts at E with its first update
+                                // tagged E + 1. Never the CURRENT shares, which
+                                // would carry a top-up from a clearing that ran
+                                // after the last settled epoch.
+                                sharesAtEpoch: parseFloat((_c = (_b = (_a = fixedTermDeposit.lockSharesAtLastEpoch) === null || _a === void 0 ? void 0 : _a[0]) === null || _b === void 0 ? void 0 : _b.shares) !== null && _c !== void 0 ? _c : fixedTermDeposit.initialTrancheShares),
+                                sharesBeforeEpoch: parseFloat((_f = (_e = (_d = fixedTermDeposit
+                                    .userLendingPoolTrancheFixedTermDepositLockShareUpdate) === null || _d === void 0 ? void 0 : _d[0]) === null || _e === void 0 ? void 0 : _e.shares) !== null && _f !== void 0 ? _f : fixedTermDeposit.initialTrancheShares),
+                            });
+                        }),
+                    });
                     const userTrancheBalance = {
                         balance: '0',
                         yieldEarned: 0,
@@ -18140,47 +18666,20 @@ class Portfolio {
                         }
                     }
                     let totalLifetimeFtdYield = 0;
-                    let lastEpochVariableBaseYield = lastEpochTotalBaseYield;
-                    const fixedLoans = lastEpochUserTrancheDetails.userLendingPoolTrancheFixedTermDepositLocks.map((fixedTermDeposit) => {
-                        var _a, _b, _c, _d, _e;
+                    const fixedLoans = fixedTermDeposits.map((fixedTermDeposit, lockIndex) => {
+                        var _a, _b;
                         const fixedLoanDepositDetails = (_a = userRequest === null || userRequest === void 0 ? void 0 : userRequest[fixedTermDeposit
-                            .lendingPoolTrancheFixedTermConfig
-                            .configId]) !== null && _a !== void 0 ? _a : [];
-                        let lastEpochYieldEarned = 0;
-                        let lifetimeYieldEarned = 0;
-                        if (parseFloat(fixedTermDeposit.epochLockStart) <
-                            previousEpoch.toNumber() &&
-                            parseFloat(fixedTermDeposit.epochLockEnd) >=
-                                previousEpoch.toNumber() &&
-                            Boolean((_b = lastEpochUserTrancheDetails
-                                .lendingPoolTrancheUserEpochSharesUpdates) === null || _b === void 0 ? void 0 : _b.length)) {
-                            const currentEpochFtdShares = parseFloat(fixedTermDeposit.trancheShares);
-                            const lastEpochFtdShares = parseFloat((_e = (_d = (_c = fixedTermDeposit
-                                .userLendingPoolTrancheFixedTermDepositLockShareUpdate) === null || _c === void 0 ? void 0 : _c[0]) === null || _d === void 0 ? void 0 : _d.shares) !== null && _e !== void 0 ? _e : '0');
-                            const additionalFtdYield = ((currentEpochFtdShares -
-                                lastEpochFtdShares) *
-                                currentTotalAmount) /
-                                currentTotalShares;
-                            const lastEpochFtdBaseYield = (lastEpochTotalBaseYield *
-                                lastEpochFtdShares) /
-                                lastEpochUserShares;
-                            lastEpochVariableBaseYield -=
-                                lastEpochFtdBaseYield;
-                            lastEpochYieldEarned =
-                                lastEpochFtdBaseYield + additionalFtdYield;
-                        }
-                        lifetimeYieldEarned =
-                            this.calculateFixedTermDepositEarnings(fixedTermDeposit, lastEpochUserTrancheDetails.tranche.balance, lastEpochUserTrancheDetails.tranche.shares);
+                            .lendingPoolTrancheFixedTermConfig.configId]) !== null && _a !== void 0 ? _a : [];
+                        const lastEpochYieldEarned = (_b = lastEpochYield.locks[lockIndex]) !== null && _b !== void 0 ? _b : 0;
+                        const lifetimeYieldEarned = this.calculateFixedTermDepositEarnings(fixedTermDeposit, lastEpochUserTrancheDetails.tranche.balance, lastEpochUserTrancheDetails.tranche.shares);
                         totalLifetimeFtdYield += lifetimeYieldEarned;
-                        totalYieldEarnedLastEpoch += lastEpochYieldEarned;
                         const lockDuration = parseFloat(fixedTermDeposit
                             .lendingPoolTrancheFixedTermConfig
                             .epochLockDuration) * SECONDS_PER_EPOCH;
                         return {
                             lockId: fixedTermDeposit.lockId,
                             configId: fixedTermDeposit
-                                .lendingPoolTrancheFixedTermConfig
-                                .configId,
+                                .lendingPoolTrancheFixedTermConfig.configId,
                             epochLockDuration: fixedTermDeposit
                                 .lendingPoolTrancheFixedTermConfig
                                 .epochLockDuration,
@@ -18190,9 +18689,7 @@ class Portfolio {
                                 .epochInterestRate,
                             epochLockStart: fixedTermDeposit.epochLockStart,
                             amount: this._userLendingService
-                                .convertSharesToAssets(fixedTermDeposit.trancheShares, lastEpochUserTrancheDetails.tranche
-                                .balance, lastEpochUserTrancheDetails.tranche
-                                .shares)
+                                .convertSharesToAssets(fixedTermDeposit.trancheShares, lastEpochUserTrancheDetails.tranche.balance, lastEpochUserTrancheDetails.tranche.shares)
                                 .toString(),
                             endTime: parseInt(fixedTermDeposit.createdOn) +
                                 lockDuration,
@@ -18200,20 +18697,22 @@ class Portfolio {
                             isWithdrawalRequested: fixedTermDeposit.isWithdrawalRequested,
                             startTime: parseInt(fixedTermDeposit.createdOn),
                             yieldEarnings: {
-                                lastEpoch: lastEpochYieldEarned.toString(),
+                                lastEpoch: this.precisionToString(lastEpochYieldEarned),
                                 lifetime: this.precisionToString(lifetimeYieldEarned),
                             },
                             depositDetails: fixedLoanDepositDetails,
                         };
                     });
-                    totalYieldEarnedLastEpoch += lastEpochTotalBaseYield;
+                    // This POOL's last-epoch total: the tranche totals summed, the
+                    // locks counted once (inside `total`).
+                    poolYieldEarnedLastEpoch += lastEpochYield.total;
                     tranches.push(Object.assign(Object.assign({}, tranche), { investedAmount: userTrancheBalance, yieldEarnings: {
-                            lastEpoch: lastEpochVariableBaseYield.toString(),
+                            lastEpoch: this.precisionToString(lastEpochYield.variable),
                             lifetime: this.precisionToString(totalLifetimeFtdYield), // passing in total FTD yield to be subtracted by total trache lifetime later down
                         }, fixedLoans,
                         depositDetails }));
                 }
-                portfolioLendingPoolsPromise.push(Object.assign(Object.assign({}, poolOverview), { totalYieldEarningsLastEpoch: totalYieldEarnedLastEpoch.toString(), totalInvestedAmount: userPoolBalance.balance.toString(), totalYieldEarningsLifetime: userPoolBalance.yieldEarned.toString(), tranches }));
+                portfolioLendingPoolsPromise.push(Object.assign(Object.assign({}, poolOverview), { totalYieldEarningsLastEpoch: this.precisionToString(poolYieldEarnedLastEpoch), totalInvestedAmount: userPoolBalance.balance.toString(), totalYieldEarningsLifetime: userPoolBalance.yieldEarned.toString(), tranches }));
             }
             const portfolioLendingPools = portfolioLendingPoolsPromise.map((pool) => (Object.assign(Object.assign({}, pool), { tranches: pool.tranches.map((tranche) => {
                     const trancheBalance = tranche.investedAmount;
@@ -18231,7 +18730,87 @@ class Portfolio {
                 !utils$2.parseUnits(pool.totalYieldEarningsLifetime).isZero());
         });
     }
+    /**
+     * The lender's settled yield per cycle (epoch), per pool and tranche —
+     * what the chain credited at each close, NET of the performance fee
+     * (`domain/yield-history.ts`), in the deployment's own stable token. Each
+     * entry runs the same `epochTrancheYield` as `getPortfolioLendingData`'s
+     * last-epoch figures: a tranche's `yieldEarnings.lastEpoch` plus its
+     * locks' equals its entry for the epoch of the tranche's most recently
+     * APPLIED interest (older than the last cycle for a pool that has not
+     * cleared since; no entry, and a figure of 0, when the lender held
+     * nothing at that epoch).
+     *
+     * Sum entries with `aggregateYieldHistory` (all strategies, or one with
+     * `{ poolId }`). Only epochs in which the lender held shares appear — a
+     * new lender gets `[]`. Pools in `UNUSED_LENDING_POOL_IDS` are left out,
+     * as in `lendingPortfolioQuery`; Directus enablement is NOT applied.
+     *
+     * Cost: three parallel `SystemVariables` reads and the positions query in
+     * one round, then one subgraph request per page of the longest series
+     * (1000 rows a page) — normally two subgraph round trips in all, never one
+     * per epoch.
+     *
+     * On a LITE deployment, a subgraph that lacks the entities (a validation
+     * error naming them) yields `[]`; on a full deployment that error throws,
+     * like every other failure (`isEmptyHistoryError`).
+     *
+     * @throws RangeError on a malformed `fromEpoch` / `count`, before any
+     * network read.
+     */
+    getYieldHistory(userAddress_1) {
+        return __awaiter(this, arguments, void 0, function* (userAddress, options = {}) {
+            validateYieldHistoryOptions(options);
+            try {
+                const [currentEpoch, epochZeroStart, epochDuration, positions] = yield Promise.all([
+                    this._systemVariablesAbi.currentEpochNumber(),
+                    this._systemVariablesAbi.epochStartTimestamp(0),
+                    this._systemVariablesAbi.epochDuration(),
+                    this._graph.request(yieldHistoryPositionsQuery, {
+                        userAddress: userAddress.toLowerCase(),
+                        unusedPools: this._kasuConfig.UNUSED_LENDING_POOL_IDS,
+                        first: YIELD_HISTORY_PAGE_SIZE,
+                    }),
+                ]);
+                const window = resolveYieldHistoryWindow(options, currentEpoch.toNumber());
+                if (!window || !positions.user)
+                    return [];
+                const userTranches = [];
+                const tranches = new Set();
+                const locks = [];
+                for (const pool of positions.user.lendingPoolUserDetails) {
+                    for (const position of pool.lendingPoolTrancheUserDetails) {
+                        userTranches.push(position.id);
+                        tranches.add(position.tranche.id);
+                        for (const lock of position.userLendingPoolTrancheFixedTermDepositLocks) {
+                            locks.push(lock.id);
+                        }
+                    }
+                }
+                if (userTranches.length === 0)
+                    return [];
+                const { rows } = yield fetchYieldHistorySeries((variables) => this._graph.request(yieldHistoryPageQuery, variables), { tranches: [...tranches], userTranches, locks }, window);
+                return buildYieldHistory(Object.assign({ positions }, rows), window, {
+                    epochZeroStart: epochZeroStart.toNumber(),
+                    epochDuration: epochDuration.toNumber(),
+                });
+            }
+            catch (error) {
+                if (isEmptyHistoryError(error, this._isLiteDeployment))
+                    return [];
+                throw error;
+            }
+        });
+    }
+    /**
+     * A money figure as a plain decimal string. Below a millionth of a token
+     * (the stable asset's own precision) is float noise, never money, so it
+     * is `'0'` — not `'1e-7'`, which `parseUnits` rejects, nor `'-3e-12'`. A
+     * small negative remainder (above −0.0001) is `'0'` as well.
+     */
     precisionToString(val) {
+        if (Math.abs(val) < 1e-6)
+            return '0';
         if (val < 0 && val > -1e-4) {
             return '0';
         }
@@ -28254,6 +28833,40 @@ class PortfolioFacade {
             return { pools, summary };
         });
     }
+    /**
+     * The lender's settled yield per cycle, per pool and tranche: what each
+     * close credited them, NET of the performance fee (the chain credits it
+     * net), in display units of the deployment's own stable token (AUDD on
+     * XDC AUDD). `epochEnd` is unix seconds. Net only — no gross is offered.
+     *
+     * Validates `options` before any read (`RangeError` on a malformed one).
+     *
+     * ```ts
+     * const entries = await kasu.portfolio.getYieldHistory('0xUser...', { count: 52 });
+     * const allStrategies = aggregateYieldHistory(entries);
+     * const oneStrategy = aggregateYieldHistory(entries, { poolId });
+     * ```
+     *
+     * `getPositions`' `totalYieldEarningsLastEpoch` for a pool equals that
+     * pool's bar for the epoch of its most recently APPLIED interest — which
+     * is older than the last cycle for a pool that has not cleared since (the
+     * bar carries that older `epochId`). A lender who held nothing at that
+     * epoch has no bar there and a figure of 0; their newest bar is from
+     * when they last held shares.
+     *
+     * For a fixed-term lock holder the bars can sum to slightly more than the
+     * lifetime interest (up to about 0.2 %), because each top-up is valued at
+     * today's share price — show "earned to date" from the lifetime figure,
+     * never from the sum of the bars.
+     *
+     * `[]` for a lender with no history, and on a LITE deployment whose
+     * subgraph lacks the entities; on a full deployment that error throws.
+     */
+    getYieldHistory(userAddress, options) {
+        return __awaiter(this, void 0, void 0, function* () {
+            return yield this._portfolio.getYieldHistory(userAddress, options);
+        });
+    }
     /**
      * Fetch a user's full transaction history (deposits, withdrawals, cancellations).
      */
@@ -29219,6 +29832,7 @@ exports.StrategiesFacade = StrategiesFacade;
 exports.UPPER_MEZZANINE = UPPER_MEZZANINE;
 exports.WithdrawFlow = WithdrawFlow;
 exports.accruedInterest = accruedInterest;
+exports.aggregateYieldHistory = aggregateYieldHistory;
 exports.apyToEpochRate = apyToEpochRate;
 exports.asContractType = asContractType;
 exports.auMinimumRemaining = auMinimumRemaining;
@@ -29249,6 +29863,7 @@ exports.encodeRequestWithdrawalCall = encodeRequestWithdrawalCall;
 exports.encodeStableTransfer = encodeStableTransfer;
 exports.encodeWithdrawAtExpiryCall = encodeWithdrawAtExpiryCall;
 exports.epochRateToApy = epochRateToApy;
+exports.epochTrancheYield = epochTrancheYield;
 exports.explorerAddressUrl = explorerAddressUrl;
 exports.explorerTxUrl = explorerTxUrl;
 exports.extractRevertData = extractRevertData;