state transitions

docs/spec/staking/state_transitions.md

@@ -8,7 +8,7 @@ This document describes the state transition operations pertaining to:
 
 ## Validators
 
-### non-bonded to bonded
+### Non-Bonded to Bonded
 When a validator is bonded from any other state the following operations occur:  
  - set `Validator.BondHeight` to current height
  - set `validator.Status` to `Bonded`
@@ -18,7 +18,7 @@ When a validator is bonded from any other state the following operations occur:
  - update the `Validator` object for this validator
  - if it exists, delete any `ValidatorQueue` record for this validator 
 
-### bonded to unbonding
+### Bonded to Unbonding
 When a validator begins the unbonding process the following operations occur: 
  - update the `Pool` object with tokens moved from `BondedTokens` to `NotBondedTokens`
  - set `validator.Status` to `Unbonding`
@@ -27,13 +27,13 @@ When a validator begins the unbonding process the following operations occur:
  - update the `Validator` object for this validator
  - insert a new record into the `ValidatorQueue` for this validator 
 
-### unbonding to unbonded
+### Unbonding to Unbonded
 A validator moves from unbonding to unbonded when the `ValidatorQueue` object
 moves from bonded to unbonded
  - update the `Validator` object for this validator
  - set `validator.Status` to `Unbonded`
 
-### jail/unjail 
+### Jail/Unjail 
 when a validator is jailed it is effectively removed from the Tendermint set.
 this process may be also be reversed. the following operations occur:
  - set `Validator.Jailed` and update object 
@@ -44,7 +44,7 @@ this process may be also be reversed. the following operations occur:
 ## Delegations
 
 ### Delegate
-When a delegation occurs both the validator object are affected  
+When a delegation occurs both the validator and the delegtion objects are affected  
  - determine the delegators shares based on tokens delegated and the validator's exchange rate
  - remove tokens from the sending account 
  - add shares the delegation object or add them to a created validator object
@@ -53,29 +53,48 @@ When a delegation occurs both the validator object are affected
  - delete record the existing record from `ValidatorByPowerIndex`
  - add an new updated record to the `ValidatorByPowerIndex`
 
-### Undelegate
-When a
-
-unbond
-	// subtract shares from delegator
-	// remove the delegation or // update the delegation
-	// if the delegation is the operator of the validator then
-	// trigger a jail validator
-	// remove the coins from the validator
-	// if not unbonded, we must instead remove validator in EndBlocker once it finishes its unbonding period
-
-### CompleteUnbonding
- - 
-
-### BeginRedelegation
-
-### CompleteRedelegation
+#### Unbond Delegation
+As a part of the Undelegate and Complete Unbonding state transitions Unbond
+Delegation may be called. 
+ - subtract the unbonded shares from delegator
+ - update the delegation or remove the delegation if there are no more shares
+ - if the delegation is the operator of the validator and no more shares exist
+   then trigger a jail validator
+ - update the validator with removed the delegator shares and associated coins, update
+   the pool for any shifts between bonded and non-bonded tokens. 
+ - remove the validator if it is unbonded and there are no more delegation shares. 
 
+### Undelegate
+When an delegation occurs both the validator and the delegtion objects are affected  
+ - perform an unbond delegation 
+   - if the validator is unbonding or bonded add the tokens to an
+     `UnbondingDelegation` Entry
+   - if the validator is unbonded send the tokens directly to the withdraw
+     account
+
+### Complete Unbonding
+For undelegations which do not complete immediately, the following operations
+occur when the unbonding delegation queue element matures:
+ - remove the entry from the `UnbondingDelegation` object
+ - withdraw the tokens to the delegator withdraw address 
+
+### Begin Redelegation
+Redelegations affect the delegation, source and destination validators. 
+ - perform an unbond delegation from the source validator 
+ - using the generated tokens perform a Delegate to the destination
+   validator
+ - record the token amount in an new entry in the relevant `Redelegation`
+
+### Complete Redelegation
+When a redelegations complete the following occurs:
+ - remove the entry from the `Redelegation` object
 
 
 TODO TODO TOFU TODO
 ## Slashing
-### Slash
-### slashUnbondingDelegation
-### slashRedelegation
 
+### Slash Validator
+
+### Slash Unbonding Delegation
+
+### Slash Redelegation

x/staking/keeper/delegation.go

@@ -534,7 +534,7 @@ func (k Keeper) unbond(ctx sdk.Context, delAddr sdk.AccAddress, valAddr sdk.ValA
 		k.AfterDelegationModified(ctx, delegation.DelegatorAddr, delegation.ValidatorAddr)
 	}
 
-	// remove the coins from the validator
+	// remove the sharea and coins from the validator
 	validator, amount = k.RemoveValidatorTokensAndShares(ctx, validator, shares)
 
 	if validator.DelegatorShares.IsZero() && validator.Status == sdk.Unbonded {