@kasufinance/kasu-sdk 2.4.2 → 2.5.0

package/src/domain/pools.test.ts

@@ -0,0 +1,260 @@
+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/pools.ts

@@ -0,0 +1,150 @@
+import { PoolOverview, TrancheData } from '../services/DataService/types';
+
+import { netEffectiveApy } from './rates';
+import { trancheHasCapacity } from './tranches';
+
+/**
+ * The highest FTD-inclusive upper bound across a pool's tranches, or `0` when
+ * none is usable. The sort key behind `selectVisiblePools`.
+ */
+export function poolMaxApy(pool: PoolOverview): number {
+    let hi = 0;
+    for (const t of pool.tranches) {
+        const v = parseFloat(t.maxApy);
+        if (Number.isFinite(v) && v > hi) hi = v;
+    }
+    return hi;
+}
+
+/**
+ * A lending grid's visible pool set: *active* and *not yet oversubscribed*
+ * pools, sorted with has-capacity strategies first, then by highest max APY.
+ *
+ * Shared so a server-rendered payload and a client re-fetch can never
+ * disagree — kasu-ui's SSR fetcher and client hook used to carry verbatim
+ * copies of this filter + sort, and any drift surfaced as an SSR→CSR content
+ * flip on the lending page.
+ *
+ * Pure: operates on a fresh array (`filter` output), so the in-place `sort`
+ * does not mutate the caller's input.
+ */
+export function selectVisiblePools(all: PoolOverview[]): PoolOverview[] {
+    const active = all.filter((p) => p.isActive && !p.isOversubscribed);
+    return active.sort((a, b) => {
+        const aHas = a.tranches.some(trancheHasCapacity) ? 1 : 0;
+        const bHas = b.tranches.some(trancheHasCapacity) ? 1 : 0;
+        if (aHas !== bHas) return bHas - aHas;
+        return poolMaxApy(b) - poolMaxApy(a);
+    });
+}
+
+// `tranches` is typed as a required array but arrives from the subgraph, so
+// both scanners below read it as possibly missing — a pool with no tranche
+// list contributes nothing instead of throwing. Mirrors the `?? []` the
+// kasu-ui originals carried.
+function tranchesOf(tranches: TrancheData[] | undefined): TrancheData[] {
+    return tranches ?? [];
+}
+
+export interface BestTranche {
+    pool: PoolOverview;
+    tranche: TrancheData;
+    /** Base variable-rate APY as a decimal fraction (e.g. `0.12`). */
+    apy: number;
+}
+
+/**
+ * The highest-yielding tranche that still has capacity, across all pools.
+ *
+ * Compares `tranche.apy` — the base variable rate — NOT `minApy`/`maxApy`,
+ * which the data service widens with fixed-term-deposit variants. A headline
+ * naming one tranche should advertise the rate every depositor gets, not an
+ * FTD-locked uplift.
+ *
+ * Capacity is gated by the shared `trancheHasCapacity` (≥ 1 stable unit), so
+ * full tranches never win. Ties on APY break toward more remaining capacity.
+ * Returns `null` when no tranche qualifies (empty list, all full, or all rates
+ * unset) — callers fall back to static copy.
+ */
+export function pickHighestYieldTranche(
+    pools?: PoolOverview[] | null,
+): BestTranche | null {
+    if (!pools?.length) return null;
+
+    let best: BestTranche | null = null;
+
+    for (const pool of pools) {
+        for (const tranche of tranchesOf(pool.tranches)) {
+            if (!trancheHasCapacity(tranche)) continue;
+
+            const apy = parseFloat(tranche.apy);
+            if (!Number.isFinite(apy) || apy <= 0) continue;
+
+            if (!best) {
+                best = { pool, tranche, apy };
+                continue;
+            }
+
+            const capacity = parseFloat(tranche.poolCapacity);
+            const bestCapacity = parseFloat(best.tranche.poolCapacity);
+            if (apy > best.apy || (apy === best.apy && capacity > bestCapacity)) {
+                best = { pool, tranche, apy };
+            }
+        }
+    }
+
+    return best;
+}
+
+/**
+ * The highest NET Effective Interest Rate on offer across the pools passed in
+ * — the ceiling behind an "up to …" claim. The numeric core of kasu-ui's
+ * `formatMaxNetRate`.
+ *
+ * `null` when there is nothing to quote, and callers must then DROP the claim
+ * rather than print a placeholder: this feeds text that gets posted publicly.
+ *
+ * Scope follows the caller's pool list, which is normally keyed to one chain —
+ * so a lender on XDC AUDD quotes the AUDD ceiling, not Base's. That is the
+ * intended reading: they are sharing the deployment they are on.
+ *
+ * Reads `maxApy` — the FTD-inclusive upper bound — unlike
+ * `pickHighestYieldTranche` above, which names one tranche's variable rate. A
+ * ceiling claim and a specific tranche's rate are different statements, and
+ * the ceiling must agree with the top of `netTrancheApyBounds`, which reads
+ * the same field. `apy` is taken into the comparison too: `maxApy` is derived
+ * from the base rate plus any fixed-term configs, so it can never be lower,
+ * and a tranche that carries no `maxApy` at all still contributes its base
+ * rate instead of dropping out.
+ *
+ * Capacity-gated by `trancheHasCapacity` — we never advertise a rate no lender
+ * could take up.
+ *
+ * FAIL CLOSED: an out-of-domain fee, or a net rate that is non-finite or ≤ 0,
+ * returns `null`. The gross figure is never a substitute, and a caller that
+ * does not yet know the fee must not pass `0`.
+ *
+ * @param feePercent the chain's performance fee, 0..100 — never a fraction.
+ */
+export function maxNetRateCeiling(
+    pools: PoolOverview[] | undefined | null,
+    feePercent: number,
+): number | null {
+    if (!pools?.length) return null;
+
+    let ceiling = 0;
+    for (const pool of pools) {
+        for (const tranche of tranchesOf(pool.tranches)) {
+            if (!trancheHasCapacity(tranche)) continue;
+            for (const raw of [tranche.maxApy, tranche.apy]) {
+                const apy = parseFloat(raw);
+                if (Number.isFinite(apy) && apy > ceiling) ceiling = apy;
+            }
+        }
+    }
+    if (ceiling <= 0) return null;
+
+    const rate = netEffectiveApy(ceiling, feePercent);
+    if (!Number.isFinite(rate) || rate <= 0) return null;
+    return rate;
+}

package/src/domain/rates.test.ts

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