@zuhaibnoor/zigchain-sdk 1.0.3 → 1.1.1

package/docs/tokenwrapper.md

@@ -0,0 +1,294 @@
+# Token Wrapper Module
+
+## 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.
+
+---
+
+## 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
+
+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>
+```
+
+The hash is derived from the channel and original denom path, making each IBC token globally unique on the receiving chain.
+
+### 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.
+
+---
+
+## Setup
+
+```ts
+import {
+  ChainTokenWrapperApi,
+  getNetworkEndpoints,
+  Network,
+} from '@zuhaibnoor/zigchain-sdk'
+
+const endpoints = getNetworkEndpoints(Network.Testnet)
+const tokenWrapperApi = new ChainTokenWrapperApi(endpoints)
+```
+
+---
+
+# 1️⃣ fetchModuleInfo
+
+## Method
+
+```ts
+async fetchModuleInfo()
+```
+
+## CLI Equivalent
+
+```bash
+zigchaind query tokenwrapper module-info
+```
+
+## 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 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
+}
+```
+
+## Response Field Explanation
+
+### 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     |
+
+### Access Control
+
+| 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)       |
+
+### 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
+async fetchParams()
+```
+
+## 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.dir(params, { depth: null })
+```
+
+## Example Response
+
+```json
+{
+  "params": {}
+}
+```
+
+## Response Field Explanation
+
+| Field  | Description                                                              |
+| ------ | ------------------------------------------------------------------------ |
+| params | Module parameter object. Currently empty on ZigChain testnet            |
+
+> 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.
+
+---
+
+# 3️⃣ fetchTotalTransfers
+
+## Method
+
+```ts
+async fetchTotalTransfers()
+```
+
+## CLI Equivalent
+
+```bash
+zigchaind query tokenwrapper total-transfers
+```
+
+## Description
+
+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.
+
+## Parameters
+
+None.
+
+## Usage Example
+
+```ts
+const totals = await tokenWrapperApi.fetchTotalTransfers()
+console.dir(totals, { depth: null })
+```
+
+## Example Response
+
+```json
+{
+  "total_transferred_in": "490615709",
+  "total_transferred_out": "191529021"
+}
+```
+
+## Response Field Explanation
+
+| 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)      |
+
+
+---