@kasufinance/kasu-sdk 2.5.0 → 2.7.0

package/src/domain/pools.test.ts

@@ -1,260 +0,0 @@
-import { PoolOverview, TrancheData } from '../services/DataService/types';
-
-import {
-    maxNetRateCeiling,
-    pickHighestYieldTranche,
-    poolMaxApy,
-    selectVisiblePools,
-} from './pools';
-import { netEffectiveApy } from './rates';
-
-/**
- * Ported from kasu-ui `select-visible-pools.test.ts` and the
- * `pickHighestYieldTranche` / `formatMaxNetRate` cases of
- * `pick-best-tranche.test.ts`. The `formatMaxNetRate` assertions are on the
- * ceiling NUMBER here; their rendered strings stay in kasu-ui.
- */
-
-function tranche(
-    name: string,
-    apy: string,
-    poolCapacity: string,
-    maxApy?: string,
-): TrancheData {
-    return { id: name, name, apy, poolCapacity, maxApy } as unknown as TrancheData;
-}
-
-function pool(over: Partial<PoolOverview>): PoolOverview {
-    return {
-        id: 'p',
-        poolName: 'p',
-        isActive: true,
-        isOversubscribed: false,
-        tranches: [tranche('Senior', '0.09', '250000', '0.10')],
-        ...over,
-    } as unknown as PoolOverview;
-}
-
-const withCapacity = (): TrancheData[] => [
-    tranche('Senior', '0.09', '250000', '0.10'),
-];
-const noCapacity = (): TrancheData[] => [tranche('Senior', '0.09', '0', '0.10')];
-
-/** The live performance fee on all deployments. */
-const FEE = 10;
-
-describe('poolMaxApy', () => {
-    it('takes the highest usable maxApy across tranches', () => {
-        expect(
-            poolMaxApy(
-                pool({
-                    tranches: [
-                        tranche('Senior', '0.09', '1', '0.10'),
-                        tranche('Junior', '0.12', '1', '0.18'),
-                    ],
-                }),
-            ),
-        ).toBe(0.18);
-    });
-
-    it('is 0 when nothing is usable', () => {
-        expect(poolMaxApy(pool({ tranches: [] }))).toBe(0);
-        expect(
-            poolMaxApy(pool({ tranches: [tranche('Senior', '0.09', '1', 'x')] })),
-        ).toBe(0);
-    });
-});
-
-describe('selectVisiblePools', () => {
-    it('drops inactive pools', () => {
-        const pools = [
-            pool({ id: 'active', isActive: true }),
-            pool({ id: 'inactive', isActive: false }),
-        ];
-        expect(selectVisiblePools(pools).map((p) => p.id)).toEqual(['active']);
-    });
-
-    it('drops oversubscribed pools', () => {
-        const pools = [
-            pool({ id: 'open', isOversubscribed: false }),
-            pool({ id: 'full', isOversubscribed: true }),
-        ];
-        expect(selectVisiblePools(pools).map((p) => p.id)).toEqual(['open']);
-    });
-
-    it('sorts pools with capacity ahead of pools without', () => {
-        const pools = [
-            pool({ id: 'empty', tranches: noCapacity() }),
-            pool({ id: 'has-cap', tranches: withCapacity() }),
-        ];
-        expect(selectVisiblePools(pools).map((p) => p.id)).toEqual([
-            'has-cap',
-            'empty',
-        ]);
-    });
-
-    it('sorts by highest max APY within the same capacity bucket', () => {
-        const pools = [
-            pool({
-                id: 'low',
-                tranches: [tranche('Senior', '0.08', '250000', '0.08')],
-            }),
-            pool({
-                id: 'high',
-                tranches: [tranche('Senior', '0.15', '250000', '0.15')],
-            }),
-        ];
-        expect(selectVisiblePools(pools).map((p) => p.id)).toEqual([
-            'high',
-            'low',
-        ]);
-    });
-
-    it('does not mutate the input array', () => {
-        const pools = [
-            pool({ id: 'a', tranches: noCapacity() }),
-            pool({ id: 'b', tranches: withCapacity() }),
-        ];
-        const before = pools.map((p) => p.id);
-        selectVisiblePools(pools);
-        expect(pools.map((p) => p.id)).toEqual(before);
-    });
-});
-
-describe('pickHighestYieldTranche', () => {
-    const named = (poolName: string, tranches: TrancheData[]): PoolOverview =>
-        pool({ id: poolName, poolName, tranches });
-
-    it('returns null for empty / nullish input', () => {
-        expect(pickHighestYieldTranche(undefined)).toBeNull();
-        expect(pickHighestYieldTranche(null)).toBeNull();
-        expect(pickHighestYieldTranche([])).toBeNull();
-    });
-
-    it('picks the highest base APY across all pools with capacity', () => {
-        const best = pickHighestYieldTranche([
-            named('A', [tranche('Junior', '0.12', '5000')]),
-            named('B', [
-                tranche('Senior', '0.18', '5000'),
-                tranche('Mezz', '0.15', '5000'),
-            ]),
-        ]);
-        expect(best?.pool.poolName).toBe('B');
-        expect(best?.tranche.name).toBe('Senior');
-        expect(best?.apy).toBeCloseTo(0.18);
-    });
-
-    it('skips tranches without capacity (< 1 unit)', () => {
-        const best = pickHighestYieldTranche([
-            named('Full', [tranche('Junior', '0.30', '0')]),
-            named('Live', [tranche('Senior', '0.10', '2000')]),
-        ]);
-        expect(best?.pool.poolName).toBe('Live');
-        expect(best?.apy).toBeCloseTo(0.1);
-    });
-
-    it('breaks APY ties toward more remaining capacity', () => {
-        const best = pickHighestYieldTranche([
-            named('Small', [tranche('Junior', '0.15', '1000')]),
-            named('Big', [tranche('Junior', '0.15', '9000')]),
-        ]);
-        expect(best?.pool.poolName).toBe('Big');
-    });
-
-    it('ignores zero / non-finite APY values', () => {
-        const best = pickHighestYieldTranche([
-            named('Zero', [tranche('Junior', '0', '5000')]),
-            named('NaN', [tranche('Junior', 'not-a-number', '5000')]),
-            named('Real', [tranche('Junior', '0.09', '5000')]),
-        ]);
-        expect(best?.pool.poolName).toBe('Real');
-    });
-
-    it('reads the BASE rate, not the FTD-widened maxApy', () => {
-        // A ceiling claim and a named tranche's rate are different statements.
-        const best = pickHighestYieldTranche([
-            named('A', [tranche('Junior', '0.12', '5000', '0.30')]),
-            named('B', [tranche('Senior', '0.18', '5000', '0.18')]),
-        ]);
-        expect(best?.pool.poolName).toBe('B');
-    });
-});
-
-describe('maxNetRateCeiling', () => {
-    const named = (poolName: string, tranches: TrancheData[]): PoolOverview =>
-        pool({ id: poolName, poolName, tranches });
-
-    it('returns the highest ceiling across all pools, net of the fee', () => {
-        const rate = maxNetRateCeiling(
-            [
-                named('A', [tranche('Junior', '0.12', '5000', '0.18')]),
-                named('B', [tranche('Senior', '0.10', '5000', '0.22')]),
-            ],
-            FEE,
-        );
-        // 0.22 gross → 19.60% net, the same arithmetic as everywhere else.
-        expect(rate).toBe(netEffectiveApy(0.22, FEE));
-        expect(rate).toBeCloseTo(0.196, 4);
-    });
-
-    it('prefers the FTD-inclusive maxApy over the base rate', () => {
-        // The strategies card's range tops out at maxApy; an "up to" claim
-        // quoting the base rate would contradict it on the same screen.
-        expect(
-            maxNetRateCeiling(
-                [named('A', [tranche('Junior', '0.10', '5000', '0.22')])],
-                FEE,
-            ),
-        ).toBe(netEffectiveApy(0.22, FEE));
-    });
-
-    it('falls back to the base rate when a tranche carries no maxApy', () => {
-        expect(
-            maxNetRateCeiling(
-                [named('A', [tranche('Junior', '0.22', '5000')])],
-                FEE,
-            ),
-        ).toBe(netEffectiveApy(0.22, FEE));
-    });
-
-    it('skips tranches without capacity — an unreachable rate is not a claim', () => {
-        const rate = maxNetRateCeiling(
-            [
-                named('Full', [tranche('Junior', '0.30', '0', '0.30')]),
-                named('Live', [tranche('Senior', '0.10', '5000', '0.10')]),
-            ],
-            FEE,
-        );
-        expect(rate).toBe(netEffectiveApy(0.1, FEE));
-        expect(rate).toBeCloseTo(0.0896, 4);
-    });
-
-    it('returns null rather than a gross figure when the fee is out of domain', () => {
-        const pools = [named('A', [tranche('Junior', '0.22', '5000', '0.22')])];
-        expect(maxNetRateCeiling(pools, 1000)).toBeNull();
-        expect(maxNetRateCeiling(pools, -1)).toBeNull();
-        expect(maxNetRateCeiling(pools, NaN)).toBeNull();
-        // A 100% fee leaves nothing to claim.
-        expect(maxNetRateCeiling(pools, 100)).toBeNull();
-    });
-
-    it('returns null for empty, nullish or rate-less input', () => {
-        expect(maxNetRateCeiling(undefined, FEE)).toBeNull();
-        expect(maxNetRateCeiling(null, FEE)).toBeNull();
-        expect(maxNetRateCeiling([], FEE)).toBeNull();
-        expect(
-            maxNetRateCeiling(
-                [named('Zero', [tranche('Junior', '0', '5000', '0')])],
-                FEE,
-            ),
-        ).toBeNull();
-    });
-
-    it('agrees with the top of the tranche range it must sit alongside', () => {
-        // Both read maxApy through netEffectiveApy; they must not disagree.
-        const tranches = [tranche('Senior', '0.14', '5000', '0.22')];
-        expect(maxNetRateCeiling([named('A', tranches)], FEE)).toBe(
-            netEffectiveApy(0.22, FEE),
-        );
-    });
-});

package/src/domain/rates.test.ts

@@ -1,254 +0,0 @@
-import * as fc from 'fast-check';
-
-import {
-    apyToEpochRate,
-    epochRateToApy,
-    EPOCHS_IN_YEAR,
-    netEffectiveApy,
-} from './rates';
-
-/**
- * Ported from kasu-ui `src/features/lending/lib/interest-rate.test.ts`. The
- * `formatEffectiveRate` cases stay there — they assert copy and locale, which
- * this layer does not own.
- */
-
-/** The live performance fee on all deployments (subgraph units: 10 = ten percent). */
-const LIVE_FEE_PERCENT = 10;
-
-/**
- * Spec §9 — every distinct per-epoch rate configured on Base, read on-chain
- * 2026-09-01, with the NET Effective Interest Rate each must display at the
- * live 10% fee. This table IS the review sanity check: a correct
- * implementation reproduces the whole column, including the 30% crossover row
- * (26.30% gross nominal → 26.64% net APY) which moves UP while every other row
- * moves down, because the two errors in the old display — no fee deducted, and
- * a spurious de-compounding — pull in opposite directions and cross over near
- * 28%.
- */
-const GROUND_TRUTH: readonly { grossApy: number; netPercent: number }[] = [
-    { grossApy: 0.1, netPercent: 8.96 },
-    { grossApy: 0.105, netPercent: 9.4 },
-    { grossApy: 0.12, netPercent: 10.74 },
-    { grossApy: 0.14, netPercent: 12.52 },
-    { grossApy: 0.15, netPercent: 13.41 },
-    { grossApy: 0.16, netPercent: 14.29 },
-    { grossApy: 0.2, netPercent: 17.84 },
-    { grossApy: 0.22, netPercent: 19.6 },
-    { grossApy: 0.3, netPercent: 26.64 },
-];
-
-describe('netEffectiveApy — spec §9 ground truth', () => {
-    it.each(GROUND_TRUTH)(
-        'gross $grossApy at a 10% fee is $netPercent% net',
-        ({ grossApy, netPercent }) => {
-            expect(netEffectiveApy(grossApy, LIVE_FEE_PERCENT) * 100).toBeCloseTo(
-                netPercent,
-                2,
-            );
-        },
-    );
-
-    it('reproduces the 30% crossover — the net APY is ABOVE the old gross nominal figure', () => {
-        // Old display: 52.17857 · ((1.30)^(1/52.17857) − 1) = 26.30%. New: 26.64%.
-        const oldGrossNominal = EPOCHS_IN_YEAR * (1.3 ** (1 / EPOCHS_IN_YEAR) - 1);
-        expect(oldGrossNominal * 100).toBeCloseTo(26.3, 1);
-        expect(netEffectiveApy(0.3, LIVE_FEE_PERCENT)).toBeGreaterThan(
-            oldGrossNominal,
-        );
-    });
-});
-
-describe('netEffectiveApy — units (spec §2.3)', () => {
-    it('reads feePercent as a PERCENTAGE: 22% gross at fee 10 is ≈19.602%', () => {
-        expect(netEffectiveApy(0.22, 10)).toBeCloseTo(0.19602, 5);
-    });
-
-    it('does not silently accept the 0..1 fraction — 0.1 is a 0.1% fee, not 10%', () => {
-        const wrongUnit = netEffectiveApy(0.22, 0.1);
-        const correct = netEffectiveApy(0.22, 10);
-        // It is a finite, in-range number (we cannot reject it — 0.1% is a
-        // legal fee), so the guard cannot catch this. What protects us is that
-        // it is MATERIALLY different: ~2.37pp too high, not a plausible
-        // near-miss that could sit on screen unnoticed.
-        expect(wrongUnit).toBeCloseTo(0.21976, 5);
-        expect(wrongUnit - correct).toBeGreaterThan(0.02);
-    });
-
-    it('rejects the RAW subgraph integer (1000 = 10%, pre-integerToPercentage2)', () => {
-        expect(netEffectiveApy(0.22, 1000)).toBeNaN();
-    });
-
-    it('rejects a fee outside 0..100', () => {
-        expect(netEffectiveApy(0.22, 101)).toBeNaN();
-        expect(netEffectiveApy(0.22, -1)).toBeNaN();
-        expect(netEffectiveApy(0.22, NaN)).toBeNaN();
-        expect(netEffectiveApy(0.22, Infinity)).toBeNaN();
-    });
-
-    it('accepts the domain edges', () => {
-        expect(netEffectiveApy(0.22, 0)).toBe(0.22);
-        // A 100% fee leaves the lender nothing — 0, not NaN: the fee is
-        // knowable and the answer is "you earn zero", which consumers render
-        // as "—".
-        expect(netEffectiveApy(0.22, 100)).toBe(0);
-    });
-
-    it('returns NaN for a non-finite or negative gross APY (callers render "—")', () => {
-        expect(netEffectiveApy(NaN, 10)).toBeNaN();
-        expect(netEffectiveApy(Infinity, 10)).toBeNaN();
-        expect(netEffectiveApy(-Infinity, 10)).toBeNaN();
-        expect(netEffectiveApy(-0.01, 10)).toBeNaN();
-    });
-});
-
-// The FULL in-domain range, down to and including zero and the denormals. The
-// invariants below are the reason `netEffectiveApy` is written with
-// `log1p`/`expm1`: the direct `(1 + x) ** n - 1` form breaks the `net <= gross`
-// invariant for tiny rates, and the property runner finds that in a few hundred
-// cases. Narrowing this arb would hide it.
-const grossApyArb = fc.double({
-    min: 0,
-    max: 5,
-    noNaN: true,
-    noDefaultInfinity: true,
-});
-const feePercentArb = fc.double({
-    min: 0,
-    max: 100,
-    noNaN: true,
-    noDefaultInfinity: true,
-});
-/**
- * A fee as the subgraph can actually express one: `integerToPercentage2`
- * divides a uint by 100, so every reachable value is a 2dp multiple of 0.01 in
- * 0..100. Used only for the STRICT-decrease property, which cannot hold for a
- * fee of 1e-300 percent — `1 − feePercent/100` rounds to exactly 1 and the net
- * rate is the gross one. That is arithmetic, not a defect, and no such fee
- * exists.
- */
-const realisticFeePercentArb = fc
-    .integer({ min: 1, max: 10_000 })
-    .map((n) => n / 100);
-
-describe('netEffectiveApy — invariants', () => {
-    it('never returns more than the gross APY it came from', () => {
-        fc.assert(
-            fc.property(grossApyArb, feePercentArb, (grossApy, feePercent) => {
-                expect(netEffectiveApy(grossApy, feePercent)).toBeLessThanOrEqual(
-                    grossApy,
-                );
-            }),
-        );
-    });
-
-    it('equals the gross APY EXACTLY when the fee is zero', () => {
-        fc.assert(
-            // Exact equality, not "close to": if the fee is ever set to zero
-            // on-chain, the rate must be the SDK's own APY, with no float drift
-            // from the de-compound/re-compound round trip.
-            fc.property(grossApyArb, (grossApy) => {
-                expect(netEffectiveApy(grossApy, 0)).toBe(grossApy);
-            }),
-        );
-    });
-
-    it('is STRICTLY below the gross APY for any real (2dp) non-zero fee', () => {
-        fc.assert(
-            fc.property(
-                grossApyArb,
-                realisticFeePercentArb,
-                (grossApy, feePercent) => {
-                    if (grossApy === 0) return;
-                    expect(netEffectiveApy(grossApy, feePercent)).toBeLessThan(
-                        grossApy,
-                    );
-                },
-            ),
-        );
-    });
-
-    it('decreases monotonically as the fee rises', () => {
-        fc.assert(
-            fc.property(
-                grossApyArb,
-                feePercentArb,
-                feePercentArb,
-                (grossApy, a, b) => {
-                    const [lo, hi] = a <= b ? [a, b] : [b, a];
-                    expect(netEffectiveApy(grossApy, hi)).toBeLessThanOrEqual(
-                        netEffectiveApy(grossApy, lo),
-                    );
-                },
-            ),
-        );
-    });
-
-    it('increases monotonically as the gross APY rises', () => {
-        fc.assert(
-            fc.property(
-                grossApyArb,
-                grossApyArb,
-                feePercentArb,
-                (a, b, feePercent) => {
-                    const [lo, hi] = a <= b ? [a, b] : [b, a];
-                    expect(netEffectiveApy(hi, feePercent)).toBeGreaterThanOrEqual(
-                        netEffectiveApy(lo, feePercent),
-                    );
-                },
-            ),
-        );
-    });
-
-    it('is never negative for any in-domain input', () => {
-        fc.assert(
-            fc.property(grossApyArb, feePercentArb, (grossApy, feePercent) => {
-                expect(
-                    netEffectiveApy(grossApy, feePercent),
-                ).toBeGreaterThanOrEqual(0);
-            }),
-        );
-    });
-});
-
-describe('epochRateToApy / apyToEpochRate', () => {
-    it('compounds a per-epoch rate exactly as the data service always has', () => {
-        // The literal expression `calculateApyForTranche` carried inline.
-        for (const r of [0, 0.001, 0.0025, 0.003, 0.005, 0.01]) {
-            expect(epochRateToApy(r)).toBe((1 + r) ** EPOCHS_IN_YEAR - 1);
-        }
-    });
-
-    it('round-trips within 1e-12 for realistic per-epoch rates', () => {
-        fc.assert(
-            fc.property(
-                // 0.0001..0.02 per epoch ≈ 0.5%..190% APY — wider than any
-                // rate the platform has configured.
-                fc.double({
-                    min: 0.0001,
-                    max: 0.02,
-                    noNaN: true,
-                    noDefaultInfinity: true,
-                }),
-                (r) => {
-                    expect(apyToEpochRate(epochRateToApy(r))).toBeCloseTo(r, 12);
-                },
-            ),
-        );
-    });
-
-    it('inverts the APYs the platform actually quotes', () => {
-        for (const apy of [0.1, 0.12, 0.14, 0.16, 0.22, 0.3]) {
-            expect(epochRateToApy(apyToEpochRate(apy))).toBeCloseTo(apy, 12);
-        }
-    });
-
-    it('is the same de-compounding netEffectiveApy uses at a zero-ish fee', () => {
-        // A fee of exactly 0 short-circuits; the smallest fee that does not
-        // must still agree with the round trip to well under a basis point.
-        const gross = 0.22;
-        const net = netEffectiveApy(gross, 0.01);
-        expect(net).toBeLessThan(gross);
-        expect(gross - net).toBeLessThan(0.0005);
-    });
-});

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

@@ -1,96 +0,0 @@
-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 }),
-            );
-        }
-    });
-});