@kasufinance/kasu-sdk 2.11.0 → 2.12.0

package/dist/domain/index.d.ts

@@ -41,7 +41,7 @@ export type { ContractListItem, ContractSection, ContractType, ExemptLoanContrac
 export { maxNetRateCeiling, pickHighestYieldTranche, poolMaxApy, selectVisiblePools, } from './pools';
 export type { BestTranche } from './pools';
 export { cancelDeadline, countSubmissions, deriveRequestState, firstSubmissionTimestamp, isCycleClosed, 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';
 export { CLEARING_WINDOW_SECONDS, computeSettlementWindow, deriveCycleDates, nextCycleBoundary, } from './settlement';
@@ -52,8 +52,10 @@ export { pickShortDescription } from './strategy-summary';
 export type { ShortDescriptionSource } from './strategy-summary';
 export { getTrancheDisplayName, UPPER_MEZZANINE } from './tranche-display-name';
 export { compareTrancheSeniority, derivePoolStatus, MIN_TRANCHE_CAPACITY, netTrancheApyBounds, pickDefaultTrancheId, poolAllTranchesFull, trancheApyBounds, trancheHasCapacity, trancheRiskRank, } from './tranches';
-export type { ApyBounds, PoolStatus, TrancheCapacitySignal, } from './tranches';
+export type { ApyBounds, PoolStatus, TrancheCapacitySignal } from './tranches';
 export { classifyWalletFailure, isUnpredictableGas, isUserRejected, } 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, projectedAnnualEarnings, SECONDS_PER_WEEK, weeklyInterest, weightedAverageApy, } from './yields';
 export type { InterestSlice, PoolAccrual } from './yields';

package/dist/domain/index.js

@@ -40,5 +40,6 @@ export { pickShortDescription } from './strategy-summary';
 export { getTrancheDisplayName, UPPER_MEZZANINE } from './tranche-display-name';
 export { compareTrancheSeniority, derivePoolStatus, MIN_TRANCHE_CAPACITY, netTrancheApyBounds, pickDefaultTrancheId, poolAllTranchesFull, trancheApyBounds, trancheHasCapacity, trancheRiskRank, } from './tranches';
 export { classifyWalletFailure, isUnpredictableGas, isUserRejected, } from './wallet-errors';
+export { aggregateYieldHistory, epochTrancheYield } from './yield-history';
 export { accruedInterest, dailyInterest, projectedAnnualEarnings, SECONDS_PER_WEEK, weeklyInterest, weightedAverageApy, } from './yields';
 //# sourceMappingURL=index.js.map

package/dist/domain/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/domain/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,OAAO,EACH,cAAc,EACd,cAAc,EACd,cAAc,EACd,eAAe,GAClB,MAAM,SAAS,CAAC;AAEjB,OAAO,EACH,SAAS,EACT,2BAA2B,EAC3B,kBAAkB,EAClB,cAAc,EACd,iBAAiB,EACjB,eAAe,EACf,eAAe,GAClB,MAAM,cAAc,CAAC;AAGtB,OAAO,EACH,yBAAyB,EACzB,eAAe,EACf,qBAAqB,EACrB,2BAA2B,EAC3B,yBAAyB,GAC5B,MAAM,eAAe,CAAC;AAavB,OAAO,EACH,WAAW,EACX,YAAY,EACZ,sBAAsB,EACtB,2BAA2B,EAC3B,2BAA2B,EAC3B,iBAAiB,EACjB,qBAAqB,EACrB,oBAAoB,GACvB,MAAM,kBAAkB,CAAC;AAG1B,OAAO,EAAE,kBAAkB,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAGpE,OAAO,EACH,yBAAyB,EACzB,cAAc,EACd,cAAc,EACd,mBAAmB,EACnB,gBAAgB,EAChB,kBAAkB,EAClB,mBAAmB,GACtB,MAAM,cAAc,CAAC;AAGtB,OAAO,EACH,MAAM,EACN,mBAAmB,EACnB,sBAAsB,EACtB,iBAAiB,EACjB,WAAW,EACX,aAAa,GAChB,MAAM,YAAY,CAAC;AAGpB,OAAO,EACH,cAAc,EACd,wBAAwB,EACxB,2BAA2B,EAC3B,iCAAiC,EACjC,6BAA6B,EAC7B,iBAAiB,EACjB,sBAAsB,EACtB,qBAAqB,GACxB,MAAM,iBAAiB,CAAC;AAYzB,OAAO,EACH,iBAAiB,EACjB,uBAAuB,EACvB,UAAU,EACV,kBAAkB,GACrB,MAAM,SAAS,CAAC;AAGjB,OAAO,EACH,cAAc,EACd,gBAAgB,EAChB,kBAAkB,EAClB,wBAAwB,EACxB,aAAa,EACb,kBAAkB,EAClB,gBAAgB,GACnB,MAAM,YAAY,CAAC;AAOpB,OAAO,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAGlE,OAAO,EACH,uBAAuB,EACvB,uBAAuB,EACvB,gBAAgB,EAChB,iBAAiB,GACpB,MAAM,cAAc,CAAC;AAOtB,OAAO,EACH,uBAAuB,EACvB,0BAA0B,EAC1B,2BAA2B,EAC3B,oBAAoB,EACpB,0BAA0B,EAC1B,oBAAoB,EACpB,wBAAwB,EACxB,uBAAuB,GAC1B,MAAM,mBAAmB,CAAC;AAG3B,OAAO,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAG1D,OAAO,EAAE,qBAAqB,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAEhF,OAAO,EACH,uBAAuB,EACvB,gBAAgB,EAChB,oBAAoB,EACpB,mBAAmB,EACnB,oBAAoB,EACpB,mBAAmB,EACnB,gBAAgB,EAChB,kBAAkB,EAClB,eAAe,GAClB,MAAM,YAAY,CAAC;AAOpB,OAAO,EACH,qBAAqB,EACrB,kBAAkB,EAClB,cAAc,GACjB,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EACH,eAAe,EACf,aAAa,EACb,uBAAuB,EACvB,gBAAgB,EAChB,cAAc,EACd,kBAAkB,GACrB,MAAM,UAAU,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/domain/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,OAAO,EACH,cAAc,EACd,cAAc,EACd,cAAc,EACd,eAAe,GAClB,MAAM,SAAS,CAAC;AAEjB,OAAO,EACH,SAAS,EACT,2BAA2B,EAC3B,kBAAkB,EAClB,cAAc,EACd,iBAAiB,EACjB,eAAe,EACf,eAAe,GAClB,MAAM,cAAc,CAAC;AAGtB,OAAO,EACH,yBAAyB,EACzB,eAAe,EACf,qBAAqB,EACrB,2BAA2B,EAC3B,yBAAyB,GAC5B,MAAM,eAAe,CAAC;AAavB,OAAO,EACH,WAAW,EACX,YAAY,EACZ,sBAAsB,EACtB,2BAA2B,EAC3B,2BAA2B,EAC3B,iBAAiB,EACjB,qBAAqB,EACrB,oBAAoB,GACvB,MAAM,kBAAkB,CAAC;AAG1B,OAAO,EAAE,kBAAkB,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAGpE,OAAO,EACH,yBAAyB,EACzB,cAAc,EACd,cAAc,EACd,mBAAmB,EACnB,gBAAgB,EAChB,kBAAkB,EAClB,mBAAmB,GACtB,MAAM,cAAc,CAAC;AAGtB,OAAO,EACH,MAAM,EACN,mBAAmB,EACnB,sBAAsB,EACtB,iBAAiB,EACjB,WAAW,EACX,aAAa,GAChB,MAAM,YAAY,CAAC;AAGpB,OAAO,EACH,cAAc,EACd,wBAAwB,EACxB,2BAA2B,EAC3B,iCAAiC,EACjC,6BAA6B,EAC7B,iBAAiB,EACjB,sBAAsB,EACtB,qBAAqB,GACxB,MAAM,iBAAiB,CAAC;AAYzB,OAAO,EACH,iBAAiB,EACjB,uBAAuB,EACvB,UAAU,EACV,kBAAkB,GACrB,MAAM,SAAS,CAAC;AAGjB,OAAO,EACH,cAAc,EACd,gBAAgB,EAChB,kBAAkB,EAClB,wBAAwB,EACxB,aAAa,EACb,kBAAkB,EAClB,gBAAgB,GACnB,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAGlE,OAAO,EACH,uBAAuB,EACvB,uBAAuB,EACvB,gBAAgB,EAChB,iBAAiB,GACpB,MAAM,cAAc,CAAC;AAOtB,OAAO,EACH,uBAAuB,EACvB,0BAA0B,EAC1B,2BAA2B,EAC3B,oBAAoB,EACpB,0BAA0B,EAC1B,oBAAoB,EACpB,wBAAwB,EACxB,uBAAuB,GAC1B,MAAM,mBAAmB,CAAC;AAG3B,OAAO,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAG1D,OAAO,EAAE,qBAAqB,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAEhF,OAAO,EACH,uBAAuB,EACvB,gBAAgB,EAChB,oBAAoB,EACpB,mBAAmB,EACnB,oBAAoB,EACpB,mBAAmB,EACnB,gBAAgB,EAChB,kBAAkB,EAClB,eAAe,GAClB,MAAM,YAAY,CAAC;AAGpB,OAAO,EACH,qBAAqB,EACrB,kBAAkB,EAClB,cAAc,GACjB,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EAAE,qBAAqB,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAU3E,OAAO,EACH,eAAe,EACf,aAAa,EACb,uBAAuB,EACvB,gBAAgB,EAChB,cAAc,EACd,kBAAkB,GACrB,MAAM,UAAU,CAAC"}

package/dist/domain/yield-history.d.ts

@@ -0,0 +1,122 @@
+/**
+ * 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 declare function epochTrancheYield(input: EpochTrancheYieldInput): EpochTrancheYield;
+/** 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 declare function aggregateYieldHistory(entries: readonly YieldHistoryEntry[], filter?: YieldHistoryFilter): YieldHistoryPoint[];

package/dist/domain/yield-history.js

@@ -0,0 +1,95 @@
+/**
+ * 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`.
+ */
+export 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.
+ */
+export 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);
+}
+//# sourceMappingURL=yield-history.js.map

package/dist/domain/yield-history.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"yield-history.js","sourceRoot":"","sources":["../../src/domain/yield-history.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AA4CH;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,iBAAiB,CAC7B,KAA6B;IAE7B,MAAM,IAAI,GACN,KAAK,CAAC,aAAa,KAAK,CAAC;QACrB,CAAC,CAAC,CAAC;QACH,CAAC,CAAC,CAAC,KAAK,CAAC,aAAa,GAAG,KAAK,CAAC,UAAU,CAAC,GAAG,KAAK,CAAC,aAAa,CAAC;IAEzE,IAAI,QAAQ,GAAG,IAAI,CAAC;IACpB,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE;QACnC,IAAI,CAAC,IAAI,CAAC,MAAM;YAAE,OAAO,CAAC,CAAC;QAE3B,MAAM,KAAK,GACP,KAAK,CAAC,gBAAgB,KAAK,CAAC;YACxB,CAAC,CAAC,CAAC;YACH,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,aAAa,GAAG,IAAI,CAAC,iBAAiB,CAAC;gBAC1C,KAAK,CAAC,iBAAiB,CAAC;gBAC5B,KAAK,CAAC,gBAAgB,CAAC;QAEjC,MAAM,QAAQ,GACV,KAAK,CAAC,UAAU,KAAK,CAAC;YAClB,CAAC,CAAC,CAAC;YACH,CAAC,CAAC,CAAC,IAAI,GAAG,IAAI,CAAC,iBAAiB,CAAC,GAAG,KAAK,CAAC,UAAU,CAAC;QAE7D,QAAQ,IAAI,QAAQ,CAAC;QAErB,OAAO,QAAQ,GAAG,KAAK,CAAC;IAC5B,CAAC,CAAC,CAAC;IAEH,MAAM,KAAK,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,SAAS,EAAE,EAAE,CAAC,GAAG,GAAG,SAAS,EAAE,QAAQ,CAAC,CAAC;IAE1E,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC;AACtC,CAAC;AAwCD;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,qBAAqB,CACjC,OAAqC,EACrC,SAA6B,EAAE;;IAE/B,MAAM,MAAM,GAAG,MAAA,MAAM,CAAC,MAAM,0CAAE,WAAW,EAAE,CAAC;IAC5C,MAAM,SAAS,GAAG,MAAA,MAAM,CAAC,SAAS,0CAAE,WAAW,EAAE,CAAC;IAClD,MAAM,OAAO,GAAG,IAAI,GAAG,EAA6B,CAAC;IAErD,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC1B,IAAI,MAAM,KAAK,SAAS,IAAI,KAAK,CAAC,MAAM,CAAC,WAAW,EAAE,KAAK,MAAM,EAAE,CAAC;YAChE,SAAS;QACb,CAAC;QACD,IACI,SAAS,KAAK,SAAS;YACvB,KAAK,CAAC,SAAS,CAAC,WAAW,EAAE,KAAK,SAAS,EAC7C,CAAC;YACC,SAAS;QACb,CAAC;QAED,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QACzC,IAAI,KAAK,EAAE,CAAC;YACR,KAAK,CAAC,QAAQ,IAAI,KAAK,CAAC,QAAQ,CAAC;YACjC,SAAS;QACb,CAAC;QACD,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,OAAO,EAAE;YACvB,OAAO,EAAE,KAAK,CAAC,OAAO;YACtB,QAAQ,EAAE,KAAK,CAAC,QAAQ;YACxB,QAAQ,EAAE,KAAK,CAAC,QAAQ;SAC3B,CAAC,CAAC;IACP,CAAC;IAED,OAAO,CAAC,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,GAAG,CAAC,CAAC,OAAO,CAAC,CAAC;AACvE,CAAC"}

package/dist/facade/user-portfolio.d.ts

@@ -1,7 +1,9 @@
 import { Provider } from '@ethersproject/providers';
 import { RequestState } from '../domain/requests';
+import { YieldHistoryEntry } from '../domain/yield-history';
 import { DataService } from '../services/DataService/data-service';
 import { Portfolio } from '../services/Portfolio/portfolio';
+import { YieldHistoryOptions } from '../services/Portfolio/yield-history';
 import { UserRequest } from '../services/UserLending/types';
 import { UserLending } from '../services/UserLending/user-lending';
 import { UserPositions } from './types';
@@ -29,6 +31,36 @@ export declare class PortfolioFacade {
      *                      SDK was initialised with a Signer but you need a read-only provider).
      */
     getPositions(userAddress: string, provider?: Provider): Promise<UserPositions>;
+    /**
+     * 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: string, options?: YieldHistoryOptions): Promise<YieldHistoryEntry[]>;
     /**
      * Fetch a user's full transaction history (deposits, withdrawals, cancellations).
      */

package/dist/facade/user-portfolio.js

@@ -41,6 +41,40 @@ export 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).
      */

package/dist/facade/user-portfolio.js.map

@@ -1 +1 @@
-{"version":3,"file":"user-portfolio.js","sourceRoot":"","sources":["../../src/facade/user-portfolio.ts"],"names":[],"mappings":";;;;;;;;;AAEA,OAAO,EAAE,kBAAkB,EAAgB,MAAM,oBAAoB,CAAC;AAQtE;;;;;GAKG;AACH,MAAM,OAAO,eAAe;IACxB,YACY,YAAyB,EACzB,YAAyB,EACzB,UAAqB;QAFrB,iBAAY,GAAZ,YAAY,CAAa;QACzB,iBAAY,GAAZ,YAAY,CAAa;QACzB,eAAU,GAAV,UAAU,CAAW;IAC9B,CAAC;IAEJ;;;;;;;;;;;OAWG;IACG,YAAY,CACd,WAAmB,EACnB,QAAmB;;YAEnB,MAAM,YAAY,GAAG,MAAM,IAAI,CAAC,YAAY,CAAC,eAAe,EAAE,CAAC;YAE/D,MAAM,aAAa,GAAG,MAAM,IAAI,CAAC,YAAY,CAAC,eAAe,CACzD,YAAY,CACf,CAAC;YAEF,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,UAAU,CAAC,uBAAuB,CACvD,WAAW,EACX,aAAa,EACb,YAAY,EACZ,QAAQ,CACX,CAAC;YAEF,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,UAAU,CAAC,mBAAmB,CACrD,WAAW,EACX,KAAK,EACL,YAAY,CACf,CAAC;YAEF,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC;QAC9B,CAAC;KAAA;IAED;;OAEG;IACG,qBAAqB,CACvB,WAA0B;;YAE1B,MAAM,YAAY,GAAG,MAAM,IAAI,CAAC,YAAY,CAAC,eAAe,EAAE,CAAC;YAC/D,OAAO,MAAM,IAAI,CAAC,YAAY,CAAC,eAAe,CAC1C,WAAW,EACX,YAAY,CACf,CAAC;QACN,CAAC;KAAA;IAED;;;;;;;;;;;;;;;OAeG;IACG,gBAAgB,CAClB,WAA0B;;YAE1B,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,qBAAqB,CAAC,WAAW,CAAC,CAAC;YAC/D,OAAO,QAAQ,CAAC,GAAG,CAAC,kBAAkB,CAAC,CAAC;QAC5C,CAAC;KAAA;CACJ"}
+{"version":3,"file":"user-portfolio.js","sourceRoot":"","sources":["../../src/facade/user-portfolio.ts"],"names":[],"mappings":";;;;;;;;;AAEA,OAAO,EAAE,kBAAkB,EAAgB,MAAM,oBAAoB,CAAC;AAUtE;;;;;GAKG;AACH,MAAM,OAAO,eAAe;IACxB,YACY,YAAyB,EACzB,YAAyB,EACzB,UAAqB;QAFrB,iBAAY,GAAZ,YAAY,CAAa;QACzB,iBAAY,GAAZ,YAAY,CAAa;QACzB,eAAU,GAAV,UAAU,CAAW;IAC9B,CAAC;IAEJ;;;;;;;;;;;OAWG;IACG,YAAY,CACd,WAAmB,EACnB,QAAmB;;YAEnB,MAAM,YAAY,GAAG,MAAM,IAAI,CAAC,YAAY,CAAC,eAAe,EAAE,CAAC;YAE/D,MAAM,aAAa,GACf,MAAM,IAAI,CAAC,YAAY,CAAC,eAAe,CAAC,YAAY,CAAC,CAAC;YAE1D,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,UAAU,CAAC,uBAAuB,CACvD,WAAW,EACX,aAAa,EACb,YAAY,EACZ,QAAQ,CACX,CAAC;YAEF,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,UAAU,CAAC,mBAAmB,CACrD,WAAW,EACX,KAAK,EACL,YAAY,CACf,CAAC;YAEF,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC;QAC9B,CAAC;KAAA;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;IACG,eAAe,CACjB,WAAmB,EACnB,OAA6B;;YAE7B,OAAO,MAAM,IAAI,CAAC,UAAU,CAAC,eAAe,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;QACvE,CAAC;KAAA;IAED;;OAEG;IACG,qBAAqB,CACvB,WAA0B;;YAE1B,MAAM,YAAY,GAAG,MAAM,IAAI,CAAC,YAAY,CAAC,eAAe,EAAE,CAAC;YAC/D,OAAO,MAAM,IAAI,CAAC,YAAY,CAAC,eAAe,CAC1C,WAAW,EACX,YAAY,CACf,CAAC;QACN,CAAC;KAAA;IAED;;;;;;;;;;;;;;;OAeG;IACG,gBAAgB,CAClB,WAA0B;;YAE1B,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,qBAAqB,CAAC,WAAW,CAAC,CAAC;YAC/D,OAAO,QAAQ,CAAC,GAAG,CAAC,kBAAkB,CAAC,CAAC;QAC5C,CAAC;KAAA;CACJ"}

package/dist/index.d.ts

@@ -4,6 +4,7 @@ export { SdkConfig } from './sdk-config';
 export type { PoolOverview, TrancheData, LendingTotals, PoolRepayment, RiskManagement, PoolDelegateProfileAndHistory, PoolTranche, PoolCreditMetrics, BadAndDoubtfulDebts, FinancialReportingDocuments, } from './services/DataService/types';
 export type { UserRequest, UserRequestEvent, UserTrancheBalance, UserPoolBalance, UserApyBonus, PortfolioUserTrancheBalance, } from './services/UserLending/types';
 export type { PortfolioSummary, PortfolioLendingPool, PortfolioTranche, PortfolioRewards, PortfolioTrancheDepositDetails, } from './services/Portfolio/types';
+export type { YieldHistoryOptions } from './services/Portfolio/yield-history';
 export type { UserLock, UserBonusData, LockPeriod, GQLGetLockingPeriods, SystemVariables, } from './services/Locking/types';
 export type { PoolOverviewDirectus, PlatformOverviewDirectus, } from './services/DataService/directus-types';
 export { NO_DIRECTUS_URL_MESSAGE } from './services/DataService/directus-client';

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,4CAA4C;AAC5C,8EAA8E;AAC9E,OAAO,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAMrC,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAgDzC,OAAO,EAAE,uBAAuB,EAAE,MAAM,wCAAwC,CAAC;AAEjF,8EAA8E;AAC9E,+CAA+C;AAC/C,8EAA8E;AAC9E,cAAc,UAAU,CAAC;AAEzB,8EAA8E;AAC9E,6EAA6E;AAC7E,uDAAuD;AACvD,8EAA8E;AAC9E,cAAc,UAAU,CAAC;AAEzB,8EAA8E;AAC9E,6EAA6E;AAC7E,uEAAuE;AACvE,wDAAwD;AACxD,8EAA8E;AAC9E,cAAc,SAAS,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,4CAA4C;AAC5C,8EAA8E;AAC9E,OAAO,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAMrC,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAkDzC,OAAO,EAAE,uBAAuB,EAAE,MAAM,wCAAwC,CAAC;AAEjF,8EAA8E;AAC9E,+CAA+C;AAC/C,8EAA8E;AAC9E,cAAc,UAAU,CAAC;AAEzB,8EAA8E;AAC9E,6EAA6E;AAC7E,uDAAuD;AACvD,8EAA8E;AAC9E,cAAc,UAAU,CAAC;AAEzB,8EAA8E;AAC9E,6EAA6E;AAC7E,uEAAuE;AACvE,wDAAwD;AACxD,8EAA8E;AAC9E,cAAc,SAAS,CAAC"}

package/dist/services/Portfolio/portfolio.d.ts

@@ -1,10 +1,12 @@
 import { Provider } from '@ethersproject/providers';
 import { BigNumber, Signer } from 'ethers';
+import { YieldHistoryEntry } from '../../domain/yield-history';
 import { SdkConfig } from '../../sdk-config';
 import { TrancheConfigurationSubgraphResult, TrancheSubgraphResult } from '../DataService/subgraph-types';
 import { PoolOverview } from '../DataService/types';
 import { LockingSummarySubgraphResult, SystemVariables } from '../Locking/types';
 import { PortfolioLendingPool, PortfolioRewards, PortfolioSummary, UserLendingPoolTrancheFixedTermDepositLock } from './types';
+import { YieldHistoryOptions } from './yield-history';
 export declare class Portfolio {
     private _kasuConfig;
     private _lockingService;
@@ -56,6 +58,41 @@ export declare class Portfolio {
     getUserNfts(userAddress: string): Promise<number[]>;
     getPortfolioSummary(userAddress: string, portfolioLendingPools: PortfolioLendingPool[], currentEpoch: string): Promise<PortfolioSummary>;
     getPortfolioLendingData(userAddress: string, poolOverviews: PoolOverview[], currentEpoch: string, provider?: Provider): Promise<PortfolioLendingPool[]>;
+    /**
+     * 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: string, options?: YieldHistoryOptions): Promise<YieldHistoryEntry[]>;
+    /**
+     * 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: number): string;
     calculateFixedTermDepositEarnings(fixedTermDepositLock: UserLendingPoolTrancheFixedTermDepositLock, totalTrancheBalance: string, totalTrancheShares: string): number;
 }