@zuhaibnoor/zigchain-sdk 1.1.0 → 1.1.1

package/docs/factory.md

@@ -1,7 +1,77 @@
 # Factory Module
 
-The **ChainFactoryApi** allows you to interact with the chain’s token factory module.
-It is used to query **denoms created by admins**, **denom details**, **denom authorizations**, and the **module parameters**.
+## What is the Factory Module?
+
+The **Factory module** is a ZigChain-native token factory that allows any address to **create and manage custom tokens** directly on-chain.
+
+---
+
+## Important Terminology
+
+### Factory Token
+
+A token created through the Factory module. Every factory token has a structured denom format:
+
+```
+coin.<creator-address>.<token-name>
+```
+
+Example:
+```
+coin.zig1020uljv3lamnhlgvetx5tq5gtjl6p7ggvepdeep2fjul6u0pevzsjz270a.neon
+```
+
+This format ensures every factory token is globally unique and its creator is identifiable directly from the denom.
+
+---
+
+### Creator
+
+The address that originally created the token through the Factory module. The creator address is permanently embedded in the token denom and cannot be changed.
+
+---
+
+### Bank Admin
+
+The address authorized to **mint and burn** this token. By default this is the creator, but it can be transferred to another address — for example, a smart contract that controls minting logic.
+
+---
+
+### Metadata Admin
+
+The address authorized to **update the token's metadata** (name, symbol, description, URI). Also defaults to the creator and can be transferred independently of the bank admin.
+
+> Bank admin and metadata admin can be different addresses — this allows separating minting authority from metadata management.
+
+---
+
+### Minting Cap
+
+The maximum amount that can be minted **in a single minting operation**. This is a per-operation limit, not a total supply limit.
+
+```
+minting_cap = '1000000000'
+```
+
+---
+
+### Max Supply
+
+The absolute maximum total supply this token can ever reach. Once `total_minted` reaches `max_supply`, no more tokens can be minted.
+
+```
+max_supply = '1000000000'
+```
+
+---
+
+### Creation Fee
+
+A flat fee in `uzig` that must be paid to create a new factory token. This fee goes to the configured `beneficiary` address.
+
+```
+create_fee_amount = 100000000  →  100 ZIG
+```
 
 ---
 
@@ -16,144 +86,320 @@ import {
 
 const endpoints = getNetworkEndpoints(Network.Testnet)
 const factoryApi = new ChainFactoryApi(endpoints)
+
+const denom = 'coin.zig1020uljv3lamnhlgvetx5tq5gtjl6p7ggvepdeep2fjul6u0pevzsjz270a.neon'
+const denom_admin = 'zig1020uljv3lamnhlgvetx5tq5gtjl6p7ggvepdeep2fjul6u0pevzsjz270a'
 ```
 
 ---
 
-## `fetchParams`
+# 1️⃣ fetchParams
+
+## Method
 
-Fetch the **factory module parameters**.
+```ts
+async fetchParams()
+```
 
-**CLI equivalent**
+## CLI Equivalent
 
 ```bash
 zigchaind query factory params
 ```
 
-**Method**
+## Description
 
-```ts
-fetchParams()
-```
+Fetches the **Factory module parameters** configured at chain level.
 
-**Returns**
+These governance-controlled settings define the cost of creating a new token and where that fee is sent. Anyone who wants to create a factory token must pay the `create_fee_amount` in `create_fee_denom` to the `beneficiary` address.
 
-* `FactoryParamsResponse` – Contains factory-related settings and limits.
+## Parameters
 
-**Example**
+None.
+
+## Usage Example
 
 ```ts
 const params = await factoryApi.fetchParams()
-console.log('Factory params:')
 console.dir(params, { depth: null })
 ```
 
+## Example Response
+
+```json
+{
+  "params": {
+    "create_fee_denom": "uzig",
+    "create_fee_amount": 100000000,
+    "beneficiary": "zig1s3mhkcycpgjj5tdv09ux6qg7hgzcyu6shzsfu0"
+  }
+}
+```
+
+## Response Field Explanation
+
+### `params`
+
+| Field              | Description                                                                     |
+| ------------------ | ------------------------------------------------------------------------------- |
+| create_fee_denom   | Denomination in which the creation fee must be paid (always `uzig`)             |
+| create_fee_amount  | Amount in `uzig` required to create a new token (`100000000` = 100 ZIG)         |
+| beneficiary        | Address that receives the token creation fee                                    |
+
+## When to Use
+
+* Displaying token creation cost to users before they create a token
+* Verifying current fee requirements for factory token creation
+* Governance monitoring for fee parameter changes
+
 ---
 
-## `fetchDenomsByAdmin`
+# 2️⃣ fetchDenomsByAdmin
 
-Fetch all **denoms created by a specific admin address**.
+## Method
+
+```ts
+async fetchDenomsByAdmin(admin: string)
+```
 
-**CLI equivalent**
+## CLI Equivalent
 
 ```bash
 zigchaind query factory denoms-by-admin <admin-address>
 ```
 
-**Method**
+---
 
-```ts
-fetchDenomsByAdmin(admin: string)
-```
+## Description
 
-**Parameters**
+Fetches **all factory tokens created by a specific address**.
 
-* `admin: string` – Address of the admin whose denoms you want to fetch.
+This answers the question: "Which tokens has this address created through the factory module?" It returns the full list of token denoms owned by the given admin, paginated for large collections.
 
-**Returns**
+---
+
+## Parameters
 
-* `DenomsByAdminResponse` – List of denoms created by the admin.
+| Name  | Type   | Description                                             |
+| ----- | ------ | ------------------------------------------------------- |
+| admin | string | Bech32 address of the token creator/admin to query      |
+
+---
 
-**Example**
+## Usage Example
 
 ```ts
-const denoms = await factoryApi.fetchDenomsByAdmin('zig1...adminaddress')
-console.log('Denoms by admin:')
+const denoms = await factoryApi.fetchDenomsByAdmin(denom_admin)
 console.dir(denoms, { depth: null })
 ```
 
+## Example Response
+
+```json
+{
+  "denoms": [
+    "coin.zig1020uljv3lamnhlgvetx5tq5gtjl6p7ggvepdeep2fjul6u0pevzsjz270a.neon"
+  ],
+  "pagination": {
+    "next_key": null,
+    "total": "1"
+  }
+}
+```
+
+## Response Field Explanation
+
+### `denoms`
+
+Array of factory token denoms created by this admin.
+
+| Field  | Description                                                    |
+| ------ | -------------------------------------------------------------- |
+| denoms | List of full token denom strings owned by this admin address   |
+
+Each denom follows the format `coin.<admin-address>.<token-name>`.
+
+### `pagination`
+
+| Field    | Description                                                   |
+| -------- | ------------------------------------------------------------- |
+| next_key | Cursor for next page. `null` if all results are returned      |
+| total    | Total number of factory tokens created by this address        |
+
+## When to Use
+
+* Wallet dashboards showing all tokens a user has created
+* Token discovery tools for a specific creator
+* Auditing which tokens an address controls as admin
+* Building creator profile pages in token explorers
+
 ---
 
-## `fetchDenom`
+# 3️⃣ fetchDenom
 
-Fetch **details of a specific denom**.
+## Method
 
-**CLI equivalent**
+```ts
+async fetchDenom(denom: string)
+```
+
+## CLI Equivalent
 
 ```bash
 zigchaind query factory show-denom <denom>
 ```
 
-**Method**
+## Description
 
-```ts
-fetchDenom(denom: string)
-```
-
-**Parameters**
+Fetches the **full details and lifecycle statistics** of a specific factory token.
 
-* `denom: string` – The denom to query.
+This returns everything about a token — its supply stats (minted, burned, current), supply caps, whether the minting cap can be changed, and the addresses holding admin and metadata authority.
 
-**Returns**
+## Parameters
 
-* `ShowDenomResponse` – Information about the denom, such as creator, admin, and metadata.
+| Name  | Type   | Description                              |
+| ----- | ------ | ---------------------------------------- |
+| denom | string | Full factory token denom to query        |
 
-**Example**
+## Usage Example
 
 ```ts
-const denomInfo = await factoryApi.fetchDenom('uzig')
-console.log('Denom info:')
+const denomInfo = await factoryApi.fetchDenom(denom)
 console.dir(denomInfo, { depth: null })
 ```
 
----
+## Example Response
+
+```json
+{
+  "denom": "coin.zig1020uljv3lamnhlgvetx5tq5gtjl6p7ggvepdeep2fjul6u0pevzsjz270a.neon",
+  "total_minted": "0",
+  "total_supply": "0",
+  "total_burned": "0",
+  "minting_cap": "1000000000",
+  "max_supply": "1000000000",
+  "can_change_minting_cap": true,
+  "creator": "zig1020uljv3lamnhlgvetx5tq5gtjl6p7ggvepdeep2fjul6u0pevzsjz270a",
+  "bank_admin": "zig1020uljv3lamnhlgvetx5tq5gtjl6p7ggvepdeep2fjul6u0pevzsjz270a",
+  "metadata_admin": "zig1020uljv3lamnhlgvetx5tq5gtjl6p7ggvepdeep2fjul6u0pevzsjz270a"
+}
+```
 
-## `fetchDenomAuth`
+## Response Field Explanation
 
-Fetch the **authorization details for a specific denom**.
+| Field                 | Description                                                                        |
+| --------------------- | ---------------------------------------------------------------------------------- |
+| denom                 | Full factory token denom string                                                    |
+| total_minted          | Cumulative amount ever minted since token creation                                 |
+| total_supply          | Current circulating supply (`total_minted - total_burned`)                         |
+| total_burned          | Cumulative amount ever burned since token creation                                 |
+| minting_cap           | Maximum amount mintable in a single minting operation                              |
+| max_supply            | Absolute maximum total supply this token can ever reach                            |
+| can_change_minting_cap | Whether the bank admin can update the `minting_cap` in the future                 |
+| creator               | Address that originally created this token — permanently embedded in the denom     |
+| bank_admin            | Address authorized to mint and burn this token                                     |
+| metadata_admin        | Address authorized to update this token's name, symbol, description, and URI       |
 
-**CLI equivalent**
+### Supply Lifecycle
 
-```bash
-zigchaind query factory denom-auth <denom>
+```
+total_minted - total_burned = total_supply
 ```
 
-**Method**
+| Field         | Meaning                                      |
+| ------------- | -------------------------------------------- |
+| total_minted  | All tokens ever created (cumulative)         |
+| total_burned  | All tokens ever destroyed (cumulative)       |
+| total_supply  | Tokens currently in circulation              |
+
+> In the example, all three supply fields are `0` — this token was created but no minting has occurred yet.
+
+## When to Use
+
+* Verifying a token's supply cap before interacting with it
+* Checking who controls minting and metadata for a token
+* Auditing token admin authority for security reviews
+* Tracking a token's mint/burn history over time
+
+---
+
+# 4️⃣ fetchDenomAuth
+
+## Method
 
 ```ts
-fetchDenomAuth(denom: string)
+async fetchDenomAuth(denom: string)
 ```
 
-**Parameters**
+## CLI Equivalent
+
+```bash
+zigchaind query factory denom-auth <denom>
+```
 
-* `denom: string` – The denom to query.
+## Description
 
-**Returns**
+Fetches the **current authorization configuration** for a factory token — specifically which addresses hold bank admin and metadata admin authority.
 
-* `DenomAuthResponse` – Shows the permissions and authorities associated with the denom.
+This is a lightweight alternative to `fetchDenom` when you only need to check who controls a token, without the full supply statistics.
 
-**Example**
+## Parameters
+
+| Name  | Type   | Description                               |
+| ----- | ------ | ----------------------------------------- |
+| denom | string | Full factory token denom to query         |
+
+## Usage Example
 
 ```ts
-const auth = await factoryApi.fetchDenomAuth('uzig')
-console.log('Denom authorization:')
+const auth = await factoryApi.fetchDenomAuth(denom)
 console.dir(auth, { depth: null })
 ```
 
----
+## Example Response
+
+```json
+{
+  "denom_auth": {
+    "denom": "coin.zig1020uljv3lamnhlgvetx5tq5gtjl6p7ggvepdeep2fjul6u0pevzsjz270a.neon",
+    "bank_admin": "zig1020uljv3lamnhlgvetx5tq5gtjl6p7ggvepdeep2fjul6u0pevzsjz270a",
+    "metadata_admin": "zig1020uljv3lamnhlgvetx5tq5gtjl6p7ggvepdeep2fjul6u0pevzsjz270a"
+  }
+}
+```
+
+## Response Field Explanation
+
+### `denom_auth`
+
+| Field          | Description                                                              |
+| -------------- | ------------------------------------------------------------------------ |
+| denom          | The factory token denom this authorization applies to                    |
+| bank_admin     | Address authorized to mint and burn this token                           |
+| metadata_admin | Address authorized to update this token's metadata                       |
+
+### `fetchDenom` vs `fetchDenomAuth`
+
+| Feature                    | fetchDenom          | fetchDenomAuth              |
+| -------------------------- | ------------------- | --------------------------- |
+| Admin addresses            | ✅ Yes              | ✅ Yes                      |
+| Supply statistics          | ✅ Yes              | ❌ No                       |
+| Supply caps                | ✅ Yes              | ❌ No                       |
+| Creator address            | ✅ Yes              | ❌ No                       |
+| Use case                   | Full token details  | Quick authority check only  |
+
+### Admin Role Separation
+
+| Role           | Can Do                                        | Cannot Do                    |
+| -------------- | --------------------------------------------- | ---------------------------- |
+| bank_admin     | Mint tokens, burn tokens, update minting cap  | Change metadata              |
+| metadata_admin | Update name, symbol, description, URI         | Mint or burn tokens          |
+
+> When both admin roles are the same address (as in the example), the creator has full control over the token. When they differ, minting authority and metadata authority are independently delegated.
+
+## When to Use
 
-## Notes
+* Quick check of who can mint or burn a specific token
+* Verifying whether admin authority has been transferred
+* Security audits of token control structures
 
-* All queries are **read-only** and do not require a wallet.
-* Useful for tracking **admin-created tokens** and their **permissions**.
-* Denom authorizations indicate **who can mint, burn, or manage a token**.