@kasufinance/kasu-sdk 2.4.2 → 2.6.0

package/src/domain/settlement.ts

@@ -0,0 +1,161 @@
+/**
+ * Cycles and the clearing window — the protocol's weekly clock, as numbers.
+ *
+ * Lifted verbatim from kasu-ui's `features/portfolio/lib/settlement-window.ts`
+ * and `features/lending/lib/cycle-dates.ts`. The two formatters that live
+ * beside `deriveCycleDates` there (`formatCycleDate`, `formatCycleCloseUtc`)
+ * print words and stay in the applications; everything here is unix seconds in
+ * and unix seconds out.
+ *
+ * The clearing window is the fixed 48 hours immediately preceding an epoch
+ * end. Inside it, pending requests are being processed and cannot be modified,
+ * and the countdown runs to the epoch end. Outside it, the countdown runs to
+ * the next clearing-window start.
+ *
+ * The epoch end comes straight from the chain (`nextEpochStartTimestamp`, i.e.
+ * the SDK's `getNextEpochDate`) — the same value the protocol's own
+ * `getNextClearingPeriodDate` derives from — so the window always lines up
+ * with the real weekly schedule (Tue 06:00 → Thu 06:00 UTC on Base) instead of
+ * a projected subgraph timestamp that can drift off the grid.
+ */
+
+/**
+ * Clearing-window length — a fixed 48h protocol constant. Exported so every
+ * consumer derives the window from the same number this module runs on.
+ */
+export const CLEARING_WINDOW_SECONDS = 48 * 60 * 60;
+
+/**
+ * Weekly cadence — the epoch schedule is fixed weekly (Tue → Thu UTC on Base).
+ * Used only to roll a cycle forward when a request lands inside a window that
+ * has already closed.
+ */
+const WEEK_SECONDS = 7 * 24 * 60 * 60;
+
+export type SettlementWindowState =
+    | {
+          phase: 'awaiting';
+          secondsUntilClearing: number;
+          nextClearingStart: number;
+      }
+    | { phase: 'clearing'; secondsUntilEpochEnd: number; epochEnd: number }
+    | { phase: 'unknown' };
+
+export interface SettlementWindowInput {
+    /** Now, in unix seconds. */
+    nowSeconds: number;
+    /**
+     * Authoritative epoch end, in unix seconds — the chain's
+     * `nextEpochStartTimestamp` (SDK `getNextEpochDate`). During an epoch this
+     * is in the future; it refetches to the next boundary once it rolls.
+     */
+    nextEpochStart: number;
+    /** Clearing-window length; defaults to the 48h protocol constant. */
+    clearingWindowSeconds?: number;
+}
+
+/**
+ * Which phase of the weekly cycle `nowSeconds` falls in, and how long is left
+ * of it.
+ *
+ * `'unknown'` when no epoch boundary has been loaded yet, or when the one on
+ * hand is stale (it has already elapsed — the on-chain value refetches to the
+ * next boundary shortly after rollover). A caller must render its "no cycle
+ * loaded" state there, never a zeroed countdown.
+ */
+export function computeSettlementWindow({
+    nowSeconds,
+    nextEpochStart,
+    clearingWindowSeconds = CLEARING_WINDOW_SECONDS,
+}: SettlementWindowInput): SettlementWindowState {
+    // No epoch boundary loaded yet, or a stale one that already elapsed.
+    if (nextEpochStart <= 0 || nextEpochStart <= nowSeconds) {
+        return { phase: 'unknown' };
+    }
+
+    const clearingStart = nextEpochStart - clearingWindowSeconds;
+
+    if (nowSeconds < clearingStart) {
+        return {
+            phase: 'awaiting',
+            secondsUntilClearing: clearingStart - nowSeconds,
+            nextClearingStart: clearingStart,
+        };
+    }
+
+    // nowSeconds is in [clearingStart, nextEpochStart) — inside the window.
+    return {
+        phase: 'clearing',
+        secondsUntilEpochEnd: nextEpochStart - nowSeconds,
+        epochEnd: nextEpochStart,
+    };
+}
+
+/**
+ * The next cycle boundary strictly after `nowSeconds`, in unix seconds — the
+ * cycle close (`nextEpochStart − 48h`) while the window is still open, the
+ * epoch end once we are inside it.
+ *
+ * `undefined` when there is no boundary left to wait for: no epoch boundary
+ * loaded, or a cached one that has already elapsed — the same staleness rule
+ * `computeSettlementWindow` applies before it reports `'unknown'`.
+ *
+ * Split out of the state machine because some consumers need the INSTANT
+ * rather than the phase: one to flush the cycle-dependent caches when the
+ * clock crosses it, one to move a pre-commit screen's snapshot clock at the
+ * same moment.
+ */
+export function nextCycleBoundary(
+    nextEpochStart: number | undefined,
+    nowSeconds: number,
+    clearingWindowSeconds: number = CLEARING_WINDOW_SECONDS,
+): number | undefined {
+    if (!nextEpochStart || nextEpochStart <= 0) return undefined;
+    const clearingStart = nextEpochStart - clearingWindowSeconds;
+    if (nowSeconds < clearingStart) return clearingStart;
+    if (nowSeconds < nextEpochStart) return nextEpochStart;
+    return undefined;
+}
+
+export interface CycleDates {
+    /** Unix seconds — the next cycle close (clearing-window start). */
+    close: number;
+    /** Unix seconds — the outcome-confirmed-by boundary (close + 48h). */
+    outcome: number;
+}
+
+/**
+ * The cycle-close and outcome dates for a request submitted `now`.
+ *
+ * - The cycle "closes" (stops accepting requests, starts processing) at the
+ *   start of the 48h clearing window, i.e. 48h before the epoch end.
+ * - Processing takes up to 48h, so the outcome is confirmed by the epoch end
+ *   (close + 48h).
+ *
+ * Returns `null` when the epoch boundary is not available or is stale — a
+ * caller then omits the dates entirely (omit, don't stub).
+ *
+ * The common case is a request submitted OUTSIDE the clearing window: the
+ * close is `nextEpochStart − 48h` and the outcome is `nextEpochStart`. When
+ * the request lands INSIDE the current clearing window (that close is already
+ * in the past), it queues for the NEXT weekly cycle, so the close is advanced
+ * by whole weeks until it is in the future.
+ */
+export function deriveCycleDates(
+    nextEpochStart: number | undefined,
+    nowSeconds: number,
+): CycleDates | null {
+    // No boundary loaded, or a stale one that already elapsed — the same
+    // staleness rule as `computeSettlementWindow`.
+    if (!nextEpochStart || nextEpochStart <= nowSeconds) return null;
+
+    let close = nextEpochStart - CLEARING_WINDOW_SECONDS;
+    let outcome = nextEpochStart;
+    // Inside the current clearing window the close already passed; a request
+    // now is queued for the next weekly cycle.
+    while (close <= nowSeconds) {
+        close += WEEK_SECONDS;
+        outcome += WEEK_SECONDS;
+    }
+    return { close, outcome };
+}

package/src/domain/tranche-display-name.test.ts

@@ -0,0 +1,96 @@
+import { getTrancheDisplayName, UPPER_MEZZANINE } from './tranche-display-name';
+
+// Ported from kasu-ui `src/features/lending/lib/tranche-display-name.test.ts`.
+
+describe('getTrancheDisplayName', () => {
+    it('renames Senior to Upper Mezzanine on Apxium pools', () => {
+        expect(
+            getTrancheDisplayName('Senior', {
+                poolName: 'Taxation Funding (Tax Pay)',
+            }),
+        ).toBe(UPPER_MEZZANINE);
+        expect(
+            getTrancheDisplayName('Senior', {
+                poolName: 'Professional Fee Funding',
+            }),
+        ).toBe(UPPER_MEZZANINE);
+        expect(
+            getTrancheDisplayName('Senior', { poolName: 'Whole Ledger Funding' }),
+        ).toBe(UPPER_MEZZANINE);
+    });
+
+    it('keeps Senior on non-Apxium (InvoiceMate) pools', () => {
+        expect(
+            getTrancheDisplayName('Senior', {
+                poolName: 'Payment Finance (PayFi) - Clearing Houses',
+            }),
+        ).toBe('Senior');
+    });
+
+    it('never touches other tranche names, on any pool', () => {
+        expect(
+            getTrancheDisplayName('Mezzanine', { poolName: 'Taxation Funding' }),
+        ).toBe('Mezzanine');
+        expect(
+            getTrancheDisplayName('Junior', { poolName: 'Taxation Funding' }),
+        ).toBe('Junior');
+        expect(
+            getTrancheDisplayName('Mezzanine', {
+                poolName: 'Payment Finance (PayFi)',
+            }),
+        ).toBe('Mezzanine');
+    });
+
+    it('matches the Senior name case-insensitively but preserves unknown names verbatim', () => {
+        expect(
+            getTrancheDisplayName('SENIOR', { poolName: 'Taxation Funding' }),
+        ).toBe(UPPER_MEZZANINE);
+        expect(
+            getTrancheDisplayName('Senior Plus', { poolName: 'Taxation Funding' }),
+        ).toBe('Senior Plus');
+    });
+
+    it('treats missing pool names as Apxium (matches getCreditOriginator default)', () => {
+        // getCreditOriginator defaults unknown pools to Apxium; the display
+        // name must follow the same rule or the two surfaces would disagree.
+        expect(getTrancheDisplayName('Senior', { poolName: '' })).toBe(
+            UPPER_MEZZANINE,
+        );
+        expect(getTrancheDisplayName('Senior', {})).toBe(UPPER_MEZZANINE);
+    });
+});
+
+describe('getTrancheDisplayName — the widened PoolNameSignal', () => {
+    it('accepts the facade Strategy shape (`name`)', () => {
+        expect(getTrancheDisplayName('Senior', { name: 'Taxation Funding' })).toBe(
+            UPPER_MEZZANINE,
+        );
+        expect(
+            getTrancheDisplayName('Senior', {
+                name: 'Payment Finance (PayFi)',
+            }),
+        ).toBe('Senior');
+    });
+
+    it('accepts a bare pool name', () => {
+        expect(getTrancheDisplayName('Senior', 'Whole Ledger Funding')).toBe(
+            UPPER_MEZZANINE,
+        );
+        expect(getTrancheDisplayName('Senior', 'Payment Finance (PayFi)')).toBe(
+            'Senior',
+        );
+    });
+
+    it('gives the same answer for the raw and facade shapes of one pool', () => {
+        for (const poolName of [
+            'Taxation Funding (Tax Pay)',
+            'Payment Finance (PayFi)',
+            'Whole Ledger Funding',
+            '',
+        ]) {
+            expect(getTrancheDisplayName('Senior', { poolName })).toBe(
+                getTrancheDisplayName('Senior', { name: poolName }),
+            );
+        }
+    });
+});

package/src/domain/tranche-display-name.ts

@@ -0,0 +1,34 @@
+import { APXIUM, getCreditOriginator, PoolNameSignal } from './partners';
+
+// Business rename (2026-07): Apxium strategies market their top retail tranche
+// as "Upper Mezzanine" — the true senior position is held by the institutional
+// lender (Rixon Capital), so retail lenders are never actually senior in the
+// waterfall. Display-only: subgraph/SDK tranche names, ids and any
+// seniority-ranking logic keep the on-chain "Senior" name.
+export const UPPER_MEZZANINE = 'Upper Mezzanine';
+
+const SENIOR = 'senior';
+
+/**
+ * User-facing display name for a tranche. Maps `Senior` → `Upper Mezzanine`
+ * on Apxium pools (identified by pool name, see `partners.ts`); every other
+ * tranche/pool combination passes through unchanged.
+ *
+ * Call this at the view-model boundary (options, cards, transaction views),
+ * NEVER in matching/sorting logic — `compareTrancheSeniority` and
+ * `pickDefaultTrancheId` rank by the raw subgraph name and must keep doing so.
+ * This is the one function in `domain/` that returns a user-visible string,
+ * and it is here rather than in each frontend so all three cannot drift.
+ *
+ * `pool` accepts the raw `PoolOverview` (`poolName`), the facade `Strategy`
+ * (`name`), or the name itself.
+ */
+export function getTrancheDisplayName(
+    trancheName: string,
+    pool: PoolNameSignal,
+): string {
+    if (trancheName.trim().toLowerCase() !== SENIOR) return trancheName;
+    return getCreditOriginator(pool).name === APXIUM.name
+        ? UPPER_MEZZANINE
+        : trancheName;
+}

package/src/domain/tranches.test.ts

@@ -0,0 +1,300 @@
+import * as fc from 'fast-check';
+
+import { PoolOverview, TrancheData } from '../services/DataService/types';
+
+import { netEffectiveApy } from './rates';
+import {
+    compareTrancheSeniority,
+    derivePoolStatus,
+    MIN_TRANCHE_CAPACITY,
+    netTrancheApyBounds,
+    pickDefaultTrancheId,
+    poolAllTranchesFull,
+    trancheApyBounds,
+    trancheHasCapacity,
+    trancheRiskRank,
+} from './tranches';
+
+/**
+ * Ported from kasu-ui `pick-default-tranche.test.ts` and the NUMERIC half of
+ * `format-tranche-apy.range.test.ts`. The formatting cases — whole-percent
+ * rendering, the en-dash shape, the locale table and the "collapse when both
+ * bounds print the same" rule — stay in kasu-ui: they are decided on rendered
+ * digits, which this layer never produces.
+ */
+
+// `id === name` keeps assertions readable; `poolCapacity` drives
+// `trancheHasCapacity` (≥ 1 stable unit → selectable).
+function tranche(name: string, poolCapacity: string, apy = '0.12'): TrancheData {
+    return { id: name, name, apy, poolCapacity } as unknown as TrancheData;
+}
+function pool(tranches: TrancheData[], enabled = true): PoolOverview {
+    return { id: 'p', poolName: 'p', enabled, tranches } as unknown as PoolOverview;
+}
+function rated(minApy: string, maxApy: string): TrancheData {
+    return { minApy, maxApy } as unknown as TrancheData;
+}
+
+/** The live performance fee on all deployments (subgraph units: 10 = 10%). */
+const FEE = 10;
+
+describe('trancheHasCapacity', () => {
+    it('accepts a tranche with at least one whole stable unit left', () => {
+        expect(trancheHasCapacity({ poolCapacity: '5000' })).toBe(true);
+        expect(
+            trancheHasCapacity({ poolCapacity: String(MIN_TRANCHE_CAPACITY) }),
+        ).toBe(true);
+    });
+
+    it('rejects sub-unit dust, zero and unparseable capacity', () => {
+        expect(trancheHasCapacity({ poolCapacity: '0.99' })).toBe(false);
+        expect(trancheHasCapacity({ poolCapacity: '0' })).toBe(false);
+        expect(
+            trancheHasCapacity({ poolCapacity: '1.4551915228366852e-11' }),
+        ).toBe(false);
+        expect(trancheHasCapacity({ poolCapacity: '' })).toBe(false);
+        expect(trancheHasCapacity({ poolCapacity: 'not-a-number' })).toBe(false);
+    });
+
+    it('reads the facade tranche shape (availableCapacity) identically', () => {
+        // `StrategyTranche` renames the same number; one gate, both shapes.
+        expect(trancheHasCapacity({ availableCapacity: '5000' })).toBe(true);
+        expect(trancheHasCapacity({ availableCapacity: '0' })).toBe(false);
+    });
+});
+
+describe('trancheRiskRank / compareTrancheSeniority', () => {
+    it('ranks the waterfall safest-first by the RAW name', () => {
+        expect(trancheRiskRank(tranche('Senior', '1'))).toBe(0);
+        expect(trancheRiskRank(tranche('Mezzanine', '1'))).toBe(1);
+        expect(trancheRiskRank(tranche('Junior', '1'))).toBe(2);
+    });
+
+    it('is case- and whitespace-insensitive, and sorts unknown names last', () => {
+        expect(trancheRiskRank(tranche('  SENIOR ', '1'))).toBe(0);
+        expect(trancheRiskRank(tranche('Upper Mezzanine', '1'))).toBe(
+            Number.POSITIVE_INFINITY,
+        );
+    });
+
+    it('sorts Senior → Mezzanine → Junior, keeping ties in input order', () => {
+        const tranches = [
+            tranche('Junior', '5000'),
+            tranche('Tranche B', '5000'),
+            tranche('Senior', '5000'),
+            tranche('Tranche A', '5000'),
+            tranche('Mezzanine', '5000'),
+        ];
+        expect(
+            [...tranches].sort(compareTrancheSeniority).map((t) => t.name),
+        ).toEqual([
+            'Senior',
+            'Mezzanine',
+            'Junior',
+            'Tranche B',
+            'Tranche A',
+        ]);
+    });
+});
+
+describe('pickDefaultTrancheId', () => {
+    it('defaults to the lowest-risk tranche (Senior) when all have capacity', () => {
+        // Subgraph order is Junior → Mezzanine → Senior; the default must NOT
+        // be the highest-risk Junior that sits first (audit 3.2).
+        const id = pickDefaultTrancheId(
+            pool([
+                tranche('Junior', '5000'),
+                tranche('Mezzanine', '5000'),
+                tranche('Senior', '5000'),
+            ]),
+        );
+        expect(id).toBe('Senior');
+    });
+
+    it('picks the lowest-risk tranche that is still AVAILABLE (skips a full Senior)', () => {
+        const id = pickDefaultTrancheId(
+            pool([
+                tranche('Junior', '5000'),
+                tranche('Mezzanine', '5000'),
+                tranche('Senior', '0'),
+            ]),
+        );
+        expect(id).toBe('Mezzanine');
+    });
+
+    it('does not rank by APY — a Senior priced above Mezzanine is still preferred', () => {
+        // Real pools can price Senior above Mezzanine; risk is ranked by name,
+        // not rate.
+        const id = pickDefaultTrancheId(
+            pool([
+                tranche('Mezzanine', '5000', '0.15'),
+                tranche('Senior', '5000', '0.18'),
+            ]),
+        );
+        expect(id).toBe('Senior');
+    });
+
+    it('falls back to the lowest-risk tranche when every tranche is full', () => {
+        const id = pickDefaultTrancheId(
+            pool([tranche('Junior', '0'), tranche('Senior', '0')]),
+        );
+        expect(id).toBe('Senior');
+    });
+
+    it('falls back to the first available tranche when names are unrecognised', () => {
+        const id = pickDefaultTrancheId(
+            pool([tranche('Tranche B', '5000'), tranche('Tranche A', '5000')]),
+        );
+        expect(id).toBe('Tranche B');
+    });
+
+    it('returns an empty string for a pool with no tranches', () => {
+        expect(pickDefaultTrancheId(pool([]))).toBe('');
+    });
+});
+
+describe('poolAllTranchesFull', () => {
+    it('is true when every tranche lacks remaining capacity', () => {
+        expect(
+            poolAllTranchesFull(
+                pool([tranche('Junior', '0'), tranche('Senior', '0')]),
+            ),
+        ).toBe(true);
+    });
+
+    it('is false when at least one tranche still has capacity', () => {
+        expect(
+            poolAllTranchesFull(
+                pool([tranche('Junior', '0'), tranche('Senior', '5000')]),
+            ),
+        ).toBe(false);
+    });
+
+    it('is false for a pool with no tranches (nothing to be full)', () => {
+        expect(poolAllTranchesFull(pool([]))).toBe(false);
+    });
+});
+
+describe('derivePoolStatus', () => {
+    it('is "Coming soon" for a pool that is not yet enabled, full or not', () => {
+        expect(derivePoolStatus(pool([tranche('Senior', '5000')], false))).toBe(
+            'Coming soon',
+        );
+        expect(derivePoolStatus(pool([tranche('Senior', '0')], false))).toBe(
+            'Coming soon',
+        );
+    });
+
+    it('is "Full" for an enabled pool with no capacity anywhere', () => {
+        expect(derivePoolStatus(pool([tranche('Senior', '0')]))).toBe('Full');
+    });
+
+    it('is "Live" for an enabled pool with capacity, or with no tranches yet', () => {
+        expect(derivePoolStatus(pool([tranche('Senior', '5000')]))).toBe('Live');
+        expect(derivePoolStatus(pool([]))).toBe('Live');
+    });
+});
+
+describe('trancheApyBounds', () => {
+    it('spans the lowest minApy and the highest maxApy across tranches', () => {
+        expect(
+            trancheApyBounds([rated('0.12', '0.12'), rated('0.185', '0.185')]),
+        ).toEqual({ min: 0.12, max: 0.185 });
+    });
+
+    it('carries a single-option strategy as an equal pair', () => {
+        expect(trancheApyBounds([rated('0.1', '0.1')])).toEqual({
+            min: 0.1,
+            max: 0.1,
+        });
+    });
+
+    it('skips zero and non-finite rates rather than dragging the range down', () => {
+        // A tranche with no fixed-term config must not turn a 10.5% range into
+        // 0–10.5%.
+        expect(
+            trancheApyBounds([rated('0', '0'), rated('0.105', '0.105')]),
+        ).toEqual({ min: 0.105, max: 0.105 });
+        expect(
+            trancheApyBounds([rated('not-a-number', 'x'), rated('0.12', '0.14')]),
+        ).toEqual({ min: 0.12, max: 0.14 });
+    });
+
+    it('is null when nothing usable remains', () => {
+        expect(trancheApyBounds([])).toBeNull();
+        expect(trancheApyBounds([rated('0', '0')])).toBeNull();
+        expect(trancheApyBounds([rated('-0.1', '-0.1')])).toBeNull();
+    });
+
+    it('is null when only ONE side is usable — never half a range', () => {
+        expect(trancheApyBounds([rated('0.12', '0')])).toBeNull();
+        expect(trancheApyBounds([rated('0', '0.12')])).toBeNull();
+    });
+});
+
+describe('netTrancheApyBounds', () => {
+    it('reproduces the spec §2.5 card range: 14–22% gross is 13–20% net', () => {
+        const bounds = netTrancheApyBounds([rated('0.14', '0.22')], FEE);
+        expect(bounds).not.toBeNull();
+        expect(bounds?.min).toBeCloseTo(0.1252, 4);
+        expect(bounds?.max).toBeCloseTo(0.196, 4);
+    });
+
+    it('puts each bound through netEffectiveApy and nothing else', () => {
+        const bounds = netTrancheApyBounds([rated('0.12', '0.185')], FEE);
+        expect(bounds).toEqual({
+            min: netEffectiveApy(0.12, FEE),
+            max: netEffectiveApy(0.185, FEE),
+        });
+    });
+
+    it('returns the gross bounds unchanged at a zero fee', () => {
+        expect(netTrancheApyBounds([rated('0.14', '0.22')], 0)).toEqual({
+            min: 0.14,
+            max: 0.22,
+        });
+    });
+
+    it('FAILS CLOSED on an out-of-domain fee — never the gross range', () => {
+        // The raw subgraph integer (1000 = 10%) and a negative fee both land
+        // here. A caller that does not KNOW the fee must not call at all;
+        // substituting 0 would overstate the rate with nothing saying so.
+        expect(netTrancheApyBounds([rated('0.14', '0.22')], 1000)).toBeNull();
+        expect(netTrancheApyBounds([rated('0.14', '0.22')], -1)).toBeNull();
+        expect(netTrancheApyBounds([rated('0.14', '0.22')], NaN)).toBeNull();
+    });
+
+    it('is null when a 100% fee leaves the lender nothing', () => {
+        expect(netTrancheApyBounds([rated('0.14', '0.22')], 100)).toBeNull();
+    });
+
+    it('is null whenever the gross range is', () => {
+        expect(netTrancheApyBounds([], FEE)).toBeNull();
+        expect(netTrancheApyBounds([rated('0', '0')], FEE)).toBeNull();
+    });
+
+    it('never inverts the range it was given', () => {
+        fc.assert(
+            fc.property(
+                fc.double({ min: 0.0001, max: 0.99, noNaN: true }),
+                fc.double({ min: 0.0001, max: 0.99, noNaN: true }),
+                fc.double({ min: 0, max: 99, noNaN: true }),
+                (a, b, feePercent) => {
+                    const bounds = netTrancheApyBounds(
+                        [
+                            rated(
+                                String(Math.min(a, b)),
+                                String(Math.max(a, b)),
+                            ),
+                        ],
+                        feePercent,
+                    );
+                    if (!bounds) return;
+                    expect(bounds.min).toBeLessThanOrEqual(bounds.max);
+                    expect(bounds.min).toBeGreaterThan(0);
+                },
+            ),
+            { numRuns: 2000 },
+        );
+    });
+});