@kasufinance/kasu-sdk 2.4.2 → 2.5.0

package/src/facade/kasu.ts

@@ -1,10 +1,18 @@
+import { Provider } from '@ethersproject/providers';
+import { providers, Signer } from 'ethers';
+
 import { KasuSdk } from '../kasu-sdk';
-import { SdkConfig } from '../sdk-config';
+import { SdkConfig, SdkConfigOptions } from '../sdk-config';
 
 import { CHAIN_CONFIGS } from './chain-configs';
 import { DepositsFacade } from './deposits';
 import { StrategiesFacade } from './strategies';
-import { ChainConfigEntry, KasuOptions, SupportedChain } from './types';
+import {
+    ChainConfigEntry,
+    KasuOptions,
+    StableAsset,
+    SupportedChain,
+} from './types';
 import { PortfolioFacade } from './user-portfolio';
 
 /**
@@ -16,15 +24,15 @@ import { PortfolioFacade } from './user-portfolio';
  * ```ts
  * import { Kasu } from '@kasufinance/kasu-sdk';
  *
- * const kasu = Kasu.create({ chain: 'base', signerOrProvider: provider });
- *
- * // Browse strategies
+ * // Read-only — no wallet needed, uses the chain's default RPC
+ * const kasu = Kasu.create({ chain: 'base' });
  * const strategies = await kasu.strategies.getAll();
  *
- * // Deposit
- * const tx = await kasu.deposits.deposit({ poolId, trancheId, amount, kycSignature });
+ * // Writable — same config, bound to a signer
+ * const signed = kasu.connect(signer);
+ * const tx = await signed.deposits.deposit({ poolId, trancheId, amount, kycSignature });
  *
- * // User positions
+ * // User positions (read-only is enough)
  * const positions = await kasu.portfolio.getPositions(userAddress);
  * ```
  */
@@ -38,13 +46,24 @@ export class Kasu {
 
     private readonly _sdk: KasuSdk;
     private readonly _chainConfig: ChainConfigEntry;
+    private readonly _signerOrProvider: Provider | Signer;
+    /**
+     * Kept so `connect(signer)` can rebuild an identical instance. A connected
+     * instance that silently dropped the overrides would query a different set
+     * of pools than the read-only one it came from.
+     */
+    private readonly _configOverrides: Partial<SdkConfigOptions>;
 
     private constructor(
         sdk: KasuSdk,
         chainConfig: ChainConfigEntry,
+        signerOrProvider: Provider | Signer,
+        configOverrides: Partial<SdkConfigOptions>,
     ) {
         this._sdk = sdk;
         this._chainConfig = chainConfig;
+        this._signerOrProvider = signerOrProvider;
+        this._configOverrides = configOverrides;
 
         this.strategies = new StrategiesFacade(
             sdk.DataService,
@@ -54,6 +73,7 @@ export class Kasu {
         this.deposits = new DepositsFacade(
             sdk.UserLending,
             chainConfig.chainId.toString(),
+            !Signer.isSigner(signerOrProvider),
         );
 
         this.portfolio = new PortfolioFacade(
@@ -66,9 +86,12 @@ export class Kasu {
     /**
      * Create a Kasu instance with built-in chain config.
      *
+     * `signerOrProvider` is optional: without one the instance is READ-ONLY on
+     * `chainConfig.rpcUrls[0]`. Use `connect(signer)` when a wallet arrives.
+     *
      * ```ts
-     * // Minimal setup — uses built-in Base mainnet config
-     * const kasu = Kasu.create({ chain: 'base', signerOrProvider: provider });
+     * // Minimal setup — read-only, built-in Base mainnet config
+     * const kasu = Kasu.create({ chain: 'base' });
      *
      * // Custom config override
      * const kasu = Kasu.create({
@@ -102,10 +125,46 @@ export class Kasu {
             poolMetadataMapping:
                 overrides.poolMetadataMapping ??
                 chainConfig.poolMetadataMapping,
+            // Follow the chain's own token rather than `SdkConfig`'s default
+            // of 6. Every live deployment happens to be 6dp today, so the
+            // default was right by luck; the next one need not be.
+            stableAssetDecimals:
+                overrides.stableAssetDecimals ??
+                stableAssetOf(chainConfig)?.decimals,
         });
 
-        const sdk = new KasuSdk(sdkConfig, options.signerOrProvider);
-        return new Kasu(sdk, chainConfig);
+        const signerOrProvider =
+            options.signerOrProvider ??
+            defaultProvider(
+                chainConfig,
+                typeof options.chain === 'string'
+                    ? options.chain
+                    : chainConfig.name,
+            );
+
+        const sdk = new KasuSdk(sdkConfig, signerOrProvider);
+        return new Kasu(sdk, chainConfig, signerOrProvider, overrides);
+    }
+
+    /**
+     * A NEW instance bound to `signer`, with the same chain config and the same
+     * `configOverrides` — the writable counterpart of a read-only instance.
+     *
+     * Named after `contract.connect(signer)` in ethers, and behaves the same
+     * way: the receiver is not mutated, so a read-only `Kasu` stays read-only
+     * and can keep serving public data after a wallet connects.
+     *
+     * ```ts
+     * const kasu = Kasu.create({ chain: 'base' });        // read-only
+     * const signed = kasu.connect(await getSigner());     // writable
+     * ```
+     */
+    connect(signer: Signer): Kasu {
+        return Kasu.create({
+            chain: this._chainConfig,
+            signerOrProvider: signer,
+            configOverrides: this._configOverrides,
+        });
     }
 
     /**
@@ -128,12 +187,96 @@ export class Kasu {
     get isLiteDeployment(): boolean {
         return this._chainConfig.isLiteDeployment;
     }
+
+    /**
+     * True when this instance was built from a Provider rather than a Signer,
+     * so every read works and every write is refused. Call `connect(signer)`
+     * for a writable instance.
+     */
+    get isReadOnly(): boolean {
+        return !Signer.isSigner(this._signerOrProvider);
+    }
+
+    /**
+     * The provider this instance reads through — the signer's own provider when
+     * it was created from a signer.
+     *
+     * Throws for a signer with no provider attached (an offline signer can sign
+     * but cannot read), because there is no provider to hand back and returning
+     * `undefined` would only move the failure somewhere less obvious.
+     */
+    get provider(): Provider {
+        if (Signer.isSigner(this._signerOrProvider)) {
+            const provider = this._signerOrProvider.provider;
+            if (!provider) {
+                throw new Error(
+                    'Kasu: the signer this instance was created with has no provider attached',
+                );
+            }
+            return provider;
+        }
+        return this._signerOrProvider;
+    }
 }
 
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
 
+// `stableAsset` and `rpcUrls` are REQUIRED on `ChainConfigEntry`, so every
+// built-in config and every entry written against 2.5.0 carries them. A custom
+// entry hand-built against an older release does not, and a consumer bumping to
+// 2.5.0 must not crash on `undefined.decimals` before TypeScript has told them
+// what to add (kasu-app-admin builds one for base-sepolia). Both readers below
+// take the field as possibly absent and fall back: the stable-asset decimals to
+// `SdkConfig`'s own default of 6, the RPC list to empty — which makes a
+// read-only `create` throw the same clear message a retired chain does.
+function stableAssetOf(
+    chainConfig: ChainConfigEntry,
+): StableAsset | undefined {
+    return (chainConfig as { stableAsset?: StableAsset }).stableAsset;
+}
+
+function rpcUrlsOf(chainConfig: ChainConfigEntry): string[] {
+    return (chainConfig as { rpcUrls?: string[] }).rpcUrls ?? [];
+}
+
+/**
+ * The read-only provider used when the caller passes no `signerOrProvider`.
+ *
+ * `StaticJsonRpcProvider` rather than `JsonRpcProvider`: the chain id is known
+ * from the config, so it skips the `eth_chainId` round trip on every call and
+ * never re-detects the network — the right choice for an endpoint that serves
+ * exactly one chain.
+ *
+ * Only `rpcUrls[0]` is used. The list is a starting preference, not a failover
+ * strategy: an app that needs failover builds its own provider and passes it
+ * in, and baking a retry policy in here would hide outages from the app that
+ * has to report them.
+ *
+ * Constructed through the `ethers` namespace rather than by importing
+ * `StaticJsonRpcProvider` from `@ethersproject/providers` directly. `ethers` is
+ * the only provider package the rollup config marks external, so this picks up
+ * the CONSUMER's build — the Node one under Node, the browser one in a browser.
+ * Importing the class directly would inline the browser transport into the
+ * bundle, and its `fetch` call carries `referrer: 'client'`, which Node rejects
+ * outright ("Referrer \"client\" is not a valid URL"). It would also give the
+ * SDK a second provider implementation, so `instanceof` against the consumer's
+ * ethers would quietly fail.
+ */
+function defaultProvider(
+    chainConfig: ChainConfigEntry,
+    chainLabel: string,
+): Provider {
+    const url = rpcUrlsOf(chainConfig)[0];
+    if (!url) {
+        throw new Error(
+            `Kasu.create: chain "${chainLabel}" has no default RPC (retired); pass signerOrProvider`,
+        );
+    }
+    return new providers.StaticJsonRpcProvider(url, chainConfig.chainId);
+}
+
 function resolveChainConfig(
     chain: SupportedChain | ChainConfigEntry,
 ): ChainConfigEntry {

package/src/facade/strategies.ts

@@ -1,3 +1,4 @@
+import { selectVisiblePools } from '../domain/pools';
 import { DataService } from '../services/DataService/data-service';
 import { PoolOverview } from '../services/DataService/types';
 import { UserLending } from '../services/UserLending/user-lending';
@@ -34,6 +35,41 @@ export class StrategiesFacade {
         return pools.map((pool) => this.mapPoolToStrategy(pool));
     }
 
+    /**
+     * The strategies a lender should actually see: active, not oversubscribed,
+     * with the ones that still have capacity first and the highest max APY
+     * next. `getAll` returns everything the subgraph knows about, including
+     * pools that are wound down.
+     *
+     * The filter runs on the raw `PoolOverview[]` BEFORE mapping, so `_raw` on
+     * every returned `Strategy` is the untouched pool object.
+     */
+    async getVisible(poolIds?: string[]): Promise<Strategy[]> {
+        const epochId = await this._userLending.getCurrentEpoch();
+        const pools = await this._dataService.getPoolOverview(epochId, poolIds);
+        return selectVisiblePools(pools).map((pool) =>
+            this.mapPoolToStrategy(pool),
+        );
+    }
+
+    /**
+     * The chain's performance fee.
+     *
+     * ⚠️ A PERCENTAGE IN 0..100 (`10` means ten percent), NOT a fraction —
+     * feed it to `netEffectiveApy` as-is. Treating it as `0.10` computes a
+     * nonsense negative rate that still renders as a plausible-looking
+     * percentage, which is why the units are stated here and in
+     * `netEffectiveApy`'s own JSDoc.
+     *
+     * ```ts
+     * const feePercent = await kasu.strategies.getPerformanceFeePercent();
+     * const net = netEffectiveApy(strategy.tranches[0].apy, feePercent);
+     * ```
+     */
+    async getPerformanceFeePercent(): Promise<number> {
+        return await this._dataService.getPerformanceFee();
+    }
+
     /**
      * Fetch a single strategy by pool ID. Returns `null` if not found.
      */

package/src/facade/types.ts

@@ -13,6 +13,34 @@ import {
 
 export type SupportedChain = 'base' | 'xdc' | 'xdc-usdc' | 'plume';
 
+/**
+ * The single stable token a deployment lends in. There is exactly ONE per
+ * deployment and it never changes: a different stable token is a separate full
+ * deployment (the XDC AUDD / XDC USDC pattern), never a companion vault on an
+ * existing one. That is why this is a plain object on the chain config rather
+ * than a list.
+ */
+export interface StableAsset {
+    /** ERC-20 address of the stable token on this chain. */
+    address: string;
+    /** Ticker as the token contract reports it (`USDC`, `AUDD`, `pUSD`). */
+    symbol: string;
+    /** Token name as the contract reports it (`USD Coin`). */
+    name: string;
+    /**
+     * Token decimals. Feeds `SdkConfig.stableAssetDecimals`, so every
+     * `parseUnits`/`formatUnits` in the SDK follows the chain rather than the
+     * hard-coded default of 6.
+     */
+    decimals: number;
+    /**
+     * ISO-4217 code of the fiat currency the token tracks (`USD`, `AUD`).
+     * A CODE, not copy: consumers pick their own symbol and locale from it.
+     * Nothing in this SDK formats it.
+     */
+    currencyCode: string;
+}
+
 export interface ChainConfigEntry {
     chainId: number;
     name: string;
@@ -20,16 +48,46 @@ export interface ChainConfigEntry {
     contracts: ContractAddresses;
     subgraphUrl: string;
     directusUrl: string;
+    /**
+     * Pools to hide. An EMPTY array is normalised to `['']` by `SdkConfig` —
+     * the subgraph reads `id_not_in: []` as "match nothing" and returns zero
+     * pools. See `SdkConfigOptions.UNUSED_LENDING_POOL_IDS`.
+     */
     unusedPoolIds: string[];
     poolMetadataMapping?: Record<string, string>;
+    /** The one stable token this deployment lends in. */
+    stableAsset: StableAsset;
+    /**
+     * Public RPC endpoints for read-only use, in STARTING preference order
+     * only. Apps are expected to override with their own paid/keyed endpoints
+     * and their own failover; `Kasu.create` uses `rpcUrls[0]` and nothing else
+     * when no `signerOrProvider` is passed.
+     *
+     * Empty on a retired deployment, which has no read-only default.
+     */
+    rpcUrls: string[];
+    /**
+     * True for a wound-down deployment kept only as frozen history. It has no
+     * default RPC, so a read-only `Kasu.create` on it throws.
+     */
+    retired?: boolean;
 }
 
 /** Options passed to `Kasu.create()`. */
 export interface KasuOptions {
     /** A supported chain name or a custom `ChainConfigEntry`. */
     chain: SupportedChain | ChainConfigEntry;
-    /** ethers Signer (for transactions) or Provider (read-only). */
-    signerOrProvider: import('ethers').Signer | import('@ethersproject/providers').Provider;
+    /**
+     * ethers Signer (for transactions) or Provider (read-only).
+     *
+     * OPTIONAL. When omitted, `Kasu.create` builds a read-only
+     * `StaticJsonRpcProvider` on `chainConfig.rpcUrls[0]`, so browsing
+     * strategies and platform stats needs no wallet at all. Get a writable
+     * instance later with `kasu.connect(signer)`.
+     */
+    signerOrProvider?:
+        | import('ethers').Signer
+        | import('@ethersproject/providers').Provider;
     /** Override any default config value. */
     configOverrides?: Partial<SdkConfigOptions>;
 }

package/src/facade/unused-pool-ids.ts

@@ -0,0 +1,59 @@
+/** Directus instance holding Kasu's pool editorial content. */
+const DEFAULT_DIRECTUS_URL = 'https://kasu-finance.directus.app/';
+
+interface PoolOverviewIdRow {
+    id?: unknown;
+}
+
+interface PoolOverviewIdResponse {
+    data?: PoolOverviewIdRow[];
+}
+
+/**
+ * The pool ids that are configured but NOT enabled — the ones every query
+ * should exclude.
+ *
+ * "Enabled" is editorial state, held in Directus rather than on-chain: a pool
+ * exists in the subgraph from the moment it is deployed, and stays hidden
+ * until content has been written for it. Every consumer has been hard-coding
+ * this list; reading it means a pool goes live without a frontend release.
+ *
+ * ```ts
+ * const kasu = Kasu.create({
+ *     chain: 'base',
+ *     configOverrides: { UNUSED_LENDING_POOL_IDS: await fetchUnusedPoolIds() },
+ * });
+ * ```
+ *
+ * May legitimately return an empty array (every pool enabled). Pass it
+ * straight through: `SdkConfig` normalises an empty list to the `['']`
+ * sentinel, because the subgraph reads `id_not_in: []` as "match nothing" and
+ * would hide every pool.
+ *
+ * Uses the global `fetch`, so it needs Node 18+ or a browser. This is I/O and
+ * deliberately not part of `domain/`.
+ *
+ * @param directusUrl base URL of the Directus instance, with or without a
+ *   trailing slash.
+ * @throws when the request fails or Directus answers with a non-2xx status —
+ *   never silently returns `[]`, which would be indistinguishable from "every
+ *   pool is enabled" and would un-hide pools that have no content.
+ */
+export async function fetchUnusedPoolIds(
+    directusUrl: string = DEFAULT_DIRECTUS_URL,
+): Promise<string[]> {
+    const base = directusUrl.endsWith('/') ? directusUrl : `${directusUrl}/`;
+    const url = `${base}items/PoolOverview?filter[enabled][_neq]=true`;
+
+    const response = await fetch(url);
+    if (!response.ok) {
+        throw new Error(
+            `fetchUnusedPoolIds: Directus responded ${String(response.status)} ${response.statusText} for ${url}`,
+        );
+    }
+
+    const body = (await response.json()) as PoolOverviewIdResponse;
+    return (body.data ?? [])
+        .map((row) => row.id)
+        .filter((id): id is string => typeof id === 'string' && id.length > 0);
+}

package/src/index.ts

@@ -59,3 +59,9 @@ export type {
 // Re-export facade (high-level integrator API)
 // ---------------------------------------------------------------------------
 export * from './facade';
+
+// ---------------------------------------------------------------------------
+// Shared domain layer — pure rate, tranche and pool rules. Numbers and codes
+// only: no copy, no locale. See `src/domain/index.ts`.
+// ---------------------------------------------------------------------------
+export * from './domain';

package/src/sdk-config.ts

@@ -20,6 +20,17 @@ export interface SdkConfigOptions {
     contracts: ContractAddresses;
     /** Directus CMS URL. Optional – when omitted, pool descriptions/images will not be available but on-chain data still works. */
     directusUrl?: string;
+    /**
+     * Pool ids to EXCLUDE from every subgraph query (`id_not_in`).
+     *
+     * An empty array is normalised to `['']` by the `SdkConfig` constructor.
+     * The subgraph reads `id_not_in: []` as "match nothing", not "exclude
+     * nothing": on Base, `[]` returns 0 pools where `['']` returns all 9
+     * (verified live 2026-09-04). Passing `[]` therefore used to make the SDK
+     * silently return an empty platform, which is why every consumer already
+     * passes a sentinel of its own. A sentinel you pass yourself is left
+     * untouched.
+     */
     UNUSED_LENDING_POOL_IDS: string[];
     /**
      * Whether this is a Lite deployment (no KSU token, locking, or loyalty features).
@@ -55,7 +66,14 @@ export class SdkConfig {
         this.subgraphUrl = options.subgraphUrl;
         this.contracts = options.contracts;
         this.directusUrl = options.directusUrl ?? '';
-        this.UNUSED_LENDING_POOL_IDS = options.UNUSED_LENDING_POOL_IDS;
+        // `id_not_in: []` matches NOTHING in the subgraph, so an empty
+        // exclusion list would hide every pool. The empty-string sentinel is
+        // the "exclude nothing" spelling — no pool id is the empty string, and
+        // it is what the consumers already work around this with.
+        this.UNUSED_LENDING_POOL_IDS =
+            options.UNUSED_LENDING_POOL_IDS.length > 0
+                ? options.UNUSED_LENDING_POOL_IDS
+                : [''];
         this.isLiteDeployment = options.isLiteDeployment ?? false;
         this.poolMetadataMapping = options.poolMetadataMapping ?? {};
         this.stableAssetDecimals = options.stableAssetDecimals ?? 6;

package/src/services/DataService/data-service.ts

@@ -17,6 +17,7 @@ import {
     KasuPoolExternalTVLAbi,
     KasuPoolExternalTVLAbi__factory,
 } from '../../contracts';
+import { epochRateToApy } from '../../domain/rates';
 import { SdkConfig } from '../../sdk-config';
 import { getSystemVariablesQuery } from '../Locking/queries';
 import { SystemVariables } from '../Locking/types';
@@ -171,9 +172,13 @@ export class DataService {
         );
     }
 
+    /**
+     * The subgraph's per-epoch `interestRate` compounded into an APY.
+     * Unchanged arithmetic — `EPOCHS_IN_YEAR` and the formula now come from
+     * `domain/rates` so this file and `KSULocking` cannot drift apart.
+     */
     calculateApyForTranche(interestRate: string): number {
-        const EPOCHS_IN_YEAR = 52.17857;
-        return (1 + parseFloat(interestRate)) ** EPOCHS_IN_YEAR - 1;
+        return epochRateToApy(parseFloat(interestRate));
     }
 
     async getPlatformOverview(): Promise<PlatformOverviewDirectus> {

package/src/services/Locking/calculate-apy.test.ts

@@ -0,0 +1,52 @@
+import { providers } from 'ethers';
+
+import { apyToEpochRate, epochRateToApy } from '../../domain/rates';
+import { CHAIN_CONFIGS } from '../../facade/chain-configs';
+import { SdkConfig } from '../../sdk-config';
+
+import { KSULocking } from './locking';
+
+// Offline: the constructor only builds contract instances. Nothing here calls
+// the RPC or the subgraph.
+function locking(): KSULocking {
+    const chain = CHAIN_CONFIGS.base;
+    const config = new SdkConfig({
+        subgraphUrl: 'https://example.invalid/subgraph',
+        contracts: chain.contracts,
+        UNUSED_LENDING_POOL_IDS: [''],
+    });
+    return new KSULocking(
+        config,
+        new providers.StaticJsonRpcProvider(chain.rpcUrls[0], chain.chainId),
+    );
+}
+
+describe('KSULocking.calculateApy', () => {
+    it('compounds the epoch rate instead of XOR-ing it', () => {
+        // The old body was `(1 + r) ^ (EPOCHS_IN_YEAR - 1)` — bitwise XOR on
+        // int32 operands, so every realistic rate returned the constant 50.
+        for (const r of [0.001, 0.0025, 0.003, 0.005]) {
+            expect(locking().calculateApy(r)).toBe(epochRateToApy(r));
+            expect(locking().calculateApy(r)).not.toBe(50);
+        }
+    });
+
+    it('lands on the APYs the platform actually quotes', () => {
+        // Every live tranche APY, back through its own per-epoch rate.
+        for (const apy of [0.1, 0.12, 0.14, 0.16, 0.22, 0.3]) {
+            expect(locking().calculateApy(apyToEpochRate(apy))).toBeCloseTo(
+                apy,
+                10,
+            );
+        }
+        expect(locking().calculateApy(0)).toBe(0);
+    });
+
+    it('agrees with DataService.calculateApyForTranche', () => {
+        // The two used to carry separate copies of the constant AND separate
+        // (one of them wrong) formulas.
+        for (const r of [0.001, 0.003, 0.01]) {
+            expect(locking().calculateApy(r)).toBe(epochRateToApy(r));
+        }
+    });
+});

package/src/services/Locking/locking.ts

@@ -17,6 +17,7 @@ import {
     IUserManagerAbi,
     IUserManagerAbi__factory,
 } from '../../contracts';
+import { epochRateToApy } from '../../domain/rates';
 import { SdkConfig } from '../../sdk-config';
 import {
     getAllTrancheConfigurationsQuery,
@@ -265,9 +266,22 @@ export class KSULocking {
         );
     }
 
+    /**
+     * A per-epoch interest rate compounded into an APY.
+     *
+     * This used to read `(1 + epochInterestRate) ^ (EPOCHS_IN_YEAR - 1)`.
+     * `^` is JavaScript's BITWISE XOR, not exponentiation: both operands were
+     * coerced to int32, so for a realistic epoch rate of ~0.003 it computed
+     * `1 ^ 51` and returned the constant 50 — a 5000% APY — for every tranche,
+     * regardless of its rate. Its only caller,
+     * `calculateUserLockProjectedProtocolFeeRewards`, multiplied that by each
+     * tranche balance, so its projection was nonsense rather than merely
+     * imprecise.
+     *
+     * Now the same compounding every other rate in the SDK uses.
+     */
     calculateApy(epochInterestRate: number): number {
-        const EPOCHS_IN_YEAR = 52.17857;
-        return (1 + epochInterestRate) ^ (EPOCHS_IN_YEAR - 1);
+        return epochRateToApy(epochInterestRate);
     }
 
     async getUserLocks(userAddress: string): Promise<UserLock[]> {