added blockreward transition map tests and docs

ethcore/src/engines/authority_round/mod.rs

@@ -1633,6 +1633,7 @@ impl Engine for AuthorityRound {
 #[cfg(test)]
 mod tests {
 	use std::collections::BTreeMap;
+	use std::str::FromStr;
 	use std::sync::Arc;
 	use std::sync::atomic::{AtomicUsize, Ordering as AtomicOrdering};
 	use hash::keccak;
@@ -1653,9 +1654,11 @@ mod tests {
 	};
 	use spec::Spec;
 	use engines::{Seal, Engine};
+	use engines::block_reward::BlockRewardContract;
 	use engines::validator_set::{TestSet, SimpleList};
 	use super::{AuthorityRoundParams, AuthorityRound, EmptyStep, SealedEmptyStep, calculate_score};
 	use machine::Machine;
+	use ethjson;
 
 	fn build_aura<F>(f: F) -> Arc<AuthorityRound> where
 		F: FnOnce(&mut AuthorityRoundParams),
@@ -2438,4 +2441,55 @@ mod tests {
 		set_empty_steps_seal(&mut header, step, &signature, &empty_steps);
 		assert_eq!(engine.verify_block_family(&header, &parent).unwrap(), ());
 	}
+
+	#[test]
+	fn should_collect_block_reward_transitions() {
+		let config = r#"{
+			"params": {
+				"stepDuration": "5",
+				"validators": {
+					"list" : ["0x1000000000000000000000000000000000000001"]
+				},
+                "blockRewardContractTransition": "0",
+				"blockRewardContractAddress": "0x2000000000000000000000000000000000000002",
+				"blockRewardContractTransitions": {
+					"7": "0x3000000000000000000000000000000000000003",
+					"42": "0x4000000000000000000000000000000000000004"
+				}
+			}
+		}"#;
+		let deserialized: ethjson::spec::AuthorityRound = serde_json::from_str(config).unwrap();
+		let params = AuthorityRoundParams::from(deserialized.params);
+		for ((block_num1, address1), (block_num2, address2)) in
+			params.block_reward_contract_transitions.iter().zip(
+				[(0u64, BlockRewardContract::new_from_address(Address::from_str("2000000000000000000000000000000000000002").unwrap())),
+				 (7u64, BlockRewardContract::new_from_address(Address::from_str("3000000000000000000000000000000000000003").unwrap())),
+				 (42u64, BlockRewardContract::new_from_address(Address::from_str("4000000000000000000000000000000000000004").unwrap())),
+				].iter())
+		{
+			assert_eq!(block_num1, block_num2);
+			assert_eq!(address1, address2);
+		}
+	}
+
+	#[test]
+	#[should_panic(expected="blockRewardContractTransition should be less than any of the keys in blockRewardContractTransitions")]
+	fn should_reject_out_of_order_block_reward_transition() {
+		let config = r#"{
+			"params": {
+				"stepDuration": "5",
+				"validators": {
+					"list" : ["0x1000000000000000000000000000000000000001"]
+				},
+                "blockRewardContractTransition": "7",
+				"blockRewardContractAddress": "0x2000000000000000000000000000000000000002",
+				"blockRewardContractTransitions": {
+					"0": "0x3000000000000000000000000000000000000003",
+					"42": "0x4000000000000000000000000000000000000004"
+				}
+			}
+		}"#;
+		let deserialized: ethjson::spec::AuthorityRound = serde_json::from_str(config).unwrap();
+		AuthorityRoundParams::from(deserialized.params);
+	}
 }

json/src/spec/authority_round.rs

@@ -14,7 +14,29 @@
 // You should have received a copy of the GNU General Public License
 // along with Parity Ethereum.  If not, see <http://www.gnu.org/licenses/>.
 
-//! Authority params deserialization.
+//! Authority Round parameter deserialization.
+//!
+//! Here is an example of input parameters where the step duration is constant at 5 seconds, the set
+//! of validators is decided by the contract at address `0x10..01` starting from block 0, and where
+//! the address of the contract that computes block rewards is set to `0x20..02` for blocks 0
+//! through 41 and to `0x30.03` for all blocks starting from block 42.
+//!
+//! ```ignore
+//! "params": {
+//!     "stepDuration": "5",
+//!     "validators": {
+//!         "multi": {
+//!             "0": {
+//!                 "contract": "0x1000000000000000000000000000000000000001"
+//!             }
+//!         }
+//!     },
+//!     "blockRewardContractTransitions": {
+//!         "0": "0x2000000000000000000000000000000000000002",
+//!         "42": "0x3000000000000000000000000000000000000003"
+//!     }
+//! }
+//! ```
 
 use std::collections::BTreeMap;
 use hash::Address;
@@ -46,14 +68,19 @@ pub struct AuthorityRoundParams {
 	/// a single block reward contract transition and is compatible with the multiple address option
 	/// `block_reward_contract_transitions` below.
 	pub block_reward_contract_transition: Option<Uint>,
-	/// Block reward contract address (setting the block reward contract overrides the static block
-	/// reward definition). This option allows to add a single block reward contract address and is
-	/// compatible with the multiple address option `block_reward_contract_transitions` below.
+	/// Block reward contract address which overrides the `block_reward` setting. This option allows
+	/// to add a single block reward contract address and is compatible with the multiple address
+	/// option `block_reward_contract_transitions` below.
 	pub block_reward_contract_address: Option<Address>,
-	/// Block reward contract addresses with their associated starting block numbers. Setting the
-	/// block reward contract overrides the static block reward definition. If the single block
-	/// reward contract address is also present then it is added into the map at the block number
-	/// stored in `block_reward_contract_transition` or 0 if that block number is not provided.
+	/// Block reward contract addresses with their associated starting block numbers.
+	///
+	/// Setting the block reward contract overrides `block_reward`. If the single block reward
+	/// contract address is also present then it is added into the map at the block number stored in
+	/// `block_reward_contract_transition` or 0 if that block number is not provided. Therefore both
+	/// a single block reward contract transition and a map of reward contract transitions can be
+	/// used simulataneously in the same configuration. In such a case the code requires that the
+	/// block number of the single transition is strictly less than any of the block numbers in the
+	/// map.
 	pub block_reward_contract_transitions: Option<BTreeMap<Uint, Address>>,
 	/// Block reward code. This overrides the block reward contract address.
 	pub block_reward_contract_code: Option<Bytes>,