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.