@kasufinance/kasu-sdk 2.4.2 → 2.5.0

package/dist/domain/pools.js

@@ -0,0 +1,134 @@
+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) {
+    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) {
+    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) {
+    return tranches !== null && tranches !== void 0 ? tranches : [];
+}
+/**
+ * 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) {
+    if (!(pools === null || pools === void 0 ? void 0 : pools.length))
+        return null;
+    let best = 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, feePercent) {
+    if (!(pools === null || pools === void 0 ? void 0 : 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;
+}
+//# sourceMappingURL=pools.js.map

package/dist/domain/pools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pools.js","sourceRoot":"","sources":["../../src/domain/pools.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAC1C,OAAO,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAEhD;;;GAGG;AACH,MAAM,UAAU,UAAU,CAAC,IAAkB;IACzC,IAAI,EAAE,GAAG,CAAC,CAAC;IACX,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;QAC5B,MAAM,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;QAC/B,IAAI,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE;YAAE,EAAE,GAAG,CAAC,CAAC;IAC7C,CAAC;IACD,OAAO,EAAE,CAAC;AACd,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,kBAAkB,CAAC,GAAmB;IAClD,MAAM,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,IAAI,CAAC,CAAC,CAAC,gBAAgB,CAAC,CAAC;IACpE,OAAO,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE;QACxB,MAAM,IAAI,GAAG,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,kBAAkB,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QACzD,MAAM,IAAI,GAAG,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,kBAAkB,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QACzD,IAAI,IAAI,KAAK,IAAI;YAAE,OAAO,IAAI,GAAG,IAAI,CAAC;QACtC,OAAO,UAAU,CAAC,CAAC,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC,CAAC;IACzC,CAAC,CAAC,CAAC;AACP,CAAC;AAED,4EAA4E;AAC5E,2EAA2E;AAC3E,wEAAwE;AACxE,6BAA6B;AAC7B,SAAS,UAAU,CAAC,QAAmC;IACnD,OAAO,QAAQ,aAAR,QAAQ,cAAR,QAAQ,GAAI,EAAE,CAAC;AAC1B,CAAC;AASD;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,uBAAuB,CACnC,KAA6B;IAE7B,IAAI,CAAC,CAAA,KAAK,aAAL,KAAK,uBAAL,KAAK,CAAE,MAAM,CAAA;QAAE,OAAO,IAAI,CAAC;IAEhC,IAAI,IAAI,GAAuB,IAAI,CAAC;IAEpC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACvB,KAAK,MAAM,OAAO,IAAI,UAAU,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC;YAC9C,IAAI,CAAC,kBAAkB,CAAC,OAAO,CAAC;gBAAE,SAAS;YAE3C,MAAM,GAAG,GAAG,UAAU,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;YACpC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,GAAG,IAAI,CAAC;gBAAE,SAAS;YAEhD,IAAI,CAAC,IAAI,EAAE,CAAC;gBACR,IAAI,GAAG,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC;gBAC9B,SAAS;YACb,CAAC;YAED,MAAM,QAAQ,GAAG,UAAU,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC;YAClD,MAAM,YAAY,GAAG,UAAU,CAAC,IAAI,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC;YAC3D,IAAI,GAAG,GAAG,IAAI,CAAC,GAAG,IAAI,CAAC,GAAG,KAAK,IAAI,CAAC,GAAG,IAAI,QAAQ,GAAG,YAAY,CAAC,EAAE,CAAC;gBAClE,IAAI,GAAG,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC;YAClC,CAAC;QACL,CAAC;IACL,CAAC;IAED,OAAO,IAAI,CAAC;AAChB,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,UAAU,iBAAiB,CAC7B,KAAwC,EACxC,UAAkB;IAElB,IAAI,CAAC,CAAA,KAAK,aAAL,KAAK,uBAAL,KAAK,CAAE,MAAM,CAAA;QAAE,OAAO,IAAI,CAAC;IAEhC,IAAI,OAAO,GAAG,CAAC,CAAC;IAChB,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACvB,KAAK,MAAM,OAAO,IAAI,UAAU,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC;YAC9C,IAAI,CAAC,kBAAkB,CAAC,OAAO,CAAC;gBAAE,SAAS;YAC3C,KAAK,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;gBAC9C,MAAM,GAAG,GAAG,UAAU,CAAC,GAAG,CAAC,CAAC;gBAC5B,IAAI,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,GAAG,GAAG,OAAO;oBAAE,OAAO,GAAG,GAAG,CAAC;YAC7D,CAAC;QACL,CAAC;IACL,CAAC;IACD,IAAI,OAAO,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IAE9B,MAAM,IAAI,GAAG,eAAe,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC;IAClD,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IACrD,OAAO,IAAI,CAAC;AAChB,CAAC"}

package/dist/domain/pools.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/domain/pools.test.js

@@ -0,0 +1,184 @@
+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, apy, poolCapacity, maxApy) {
+    return { id: name, name, apy, poolCapacity, maxApy };
+}
+function pool(over) {
+    return Object.assign({ id: 'p', poolName: 'p', isActive: true, isOversubscribed: false, tranches: [tranche('Senior', '0.09', '250000', '0.10')] }, over);
+}
+const withCapacity = () => [
+    tranche('Senior', '0.09', '250000', '0.10'),
+];
+const noCapacity = () => [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, tranches) => 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 === null || best === void 0 ? void 0 : best.pool.poolName).toBe('B');
+        expect(best === null || best === void 0 ? void 0 : best.tranche.name).toBe('Senior');
+        expect(best === null || best === void 0 ? void 0 : 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 === null || best === void 0 ? void 0 : best.pool.poolName).toBe('Live');
+        expect(best === null || best === void 0 ? void 0 : 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 === null || best === void 0 ? void 0 : 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 === null || best === void 0 ? void 0 : 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 === null || best === void 0 ? void 0 : best.pool.poolName).toBe('B');
+    });
+});
+describe('maxNetRateCeiling', () => {
+    const named = (poolName, tranches) => 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));
+    });
+});
+//# sourceMappingURL=pools.test.js.map

package/dist/domain/pools.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pools.test.js","sourceRoot":"","sources":["../../src/domain/pools.test.ts"],"names":[],"mappings":"AAEA,OAAO,EACH,iBAAiB,EACjB,uBAAuB,EACvB,UAAU,EACV,kBAAkB,GACrB,MAAM,SAAS,CAAC;AACjB,OAAO,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAE1C;;;;;GAKG;AAEH,SAAS,OAAO,CACZ,IAAY,EACZ,GAAW,EACX,YAAoB,EACpB,MAAe;IAEf,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,EAAE,YAAY,EAAE,MAAM,EAA4B,CAAC;AACnF,CAAC;AAED,SAAS,IAAI,CAAC,IAA2B;IACrC,OAAO,gBACH,EAAE,EAAE,GAAG,EACP,QAAQ,EAAE,GAAG,EACb,QAAQ,EAAE,IAAI,EACd,gBAAgB,EAAE,KAAK,EACvB,QAAQ,EAAE,CAAC,OAAO,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,CAAC,CAAC,IACpD,IAAI,CACiB,CAAC;AACjC,CAAC;AAED,MAAM,YAAY,GAAG,GAAkB,EAAE,CAAC;IACtC,OAAO,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,CAAC;CAC9C,CAAC;AACF,MAAM,UAAU,GAAG,GAAkB,EAAE,CAAC,CAAC,OAAO,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,CAAC,CAAC,CAAC;AAEjF,mDAAmD;AACnD,MAAM,GAAG,GAAG,EAAE,CAAC;AAEf,QAAQ,CAAC,YAAY,EAAE,GAAG,EAAE;IACxB,EAAE,CAAC,iDAAiD,EAAE,GAAG,EAAE;QACvD,MAAM,CACF,UAAU,CACN,IAAI,CAAC;YACD,QAAQ,EAAE;gBACN,OAAO,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,CAAC;gBACtC,OAAO,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,CAAC;aACzC;SACJ,CAAC,CACL,CACJ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACjB,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,6BAA6B,EAAE,GAAG,EAAE;QACnC,MAAM,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QACnD,MAAM,CACF,UAAU,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,CAAC,OAAO,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,CACxE,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACd,CAAC,CAAC,CAAC;AACP,CAAC,CAAC,CAAC;AAEH,QAAQ,CAAC,oBAAoB,EAAE,GAAG,EAAE;IAChC,EAAE,CAAC,sBAAsB,EAAE,GAAG,EAAE;QAC5B,MAAM,KAAK,GAAG;YACV,IAAI,CAAC,EAAE,EAAE,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;YACtC,IAAI,CAAC,EAAE,EAAE,EAAE,UAAU,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC;SAC5C,CAAC;QACF,MAAM,CAAC,kBAAkB,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC;IAC3E,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,4BAA4B,EAAE,GAAG,EAAE;QAClC,MAAM,KAAK,GAAG;YACV,IAAI,CAAC,EAAE,EAAE,EAAE,MAAM,EAAE,gBAAgB,EAAE,KAAK,EAAE,CAAC;YAC7C,IAAI,CAAC,EAAE,EAAE,EAAE,MAAM,EAAE,gBAAgB,EAAE,IAAI,EAAE,CAAC;SAC/C,CAAC;QACF,MAAM,CAAC,kBAAkB,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC;IACzE,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,kDAAkD,EAAE,GAAG,EAAE;QACxD,MAAM,KAAK,GAAG;YACV,IAAI,CAAC,EAAE,EAAE,EAAE,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,EAAE,CAAC;YAC7C,IAAI,CAAC,EAAE,EAAE,EAAE,SAAS,EAAE,QAAQ,EAAE,YAAY,EAAE,EAAE,CAAC;SACpD,CAAC;QACF,MAAM,CAAC,kBAAkB,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC;YACvD,SAAS;YACT,OAAO;SACV,CAAC,CAAC;IACP,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,0DAA0D,EAAE,GAAG,EAAE;QAChE,MAAM,KAAK,GAAG;YACV,IAAI,CAAC;gBACD,EAAE,EAAE,KAAK;gBACT,QAAQ,EAAE,CAAC,OAAO,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,CAAC,CAAC;aAC1D,CAAC;YACF,IAAI,CAAC;gBACD,EAAE,EAAE,MAAM;gBACV,QAAQ,EAAE,CAAC,OAAO,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,CAAC,CAAC;aAC1D,CAAC;SACL,CAAC;QACF,MAAM,CAAC,kBAAkB,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC;YACvD,MAAM;YACN,KAAK;SACR,CAAC,CAAC;IACP,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,iCAAiC,EAAE,GAAG,EAAE;QACvC,MAAM,KAAK,GAAG;YACV,IAAI,CAAC,EAAE,EAAE,EAAE,GAAG,EAAE,QAAQ,EAAE,UAAU,EAAE,EAAE,CAAC;YACzC,IAAI,CAAC,EAAE,EAAE,EAAE,GAAG,EAAE,QAAQ,EAAE,YAAY,EAAE,EAAE,CAAC;SAC9C,CAAC;QACF,MAAM,MAAM,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;QACtC,kBAAkB,CAAC,KAAK,CAAC,CAAC;QAC1B,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IACnD,CAAC,CAAC,CAAC;AACP,CAAC,CAAC,CAAC;AAEH,QAAQ,CAAC,yBAAyB,EAAE,GAAG,EAAE;IACrC,MAAM,KAAK,GAAG,CAAC,QAAgB,EAAE,QAAuB,EAAgB,EAAE,CACtE,IAAI,CAAC,EAAE,EAAE,EAAE,QAAQ,EAAE,QAAQ,EAAE,QAAQ,EAAE,CAAC,CAAC;IAE/C,EAAE,CAAC,wCAAwC,EAAE,GAAG,EAAE;QAC9C,MAAM,CAAC,uBAAuB,CAAC,SAAS,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC;QACtD,MAAM,CAAC,uBAAuB,CAAC,IAAI,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC;QACjD,MAAM,CAAC,uBAAuB,CAAC,EAAE,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC;IACnD,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,2DAA2D,EAAE,GAAG,EAAE;QACjE,MAAM,IAAI,GAAG,uBAAuB,CAAC;YACjC,KAAK,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;YAC/C,KAAK,CAAC,GAAG,EAAE;gBACP,OAAO,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC;gBACjC,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC;aAClC,CAAC;SACL,CAAC,CAAC;QACH,MAAM,CAAC,IAAI,aAAJ,IAAI,uBAAJ,IAAI,CAAE,IAAI,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACtC,MAAM,CAAC,IAAI,aAAJ,IAAI,uBAAJ,IAAI,CAAE,OAAO,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QAC1C,MAAM,CAAC,IAAI,aAAJ,IAAI,uBAAJ,IAAI,CAAE,GAAG,CAAC,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC;IACxC,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,4CAA4C,EAAE,GAAG,EAAE;QAClD,MAAM,IAAI,GAAG,uBAAuB,CAAC;YACjC,KAAK,CAAC,MAAM,EAAE,CAAC,OAAO,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC;YAC/C,KAAK,CAAC,MAAM,EAAE,CAAC,OAAO,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;SACrD,CAAC,CAAC;QACH,MAAM,CAAC,IAAI,aAAJ,IAAI,uBAAJ,IAAI,CAAE,IAAI,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QACzC,MAAM,CAAC,IAAI,aAAJ,IAAI,uBAAJ,IAAI,CAAE,GAAG,CAAC,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;IACvC,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,gDAAgD,EAAE,GAAG,EAAE;QACtD,MAAM,IAAI,GAAG,uBAAuB,CAAC;YACjC,KAAK,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;YACnD,KAAK,CAAC,KAAK,EAAE,CAAC,OAAO,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;SACpD,CAAC,CAAC;QACH,MAAM,CAAC,IAAI,aAAJ,IAAI,uBAAJ,IAAI,CAAE,IAAI,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAC5C,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,sCAAsC,EAAE,GAAG,EAAE;QAC5C,MAAM,IAAI,GAAG,uBAAuB,CAAC;YACjC,KAAK,CAAC,MAAM,EAAE,CAAC,OAAO,CAAC,QAAQ,EAAE,GAAG,EAAE,MAAM,CAAC,CAAC,CAAC;YAC/C,KAAK,CAAC,KAAK,EAAE,CAAC,OAAO,CAAC,QAAQ,EAAE,cAAc,EAAE,MAAM,CAAC,CAAC,CAAC;YACzD,KAAK,CAAC,MAAM,EAAE,CAAC,OAAO,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;SACrD,CAAC,CAAC;QACH,MAAM,CAAC,IAAI,aAAJ,IAAI,uBAAJ,IAAI,CAAE,IAAI,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IAC7C,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,iDAAiD,EAAE,GAAG,EAAE;QACvD,uEAAuE;QACvE,MAAM,IAAI,GAAG,uBAAuB,CAAC;YACjC,KAAK,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;YACvD,KAAK,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;SAC1D,CAAC,CAAC;QACH,MAAM,CAAC,IAAI,aAAJ,IAAI,uBAAJ,IAAI,CAAE,IAAI,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAC1C,CAAC,CAAC,CAAC;AACP,CAAC,CAAC,CAAC;AAEH,QAAQ,CAAC,mBAAmB,EAAE,GAAG,EAAE;IAC/B,MAAM,KAAK,GAAG,CAAC,QAAgB,EAAE,QAAuB,EAAgB,EAAE,CACtE,IAAI,CAAC,EAAE,EAAE,EAAE,QAAQ,EAAE,QAAQ,EAAE,QAAQ,EAAE,CAAC,CAAC;IAE/C,EAAE,CAAC,8DAA8D,EAAE,GAAG,EAAE;QACpE,MAAM,IAAI,GAAG,iBAAiB,CAC1B;YACI,KAAK,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;YACvD,KAAK,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;SAC1D,EACD,GAAG,CACN,CAAC;QACF,mEAAmE;QACnE,MAAM,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,eAAe,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC,CAAC;QAC9C,MAAM,CAAC,IAAI,CAAC,CAAC,WAAW,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;IACvC,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,qDAAqD,EAAE,GAAG,EAAE;QAC3D,mEAAmE;QACnE,gEAAgE;QAChE,MAAM,CACF,iBAAiB,CACb,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,EACzD,GAAG,CACN,CACJ,CAAC,IAAI,CAAC,eAAe,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC,CAAC;IACvC,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,8DAA8D,EAAE,GAAG,EAAE;QACpE,MAAM,CACF,iBAAiB,CACb,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,EACjD,GAAG,CACN,CACJ,CAAC,IAAI,CAAC,eAAe,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC,CAAC;IACvC,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,sEAAsE,EAAE,GAAG,EAAE;QAC5E,MAAM,IAAI,GAAG,iBAAiB,CAC1B;YACI,KAAK,CAAC,MAAM,EAAE,CAAC,OAAO,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,CAAC,CAAC,CAAC;YACvD,KAAK,CAAC,MAAM,EAAE,CAAC,OAAO,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;SAC7D,EACD,GAAG,CACN,CAAC;QACF,MAAM,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,eAAe,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC;QAC7C,MAAM,CAAC,IAAI,CAAC,CAAC,WAAW,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;IACxC,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,uEAAuE,EAAE,GAAG,EAAE;QAC7E,MAAM,KAAK,GAAG,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;QACxE,MAAM,CAAC,iBAAiB,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC;QAClD,MAAM,CAAC,iBAAiB,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC;QAChD,MAAM,CAAC,iBAAiB,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC;QACjD,sCAAsC;QACtC,MAAM,CAAC,iBAAiB,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC;IACrD,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,oDAAoD,EAAE,GAAG,EAAE;QAC1D,MAAM,CAAC,iBAAiB,CAAC,SAAS,EAAE,GAAG,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC;QACrD,MAAM,CAAC,iBAAiB,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC;QAChD,MAAM,CAAC,iBAAiB,CAAC,EAAE,EAAE,GAAG,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC;QAC9C,MAAM,CACF,iBAAiB,CACb,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC,OAAO,CAAC,QAAQ,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,EACtD,GAAG,CACN,CACJ,CAAC,QAAQ,EAAE,CAAC;IACjB,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,gEAAgE,EAAE,GAAG,EAAE;QACtE,oEAAoE;QACpE,MAAM,QAAQ,GAAG,CAAC,OAAO,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;QAC7D,MAAM,CAAC,iBAAiB,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC,IAAI,CACvD,eAAe,CAAC,IAAI,EAAE,GAAG,CAAC,CAC7B,CAAC;IACN,CAAC,CAAC,CAAC;AACP,CAAC,CAAC,CAAC"}

package/dist/domain/rates.d.ts

@@ -0,0 +1,83 @@
+/**
+ * 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 declare 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 declare function epochRateToApy(epochRate: number): number;
+/**
+ * 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 declare function apyToEpochRate(apy: number): number;
+/**
+ * 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 declare function netEffectiveApy(grossApy: number, feePercent: number): number;

package/dist/domain/rates.js

@@ -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) {
+    return Math.pow((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) {
+    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, feePercent) {
+    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);
+}
+//# sourceMappingURL=rates.js.map

package/dist/domain/rates.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rates.js","sourceRoot":"","sources":["../../src/domain/rates.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,QAAQ,CAAC;AAEvC;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,cAAc,CAAC,SAAiB;IAC5C,OAAO,SAAA,CAAC,CAAC,GAAG,SAAS,CAAC,EAAI,cAAc,CAAA,GAAG,CAAC,CAAC;AACjD,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,cAAc,CAAC,GAAW;IACtC,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,cAAc,CAAC,CAAC;AACxD,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,MAAM,UAAU,eAAe,CAAC,QAAgB,EAAE,UAAkB;IAChE,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,QAAQ,GAAG,CAAC;QAAE,OAAO,GAAG,CAAC;IAC3D,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,UAAU,CAAC,IAAI,UAAU,GAAG,CAAC,IAAI,UAAU,GAAG,GAAG,EAAE,CAAC;QACrE,OAAO,GAAG,CAAC;IACf,CAAC;IACD,2EAA2E;IAC3E,wEAAwE;IACxE,wEAAwE;IACxE,wEAAwE;IACxE,0EAA0E;IAC1E,iEAAiE;IACjE,yEAAyE;IACzE,iEAAiE;IACjE,MAAM,WAAW,GAAG,CAAC,GAAG,UAAU,GAAG,GAAG,CAAC;IACzC,IAAI,WAAW,KAAK,CAAC;QAAE,OAAO,QAAQ,CAAC;IACvC,4EAA4E;IAC5E,0EAA0E;IAC1E,4EAA4E;IAC5E,uEAAuE;IACvE,0EAA0E;IAC1E,sDAAsD;IACtD,MAAM,cAAc,GAAG,cAAc,CAAC,QAAQ,CAAC,CAAC;IAChD,MAAM,YAAY,GAAG,cAAc,GAAG,WAAW,CAAC;IAClD,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,cAAc,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC,CAAC;IAClE,wEAAwE;IACxE,wEAAwE;IACxE,0EAA0E;IAC1E,uEAAuE;IACvE,sEAAsE;IACtE,OAAO,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC;AACnC,CAAC"}

package/dist/domain/rates.test.d.ts

@@ -0,0 +1 @@
+export {};