@kasufinance/kasu-sdk 2.4.2 → 2.6.0

package/src/domain/tranches.ts

@@ -0,0 +1,177 @@
+import { PoolOverview, TrancheData } from '../services/DataService/types';
+
+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;
+
+/**
+ * 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 function trancheHasCapacity(tranche: TrancheCapacitySignal): boolean {
+    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: PoolOverview): boolean {
+    return pool.tranches.length > 0 && !pool.tranches.some(trancheHasCapacity);
+}
+
+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 function derivePoolStatus(pool: PoolOverview): PoolStatus {
+    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: Record<string, number | undefined> = {
+    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: string | undefined): number {
+    return (
+        TRANCHE_RISK_RANK[name?.trim().toLowerCase() ?? ''] ??
+        Number.POSITIVE_INFINITY
+    );
+}
+
+export function trancheRiskRank(tranche: TrancheData): number {
+    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: TrancheData, b: TrancheData): number {
+    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: PoolOverview): string {
+    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;
+}
+
+/** 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 function trancheApyBounds(tranches: TrancheData[]): ApyBounds | null {
+    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: TrancheData[],
+    feePercent: number,
+): ApyBounds | null {
+    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 };
+}

package/src/domain/wallet-errors.test.ts

@@ -0,0 +1,100 @@
+import { isUnpredictableGas, isUserRejected } from './wallet-errors';
+
+/**
+ * `isUserRejected` cases ported from kasu-ui
+ * `src/lib/web3/is-user-rejected.test.ts`. `isUnpredictableGas` had no test in
+ * kasu-mobile; one is written here.
+ */
+
+describe('isUserRejected', () => {
+    it('detects EIP-1193 numeric code 4001', () => {
+        expect(isUserRejected({ code: 4001, message: 'whatever' })).toBe(true);
+    });
+
+    it('detects ACTION_REJECTED string code (ethers v5)', () => {
+        expect(
+            isUserRejected({ code: 'ACTION_REJECTED', message: 'rejected' }),
+        ).toBe(true);
+    });
+
+    it('detects "User rejected" message string', () => {
+        expect(isUserRejected(new Error('User rejected the request'))).toBe(
+            true,
+        );
+    });
+
+    it('detects "User denied" message string', () => {
+        expect(
+            isUserRejected(new Error('User denied transaction signature')),
+        ).toBe(true);
+    });
+
+    it('detects the ethers ACTION_REJECTED marker in a message', () => {
+        expect(
+            isUserRejected(new Error('transaction failed: ACTION_REJECTED')),
+        ).toBe(true);
+    });
+
+    it('is case-insensitive', () => {
+        expect(isUserRejected(new Error('user REJECTED the request'))).toBe(
+            true,
+        );
+    });
+
+    it('returns false for unrelated errors', () => {
+        expect(isUserRejected(new Error('Network error'))).toBe(false);
+        expect(isUserRejected(new Error('Insufficient funds'))).toBe(false);
+    });
+
+    it('returns false for null / undefined', () => {
+        expect(isUserRejected(null)).toBe(false);
+        expect(isUserRejected(undefined)).toBe(false);
+    });
+
+    it('handles non-Error throwables', () => {
+        expect(isUserRejected('user rejected')).toBe(true);
+        expect(isUserRejected('something else')).toBe(false);
+    });
+
+    it('is not fooled by a numeric code that only looks like 4001', () => {
+        expect(isUserRejected({ code: '4001' })).toBe(false);
+        expect(isUserRejected({ code: 4002 })).toBe(false);
+    });
+});
+
+describe('isUnpredictableGas', () => {
+    it('detects the ethers v5 gas-estimation revert code', () => {
+        expect(isUnpredictableGas({ code: 'UNPREDICTABLE_GAS_LIMIT' })).toBe(
+            true,
+        );
+    });
+
+    it('does not fire on a user rejection', () => {
+        expect(isUnpredictableGas({ code: 'ACTION_REJECTED' })).toBe(false);
+        expect(isUnpredictableGas({ code: 4001 })).toBe(false);
+    });
+
+    it('does not fire on the code appearing only in a message', () => {
+        // The code is the signal; a message mentioning it is not one, or a
+        // logged error string would be mistaken for a revert.
+        expect(
+            isUnpredictableGas(new Error('UNPREDICTABLE_GAS_LIMIT')),
+        ).toBe(false);
+        expect(isUnpredictableGas('UNPREDICTABLE_GAS_LIMIT')).toBe(false);
+    });
+
+    it('returns false for null / undefined and for unrelated errors', () => {
+        expect(isUnpredictableGas(null)).toBe(false);
+        expect(isUnpredictableGas(undefined)).toBe(false);
+        expect(isUnpredictableGas(new Error('Network error'))).toBe(false);
+    });
+
+    it('reads the code off an ethers error object', () => {
+        const err = Object.assign(new Error('cannot estimate gas'), {
+            code: 'UNPREDICTABLE_GAS_LIMIT',
+            reason: 'execution reverted: ERC20: insufficient allowance',
+        });
+        expect(isUnpredictableGas(err)).toBe(true);
+        expect(isUserRejected(err)).toBe(false);
+    });
+});

package/src/domain/wallet-errors.ts

@@ -0,0 +1,56 @@
+/**
+ * Wallet and RPC error predicates — pure functions over `unknown`.
+ *
+ * Every consumer has to tell three things apart when a write fails: the lender
+ * changed their mind, the call would revert, and everything else. The first
+ * two must never be reported as a failure the lender should retry or contact
+ * support about, and each wallet spells them differently, so the shapes are
+ * enumerated once here.
+ *
+ * Lifted from kasu-ui's `src/lib/web3/is-user-rejected.ts` and kasu-mobile's
+ * `src/features/lending/lib/errors.ts`.
+ */
+
+/**
+ * Did the lender reject the request in their wallet?
+ *
+ * Providers surface a rejection in different shapes:
+ *   - MetaMask and most EIP-1193 wallets: `code: 4001`
+ *   - WalletConnect and some Privy paths: `Error('User rejected the request')`
+ *   - ethers v5 wraps it as `ACTION_REJECTED`
+ *   - Coinbase Wallet sometimes: `code: 'ACTION_REJECTED'` as a string
+ *
+ * This is kasu-ui's implementation verbatim. kasu-mobile's copy additionally
+ * reads a nested `error.code` / `error.message`, an ethers `reason`, and the
+ * words "request rejected" / "declined"; a consumer that needs those shapes
+ * should keep its own check on top rather than assume they are covered here.
+ */
+export function isUserRejected(err: unknown): boolean {
+    if (!err) return false;
+    if (typeof err === 'object') {
+        const code = (err as { code?: unknown }).code;
+        if (code === 4001 || code === 'ACTION_REJECTED') return true;
+    }
+    const msg = err instanceof Error ? err.message : String(err);
+    const lower = msg.toLowerCase();
+    return (
+        lower.includes('user rejected') ||
+        lower.includes('user denied') ||
+        lower.includes('rejected the request') ||
+        lower.includes('action_rejected')
+    );
+}
+
+/**
+ * Did the wallet or RPC signal that the on-chain call would revert?
+ *
+ * ethers v5 raises `UNPREDICTABLE_GAS_LIMIT` when gas estimation reverts —
+ * most often an underlying `transferFrom` failing on an insufficient balance
+ * or allowance. Distinct from a rejection: nothing was refused by the lender,
+ * the transaction simply cannot succeed as composed, so the caller should
+ * re-check its preconditions rather than invite a retry.
+ */
+export function isUnpredictableGas(err: unknown): boolean {
+    if (!err || typeof err !== 'object') return false;
+    return (err as { code?: unknown }).code === 'UNPREDICTABLE_GAS_LIMIT';
+}

package/src/facade/chain-configs.ts

@@ -1,5 +1,20 @@
 import { ChainConfigEntry } from './types';
 
+/**
+ * Browser-viable XDC RPCs only. `rpc.xdc.org` / `erpc.xdc.org` answer OPTIONS
+ * without `access-control-allow-origin`, so a browser call hangs on preflight
+ * — they must never appear here. The four below ship CORS `*` and are DISTINCT
+ * operators, so one vendor incident cannot exhaust the list. Order is a
+ * STARTING preference only; consumers are expected to fold the list into their
+ * own failover. Shared by both XDC deployments (same chain, same endpoints).
+ */
+const XDC_RPC_URLS: string[] = [
+    'https://rpc.ankr.com/xdc',
+    'https://rpc.xdcrpc.com',
+    'https://rpc.xinfin.network',
+    'https://rpc.primenumbers.xyz/',
+];
+
 /**
  * Built-in chain configurations for Kasu-supported networks.
  *
@@ -33,6 +48,17 @@ export const CHAIN_CONFIGS: Record<'base' | 'xdc' | 'xdc-usdc' | 'plume', ChainC
         directusUrl: 'https://kasu-finance.directus.app/',
         unusedPoolIds: [],
         poolMetadataMapping: undefined,
+        stableAsset: {
+            address: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
+            symbol: 'USDC',
+            name: 'USD Coin',
+            decimals: 6,
+            currencyCode: 'USD',
+        },
+        rpcUrls: [
+            'https://base-rpc.publicnode.com',
+            'https://mainnet.base.org',
+        ],
     },
 
     xdc: {
@@ -65,6 +91,14 @@ export const CHAIN_CONFIGS: Record<'base' | 'xdc' | 'xdc-usdc' | 'plume', ChainC
             '0xeda50c91a8c4ca8a83652b8542c0b3bd00a71fad':
                 '0xc347a9e4aec8c8d11a149d2907deb2bf23b81c6f',
         },
+        stableAsset: {
+            address: '0x9fe4e6321eeb7c4bc537570f015e4734b15002b8',
+            symbol: 'AUDD',
+            name: 'Novatti Australian Dollar',
+            decimals: 6,
+            currencyCode: 'AUD',
+        },
+        rpcUrls: XDC_RPC_URLS,
     },
 
     'xdc-usdc': {
@@ -90,6 +124,14 @@ export const CHAIN_CONFIGS: Record<'base' | 'xdc' | 'xdc-usdc' | 'plume', ChainC
         directusUrl: 'https://kasu-finance.directus.app/',
         unusedPoolIds: [],
         poolMetadataMapping: undefined,
+        stableAsset: {
+            address: '0xfa2958cb79b0491cc627c1557f441ef849ca8eb1',
+            symbol: 'USDC',
+            name: 'USD Coin',
+            decimals: 6,
+            currencyCode: 'USD',
+        },
+        rpcUrls: XDC_RPC_URLS,
     },
 
     plume: {
@@ -109,10 +151,29 @@ export const CHAIN_CONFIGS: Record<'base' | 'xdc' | 'xdc-usdc' | 'plume', ChainC
             ClearingCoordinator: '',
             ExternalTVL: '',
         },
+        // The frozen Plume history is indexed on the LEGACY Goldsky project,
+        // not the one the live chains use: the same path under the current
+        // project 404s. Verified 2026-09-05 — this URL answers
+        // `{ lendingPools { id name } }` with the three Plume pools; the
+        // current-project spelling returns HTTP 404. Note the `/gn` suffix,
+        // which the current project's URLs do not carry.
         subgraphUrl:
-            'https://api.goldsky.com/api/public/project_cmgzlpxm300765np2a19421om/subgraphs/kasu-plume/prod',
+            'https://api.goldsky.com/api/public/project_cm9t3064xeuyn01tgctdo3c17/subgraphs/kasu-plume/prod/gn',
         directusUrl: 'https://kasu-finance.directus.app/',
         unusedPoolIds: [],
         poolMetadataMapping: undefined,
+        stableAsset: {
+            address: '0xdddD73F5Df1F0DC31373357beAC77545dC5A6f3F',
+            symbol: 'pUSD',
+            name: 'Plume USD',
+            decimals: 6,
+            currencyCode: 'USD',
+        },
+        // Retired — drained and wound down. No default RPC, so a read-only
+        // `Kasu.create({ chain: 'plume' })` throws rather than quietly
+        // pointing at an endpoint nobody maintains. Pass your own
+        // `signerOrProvider` to read the frozen history.
+        rpcUrls: [],
+        retired: true,
     },
 };