@zuhaibnoor/zigchain-sdk 1.1.0 → 1.1.1

package/docs/staking.md

@@ -1,633 +1,756 @@
-# Staking Module
+# STAKING Module
 
-The **Staking module** manages everything related to **validators**, **delegations**, **unbonding**, and **redelegation**.
+## What is STAKING?
 
-In simple terms:
+**Staking** in the Cosmos ecosystem (including **ZigChain**) allows token holders to:
 
-* **Delegators** stake tokens to validators
-* **Validators** secure the network
-* Rewards, slashing, and voting power all depend on staking state
+* Delegate tokens to validators
+* Earn rewards
+* Participate in network security
 
-The `ChainStakingApi` provides **read-only access** to staking data using LCD endpoints.
+The staking module tracks delegations, validators, and staking parameters.
 
 ---
 
-## Setup
+# Important Terminology
 
-```ts
-import {
-  ChainStakingApi,
-  getNetworkEndpoints,
-  Network,
-} from '@zuhaibnoor/zigchain-sdk'
-
-const endpoints = getNetworkEndpoints(Network.Testnet)
-const stakingApi = new ChainStakingApi(endpoints)
-```
+### Delegator
 
----
-
-## `fetchDelegation`
+A user who locks tokens by delegating to a validator.
 
-Fetch **a single delegation relationship** between:
+### Validator
 
-* one **delegator**
-* one **validator**
+An entity responsible for validating blocks.
 
-Use this when you already know **both addresses** and want to check:
+### Delegation
 
-* delegated amount
-* shares
-* delegation status
+Tokens staked by a delegator to a validator.
 
-**When to use**
+### Shares
 
-* Checking if a delegator has staked with a specific validator
-* Showing detailed info for one delegation
+Proportional representation of a delegator’s stake in the validator.
 
-**CLI equivalent**
+---
 
-```bash
-zigchaind query staking delegation <delegator> <validator>
-```
+# Functions Documentation
 
-**Method**
+Setup:
 
 ```ts
-fetchDelegation(
-  delegatorAddress: string,
-  validatorAddress: string
-)
-```
-
-**Example**
+import {
+  ChainStakingApi,
+  getNetworkEndpoints,
+  Network
+} from '@zuhaibnoor/zigchain-sdk'
 
-```ts
-const delegation = await stakingApi.fetchDelegation(
-  delegatorAddr,
-  validatorAddr
-)
+const endpoints = getNetworkEndpoints(Network.Testnet)
+const stakingApi = new ChainStakingApi(endpoints)
 
-console.dir(delegation, { depth: null })
+const delegator = 'zig1q8uh4ytf632jqykrd4m0weuzq9uv4r4jzra9h6'
+const validator = 'zigvaloper1q8uh4ytf632jqykrd4m0weuzq9uv4r4jhy3rkr'
 ```
 
 ---
 
-## `fetchDelegations`
-
-Fetch **all delegations made by a delegator** across **all validators**.
-
-This returns a **list**, not a single delegation.
+# 1️⃣ fetchDelegations
 
-**When to use**
+## Method
 
-* Showing a delegator’s entire staking portfolio
-* Wallet dashboards
-* Calculating total staked amount for a user
-
-**Difference from `fetchDelegation`**
-
-* `fetchDelegation` → one validator
-* `fetchDelegations` → all validators
+```ts
+async fetchDelegations(delegatorAddress: string)
+```
 
-**CLI equivalent**
+## CLI Equivalent
 
 ```bash
 zigchaind query staking delegations <delegator>
 ```
 
-**Method**
+## Description
 
-```ts
-fetchDelegations(delegatorAddress: string)
-```
+Query all delegations made by a delegator.
+
+
+## Parameters
+
+| Name             | Type   | Description                     |
+| ---------------- | ------ | ------------------------------- |
+| delegatorAddress | string | Bech32 address of the delegator |
 
-**Example**
+## Usage Example
 
 ```ts
-const delegations = await stakingApi.fetchDelegations(delegatorAddr)
+const delegations = await stakingApi.fetchDelegations(delegator)
 console.dir(delegations, { depth: null })
 ```
 
----
 
-## `fetchValidatorDelegations`
 
-Fetch **all delegations made to a specific validator** by **all delegators**.
+## Example Response
 
-This is the **validator-centric** view of delegations.
+```json
+{
+  "delegation_responses": [
+    {
+      "delegation": {
+        "delegator_address": "zig1q8uh4ytf632jqykrd4m0weuzq9uv4r4jzra9h6",
+        "validator_address": "zigvaloper1q8uh4ytf632jqykrd4m0weuzq9uv4r4jhy3rkr",
+        "shares": "1500000.000000000000000000"
+      },
+      "balance": { "denom": "uzig", "amount": "1500000" }
+    }
+  ],
+  "pagination": { "next_key": null, "total": "1" }
+}
+```
 
-**When to use**
+---
 
-* Validator dashboards
-* Showing who has delegated to a validator
-* Calculating validator voting power
+## Response Field Explanation
 
-**Difference from `fetchDelegations`**
+| Field                        | Description                            |
+| ---------------------------- | -------------------------------------- |
+| delegation_responses         | Array of delegations for the delegator |
+| delegation.delegator_address | Address of the delegator               |
+| delegation.validator_address | Address of the validator               |
+| delegation.shares            | Delegation shares                      |
+| balance.denom                | Token denomination (`uzig`)            |
+| balance.amount               | Delegated amount in smallest unit      |
+| pagination.next_key          | Key for next page (null if none)       |
+| pagination.total             | Total delegations                      |
 
-* `fetchDelegations` → delegator → validators
-* `fetchValidatorDelegations` → validator → delegators
+---
 
-**CLI equivalent**
+# 2️⃣ fetchDelegation
 
-```bash
-zigchaind query staking delegations-to <validator>
-```
-
-**Method**
+## Method
 
 ```ts
-fetchValidatorDelegations(validatorAddress: string)
+async fetchDelegation(delegatorAddress: string, validatorAddress: string)
 ```
 
-**Example**
+## CLI Equivalent
 
-```ts
-const validatorDelegations =
-  await stakingApi.fetchValidatorDelegations(validatorAddr)
-
-console.dir(validatorDelegations, { depth: null })
+```bash
+zigchaind query staking delegation <delegator> <validator>
 ```
 
----
-
-## `fetchDelegatorValidator`
+## Description
 
-Fetch **validator information** for a **specific delegator–validator pair**.
+Query a **single delegation** from a delegator to a specific validator.
 
-This endpoint confirms:
+## Parameters
 
-* whether a validator exists for a delegator
-* whether the delegator is bonded to that validator
+| Name             | Type   | Description                     |
+| ---------------- | ------ | ------------------------------- |
+| delegatorAddress | string | Bech32 address of the delegator |
+| validatorAddress | string | Bech32 address of the validator |
 
-⚠️ Even though the endpoint looks similar to `fetchDelegation`,
-this method focuses on **validator details**, not delegation amounts.
+## Usage Example
 
-**When to use**
-
-* Validating a delegator–validator relationship
-* Checking validator status (bonded / unbonded / jailed) for a delegator
-* UI flows that depend on validator state
-
-**Difference from `fetchDelegation`**
+```ts
+const delegation = await stakingApi.fetchDelegation(delegator, validator)
+console.dir(delegation, { depth: null })
+```
 
-* `fetchDelegation` → delegation data (shares, balance)
-* `fetchDelegatorValidator` → validator info in context of delegator
+## Example Response
+
+```json
+{
+  "validator": {
+    "operator_address": "zigvaloper1q8uh4ytf632jqykrd4m0weuzq9uv4r4jhy3rkr",
+    "consensus_pubkey": {
+      "@type": "/cosmos.crypto.ed25519.PubKey",
+      "key": "qLwYZi8Sm9IUvjoa48+sS9Sqata0Lm2r9QhjesO+6ZI="
+    },
+    "jailed": false,
+    "status": "BOND_STATUS_UNBONDED",
+    "tokens": "1501000",
+    "delegator_shares": "1501000.000000000000000000",
+    "description": {
+      "moniker": "testnet-validator-multisig",
+      "identity": "",
+      "website": "https://testnet-validator.example.com",
+      "security_contact": "security@example.com",
+      "details": "Multi-sig test: Updated validator description"
+    },
+    "unbonding_height": "0",
+    "unbonding_time": "1970-01-01T00:00:00Z",
+    "commission": {
+      "commission_rates": {
+        "rate": "0.100000000000000000",
+        "max_rate": "0.200000000000000000",
+        "max_change_rate": "0.010000000000000000"
+      },
+      "update_time": "2025-12-03T07:13:59.701638398Z"
+    },
+    "min_self_delegation": "1",
+    "unbonding_on_hold_ref_count": "0",
+    "unbonding_ids": []
+  }
+}
+```
+
+## Response Field Explanation
+
+| Field                                                 | Description                         |
+| ----------------------------------------------------- | ----------------------------------- |
+| validator.operator_address                            | Validator operator address          |
+| validator.consensus_pubkey.@type                      | Public key type                     |
+| validator.consensus_pubkey.key                        | Base64-encoded validator public key |
+| validator.jailed                                      | Whether validator is jailed         |
+| validator.status                                      | Bond status                         |
+| validator.tokens                                      | Total tokens for validator          |
+| validator.delegator_shares                            | Delegator’s share in validator      |
+| validator.description.moniker                         | Validator display name              |
+| validator.description.identity                        | Identity field                      |
+| validator.description.website                         | Validator website                   |
+| validator.description.security_contact                | Security contact                    |
+| validator.description.details                         | Extra description                   |
+| validator.unbonding_height                            | Unbonding start height              |
+| validator.unbonding_time                              | Unbonding start time                |
+| validator.commission.commission_rates.rate            | Current commission rate             |
+| validator.commission.commission_rates.max_rate        | Max commission rate                 |
+| validator.commission.commission_rates.max_change_rate | Max change per update               |
+| validator.commission.update_time                      | Last commission update timestamp    |
+| validator.min_self_delegation                         | Minimum self-delegation required    |
+| validator.unbonding_on_hold_ref_count                 | Counter for unbonding references    |
+| validator.unbonding_ids                               | Array of unbonding IDs              |
 
-**CLI equivalent**
+---
 
-```bash
-zigchaind query staking delegator-validator <delegator> <validator>
-```
+# 3️⃣ fetchValidatorDelegations
 
-**Method**
+## Method
 
 ```ts
-fetchDelegatorValidator(
-  delegatorAddress: string,
-  validatorAddress: string
-)
+async fetchValidatorDelegations(validator_addr: string)
 ```
 
-**Example**
+## CLI Equivalent
 
-```ts
-const validatorInfo =
-  await stakingApi.fetchDelegatorValidator(
-    delegatorAddr,
-    validatorAddr
-  )
-
-console.dir(validatorInfo, { depth: null })
+```bash
+zigchaind query staking delegations-to <validator>
 ```
 
----
-
-## `fetchDelegatorValidators`
+## Description
 
-Fetch **all validator information associated with a delegator**.
+Fetch all delegations to a specific validator.
 
-This returns the **validators a delegator is bonded to**, along with each validator’s metadata and status.
+## Parameters
 
-**Key idea**
+| Name           | Type   | Description                     |
+| -------------- | ------ | ------------------------------- |
+| validator_addr | string | Bech32 address of the validator |
 
-* This is **validator-focused**, not delegation-amount–focused.
-* It answers *“Which validators am I connected to?”* rather than *“How much did I stake?”*
+## Usage Example
 
-**When to use**
-
-* Showing a delegator’s active validators
-* Validator lists inside wallets
-* Navigation links from delegator → validator pages
+```ts
+const valDelegations = await stakingApi.fetchValidatorDelegations(validator)
+console.dir(valDelegations, { depth: null })
+```
+
+## Example Response
+
+```json
+{
+  "delegation_responses": [
+    {
+      "delegation": {
+        "delegator_address": "zig1q8uh4ytf632jqykrd4m0weuzq9uv4r4jzra9h6",
+        "validator_address": "zigvaloper1q8uh4ytf632jqykrd4m0weuzq9uv4r4jhy3rkr",
+        "shares": "1500000.000000000000000000"
+      },
+      "balance": { "denom": "uzig", "amount": "1500000" }
+    },
+    {
+      "delegation": {
+        "delegator_address": "zig1zxxkdjzsvtu7zgnu04wvlvq9umhl4rgcq83cyl",
+        "validator_address": "zigvaloper1q8uh4ytf632jqykrd4m0weuzq9uv4r4jhy3rkr",
+        "shares": "1000.000000000000000000"
+      },
+      "balance": { "denom": "uzig", "amount": "1000" }
+    }
+  ],
+  "pagination": { "next_key": null, "total": "2" }
+}
+```
 
-**Difference from similar methods**
+---
 
-* `fetchDelegations` → delegation amounts & shares
-* `fetchDelegatorValidators` → validator identities & status
+# 4️⃣ fetchDelegatorValidator
 
-**CLI equivalent**
+## Method
 
-```bash
-zigchaind query staking delegator-validators <delegator>
+```ts
+async fetchDelegatorValidator(delegatorAddress: string, validatorAddress: string)
 ```
 
-**Method**
+## CLI Equivalent
 
-```ts
-fetchDelegatorValidators(delegatorAddress: string)
+```bash
+zigchaind query staking delegator-validator <delegator> <validator>
 ```
 
-**Example**
+## Description
 
-```ts
-const validators =
-  await stakingApi.fetchDelegatorValidators(delegatorAddr)
+Query validator info for a specific delegator-validator pair.
 
-console.dir(validators, { depth: null })
-```
+## Parameters
 
----
+| Name             | Type   | Description              |
+| ---------------- | ------ | ------------------------ |
+| delegatorAddress | string | Bech32 delegator address |
+| validatorAddress | string | Bech32 validator address |
 
-## `fetchHistoricalInfo`
+## Usage Example
 
-Fetch **historical staking state at a specific block height**.
+```ts
+const delegatorValidator = await stakingApi.fetchDelegatorValidator(delegator, validator)
+console.dir(delegatorValidator, { depth: null })
+```
 
-This includes:
+## Example Response
 
-* validator set at that height
-* total voting power
-* staking-related metadata
+*(Same as `fetchDelegation` — returns validator object.)*
 
-This endpoint is mainly useful for **indexers, explorers, and analytics tools**.
+---
 
-**When to use**
+# 5️⃣ fetchDelegatorValidators
 
-* Analyzing past validator sets
-* Replaying chain state for historical research
-* Governance or slashing investigations
+## Method
 
-⚠️ This data is **not available for all heights** — only heights explicitly stored by the chain.
+```ts
+async fetchDelegatorValidators(delegatorAddress: string)
+```
 
-**CLI equivalent**
+## CLI Equivalent
 
 ```bash
-zigchaind query staking historical-info <height>
+zigchaind query staking delegator-validators <delegator>
 ```
 
-**Method**
+## Description
 
-```ts
-fetchHistoricalInfo(height: number | string)
-```
+Fetch info of **all validators** a delegator has delegated to.
 
-**Example**
+## Parameters
 
-```ts
-const history = await stakingApi.fetchHistoricalInfo(100000)
-console.dir(history, { depth: null })
-```
+| Name             | Type   | Description              |
+| ---------------- | ------ | ------------------------ |
+| delegatorAddress | string | Bech32 delegator address |
 
 ---
 
-## `fetchStakingParams`
+## Usage Example
 
-Fetch the **global staking parameters** of the chain.
+```ts
+const delegatorValidators = await stakingApi.fetchDelegatorValidators(delegator)
+console.dir(delegatorValidators, { depth: null })
+```
+
+## Example Response
+
+```json
+{
+  "validators": [
+    {
+      "operator_address": "zigvaloper1q8uh4ytf632jqykrd4m0weuzq9uv4r4jhy3rkr",
+      "consensus_pubkey": { "@type": "/cosmos.crypto.ed25519.PubKey", "key": "qLwYZi8Sm9IUvjoa48+sS9Sqata0Lm2r9QhjesO+6ZI=" },
+      "jailed": false,
+      "status": "BOND_STATUS_UNBONDED",
+      "tokens": "1501000",
+      "delegator_shares": "1501000.000000000000000000",
+      "description": { "moniker": "testnet-validator-multisig", "identity": "", "website": "https://testnet-validator.example.com", "security_contact": "security@example.com", "details": "Multi-sig test: Updated validator description" },
+      "unbonding_height": "0",
+      "unbonding_time": "1970-01-01T00:00:00Z",
+      "commission": { "commission_rates": { "rate": "0.100000000000000000", "max_rate": "0.200000000000000000", "max_change_rate": "0.010000000000000000" }, "update_time": "2025-12-03T07:13:59.701638398Z" },
+      "min_self_delegation": "1",
+      "unbonding_on_hold_ref_count": "0",
+      "unbonding_ids": []
+    }
+  ],
+  "pagination": { "next_key": null, "total": "1" }
+}
+```
 
-These parameters control:
+---
 
-* unbonding period
-* maximum number of validators
-* bond denomination
+# 6️⃣ fetchStakingParams
 
-**When to use**
+## Method
 
-* Displaying chain staking rules
-* Validating staking-related UI logic
-* Tooling that depends on unbonding duration or validator limits
+```ts
+async fetchStakingParams()
+```
 
-**CLI equivalent**
+## CLI Equivalent
 
 ```bash
 zigchaind query staking params
 ```
 
-**Method**
+## Description
 
-```ts
-fetchStakingParams()
-```
+Fetches chain-level **staking module parameters**.
+
+## Parameters
+
+None.
 
-**Example**
+## Usage Example
 
 ```ts
 const params = await stakingApi.fetchStakingParams()
 console.dir(params, { depth: null })
 ```
 
----
-
-## `fetchStakingPool`
-
-Fetch the **current staking pool state**.
+## Example Response
 
-This shows:
-
-* total bonded tokens
-* total not-bonded tokens
+```json
+{
+  "params": {
+    "unbonding_time": "604800s",
+    "max_validators": 8,
+    "max_entries": 8,
+    "historical_entries": 10000,
+    "bond_denom": "uzig",
+    "min_commission_rate": "0.000000000000000000"
+  }
+}
+```
 
-It represents the **global staking balance of the network**.
+## Response Field Explanation
 
-**When to use**
+| Field               | Description                                   |
+| ------------------- | --------------------------------------------- |
+| unbonding_time      | Duration tokens take to unbond                |
+| max_validators      | Maximum validators allowed                    |
+| max_entries         | Max unbonding entries per delegator           |
+| historical_entries  | How many historical validator sets are stored |
+| bond_denom          | Token denomination used for staking           |
+| min_commission_rate | Minimum allowed validator commission          |
 
-* Network health dashboards
-* Calculating staking ratios
-* Showing bonded vs unbonded supply
+---
 
-**Difference from params**
+Here's batch 1 of the Staking module documentation:
 
-* Params → rules
-* Pool → live staking state
+---
 
-**CLI equivalent**
 
-```bash
-zigchaind query staking pool
-```
+# fetchStakingPool
 
-**Method**
+## Method
 
 ```ts
-fetchStakingPool()
+async fetchStakingPool()
 ```
 
-**Example**
+## CLI Equivalent
 
-```ts
-const pool = await stakingApi.fetchStakingPool()
-console.dir(pool, { depth: null })
+```bash
+zigchaind query staking pool
 ```
 
----
-
-## `fetchRedelegation`
-
-Fetch **all redelegations initiated by a delegator**.
-
-Redelegation allows moving stake from:
-
-* one validator → another
-* **without unbonding**
-
-This endpoint returns **ongoing and completed redelegations** for a delegator.
+## Description
 
-**When to use**
+Fetches the **chain-wide staking pool** — the total accounting of all bonded and non-bonded tokens across every validator.
 
-* Showing redelegation history
-* Tracking in-progress redelegations
-* Preventing invalid redelegation actions in UI
+This gives a high-level view of how much of the total token supply is currently actively staked (securing consensus) versus sitting in unbonding or with inactive validators.
 
-**Difference from delegation queries**
+## Parameters
 
-* Delegation → current stake
-* Redelegation → stake movement between validators
+None.
 
-**CLI equivalent**
-
-```bash
-zigchaind query staking redelegations <delegator>
-```
-
-**Method**
+## Usage Example
 
 ```ts
-fetchRedelegation(delegatorAddress: string)
+const pool = await stakingApi.fetchStakingPool()
+console.dir(pool, { depth: null })
 ```
 
-**Example**
+## Example Response
 
-```ts
-const redelegations =
-  await stakingApi.fetchRedelegation(delegatorAddr)
-
-console.dir(redelegations, { depth: null })
+```json
+{
+  "pool": {
+    "not_bonded_tokens": "108314438077",
+    "bonded_tokens": "101692473101453"
+  }
+}
 ```
 
----
+## Response Field Explanation
 
-Perfect — with these, your **staking module is now complete**.
-These functions cover **unbonding flows and validator discovery**, which are the last big pieces users usually get confused about. I’ll document them *very clearly* and show how they differ from each other.
+### `pool`
 
-You can paste this directly under the **Staking Module** section in your docs.
+| Field             | Description                                                                     |
+| ----------------- | ------------------------------------------------------------------------------- |
+| bonded_tokens     | Total `uzig` staked with validators in `BOND_STATUS_BONDED` (active set)        |
+| not_bonded_tokens | Total `uzig` held by unbonding or inactive (`BOND_STATUS_UNBONDED`) validators  |
 
 ---
 
-## `fetchUnbondingDelegation`
-
-Fetch the **unbonding delegation between a specific delegator and validator**.
-
-This shows stake that:
-
-* has been undelegated
-* is still in the **unbonding period**
-* is **not yet liquid**
-
-**What you get**
-
-* balance currently unbonding
-* completion time
-* creation height
-
-**When to use**
-
-* Showing “pending unstake” information
-* Tracking completion times in wallets
-* Validator-level unbonding inspections
-
-**Difference from other unbonding queries**
-
-* This is **one delegator → one validator**
-* Most granular unbonding query
-
-**CLI equivalent**
-
-```bash
-zigchaind query staking unbonding-delegation <delegator> <validator>
-```
+# fetchRedelegation
 
-**Method**
+## Method
 
 ```ts
-fetchUnbondingDelegation(delegator: string, validator: string)
+async fetchRedelegation(delegator_addr: string)
 ```
 
-**Example**
+## CLI Equivalent
 
-```ts
-const unbonding =
-  await stakingApi.fetchUnbondingDelegation(delegator, validator)
-
-console.dir(unbonding, { depth: null })
+```bash
+zigchaind query staking redelegation <delegator-address>
 ```
 
----
-
-## `fetchUnbondingDelegations`
-
-Fetch **all unbonding delegations for a delegator** across every validator.
+## Description
 
-This aggregates **all pending unbondings** initiated by a delegator.
+Fetches all **active redelegations** for a specific delegator.
 
-**When to use**
+A redelegation represents stake that has been moved from one validator to another but has not yet completed its cooldown period. During this period the stake cannot be redelegated again — this prevents "redelegation hopping" attacks.
 
-* Wallet “Unstaking” screens
-* Showing total pending unbonded stake
-* Preventing double-unbonding actions
+An empty `redelegation_responses` array means the delegator has no active redelegations in progress.
 
-**Difference from similar methods**
+## Parameters
 
-* `fetchUnbondingDelegation` → one validator
-* `fetchUnbondingDelegations` → all validators (delegator-wide)
+| Name           | Type   | Description                                      |
+| -------------- | ------ | ------------------------------------------------ |
+| delegator_addr | string | Bech32 address of the delegator to query         |
 
-⚠️ Even though the path contains `validators`, the **input is a delegator address**.
-
-**CLI equivalent**
-
-```bash
-zigchaind query staking unbonding-delegations <delegator>
-```
-
-**Method**
+## Usage Example
 
 ```ts
-fetchUnbondingDelegations(delegator: string)
+const redelegations = await stakingApi.fetchRedelegation(delegator)
+console.dir(redelegations, { depth: null })
 ```
 
-**Example**
+## Example Response
 
-```ts
-const unbondings =
-  await stakingApi.fetchUnbondingDelegations(delegator)
-
-console.dir(unbondings, { depth: null })
+```json
+{
+  "redelegation_responses": [],
+  "pagination": {
+    "next_key": null,
+    "total": "0"
+  }
+}
 ```
 
----
-
-## `fetchUnbondingDelegationsFrom`
+## Response Field Explanation
 
-Fetch **all unbonding delegations *from* a specific validator**.
+### `redelegation_responses`
 
-This shows which delegators are currently unbonding **away from a validator**.
+Array of active redelegation entries for this delegator. Empty if no redelegations are in progress.
 
-**When to use**
+If entries are present, each would contain:
 
-* Validator dashboards
-* Monitoring validator stake outflows
-* Risk and decentralization analysis
+| Field                              | Description                                           |
+| ---------------------------------- | ----------------------------------------------------- |
+| redelegation.delegator_address     | The delegator's address                               |
+| redelegation.validator_src_address | Validator the stake is moving away from               |
+| redelegation.validator_dst_address | Validator the stake is moving toward                  |
+| entries[].completion_time          | When the redelegation cooldown ends                   |
+| entries[].shares_dst               | Amount of shares being redelegated                    |
+| balance                            | Token amount being redelegated                        |
 
-**Perspective**
 
-* Delegator-focused → *who is unstaking*
-* Validator-focused → *from where stake is leaving*
 
-**CLI equivalent**
+---
 
-```bash
-zigchaind query staking unbonding-delegations-from <validator>
-```
+# fetchValidator
 
-**Method**
+## Method
 
 ```ts
-fetchUnbondingDelegationsFrom(validator: string)
+async fetchValidator(validator: string)
 ```
 
-**Example**
-
-```ts
-const validatorUnbondings =
-  await stakingApi.fetchUnbondingDelegationsFrom(validator)
+## CLI Equivalent
 
-console.dir(validatorUnbondings, { depth: null })
+```bash
+zigchaind query staking validator <validator-address>
 ```
 
----
-
-## `fetchValidator`
+## Description
 
-Fetch **detailed information about a single validator**.
+Fetches the **full details of a single validator** by their operator address.
 
-Includes:
+Returns the validator's complete profile — their bonding status, total stake, commission structure, self-delegation minimum, description, and unbonding state. This is the most detailed single-validator view available.
 
-* status (bonded / unbonded / unbonding)
-* commission rates
-* operator address
-* consensus public key
-* voting power
+## Parameters
 
-**When to use**
+| Name      | Type   | Description                                           |
+| --------- | ------ | ----------------------------------------------------- |
+| validator | string | Validator operator address (`zigvaloper...`) to query |
 
-* Validator profile pages
-* Delegation confirmation screens
-* Governance and slashing tools
-
-**CLI equivalent**
-
-```bash
-zigchaind query staking validator <validator>
-```
-
-**Method**
-
-```ts
-fetchValidator(validator: string)
-```
-
-**Example**
+## Usage Example
 
 ```ts
-const validatorInfo =
-  await stakingApi.fetchValidator(validatorAddr)
+const val = await stakingApi.fetchValidator(validator)
+console.dir(val, { depth: null })
+```
+
+## Example Response
+
+```json
+{
+  "validator": {
+    "operator_address": "zigvaloper1q8uh4ytf632jqykrd4m0weuzq9uv4r4jhy3rkr",
+    "consensus_pubkey": {
+      "@type": "/cosmos.crypto.ed25519.PubKey",
+      "key": "qLwYZi8Sm9IUvjoa48+sS9Sqata0Lm2r9QhjesO+6ZI="
+    },
+    "jailed": false,
+    "status": "BOND_STATUS_UNBONDED",
+    "tokens": "1501000",
+    "delegator_shares": "1501000.000000000000000000",
+    "description": {
+      "moniker": "testnet-validator-multisig",
+      "identity": "",
+      "website": "https://testnet-validator.example.com",
+      "security_contact": "security@example.com",
+      "details": "Multi-sig test: Updated validator description"
+    },
+    "unbonding_height": "0",
+    "unbonding_time": "1970-01-01T00:00:00Z",
+    "commission": {
+      "commission_rates": {
+        "rate": "0.100000000000000000",
+        "max_rate": "0.200000000000000000",
+        "max_change_rate": "0.010000000000000000"
+      },
+      "update_time": "2025-12-03T07:13:59.701638398Z"
+    },
+    "min_self_delegation": "1",
+    "unbonding_on_hold_ref_count": "0",
+    "unbonding_ids": []
+  }
+}
+```
+
+## Response Field Explanation
+
+### `validator`
+
+| Field                      | Description                                                                      |
+| -------------------------- | -------------------------------------------------------------------------------- |
+| operator_address           | Validator's staking operator address (`zigvaloper...`)                           |
+| consensus_pubkey.@type     | Key type — always Ed25519 for CometBFT validators                                |
+| consensus_pubkey.key       | Base64-encoded Ed25519 public key used for block signing                         |
+| jailed                     | `true` if validator has been penalized and removed from active set               |
+| status                     | Current bond status (`BONDED`, `UNBONDED`, or `UNBONDING`)                       |
+| tokens                     | Total `uzig` bonded to this validator                                            |
+| delegator_shares           | Internal share accounting — normally equals `tokens` unless slashed              |
+| description.moniker        | Human-readable validator name                                                    |
+| description.identity       | Optional Keybase identity for verification                                       |
+| description.website        | Validator's website                                                              |
+| description.security_contact | Contact email for security issues                                              |
+| description.details        | Validator's self-description                                                     |
+| unbonding_height           | Block height when unbonding began. `0` if not currently unbonding                |
+| unbonding_time             | Timestamp when unbonding completes. Epoch zero if not unbonding                  |
+| commission.commission_rates.rate | Current commission rate charged to delegators                              |
+| commission.commission_rates.max_rate | Hard cap on commission — can never be increased above this             |
+| commission.commission_rates.max_change_rate | Max daily commission rate change — prevents sudden increases      |
+| commission.update_time     | When commission was last changed                                                  |
+| min_self_delegation        | Minimum `uzig` the validator operator must self-delegate                         |
+| unbonding_ids              | IDs of active unbonding operations. Empty if none                                |
 
-console.dir(validatorInfo, { depth: null })
-```
 
 ---
 
-## `fetchValidators`
-
-Fetch **all validators in the network**.
-
-This returns the **full validator set**, optionally filtered by status at the chain level.
+# 4️⃣ fetchValidators
 
-**When to use**
+## Method
 
-* Validator explorer pages
-* Delegation selection UI
-* Network decentralization analysis
-
-**Difference from delegator-validator queries**
-
-* `fetchValidators` → network-wide
-* `fetchDelegatorValidators` → user-specific
+```ts
+async fetchValidators()
+```
 
-**CLI equivalent**
+## CLI Equivalent
 
 ```bash
 zigchaind query staking validators
 ```
 
-**Method**
+## Description
 
-```ts
-fetchValidators()
-```
+Fetches **all validators** registered on the chain — both active (bonded) and inactive (unbonded), including jailed validators.
 
-**Example**
+## Parameters
+
+None.
+
+## Usage Example
 
 ```ts
-const validators = await stakingApi.fetchValidators()
-console.dir(validators, { depth: null })
-```
----
+const vals = await stakingApi.fetchValidators()
+console.dir(vals, { depth: null })
+```
+
+## Example Response
+
+```json
+{
+  "validators": [
+    {
+      "operator_address": "zigvaloper1pwwymlyeyfcz3pjvcegvz8tj3yf0pr3wqqhrwk",
+      "consensus_pubkey": {
+        "@type": "/cosmos.crypto.ed25519.PubKey",
+        "key": "f+akljJ8Y0dKwWz3bKkRN+RDz9EM+yA/j7Gre+Hn02c="
+      },
+      "jailed": false,
+      "status": "BOND_STATUS_BONDED",
+      "tokens": "25350105116909",
+      "delegator_shares": "25350105116909.000000000000000000",
+      "description": {
+        "moniker": "ZIG Sentinel - Foundation 1",
+        "identity": "D752CA2B4A74AD75",
+        "website": "https://zigchain.com",
+        "security_contact": "",
+        "details": "The guardian of ZIGChain..."
+      },
+      "commission": {
+        "commission_rates": {
+          "rate": "0.050000000000000000",
+          "max_rate": "0.200000000000000000",
+          "max_change_rate": "0.010000000000000000"
+        },
+        "update_time": "2025-09-17T16:00:38.206163930Z"
+      },
+      "min_self_delegation": "1"
+    }
+  ],
+  "pagination": {
+    "next_key": null,
+    "total": "30"
+  }
+}
+```
+
+Each validator entry has the same structure as `fetchValidator` — refer to that section for the full field-by-field breakdown.
+
+## Response Field Explanation
+
+### `validators`
+
+Array of all registered validators. Each entry is identical in structure to the `validator` object returned by `fetchValidator`.
+
+
+### `fetchValidator` vs `fetchValidators`
+
+| Feature               | fetchValidator             | fetchValidators             |
+| --------------------- | -------------------------- | --------------------------- |
+| Scope                 | Single validator by address | All validators              |
+| Use case              | Specific validator lookup  | Full registry overview      |
+| Response size         | Minimal                    | Large (paginated)           |
+
+## When to Use
+
+* Building validator list pages in explorers or wallets
+* Letting users browse and compare validators before delegating
+* Calculating total network stake across all validators
+* Monitoring the active validator set
 
+---