@zuhaibnoor/zigchain-sdk 1.1.0 → 1.1.1

package/docs/ibc/ibcChannel.md

@@ -1,490 +1,977 @@
-# IBC Module
+# IBC Channel Module
 
-The **IBC (Inter-Blockchain Communication)** module allows ZigChain to communicate with other blockchains.
+## What is IBC?
 
-Think of IBC like a **secure bridge system** between blockchains.
+**IBC (Inter-Blockchain Communication)** is a protocol that allows independent blockchains to securely exchange messages and tokens. ZigChain uses IBC to connect with other Cosmos ecosystem chains.
 
-It works using:
+The IBC stack has four layers that build on each other:
 
-* **Clients** → light verifiers that track another chain
-* **Connections** → links between two chains
-* **Channels** → communication lanes built on top of connections
-* **Packets** → messages or token transfers sent through channels
+```
+Packets   →  the messages/tokens being transferred
+Channels  →  the lanes packets travel through
+Connections →  the secured links between two chains
+Clients   →  light clients that verify the other chain's state
+```
+---
 
-# Setup
+## Important Terminology
 
-```ts
-import {
-  ChainIbcChannelApi,
-  getNetworkEndpoints,
-  Network,
-} from '@zuhaibnoor/zigchain-sdk'
+### Channel
 
-const endpoints = getNetworkEndpoints(Network.Testnet)
-const ibcApi = new ChainIbcApi(endpoints)
+A **channel** is a communication lane between a specific port on ZigChain and a specific port on a counterparty chain. All IBC token transfers go through channels. Each channel is built on top of a connection.
+
+```
+channel-0  (ZigChain)  ↔  channel-612  (counterparty)
 ```
 
 ---
-## `fetchChannels()`
 
-### What it does
+### Port
 
-Returns **all IBC channels** that exist on ZigChain.
+A **port** is an application-level identifier that specifies which module on a chain handles the packets. The standard token transfer port is `transfer`. NFT transfers use `wasm.<contract-address>` ports.
 
-### What is a Channel?
-
-A **channel** is like a communication lane between two blockchains.
+```
+port_id = 'transfer'
+```
 
-If:
+---
 
-* Connection = physical cable
-* Channel = lane inside that cable
-* Packet = message sent through the lane
+### Channel State
 
-Then this function shows you all those lanes.
+| State        | Meaning                                                    |
+| ------------ | ---------------------------------------------------------- |
+| `STATE_OPEN` | Channel is active and can send/receive packets             |
+| `STATE_INIT` | Channel is being opened — handshake in progress            |
+| `STATE_TRYOPEN` | Counterparty acknowledged the open, waiting for confirmation |
+| `STATE_CLOSED` | Channel has been closed — no longer usable               |
 
 ---
 
-### CLI equivalent
+### Channel Ordering
 
-```bash
-zigchaind query ibc channel channels
-```
+| Ordering           | Meaning                                                         |
+| ------------------ | --------------------------------------------------------------- |
+| `ORDER_UNORDERED`  | Packets can be received in any order — used for token transfers |
+| `ORDER_ORDERED`    | Packets must be received in sequence — used for ordered apps    |
 
-### Example
+All ZigChain IBC channels use `ORDER_UNORDERED`.
 
-```ts
-const channels = await ibcApi.fetchChannels()
-console.dir(channels, { depth: null })
-```
+---
+
+### Connection Hops
 
-You’ll see:
+The list of connections a channel traverses. For a direct channel this is always one connection. Multi-hop channels (not yet standard) would have multiple hops.
 
-* channel IDs
-* port IDs
-* connection ID
-* whether the channel is OPEN or CLOSED
+```
+connection_hops = ['connection-0']
+```
 
 ---
 
-## `fetchChannelClientState()`
+### Packet Sequence Number
 
-```ts
-fetchChannelClientState(portId: string, channelId: string)
+Every packet sent through a channel gets an incrementing integer sequence number. This prevents duplicates, ensures ordering where required, and allows tracking of specific packets.
+
+```
+sequence = 70
 ```
 
-### What it does
+---
+
+### Packet Commitment
 
-Returns the **client state** associated with a channel.
+A **cryptographic hash** stored on the sending chain when a packet is created. It proves the packet exists and was committed to chain state. Used by the receiving chain to verify the packet is legitimate.
 
 ---
 
-### What is a Client?
+### Packet Acknowledgement
 
-In IBC, a **client** is a small verifier inside ZigChain that:
+A **confirmation** sent back from the receiving chain after processing a packet. It proves the packet was received and whether it succeeded or failed.
 
-* Tracks another blockchain
-* Confirms that the other chain is valid
+---
 
-It is NOT a user.
-It is NOT a wallet.
+### Packet Receipt
 
-It is a **light client**.
+A record stored on the receiving chain after a packet is processed. Proves the packet was received — used to prevent replay attacks.
 
 ---
 
-### What is State?
+### Proof Height
 
-"State" simply means the **current stored information** about something.
+The block height at which the returned proof or data was generated.
 
-So:
+```json
+{ "revision_number": "2", "revision_height": "4647092" }
+```
 
-**Client State = the current verification information about the other chain.**
+`revision_number` is the chain's revision (incremented on resets). `revision_height` is the block number.
 
-It contains:
+---
 
-* chain ID
-* latest height
-* trust level
-* proof parameters
+## Setup
 
----
+```ts
+import {
+  ChainIbcChannelApi,
+  getNetworkEndpoints,
+  Network,
+} from '@zuhaibnoor/zigchain-sdk'
 
-### CLI equivalent
+const endpoints = getNetworkEndpoints(Network.Testnet)
+const ibcChannelApi = new ChainIbcChannelApi(endpoints)
 
-```bash
-zigchaind query ibc channel client-state <port-id> <channel-id>
+const portId = 'transfer'
+const channelId = 'channel-0'
 ```
 
-### Example
+---
+
+# 1️⃣ fetchChannels
+
+## Method
 
 ```ts
-const clientState = await ibcApi.fetchChannelClientState(
-  'transfer',
-  'channel-0'
-)
+async fetchChannels()
+```
 
-console.dir(clientState, { depth: null })
+## CLI Equivalent
+
+```bash
+zigchaind query ibc channel channels
 ```
+## Description
 
----
+Fetches **all IBC channels** registered on ZigChain across all ports and connections.
 
-## `fetchChannelsByConnection()`
+## Parameters
+
+None.
+
+## Usage Example
 
 ```ts
-fetchChannelsByConnection(connectionId: string)
+const channels = await ibcChannelApi.fetchChannels()
+console.dir(channels, { depth: null })
 ```
 
-### What it does
+## Example Response
+
+```json
+{
+  "channels": [
+    {
+      "state": "STATE_OPEN",
+      "ordering": "ORDER_UNORDERED",
+      "counterparty": {
+        "port_id": "transfer",
+        "channel_id": "channel-612"
+      },
+      "connection_hops": ["connection-0"],
+      "version": "ics20-1",
+      "port_id": "transfer",
+      "channel_id": "channel-0"
+    },
+    {
+      "state": "STATE_OPEN",
+      "ordering": "ORDER_UNORDERED",
+      "counterparty": {
+        "port_id": "wasm.inj1wvtzf6s4rdpttgvpvgwwfpepv8uw0gxvs5qwxp",
+        "channel_id": "channel-77060"
+      },
+      "connection_hops": ["connection-39"],
+      "version": "ics721-1",
+      "port_id": "wasm.zig12gmfscd27ercy99t9tlmntljnr87muhtpykygpjssf5m63xrma3qymqjp2",
+      "channel_id": "channel-25"
+    }
+  ],
+  "pagination": { "next_key": null, "total": "48" },
+  "height": { "revision_number": "2", "revision_height": "4647091" }
+}
+```
 
-Returns all channels built on a specific connection.
+## Response Field Explanation
 
----
+### `channels[]`
+
+| Field            | Description                                                          |
+| ---------------- | -------------------------------------------------------------------- |
+| state            | Current channel state (`STATE_OPEN`, `STATE_INIT`, etc.)            |
+| ordering         | Packet ordering mode (`ORDER_UNORDERED` for all ZigChain channels)  |
+| counterparty.port_id   | Port on the remote chain this channel connects to              |
+| counterparty.channel_id | Channel ID on the remote chain                                |
+| connection_hops  | Connection(s) this channel is built on                               |
+| version          | IBC application protocol (`ics20-1` for tokens, `ics721-1` for NFTs)|
+| port_id          | Port on ZigChain this channel is bound to                            |
+| channel_id       | ZigChain's channel identifier                                        |
+
+### `height`
 
-### What is a Connection?
+The block height at which this data was read.
 
-A **connection** is a secure link between two chains.
+### Channel Types on ZigChain Testnet
 
-You can think of it like:
+| Version    | Port Type        | Use Case             | Example                |
+| ---------- | ---------------- | -------------------- | ---------------------- |
+| `ics20-1`  | `transfer`       | Fungible token IBC   | `channel-0` to Axelar  |
+| `ics721-1` | `wasm.<address>` | NFT IBC transfers    | `channel-25` to Injective |
 
-* Client = verifier
-* Connection = secured bridge
-* Channel = lane on the bridge
+## When to Use
 
-A single connection can have multiple channels.
+* Building IBC channel explorers or dashboards
+* Discovering which chains ZigChain is connected to
+* Finding the correct channel ID before initiating an IBC transfer
+* Monitoring for new channel openings or closures
 
 ---
 
-### CLI equivalent
+# 2️⃣ fetchChannelClientState
+
+## Method
+
+```ts
+async fetchChannelClientState(portId: string, channelId: string)
+```
+
+## CLI Equivalent
 
 ```bash
-zigchaind query ibc channel connections <connection-id>
+zigchaind query ibc channel client-state <port-id> <channel-id>
 ```
 
-### Example
+## Description
+
+Fetches the **IBC light client state** associated with a specific channel.
+
+The light client is ZigChain's internal verifier for the counterparty chain. Its state includes the counterparty chain's ID, the latest tracked height, trust parameters, and proof specifications. This tells you what chain is on the other end of the channel and how ZigChain is currently tracking it.
+
+## Parameters
+
+| Name      | Type   | Description                                           |
+| --------- | ------ | ----------------------------------------------------- |
+| portId    | string | Port the channel is bound to (e.g. `'transfer'`)      |
+| channelId | string | Channel identifier (e.g. `'channel-0'`)               |
+
+## Usage Example
 
 ```ts
-const channels = await ibcApi.fetchChannelsByConnection(
-  'connection-0'
-)
+const clientState = await ibcChannelApi.fetchChannelClientState('transfer', 'channel-0')
+console.dir(clientState, { depth: null })
+```
 
-console.dir(channels, { depth: null })
+## Example Response
+
+```json
+{
+  "identified_client_state": {
+    "client_id": "07-tendermint-0",
+    "client_state": {
+      "@type": "/ibc.lightclients.tendermint.v1.ClientState",
+      "chain_id": "axelar-testnet-lisbon-3",
+      "trust_level": { "numerator": "2", "denominator": "3" },
+      "trusting_period": "403200s",
+      "unbonding_period": "604800s",
+      "max_clock_drift": "40s",
+      "frozen_height": { "revision_number": "0", "revision_height": "0" },
+      "latest_height": { "revision_number": "3", "revision_height": "26422416" }
+    }
+  },
+  "proof": null,
+  "proof_height": { "revision_number": "2", "revision_height": "4647092" }
+}
 ```
 
+## Response Field Explanation
+
+### `identified_client_state`
+
+| Field            | Description                                                        |
+| ---------------- | ------------------------------------------------------------------ |
+| client_id        | IBC light client ID tracking this counterparty (`07-tendermint-0`) |
+| client_state.@type | Client implementation type — Tendermint for Cosmos chains        |
+| client_state.chain_id | The counterparty chain's chain ID                            |
+| trust_level      | Fraction of validators needed to trust an update (2/3 = standard) |
+| trusting_period  | How long a header can be trusted without an update (in seconds)    |
+| unbonding_period | Counterparty chain's unbonding period                              |
+| max_clock_drift  | Maximum allowed time difference between chains                     |
+| frozen_height    | If non-zero, the client is frozen due to misbehaviour              |
+| latest_height    | Most recent counterparty block this client has verified            |
+
+> `channel-0` connects ZigChain to `axelar-testnet-lisbon-3` via client `07-tendermint-0`. The counterparty is at block height `26,422,416`.
+
+> A `frozen_height` of `0` means the client is healthy and not frozen.
+
+## When to Use
+
+* Identifying which chain is on the other end of a channel
+* Verifying the light client is not frozen before attempting a transfer
+* Debugging IBC transfer failures caused by expired or outdated clients
+* Chain connectivity dashboards showing counterparty chain details
+
 ---
 
-## `fetchChannelEnd()`
+# 3️⃣ fetchChannelsByConnection
+
+## Method
 
 ```ts
-fetchChannelEnd(portId: string, channelId: string)
+async fetchChannelsByConnection(connectionId: string)
 ```
 
-### What it does
+## CLI Equivalent
 
-Returns full details of a specific channel.
+```bash
+zigchaind query ibc channel connections <connection-id>
+```
 
----
+## Description
 
-### Why is it called "Channel End"?
+Fetches **all channels built on a specific connection**.
 
-Because a channel exists on **both chains**.
+A single IBC connection can host multiple channels for different applications. This lets you see all the communication lanes running over a particular secured link between two chains.
 
-Each chain stores its own "end" of the channel.
+## Parameters
 
-So:
+| Name         | Type   | Description                               |
+| ------------ | ------ | ----------------------------------------- |
+| connectionId | string | Connection identifier (e.g. `'connection-0'`) |
 
-* ZigChain has one end
-* The other chain has another end
+## Usage Example
 
-This function shows ZigChain’s side.
+```ts
+const byConnection = await ibcChannelApi.fetchChannelsByConnection('connection-0')
+console.dir(byConnection, { depth: null })
+```
 
----
+## Example Response
+
+```json
+{
+  "channels": [
+    {
+      "state": "STATE_OPEN",
+      "ordering": "ORDER_UNORDERED",
+      "counterparty": { "port_id": "transfer", "channel_id": "channel-612" },
+      "connection_hops": ["connection-0"],
+      "version": "ics20-1",
+      "port_id": "transfer",
+      "channel_id": "channel-0"
+    },
+    {
+      "state": "STATE_OPEN",
+      "ordering": "ORDER_UNORDERED",
+      "counterparty": { "port_id": "transfer", "channel_id": "channel-614" },
+      "connection_hops": ["connection-0"],
+      "version": "ics20-1",
+      "port_id": "transfer",
+      "channel_id": "channel-1"
+    }
+  ],
+  "pagination": { "next_key": null, "total": "2" },
+  "height": { "revision_number": "2", "revision_height": "4647092" }
+}
+```
 
-### CLI equivalent
+## Response Field Explanation
 
-```bash
-zigchaind query ibc channel end <port-id> <channel-id>
-```
+Same channel object structure as `fetchChannels`. See that section for full field descriptions.
 
 ---
 
-##  `fetchNextSequenceReceive()`
+# 4️⃣ fetchChannelEnd
+
+## Method
 
 ```ts
-fetchNextSequenceReceive(portId: string, channelId: string)
+async fetchChannelEnd(portId: string, channelId: string)
+```
+
+## CLI Equivalent
+
+```bash
+zigchaind query ibc channel end <port-id> <channel-id>
 ```
 
-### What it does
+## Description
 
-Returns the **next packet number ZigChain expects to receive**.
+Fetches the **channel end** — ZigChain's stored state for a specific channel.
 
----
+A channel exists on both chains simultaneously; each chain stores its own "end." This function returns ZigChain's end, which includes the channel's state, ordering, counterparty identifiers, connection, and version. It is the single-channel equivalent of an entry in `fetchChannels`.
 
-### What is a Sequence?
+## Parameters
 
-Every packet sent through a channel gets a number:
+| Name      | Type   | Description                                      |
+| --------- | ------ | ------------------------------------------------ |
+| portId    | string | Port the channel is bound to (e.g. `'transfer'`) |
+| channelId | string | Channel identifier (e.g. `'channel-0'`)          |
 
-1
-2
-3
-4
+## Usage Example
 
-This number is called a **sequence number**.
+```ts
+const channelEnd = await ibcChannelApi.fetchChannelEnd('transfer', 'channel-0')
+console.dir(channelEnd, { depth: null })
+```
 
-It ensures:
+## Example Response
+
+```json
+{
+  "channel": {
+    "state": "STATE_OPEN",
+    "ordering": "ORDER_UNORDERED",
+    "counterparty": { "port_id": "transfer", "channel_id": "channel-612" },
+    "connection_hops": ["connection-0"],
+    "version": "ics20-1"
+  },
+  "proof": null,
+  "proof_height": { "revision_number": "2", "revision_height": "4647092" }
+}
+```
 
-* No duplicates
-* No skipped packets
-* Proper ordering
+## Response Field Explanation
 
----
+### `channel`
 
-### So what is "Next Sequence Receive"?
+| Field           | Description                                             |
+| --------------- | ------------------------------------------------------- |
+| state           | Current channel state                                   |
+| ordering        | Packet ordering mode                                    |
+| counterparty    | Port and channel ID on the remote chain                 |
+| connection_hops | Connection(s) this channel uses                         |
+| version         | IBC application protocol version                        |
 
-It means:
+### `fetchChannels` vs `fetchChannelEnd`
 
-> “What is the next packet number I am waiting to receive?”
+| Feature               | fetchChannels           | fetchChannelEnd              |
+| --------------------- | ----------------------- | ---------------------------- |
+| Scope                 | All channels            | Single channel               |
+| Includes channel ID   | ✅ Yes                  | ❌ No (you provide it)       |
+| Includes proof_height | ❌ No                   | ✅ Yes                       |
+| Use case              | Full channel discovery  | Single channel verification  |
 
-If it returns `15`,
-that means ZigChain has already received up to 14.
+## When to Use
+
+* Verifying a specific channel is open before initiating a transfer
+* Checking counterparty channel and port for a known channel
 
 ---
 
-### CLI equivalent
+# 5️⃣ fetchNextSequenceReceive
+
+## Method
+
+```ts
+async fetchNextSequenceReceive(portId: string, channelId: string)
+```
+
+## CLI Equivalent
 
 ```bash
 zigchaind query ibc channel next-sequence-receive <port-id> <channel-id>
 ```
 
----
+## Description
 
-##  `fetchNextSequenceSend()`
+Fetches the **next packet sequence number ZigChain expects to receive** on a channel.
+
+If this returns `15`, ZigChain has already processed packets 1–14 and is waiting for packet 15. A value of `0` on ZigChain testnet's `channel-0` reflects that this channel is primarily used for outbound transfers.
+
+## Parameters
+
+| Name      | Type   | Description                                      |
+| --------- | ------ | ------------------------------------------------ |
+| portId    | string | Port the channel is bound to (e.g. `'transfer'`) |
+| channelId | string | Channel identifier (e.g. `'channel-0'`)          |
+
+## Usage Example
 
 ```ts
-fetchNextSequenceSend(portId: string, channelId: string)
+const nextRecv = await ibcChannelApi.fetchNextSequenceReceive('transfer', 'channel-0')
+console.dir(nextRecv, { depth: null })
 ```
 
-### What it does
+## Example Response
 
-Returns the next packet number that will be used when sending a packet.
+```json
+{
+  "next_sequence_receive": "0",
+  "proof": null,
+  "proof_height": { "revision_number": "2", "revision_height": "4647093" }
+}
+```
 
----
+## Response Field Explanation
 
-### What does this mean?
+| Field                 | Description                                                            |
+| --------------------- | ---------------------------------------------------------------------- |
+| next_sequence_receive | The next packet sequence this chain expects to receive on this channel |
+| proof                 | Merkle proof (null for simple queries)                                 |
+| proof_height          | Block height at which this data was read                               |
 
-If it returns `20`,
-then the next packet you send will be sequence number 20.
+## When to Use
 
-This helps track outgoing transfers.
+* Monitoring incoming packet delivery progress
+* Detecting stuck inbound packets
+* Verifying a channel is actively receiving packets
 
 ---
 
-### CLI equivalent
+# 6️⃣ fetchNextSequenceSend
+
+## Method
+
+```ts
+async fetchNextSequenceSend(portId: string, channelId: string)
+```
+
+## CLI Equivalent
 
 ```bash
 zigchaind query ibc channel next-sequence-send <port-id> <channel-id>
 ```
 
----
+## Description
+
+Fetches the **next packet sequence number that will be assigned** when a new packet is sent on this channel.
+
+If this returns `74`, then 73 packets have already been sent and the next outbound transfer on this channel will be sequence `74`.
+
+## Parameters
 
-## `fetchPacketAcknowledgement()`
+| Name      | Type   | Description                                      |
+| --------- | ------ | ------------------------------------------------ |
+| portId    | string | Port the channel is bound to (e.g. `'transfer'`) |
+| channelId | string | Channel identifier (e.g. `'channel-0'`)          |
+
+## Usage Example
 
 ```ts
-fetchPacketAcknowledgement(
-  portId: string,
-  channelId: string,
-  sequence: number | string
-)
+const nextSend = await ibcChannelApi.fetchNextSequenceSend('transfer', 'channel-0')
+console.dir(nextSend, { depth: null })
 ```
 
-### What it does
+## Example Response
+
+```json
+{
+  "next_sequence_send": "74",
+  "proof": null,
+  "proof_height": { "revision_number": "2", "revision_height": "4647093" }
+}
+```
+
+## Response Field Explanation
+
+| Field             | Description                                                       |
+| ----------------- | ----------------------------------------------------------------- |
+| next_sequence_send | The sequence number the next outbound packet will be assigned    |
+| proof             | Merkle proof (null for simple queries)                            |
+| proof_height      | Block height at which this data was read                          |
+
+## When to Use
 
-Returns the acknowledgement for a specific packet.
+* Tracking total outbound transfer volume on a channel
+* Predicting the sequence number of the next transfer
+* Auditing outbound packet counts
 
 ---
 
-### What is an Acknowledgement?
+# 7️⃣ fetchPacketAcknowledgement
 
-When a packet is sent to another chain:
+## Method
 
-1. It gets processed there.
-2. The other chain sends back a confirmation.
-3. That confirmation is called an **acknowledgement**.
+```ts
+async fetchPacketAcknowledgement(portId: string, channelId: string, sequence: number | string)
+```
 
-Think of it like:
+## CLI Equivalent
 
-* You send a parcel 📦
-* Receiver signs and confirms delivery
-* That confirmation = acknowledgement
+```bash
+zigchaind query ibc channel packet-ack <port-id> <channel-id> <sequence>
+```
 
----
+## Description
+
+Fetches the **acknowledgement stored for a specific packet**.
 
-### Why is this important?
+When a packet is processed on the counterparty chain, it sends back an acknowledgement that ZigChain stores. This acknowledgement proves the packet was received and contains information about whether processing succeeded or failed.
 
-It proves:
+## Parameters
 
-* The packet was received
-* The packet was processed successfully (or failed)
+| Name      | Type              | Description                                      |
+| --------- | ----------------- | ------------------------------------------------ |
+| portId    | string            | Port the channel is bound to                     |
+| channelId | string            | Channel identifier                               |
+| sequence  | number \| string  | Packet sequence number to query                  |
 
+## Usage Example
+
+```ts
+const ack = await ibcChannelApi.fetchPacketAcknowledgement('transfer', 'channel-0', 70)
+console.dir(ack, { depth: null })
+```
+
+## Example Response
+
+```json
+{
+  "acknowledgement": "CPdVftUYJv4Y2EUSvyTsdQAe268hI6R333KgqfNkCnw=",
+  "proof": null,
+  "proof_height": { "revision_number": "2", "revision_height": "4647093" }
+}
+```
+
+## Response Field Explanation
+
+| Field           | Description                                                              |
+| --------------- | ------------------------------------------------------------------------ |
+| acknowledgement | Base64-encoded acknowledgement data returned by the counterparty chain   |
+| proof           | Merkle proof (null for simple queries)                                   |
+| proof_height    | Block height at which this data was read                                 |
+
+## When to Use
+
+* Verifying a specific packet was acknowledged by the counterparty
+* Checking whether a transfer succeeded or failed on the remote chain
+* Building packet status trackers for IBC explorers
 ---
 
-### CLI equivalent
+# 8️⃣ fetchPacketCommitment
+
+## Method
+
+```ts
+async fetchPacketCommitment(portId: string, channelId: string, sequence: number | string)
+```
+
+## CLI Equivalent
 
 ```bash
-zigchaind query ibc channel packet-ack <port-id> <channel-id> <sequence>
+zigchaind query ibc channel packet-commitment <port-id> <channel-id> <sequence>
 ```
 
+## Description
+
+Fetches the **packet commitment** stored for a specific outbound packet.
+
+When ZigChain sends a packet, it stores a cryptographic hash (commitment) of that packet. This commitment remains on-chain until the packet is acknowledged by the counterparty. If a commitment exists, it means the packet was sent but the acknowledgement has not yet been received back.
+
 ---
 
-## `fetchPacketCommitment()`
+## Parameters
+
+| Name      | Type              | Description                                  |
+| --------- | ----------------- | -------------------------------------------- |
+| portId    | string            | Port the channel is bound to                 |
+| channelId | string            | Channel identifier                           |
+| sequence  | number \| string  | Packet sequence number to query              |
+
+## Usage Example
 
 ```ts
-async fetchPacketCommitment(
-  portId: string,
-  channelId: string,
-  sequence: number | string
-)
+const commitment = await ibcChannelApi.fetchPacketCommitment('transfer', 'channel-0', 55)
+console.dir(commitment, { depth: null })
 ```
 
-### Description
+## Example Response
 
-Queries the **packet commitment** for a specific packet sequence.
+```json
+{
+  "commitment": "TGCM/XS6O6oh0TgzrQfICRxgJ0Fxb2AerhtOtSfaG3U=",
+  "proof": null,
+  "proof_height": { "revision_number": "2", "revision_height": "4647094" }
+}
+```
+
+## Response Field Explanation
 
-A **packet commitment** is a cryptographic record stored on the sending chain when a packet is sent.
-It proves that the packet was created and committed to state.
+| Field        | Description                                                              |
+| ------------ | ------------------------------------------------------------------------ |
+| commitment   | Base64-encoded hash of the packet data — proves the packet was committed |
+| proof        | Merkle proof (null for simple queries)                                   |
+| proof_height | Block height at which this data was read                                 |
 
-This function answers:
+## When to Use
 
-> “Was packet `<sequence>` committed on this channel?”
+* Checking if a specific packet is still awaiting acknowledgement
+* Debugging in-flight or stuck transfers
 
 ---
 
-### Parameters
+# 9️⃣ fetchPacketCommitments
 
-* **portId** – The application port (e.g., `"transfer"`).
-* **channelId** – The IBC channel identifier (e.g., `"channel-0"`).
-* **sequence** – The packet sequence number.
+## Method
 
----
+```ts
+async fetchPacketCommitments(portId: string, channelId: string)
+```
 
-## `fetchPacketCommitments()`
+## CLI Equivalent
+
+```bash
+zigchaind query ibc channel packet-commitments <port-id> <channel-id>
+```
+
+## Description
+
+Fetches **all outstanding packet commitments** on a channel — every packet that has been sent but not yet acknowledged.
+
+## Parameters
+
+| Name      | Type   | Description                                      |
+| --------- | ------ | ------------------------------------------------ |
+| portId    | string | Port the channel is bound to (e.g. `'transfer'`) |
+| channelId | string | Channel identifier (e.g. `'channel-0'`)          |
+
+## Usage Example
 
 ```ts
-async fetchPacketCommitments(
-  portId: string,
-  channelId: string
-)
+const commitments = await ibcChannelApi.fetchPacketCommitments('transfer', 'channel-0')
+console.dir(commitments, { depth: null })
 ```
 
-### Description
+## Example Response
+
+```json
+{
+  "commitments": [
+    {
+      "port_id": "transfer",
+      "channel_id": "channel-0",
+      "sequence": "53",
+      "data": "o6Kf3yL0iV5BVzwm0O/j8sOHy+bvO0foTqBgBZx0Bt4="
+    },
+    {
+      "port_id": "transfer",
+      "channel_id": "channel-0",
+      "sequence": "54",
+      "data": "Hn9W269hLobcNGLWmTMDXI8ITsXlEUubBdR3pjYOyTI="
+    },
+    {
+      "port_id": "transfer",
+      "channel_id": "channel-0",
+      "sequence": "55",
+      "data": "TGCM/XS6O6oh0TgzrQfICRxgJ0Fxb2AerhtOtSfaG3U="
+    }
+  ],
+  "pagination": { "next_key": null, "total": "3" },
+  "height": { "revision_number": "2", "revision_height": "4647094" }
+}
+```
 
-Queries **all packet commitments** for a given channel and port.
+## Response Field Explanation
 
-This returns all packets that:
+### `commitments[]`
 
-* Were sent from this chain
-* Still have commitments stored
+| Field      | Description                                                     |
+| ---------- | --------------------------------------------------------------- |
+| port_id    | Port this commitment belongs to                                 |
+| channel_id | Channel this commitment belongs to                              |
+| sequence   | Packet sequence number                                          |
+| data       | Base64-encoded commitment hash of the packet                    |
 
-It is useful to see all outstanding or tracked packets on a channel.
+### `fetchPacketCommitment` vs `fetchPacketCommitments`
+
+| Feature             | fetchPacketCommitment     | fetchPacketCommitments          |
+| ------------------- | ------------------------- | ------------------------------- |
+| Scope               | Single sequence           | All outstanding commitments     |
+| Use case            | Check one specific packet | Overview of all in-flight packets |
 
 ---
 
-### Parameters
+# 🔟 fetchPacketReceipt
+
+## Method
 
-* **portId** – The application port.
-* **channelId** – The IBC channel identifier.
+```ts
+async fetchPacketReceipt(portId: string, channelId: string, sequence: number | string)
+```
+
+## CLI Equivalent
+
+```bash
+zigchaind query ibc channel packet-receipt <port-id> <channel-id> <sequence>
+```
+
+## Description
+
+Checks whether a **specific inbound packet has been received** by ZigChain.
+
+A packet receipt is stored on the receiving chain after the packet is processed. This is the definitive proof that ZigChain received and executed a specific packet from the counterparty. Returns `received: true` if the packet was processed, `false` if not.
+
+## Parameters
+
+| Name      | Type              | Description                                  |
+| --------- | ----------------- | -------------------------------------------- |
+| portId    | string            | Port the channel is bound to                 |
+| channelId | string            | Channel identifier                           |
+| sequence  | number \| string  | Packet sequence number to check              |
 
 ---
 
-## `fetchPacketReceipt()`
+## Usage Example
 
 ```ts
-async fetchPacketReceipt(
-  portId: string,
-  channelId: string,
-  sequence: number | string
-)
+const receipt = await ibcChannelApi.fetchPacketReceipt('transfer', 'channel-0', 70)
+console.dir(receipt, { depth: null })
 ```
 
-### Description
+## Example Response
 
-Queries the **packet receipt** for a specific packet.
+```json
+{
+  "received": true,
+  "proof": null,
+  "proof_height": { "revision_number": "2", "revision_height": "4647094" }
+}
+```
 
-A **packet receipt** is stored on the receiving chain after a packet is successfully processed.
-It confirms that the packet was received.
+## Response Field Explanation
 
-This function answers:
+| Field        | Description                                                        |
+| ------------ | ------------------------------------------------------------------ |
+| received     | `true` if ZigChain has received and processed this packet          |
+| proof        | Merkle proof (null for simple queries)                             |
+| proof_height | Block height at which this data was read                           |
 
-> “Has packet `<sequence>` been received on this chain?”
+## When to Use
 
+* Verifying an inbound packet was successfully received
+* Confirming an incoming IBC transfer reached ZigChain
 ---
 
-### Parameters
+# 1️⃣1️⃣ fetchUnreceivedAcks
 
-* **portId** – The application port.
-* **channelId** – The IBC channel identifier.
-* **sequence** – The packet sequence number.
+## Method
 
----
+```ts
+async fetchUnreceivedAcks(portId: string, channelId: string, sequences: (number | string)[])
+```
 
-## `fetchUnreceivedAcks()`
+## CLI Equivalent
+
+```bash
+zigchaind query ibc channel unreceived-acks <port-id> <channel-id> <sequences>
+```
+
+## Description
+
+Given a list of packet sequences, returns which ones have **acknowledgements that ZigChain has not yet received back**.
+
+This identifies packets that were sent from ZigChain, processed on the counterparty, but whose acknowledgements haven't been relayed back to ZigChain yet. These are packets with commitments still stored on ZigChain waiting to be cleared.
+
+## Parameters
+
+| Name      | Type                    | Description                                              |
+| --------- | ----------------------- | -------------------------------------------------------- |
+| portId    | string                  | Port the channel is bound to                             |
+| channelId | string                  | Channel identifier                                       |
+| sequences | (number \| string)[]    | List of sequence numbers to check for missing acks       |
+
+## Usage Example
 
 ```ts
-async fetchUnreceivedAcks(
-  portId: string,
-  channelId: string,
-  sequences: (number | string)[]
+const unreceivedAcks = await ibcChannelApi.fetchUnreceivedAcks(
+  'transfer',
+  'channel-0',
+  [53, 54, 71]
 )
+console.dir(unreceivedAcks, { depth: null })
 ```
 
-### Description
+## Example Response
 
-Checks which packet acknowledgements have **not yet been received**.
+```json
+{
+  "sequences": ["53", "54"],
+  "height": { "revision_number": "2", "revision_height": "4647095" }
+}
+```
+
+## Response Field Explanation
 
-An **acknowledgement (ack)** is a confirmation sent back to the original chain after a packet is processed on the counterparty chain.
+| Field     | Description                                                                        |
+| --------- | ---------------------------------------------------------------------------------- |
+| sequences | The subset of queried sequences whose acknowledgements have not yet been received  |
+| height    | Block height at which this data was read                                           |
 
-This function answers:
+## When to Use
 
-> “Out of these sequences, which acknowledgements are still missing?”
+* Checking which packets need ack relaying
+* Identifying the workload for an IBC relayer
+* Monitoring channel health and ack latency
+* Alerting when acks are pending for too long
 
 ---
 
-### Parameters
+# 1️⃣2️⃣ fetchUnreceivedPackets
 
-* **portId** – The application port.
-* **channelId** – The IBC channel identifier.
-* **sequences** – List of packet sequence numbers to check.
+## Method
 
----
+```ts
+async fetchUnreceivedPackets(portId: string, channelId: string, sequences: (number | string)[])
+```
+
+## CLI Equivalent
+
+```bash
+zigchaind query ibc channel unreceived-packets <port-id> <channel-id> <sequences>
+```
+
+## Description
+
+Given a list of packet sequences, returns which ones have been **committed on the counterparty but not yet received by ZigChain**.
+
+This is the inbound counterpart to `fetchUnreceivedAcks` — it identifies packets sent to ZigChain that haven't arrived yet. An empty result means all queried packets have already been received.
+
+
+## Parameters
 
-## `fetchUnreceivedPackets()`
+| Name      | Type                    | Description                                               |
+| --------- | ----------------------- | --------------------------------------------------------- |
+| portId    | string                  | Port the channel is bound to                              |
+| channelId | string                  | Channel identifier                                        |
+| sequences | (number \| string)[]    | List of sequence numbers to check for missing receipts    |
+
+## Usage Example
 
 ```ts
-async fetchUnreceivedPackets(
-  portId: string,
-  channelId: string,
-  sequences: (number | string)[]
+const unreceivedPackets = await ibcChannelApi.fetchUnreceivedPackets(
+  'transfer',
+  'channel-0',
+  [53, 54, 71]
 )
+console.dir(unreceivedPackets, { depth: null })
 ```
 
-### Description
+## Example Response
 
-Checks which packets have been committed but **not yet received** on the counterparty chain.
+```json
+{
+  "sequences": [],
+  "height": { "revision_number": "2", "revision_height": "4647095" }
+}
+```
 
-This helps detect pending or stuck packets.
+## Response Field Explanation
 
-This function answers:
+| Field     | Description                                                                      |
+| --------- | -------------------------------------------------------------------------------- |
+| sequences | The subset of queried sequences that have not yet been received by ZigChain      |
+| height    | Block height at which this data was read                                         |
 
-> “Out of these committed packets, which ones have not been received?”
+> An empty `sequences` array means all queried packets (`53`, `54`, `71`) have already been received by ZigChain — no inbound delivery is pending.
 
----
+### `fetchUnreceivedAcks` vs `fetchUnreceivedPackets`
 
-### Parameters
+| Feature   | fetchUnreceivedAcks                  | fetchUnreceivedPackets               |
+| --------- | ------------------------------------ | ------------------------------------ |
+| Direction | Outbound (sent from ZigChain)        | Inbound (sent to ZigChain)           |
+| Question  | Which acks haven't come back yet?    | Which packets haven't arrived yet?   |
+| Result    | Sequences `[53, 54]` pending         | Empty — all received                 |
 
-* **portId** – The application port.
-* **channelId** – The IBC channel identifier.
-* **sequences** – List of packet sequence numbers to check.
-
----
+## When to Use
 
+* Checking for packets in transit toward ZigChain
+* Detecting dropped or stuck inbound IBC transfers
 
+---