@zuhaibnoor/zigchain-sdk 1.0.3 → 1.1.1

package/docs/staking.md

@@ -0,0 +1,756 @@
+# STAKING Module
+
+## What is STAKING?
+
+**Staking** in the Cosmos ecosystem (including **ZigChain**) allows token holders to:
+
+* Delegate tokens to validators
+* Earn rewards
+* Participate in network security
+
+The staking module tracks delegations, validators, and staking parameters.
+
+---
+
+# Important Terminology
+
+### Delegator
+
+A user who locks tokens by delegating to a validator.
+
+### Validator
+
+An entity responsible for validating blocks.
+
+### Delegation
+
+Tokens staked by a delegator to a validator.
+
+### Shares
+
+Proportional representation of a delegator’s stake in the validator.
+
+---
+
+# Functions Documentation
+
+Setup:
+
+```ts
+import {
+  ChainStakingApi,
+  getNetworkEndpoints,
+  Network
+} from '@zuhaibnoor/zigchain-sdk'
+
+const endpoints = getNetworkEndpoints(Network.Testnet)
+const stakingApi = new ChainStakingApi(endpoints)
+
+const delegator = 'zig1q8uh4ytf632jqykrd4m0weuzq9uv4r4jzra9h6'
+const validator = 'zigvaloper1q8uh4ytf632jqykrd4m0weuzq9uv4r4jhy3rkr'
+```
+
+---
+
+# 1️⃣ fetchDelegations
+
+## Method
+
+```ts
+async fetchDelegations(delegatorAddress: string)
+```
+
+## CLI Equivalent
+
+```bash
+zigchaind query staking delegations <delegator>
+```
+
+## Description
+
+Query all delegations made by a delegator.
+
+
+## Parameters
+
+| Name             | Type   | Description                     |
+| ---------------- | ------ | ------------------------------- |
+| delegatorAddress | string | Bech32 address of the delegator |
+
+## Usage Example
+
+```ts
+const delegations = await stakingApi.fetchDelegations(delegator)
+console.dir(delegations, { depth: null })
+```
+
+
+
+## Example Response
+
+```json
+{
+  "delegation_responses": [
+    {
+      "delegation": {
+        "delegator_address": "zig1q8uh4ytf632jqykrd4m0weuzq9uv4r4jzra9h6",
+        "validator_address": "zigvaloper1q8uh4ytf632jqykrd4m0weuzq9uv4r4jhy3rkr",
+        "shares": "1500000.000000000000000000"
+      },
+      "balance": { "denom": "uzig", "amount": "1500000" }
+    }
+  ],
+  "pagination": { "next_key": null, "total": "1" }
+}
+```
+
+---
+
+## Response Field Explanation
+
+| 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                      |
+
+---
+
+# 2️⃣ fetchDelegation
+
+## Method
+
+```ts
+async fetchDelegation(delegatorAddress: string, validatorAddress: string)
+```
+
+## CLI Equivalent
+
+```bash
+zigchaind query staking delegation <delegator> <validator>
+```
+
+## Description
+
+Query a **single delegation** from a delegator to a specific validator.
+
+## Parameters
+
+| Name             | Type   | Description                     |
+| ---------------- | ------ | ------------------------------- |
+| delegatorAddress | string | Bech32 address of the delegator |
+| validatorAddress | string | Bech32 address of the validator |
+
+## Usage Example
+
+```ts
+const delegation = await stakingApi.fetchDelegation(delegator, validator)
+console.dir(delegation, { 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
+
+| 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              |
+
+---
+
+# 3️⃣ fetchValidatorDelegations
+
+## Method
+
+```ts
+async fetchValidatorDelegations(validator_addr: string)
+```
+
+## CLI Equivalent
+
+```bash
+zigchaind query staking delegations-to <validator>
+```
+
+## Description
+
+Fetch all delegations to a specific validator.
+
+## Parameters
+
+| Name           | Type   | Description                     |
+| -------------- | ------ | ------------------------------- |
+| validator_addr | string | Bech32 address of the validator |
+
+## Usage Example
+
+```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" }
+}
+```
+
+---
+
+# 4️⃣ fetchDelegatorValidator
+
+## Method
+
+```ts
+async fetchDelegatorValidator(delegatorAddress: string, validatorAddress: string)
+```
+
+## CLI Equivalent
+
+```bash
+zigchaind query staking delegator-validator <delegator> <validator>
+```
+
+## Description
+
+Query validator info for a specific delegator-validator pair.
+
+## Parameters
+
+| Name             | Type   | Description              |
+| ---------------- | ------ | ------------------------ |
+| delegatorAddress | string | Bech32 delegator address |
+| validatorAddress | string | Bech32 validator address |
+
+## Usage Example
+
+```ts
+const delegatorValidator = await stakingApi.fetchDelegatorValidator(delegator, validator)
+console.dir(delegatorValidator, { depth: null })
+```
+
+## Example Response
+
+*(Same as `fetchDelegation` — returns validator object.)*
+
+---
+
+# 5️⃣ fetchDelegatorValidators
+
+## Method
+
+```ts
+async fetchDelegatorValidators(delegatorAddress: string)
+```
+
+## CLI Equivalent
+
+```bash
+zigchaind query staking delegator-validators <delegator>
+```
+
+## Description
+
+Fetch info of **all validators** a delegator has delegated to.
+
+## Parameters
+
+| Name             | Type   | Description              |
+| ---------------- | ------ | ------------------------ |
+| delegatorAddress | string | Bech32 delegator address |
+
+---
+
+## Usage Example
+
+```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" }
+}
+```
+
+---
+
+# 6️⃣ fetchStakingParams
+
+## Method
+
+```ts
+async fetchStakingParams()
+```
+
+## CLI Equivalent
+
+```bash
+zigchaind query staking params
+```
+
+## Description
+
+Fetches chain-level **staking module parameters**.
+
+## Parameters
+
+None.
+
+## Usage Example
+
+```ts
+const params = await stakingApi.fetchStakingParams()
+console.dir(params, { depth: null })
+```
+
+## Example Response
+
+```json
+{
+  "params": {
+    "unbonding_time": "604800s",
+    "max_validators": 8,
+    "max_entries": 8,
+    "historical_entries": 10000,
+    "bond_denom": "uzig",
+    "min_commission_rate": "0.000000000000000000"
+  }
+}
+```
+
+## Response Field Explanation
+
+| 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          |
+
+---
+
+Here's batch 1 of the Staking module documentation:
+
+---
+
+
+# fetchStakingPool
+
+## Method
+
+```ts
+async fetchStakingPool()
+```
+
+## CLI Equivalent
+
+```bash
+zigchaind query staking pool
+```
+
+## Description
+
+Fetches the **chain-wide staking pool** — the total accounting of all bonded and non-bonded tokens across every validator.
+
+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.
+
+## Parameters
+
+None.
+
+## Usage Example
+
+```ts
+const pool = await stakingApi.fetchStakingPool()
+console.dir(pool, { depth: null })
+```
+
+## Example Response
+
+```json
+{
+  "pool": {
+    "not_bonded_tokens": "108314438077",
+    "bonded_tokens": "101692473101453"
+  }
+}
+```
+
+## Response Field Explanation
+
+### `pool`
+
+| 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  |
+
+---
+
+# fetchRedelegation
+
+## Method
+
+```ts
+async fetchRedelegation(delegator_addr: string)
+```
+
+## CLI Equivalent
+
+```bash
+zigchaind query staking redelegation <delegator-address>
+```
+
+## Description
+
+Fetches all **active redelegations** for a specific delegator.
+
+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.
+
+An empty `redelegation_responses` array means the delegator has no active redelegations in progress.
+
+## Parameters
+
+| Name           | Type   | Description                                      |
+| -------------- | ------ | ------------------------------------------------ |
+| delegator_addr | string | Bech32 address of the delegator to query         |
+
+## Usage Example
+
+```ts
+const redelegations = await stakingApi.fetchRedelegation(delegator)
+console.dir(redelegations, { depth: null })
+```
+
+## Example Response
+
+```json
+{
+  "redelegation_responses": [],
+  "pagination": {
+    "next_key": null,
+    "total": "0"
+  }
+}
+```
+
+## Response Field Explanation
+
+### `redelegation_responses`
+
+Array of active redelegation entries for this delegator. Empty if no redelegations are in progress.
+
+If entries are present, each would contain:
+
+| 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                        |
+
+
+
+---
+
+# fetchValidator
+
+## Method
+
+```ts
+async fetchValidator(validator: string)
+```
+
+## CLI Equivalent
+
+```bash
+zigchaind query staking validator <validator-address>
+```
+
+## Description
+
+Fetches the **full details of a single validator** by their operator address.
+
+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.
+
+## Parameters
+
+| Name      | Type   | Description                                           |
+| --------- | ------ | ----------------------------------------------------- |
+| validator | string | Validator operator address (`zigvaloper...`) to query |
+
+## Usage Example
+
+```ts
+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                                |
+
+
+---
+
+# 4️⃣ fetchValidators
+
+## Method
+
+```ts
+async fetchValidators()
+```
+
+## CLI Equivalent
+
+```bash
+zigchaind query staking validators
+```
+
+## Description
+
+Fetches **all validators** registered on the chain — both active (bonded) and inactive (unbonded), including jailed validators.
+
+## Parameters
+
+None.
+
+## Usage Example
+
+```ts
+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
+
+---