@kasufinance/kasu-sdk 2.4.2 → 2.5.0

package/dist/domain/rates.test.js

@@ -0,0 +1,181 @@
+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 = [
+    { 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 * (Math.pow(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: 10000 })
+    .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(Math.pow((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);
+    });
+});
+//# sourceMappingURL=rates.test.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"rates.test.js","sourceRoot":"","sources":["../../src/domain/rates.test.ts"],"names":[],"mappings":"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"}

package/dist/domain/tranche-display-name.d.ts

@@ -0,0 +1,17 @@
+import { PoolNameSignal } from './partners';
+export declare const UPPER_MEZZANINE = "Upper Mezzanine";
+/**
+ * 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 declare function getTrancheDisplayName(trancheName: string, pool: PoolNameSignal): string;

package/dist/domain/tranche-display-name.js

@@ -0,0 +1,30 @@
+import { APXIUM, getCreditOriginator } 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, pool) {
+    if (trancheName.trim().toLowerCase() !== SENIOR)
+        return trancheName;
+    return getCreditOriginator(pool).name === APXIUM.name
+        ? UPPER_MEZZANINE
+        : trancheName;
+}
+//# sourceMappingURL=tranche-display-name.js.map

package/dist/domain/tranche-display-name.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tranche-display-name.js","sourceRoot":"","sources":["../../src/domain/tranche-display-name.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,mBAAmB,EAAkB,MAAM,YAAY,CAAC;AAEzE,+EAA+E;AAC/E,+EAA+E;AAC/E,6EAA6E;AAC7E,mEAAmE;AACnE,2DAA2D;AAC3D,MAAM,CAAC,MAAM,eAAe,GAAG,iBAAiB,CAAC;AAEjD,MAAM,MAAM,GAAG,QAAQ,CAAC;AAExB;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,qBAAqB,CACjC,WAAmB,EACnB,IAAoB;IAEpB,IAAI,WAAW,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,KAAK,MAAM;QAAE,OAAO,WAAW,CAAC;IACpE,OAAO,mBAAmB,CAAC,IAAI,CAAC,CAAC,IAAI,KAAK,MAAM,CAAC,IAAI;QACjD,CAAC,CAAC,eAAe;QACjB,CAAC,CAAC,WAAW,CAAC;AACtB,CAAC"}

package/dist/domain/tranche-display-name.test.d.ts

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

package/dist/domain/tranche-display-name.test.js

@@ -0,0 +1,58 @@
+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 }));
+        }
+    });
+});
+//# sourceMappingURL=tranche-display-name.test.js.map

package/dist/domain/tranche-display-name.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tranche-display-name.test.js","sourceRoot":"","sources":["../../src/domain/tranche-display-name.test.ts"],"names":[],"mappings":"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"}

package/dist/domain/tranches.d.ts

@@ -0,0 +1,89 @@
+import { PoolOverview, TrancheData } from '../services/DataService/types';
+/**
+ * Minimum remaining capacity (in stable-asset units) for a tranche to be
+ * selectable. Mirrors `MIN_CAPACITY = toBigNumber('1')` in kasu-fe-next's
+ * lending modal after its `formatEther`. Anything below this is rounding
+ * noise — the SDK's own capacity arithmetic routinely leaves sub-cent dust
+ * behind.
+ */
+export declare const MIN_TRANCHE_CAPACITY = 1;
+/**
+ * Remaining capacity as it reaches this layer. `TrancheData` (raw, from the
+ * data service) calls it `poolCapacity`; the facade's `StrategyTranche` calls
+ * the same number `availableCapacity`. Accepting both keeps ONE capacity gate
+ * for the whole SDK rather than a duplicate per shape.
+ */
+export type TrancheCapacitySignal = {
+    poolCapacity: string;
+} | {
+    availableCapacity: string;
+};
+export declare function trancheHasCapacity(tranche: TrancheCapacitySignal): boolean;
+/**
+ * Whole-strategy capacity gate: true when the pool has tranches but none of
+ * them has remaining capacity. Drives a lend form's full-capacity message and
+ * its step-counter suppression.
+ */
+export declare function poolAllTranchesFull(pool: PoolOverview): boolean;
+export type PoolStatus = 'Live' | 'Full' | 'Coming soon';
+/**
+ * The status CODE for a pool. A code, not copy: consumers map it to their own
+ * wording and locale.
+ */
+export declare function derivePoolStatus(pool: PoolOverview): PoolStatus;
+export declare function trancheRiskRank(tranche: TrancheData): number;
+/**
+ * Comparator that orders tranches SAFEST-FIRST (Senior → Mezzanine → Junior)
+ * by the same name-based risk rank the default-pick uses. Ranks by the RAW
+ * subgraph name, so the Apxium "Upper Mezzanine" display rename never reaches
+ * here. Ties (incl. unrecognised names, which both rank last) keep their input
+ * order under a stable sort. Used by a lend dropdown to list the least-risky
+ * option first.
+ */
+export declare function compareTrancheSeniority(a: TrancheData, b: TrancheData): number;
+/**
+ * Capacity-aware default tranche pick: the LOWEST-risk tranche that still has
+ * capacity, so a new lender lands on the safest available option. Riskier
+ * tranches remain a deliberate opt-in — we must never pre-select the
+ * highest-risk Junior (audit 3.2). When every tranche is full we fall back to
+ * the lowest-risk one regardless, so a form still mounts in a known state
+ * (the dropdown marks it full and the submit gate blocks progress).
+ */
+export declare function pickDefaultTrancheId(pool: PoolOverview): string;
+/** A closed APY range, both bounds as 0..1 fractions. */
+export interface ApyBounds {
+    min: number;
+    max: number;
+}
+/**
+ * GROSS APY range across a pool's tranches — the numeric core of kasu-ui's
+ * `formatTrancheApyRange`. Each `TrancheData` carries `minApy`/`maxApy`
+ * derived from the base rate plus any fixed-term configs (`data-service.ts`).
+ *
+ * Zero and negative values are skipped — an unset/missing rate (e.g. a tranche
+ * with no fixed-term config) must not drag the range down to `0–10.5%`.
+ * `null` when nothing usable remains, which is the caller's cue to render its
+ * "no rate" state rather than a confident zero.
+ *
+ * The min is taken over `minApy` and the max over `maxApy`, so a single
+ * unusable side collapses the whole range to `null` rather than half a range.
+ *
+ * Formatting is NOT here. The rule that two bounds printing the same figure
+ * collapse to one is decided on the rendered digits, so it belongs with the
+ * formatter that produces them (kasu-ui `format-tranche-apy.ts`).
+ */
+export declare function trancheApyBounds(tranches: TrancheData[]): ApyBounds | null;
+/**
+ * The same range as NET Effective Interest Rates — each bound through
+ * `netEffectiveApy`.
+ *
+ * FAIL CLOSED: `null` when either bound comes back non-finite or ≤ 0, so an
+ * out-of-domain fee or a rate-less pool can never be rendered as a confident
+ * figure. A caller that does not yet know the fee must not substitute `0` —
+ * a fee-less rate overstates the figure by up to 3.4pp with nothing on screen
+ * saying so; it should skip the call and render its unavailable state.
+ *
+ * @param feePercent the chain's performance fee, 0..100 — never a fraction.
+ *   See `netEffectiveApy` for why the units matter.
+ */
+export declare function netTrancheApyBounds(tranches: TrancheData[], feePercent: number): ApyBounds | null;

package/dist/domain/tranches.js

@@ -0,0 +1,150 @@
+import { netEffectiveApy } from './rates';
+/**
+ * Minimum remaining capacity (in stable-asset units) for a tranche to be
+ * selectable. Mirrors `MIN_CAPACITY = toBigNumber('1')` in kasu-fe-next's
+ * lending modal after its `formatEther`. Anything below this is rounding
+ * noise — the SDK's own capacity arithmetic routinely leaves sub-cent dust
+ * behind.
+ */
+export const MIN_TRANCHE_CAPACITY = 1;
+export function trancheHasCapacity(tranche) {
+    const raw = 'poolCapacity' in tranche
+        ? tranche.poolCapacity
+        : tranche.availableCapacity;
+    const remaining = parseFloat(raw);
+    return Number.isFinite(remaining) && remaining >= MIN_TRANCHE_CAPACITY;
+}
+/**
+ * Whole-strategy capacity gate: true when the pool has tranches but none of
+ * them has remaining capacity. Drives a lend form's full-capacity message and
+ * its step-counter suppression.
+ */
+export function poolAllTranchesFull(pool) {
+    return pool.tranches.length > 0 && !pool.tranches.some(trancheHasCapacity);
+}
+/**
+ * The status CODE for a pool. A code, not copy: consumers map it to their own
+ * wording and locale.
+ */
+export function derivePoolStatus(pool) {
+    if (!pool.enabled)
+        return 'Coming soon';
+    if (poolAllTranchesFull(pool))
+        return 'Full';
+    return 'Live';
+}
+/**
+ * Seniority rank of a tranche by name — LOWER is less risky. The credit
+ * waterfall is Senior (repaid first, lowest risk) → Mezzanine → Junior
+ * (repaid last, highest risk). APY is NOT a reliable proxy (a pool can price
+ * its Senior tranche above its Mezzanine), so risk is ranked by name.
+ * Unrecognised names sort last, so a known-safe tranche always wins the
+ * default. Ranks by the RAW subgraph name — the Apxium "Upper Mezzanine"
+ * rename is display-only and must never reach here (see
+ * `tranche-display-name.ts`).
+ */
+const TRANCHE_RISK_RANK = {
+    senior: 0,
+    mezzanine: 1,
+    junior: 2,
+};
+// `name` is typed `string` on `TrancheData` but arrives from the subgraph, so
+// it is taken as possibly missing here: an unnamed tranche ranks last rather
+// than throwing on `.trim()`.
+function riskRankOfName(name) {
+    var _a, _b;
+    return ((_b = TRANCHE_RISK_RANK[(_a = name === null || name === void 0 ? void 0 : name.trim().toLowerCase()) !== null && _a !== void 0 ? _a : '']) !== null && _b !== void 0 ? _b : Number.POSITIVE_INFINITY);
+}
+export function trancheRiskRank(tranche) {
+    return riskRankOfName(tranche.name);
+}
+/**
+ * Comparator that orders tranches SAFEST-FIRST (Senior → Mezzanine → Junior)
+ * by the same name-based risk rank the default-pick uses. Ranks by the RAW
+ * subgraph name, so the Apxium "Upper Mezzanine" display rename never reaches
+ * here. Ties (incl. unrecognised names, which both rank last) keep their input
+ * order under a stable sort. Used by a lend dropdown to list the least-risky
+ * option first.
+ */
+export function compareTrancheSeniority(a, b) {
+    const ra = trancheRiskRank(a);
+    const rb = trancheRiskRank(b);
+    if (ra === rb)
+        return 0;
+    return ra < rb ? -1 : 1;
+}
+/**
+ * Capacity-aware default tranche pick: the LOWEST-risk tranche that still has
+ * capacity, so a new lender lands on the safest available option. Riskier
+ * tranches remain a deliberate opt-in — we must never pre-select the
+ * highest-risk Junior (audit 3.2). When every tranche is full we fall back to
+ * the lowest-risk one regardless, so a form still mounts in a known state
+ * (the dropdown marks it full and the submit gate blocks progress).
+ */
+export function pickDefaultTrancheId(pool) {
+    const withCapacity = pool.tranches.filter(trancheHasCapacity);
+    const candidates = withCapacity.length > 0 ? withCapacity : pool.tranches;
+    if (candidates.length === 0)
+        return '';
+    return candidates.reduce((best, t) => trancheRiskRank(t) < trancheRiskRank(best) ? t : best).id;
+}
+/**
+ * GROSS APY range across a pool's tranches — the numeric core of kasu-ui's
+ * `formatTrancheApyRange`. Each `TrancheData` carries `minApy`/`maxApy`
+ * derived from the base rate plus any fixed-term configs (`data-service.ts`).
+ *
+ * Zero and negative values are skipped — an unset/missing rate (e.g. a tranche
+ * with no fixed-term config) must not drag the range down to `0–10.5%`.
+ * `null` when nothing usable remains, which is the caller's cue to render its
+ * "no rate" state rather than a confident zero.
+ *
+ * The min is taken over `minApy` and the max over `maxApy`, so a single
+ * unusable side collapses the whole range to `null` rather than half a range.
+ *
+ * Formatting is NOT here. The rule that two bounds printing the same figure
+ * collapse to one is decided on the rendered digits, so it belongs with the
+ * formatter that produces them (kasu-ui `format-tranche-apy.ts`).
+ */
+export function trancheApyBounds(tranches) {
+    if (tranches.length === 0)
+        return null;
+    let lo = Number.POSITIVE_INFINITY;
+    let hi = Number.NEGATIVE_INFINITY;
+    for (const t of tranches) {
+        const min = parseFloat(t.minApy);
+        const max = parseFloat(t.maxApy);
+        if (Number.isFinite(min) && min > 0)
+            lo = Math.min(lo, min);
+        if (Number.isFinite(max) && max > 0)
+            hi = Math.max(hi, max);
+    }
+    if (!Number.isFinite(lo) || !Number.isFinite(hi))
+        return null;
+    return { min: lo, max: hi };
+}
+/**
+ * The same range as NET Effective Interest Rates — each bound through
+ * `netEffectiveApy`.
+ *
+ * FAIL CLOSED: `null` when either bound comes back non-finite or ≤ 0, so an
+ * out-of-domain fee or a rate-less pool can never be rendered as a confident
+ * figure. A caller that does not yet know the fee must not substitute `0` —
+ * a fee-less rate overstates the figure by up to 3.4pp with nothing on screen
+ * saying so; it should skip the call and render its unavailable state.
+ *
+ * @param feePercent the chain's performance fee, 0..100 — never a fraction.
+ *   See `netEffectiveApy` for why the units matter.
+ */
+export function netTrancheApyBounds(tranches, feePercent) {
+    const gross = trancheApyBounds(tranches);
+    if (!gross)
+        return null;
+    const min = netEffectiveApy(gross.min, feePercent);
+    const max = netEffectiveApy(gross.max, feePercent);
+    if (!Number.isFinite(min) || min <= 0)
+        return null;
+    if (!Number.isFinite(max) || max <= 0)
+        return null;
+    return { min, max };
+}
+//# sourceMappingURL=tranches.js.map

package/dist/domain/tranches.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tranches.js","sourceRoot":"","sources":["../../src/domain/tranches.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAE1C;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,CAAC;AAYtC,MAAM,UAAU,kBAAkB,CAAC,OAA8B;IAC7D,MAAM,GAAG,GACL,cAAc,IAAI,OAAO;QACrB,CAAC,CAAC,OAAO,CAAC,YAAY;QACtB,CAAC,CAAC,OAAO,CAAC,iBAAiB,CAAC;IACpC,MAAM,SAAS,GAAG,UAAU,CAAC,GAAG,CAAC,CAAC;IAClC,OAAO,MAAM,CAAC,QAAQ,CAAC,SAAS,CAAC,IAAI,SAAS,IAAI,oBAAoB,CAAC;AAC3E,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,mBAAmB,CAAC,IAAkB;IAClD,OAAO,IAAI,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,kBAAkB,CAAC,CAAC;AAC/E,CAAC;AAID;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAAkB;IAC/C,IAAI,CAAC,IAAI,CAAC,OAAO;QAAE,OAAO,aAAa,CAAC;IACxC,IAAI,mBAAmB,CAAC,IAAI,CAAC;QAAE,OAAO,MAAM,CAAC;IAC7C,OAAO,MAAM,CAAC;AAClB,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,iBAAiB,GAAuC;IAC1D,MAAM,EAAE,CAAC;IACT,SAAS,EAAE,CAAC;IACZ,MAAM,EAAE,CAAC;CACZ,CAAC;AAEF,8EAA8E;AAC9E,6EAA6E;AAC7E,8BAA8B;AAC9B,SAAS,cAAc,CAAC,IAAwB;;IAC5C,OAAO,CACH,MAAA,iBAAiB,CAAC,MAAA,IAAI,aAAJ,IAAI,uBAAJ,IAAI,CAAE,IAAI,GAAG,WAAW,EAAE,mCAAI,EAAE,CAAC,mCACnD,MAAM,CAAC,iBAAiB,CAC3B,CAAC;AACN,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,OAAoB;IAChD,OAAO,cAAc,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;AACxC,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,uBAAuB,CAAC,CAAc,EAAE,CAAc;IAClE,MAAM,EAAE,GAAG,eAAe,CAAC,CAAC,CAAC,CAAC;IAC9B,MAAM,EAAE,GAAG,eAAe,CAAC,CAAC,CAAC,CAAC;IAC9B,IAAI,EAAE,KAAK,EAAE;QAAE,OAAO,CAAC,CAAC;IACxB,OAAO,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAC5B,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,oBAAoB,CAAC,IAAkB;IACnD,MAAM,YAAY,GAAG,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,kBAAkB,CAAC,CAAC;IAC9D,MAAM,UAAU,GAAG,YAAY,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC;IAC1E,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IACvC,OAAO,UAAU,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,CAAC,EAAE,EAAE,CACjC,eAAe,CAAC,CAAC,CAAC,GAAG,eAAe,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CACxD,CAAC,EAAE,CAAC;AACT,CAAC;AAQD;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,gBAAgB,CAAC,QAAuB;IACpD,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACvC,IAAI,EAAE,GAAG,MAAM,CAAC,iBAAiB,CAAC;IAClC,IAAI,EAAE,GAAG,MAAM,CAAC,iBAAiB,CAAC;IAClC,KAAK,MAAM,CAAC,IAAI,QAAQ,EAAE,CAAC;QACvB,MAAM,GAAG,GAAG,UAAU,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;QACjC,MAAM,GAAG,GAAG,UAAU,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;QACjC,IAAI,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,GAAG,GAAG,CAAC;YAAE,EAAE,GAAG,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,GAAG,CAAC,CAAC;QAC5D,IAAI,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,GAAG,GAAG,CAAC;YAAE,EAAE,GAAG,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,GAAG,CAAC,CAAC;IAChE,CAAC;IACD,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC;QAAE,OAAO,IAAI,CAAC;IAC9D,OAAO,EAAE,GAAG,EAAE,EAAE,EAAE,GAAG,EAAE,EAAE,EAAE,CAAC;AAChC,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,mBAAmB,CAC/B,QAAuB,EACvB,UAAkB;IAElB,MAAM,KAAK,GAAG,gBAAgB,CAAC,QAAQ,CAAC,CAAC;IACzC,IAAI,CAAC,KAAK;QAAE,OAAO,IAAI,CAAC;IACxB,MAAM,GAAG,GAAG,eAAe,CAAC,KAAK,CAAC,GAAG,EAAE,UAAU,CAAC,CAAC;IACnD,MAAM,GAAG,GAAG,eAAe,CAAC,KAAK,CAAC,GAAG,EAAE,UAAU,CAAC,CAAC;IACnD,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,GAAG,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IACnD,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,GAAG,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IACnD,OAAO,EAAE,GAAG,EAAE,GAAG,EAAE,CAAC;AACxB,CAAC"}

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

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