@zuhaibnoor/zigchain-sdk 1.0.3 → 1.1.1

package/docs/distribution.md

@@ -0,0 +1,772 @@
+# Distribution Module
+
+## What is the Distribution Module?
+
+The **Distribution module** is a core Cosmos SDK module responsible for **collecting and distributing staking rewards** on ZigChain.
+
+Every block, newly minted tokens and transaction fees flow through this module. It handles splitting rewards between validators (as commission) and delegators (as staking rewards), maintains the community pool, and tracks outstanding and withdrawn amounts for every participant.
+
+---
+
+## Important Terminology
+
+### Staking Rewards
+
+When you delegate tokens to a validator, you earn a share of the block rewards proportional to your stake. These accumulate over time and must be explicitly withdrawn.
+
+---
+
+### Validator Commission
+
+A **commission** is the percentage of delegator rewards that a validator keeps for themselves as payment for running the node. The remaining portion flows to delegators.
+
+Commission accumulates continuously and is tracked separately from delegator rewards.
+
+---
+
+### Community Pool
+
+A portion of every block reward (defined by `community_tax`) is sent to the **community pool** — a shared on-chain treasury. These funds can only be spent via governance proposals.
+
+---
+
+### Withdraw Address
+
+By default, a delegator's rewards are sent to their own address when withdrawn. A delegator can optionally configure a **custom withdraw address** — a different address where rewards will be sent instead.
+
+---
+
+### Community Tax
+
+The fraction of each block reward that is diverted to the community pool before distributing the remainder to validators and delegators.
+
+```
+community_tax = 0.02  →  2% of all block rewards go to the community pool
+```
+
+---
+
+### Outstanding Rewards
+
+Rewards that have been earned but **not yet withdrawn**. These accumulate on-chain until the validator or delegator explicitly claims them.
+
+---
+
+## Setup
+
+```ts
+import {
+  ChainDistributionApi,
+  getNetworkEndpoints,
+  Network,
+} from '@zuhaibnoor/zigchain-sdk'
+
+const endpoints = getNetworkEndpoints(Network.Testnet)
+const distributionApi = new ChainDistributionApi(endpoints)
+
+const delegator = 'zig1q8uh4ytf632jqykrd4m0weuzq9uv4r4jzra9h6'
+const validator = 'zigvaloper1pwwymlyeyfcz3pjvcegvz8tj3yf0pr3wqqhrwk'
+```
+
+---
+
+# 1️⃣ fetchParams
+
+## Method
+
+```ts
+async fetchParams()
+```
+
+## CLI Equivalent
+
+```bash
+zigchaind query distribution params
+```
+
+## Description
+
+Fetches the **Distribution module parameters** configured at chain level.
+
+These are governance-controlled settings that define how block rewards are split across the community pool, validators, and delegators. The most important parameter is `community_tax` — the fraction of every block reward redirected to the community pool before validator and delegator distribution.
+
+## Parameters
+
+None.
+
+## Usage Example
+
+```ts
+const params = await distributionApi.fetchParams()
+console.dir(params, { depth: null })
+```
+
+## Example Response
+
+```json
+{
+  "params": {
+    "community_tax": "0.020000000000000000",
+    "base_proposer_reward": "0.000000000000000000",
+    "bonus_proposer_reward": "0.000000000000000000",
+    "withdraw_addr_enabled": true
+  }
+}
+```
+
+## Response Field Explanation
+
+### `params`
+
+| Field                  | Description                                                                             |
+| ---------------------- | --------------------------------------------------------------------------------------- |
+| community_tax          | Fraction of each block reward sent to the community pool (`0.02` = 2%)                 |
+| base_proposer_reward   | Base bonus reward for the block proposer. Set to `0` on ZigChain                       |
+| bonus_proposer_reward  | Additional bonus for proposers based on included votes. Set to `0` on ZigChain         |
+| withdraw_addr_enabled  | Whether delegators can set a custom reward withdrawal address (`true` = enabled)        |
+
+> On ZigChain, both proposer reward bonuses are set to `0`, meaning all validators earn equal reward rates regardless of whether they proposed the block. The 2% community tax applies to every block.
+
+## When to Use
+
+* Understanding how block rewards are split at the protocol level
+* Verifying whether custom withdraw addresses are enabled
+* Governance monitoring for parameter change proposals
+
+---
+
+# 2️⃣ fetchCommunityPool
+
+## Method
+
+```ts
+async fetchCommunityPool()
+```
+
+## CLI Equivalent
+
+```bash
+zigchaind query distribution community-pool
+```
+
+## Description
+
+Fetches the **current balance of the community pool**.
+
+The community pool accumulates 2% of every block reward continuously. The balance shown includes fractional amounts tracked with high precision — these accumulate as decimal remainders from reward calculations.
+
+## Parameters
+
+None.
+
+## Usage Example
+
+```ts
+const pool = await distributionApi.fetchCommunityPool()
+console.dir(pool, { depth: null })
+```
+
+## Example Response
+
+```json
+{
+  "pool": [
+    {
+      "denom": "uzig",
+      "amount": "243098073712.963766803812287124"
+    }
+  ]
+}
+```
+
+## Response Field Explanation
+
+### `pool`
+
+Array of coin balances in the community pool. Currently only `uzig` accumulates here on ZigChain testnet.
+
+| Field  | Description                                                                       |
+| ------ | --------------------------------------------------------------------------------- |
+| denom  | Token denomination in the pool                                                    |
+| amount | High-precision decimal balance — includes fractional `uzig` from reward rounding  |
+
+## When to Use
+
+* Governance dashboards displaying available community funds
+* Tracking community pool growth over time
+* Calculating how much is available for governance spending proposals
+
+---
+
+# 3️⃣ fetchDelegatorValidators
+
+## Method
+
+```ts
+async fetchDelegatorValidators(delegator: string)
+```
+
+## CLI Equivalent
+
+```bash
+zigchaind query distribution delegator-validators <delegator>
+```
+
+## Description
+
+Fetches the **list of validators a delegator is currently earning rewards from**.
+
+This returns only validators with active delegations from the given address — validators where the delegator has staked tokens and is accumulating rewards. It does not include validators with zero delegation.
+
+---
+
+## Parameters
+
+| Name      | Type   | Description                                    |
+| --------- | ------ | ---------------------------------------------- |
+| delegator | string | Bech32 address of the delegator to query       |
+
+---
+
+## Usage Example
+
+```ts
+const delegatorValidators = await distributionApi.fetchDelegatorValidators(delegator)
+console.dir(delegatorValidators, { depth: null })
+```
+
+## Example Response
+
+```json
+{
+  "validators": [
+    "zigvaloper1q8uh4ytf632jqykrd4m0weuzq9uv4r4jhy3rkr"
+  ]
+}
+```
+
+## Response Field Explanation
+
+### `validators`
+
+Array of validator operator addresses (`zigvaloper...`) from which this delegator is earning rewards.
+
+| Field      | Description                                                             |
+| ---------- | ----------------------------------------------------------------------- |
+| validators | List of validator operator addresses with active delegations            |
+
+> In the example, this delegator has staked with exactly one validator. A delegator who has spread stake across multiple validators will see multiple entries here.
+
+## When to Use
+
+* Displaying a delegator's active staking positions
+* Wallet dashboards showing which validators a user is staked with
+* Building staking portfolio views
+
+---
+
+# 4️⃣ fetchDelegatorWithdrawAddress
+
+## Method
+
+```ts
+async fetchDelegatorWithdrawAddress(delegator: string)
+```
+
+## CLI Equivalent
+
+```bash
+zigchaind query distribution delegator-withdraw-address <delegator>
+```
+
+## Description
+
+Fetches the **reward withdrawal address** configured for a delegator.
+
+By default, this matches the delegator's own address. If the delegator has set a custom withdraw address, rewards will be sent there instead when claimed. This is useful for directing rewards to a separate cold wallet or treasury address.
+
+---
+
+## Parameters
+
+| Name      | Type   | Description                                      |
+| --------- | ------ | ------------------------------------------------ |
+| delegator | string | Bech32 address of the delegator to query         |
+
+---
+
+## Usage Example
+
+```ts
+const withdrawAddr = await distributionApi.fetchDelegatorWithdrawAddress(delegator)
+console.dir(withdrawAddr, { depth: null })
+```
+
+## Example Response
+
+```json
+{
+  "withdraw_address": "zig1q8uh4ytf632jqykrd4m0weuzq9uv4r4jzra9h6"
+}
+```
+
+## Response Field Explanation
+
+| Field            | Description                                                                         |
+| ---------------- | ----------------------------------------------------------------------------------- |
+| withdraw_address | Address where rewards will be sent when the delegator withdraws. Defaults to the delegator's own address. |
+
+> When `withdraw_address` matches the delegator's own address (as in the example), no custom withdraw address has been set — this is the default state.
+
+## When to Use
+
+* Verifying where a delegator's rewards will be sent before withdrawal
+* Wallet UIs displaying reward destination
+* Confirming a custom withdraw address was set correctly
+
+---
+
+# 5️⃣ fetchValidatorCommission
+
+## Method
+
+```ts
+async fetchValidatorCommission(validator: string)
+```
+
+## CLI Equivalent
+
+```bash
+zigchaind query distribution commission <validator>
+```
+
+## Description
+
+Fetches the **accumulated commission** that a validator has earned but not yet withdrawn.
+
+Commission is the validator's share of delegator rewards, taken at the validator's configured commission rate each block. It accumulates continuously until the validator explicitly withdraws it.
+
+## Parameters
+
+| Name      | Type   | Description                                           |
+| --------- | ------ | ----------------------------------------------------- |
+| validator | string | Validator operator address (`zigvaloper...`) to query |
+
+## Usage Example
+
+```ts
+const commission = await distributionApi.fetchValidatorCommission(validator)
+console.dir(commission, { depth: null })
+```
+
+## Example Response
+
+```json
+{
+  "commission": {
+    "commission": [
+      {
+        "denom": "uzig",
+        "amount": "221571475888.997127352507253303"
+      }
+    ]
+  }
+}
+```
+
+## Response Field Explanation
+
+### `commission.commission`
+
+Array of outstanding commission amounts per denom.
+
+| Field  | Description                                                                        |
+| ------ | ---------------------------------------------------------------------------------- |
+| denom  | Token denomination of the commission                                               |
+| amount | High-precision accumulated commission amount not yet withdrawn by the validator    |
+
+> `221571475888 uzig` ≈ 221,571 ZIG in outstanding commission for this validator — reflecting the high activity of a top validator on ZigChain testnet.
+
+## When to Use
+
+* Validator dashboards showing pending commission to withdraw
+* Comparing commission accumulation across validators
+
+---
+
+# 6️⃣ fetchDelegatorRewards
+
+## Method
+
+```ts
+async fetchDelegatorRewards(delegator: string)
+```
+
+## CLI Equivalent
+
+```bash
+zigchaind query distribution rewards <delegator-address>
+```
+
+## Description
+
+Fetches **all pending staking rewards** accumulated by a delegator across every validator they are staked with.
+
+Returns a per-validator breakdown of rewards as well as the combined total across all validators. Rewards accumulate each block and remain here until the delegator explicitly withdraws them.
+
+## Parameters
+
+| Name      | Type   | Description                                    |
+| --------- | ------ | ---------------------------------------------- |
+| delegator | string | Bech32 address of the delegator to query       |
+
+## Usage Example
+
+```ts
+const rewards = await distributionApi.fetchDelegatorRewards(delegator)
+console.dir(rewards, { depth: null })
+```
+
+## Example Response
+
+```json
+{
+  "rewards": [
+    {
+      "validator_address": "zigvaloper1q8uh4ytf632jqykrd4m0weuzq9uv4r4jhy3rkr",
+      "reward": []
+    }
+  ],
+  "total": []
+}
+```
+
+## Response Field Explanation
+
+### `rewards`
+
+Array of per-validator reward entries for this delegator.
+
+| Field             | Description                                                              |
+| ----------------- | ------------------------------------------------------------------------ |
+| validator_address | Validator operator address this reward entry is associated with          |
+| reward            | Array of pending reward coins from this validator. Empty if none pending |
+
+### `total`
+
+Aggregated rewards across all validators combined.
+
+| Field | Description                                                           |
+| ----- | --------------------------------------------------------------------- |
+| total | Array of total pending reward coins. Empty if no rewards are pending  |
+
+
+## When to Use
+
+* Wallet dashboards displaying a user's total pending rewards
+* Showing per-validator reward breakdown before withdrawal
+* Calculating total claimable rewards across all staking positions
+
+---
+
+# 7️⃣ fetchDelegatorRewardsByValidator
+
+## Method
+
+```ts
+async fetchDelegatorRewardsByValidator(delegator: string, validator: string)
+```
+
+## CLI Equivalent
+
+```bash
+zigchaind query distribution rewards-by-validator <delegator> <validator>
+```
+
+## Description
+
+Fetches the **pending rewards earned by a delegator from a single specific validator**.
+
+This is the targeted alternative to `fetchDelegatorRewards` — use this when you only need the reward from one particular validator rather than the full cross-validator breakdown.
+
+## Parameters
+
+| Name      | Type   | Description                                             |
+| --------- | ------ | ------------------------------------------------------- |
+| delegator | string | Bech32 address of the delegator                         |
+| validator | string | Validator operator address (`zigvaloper...`) to query   |
+
+## Usage Example
+
+```ts
+const rewardsByVal = await distributionApi.fetchDelegatorRewardsByValidator(
+  delegator,
+  'zigvaloper1q8uh4ytf632jqykrd4m0weuzq9uv4r4jhy3rkr'
+)
+console.dir(rewardsByVal, { depth: null })
+```
+
+## Example Response
+
+```json
+{
+  "rewards": []
+}
+```
+
+## Response Field Explanation
+
+### `rewards`
+
+Array of pending reward coins from this specific validator.
+
+| Field   | Description                                                             |
+| ------- | ----------------------------------------------------------------------- |
+| rewards | Array of coin amounts pending from this validator. Empty if none pending |
+
+### `fetchDelegatorRewards` vs `fetchDelegatorRewardsByValidator`
+
+| Feature                    | fetchDelegatorRewards       | fetchDelegatorRewardsByValidator  |
+| -------------------------- | --------------------------- | --------------------------------- |
+| Scope                      | All validators              | Single validator only             |
+| Includes total             | ✅ Yes                      | ❌ No                             |
+| Use case                   | Full portfolio rewards view | Per-validator reward inspection   |
+
+## When to Use
+
+* Per-validator reward analytics
+* Validator-specific staking dashboards
+* Comparing reward rates across different validators a delegator uses
+
+---
+
+# 8️⃣ fetchValidatorSlashes
+
+## Method
+
+```ts
+async fetchValidatorSlashes(validator: string)
+```
+
+## CLI Equivalent
+
+```bash
+zigchaind query distribution slashes <validator-address>
+```
+
+## Description
+
+Fetches the **slashing history** of a specific validator.
+
+A slash is a penalty applied to a validator (and proportionally to their delegators) for misbehaviour — such as double signing a block or extended downtime. Each slash event records the period it occurred in and the fraction of stake that was penalized.
+
+An empty `slashes` array means the validator has **no recorded slashing events** — a good sign of validator reliability.
+
+## Parameters
+
+| Name      | Type   | Description                                           |
+| --------- | ------ | ----------------------------------------------------- |
+| validator | string | Validator operator address (`zigvaloper...`) to query |
+
+## Usage Example
+
+```ts
+const slashes = await distributionApi.fetchValidatorSlashes(validator)
+console.dir(slashes, { depth: null })
+```
+
+## Example Response
+
+```json
+{
+  "slashes": [],
+  "pagination": {
+    "next_key": null,
+    "total": "0"
+  }
+}
+```
+
+## Response Field Explanation
+
+### `slashes`
+
+Array of slashing events applied to this validator. Empty means no slashes on record.
+
+If slash events are present, each entry would contain:
+
+| Field            | Description                                                          |
+| ---------------- | -------------------------------------------------------------------- |
+| validator_period | The distribution period during which the slash occurred              |
+| fraction         | The fraction of stake that was slashed (e.g. `0.05` = 5% penalty)   |
+
+### `pagination`
+
+| Field    | Description                                          |
+| -------- | ---------------------------------------------------- |
+| next_key | Cursor for next page. `null` if all results returned |
+| total    | Total number of slash events recorded                |
+
+> `total: '0'` for this validator confirms a clean slashing history — no misbehaviour has been recorded.
+
+## When to Use
+
+* Assessing validator reliability before delegating
+* Building validator comparison and reputation dashboards
+* Monitoring validators for new slash events
+
+---
+
+# 9️⃣ fetchValidatorDistributionInfo
+
+## Method
+
+```ts
+async fetchValidatorDistributionInfo(validator: string)
+```
+
+## CLI Equivalent
+
+```bash
+zigchaind query distribution validator-distribution-info <validator-address>
+```
+
+## Description
+
+Fetches a **complete distribution overview for a validator**, including their self-bond rewards and accumulated commission — all in a single query.
+
+This is the most comprehensive single-call view of a validator's earnings from the distribution module. It shows both the rewards earned on the validator's own staked tokens and the commission earned from delegator rewards.
+
+## Parameters
+
+| Name      | Type   | Description                                           |
+| --------- | ------ | ----------------------------------------------------- |
+| validator | string | Validator operator address (`zigvaloper...`) to query |
+
+## Usage Example
+
+```ts
+const distInfo = await distributionApi.fetchValidatorDistributionInfo(validator)
+console.dir(distInfo, { depth: null })
+```
+
+## Example Response
+
+```json
+{
+  "operator_address": "zig1pwwymlyeyfcz3pjvcegvz8tj3yf0pr3w48m900",
+  "self_bond_rewards": [
+    {
+      "denom": "uzig",
+      "amount": "744261754912.141600000000000000"
+    }
+  ],
+  "commission": [
+    {
+      "denom": "uzig",
+      "amount": "221589430188.073196173617296226"
+    }
+  ]
+}
+```
+
+## Response Field Explanation
+
+| Field             | Description                                                                         |
+| ----------------- | ----------------------------------------------------------------------------------- |
+| operator_address  | The validator's account address (`zig...`) — where rewards are sent on withdrawal   |
+| self_bond_rewards | Pending rewards earned on the validator's own self-delegated stake                  |
+| commission        | Pending commission accumulated from delegator rewards, not yet withdrawn            |
+
+### `self_bond_rewards` and `commission`
+
+Both fields are arrays of coin amounts with high-precision decimal values:
+
+| Field  | Description                                                   |
+| ------ | ------------------------------------------------------------- |
+| denom  | Token denomination                                            |
+| amount | High-precision accumulated amount including decimal remainder |
+
+> For this validator: ~744,261 ZIG in self-bond rewards and ~221,589 ZIG in commission are outstanding — both reflecting a high-activity top validator on ZigChain testnet.
+
+### Total Validator Earnings Breakdown
+
+| Source            | Field              | Description                              |
+| ----------------- | ------------------ | ---------------------------------------- |
+| Own stake rewards | self_bond_rewards  | Earned as a delegator on own validator   |
+| Commission        | commission         | Earned as a percentage of delegator rewards |
+
+## When to Use
+
+* Validator dashboards showing total pending earnings in one call
+* Comparing validator self-bond rewards vs commission income
+* Calculating total validator revenue for analytics
+---
+
+# 🔟 fetchValidatorOutstandingRewards
+
+## Method
+
+```ts
+async fetchValidatorOutstandingRewards(validator: string)
+```
+
+## CLI Equivalent
+
+```bash
+zigchaind query distribution validator-outstanding-rewards <validator-address>
+```
+
+---
+
+## Description
+
+Fetches the **total outstanding rewards** for a validator — the sum of all unwithdrawn rewards across all delegations to that validator, plus the validator's own pending commission and self-bond rewards.
+
+This represents the complete pool of rewards sitting in the distribution module that are attributable to this validator, across every participant who has not yet withdrawn.
+
+---
+
+## Parameters
+
+| Name      | Type   | Description                                           |
+| --------- | ------ | ----------------------------------------------------- |
+| validator | string | Validator operator address (`zigvaloper...`) to query |
+
+---
+
+## Usage Example
+
+```ts
+const outstanding = await distributionApi.fetchValidatorOutstandingRewards(validator)
+console.dir(outstanding, { depth: null })
+```
+
+## Example Response
+
+```json
+{
+  "rewards": {
+    "rewards": [
+      {
+        "denom": "uzig",
+        "amount": "985083471414.779638309606269193"
+      }
+    ]
+  }
+}
+```
+
+## Response Field Explanation
+
+### `rewards.rewards`
+
+Array of total outstanding reward amounts across all delegations to this validator.
+
+| Field  | Description                                                                       |
+| ------ | --------------------------------------------------------------------------------- |
+| denom  | Token denomination                                                                |
+| amount | Total unwithdrawn rewards attributable to this validator, with high-precision decimals |
+
+
+---