From b8d6465613b9ba8f5ab730bff215a0f3f35c9ae2 Mon Sep 17 00:00:00 2001
From: Christopher Goes <cwgoes@pluranimity.org>
Date: Mon, 20 Aug 2018 16:58:24 +0200
Subject: [PATCH] Conceptual overview & ASCII diagrams of slashing period

---
 docs/spec/slashing/state-machine.md | 57 +++++++++++++++++++++++++++++
 1 file changed, 57 insertions(+)

diff --git a/docs/spec/slashing/state-machine.md b/docs/spec/slashing/state-machine.md
index df849398bd..46566caa67 100644
--- a/docs/spec/slashing/state-machine.md
+++ b/docs/spec/slashing/state-machine.md
@@ -1,5 +1,62 @@
 ## Transaction & State Machine Interaction Overview
 
+### Conceptual overview
+
+#### States
+
+At any given time, there are any number of validator candidates registered in the state machine.
+Each block, the top `n` candidates who are not jailed become *bonded*, meaning that they may propose and vote on blocks.
+Validators who are *bonded* are *at stake*, meaning that part or all of their stake is at risk if they commit a protocol fault.
+
+#### Slashing period
+
+In order to mitigate the impact of initially likely categories of non-malicious protocol faults, the Cosmos Hub implements for each validator
+a *slashing period*, in which the amount by which a validator can be slashed is capped at the punishment for the worst violation. For example,
+if you misconfigure your HSM and double-sign a bunch of old blocks, you'll only be punished for the first double-sign (and then immediately jailed,
+so that you have a chance to reconfigure your setup). This will still be quite expensive and desirable to avoid, but slashing periods somewhat blunt
+the economic impact of unintentional misconfiguration.
+
+A new slashing period starts whenever a validator is bonded and ends whenever the validator is unbonded (which will happen if the validator is jailed).
+The amount of tokens slashed relative to validator power for infractions committed within the slashing period, whenever they are discovered, is capped
+at the punishment for the worst infraction (which for the Cosmos Hub at launch will be double-signing a block).
+
+##### ASCII timelines
+
+*Code*
+
+*[*   : timeline start  
+*]*   : timeline end  
+*<*   : slashing period start  
+*>*   : slashing period end  
+*C<sub>n</sub>* : infraction `n` committed  
+*D<sub>n</sub>* : infraction `n` discovered  
+*V<sub>b</sub>* : validator bonded  
+*V<sub>u</sub>* : validator unbonded  
+
+*Single infraction*
+
+<----------------->   
+[----------C<sub>1</sub>----D<sub>1</sub>,V<sub>u</sub>-----]
+
+A single infraction is committed then later discovered, at which point the validator is unbonded and slashed at the full amount for the infraction.
+
+*Multiple infractions*
+
+<---------------------------->   
+[----------C<sub>1</sub>--C<sub>2</sub>---C<sub>3</sub>---D<sub>1</sub>,D<sub>2</sub>,D<sub>3</sub>V<sub>u</sub>-----]
+
+Multiple infractions are committed within a single slashing period then later discovered, at which point the validator is unbonded and slashed for only the worst infraction.
+
+*Multiple infractions after rebonding*
+
+
+<---------------------------->&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<-------------->  
+[----------C<sub>1</sub>--C<sub>2</sub>---C<sub>3</sub>---D<sub>1</sub>,D<sub>2</sub>,D<sub>3</sub>V<sub>u</sub>---V<sub>b</sub>---C<sub>4</sub>----D<sub>4</sub>,V<sub>u</sub>--]
+
+Multiple infractions are committed within a single slashing period then later discovered, at which point the validator is unbonded and slashed for only the worst infraction.
+The validator then unjails themself and rebonds, then commits a fourth infraction - which is discovered and punished at the full amount, since a new slashing period started
+when they unjailed and rebonded.
+
 ### Transactions
 
 In this section we describe the processing of transactions for the `slashing` module.