@kasufinance/kasu-sdk 1.0.4 → 2.2.0

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,
+        };
+    }
+}

package/src/facade/types.ts

@@ -0,0 +1,168 @@
+import { BigNumberish, BytesLike } from 'ethers';
+
+import { ContractAddresses, SdkConfigOptions } from '../sdk-config';
+import { LendingTotals, PoolOverview, TrancheData } from '../services/DataService/types';
+import {
+    PortfolioLendingPool,
+    PortfolioSummary,
+} from '../services/Portfolio/types';
+
+// ---------------------------------------------------------------------------
+// Chain & SDK Configuration
+// ---------------------------------------------------------------------------
+
+export type SupportedChain = 'base' | 'xdc' | 'plume';
+
+export interface ChainConfigEntry {
+    chainId: number;
+    name: string;
+    isLiteDeployment: boolean;
+    contracts: ContractAddresses;
+    subgraphUrl: string;
+    directusUrl: string;
+    unusedPoolIds: string[];
+    poolMetadataMapping?: Record<string, string>;
+}
+
+/** 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;
+    /** Override any default config value. */
+    configOverrides?: Partial<SdkConfigOptions>;
+}
+
+// ---------------------------------------------------------------------------
+// Strategy (pool) types – integrator-friendly view of PoolOverview
+// ---------------------------------------------------------------------------
+
+export interface Strategy {
+    id: string;
+    name: string;
+    description: string;
+    isActive: boolean;
+    /** Weighted-average APY across tranches (decimal, e.g. 0.08 = 8 %). */
+    apy: number;
+    tvl: {
+        /** On-chain + off-chain total. */
+        total: string;
+        offchain: string;
+    };
+    /** Remaining capacity across all tranches. */
+    availableCapacity: string;
+    /** 0-1 utilisation ratio. */
+    capacityUtilisation: string;
+    tranches: StrategyTranche[];
+    /** Asset class label (e.g. "Tax Receivables"). */
+    assetClass: string;
+    /** Fixed or Variable. */
+    apyStructure: 'Variable' | 'Fixed';
+    /** Thumbnail image URL (empty string when Directus unavailable). */
+    thumbnailUrl: string;
+    /** Banner image URL (empty string when Directus unavailable). */
+    bannerUrl: string;
+    /** Raw `PoolOverview` for power-users who need all fields. */
+    _raw: PoolOverview;
+}
+
+export interface StrategyTranche {
+    id: string;
+    name: string;
+    /** Current base APY (decimal). */
+    apy: number;
+    minApy: number;
+    maxApy: number;
+    /** Minimum deposit in stable asset units (ether-formatted string). */
+    minimumDeposit: string;
+    /** Maximum deposit in stable asset units (ether-formatted string). */
+    maximumDeposit: string;
+    /** Remaining tranche capacity (ether-formatted string). */
+    availableCapacity: string;
+    /** Fixed-term deposit options on this tranche. */
+    fixedTermOptions: FixedTermOption[];
+    /** Raw `TrancheData` for power-users. */
+    _raw: TrancheData;
+}
+
+export interface FixedTermOption {
+    configId: string;
+    /** Annual APY (decimal). */
+    apy: number;
+    /** Lock duration in epochs (1 epoch ≈ 1 week). */
+    epochLockDuration: string;
+}
+
+// ---------------------------------------------------------------------------
+// Deposit / Withdraw
+// ---------------------------------------------------------------------------
+
+export interface DepositParams {
+    poolId: string;
+    trancheId: string;
+    /** Amount in stable asset base units (BigNumberish). */
+    amount: BigNumberish;
+    /** KYC signature obtained from the Nexera flow. */
+    kycSignature: {
+        blockExpiration: BigNumberish;
+        signature: BytesLike;
+    };
+    /** ABI-encoded deposit data (contract acceptance). Pass `'0x'` when not needed. */
+    depositData?: BytesLike;
+    /** Fixed-term config ID. Pass `0` for variable deposits. */
+    fixedTermConfigId?: BigNumberish;
+    /** Swap calldata. Pass `'0x'` when depositing the stable asset directly. */
+    swapData?: BytesLike;
+    /** Native token value to send (e.g. for gas on some chains). Defaults to `'0'`. */
+    ethValue?: string;
+}
+
+export interface WithdrawParams {
+    poolId: string;
+    trancheId: string;
+    /** Stable asset amount to withdraw, or `'max'` to withdraw entire balance. */
+    amount: BigNumberish;
+    /** Required when `amount` is `'max'`. */
+    userAddress?: string;
+}
+
+export interface DepositLimits {
+    /** Minimum deposit (ether-formatted stable asset amount). */
+    min: string;
+    /** Maximum deposit (ether-formatted stable asset amount). */
+    max: string;
+    /** Remaining tranche capacity (ether-formatted stable asset amount). */
+    availableCapacity: string;
+}
+
+// ---------------------------------------------------------------------------
+// KYC helpers
+// ---------------------------------------------------------------------------
+
+export interface KycParams {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    contractAbi: any;
+    contractAddress: string;
+    functionName: string;
+    args: BytesLike[];
+    userAddress: string;
+    chainId: string;
+}
+
+// ---------------------------------------------------------------------------
+// Portfolio
+// ---------------------------------------------------------------------------
+
+export interface UserPositions {
+    /** Per-pool breakdown. */
+    pools: PortfolioLendingPool[];
+    /** Aggregate summary (invested, yields, APY). */
+    summary: PortfolioSummary;
+}
+
+// ---------------------------------------------------------------------------
+// Platform stats
+// ---------------------------------------------------------------------------
+
+export type PlatformStats = LendingTotals;

package/src/facade/user-portfolio.ts

@@ -0,0 +1,73 @@
+import { Provider } from '@ethersproject/providers';
+
+import { DataService } from '../services/DataService/data-service';
+import { Portfolio } from '../services/Portfolio/portfolio';
+import { UserRequest } from '../services/UserLending/types';
+import { UserLending } from '../services/UserLending/user-lending';
+
+import { UserPositions } from './types';
+
+/**
+ * High-level facade for querying a user's portfolio, positions, and history.
+ *
+ * Orchestrates DataService, UserLending, and Portfolio services so the caller
+ * only needs to provide a wallet address.
+ */
+export class PortfolioFacade {
+    constructor(
+        private _dataService: DataService,
+        private _userLending: UserLending,
+        private _portfolio: Portfolio,
+    ) {}
+
+    /**
+     * Fetch a user's complete portfolio: per-pool positions and aggregate summary.
+     *
+     * ```ts
+     * const positions = await kasu.portfolio.getPositions('0xUser...');
+     * console.log(positions.summary.current.totalLendingPoolInvestments);
+     * ```
+     *
+     * @param userAddress - Wallet address.
+     * @param provider    - Optional separate provider for balance queries (useful when the
+     *                      SDK was initialised with a Signer but you need a read-only provider).
+     */
+    async getPositions(
+        userAddress: string,
+        provider?: Provider,
+    ): Promise<UserPositions> {
+        const currentEpoch = await this._userLending.getCurrentEpoch();
+
+        const poolOverviews = await this._dataService.getPoolOverview(
+            currentEpoch,
+        );
+
+        const pools = await this._portfolio.getPortfolioLendingData(
+            userAddress,
+            poolOverviews,
+            currentEpoch,
+            provider,
+        );
+
+        const summary = await this._portfolio.getPortfolioSummary(
+            userAddress,
+            pools,
+            currentEpoch,
+        );
+
+        return { pools, summary };
+    }
+
+    /**
+     * Fetch a user's full transaction history (deposits, withdrawals, cancellations).
+     */
+    async getTransactionHistory(
+        userAddress: `0x${string}`,
+    ): Promise<UserRequest[]> {
+        const currentEpoch = await this._userLending.getCurrentEpoch();
+        return await this._userLending.getUserRequests(
+            userAddress,
+            currentEpoch,
+        );
+    }
+}

package/src/index.ts

@@ -1,27 +1,61 @@
-import { Provider } from '@ethersproject/providers';
-import { ethers, Signer } from 'ethers';
-import { GraphQLClient } from 'graphql-request';
+// ---------------------------------------------------------------------------
+// Core SDK class (low-level service access)
+// ---------------------------------------------------------------------------
+export { KasuSdk } from './kasu-sdk';
 
-import { SdkConfig } from './sdk-config';
-import { DataService } from './services/DataService/data-service';
-import { KSULocking } from './services/Locking/locking';
-import { Portfolio } from './services/Portfolio/portfolio';
-import { Swapper } from './services/Swapper/swapper';
-import { UserLending } from './services/UserLending/user-lending';
+// ---------------------------------------------------------------------------
+// Re-export config types
+// ---------------------------------------------------------------------------
+export type { ContractAddresses, SdkConfigOptions } from './sdk-config';
+export { SdkConfig } from './sdk-config';
 
-export class KasuSdk {
-    private readonly _graphClient: GraphQLClient;
-    public readonly Locking: KSULocking;
-    public readonly DataService: DataService;
-    public readonly UserLending: UserLending;
-    public readonly Portfolio: Portfolio;
-    public readonly Swapper: Swapper;
-    constructor(config: SdkConfig, signerOrProvider: Provider | Signer) {
-        this._graphClient = new GraphQLClient(config.subgraphUrl);
-        this.Locking = new KSULocking(config, signerOrProvider);
-        this.UserLending = new UserLending(config, signerOrProvider);
-        this.DataService = new DataService(config, signerOrProvider);
-        this.Portfolio = new Portfolio(config, signerOrProvider);
-        this.Swapper = new Swapper();
-    }
-}
+// ---------------------------------------------------------------------------
+// Re-export service types so consumers don't need deep imports
+// ---------------------------------------------------------------------------
+export type {
+    PoolOverview,
+    TrancheData,
+    LendingTotals,
+    PoolRepayment,
+    RiskManagement,
+    PoolDelegateProfileAndHistory,
+    PoolTranche,
+    PoolCreditMetrics,
+    BadAndDoubtfulDebts,
+    FinancialReportingDocuments,
+} from './services/DataService/types';
+
+export type {
+    UserRequest,
+    UserRequestEvent,
+    UserTrancheBalance,
+    UserPoolBalance,
+    UserApyBonus,
+    PortfolioUserTrancheBalance,
+} from './services/UserLending/types';
+
+export type {
+    PortfolioSummary,
+    PortfolioLendingPool,
+    PortfolioTranche,
+    PortfolioRewards,
+    PortfolioTrancheDepositDetails,
+} from './services/Portfolio/types';
+
+export type {
+    UserLock,
+    UserBonusData,
+    LockPeriod,
+    GQLGetLockingPeriods,
+    SystemVariables,
+} from './services/Locking/types';
+
+export type {
+    PoolOverviewDirectus,
+    PlatformOverviewDirectus,
+} from './services/DataService/directus-types';
+
+// ---------------------------------------------------------------------------
+// Re-export facade (high-level integrator API)
+// ---------------------------------------------------------------------------
+export * from './facade';

package/src/kasu-sdk.ts

@@ -0,0 +1,27 @@
+import { Provider } from '@ethersproject/providers';
+import { Signer } from 'ethers';
+import { GraphQLClient } from 'graphql-request';
+
+import { SdkConfig } from './sdk-config';
+import { DataService } from './services/DataService/data-service';
+import { KSULocking } from './services/Locking/locking';
+import { Portfolio } from './services/Portfolio/portfolio';
+import { Swapper } from './services/Swapper/swapper';
+import { UserLending } from './services/UserLending/user-lending';
+
+export class KasuSdk {
+    private readonly _graphClient: GraphQLClient;
+    public readonly Locking: KSULocking;
+    public readonly DataService: DataService;
+    public readonly UserLending: UserLending;
+    public readonly Portfolio: Portfolio;
+    public readonly Swapper: Swapper;
+    constructor(config: SdkConfig, signerOrProvider: Provider | Signer) {
+        this._graphClient = new GraphQLClient(config.subgraphUrl);
+        this.Locking = new KSULocking(config, signerOrProvider);
+        this.UserLending = new UserLending(config, signerOrProvider);
+        this.DataService = new DataService(config, signerOrProvider);
+        this.Portfolio = new Portfolio(config, signerOrProvider);
+        this.Swapper = new Swapper();
+    }
+}