@kasufinance/kasu-sdk 2.5.0 → 2.7.0

package/src/domain/tranches.test.ts

@@ -1,300 +0,0 @@
-import * as fc from 'fast-check';
-
-import { PoolOverview, TrancheData } from '../services/DataService/types';
-
-import { netEffectiveApy } from './rates';
-import {
-    compareTrancheSeniority,
-    derivePoolStatus,
-    MIN_TRANCHE_CAPACITY,
-    netTrancheApyBounds,
-    pickDefaultTrancheId,
-    poolAllTranchesFull,
-    trancheApyBounds,
-    trancheHasCapacity,
-    trancheRiskRank,
-} from './tranches';
-
-/**
- * Ported from kasu-ui `pick-default-tranche.test.ts` and the NUMERIC half of
- * `format-tranche-apy.range.test.ts`. The formatting cases — whole-percent
- * rendering, the en-dash shape, the locale table and the "collapse when both
- * bounds print the same" rule — stay in kasu-ui: they are decided on rendered
- * digits, which this layer never produces.
- */
-
-// `id === name` keeps assertions readable; `poolCapacity` drives
-// `trancheHasCapacity` (≥ 1 stable unit → selectable).
-function tranche(name: string, poolCapacity: string, apy = '0.12'): TrancheData {
-    return { id: name, name, apy, poolCapacity } as unknown as TrancheData;
-}
-function pool(tranches: TrancheData[], enabled = true): PoolOverview {
-    return { id: 'p', poolName: 'p', enabled, tranches } as unknown as PoolOverview;
-}
-function rated(minApy: string, maxApy: string): TrancheData {
-    return { minApy, maxApy } as unknown as TrancheData;
-}
-
-/** The live performance fee on all deployments (subgraph units: 10 = 10%). */
-const FEE = 10;
-
-describe('trancheHasCapacity', () => {
-    it('accepts a tranche with at least one whole stable unit left', () => {
-        expect(trancheHasCapacity({ poolCapacity: '5000' })).toBe(true);
-        expect(
-            trancheHasCapacity({ poolCapacity: String(MIN_TRANCHE_CAPACITY) }),
-        ).toBe(true);
-    });
-
-    it('rejects sub-unit dust, zero and unparseable capacity', () => {
-        expect(trancheHasCapacity({ poolCapacity: '0.99' })).toBe(false);
-        expect(trancheHasCapacity({ poolCapacity: '0' })).toBe(false);
-        expect(
-            trancheHasCapacity({ poolCapacity: '1.4551915228366852e-11' }),
-        ).toBe(false);
-        expect(trancheHasCapacity({ poolCapacity: '' })).toBe(false);
-        expect(trancheHasCapacity({ poolCapacity: 'not-a-number' })).toBe(false);
-    });
-
-    it('reads the facade tranche shape (availableCapacity) identically', () => {
-        // `StrategyTranche` renames the same number; one gate, both shapes.
-        expect(trancheHasCapacity({ availableCapacity: '5000' })).toBe(true);
-        expect(trancheHasCapacity({ availableCapacity: '0' })).toBe(false);
-    });
-});
-
-describe('trancheRiskRank / compareTrancheSeniority', () => {
-    it('ranks the waterfall safest-first by the RAW name', () => {
-        expect(trancheRiskRank(tranche('Senior', '1'))).toBe(0);
-        expect(trancheRiskRank(tranche('Mezzanine', '1'))).toBe(1);
-        expect(trancheRiskRank(tranche('Junior', '1'))).toBe(2);
-    });
-
-    it('is case- and whitespace-insensitive, and sorts unknown names last', () => {
-        expect(trancheRiskRank(tranche('  SENIOR ', '1'))).toBe(0);
-        expect(trancheRiskRank(tranche('Upper Mezzanine', '1'))).toBe(
-            Number.POSITIVE_INFINITY,
-        );
-    });
-
-    it('sorts Senior → Mezzanine → Junior, keeping ties in input order', () => {
-        const tranches = [
-            tranche('Junior', '5000'),
-            tranche('Tranche B', '5000'),
-            tranche('Senior', '5000'),
-            tranche('Tranche A', '5000'),
-            tranche('Mezzanine', '5000'),
-        ];
-        expect(
-            [...tranches].sort(compareTrancheSeniority).map((t) => t.name),
-        ).toEqual([
-            'Senior',
-            'Mezzanine',
-            'Junior',
-            'Tranche B',
-            'Tranche A',
-        ]);
-    });
-});
-
-describe('pickDefaultTrancheId', () => {
-    it('defaults to the lowest-risk tranche (Senior) when all have capacity', () => {
-        // Subgraph order is Junior → Mezzanine → Senior; the default must NOT
-        // be the highest-risk Junior that sits first (audit 3.2).
-        const id = pickDefaultTrancheId(
-            pool([
-                tranche('Junior', '5000'),
-                tranche('Mezzanine', '5000'),
-                tranche('Senior', '5000'),
-            ]),
-        );
-        expect(id).toBe('Senior');
-    });
-
-    it('picks the lowest-risk tranche that is still AVAILABLE (skips a full Senior)', () => {
-        const id = pickDefaultTrancheId(
-            pool([
-                tranche('Junior', '5000'),
-                tranche('Mezzanine', '5000'),
-                tranche('Senior', '0'),
-            ]),
-        );
-        expect(id).toBe('Mezzanine');
-    });
-
-    it('does not rank by APY — a Senior priced above Mezzanine is still preferred', () => {
-        // Real pools can price Senior above Mezzanine; risk is ranked by name,
-        // not rate.
-        const id = pickDefaultTrancheId(
-            pool([
-                tranche('Mezzanine', '5000', '0.15'),
-                tranche('Senior', '5000', '0.18'),
-            ]),
-        );
-        expect(id).toBe('Senior');
-    });
-
-    it('falls back to the lowest-risk tranche when every tranche is full', () => {
-        const id = pickDefaultTrancheId(
-            pool([tranche('Junior', '0'), tranche('Senior', '0')]),
-        );
-        expect(id).toBe('Senior');
-    });
-
-    it('falls back to the first available tranche when names are unrecognised', () => {
-        const id = pickDefaultTrancheId(
-            pool([tranche('Tranche B', '5000'), tranche('Tranche A', '5000')]),
-        );
-        expect(id).toBe('Tranche B');
-    });
-
-    it('returns an empty string for a pool with no tranches', () => {
-        expect(pickDefaultTrancheId(pool([]))).toBe('');
-    });
-});
-
-describe('poolAllTranchesFull', () => {
-    it('is true when every tranche lacks remaining capacity', () => {
-        expect(
-            poolAllTranchesFull(
-                pool([tranche('Junior', '0'), tranche('Senior', '0')]),
-            ),
-        ).toBe(true);
-    });
-
-    it('is false when at least one tranche still has capacity', () => {
-        expect(
-            poolAllTranchesFull(
-                pool([tranche('Junior', '0'), tranche('Senior', '5000')]),
-            ),
-        ).toBe(false);
-    });
-
-    it('is false for a pool with no tranches (nothing to be full)', () => {
-        expect(poolAllTranchesFull(pool([]))).toBe(false);
-    });
-});
-
-describe('derivePoolStatus', () => {
-    it('is "Coming soon" for a pool that is not yet enabled, full or not', () => {
-        expect(derivePoolStatus(pool([tranche('Senior', '5000')], false))).toBe(
-            'Coming soon',
-        );
-        expect(derivePoolStatus(pool([tranche('Senior', '0')], false))).toBe(
-            'Coming soon',
-        );
-    });
-
-    it('is "Full" for an enabled pool with no capacity anywhere', () => {
-        expect(derivePoolStatus(pool([tranche('Senior', '0')]))).toBe('Full');
-    });
-
-    it('is "Live" for an enabled pool with capacity, or with no tranches yet', () => {
-        expect(derivePoolStatus(pool([tranche('Senior', '5000')]))).toBe('Live');
-        expect(derivePoolStatus(pool([]))).toBe('Live');
-    });
-});
-
-describe('trancheApyBounds', () => {
-    it('spans the lowest minApy and the highest maxApy across tranches', () => {
-        expect(
-            trancheApyBounds([rated('0.12', '0.12'), rated('0.185', '0.185')]),
-        ).toEqual({ min: 0.12, max: 0.185 });
-    });
-
-    it('carries a single-option strategy as an equal pair', () => {
-        expect(trancheApyBounds([rated('0.1', '0.1')])).toEqual({
-            min: 0.1,
-            max: 0.1,
-        });
-    });
-
-    it('skips zero and non-finite rates rather than dragging the range down', () => {
-        // A tranche with no fixed-term config must not turn a 10.5% range into
-        // 0–10.5%.
-        expect(
-            trancheApyBounds([rated('0', '0'), rated('0.105', '0.105')]),
-        ).toEqual({ min: 0.105, max: 0.105 });
-        expect(
-            trancheApyBounds([rated('not-a-number', 'x'), rated('0.12', '0.14')]),
-        ).toEqual({ min: 0.12, max: 0.14 });
-    });
-
-    it('is null when nothing usable remains', () => {
-        expect(trancheApyBounds([])).toBeNull();
-        expect(trancheApyBounds([rated('0', '0')])).toBeNull();
-        expect(trancheApyBounds([rated('-0.1', '-0.1')])).toBeNull();
-    });
-
-    it('is null when only ONE side is usable — never half a range', () => {
-        expect(trancheApyBounds([rated('0.12', '0')])).toBeNull();
-        expect(trancheApyBounds([rated('0', '0.12')])).toBeNull();
-    });
-});
-
-describe('netTrancheApyBounds', () => {
-    it('reproduces the spec §2.5 card range: 14–22% gross is 13–20% net', () => {
-        const bounds = netTrancheApyBounds([rated('0.14', '0.22')], FEE);
-        expect(bounds).not.toBeNull();
-        expect(bounds?.min).toBeCloseTo(0.1252, 4);
-        expect(bounds?.max).toBeCloseTo(0.196, 4);
-    });
-
-    it('puts each bound through netEffectiveApy and nothing else', () => {
-        const bounds = netTrancheApyBounds([rated('0.12', '0.185')], FEE);
-        expect(bounds).toEqual({
-            min: netEffectiveApy(0.12, FEE),
-            max: netEffectiveApy(0.185, FEE),
-        });
-    });
-
-    it('returns the gross bounds unchanged at a zero fee', () => {
-        expect(netTrancheApyBounds([rated('0.14', '0.22')], 0)).toEqual({
-            min: 0.14,
-            max: 0.22,
-        });
-    });
-
-    it('FAILS CLOSED on an out-of-domain fee — never the gross range', () => {
-        // The raw subgraph integer (1000 = 10%) and a negative fee both land
-        // here. A caller that does not KNOW the fee must not call at all;
-        // substituting 0 would overstate the rate with nothing saying so.
-        expect(netTrancheApyBounds([rated('0.14', '0.22')], 1000)).toBeNull();
-        expect(netTrancheApyBounds([rated('0.14', '0.22')], -1)).toBeNull();
-        expect(netTrancheApyBounds([rated('0.14', '0.22')], NaN)).toBeNull();
-    });
-
-    it('is null when a 100% fee leaves the lender nothing', () => {
-        expect(netTrancheApyBounds([rated('0.14', '0.22')], 100)).toBeNull();
-    });
-
-    it('is null whenever the gross range is', () => {
-        expect(netTrancheApyBounds([], FEE)).toBeNull();
-        expect(netTrancheApyBounds([rated('0', '0')], FEE)).toBeNull();
-    });
-
-    it('never inverts the range it was given', () => {
-        fc.assert(
-            fc.property(
-                fc.double({ min: 0.0001, max: 0.99, noNaN: true }),
-                fc.double({ min: 0.0001, max: 0.99, noNaN: true }),
-                fc.double({ min: 0, max: 99, noNaN: true }),
-                (a, b, feePercent) => {
-                    const bounds = netTrancheApyBounds(
-                        [
-                            rated(
-                                String(Math.min(a, b)),
-                                String(Math.max(a, b)),
-                            ),
-                        ],
-                        feePercent,
-                    );
-                    if (!bounds) return;
-                    expect(bounds.min).toBeLessThanOrEqual(bounds.max);
-                    expect(bounds.min).toBeGreaterThan(0);
-                },
-            ),
-            { numRuns: 2000 },
-        );
-    });
-});

package/src/facade/config.test.ts

@@ -1,265 +0,0 @@
-import { providers, Wallet } from 'ethers';
-
-import { SdkConfig } from '../sdk-config';
-
-import { CHAIN_CONFIGS } from './chain-configs';
-import { Kasu } from './kasu';
-import { ChainConfigEntry } from './types';
-
-// Pure config assertions — no network, unlike `facade.test.ts`.
-
-const BASE_CONTRACTS = CHAIN_CONFIGS.base.contracts;
-
-/** A signer with a provider attached, offline — nothing here sends anything. */
-function signer(): Wallet {
-    return Wallet.createRandom().connect(
-        new providers.StaticJsonRpcProvider(
-            CHAIN_CONFIGS.base.rpcUrls[0],
-            CHAIN_CONFIGS.base.chainId,
-        ),
-    );
-}
-
-describe('SdkConfig — UNUSED_LENDING_POOL_IDS normalisation', () => {
-    it("turns an empty exclusion list into the [''] sentinel", () => {
-        // `id_not_in: []` matches NOTHING in the subgraph: on Base it returns
-        // 0 pools where `['']` returns all 9 (verified live 2026-09-04).
-        const config = new SdkConfig({
-            subgraphUrl: 'https://example.invalid/subgraph',
-            contracts: BASE_CONTRACTS,
-            UNUSED_LENDING_POOL_IDS: [],
-        });
-        expect(config.UNUSED_LENDING_POOL_IDS).toEqual(['']);
-    });
-
-    it('leaves a caller-supplied exclusion list untouched', () => {
-        const config = new SdkConfig({
-            subgraphUrl: 'https://example.invalid/subgraph',
-            contracts: BASE_CONTRACTS,
-            UNUSED_LENDING_POOL_IDS: ['0xdead'],
-        });
-        expect(config.UNUSED_LENDING_POOL_IDS).toEqual(['0xdead']);
-    });
-
-    it('leaves a sentinel a consumer already passes untouched', () => {
-        // kasu-ui passes [''], kasu-mobile passes the zero address.
-        const zeroAddress = '0x0000000000000000000000000000000000000000';
-        for (const sentinel of [[''], [zeroAddress]]) {
-            const config = new SdkConfig({
-                subgraphUrl: 'https://example.invalid/subgraph',
-                contracts: BASE_CONTRACTS,
-                UNUSED_LENDING_POOL_IDS: sentinel,
-            });
-            expect(config.UNUSED_LENDING_POOL_IDS).toEqual(sentinel);
-        }
-    });
-});
-
-describe('CHAIN_CONFIGS — stable asset', () => {
-    it('gives every chain exactly one stable asset', () => {
-        for (const [chain, config] of Object.entries(CHAIN_CONFIGS)) {
-            expect(config.stableAsset.address).toMatch(/^0x[0-9a-fA-F]{40}$/);
-            expect(config.stableAsset.symbol.length).toBeGreaterThan(0);
-            expect(config.stableAsset.decimals).toBeGreaterThan(0);
-            expect(config.stableAsset.currencyCode).toMatch(/^[A-Z]{3}$/);
-            expect(chain).toBeTruthy();
-        }
-    });
-
-    it('carries the live token per deployment', () => {
-        expect(CHAIN_CONFIGS.base.stableAsset).toEqual({
-            address: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
-            symbol: 'USDC',
-            name: 'USD Coin',
-            decimals: 6,
-            currencyCode: 'USD',
-        });
-        expect(CHAIN_CONFIGS.xdc.stableAsset.symbol).toBe('AUDD');
-        expect(CHAIN_CONFIGS.xdc.stableAsset.currencyCode).toBe('AUD');
-        expect(CHAIN_CONFIGS['xdc-usdc'].stableAsset.symbol).toBe('USDC');
-        expect(CHAIN_CONFIGS.plume.stableAsset.symbol).toBe('pUSD');
-    });
-});
-
-describe('CHAIN_CONFIGS — rpcUrls', () => {
-    it('gives every live deployment at least one default endpoint', () => {
-        for (const chain of ['base', 'xdc', 'xdc-usdc'] as const) {
-            expect(CHAIN_CONFIGS[chain].rpcUrls.length).toBeGreaterThan(0);
-            expect(CHAIN_CONFIGS[chain].retired).toBeUndefined();
-        }
-    });
-
-    it('never lists an XDC endpoint that fails CORS preflight', () => {
-        // `rpc.xdc.org` / `erpc.xdc.org` answer OPTIONS without
-        // `access-control-allow-origin`, so a browser call hangs. House rule.
-        for (const config of Object.values(CHAIN_CONFIGS)) {
-            for (const url of config.rpcUrls) {
-                expect(url).not.toContain('rpc.xdc.org');
-                expect(url).not.toContain('erpc.xdc.org');
-            }
-        }
-    });
-
-    it('marks the retired deployment and leaves it without a default RPC', () => {
-        expect(CHAIN_CONFIGS.plume.retired).toBe(true);
-        expect(CHAIN_CONFIGS.plume.rpcUrls).toEqual([]);
-    });
-});
-
-describe('Kasu — read-only create and connect', () => {
-    it('creates a read-only instance with no signerOrProvider', () => {
-        const kasu = Kasu.create({ chain: 'base' });
-        expect(kasu.isReadOnly).toBe(true);
-        expect(kasu.provider).toBeInstanceOf(providers.StaticJsonRpcProvider);
-    });
-
-    it('uses rpcUrls[0] and the config chain id, with no network detection', () => {
-        const kasu = Kasu.create({ chain: 'base' });
-        const provider = kasu.provider as providers.StaticJsonRpcProvider;
-        expect(provider.connection.url).toBe(CHAIN_CONFIGS.base.rpcUrls[0]);
-        expect(provider.network.chainId).toBe(CHAIN_CONFIGS.base.chainId);
-    });
-
-    it('refuses a read-only create on a retired chain with no default RPC', () => {
-        expect(() => Kasu.create({ chain: 'plume' })).toThrow(
-            'Kasu.create: chain "plume" has no default RPC (retired); pass signerOrProvider',
-        );
-    });
-
-    it('still accepts an explicit provider for the retired chain', () => {
-        const provider = new providers.StaticJsonRpcProvider(
-            'https://example.invalid/plume',
-            CHAIN_CONFIGS.plume.chainId,
-        );
-        const kasu = Kasu.create({ chain: 'plume', signerOrProvider: provider });
-        expect(kasu.isReadOnly).toBe(true);
-        expect(kasu.provider).toBe(provider);
-    });
-
-    it('is writable when created from a signer', () => {
-        const kasu = Kasu.create({ chain: 'base', signerOrProvider: signer() });
-        expect(kasu.isReadOnly).toBe(false);
-    });
-
-    it('connect returns a NEW writable instance, leaving the original read-only', () => {
-        const readOnly = Kasu.create({ chain: 'base' });
-        const connected = readOnly.connect(signer());
-        expect(connected).not.toBe(readOnly);
-        expect(connected.isReadOnly).toBe(false);
-        expect(readOnly.isReadOnly).toBe(true);
-    });
-
-    it('connect keeps the chain config and the configOverrides', () => {
-        const readOnly = Kasu.create({
-            chain: 'base',
-            configOverrides: { UNUSED_LENDING_POOL_IDS: ['0xhidden'] },
-        });
-        const connected = readOnly.connect(signer());
-        expect(connected.chainConfig).toBe(readOnly.chainConfig);
-        const configOf = (kasu: Kasu): SdkConfig =>
-            (kasu.services.DataService as unknown as { _kasuConfig: SdkConfig })
-                ._kasuConfig;
-        expect(configOf(connected).UNUSED_LENDING_POOL_IDS).toEqual([
-            '0xhidden',
-        ]);
-    });
-
-    it('exposes the signer’s own provider on a connected instance', () => {
-        const wallet = signer();
-        const kasu = Kasu.create({ chain: 'base', signerOrProvider: wallet });
-        expect(kasu.provider).toBe(wallet.provider);
-    });
-
-    it('throws rather than returning undefined for a provider-less signer', () => {
-        const kasu = Kasu.create({
-            chain: 'base',
-            signerOrProvider: Wallet.createRandom(),
-        });
-        expect(() => kasu.provider).toThrow('has no provider attached');
-    });
-});
-
-describe('DepositsFacade — read-only writes', () => {
-    const readOnly = (): Kasu => Kasu.create({ chain: 'base' });
-    const READ_ONLY_MESSAGE =
-        'Kasu: this instance is read-only; call kasu.connect(signer) first';
-
-    it('refuses deposit before touching the contract', async () => {
-        await expect(
-            readOnly().deposits.deposit({
-                poolId: '0xpool',
-                trancheId: '0xtranche',
-                amount: 1,
-                kycSignature: { blockExpiration: 0, signature: '0x' },
-            }),
-        ).rejects.toThrow(READ_ONLY_MESSAGE);
-    });
-
-    it('refuses withdraw', async () => {
-        await expect(
-            readOnly().deposits.withdraw({
-                poolId: '0xpool',
-                trancheId: '0xtranche',
-                amount: 1,
-            }),
-        ).rejects.toThrow(READ_ONLY_MESSAGE);
-    });
-
-    it('refuses withdrawMax', async () => {
-        await expect(
-            readOnly().deposits.withdrawMax('0xpool', '0xtranche', '0xuser'),
-        ).rejects.toThrow(READ_ONLY_MESSAGE);
-    });
-
-    it('lets a connected instance past the guard', () => {
-        const connected = readOnly().connect(signer());
-        // Reaches the contract call (and fails there on a fake address) rather
-        // than being refused up front. Probing the guard directly keeps the
-        // assertion off the network.
-        const guard = connected.deposits as unknown as {
-            assertWritable(): void;
-        };
-        expect(() => {
-            guard.assertWritable();
-        }).not.toThrow();
-    });
-});
-
-describe('Kasu.create — a ChainConfigEntry written before 2.5.0', () => {
-    // kasu-app-admin hand-builds one of these for base-sepolia. TypeScript will
-    // ask it for `stableAsset` and `rpcUrls` on bump; the runtime must not
-    // crash first.
-    const legacy = (): ChainConfigEntry =>
-        ({
-            chainId: 84532,
-            name: 'base-sepolia',
-            isLiteDeployment: false,
-            contracts: BASE_CONTRACTS,
-            subgraphUrl: 'https://example.invalid/subgraph',
-            // Non-empty: `SdkConfig` documents `directusUrl` as optional, but
-            // `createDirectus('')` throws `TypeError: Invalid URL`. Pre-existing,
-            // and unrelated to what this test covers.
-            directusUrl: 'https://example.invalid/directus/',
-            unusedPoolIds: [''],
-        }) as unknown as ChainConfigEntry;
-
-    it('constructs with an explicit provider and falls back to 6 decimals', () => {
-        const kasu = Kasu.create({
-            chain: legacy(),
-            signerOrProvider: new providers.StaticJsonRpcProvider(
-                'https://example.invalid/rpc',
-                84532,
-            ),
-        });
-        const config = (
-            kasu.services.DataService as unknown as { _kasuConfig: SdkConfig }
-        )._kasuConfig;
-        expect(config.stableAssetDecimals).toBe(6);
-    });
-
-    it('refuses a read-only create with the same message a retired chain gives', () => {
-        expect(() => Kasu.create({ chain: legacy() })).toThrow(
-            'Kasu.create: chain "base-sepolia" has no default RPC (retired); pass signerOrProvider',
-        );
-    });
-});