@kasufinance/kasu-sdk 2.4.2 → 2.6.0

package/src/facade/config.test.ts

@@ -0,0 +1,265 @@
+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',
+        );
+    });
+});

package/src/facade/deposits.ts

@@ -14,8 +14,30 @@ export class DepositsFacade {
     constructor(
         private _userLending: UserLending,
         private _chainId: string,
+        /**
+         * True when the SDK holds a Provider rather than a Signer. Optional and
+         * defaulting to false so constructing this facade directly keeps
+         * working; `Kasu` always passes it.
+         */
+        private _isReadOnly = false,
     ) {}
 
+    /**
+     * Refuse a write BEFORE touching the contract.
+     *
+     * ethers would throw its own "sending a transaction requires a signer" a
+     * few frames deeper, after the params have been encoded — a message that
+     * says nothing about how to get a signer onto THIS object. Failing here
+     * names the fix.
+     */
+    private assertWritable(): void {
+        if (this._isReadOnly) {
+            throw new Error(
+                'Kasu: this instance is read-only; call kasu.connect(signer) first',
+            );
+        }
+    }
+
     /**
      * Submit a deposit request.
      *
@@ -34,6 +56,7 @@ export class DepositsFacade {
      * ```
      */
     async deposit(params: DepositParams): Promise<ContractTransaction> {
+        this.assertWritable();
         return await this._userLending.requestDepositWithKyc(
             params.poolId,
             params.trancheId,
@@ -50,6 +73,7 @@ export class DepositsFacade {
      * Submit a withdrawal request for a specific stable asset amount.
      */
     async withdraw(params: WithdrawParams): Promise<ContractTransaction> {
+        this.assertWritable();
         return await this._userLending.requestWithdrawalInAsset(
             params.poolId,
             params.trancheId,
@@ -65,6 +89,7 @@ export class DepositsFacade {
         trancheId: string,
         userAddress: string,
     ): Promise<ContractTransaction> {
+        this.assertWritable();
         return await this._userLending.requestWithdrawalMax(
             poolId,
             trancheId,

package/src/{tests → facade}/facade.test.ts

@@ -1,8 +1,20 @@
-import { CHAIN_CONFIGS } from '../facade/chain-configs';
-import { DepositsFacade } from '../facade/deposits';
-import { Kasu } from '../facade/kasu';
-import { StrategiesFacade } from '../facade/strategies';
-import { PortfolioFacade } from '../facade/user-portfolio';
+/**
+ * Offline facade specs — a mock provider and pure helpers, no network. Moved
+ * here from `src/tests/` so it runs beside the code it covers, and so the
+ * opt-in `LIVE_TESTS` gate on `src/tests/` does not take it out of CI.
+ */
+import { DataService } from '../services/DataService/data-service';
+import { NO_DIRECTUS_URL_MESSAGE } from '../services/DataService/directus-client';
+import { Portfolio } from '../services/Portfolio/portfolio';
+import { UserRequestStatus } from '../services/UserLending/subgraph-types';
+import { UserRequest } from '../services/UserLending/types';
+import { UserLending } from '../services/UserLending/user-lending';
+
+import { CHAIN_CONFIGS } from './chain-configs';
+import { DepositsFacade } from './deposits';
+import { Kasu } from './kasu';
+import { StrategiesFacade } from './strategies';
+import { PortfolioFacade } from './user-portfolio';
 
 // ---------------------------------------------------------------------------
 // Chain configs
@@ -47,6 +59,18 @@ describe('CHAIN_CONFIGS', () => {
         }
     });
 
+    it('plume points at the LEGACY goldsky project its frozen history is on', () => {
+        // Plume was indexed before the live chains moved to the current
+        // project; the same path under that project returns HTTP 404, so the
+        // retired deployment's history is only readable at this spelling —
+        // note the `/gn` suffix the current project's URLs do not carry.
+        const projectOf = (url: string): string => url.split('/')[5] ?? '';
+        expect(projectOf(CHAIN_CONFIGS.plume.subgraphUrl)).not.toBe(
+            projectOf(CHAIN_CONFIGS.base.subgraphUrl),
+        );
+        expect(CHAIN_CONFIGS.plume.subgraphUrl.endsWith('/gn')).toBe(true);
+    });
+
     it('xdc should have poolMetadataMapping', () => {
         const mapping = CHAIN_CONFIGS.xdc.poolMetadataMapping;
         expect(mapping).toBeDefined();
@@ -126,6 +150,35 @@ describe('Kasu.create()', () => {
         expect(kasu).toBeInstanceOf(Kasu);
     });
 
+    it('constructs without a directusUrl — on-chain data does not need one', () => {
+        // `createDirectus('')` throws `Invalid URL`, so an SDK configured
+        // without the (documented-optional) CMS URL used to be
+        // unconstructable rather than merely CMS-less.
+        const kasu = Kasu.create({
+            chain: 'base',
+            signerOrProvider: mockProvider as never,
+            configOverrides: { directusUrl: '' },
+        });
+
+        expect(kasu).toBeInstanceOf(Kasu);
+        expect(kasu.services.DataService).toBeDefined();
+        expect(kasu.services.UserLending).toBeDefined();
+    });
+
+    it('refuses a CMS-only call clearly when no directusUrl is configured', async () => {
+        const kasu = Kasu.create({
+            chain: 'base',
+            signerOrProvider: mockProvider as never,
+            configOverrides: { directusUrl: '' },
+        });
+
+        // A sentence naming what to configure, not a null dereference thrown
+        // from inside the vendor SDK.
+        await expect(
+            kasu.services.DataService.getPlatformOverview(),
+        ).rejects.toThrow(NO_DIRECTUS_URL_MESSAGE);
+    });
+
     it('should expose the underlying KasuSdk via .services', () => {
         const kasu = Kasu.create({
             chain: 'base',
@@ -196,6 +249,59 @@ describe('StrategiesFacade.calculateDepositLimits()', () => {
     });
 });
 
+// ---------------------------------------------------------------------------
+// PortfolioFacade.getRequestStates()
+// ---------------------------------------------------------------------------
+
+describe('PortfolioFacade.getRequestStates()', () => {
+    it('maps the transaction history through deriveRequestState', async () => {
+        const requests: UserRequest[] = [
+            makeUserRequest({ id: 'req-1' }),
+            makeUserRequest({
+                id: 'req-2',
+                requestType: 'Withdrawal',
+                status: UserRequestStatus.PROCESSED,
+                canCancel: false,
+                acceptedAmount: '100',
+            }),
+        ];
+        const userLending = {
+            getCurrentEpoch: (): Promise<string> => Promise.resolve('42'),
+            getUserRequests: (): Promise<UserRequest[]> =>
+                Promise.resolve(requests),
+        } as unknown as UserLending;
+
+        const facade = new PortfolioFacade(
+            {} as unknown as DataService,
+            userLending,
+            {} as unknown as Portfolio,
+        );
+
+        const states = await facade.getRequestStates('0xuser');
+
+        expect(states.map((s) => s.id)).toEqual(['req-1', 'req-2']);
+        expect(states[0].statusCode).toBe('pending');
+        expect(states[0].amount).toBe(100);
+        expect(states[1].statusCode).toBe('complete');
+        expect(states[1].amount).toBe(-100);
+    });
+
+    it('returns an empty list for a wallet with no history', async () => {
+        const userLending = {
+            getCurrentEpoch: (): Promise<string> => Promise.resolve('42'),
+            getUserRequests: (): Promise<UserRequest[]> => Promise.resolve([]),
+        } as unknown as UserLending;
+
+        const facade = new PortfolioFacade(
+            {} as unknown as DataService,
+            userLending,
+            {} as unknown as Portfolio,
+        );
+
+        await expect(facade.getRequestStates('0xuser')).resolves.toEqual([]);
+    });
+});
+
 // ---------------------------------------------------------------------------
 // Type exports — verify key facade types are importable
 // ---------------------------------------------------------------------------
@@ -243,3 +349,26 @@ function makeTranche(raw: {
         },
     } as never;
 }
+
+
+function makeUserRequest(overrides: Partial<UserRequest> = {}): UserRequest {
+    return {
+        id: 'req-1',
+        userId: '0xuser',
+        lendingPool: { id: '0xpool', name: 'Pool', tranches: [{ orderId: '0' }] },
+        requestType: 'Deposit',
+        trancheId: '0xtranche',
+        trancheName: 'Senior',
+        requestedAmount: '100',
+        acceptedAmount: '0',
+        rejectedAmount: '0',
+        timestamp: 1_700_000_000,
+        status: UserRequestStatus.REQUESTED,
+        canCancel: true,
+        events: [],
+        nftId: '',
+        apy: '0',
+        fixedTermConfig: undefined,
+        ...overrides,
+    };
+}

package/src/facade/index.ts

@@ -9,10 +9,14 @@ export { PortfolioFacade } from './user-portfolio';
 // Chain configurations
 export { CHAIN_CONFIGS } from './chain-configs';
 
+// Directus-backed helpers (I/O — not part of `domain/`)
+export { fetchUnusedPoolIds } from './unused-pool-ids';
+
 // All facade types
 export type {
     SupportedChain,
     ChainConfigEntry,
+    StableAsset,
     KasuOptions,
     Strategy,
     StrategyTranche,