@zuhaibnoor/zigchain-sdk 1.0.3 → 1.1.1

package/docs/ibc/ibcClient.md

@@ -0,0 +1,771 @@
+# IBC Client Module
+
+## What is the IBC Client Module?
+
+The **IBC Client module** allows you to query information about IBC (Inter-Blockchain Communication) light clients.
+
+IBC clients are light clients that verify the state of other blockchains within ZigChain. They maintain state history and validate cross-chain transactions.
+
+This module helps you:
+
+* Query client configurations
+* Monitor client status and health
+* Verify cross-chain communication setup
+* Track client creators and parameters
+
+---
+
+# Important Terminology
+
+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:
+
+```
+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.
+
+---
+
+### Revision Number and Height
+
+IBC blockchains use a two-part height identifier:
+
+* **Revision Number** – Increments on chain upgrades
+* **Revision Height** – Block number within that revision
+
+Example:
+
+```
+revision_number: 3
+revision_height: 20311715
+```
+
+This represents block `20311715` in revision `3`.
+
+---
+
+### Client Status
+
+The **Client Status** indicates the operational state of a light client.
+
+Possible values:
+
+* `Active` – Client is operational
+* `Expired` – Client has expired (no updates)
+* `Frozen` – Client is frozen due to misbehavior
+
+---
+
+### Light Client Type
+
+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'
+```
+
+---
+
+# 1️⃣ fetchConsensusState
+
+## Method
+
+```ts
+async fetchConsensusState(
+  clientId: string,
+  height: number | string,
+  rev_no: number | string
+)
+```
+
+## CLI Equivalent
+
+```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
+
+| 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
+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"
+  }
+}
+```
+
+## Response Field Explanation
+
+### `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            |
+
+### `proof`
+
+Merkle proof for verification (usually null for queries).
+
+### `proof_height`
+
+Height of the proof on the ZigChain blockchain.
+
+## When to Use
+
+* Verifying state from a specific height on remote chain
+* Accessing historical consensus information
+* Validating cross-chain proofs
+* Debugging IBC transactions
+
+---
+
+# 2️⃣ fetchConsensusStates
+
+## Method
+
+```ts
+async fetchConsensusStates(clientId: string)
+```
+
+## CLI Equivalent
+
+```bash
+zigchaind query ibc client consensus-states <client-id>
+```
+
+
+## Description
+
+Fetches **all consensus states** stored for a client.
+
+Returns a paginated list of every consensus state the client has verified.
+
+## Parameters
+
+| Name     | Type   | Description                    |
+| -------- | ------ | ------------------------------ |
+| clientId | string | IBC client identifier          |
+
+## Usage Example
+
+```ts
+const states = await clientApi.fetchConsensusStates('07-tendermint-40')
+console.dir(states, { depth: null })
+```
+
+## Example Response
+
+```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"
+  }
+}
+```
+
+## Response Field Explanation
+
+### `consensus_states`
+
+Array of consensus state entries.
+
+Each entry contains:
+
+| Field              | Description                           |
+| ------------------ | ------------------------------------- |
+| height             | Revision number and height            |
+| consensus_state    | The consensus state data              |
+
+
+---
+
+# 3️⃣ fetchConsensusStateHeights
+
+## Method
+
+```ts
+async fetchConsensusStateHeights(clientId: string)
+```
+
+## CLI Equivalent
+
+```bash
+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.
+
+## Parameters
+
+| Name     | Type   | Description           |
+| -------- | ------ | --------------------- |
+| clientId | string | IBC client identifier |
+
+## Usage Example
+
+```ts
+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"
+  }
+}
+```
+
+## Response Field Explanation
+
+### `consensus_state_heights`
+
+Array of height objects at which consensus states are stored.
+
+Each entry contains:
+
+| Field              | Description      |
+| ------------------ | ---------------- |
+| revision_number    | Revision number  |
+| revision_height    | Block height     |
+
+### `pagination`
+
+Pagination information.
+
+---
+
+# 4️⃣ fetchClientCreator
+
+## Method
+
+```ts
+async fetchClientCreator(clientId: string)
+```
+
+## CLI Equivalent
+
+```bash
+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 |
+
+## Usage Example
+
+```ts
+const creator = await clientApi.fetchClientCreator('07-tendermint-40')
+console.dir(creator, { depth: null })
+```
+
+## Example Response
+
+```json
+{
+  "creator": "zig1xj0nym9p4mugg93cmxa46unzy0lt2hvddm2986"
+}
+```
+
+
+## Response Field Explanation
+
+| Field   | Description                    |
+| ------- | ------------------------------ |
+| creator | Bech32 address of client creator |
+
+
+## When to Use
+
+* Auditing client creation
+* Tracking who set up cross-chain connections
+---
+
+# 5️⃣ fetchClientParams
+
+## Method
+
+```ts
+async fetchClientParams()
+```
+
+## CLI Equivalent
+
+```bash
+zigchaind query ibc client params
+```
+
+
+## Description
+
+Fetches the **IBC client module parameters**.
+
+These are chain-level settings that control client behavior.
+
+## Parameters
+
+None.
+
+## Usage Example
+
+```ts
+const params = await clientApi.fetchClientParams()
+console.dir(params, { depth: null })
+```
+
+## Example Response
+
+```json
+{
+  "params": {
+    "allowed_clients": ["*"]
+  }
+}
+```
+
+## 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
+
+* Checking which light clients can be created
+* Verifying chain configuration
+
+
+---
+
+# 6️⃣ fetchClientState
+
+## Method
+
+```ts
+async fetchClientState(clientId: string)
+```
+
+## CLI Equivalent
+
+```bash
+zigchaind query ibc client client-state <client-id>
+```
+
+## Description
+
+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
+const clientState = await clientApi.fetchClientState('07-tendermint-40')
+console.dir(clientState, { depth: null })
+```
+
+## Example Response
+
+```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.
+
+Example: `numerator: 2, denominator: 3` = 2/3 of validators
+
+### Time Periods
+
+All time values are in duration format (e.g., `403200s` = 403200 seconds).
+
+---
+
+# 7️⃣ fetchClientStates
+
+## Method
+
+```ts
+async fetchClientStates()
+```
+
+## CLI Equivalent
+
+```bash
+zigchaind query ibc client client-states
+```
+
+## Description
+
+Fetches **all IBC clients** on the chain.
+
+Returns the client state of every light client configured on ZigChain.
+
+## Parameters
+
+None.
+
+## Usage Example
+
+```ts
+const allClients = await clientApi.fetchClientStates()
+console.dir(allClients, { depth: null })
+```
+
+## Example Response (Partial)
+
+```json
+{
+  "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:
+
+| Field         | Description              |
+| ------------- | ------------------------ |
+| client_id     | Unique client identifier |
+| client_state  | Full client configuration |
+
+
+## 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
+
+---
+
+# 8️⃣ fetchClientStatus
+
+## Method
+
+```ts
+async fetchClientStatus(clientId: string)
+```
+
+## CLI Equivalent
+
+```bash
+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
+
+---
+