@zuhaibnoor/zigchain-sdk 1.1.0 → 1.1.1

package/docs/gov.md

@@ -1,7 +1,82 @@
-# Governance Module
+# Governance (Gov) Module
 
-The **ChainGovApi** provides access to the on-chain governance system.
-It is used to query **proposals**, **votes**, **tallies**, **governance parameters**.
+## What is the Gov Module?
+
+The **Governance (Gov) module** enables **on-chain decision making** on ZigChain.
+
+It allows token holders to:
+
+* Submit proposals
+* Deposit tokens to activate proposals
+* Vote on proposals
+* Update critical chain parameters
+
+Governance is how ZigChain evolves — parameter changes, validator set updates and other core settings are modified through this module.
+
+---
+
+## Governance Flow (High Level)
+
+1. A proposer submits a proposal
+2. Deposits are collected
+3. Voting period begins
+4. Validators & delegators vote
+5. Tally is calculated
+6. Proposal is **Passed** or **Rejected**
+7. If passed → state changes are executed automatically
+
+---
+
+## Important Terminology
+
+### Proposal
+
+A **proposal** is a request to modify the chain state.
+
+Each proposal contains:
+
+* `messages` → The actual state-changing messages (e.g., `MsgUpdateParams`)
+* `title` and `summary`
+* Voting period timestamps
+* Final tally result
+* Status
+
+---
+
+### Proposal Status
+
+| Status                           | Meaning                    |
+| -------------------------------- | -------------------------- |
+| `PROPOSAL_STATUS_DEPOSIT_PERIOD` | Waiting for enough deposit |
+| `PROPOSAL_STATUS_VOTING_PERIOD`  | Voting is ongoing          |
+| `PROPOSAL_STATUS_PASSED`         | Approved and executed      |
+| `PROPOSAL_STATUS_REJECTED`       | Did not pass               |
+| `PROPOSAL_STATUS_FAILED`         | Execution failed           |
+
+---
+
+### Tally
+
+The **tally** is the final vote count:
+
+* `yes_count`
+* `no_count`
+* `abstain_count`
+* `no_with_veto_count`
+
+Governance parameters define quorum and thresholds required for passing.
+
+---
+
+### Governance Parameters
+
+Governance behavior is controlled by three parameter groups:
+
+| Type       | Controls                         |
+| ---------- | -------------------------------- |
+| `deposit`  | Minimum deposit & deposit period |
+| `voting`   | Voting duration                  |
+| `tallying` | Quorum, threshold, veto rules    |
 
 ---
 
@@ -11,7 +86,7 @@ It is used to query **proposals**, **votes**, **tallies**, **governance paramete
 import {
   ChainGovApi,
   getNetworkEndpoints,
-  Network,
+  Network
 } from '@zuhaibnoor/zigchain-sdk'
 
 const endpoints = getNetworkEndpoints(Network.Testnet)
@@ -20,147 +95,270 @@ const govApi = new ChainGovApi(endpoints)
 
 ---
 
-## `fetchConstitution`
+# 1️⃣ fetchConstitution
 
-Fetch the **governance constitution** of the chain.
+## Method
 
-**CLI equivalent**
+```ts
+async fetchConstitution()
+```
+
+## CLI Equivalent
 
 ```bash
 zigchaind query gov constitution
 ```
 
-**Method**
+## Description
 
-```ts
-fetchConstitution()
-```
+Returns the **chain constitution text**.
 
-**Example**
+This defines the high-level vision or guiding principle of ZigChain governance.
 
-```ts
-const constitution = await govApi.fetchConstitution()
-console.log(constitution)
+### Example Response
+
+```json
+{
+  "constitution": "Enabling wealth generation to everyone."
+}
 ```
 
+## When to Use
+
+* Display governance philosophy in explorers
+* Governance dashboards
+* Public documentation tools
+
 ---
 
-## `fetchProposal`
+# 2️⃣ fetchAllProposals
 
-Fetch a **single governance proposal by ID**.
+## Method
 
-**CLI equivalent**
+```ts
+async fetchAllProposals()
+```
+
+## CLI Equivalent
 
 ```bash
-zigchaind query gov proposal <id>
+zigchaind query gov proposals
 ```
 
-**Method**
+## Description
 
-```ts
-fetchProposal(proposalId: string | number)
-```
+Returns **all governance proposals** on the chain (paginated).
+
+On ZigChain testnet:
 
-**Parameters**
+```json
+{
+  "pagination": {
+    "next_key": null,
+    "total": "79"
+  }
+}
+```
 
-* `proposalId` – Proposal ID to query.
+This means 79 proposals currently exist.
 
-**Example**
+## Usage Example
 
 ```ts
-const proposal = await govApi.fetchProposal(12)
-console.log(proposal)
+const proposals = await govApi.fetchAllProposals()
+console.dir(proposals, { depth: null })
 ```
 
----
+## Response Structure
 
-## `fetchAllProposals`
+Each proposal contains:
 
-Fetch **all governance proposals** on the chain.
+| Field              | Description                    |
+| ------------------ | ------------------------------ |
+| id                 | Unique proposal ID             |
+| messages           | State-changing messages        |
+| status             | Proposal status                |
+| final_tally_result | Vote counts                    |
+| submit_time        | Submission timestamp           |
+| voting_start_time  | Voting start                   |
+| voting_end_time    | Voting end                     |
+| total_deposit      | Deposited tokens               |
+| proposer           | Address of proposer            |
+| expedited          | Whether proposal was expedited |
+| failed_reason      | Reason if rejected/failed      |
 
-**CLI equivalent**
 
-```bash
-zigchaind query gov proposals
-```
+# 3️⃣ fetchProposal
 
-**Method**
+## Method
 
 ```ts
-fetchAllProposals()
+async fetchProposal(proposalId: string | number)
 ```
 
-**Example**
+## CLI Equivalent
+
+```bash
+zigchaind query gov proposal <id>
+```
+
+## Description
+
+Fetches detailed information for a **single proposal**.
+
+## Parameters
+
+| Name       | Type            | Description        |
+| ---------- | --------------- | ------------------ |
+| proposalId | string | number | ID of the proposal |
+
+## Usage Example
 
 ```ts
-const proposals = await govApi.fetchAllProposals()
-console.log(proposals)
+const proposal = await govApi.fetchProposal(59)
+console.dir(proposal, { depth: null })
 ```
 
+## Example Response (Simplified)
+
+```json
+{
+  "proposal": {
+    "id": "59",
+    "status": "PROPOSAL_STATUS_REJECTED",
+    "title": "Proposal test",
+    "failed_reason": "proposal did not get enough votes to pass"
+  }
+}
+```
+
+## When to Use
+
+* Viewing detailed proposal metadata
+* Explorer proposal pages
+* Governance analytics
+
 ---
 
-## `fetchTally`
+# 4️⃣ fetchTally
 
-Fetch the **vote tally for a proposal**.
+## Method
 
-**CLI equivalent**
+```ts
+async fetchTally(proposalId: string | number)
+```
+
+## CLI Equivalent
 
 ```bash
 zigchaind query gov tally <proposal_id>
 ```
 
-**Method**
+## Description
 
-```ts
-fetchTally(proposalId: string | number)
-```
+Returns the **current or final vote tally** for a proposal.
 
-**Parameters**
+## Example Response
 
-* `proposalId` – Proposal ID to query tally for.
+```json
+{
+  "tally": {
+    "yes_count": "0",
+    "abstain_count": "0",
+    "no_count": "0",
+    "no_with_veto_count": "0"
+  }
+}
+```
 
-**Example**
+## When to Use
 
-```ts
-const tally = await govApi.fetchTally(12)
-console.log(tally)
-```
+* Live governance dashboards
+* Displaying vote breakdowns
+* Monitoring active proposals
 
 ---
 
-## `fetchParams`
+# 5️⃣ fetchParams
 
-Fetch **governance module parameters** by type.
+## Method
 
-**CLI equivalent**
+```ts
+async fetchParams(params_type: string)
+```
+
+## CLI Equivalent
 
 ```bash
-zigchaind query gov params <params_type>
+zigchaind query gov params <type>
 ```
 
-**Method**
+Where `<type>` can be:
+
+* `deposit`
+* `voting`
+* `tallying`
+
+## Description
+
+Fetches governance parameters controlling proposal lifecycle rules.
+
+## Usage Example
 
 ```ts
-fetchParams(params_type: string)
+await govApi.fetchParams("voting")
+await govApi.fetchParams("deposit")
+await govApi.fetchParams("tallying")
 ```
 
-**Parameters**
+## Example (Voting Params)
 
-* `params_type` – Type of parameters to query
-  (e.g. `voting`, `deposit`, `tallying`).
+```json
+{
+  "voting_params": {
+    "voting_period": "600s"
+  }
+}
+```
 
-**Example**
+This means proposals remain open for voting for **600 seconds (10 minutes)**.
 
-```ts
-const votingParams = await govApi.fetchParams('voting')
-console.log(votingParams)
+## Example (Tallying Params)
+
+```json
+{
+  "tally_params": {
+    "quorum": "0.334",
+    "threshold": "0.51",
+    "veto_threshold": "0.334"
+  }
+}
 ```
 
+### Field Explanation
+
+| Field          | Meaning                            |
+| -------------- | ---------------------------------- |
+| quorum         | Minimum participation required     |
+| threshold      | % of yes votes required to pass    |
+| veto_threshold | % of veto votes required to reject |
+
+## When to Use
+
+* Governance analytics tools
+* Chain configuration dashboards
+
 ---
 
-## Notes
+## Summary Table
 
-* All governance queries are **read-only**.
-* Parameter queries must specify a valid `params_type`.
+| Function            | CLI Command                         | Purpose                     |
+| ------------------- | ----------------------------------- | --------------------------- |
+| `fetchConstitution` | `zigchaind query gov constitution`  | Fetch chain constitution    |
+| `fetchAllProposals` | `zigchaind query gov proposals`     | List all proposals          |
+| `fetchProposal`     | `zigchaind query gov proposal <id>` | Get single proposal details |
+| `fetchTally`        | `zigchaind query gov tally <id>`    | Get vote tally              |
+| `fetchParams`       | `zigchaind query gov params <type>` | Fetch governance parameters |
 
+---