@galacticcouncil/sdk-next 1.0.0-beta.0 → 1.0.0

package/README.md

@@ -2,15 +2,24 @@
 
 [![npm version](https://img.shields.io/npm/v/@galacticcouncil/sdk-next.svg)](https://www.npmjs.com/package/@galacticcouncil/sdk-next)
 
-Next gen hydration sdk build on top of [Polkadot API (Papi)](https://papi.how/).
+Next gen Hydration SDK built on top of [Polkadot API (Papi)](https://papi.how/).
 
-Table of content:
+Table of contents:
 
 - [Installation](#installation)
+- [Usage](#usage)
 - [Components](#components)
-  - [PoolContextProvider](#poolcontextprovider)
-  - [Router](#router)
+  - [api](#api)
+  - [client](#client)
+  - [ctx](#ctx)
+  - [tx](#tx)
+- [API Reference](#api-reference)
+  - [AaveUtils](#aaveutils)
   - [TradeRouter](#traderouter)
+  - [TradeScheduler](#tradescheduler)
+  - [BalanceClient](#balanceclient)
+  - [AssetClient](#assetclient)
+- [Examples](#examples)
 
 ## Installation
 
@@ -18,124 +27,168 @@ Install with [npm](https://www.npmjs.com/):
 
 `npm install @galacticcouncil/sdk-next`
 
-## Components
+## Usage
 
-### Pool
+Use `createSdkContext` to quickly set up all components of the SDK — pool context, trading logic, client access, and transaction building — in a single call.
 
-#### PoolContextProvider
+```ts
+import { api, createSdkContext } from '@galacticcouncil/sdk-next';
+import { createClient } from 'polkadot-api';
 
-Builds and maintains the pool context, handling subscriptions to pool changes.
+const provider = api.getWs('wss://hydradx-rpc.dwellir.com');
+const client = createClient(provider);
+const sdk = await createSdkContext(client);
 
-##### Usage
+// Don't forget to cleanup resources when DONE
+sdk.destroy();
+```
 
-Subscribe to desired AMMs. Only one `ctx` instance should exist!
+It handles all necessary setup under the hood. Just plug in your PolkadotClient, and you're ready to interact with registry, accounts, pools, router, and more.
 
-```typescript
-import { api, pool } from '@galacticcouncil/sdk-next';
+⚠️ **Note:** Make sure to keep only single instance of context per session.
 
-const client = await api.getWs('wss://rpc.hydradx.cloud');
-const ctx = new pool.PoolContextProvider(client)
-  .withOmnipool()
-  .withStableswap()
-  .withXyk();
+## Components
 
-const pools = await ctx.getPools();
-console.log(pools);
+### `api`
 
-// Don't forget to cleanup the resources
-ctx.destroy();
-client.destroy();
-```
+- `aave: AaveUtils` — Aave-related utilities.
+- `router: TradeRouter` — Off-chain optimization of trades across pools for best price execution.
+- `scheduler: TradeScheduler` — Trade orders scheduling.
 
-➡️ For type definitions visit [types.ts](src/pool/types.ts)<br />
+### `client`
 
-### SOR
+- `asset: AssetClient` — Registry metadata and lookup.
+- `balance: BalanceClient` — Account balance tracking.
+- `evm: EvmClient` — Interacts with EVM.
 
-#### Router
+### `ctx`
 
-Off-chain routing, build to find the most suitable routes across the pools. Building block for `TradeRouter`.
+- `pool: PoolContextProvider` — Internal stateful pool context. Initialized with support for:
+  - Aave
+  - Omnipool
+  - Stableswap
+  - XYK pools
+  - LBP pools
 
-##### API Reference
+### `tx`
 
-| Method | Description |
-| :----- | :----------- |
-| `getPools(): PoolBase[]` | Returns the current list of available pools. |
-| `getRoutes(assetIn: number, assetOut: number): Hop[][]` | Computes possible routes between two assets. |
-| `getTradeableAssets(): number[]` | Lists all assets that are tradeable through the router. |
+- `TxBuilderFactory` — Factory for generating submittable transaction using fluent APIs.
+
+### `destroy()`
 
-#### TradeRouter
+Gracefully cleans up SDK resources. Always call before exiting to avoid memory leaks or stale subscriptions.
 
-Off-chain optimization of orders across pools for best price execution. TradeRouter does not perform any on-chain transations.
+## API Reference
 
-##### API Reference
+### AaveUtils
 
-| Method | Description |
+| Method | Description  |
 | :----- | :----------- |
+| `getSummary(user: string): AaveSummary` | Returns market summary. |
+| `getHealthFactor(user: string): number` | Calculate HF. |
+| `getHealthFactorAfterWithdraw(user: string, reserve:number, withdrawAmount: string): number` | Calculate HF after withdraw. |
+| `getHealthFactorAfterSupply(user: string, reserve:number, supplyAmount: string): number` | Calculate HF after supply. |
+| `getMaxWithdraw(user: string, reserve:number): Amount` | Get max possible safe withdraw. |
+
+➡️ For type definitions visit [types.ts](src/aave/types.ts)<br />
+
+### TradeRouter
+
+| Method | Description  |
+| :----- | :----------- |
+| `getPools(): PoolBase[]` | Returns the current list of available pools. |
+| `getRoutes(assetIn: number, assetOut: number): Hop[][]` | Computes possible routes between two assets. |
+| `getTradeableAssets(): number[]` | Lists all assets that are tradeable through the router. |
 | `getBestSell(tokenIn: number, tokenOut: number, amountIn: bigint \| string): Trade` | Find the best sell trade for given input amount. |
 | `getBestBuy(tokenIn: number, tokenOut: number, amountOut: bigint \| string): Trade` | Find the best buy trade for given output amount. |
-| `getBuy(tokenIn: number, tokenOut: number, amountOut: bigint \| string, route?: Hop[]): Trade` | Execute a buy using a specified route (optional). |
-| `getSell(tokenIn: number, tokenOut: number, amountIn: bigint \| string, route?: Hop[]): Trade` | Execute a sell using a specified route (optional). |
+| `getBuy(tokenIn: number, tokenOut: number, amountOut: bigint \| string, route?: Hop[]): Trade` | Calculate a buy using a specific route (optional). |
+| `getSell(tokenIn: number, tokenOut: number, amountIn: bigint \| string, route?: Hop[]): Trade` | Calculate a sell using a specific route (optional). |
 | `getSpotPrice(tokenIn: number, tokenOut: number): Amount` | Get the current spot price between two tokens. |
 | `getMostLiquidRoute(tokenIn: number, tokenOut: number): Hop[]` | Find the route with the highest liquidity between two tokens. |
 
-##### Usage
+➡️ For type definitions visit [types.ts](src/sor/types.ts)<br />
 
-Calculate sell of 1 DOT for HDX. For convenience, the router amount can be specified either as a native bigint or as a human-readable string.
+### TradeScheduler
 
-For example, `"1"` DOT (string) is equivalent to `10_000_000_000n` (bigint), as DOT has 10 decimals.
+| Method | Description  |
+| :----- | :----------- |
+| `getDcaOrder(assetIn: number, assetOut: number, amountInTotal: string, duration: number): TradeDcaOrder` | Calculate DCA order. |
+| `getTwapBuyOrder(assetIn: number, assetOut: number, amountInTotal: string): TradeOrder` | Calculate TWAP buy order. |
+| `getTwapSellOrder(assetIn: number, assetOut: number, amountInTotal: string): TradeOrder` | Calculate TWAP sell order. |
 
-```typescript
-import { api, pool, sor } from '@galacticcouncil/sdk-next';
+➡️ For type definitions visit [types.ts](src/sor/types.ts)<br />
 
-const client = await api.getWs('wss://rpc.hydradx.cloud');
-const ctx = new pool.PoolContextProvider(client)
-  .withOmnipool()
-  .withStableswap()
-  .withXyk();
+### BalanceClient
 
-const router = new sor.TradeRouter(ctx);
-const utils = new sor.TradeUtils(client);
+| Method | Description  |
+| :----- | :----------- |
+| `watchBalance(address: string): Observable<AssetAmount>` | Subscribe account balance. |
+| `watchSystemBalance(address: string): Observable<AssetAmount>` | Subscribe native account balance. |
+| `watchTokenBalance(address: string, assetId: number): Observable<AssetAmount>` | Subscribe token account balance. |
+| `watchTokensBalance(address: string): Observable<AssetAmount[]>` | Subscribe tokens account balances. |
+| `watchErc20Balance(address: string, includeOnly?: number[]):  Observable<AssetAmount[]>` | Subscribe erc20 assets balances |
 
-const sell = await router.getBestSell(5, 0, 10_000_000_000n);
-const tx = await utils.buildSellTx(sell);
-console.log(sell.toHuman());
-console.log('Transaction hash: ' + tx.asHex());
+➡️ For type definitions visit [types.ts](src/types.ts)<br />
 
-// Don't forget to cleanup the resources
-ctx.destroy();
-client.destroy();
-```
+### AssetClient
 
-➡️ For type definitions visit [types.ts](src/sor/types.ts)<br />
+| Method | Description  |
+| :----- | :----------- |
+| `getSupported(includeInvalid?: boolean, external?: ExternalAsset[]): Promise<Asset[]>` | Returns assets with metadata from registry. |
+
+➡️ For type definitions visit [types.ts](src/types.ts)<br />
+
+## Examples
 
-### Client
+All examples assume SDK has been initialized, [see](#usage)
 
-#### BalanceClient
+### TradeRouter
 
-Subscribe to the balance of the Hydration account.
+Calculate sell of 1 DOT for HDX & build tx with 5% slippage (default to 1% if not specified)
 
 ```typescript
-import { api, client as c } from '@galacticcouncil/sdk-next';
+const { api, tx } = sdk;
+
+const trade = await api.router.getBestSell(5, 10, 10_000_000_000n);
+const tradeTx = await tx.trade(trade)
+  .withBeneficiary(BENEFICIARY)
+  .withSlippage(5)
+  .build();
+const tradeCall = await tradeTx.get().getEncodedData();
+console.log(trade.toHuman());
+console.log('Transaction hash:', Binary.toHex(tradeCall));
+```
+
+**Note:** For convenience, the router amount can be specified either as a native bigint or as a human-readable string.
 
-const omnipoolAddress = "7L53bUTBbfuj14UpdCNPwmgzzHSsrsTWBHX5pys32mVWM3C1"
+For example, `"1"` DOT (string) is equivalent to `10_000_000_000n` (bigint), as DOT has 10 decimals.
 
-const client = await api.getWs('wss://rpc.hydradx.cloud');
-const balanceClient = new c.BalanceClient(client);
-const observable = balanceClient.subscribeBalance(omnipoolAddress);
-const balances = firstValueFrom(observable);
-console.log(balances);
+### BalanceClient
 
-// Don't forget to cleanup the resources
-ctx.destroy();
-client.destroy();
+Subscribe hydration treasury account.
+
+```typescript
+const { client } = sdk;
+
+const account = "7L53bUTBbfuj14UpdCNPwmgzzHSsrsTWBHX5pys32mVWM3C1"
+const subscription = client.balance
+  .watch(account)
+  .subscribe((balances) => {
+    console.log(balances);
+  });
 ```
 
-## Examples
+### AssetClient
+
+Get default on-chain data.
 
-SDK Examples and testing helpers.
+```typescript
+const { client } = sdk;
 
-### Run
+const assets = await client.asset.getSupported();
+console.log(assets);
+```
 
-Run: `$ npx tsx ./test/script/examples/<examplePackage>/<exampleName>.ts` with valid example package & name.
+To demonstrate more full working examples on real chain see [script](test/script/examples) section.
 
-To demonstrate full working examples on real chain see [script](test/script/examples) section.
+Run: `$ npx tsx ./test/script/examples/<examplePackage>/<exampleName>.ts` with valid example package & name.

package/build/aave/AaveClient.d.ts

@@ -0,0 +1,77 @@
+import { EvmClient } from '../evm';
+export declare class AaveClient {
+    private client;
+    constructor(evm: EvmClient);
+    getBlockTimestamp(): Promise<number>;
+    getReservesData(): Promise<readonly [readonly {
+        underlyingAsset: `0x${string}`;
+        name: string;
+        symbol: string;
+        decimals: bigint;
+        baseLTVasCollateral: bigint;
+        reserveLiquidationThreshold: bigint;
+        reserveLiquidationBonus: bigint;
+        reserveFactor: bigint;
+        usageAsCollateralEnabled: boolean;
+        borrowingEnabled: boolean;
+        stableBorrowRateEnabled: boolean;
+        isActive: boolean;
+        isFrozen: boolean;
+        liquidityIndex: bigint;
+        variableBorrowIndex: bigint;
+        liquidityRate: bigint;
+        variableBorrowRate: bigint;
+        stableBorrowRate: bigint;
+        lastUpdateTimestamp: number;
+        aTokenAddress: `0x${string}`;
+        stableDebtTokenAddress: `0x${string}`;
+        variableDebtTokenAddress: `0x${string}`;
+        interestRateStrategyAddress: `0x${string}`;
+        availableLiquidity: bigint;
+        totalPrincipalStableDebt: bigint;
+        averageStableRate: bigint;
+        stableDebtLastUpdateTimestamp: bigint;
+        totalScaledVariableDebt: bigint;
+        priceInMarketReferenceCurrency: bigint;
+        priceOracle: `0x${string}`;
+        variableRateSlope1: bigint;
+        variableRateSlope2: bigint;
+        stableRateSlope1: bigint;
+        stableRateSlope2: bigint;
+        baseStableBorrowRate: bigint;
+        baseVariableBorrowRate: bigint;
+        optimalUsageRatio: bigint;
+        isPaused: boolean;
+        isSiloedBorrowing: boolean;
+        accruedToTreasury: bigint;
+        unbacked: bigint;
+        isolationModeTotalDebt: bigint;
+        flashLoanEnabled: boolean;
+        debtCeiling: bigint;
+        debtCeilingDecimals: bigint;
+        eModeCategoryId: number;
+        borrowCap: bigint;
+        supplyCap: bigint;
+        eModeLtv: number;
+        eModeLiquidationThreshold: number;
+        eModeLiquidationBonus: number;
+        eModePriceSource: `0x${string}`;
+        eModeLabel: string;
+        borrowableInIsolation: boolean;
+    }[], {
+        marketReferenceCurrencyUnit: bigint;
+        marketReferenceCurrencyPriceInUsd: bigint;
+        networkBaseTokenPriceInUsd: bigint;
+        networkBaseTokenPriceDecimals: number;
+    }]>;
+    getUserReservesData(user: string): Promise<readonly [readonly {
+        underlyingAsset: `0x${string}`;
+        scaledATokenBalance: bigint;
+        usageAsCollateralEnabledOnUser: boolean;
+        stableBorrowRate: bigint;
+        scaledVariableDebt: bigint;
+        principalStableDebt: bigint;
+        stableBorrowLastUpdateTimestamp: bigint;
+    }[], number]>;
+    getUserAccountData(user: string): Promise<readonly [bigint, bigint, bigint, bigint, bigint, bigint]>;
+}

package/build/aave/AaveUtils.d.ts

@@ -0,0 +1,78 @@
+import { AaveSummary } from './types';
+import { EvmClient } from '../evm';
+import { Amount } from '../types';
+export declare class AaveUtils {
+    private client;
+    constructor(evm: EvmClient);
+    getSummary(user: string): Promise<AaveSummary>;
+    /**
+     * Check if user has active borrow positions
+     *
+     * @param user - user address
+     * @returns true if user has debt, otherwise false
+     */
+    hasBorrowPositions(user: string): Promise<boolean>;
+    /**
+     * Get current user health factor
+     *
+     * @param user - user address
+     * @returns health factor decimal value
+     */
+    getHealthFactor(user: string): Promise<number>;
+    /**
+     * Estimate health factor after aToken withdraw
+     *
+     * @param user - user address
+     * @param reserve - reserve on-chain id (registry)
+     * @param withdrawAmount - aToken withdrawAmount amount (decimal)
+     * @returns health factor decimal value
+     */
+    getHealthFactorAfterWithdraw(user: string, reserve: number, withdrawAmount: string): Promise<number>;
+    /**
+     * Estimate health factor after reserve supply
+     *
+     * @param user - user address
+     * @param reserve - reserve on-chain id (registry)
+     * @param supplyAmount - reserve supply amount (decimal)
+     * @returns health factor decimal value
+     */
+    getHealthFactorAfterSupply(user: string, reserve: number, supplyAmount: string): Promise<number>;
+    /**
+     * Estimate health factor after swapping between reserves
+     *
+     * @param user - user address
+     * @param fromAmount - amount to withdraw (decimal)
+     * @param fromReserve - reserve on-chain id (registry) to withdraw from
+     * @param toAmount - amount to supply (decimal)
+     * @param toReserve - reserve on-chain id (registry) to supply to
+     * @returns health factor decimal value after swap
+     */
+    getHealthFactorAfterSwap(user: string, fromAmount: string, fromReserve: number, toAmount: string, toReserve: number): Promise<number>;
+    /**
+     * Get MAX withdraw balance for given user reserve
+     *
+     * @param user - user address
+     * @param reserve - reserve on-chain id (registry)
+     * @returns aToken max withdrawable balance
+     */
+    getMaxWithdraw(user: string, reserve: number): Promise<Amount>;
+    /**
+     * Get MAX withdraw balances for all user reserves
+     *
+     * @param user - user address
+     * @returns aTokens max withdrawable balances
+     */
+    getMaxWithdrawAll(user: string): Promise<Record<number, Amount>>;
+    /**
+     * Calculate maxWithdraw using following formula:
+     *
+     * maxWithdraw = (HF - 1.01 x totalDebt) / reserveLT
+     */
+    private calculateWithdrawMax;
+    private calculateLinearInterest;
+    /**
+     * Original AAVE health factor calculation formula:
+     * @see https://github.com/aave/aave-utilities/blob/432e283b2e76d9793b20d37bd4cb94aca97ed20e/packages/math-utils/src/pool-math.ts#L139
+     */
+    private calculateHealthFactorFromBalances;
+}

package/build/aave/abi/AavePool.d.ts

@@ -0,0 +1,208 @@
+export declare const AAVE_POOL_ABI: readonly [{
+    readonly anonymous: false;
+    readonly inputs: readonly [{
+        readonly indexed: true;
+        readonly internalType: "address";
+        readonly name: "reserve";
+        readonly type: "address";
+    }, {
+        readonly indexed: false;
+        readonly internalType: "address";
+        readonly name: "user";
+        readonly type: "address";
+    }, {
+        readonly indexed: true;
+        readonly internalType: "address";
+        readonly name: "onBehalfOf";
+        readonly type: "address";
+    }, {
+        readonly indexed: false;
+        readonly internalType: "uint256";
+        readonly name: "amount";
+        readonly type: "uint256";
+    }, {
+        readonly indexed: true;
+        readonly internalType: "uint16";
+        readonly name: "referralCode";
+        readonly type: "uint16";
+    }];
+    readonly name: "Supply";
+    readonly type: "event";
+}, {
+    readonly anonymous: false;
+    readonly inputs: readonly [{
+        readonly indexed: true;
+        readonly internalType: "address";
+        readonly name: "reserve";
+        readonly type: "address";
+    }, {
+        readonly indexed: true;
+        readonly internalType: "address";
+        readonly name: "user";
+        readonly type: "address";
+    }, {
+        readonly indexed: true;
+        readonly internalType: "address";
+        readonly name: "to";
+        readonly type: "address";
+    }, {
+        readonly indexed: false;
+        readonly internalType: "uint256";
+        readonly name: "amount";
+        readonly type: "uint256";
+    }];
+    readonly name: "Withdraw";
+    readonly type: "event";
+}, {
+    readonly inputs: readonly [{
+        readonly internalType: "address";
+        readonly name: "asset";
+        readonly type: "address";
+    }, {
+        readonly internalType: "uint256";
+        readonly name: "amount";
+        readonly type: "uint256";
+    }, {
+        readonly internalType: "address";
+        readonly name: "to";
+        readonly type: "address";
+    }];
+    readonly name: "withdraw";
+    readonly outputs: readonly [{
+        readonly internalType: "uint256";
+        readonly name: "";
+        readonly type: "uint256";
+    }];
+    readonly stateMutability: "nonpayable";
+    readonly type: "function";
+}, {
+    readonly anonymous: false;
+    readonly inputs: readonly [{
+        readonly indexed: true;
+        readonly internalType: "address";
+        readonly name: "reserve";
+        readonly type: "address";
+    }, {
+        readonly indexed: false;
+        readonly internalType: "address";
+        readonly name: "user";
+        readonly type: "address";
+    }, {
+        readonly indexed: true;
+        readonly internalType: "address";
+        readonly name: "onBehalfOf";
+        readonly type: "address";
+    }, {
+        readonly indexed: false;
+        readonly internalType: "uint256";
+        readonly name: "amount";
+        readonly type: "uint256";
+    }, {
+        readonly indexed: false;
+        readonly internalType: "enum DataTypes.InterestRateMode";
+        readonly name: "interestRateMode";
+        readonly type: "uint8";
+    }, {
+        readonly indexed: false;
+        readonly internalType: "uint256";
+        readonly name: "borrowRate";
+        readonly type: "uint256";
+    }, {
+        readonly indexed: true;
+        readonly internalType: "uint16";
+        readonly name: "referralCode";
+        readonly type: "uint16";
+    }];
+    readonly name: "Borrow";
+    readonly type: "event";
+}, {
+    readonly inputs: readonly [{
+        readonly internalType: "address";
+        readonly name: "asset";
+        readonly type: "address";
+    }, {
+        readonly internalType: "uint256";
+        readonly name: "amount";
+        readonly type: "uint256";
+    }, {
+        readonly internalType: "uint256";
+        readonly name: "interestRateMode";
+        readonly type: "uint256";
+    }, {
+        readonly internalType: "uint16";
+        readonly name: "referralCode";
+        readonly type: "uint16";
+    }, {
+        readonly internalType: "address";
+        readonly name: "onBehalfOf";
+        readonly type: "address";
+    }];
+    readonly name: "borrow";
+    readonly outputs: readonly [];
+    readonly stateMutability: "nonpayable";
+    readonly type: "function";
+}, {
+    readonly anonymous: false;
+    readonly inputs: readonly [{
+        readonly indexed: true;
+        readonly internalType: "address";
+        readonly name: "reserve";
+        readonly type: "address";
+    }, {
+        readonly indexed: true;
+        readonly internalType: "address";
+        readonly name: "user";
+        readonly type: "address";
+    }, {
+        readonly indexed: true;
+        readonly internalType: "address";
+        readonly name: "repayer";
+        readonly type: "address";
+    }, {
+        readonly indexed: false;
+        readonly internalType: "uint256";
+        readonly name: "amount";
+        readonly type: "uint256";
+    }, {
+        readonly indexed: false;
+        readonly internalType: "bool";
+        readonly name: "useATokens";
+        readonly type: "bool";
+    }];
+    readonly name: "Repay";
+    readonly type: "event";
+}, {
+    readonly inputs: readonly [{
+        readonly internalType: "address";
+        readonly name: "user";
+        readonly type: "address";
+    }];
+    readonly name: "getUserAccountData";
+    readonly outputs: readonly [{
+        readonly internalType: "uint256";
+        readonly name: "totalCollateralBase";
+        readonly type: "uint256";
+    }, {
+        readonly internalType: "uint256";
+        readonly name: "totalDebtBase";
+        readonly type: "uint256";
+    }, {
+        readonly internalType: "uint256";
+        readonly name: "availableBorrowsBase";
+        readonly type: "uint256";
+    }, {
+        readonly internalType: "uint256";
+        readonly name: "currentLiquidationThreshold";
+        readonly type: "uint256";
+    }, {
+        readonly internalType: "uint256";
+        readonly name: "ltv";
+        readonly type: "uint256";
+    }, {
+        readonly internalType: "uint256";
+        readonly name: "healthFactor";
+        readonly type: "uint256";
+    }];
+    readonly stateMutability: "view";
+    readonly type: "function";
+}];