@zuhaibnoor/zigchain-sdk 1.0.3 → 1.1.1

package/docs/block.md

@@ -1,7 +1,87 @@
-# Block Info
+# Block
 
-The **ChainBlockApi** lets you query blockchain blocks and block data.
-It is mainly used to fetch the latest block or retrieve a block at a specific height, including historical state queries.
+## What does this class do?
+
+The **Block** provides access to **raw block data** on ZigChain.
+
+Every block contains the transactions included in it, the header metadata that links it to the rest of the chain, the validator signatures that committed it, and evidence of any misbehaviour. This class lets you retrieve any of that data by height or fetch the current chain tip.
+
+---
+
+## Important Terminology
+
+### Block
+
+A **block** is a sealed, immutable unit of the blockchain. Each block contains an ordered list of transactions, a header with metadata, validator commit signatures, and a link back to the previous block.
+
+---
+
+### Block Height
+
+The sequential position of a block in the chain, starting from `1`. Every new block increments the height by one.
+
+```
+height = 2990050
+```
+
+---
+
+### Block Header
+
+Metadata that describes a block and cryptographically links it to the chain. Contains chain ID, timestamps, hashes, and the proposer address.
+
+---
+
+### Block Hash
+
+A cryptographic hash uniquely identifying a block. Represented as a Base64-encoded string in responses.
+
+```
+hash = 'r08gjOcW8lS6yGkwecQttOBbLiKP9gjBXOx6GO75B1I='
+```
+
+---
+
+### Proposer
+
+The validator that was selected to propose (create) a given block. Identified by their consensus address.
+
+---
+
+### Transactions (`txs`)
+
+Raw Base64-encoded transaction data included in the block.
+
+---
+
+### Last Commit
+
+The set of validator signatures that committed the **previous block**. Each signature entry identifies the validator and confirms they voted for that block.
+
+---
+
+### `block` vs `sdk_block`
+
+The response contains two representations of the same block:
+
+| Field       | Description                                                                 |
+| ----------- | --------------------------------------------------------------------------- |
+| `block`     | Raw Tendermint/CometBFT block — proposer address is raw bytes (Base64)      |
+| `sdk_block` | Cosmos SDK-enhanced block — proposer address is a bech32 `zigvalcons` address |
+
+For most use cases, `sdk_block` is easier to work with because addresses are human-readable.
+
+---
+
+### Block ID Flag
+
+Each validator signature in `last_commit.signatures` includes a `block_id_flag` indicating how that validator voted:
+
+| Flag                    | Meaning                                      |
+| ----------------------- | -------------------------------------------- |
+| `BLOCK_ID_FLAG_COMMIT`  | Validator signed and committed this block    |
+| `BLOCK_ID_FLAG_ABSENT`  | Validator did not participate                |
+| `BLOCK_ID_FLAG_NIL`     | Validator voted nil (no block)               |
 
 ---
 
@@ -20,78 +100,285 @@ const blockApi = new ChainBlockApi(endpoints)
 
 ---
 
-## `getLatestBlock`
+# 1️⃣ getBlockByHeight
+
+## Method
 
-Fetch the **latest committed block** on the chain.
-You can also query how the latest block looked at a specific historical height.
+```ts
+async getBlockByHeight(height: number, atHeight?: number)
+```
 
-**CLI equivalent**
+## CLI Equivalent
 
 ```bash
-zigchaind query block
-zigchaind query block --height <H>
+zigchaind query block --type=height <height>
+zigchaind query block --type=height <height> --height <H>
 ```
 
-**Method**
+---
+
+## Description
+
+Fetches the **full block data for a specific block height**.
+
+Returns the block header, all raw transactions included in the block, validator commit signatures, and evidence. The response includes both the raw Tendermint representation (`block`) and the Cosmos SDK-enhanced representation (`sdk_block`) with human-readable addresses.
+
+The optional `atHeight` parameter allows querying this block as seen from a specific historical chain state — useful for advanced historical state comparisons.
+
+---
+
+## Parameters
+
+| Name     | Type   | Required | Description                                                                          |
+| -------- | ------ | -------- | ------------------------------------------------------------------------------------ |
+| height   | number | ✅ Yes   | The block height to fetch                                                            |
+| atHeight | number | ❌ No    | Query the block from this historical chain state. Omit for latest state.             |
+
+> ⚠️ Using `atHeight` may fail if the node has pruned state at that height.
+
+---
+
+## Usage Example
+
+**Fetch a specific block:**
 
 ```ts
-getLatestBlock(atHeight?: number)
+const block = await blockApi.getBlockByHeight(2990050)
+console.dir(block, { depth: null })
 ```
 
-**Example (latest block)**
+**Fetch a block as seen from a historical chain state:**
 
 ```ts
-const latestBlock = await blockApi.getLatestBlock()
-console.log(latestBlock)
+const block = await blockApi.getBlockByHeight(2990050, 3000000)
+console.dir(block, { depth: null })
 ```
 
-**Example (latest block at a specific height)**
+## Example Response
 
-```ts
-const latestAtHeight = await blockApi.getLatestBlock(120000)
-console.log(latestAtHeight)
+```json
+{
+  "block_id": {
+    "hash": "r08gjOcW8lS6yGkwecQttOBbLiKP9gjBXOx6GO75B1I=",
+    "part_set_header": {
+      "total": 1,
+      "hash": "Bg/0BUwDfIUGfmmzD4aPGEoB9UdkY4JIRnWe8P8t+Hc="
+    }
+  },
+  "block": {
+    "header": {
+      "version": { "block": "11", "app": "0" },
+      "chain_id": "zig-test-2",
+      "height": "2990050",
+      "time": "2025-11-08T22:46:27.230010252Z",
+      "proposer_address": "j1fOFWcZJdBrtOxW6WFT42/v65k="
+    },
+    "data": {
+      "txs": [
+        "CvADCtYDCiQvY29zbXdhc20ud2FzbS52MS5Nc2dFeGVjdXRlQ29udHJhY3QS..."
+      ]
+    },
+    "evidence": { "evidence": [] },
+    "last_commit": {
+      "height": "2990049",
+      "round": 0,
+      "signatures": [
+        {
+          "block_id_flag": "BLOCK_ID_FLAG_COMMIT",
+          "validator_address": "pfDCXVd4xiHCDhc16B4iUyulD7M=",
+          "timestamp": "2025-11-08T22:46:27.230010252Z",
+          "signature": "R9qDAUn+aLgeZ0l5fAc2..."
+        }
+      ]
+    }
+  },
+  "sdk_block": {
+    "header": {
+      "chain_id": "zig-test-2",
+      "height": "2990050",
+      "time": "2025-11-08T22:46:27.230010252Z",
+      "proposer_address": "zigvalcons13atuu9t8ryjaq6a5a3twjc2nudh7l6uemvgmes"
+    }
+  }
+}
 ```
 
+## Response Field Explanation
+
+### `block_id`
+
+| Field                    | Description                                          |
+| ------------------------ | ---------------------------------------------------- |
+| hash                     | Base64-encoded hash uniquely identifying this block  |
+| part_set_header.total    | Number of block parts (always `1` for normal blocks) |
+| part_set_header.hash     | Hash of the block part set                           |
+
+### `block.header` / `sdk_block.header`
+
+| Field                | Description                                                           |
+| -------------------- | --------------------------------------------------------------------- |
+| version.block        | CometBFT protocol version                                             |
+| chain_id             | Network identifier (e.g. `zig-test-2`)                                |
+| height               | This block's height                                                   |
+| time                 | Timestamp when the block was committed                       |
+| last_block_id.hash   | Hash of the previous block — links the chain together                 |
+| last_commit_hash     | Hash of the previous block's commit signatures                        |
+| data_hash            | Hash of the transactions in this block                                |
+| validators_hash      | Hash of the current validator set                                     |
+| next_validators_hash | Hash of the next block's validator set                                |
+| app_hash             | Application state hash after all transactions were applied            |
+| last_results_hash    | Hash of the previous block's transaction results                      |
+| evidence_hash        | Hash of any misbehaviour evidence included in this block              |
+| proposer_address     | In `block`: raw Base64. In `sdk_block`: bech32 `zigvalcons` address   |
+
+### `block.data`
+
+| Field | Description                                                          |
+| ----- | -------------------------------------------------------------------- |
+| txs   | Array of raw Base64-encoded transactions included in this block      |
+
+> An empty `txs` array means the block contained no transactions (an empty block).
+
+### `block.last_commit`
+
+| Field      | Description                                              |
+| ---------- | -------------------------------------------------------- |
+| height     | Height of the block this commit finalised (current - 1) |
+| round      | Consensus round in which this block was committed        |
+| block_id   | Hash reference to the previous block                     |
+| signatures | Array of validator commit signatures                     |
+
+Each signature entry:
+
+| Field             | Description                                             |
+| ----------------- | ------------------------------------------------------- |
+| block_id_flag     | Validator's vote type (`COMMIT`, `ABSENT`, or `NIL`)    |
+| validator_address | Base64-encoded validator consensus address              |
+| timestamp         | When the validator signed                               |
+| signature         | Base64-encoded cryptographic signature                  |
+
+## When to Use
+
+* Fetching full block contents for a known height
+* Verifying which transactions were included in a block
+* Checking which validators signed a specific block
+* Building block explorer block detail pages
+* Auditing chain state at a specific point in time
+
 ---
 
-## `getBlockByHeight`
+# 2️⃣ getLatestBlock
+
+## Method
 
-Query a **specific block by its height**.
-Optionally, you can query the result from a historical chain state.
+```ts
+async getLatestBlock(atHeight?: number)
+```
 
-**CLI equivalent**
+## CLI Equivalent
 
 ```bash
-zigchaind query block --type=height <height>
-zigchaind query block --type=height <height> --height <H>
+zigchaind query block
+zigchaind query block --height <H>
 ```
 
-**Method**
+---
+
+## Description
+
+Fetches the **most recently committed block** on the chain.
+
+This is the equivalent of checking the current chain tip — it tells you the latest block height, when it was produced, how many transactions it contained, and which validator proposed it.
+
+The optional `atHeight` parameter is an advanced option that queries the latest block as seen from a specific historical chain state.
+
+---
+
+## Parameters
+
+| Name     | Type   | Required | Description                                                                  |
+| -------- | ------ | -------- | ---------------------------------------------------------------------------- |
+| atHeight | number | ❌ No    | Query from this historical chain state. Omit to query current latest block.  |
+
+---
+
+## Usage Example
+
+**Fetch the current latest block:**
 
 ```ts
-getBlockByHeight(height: number, atHeight?: number)
+const latestBlock = await blockApi.getLatestBlock()
+console.dir(latestBlock, { depth: null })
 ```
 
-**Example (specific block)**
+**Fetch the latest block as seen from a historical state:**
 
 ```ts
-const block = await blockApi.getBlockByHeight(150000)
-console.log(block)
+const latestAtHeight = await blockApi.getLatestBlock(3000000)
+console.dir(latestAtHeight, { depth: null })
 ```
 
-**Example (block queried at historical height)**
+## Example Response
 
-```ts
-const blockAtHeight = await blockApi.getBlockByHeight(150000, 160000)
-console.log(blockAtHeight)
+```json
+{
+  "block_id": {
+    "hash": "mDilLWqtCONHxux337yRYE8VgZN84E/2I4OQ2av0ysA=",
+    "part_set_header": { "total": 1, "hash": "X3COeE3KT8GuDahnnLUXJdabG++b68n+ELxm3OJ1P1g=" }
+  },
+  "block": {
+    "header": {
+      "chain_id": "zig-test-2",
+      "height": "4600308",
+      "time": "2026-02-21T05:56:32.495366040Z",
+      "proposer_address": "kf+/IYvD2VICszA7kymoXAyX+y4="
+    },
+    "data": { "txs": [] },
+    "evidence": { "evidence": [] },
+    "last_commit": {
+      "height": "4600307",
+      "round": 0,
+      "signatures": [
+        {
+          "block_id_flag": "BLOCK_ID_FLAG_COMMIT",
+          "validator_address": "pfDCXVd4xiHCDhc16B4iUyulD7M=",
+          "timestamp": "2026-02-21T05:56:32.495335987Z",
+          "signature": "YXHcv+uwO2/qPktnHfSWjCnQ6CU4..."
+        }
+      ]
+    }
+  },
+  "sdk_block": {
+    "header": {
+      "chain_id": "zig-test-2",
+      "height": "4600308",
+      "time": "2026-02-21T05:56:32.495366040Z",
+      "proposer_address": "zigvalcons1j8lm7gvtc0v4yq4nxqaex2dgtsxf07ewjvh3rh"
+    },
+    "data": { "txs": [] }
+  }
+}
 ```
 
----
+The response structure is identical to `getBlockByHeight` — refer to that section for the full field-by-field breakdown.
+
+### Quick Reads from the Latest Block
+
+Here are the most commonly needed values and where to find them:
+
+| Information needed          | Field path                              |
+| --------------------------- | --------------------------------------- |
+| Current block height        | `sdk_block.header.height`               |
+| Block timestamp             | `sdk_block.header.time`                 |
+| Proposing validator address | `sdk_block.header.proposer_address`     |
+| Number of transactions      | `sdk_block.data.txs.length`             |
+| Chain ID                    | `sdk_block.header.chain_id`             |
 
-## Notes
+## When to Use
 
-* Block queries are **read-only** and do not require any wallet.
-* Querying at historical heights may fail if the node has pruned old data.
-* LCD does **not** support querying blocks by hash (height-based queries only).
+* Getting the current block height and chain tip
+* Checking whether the chain is live and producing blocks
+* Syncing an indexer to the latest state
+* Displaying live block information in dashboards or explorers
 
 ---

package/docs/circuit.md

@@ -1,7 +1,50 @@
 # Circuit Module
 
-The **ChainCircuitApi** lets you query **account-level transaction permissions** for the circuit module.
-It is mainly used to check which accounts are **blocked or restricted** from sending transactions on the chain.
+## What is the Circuit Module?
+
+The **Circuit module** provides a **transaction permission and circuit breaker** system for ZigChain.
+
+It allows designated super-admin accounts to selectively disable specific message types on the chain — acting as an emergency brake. This is a governance and safety mechanism, not something that affects normal users under typical chain operation.
+
+---
+
+## Important Terminology
+
+### Circuit Breaker
+
+A **circuit breaker** is a safety mechanism that allows authorized accounts to disable specific transaction types on the chain without requiring a full governance vote. This is used in emergency situations — for example, if a vulnerability is discovered in a particular module.
+
+---
+
+### Permission Level
+
+Each account in the circuit module is assigned a **permission level** that defines what authority they have over circuit controls.
+
+| Level               | Description                                                                 |
+| ------------------- | --------------------------------------------------------------------------- |
+| `LEVEL_NONE_UNSPECIFIED` | No circuit permissions — standard account                             |
+| `LEVEL_SOME_MSGS`   | Can disable a specific limited set of message types only                    |
+| `LEVEL_ALL_MSGS`    | Can disable any message type on the chain                                   |
+| `LEVEL_SUPER_ADMIN` | Full control — can disable messages and grant/revoke permissions to others  |
+
+---
+
+### Limit Type URLs
+
+When a permission level is `LEVEL_SOME_MSGS`, the `limit_type_urls` field specifies exactly which message types that account is authorized to circuit-break.
+
+An empty `limit_type_urls` combined with `LEVEL_SUPER_ADMIN` means the account has **unrestricted** circuit breaker authority — no specific limits apply.
+
+Example of a type URL:
+```
+/cosmos.bank.v1beta1.MsgSend
+```
+
+---
+
+### Disabled List
+
+The set of message type URLs that are currently disabled (circuit-broken) on the chain. Any transaction containing a disabled message type will be rejected until the circuit is reset.
 
 ---
 
@@ -16,78 +59,164 @@ import {
 
 const endpoints = getNetworkEndpoints(Network.Testnet)
 const circuitApi = new ChainCircuitApi(endpoints)
+
+const address = 'zig15yk64u7zc9g9k2yr2wmzeva5qgwxps6y8c2amk'
 ```
 
 ---
 
-## `getAccountPermissions`
+# 1️⃣ getAccountPermissions
 
-Fetch the **circuit permissions for a specific account**.
+## Method
+
+```ts
+async getAccountPermissions(address: string)
+```
 
-**CLI equivalent**
+## CLI Equivalent
 
 ```bash
 zigchaind query circuit account <address>
 ```
 
-**Method**
+## Description
+
+Fetches the **circuit breaker permissions** assigned to a specific account.
+
+This tells you what level of circuit authority an account holds and, if applicable, which message types they are restricted to controlling. Most regular accounts will have no circuit permissions at all — only specifically designated addresses will appear in the circuit module with elevated levels.
+
+## Parameters
+
+| Name    | Type   | Description                                           |
+| ------- | ------ | ----------------------------------------------------- |
+| address | string | Bech32 address of the account to query permissions for |
+
+## Usage Example
 
 ```ts
-getAccountPermissions(address: string)
+const account = await circuitApi.getAccountPermissions(address)
+console.dir(account, { depth: null })
 ```
 
-**Parameters**
+## Example Response
 
-* `address: string` – The account address to query.
+```json
+{
+  "permission": {
+    "level": "LEVEL_SUPER_ADMIN",
+    "limit_type_urls": []
+  }
+}
+```
 
-**Returns**
+## Response Field Explanation
 
-* `CircuitAccountResponse` – Contains whether the account is blocked or restricted.
+### `permission`
 
-**Example**
+| Field            | Description                                                                       |
+| ---------------- | --------------------------------------------------------------------------------- |
+| level            | Permission level assigned to this account                                         |
+| limit_type_urls  | Specific message type URLs this account can circuit-break. Empty if unrestricted  |
 
-```ts
-const address = 'zig1svkn4sqrlz8r6krq96ty6kze54n2ec03u0vat5'
-const permissions = await circuitApi.getAccountPermissions(address)
-console.log(`Circuit permissions for ${address}:`)
-console.dir(permissions, { depth: null })
-```
+### Permission Level Values
+
+| Value                    | Meaning                                                              |
+| ------------------------ | -------------------------------------------------------------------- |
+| `LEVEL_NONE_UNSPECIFIED` | No circuit permissions                                               |
+| `LEVEL_SOME_MSGS`        | Can only circuit-break the specific types listed in `limit_type_urls` |
+| `LEVEL_ALL_MSGS`         | Can circuit-break any message type                                   |
+| `LEVEL_SUPER_ADMIN`      | Full authority — can circuit-break messages and manage permissions   |
+
+> In the example above, `LEVEL_SUPER_ADMIN` with an empty `limit_type_urls` means this account has unrestricted circuit breaker authority over the entire chain.
+
+## When to Use
+
+* Verifying whether a specific address holds circuit breaker authority
+* Auditing which accounts can perform emergency interventions
+* Security reviews of chain admin key holders
+* Building governance monitoring tools
 
 ---
 
-## `getAllAccountPermissions`
+# 2️⃣ getAllAccountPermissions
+
+## Method
 
-Fetch **all accounts with circuit restrictions or permissions**.
+```ts
+async getAllAccountPermissions()
+```
 
-**CLI equivalent**
+## CLI Equivalent
 
 ```bash
 zigchaind query circuit accounts
 ```
 
-**Method**
+## Description
 
-```ts
-getAllAccountPermissions()
-```
+Fetches **all accounts** that have been assigned circuit breaker permissions on the chain.
+
+On ZigChain testnet, only one account currently holds circuit permissions (`LEVEL_SUPER_ADMIN`). This reflects the typical setup where circuit authority is granted to a small number of trusted admin addresses for emergency use.
 
-**Returns**
+## Parameters
 
-* `CircuitAccountsResponse` – Contains a list of all accounts and their circuit permission status.
+None.
 
-**Example**
+## Usage Example
 
 ```ts
-const allPermissions = await circuitApi.getAllAccountPermissions()
-console.log('All accounts with circuit permissions:')
-console.dir(allPermissions, { depth: null })
+const accounts = await circuitApi.getAllAccountPermissions()
+console.dir(accounts, { depth: null })
 ```
 
----
+## Example Response
+
+```json
+{
+  "accounts": [
+    {
+      "address": "zig15yk64u7zc9g9k2yr2wmzeva5qgwxps6y8c2amk",
+      "permissions": {
+        "level": "LEVEL_SUPER_ADMIN",
+        "limit_type_urls": []
+      }
+    }
+  ],
+  "pagination": {
+    "next_key": null,
+    "total": "1"
+  }
+}
+```
+
+## Response Field Explanation
 
-## Notes
+### `accounts`
 
-* Useful for **auditing and monitoring** restricted accounts.
-* The `getAllAccountPermissions` method may return large datasets if many accounts are restricted.
+Array of all accounts holding circuit breaker permissions.
 
+Each entry contains:
 
+| Field                       | Description                                                              |
+| --------------------------- | ------------------------------------------------------------------------ |
+| address                     | Bech32 address of the account with circuit permissions                   |
+| permissions.level           | Permission level assigned to this account                                |
+| permissions.limit_type_urls | Message types this account can control. Empty if unrestricted            |
+
+### `pagination`
+
+| Field    | Description                                                          |
+| -------- | -------------------------------------------------------------------- |
+| next_key | Cursor for next page. `null` if all results are returned             |
+| total    | Total number of accounts with circuit permissions on the chain       |
+
+> On ZigChain testnet, `total` is `"1"` — only one super admin account exists. A healthy, normally-operating chain will typically have a very small number of circuit-permissioned accounts.
+
+## When to Use
+
+* Full audit of all accounts with emergency chain intervention authority
+* Verifying the complete set of circuit admins
+* Chain governance and security dashboards
+* Monitoring for unexpected changes to the circuit permission list
+
+---