@zuhaibnoor/zigchain-sdk 1.1.0 → 1.1.1

package/docs/slashing.md

@@ -1,11 +1,65 @@
 # Slashing Module
 
-The **ChainSlashingApi** lets you query slashing-related data.
-It is used to fetch **slashing parameters** and **validator signing information**, which helps track validator uptime and potential slashing conditions.
+## What is the Slashing Module?
+
+The **Slashing module** enforces validator accountability.
+
+It penalizes validators for:
+
+* Double-signing blocks
+* Missing too many blocks (downtime)
+
+Penalties may include:
+
+* Token slashing (stake reduction)
+* Temporary jailing
+* Permanent tombstoning (for double-signing)
+
+This module ensures network security and validator reliability.
+
+---
+
+# Important Terminology
+
+### Validator Consensus Address (`valcons`)
+
+A special validator address used for consensus-level operations.
+
+Example:
+
+```text
+zigvalcons1qd9g9rwjmgs7k02w65t2hlekc39vnqsq0ajs47
+```
+
+Used when querying signing information.
+
+---
+
+### Signed Blocks Window
+
+Number of recent blocks tracked for validator uptime.
+
+---
+
+### Missed Blocks Counter
+
+Number of missed blocks within the tracking window.
+
+---
+
+### Tombstoned
+
+If `true`, the validator permanently double-signed and can never rejoin the validator set.
 
 ---
 
-## Setup
+### Jail
+
+Temporary removal from the validator set due to downtime.
+
+---
+
+# Setup
 
 ```ts
 import {
@@ -20,120 +74,214 @@ const slashingApi = new ChainSlashingApi(endpoints)
 
 ---
 
-## `fetchParams`
+# 1️⃣ fetchParams
 
-Fetch the **slashing module parameters**.
+## Method
+
+```ts
+async fetchParams()
+```
 
-**CLI equivalent**
+## CLI Equivalent
 
 ```bash
 zigchaind query slashing params
 ```
 
-**Method**
+## Description
 
-```ts
-fetchParams()
-```
+Fetches the **slashing module parameters** that define:
+
+* Uptime requirements
+* Jail duration
+* Slashing percentages
+
+## Parameters
+
+None.
 
-**Example**
+## Usage Example
 
 ```ts
 const params = await slashingApi.fetchParams()
 console.dir(params, { depth: null })
 ```
 
+## Example Response
+
+```json
+{
+  "params": {
+    "signed_blocks_window": "35000",
+    "min_signed_per_window": "0.800000000000000000",
+    "downtime_jail_duration": "600s",
+    "slash_fraction_double_sign": "0.000500000000000000",
+    "slash_fraction_downtime": "0.000100000000000000"
+  }
+}
+```
+
+## Response Field Explanation
+
+| Field                      | Description                                      |
+| -------------------------- | ------------------------------------------------ |
+| signed_blocks_window       | Number of blocks tracked for validator uptime    |
+| min_signed_per_window      | Minimum percentage of blocks that must be signed |
+| downtime_jail_duration     | Time a validator remains jailed for downtime     |
+| slash_fraction_double_sign | Percentage slashed for double-signing            |
+| slash_fraction_downtime    | Percentage slashed for excessive downtime        |
+
+### Example Interpretation
+
+```text
+min_signed_per_window = 0.8 → validator must sign 80% of 35,000 blocks
+downtime_jail_duration = 600s → jailed for 10 minutes
+```
+
 ---
 
-## `fetchSigningInfos`
+# 2️⃣ fetchSigningInfos
 
-Fetch **signing information for all validators**.
-This includes missed blocks, start height, and jail status.
+## Method
+
+```ts
+async fetchSigningInfos()
+```
 
-**CLI equivalent**
+## CLI Equivalent
 
 ```bash
 zigchaind query slashing signing-infos
 ```
 
-**Method**
+## Description
 
-```ts
-fetchSigningInfos()
-```
+Fetches **signing information for all validators**.
+
+Includes:
+
+* Start height
+* Jail status
+* Missed block count
+* Tombstone status
+
+## Parameters
 
-**Example**
+None.
+
+## Usage Example
 
 ```ts
 const infos = await slashingApi.fetchSigningInfos()
 console.log(infos)
 ```
 
+## Example Response (Truncated)
+
+```json
+{
+  "info": [
+    {
+      "address": "zigvalcons1qd9g9rwjmgs7k02w65t2hlekc39vnqsq0ajs47",
+      "start_height": "3909190",
+      "index_offset": "724541",
+      "jailed_until": "1970-01-01T00:00:00Z",
+      "tombstoned": false,
+      "missed_blocks_counter": "0"
+    }
+  ],
+  "pagination": {
+    "next_key": null,
+    "total": "8"
+  }
+}
+```
+
 ---
 
-## `fetchSigningInfo`
+## Signing Info Field Explanation
 
-Fetch **signing information for a specific validator** using its **consensus address**.
+| Field                 | Description                         |
+| --------------------- | ----------------------------------- |
+| address               | Validator consensus address         |
+| start_height          | Block height when tracking started  |
+| index_offset          | Internal block tracking offset      |
+| jailed_until          | Timestamp until validator is jailed |
+| tombstoned            | Permanent ban indicator             |
+| missed_blocks_counter | Number of missed blocks             |
 
-**CLI equivalent**
+### Jail Status Interpretation
 
-```bash
-zigchaind query slashing signing-info <valcons-address>
+If:
+
+```text
+jailed_until = 1970-01-01T00:00:00Z
 ```
 
-**Method**
+The validator is **not currently jailed**.
 
-```ts
-fetchSigningInfo(valConsAddress: string)
-```
+If the timestamp is in the future → validator is jailed.
+
+---
 
-**Example**
+# 3️⃣ fetchSigningInfo
+
+## Method
 
 ```ts
-const signingInfo = await slashingApi.fetchSigningInfo(
-  'zigvalcons1qd9g9rwjmgs7k02w65t2hlekc39vnqsq0ajs47'
-)
+async fetchSigningInfo(valConsAddress: string)
+```
+
+## CLI Equivalent
 
-console.dir(signingInfo, { depth: null })
+```bash
+zigchaind query slashing signing-info <valcons-address>
 ```
 
----
+## Description
 
-## Example (Full)
+Fetches signing information for a **specific validator** using its consensus address.
 
-```ts
-import {
-  ChainSlashingApi,
-  getNetworkEndpoints,
-  Network
-} from '@zuhaibnoor/zigchain-sdk'
+## Parameters
+
+| Parameter      | Type   | Description                             |
+| -------------- | ------ | --------------------------------------- |
+| valConsAddress | string | Validator consensus (`valcons`) address |
 
-async function main() {
-  const endpoints = getNetworkEndpoints(Network.Testnet)
-  const slashingApi = new ChainSlashingApi(endpoints)
+## Usage Example
 
-  console.log('--- Slashing Params ---')
-  const params = await slashingApi.fetchParams()
-  console.dir(params, { depth: null })
+```ts
+const singleInfo = await slashingApi.fetchSigningInfo(
+  'zigvalcons1qd9g9rwjmgs7k02w65t2hlekc39vnqsq0ajs47'
+)
 
-  console.log('\n--- All Signing Infos ---')
-  const infos = await slashingApi.fetchSigningInfos()
-  console.log(infos)
+console.dir(singleInfo, { depth: null })
+```
 
-  console.log('\n--- Single Signing Info ---')
-  const singleInfo = await slashingApi.fetchSigningInfo(
-    'zigvalcons1qd9g9rwjmgs7k02w65t2hlekc39vnqsq0ajs47'
-  )
-  console.dir(singleInfo, { depth: null })
+## Example Response
+
+```json
+{
+  "val_signing_info": {
+    "address": "zigvalcons1qd9g9rwjmgs7k02w65t2hlekc39vnqsq0ajs47",
+    "start_height": "3909190",
+    "index_offset": "724541",
+    "jailed_until": "1970-01-01T00:00:00Z",
+    "tombstoned": false,
+    "missed_blocks_counter": "0"
+  }
 }
-
-main()
 ```
 
 ---
 
-## Notes
+# Summary
 
-* Slashing queries are **read-only** and require no wallet.
-* All slashing queries are performed via **LCD endpoints**.
+| Function              | CLI Equivalent                                    | Purpose                                 |
+| --------------------- | ------------------------------------------------- | --------------------------------------- |
+| `fetchParams()`       | `zigchaind query slashing params`                 | Returns slashing configuration          |
+| `fetchSigningInfos()` | `zigchaind query slashing signing-infos`          | Returns signing info for all validators |
+| `fetchSigningInfo()`  | `zigchaind query slashing signing-info <valcons>` | Returns signing info for one validator  |
+
+---