@kasufinance/kasu-sdk 1.0.1 → 1.0.2

package/.github/workflows/ci.yml

@@ -0,0 +1,39 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - main
+      - develop
+  pull_request:
+    branches:
+      - main
+      - develop
+
+permissions:
+  contents: read
+
+jobs:
+  quality-checks:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Generate contract typings
+        run: npm run build-tc
+
+      - name: Lint & type-check
+        run: npm run build
+
+      - name: Bundle library
+        run: npm run rollup-build

package/.github/workflows/main.yml

@@ -16,28 +16,32 @@ jobs:
 
     steps:
       - uses: actions/checkout@v3
-      - name: Get the version
-        id: get_version
-        run: echo "VERSION=${GITHUB_REF#refs/tags/}" >> "$GITHUB_OUTPUT"
 
-      - name: Remove leading v
-        id: replaced_version
-        env:
-          IMAGE_TAG: ${{ steps.get_version.outputs.VERSION }}
+      - name: Get tag version
+        id: tag_version
         run: |
-          string=$IMAGE_TAG
-          echo "VERSION=${string#v}" >> "$GITHUB_OUTPUT"
+          RAW_TAG="${GITHUB_REF#refs/tags/}"
+          echo "TAG_VERSION=${RAW_TAG#v}" >> "$GITHUB_OUTPUT"
 
-      - name: Replace version inside package.json
-        env:
-          VERSION: ${{ steps.replaced_version.outputs.VERSION }}
-        run: bash versioner.sh $VERSION
+      - name: Read package version
+        id: package_version
+        run: |
+          PKG_VERSION=$(node -p "require('./package.json').version")
+          echo "PACKAGE_VERSION=$PKG_VERSION" >> "$GITHUB_OUTPUT"
+
+      - name: Ensure tag matches package.json
+        run: |
+          if [ "${{ steps.tag_version.outputs.TAG_VERSION }}" != "${{ steps.package_version.outputs.PACKAGE_VERSION }}" ]; then
+            echo "Tag version ${{ steps.tag_version.outputs.TAG_VERSION }} does not match package.json version ${{ steps.package_version.outputs.PACKAGE_VERSION }}."
+            exit 1
+          fi
 
       - uses: actions/setup-node@v3
         with:
           node-version: 18
           registry-url: https://registry.npmjs.org/
           scope: '@kasufinance'
+
       - run: npm install && npm run build-tc && npm run build && npm run rollup-build && npm publish
         env:
           NODE_AUTH_TOKEN: ${{secrets.NPM_TOKEN}}

package/README.md

@@ -0,0 +1,146 @@
+# Kasu SDK
+
+`@kasufinance/kasu-sdk` is the shared TypeScript/JavaScript toolkit used by Kasu
+frontends to interact with the Kasu protocol. It wraps the core smart
+contracts, subgraphs, and Directus CMS in a single object so that dapps can
+query pool data, compute portfolio statistics, and submit locking or lending
+transactions without re-implementing the plumbing.
+
+## Installation
+
+```bash
+npm install @kasufinance/kasu-sdk
+# or
+yarn add @kasufinance/kasu-sdk
+```
+
+The SDK is built against `ethers@5`, so make sure your project already depends
+on it (or install it alongside the SDK).
+
+## Runtime requirements
+
+- **Node or browser environment with fetch/XHR** – when using the SDK on the
+  server (Next.js `app` router actions, serverless functions, etc.) you must
+  provide an XHR implementation because Directus uses it under the hood:
+
+  ```ts
+  // server.ts
+  import { XMLHttpRequest } from 'xhr2';
+  global.XMLHttpRequest = XMLHttpRequest;
+  ```
+
+- **Provider/Signer** – pass an `ethers` `Signer` for write actions or a
+  `Provider` for read-only usage. The SDK does not create its own provider,
+  so you are free to reuse whatever the dapp already uses.
+
+## Configuring the SDK
+
+The `SdkConfig` object wires the SDK to the right contracts and backends:
+
+```ts
+import { JsonRpcProvider } from '@ethersproject/providers';
+import { KasuSdk, SdkConfig } from '@kasufinance/kasu-sdk';
+import { XMLHttpRequest } from 'xhr2';
+
+global.XMLHttpRequest = XMLHttpRequest; // required on Node runtimes
+
+const provider = new JsonRpcProvider(process.env.RPC_URL!, { skipFetchSetup: true });
+
+const config: SdkConfig = {
+  contracts: {
+    KSUToken: '0x…',
+    IKSULocking: '0x…',
+    IKSULockBonus: '0x…',
+    UserManager: '0x…',
+    LendingPoolManager: '0x…',
+    KasuAllowList: '0x…',
+    SystemVariables: '0x…',
+    UserLoyaltyRewards: '0x…',
+    KsuPrice: '0x…',
+    ClearingCoordinator: '0x…',
+    KasuNFTs: '0x…',
+    ExternalTVL: '0x…',
+  },
+  // If certain pools should be hidden from users, provide their ids. Empty string
+  // keeps the Graph queries happy when nothing is filtered out.
+  UNUSED_LENDING_POOL_IDS: [''],
+  directusUrl: 'https://kasu-finance.directus.app/',
+  subgraphUrl: 'https://subgraph.satsuma-prod.com/.../api',
+  plumeSubgraphUrl: 'https://api.goldsky.com/.../kasu-plume/prod/gn',
+};
+
+export const kasuSdk = new KasuSdk(config, provider);
+```
+
+See `kasu-fe-next/src/config/sdk` in the Kasu frontend repository for full
+mainnet and testnet examples, including how Kasu fetches unused pool ids before
+instantiating the SDK.
+
+## Quick start
+
+```ts
+import { JsonRpcProvider } from '@ethersproject/providers';
+import { KasuSdk } from '@kasufinance/kasu-sdk';
+
+const provider = new JsonRpcProvider(RPC_URL);
+const sdk = new KasuSdk(config, provider);
+
+const pools = await sdk.DataService.getPoolOverview(currentEpochId);
+const lockingPeriods = await sdk.Locking.getLockPeriods();
+const userSummary = await sdk.Portfolio.getPortfolioSummary(userAddress);
+await sdk.Locking.lockKSUTokens(amountBn, lockPeriodBn); // signer required
+```
+
+The SDK exposes services as properties on `KasuSdk`. Each service contains the
+methods for a single protocol facet:
+
+| Service       | Purpose                                                                                                      |
+| ------------- | ------------------------------------------------------------------------------------------------------------ |
+| `DataService` | Aggregates on-chain data (subgraphs/external TVL) and off-chain content from Directus (pool descriptions, KPIs). |
+| `Locking`     | High-level helpers for KSU locking: read locking periods, calculate projected rewards, lock/unlock, claim fees. |
+| `UserLending` | User-centric lending utilities (deposit/withdraw requests, transaction history, CSV builders).               |
+| `Portfolio`   | Portfolio snapshots: balances, rewards, lending totals, APY calculations.                                    |
+| `Swapper`     | Helpers for contract calls through the on-chain swapper.                                                     |
+
+Every method is fully typed, so your editor can discover the shape of responses
+(`PoolOverview`, `LockPeriod`, `PortfolioRewards`, etc.) without digging into
+the implementation.
+
+### Working with pool filters
+
+Many queries accept a list of pool ids to ignore (see `UNUSED_LENDING_POOL_IDS`
+in the config). In the Kasu frontend we load this list from Directus before
+creating the SDK:
+
+```ts
+const unusedPools = await getUnusedPools(); // fetches Directus list
+const sdk = new KasuSdk(
+  { ...config, UNUSED_LENDING_POOL_IDS: unusedPools.length ? unusedPools : [''] },
+  provider,
+);
+```
+
+Mirroring this pattern keeps your subgraph requests aligned with the official
+UI and prevents deprecated pools from leaking into calculations.
+
+## Building & testing locally
+
+```bash
+npm install
+npm run build-tc   # regenerate typechain factories
+npm run build      # type-check + compile
+npm run rollup-build
+npm test
+```
+
+These are the same steps executed by the release workflow before publishing to
+npm.
+
+## Support
+For questions, issues, or contributions:
+- GitHub Issues: [Create an issue](https://github.com/kasufinance/kasu-sdk/issues)
+- Documentation: [View full docs](https://docs.kasu.finance)
+- Discord: [Join our community](https://discord.gg/kasufinance)
+
+## License
+This project is licensed under the MIT License - see the LICENSE file for details.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@kasufinance/kasu-sdk",
-    "version": "1.0.1",
+    "version": "1.0.2",
     "description": "",
     "main": "dist/bundle.cjs.js",
     "module": "dist/bundle.esm.js",

package/src/contracts/IClearingCoordinatorAbi.ts

@@ -1,406 +0,0 @@
-/* Autogenerated file. Do not edit manually. */
-/* tslint:disable */
-/* eslint-disable */
-import type {
-  BaseContract,
-  BigNumber,
-  BigNumberish,
-  BytesLike,
-  CallOverrides,
-  ContractTransaction,
-  Overrides,
-  PopulatedTransaction,
-  Signer,
-  utils,
-} from "ethers";
-import type {
-  FunctionFragment,
-  Result,
-  EventFragment,
-} from "@ethersproject/abi";
-import type { Listener, Provider } from "@ethersproject/providers";
-import type {
-  TypedEventFilter,
-  TypedEvent,
-  TypedListener,
-  OnEvent,
-} from "./common";
-
-export type ClearingConfigurationStruct = {
-  drawAmount: BigNumberish;
-  trancheDesiredRatios: BigNumberish[];
-  maxExcessPercentage: BigNumberish;
-  minExcessPercentage: BigNumberish;
-};
-
-export type ClearingConfigurationStructOutput = [
-  BigNumber,
-  BigNumber[],
-  BigNumber,
-  BigNumber
-] & {
-  drawAmount: BigNumber;
-  trancheDesiredRatios: BigNumber[];
-  maxExcessPercentage: BigNumber;
-  minExcessPercentage: BigNumber;
-};
-
-export interface IClearingCoordinatorAbiInterface extends utils.Interface {
-  functions: {
-    "doClearing(address,uint256,uint256,uint256,(uint256,uint256[],uint256,uint256),bool)": FunctionFragment;
-    "initializeLendingPool(address)": FunctionFragment;
-    "isLendingPoolClearingPending(address)": FunctionFragment;
-    "lendingPoolClearingStatus(address,uint256)": FunctionFragment;
-    "lendingPoolMaxDrawAmount(address)": FunctionFragment;
-    "nextLendingPoolClearingEpoch(address)": FunctionFragment;
-  };
-
-  getFunction(
-    nameOrSignatureOrTopic:
-      | "doClearing"
-      | "initializeLendingPool"
-      | "isLendingPoolClearingPending"
-      | "lendingPoolClearingStatus"
-      | "lendingPoolMaxDrawAmount"
-      | "nextLendingPoolClearingEpoch"
-  ): FunctionFragment;
-
-  encodeFunctionData(
-    functionFragment: "doClearing",
-    values: [
-      string,
-      BigNumberish,
-      BigNumberish,
-      BigNumberish,
-      ClearingConfigurationStruct,
-      boolean
-    ]
-  ): string;
-  encodeFunctionData(
-    functionFragment: "initializeLendingPool",
-    values: [string]
-  ): string;
-  encodeFunctionData(
-    functionFragment: "isLendingPoolClearingPending",
-    values: [string]
-  ): string;
-  encodeFunctionData(
-    functionFragment: "lendingPoolClearingStatus",
-    values: [string, BigNumberish]
-  ): string;
-  encodeFunctionData(
-    functionFragment: "lendingPoolMaxDrawAmount",
-    values: [string]
-  ): string;
-  encodeFunctionData(
-    functionFragment: "nextLendingPoolClearingEpoch",
-    values: [string]
-  ): string;
-
-  decodeFunctionResult(functionFragment: "doClearing", data: BytesLike): Result;
-  decodeFunctionResult(
-    functionFragment: "initializeLendingPool",
-    data: BytesLike
-  ): Result;
-  decodeFunctionResult(
-    functionFragment: "isLendingPoolClearingPending",
-    data: BytesLike
-  ): Result;
-  decodeFunctionResult(
-    functionFragment: "lendingPoolClearingStatus",
-    data: BytesLike
-  ): Result;
-  decodeFunctionResult(
-    functionFragment: "lendingPoolMaxDrawAmount",
-    data: BytesLike
-  ): Result;
-  decodeFunctionResult(
-    functionFragment: "nextLendingPoolClearingEpoch",
-    data: BytesLike
-  ): Result;
-
-  events: {
-    "ClearingConfigSet(address,uint256,(uint256,uint256[],uint256,uint256))": EventFragment;
-    "ClearingExecuted(address,uint256,uint8)": EventFragment;
-    "Initialized(uint64)": EventFragment;
-  };
-
-  getEvent(nameOrSignatureOrTopic: "ClearingConfigSet"): EventFragment;
-  getEvent(nameOrSignatureOrTopic: "ClearingExecuted"): EventFragment;
-  getEvent(nameOrSignatureOrTopic: "Initialized"): EventFragment;
-}
-
-export interface ClearingConfigSetEventObject {
-  lendingPool: string;
-  epoch: BigNumber;
-  clearingConfig: ClearingConfigurationStructOutput;
-}
-export type ClearingConfigSetEvent = TypedEvent<
-  [string, BigNumber, ClearingConfigurationStructOutput],
-  ClearingConfigSetEventObject
->;
-
-export type ClearingConfigSetEventFilter =
-  TypedEventFilter<ClearingConfigSetEvent>;
-
-export interface ClearingExecutedEventObject {
-  lendingPool: string;
-  epoch: BigNumber;
-  clearingStatus: number;
-}
-export type ClearingExecutedEvent = TypedEvent<
-  [string, BigNumber, number],
-  ClearingExecutedEventObject
->;
-
-export type ClearingExecutedEventFilter =
-  TypedEventFilter<ClearingExecutedEvent>;
-
-export interface InitializedEventObject {
-  version: BigNumber;
-}
-export type InitializedEvent = TypedEvent<[BigNumber], InitializedEventObject>;
-
-export type InitializedEventFilter = TypedEventFilter<InitializedEvent>;
-
-export interface IClearingCoordinatorAbi extends BaseContract {
-  connect(signerOrProvider: Signer | Provider | string): this;
-  attach(addressOrName: string): this;
-  deployed(): Promise<this>;
-
-  interface: IClearingCoordinatorAbiInterface;
-
-  queryFilter<TEvent extends TypedEvent>(
-    event: TypedEventFilter<TEvent>,
-    fromBlockOrBlockhash?: string | number | undefined,
-    toBlock?: string | number | undefined
-  ): Promise<Array<TEvent>>;
-
-  listeners<TEvent extends TypedEvent>(
-    eventFilter?: TypedEventFilter<TEvent>
-  ): Array<TypedListener<TEvent>>;
-  listeners(eventName?: string): Array<Listener>;
-  removeAllListeners<TEvent extends TypedEvent>(
-    eventFilter: TypedEventFilter<TEvent>
-  ): this;
-  removeAllListeners(eventName?: string): this;
-  off: OnEvent<this>;
-  on: OnEvent<this>;
-  once: OnEvent<this>;
-  removeListener: OnEvent<this>;
-
-  functions: {
-    doClearing(
-      lendingPool: string,
-      targetEpoch: BigNumberish,
-      priorityCalculationBatchSize: BigNumberish,
-      acceptRequestsBatchSize: BigNumberish,
-      clearingConfig: ClearingConfigurationStruct,
-      isConfigOverridden: boolean,
-      overrides?: Overrides & { from?: string }
-    ): Promise<ContractTransaction>;
-
-    initializeLendingPool(
-      lendingPool: string,
-      overrides?: Overrides & { from?: string }
-    ): Promise<ContractTransaction>;
-
-    isLendingPoolClearingPending(
-      lendingPool: string,
-      overrides?: CallOverrides
-    ): Promise<[boolean] & { isPending: boolean }>;
-
-    lendingPoolClearingStatus(
-      lendingPool: string,
-      epoch: BigNumberish,
-      overrides?: CallOverrides
-    ): Promise<[number] & { status: number }>;
-
-    lendingPoolMaxDrawAmount(
-      lendingPool: string,
-      overrides?: CallOverrides
-    ): Promise<[BigNumber]>;
-
-    nextLendingPoolClearingEpoch(
-      lendingPool: string,
-      overrides?: CallOverrides
-    ): Promise<[BigNumber] & { nextClearingEpoch: BigNumber }>;
-  };
-
-  doClearing(
-    lendingPool: string,
-    targetEpoch: BigNumberish,
-    priorityCalculationBatchSize: BigNumberish,
-    acceptRequestsBatchSize: BigNumberish,
-    clearingConfig: ClearingConfigurationStruct,
-    isConfigOverridden: boolean,
-    overrides?: Overrides & { from?: string }
-  ): Promise<ContractTransaction>;
-
-  initializeLendingPool(
-    lendingPool: string,
-    overrides?: Overrides & { from?: string }
-  ): Promise<ContractTransaction>;
-
-  isLendingPoolClearingPending(
-    lendingPool: string,
-    overrides?: CallOverrides
-  ): Promise<boolean>;
-
-  lendingPoolClearingStatus(
-    lendingPool: string,
-    epoch: BigNumberish,
-    overrides?: CallOverrides
-  ): Promise<number>;
-
-  lendingPoolMaxDrawAmount(
-    lendingPool: string,
-    overrides?: CallOverrides
-  ): Promise<BigNumber>;
-
-  nextLendingPoolClearingEpoch(
-    lendingPool: string,
-    overrides?: CallOverrides
-  ): Promise<BigNumber>;
-
-  callStatic: {
-    doClearing(
-      lendingPool: string,
-      targetEpoch: BigNumberish,
-      priorityCalculationBatchSize: BigNumberish,
-      acceptRequestsBatchSize: BigNumberish,
-      clearingConfig: ClearingConfigurationStruct,
-      isConfigOverridden: boolean,
-      overrides?: CallOverrides
-    ): Promise<void>;
-
-    initializeLendingPool(
-      lendingPool: string,
-      overrides?: CallOverrides
-    ): Promise<void>;
-
-    isLendingPoolClearingPending(
-      lendingPool: string,
-      overrides?: CallOverrides
-    ): Promise<boolean>;
-
-    lendingPoolClearingStatus(
-      lendingPool: string,
-      epoch: BigNumberish,
-      overrides?: CallOverrides
-    ): Promise<number>;
-
-    lendingPoolMaxDrawAmount(
-      lendingPool: string,
-      overrides?: CallOverrides
-    ): Promise<BigNumber>;
-
-    nextLendingPoolClearingEpoch(
-      lendingPool: string,
-      overrides?: CallOverrides
-    ): Promise<BigNumber>;
-  };
-
-  filters: {
-    "ClearingConfigSet(address,uint256,(uint256,uint256[],uint256,uint256))"(
-      lendingPool?: string | null,
-      epoch?: BigNumberish | null,
-      clearingConfig?: null
-    ): ClearingConfigSetEventFilter;
-    ClearingConfigSet(
-      lendingPool?: string | null,
-      epoch?: BigNumberish | null,
-      clearingConfig?: null
-    ): ClearingConfigSetEventFilter;
-
-    "ClearingExecuted(address,uint256,uint8)"(
-      lendingPool?: string | null,
-      epoch?: BigNumberish | null,
-      clearingStatus?: null
-    ): ClearingExecutedEventFilter;
-    ClearingExecuted(
-      lendingPool?: string | null,
-      epoch?: BigNumberish | null,
-      clearingStatus?: null
-    ): ClearingExecutedEventFilter;
-
-    "Initialized(uint64)"(version?: null): InitializedEventFilter;
-    Initialized(version?: null): InitializedEventFilter;
-  };
-
-  estimateGas: {
-    doClearing(
-      lendingPool: string,
-      targetEpoch: BigNumberish,
-      priorityCalculationBatchSize: BigNumberish,
-      acceptRequestsBatchSize: BigNumberish,
-      clearingConfig: ClearingConfigurationStruct,
-      isConfigOverridden: boolean,
-      overrides?: Overrides & { from?: string }
-    ): Promise<BigNumber>;
-
-    initializeLendingPool(
-      lendingPool: string,
-      overrides?: Overrides & { from?: string }
-    ): Promise<BigNumber>;
-
-    isLendingPoolClearingPending(
-      lendingPool: string,
-      overrides?: CallOverrides
-    ): Promise<BigNumber>;
-
-    lendingPoolClearingStatus(
-      lendingPool: string,
-      epoch: BigNumberish,
-      overrides?: CallOverrides
-    ): Promise<BigNumber>;
-
-    lendingPoolMaxDrawAmount(
-      lendingPool: string,
-      overrides?: CallOverrides
-    ): Promise<BigNumber>;
-
-    nextLendingPoolClearingEpoch(
-      lendingPool: string,
-      overrides?: CallOverrides
-    ): Promise<BigNumber>;
-  };
-
-  populateTransaction: {
-    doClearing(
-      lendingPool: string,
-      targetEpoch: BigNumberish,
-      priorityCalculationBatchSize: BigNumberish,
-      acceptRequestsBatchSize: BigNumberish,
-      clearingConfig: ClearingConfigurationStruct,
-      isConfigOverridden: boolean,
-      overrides?: Overrides & { from?: string }
-    ): Promise<PopulatedTransaction>;
-
-    initializeLendingPool(
-      lendingPool: string,
-      overrides?: Overrides & { from?: string }
-    ): Promise<PopulatedTransaction>;
-
-    isLendingPoolClearingPending(
-      lendingPool: string,
-      overrides?: CallOverrides
-    ): Promise<PopulatedTransaction>;
-
-    lendingPoolClearingStatus(
-      lendingPool: string,
-      epoch: BigNumberish,
-      overrides?: CallOverrides
-    ): Promise<PopulatedTransaction>;
-
-    lendingPoolMaxDrawAmount(
-      lendingPool: string,
-      overrides?: CallOverrides
-    ): Promise<PopulatedTransaction>;
-
-    nextLendingPoolClearingEpoch(
-      lendingPool: string,
-      overrides?: CallOverrides
-    ): Promise<PopulatedTransaction>;
-  };
-}