docs: explain slashing mechanism (#1273)

* docs: explain slashing mechanism * docs: update parameters for slashing * docs: link specificationss page * Update developers/slashing.md Co-authored-by: Josh Stein <[email protected]> * Apply suggestions from code review Co-authored-by: Rootul P <[email protected]> * docs: correct and improve explanations * docs: move slashing doc to node operators section * Apply suggestions from code review --------- Co-authored-by: Josh Stein <[email protected]> Co-authored-by: Rootul P <[email protected]>
celestiaorg · Jan 31, 2024 · ea57962 · ea57962
1 parent 2bec065
commit ea57962
Show file tree

Hide file tree

Showing 2 changed files with 41 additions and 0 deletions.
diff --git a/.vitepress/config.ts b/.vitepress/config.ts
@@ -472,6 +472,10 @@ function sidebarHome() {
                   text: "Multisig",
                   link: "/nodes/celestia-app-multisig",
                 },
+                {
+                  text: "Slashing mechanics",
+                  link: "/nodes/celestia-app-slashing",
+                },
                 {
                   text: "Specifications",
                   link: "https://celestiaorg.github.io/celestia-app/",

diff --git a/nodes/celestia-app-slashing.md b/nodes/celestia-app-slashing.md
@@ -0,0 +1,37 @@
+---
+description: This section covers the slashing mechanics for validators in Celestia.
+---
+
+# Slashing on Celestia
+
+Slashing is a mechanism employed in proof of stake blockchains
+that is used to deter and punish malicious behavior.
+It functions by removing a percentage of a validator's stake
+each time they act harmfully towards the network.
+
+Celestia is built with the Cosmos SDK and uses the `x/slashing` module.
+
+If a validator gets slashed, delegators bonded to that validator will also
+have the same percentage of their delegated funds slashed.
+
+The following are the conditions for a validator to get slashed:
+
+1. **Downtime**: If a validator is offline for more than 25% of a rolling window
+   of the last 5,000 blocks, they will be jailed for 1 minute.
+   During this period, the validator is removed from the validator set
+   temporarily, and will be unable to propose new blocks or earn rewards.
+   After the jail period, the validator can send an unjail request to
+   rejoin the validator set.
+
+2. **Double signing**: This is a more severe offense and results in a larger
+   percentage loss. If a validator engages in double signing, the validator
+   will lose 2% of their stake and the remainder of their stake
+   will be returned to them. The validator will be permanently removed
+   from the validator set and will not have the ability to unjail.
+   Delegators bonded to that validator will automatically enter the unbonding
+   period for 21 days, and can delegate to another validator after
+   they have been unbonded.
+
+For more details on the slashing parameters, refer to the
+[celestia-app specifications](https://celestiaorg.github.io/celestia-app/specs/params.html#module-parameters)
+page.