@kasufinance/kasu-sdk 1.0.3 → 2.1.0

package/src/services/Portfolio/portfolio.ts

@@ -8,11 +8,29 @@ import {
     IKasuNFTsAbi__factory,
     ISystemVariablesAbi,
     ISystemVariablesAbi__factory,
+    IUserLoyaltyRewardsAbi__factory,
 } from '../../contracts';
 import { SdkConfig } from '../../sdk-config';
+import { isLiteDeployment } from '../../utils/deployment-mode';
 import { DataService } from '../DataService/data-service';
+import {
+    getAllTrancheConfigurationsQuery,
+    getAllTranchesQuery,
+} from '../DataService/queries';
+import {
+    TrancheConfigurationSubgraphResult,
+    TrancheSubgraphResult,
+} from '../DataService/subgraph-types';
 import { PoolOverview } from '../DataService/types';
 import { KSULocking } from '../Locking/locking';
+import {
+    getSystemVariablesQuery,
+    lockingSummariesQuery,
+} from '../Locking/queries';
+import {
+    LockingSummarySubgraphResult,
+    SystemVariables,
+} from '../Locking/types';
 import { UserLending } from '../UserLending/user-lending';
 
 import { lendingPortfolioQuery } from './queries';
@@ -33,8 +51,12 @@ export class Portfolio {
     private readonly _graph: GraphQLClient;
 
     private _systemVariablesAbi: ISystemVariablesAbi;
-    private _kasuNftContract: IKasuNFTsAbi;
+    private _userLoyaltyRewardsAbi: ReturnType<
+        typeof IUserLoyaltyRewardsAbi__factory.connect
+    >;
+    private _kasuNftContract: IKasuNFTsAbi | null;
     readonly _signerOrProvider: Signer | Provider;
+    private _isLiteDeployment: boolean;
 
     constructor(
         private _kasuConfig: SdkConfig,
@@ -47,60 +69,35 @@ export class Portfolio {
             _kasuConfig.contracts.SystemVariables,
             signerOrProvider,
         );
-        this._userLendingService = new UserLending(
-            _kasuConfig,
+        this._userLoyaltyRewardsAbi = IUserLoyaltyRewardsAbi__factory.connect(
+            _kasuConfig.contracts.UserLoyaltyRewards,
             signerOrProvider,
         );
-        this._kasuNftContract = IKasuNFTsAbi__factory.connect(
-            _kasuConfig.contracts.KasuNFTs,
+        this._userLendingService = new UserLending(
+            _kasuConfig,
             signerOrProvider,
         );
+        this._isLiteDeployment = isLiteDeployment(_kasuConfig);
+        this._kasuNftContract = _kasuConfig.contracts.KasuNFTs
+            ? IKasuNFTsAbi__factory.connect(
+                  _kasuConfig.contracts.KasuNFTs,
+                  signerOrProvider,
+              )
+            : null;
         this._graph = new GraphQLClient(_kasuConfig.subgraphUrl);
     }
 
-    async getPortfolioRewards(userAddress: string): Promise<PortfolioRewards> {
-        const userLockingData =
-            await this._lockingService.getUserBonusData(userAddress);
-        const lockingRewards =
-            await this._lockingService.getLockingRewards(userAddress);
-        const ksuLaunchBonus =
-            await this._lockingService.getUserTotalBonusAmount(userAddress);
-        return {
-            bonusYieldEarnings: {
-                claimableBalance: {
-                    ksuAmount: userLockingData.ksuBonusAndRewards,
-                },
-                lifeTime: {
-                    ksuAmount: userLockingData.ksuBonusAndRewardsLifetime,
-                },
-            },
-            protocolFees: {
-                claimableBalance: {
-                    usdcAmount: lockingRewards.claimableRewards,
-                },
-                lifeTime: { usdcAmount: lockingRewards.lifeTimeRewards },
-            },
-            ksuLaunchBonus: { lifeTime: { ksuAmount: ksuLaunchBonus } },
-        };
-    }
-
-    async getUserNfts(userAddress: string): Promise<number[]> {
-        const usernfts = await this._kasuNftContract.tokensOfOwner(userAddress);
-
-        return usernfts.map((nft) => nft.toNumber());
-    }
-
-    async getPortfolioSummary(
-        userAddress: string,
+    private computeYieldMetrics(
         portfolioLendingPools: PortfolioLendingPool[],
-    ): Promise<PortfolioSummary> {
-        const userLockingData =
-            await this._lockingService.getUserBonusData(userAddress);
+    ): {
+        totalInvestments: number;
+        totalYieldEarned: number;
+        weightedApy: number;
+        weeklyYieldEarnings: number;
+    } {
         let totalInvestments = 0;
-
-        let weightedApy = 0;
         let totalYieldEarned = 0;
-
+        let weightedApy = 0;
         let weeklyYieldEarnings = 0;
 
         for (const pool of portfolioLendingPools) {
@@ -139,6 +136,238 @@ export class Portfolio {
             }
         }
 
+        return {
+            totalInvestments,
+            totalYieldEarned,
+            weightedApy,
+            weeklyYieldEarnings,
+        };
+    }
+
+    /**
+     * Calculate aggregate yield metrics for a set of portfolio lending pools.
+     * Accepts pre-fetched pool data and returns totals without performing any network calls.
+     */
+    public calculateYieldMetrics(
+        portfolioLendingPools: PortfolioLendingPool[],
+    ): {
+        totalInvestments: number;
+        totalYieldEarned: number;
+        weightedApy: number;
+        weeklyYieldEarnings: number;
+    } {
+        return this.computeYieldMetrics(portfolioLendingPools);
+    }
+
+    /**
+     * Calculate the user's weekly protocol fee share (USDC) given tranche balances/configs,
+     * system variables and locking summary. All inputs are expected to be pre-fetched.
+     */
+    public calculateWeeklyProtocolFees(params: {
+        trancheBalances: TrancheSubgraphResult;
+        trancheConfigurations: TrancheConfigurationSubgraphResult;
+        systemVariables: SystemVariables;
+        lockingSummary: LockingSummarySubgraphResult;
+        userRksuAmount: string;
+    }): number {
+        const {
+            trancheBalances,
+            trancheConfigurations,
+            systemVariables,
+            lockingSummary,
+            userRksuAmount,
+        } = params;
+
+        const totalRKsuAmount = parseFloat(
+            lockingSummary.lockingSummaries[0]?.totalRKsuAmount ?? '0',
+        );
+        const userRKsuAmount = parseFloat(userRksuAmount || '0');
+
+        const performanceFee =
+            parseFloat(systemVariables.systemVariables.performanceFee) / 100;
+        const ecosystemFeeRate =
+            parseFloat(systemVariables.systemVariables.ecosystemFeeRate) / 100;
+
+        if (
+            totalRKsuAmount <= 0 ||
+            userRKsuAmount <= 0 ||
+            performanceFee <= 0 ||
+            ecosystemFeeRate <= 0
+        ) {
+            return 0;
+        }
+
+        let totalWeeklyEcosystemFees = 0;
+
+        for (const tranche of trancheBalances.lendingPoolTranches) {
+            const trancheConfig =
+                trancheConfigurations.lendingPoolTrancheConfigurations.find(
+                    (config) => config.id === tranche.id,
+                );
+
+            if (!trancheConfig) continue;
+
+            const interestUpdates =
+                trancheConfig.lendingPoolTrancheInterestRateUpdates;
+
+            const interestRate = interestUpdates.length
+                ? interestUpdates[0].epochInterestRate
+                : trancheConfig.interestRate;
+
+            totalWeeklyEcosystemFees +=
+                parseFloat(tranche.balance) *
+                parseFloat(interestRate) *
+                performanceFee *
+                ecosystemFeeRate;
+        }
+
+        return (
+            (totalWeeklyEcosystemFees * userRKsuAmount) / totalRKsuAmount
+        );
+    }
+
+    /**
+     * Calculate the user's weekly KASU bonus rewards (KASU) based on current deposits,
+     * loyalty level, reward rate, and KSU epoch price. Inputs should be pre-fetched.
+     */
+    public async calculateWeeklyKsuBonusRewards(params: {
+        userAddress: string;
+        userRksuAmount: string;
+        userDepositAmounts: [BigNumber, BigNumber];
+        ksuEpochPrice: { price: BigNumber; decimals: number };
+    }): Promise<number> {
+        const { userAddress, userRksuAmount, userDepositAmounts, ksuEpochPrice } =
+            params;
+
+        const totalUserDeposits = userDepositAmounts[0].add(
+            userDepositAmounts[1],
+        );
+
+        if (totalUserDeposits.isZero()) return 0;
+
+        const rKSUtoUSDCRatio = await this._lockingService.getRKSUvsUSDCRatio(
+            userRksuAmount,
+            userAddress,
+        );
+        const { loyaltyLevel } =
+            this._lockingService.getLoyaltyLevelAndApyBonusFromRatio(
+                rKSUtoUSDCRatio,
+            );
+
+        const loyaltyRewardRate =
+            await this._userLoyaltyRewardsAbi.loyaltyEpochRewardRates(
+                loyaltyLevel,
+            );
+
+        if (loyaltyRewardRate.isZero() || ksuEpochPrice.price.isZero()) {
+            return 0;
+        }
+
+        const reward = totalUserDeposits
+            .mul(loyaltyRewardRate)
+            .mul(BigNumber.from(10).pow(12))
+            .div(ksuEpochPrice.price);
+
+        return parseFloat(formatEther(reward));
+    }
+
+    async getPortfolioRewards(userAddress: string): Promise<PortfolioRewards> {
+        const userLockingData =
+            await this._lockingService.getUserBonusData(userAddress);
+        const lockingRewards =
+            await this._lockingService.getLockingRewards(userAddress);
+        const ksuLaunchBonus =
+            await this._lockingService.getUserTotalBonusAmount(userAddress);
+        return {
+            bonusYieldEarnings: {
+                claimableBalance: {
+                    ksuAmount: userLockingData.ksuBonusAndRewards,
+                },
+                lifeTime: {
+                    ksuAmount: userLockingData.ksuBonusAndRewardsLifetime,
+                },
+            },
+            protocolFees: {
+                claimableBalance: {
+                    usdcAmount: lockingRewards.claimableRewards,
+                },
+                lifeTime: { usdcAmount: lockingRewards.lifeTimeRewards },
+            },
+            ksuLaunchBonus: { lifeTime: { ksuAmount: ksuLaunchBonus } },
+        };
+    }
+
+    async getUserNfts(userAddress: string): Promise<number[]> {
+        // NFTs are not available on Lite deployments
+        if (this._isLiteDeployment || !this._kasuNftContract) {
+            return [];
+        }
+
+        const usernfts = await this._kasuNftContract.tokensOfOwner(userAddress);
+
+        return usernfts.map((nft) => nft.toNumber());
+    }
+
+    async getPortfolioSummary(
+        userAddress: string,
+        portfolioLendingPools: PortfolioLendingPool[],
+        currentEpoch: string,
+    ): Promise<PortfolioSummary> {
+        const epochId = currentEpoch.toString();
+        const [
+            userLockingData,
+            userRksuAmount,
+            lockingSummary,
+            systemVariables,
+            trancheBalances,
+            trancheConfigurations,
+            userDepositAmounts,
+            ksuEpochPrice,
+        ] = await Promise.all([
+            this._lockingService.getUserBonusData(userAddress),
+            this._lockingService.getUserEarnedrKsu(userAddress),
+            this._graph.request<LockingSummarySubgraphResult>(
+                lockingSummariesQuery,
+            ),
+            this._graph.request<SystemVariables>(getSystemVariablesQuery),
+            this._graph.request<TrancheSubgraphResult>(getAllTranchesQuery, {
+                unusedPools: this._kasuConfig.UNUSED_LENDING_POOL_IDS,
+            }),
+            this._graph.request<TrancheConfigurationSubgraphResult>(
+                getAllTrancheConfigurationsQuery,
+                {
+                    unusedPools: this._kasuConfig.UNUSED_LENDING_POOL_IDS,
+                    epochId,
+                },
+            ),
+            this._userLendingService.getUserTotalPendingAndActiveDepositedAmountForCurrentEpoch(
+                userAddress,
+            ),
+            this._lockingService.getKasuEpochTokenPrice(),
+        ]);
+        const {
+            totalInvestments,
+            totalYieldEarned,
+            weightedApy,
+            weeklyYieldEarnings,
+        } = this.computeYieldMetrics(portfolioLendingPools);
+
+        const weeklyProtocolFeesEarned = this.calculateWeeklyProtocolFees({
+            trancheBalances,
+            trancheConfigurations,
+            systemVariables,
+            lockingSummary,
+            userRksuAmount,
+        });
+
+        const weeklyKsuBonusRewards =
+            await this.calculateWeeklyKsuBonusRewards({
+                userAddress,
+                userRksuAmount,
+                userDepositAmounts,
+                ksuEpochPrice,
+            });
+
         return {
             current: {
                 totalKsuLocked: userLockingData.totalLockedAmount,
@@ -153,8 +382,8 @@ export class Portfolio {
             },
             weekly: {
                 yieldEarnings: weeklyYieldEarnings.toString(),
-                protocolFeesEarned: '0',
-                ksuBonusRewards: '0',
+                protocolFeesEarned: weeklyProtocolFeesEarned.toString(),
+                ksuBonusRewards: weeklyKsuBonusRewards.toString(),
             },
             lifetime: {
                 yieldEarnings: totalYieldEarned.toString(),
@@ -269,9 +498,6 @@ export class Portfolio {
                 ({ poolId }) => poolId === poolOverview.id,
             );
             if (!userPoolBalance) {
-                console.warn(
-                    `Could not find user pool balance for ${poolOverview.id}`,
-                );
                 continue;
             }
             totalInvestments = userPoolBalance.balance.add(totalInvestments);

package/src/tests/facade.test.ts

@@ -0,0 +1,245 @@
+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';
+
+// ---------------------------------------------------------------------------
+// Chain configs
+// ---------------------------------------------------------------------------
+
+describe('CHAIN_CONFIGS', () => {
+    it('should have base, xdc, and plume entries', () => {
+        expect(CHAIN_CONFIGS).toHaveProperty('base');
+        expect(CHAIN_CONFIGS).toHaveProperty('xdc');
+        expect(CHAIN_CONFIGS).toHaveProperty('plume');
+    });
+
+    it('base should be a full deployment', () => {
+        const base = CHAIN_CONFIGS.base;
+        expect(base.chainId).toBe(8453);
+        expect(base.isLiteDeployment).toBe(false);
+        expect(base.contracts.KSUToken).toBeDefined();
+        expect(base.contracts.KasuNFTs).toBeDefined();
+    });
+
+    it('xdc should be a lite deployment without KSU token', () => {
+        const xdc = CHAIN_CONFIGS.xdc;
+        expect(xdc.chainId).toBe(50);
+        expect(xdc.isLiteDeployment).toBe(true);
+        expect(xdc.contracts.KSUToken).toBeUndefined();
+        expect(xdc.contracts.KasuNFTs).toBeUndefined();
+    });
+
+    it('plume should be a lite deployment', () => {
+        const plume = CHAIN_CONFIGS.plume;
+        expect(plume.chainId).toBe(98866);
+        expect(plume.isLiteDeployment).toBe(true);
+    });
+
+    it('all chains should have required contract addresses', () => {
+        for (const [, config] of Object.entries(CHAIN_CONFIGS)) {
+            expect(config.contracts.LendingPoolManager).toBeDefined();
+            expect(config.contracts.UserManager).toBeDefined();
+            expect(config.contracts.KasuAllowList).toBeDefined();
+            expect(config.contracts.SystemVariables).toBeDefined();
+            expect(config.subgraphUrl).toContain('goldsky.com');
+        }
+    });
+
+    it('xdc should have poolMetadataMapping', () => {
+        const mapping = CHAIN_CONFIGS.xdc.poolMetadataMapping;
+        expect(mapping).toBeDefined();
+        expect(Object.keys(mapping ?? {}).length).toBeGreaterThan(0);
+    });
+});
+
+// ---------------------------------------------------------------------------
+// Kasu.create()
+// ---------------------------------------------------------------------------
+
+describe('Kasu.create()', () => {
+    // Mock provider — enough to construct the SDK without network calls
+    const mockProvider = {
+        getNetwork: jest.fn().mockResolvedValue({ chainId: 8453, name: 'base' }),
+        call: jest.fn(),
+        estimateGas: jest.fn(),
+        getBlockNumber: jest.fn(),
+        getBlock: jest.fn(),
+        getTransaction: jest.fn(),
+        getTransactionReceipt: jest.fn(),
+        getLogs: jest.fn(),
+        on: jest.fn(),
+        once: jest.fn(),
+        off: jest.fn(),
+        removeAllListeners: jest.fn(),
+        _isProvider: true,
+    };
+
+    it('should create an instance from a chain name', () => {
+        const kasu = Kasu.create({
+            chain: 'base',
+            signerOrProvider: mockProvider as never,
+        });
+
+        expect(kasu).toBeInstanceOf(Kasu);
+        expect(kasu.strategies).toBeInstanceOf(StrategiesFacade);
+        expect(kasu.deposits).toBeInstanceOf(DepositsFacade);
+        expect(kasu.portfolio).toBeInstanceOf(PortfolioFacade);
+    });
+
+    it('should expose chainConfig for the selected chain', () => {
+        const kasu = Kasu.create({
+            chain: 'xdc',
+            signerOrProvider: mockProvider as never,
+        });
+
+        expect(kasu.chainConfig.chainId).toBe(50);
+        expect(kasu.isLiteDeployment).toBe(true);
+    });
+
+    it('should accept a custom ChainConfigEntry', () => {
+        const custom = {
+            ...CHAIN_CONFIGS.base,
+            chainId: 999,
+            name: 'CustomChain',
+        };
+
+        const kasu = Kasu.create({
+            chain: custom,
+            signerOrProvider: mockProvider as never,
+        });
+
+        expect(kasu.chainConfig.chainId).toBe(999);
+        expect(kasu.chainConfig.name).toBe('CustomChain');
+    });
+
+    it('should accept configOverrides', () => {
+        const kasu = Kasu.create({
+            chain: 'base',
+            signerOrProvider: mockProvider as never,
+            configOverrides: {
+                UNUSED_LENDING_POOL_IDS: ['0xdead'],
+            },
+        });
+
+        expect(kasu).toBeInstanceOf(Kasu);
+    });
+
+    it('should expose the underlying KasuSdk via .services', () => {
+        const kasu = Kasu.create({
+            chain: 'base',
+            signerOrProvider: mockProvider as never,
+        });
+
+        expect(kasu.services).toBeDefined();
+        expect(kasu.services.DataService).toBeDefined();
+        expect(kasu.services.UserLending).toBeDefined();
+        expect(kasu.services.Locking).toBeDefined();
+        expect(kasu.services.Portfolio).toBeDefined();
+    });
+});
+
+// ---------------------------------------------------------------------------
+// StrategiesFacade.calculateDepositLimits()
+// ---------------------------------------------------------------------------
+
+describe('StrategiesFacade.calculateDepositLimits()', () => {
+    // We can test this pure function without network calls by constructing
+    // a StrategiesFacade with null services and calling calculateDepositLimits directly.
+    const facade = new StrategiesFacade(null as never, null as never);
+
+    it('should enforce minimum of 1 USDC', () => {
+        const tranche = makeTranche({
+            minimumDeposit: '0.5',
+            maximumDeposit: '10000',
+            poolCapacity: '50000',
+        });
+
+        const limits = facade.calculateDepositLimits(tranche);
+        expect(limits.min).toBe('1');
+        expect(limits.max).toBe('10000');
+        expect(limits.availableCapacity).toBe('50000');
+    });
+
+    it('should pass through minimum when >= 1', () => {
+        const tranche = makeTranche({
+            minimumDeposit: '100',
+            maximumDeposit: '10000',
+            poolCapacity: '50000',
+        });
+
+        const limits = facade.calculateDepositLimits(tranche);
+        expect(limits.min).toBe('100');
+    });
+
+    it('should cap max at pool capacity when capacity is lower', () => {
+        const tranche = makeTranche({
+            minimumDeposit: '100',
+            maximumDeposit: '50000',
+            poolCapacity: '10000',
+        });
+
+        const limits = facade.calculateDepositLimits(tranche);
+        expect(limits.max).toBe('10000');
+    });
+
+    it('should use maximumDeposit when capacity is higher', () => {
+        const tranche = makeTranche({
+            minimumDeposit: '100',
+            maximumDeposit: '5000',
+            poolCapacity: '50000',
+        });
+
+        const limits = facade.calculateDepositLimits(tranche);
+        expect(limits.max).toBe('5000');
+    });
+});
+
+// ---------------------------------------------------------------------------
+// Type exports — verify key facade types are importable
+// ---------------------------------------------------------------------------
+
+describe('Type re-exports', () => {
+    it('should export facade classes from the main entry', () => {
+        // Verify the barrel exports resolve — these would fail at compile time
+        // if the re-exports were broken.
+        expect(Kasu).toBeDefined();
+        expect(CHAIN_CONFIGS).toBeDefined();
+        expect(StrategiesFacade).toBeDefined();
+        expect(DepositsFacade).toBeDefined();
+        expect(PortfolioFacade).toBeDefined();
+    });
+});
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+// eslint-disable-next-line @typescript-eslint/explicit-function-return-type
+function makeTranche(raw: {
+    minimumDeposit: string;
+    maximumDeposit: string;
+    poolCapacity: string;
+}) {
+    return {
+        id: '0xtest',
+        name: 'Test Tranche',
+        apy: 0.08,
+        minApy: 0.06,
+        maxApy: 0.10,
+        minimumDeposit: raw.minimumDeposit,
+        maximumDeposit: raw.maximumDeposit,
+        availableCapacity: raw.poolCapacity,
+        fixedTermOptions: [],
+        _raw: {
+            ...raw,
+            id: '0xtest',
+            name: 'Test Tranche',
+            apy: '0.08',
+            minApy: '0.06',
+            maxApy: '0.10',
+            fixedTermConfig: [],
+        },
+    } as never;
+}

package/src/tests/sample.test.ts

@@ -12,10 +12,10 @@ test('subgraphCall', async () => {
         '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',
-        {
+    const config = new SdkConfig({
+        subgraphUrl:
+            'https://api.studio.thegraph.com/query/63245/kasu-wip-sepolia/version/latest',
+        contracts: {
             IKSULocking: '0x529A81c11ab6176c5E88670d293BB771800066a2',
             IKSULockBonus: '0xBBfFd5F744156FFc526df12F5e09dC7b208Be740',
             KSUToken: '0xa0f698Feb9Bc2BeA6E85eb071D5E3F59dc5bC56b',
@@ -29,11 +29,9 @@ test('subgraphCall', async () => {
             KasuNFTs: '0x0000000000000000000000000000000000000000',
             ExternalTVL: '0x0000000000000000000000000000000000000000',
         },
-
-        'https://kasu-finance.directus.app',
-
-        [''],
-    );
+        directusUrl: 'https://kasu-finance.directus.app',
+        UNUSED_LENDING_POOL_IDS: [''],
+    });
     const sdk = new KasuSdk(config, wallet);
 
     console.log(

package/src/utils/deployment-mode.ts

@@ -0,0 +1,9 @@
+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 function isLiteDeployment(config: SdkConfig): boolean {
+    return config.isLiteDeployment;
+}

package/tsconfig.json

@@ -6,7 +6,7 @@
         "target": "es6",
         "module": "esnext",
         "lib": ["es6", "dom", "dom.iterable", "esnext", "es2020"],
-        "sourceMap": false,
+        "sourceMap": true,
         "allowJs": true,
         "outDir": "./dist",
         "rootDir": "src",