@zuhaibnoor/zigchain-sdk 1.1.0 → 1.1.1

package/docs/ibc/ibcClient.md

@@ -1,302 +1,771 @@
-# IBC Client
+# IBC Client Module
 
-The **IBC Client** is the security foundation of IBC.
+## What is the IBC Client Module?
 
-If IBC is a secure bridge between blockchains, then:
+The **IBC Client module** allows you to query information about IBC (Inter-Blockchain Communication) light clients.
 
-* **Client** → the verifier
-* **Connection** → secured bridge
-* **Channel** → communication lane
-* **Packet** → message sent through the lane
+IBC clients are light clients that verify the state of other blockchains within ZigChain. They maintain state history and validate cross-chain transactions.
 
-Without a client, nothing in IBC works.
+This module helps you:
+
+* Query client configurations
+* Monitor client status and health
+* Verify cross-chain communication setup
+* Track client creators and parameters
 
 ---
 
-# Setup
+# Important Terminology
 
-```ts
-import {
-  ChainIbcClientApi,
-  getNetworkEndpoints,
-  Network,
-} from '@zuhaibnoor/zigchain-sdk'
+Before documenting functions, let's define key terms.
+
+### IBC Client
+
+An **IBC Client** is a light client that tracks the consensus state of another blockchain.
+
+Each client:
+* Is assigned a unique `client_id`
+* Verifies state proofs from another chain
+* Maintains a history of consensus states
+* Can be updated with new blocks
+
+Example client ID:
 
-const endpoints = getNetworkEndpoints(Network.Testnet)
-const ibcClientApi = new ChainIbcClientApi(endpoints)
 ```
+07-tendermint-40
+```
+
+The naming convention is `<light-client-type>-<instance-number>`.
+
+---
+
+### Client State
+
+The **Client State** contains the configuration and current status of a light client.
+
+It includes:
+* Chain ID of the remote chain
+* Trust parameters
+* Latest verified height
+* Proof specifications
+
+---
+
+### Consensus State
+
+A **Consensus State** is a snapshot of a blockchain's validator set and app hash at a specific height.
 
 ---
 
-# What is an IBC Client?
+### Revision Number and Height
 
-An **IBC client** is NOT a user.
-It is NOT a wallet.
+IBC blockchains use a two-part height identifier:
 
-It is a **light verifier** stored on ZigChain that:
+* **Revision Number** – Increments on chain upgrades
+* **Revision Height** – Block number within that revision
 
-* Tracks another blockchain
-* Verifies its block headers
-* Stores its consensus states
-* Ensures packets are valid
+Example:
 
-Think of it like:
+```
+revision_number: 3
+revision_height: 20311715
+```
 
-> A small embedded validator that watches another chain.
+This represents block `20311715` in revision `3`.
 
 ---
 
-# `fetchClientStates()`
+### Client Status
 
-### What it does
+The **Client Status** indicates the operational state of a light client.
 
-Returns **all IBC clients** stored on ZigChain.
+Possible values:
 
-Each client represents one external blockchain.
+* `Active` – Client is operational
+* `Expired` – Client has expired (no updates)
+* `Frozen` – Client is frozen due to misbehavior
 
 ---
 
-### CLI equivalent
+### Light Client Type
 
-```bash
-zigchaind query ibc client states
+Different light client implementations for different blockchain types.
+
+Common types:
+
+* `07-tendermint` – Tendermint consensus
+* `06-solomachine` – Solo machine client
+
+---
+
+# Functions Documentation
+
+Setup:
+```ts
+import {
+  ChainIbcClientApi,
+  getNetworkEndpoints,
+  Network
+} from '@zuhaibnoor/zigchain-sdk'
+
+const endpoints = getNetworkEndpoints(Network.Testnet)
+const clientApi = new ChainIbcClientApi(endpoints)
+
+const clientId = '07-tendermint-40'
+const revision_no = '3'
+const revision_height = '20311715'
 ```
 
 ---
 
-### Example
+# 1️⃣ fetchConsensusState
+
+## Method
 
 ```ts
-const clients = await ibcClientApi.fetchClientStates()
-console.dir(clients, { depth: null })
+async fetchConsensusState(
+  clientId: string,
+  height: number | string,
+  rev_no: number | string
+)
 ```
 
-You’ll see:
+## CLI Equivalent
 
-* client IDs
-* client types
-* latest height
+```bash
+zigchaind query ibc client consensus-state <client-id> <revision-number> <revision-height>
+```
+## Description
 
----
+Fetches the **consensus state of a client at a specific height**.
+
+Returns the validator set and app hash at that block, along with proof information.
+
+## Parameters
 
-# `fetchClientState()`
+| Name     | Type              | Description                           |
+| -------- | ----------------- | ------------------------------------- |
+| clientId | string            | IBC client identifier (e.g., `07-tendermint-40`) |
+| height   | number \| string  | Revision height (block number)        |
+| rev_no   | number \| string  | Revision number                       |
+
+## Usage Example
 
 ```ts
-fetchClientState(clientId: string)
+const consensusState = await clientApi.fetchConsensusState(
+  '07-tendermint-40',
+  '20311715',
+  '3'
+)
+console.dir(consensusState, { depth: null })
+```
+
+## Example Response
+
+```json
+{
+  "consensus_state": {
+    "@type": "/ibc.lightclients.tendermint.v1.ConsensusState",
+    "timestamp": "2025-08-07T09:58:01.945662422Z",
+    "root": {
+      "hash": "z5EtwHpY4eOr2J9pxHRVC0jO68sjrEq5kOFKXZ4Un8c="
+    },
+    "next_validators_hash": "C7A4E4A6E4D3CE7EE93C83CDC6EC2A68F2C424AC8DD6CB9F769B55D8FE14BCF9"
+  },
+  "proof": null,
+  "proof_height": {
+    "revision_number": "2",
+    "revision_height": "4647355"
+  }
+}
 ```
 
-### What it does
+## Response Field Explanation
 
-Returns the **full state of a specific client**.
+### `consensus_state`
 
----
+The consensus state of the remote blockchain at that height.
+
+| Field                 | Description                           |
+| --------------------- | ------------------------------------- |
+| @type                 | Type of consensus state               |
+| timestamp             | When this consensus state was created |
+| root                  | App hash (merkle root)                |
+| next_validators_hash  | Hash of next validator set            |
 
-### What is "State"?
+### `proof`
 
-State means:
+Merkle proof for verification (usually null for queries).
 
-> The stored verification information about the other chain.
+### `proof_height`
 
-It contains things like:
+Height of the proof on the ZigChain blockchain.
 
-* chain ID
-* latest verified height
-* trust level
-* frozen height (if compromised)
+## When to Use
+
+* Verifying state from a specific height on remote chain
+* Accessing historical consensus information
+* Validating cross-chain proofs
+* Debugging IBC transactions
 
 ---
 
-### CLI equivalent
+# 2️⃣ fetchConsensusStates
+
+## Method
+
+```ts
+async fetchConsensusStates(clientId: string)
+```
+
+## CLI Equivalent
 
 ```bash
-zigchaind query ibc client state <client-id>
+zigchaind query ibc client consensus-states <client-id>
 ```
 
----
 
-### Example
+## Description
 
-```ts
-const state = await ibcClientApi.fetchClientState(
-  '07-tendermint-0'
-)
+Fetches **all consensus states** stored for a client.
 
-console.dir(state, { depth: null })
-```
+Returns a paginated list of every consensus state the client has verified.
 
----
+## Parameters
 
-# `fetchClientStatus()`
+| Name     | Type   | Description                    |
+| -------- | ------ | ------------------------------ |
+| clientId | string | IBC client identifier          |
+
+## Usage Example
 
 ```ts
-fetchClientStatus(clientId: string)
+const states = await clientApi.fetchConsensusStates('07-tendermint-40')
+console.dir(states, { depth: null })
 ```
 
-### What it does
+## Example Response
 
-Returns the health status of a client.
+```json
+{
+  "consensus_states": [
+    {
+      "height": {
+        "revision_number": "3",
+        "revision_height": "20214158"
+      },
+      "consensus_state": {
+        "@type": "/ibc.lightclients.tendermint.v1.ConsensusState",
+        "timestamp": "2025-08-01T01:03:18.104587239Z",
+        "root": {
+          "hash": "S4bGyoy7tgkNwGo/+rMIbLwgT3k2wbUcdgJ0/2dO77A="
+        },
+        "next_validators_hash": "3D03EA8EA7B8F287D43FA16CD76EDC99DEA2FF78B9F3F4E26F1C5F38A702988E"
+      }
+    },
+    {
+      "height": {
+        "revision_number": "3",
+        "revision_height": "20214413"
+      },
+      "consensus_state": {
+        "@type": "/ibc.lightclients.tendermint.v1.ConsensusState",
+        "timestamp": "2025-08-01T01:27:16.945419603Z",
+        "root": {
+          "hash": "hG5WlVXUUlmq8Gj50VySITymGCJamkSFaT+2X1VIh8A="
+        },
+        "next_validators_hash": "3D03EA8EA7B8F287D43FA16CD76EDC99DEA2FF78B9F3F4E26F1C5F38A702988E"
+      }
+    }
+  ],
+  "pagination": {
+    "next_key": null,
+    "total": "10"
+  }
+}
+```
 
-Possible values:
+## Response Field Explanation
 
-* `Active`
-* `Frozen`
-* `Expired`
-* `Unknown`
+### `consensus_states`
 
----
+Array of consensus state entries.
 
-### Why does this matter?
+Each entry contains:
 
-If a client is:
+| Field              | Description                           |
+| ------------------ | ------------------------------------- |
+| height             | Revision number and height            |
+| consensus_state    | The consensus state data              |
 
-* Frozen → packets cannot be verified
-* Expired → it needs updating
-* Active → everything works normally
 
 ---
 
-### CLI equivalent
+# 3️⃣ fetchConsensusStateHeights
+
+## Method
+
+```ts
+async fetchConsensusStateHeights(clientId: string)
+```
+
+## CLI Equivalent
 
 ```bash
-zigchaind query ibc client status <client-id>
+zigchaind query ibc client consensus-state-heights <client-id>
 ```
 
----
+## Description
+
+Fetches **all heights** at which consensus states are stored for a client.
+
+Returns a lightweight list of heights without full state data.
+
+Useful for efficient lookups and pagination.
 
-# `fetchConsensusStates()`
+## Parameters
+
+| Name     | Type   | Description           |
+| -------- | ------ | --------------------- |
+| clientId | string | IBC client identifier |
+
+## Usage Example
 
 ```ts
-fetchConsensusStates(clientId: string)
+const heights = await clientApi.fetchConsensusStateHeights('07-tendermint-40')
+console.dir(heights, { depth: null })
+```
+
+## Example Response
+
+```json
+{
+  "consensus_state_heights": [
+    { "revision_number": "3", "revision_height": "20214158" },
+    { "revision_number": "3", "revision_height": "20214413" },
+    { "revision_number": "3", "revision_height": "20228806" },
+    { "revision_number": "3", "revision_height": "20244115" },
+    { "revision_number": "3", "revision_height": "20259431" },
+    { "revision_number": "3", "revision_height": "20274741" },
+    { "revision_number": "3", "revision_height": "20310435" },
+    { "revision_number": "3", "revision_height": "20311711" },
+    { "revision_number": "3", "revision_height": "20311714" },
+    { "revision_number": "3", "revision_height": "20311715" }
+  ],
+  "pagination": {
+    "next_key": null,
+    "total": "10"
+  }
+}
 ```
 
-### What it does
+## Response Field Explanation
 
-Returns **all stored consensus states** of a client.
+### `consensus_state_heights`
 
----
+Array of height objects at which consensus states are stored.
 
-### What is a Consensus State?
+Each entry contains:
 
-A consensus state is:
+| Field              | Description      |
+| ------------------ | ---------------- |
+| revision_number    | Revision number  |
+| revision_height    | Block height     |
 
-> A verified snapshot of the other chain at a specific height.
+### `pagination`
 
-Each time a client is updated, a new consensus state is stored.
+Pagination information.
 
 ---
 
-### CLI equivalent
+# 4️⃣ fetchClientCreator
+
+## Method
+
+```ts
+async fetchClientCreator(clientId: string)
+```
+
+## CLI Equivalent
 
 ```bash
-zigchaind query ibc client consensus-states <client-id>
+zigchaind query ibc client client-creator <client-id>
 ```
 
----
+## Description
+
+Fetches the **address that created** the IBC client.
+
+This shows who initialized the client on ZigChain.
+
+## Parameters
+
+| Name     | Type   | Description           |
+| -------- | ------ | --------------------- |
+| clientId | string | IBC client identifier |
 
-# `fetchConsensusState()`
+## Usage Example
 
 ```ts
-fetchConsensusState(
-  clientId: string,
-  height: number | string,
-  revisionNumber: number | string
-)
+const creator = await clientApi.fetchClientCreator('07-tendermint-40')
+console.dir(creator, { depth: null })
+```
+
+## Example Response
+
+```json
+{
+  "creator": "zig1xj0nym9p4mugg93cmxa46unzy0lt2hvddm2986"
+}
 ```
 
-### What it does
 
-Returns the consensus state of a client at a specific height.
+## Response Field Explanation
+
+| Field   | Description                    |
+| ------- | ------------------------------ |
+| creator | Bech32 address of client creator |
+
 
+## When to Use
+
+* Auditing client creation
+* Tracking who set up cross-chain connections
 ---
 
-### CLI equivalent
+# 5️⃣ fetchClientParams
+
+## Method
+
+```ts
+async fetchClientParams()
+```
+
+## CLI Equivalent
 
 ```bash
-zigchaind query ibc client consensus-state <client-id> <revision> <height>
+zigchaind query ibc client params
 ```
 
----
 
-# `fetchConsensusStateHeights()`
+## Description
+
+Fetches the **IBC client module parameters**.
+
+These are chain-level settings that control client behavior.
+
+## Parameters
+
+None.
+
+## Usage Example
 
 ```ts
-fetchConsensusStateHeights(clientId: string)
+const params = await clientApi.fetchClientParams()
+console.dir(params, { depth: null })
+```
+
+## Example Response
+
+```json
+{
+  "params": {
+    "allowed_clients": ["*"]
+  }
+}
 ```
 
-### What it does
+## Response Field Explanation
+
+### `params`
+
+Client module parameters.
+
+| Field             | Description                           |
+| ----------------- | ------------------------------------- |
+| allowed_clients   | List of allowed client types          |
+
+### `allowed_clients`
+
+Array of permitted light client types.
+
+* `*` – All client types allowed
+* List of specific types – Only those types allowed
+
+
+
+## When to Use
 
-Returns all heights for which consensus states exist.
+* Checking which light clients can be created
+* Verifying chain configuration
 
-Useful to know which heights are verifiable.
 
 ---
 
-### CLI equivalent
+# 6️⃣ fetchClientState
+
+## Method
+
+```ts
+async fetchClientState(clientId: string)
+```
+
+## CLI Equivalent
 
 ```bash
-zigchaind query ibc client consensus-state-heights <client-id>
+zigchaind query ibc client client-state <client-id>
 ```
 
----
+## Description
 
-# `fetchClientCreator()`
+Fetches the **raw client state** of a specific IBC client.
+
+Contains all configuration parameters and the latest verified height.
+
+## Parameters
+
+| Name     | Type   | Description           |
+| -------- | ------ | --------------------- |
+| clientId | string | IBC client identifier |
+
+## Usage Example
 
 ```ts
-fetchClientCreator(clientId: string)
+const clientState = await clientApi.fetchClientState('07-tendermint-40')
+console.dir(clientState, { depth: null })
 ```
 
-### What it does
+## Example Response
 
-Returns the account address that created the client.
+```json
+{
+  "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": "20311715" },
+    "proof_specs": [
+      {
+        "leaf_spec": {
+          "hash": "SHA256",
+          "prehash_key": "NO_HASH",
+          "prehash_value": "SHA256",
+          "length": "VAR_PROTO",
+          "prefix": "AA=="
+        },
+        "inner_spec": {
+          "child_order": [0, 1],
+          "child_size": 33,
+          "min_prefix_length": 4,
+          "max_prefix_length": 12,
+          "empty_child": null,
+          "hash": "SHA256"
+        },
+        "max_depth": 0,
+        "min_depth": 0,
+        "prehash_key_before_comparison": false
+      }
+    ],
+    "upgrade_path": ["upgrade", "upgradedIBCState"],
+    "allow_update_after_expiry": true,
+    "allow_update_after_misbehaviour": true
+  },
+  "proof": null,
+  "proof_height": { "revision_number": "2", "revision_height": "4647357" }
+}
+```
 
----
+## Response Field Explanation
+
+### `client_state`
+
+The complete client configuration.
+
+| Field                        | Description                           |
+| ---------------------------- | ------------------------------------- |
+| @type                        | Client type (e.g., Tendermint)        |
+| chain_id                     | Chain ID of the remote blockchain     |
+| trust_level                  | Fraction of validators needed to trust |
+| trusting_period              | How long to trust client without update |
+| unbonding_period             | Unbonding period of remote chain      |
+| max_clock_drift              | Maximum allowed clock drift           |
+| frozen_height                | Height at which client was frozen (if any) |
+| latest_height                | Latest verified height                |
+| proof_specs                  | Merkle proof specifications           |
+| upgrade_path                 | Path for client upgrades              |
+| allow_update_after_expiry    | Whether to allow updates after expiry |
+| allow_update_after_misbehaviour | Whether to allow updates after misbehavior |
+
+### Trust Level
+
+The fraction of validators whose signatures are required to trust the client.
 
-### Why is this useful?
+Example: `numerator: 2, denominator: 3` = 2/3 of validators
 
-* Auditing
-* Governance
-* Debugging
+### Time Periods
+
+All time values are in duration format (e.g., `403200s` = 403200 seconds).
 
 ---
 
-### CLI equivalent
+# 7️⃣ fetchClientStates
+
+## Method
+
+```ts
+async fetchClientStates()
+```
+
+## CLI Equivalent
 
 ```bash
-zigchaind query ibc client creator <client-id>
+zigchaind query ibc client client-states
 ```
 
----
+## Description
 
-# `fetchClientParams()`
+Fetches **all IBC clients** on the chain.
 
-### What it does
+Returns the client state of every light client configured on ZigChain.
 
-Returns the global parameters of the IBC client module.
+## Parameters
 
-Example response:
+None.
+
+## Usage Example
+
+```ts
+const allClients = await clientApi.fetchClientStates()
+console.dir(allClients, { depth: null })
+```
+
+## Example Response (Partial)
 
 ```json
 {
-  "params": {
-    "allowed_clients": ["*"]
+  "client_states": [
+    {
+      "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_specs": [...]
+      }
+    },
+    {
+      "client_id": "07-tendermint-1",
+      "client_state": {
+        "@type": "/ibc.lightclients.tendermint.v1.ClientState",
+        "chain_id": "cosmoshub-4",
+        "trust_level": { "numerator": "1", "denominator": "3" },
+        "trusting_period": "1209600s",
+        "unbonding_period": "1814400s",
+        ...
+      }
+    }
+  ],
+  "pagination": {
+    "next_key": null,
+    "total": "88"
   }
 }
 ```
 
----
+## Response Field Explanation
+
+### `client_states`
+
+Array of client entries.
+
+Each entry contains:
 
-### What does `"*"` mean?
+| Field         | Description              |
+| ------------- | ------------------------ |
+| client_id     | Unique client identifier |
+| client_state  | Full client configuration |
 
-It means:
 
-> All client types are allowed on this chain.
+## When to Use
+
+* Discovering all IBC clients on chain
+* Building chain topology maps
+* Analyzing cross-chain connections
+* Auditing IBC setup
+* Finding clients tracking specific chains
 
 ---
 
-### CLI equivalent
+# 8️⃣ fetchClientStatus
+
+## Method
+
+```ts
+async fetchClientStatus(clientId: string)
+```
+
+## CLI Equivalent
 
 ```bash
-zigchaind query ibc client params
+zigchaind query ibc client status <client-id>
+```
+
+## Description
+
+Fetches the **operational status** of an IBC client.
+
+Indicates whether the client is actively tracking the remote blockchain.
+
+## Parameters
+
+| Name     | Type   | Description           |
+| -------- | ------ | --------------------- |
+| clientId | string | IBC client identifier |
+
+## Usage Example
+
+```ts
+const status = await clientApi.fetchClientStatus('07-tendermint-40')
+console.dir(status, { depth: null })
 ```
 
+## Example Response
+
+```json
+{
+  "status": "Expired"
+}
+```
+
+## Response Field Explanation
+
+| Field  | Description              |
+| ------ | ------------------------ |
+| status | Current client status    |
+
+### Status Values
+
+| Status  | Meaning                                      |
+| ------- | -------------------------------------------- |
+| `Active` | Client is healthy and actively tracking      |
+| `Expired` | Client has not been updated recently         |
+| `Frozen` | Client is frozen due to misbehavior detection |
+
+## When to Use
+
+* Monitoring client health
+* Detecting stale or frozen clients
+* Alerting on client problems
+* Building status dashboards
+
 ---
+