comments on validator ordering (#3452)

* comments on validator ordering

* NextValidatorsHash

docs/spec/blockchain/blockchain.md

@@ -332,6 +332,7 @@ block.ValidatorsHash == MerkleRoot(state.Validators)
 
 MerkleRoot of the current validator set that is committing the block.
 This can be used to validate the `LastCommit` included in the next block.
+Note the validators are sorted by their address before computing the MerkleRoot.
 
 ### NextValidatorsHash
 
@@ -342,6 +343,7 @@ block.NextValidatorsHash == MerkleRoot(state.NextValidators)
 MerkleRoot of the next validator set that will be the validator set that commits the next block.
 This is included so that the current validator set gets a chance to sign the
 next validator sets Merkle root.
+Note the validators are sorted by their address before computing the MerkleRoot.
 
 ### ConsensusHash
 

rpc/core/consensus.go

@@ -10,6 +10,8 @@ import (
 
 // Get the validator set at the given block height.
 // If no height is provided, it will fetch the current validator set.
+// Note the validators are sorted by their address - this is the canonical
+// order for the validators in the set as used in computing their Merkle root.
 //
 // ```shell
 // curl 'localhost:26657/validators'

types/validator_set.go

@@ -31,7 +31,8 @@ const (
 // ValidatorSet represent a set of *Validator at a given height.
 // The validators can be fetched by address or index.
 // The index is in order of .Address, so the indices are fixed
-// for all rounds of a given blockchain height.
+// for all rounds of a given blockchain height - ie. the validators
+// are sorted by their address.
 // On the other hand, the .ProposerPriority of each validator and
 // the designated .GetProposer() of a set changes every round,
 // upon calling .IncrementProposerPriority().