@zuhaibnoor/zigchain-sdk 1.0.3 → 1.1.0

package/docs/block-results.md

@@ -1,7 +1,103 @@
 # Block Results
 
-The **ChainBlockResultsApi** lets you query the **execution results of a committed block**.
-It includes transaction logs, events, fees, and validator execution 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.
 
 ---
 
@@ -20,45 +116,256 @@ const blockResultsApi = new ChainBlockResultsApi(endpoints)
 
 ---
 
-## `fetchBlockResults`
+# 1️⃣ fetchBlockResults
 
-Fetch the **execution results of a block at a specific height**.
+## Method
 
-**CLI equivalent**
+```ts
+async fetchBlockResults(height: number)
+```
+
+## CLI Equivalent
 
 ```bash
 zigchaind query block-results <height>
 ```
 
-**Method**
+---
 
-```ts
-fetchBlockResults(height: number)
-```
+## Description
 
-**Parameters**
+Fetches the **full execution results for a specific block** by height.
 
-* `height: number` – The block height to query.
+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.
 
-**Returns**
+This is the most detailed view available for what happened at a specific point in chain history.
 
-* `BlockResultsResponse` – Contains transaction results, logs, events, and validator execution info.
+> ⚠️ This function queries the **RPC endpoint** internally, unlike all other SDK modules which use the LCD endpoint.
 
-**Example**
+---
+
+## Parameters
+
+| Name   | Type   | Required | Description                        |
+| ------ | ------ | -------- | ---------------------------------- |
+| height | number | ✅ Yes   | Block height to fetch results for  |
+
+---
+
+## Usage Example
 
 ```ts
-const height = 12345
-const results = await blockResultsApi.fetchBlockResults(height)
-console.log(`Block Results at height ${height}:`)
+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).
+
 ---
 
-## Notes
+## When to Use
 
-* Only works with **RPC endpoints** (`endpoints.rpc`), LCD endpoints cannot be used.
-* Useful for analyzing **transaction success/failure**, events emitted, and validator execution info.
-* Querying non-existent or pruned heights may return errors.
+* 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/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 })
+```
+
+---

package/docs/distribution.md

@@ -0,0 +1,201 @@
+# Distribution Module
+
+The **Distribution module** handles reward distribution in the ZigChain network.
+It manages validator commissions, delegator rewards, community pool funds, and distribution-related parameters.
+
+This module allows you to **query how rewards are shared** between validators, delegators, and the community pool.
+
+---
+
+## `ChainDistributionApi`
+
+```ts
+import { ChainDistributionApi } from '@zuhaibnoor/zigchain-sdk'
+```
+
+---
+
+## Constructor
+
+```ts
+const distribution = new ChainDistributionApi(endpoints)
+```
+
+Initializes the Distribution API using the network’s LCD endpoint.
+
+---
+
+## Functions
+
+---
+
+### `fetchValidatorCommission(validator: string)`
+
+**Purpose:**
+Returns the commission accumulated by a specific validator from delegators’ rewards.
+
+**When to use:**
+Use this when you want to check how much commission a validator has earned.
+
+```ts
+const commission = await distribution.fetchValidatorCommission(
+  'zigvaloper1...'
+)
+```
+
+---
+
+### `fetchCommunityPool()`
+
+**Purpose:**
+Fetches the total balance of the **community pool**, which is used for governance-approved spending.
+
+**When to use:**
+Helpful for governance dashboards or tracking ecosystem funds.
+
+```ts
+const pool = await distribution.fetchCommunityPool()
+```
+
+---
+
+### `fetchDelegatorValidators(delegator: string)`
+
+**Purpose:**
+Returns the list of validators from which a delegator is currently earning rewards.
+
+**When to use:**
+Use this to understand which validators are paying rewards to a specific delegator.
+
+```ts
+const validators =
+  await distribution.fetchDelegatorValidators('zig1...')
+```
+
+---
+
+### `fetchDelegatorWithdrawAddress(delegator: string)`
+
+**Purpose:**
+Fetches the withdraw address where a delegator’s rewards are sent.
+
+**When to use:**
+Useful for checking whether a delegator has set a **custom reward withdrawal address**.
+
+```ts
+const withdrawAddress =
+  await distribution.fetchDelegatorWithdrawAddress('zig1...')
+```
+
+---
+
+### `fetchParams()`
+
+**Purpose:**
+Returns the current **distribution parameters**, including community tax and reward configuration.
+
+**When to use:**
+Helpful for understanding how rewards are split at the protocol level.
+
+```ts
+const params = await distribution.fetchParams()
+```
+
+---
+
+## `fetchDelegatorRewards(delegator)`
+
+**Purpose:**
+Fetches **all staking rewards** earned by a delegator across **all validators**.
+
+**When to use:**
+Use this when you want a complete view of a delegator’s accumulated rewards before withdrawal.
+
+**CLI equivalent:**
+
+```
+zigchaind query distribution rewards <delegator-address>
+```
+
+---
+
+## `fetchDelegatorRewardsByValidator(delegator, validator)`
+
+**Purpose:**
+Returns rewards earned by a delegator **from a specific validator only**.
+
+**When to use:**
+Helpful when analyzing reward contribution per validator or building validator-specific dashboards.
+
+**CLI equivalent:**
+
+```
+zigchaind query distribution rewards-by-validator <delegator> <validator>
+```
+
+---
+
+## `fetchValidatorSlashes(validator)`
+
+**Purpose:**
+Fetches **slashing events** applied to a validator, including the slashing fraction and period.
+
+**When to use:**
+Use this to inspect validator misbehavior history and assess validator risk.
+
+**CLI equivalent:**
+
+```
+zigchaind query distribution slashes <validator-address>
+```
+
+---
+
+## `fetchValidatorDistributionInfo(validator)`
+
+**Purpose:**
+Returns a validator’s **distribution overview**, including self-bond rewards and commission earned.
+
+**When to use:**
+Useful for validators or explorers to understand validator earnings structure.
+
+**CLI equivalent:**
+
+```
+zigchaind query distribution validator-distribution-info <validator-address>
+```
+
+---
+
+## `fetchValidatorOutstandingRewards(validator)`
+
+**Purpose:**
+Fetches **unwithdrawn (outstanding) rewards** for a validator and all of its delegations.
+
+**When to use:**
+Use this to check pending rewards that have not yet been withdrawn.
+
+**CLI equivalent:**
+
+```
+zigchaind query distribution validator-outstanding-rewards <validator-address>
+```
+
+---
+
+## 📌 Summary
+
+| Function                        | What it tells you                          |
+| ------------------------------- | ------------------------------------------ |
+| `fetchValidatorCommission`      | How much commission a validator has earned |
+| `fetchCommunityPool`            | Total funds in the community pool          |
+| `fetchDelegatorValidators`      | Validators paying rewards to a delegator   |
+| `fetchDelegatorWithdrawAddress` | Where delegator rewards are withdrawn      |
+| `fetchParams`                   | Network-wide reward distribution rules     |
+| `fetchDelegatorRewards`            | Get all staking rewards for a delegator across all validators |
+| `fetchDelegatorRewardsByValidator` | Get delegator rewards from a specific validator               |
+| `fetchValidatorSlashes`            | Query slashing events applied to a validator                  |
+| `fetchValidatorDistributionInfo`   | Fetch validator commission and self-bond rewards              |
+| `fetchValidatorOutstandingRewards` | Get unwithdrawn rewards for a validator                       |
+---
+