@zuhaibnoor/zigchain-sdk 1.0.3 → 1.1.1

package/docs/feegrant.md

@@ -0,0 +1,206 @@
+# Feegrant Module
+
+## Module Overview
+
+The **Feegrant module** allows one account (**granter**) to **pay transaction fees for another account (**grantee**)**.
+This is useful when a user needs to submit transactions but does not have tokens to pay gas fees themselves.
+
+Fee grants are created **explicitly by the granter** and exist only between specific address pairs.
+
+---
+
+## When Should You Use Feegrant?
+
+* When an application wants to **sponsor transaction fees** for its users
+* When fees should be paid **from a different account**
+
+---
+
+## ChainFeegrantApi
+
+This module provides read-only access to fee grant information available on-chain.
+
+### `fetchGrant(granter, grantee)`
+
+**Purpose:**
+Fetch details of a fee grant between a specific granter and grantee.
+
+**What it tells you:**
+
+* Whether a fee grant exists
+* Spend limit (if any)
+* Expiration time (if set)
+
+**When to use:**
+
+* To check if a grantee is allowed to use the granter’s balance for fees
+* Before sending a transaction using fee grants
+
+---
+
+### `fetchGrantsByGrantee(grantee)`
+
+**Purpose:**
+Fetch all fee grants **received by a given grantee**.
+
+**What it tells you:**
+
+* Which accounts are paying fees for this grantee
+* Limits and expiration details for each grant
+
+**When to use:**
+
+* To show a user who is sponsoring their transaction fees
+* To decide which grant to use when multiple grants exist
+
+---
+
+### `fetchGrantsByGranter(granter)`
+
+**Purpose:**
+Fetch all fee grants **created by a given granter**.
+
+**What it tells you:**
+
+* Which accounts can use the granter’s tokens to pay fees
+* How much fee allowance has been given
+
+**When to use:**
+
+* To monitor sponsored users
+* To audit or manage fee sponsorships
+
+---
+
+## Important Notes
+
+* Fee grants **do not exist by default**
+* If no fee grants are created, queries will return **empty results**
+* There is **no global list of all fee grants** on the chain
+* Fee grants are always **address-to-address**
+
+---
+
+## Feegrant vs Authz (Clear & Simple)
+
+This section is critical, so let’s be **very explicit**.
+
+### Feegrant Module
+
+**What it controls:**
+👉 **Who pays the transaction fee**
+
+**What changes:**
+
+* The **fee** is paid by the granter
+* The **transaction content** still belongs to the sender
+
+**Example:**
+
+* Alice submits a transaction
+* Bob pays the gas fee for Alice
+* Alice’s transaction still affects Alice’s account, not Bob’s
+
+---
+
+### Authz Module
+
+**What it controls:**
+👉 **Who is allowed to submit transactions on someone else’s behalf**
+
+**What changes:**
+
+* One account submits transactions **for another account**
+* The transaction affects the **owner’s account**, not the sender
+
+**Example:**
+
+* Bob submits a transaction
+* The transaction modifies Alice’s account
+* Bob is acting *on behalf of Alice*
+
+---
+
+### Simple Comparison Table
+
+| Feature                  | Feegrant         | Authz              |
+| ------------------------ | ---------------- | ------------------ |
+| Pays transaction fee     | Someone else     | Sender             |
+| Submits transaction      | Original account | Authorized account |
+| Changes account state of | Sender           | Account owner      |
+| Main purpose             | Fee sponsorship  | Account delegation |
+
+---
+
+## Key Takeaway
+
+* **Feegrant = “Who pays the fee?”**
+* **Authz = “Who is allowed to submit the transaction?”**
+
+They solve **different problems** and are often used **together**, but they are **not the same**.
+
+Perfect 👍 — below is a **complete, copy-pasteable testing example** written exactly in the style you’ve been using for other modules.
+It’s **doc-ready**, beginner-friendly, and explains *what is being tested* and *why*.
+
+You can drop this straight into your **Feegrant module documentation**.
+
+---
+
+# Testing Example
+
+## Test Setup
+
+```ts
+import {
+  ChainFeegrantApi,
+  getNetworkEndpoints,
+  Network
+} from '@zuhaibnoor/zigchain-sdk'
+```
+
+---
+
+## Full Test Example
+
+```ts
+async function main() {
+  // 1. Select network
+  const endpoints = getNetworkEndpoints(Network.Testnet)
+
+  // 2. Initialize Feegrant module
+  const feegrant = new ChainFeegrantApi(endpoints)
+
+  // Replace these with REAL addresses that have an existing fee grant
+  const granter = 'zig1xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'
+  const grantee = 'zig1yyyyyyyyyyyyyyyyyyyyyyyyyyyyyy'
+
+  // --------------------------------------------------
+  // Query a specific fee grant (granter -> grantee)
+  // --------------------------------------------------
+  console.log('\n--- Fee Grant (Granter → Grantee) ---')
+  try {
+    const grant = await feegrant.fetchGrant(granter, grantee)
+    console.dir(grant, { depth: null })
+  } catch (err) {
+    console.log('No direct fee grant found between granter and grantee')
+  }
+
+  // --------------------------------------------------
+  // Query all grants received by a grantee
+  // --------------------------------------------------
+  console.log('\n--- Grants By Grantee ---')
+  const grantsByGrantee = await feegrant.fetchGrantsByGrantee(grantee)
+  console.dir(grantsByGrantee, { depth: null })
+
+  // --------------------------------------------------
+  // Query all grants created by a granter
+  // --------------------------------------------------
+  console.log('\n--- Grants By Granter ---')
+  const grantsByGranter = await feegrant.fetchGrantsByGranter(granter)
+  console.dir(grantsByGranter, { depth: null })
+}
+
+main()
+```
+
+---

package/docs/gov.md

@@ -0,0 +1,364 @@
+# Governance (Gov) Module
+
+## 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    |
+
+---
+
+## Setup
+
+```ts
+import {
+  ChainGovApi,
+  getNetworkEndpoints,
+  Network
+} from '@zuhaibnoor/zigchain-sdk'
+
+const endpoints = getNetworkEndpoints(Network.Testnet)
+const govApi = new ChainGovApi(endpoints)
+```
+
+---
+
+# 1️⃣ fetchConstitution
+
+## Method
+
+```ts
+async fetchConstitution()
+```
+
+## CLI Equivalent
+
+```bash
+zigchaind query gov constitution
+```
+
+## Description
+
+Returns the **chain constitution text**.
+
+This defines the high-level vision or guiding principle of ZigChain governance.
+
+### Example Response
+
+```json
+{
+  "constitution": "Enabling wealth generation to everyone."
+}
+```
+
+## When to Use
+
+* Display governance philosophy in explorers
+* Governance dashboards
+* Public documentation tools
+
+---
+
+# 2️⃣ fetchAllProposals
+
+## Method
+
+```ts
+async fetchAllProposals()
+```
+
+## CLI Equivalent
+
+```bash
+zigchaind query gov proposals
+```
+
+## Description
+
+Returns **all governance proposals** on the chain (paginated).
+
+On ZigChain testnet:
+
+```json
+{
+  "pagination": {
+    "next_key": null,
+    "total": "79"
+  }
+}
+```
+
+This means 79 proposals currently exist.
+
+## Usage Example
+
+```ts
+const proposals = await govApi.fetchAllProposals()
+console.dir(proposals, { depth: null })
+```
+
+## Response Structure
+
+Each proposal contains:
+
+| 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      |
+
+
+# 3️⃣ fetchProposal
+
+## Method
+
+```ts
+async fetchProposal(proposalId: string | number)
+```
+
+## 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 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
+
+---
+
+# 4️⃣ fetchTally
+
+## Method
+
+```ts
+async fetchTally(proposalId: string | number)
+```
+
+## CLI Equivalent
+
+```bash
+zigchaind query gov tally <proposal_id>
+```
+
+## Description
+
+Returns the **current or final vote tally** for a proposal.
+
+## Example Response
+
+```json
+{
+  "tally": {
+    "yes_count": "0",
+    "abstain_count": "0",
+    "no_count": "0",
+    "no_with_veto_count": "0"
+  }
+}
+```
+
+## When to Use
+
+* Live governance dashboards
+* Displaying vote breakdowns
+* Monitoring active proposals
+
+---
+
+# 5️⃣ fetchParams
+
+## Method
+
+```ts
+async fetchParams(params_type: string)
+```
+
+## CLI Equivalent
+
+```bash
+zigchaind query gov params <type>
+```
+
+Where `<type>` can be:
+
+* `deposit`
+* `voting`
+* `tallying`
+
+## Description
+
+Fetches governance parameters controlling proposal lifecycle rules.
+
+## Usage Example
+
+```ts
+await govApi.fetchParams("voting")
+await govApi.fetchParams("deposit")
+await govApi.fetchParams("tallying")
+```
+
+## Example (Voting Params)
+
+```json
+{
+  "voting_params": {
+    "voting_period": "600s"
+  }
+}
+```
+
+This means proposals remain open for voting for **600 seconds (10 minutes)**.
+
+## 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
+
+---
+
+## Summary Table
+
+| 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 |
+
+---
+