@zuhaibnoor/zigchain-sdk 1.1.0 → 1.1.1

package/docs/dex.md

@@ -1,7 +1,85 @@
-# Decentralized Exchange (DEX) Module
+# DEX Module
 
-The **ChainDexApi** allows you to interact with the chain’s decentralized exchange (DEX).
-It is used to fetch information about liquidity pools, pool balances, pool IDs for token pairs, and DEX parameters.
+## What is the DEX Module?
+
+The **DEX module** is a ZigChain-native decentralized exchange built directly into the chain.
+
+---
+
+## Important Terminology
+
+### Pool
+
+A **pool** is a liquidity pair that holds two tokens in reserve. Users can swap between those two tokens, with the exchange rate determined by the pool's pricing formula.
+
+Each pool is identified by a unique **pool ID** in the format `zp<number>`.
+
+Example:
+```
+zp23
+```
+
+---
+
+### Pool ID
+
+A unique identifier assigned to each pool when it is created.
+
+```
+pool_id = 'zp23'
+```
+
+---
+
+### LP Token
+
+A **Liquidity Provider token** is minted and given to users when they deposit tokens into a pool. It represents their proportional ownership of the pool's reserves.
+
+LP tokens use the pool ID as their denom:
+```
+denom = 'zp23'
+amount = '1414213'
+```
+
+When a user withdraws liquidity, their LP tokens are burned and the underlying tokens are returned.
+
+---
+
+### Fee
+
+The swap fee charged on each trade.
+
+```
+fee = 100  →  1% swap fee (100 basis points)
+```
+
+---
+
+### Pool UID
+
+A human-readable string that uniquely identifies a token pair, regardless of which pool holds them.
+
+```
+pool_uid = 'coin.zig12jzwc0a3pyv4dze0t252qkwf77t4vs5rqfn3zc.panda-uzig'
+```
+
+This is constructed by joining the two token denoms with a `-` separator.
+
+---
+
+### Pool Address
+
+Every pool has its own on-chain address that holds the actual token reserves.
+
+```
+address = 'zig1zhltn0ffu30waa5vlagwrsue30xflfem2k0753'
+```
+
+---
+
+### Slippage
+
+The difference between the expected and actual price of a swap due to pool reserve changes. `max_slippage` in the DEX params defines the maximum tolerated slippage (in basis points) before a swap is rejected.
 
 ---
 
@@ -20,140 +98,312 @@ const dexApi = new ChainDexApi(endpoints)
 
 ---
 
-## `fetchPool`
+# 1️⃣ fetchPool
+
+## Method
 
-Fetch **details of a specific liquidity pool** by its pool ID.
+```ts
+async fetchPool(poolId: string)
+```
 
-**CLI equivalent**
+## CLI Equivalent
 
 ```bash
 zigchaind query dex get-pool <pool-id>
 ```
 
-**Method**
+## Description
 
-```ts
-fetchPool(poolId: string)
-```
+Fetches the **full details of a specific liquidity pool** by its pool ID.
+
+Returns the pool's configuration including its token pair, current reserve amounts, LP token supply, swap fee, pricing formula, creator, and on-chain address.
 
-**Parameters**
+---
 
-* `poolId: string` – The ID of the pool you want to query.
+## Parameters
 
-**Returns**
+| Name   | Type   | Description                              |
+| ------ | ------ | ---------------------------------------- |
+| poolId | string | Pool identifier in the format `zp<number>` (e.g. `'zp23'`) |
 
-* `DexPoolResponse` – Includes pool tokens, liquidity, swap fees, and other pool data.
+---
 
-**Example**
+## Usage Example
 
 ```ts
-const pool = await dexApi.fetchPool('1')
-console.log('Pool info:')
+const pool = await dexApi.fetchPool('zp23')
 console.dir(pool, { depth: null })
 ```
 
+## Example Response
+
+```json
+{
+  "pool": {
+    "pool_id": "zp23",
+    "lp_token": { "denom": "zp23", "amount": "1414213" },
+    "creator": "zig1648nalqktvkes73hxn4spayp3p5my0hq0hl9pe",
+    "fee": 100,
+    "formula": "constant_product",
+    "coins": [
+      {
+        "denom": "coin.zig1648nalqktvkes73hxn4spayp3p5my0hq0hl9pe.apl",
+        "amount": "1000"
+      },
+      { "denom": "uzig", "amount": "2000000000" }
+    ],
+    "address": "zig1zhltn0ffu30waa5vlagwrsue30xflfem2k0753"
+  }
+}
+```
+
+## Response Field Explanation
+
+### `pool`
+
+| Field          | Description                                                             |
+| -------------- | ----------------------------------------------------------------------- |
+| pool_id        | Unique pool identifier (e.g. `zp23`)                                    |
+| lp_token.denom | LP token denom — same as the pool ID                                    |
+| lp_token.amount | Total LP tokens currently in circulation                               |
+| creator        | Address that created this pool                                          |
+| fee            | Swap fee in basis points (100 = 1%)                                     |
+| formula        | Pricing model used (`constant_product`)                                 |
+| coins          | Array of the two token reserves held in this pool                       |
+| address        | On-chain address of the pool's reserve account                          |
+
+### `coins[]`
+
+| Field  | Description                              |
+| ------ | ---------------------------------------- |
+| denom  | Token denomination                       |
+| amount | Current reserve amount in the pool       |
+
+## When to Use
+
+* Displaying pool details in a DEX interface
+* Calculating current exchange rates from reserve ratios
+* Checking pool fee and formula before executing a swap
+* Verifying a pool's creator and configuration
+
 ---
 
-## `fetchPoolBalances`
+# 2️⃣ fetchPoolBalances
+
+## Method
 
-Fetch **balances of tokens in a specific pool**.
+```ts
+async fetchPoolBalances(poolId: string)
+```
 
-**CLI equivalent**
+## CLI Equivalent
 
 ```bash
 zigchaind query dex get-pool-balances <pool-id>
 ```
 
-**Method**
+## Description
+
+Fetches the **current token balances** held in a specific pool, alongside the full pool metadata.
+
+While `fetchPool` already includes reserve amounts inside `coins`, this endpoint provides a dedicated `balances` array that is more convenient for balance-focused queries — for example when building swap calculators or liquidity displays.
+
+## Parameters
+
+| Name   | Type   | Description                                              |
+| ------ | ------ | -------------------------------------------------------- |
+| poolId | string | Pool identifier in the format `zp<number>` (e.g. `'zp23'`) |
+
+## Usage Example
 
 ```ts
-fetchPoolBalances(poolId: string)
+const poolBalances = await dexApi.fetchPoolBalances('zp23')
+console.dir(poolBalances, { depth: null })
 ```
 
-**Parameters**
+## Example Response
+
+```json
+{
+  "pool": {
+    "pool_id": "zp23",
+    "lp_token": { "denom": "zp23", "amount": "1414213" },
+    "creator": "zig1648nalqktvkes73hxn4spayp3p5my0hq0hl9pe",
+    "fee": 100,
+    "formula": "constant_product",
+    "coins": [
+      { "denom": "coin.zig1648nalqktvkes73hxn4spayp3p5my0hq0hl9pe.apl", "amount": "1000" },
+      { "denom": "uzig", "amount": "2000000000" }
+    ],
+    "address": "zig1zhltn0ffu30waa5vlagwrsue30xflfem2k0753"
+  },
+  "balances": [
+    { "denom": "coin.zig1648nalqktvkes73hxn4spayp3p5my0hq0hl9pe.apl", "amount": "1000" },
+    { "denom": "uzig", "amount": "2000000000" }
+  ]
+}
+```
 
-* `poolId: string` – The pool ID to query balances for.
+## Response Field Explanation
 
-**Returns**
+### `pool`
 
-* `DexPoolBalancesResponse` – Contains the amounts of each token in the pool.
+Full pool metadata — identical structure to `fetchPool`. See that section for field descriptions.
 
-**Example**
+### `balances`
 
-```ts
-const balances = await dexApi.fetchPoolBalances('1')
-console.log('Pool balances:')
-console.dir(balances, { depth: null })
-```
+A dedicated array of the current token reserves held in the pool.
+
+| Field  | Description                             |
+| ------ | --------------------------------------- |
+| denom  | Token denomination                      |
+| amount | Current reserve amount in the pool      |
+
+### `fetchPool` vs `fetchPoolBalances`
+
+| Feature                    | fetchPool    | fetchPoolBalances         |
+| -------------------------- | ------------ | ------------------------- |
+| Full pool metadata         | ✅ Yes       | ✅ Yes (same pool object) |
+| Dedicated balances array   | ❌ No        | ✅ Yes                    |
+| Use case                   | Pool info    | Balance-focused queries   |
+
+## When to Use
+
+* Building swap calculators that need clean reserve amounts
+* Displaying current pool liquidity depth
+* Monitoring pool reserve changes over time
 
 ---
 
-## `fetchPoolUids`
+# 3️⃣ fetchPoolUids
+
+## Method
 
-Fetch the **pool IDs for a given token pair**.
+```ts
+async fetchPoolUids(tokenA: string, tokenB: string)
+```
 
-**CLI equivalent**
+## CLI Equivalent
 
 ```bash
 zigchaind query dex pool-uids <tokenA> <tokenB>
 ```
 
-**Method**
+## Description
 
-```ts
-fetchPoolUids(tokenA: string, tokenB: string)
-```
+Resolves the **pool UID and pool ID** for a given token pair.
 
-**Parameters**
+Use this when you know the two tokens you want to swap or provide liquidity for, but don't know which pool serves that pair. This is the lookup function that maps a token pair to its corresponding pool.
 
-* `tokenA: string` – Symbol or denom of the first token.
-* `tokenB: string` – Symbol or denom of the second token.
+## Parameters
 
-**Returns**
+| Name   | Type   | Description                                    |
+| ------ | ------ | ---------------------------------------------- |
+| tokenA | string | Full denom of the first token in the pair      |
+| tokenB | string | Full denom of the second token in the pair     |
 
-* `poolUidResponse` – Pool IDs that match the token pair.
+> Pass the full token denom, not a short symbol — e.g. `'coin.zig12jzwc0a3pyv4dze0t252qkwf77t4vs5rqfn3zc.panda'` not `'panda'`.
 
-**Example**
+## Usage Example
 
 ```ts
-const uids = await dexApi.fetchPoolUids('uzig', 'uatom')
-console.log('Pool IDs for token pair:')
-console.dir(uids, { depth: null })
+const poolUids = await dexApi.fetchPoolUids(
+  'coin.zig12jzwc0a3pyv4dze0t252qkwf77t4vs5rqfn3zc.panda',
+  'uzig'
+)
+console.dir(poolUids, { depth: null })
+```
+
+## Example Response
+
+```json
+{
+  "pool_uids": {
+    "pool_uid": "coin.zig12jzwc0a3pyv4dze0t252qkwf77t4vs5rqfn3zc.panda-uzig",
+    "pool_id": "zp72"
+  }
+}
 ```
 
+## Response Field Explanation
+
+### `pool_uids`
+
+| Field    | Description                                                               |
+| -------- | ------------------------------------------------------------------------- |
+| pool_uid | Human-readable string identifying this token pair (`tokenA-tokenB`)       |
+| pool_id  | The pool ID for this pair — use this with `fetchPool` or `fetchPoolBalances` |
+
+> Once you have the `pool_id`, you can pass it to `fetchPool('zp72')` or `fetchPoolBalances('zp72')` to get full pool details.
+
+## When to Use
+
+* Finding which pool to use for a given token pair
+* Resolving a pool ID before executing a swap
+* Checking if a pool exists for a specific pair
+
 ---
 
-## `fetchParams`
+# 4️⃣ fetchParams
+
+## Method
 
-Fetch the **DEX module parameters**.
+```ts
+async fetchParams()
+```
 
-**CLI equivalent**
+## CLI Equivalent
 
 ```bash
 zigchaind query dex params
 ```
 
-**Method**
+## Description
 
-```ts
-fetchParams()
-```
+Fetches the **DEX module parameters** configured at chain level.
+
+These are governance-controlled settings that define pool creation costs, fee structures, slippage limits, and the beneficiary address that receives protocol fees.
 
-**Returns**
+## Parameters
 
-* `DexParamsResponse` – Includes swap fees, allowed pools, and other DEX settings.
+None.
 
-**Example**
+## Usage Example
 
 ```ts
 const params = await dexApi.fetchParams()
-console.log('DEX params:')
 console.dir(params, { depth: null })
 ```
 
----
+## Example Response
+
+```json
+{
+  "params": {
+    "new_pool_fee_pct": 100,
+    "creation_fee": 10000000,
+    "beneficiary": "zig1s3mhkcycpgjj5tdv09ux6qg7hgzcyu6shzsfu0",
+    "minimal_liquidity_lock": 1000,
+    "max_slippage": 100
+  }
+}
+```
+
+## Response Field Explanation
 
-## Notes
+### `params`
 
-* All queries are **read-only** and do not require a wallet.
-* Pool-related queries are useful for **tracking liquidity, swaps, and token balances**.
+| Field                  | Description                                                                     |
+| ---------------------- | ------------------------------------------------------------------------------- |
+| new_pool_fee_pct       | Fee percentage charged on new pool creation, in basis points (100 = 1%)         |
+| creation_fee           | Flat fee in `uzig` required to create a new pool (`10000000` = 10 ZIG)          |
+| beneficiary            | Address that receives protocol-level fees from pool creation                    |
+| minimal_liquidity_lock | Minimum LP token amount that must remain locked in a pool at all times          |
+| max_slippage           | Maximum allowed slippage per swap in basis points (100 = 1%)                    |
+
+## When to Use
+
+* Displaying pool creation costs to users before they create a pool
+* Verifying current slippage limits for swap transactions
+* Governance monitoring for DEX parameter changes
+---