@kasufinance/kasu-sdk 2.10.3 → 2.12.0

package/src/domain/strategy-summary.ts

@@ -0,0 +1,88 @@
+/**
+ * A strategy's SHORT blurb, as plain text: the CMS `liteDescription` first,
+ * else the first paragraph of the long `description`, else nothing.
+ *
+ * Lifted from kasu-ui (`pickShortDescription`, its deposit dialog and landing
+ * strategy card) so every app shows the same line, and pinned to its output
+ * for every live CMS row. The rules are facts about how the CMS is authored,
+ * not formatting preferences:
+ *
+ *   - `liteDescription` IS THE SHORT ONE. `description` is the credit
+ *     originator's several-paragraph profile; on a card it is a wall.
+ *   - `"Not Available"` IS A PLACEHOLDER, not editorial. Several rows carry it
+ *     verbatim, and it must read as missing, not print. Matched on the whole
+ *     trimmed value, case-insensitively. It applies to `liteDescription` only.
+ *   - EMPTY OR BLANK IS MISSING. The service maps a pool with no CMS record to
+ *     `''`.
+ *   - THE FIELDS HOLD MARKDOWN. `liteDescription` can open with a `**bold**`
+ *     lead, and the surfaces this feeds render plain text, so the markers are
+ *     stripped (bold, then italic, then inline code).
+ *   - AND HARD NEWLINES. Every run of whitespace becomes one space, so a
+ *     paragraph break inside the value is not a gap in a one-line slot.
+ *   - NOT SANITISED. "Plain text" means text to render AS text. HTML tags,
+ *     entities and link syntax (`<script>`, `&lt;`, `[a](javascript:…)`) pass
+ *     through unchanged, and removing markers can join fragments into a tag
+ *     (`<scr**i**pt>` becomes `<script>`). Render it as a text node, never as
+ *     HTML or markdown.
+ *
+ * Two refinements over the kasu-ui original, neither reachable by any live
+ * row: the cleaned text is trimmed (a CRLF value no longer ends in a space),
+ * and a `liteDescription` that cleans to nothing (`** **`) counts as missing,
+ * so the result is never a blank string.
+ *
+ * This authors no string of its own. It selects and cleans editorial the CMS
+ * already holds, and an absent blurb is `undefined`, never a fallback sentence:
+ * what "no blurb" means is the render site's decision.
+ *
+ * Pure. A value that is not a string reads as missing.
+ */
+export function pickShortDescription(
+    source: ShortDescriptionSource,
+): string | undefined {
+    const lite = asTrimmed(source.liteDescription);
+    if (lite && !NOT_AVAILABLE.test(lite)) {
+        const summary = toOneLine(lite);
+        if (summary) return summary;
+    }
+    const long = asTrimmed(source.description);
+    if (long) {
+        const firstParagraph = long.split(PARAGRAPH_BREAK, 1)[0] ?? long;
+        return toOneLine(firstParagraph) || undefined;
+    }
+    return undefined;
+}
+
+/**
+ * The two CMS fields `pickShortDescription` reads. A `PoolOverview` and a
+ * facade `Strategy` both satisfy it.
+ */
+export interface ShortDescriptionSource {
+    liteDescription?: string | null;
+    description?: string | null;
+}
+
+const NOT_AVAILABLE = /^not available$/i;
+const PARAGRAPH_BREAK = /\n\s*\n/;
+
+function asTrimmed(value: unknown): string {
+    return typeof value === 'string' ? value.trim() : '';
+}
+
+/** Markers off, whitespace runs to one space, ends trimmed. `''` when nothing is left. */
+function toOneLine(text: string): string {
+    return stripInlineMarkdown(text).replace(/\s+/gu, ' ').trim();
+}
+
+/**
+ * Inline markdown markers off, in the order bold → italic → code. The bold
+ * passes consume every `**` / `__` pair first, so the italic patterns can match
+ * a lone `*` / `_` without lookarounds.
+ */
+function stripInlineMarkdown(input: string): string {
+    return input
+        .replace(/\*\*(.+?)\*\*/g, '$1')
+        .replace(/__(.+?)__/g, '$1')
+        .replace(/\*(.+?)\*/g, '$1')
+        .replace(/_(.+?)_/g, '$1')
+        .replace(/`([^`]+)`/g, '$1');
+}

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);
+}

package/src/facade/strategies.ts

@@ -1,4 +1,5 @@
 import { selectVisiblePools } from '../domain/pools';
+import { pickShortDescription } from '../domain/strategy-summary';
 import { DataService } from '../services/DataService/data-service';
 import {
     PoolDelegateProfileAndHistory,
@@ -218,6 +219,7 @@ export class StrategiesFacade {
             subheading: nonEmptyOrUndefined(pool.subheading),
             description: pool.description,
             liteDescription: nonEmptyOrUndefined(pool.liteDescription),
+            summary: pickShortDescription(pool),
             isActive: pool.isActive,
             apy: pool.apy,
             tvl: pool.totalValueLocked,

package/src/facade/types.ts

@@ -121,6 +121,19 @@ export interface Strategy {
      * Absent when the record has none, or an empty one.
      */
     liteDescription?: string;
+    /**
+     * The strategy's short blurb as ONE line of plain text, for cards and
+     * compact surfaces: `liteDescription` when it is usable, else the first
+     * paragraph of `description`, with inline markdown markers stripped and
+     * every run of whitespace collapsed to one space. The `"Not Available"`
+     * placeholder, an empty or blank value, and a missing one all count as
+     * absent. `undefined` when neither field yields a blurb; the SDK never
+     * substitutes a sentence of its own. See `pickShortDescription`.
+     *
+     * Not sanitised: HTML tags and link syntax pass through unchanged. Render
+     * it as text, never as HTML or markdown.
+     */
+    summary?: string;
     isActive: boolean;
     /** Weighted-average APY across tranches (decimal, e.g. 0.08 = 8 %). */
     apy: number;

package/src/facade/user-portfolio.ts

@@ -1,8 +1,10 @@
 import { Provider } from '@ethersproject/providers';
 
 import { deriveRequestState, 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';
 
@@ -39,9 +41,8 @@ export class PortfolioFacade {
     ): Promise<UserPositions> {
         const currentEpoch = await this._userLending.getCurrentEpoch();
 
-        const poolOverviews = await this._dataService.getPoolOverview(
-            currentEpoch,
-        );
+        const poolOverviews =
+            await this._dataService.getPoolOverview(currentEpoch);
 
         const pools = await this._portfolio.getPortfolioLendingData(
             userAddress,
@@ -59,6 +60,42 @@ 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.
+     */
+    async getYieldHistory(
+        userAddress: string,
+        options?: YieldHistoryOptions,
+    ): Promise<YieldHistoryEntry[]> {
+        return await this._portfolio.getYieldHistory(userAddress, options);
+    }
+
     /**
      * Fetch a user's full transaction history (deposits, withdrawals, cancellations).
      */

package/src/index.ts

@@ -42,6 +42,8 @@ export type {
     PortfolioTrancheDepositDetails,
 } from './services/Portfolio/types';
 
+export type { YieldHistoryOptions } from './services/Portfolio/yield-history';
+
 export type {
     UserLock,
     UserBonusData,