@zuhaibnoor/zigchain-sdk 1.0.3 → 1.1.1

package/docs/upgrade.md

@@ -0,0 +1,356 @@
+# Upgrade Module
+
+## What is the Upgrade Module?
+
+This **Upgrade module** allows you to query information about chain upgrades, including:
+
+* Current upgrade plans scheduled for the chain
+* Who has authority to schedule upgrades
+* Module versions currently running on the chain
+
+Its module is essential for:
+
+* Monitoring planned network upgrades
+* Verifying upgrade governance
+* Tracking module versions across the network
+* Planning infrastructure updates
+
+---
+
+# Important Terminology
+
+Before documenting functions, let's define key terms.
+
+### Upgrade Plan
+
+An **Upgrade Plan** is a scheduled network upgrade that will happen at a specific block height.
+
+An upgrade plan contains:
+
+* **Name** – Identifier for the upgrade
+* **Height** – Block number when the upgrade takes effect
+* **Info** – Description of what changes
+
+Example:
+
+```json
+{
+  "name": "v2.0.0",
+  "height": 5000000,
+  "info": "Major network upgrade with new features"
+}
+```
+
+⚠️ If no upgrade is currently planned, the plan will be `null`.
+
+---
+
+### Upgrade Authority
+
+The **Upgrade Authority** is the address that has permission to schedule network upgrades.
+
+Only this address can propose and approve upgrade plans (via governance).
+
+Example:
+
+```
+zig10d07y265gmmuvt4z0w9aw880jnsr700jmgkh5m
+```
+
+---
+
+### Module Version
+
+Each **module** running on the chain has a **version number**.
+
+Modules are components of the blockchain (e.g., `bank`, `staking`, `auth`).
+
+Example module:
+
+```json
+{
+  "name": "bank",
+  "version": "4"
+}
+```
+
+---
+
+# Functions Documentation
+
+Setup:
+```ts
+import {
+  ChainUpgradeApi,
+  getNetworkEndpoints,
+  Network
+} from '@zuhaibnoor/zigchain-sdk'
+
+const endpoints = getNetworkEndpoints(Network.Testnet)
+const upgradeApi = new ChainUpgradeApi(endpoints)
+```
+
+---
+
+# 1️⃣ fetchCurrentPlan
+
+## Method
+
+```ts
+async fetchCurrentPlan(): Promise<CurrentPlanResponse>
+```
+
+## CLI Equivalent
+
+```bash
+zigchaind query upgrade plan
+```
+
+## Description
+
+Fetches the **current upgrade plan** scheduled on the chain.
+
+Returns:
+
+* Plan name
+* Target block height
+* Plan description
+
+If no upgrade is planned, returns `plan: null`.
+
+## Parameters
+
+None.
+
+## Usage Example
+
+```ts
+const plan = await upgradeApi.fetchCurrentPlan()
+console.dir(plan, { depth: null })
+```
+
+## Example Response
+
+### When an Upgrade is Planned
+
+```json
+{
+  "plan": {
+    "name": "v2.0.0",
+    "time": "0001-01-01T00:00:00Z",
+    "height": "5000000",
+    "info": "Major network upgrade introducing new governance features and performance improvements",
+    "upgraded_client_state": null
+  }
+}
+```
+
+### When No Upgrade is Planned
+
+```json
+{
+  "plan": null
+}
+```
+
+## Response Field Explanation
+
+### `plan`
+
+The upgrade plan object, or `null` if no upgrade is scheduled.
+
+If present, contains:
+
+| Field                    | Description                                    |
+| ------------------------ | ---------------------------------------------- |
+| name                     | Name/identifier of the upgrade                 |
+| time                     | Estimated time          |
+| height                   | Block height when upgrade takes effect         |
+| info                     | Human-readable description of changes          |
+| upgraded_client_state    | IBC client state after upgrade      |
+
+## When to Use
+
+* Monitoring network upgrade schedules
+* Planning infrastructure maintenance
+* Setting up notifications for upcoming upgrades
+* Building chain status dashboards
+* Verifying upgrade timing
+
+---
+
+# 2️⃣ fetchAuthority
+
+## Method
+
+```ts
+async fetchAuthority(): Promise<UpgradeAuthorityResponse>
+```
+
+## CLI Equivalent
+
+```bash
+zigchaind query upgrade authority
+```
+
+## Description
+
+Fetches the **address with authority to schedule upgrades**.
+
+This is the account that can propose and execute upgrade plans through governance.
+
+## Parameters
+
+None.
+
+## Usage Example
+
+```ts
+const authority = await upgradeApi.fetchAuthority()
+console.dir(authority, { depth: null })
+```
+
+## Example Response
+
+```json
+{
+  "address": "zig10d07y265gmmuvt4z0w9aw880jnsr700jmgkh5m"
+}
+```
+
+## Response Field Explanation
+
+| Field   | Description                                  |
+| ------- | -------------------------------------------- |
+| address | Bech32 address of the upgrade authority      |
+
+## When to Use
+
+* Auditing governance configuration
+* Verifying upgrade permissions
+* Building chain dashboards
+* Security analysis
+* Understanding governance structure
+
+---
+
+# 3️⃣ fetchModuleVersions
+
+## Method
+
+```ts
+async fetchModuleVersions(): Promise<ModuleVersionsResponse>
+```
+
+## CLI Equivalent
+
+```bash
+zigchaind query upgrade module-versions
+```
+## Description
+
+Fetches the **versions of all modules** running on the chain.
+
+Returns a list of every module with its current version number.
+
+This helps track which features and improvements are active on the network.
+
+## Parameters
+
+None.
+
+## Usage Example
+
+```ts
+const versions = await upgradeApi.fetchModuleVersions()
+console.dir(versions, { depth: null })
+```
+
+## Example Response
+
+```json
+{
+  "module_versions": [
+    { "name": "06-solomachine", "version": "0" },
+    { "name": "07-tendermint", "version": "0" },
+    { "name": "auth", "version": "5" },
+    { "name": "authz", "version": "2" },
+    { "name": "bank", "version": "4" },
+    { "name": "circuit", "version": "1" },
+    { "name": "consensus", "version": "1" },
+    { "name": "crisis", "version": "2" },
+    { "name": "dex", "version": "2" },
+    { "name": "distribution", "version": "3" },
+    { "name": "evidence", "version": "1" },
+    { "name": "factory", "version": "2" },
+    { "name": "feegrant", "version": "2" },
+    { "name": "genutil", "version": "1" },
+    { "name": "gov", "version": "5" },
+    { "name": "group", "version": "2" },
+    { "name": "ibc", "version": "8" },
+    { "name": "interchainaccounts", "version": "3" },
+    { "name": "mint", "version": "2" },
+    { "name": "nft", "version": "1" },
+    { "name": "packetfowardmiddleware", "version": "3" },
+    { "name": "params", "version": "1" },
+    { "name": "ratelimit", "version": "1" },
+    { "name": "runtime", "version": "0" },
+    { "name": "slashing", "version": "4" },
+    { "name": "staking", "version": "5" },
+    { "name": "tokenwrapper", "version": "2" },
+    { "name": "transfer", "version": "6" },
+    { "name": "upgrade", "version": "2" },
+    { "name": "vesting", "version": "1" },
+    { "name": "wasm", "version": "4" }
+  ]
+}
+```
+
+## Response Field Explanation
+
+### `module_versions`
+
+Array of module version objects.
+
+Each entry contains:
+
+| Field   | Description              |
+| ------- | ------------------------ |
+| name    | Module name/identifier   |
+| version | Current version number   |
+
+
+## Common ZigChain Modules
+
+| Module Name              | Purpose                                    |
+| ------------------------ | ------------------------------------------ |
+| `auth`                   | Account authentication and management      |
+| `authz`                  | Authorization and delegation               |
+| `bank`                   | Token transfers and balances               |
+| `consensus`              | Consensus parameters                       |
+| `dex`                    | Decentralized exchange                     |
+| `distribution`           | Validator reward distribution              |
+| `factory`                | Token factory for creating new assets      |
+| `gov`                    | On-chain governance and voting             |
+| `group`                  | Group account management                   |
+| `ibc`                    | Inter-Blockchain Communication             |
+| `interchainaccounts`     | IBC account abstraction                    |
+| `mint`                   | Token minting and inflation                |
+| `nft`                    | NFT module                                 |
+| `slashing`               | Validator punishment for misbehavior       |
+| `staking`                | Validator staking and delegation           |
+| `transfer`               | IBC asset transfers                        |
+| `upgrade`                | Network upgrade management                 |
+| `wasm`                   | Smart contracts (WebAssembly)              |
+
+## When to Use
+
+* Checking which features are available on the chain
+* Verifying module compatibility
+* Building chain status dashboards
+* Comparing module versions across networks
+* Planning development based on module versions
+* Auditing chain capabilities
+
+---
+

package/docs/validator-set.md

@@ -0,0 +1,177 @@
+# Validator Set
+
+## What is the Validator Set?
+
+The **Validator Set** is the active set of nodes currently responsible for producing and signing blocks on ZigChain.
+
+At any given block height, a fixed set of validators participates in  consensus. Each validator has a voting power proportional to their stake, and one validator is selected as the **proposer** for each block based on a weighted round-robin algorithm driven by `proposer_priority`.
+
+---
+
+## Important Terminology
+
+### Validator
+
+A **validator** is a node actively participating in block production. They are identified here by their **consensus address** (`zigvalcons...`), which is distinct from their operator address (`zigvaloper...`) used in the staking module.
+
+---
+
+### Consensus Address
+
+The `zigvalcons` address is the validator's identity. It is derived from their Ed25519 consensus public key.
+
+Example:
+```
+zigvalcons15hcvyh2h0rrzrsswzu67s83z2v462rantszqnx
+```
+
+> This is different from the validator's staking operator address (`zigvaloper...`). The consensus address is used for block signing; the operator address is used for staking operations.
+
+---
+
+### Voting Power
+
+A validator's **voting power** is their relative weight in the consensus process. It is proportional to the amount of stake bonded to that validator.
+
+---
+
+### Proposer Priority
+
+An internal numeric value used by CometBFT's weighted round-robin algorithm to determine which validator proposes the next block. It adjusts each round based on voting power — validators with higher voting power propose more frequently.
+
+This value oscillates between positive and negative and is not directly meaningful on its own.
+
+---
+
+### Historical Validator Set
+
+The validator set is **not static** — validators can be added or removed via staking and governance. Querying at a specific height shows the exact set that was active at that point in chain history.
+
+Comparing the validator set across heights lets you track validator churn — for example, the set at height `4009281` had 7 validators while the set at height `4646865` has 8, indicating a new validator joined during that period.
+
+---
+
+## Setup
+
+```ts
+import {
+  ChainValidatorSetApi,
+  getNetworkEndpoints,
+  Network,
+} from '@zuhaibnoor/zigchain-sdk'
+
+const endpoints = getNetworkEndpoints(Network.Testnet)
+const validatorApi = new ChainValidatorSetApi(endpoints)
+```
+
+---
+
+# 1️⃣ fetchValidatorSet
+
+## Method
+
+```ts
+async fetchValidatorSet(height?: number | string)
+```
+
+## CLI Equivalent
+
+```bash
+# Latest validator set
+zigchaind query comet-validator-set
+
+# Validator set at a specific height
+zigchaind query comet-validator-set <height>
+```
+
+## Description
+
+Fetches the **full validator set** — either at the latest block or at a specific historical height.
+
+Each entry in the set includes the validator's consensus address, their public key, current voting power, and proposer priority. This is the consensus-layer view of validators, as opposed to the staking-layer view available through the staking module.
+
+Omit `height` to get the current active validator set. Pass a height to inspect the set at any past block.
+
+## Parameters
+
+| Name   | Type             | Required | Description                                               |
+| ------ | ---------------- | -------- | --------------------------------------------------------- |
+| height | number \| string | ❌ No    | Block height to query. Omit for the latest validator set. |
+
+## Usage Example
+
+**Latest validator set:**
+
+```ts
+const validatorSet = await validatorApi.fetchValidatorSet()
+console.dir(validatorSet, { depth: null })
+```
+
+**Validator set at a specific height:**
+
+```ts
+const validatorSetAtHeight = await validatorApi.fetchValidatorSet('4009281')
+console.dir(validatorSetAtHeight, { depth: null })
+```
+
+## Example Response
+
+```json
+{
+  "block_height": "4646865",
+  "validators": [
+    {
+      "address": "zigvalcons15hcvyh2h0rrzrsswzu67s83z2v462rantszqnx",
+      "pub_key": {
+        "@type": "/cosmos.crypto.ed25519.PubKey",
+        "key": "f+akljJ8Y0dKwWz3bKkRN+RDz9EM+yA/j7Gre+Hn02c="
+      },
+      "voting_power": "25350158",
+      "proposer_priority": "17577896"
+    },
+    {
+      "address": "zigvalcons13atuu9t8ryjaq6a5a3twjc2nudh7l6uemvgmes",
+      "pub_key": {
+        "@type": "/cosmos.crypto.ed25519.PubKey",
+        "key": "SBjHwAbgG2ZfZtbBMJgcr+z+S/2BuPQZROVLnvS4QHM="
+      },
+      "voting_power": "25227820",
+      "proposer_priority": "28755507"
+    }
+  ],
+  "pagination": {
+    "next_key": null,
+    "total": "8"
+  }
+}
+```
+
+## Response Field Explanation
+
+### Top-level fields
+
+| Field        | Description                                          |
+| ------------ | ---------------------------------------------------- |
+| block_height | The block height this validator set corresponds to   |
+| validators   | Array of all active validators at this height        |
+| pagination   | Pagination info for the validator list               |
+
+### `validators[]` — Per-Validator Entry
+
+| Field             | Description                                                              |
+| ----------------- | ------------------------------------------------------------------------ |
+| address           | Validator's consensus address (`zigvalcons...`)                          |
+| pub_key.@type     | Cryptographic key type — always `ed25519` for CometBFT validators        |
+| pub_key.key       | Base64-encoded Ed25519 public key used for block signing                 |
+| voting_power      | Validator's weighted vote in consensus, proportional to bonded stake     |
+| proposer_priority | Internal CometBFT value used to select the next block proposer           |
+
+---
+
+## When to Use
+
+* Displaying the active validator set in a block explorer
+* Checking current voting power distribution
+* Tracking validator set changes over time
+* Verifying which validators were active at a specific block
+---