@zuhaibnoor/zigchain-sdk 1.0.2 → 1.1.0

package/docs/ibc/ibcClient.md

@@ -0,0 +1,302 @@
+# IBC Client
+
+The **IBC Client** is the security foundation of IBC.
+
+If IBC is a secure bridge between blockchains, then:
+
+* **Client** → the verifier
+* **Connection** → secured bridge
+* **Channel** → communication lane
+* **Packet** → message sent through the lane
+
+Without a client, nothing in IBC works.
+
+---
+
+# Setup
+
+```ts
+import {
+  ChainIbcClientApi,
+  getNetworkEndpoints,
+  Network,
+} from '@zuhaibnoor/zigchain-sdk'
+
+const endpoints = getNetworkEndpoints(Network.Testnet)
+const ibcClientApi = new ChainIbcClientApi(endpoints)
+```
+
+---
+
+# What is an IBC Client?
+
+An **IBC client** is NOT a user.
+It is NOT a wallet.
+
+It is a **light verifier** stored on ZigChain that:
+
+* Tracks another blockchain
+* Verifies its block headers
+* Stores its consensus states
+* Ensures packets are valid
+
+Think of it like:
+
+> A small embedded validator that watches another chain.
+
+---
+
+# `fetchClientStates()`
+
+### What it does
+
+Returns **all IBC clients** stored on ZigChain.
+
+Each client represents one external blockchain.
+
+---
+
+### CLI equivalent
+
+```bash
+zigchaind query ibc client states
+```
+
+---
+
+### Example
+
+```ts
+const clients = await ibcClientApi.fetchClientStates()
+console.dir(clients, { depth: null })
+```
+
+You’ll see:
+
+* client IDs
+* client types
+* latest height
+
+---
+
+# `fetchClientState()`
+
+```ts
+fetchClientState(clientId: string)
+```
+
+### What it does
+
+Returns the **full state of a specific client**.
+
+---
+
+### What is "State"?
+
+State means:
+
+> The stored verification information about the other chain.
+
+It contains things like:
+
+* chain ID
+* latest verified height
+* trust level
+* frozen height (if compromised)
+
+---
+
+### CLI equivalent
+
+```bash
+zigchaind query ibc client state <client-id>
+```
+
+---
+
+### Example
+
+```ts
+const state = await ibcClientApi.fetchClientState(
+  '07-tendermint-0'
+)
+
+console.dir(state, { depth: null })
+```
+
+---
+
+# `fetchClientStatus()`
+
+```ts
+fetchClientStatus(clientId: string)
+```
+
+### What it does
+
+Returns the health status of a client.
+
+Possible values:
+
+* `Active`
+* `Frozen`
+* `Expired`
+* `Unknown`
+
+---
+
+### Why does this matter?
+
+If a client is:
+
+* Frozen → packets cannot be verified
+* Expired → it needs updating
+* Active → everything works normally
+
+---
+
+### CLI equivalent
+
+```bash
+zigchaind query ibc client status <client-id>
+```
+
+---
+
+# `fetchConsensusStates()`
+
+```ts
+fetchConsensusStates(clientId: string)
+```
+
+### What it does
+
+Returns **all stored consensus states** of a client.
+
+---
+
+### What is a Consensus State?
+
+A consensus state is:
+
+> A verified snapshot of the other chain at a specific height.
+
+Each time a client is updated, a new consensus state is stored.
+
+---
+
+### CLI equivalent
+
+```bash
+zigchaind query ibc client consensus-states <client-id>
+```
+
+---
+
+# `fetchConsensusState()`
+
+```ts
+fetchConsensusState(
+  clientId: string,
+  height: number | string,
+  revisionNumber: number | string
+)
+```
+
+### What it does
+
+Returns the consensus state of a client at a specific height.
+
+---
+
+### CLI equivalent
+
+```bash
+zigchaind query ibc client consensus-state <client-id> <revision> <height>
+```
+
+---
+
+# `fetchConsensusStateHeights()`
+
+```ts
+fetchConsensusStateHeights(clientId: string)
+```
+
+### What it does
+
+Returns all heights for which consensus states exist.
+
+Useful to know which heights are verifiable.
+
+---
+
+### CLI equivalent
+
+```bash
+zigchaind query ibc client consensus-state-heights <client-id>
+```
+
+---
+
+# `fetchClientCreator()`
+
+```ts
+fetchClientCreator(clientId: string)
+```
+
+### What it does
+
+Returns the account address that created the client.
+
+---
+
+### Why is this useful?
+
+* Auditing
+* Governance
+* Debugging
+
+---
+
+### CLI equivalent
+
+```bash
+zigchaind query ibc client creator <client-id>
+```
+
+---
+
+# `fetchClientParams()`
+
+### What it does
+
+Returns the global parameters of the IBC client module.
+
+Example response:
+
+```json
+{
+  "params": {
+    "allowed_clients": ["*"]
+  }
+}
+```
+
+---
+
+### What does `"*"` mean?
+
+It means:
+
+> All client types are allowed on this chain.
+
+---
+
+### CLI equivalent
+
+```bash
+zigchaind query ibc client params
+```
+
+---

package/docs/ibc/ibcConnection.md

@@ -0,0 +1,214 @@
+# IBC Connection
+
+The **IBC Connection** creates a secure link between two blockchains.
+
+If IBC is a secure bridge system:
+
+* **Client** → verifier
+* **Connection** → secured bridge
+* **Channel** → lane on the bridge
+* **Packet** → message sent through the lane
+
+A connection must be established before channels can be created.
+
+---
+
+# Setup
+
+```ts
+import {
+  ChainIbcConnectionApi,
+  getNetworkEndpoints,
+  Network,
+} from '@zuhaibnoor/zigchain-sdk'
+
+const endpoints = getNetworkEndpoints(Network.Testnet)
+const ibcConnectionApi = new ChainIbcConnectionApi(endpoints)
+```
+
+---
+
+# What is a Connection?
+
+A **connection** is a secure, authenticated bridge between two chains.
+
+It is created using a handshake process:
+
+1. INIT
+2. TRY
+3. ACK
+4. CONFIRM
+
+Once the connection state becomes `OPEN`, channels can be built on top of it.
+
+---
+
+# `fetchConnections()`
+
+### What it does
+
+Returns **all IBC connections** stored on ZigChain.
+
+---
+
+### Why is this useful?
+
+It lets you see:
+
+* Which chains ZigChain is connected to
+* Connection states (INIT, TRYOPEN, OPEN)
+* Associated client IDs
+
+---
+
+### CLI equivalent
+
+```bash
+zigchaind query ibc connection connections
+```
+
+---
+
+### Example
+
+```ts
+const connections = await ibcConnectionApi.fetchConnections()
+console.dir(connections, { depth: null })
+```
+
+---
+
+# `fetchConnectionEnd()`
+
+```ts
+fetchConnectionEnd(connectionId: string)
+```
+
+### What it does
+
+Returns full details of a specific connection.
+
+---
+
+### Why is it called "Connection End"?
+
+Because the connection exists on **both chains**.
+
+Each chain stores its own side (or "end") of the connection.
+
+This function returns ZigChain’s side.
+
+---
+
+### It contains:
+
+* client ID
+* counterparty client ID
+* connection state
+* supported versions
+
+---
+
+### CLI equivalent
+
+```bash
+zigchaind query ibc connection end <connection-id>
+```
+
+---
+
+### Example
+
+```ts
+const connection = await ibcConnectionApi.fetchConnectionEnd(
+  'connection-0'
+)
+
+console.dir(connection, { depth: null })
+```
+
+---
+
+# `fetchConnectionParams()`
+
+### What it does
+
+Returns the global parameters of the IBC connection module.
+
+---
+
+### What are Connection Parameters?
+
+These are chain-wide rules that control:
+
+* Expected "block time" (The average time it takes for a blockchain to produce a new block.) 
+* Verification timing assumptions
+
+These parameters affect timeout behavior and security assumptions.
+
+---
+
+### CLI equivalent
+
+```bash
+zigchaind query ibc connection params
+```
+
+---
+
+### Example
+
+```ts
+const params = await ibcConnectionApi.fetchConnectionParams()
+console.dir(params)
+```
+
+---
+
+# `fetchClientConnectionPaths()`
+
+```ts
+fetchClientConnectionPaths(clientId: string)
+```
+
+### What it does
+
+Returns all connections that were created using a specific client.
+
+---
+
+### Why is this useful?
+
+Remember:
+
+Client → verifies another chain
+Connection → built using that client
+
+So this query answers:
+
+> “Which bridges were created using this verifier?”
+
+---
+
+### CLI equivalent
+
+```bash
+zigchaind query ibc connection path <client-id>
+```
+
+---
+
+### Example
+
+```ts
+const paths = await ibcConnectionApi.fetchClientConnectionPaths(
+  '07-tendermint-0'
+)
+
+console.dir(paths)
+```
+
+---
+
+
+

package/docs/ibc-transfer.md

@@ -0,0 +1,204 @@
+# IBC Transfer
+
+The **IBC Transfer module** allows ZigChain to **send and receive fungible tokens** across different blockchains using IBC.
+Think of it as a **secure token bridge system**.
+
+It works using:
+
+* **Denoms** → representations of tokens on other chains (can be traced via `denom trace` or `denom hash`)
+* **Escrow accounts** → temporary holding accounts for tokens being transferred
+* **Parameters** → rules and settings of the IBC transfer module
+
+---
+
+# Setup
+
+```ts
+import {
+  ChainIbcTransferApi,
+  getNetworkEndpoints,
+  Network,
+} from '@zuhaibnoor/zigchain-sdk'
+
+const endpoints = getNetworkEndpoints(Network.Testnet)
+const ibcTransferApi = new ChainIbcTransferApi(endpoints)
+```
+
+---
+
+## `fetchDenomByHash()`
+
+```ts
+fetchDenomByHash(hash: string)
+```
+
+### What it does
+
+Fetches the **denom trace info** from a **denom hash**.
+A **denom trace** shows the **origin chain, port, and channel** of a token.
+
+---
+
+### CLI equivalent
+
+```bash
+zigchaind query ibc-transfer denom <hash>
+```
+
+### Example
+
+```ts
+const denomTrace = await ibcTransferApi.fetchDenomByHash(
+  '5260516290F7883EC893AADA09A6B8CEC790F2EEF3196F440037908749785BE8'
+)
+console.dir(denomTrace, { depth: null })
+```
+
+---
+
+## `fetchDenomHash()`
+
+```ts
+fetchDenomHash(portId: string, channelId: string, denom: string)
+```
+
+### What it does
+
+Fetches the **denom hash** for a token given its **port, channel, and token name**.
+This hash uniquely identifies the token across chains.
+
+---
+
+### CLI equivalent
+
+```bash
+zigchaind query ibc-transfer denom-hash <port> <channel> <denom>
+```
+
+### Example
+
+```ts
+const denomHash = await ibcTransferApi.fetchDenomHash(
+  'transfer',
+  'channel-0',
+  'uzig'
+)
+console.dir(denomHash, { depth: null })
+```
+
+---
+
+## `fetchDenoms()`
+
+```ts
+fetchDenoms()
+```
+
+### What it does
+
+Returns **all denom traces** currently registered in the IBC transfer module.
+Useful to **list all IBC token representations** on the chain.
+
+---
+
+### CLI equivalent
+
+```bash
+zigchaind query ibc-transfer denoms
+```
+
+### Example
+
+```ts
+const allDenoms = await ibcTransferApi.fetchDenoms()
+console.dir(allDenoms, { depth: null })
+```
+
+---
+
+## `fetchEscrowAddress()`
+
+```ts
+fetchEscrowAddress(portId: string, channelId: string)
+```
+
+### What it does
+
+Returns the **escrow account address** for a given port and channel.
+Tokens being sent across IBC are **temporarily held** in this escrow account until they reach the other chain.
+
+---
+
+### CLI equivalent
+
+```bash
+zigchaind query ibc-transfer escrow-address <port> <channel>
+```
+
+### Example
+
+```ts
+const escrowAddr = await ibcTransferApi.fetchEscrowAddress(
+  'transfer',
+  'channel-0'
+)
+console.dir(escrowAddr, { depth: null })
+```
+
+---
+
+## `fetchTransferParams()`
+
+```ts
+fetchTransferParams()
+```
+
+### What it does
+
+Returns the **current parameters** of the IBC transfer module.
+This includes rules like **allowed tokens, transfer fees, and limits**.
+
+---
+
+### CLI equivalent
+
+```bash
+zigchaind query ibc-transfer params
+```
+
+### Example
+
+```ts
+const params = await ibcTransferApi.fetchTransferParams()
+console.dir(params, { depth: null })
+```
+
+---
+
+### How Escrow Works with Token Wrapping
+
+1. **Original tokens exist on the source chain** (e.g., `uzig` on ZigChain).
+
+2. **When you initiate an IBC transfer** to another chain:
+
+   * The tokens are **not sent directly**.
+   * Instead, they are **locked in an escrow account** on the source chain.
+   * The escrow account acts like a **safe holding place** for those tokens.
+
+3. **Receipt / Wrapped Token:**
+
+   * The destination chain does **not get the original tokens**.
+   * Instead, it receives a **representation of those tokens** — often called a **voucher** or **wrapped token**.
+   * This wrapped token can be used on the destination chain as if it were the original token.
+
+4. **Completion / Finalization:**
+
+   * Once the destination chain confirms the receipt of the wrapped token, the escrow account on the source chain marks the tokens as **spent / transferred**.
+   * If the transfer fails or is canceled, the tokens remain in the escrow account and can be returned to the original owner.
+
+---
+
+
+
+
+