@zuhaibnoor/zigchain-sdk 1.0.3 → 1.1.1

package/docs/ibc/ibcChannel.md

@@ -0,0 +1,977 @@
+# IBC Channel Module
+
+## What is IBC?
+
+**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.
+
+The IBC stack has four layers that build on each other:
+
+```
+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
+```
+---
+
+## Important Terminology
+
+### Channel
+
+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)
+```
+
+---
+
+### Port
+
+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.
+
+```
+port_id = 'transfer'
+```
+
+---
+
+### Channel State
+
+| 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               |
+
+---
+
+### Channel Ordering
+
+| 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    |
+
+All ZigChain IBC channels use `ORDER_UNORDERED`.
+
+---
+
+### Connection Hops
+
+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.
+
+```
+connection_hops = ['connection-0']
+```
+
+---
+
+### Packet Sequence Number
+
+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
+```
+
+---
+
+### Packet Commitment
+
+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.
+
+---
+
+### Packet Acknowledgement
+
+A **confirmation** sent back from the receiving chain after processing a packet. It proves the packet was received and whether it succeeded or failed.
+
+---
+
+### Packet Receipt
+
+A record stored on the receiving chain after a packet is processed. Proves the packet was received — used to prevent replay attacks.
+
+---
+
+### Proof Height
+
+The block height at which the returned proof or data was generated.
+
+```json
+{ "revision_number": "2", "revision_height": "4647092" }
+```
+
+`revision_number` is the chain's revision (incremented on resets). `revision_height` is the block number.
+
+---
+
+## Setup
+
+```ts
+import {
+  ChainIbcChannelApi,
+  getNetworkEndpoints,
+  Network,
+} from '@zuhaibnoor/zigchain-sdk'
+
+const endpoints = getNetworkEndpoints(Network.Testnet)
+const ibcChannelApi = new ChainIbcChannelApi(endpoints)
+
+const portId = 'transfer'
+const channelId = 'channel-0'
+```
+
+---
+
+# 1️⃣ fetchChannels
+
+## Method
+
+```ts
+async fetchChannels()
+```
+
+## CLI Equivalent
+
+```bash
+zigchaind query ibc channel channels
+```
+## Description
+
+Fetches **all IBC channels** registered on ZigChain across all ports and connections.
+
+## Parameters
+
+None.
+
+## Usage Example
+
+```ts
+const channels = await ibcChannelApi.fetchChannels()
+console.dir(channels, { 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": "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" }
+}
+```
+
+## 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`
+
+The block height at which this data was read.
+
+### Channel Types on ZigChain Testnet
+
+| 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 |
+
+## When to Use
+
+* 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
+
+---
+
+# 2️⃣ fetchChannelClientState
+
+## Method
+
+```ts
+async fetchChannelClientState(portId: string, channelId: string)
+```
+
+## CLI Equivalent
+
+```bash
+zigchaind query ibc channel client-state <port-id> <channel-id>
+```
+
+## 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 clientState = await ibcChannelApi.fetchChannelClientState('transfer', 'channel-0')
+console.dir(clientState, { 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
+
+---
+
+# 3️⃣ fetchChannelsByConnection
+
+## Method
+
+```ts
+async fetchChannelsByConnection(connectionId: string)
+```
+
+## CLI Equivalent
+
+```bash
+zigchaind query ibc channel connections <connection-id>
+```
+
+## Description
+
+Fetches **all channels built on a specific connection**.
+
+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.
+
+## Parameters
+
+| Name         | Type   | Description                               |
+| ------------ | ------ | ----------------------------------------- |
+| connectionId | string | Connection identifier (e.g. `'connection-0'`) |
+
+## Usage Example
+
+```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" }
+}
+```
+
+## Response Field Explanation
+
+Same channel object structure as `fetchChannels`. See that section for full field descriptions.
+
+---
+
+# 4️⃣ fetchChannelEnd
+
+## Method
+
+```ts
+async fetchChannelEnd(portId: string, channelId: string)
+```
+
+## CLI Equivalent
+
+```bash
+zigchaind query ibc channel end <port-id> <channel-id>
+```
+
+## Description
+
+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`.
+
+## 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 channelEnd = await ibcChannelApi.fetchChannelEnd('transfer', 'channel-0')
+console.dir(channelEnd, { depth: null })
+```
+
+## 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" }
+}
+```
+
+## Response Field Explanation
+
+### `channel`
+
+| 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                        |
+
+### `fetchChannels` vs `fetchChannelEnd`
+
+| 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  |
+
+## When to Use
+
+* Verifying a specific channel is open before initiating a transfer
+* Checking counterparty channel and port for a known channel
+
+---
+
+# 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
+
+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
+const nextRecv = await ibcChannelApi.fetchNextSequenceReceive('transfer', 'channel-0')
+console.dir(nextRecv, { depth: null })
+```
+
+## Example Response
+
+```json
+{
+  "next_sequence_receive": "0",
+  "proof": null,
+  "proof_height": { "revision_number": "2", "revision_height": "4647093" }
+}
+```
+
+## Response Field Explanation
+
+| 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                               |
+
+## When to Use
+
+* Monitoring incoming packet delivery progress
+* Detecting stuck inbound packets
+* Verifying a channel is actively receiving packets
+
+---
+
+# 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
+
+| 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 nextSend = await ibcChannelApi.fetchNextSequenceSend('transfer', 'channel-0')
+console.dir(nextSend, { depth: null })
+```
+
+## 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
+
+* Tracking total outbound transfer volume on a channel
+* Predicting the sequence number of the next transfer
+* Auditing outbound packet counts
+
+---
+
+# 7️⃣ fetchPacketAcknowledgement
+
+## Method
+
+```ts
+async fetchPacketAcknowledgement(portId: string, channelId: string, sequence: number | string)
+```
+
+## CLI Equivalent
+
+```bash
+zigchaind query ibc channel packet-ack <port-id> <channel-id> <sequence>
+```
+
+## Description
+
+Fetches the **acknowledgement stored for a specific packet**.
+
+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.
+
+## 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
+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
+---
+
+# 8️⃣ fetchPacketCommitment
+
+## Method
+
+```ts
+async fetchPacketCommitment(portId: string, channelId: string, sequence: number | string)
+```
+
+## CLI Equivalent
+
+```bash
+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.
+
+---
+
+## 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
+const commitment = await ibcChannelApi.fetchPacketCommitment('transfer', 'channel-0', 55)
+console.dir(commitment, { depth: null })
+```
+
+## Example Response
+
+```json
+{
+  "commitment": "TGCM/XS6O6oh0TgzrQfICRxgJ0Fxb2AerhtOtSfaG3U=",
+  "proof": null,
+  "proof_height": { "revision_number": "2", "revision_height": "4647094" }
+}
+```
+
+## Response Field Explanation
+
+| 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                                 |
+
+## When to Use
+
+* Checking if a specific packet is still awaiting acknowledgement
+* Debugging in-flight or stuck transfers
+
+---
+
+# 9️⃣ fetchPacketCommitments
+
+## Method
+
+```ts
+async fetchPacketCommitments(portId: string, channelId: string)
+```
+
+## 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
+const commitments = await ibcChannelApi.fetchPacketCommitments('transfer', 'channel-0')
+console.dir(commitments, { depth: null })
+```
+
+## 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" }
+}
+```
+
+## Response Field Explanation
+
+### `commitments[]`
+
+| 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                    |
+
+### `fetchPacketCommitment` vs `fetchPacketCommitments`
+
+| Feature             | fetchPacketCommitment     | fetchPacketCommitments          |
+| ------------------- | ------------------------- | ------------------------------- |
+| Scope               | Single sequence           | All outstanding commitments     |
+| Use case            | Check one specific packet | Overview of all in-flight packets |
+
+---
+
+# 🔟 fetchPacketReceipt
+
+## Method
+
+```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              |
+
+---
+
+## Usage Example
+
+```ts
+const receipt = await ibcChannelApi.fetchPacketReceipt('transfer', 'channel-0', 70)
+console.dir(receipt, { depth: null })
+```
+
+## Example Response
+
+```json
+{
+  "received": true,
+  "proof": null,
+  "proof_height": { "revision_number": "2", "revision_height": "4647094" }
+}
+```
+
+## Response Field Explanation
+
+| 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                           |
+
+## When to Use
+
+* Verifying an inbound packet was successfully received
+* Confirming an incoming IBC transfer reached ZigChain
+---
+
+# 1️⃣1️⃣ fetchUnreceivedAcks
+
+## Method
+
+```ts
+async fetchUnreceivedAcks(portId: string, channelId: string, sequences: (number | string)[])
+```
+
+## 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
+const unreceivedAcks = await ibcChannelApi.fetchUnreceivedAcks(
+  'transfer',
+  'channel-0',
+  [53, 54, 71]
+)
+console.dir(unreceivedAcks, { depth: null })
+```
+
+## Example Response
+
+```json
+{
+  "sequences": ["53", "54"],
+  "height": { "revision_number": "2", "revision_height": "4647095" }
+}
+```
+
+## Response Field Explanation
+
+| Field     | Description                                                                        |
+| --------- | ---------------------------------------------------------------------------------- |
+| sequences | The subset of queried sequences whose acknowledgements have not yet been received  |
+| height    | Block height at which this data was read                                           |
+
+## When to Use
+
+* 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
+
+---
+
+# 1️⃣2️⃣ fetchUnreceivedPackets
+
+## 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
+
+| 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
+const unreceivedPackets = await ibcChannelApi.fetchUnreceivedPackets(
+  'transfer',
+  'channel-0',
+  [53, 54, 71]
+)
+console.dir(unreceivedPackets, { depth: null })
+```
+
+## Example Response
+
+```json
+{
+  "sequences": [],
+  "height": { "revision_number": "2", "revision_height": "4647095" }
+}
+```
+
+## Response Field Explanation
+
+| 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                                         |
+
+> 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`
+
+| 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                 |
+
+## When to Use
+
+* Checking for packets in transit toward ZigChain
+* Detecting dropped or stuck inbound IBC transfers
+
+---