@zuhaibnoor/zigchain-sdk 1.0.2 → 1.1.0

package/docs/block-results.md

@@ -0,0 +1,371 @@
+# Block Results
+
+## What are the Block Results?
+
+The **Block Results** provides access to the **execution results of a specific block** on ZigChain.
+
+While other modules query the current state of the chain (balances, accounts, validators), the Block Results module lets you look back at what actually *happened* in a given block — every transaction that was processed, every event emitted, and every state change that occurred.
+
+> ⚠️ **Important:** This module uses the **RPC endpoint**, not the LCD endpoint used by all other modules. This is handled automatically by the SDK — no extra configuration is needed.
+
+---
+
+## Important Terminology
+
+### Block
+
+A **block** is a unit of the blockchain containing an ordered set of transactions. Each block is identified by a unique sequential **height**.
+
+---
+
+### Block Height
+
+The position of a block in the chain, starting from `1`. Every new block increments the height by `1`.
+
+Example:
+```
+height = 2990050
+```
+
+---
+
+### Transaction Result (`txs_results`)
+
+The execution outcome of each transaction included in the block.
+
+Each result includes:
+
+- Whether the transaction **succeeded or failed** (`code`)
+- **Gas** consumed vs requested
+- **Events** emitted during execution
+- An **error log** if the transaction failed
+
+---
+
+### Transaction Code
+
+A numeric result code indicating transaction success or failure.
+
+| Code | Meaning |
+| ---- | ------- |
+| `0`  | Success — transaction executed without errors |
+| Any non-zero | Failure — see `log` for the error message |
+
+---
+
+### Events
+
+**Events** are structured log entries emitted during block and transaction execution. They are the primary way to track on-chain activity such as token transfers, contract executions, reward distributions, and fee payments.
+
+Each event has a `type` and an array of `attributes` (key-value pairs).
+
+---
+
+### Common Event Types
+
+| Event Type          | Description                                          |
+| ------------------- | ---------------------------------------------------- |
+| `coin_spent`        | Tokens were debited from an address                  |
+| `coin_received`     | Tokens were credited to an address                   |
+| `transfer`          | A token transfer occurred between addresses          |
+| `message`           | A message was processed (action, sender, etc.)       |
+| `tx`                | Transaction-level metadata (fee, signature, acc_seq) |
+| `execute`           | A CosmWasm contract was executed                     |
+| `wasm`              | Events emitted from within a CosmWasm contract       |
+| `coinbase`          | New tokens were minted                               |
+| `mint`              | Block-level inflation minting details                |
+| `commission`        | Validator commission was distributed                 |
+| `rewards`           | Staking rewards were distributed to validators       |
+| `denom_minted_and_sent` | Factory module minted and transferred tokens     |
+
+---
+
+### Finalize Block Events (`finalize_block_events`)
+
+Events that occur at the **block level** rather than within individual transactions. These cover system-level operations that happen automatically each block, such as:
+
+- Inflation minting
+- Fee collection
+- Staking reward and commission distribution to validators
+
+---
+
+### Gas
+
+| Field        | Description                                                  |
+| ------------ | ------------------------------------------------------------ |
+| `gas_wanted` | Maximum gas the transaction sender authorized                |
+| `gas_used`   | Actual gas consumed during execution                         |
+
+> If `gas_used` approaches `gas_wanted`, the transaction may have been close to running out of gas.
+
+---
+
+## Setup
+
+```ts
+import {
+  ChainBlockResultsApi,
+  getNetworkEndpoints,
+  Network,
+} from '@zuhaibnoor/zigchain-sdk'
+
+const endpoints = getNetworkEndpoints(Network.Testnet)
+const blockResultsApi = new ChainBlockResultsApi(endpoints)
+```
+
+---
+
+# 1️⃣ fetchBlockResults
+
+## Method
+
+```ts
+async fetchBlockResults(height: number)
+```
+
+## CLI Equivalent
+
+```bash
+zigchaind query block-results <height>
+```
+
+---
+
+## Description
+
+Fetches the **full execution results for a specific block** by height.
+
+This includes every transaction result processed in that block, all events emitted at the transaction level, all events emitted at the block level (finalize block events), validator updates, and consensus parameter updates.
+
+This is the most detailed view available for what happened at a specific point in chain history.
+
+> ⚠️ This function queries the **RPC endpoint** internally, unlike all other SDK modules which use the LCD endpoint.
+
+---
+
+## Parameters
+
+| Name   | Type   | Required | Description                        |
+| ------ | ------ | -------- | ---------------------------------- |
+| height | number | ✅ Yes   | Block height to fetch results for  |
+
+---
+
+## Usage Example
+
+```ts
+const results = await blockResultsApi.fetchBlockResults(2990050)
+console.dir(results, { depth: null })
+```
+
+## Example Response
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": -1,
+  "result": {
+    "height": "2990050",
+    "txs_results": [
+      {
+        "code": 0,
+        "data": "Ei4KLC9jb3Ntd2FzbS53YXNtLnYxLk1zZ0V4ZWN1dGVDb250cmFjdFJlc3BvbnNl",
+        "log": "",
+        "info": "",
+        "gas_wanted": "286320",
+        "gas_used": "245458",
+        "events": [
+          {
+            "type": "transfer",
+            "attributes": [
+              { "key": "recipient", "value": "zig17xpfvakm2amg962yls6f84z3kell8c5l3nxjf4", "index": true },
+              { "key": "sender",    "value": "zig1eyrwj20cujzwrln2gztmxgfx2vkp0l6le3xf2z", "index": true },
+              { "key": "amount",    "value": "8590uzig", "index": true }
+            ]
+          },
+          {
+            "type": "wasm",
+            "attributes": [
+              { "key": "_contract_address", "value": "zig15jqg0hmp9n06q0as7uk3x9xkwr9k3r7yh4ww2uc0hek8zlryrgmsamk4qg", "index": true },
+              { "key": "action",           "value": "provide_liquidity", "index": true },
+              { "key": "share",            "value": "285", "index": true }
+            ]
+          }
+        ],
+        "codespace": ""
+      },
+      {
+        "code": 5,
+        "data": null,
+        "log": "failed to execute message; message index: 0: Operation exceeds max spread limit: execute wasm contract failed",
+        "gas_wanted": "500000",
+        "gas_used": "212387",
+        "events": [...],
+        "codespace": "wasm"
+      }
+    ],
+    "finalize_block_events": [
+      {
+        "type": "mint",
+        "attributes": [
+          { "key": "bonded_ratio",      "value": "0.043487338234004096", "index": true },
+          { "key": "inflation",         "value": "0.013406523098689013", "index": true },
+          { "key": "annual_provisions", "value": "31088831973883.453729872137993930", "index": true },
+          { "key": "amount",            "value": "2464550", "index": true }
+        ]
+      },
+      {
+        "type": "rewards",
+        "attributes": [
+          { "key": "amount",    "value": "619572.861060342856543622uzig", "index": true },
+          { "key": "validator", "value": "zigvaloper1pwwymlyeyfcz3pjvcegvz8tj3yf0pr3wqqhrwk", "index": true }
+        ]
+      }
+    ],
+    "validator_updates": null,
+    "consensus_param_updates": {
+      "block": { "max_bytes": "5000000", "max_gas": "100000000" },
+      "evidence": {
+        "max_age_num_blocks": "100000",
+        "max_age_duration": "172800000000000",
+        "max_bytes": "1048576"
+      },
+      "validator": { "pub_key_types": ["ed25519"] }
+    },
+    "app_hash": "PPCXOVQT5jIl2vYJvYUjDbgYe36WtCVdzuNx3mmF+dk="
+  }
+}
+```
+
+---
+
+## Response Field Explanation
+
+### Top-level wrapper
+
+| Field   | Description                                      |
+| ------- | ------------------------------------------------ |
+| jsonrpc | JSON-RPC protocol version (always `"2.0"`)       |
+| id      | Request ID (always `-1` for SDK queries)         |
+| result  | The actual block results payload                 |
+
+---
+
+### `result`
+
+| Field                    | Description                                                          |
+| ------------------------ | -------------------------------------------------------------------- |
+| height                   | Block height this result corresponds to                              |
+| txs_results              | Array of execution results, one per transaction in the block         |
+| finalize_block_events    | Block-level events (inflation, rewards, commissions)                 |
+| validator_updates        | Any validator set changes applied at this block. `null` if none      |
+| consensus_param_updates  | Consensus configuration active at this block                         |
+| app_hash                 | Application state hash after this block was applied                  |
+
+---
+
+### `txs_results[]` — Per-Transaction Result
+
+| Field       | Description                                                              |
+| ----------- | ------------------------------------------------------------------------ |
+| code        | `0` = success. Any non-zero = failure                                    |
+| data        | Base64-encoded protobuf response from the message handler                |
+| log         | Empty on success. Contains the error message on failure                  |
+| info        | Optional additional info string                                          |
+| gas_wanted  | Gas limit set by the transaction sender                                  |
+| gas_used    | Actual gas consumed during execution                                     |
+| events      | Array of events emitted by this transaction                              |
+| codespace   | Module namespace for the error code. Empty on success                    |
+
+---
+
+### `events[]` — Event Structure
+
+Each event (at both transaction and block level) follows this structure:
+
+| Field      | Description                                          |
+| ---------- | ---------------------------------------------------- |
+| type       | Event category (e.g. `transfer`, `wasm`, `mint`)     |
+| attributes | Array of key-value pairs describing the event detail |
+
+Each attribute contains:
+
+| Field | Description                                            |
+| ----- | ------------------------------------------------------ |
+| key   | Attribute name                                         |
+| value | Attribute value                                        |
+| index | Whether this attribute is indexed for event search     |
+
+---
+
+### `finalize_block_events[]` — Block-Level Events
+
+These events fire automatically each block regardless of transactions. Common block-level events and their attributes:
+
+**`mint`** — Inflation tokens minted this block
+
+| Attribute          | Description                              |
+| ------------------ | ---------------------------------------- |
+| bonded_ratio       | Fraction of supply currently staked      |
+| inflation          | Current annual inflation rate            |
+| annual_provisions  | Projected annual token emission          |
+| amount             | Tokens minted this block (in `uzig`)     |
+
+**`commission`** — Validator commission distributed
+
+| Attribute | Description                         |
+| --------- | ----------------------------------- |
+| amount    | Commission amount paid               |
+| validator | Validator operator address           |
+
+**`rewards`** — Staking rewards distributed
+
+| Attribute | Description                           |
+| --------- | ------------------------------------- |
+| amount    | Total rewards distributed             |
+| validator | Validator operator address             |
+
+---
+
+### `consensus_param_updates`
+
+Active consensus configuration for this block.
+
+| Field                          | Description                                         |
+| ------------------------------ | --------------------------------------------------- |
+| block.max_bytes                | Maximum block size in bytes                         |
+| block.max_gas                  | Maximum gas allowed per block                       |
+| evidence.max_age_num_blocks    | How many blocks back evidence remains valid         |
+| evidence.max_age_duration      | Time duration evidence remains valid (nanoseconds)  |
+| evidence.max_bytes             | Maximum evidence size per block                     |
+| validator.pub_key_types        | Accepted validator key types (e.g. `ed25519`)       |
+
+---
+
+## Reading a Failed Transaction
+
+When `code` is non-zero, the `log` field contains the error reason and `codespace` identifies which module raised it:
+
+```json
+{
+  "code": 5,
+  "log": "failed to execute message; message index: 0: Operation exceeds max spread limit: execute wasm contract failed",
+  "codespace": "wasm"
+}
+```
+
+> Even failed transactions consume gas and emit fee-related events (the fee is still charged).
+
+---
+
+## When to Use
+
+* Indexing all on-chain activity for a given block
+* Building block explorer transaction detail pages
+* Tracking contract executions and their emitted events
+* Monitoring validator reward and commission distribution
+* Debugging failed transactions and identifying error reasons
+* Auditing token flows within a specific block
+
+---

package/docs/block.md

@@ -0,0 +1,97 @@
+# Block Info
+
+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.
+
+---
+
+## Setup
+
+```ts
+import {
+  ChainBlockApi,
+  getNetworkEndpoints,
+  Network,
+} from '@zuhaibnoor/zigchain-sdk'
+
+const endpoints = getNetworkEndpoints(Network.Testnet)
+const blockApi = new ChainBlockApi(endpoints)
+```
+
+---
+
+## `getLatestBlock`
+
+Fetch the **latest committed block** on the chain.
+You can also query how the latest block looked at a specific historical height.
+
+**CLI equivalent**
+
+```bash
+zigchaind query block
+zigchaind query block --height <H>
+```
+
+**Method**
+
+```ts
+getLatestBlock(atHeight?: number)
+```
+
+**Example (latest block)**
+
+```ts
+const latestBlock = await blockApi.getLatestBlock()
+console.log(latestBlock)
+```
+
+**Example (latest block at a specific height)**
+
+```ts
+const latestAtHeight = await blockApi.getLatestBlock(120000)
+console.log(latestAtHeight)
+```
+
+---
+
+## `getBlockByHeight`
+
+Query a **specific block by its height**.
+Optionally, you can query the result from a historical chain state.
+
+**CLI equivalent**
+
+```bash
+zigchaind query block --type=height <height>
+zigchaind query block --type=height <height> --height <H>
+```
+
+**Method**
+
+```ts
+getBlockByHeight(height: number, atHeight?: number)
+```
+
+**Example (specific block)**
+
+```ts
+const block = await blockApi.getBlockByHeight(150000)
+console.log(block)
+```
+
+**Example (block queried at historical height)**
+
+```ts
+const blockAtHeight = await blockApi.getBlockByHeight(150000, 160000)
+console.log(blockAtHeight)
+```
+
+---
+
+## Notes
+
+* 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).
+
+---

package/docs/circuit.md

@@ -0,0 +1,93 @@
+# 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.
+
+---
+
+## Setup
+
+```ts
+import {
+  ChainCircuitApi,
+  getNetworkEndpoints,
+  Network,
+} from '@zuhaibnoor/zigchain-sdk'
+
+const endpoints = getNetworkEndpoints(Network.Testnet)
+const circuitApi = new ChainCircuitApi(endpoints)
+```
+
+---
+
+## `getAccountPermissions`
+
+Fetch the **circuit permissions for a specific account**.
+
+**CLI equivalent**
+
+```bash
+zigchaind query circuit account <address>
+```
+
+**Method**
+
+```ts
+getAccountPermissions(address: string)
+```
+
+**Parameters**
+
+* `address: string` – The account address to query.
+
+**Returns**
+
+* `CircuitAccountResponse` – Contains whether the account is blocked or restricted.
+
+**Example**
+
+```ts
+const address = 'zig1svkn4sqrlz8r6krq96ty6kze54n2ec03u0vat5'
+const permissions = await circuitApi.getAccountPermissions(address)
+console.log(`Circuit permissions for ${address}:`)
+console.dir(permissions, { depth: null })
+```
+
+---
+
+## `getAllAccountPermissions`
+
+Fetch **all accounts with circuit restrictions or permissions**.
+
+**CLI equivalent**
+
+```bash
+zigchaind query circuit accounts
+```
+
+**Method**
+
+```ts
+getAllAccountPermissions()
+```
+
+**Returns**
+
+* `CircuitAccountsResponse` – Contains a list of all accounts and their circuit permission status.
+
+**Example**
+
+```ts
+const allPermissions = await circuitApi.getAllAccountPermissions()
+console.log('All accounts with circuit permissions:')
+console.dir(allPermissions, { depth: null })
+```
+
+---
+
+## Notes
+
+* Useful for **auditing and monitoring** restricted accounts.
+* The `getAllAccountPermissions` method may return large datasets if many accounts are restricted.
+
+

package/docs/comet-validator-set.md

@@ -0,0 +1,70 @@
+# Comet Validator Set Module
+
+The **Comet Validator Set** module allows you to query the **full CometBFT validator set** on ZigChain.
+
+Think of it as a way to see **all the nodes that are currently validating blocks** at any given height.
+
+---
+
+## Setup
+
+```ts
+import {
+  ChainCometValidatorSetApi,
+  getNetworkEndpoints,
+  Network
+} from '@zuhaibnoor/zigchain-sdk'
+
+const endpoints = getNetworkEndpoints(Network.Testnet)
+const validatorApi = new ChainCometValidatorSetApi(endpoints)
+```
+
+---
+
+## `fetchValidatorSet(height?: number)`
+
+### What it does
+
+Fetches the **full list of validators** for a specific block height.
+
+* If `height` is **not provided**, it returns the **latest validator set**.
+* If `height` is provided, it returns the **validator set at that block height**.
+
+---
+
+### Validator Info
+
+Each validator object contains:
+
+* `operator_address` → the validator’s address
+* `consensus_pubkey` → their public key used for block signing
+* `voting_power` → the validator’s current voting weight
+* `proposer_priority` → used internally to determine which validator proposes the next block
+
+---
+
+### CLI Equivalent
+
+```bash
+# Latest validator set
+zigchaind query comet-validator-set
+
+# Validator set at specific height
+zigchaind query comet-validator-set <height>
+```
+
+---
+
+### Example
+
+```ts
+// Latest validator set
+const latestValidators = await validatorApi.fetchValidatorSet()
+console.dir(latestValidators, { depth: null })
+
+// Validator set at height 2990010
+const validatorsAtHeight = await validatorApi.fetchValidatorSet(2990010)
+console.dir(validatorsAtHeight, { depth: null })
+```
+
+---