@zuhaibnoor/zigchain-sdk 1.1.0 → 1.1.1

package/docs/ibc-transfer.md

@@ -1,204 +1,463 @@
 # IBC Transfer
 
-The **IBC Transfer module** allows ZigChain to **send and receive fungible tokens** across different blockchains using IBC.
-Think of it as a **secure token bridge system**.
+## What is IBC Transfer?
 
-It works using:
+The **IBC Transfer** enables ZigChain to send and receive fungible tokens across other IBC-enabled blockchains.
 
-* **Denoms** → representations of tokens on other chains (can be traced via `denom trace` or `denom hash`)
-* **Escrow accounts** → temporary holding accounts for tokens being transferred
-* **Parameters** → rules and settings of the IBC transfer module
+Instead of directly moving tokens between chains, IBC Transfer:
 
+* Locks tokens in escrow on the source chain
+* Mints voucher tokens on the destination chain
 ---
 
-# Setup
+# Important Terminology
+
+Before documenting functions, let’s define key terms.
+
+### Denom
+
+A token denomination.
+
+Examples:
+
+```
+uzig
+uusdc
+uatom
+```
+
+On IBC transfers, denoms can become:
+
+```
+ibc/<HASH>
+```
+
+### Denom Trace
+
+Describes the full path a token took across chains.
+
+Example:
+
+```
+transfer/channel-44/uusdc
+```
+
+It contains:
+
+* Port ID
+* Channel ID
+* Base denom
+
+### Denom Hash
+
+A SHA256 hash of the full denom trace string.
+
+Example:
+
+```
+SHA256("transfer/channel-44/uusdc")
+=
+5260516290F7883EC893AADA09A6B8CEC790F2EEF3196F440037908749785BE8
+```
+
+On-chain representation:
+
+```
+ibc/5260516290F7883EC893AADA09A6B8CEC790F2EEF3196F440037908749785BE8
+```
+
+### Escrow Account
+
+An **escrow account** is a special account controlled by the IBC Transfer module that temporarily holds tokens during a cross-chain transfer.
+
+When you send tokens to another chain, they are **locked in this escrow account** on the source chain. The tokens do not leave immediately — instead, they are safely held while the destination chain mints a corresponding voucher token.
+
+If the transfer succeeds, the escrowed tokens remain locked.
+If the transfer fails, the tokens are released back to the sender.
+
+This mechanism ensures:
+
+* No tokens are duplicated
+* Total supply remains correct
+* Cross-chain transfers are secure and verifiable
+
+--- 
+
+### Transfer Parameters
+
+Chain-level configuration controlling:
+
+* Whether sending is enabled
+* Whether receiving is enabled
+
+---
+
+# Functions Documentation
+
+## Setup
 
 ```ts
 import {
   ChainIbcTransferApi,
   getNetworkEndpoints,
-  Network,
+  Network
 } from '@zuhaibnoor/zigchain-sdk'
 
 const endpoints = getNetworkEndpoints(Network.Testnet)
 const ibcTransferApi = new ChainIbcTransferApi(endpoints)
+
+const hash = '5260516290F7883EC893AADA09A6B8CEC790F2EEF3196F440037908749785BE8'
+const portId = 'transfer'
+const channelId = 'channel-44'
+const denom = 'uusdc'
 ```
 
 ---
 
-## `fetchDenomByHash()`
+# 1️⃣ fetchDenomByHash
+
+## Method
 
 ```ts
-fetchDenomByHash(hash: string)
+async fetchDenomByHash(hash: string)
 ```
 
-### What it does
-
-Fetches the **denom trace info** from a **denom hash**.
-A **denom trace** shows the **origin chain, port, and channel** of a token.
-
----
-
-### CLI equivalent
+## CLI Equivalent
 
 ```bash
 zigchaind query ibc-transfer denom <hash>
 ```
 
-### Example
+## Description
+
+Fetches the **denom trace** associated with a given IBC denom hash.
+
+This allows you to:
+
+* Identify the original base token
+* See which port and channel it arrived through
+* Reverse lookup `ibc/<hash>` tokens
+
+## Parameters
+
+| Name | Type   | Description                |
+| ---- | ------ | -------------------------- |
+| hash | string | IBC denom hash (no `ibc/`) |
+
+## Usage Example
 
 ```ts
-const denomTrace = await ibcTransferApi.fetchDenomByHash(
-  '5260516290F7883EC893AADA09A6B8CEC790F2EEF3196F440037908749785BE8'
-)
-console.dir(denomTrace, { depth: null })
+const trace = await ibcTransferApi.fetchDenomByHash(hash)
+console.dir(trace, { depth: null })
 ```
 
 ---
 
-## `fetchDenomHash()`
-
-```ts
-fetchDenomHash(portId: string, channelId: string, denom: string)
+## Example Response
+
+```json
+{
+  "denom": {
+    "base": "uusdc",
+    "trace": [
+      {
+        "port_id": "transfer",
+        "channel_id": "channel-44"
+      }
+    ]
+  }
+}
 ```
 
-### What it does
+## Response Field Explanation
 
-Fetches the **denom hash** for a token given its **port, channel, and token name**.
-This hash uniquely identifies the token across chains.
+### `denom`
+
+Contains denom trace information.
+
+| Field | Description                |
+| ----- | -------------------------- |
+| base  | Original token denom       |
+| trace | Array of port/channel hops |
+
+Each trace entry includes:
+
+| Field      | Description            |
+| ---------- | ---------------------- |
+| port_id    | IBC port identifier    |
+| channel_id | IBC channel identifier |
+
+## When to Use
+
+* Resolving `ibc/<hash>` tokens
+* Building explorers
+* Wallet token metadata resolution
 
 ---
 
-### CLI equivalent
+# 2️⃣ fetchDenomHash
+
+## Method
+
+```ts
+async fetchDenomHash(
+  portId: string,
+  channelId: string,
+  denom: string
+)
+```
+
+## CLI Equivalent
 
 ```bash
 zigchaind query ibc-transfer denom-hash <port> <channel> <denom>
 ```
 
-### Example
+## Description
+
+Computes and returns the **IBC denom hash** from:
+
+* Port ID
+* Channel ID
+* Base denom
+
+This produces the deterministic hash used on-chain.
+
+## Parameters
+
+| Name      | Type   | Description                   |
+| --------- | ------ | ----------------------------- |
+| portId    | string | IBC port (usually `transfer`) |
+| channelId | string | IBC channel identifier        |
+| denom     | string | Base token denom              |
+
+## Usage Example
 
 ```ts
 const denomHash = await ibcTransferApi.fetchDenomHash(
-  'transfer',
-  'channel-0',
-  'uzig'
+  portId,
+  channelId,
+  denom
 )
+
 console.dir(denomHash, { depth: null })
 ```
 
----
-
-## `fetchDenoms()`
+## Example Response
 
-```ts
-fetchDenoms()
+```json
+{
+  "hash": "5260516290F7883EC893AADA09A6B8CEC790F2EEF3196F440037908749785BE8"
+}
 ```
 
-### What it does
+## Response Field Explanation
+
+| Field | Description                     |
+| ----- | ------------------------------- |
+| hash  | SHA256 hash of full denom trace |
 
-Returns **all denom traces** currently registered in the IBC transfer module.
-Useful to **list all IBC token representations** on the chain.
+## When to Use
+
+* Generating `ibc/<hash>` values
+* Wallet token display logic
+* SDK internal conversions
+* Verifying denom determinism
 
 ---
 
-### CLI equivalent
+# 3️⃣ fetchDenoms
+
+## Method
+
+```ts
+async fetchDenoms()
+```
+
+## CLI Equivalent
 
 ```bash
 zigchaind query ibc-transfer denoms
 ```
 
-### Example
+## Description
+
+Returns all registered IBC denom traces on ZigChain.
+
+Useful for discovering:
+
+* Imported tokens
+* Multi-hop tokens
+* All IBC assets on-chain
+
+## Parameters
+
+None.
+
+## Usage Example
 
 ```ts
-const allDenoms = await ibcTransferApi.fetchDenoms()
-console.dir(allDenoms, { depth: null })
+const denoms = await ibcTransferApi.fetchDenoms()
+console.dir(denoms, { depth: null })
+```
+
+## Example Response
+
+```json
+{
+  "denoms": [
+    {
+      "base": "uusdc",
+      "trace": [
+        {
+          "port_id": "transfer",
+          "channel_id": "channel-44"
+        }
+      ]
+    }
+  ],
+  "pagination": {
+    "next_key": null,
+    "total": "15"
+  }
+}
 ```
 
 ---
 
-## `fetchEscrowAddress()`
+## Response Field Explanation
 
-```ts
-fetchEscrowAddress(portId: string, channelId: string)
-```
+### `denoms`
+
+Array of denom traces.
+
+Each entry includes:
 
-### What it does
+| Field | Description         |
+| ----- | ------------------- |
+| base  | Original base denom |
+| trace | Path of IBC hops    |
 
-Returns the **escrow account address** for a given port and channel.
-Tokens being sent across IBC are **temporarily held** in this escrow account until they reach the other chain.
+## When to Use
+
+* Building token explorers
+* Indexing IBC assets
+* Chain analytics
+* Asset discovery tools
 
 ---
 
-### CLI equivalent
+# 4️⃣ fetchEscrowAddress
+
+## Method
+
+```ts
+async fetchEscrowAddress(
+  portId: string,
+  channelId: string
+)
+```
+
+## CLI Equivalent
 
 ```bash
 zigchaind query ibc-transfer escrow-address <port> <channel>
 ```
 
-### Example
+## Description
+
+Returns the escrow account address for a specific port and channel.
+
+Tokens sent through this channel are temporarily locked here before being transferred.
+
+## Parameters
+
+| Name      | Type   | Description            |
+| --------- | ------ | ---------------------- |
+| portId    | string | IBC port identifier    |
+| channelId | string | IBC channel identifier |
+
+## Usage Example
 
 ```ts
-const escrowAddr = await ibcTransferApi.fetchEscrowAddress(
-  'transfer',
-  'channel-0'
+const escrow = await ibcTransferApi.fetchEscrowAddress(
+  portId,
+  channelId
 )
-console.dir(escrowAddr, { depth: null })
-```
 
----
+console.dir(escrow, { depth: null })
+```
 
-## `fetchTransferParams()`
+## Example Response
 
-```ts
-fetchTransferParams()
+```json
+{
+  "escrow_address": "zig1hcea3h0ykw4jqyjhj3tnydsk22s06adh5y350m"
+}
 ```
 
-### What it does
+## Response Field Explanation
 
-Returns the **current parameters** of the IBC transfer module.
-This includes rules like **allowed tokens, transfer fees, and limits**.
+| Field          | Description                   |
+| -------------- | ----------------------------- |
+| escrow_address | Module escrow account address |
 
 ---
 
-### CLI equivalent
+# 5️⃣ fetchTransferParams
 
-```bash
-zigchaind query ibc-transfer params
+## Method
+
+```ts
+async fetchTransferParams()
 ```
 
-### Example
+## CLI Equivalent
 
-```ts
-const params = await ibcTransferApi.fetchTransferParams()
-console.dir(params, { depth: null })
+```bash
+zigchaind query ibc-transfer params
 ```
 
----
+## Description
 
-### How Escrow Works with Token Wrapping
+Fetches the chain-level configuration of the IBC Transfer module.
 
-1. **Original tokens exist on the source chain** (e.g., `uzig` on ZigChain).
+These parameters determine whether token transfers are allowed.
 
-2. **When you initiate an IBC transfer** to another chain:
+## Parameters
 
-   * The tokens are **not sent directly**.
-   * Instead, they are **locked in an escrow account** on the source chain.
-   * The escrow account acts like a **safe holding place** for those tokens.
+None.
 
-3. **Receipt / Wrapped Token:**
+## Usage Example
 
-   * The destination chain does **not get the original tokens**.
-   * Instead, it receives a **representation of those tokens** — often called a **voucher** or **wrapped token**.
-   * This wrapped token can be used on the destination chain as if it were the original token.
+```ts
+const params = await ibcTransferApi.fetchTransferParams()
+console.dir(params, { depth: null })
+```
 
-4. **Completion / Finalization:**
+## Example Response
 
-   * Once the destination chain confirms the receipt of the wrapped token, the escrow account on the source chain marks the tokens as **spent / transferred**.
-   * If the transfer fails or is canceled, the tokens remain in the escrow account and can be returned to the original owner.
+```json
+{
+  "params": {
+    "send_enabled": true,
+    "receive_enabled": true
+  }
+}
+```
 
----
+## Response Field Explanation
 
+### `params`
 
+| Field           | Description                                 |
+| --------------- | ------------------------------------------- |
+| send_enabled    | Whether outgoing IBC transfers are allowed  |
+| receive_enabled | Whether incoming IBC transfers are accepted |
 
+## When to Use
 
+* Checking if transfers are paused
+* Governance audits
+---