From 81b9bdf40010c6a4e336133ec53fe6e4e6089911 Mon Sep 17 00:00:00 2001
From: Ethan Buchman <ethan@coinculture.info>
Date: Wed, 20 Mar 2019 08:29:40 -0400
Subject: [PATCH] comments on validator ordering (#3452)

* comments on validator ordering

* NextValidatorsHash
---
 docs/spec/blockchain/blockchain.md | 2 ++
 rpc/core/consensus.go              | 2 ++
 types/validator_set.go             | 3 ++-
 3 files changed, 6 insertions(+), 1 deletion(-)

diff --git a/docs/spec/blockchain/blockchain.md b/docs/spec/blockchain/blockchain.md
index 00cccfc2e..60a07d42a 100644
--- a/docs/spec/blockchain/blockchain.md
+++ b/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
 
diff --git a/rpc/core/consensus.go b/rpc/core/consensus.go
index b8a91f107..3850999d3 100644
--- a/rpc/core/consensus.go
+++ b/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'
diff --git a/types/validator_set.go b/types/validator_set.go
index 3d31cf7d0..36ce67f06 100644
--- a/types/validator_set.go
+++ b/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().