@zuhaibnoor/zigchain-sdk 1.1.0 → 1.1.1

package/docs/tokenwrapper.md

@@ -1,22 +1,75 @@
 # Token Wrapper Module
 
-The **Token Wrapper module** keeps track of ZIG tokens that move **out of ZigChain to other blockchains** and come **back again**.
-It helps the chain maintain balance by **locking tokens when they leave** and **unlocking them when they return**, so no extra tokens are ever created.
+## What is the Token Wrapper Module?
+
+The **Token Wrapper module** is a ZigChain module that handles **wrapping and unwrapping tokens** transferred via IBC.
+
+It acts as a controlled gateway between ZigChain and a counterparty chain. Tokens that arrive via IBC are held by the module and a corresponding wrapped representation is issued on ZigChain. When tokens are sent back out, the wrapped tokens are burned and the originals are released.
 
 ---
 
-## How Token Wrapping Works (Simple Explanation)
+## Important Terminology
+
+### Token Wrapping
+
+The process of converting an IBC-received token into a ZigChain-native wrapped representation. The original IBC token is held in custody by the module while the wrapped version circulates on ZigChain.
+
+### Unwrapping
 
-1. You send **ZIG tokens out of ZigChain**
-2. Those ZIG tokens are **locked** on ZigChain
-3. You receive **wrapped ZIG** on another chain
-4. If wrapped ZIG comes back:
+The reverse process — burning the wrapped token on ZigChain and releasing the original IBC token back to the counterparty chain.
+
+### IBC Denom
+
+A token received via IBC has a denom in the format:
+
+```
+ibc/<hash>
+```
 
-   * Wrapped tokens are **destroyed**
-   * Original ZIG tokens are **unlocked**
+The hash is derived from the channel and original denom path, making each IBC token globally unique on the receiving chain.
 
-If wrapped ZIG is **spent on the other chain and never returned**,
-the corresponding ZIG **remains locked forever** on ZigChain.
+### Native vs Counterparty
+
+| Term                | Description                                             |
+| ------------------- | ------------------------------------------------------- |
+| Native (ZigChain)   | ZigChain's side of the IBC connection                   |
+| Counterparty        | The remote chain on the other end of the IBC channel    |
+
+### IBC Channel
+
+The specific IBC channel this module uses for transfers. Each direction has its own channel ID.
+
+```
+native_channel   = 'channel-0'       (ZigChain's channel)
+counterparty_channel = 'channel-612' (remote chain's channel)
+```
+
+### Client ID
+
+The IBC light client ID tracking the counterparty chain's state.
+
+```
+native_client_id       = '07-tendermint-0'
+counterparty_client_id = '07-tendermint-1163'
+```
+
+---
+
+### Operator Address
+
+The address authorized to manage and configure the Token Wrapper module. A `proposed_operator_address` indicates a pending operator transfer that has not yet been accepted.
+
+---
+
+### Pauser Addresses
+
+Addresses authorized to **pause** the Token Wrapper module in an emergency. When paused, wrapping and unwrapping are disabled to protect users.
+
+---
+
+### Total Transfers
+
+Cumulative counters tracking the total volume of tokens moved through the module in each direction since deployment.
 
 ---
 
@@ -26,7 +79,7 @@ the corresponding ZIG **remains locked forever** on ZigChain.
 import {
   ChainTokenWrapperApi,
   getNetworkEndpoints,
-  Network
+  Network,
 } from '@zuhaibnoor/zigchain-sdk'
 
 const endpoints = getNetworkEndpoints(Network.Testnet)
@@ -35,103 +88,207 @@ const tokenWrapperApi = new ChainTokenWrapperApi(endpoints)
 
 ---
 
-## `fetchModuleInfo`
+# 1️⃣ fetchModuleInfo
 
-Returns basic information about the Token Wrapper module.
+## Method
 
+```ts
+async fetchModuleInfo()
+```
 
-**Method**
+## CLI Equivalent
 
-```ts
-fetchModuleInfo()
+```bash
+zigchaind query tokenwrapper module-info
 ```
 
-**Example**
+## Description
+
+Fetches the **full configuration and current state** of the Token Wrapper module.
+
+This is the most comprehensive query for this module — it returns the module's on-chain address and current token balances, the operator and pauser configuration, the IBC channel and client details connecting ZigChain to the counterparty chain, the wrapped token denom, and whether the module is currently enabled.
+
+## Parameters
+
+None.
+
+## Usage Example
 
 ```ts
-const info = await tokenWrapperApi.fetchModuleInfo()
-console.log(info)
+const moduleInfo = await tokenWrapperApi.fetchModuleInfo()
+console.dir(moduleInfo, { depth: null })
+```
+
+## Example Response
+
+```json
+{
+  "module_address": "zig1hdq87rzf327fwz8rw9rnmchj7qa3uxrpxds2fw",
+  "balances": [
+    {
+      "denom": "ibc/2CC0B1B7A981ACC74854717F221008484603BB8360E81B262411B0D830EDE9B0",
+      "amount": "1028"
+    },
+    {
+      "denom": "ibc/B6863C1B541063B17C757293EC2E45BD2984AAC8CADD5ED7EDC2DA58B99445DC",
+      "amount": "261743802259999999900"
+    },
+    { "denom": "uzig", "amount": "20166055" }
+  ],
+  "operator_address": "zig1fw7yrucw09guffffdac64c3x5yc6rtlpt0nm5a",
+  "proposed_operator_address": "zig126kn23lxurns83w2n59a7e0v2wprjdrrfv4xw8",
+  "pauser_addresses": [
+    "zig19n4c3nmegkt06e0zj0yydhppfe6pzz53y3zxlz",
+    "zig155tasjju2zne3dnnh8ns2zqqcpfuljmke8hedt"
+  ],
+  "token_wrapper_enabled": true,
+  "native_client_id": "07-tendermint-0",
+  "counterparty_client_id": "07-tendermint-1163",
+  "native_port": "transfer",
+  "counterparty_port": "transfer",
+  "native_channel": "channel-0",
+  "counterparty_channel": "channel-612",
+  "denom": "unit-zig",
+  "decimal_difference": 12
+}
 ```
 
-**Use case**
+## Response Field Explanation
 
-* Verify that the Token Wrapper module is available and active on the chain
+### Module Identity and State
 
----
+| Field                     | Description                                                                         |
+| ------------------------- | ----------------------------------------------------------------------------------- |
+| module_address            | On-chain address of the Token Wrapper module — holds IBC tokens in custody         |
+| token_wrapper_enabled     | `true` if wrapping and unwrapping are currently active. `false` means paused        |
+| denom                     | The name of the wrapped token representation on ZigChain              |
+| decimal_difference        | Decimal scaling factor between the wrapped and original token (12 = 10^12 scale)   |
+
+### `balances`
+
+The current token holdings of the module's custody address. These are the IBC tokens being held in reserve plus any native `uzig` for operational use.
+
+| Field  | Description                                               |
+| ------ | --------------------------------------------------------- |
+| denom  | Token denomination (`ibc/<hash>` or native denom)         |
+| amount | Amount currently held in the module's custody account     |
 
-## `fetchParams`
+### Access Control
 
-Fetches the **configuration parameters** of the Token Wrapper module.
+| Field                     | Description                                                                      |
+| ------------------------- | -------------------------------------------------------------------------------- |
+| operator_address          | Address with authority to configure the module                                   |
+| proposed_operator_address | Pending operator transfer — this address has been proposed but not yet accepted  |
+| pauser_addresses          | Addresses that can pause the module in an emergency (2 pausers on testnet)       |
 
-**Method**
+### IBC Connection Configuration
+
+| Field                   | Description                                                          |
+| ----------------------- | -------------------------------------------------------------------- |
+| native_client_id        | ZigChain's IBC light client tracking the counterparty chain          |
+| counterparty_client_id  | Counterparty chain's IBC light client tracking ZigChain              |
+| native_port             | IBC port on ZigChain's side (always `transfer`)                      |
+| counterparty_port       | IBC port on the counterparty chain's side (always `transfer`)        |
+| native_channel          | ZigChain's IBC channel ID for this connection (`channel-0`)          |
+| counterparty_channel    | Counterparty chain's IBC channel ID (`channel-612`)                  |
+
+---
+
+# 2️⃣ fetchParams
+
+## Method
 
 ```ts
-fetchParams()
+async fetchParams()
 ```
 
-**Example**
+## CLI Equivalent
+
+```bash
+zigchaind query tokenwrapper params
+```
+
+## Description
+
+Fetches the **Token Wrapper module parameters**.
+
+On ZigChain testnet, the params object is currently empty — all configuration is managed directly through the module info rather than a separate params structure. This endpoint is included for completeness and forward compatibility as the module evolves.
+
+## Parameters
+
+None.
+
+## Usage Example
 
 ```ts
 const params = await tokenWrapperApi.fetchParams()
-console.log(params)
+console.dir(params, { depth: null })
 ```
 
-**Use case**
+## Example Response
 
-* Check whether token wrapping is enabled
-* Inspect module behavior settings
+```json
+{
+  "params": {}
+}
+```
 
----
+## Response Field Explanation
+
+| Field  | Description                                                              |
+| ------ | ------------------------------------------------------------------------ |
+| params | Module parameter object. Currently empty on ZigChain testnet            |
 
-## `fetchTotalTransfers`
+> The Token Wrapper module's operational configuration (channel IDs, operator address, pauser addresses, enabled state) is stored directly in module state and returned by `fetchModuleInfo`. The `params` endpoint is reserved for governance-controlled parameters that may be added in future module versions.
 
-Returns the **total amount of ZIG tokens**:
+---
 
-* Sent **out of ZigChain**
-* Returned **back to ZigChain**
+# 3️⃣ fetchTotalTransfers
 
-**Method**
+## Method
 
 ```ts
-fetchTotalTransfers()
+async fetchTotalTransfers()
 ```
 
-**Example**
+## CLI Equivalent
 
-```ts
-const totals = await tokenWrapperApi.fetchTotalTransfers()
-console.log(totals)
+```bash
+zigchaind query tokenwrapper total-transfers
 ```
 
-**What this tells you**
+## Description
 
-* How much ZIG is currently **locked**
-* How much ZIG has **returned**
-* Helps audit cross-chain token movement
+Fetches the **cumulative transfer volume** through the Token Wrapper module since its deployment — the total amount of tokens that have been wrapped (transferred in) and unwrapped (transferred out).
 
----
+This provides a lifetime volume metric for the bridge, useful for analytics and monitoring net flow direction.
 
-## Real-World Example
+## Parameters
 
-* You send **10 ZIG** out of ZigChain
-* ZigChain **locks 10 ZIG**
-* You receive **10 wrapped ZIG** on another chain
-* You spend **5 wrapped ZIG**
-* You return **5 wrapped ZIG** back
+None.
 
-Result:
+## Usage Example
 
-* **5 ZIG unlocked and returned**
-* **5 ZIG remain locked forever** (because they were spent)
+```ts
+const totals = await tokenWrapperApi.fetchTotalTransfers()
+console.dir(totals, { depth: null })
+```
 
----
+## Example Response
+
+```json
+{
+  "total_transferred_in": "490615709",
+  "total_transferred_out": "191529021"
+}
+```
 
-## Summary Table
+## Response Field Explanation
 
-| Function              | Purpose                                         |
-| --------------------- | ----------------------------------------------- |
-| `fetchModuleInfo`     | Shows basic info about the Token Wrapper module |
-| `fetchParams`         | Displays module configuration settings          |
-| `fetchTotalTransfers` | Shows total ZIG moved out and returned          |
+| Field                  | Description                                                                  |
+| ---------------------- | ---------------------------------------------------------------------------- |
+| total_transferred_in   | Cumulative amount of tokens wrapped (received from counterparty chain)       |
+| total_transferred_out  | Cumulative amount of tokens unwrapped (sent back to counterparty chain)      |
 
 
+---