@zuhaibnoor/zigchain-sdk 1.0.3 → 1.1.1

package/docs/slashing.md

@@ -0,0 +1,287 @@
+# Slashing Module
+
+## 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.
+
+---
+
+### Jail
+
+Temporary removal from the validator set due to downtime.
+
+---
+
+# Setup
+
+```ts
+import {
+  ChainSlashingApi,
+  getNetworkEndpoints,
+  Network,
+} from '@zuhaibnoor/zigchain-sdk'
+
+const endpoints = getNetworkEndpoints(Network.Testnet)
+const slashingApi = new ChainSlashingApi(endpoints)
+```
+
+---
+
+# 1️⃣ fetchParams
+
+## Method
+
+```ts
+async fetchParams()
+```
+
+## CLI Equivalent
+
+```bash
+zigchaind query slashing params
+```
+
+## Description
+
+Fetches the **slashing module parameters** that define:
+
+* Uptime requirements
+* Jail duration
+* Slashing percentages
+
+## Parameters
+
+None.
+
+## 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
+```
+
+---
+
+# 2️⃣ fetchSigningInfos
+
+## Method
+
+```ts
+async fetchSigningInfos()
+```
+
+## CLI Equivalent
+
+```bash
+zigchaind query slashing signing-infos
+```
+
+## Description
+
+Fetches **signing information for all validators**.
+
+Includes:
+
+* Start height
+* Jail status
+* Missed block count
+* Tombstone status
+
+## Parameters
+
+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"
+  }
+}
+```
+
+---
+
+## Signing Info Field Explanation
+
+| 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             |
+
+### Jail Status Interpretation
+
+If:
+
+```text
+jailed_until = 1970-01-01T00:00:00Z
+```
+
+The validator is **not currently jailed**.
+
+If the timestamp is in the future → validator is jailed.
+
+---
+
+# 3️⃣ fetchSigningInfo
+
+## Method
+
+```ts
+async fetchSigningInfo(valConsAddress: string)
+```
+
+## CLI Equivalent
+
+```bash
+zigchaind query slashing signing-info <valcons-address>
+```
+
+## Description
+
+Fetches signing information for a **specific validator** using its consensus address.
+
+## Parameters
+
+| Parameter      | Type   | Description                             |
+| -------------- | ------ | --------------------------------------- |
+| valConsAddress | string | Validator consensus (`valcons`) address |
+
+## Usage Example
+
+```ts
+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"
+  }
+}
+```
+
+---
+
+# Summary
+
+| 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  |
+
+---
+