@zuhaibnoor/zigchain-sdk 1.0.3 → 1.1.1

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
 
 ---