@zuhaibnoor/zigchain-sdk 1.0.2 → 1.1.0

package/docs/auth.md

@@ -0,0 +1,555 @@
+# Auth Module
+
+## What is the Auth Module?
+
+The **Auth module** is a core Cosmos SDK module responsible for managing **accounts** on the blockchain.
+
+In **ZigChain**, every address that holds tokens, signs transactions, or interacts with the chain is backed by an account managed by this module.
+
+---
+
+## Important Terminology
+
+### Account
+
+An **Account** is an on-chain entity identified by a unique bech32 address. It tracks the public key, sequence number, and account number required to authorize transactions.
+
+There are different account types:
+
+| Type          | Description                                      |
+| ------------- | ------------------------------------------------ |
+| BaseAccount   | Standard user account                            |
+| ModuleAccount | System account owned by a chain module (e.g. staking, gov) |
+
+---
+
+### Account Number
+
+A unique numeric ID assigned to an account when it is first seen on-chain.
+
+Example:
+```
+account_number = 138553
+```
+
+---
+
+### Sequence
+
+A counter that increments with every transaction signed by an account. Used to prevent replay attacks.
+
+Example:
+```
+sequence = 115309
+```
+
+> Both `account_number` and `sequence` are **required** when building and signing transactions.
+
+---
+
+### Public Key
+
+The cryptographic public key associated with an account. Used to verify transaction signatures.
+
+---
+
+### Bech32 Prefix
+
+The human-readable prefix prepended to all addresses on a chain. ZigChain uses `zig` as its prefix.
+
+Example:
+```
+zig1svkn4sqrlz8r6krq96ty6kze54n2ec03u0vat5
+```
+
+---
+
+## Setup
+
+```ts
+import {
+  ChainAuthApi,
+  getNetworkEndpoints,
+  Network,
+} from '@zuhaibnoor/zigchain-sdk'
+
+const endpoints = getNetworkEndpoints(Network.Testnet)
+const authApi = new ChainAuthApi(endpoints)
+
+const address = 'zig1svkn4sqrlz8r6krq96ty6kze54n2ec03u0vat5'
+```
+
+---
+
+# 1️⃣ fetchAccount
+
+## Method
+
+```ts
+async fetchAccount(address: string)
+```
+
+## CLI Equivalent
+
+```bash
+zigchaind query auth account <address>
+```
+
+## Description
+
+Fetches the **full account object** for a given address.
+
+This returns the complete account representation, which varies depending on account type. For a standard user wallet this will be a `BaseAccount`. For chain-owned system addresses it may be a `ModuleAccount`.
+
+This is the most complete account query available.
+
+## Parameters
+
+| Name    | Type   | Description                        |
+| ------- | ------ | ---------------------------------- |
+| address | string | Bech32 address of the account to query |
+
+## Usage Example
+
+```ts
+const account = await authApi.fetchAccount(address)
+console.dir(account, { depth: null })
+```
+
+## Example Response
+
+```json
+{
+  "account": {
+    "@type": "/cosmos.auth.v1beta1.BaseAccount",
+    "address": "zig1svkn4sqrlz8r6krq96ty6kze54n2ec03u0vat5",
+    "pub_key": {
+      "@type": "/cosmos.crypto.secp256k1.PubKey",
+      "key": "Ax6bvKIvU8eViWA6rmn6c/fyYiyuj3/tyiJt2gzv/UDP"
+    },
+    "account_number": "138553",
+    "sequence": "115309"
+  }
+}
+```
+
+## Response Field Explanation
+
+### `account`
+
+The full account object.
+
+| Field          | Description                                                |
+| -------------- | ---------------------------------------------------------- |
+| @type          | Protobuf type URL indicating the account type              |
+| address        | Bech32 address of the account                              |
+| pub_key.@type  | Cryptographic key type (secp256k1 for standard accounts)   |
+| pub_key.key    | Base64-encoded public key                                  |
+| account_number | Unique chain-assigned ID for this account                  |
+| sequence       | Number of transactions sent — increments with each tx      |
+
+> ⚠️ `pub_key` may be `null` if the account exists on-chain but has never signed a transaction.
+
+## When to Use
+
+* Inspecting the full account object and type
+* Checking account type (`BaseAccount` vs `ModuleAccount`)
+* Block explorers displaying full account details
+* Debugging account state
+
+---
+
+# 2️⃣ fetchAccountInfo
+
+## Method
+
+```ts
+async fetchAccountInfo(address: string)
+```
+
+## CLI Equivalent
+
+```bash
+zigchaind query auth account-info <address>
+```
+
+## Description
+
+Fetches **lightweight account info** — only the fields required for **signing transactions**.
+
+Unlike `fetchAccount`, this endpoint returns a consistent, type-agnostic response regardless of the underlying account type. This makes it the preferred query when building and signing transactions.
+
+Returns: address, public key, account number, and sequence.
+
+
+## Parameters
+
+| Name    | Type   | Description                            |
+| ------- | ------ | -------------------------------------- |
+| address | string | Bech32 address of the account to query |
+
+
+## Usage Example
+
+```ts
+const info = await authApi.fetchAccountInfo(address)
+console.dir(info, { depth: null })
+```
+
+## Example Response
+
+```json
+{
+  "info": {
+    "address": "zig1svkn4sqrlz8r6krq96ty6kze54n2ec03u0vat5",
+    "pub_key": {
+      "@type": "/cosmos.crypto.secp256k1.PubKey",
+      "key": "Ax6bvKIvU8eViWA6rmn6c/fyYiyuj3/tyiJt2gzv/UDP"
+    },
+    "account_number": "138553",
+    "sequence": "115309"
+  }
+}
+```
+
+## Response Field Explanation
+
+### `info`
+
+| Field          | Description                                           |
+| -------------- | ----------------------------------------------------- |
+| address        | Bech32 address of the account                         |
+| pub_key.@type  | Cryptographic key type                                |
+| pub_key.key    | Base64-encoded public key                             |
+| account_number | Required for tx signing — unique ID for this account  |
+| sequence       | Required for tx signing — increments with each tx     |
+
+### `fetchAccountInfo` vs `fetchAccount`
+
+| Feature              | fetchAccount         | fetchAccountInfo       |
+| -------------------- | -------------------- | ---------------------- |
+| Returns account type | ✅ Yes               | ❌ No                  |
+| Ideal for tx signing | ⚠️ Works but verbose | ✅ Preferred            |
+| Response size        | Larger               | Minimal                |
+
+## When to Use
+
+* Building and signing transactions (primary use case)
+* Fetching `account_number` and `sequence` for tx construction
+* Wallet implementations
+* Any scenario where only signing data is needed
+
+---
+
+# 3️⃣ fetchBech32Prefix
+
+## Method
+
+```ts
+async fetchBech32Prefix()
+```
+
+## CLI Equivalent
+
+```bash
+zigchaind query auth bech32-prefix
+```
+
+## Description
+
+Fetches the **Bech32 address prefix** configured for the chain.
+
+This prefix is prepended to all addresses on the network. For ZigChain, this will always be `zig`.
+
+This is useful when you need to programmatically verify that an address belongs to ZigChain, or when building tools that support multiple chains.
+
+## Parameters
+
+None.
+
+
+## Usage Example
+
+```ts
+const prefix = await authApi.fetchBech32Prefix()
+console.dir(prefix, { depth: null })
+```
+
+## Example Response
+
+```json
+{
+  "bech32_prefix": "zig"
+}
+```
+
+## Response Field Explanation
+
+| Field         | Description                              |
+| ------------- | ---------------------------------------- |
+| bech32_prefix | The human-readable prefix for addresses on this chain |
+
+## When to Use
+
+* Validating that an address belongs to ZigChain
+* Multi-chain tools that need to identify the network
+
+---
+
+# 4️⃣ fetchModuleAccounts
+
+## Method
+
+```ts
+async fetchModuleAccounts()
+```
+
+## CLI Equivalent
+
+```bash
+zigchaind query auth module-accounts
+```
+
+## Description
+
+Fetches **all module accounts** registered on the chain.
+
+Module accounts are special system-owned accounts that belong to chain modules (e.g. `gov`, `staking`, `mint`). Unlike user accounts, they are not controlled by a private key — they are controlled programmatically by their respective modules.
+
+Each module account has a set of **permissions** that define what it is allowed to do with tokens.
+
+## Parameters
+
+None.
+
+## Usage Example
+
+```ts
+const modAccounts = await authApi.fetchModuleAccounts()
+console.dir(modAccounts, { depth: null })
+```
+
+## Example Response
+
+```json
+{
+  "accounts": [
+    {
+      "@type": "/cosmos.auth.v1beta1.ModuleAccount",
+      "base_account": {
+        "address": "zig1fl48vsnmsdzcv85q5d2q4z5ajdha8yu353vaml",
+        "pub_key": null,
+        "account_number": "17",
+        "sequence": "0"
+      },
+      "name": "bonded_tokens_pool",
+      "permissions": ["burner", "staking"]
+    },
+    {
+      "@type": "/cosmos.auth.v1beta1.ModuleAccount",
+      "base_account": {
+        "address": "zig10d07y265gmmuvt4z0w9aw880jnsr700jmgkh5m",
+        "pub_key": null,
+        "account_number": "19",
+        "sequence": "0"
+      },
+      "name": "gov",
+      "permissions": ["burner"]
+    }
+  ]
+}
+```
+
+## Response Field Explanation
+
+### `accounts`
+
+Array of all module accounts on the chain.
+
+Each entry contains:
+
+| Field                       | Description                                              |
+| --------------------------- | -------------------------------------------------------- |
+| @type                       | Always `/cosmos.auth.v1beta1.ModuleAccount`              |
+| base_account.address        | Bech32 address of the module account                     |
+| base_account.pub_key        | Always `null` — module accounts have no private key      |
+| base_account.account_number | Chain-assigned account ID                                |
+| base_account.sequence       | Always `0` — module accounts never sign transactions     |
+| name                        | Unique identifier for the module (e.g. `gov`, `staking`) |
+| permissions                 | List of token operation permissions granted to this module |
+
+### Module Permission Types
+
+| Permission | Meaning                                          |
+| ---------- | ------------------------------------------------ |
+| minter     | Can mint (create) new tokens                     |
+| burner     | Can burn (destroy) tokens                        |
+| staking    | Can interact with staked/bonded token operations |
+
+## When to Use
+
+* Inspecting all system accounts on the chain
+* Understanding which modules have minting or burning capabilities
+* Block explorer chain overview pages
+* Security auditing of module permissions
+
+---
+
+# 5️⃣ fetchAccountsByModule
+
+## Method
+
+```ts
+async fetchAccountsByModule(moduleName: string)
+```
+
+## CLI Equivalent
+
+```bash
+zigchaind query auth module-account <module_name>
+```
+
+## Description
+
+Fetches the **module account details** for a single, specific module by name.
+
+Use this when you need the address, account number, or permissions of one particular module rather than fetching all of them with `fetchModuleAccounts`.
+
+## Parameters
+
+| Name       | Type   | Description                                                    |
+| ---------- | ------ | -------------------------------------------------------------- |
+| moduleName | string | Name of the module (e.g. `gov`, `staking` etc) |
+
+
+## Usage Example
+
+```ts
+const govModule = await authApi.fetchAccountsByModule('gov')
+console.dir(govModule, { depth: null })
+```
+
+## Example Response
+
+```json
+{
+  "account": {
+    "@type": "/cosmos.auth.v1beta1.ModuleAccount",
+    "base_account": {
+      "address": "zig10d07y265gmmuvt4z0w9aw880jnsr700jmgkh5m",
+      "pub_key": null,
+      "account_number": "19",
+      "sequence": "0"
+    },
+    "name": "gov",
+    "permissions": ["burner"]
+  }
+}
+```
+
+## Response Field Explanation
+
+### `account`
+
+| Field                       | Description                                        |
+| --------------------------- | -------------------------------------------------- |
+| @type                       | Always `/cosmos.auth.v1beta1.ModuleAccount`        |
+| base_account.address        | Bech32 address of this module account              |
+| base_account.pub_key        | Always `null` — no private key for module accounts |
+| base_account.account_number | Chain-assigned ID for this account                 |
+| base_account.sequence       | Always `0`                                         |
+| name                        | The module name as registered on-chain             |
+| permissions                 | Token operation permissions for this module        |
+
+## When to Use
+
+* Checking permissions of a particular module
+* Verifying module account existence
+* Building tools that interact with module-controlled addresses (e.g. tracking gov deposit pool balances)
+
+---
+
+# 6️⃣ fetchAuthParams
+
+## Method
+
+```ts
+async fetchAuthParams(height?: number)
+```
+
+## CLI Equivalent
+
+```bash
+zigchaind query auth params
+zigchaind query auth params --height <H>
+```
+
+## Description
+
+Fetches the **Auth module parameters** configured at chain level.
+
+These parameters govern transaction validation rules — such as how large a memo can be, how many signatures a transaction can carry, and the computational cost of signature verification.
+
+These are governance-controlled settings and can be updated via on-chain proposals.
+
+Supports querying parameters at a **specific block height** for historical state.
+
+## Parameters
+
+| Name   | Type   | Required | Description                                                       |
+| ------ | ------ | -------- | ----------------------------------------------------------------- |
+| height | number | ❌ No    | Block height to query at. Omit for latest state. |
+
+## Usage Example
+
+**Latest state:**
+
+```ts
+const params = await authApi.fetchAuthParams()
+console.dir(params, { depth: null })
+```
+
+**Historical state at a specific block height:**
+
+```ts
+const paramsAtHeight = await authApi.fetchAuthParams(500000)
+console.dir(paramsAtHeight, { depth: null })
+```
+
+## Example Response
+
+```json
+{
+  "params": {
+    "max_memo_characters": "256",
+    "tx_sig_limit": "7",
+    "tx_size_cost_per_byte": "10",
+    "sig_verify_cost_ed25519": "590",
+    "sig_verify_cost_secp256k1": "1000"
+  }
+}
+```
+
+## Response Field Explanation
+
+### `params`
+
+| Field                    | Description                                                              |
+| ------------------------ | ------------------------------------------------------------------------ |
+| max_memo_characters      | Maximum number of characters allowed in a transaction memo               |
+| tx_sig_limit             | Maximum number of signatures allowed per transaction                     |
+| tx_size_cost_per_byte    | Gas cost charged per byte of transaction size                            |
+| sig_verify_cost_ed25519  | Gas cost for verifying an Ed25519 signature                              |
+| sig_verify_cost_secp256k1 | Gas cost for verifying a secp256k1 signature (standard user transactions) |
+
+> On ZigChain, most user transactions use `secp256k1` signatures, so `sig_verify_cost_secp256k1` is the most commonly applied verification cost.
+
+## When to Use
+
+* Validating memo length before broadcasting a transaction
+* Estimating gas costs for multi-signature transactions
+* Auditing chain governance parameters
+* Building chain configuration dashboards
+
+---
+