@zuhaibnoor/zigchain-sdk 1.1.0 → 1.1.2

package/docs/evidence.md

@@ -1,18 +1,53 @@
 # 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.
+## What is the Evidence Module?
 
-This module allows developers to:
+The **Evidence module** is responsible for handling **cryptographic proof of validator misbehavior** on ZigChain.
 
-* Inspect individual evidence records by hash
-* List all submitted evidence (paginated)
+It allows the chain to objectively verify faults such as:
 
-All queries in this module use **LCD endpoints**.
+* Double-signing (signing two different blocks at the same height)
+* Or other consensus rule violations
+
+Once verified, this evidence is forwarded to the **Slashing module**, which may:
+
+* Slash validator stake
+* Jail the validator
+* Tombstone the validator (permanent ban)
+
+This module is part of ZigChain’s **core security layer**.
+
+---
+
+## Important Terminology
+
+### Evidence
+
+**Evidence** is a cryptographic proof that a validator violated consensus rules.
+
+It contains enough data for the blockchain to independently verify the misbehavior without trusting any party.
+
+Evidence is:
+
+* Public
+* Immutable once accepted
+* Automatically processed by the chain
 
 ---
 
-## Initialization
+### Evidence Hash
+
+Each evidence record has a **unique hash** that identifies it on-chain.
+
+This hash is used to query a specific evidence record via:
+
+```bash
+zigchaind query evidence evidence <hash>
+```
+
+---
+
+## Setup
 
 ```ts
 import {
@@ -27,30 +62,39 @@ const evidenceApi = new ChainEvidenceApi(endpoints)
 
 ---
 
-## `fetchEvidence`
+# 1️⃣ fetchEvidence
+
+## Method
 
 ```ts
 async fetchEvidence(hash: string)
 ```
 
-**CLI equivalent**
+## CLI Equivalent
 
 ```bash
 zigchaind query evidence evidence <hash>
 ```
 
-### Description
+## 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
+This is useful when:
 
-| Name   | Type     | Description                          |
-| ------ | -------- | ------------------------------------ |
-| `hash` | `string` | Unique hash identifying the evidence |
+* You obtained a hash from logs or an explorer
+* You are auditing a slashing event
+* You are investigating validator misbehavior
 
-### Example
+If the hash does not exist, the chain will return an error.
+
+## Parameters
+
+| Name | Type   | Description                                 |
+| ---- | ------ | ------------------------------------------- |
+| hash | string | Unique hash identifying the evidence record |
+
+## Usage Example
 
 ```ts
 const evidence = await evidenceApi.fetchEvidence(
@@ -60,140 +104,91 @@ const evidence = await evidenceApi.fetchEvidence(
 console.dir(evidence, { depth: null })
 ```
 
-### When to use
-
-* Inspect a **specific validator misbehavior**
-* Debug or audit slashing events
-* Explorer or monitoring tools
-
----
-
-## `fetchAllEvidence`
+## Response Structure
 
 ```ts
-async fetchAllEvidence()
+{
+  evidence: {
+    type_url: string
+    value: any
+  }
+}
 ```
 
-**CLI equivalent**
+### `evidence`
 
-```bash
-zigchaind query evidence list
-```
+| Field     | Description |
+----------|------------|
+| `type_url` | Identifies the evidence type (e.g., duplicate vote) |
+| `value`   | Evidence-specific structure (depends on type) |
 
-### Description
+## When to Use
 
-Returns **all submitted evidence records** on the chain.
-The response is **paginated**, meaning large networks may return results in chunks.
+* Debugging validator slashing
+* Explorer implementations
+* Governance/security monitoring
+* Auditing historical faults
 
-This method is ideal for:
+---
 
-* Block explorers
-* Security dashboards
-* Chain analytics tools
+# 2️⃣ fetchAllEvidence
 
-### Example
+## Method
 
 ```ts
-const allEvidence = await evidenceApi.fetchAllEvidence()
-console.dir(allEvidence, { depth: null })
+async fetchAllEvidence()
 ```
 
-### Notes
+## CLI Equivalent
 
-* Evidence types can vary, so the `value` field is returned as a flexible structure.
-* Pagination info is included if the dataset is large.
+```bash
+zigchaind query evidence list
+```
 
----
+## Description
 
-## Response Types Overview
+Returns **all submitted evidence records** currently stored on-chain.
 
-### `Evidence`
+On ZigChain testnet, this typically returns:
 
-```ts
+```json
 {
-  type_url: string
-  value: any
+  "evidence": [],
+  "pagination": {
+    "next_key": null,
+    "total": "0"
+  }
 }
 ```
 
-* `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**.
+This simply means no validator misbehavior has been recorded.
 
-It is submitted by:
+## Parameters
 
-* **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.
-
----
+None.
 
-### Common Types of Evidence
+## Usage Example
 
-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.
-
----
+```ts
+const allEvidence = await evidenceApi.fetchAllEvidence()
+console.dir(allEvidence, { depth: null })
+```
 
-### Key Characteristics
+## Response Structure
 
-* 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)
+```ts
+{
+  evidence: Evidence[]
+  pagination: {
+    next_key: string | null
+    total: string
+  }
+}
+```
 
+## When to Use
 
+* Building blockchain explorers
+* Monitoring validator behavior
+* Security dashboards
+---