@zuhaibnoor/zigchain-sdk 1.0.3 → 1.1.1

package/docs/wasm.md

@@ -0,0 +1,916 @@
+# WASM Module
+
+## What is WASM?
+
+**WASM (WebAssembly)** is a portable binary instruction format designed to run code safely.
+
+In the Cosmos ecosystem (including **ZigChain**), WASM is used through **CosmWasm**, which allows developers to deploy and execute smart contracts on-chain.
+
+---
+# Important Terminology
+
+Before documenting functions, let’s define key terms.
+
+### Code
+
+**Code** refers to uploaded smart contract bytecode stored on-chain.
+
+* It is stored once.
+* It is assigned a unique `code_id`.
+* Multiple contracts can be instantiated from the same code.
+
+Think of it like:
+
+> Code = Blueprint
+> Contract = Deployed instance of blueprint
+
+---
+
+### Code ID
+
+A unique numeric identifier assigned when contract bytecode is uploaded.
+
+Example:
+
+```
+code_id = 12
+```
+
+---
+
+### Contract
+
+A deployed instance created from a stored `code_id`.
+
+* Has its own unique contract address.
+* Maintains its own state.
+* Can be executed and queried independently.
+
+---
+
+### Contract Address
+
+A bech32 address representing a deployed contract.
+
+Example:
+
+```
+zig1abcd....
+```
+
+---
+
+### Contract State
+
+The stored key-value data maintained by a contract.
+
+---
+
+### Contract History
+
+Tracks migrations and updates related to a contract’s code.
+
+---
+
+# Functions Documentation
+Setup:
+```ts
+import {
+  ChainWasmApi,
+  getNetworkEndpoints,
+  Network
+} from '@zuhaibnoor/zigchain-sdk'
+
+const endpoints = getNetworkEndpoints(Network.Testnet)
+const wasmApi = new ChainWasmApi(endpoints)
+
+const codeId = '1'
+const contractAddress = 'zig15jqg0hmp9n06q0as7uk3x9xkwr9k3r7yh4ww2uc0hek8zlryrgmsamk4qg'
+const codeHash = '72A7D1420836189D5F3FBE4EDF8AC1246532F18E7CEE67CBEEA5F881DDC482E5'
+const creatorAddress = 'zig1v6q4m8u95hwghzskk59a79gk5zymfp263vkyec'
+
+```
+
+# 1️⃣ fetchCode
+
+## Method
+
+```ts
+async fetchCode(codeId: string)
+```
+
+## CLI Equivalent
+
+```bash
+zigchaind query wasm code <code-id>
+```
+
+---
+
+## Description
+
+Downloads the **raw WASM bytecode** stored on-chain for a given `code_id`.
+
+This returns:
+
+* Metadata about the code
+* The actual compiled WASM binary (base64 encoded)
+
+This is the full smart contract blueprint stored on the chain.
+
+---
+
+## Parameters
+
+| Name   | Type   | Description                                           |
+| ------ | ------ | ----------------------------------------------------- |
+| codeId | string | Unique identifier of the uploaded smart contract code |
+
+---
+
+## Usage Example
+
+```ts
+const code = await wasmApi.fetchCode('1')
+console.dir(code, { depth: null })
+```
+
+
+
+## Example Response
+
+```json
+{
+  "code_info": {
+    "code_id": "1",
+    "creator": "zig1v6q4m8u95hwghzskk59a79gk5zymfp263vkyec",
+    "data_hash": "72A7D1420836189D5F3FBE4EDF8AC1246532F18E7CEE67CBEEA5F881DDC482E5",
+    "instantiate_permission": {
+      "permission": "Everybody",
+      "addresses": []
+    }
+  },
+  "data": "AGFzbQEAAAAB2gEcYAJ/fwF/YAJ/fwBgA..."
+}
+```
+
+
+## Response Field Explanation
+
+### `code_info`
+
+Metadata about the stored contract code.
+
+| Field                  | Description                                            |
+| ---------------------- | ------------------------------------------------------ |
+| code_id                | Unique identifier of this uploaded contract            |
+| creator                | Address that uploaded the contract                     |
+| data_hash              | SHA256 hash of the WASM bytecode                       |
+| instantiate_permission | Who is allowed to instantiate contracts from this code |
+
+### `data`
+
+Base64-encoded WASM binary.
+
+⚠️ This is the actual compiled smart contract.
+
+
+## When to Use
+
+* Verifying bytecode integrity
+* Downloading contract for auditing
+* Comparing hashes
+* Building explorers or developer tools
+
+---
+
+# 2️⃣ fetchCodeInfo
+
+## Method
+
+```ts
+async fetchCodeInfo(codeId: string)
+```
+
+## CLI Equivalent
+
+```bash
+zigchaind query wasm code-info <code-id>
+```
+
+## Description
+
+Fetches **metadata only** about stored smart contract code.
+
+⚠️ Does NOT return raw WASM bytecode.
+
+This is lightweight compared to `fetchCode`.
+
+## Parameters
+
+| Name   | Type   | Description                                           |
+| ------ | ------ | ----------------------------------------------------- |
+| codeId | string | Unique identifier of the uploaded smart contract code |
+
+
+## Usage Example
+
+```ts
+const codeInfo = await wasmApi.fetchCodeInfo('1')
+console.dir(codeInfo, { depth: null })
+```
+
+
+## Example Response
+
+```json
+{
+  "code_id": "1",
+  "creator": "zig1v6q4m8u95hwghzskk59a79gk5zymfp263vkyec",
+  "checksum": "72A7D1420836189D5F3FBE4EDF8AC1246532F18E7CEE67CBEEA5F881DDC482E5",
+  "instantiate_permission": {
+    "permission": "Everybody",
+    "addresses": []
+  }
+}
+```
+
+## Response Field Explanation
+
+| Field                  | Description                              |
+| ---------------------- | ---------------------------------------- |
+| code_id                | Unique identifier of the stored contract |
+| creator                | Address that uploaded the contract       |
+| checksum               | SHA256 hash of the WASM bytecode         |
+| instantiate_permission | Defines who can instantiate contracts    |
+
+### Instantiate Permission Values
+
+| Value       | Meaning                         |
+| ----------- | ------------------------------- |
+| Everybody   | Anyone can instantiate          |
+| OnlyAddress | Only specific addresses allowed |
+| Nobody      | Instantiation disabled          |
+
+## When to Use
+
+* Checking who uploaded code
+* Getting code hash
+* Verifying instantiation permissions
+* Quick metadata lookup without large payload
+
+---
+
+# 3️⃣ fetchContractInfo
+
+## Method
+
+```ts
+async fetchContractInfo(contractAddress: string)
+```
+
+## CLI Equivalent
+
+```bash
+zigchaind query wasm contract <contract-address>
+```
+
+## Description
+
+Fetches metadata about a deployed contract instance.
+
+Remember:
+
+* Code = blueprint
+* Contract = deployed instance
+
+This function tells you details about that deployed instance.
+
+---
+
+## Parameters
+
+| Name            | Type   | Description             |
+| --------------- | ------ | ----------------------- |
+| contractAddress | string | Bech32 contract address |
+
+## Usage Example
+
+```ts
+const contractInfo = await wasmApi.fetchContractInfo(contractAddress)
+console.dir(contractInfo, { depth: null })
+```
+
+## Example Response
+
+```json
+{
+  "address": "zig15jqg0hmp9n06q0as7uk3x9xkwr9k3r7yh4ww2uc0hek8zlryrgmsamk4qg",
+  "contract_info": {
+    "code_id": "38",
+    "creator": "zig17a7mlm84taqmd3enrpcxhrwzclj9pga8efz83vrswnnywr8tv26s7mpq30",
+    "admin": "zig13cu9679ax3vxkq2n6aqeunfzzknmkjd0fnu5he",
+    "label": "Oroswap pair",
+    "created": {
+      "block_height": "64458",
+      "tx_index": "0"
+    },
+    "ibc_port_id": "",
+    "extension": null
+  }
+}
+```
+
+## Response Field Explanation
+
+### `address`
+
+The contract’s unique on-chain address.
+
+### `contract_info`
+
+| Field                | Description                                 |
+| -------------------- | ------------------------------------------- |
+| code_id              | Code used to instantiate this contract      |
+| creator              | Address that instantiated the contract      |
+| admin                | Address allowed to migrate/upgrade (if set) |
+| label                | Human-readable label given at instantiation |
+| created.block_height | Block number when contract was created      |
+| created.tx_index     | Transaction index inside the block          |
+| ibc_port_id          | IBC port if contract uses IBC               |
+| extension            | Optional custom metadata                    |
+
+## When to Use
+
+* Determining which code a contract runs
+* Checking contract admin privileges
+* Auditing contract deployment
+* Building block explorers
+* Verifying contract creator
+
+---
+
+# 4️⃣ fetchContractHistory
+
+## Method
+
+```ts
+async fetchContractHistory(contractAddress: string)
+```
+
+## CLI Equivalent
+
+```bash
+zigchaind query wasm contract-history <contract-address>
+```
+
+## Description
+
+Fetches the **code history of a deployed contract**.
+
+This shows:
+
+* When the contract was instantiated
+* If it was migrated (upgraded)
+* Which code versions it used over time
+
+This is important for auditing and upgrade tracking.
+
+## Parameters
+
+| Name            | Type   | Description                             |
+| --------------- | ------ | --------------------------------------- |
+| contractAddress | string | Bech32 address of the deployed contract |
+
+## Usage Example
+
+```ts
+const history = await wasmApi.fetchContractHistory(contractAddress)
+console.dir(history, { depth: null })
+```
+
+## Example Response
+
+```json
+{
+  "entries": [
+    {
+      "operation": "CONTRACT_CODE_HISTORY_OPERATION_TYPE_INIT",
+      "code_id": "38",
+      "updated": {
+        "block_height": "64458",
+        "tx_index": "0"
+      },
+      "msg": {
+        "pair_type": { "xyk": {} },
+        "asset_infos": [
+          {
+            "native_token": {
+              "denom": "coin.zig10rfjm85jmzfhravjwpq3hcdz8ngxg7lxd0drkr.uoro"
+            }
+          },
+          {
+            "native_token": { "denom": "uzig" }
+          }
+        ],
+        "token_code_id": 4,
+        "factory_addr": "zig17a7mlm84taqmd3enrpcxhrwzclj9pga8efz83vrswnnywr8tv26s7mpq30",
+        "init_params": null
+      }
+    }
+  ],
+  "pagination": {
+    "next_key": null,
+    "total": "0"
+  }
+}
+```
+
+
+## Response Field Explanation
+
+### `entries`
+
+Array of history records.
+
+Each entry contains:
+
+| Field                | Description                                 |
+| -------------------- | ------------------------------------------- |
+| operation            | Type of history event (INIT, MIGRATE, etc.) |
+| code_id              | Code version used at that time              |
+| updated.block_height | Block number when update happened           |
+| updated.tx_index     | Transaction index in the block              |
+| msg                  | Instantiation or migration message payload  |
+
+
+### Operation Types
+
+| Value                                        | Meaning                   |
+| -------------------------------------------- | ------------------------- |
+| CONTRACT_CODE_HISTORY_OPERATION_TYPE_INIT    | Contract was instantiated |
+| CONTRACT_CODE_HISTORY_OPERATION_TYPE_MIGRATE | Contract was upgraded     |
+
+
+## When to Use
+
+* Auditing contract upgrades
+* Tracking contract migrations
+* Verifying original instantiation parameters
+* Building blockchain explorers
+
+---
+
+# 5️⃣ fetchContractStateAll
+
+## Method
+
+```ts
+async fetchContractStateAll(contractAddress: string)
+```
+
+## CLI Equivalent
+
+```bash
+zigchaind query wasm contract-state all <contract-address>
+```
+
+## Description
+
+Fetches the **entire raw key-value state** of a contract.
+
+⚠️ Important:
+
+* Keys are base64 encoded
+* Values are base64 encoded
+* Can be large for production contracts
+
+This returns raw storage — not decoded JSON.
+
+## Parameters
+
+| Name            | Type   | Description             |
+| --------------- | ------ | ----------------------- |
+| contractAddress | string | Bech32 contract address |
+
+## Usage Example
+
+```ts
+const stateAll = await wasmApi.fetchContractStateAll(contractAddress)
+console.dir(stateAll, { depth: null })
+```
+
+## Example Response
+
+```json
+{
+  "models": [
+    {
+      "key": "636F6E666967",
+      "value": "eyJwYWlyX2luZm8iOnsiYXNzZXRfaW5mb3MiOlt7..."
+    },
+    {
+      "key": "636F6E74726163745F696E666F",
+      "value": "eyJjb250cmFjdCI6Im9yb3N3YXAtcGFpciIsInZlcnNpb24iOiIxLjAuMCJ9"
+    }
+  ],
+  "pagination": {
+    "next_key": null,
+    "total": "0"
+  }
+}
+```
+
+## Response Field Explanation
+
+### `models`
+
+Array of raw storage entries.
+
+Each model contains:
+
+| Field | Description                 |
+| ----- | --------------------------- |
+| key   | Base64-encoded storage key  |
+| value | Base64-encoded stored value |
+
+To interpret:
+
+1. Base64 decode the key
+2. Base64 decode the value
+3. Parse JSON (if applicable)
+
+## When to Use
+
+* Debugging contract storage
+* Writing indexers
+* Full state inspection
+* Advanced developer tooling
+
+# 6️⃣ fetchCodeList
+
+## Method
+
+```ts
+async fetchCodeList()
+```
+
+## CLI Equivalent
+
+```bash
+zigchaind query wasm list-code
+```
+
+## Description
+
+Lists all WASM bytecode uploaded on the chain.
+
+Returns metadata for every stored `code_id`.
+
+Does NOT return raw bytecode.
+
+## Parameters
+
+None.
+
+## Usage Example
+
+```ts
+const codes = await wasmApi.fetchCodeList()
+console.dir(codes, { depth: null })
+```
+
+## Example Response
+
+```json
+{
+  "code_infos": [
+    {
+      "code_id": "1",
+      "creator": "zig1v6q4m8u95hwghzskk59a79gk5zymfp263vkyec",
+      "data_hash": "72A7D1420836189D5F3FBE4EDF8AC1246532F18E7CEE67CBEEA5F881DDC482E5",
+      "instantiate_permission": {
+        "permission": "Everybody",
+        "addresses": []
+      }
+    },
+    {
+      "code_id": "4",
+      "creator": "zig13cu9679ax3vxkq2n6aqeunfzzknmkjd0fnu5he",
+      "data_hash": "9E8F583DA5231377E36332C5856A56D653AA0AE2284752BF11ABD2B0E46852AE",
+      "instantiate_permission": {
+        "permission": "Everybody",
+        "addresses": []
+      }
+    }
+  ],
+  "pagination": {
+    "next_key": "AAAAAAAAAGU=",
+    "total": "0"
+  }
+}
+```
+
+---
+
+## Response Field Explanation
+
+### `code_infos`
+
+Array of uploaded contract metadata.
+
+Each entry includes:
+
+| Field                  | Description                    |
+| ---------------------- | ------------------------------ |
+| code_id                | Unique code identifier         |
+| creator                | Address that uploaded the code |
+| data_hash              | SHA256 hash of the bytecode    |
+| instantiate_permission | Who can instantiate contracts  |
+
+## When to Use
+
+* Listing all uploaded contracts
+* Explorer dashboards
+* Developer discovery tools
+* Auditing chain activity
+
+---
+# 7️⃣ fetchContractsByCode
+
+## Method
+
+```ts
+async fetchContractsByCode(codeId: string)
+```
+
+## CLI Equivalent
+
+```bash
+zigchaind query wasm list-contract-by-code <code-id>
+```
+
+## Description
+
+Lists **all deployed contract addresses** that were instantiated from a specific `code_id`.
+
+Remember:
+
+* Code = blueprint
+* Contracts = deployed instances of that blueprint
+
+This function tells you every contract created from a given code.
+
+## Parameters
+
+| Name   | Type   | Description                           |
+| ------ | ------ | ------------------------------------- |
+| codeId | string | Code ID of the uploaded WASM bytecode |
+
+## Usage Example
+
+```ts
+const contractsByCode = await wasmApi.fetchContractsByCode("38")
+console.dir(contractsByCode, { depth: null })
+```
+## Example Response
+
+```json
+{
+  "contracts": [
+    "zig15jqg0hmp9n06q0as7uk3x9xkwr9k3r7yh4ww2uc0hek8zlryrgmsamk4qg",
+    "zig1r50m5lafnmctat4xpvwdpzqndynlxt2skhr4fhzh76u0qar2y9hqu74u5h",
+    "zig1unc0549k2f0d7mjjyfm94fuz2x53wrx3px0pr55va27grdgmspcqsp4692" ...
+  ]
+}
+```
+## Response Field Explanation
+
+| Field     | Description                                                  |
+| --------- | ------------------------------------------------------------ |
+| contracts | Array of contract addresses instantiated from the given code |
+
+Each entry is a bech32 contract address.
+
+## When to Use
+
+* Explorer dashboards
+* Analytics tools
+* Contract discovery by code version
+---
+# 8️⃣ fetchContractsByCreator
+
+## Method
+
+```ts
+async fetchContractsByCreator(creatorAddress: string)
+```
+
+## CLI Equivalent
+
+```bash
+zigchaind query wasm list-contracts-by-creator <creator-address>
+```
+
+
+
+## Description
+
+Lists all contracts instantiated by a specific creator address.
+
+This answers:
+
+> “Which contracts has this account deployed?”
+
+---
+
+## Parameters
+
+| Name           | Type   | Description                                |
+| -------------- | ------ | ------------------------------------------ |
+| creatorAddress | string | Bech32 account address of contract creator |
+
+---
+
+## Usage Example
+
+```ts
+const contractsByCreator =
+  await wasmApi.fetchContractsByCreator(
+    'zig1v6q4m8u95hwghzskk59a79gk5zymfp263vkyec'
+  )
+
+console.dir(contractsByCreator, { depth: null })
+```
+
+## Example Response
+
+```json
+{
+  "contract_addresses": [
+    "zig1hrpna9v7vs3stzyd4z3xf00676kf78zpe2u5ksvljswn2vnjp3ysyz4xhr",
+    "zig10gqyjt6vxx2pr5e2wv98yd3pu8rpcq5vc3mgd0palylzqq5jkj4slgr3k6",
+    "zig1yel6f5z7rcmdwjzudf9ku0lgcx7suztmk5q7u0mm4tww0eutcgcqqhl6ah"
+  ]
+}
+```
+## Response Field Explanation
+
+| Field              | Description                                          |
+| ------------------ | ---------------------------------------------------- |
+| contract_addresses | Array of contract addresses deployed by this creator |
+
+## When to Use
+
+* Tracking developer deployments
+* Building wallet dashboards
+* Creator-based analytics
+
+---
+
+# 9️⃣ fetchParams
+
+## Method
+
+```ts
+async fetchParams()
+```
+
+## CLI Equivalent
+
+```bash
+zigchaind query wasm params
+```
+
+## Description
+
+Fetches the **WASM module parameters** configured at chain level.
+
+These parameters control:
+
+* Who can upload code
+* Default instantiation permissions
+
+These are governance-controlled settings.
+
+## Parameters
+
+None.
+
+
+## Usage Example
+
+```ts
+const params = await wasmApi.fetchParams()
+console.dir(params, { depth: null })
+```
+
+## Example Response
+
+```json
+{
+  "params": {
+    "code_upload_access": {
+      "permission": "AnyOfAddresses",
+      "addresses": [
+        "zig1cvelykm6dsu90e66ydlnmw934pxem8y8ntjlnr",
+        "zig1qh5h9vel2hqq762r4skrxjnp0nakscx7xe3edf"
+      ]
+    },
+    "instantiate_default_permission": "Everybody"
+  }
+}
+```
+
+## Response Field Explanation
+
+### `code_upload_access`
+
+Controls who can upload WASM code.
+
+| Permission Type | Meaning                         |
+| --------------- | ------------------------------- |
+| Everybody       | Anyone can upload code          |
+| Nobody          | Code upload disabled            |
+| AnyOfAddresses  | Only specific addresses allowed |
+
+### `instantiate_default_permission`
+
+Default permission for instantiating contracts when not explicitly defined.
+
+Possible values:
+
+* `Everybody`
+* `Nobody`
+* `AnyOfAddresses`
+
+## When to Use
+
+* Checking governance configuration
+* Verifying upload permissions
+* Building chain status dashboards
+* Security auditing
+
+---
+
+# 🔟 fetchPinnedCodes
+
+## Method
+
+```ts
+async fetchPinnedCodes()
+```
+
+## CLI Equivalent
+
+```bash
+zigchaind query wasm pinned
+```
+
+## Description
+
+Lists all **pinned code IDs**.
+
+Pinned codes are stored in node memory for faster execution.
+
+Pinning improves performance for frequently used contracts.
+
+## Parameters
+
+None.
+
+## Usage Example
+
+```ts
+const pinned = await wasmApi.fetchPinnedCodes()
+console.dir(pinned, { depth: null })
+```
+
+## Example Response
+
+```json
+{
+  "code_ids": [],
+  "pagination": {
+    "next_key": null,
+    "total": "0"
+  }
+}
+```
+
+---
+
+## Response Field Explanation
+
+| Field      | Description                       |
+| ---------- | --------------------------------- |
+| code_ids   | Array of pinned code IDs          |
+
+
+## When to Use
+
+* Node performance analysis
+* Advanced chain diagnostics
+
+---
+