@zuhaibnoor/zigchain-sdk 1.0.3 → 1.1.0

package/docs/ibc/ibcChannel.md

@@ -0,0 +1,490 @@
+# IBC Module
+
+The **IBC (Inter-Blockchain Communication)** module allows ZigChain to communicate with other blockchains.
+
+Think of IBC like a **secure bridge system** between blockchains.
+
+It works using:
+
+* **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
+
+# Setup
+
+```ts
+import {
+  ChainIbcChannelApi,
+  getNetworkEndpoints,
+  Network,
+} from '@zuhaibnoor/zigchain-sdk'
+
+const endpoints = getNetworkEndpoints(Network.Testnet)
+const ibcApi = new ChainIbcApi(endpoints)
+```
+
+---
+## `fetchChannels()`
+
+### What it does
+
+Returns **all IBC channels** that exist on ZigChain.
+
+### What is a Channel?
+
+A **channel** is like a communication lane between two blockchains.
+
+If:
+
+* Connection = physical cable
+* Channel = lane inside that cable
+* Packet = message sent through the lane
+
+Then this function shows you all those lanes.
+
+---
+
+### CLI equivalent
+
+```bash
+zigchaind query ibc channel channels
+```
+
+### Example
+
+```ts
+const channels = await ibcApi.fetchChannels()
+console.dir(channels, { depth: null })
+```
+
+You’ll see:
+
+* channel IDs
+* port IDs
+* connection ID
+* whether the channel is OPEN or CLOSED
+
+---
+
+## `fetchChannelClientState()`
+
+```ts
+fetchChannelClientState(portId: string, channelId: string)
+```
+
+### What it does
+
+Returns the **client state** associated with a channel.
+
+---
+
+### What is a Client?
+
+In IBC, a **client** is a small verifier inside ZigChain that:
+
+* Tracks another blockchain
+* Confirms that the other chain is valid
+
+It is NOT a user.
+It is NOT a wallet.
+
+It is a **light client**.
+
+---
+
+### What is State?
+
+"State" simply means the **current stored information** about something.
+
+So:
+
+**Client State = the current verification information about the other chain.**
+
+It contains:
+
+* chain ID
+* latest height
+* trust level
+* proof parameters
+
+---
+
+### CLI equivalent
+
+```bash
+zigchaind query ibc channel client-state <port-id> <channel-id>
+```
+
+### Example
+
+```ts
+const clientState = await ibcApi.fetchChannelClientState(
+  'transfer',
+  'channel-0'
+)
+
+console.dir(clientState, { depth: null })
+```
+
+---
+
+## `fetchChannelsByConnection()`
+
+```ts
+fetchChannelsByConnection(connectionId: string)
+```
+
+### What it does
+
+Returns all channels built on a specific connection.
+
+---
+
+### What is a Connection?
+
+A **connection** is a secure link between two chains.
+
+You can think of it like:
+
+* Client = verifier
+* Connection = secured bridge
+* Channel = lane on the bridge
+
+A single connection can have multiple channels.
+
+---
+
+### CLI equivalent
+
+```bash
+zigchaind query ibc channel connections <connection-id>
+```
+
+### Example
+
+```ts
+const channels = await ibcApi.fetchChannelsByConnection(
+  'connection-0'
+)
+
+console.dir(channels, { depth: null })
+```
+
+---
+
+## `fetchChannelEnd()`
+
+```ts
+fetchChannelEnd(portId: string, channelId: string)
+```
+
+### What it does
+
+Returns full details of a specific channel.
+
+---
+
+### Why is it called "Channel End"?
+
+Because a channel exists on **both chains**.
+
+Each chain stores its own "end" of the channel.
+
+So:
+
+* ZigChain has one end
+* The other chain has another end
+
+This function shows ZigChain’s side.
+
+---
+
+### CLI equivalent
+
+```bash
+zigchaind query ibc channel end <port-id> <channel-id>
+```
+
+---
+
+##  `fetchNextSequenceReceive()`
+
+```ts
+fetchNextSequenceReceive(portId: string, channelId: string)
+```
+
+### What it does
+
+Returns the **next packet number ZigChain expects to receive**.
+
+---
+
+### What is a Sequence?
+
+Every packet sent through a channel gets a number:
+
+1
+2
+3
+4
+
+This number is called a **sequence number**.
+
+It ensures:
+
+* No duplicates
+* No skipped packets
+* Proper ordering
+
+---
+
+### So what is "Next Sequence Receive"?
+
+It means:
+
+> “What is the next packet number I am waiting to receive?”
+
+If it returns `15`,
+that means ZigChain has already received up to 14.
+
+---
+
+### CLI equivalent
+
+```bash
+zigchaind query ibc channel next-sequence-receive <port-id> <channel-id>
+```
+
+---
+
+##  `fetchNextSequenceSend()`
+
+```ts
+fetchNextSequenceSend(portId: string, channelId: string)
+```
+
+### What it does
+
+Returns the next packet number that will be used when sending a packet.
+
+---
+
+### What does this mean?
+
+If it returns `20`,
+then the next packet you send will be sequence number 20.
+
+This helps track outgoing transfers.
+
+---
+
+### CLI equivalent
+
+```bash
+zigchaind query ibc channel next-sequence-send <port-id> <channel-id>
+```
+
+---
+
+## `fetchPacketAcknowledgement()`
+
+```ts
+fetchPacketAcknowledgement(
+  portId: string,
+  channelId: string,
+  sequence: number | string
+)
+```
+
+### What it does
+
+Returns the acknowledgement for a specific packet.
+
+---
+
+### What is an Acknowledgement?
+
+When a packet is sent to another chain:
+
+1. It gets processed there.
+2. The other chain sends back a confirmation.
+3. That confirmation is called an **acknowledgement**.
+
+Think of it like:
+
+* You send a parcel 📦
+* Receiver signs and confirms delivery
+* That confirmation = acknowledgement
+
+---
+
+### Why is this important?
+
+It proves:
+
+* The packet was received
+* The packet was processed successfully (or failed)
+
+---
+
+### CLI equivalent
+
+```bash
+zigchaind query ibc channel packet-ack <port-id> <channel-id> <sequence>
+```
+
+---
+
+## `fetchPacketCommitment()`
+
+```ts
+async fetchPacketCommitment(
+  portId: string,
+  channelId: string,
+  sequence: number | string
+)
+```
+
+### Description
+
+Queries the **packet commitment** for a specific packet sequence.
+
+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.
+
+This function answers:
+
+> “Was packet `<sequence>` committed on this channel?”
+
+---
+
+### Parameters
+
+* **portId** – The application port (e.g., `"transfer"`).
+* **channelId** – The IBC channel identifier (e.g., `"channel-0"`).
+* **sequence** – The packet sequence number.
+
+---
+
+## `fetchPacketCommitments()`
+
+```ts
+async fetchPacketCommitments(
+  portId: string,
+  channelId: string
+)
+```
+
+### Description
+
+Queries **all packet commitments** for a given channel and port.
+
+This returns all packets that:
+
+* Were sent from this chain
+* Still have commitments stored
+
+It is useful to see all outstanding or tracked packets on a channel.
+
+---
+
+### Parameters
+
+* **portId** – The application port.
+* **channelId** – The IBC channel identifier.
+
+---
+
+## `fetchPacketReceipt()`
+
+```ts
+async fetchPacketReceipt(
+  portId: string,
+  channelId: string,
+  sequence: number | string
+)
+```
+
+### Description
+
+Queries the **packet receipt** for a specific packet.
+
+A **packet receipt** is stored on the receiving chain after a packet is successfully processed.
+It confirms that the packet was received.
+
+This function answers:
+
+> “Has packet `<sequence>` been received on this chain?”
+
+---
+
+### Parameters
+
+* **portId** – The application port.
+* **channelId** – The IBC channel identifier.
+* **sequence** – The packet sequence number.
+
+---
+
+## `fetchUnreceivedAcks()`
+
+```ts
+async fetchUnreceivedAcks(
+  portId: string,
+  channelId: string,
+  sequences: (number | string)[]
+)
+```
+
+### Description
+
+Checks which packet acknowledgements have **not yet been received**.
+
+An **acknowledgement (ack)** is a confirmation sent back to the original chain after a packet is processed on the counterparty chain.
+
+This function answers:
+
+> “Out of these sequences, which acknowledgements are still missing?”
+
+---
+
+### Parameters
+
+* **portId** – The application port.
+* **channelId** – The IBC channel identifier.
+* **sequences** – List of packet sequence numbers to check.
+
+---
+
+## `fetchUnreceivedPackets()`
+
+```ts
+async fetchUnreceivedPackets(
+  portId: string,
+  channelId: string,
+  sequences: (number | string)[]
+)
+```
+
+### Description
+
+Checks which packets have been committed but **not yet received** on the counterparty chain.
+
+This helps detect pending or stuck packets.
+
+This function answers:
+
+> “Out of these committed packets, which ones have not been received?”
+
+---
+
+### Parameters
+
+* **portId** – The application port.
+* **channelId** – The IBC channel identifier.
+* **sequences** – List of packet sequence numbers to check.
+
+---
+
+