cwgoes comments, improved pseudocode

docs/spec/README.md

@@ -10,7 +10,7 @@ NOTE: the specifications are not yet complete and very much a work in progress.
 - [Governance](governance) - Governance related specifications including 
   proposals and voting.
 - [IBC](ibc) - Specification of the Cosmos inter-blockchain communication (IBC) protocol.
-- [Staking](staking) - Proof of Stake related specifications including bonding 
+- [Staking](staking) - Proof-of-stake related specifications including bonding 
   and delegation transactions, inflation, etc.
 - [Slashing](slashing) - Specifications of validator punishment mechanisms
 - [Provisioning](provisioning) - Fee distribution, and atom provision distribution specification

docs/spec/staking/state.md

@@ -8,6 +8,8 @@ information about the total amounts of Atoms in all states, representative
 validator shares for stake in the global pools, moving Atom inflation
 information, etc.
 
+ - stored object:
+
 ```golang
 type Pool struct {
     LooseUnbondedTokens int64   // tokens not associated with any validator
@@ -35,6 +37,8 @@ type PoolShares struct {
 Params is global data structure that stores system parameters and defines
 overall functioning of the stake module. 
 
+ - stored object:
+
 ```golang
 type Params struct {
     InflationRateChange sdk.Rat // maximum annual change in inflation rate
@@ -59,6 +63,8 @@ Related Store which holds Validator.ABCIValidator()
 The `Validator` holds the current state and some historical actions of the
 validator.
 
+ - stored object:
+
 ```golang
 type Validator struct {
 	Owner           sdk.Address    // sender of BondTx - UnbondTx returns here
@@ -98,6 +104,8 @@ funds are held in a `Delegation` data structure. It is owned by one
 delegator, and is associated with the shares for one validator. The sender of 
 the transaction is the owner of the bond.
 
+ - stored object:
+
 ```golang
 type Delegation struct {
 	DelegatorAddr sdk.Address // delegation owner address
@@ -114,6 +122,8 @@ A UnbondingDelegation object is created every time an unbonding is initiated.
 The unbond must be completed with a second transaction provided by the
 delegation owner after the unbonding period has passed.
 
+ - stored object:
+
 ```golang
 type UnbondingDelegation struct {
     DelegationKey    sdk.Address // key of the delegation
@@ -135,6 +145,8 @@ delegation owner after the unbonding period has passed.  The destination
 delegation of a redelegation may not itself undergo a new redelegation until
 the original redelegation has been completed.
 
+ - stored object:
+
 ```golang
 type Redelegation struct {
     SourceDelegation       sdk.Address // source delegation key

docs/spec/staking/transactions.md

@@ -44,7 +44,7 @@ createValidator(tx TxCreateValidator):
     if validator != nil return // only one validator per address
    	
     validator = NewValidator(OwnerAddr, ConsensusPubKey, GovernancePubKey, Description)
-    init validator poolShares, delegatorShares set to 0 //XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
+    init validator poolShares, delegatorShares set to 0
     init validator commision fields from tx
     validator.PoolShares = 0
    	
@@ -71,8 +71,8 @@ type TxEditCandidacy struct {
 editCandidacy(tx TxEditCandidacy):
     validator = getValidator(tx.ValidatorAddr)
     
-    if tx.Commission > CommissionMax ||  tx.Commission < 0 return halt tx
-    if rateChange(tx.Commission) > CommissionMaxChange return halt tx
+    if tx.Commission > CommissionMax ||  tx.Commission < 0 then fail 
+    if rateChange(tx.Commission) > CommissionMaxChange then fail
     validator.Commission = tx.Commission
 
     if tx.GovernancePubKey != nil validator.GovernancePubKey = tx.GovernancePubKey
@@ -126,28 +126,16 @@ startUnbonding(tx TxStartUnbonding):
     delegation, found = getDelegatorBond(store, sender, tx.PubKey)
     if !found == nil return 
     
-	if tx.Shares == "MAX" {
-		if !bond.Shares.GT(sdk.ZeroRat()) {
-			return ErrNotEnoughBondShares
-    else 
-		var err sdk.Error
-		delShares, err = sdk.NewRatFromDecimal(tx.Shares)
-		if err != nil 
-            return err
-		if bond.Shares.LT(delShares) 
+		if bond.Shares < tx.Shares
 			return ErrNotEnoughBondShares
 
-	validator, found := GetValidator(tx.ValidatorAddr)
+	validator, found = GetValidator(tx.ValidatorAddr)
 	if !found {
 		return err 
 
-	if tx.Shares == "MAX" 
-		delShares = bond.Shares
+	bond.Shares -= tx.Shares
 
-	bond.Shares -= delShares
-    
-
-	revokeCandidacy := false
+	revokeCandidacy = false
 	if bond.Shares.IsZero() {
 
 		if bond.DelegatorAddr == validator.Owner && validator.Revoked == false 
@@ -158,8 +146,8 @@ startUnbonding(tx TxStartUnbonding):
 		bond.Height = currentBlockHeight
 		setDelegation(bond)
 
-	pool := GetPool()
-	validator, pool, returnAmount := validator.removeDelShares(pool, delShares)
+	pool = GetPool()
+	validator, pool, returnAmount = validator.removeDelShares(pool, tx.Shares)
 	setPool( pool)
 
     unbondingDelegation = NewUnbondingDelegation(sender, returnAmount, currentHeight/Time, startSlashRatio)
@@ -261,13 +249,13 @@ Tendermint.
 ```golang
 updateBondedValidators(newValidator Validator) (updatedVal Validator)
 
-	kickCliffValidator := false
-	oldCliffValidatorAddr := getCliffValidator(ctx)
+	kickCliffValidator = false
+	oldCliffValidatorAddr = getCliffValidator(ctx)
 
 	// add the actual validator power sorted store
-	maxValidators := GetParams(ctx).MaxValidators
-	iterator := ReverseSubspaceIterator(ValidatorsByPowerKey) // largest to smallest
-	bondedValidatorsCount := 0
+	maxValidators = GetParams(ctx).MaxValidators
+	iterator = ReverseSubspaceIterator(ValidatorsByPowerKey) // largest to smallest
+	bondedValidatorsCount = 0
 	var validator Validator
 	for {
 		if !iterator.Valid() || bondedValidatorsCount > int(maxValidators-1) {
@@ -282,7 +270,7 @@ updateBondedValidators(newValidator Validator) (updatedVal Validator)
 		// use the validator provided because it has not yet been updated
 		// in the main validator store
 
-		ownerAddr := iterator.Value()
+		ownerAddr = iterator.Value()
 		if bytes.Equal(ownerAddr, newValidator.Owner) {
 			validator = newValidator
         else
@@ -290,7 +278,7 @@ updateBondedValidators(newValidator Validator) (updatedVal Validator)
 
 		// if not previously a validator (and unrevoked),
 		// kick the cliff validator / bond this new validator
-		if validator.Status() != sdk.Bonded && !validator.Revoked {
+		if validator.Status() != Bonded && !validator.Revoked {
 			kickCliffValidator = true
 
 			validator = bondValidator(ctx, store, validator)
@@ -302,16 +290,16 @@ updateBondedValidators(newValidator Validator) (updatedVal Validator)
 
 	// perform the actual kicks
 	if oldCliffValidatorAddr != nil && kickCliffValidator {
-		validator := getValidator(store, oldCliffValidatorAddr)
+		validator = getValidator(store, oldCliffValidatorAddr)
 		unbondValidator(ctx, store, validator)
 	return
 
 // perform all the store operations for when a validator status becomes unbonded
-unbondValidator(ctx sdk.Context, store sdk.KVStore, validator Validator)
-	pool := GetPool(ctx)
+unbondValidator(ctx Context, store KVStore, validator Validator)
+	pool = GetPool(ctx)
 
 	// set the status
-	validator, pool = validator.UpdateStatus(pool, sdk.Unbonded)
+	validator, pool = validator.UpdateStatus(pool, Unbonded)
 	setPool(ctx, pool)
 
 	// save the now unbonded validator record
@@ -325,11 +313,11 @@ unbondValidator(ctx sdk.Context, store sdk.KVStore, validator Validator)
 }
 
 // perform all the store operations for when a validator status becomes bonded
-bondValidator(ctx sdk.Context, store sdk.KVStore, validator Validator) Validator 
-	pool := GetPool(ctx)
+bondValidator(ctx Context, store KVStore, validator Validator) Validator 
+	pool = GetPool(ctx)
 
 	// set the status
-	validator, pool = validator.UpdateStatus(pool, sdk.Bonded)
+	validator, pool = validator.UpdateStatus(pool, Bonded)
 	setPool(ctx, pool)
 
 	// save the now bonded validator record to the three referenced stores