@galacticcouncil/sdk-next 0.1.0 → 0.3.0

package/README.md

@@ -4,15 +4,26 @@
 
 Next gen hydration sdk build on top of [Polkadot API (Papi)](https://papi.how/).
 
-Table of content:
+⚠️ **Disclaimer:** Next is not prod ready yet. Official `1.x` release coming soon.
+
+Missing functionality & progress tracked [here](https://github.com/galacticcouncil/sdk/issues/119)
+
+Table of contents:
 
 - [Installation](#installation)
 - [Usage](#usage)
-  - [PoolContextProvider](#poolcontextprovider)
-  - [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
 
@@ -22,87 +33,75 @@ Install with [npm](https://www.npmjs.com/):
 
 ## Usage
 
-### PoolContextProvider
-
-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.
-
-#### API Reference (internal)
-
-| Method | Description  |
-| :----- | :----------- |
-| `getPools(): Promise<PoolBase[]>` | Returns list of available pools. |
-| `getPoolFees(pool: PoolBase, feeAsset: number): Promise<PoolFees>` | Returns current pool fees |
-
-➡️ For type definitions visit [types.ts](src/pool/types.ts)<br />
-
-#### Example
-
-Initialize pool context supporting Omnipool, Stableswap & XYK pools.
+Use `createSdkContext` to quickly set up all components of the SDK — pool context, trading logic, client access, and transaction building — in a single call.
 
-```typescript
-import { api, pool, sor } from '@galacticcouncil/sdk-next';
+```ts
+import { api, createSdkContext } from '@galacticcouncil/sdk-next';
 
 const client = await api.getWs('wss://hydradx-rpc.dwellir.com');
+const sdk = await createSdkContext(client);
 
-const ctx = new pool.PoolContextProvider(client)
-  .withOmnipool()
-  .withStableswap()
-  .withXyk();
-
-// Don't forget to cleanup the resources
-ctx.destroy();
+// Don't forget to cleanup resources when DONE
+sdk.destroy();
 client.destroy();
 ```
 
-### Router
+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.
 
-Off-chain routing, build to find the most suitable routes across the pools. Building block for `TradeRouter`.
+⚠️ **Note:** Make sure to keep only single instance of context per session.
 
-#### API Reference
+## Components
 
-| 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. |
+### `api`
 
-➡️ For type definitions visit [types.ts](src/sor/types.ts)<br />
+- `aave: AaveUtils` — Aave-related utilities.
+- `router: TradeRouter` — Off-chain optimization of trades across pools for best price execution.
+- `scheduler: TradeScheduler` — Trade orders scheduling.
 
-#### Example
+### `client`
 
-List all tradable assets available in the current pool context.
+- `asset: AssetClient` — Registry metadata and lookup.
+- `balance: BalanceClient` — Account balance tracking.
+- `evm: EvmClient` — Interacts with EVM.
 
-```typescript
-import { api, pool, sor } from '@galacticcouncil/sdk-next';
+### `ctx`
 
-const client = await api.getWs('wss://hydradx-rpc.dwellir.com');
+- `pool: PoolContextProvider` — Internal stateful pool context. Initialized with support for:
+  - Aave
+  - Omnipool
+  - Stableswap
+  - XYK pools
+  - LBP pools
 
-// Make sure to keep only single instance of context per session
-const ctx = new pool.PoolContextProvider(client)
-  .withOmnipool()
-  .withStableswap()
-  .withXyk();
+### `tx`
 
-const router = new sor.Router(ctx);
+- `TxBuilderFactory` — Factory for generating submittable transaction using fluent APIs.
 
-const assets = await router.getTradeableAssets();
-console.log(assets);
+### `destroy()`
 
-// Don't forget to cleanup the resources
-ctx.destroy();
-client.destroy();
-```
+Gracefully cleans up SDK resources. Always call before exiting to avoid memory leaks or stale subscriptions.
 
-### TradeRouter
+## API Reference
+
+### AaveUtils
+
+| 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. |
 
-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/aave/types.ts)<br />
 
-#### Api Reference
+### 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` | Calculate a buy using a specific route (optional). |
@@ -112,112 +111,86 @@ Off-chain optimization of orders across pools for best price execution. TradeRou
 
 ➡️ For type definitions visit [types.ts](src/sor/types.ts)<br />
 
-#### Example
+### TradeScheduler
 
-Calculate sell of 1 DOT for HDX & build tx with 5% slippage (default to 1% if not specified)
+| 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 buy 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://hydradx-rpc.dwellir.com');
+### BalanceClient
 
-const ctx = new pool.PoolContextProvider(client)
-  .withOmnipool()
-  .withStableswap()
-  .withXyk();
+| Method | Description  |
+| :----- | :----------- |
+| `subscribeSystemBalance(address: string): Observable<AssetAmount>` | Subscribe native account balance. |
+| `subscribeTokenBalance(address: string, assetId: number): Observable<AssetAmount>` | Subscribe token account balance. |
+| `subscribeTokensBalance(address: string): Observable<AssetAmount[]>` | Subscribe tokens account balances. |
+| `subscribeErc20Balance(address: string, includeOnly?: number[]):  Observable<AssetAmount[]>` | Subscribe erc20 assets balances |
 
-const router = new sor.TradeRouter(ctx);
-const utils = new sor.TradeUtils(client);
+➡️ For type definitions visit [types.ts](src/types.ts)<br />
 
-const sell = await router.getBestSell(5, 0, 10_000_000_000n);
-const tx = await utils.buildSellTx(sell, 5);
-console.log(sell.toHuman());
-console.log('Transaction hash:', tx.asHex());
+### AssetClient
 
-// Don't forget to cleanup the resources
-ctx.destroy();
-client.destroy();
-```
+| Method | Description  |
+| :----- | :----------- |
+| `getOnChainAssets(includeInvalid?: boolean, external?: ExternalAsset[]): Promise<Asset[]>` | Returns assets with metadata from registry. |
 
-**Note:** For convenience, the router amount can be specified either as a native bigint or as a human-readable string.
+➡️ For type definitions visit [types.ts](src/types.ts)<br />
 
-For example, `"1"` DOT (string) is equivalent to `10_000_000_000n` (bigint), as DOT has 10 decimals.
+## Examples
 
-### BalanceClient
+All examples assume sdk have been initialized [see](#usage)
 
-Helper class supporting the following standards:
+### TradeRouter
 
-- "Native assets"
-- "Token assets"
-- "ERC-20 tokens"
+Calculate sell of 1 DOT for HDX & build tx with 5% slippage (default to 1% if not specified)
 
-#### API Reference
+```typescript
+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:', tradeCall.asHex());
+```
 
-| Method | Description  |
-| :----- | :----------- |
-| `subscribeSystemBalance(address: string): Observable<AssetAmount>` | Subscribe native account balance. |
-| `subscribeTokenBalance(address: string, assetId: number): Observable<AssetAmount>` | Subscribe token account balance. |
-| `subscribeTokensBalance(address: string): Observable<AssetAmount[]>` | Subscribe tokens account balances. |
-| `subscribeErc20Balance(address: string, includeOnly?: number[]):  Observable<AssetAmount[]>` | Subscribe erc20 assets balances |
+**Note:** For convenience, the router amount can be specified either as a native bigint or as a human-readable string.
 
-➡️ For type definitions visit [types.ts](src/types.ts)<br />
+For example, `"1"` DOT (string) is equivalent to `10_000_000_000n` (bigint), as DOT has 10 decimals.
 
-#### Example
+### BalanceClient
 
 Subscribe hydration treasury account.
 
 ```typescript
-import { api, client as c } from '@galacticcouncil/sdk-next';
+const { client } = sdk;
 
 const account = "7L53bUTBbfuj14UpdCNPwmgzzHSsrsTWBHX5pys32mVWM3C1"
-
-const client = await api.getWs('wss://hydradx-rpc.dwellir.com');
-const balanceClient = new c.BalanceClient(client);
-
-const subscription = balanceClient
+const subscription = client.balance
   .subscribeBalance(account)
   .subscribe((balances) => {
     console.log(balances);
   });
-
-// Don't forget to cleanup the resources
-subscription.unsubscribe();
-client.destroy();
 ```
 
 ### AssetClient
 
-Helper class to fetch registry metadata.
-
-#### API Reference
-
-| Method | Description  |
-| :----- | :----------- |
-| `getOnChainAssets(includeInvalid?: boolean, external?: ExternalAsset[]): Promise<Asset[]>` | Returns assets with metadata from registry. |
-
-➡️ For type definitions visit [types.ts](src/types.ts)<br />
-
-#### Example
-
 Get default on-chain data.
 
 ```typescript
-import { api, client as c } from '@galacticcouncil/sdk-next';
-
-const client = await api.getWs('wss://hydradx-rpc.dwellir.com');
-const assetClient = new c.AssetClient(client);
+const { client } = sdk;
 
-const assets = await assetClient.getOnChainAssets();
+const assets = await client.asset.getOnChainAssets();
 console.log(assets);
-
-// Don't forget to cleanup the resources
-client.destroy();
 ```
 
-## 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.