@zuhaibnoor/zigchain-sdk 1.0.3 → 1.1.1

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,463 @@
+# IBC Transfer
+
+## What is IBC Transfer?
+
+The **IBC Transfer** enables ZigChain to send and receive fungible tokens across other IBC-enabled blockchains.
+
+Instead of directly moving tokens between chains, IBC Transfer:
+
+* Locks tokens in escrow on the source chain
+* Mints voucher tokens on the destination chain
+---
+
+# Important Terminology
+
+Before documenting functions, let’s define key terms.
+
+### Denom
+
+A token denomination.
+
+Examples:
+
+```
+uzig
+uusdc
+uatom
+```
+
+On IBC transfers, denoms can become:
+
+```
+ibc/<HASH>
+```
+
+### Denom Trace
+
+Describes the full path a token took across chains.
+
+Example:
+
+```
+transfer/channel-44/uusdc
+```
+
+It contains:
+
+* Port ID
+* Channel ID
+* Base denom
+
+### Denom Hash
+
+A SHA256 hash of the full denom trace string.
+
+Example:
+
+```
+SHA256("transfer/channel-44/uusdc")
+=
+5260516290F7883EC893AADA09A6B8CEC790F2EEF3196F440037908749785BE8
+```
+
+On-chain representation:
+
+```
+ibc/5260516290F7883EC893AADA09A6B8CEC790F2EEF3196F440037908749785BE8
+```
+
+### Escrow Account
+
+An **escrow account** is a special account controlled by the IBC Transfer module that temporarily holds tokens during a cross-chain transfer.
+
+When you send tokens to another chain, they are **locked in this escrow account** on the source chain. The tokens do not leave immediately — instead, they are safely held while the destination chain mints a corresponding voucher token.
+
+If the transfer succeeds, the escrowed tokens remain locked.
+If the transfer fails, the tokens are released back to the sender.
+
+This mechanism ensures:
+
+* No tokens are duplicated
+* Total supply remains correct
+* Cross-chain transfers are secure and verifiable
+
+--- 
+
+### Transfer Parameters
+
+Chain-level configuration controlling:
+
+* Whether sending is enabled
+* Whether receiving is enabled
+
+---
+
+# Functions Documentation
+
+## Setup
+
+```ts
+import {
+  ChainIbcTransferApi,
+  getNetworkEndpoints,
+  Network
+} from '@zuhaibnoor/zigchain-sdk'
+
+const endpoints = getNetworkEndpoints(Network.Testnet)
+const ibcTransferApi = new ChainIbcTransferApi(endpoints)
+
+const hash = '5260516290F7883EC893AADA09A6B8CEC790F2EEF3196F440037908749785BE8'
+const portId = 'transfer'
+const channelId = 'channel-44'
+const denom = 'uusdc'
+```
+
+---
+
+# 1️⃣ fetchDenomByHash
+
+## Method
+
+```ts
+async fetchDenomByHash(hash: string)
+```
+
+## CLI Equivalent
+
+```bash
+zigchaind query ibc-transfer denom <hash>
+```
+
+## Description
+
+Fetches the **denom trace** associated with a given IBC denom hash.
+
+This allows you to:
+
+* Identify the original base token
+* See which port and channel it arrived through
+* Reverse lookup `ibc/<hash>` tokens
+
+## Parameters
+
+| Name | Type   | Description                |
+| ---- | ------ | -------------------------- |
+| hash | string | IBC denom hash (no `ibc/`) |
+
+## Usage Example
+
+```ts
+const trace = await ibcTransferApi.fetchDenomByHash(hash)
+console.dir(trace, { depth: null })
+```
+
+---
+
+## Example Response
+
+```json
+{
+  "denom": {
+    "base": "uusdc",
+    "trace": [
+      {
+        "port_id": "transfer",
+        "channel_id": "channel-44"
+      }
+    ]
+  }
+}
+```
+
+## Response Field Explanation
+
+### `denom`
+
+Contains denom trace information.
+
+| Field | Description                |
+| ----- | -------------------------- |
+| base  | Original token denom       |
+| trace | Array of port/channel hops |
+
+Each trace entry includes:
+
+| Field      | Description            |
+| ---------- | ---------------------- |
+| port_id    | IBC port identifier    |
+| channel_id | IBC channel identifier |
+
+## When to Use
+
+* Resolving `ibc/<hash>` tokens
+* Building explorers
+* Wallet token metadata resolution
+
+---
+
+# 2️⃣ fetchDenomHash
+
+## Method
+
+```ts
+async fetchDenomHash(
+  portId: string,
+  channelId: string,
+  denom: string
+)
+```
+
+## CLI Equivalent
+
+```bash
+zigchaind query ibc-transfer denom-hash <port> <channel> <denom>
+```
+
+## Description
+
+Computes and returns the **IBC denom hash** from:
+
+* Port ID
+* Channel ID
+* Base denom
+
+This produces the deterministic hash used on-chain.
+
+## Parameters
+
+| Name      | Type   | Description                   |
+| --------- | ------ | ----------------------------- |
+| portId    | string | IBC port (usually `transfer`) |
+| channelId | string | IBC channel identifier        |
+| denom     | string | Base token denom              |
+
+## Usage Example
+
+```ts
+const denomHash = await ibcTransferApi.fetchDenomHash(
+  portId,
+  channelId,
+  denom
+)
+
+console.dir(denomHash, { depth: null })
+```
+
+## Example Response
+
+```json
+{
+  "hash": "5260516290F7883EC893AADA09A6B8CEC790F2EEF3196F440037908749785BE8"
+}
+```
+
+## Response Field Explanation
+
+| Field | Description                     |
+| ----- | ------------------------------- |
+| hash  | SHA256 hash of full denom trace |
+
+## When to Use
+
+* Generating `ibc/<hash>` values
+* Wallet token display logic
+* SDK internal conversions
+* Verifying denom determinism
+
+---
+
+# 3️⃣ fetchDenoms
+
+## Method
+
+```ts
+async fetchDenoms()
+```
+
+## CLI Equivalent
+
+```bash
+zigchaind query ibc-transfer denoms
+```
+
+## Description
+
+Returns all registered IBC denom traces on ZigChain.
+
+Useful for discovering:
+
+* Imported tokens
+* Multi-hop tokens
+* All IBC assets on-chain
+
+## Parameters
+
+None.
+
+## Usage Example
+
+```ts
+const denoms = await ibcTransferApi.fetchDenoms()
+console.dir(denoms, { depth: null })
+```
+
+## Example Response
+
+```json
+{
+  "denoms": [
+    {
+      "base": "uusdc",
+      "trace": [
+        {
+          "port_id": "transfer",
+          "channel_id": "channel-44"
+        }
+      ]
+    }
+  ],
+  "pagination": {
+    "next_key": null,
+    "total": "15"
+  }
+}
+```
+
+---
+
+## Response Field Explanation
+
+### `denoms`
+
+Array of denom traces.
+
+Each entry includes:
+
+| Field | Description         |
+| ----- | ------------------- |
+| base  | Original base denom |
+| trace | Path of IBC hops    |
+
+## When to Use
+
+* Building token explorers
+* Indexing IBC assets
+* Chain analytics
+* Asset discovery tools
+
+---
+
+# 4️⃣ fetchEscrowAddress
+
+## Method
+
+```ts
+async fetchEscrowAddress(
+  portId: string,
+  channelId: string
+)
+```
+
+## CLI Equivalent
+
+```bash
+zigchaind query ibc-transfer escrow-address <port> <channel>
+```
+
+## Description
+
+Returns the escrow account address for a specific port and channel.
+
+Tokens sent through this channel are temporarily locked here before being transferred.
+
+## Parameters
+
+| Name      | Type   | Description            |
+| --------- | ------ | ---------------------- |
+| portId    | string | IBC port identifier    |
+| channelId | string | IBC channel identifier |
+
+## Usage Example
+
+```ts
+const escrow = await ibcTransferApi.fetchEscrowAddress(
+  portId,
+  channelId
+)
+
+console.dir(escrow, { depth: null })
+```
+
+## Example Response
+
+```json
+{
+  "escrow_address": "zig1hcea3h0ykw4jqyjhj3tnydsk22s06adh5y350m"
+}
+```
+
+## Response Field Explanation
+
+| Field          | Description                   |
+| -------------- | ----------------------------- |
+| escrow_address | Module escrow account address |
+
+---
+
+# 5️⃣ fetchTransferParams
+
+## Method
+
+```ts
+async fetchTransferParams()
+```
+
+## CLI Equivalent
+
+```bash
+zigchaind query ibc-transfer params
+```
+
+## Description
+
+Fetches the chain-level configuration of the IBC Transfer module.
+
+These parameters determine whether token transfers are allowed.
+
+## Parameters
+
+None.
+
+## Usage Example
+
+```ts
+const params = await ibcTransferApi.fetchTransferParams()
+console.dir(params, { depth: null })
+```
+
+## Example Response
+
+```json
+{
+  "params": {
+    "send_enabled": true,
+    "receive_enabled": true
+  }
+}
+```
+
+## Response Field Explanation
+
+### `params`
+
+| Field           | Description                                 |
+| --------------- | ------------------------------------------- |
+| send_enabled    | Whether outgoing IBC transfers are allowed  |
+| receive_enabled | Whether incoming IBC transfers are accepted |
+
+## When to Use
+
+* Checking if transfers are paused
+* Governance audits
+---
+