@kasufinance/kasu-sdk 2.11.0 → 2.12.0

package/dist/services/Portfolio/yield-history.js

@@ -0,0 +1,405 @@
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+import { gql } from 'graphql-request';
+import { epochTrancheYield, } from '../../domain/yield-history';
+/** The subgraph returns at most this many rows per collection per request. */
+export 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.
+ */
+export const YIELD_HISTORY_MAX_PAGES = 100;
+/**
+ * Throws `RangeError` on a malformed `fromEpoch` / `count`. `getYieldHistory`
+ * calls it BEFORE any network read.
+ */
+export 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)}`);
+    }
+}
+export 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.
+ */
+export 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.
+ */
+export 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.
+ */
+export 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.
+ */
+export 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`.
+ */
+export 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.
+ */
+export 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".
+ */
+export function isEmptyHistoryError(error, liteDeployment) {
+    return liteDeployment && isMissingEntityError(error);
+}
+//# sourceMappingURL=yield-history.js.map

package/dist/services/Portfolio/yield-history.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"yield-history.js","sourceRoot":"","sources":["../../../src/services/Portfolio/yield-history.ts"],"names":[],"mappings":";;;;;;;;;AAAA,OAAO,EAAE,GAAG,EAAE,MAAM,iBAAiB,CAAC;AAEtC,OAAO,EAEH,iBAAiB,GAEpB,MAAM,4BAA4B,CAAC;AAyBpC,8EAA8E;AAC9E,MAAM,CAAC,MAAM,uBAAuB,GAAG,IAAI,CAAC;AAE5C;;;GAGG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,GAAG,CAAC;AAE3C;;;GAGG;AACH,MAAM,UAAU,2BAA2B,CACvC,OAA4B;IAE5B,MAAM,EAAE,SAAS,EAAE,KAAK,EAAE,GAAG,OAAO,CAAC;IACrC,IACI,SAAS,KAAK,SAAS;QACvB,CAAC,CAAC,MAAM,CAAC,aAAa,CAAC,SAAS,CAAC,IAAI,SAAS,GAAG,CAAC,CAAC,EACrD,CAAC;QACC,MAAM,IAAI,UAAU,CAChB,kEAAkE,MAAM,CAAC,SAAS,CAAC,EAAE,CACxF,CAAC;IACN,CAAC;IACD,IAAI,KAAK,KAAK,SAAS,IAAI,CAAC,CAAC,MAAM,CAAC,aAAa,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,CAAC,CAAC,EAAE,CAAC;QACrE,MAAM,IAAI,UAAU,CAChB,0DAA0D,MAAM,CAAC,KAAK,CAAC,EAAE,CAC5E,CAAC;IACN,CAAC;AACL,CAAC;AAED,MAAM,UAAU,yBAAyB,CACrC,OAA4B,EAC5B,YAAoB;IAEpB,2BAA2B,CAAC,OAAO,CAAC,CAAC;IACrC,MAAM,EAAE,SAAS,EAAE,KAAK,EAAE,GAAG,OAAO,CAAC;IAErC,MAAM,MAAM,GAAG,YAAY,GAAG,CAAC,CAAC;IAChC,IAAI,MAAM,GAAG,CAAC;QAAE,OAAO,IAAI,CAAC;IAE5B,IAAI,IAAY,CAAC;IACjB,IAAI,EAAE,GAAG,MAAM,CAAC;IAChB,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;QAC1B,IAAI,GAAG,SAAS,CAAC;QACjB,IAAI,KAAK,KAAK,SAAS;YAAE,EAAE,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,EAAE,SAAS,GAAG,KAAK,GAAG,CAAC,CAAC,CAAC;IAC1E,CAAC;SAAM,CAAC;QACJ,IAAI,GAAG,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,MAAM,GAAG,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACrE,CAAC;IAED,OAAO,IAAI,GAAG,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC;AAC/D,CAAC;AAED,8EAA8E;AAC9E,iBAAiB;AACjB,8EAA8E;AAE9E;;;;GAIG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAG,GAAG,CAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA+B5C,CAAC;AAEF;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,GAAG,CAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA0FvC,CAAC;AAqEF;;;GAGG;AACH,MAAM,UAAgB,uBAAuB,CACzC,OAAoB,EACpB,GAAoE,EACpE,MAA0B;;;QAK1B,MAAM,IAAI,GAAwC;YAC9C,QAAQ,EAAE,EAAE;YACZ,aAAa,EAAE,EAAE;YACjB,UAAU,EAAE,EAAE;YACd,UAAU,EAAE,EAAE;SACjB,CAAC;QACF,MAAM,MAAM,GAAG;YACX,EAAE,GAAG,EAAE,UAAU,EAAE,IAAI,EAAE,cAAc,EAAE,MAAM,EAAE,gBAAgB,EAAE;YACnE;gBACI,GAAG,EAAE,eAAe;gBACpB,IAAI,EAAE,mBAAmB;gBACzB,MAAM,EAAE,qBAAqB;aAChC;YACD;gBACI,GAAG,EAAE,YAAY;gBACjB,IAAI,EAAE,gBAAgB;gBACtB,MAAM,EAAE,kBAAkB;aAC7B;YACD;gBACI,GAAG,EAAE,YAAY;gBACjB,IAAI,EAAE,gBAAgB;gBACtB,MAAM,EAAE,kBAAkB;aAC7B;SACK,CAAC;QAEX,MAAM,OAAO,GAAmD;YAC5D,QAAQ,EAAE,EAAE;YACZ,aAAa,EAAE,EAAE;YACjB,UAAU,EAAE,EAAE;YACd,UAAU,EAAE,EAAE;SACjB,CAAC;QACF,MAAM,IAAI,GAAoD;YAC1D,QAAQ,EAAE,GAAG,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC;YACjC,aAAa,EAAE,GAAG,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC;YACtC,UAAU,EAAE,GAAG,CAAC,YAAY,CAAC,MAAM,GAAG,CAAC;YACvC,UAAU,EAAE,GAAG,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC;SACnC,CAAC;QAEF,IAAI,QAAQ,GAAG,CAAC,CAAC;QACjB,OAAO,MAAM,CAAC,IAAI,CAAC,CAAC,EAAE,GAAG,EAAE,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC;YACzC,IAAI,QAAQ,IAAI,uBAAuB,EAAE,CAAC;gBACtC,MAAM,IAAI,KAAK,CACX,8BAA8B,MAAM,CAAC,uBAAuB,CAAC,uBAAuB,CACvF,CAAC;YACN,CAAC;YAED,MAAM,SAAS,GAA4B;gBACvC,QAAQ,EAAE,GAAG,CAAC,QAAQ;gBACtB,YAAY,EAAE,GAAG,CAAC,YAAY;gBAC9B,KAAK,EAAE,GAAG,CAAC,KAAK;gBAChB,SAAS,EAAE,MAAM,CAAC,MAAM,CAAC,SAAS,CAAC;gBACnC,OAAO,EAAE,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC;gBAC/B,KAAK,EAAE,uBAAuB;aACjC,CAAC;YACF,KAAK,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,MAAM,EAAE,CAAC;gBACzC,SAAS,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC;gBAC5B,SAAS,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;YACrC,CAAC;YAED,MAAM,IAAI,GAAG,MAAM,OAAO,CAAC,SAAS,CAAC,CAAC;YACtC,QAAQ,IAAI,CAAC,CAAC;YAEd,KAAK,MAAM,EAAE,GAAG,EAAE,IAAI,MAAM,EAAE,CAAC;gBAC3B,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC;oBAAE,SAAS;gBACzB,MAAM,GAAG,GAAG,MAAA,IAAI,CAAC,GAAG,CAAC,mCAAI,EAAE,CAAC;gBAC3B,IAAI,CAAC,GAAG,CAAsB,CAAC,IAAI,CAAC,GAAG,GAAG,CAAC,CAAC;gBAC7C,MAAM,IAAI,GAAG,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;gBACxB,IAAI,GAAG,CAAC,MAAM,GAAG,uBAAuB,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;oBAC7D,IAAI,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;oBAClB,SAAS;gBACb,CAAC;gBACD,IAAI,IAAI,CAAC,EAAE,IAAI,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;oBAC1B,MAAM,IAAI,KAAK,CACX,wBAAwB,GAAG,yBAAyB,CACvD,CAAC;gBACN,CAAC;gBACD,OAAO,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,EAAE,CAAC;YAC3B,CAAC;QACL,CAAC;QAED,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;IAC9B,CAAC;CAAA;AAED;;;;;GAKG;AACH,MAAM,UAAU,UAAU,CACtB,OAAkC,EAClC,KAAa;IAEb,IAAI,KAAiC,CAAC;IACtC,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;QAC3B,IAAI,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,GAAG,KAAK;YAAE,SAAS;QAC7C,IAAI,CAAC,KAAK,IAAI,MAAM,CAAC,iBAAiB,GAAG,KAAK,CAAC,iBAAiB,EAAE,CAAC;YAC/D,KAAK,GAAG,MAAM,CAAC;QACnB,CAAC;IACL,CAAC;IACD,OAAO,KAAK,CAAC;AACjB,CAAC;AAED,SAAS,OAAO,CACZ,IAAkB,EAClB,GAAuB;IAEvB,MAAM,GAAG,GAAG,IAAI,GAAG,EAAe,CAAC;IACnC,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACrB,MAAM,CAAC,GAAG,GAAG,CAAC,GAAG,CAAC,CAAC;QACnB,MAAM,IAAI,GAAG,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;QACxB,IAAI,IAAI;YAAE,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;;YACpB,GAAG,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAC3B,CAAC;IACD,OAAO,GAAG,CAAC;AACf,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,iBAAiB,CAC7B,IAAsB,EACtB,MAA0B,EAC1B,KAAiB;;IAEjB,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC;IACjC,IAAI,CAAC,IAAI;QAAE,OAAO,EAAE,CAAC;IAErB,MAAM,iBAAiB,GAAG,OAAO,CAC7B,IAAI,CAAC,QAAQ,EACb,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,kBAAkB,CAAC,EAAE,CACrC,CAAC;IACF,MAAM,sBAAsB,GAAG,OAAO,CAClC,IAAI,CAAC,aAAa,EAClB,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,kBAAkB,CAAC,EAAE,CACrC,CAAC;IACF,MAAM,oBAAoB,GAAG,OAAO,CAChC,IAAI,CAAC,UAAU,EACf,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,6BAA6B,CAAC,EAAE,CAChD,CAAC;IACF,MAAM,gBAAgB,GAAG,OAAO,CAC5B,IAAI,CAAC,UAAU,EACf,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,0CAA0C,CAAC,EAAE,CAC7D,CAAC;IAEF,MAAM,OAAO,GAAwB,EAAE,CAAC;IAExC,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,sBAAsB,EAAE,CAAC;QAC7C,KAAK,MAAM,QAAQ,IAAI,IAAI,CAAC,6BAA6B,EAAE,CAAC;YACxD,MAAM,SAAS,GAAG,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC;YACtC,MAAM,cAAc,GAAG,MAAA,sBAAsB,CAAC,GAAG,CAAC,SAAS,CAAC,mCAAI,EAAE,CAAC;YACnE,MAAM,WAAW,GAAG,MAAA,oBAAoB,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC,mCAAI,EAAE,CAAC;YAChE,MAAM,iBAAiB,GAAG,UAAU,CAAC,QAAQ,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;YAC/D,MAAM,gBAAgB,GAAG,UAAU,CAAC,QAAQ,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;YAE7D,KAAK,MAAM,MAAM,IAAI,MAAA,iBAAiB,CAAC,GAAG,CAAC,SAAS,CAAC,mCAAI,EAAE,EAAE,CAAC;gBAC1D,MAAM,KAAK,GAAG,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;gBACrC,IAAI,KAAK,GAAG,MAAM,CAAC,SAAS,IAAI,KAAK,GAAG,MAAM,CAAC,OAAO,EAAE,CAAC;oBACrD,SAAS;gBACb,CAAC;gBAED,MAAM,YAAY,GAAG,UAAU,CAAC,WAAW,EAAE,KAAK,CAAC,CAAC;gBACpD,MAAM,UAAU,GAAG,UAAU,CAAC,MAAA,YAAY,aAAZ,YAAY,uBAAZ,YAAY,CAAE,MAAM,mCAAI,GAAG,CAAC,CAAC;gBAE3D,MAAM,KAAK,GACP,QAAQ,CAAC,2CAA2C,CAAC,GAAG,CACpD,CAAC,IAAI,EAAE,EAAE;;oBACL,MAAM,WAAW,GACb,MAAA,gBAAgB,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,mCAAI,EAAE,CAAC;oBACxC,OAAO;wBACH,MAAM,EACF,UAAU,CAAC,IAAI,CAAC,cAAc,CAAC,GAAG,KAAK;4BACvC,UAAU,CAAC,IAAI,CAAC,YAAY,CAAC,IAAI,KAAK;4BACtC,YAAY,KAAK,SAAS;wBAC9B,uCAAuC;wBACvC,uCAAuC;wBACvC,sCAAsC;wBACtC,0CAA0C;wBAC1C,wCAAwC;wBACxC,aAAa,EAAE,UAAU,CACrB,MAAA,MAAA,UAAU,CAAC,WAAW,EAAE,KAAK,CAAC,0CAAE,MAAM,mCAClC,IAAI,CAAC,oBAAoB,CAChC;wBACD,iBAAiB,EAAE,UAAU,CACzB,MAAA,MAAA,UAAU,CAAC,WAAW,EAAE,KAAK,GAAG,CAAC,CAAC,0CAC5B,MAAM,mCAAI,IAAI,CAAC,oBAAoB,CAC5C;qBACJ,CAAC;gBACN,CAAC,CACJ,CAAC;gBAEN,MAAM,EAAE,KAAK,EAAE,GAAG,iBAAiB,CAAC;oBAChC,aAAa,EAAE,UAAU,CAAC,MAAM,CAAC,mBAAmB,CAAC;oBACrD,UAAU;oBACV,aAAa,EAAE,UAAU,CACrB,MAAA,MAAA,UAAU,CAAC,cAAc,EAAE,KAAK,CAAC,0CAAE,MAAM,mCAAI,GAAG,CACnD;oBACD,iBAAiB;oBACjB,gBAAgB;oBAChB,KAAK;iBACR,CAAC,CAAC;gBAEH,uDAAuD;gBACvD,sDAAsD;gBACtD,IAAI,UAAU,IAAI,CAAC,IAAI,KAAK,KAAK,CAAC;oBAAE,SAAS;gBAE7C,OAAO,CAAC,IAAI,CAAC;oBACT,OAAO,EAAE,KAAK;oBACd,QAAQ,EACJ,KAAK,CAAC,cAAc;wBACpB,CAAC,KAAK,GAAG,CAAC,CAAC,GAAG,KAAK,CAAC,aAAa;oBACrC,MAAM,EAAE,IAAI,CAAC,WAAW,CAAC,EAAE;oBAC3B,SAAS;oBACT,QAAQ,EAAE,KAAK;iBAClB,CAAC,CAAC;YACP,CAAC;QACL,CAAC;IACL,CAAC;IAED,OAAO,OAAO,CAAC,IAAI,CACf,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CACL,CAAC,CAAC,OAAO,GAAG,CAAC,CAAC,OAAO;QACrB,CAAC,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC,CAAC,MAAM,CAAC;QAChC,CAAC,CAAC,SAAS,CAAC,aAAa,CAAC,CAAC,CAAC,SAAS,CAAC,CAC7C,CAAC;AACN,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,oBAAoB,CAAC,KAAc;IAC/C,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC;IAC9D,MAAM,QAAQ,GAAI,KAA6C,CAAC,QAAQ,CAAC;IACzE,MAAM,MAAM,GAAG,QAAQ,aAAR,QAAQ,uBAAR,QAAQ,CAAE,MAAM,CAAC;IAChC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IAChE,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC,CAAU,EAAE,EAAE;QAC/B,MAAM,OAAO,GAAI,CAAkC,aAAlC,CAAC,uBAAD,CAAC,CAAmC,OAAO,CAAC;QAC7D,OAAO,CACH,OAAO,OAAO,KAAK,QAAQ;YAC3B,qFAAqF,CAAC,IAAI,CACtF,OAAO,CACV,CACJ,CAAC;IACN,CAAC,CAAC,CAAC;AACP,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,mBAAmB,CAC/B,KAAc,EACd,cAAuB;IAEvB,OAAO,cAAc,IAAI,oBAAoB,CAAC,KAAK,CAAC,CAAC;AACzD,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@kasufinance/kasu-sdk",
-    "version": "2.11.0",
+    "version": "2.12.0",
     "description": "TypeScript SDK for the Kasu Finance protocol — pool data, portfolio analytics, and KYC-gated deposits and withdrawals on Base and XDC",
     "keywords": [
         "kasu",

package/src/domain/index.ts

@@ -134,11 +134,7 @@ export {
     lastEventTimestamp,
     submissionEvents,
 } from './requests';
-export type {
-    RequestKind,
-    RequestState,
-    RequestStatusCode,
-} from './requests';
+export type { RequestKind, RequestState, RequestStatusCode } from './requests';
 
 export { decodeRevert, extractRevertData } from './revert-errors';
 export type { DecodedRevert, RevertFamily } from './revert-errors';
@@ -183,11 +179,7 @@ export {
     trancheHasCapacity,
     trancheRiskRank,
 } from './tranches';
-export type {
-    ApyBounds,
-    PoolStatus,
-    TrancheCapacitySignal,
-} from './tranches';
+export type { ApyBounds, PoolStatus, TrancheCapacitySignal } from './tranches';
 
 export {
     classifyWalletFailure,
@@ -196,6 +188,16 @@ export {
 } from './wallet-errors';
 export type { WalletFailure } from './wallet-errors';
 
+export { aggregateYieldHistory, epochTrancheYield } from './yield-history';
+export type {
+    EpochLockShares,
+    EpochTrancheYield,
+    EpochTrancheYieldInput,
+    YieldHistoryEntry,
+    YieldHistoryFilter,
+    YieldHistoryPoint,
+} from './yield-history';
+
 export {
     accruedInterest,
     dailyInterest,

package/src/domain/yield-history.ts

@@ -0,0 +1,194 @@
+/**
+ * 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.
+ */
+
+/** One fixed-term lock inside a tranche position, at one epoch. */
+export interface EpochLockShares {
+    /**
+     * The lock earns in this epoch: it started BEFORE the epoch, ends at or
+     * after it, and the lender has a share snapshot for the tranche at it.
+     */
+    active: boolean;
+    /** The lock's tranche shares as of the epoch (latest update at or before it). */
+    sharesAtEpoch: number;
+    /** The lock's tranche shares as of the epoch BEFORE it. */
+    sharesBeforeEpoch: number;
+}
+
+/** Everything one lender's share of one tranche's credited interest needs. */
+export interface EpochTrancheYieldInput {
+    /** The tranche's interest credited at this epoch's close (net of the fee). */
+    epochInterest: number;
+    /** The lender's tranche shares as of the epoch (fixed-term locks included). */
+    userShares: number;
+    /** The tranche's total shares as of the epoch. */
+    trancheShares: number;
+    /**
+     * The tranche's CURRENT balance and shares: the price a fixed-term top-up
+     * (extra shares) is valued at. The subgraph keeps no per-epoch tranche
+     * balance, so an older top-up is valued at today's price — a second-order
+     * difference, because the top-up is only the fixed rate's excess over the
+     * variable one.
+     */
+    trancheBalanceNow: number;
+    trancheSharesNow: number;
+    locks: readonly EpochLockShares[];
+}
+
+export interface EpochTrancheYield {
+    /** `variable + Σ locks` — the lender's whole yield in the tranche. */
+    total: number;
+    /** The variable residual: the share-weighted base yield minus the locks' part of it. */
+    variable: number;
+    /** Each lock's yield, in the order of `input.locks`: its base part plus its top-up. */
+    locks: number[];
+}
+
+/**
+ * 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`.
+ */
+export function epochTrancheYield(
+    input: EpochTrancheYieldInput,
+): EpochTrancheYield {
+    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 };
+}
+
+/** One lender's settled yield in one tranche at one epoch. */
+export interface YieldHistoryEntry {
+    /** The epoch (cycle) number, in the chain's numbering. */
+    epochId: number;
+    /**
+     * When the epoch ended — the next epoch's start — in unix SECONDS (not
+     * milliseconds).
+     */
+    epochEnd: number;
+    /** Lowercased lending pool address. */
+    poolId: string;
+    /** Lowercased tranche address. */
+    trancheId: string;
+    /**
+     * What the close credited the lender in this tranche, AFTER the
+     * performance fee, in display units of the deployment's own stable token
+     * (AUDD on XDC AUDD — convert before formatting it as USD).
+     */
+    netYield: number;
+}
+
+/** One epoch's yield summed over the entries an aggregation kept. */
+export interface YieldHistoryPoint {
+    /** The epoch (cycle) number. */
+    epochId: number;
+    /** The epoch's end, in unix SECONDS. */
+    epochEnd: number;
+    /** Net yield summed, in the deployment's own stable token. */
+    netYield: number;
+}
+
+export interface YieldHistoryFilter {
+    /** Keep only this pool (case-insensitive). */
+    poolId?: string;
+    /** Keep only this tranche (case-insensitive). */
+    trancheId?: string;
+}
+
+/**
+ * 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.
+ */
+export function aggregateYieldHistory(
+    entries: readonly YieldHistoryEntry[],
+    filter: YieldHistoryFilter = {},
+): YieldHistoryPoint[] {
+    const poolId = filter.poolId?.toLowerCase();
+    const trancheId = filter.trancheId?.toLowerCase();
+    const byEpoch = new Map<number, YieldHistoryPoint>();
+
+    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);
+}