State machine contd.

docs/spec/slashing/README.md

@@ -21,9 +21,9 @@ This module will be used by the Cosmos Hub, the first hub in the Cosmos ecosyste
           1. Unjail
     1. [Interactions](state-machine.md#interactions)
           1. Validator Bonded
+          1. Validator Unbonding
           1. Validator Slashed
-          1. Validator Unjailed
-          1. Slashing Period Cleanup
+    1. [State Cleanup](state-machine.md#state-cleanup)
 1. **[Begin Block](begin-block.md)**
     1. [Evidence handling](begin-block.md#evidence-handling)
     1. [Uptime tracking](begin-block.md#uptime-tracking)

docs/spec/slashing/state-machine.md

@@ -43,13 +43,38 @@ provisions and rewards.
 
 ### Interactions
 
+In this section we describe the "hooks" - slashing module code that runs when other events happen.
+
 #### Validator Bonded
 
+Upon successful bonding of a validator (a given validator changing from "unbonded" state to "bonded" state,
+which may happen on delegation, on unjailing, etc), we create a new `SlashingPeriod` structure for the
+now-bonded validator, wich `StartHeight` of the current block, `EndHeight` of `0` (sentinel value for not-yet-ended),
+and `SlashedSoFar` of `0`:
+
+```golang
+onValidatorBonded(address sdk.ValAddress)
+```
+
+#### Validator Unbonded
+
+When a validator is unbonded, we update the in-progress `SlashingPeriod` with the current block as the `EndHeight`:
+
+```golang
+onValidatorUnbonded(address sdk.ValAddress)
+```
+
 #### Validator Slashed
 
-#### Validator Unjailed
+When a validator is slashed, we look up the appropriate `SlashingPeriod` based on the validator
+address and the time of infraction, cap the fraction slashed as `max(SlashFraction, SlashedSoFar)`
+(which may be `0`), and update the `SlashingPeriod` with the increased `SlashedSoFar`:
 
-#### Slashing Period Cleanup
+```golang
+beforeValidatorSlashed(address sdk.ValAddress, fraction sdk.Rat)
+```
+
+### State Cleanup
 
 Once no evidence for a given slashing period can possibly be valid (the end time plus the unbonding period is less than the current time),
-old slashing periods should be cleaned up.
+old slashing periods should be cleaned up. This will be implemented post-launch.