@zuhaibnoor/zigchain-sdk 1.0.3 → 1.1.0

package/docs/evidence.md

@@ -0,0 +1,199 @@
+# Evidence Module
+
+The **Evidence module** exposes information about **misbehavior evidence** that has been submitted to the blockchain.
+Evidence is used by the network to **prove validator misbehavior**, such as double-signing or light-client attacks, and is a critical part of the **slashing and security mechanism** in Cosmos-SDK–based chains like ZigChain.
+
+This module allows developers to:
+
+* Inspect individual evidence records by hash
+* List all submitted evidence (paginated)
+
+All queries in this module use **LCD endpoints**.
+
+---
+
+## Initialization
+
+```ts
+import {
+  ChainEvidenceApi,
+  getNetworkEndpoints,
+  Network
+} from '@zuhaibnoor/zigchain-sdk'
+
+const endpoints = getNetworkEndpoints(Network.Testnet)
+const evidenceApi = new ChainEvidenceApi(endpoints)
+```
+
+---
+
+## `fetchEvidence`
+
+```ts
+async fetchEvidence(hash: string)
+```
+
+**CLI equivalent**
+
+```bash
+zigchaind query evidence evidence <hash>
+```
+
+### Description
+
+Fetches a **single evidence record** using its unique evidence hash.
+This is useful when you already know an evidence hash (for example, from logs, explorers, or governance discussions) and want to inspect the exact misbehavior details.
+
+### Parameters
+
+| Name   | Type     | Description                          |
+| ------ | -------- | ------------------------------------ |
+| `hash` | `string` | Unique hash identifying the evidence |
+
+### Example
+
+```ts
+const evidence = await evidenceApi.fetchEvidence(
+  'A1B2C3D4E5F6...'
+)
+
+console.dir(evidence, { depth: null })
+```
+
+### When to use
+
+* Inspect a **specific validator misbehavior**
+* Debug or audit slashing events
+* Explorer or monitoring tools
+
+---
+
+## `fetchAllEvidence`
+
+```ts
+async fetchAllEvidence()
+```
+
+**CLI equivalent**
+
+```bash
+zigchaind query evidence list
+```
+
+### Description
+
+Returns **all submitted evidence records** on the chain.
+The response is **paginated**, meaning large networks may return results in chunks.
+
+This method is ideal for:
+
+* Block explorers
+* Security dashboards
+* Chain analytics tools
+
+### Example
+
+```ts
+const allEvidence = await evidenceApi.fetchAllEvidence()
+console.dir(allEvidence, { depth: null })
+```
+
+### Notes
+
+* Evidence types can vary, so the `value` field is returned as a flexible structure.
+* Pagination info is included if the dataset is large.
+
+---
+
+## Response Types Overview
+
+### `Evidence`
+
+```ts
+{
+  type_url: string
+  value: any
+}
+```
+
+* `type_url` → Identifies the evidence type (e.g. double-sign evidence)
+* `value` → Evidence-specific data (structure depends on evidence type)
+
+---
+
+## Summary Table
+
+| Function           | CLI Command                                | Purpose                          |
+| ------------------ | ------------------------------------------ | -------------------------------- |
+| `fetchEvidence`    | `zigchaind query evidence evidence <hash>` | Query a specific evidence record |
+| `fetchAllEvidence` | `zigchaind query evidence list`            | List all submitted evidence      |
+
+---
+
+## How Evidence Works
+
+### Who Submits Evidence?
+
+Evidence is **not submitted by regular users**.
+
+It is submitted by:
+
+* **Validators** (automatically by their node software)
+* **Full nodes** that detect misbehavior
+* **Light clients** (for light-client attack proofs)
+
+In most cases, evidence is **automatically generated and broadcast** by the blockchain software when a validator’s misbehavior is detected.
+
+---
+
+### What Does Evidence Contain?
+
+Evidence is a **cryptographic proof** of validator misbehavior.
+It contains enough information for the blockchain to **verify the fault without trust**.
+
+Depending on the evidence type, it may include:
+
+* Validator consensus address
+* Block height at which misbehavior occurred
+* Conflicting block headers or signatures
+* Timestamp of the infraction
+* Power (stake) of the validator at that time
+
+Once verified, this evidence can trigger **slashing**, **jailing**, or **tombstoning** of the validator.
+
+---
+
+### Common Types of Evidence
+
+The Cosmos SDK currently supports multiple evidence types, including:
+
+* **Duplicate Vote Evidence**
+  Proof that a validator signed **two different blocks at the same height** (double-signing).
+
+* **Light Client Attack Evidence**
+  Proof of malicious behavior aimed at misleading light clients.
+
+Each evidence type is identified by its `type_url` field in the response.
+
+---
+
+### Why Evidence Is Important
+
+The Evidence module ensures:
+
+* **Network security** through objective proof
+* **Automatic punishment** without human intervention
+* **Trustless verification** of validator behavior
+
+Because evidence is cryptographically verifiable, it **cannot be faked or disputed** once accepted by the chain.
+
+---
+
+### Key Characteristics
+
+* Evidence is **immutable** once submitted
+* Evidence is **publicly queryable**
+* Evidence directly feeds into the **Slashing module**
+* Evidence is **time-sensitive** (old evidence may be rejected)
+
+

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,166 @@
+# Governance Module
+
+The **ChainGovApi** provides access to the on-chain governance system.
+It is used to query **proposals**, **votes**, **tallies**, **governance parameters**.
+
+---
+
+## Setup
+
+```ts
+import {
+  ChainGovApi,
+  getNetworkEndpoints,
+  Network,
+} from '@zuhaibnoor/zigchain-sdk'
+
+const endpoints = getNetworkEndpoints(Network.Testnet)
+const govApi = new ChainGovApi(endpoints)
+```
+
+---
+
+## `fetchConstitution`
+
+Fetch the **governance constitution** of the chain.
+
+**CLI equivalent**
+
+```bash
+zigchaind query gov constitution
+```
+
+**Method**
+
+```ts
+fetchConstitution()
+```
+
+**Example**
+
+```ts
+const constitution = await govApi.fetchConstitution()
+console.log(constitution)
+```
+
+---
+
+## `fetchProposal`
+
+Fetch a **single governance proposal by ID**.
+
+**CLI equivalent**
+
+```bash
+zigchaind query gov proposal <id>
+```
+
+**Method**
+
+```ts
+fetchProposal(proposalId: string | number)
+```
+
+**Parameters**
+
+* `proposalId` – Proposal ID to query.
+
+**Example**
+
+```ts
+const proposal = await govApi.fetchProposal(12)
+console.log(proposal)
+```
+
+---
+
+## `fetchAllProposals`
+
+Fetch **all governance proposals** on the chain.
+
+**CLI equivalent**
+
+```bash
+zigchaind query gov proposals
+```
+
+**Method**
+
+```ts
+fetchAllProposals()
+```
+
+**Example**
+
+```ts
+const proposals = await govApi.fetchAllProposals()
+console.log(proposals)
+```
+
+---
+
+## `fetchTally`
+
+Fetch the **vote tally for a proposal**.
+
+**CLI equivalent**
+
+```bash
+zigchaind query gov tally <proposal_id>
+```
+
+**Method**
+
+```ts
+fetchTally(proposalId: string | number)
+```
+
+**Parameters**
+
+* `proposalId` – Proposal ID to query tally for.
+
+**Example**
+
+```ts
+const tally = await govApi.fetchTally(12)
+console.log(tally)
+```
+
+---
+
+## `fetchParams`
+
+Fetch **governance module parameters** by type.
+
+**CLI equivalent**
+
+```bash
+zigchaind query gov params <params_type>
+```
+
+**Method**
+
+```ts
+fetchParams(params_type: string)
+```
+
+**Parameters**
+
+* `params_type` – Type of parameters to query
+  (e.g. `voting`, `deposit`, `tallying`).
+
+**Example**
+
+```ts
+const votingParams = await govApi.fetchParams('voting')
+console.log(votingParams)
+```
+
+---
+
+## Notes
+
+* All governance queries are **read-only**.
+* Parameter queries must specify a valid `params_type`.
+
+