@kasufinance/kasu-sdk 2.4.2 → 2.5.0

package/src/domain/rates.ts

@@ -0,0 +1,120 @@
+/**
+ * Epochs in a year — the single source of truth for every rate conversion in
+ * the SDK and in every consumer that undoes one.
+ *
+ * The subgraph carries a per-epoch `interestRate`; `epochRateToApy` compounds
+ * it into an APY and `apyToEpochRate` inverts exactly that. A second copy of
+ * this number anywhere would recover a different weekly rate and every derived
+ * figure — displayed APYs, net rates, projected interest — would be wrong, so
+ * `DataService.calculateApyForTranche` and `KSULocking.calculateApy` both read
+ * it from here rather than declaring their own.
+ */
+export const EPOCHS_IN_YEAR = 52.17857;
+
+/**
+ * A per-epoch interest rate compounded into an annual rate.
+ *
+ * ```
+ * apy = (1 + r)^E − 1
+ * ```
+ *
+ * This is the exact expression `DataService.calculateApyForTranche` has always
+ * used, kept in its literal `**` form rather than rewritten through
+ * `expm1`/`log1p`: it is the SDK's OWN definition of `tranche.apy`, so its
+ * float behaviour is part of the contract every consumer already calibrated
+ * against. `apyToEpochRate` is the one that must be numerically careful,
+ * because it runs on the result.
+ *
+ * @param epochRate the per-epoch rate as a 0..1 fraction (e.g. `0.003`).
+ * @returns the compounded annual rate as a 0..1 fraction.
+ */
+export function epochRateToApy(epochRate: number): number {
+    return (1 + epochRate) ** EPOCHS_IN_YEAR - 1;
+}
+
+/**
+ * The inverse of `epochRateToApy` — the per-epoch rate an APY was compounded
+ * from.
+ *
+ * `expm1`/`log1p` rather than the literal `(1 + apy) ** (1 / E) - 1`.
+ * Algebraically identical, but the direct form computes a double just above 1
+ * and subtracts 1 from it, discarding the low bits of a result that is itself
+ * ~1e-3 for a realistic rate. These two never form the intermediate near-1
+ * value.
+ *
+ * @param apy the compounded annual rate as a 0..1 fraction.
+ * @returns the per-epoch rate as a 0..1 fraction.
+ */
+export function apyToEpochRate(apy: number): number {
+    return Math.expm1(Math.log1p(apy) / EPOCHS_IN_YEAR);
+}
+
+/**
+ * The NET Effective Interest Rate — the compounded annual rate a lender
+ * actually earns, after the platform performance fee.
+ *
+ * ```
+ * r   = (1 + grossApy)^(1/E) − 1                 // the gross per-epoch rate
+ * net = (1 + r · (1 − feePercent/100))^E − 1     // fee taken each epoch, then compounded
+ * ```
+ *
+ * `LendingPool._applyTrancheInterest` mints the lender
+ * `interest × (1 − performanceFee)` at every epoch close, and it is that NET
+ * amount which capitalises and earns interest in the following epoch. So the
+ * fee is applied per epoch and the result is re-compounded — not deducted from
+ * the annual figure.
+ *
+ * ⚠️ UNITS — the one thing that must not be got wrong.
+ * `feePercent` is a PERCENTAGE IN 0..100, **not** a 0..1 fraction.
+ * `DataService.getPerformanceFee()` (and `StrategiesFacade.getPerformanceFeePercent()`)
+ * returns the subgraph's `integerToPercentage2(1000)` = `10`, meaning **ten
+ * percent**. It is NOT `0.10`. Treating it as a fraction computes
+ * `r · (1 − 10)` = `−9r` and yields a nonsense negative rate that would render
+ * as a plausible-looking `-…%`, which is why `feePercent > 100` and
+ * `feePercent < 0` both return `NaN` and why the parameter is named
+ * `feePercent` and never `fee`.
+ *
+ * This returns a NUMBER and nothing else. Rendering it — the 2dp convention,
+ * the ` p.a.` suffix, and the fail-closed em-dash for a `NaN` or non-positive
+ * result — is the consumer's job: kasu-ui does it in
+ * `src/features/lending/lib/interest-rate.ts` (`formatEffectiveRate`,
+ * `RATE_UNAVAILABLE`), which now wraps this function instead of restating it.
+ *
+ * @param grossApy compounded GROSS APY as a 0..1 fraction (e.g. `0.22` for
+ *   22%), exactly as the SDK carries it on `tranche.apy` / `tranche.maxApy`.
+ * @param feePercent the chain's performance fee as a percentage, `0..100`
+ *   (e.g. `10` for the live 10% fee).
+ * @returns the net compounded annual rate as a 0..1 fraction, or `NaN` when
+ *   either input is outside its domain. Callers render `NaN` as "—".
+ */
+export function netEffectiveApy(grossApy: number, feePercent: number): number {
+    if (!Number.isFinite(grossApy) || grossApy < 0) return NaN;
+    if (!Number.isFinite(feePercent) || feePercent < 0 || feePercent > 100) {
+        return NaN;
+    }
+    // The lender's share of each epoch's interest. Short-circuiting on `=== 1`
+    // (rather than on `feePercent === 0`) also covers a fee small enough to
+    // underflow the multiplier: if it cannot change the epoch rate, the net
+    // rate IS the gross rate, and it must be returned unchanged rather than
+    // round-tripped through the de-compound/re-compound pair below — which is
+    // exact in algebra but not in floating point (0.22 comes back as
+    // 0.22000000000000663 in the naive form). If the fee is ever set to zero
+    // on-chain, the displayed rate must equal the SDK's APY exactly.
+    const lenderShare = 1 - feePercent / 100;
+    if (lenderShare === 1) return grossApy;
+    // `expm1`/`log1p` rather than the literal `(1 + x) ** n - 1`. Algebraically
+    // identical, but the direct form computes `(1 + grossApy) ** (1 / E) - 1`
+    // by subtracting 1 from a double just above 1, discarding the low bits of a
+    // result that is itself ~1e-8 for a realistic rate. The ~1e-8 relative
+    // error that survives is enough to push the net rate ABOVE the gross one;
+    // these two never form the intermediate near-1 value.
+    const grossEpochRate = apyToEpochRate(grossApy);
+    const netEpochRate = grossEpochRate * lenderShare;
+    const net = Math.expm1(EPOCHS_IN_YEAR * Math.log1p(netEpochRate));
+    // `net ≤ grossApy` for every `lenderShare ≤ 1` is a theorem, but at the
+    // last ULP it is not a float identity — a fee of 1e-14 percent leaves a
+    // `lenderShare` one ULP below 1 and the round trip can land one ULP above
+    // `grossApy`. Clamping enforces the proven bound rather than letting a
+    // rounding artefact put a net rate above the gross rate it came from.
+    return Math.min(net, grossApy);
+}

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