@kasufinance/kasu-sdk 1.0.4 → 2.1.0

package/dist/tests/sample.test.js

@@ -13,20 +13,25 @@ import { SdkConfig } from '../sdk-config';
 test('subgraphCall', () => __awaiter(void 0, void 0, void 0, function* () {
     const provider = new ethers.providers.JsonRpcProvider('https://sepolia.base.org');
     const wallet = new ethers.Wallet('dddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd', provider);
-    const config = new SdkConfig('https://api.studio.thegraph.com/query/63245/kasu-wip-sepolia/version/latest', 'https://api.goldsky.com/api/public/project_cm9t3064xeuyn01tgctdo3c17/subgraphs/kasu-plume/prod/gn', {
-        IKSULocking: '0x529A81c11ab6176c5E88670d293BB771800066a2',
-        IKSULockBonus: '0xBBfFd5F744156FFc526df12F5e09dC7b208Be740',
-        KSUToken: '0xa0f698Feb9Bc2BeA6E85eb071D5E3F59dc5bC56b',
-        UserManager: '0xA788e9223fDd7c9Db91Ef133BbeB73515c174773',
-        LendingPoolManager: '0xc074Aaf2565aae18db2c7498ee1387610a809F40',
-        KasuAllowList: '0xaE94F9D187c9eA649ADd4966340831F7cc62B69c',
-        SystemVariables: '0xB174a3240B23e595e90bC2736A5b8ec674Cba73A',
-        UserLoyaltyRewards: '0x259631CE76FD9F65296549Cd81232aa59D53Dd0c',
-        KsuPrice: '0x2027192aCFB4810Ad734A212F19d7030F698aCE3',
-        ClearingCoordinator: '0x2027192aCFB4810Ad734A212F19d7030F698aCE3',
-        KasuNFTs: '0x0000000000000000000000000000000000000000',
-        ExternalTVL: '0x0000000000000000000000000000000000000000',
-    }, 'https://kasu-finance.directus.app', ['']);
+    const config = new SdkConfig({
+        subgraphUrl: 'https://api.studio.thegraph.com/query/63245/kasu-wip-sepolia/version/latest',
+        contracts: {
+            IKSULocking: '0x529A81c11ab6176c5E88670d293BB771800066a2',
+            IKSULockBonus: '0xBBfFd5F744156FFc526df12F5e09dC7b208Be740',
+            KSUToken: '0xa0f698Feb9Bc2BeA6E85eb071D5E3F59dc5bC56b',
+            UserManager: '0xA788e9223fDd7c9Db91Ef133BbeB73515c174773',
+            LendingPoolManager: '0xc074Aaf2565aae18db2c7498ee1387610a809F40',
+            KasuAllowList: '0xaE94F9D187c9eA649ADd4966340831F7cc62B69c',
+            SystemVariables: '0xB174a3240B23e595e90bC2736A5b8ec674Cba73A',
+            UserLoyaltyRewards: '0x259631CE76FD9F65296549Cd81232aa59D53Dd0c',
+            KsuPrice: '0x2027192aCFB4810Ad734A212F19d7030F698aCE3',
+            ClearingCoordinator: '0x2027192aCFB4810Ad734A212F19d7030F698aCE3',
+            KasuNFTs: '0x0000000000000000000000000000000000000000',
+            ExternalTVL: '0x0000000000000000000000000000000000000000',
+        },
+        directusUrl: 'https://kasu-finance.directus.app',
+        UNUSED_LENDING_POOL_IDS: [''],
+    });
     const sdk = new KasuSdk(config, wallet);
     console.log(yield sdk.UserLending.getUserApyBonus('0xef38c432682ab49095e00442aaa354e955ac03a5'));
 }));

package/dist/tests/sample.test.js.map

@@ -1 +1 @@
-{"version":3,"file":"sample.test.js","sourceRoot":"","sources":["../../src/tests/sample.test.ts"],"names":[],"mappings":";;;;;;;;;AAAA,OAAO,KAAK,MAAM,MAAM,QAAQ,CAAC;AAEjC,OAAO,EAAE,OAAO,EAAE,MAAM,IAAI,CAAC;AAC7B,OAAO,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAE1C,IAAI,CAAC,cAAc,EAAE,GAAS,EAAE;IAC5B,MAAM,QAAQ,GAAG,IAAI,MAAM,CAAC,SAAS,CAAC,eAAe,CACjD,0BAA0B,CAC7B,CAAC;IAEF,MAAM,MAAM,GAAG,IAAI,MAAM,CAAC,MAAM,CAC5B,kEAAkE,EAClE,QAAQ,CACX,CAAC;IACF,MAAM,MAAM,GAAG,IAAI,SAAS,CACxB,6EAA6E,EAC7E,mGAAmG,EACnG;QACI,WAAW,EAAE,4CAA4C;QACzD,aAAa,EAAE,4CAA4C;QAC3D,QAAQ,EAAE,4CAA4C;QACtD,WAAW,EAAE,4CAA4C;QACzD,kBAAkB,EAAE,4CAA4C;QAChE,aAAa,EAAE,4CAA4C;QAC3D,eAAe,EAAE,4CAA4C;QAC7D,kBAAkB,EAAE,4CAA4C;QAChE,QAAQ,EAAE,4CAA4C;QACtD,mBAAmB,EAAE,4CAA4C;QACjE,QAAQ,EAAE,4CAA4C;QACtD,WAAW,EAAE,4CAA4C;KAC5D,EAED,mCAAmC,EAEnC,CAAC,EAAE,CAAC,CACP,CAAC;IACF,MAAM,GAAG,GAAG,IAAI,OAAO,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAExC,OAAO,CAAC,GAAG,CACP,MAAM,GAAG,CAAC,WAAW,CAAC,eAAe,CACjC,4CAA4C,CAC/C,CACJ,CAAC;AACN,CAAC,CAAA,CAAC,CAAC"}
+{"version":3,"file":"sample.test.js","sourceRoot":"","sources":["../../src/tests/sample.test.ts"],"names":[],"mappings":";;;;;;;;;AAAA,OAAO,KAAK,MAAM,MAAM,QAAQ,CAAC;AAEjC,OAAO,EAAE,OAAO,EAAE,MAAM,IAAI,CAAC;AAC7B,OAAO,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAE1C,IAAI,CAAC,cAAc,EAAE,GAAS,EAAE;IAC5B,MAAM,QAAQ,GAAG,IAAI,MAAM,CAAC,SAAS,CAAC,eAAe,CACjD,0BAA0B,CAC7B,CAAC;IAEF,MAAM,MAAM,GAAG,IAAI,MAAM,CAAC,MAAM,CAC5B,kEAAkE,EAClE,QAAQ,CACX,CAAC;IACF,MAAM,MAAM,GAAG,IAAI,SAAS,CAAC;QACzB,WAAW,EACP,6EAA6E;QACjF,SAAS,EAAE;YACP,WAAW,EAAE,4CAA4C;YACzD,aAAa,EAAE,4CAA4C;YAC3D,QAAQ,EAAE,4CAA4C;YACtD,WAAW,EAAE,4CAA4C;YACzD,kBAAkB,EAAE,4CAA4C;YAChE,aAAa,EAAE,4CAA4C;YAC3D,eAAe,EAAE,4CAA4C;YAC7D,kBAAkB,EAAE,4CAA4C;YAChE,QAAQ,EAAE,4CAA4C;YACtD,mBAAmB,EAAE,4CAA4C;YACjE,QAAQ,EAAE,4CAA4C;YACtD,WAAW,EAAE,4CAA4C;SAC5D;QACD,WAAW,EAAE,mCAAmC;QAChD,uBAAuB,EAAE,CAAC,EAAE,CAAC;KAChC,CAAC,CAAC;IACH,MAAM,GAAG,GAAG,IAAI,OAAO,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAExC,OAAO,CAAC,GAAG,CACP,MAAM,GAAG,CAAC,WAAW,CAAC,eAAe,CACjC,4CAA4C,CAC/C,CACJ,CAAC;AACN,CAAC,CAAA,CAAC,CAAC"}

package/dist/utils/deployment-mode.d.ts

@@ -0,0 +1,6 @@
+import { SdkConfig } from '../sdk-config';
+/**
+ * Check if the SDK is configured for a Lite deployment.
+ * Lite deployments don't have KSU token, locking, or loyalty features.
+ */
+export declare function isLiteDeployment(config: SdkConfig): boolean;

package/dist/utils/deployment-mode.js

@@ -0,0 +1,8 @@
+/**
+ * Check if the SDK is configured for a Lite deployment.
+ * Lite deployments don't have KSU token, locking, or loyalty features.
+ */
+export function isLiteDeployment(config) {
+    return config.isLiteDeployment;
+}
+//# sourceMappingURL=deployment-mode.js.map

package/dist/utils/deployment-mode.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"deployment-mode.js","sourceRoot":"","sources":["../../src/utils/deployment-mode.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAC,MAAiB;IAC9C,OAAO,MAAM,CAAC,gBAAgB,CAAC;AACnC,CAAC"}

package/package.json

@@ -1,10 +1,10 @@
 {
     "name": "@kasufinance/kasu-sdk",
-    "version": "1.0.4",
+    "version": "2.1.0",
     "description": "",
     "main": "dist/bundle.cjs.js",
     "module": "dist/bundle.esm.js",
-    "types": "dist/types/index.d.ts",
+    "types": "dist/index.d.ts",
     "scripts": {
         "test": "jest --config=jest-config.ts",
         "build-tc": "typechain --target ethers-v5 --out-dir src/contracts './abis/*.json'",

package/src/facade/chain-configs.ts

@@ -0,0 +1,93 @@
+import { ChainConfigEntry } from './types';
+
+/**
+ * Built-in chain configurations for Kasu-supported networks.
+ *
+ * Usage:
+ * ```ts
+ * import { CHAIN_CONFIGS } from '@kasufinance/kasu-sdk';
+ * const base = CHAIN_CONFIGS.base;
+ * ```
+ */
+export const CHAIN_CONFIGS: Record<'base' | 'xdc' | 'plume', ChainConfigEntry> = {
+    base: {
+        chainId: 8453,
+        name: 'Base Mainnet',
+        isLiteDeployment: false,
+        contracts: {
+            KSUToken: '0x5D9b878744dbe721a3f33A60a6b102E289CeADBA',
+            IKSULocking: '0xB145C061684C701c2C018A3f322aa14F5A553CE1',
+            IKSULockBonus: '0xEEDE30AcF16caFf49c1a48F75185C67Be2e20B40',
+            LendingPoolManager: '0xE1Be322323a412579b4A09fB08ff4bfcA12096B5',
+            UserManager: '0x5Dc8D315a80fd99AbEF0f327B9a52a3FBC3C93f3',
+            KasuAllowList: '0x807A7e119EBf0282420b5Ca0e0056c0525cBf8BB',
+            SystemVariables: '0x193Bb02A24F5562b58fEB86550e6f09Bb6c41f69',
+            KsuPrice: '0x221a54CbbD5f490Bd8e77CF36acBA4B1304E5c1b',
+            UserLoyaltyRewards: '0xB4784f69Bb1F1076F50907cB0a815908a719D635',
+            ClearingCoordinator: '0x2cF12A6d91fa4bEB5a4C17589a03e78F88f57DE2',
+            KasuNFTs: '0x4946fF5f1a6550524C425479022D50446AA2968E',
+            ExternalTVL: '0x662379FEBb3e4F91400B5f7d4f7F7ce4699F3c9F',
+        },
+        subgraphUrl:
+            'https://api.goldsky.com/api/public/project_cmgzlpxm300765np2a19421om/subgraphs/kasu-base/v1.0.13/gn',
+        directusUrl: 'https://kasu-finance.directus.app/',
+        unusedPoolIds: [],
+        poolMetadataMapping: undefined,
+    },
+
+    xdc: {
+        chainId: 50,
+        name: 'XDC Mainnet',
+        isLiteDeployment: true,
+        contracts: {
+            // No KSUToken on Lite deployments
+            IKSULocking: '0x7fF469f8c5fba92A9051B8D28794CBb891760e81',
+            IKSULockBonus: '0x7cc1434EfA50301Fdd56B7c5c6fF7e30Dc20C55c',
+            LendingPoolManager: '0xa46143db92aBe5bB1f61d13d8C1cCd50fc40Ca10',
+            UserManager: '0x9b57dF89e59235f0481A5Fae942302c8831e1B81',
+            KasuAllowList: '0x32c1Ff5FbBe6D28503ddc46E5001C0D13d6E9B2A',
+            SystemVariables: '0x34d17c9DD1f31Fb34757DE923EC083601d0eDFFe',
+            KsuPrice: '0x666b589933965bF8B378eD973f0404b6cae0eb52',
+            UserLoyaltyRewards: '0xb95834C5610A178be9065Dd1EF78258D29879CDb',
+            ClearingCoordinator: '0xAF0a66953Eba1c5353eB7425b398B213Bb2c6121',
+            // No KasuNFTs on Lite deployments
+            ExternalTVL: '0xCCB4156964377CF36441f3775A2A800dbeCB8094',
+        },
+        subgraphUrl:
+            'https://api.goldsky.com/api/public/project_cmgzlpxm300765np2a19421om/subgraphs/kasu-xdc/v1.0.0/gn',
+        directusUrl: 'https://kasu-finance.directus.app/',
+        unusedPoolIds: [],
+        poolMetadataMapping: {
+            '0x20f42fb45f91657acf9528b99a5a16d0229c7800':
+                '0xc987350716fe4a7d674c3591c391d29eba26b8ce',
+            '0x3b7cb493aa22f731db2ab424d918e7375e00f6a9':
+                '0x03f93c8caa9a82e000d35673ba34a4c0e6e117a2',
+            '0xeda50c91a8c4ca8a83652b8542c0b3bd00a71fad':
+                '0xc347a9e4aec8c8d11a149d2907deb2bf23b81c6f',
+        },
+    },
+
+    plume: {
+        chainId: 98866,
+        name: 'Plume Mainnet',
+        isLiteDeployment: true,
+        contracts: {
+            // Placeholder — update when Plume contracts are deployed
+            IKSULocking: '',
+            IKSULockBonus: '',
+            LendingPoolManager: '',
+            UserManager: '',
+            KasuAllowList: '',
+            SystemVariables: '',
+            KsuPrice: '',
+            UserLoyaltyRewards: '',
+            ClearingCoordinator: '',
+            ExternalTVL: '',
+        },
+        subgraphUrl:
+            'https://api.goldsky.com/api/public/project_cmgzlpxm300765np2a19421om/subgraphs/kasu-plume/prod',
+        directusUrl: 'https://kasu-finance.directus.app/',
+        unusedPoolIds: [],
+        poolMetadataMapping: undefined,
+    },
+};

package/src/facade/deposits.ts

@@ -0,0 +1,102 @@
+import { ContractTransaction } from 'ethers';
+
+import { UserLending } from '../services/UserLending/user-lending';
+
+import { DepositParams, KycParams, WithdrawParams } from './types';
+
+/**
+ * High-level facade for deposit and withdrawal operations.
+ *
+ * Integrators use this to submit on-chain transactions without
+ * worrying about internal encoding details.
+ */
+export class DepositsFacade {
+    constructor(
+        private _userLending: UserLending,
+        private _chainId: string,
+    ) {}
+
+    /**
+     * Submit a deposit request.
+     *
+     * The integrator must first obtain a KYC signature via the Nexera flow
+     * using the params from `buildKycParams()`.
+     *
+     * ```ts
+     * const kycParams = kasu.deposits.buildKycParams('0xUser...');
+     * // ... obtain kycSignature from your backend via Nexera ...
+     * const tx = await kasu.deposits.deposit({
+     *   poolId: '0x...',
+     *   trancheId: '0x...',
+     *   amount: parseUnits('1000', 6),
+     *   kycSignature: { blockExpiration, signature },
+     * });
+     * ```
+     */
+    async deposit(params: DepositParams): Promise<ContractTransaction> {
+        return await this._userLending.requestDepositWithKyc(
+            params.poolId,
+            params.trancheId,
+            params.amount,
+            params.swapData ?? '0x',
+            params.fixedTermConfigId ?? 0,
+            params.depositData ?? '0x',
+            params.kycSignature,
+            params.ethValue ?? '0',
+        );
+    }
+
+    /**
+     * Submit a withdrawal request for a specific USDC amount.
+     */
+    async withdraw(params: WithdrawParams): Promise<ContractTransaction> {
+        return await this._userLending.requestWithdrawalInUSDC(
+            params.poolId,
+            params.trancheId,
+            params.amount,
+        );
+    }
+
+    /**
+     * Withdraw the entire balance from a tranche.
+     */
+    async withdrawMax(
+        poolId: string,
+        trancheId: string,
+        userAddress: string,
+    ): Promise<ContractTransaction> {
+        return await this._userLending.requestWithdrawalMax(
+            poolId,
+            trancheId,
+            userAddress,
+        );
+    }
+
+    /**
+     * Build KYC signature parameters for the Nexera verification flow.
+     *
+     * The integrator is responsible for sending these to their backend,
+     * which obtains the signature from Nexera's signing service.
+     */
+    buildKycParams(userAddress: `0x${string}`): KycParams {
+        return this._userLending.buildKycSignatureParams(
+            userAddress,
+            this._chainId,
+        );
+    }
+
+    /**
+     * Check whether the pool is currently in a clearing period
+     * (deposits/withdrawals are temporarily paused).
+     */
+    async isClearingPending(poolId: string): Promise<boolean> {
+        return await this._userLending.isClearingPending(poolId);
+    }
+
+    /**
+     * Get the current epoch number.
+     */
+    async getCurrentEpoch(): Promise<string> {
+        return await this._userLending.getCurrentEpoch();
+    }
+}

package/src/facade/index.ts

@@ -0,0 +1,26 @@
+// Main entry point
+export { Kasu } from './kasu';
+
+// Individual facades (for advanced composition)
+export { StrategiesFacade } from './strategies';
+export { DepositsFacade } from './deposits';
+export { PortfolioFacade } from './user-portfolio';
+
+// Chain configurations
+export { CHAIN_CONFIGS } from './chain-configs';
+
+// All facade types
+export type {
+    SupportedChain,
+    ChainConfigEntry,
+    KasuOptions,
+    Strategy,
+    StrategyTranche,
+    FixedTermOption,
+    DepositParams,
+    WithdrawParams,
+    DepositLimits,
+    KycParams,
+    UserPositions,
+    PlatformStats,
+} from './types';

package/src/facade/kasu.ts

@@ -0,0 +1,144 @@
+import { KasuSdk } from '../kasu-sdk';
+import { SdkConfig } from '../sdk-config';
+
+import { CHAIN_CONFIGS } from './chain-configs';
+import { DepositsFacade } from './deposits';
+import { StrategiesFacade } from './strategies';
+import { ChainConfigEntry, KasuOptions, SupportedChain } from './types';
+import { PortfolioFacade } from './user-portfolio';
+
+/**
+ * High-level entry point for external integrators.
+ *
+ * Provides three domain facades — `strategies`, `deposits`, `portfolio` — and
+ * exposes the underlying `KasuSdk` services via `.services` for power-users.
+ *
+ * ```ts
+ * import { Kasu } from '@kasufinance/kasu-sdk';
+ *
+ * const kasu = Kasu.create({ chain: 'base', signerOrProvider: provider });
+ *
+ * // Browse strategies
+ * const strategies = await kasu.strategies.getAll();
+ *
+ * // Deposit
+ * const tx = await kasu.deposits.deposit({ poolId, trancheId, amount, kycSignature });
+ *
+ * // User positions
+ * const positions = await kasu.portfolio.getPositions(userAddress);
+ * ```
+ */
+export class Kasu {
+    /** Browse lending strategies, APY, capacity. */
+    public readonly strategies: StrategiesFacade;
+    /** Deposit, withdraw, KYC helpers. */
+    public readonly deposits: DepositsFacade;
+    /** User positions, yields, transaction history. */
+    public readonly portfolio: PortfolioFacade;
+
+    private readonly _sdk: KasuSdk;
+    private readonly _chainConfig: ChainConfigEntry;
+
+    private constructor(
+        sdk: KasuSdk,
+        chainConfig: ChainConfigEntry,
+    ) {
+        this._sdk = sdk;
+        this._chainConfig = chainConfig;
+
+        this.strategies = new StrategiesFacade(
+            sdk.DataService,
+            sdk.UserLending,
+        );
+
+        this.deposits = new DepositsFacade(
+            sdk.UserLending,
+            chainConfig.chainId.toString(),
+        );
+
+        this.portfolio = new PortfolioFacade(
+            sdk.DataService,
+            sdk.UserLending,
+            sdk.Portfolio,
+        );
+    }
+
+    /**
+     * Create a Kasu instance with built-in chain config.
+     *
+     * ```ts
+     * // Minimal setup — uses built-in Base mainnet config
+     * const kasu = Kasu.create({ chain: 'base', signerOrProvider: provider });
+     *
+     * // Custom config override
+     * const kasu = Kasu.create({
+     *   chain: 'base',
+     *   signerOrProvider: signer,
+     *   configOverrides: { UNUSED_LENDING_POOL_IDS: ['0x...'] },
+     * });
+     *
+     * // Fully custom chain
+     * const kasu = Kasu.create({
+     *   chain: { chainId: 123, name: 'MyChain', ... },
+     *   signerOrProvider: provider,
+     * });
+     * ```
+     */
+    static create(options: KasuOptions): Kasu {
+        const chainConfig = resolveChainConfig(options.chain);
+        const overrides = options.configOverrides ?? {};
+
+        const sdkConfig = new SdkConfig({
+            subgraphUrl: overrides.subgraphUrl ?? chainConfig.subgraphUrl,
+            // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+            contracts: overrides.contracts ?? chainConfig.contracts,
+            directusUrl:
+                overrides.directusUrl ?? chainConfig.directusUrl,
+            UNUSED_LENDING_POOL_IDS:
+                overrides.UNUSED_LENDING_POOL_IDS ??
+                chainConfig.unusedPoolIds,
+            isLiteDeployment:
+                overrides.isLiteDeployment ?? chainConfig.isLiteDeployment,
+            poolMetadataMapping:
+                overrides.poolMetadataMapping ??
+                chainConfig.poolMetadataMapping,
+        });
+
+        const sdk = new KasuSdk(sdkConfig, options.signerOrProvider);
+        return new Kasu(sdk, chainConfig);
+    }
+
+    /**
+     * Access the underlying `KasuSdk` services for advanced use cases.
+     *
+     * ```ts
+     * const locks = await kasu.services.Locking.getUserLocks(address);
+     * ```
+     */
+    get services(): KasuSdk {
+        return this._sdk;
+    }
+
+    /** The resolved chain configuration. */
+    get chainConfig(): ChainConfigEntry {
+        return this._chainConfig;
+    }
+
+    /** Whether this deployment has KSU token / locking features. */
+    get isLiteDeployment(): boolean {
+        return this._chainConfig.isLiteDeployment;
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function resolveChainConfig(
+    chain: SupportedChain | ChainConfigEntry,
+): ChainConfigEntry {
+    if (typeof chain === 'string') {
+        return CHAIN_CONFIGS[chain];
+    }
+    return chain;
+}

package/src/facade/strategies.ts

@@ -0,0 +1,119 @@
+import { DataService } from '../services/DataService/data-service';
+import { PoolOverview } from '../services/DataService/types';
+import { UserLending } from '../services/UserLending/user-lending';
+
+import {
+    DepositLimits,
+    FixedTermOption,
+    PlatformStats,
+    Strategy,
+    StrategyTranche,
+} from './types';
+
+/**
+ * High-level facade for browsing Kasu lending strategies (pools).
+ *
+ * Handles epoch fetching internally so callers never need to know about epochs.
+ */
+export class StrategiesFacade {
+    constructor(
+        private _dataService: DataService,
+        private _userLending: UserLending,
+    ) {}
+
+    /**
+     * Fetch all active lending strategies.
+     *
+     * ```ts
+     * const strategies = await kasu.strategies.getAll();
+     * ```
+     */
+    async getAll(poolIds?: string[]): Promise<Strategy[]> {
+        const epochId = await this._userLending.getCurrentEpoch();
+        const pools = await this._dataService.getPoolOverview(epochId, poolIds);
+        return pools.map((pool) => this.mapPoolToStrategy(pool));
+    }
+
+    /**
+     * Fetch a single strategy by pool ID. Returns `null` if not found.
+     */
+    async getById(poolId: string): Promise<Strategy | null> {
+        const results = await this.getAll([poolId]);
+        return results[0] ?? null;
+    }
+
+    /**
+     * Aggregate platform statistics (TVL, loans, yield, loss rate).
+     */
+    async getPlatformStats(): Promise<PlatformStats> {
+        const epochId = await this._userLending.getCurrentEpoch();
+        const pools = await this._dataService.getPoolOverview(epochId);
+        return await this._dataService.getLendingTotals(pools);
+    }
+
+    /**
+     * Calculate deposit limits for a specific tranche.
+     *
+     * @param tranche - A `StrategyTranche` from `getAll()` or `getById()`.
+     * @returns min/max/capacity in ether-formatted USDC strings.
+     */
+    calculateDepositLimits(tranche: StrategyTranche): DepositLimits {
+        const raw = tranche._raw;
+        const min =
+            parseFloat(raw.minimumDeposit) < 1
+                ? '1'
+                : raw.minimumDeposit;
+
+        const max = parseFloat(raw.maximumDeposit) > parseFloat(raw.poolCapacity)
+            ? raw.poolCapacity
+            : raw.maximumDeposit;
+
+        return {
+            min,
+            max,
+            availableCapacity: raw.poolCapacity,
+        };
+    }
+
+    // ------------------------------------------------------------------
+    // Private helpers
+    // ------------------------------------------------------------------
+
+    private mapPoolToStrategy(pool: PoolOverview): Strategy {
+        const tranches: StrategyTranche[] = pool.tranches.map((t) => ({
+            id: t.id,
+            name: t.name,
+            apy: parseFloat(t.apy),
+            minApy: parseFloat(t.minApy),
+            maxApy: parseFloat(t.maxApy),
+            minimumDeposit: t.minimumDeposit,
+            maximumDeposit: t.maximumDeposit,
+            availableCapacity: t.poolCapacity,
+            fixedTermOptions: t.fixedTermConfig.map(
+                (ftd): FixedTermOption => ({
+                    configId: ftd.configId,
+                    apy: parseFloat(ftd.apy),
+                    epochLockDuration: ftd.epochLockDuration,
+                }),
+            ),
+            _raw: t,
+        }));
+
+        return {
+            id: pool.id,
+            name: pool.poolName,
+            description: pool.description,
+            isActive: pool.isActive,
+            apy: pool.apy,
+            tvl: pool.totalValueLocked,
+            availableCapacity: pool.poolCapacity,
+            capacityUtilisation: pool.poolCapacityPercentage,
+            tranches,
+            assetClass: pool.assetClass,
+            apyStructure: pool.poolApyStructure,
+            thumbnailUrl: pool.thumbnailImageUrl,
+            bannerUrl: pool.bannerImageUrl,
+            _raw: pool,
+        };
+    }
+}