@galacticcouncil/sdk 8.0.0 → 8.1.0

package/README.md

@@ -4,14 +4,23 @@
 
 Hydration sdk build on top of [@polkadot{.js} (Pjs)](https://polkadot.js.org/).
 
-Table of content:
+Table of contents:
 
 - [Installation](#installation)
 - [Troubleshooting](#troubleshooting)
 - [Usage](#usage)
-  - [PoolService](#poolservice)
-  - [Router](#router)
+- [Components](#components)
+  - [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
 
@@ -21,6 +30,14 @@ Install with [npm](https://www.npmjs.com/):
 
 ## Troubleshooting
 
+### Version 8.x
+
+⚠️ **Important:** In the 8.x release, we upgraded `@polkadot/api` to version **16.x**. 
+
+See the [changelog](https://github.com/galacticcouncil/sdk/blob/master/packages/sdk/CHANGELOG.md#800) for details.
+
+### Version 2.x
+
 As of **v2.x** .wasm files are no longer embedded in bundle
 but rather deferred to improve load performance & decrease
 module size (esm only).
@@ -29,72 +46,76 @@ For more details visit [TROUBLESHOOTING.md](TROUBLESHOOTING.md)
 
 ## Usage
 
-⚠️ Important: In the 8.x release, we upgraded `@polkadot/api` to version **16.x**.
+Use `createSdkContext` to quickly set up all components of the SDK — pool context, trading logic, client access, and transaction building — in a single call.
 
-> 🐛 **Note:** A **TTL-based LRU cache** was introduced starting from
-`@polkadot/api` **v14.1.1**, which can break router behavior if not
-addressed (eviction issue).
+```ts
+import { createSdkContext } from '@galacticcouncil/sdk';
+import { ApiPromise, WsProvider } from '@polkadot/api';
 
-- 📄 [Release notes – v14.1.1](https://github.com/polkadot-js/api/releases/tag/v14.1.1)  
-- 🐞 [GitHub Issue #6154](https://github.com/polkadot-js/api/issues/6154)
-- 🐞 [GitHub Issue #6122](https://github.com/polkadot-js/api/issues/6122)
+const ws = 'wss://hydration-rpc.n.dwellir.com';
+const wsProvider = new WsProvider(ws, 2_500, {}, 60_000, 102400, 10 * 60_000);
 
-To ensure the router works as expected, **either**:
+const api = await ApiPromise.create({
+  provider: wsProvider,
+});
 
-1. Use a custom `WsProvider` configuration with cache TTL at least 10 minutes
-2. Use a custom `WsProvider` configuration with cache TTL disabled (null)
+const sdk = await createSdkContext(api);
 
-```typescript
-const wsProvider = new WsProvider(
-  ws,
-  2_500, // autoConnect (2.5 seconds)
-  {}, // headers
-  60_000, // request timeout  (60 seconds)
-  102400, // cache capacity
-  10 * 60_000 // cache TTL (10 minutes)
-);
+// Don't forget to cleanup resources when DONE
+sdk.destroy();
+api.disconnect();
 ```
 
-### PoolService
+It handles all necessary setup under the hood. Just plug in your ApiPromise, and you're ready to interact with registry, accounts, pools, router, and more.
 
-Build and subscribe to the given AMM types, supplying data for the Router API.
+⚠️ **Note:** Make sure to keep only single instance of context per session.
 
-⚠️ **Note:** Make sure to keep only single instance of service per session.
+## Components
 
-#### API Reference (internal)
+### `api`
 
-| Method | Description  |
-| :----- | :----------- |
-| `getPools(): Promise<PoolBase[]>` | Returns list of available pools. |
-| `getPoolFees(pool: PoolBase, feeAsset: string): Promise<PoolFees>` | Returns current pool fees |
+- `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`
 
-#### Example
+- `asset: AssetClient` — Registry metadata and lookup.
+- `balance: BalanceClient` — Account balance tracking.
+- `evm: EvmClient` — Interacts with EVM.
 
-Initialize pool context and sync registry.
+### `ctx`
 
-```typescript
-import { ApiPromise, WsProvider } from '@polkadot/api';
-import { TradeRouter, PoolService, PoolType } from '@galacticcouncil/sdk';
+- `pool: PoolService` — Internal stateful pool context. Initialized with support for:
+  - Aave
+  - Omnipool
+  - Stableswap
+  - XYK pools
+  - LBP pools
 
-const ws = 'wss://hydration-rpc.n.dwellir.com';
-const wsProvider = new WsProvider(ws, 2_500, {}, 60_000, 102400, 10 * 60_000);
-const api = await ApiPromise.create({ provider: wsProvider });
+### `tx`
 
-const poolService = new PoolService(api);
-await poolService.syncRegistry();
+- `TxBuilderFactory` — Factory for generating submittable transaction using fluent APIs.
 
-// Don't forget to cleanup the resources
-poolService.destroy();
-api.disconnect();
-```
+### `destroy()`
 
-### Router
+Gracefully cleans up SDK resources. Always call before exiting to avoid memory leaks or stale subscriptions.
 
-Off-chain routing, build to find the most suitable routes across the pools. Building block for `TradeRouter`.
+## API Reference
 
-#### API Reference
+### AaveUtils
+
+| Method | Description  |
+| :----- | :----------- |
+| `getSummary(user: string): AaveSummary` | Returns market summary. |
+| `getHealthFactor(user: string): number` | Calculate HF. |
+| `getHealthFactorAfterWithdraw(user: string, reserve:string, withdrawAmount: string): number` | Calculate HF after withdraw. |
+| `getHealthFactorAfterSupply(user: string, reserve:string, supplyAmount: string): number` | Calculate HF after supply. |
+| `getMaxWithdraw(user: string, reserve:string): Amount` | Get max possible safe withdraw. |
+
+➡️ For type definitions visit [types.ts](src/aave/types.ts)<br />
+
+### TradeRouter
 
 | Method | Description  |
 | :----- | :----------- |
@@ -102,104 +123,64 @@ Off-chain routing, build to find the most suitable routes across the pools. Buil
 | `getAllPaths(tokenIn: string, tokenOut: string): Hop[][]` | Computes possible routes between two assets. |
 | `getAllAssets(): PoolBase[]` | Lists all assets that are tradeable through the router. |
 | `getAssetPairs(token: string): Asset[]` | Lists all assets given token is tradeable with. |
+| `getBestSell(tokenIn: string, tokenOut: string, amountIn: bigint \| string): Trade` | Find the best sell trade for given input amount. |
+| `getBestBuy(tokenIn: string, tokenOut: string, amountOut: bigint \| string): Trade` | Find the best buy trade for given output amount. |
+| `getBuy(tokenIn: string, tokenOut: string, amountOut: bigint \| string, route?: Hop[]): Trade` | Calculate a buy using a specific route (optional). |
+| `getSell(tokenIn: string, tokenOut: string, amountIn: bigint \| string, route?: Hop[]): Trade` | Calculate a sell using a specific route (optional). |
+| `getBestSpotPrice(tokenIn: string, tokenOut: string): Amount` | Get the current spot price between two tokens. |
+| `getMostLiquidRoute(tokenIn: string, tokenOut: string): Hop[]` | Find the route with the highest liquidity between two tokens. |
 
 ➡️ For type definitions visit [types.ts](src/sor/types.ts)<br />
 
-#### Example
-
-List all tradable assets available in the current pool context.
+### TradeScheduler
 
-```typescript
-import { ApiPromise, WsProvider } from '@polkadot/api';
-import { TradeRouter, PoolService, PoolType } from '@galacticcouncil/sdk';
-
-const ws = 'wss://hydration-rpc.n.dwellir.com';
-const wsProvider = new WsProvider(ws, 2_500, {}, 60_000, 102400, 10 * 60_000);
-const api = await ApiPromise.create({ provider: wsProvider });
-
-const poolService = new PoolService(api);
-const router = new Router(poolService);
-
-const assets = await router.getAllAssets();
-console.log(assets);
-
-// Don't forget to cleanup the resources
-poolService.destroy();
-api.disconnect();
-```
-
-### TradeRouter
+| Method | Description  |
+| :----- | :----------- |
+| `getDcaOrder(assetIn: string, assetOut: string, amountInTotal: string, duration: number): TradeDcaOrder` | Calculate DCA order. |
+| `getTwapBuyOrder(assetIn: string, assetOut: string, amountInTotal: string): TradeOrder` | Calculate TWAP buy order. |
+| `getTwapSellOrder(assetIn: string, assetOut: string, amountInTotal: string): TradeOrder` | Calculate TWAP buy order. |
 
-Off-chain optimization of orders across pools for best price execution. TradeRouter does not perform any on-chain transations.
+➡️ For type definitions visit [types.ts](src/sor/types.ts)<br />
 
-#### Api Reference
+### AssetClient
 
 | Method | Description  |
 | :----- | :----------- |
-| `getBestSell(tokenIn: string, tokenOut: string, amountIn: bigint \| string): Trade` | Find the best sell trade for given input amount. |
-| `getBestBuy(tokenIn: string, tokenOut: string, amountOut: bigint \| string): Trade` | Find the best buy trade for given output amount. |
-| `getBuy(tokenIn: string, tokenOut: string, amountOut: bigint \| string, route?: Hop[]): Trade` | Calculate a buy using a specific route (optional). |
-| `getSell(tokenIn: string, tokenOut: string, amountIn: bigint \| string, route?: Hop[]): Trade` | Calculate a sell using a specific route (optional). |
-| `getSpotPrice(tokenIn: string, tokenOut: string): Amount` | Get the current spot price between two tokens. |
-| `getMostLiquidRoute(tokenIn: string, tokenOut: string): Hop[]` | Find the route with the highest liquidity between two tokens. |
+| `getOnChainAssets(includeInvalid?: boolean, external?: ExternalAsset[]): Promise<Asset[]>` | Returns assets with metadata from registry. |
 
-➡️ For type definitions visit [types.ts](src/sor/types.ts)<br />
+➡️ For type definitions visit [types.ts](src/types.ts)<br />
+
+## Examples
 
-#### Example
+All examples assume sdk have been initialized [see](#usage)
+
+### TradeRouter
 
 Calculate sell of 1 DOT for HDX & build tx with 5% slippage (default to 1% if not specified)
 
 ```typescript
-import { ApiPromise, WsProvider } from '@polkadot/api';
-import { TradeRouter, PoolService, PoolType } from '@galacticcouncil/sdk';
-
-const ws = 'wss://hydration-rpc.n.dwellir.com';
-const wsProvider = new WsProvider(ws, 2_500, {}, 60_000, 102400, 10 * 60_000);
-const api = await ApiPromise.create({ provider: wsProvider });
+const { api, tx } = sdk;
+
+const trade = await api.router.getBestSell("5", "10", "10");
+const tradeTx = await tx.trade(trade)
+  .withBeneficiary(BENEFICIARY)
+  .withSlippage(5)
+  .build();
+console.log(trade.toHuman());
+console.log('Transaction hash:', tradeTx.hex);
+```
 
-const poolService = new PoolService(api);
-const txUtils = new TradeUtils(api);
+### AssetClient
 
-const router = new TradeRouter(poolService);
+Get default on-chain data.
 
-const sell = await router.getBestSell("5", "0", "1");
-const tx = await utils.buildSellTx(sell, 5);
-console.log(sell.toHuman());
-console.log('Transaction hash: ' + transaction.hex);
+```typescript
+const { client } = sdk;
 
-// Don't forget to cleanup the resources
-poolService.destroy();
-api.disconnect();
+const assets = await client.asset.getOnChainAssets();
+console.log(assets);
 ```
 
-## Examples
-
 To demonstrate more full working examples on real chain see [script](test/script/examples) section.
 
-### Execution
-
-Run: `$ npx tsx ./test/script/examples/<examplePackage>/<exampleName>.ts` with valid example package & name.
-
-## Roadmap
-
-Component list and current status ⬇️
-
-- 🧪 Done
-- 🛠 Work in progress
-- ⏳ Planning to build
-
-| Name        | Type |     |
-| ----------- | :--: | --: |
-| Dca         | API  |  ⏳ |
-| Router      | API  |  🧪 |
-| TradeRouter | API  |  🧪 |
-| Twap        | API  |  ⏳ |
-| LBP         | Math |  🧪 |
-| LBP         | Pool |  🧪 |
-| Omni        | Math |  🧪 |
-| Omni        | Pool |  🧪 |
-| Stable      | Math |  🧪 |
-| Stable      | Pool |  🧪 |
-| XYK         | Math |  🧪 |
-| XYK         | Pool |  🧪 |
-| Aave        | Pool |  🧪 |
+Run: `$ npx tsx ./test/script/examples/<examplePackage>/<exampleName>.ts` with valid example package & name.