Update comments and README

README.md

@@ -10,11 +10,12 @@ The algorithm provides a Sybil control mechanism for reporting malicious validat
 
 ## POSDAO Repositories and Resources
 
-- White paper https://forum.poa.network/t/posdao-white-paper/2208
-- Backported OpenEthereum client with all POSDAO features https://github.com/poanetwork/open-ethereum/tree/posdao-backport
-- Original OpenEthereum client supporting all POSDAO features https://github.com/openethereum/openethereum starting from v3.0.0
-- Integration tests setup for a POSDAO network https://github.com/poanetwork/posdao-test-setup
-- Discussion forum https://forum.poa.network/c/posdao
+- White paper: https://forum.poa.network/t/posdao-white-paper/2208
+- Backported OpenEthereum client with POSDAO features: https://github.com/poanetwork/open-ethereum/tree/posdao-backport (v2.7.2) and https://github.com/openethereum/openethereum/tree/xdai (v3.1.0-rc.1)
+- Original OpenEthereum client supporting POSDAO features: https://github.com/openethereum/parity-ethereum/tree/v3.0.1 (v3.0.1)
+- Nethermind client supporting POSDAO features: https://github.com/NethermindEth/nethermind
+- Integration tests setup for a POSDAO network: https://github.com/poanetwork/posdao-test-setup
+- Discussion forum: https://forum.poa.network/c/posdao
 
 ## Smart Contract Summaries
 
@@ -25,7 +26,7 @@ _Note: The following descriptions are for AuRa contracts only. HBBFT contract im
   - mints native coins needed for the `erc-to-native` bridge;
   - makes a snapshot of the validators stakes at the beginning of each staking epoch. That snapshot is used by the `StakingAuRa.claimReward` function to transfer rewards to validators and their delegators.
 
-- `Certifier`: allows validators to use a zero gas price for their service transactions (see [OpenEthereum Wiki](https://openethereum.github.io/wiki/Permissioning.html#gas-price) for more info). The following functions are considered service transactions:
+- `Certifier`: allows validators to use a zero gas price for their service transactions (see [OpenEthereum Wiki](https://openethereum.github.io/Permissioning.html#gas-price) for more info). The following functions are considered service transactions:
   - ValidatorSetAuRa.emitInitiateChange
   - ValidatorSetAuRa.reportMalicious
   - RandomAura.commitHash
@@ -92,7 +93,7 @@ _Note: The following descriptions are for AuRa contracts only. HBBFT contract im
     ```
     </details>
 
-- `Registry`: stores human-readable keys associated with addresses, like DNS information (see [OpenEthereum Wiki](https://openethereum.github.io/wiki/Parity-name-registry.html)). This contract is needed primarily to store the address of the `Certifier` contract (see [OpenEthereum Wiki](https://openethereum.github.io/wiki/Permissioning.html#gas-price) for details).
+- `Registry`: stores human-readable keys associated with addresses, like DNS information. This contract is needed primarily to store the address of the `Certifier` contract (see [OpenEthereum Wiki](https://openethereum.github.io/Service-transaction-checker-contract.html) for details).
 
 - `StakingAuRa`: contains staking logic including:
   - creating, storing, and removing pools by candidates and validators;
@@ -107,7 +108,7 @@ _Note: The following descriptions are for AuRa contracts only. HBBFT contract im
 
 - `TxPriority`: manages and stores the transactions priority list used by Ethereum client. See https://github.com/NethermindEth/nethermind/issues/2300 for description.
 
-- `ValidatorSetAuRa`: stores the current validator set and contains the logic for choosing new validators at the beginning of each staking epoch. The logic uses a random seed generated and stored by the `RandomAuRa` contract. Also, ValidatorSetAuRa is responsible for discovering and removing malicious validators. This contract is based on `reporting ValidatorSet` [described in OpenEthereum Wiki](https://openethereum.github.io/wiki/Validator-Set.html#reporting-contract).
+- `ValidatorSetAuRa`: stores the current validator set and contains the logic for choosing new validators at the beginning of each staking epoch. The logic uses a random seed generated and stored by the `RandomAuRa` contract. Also, ValidatorSetAuRa is responsible for discovering and removing malicious validators. This contract is based on `reporting ValidatorSet` [described in OpenEthereum Wiki](https://openethereum.github.io/Validator-Set.html#reporting-contract).
 
 For a detailed description of each function of the contracts, see their source code.
 

contracts/Certifier.sol

@@ -6,7 +6,7 @@ import "./upgradeability/UpgradeableOwned.sol";
 
 
 /// @dev Allows validators to use a zero gas price for their service transactions
-/// (see https://openethereum.github.io/wiki/Permissioning.html#gas-price for more info).
+/// (see https://openethereum.github.io/Permissioning.html#gas-price for more info).
 contract Certifier is UpgradeableOwned, ICertifier {
 
     // =============================================== Storage ========================================================

contracts/Registry.sol

@@ -23,10 +23,9 @@ contract Owned {
 }
 
 
-/// @dev Stores human-readable keys associated with addresses, like DNS information
-/// (see https://openethereum.github.io/wiki/Parity-name-registry.html). Needed primarily to store the address
-/// of the `TxPermission` contract (see
-/// https://openethereum.github.io/wiki/Permissioning.html#transaction-type for details).
+/// @dev Stores human-readable keys associated with addresses, like DNS information.
+/// Needed primarily to store the address of the `Certifier` contract (see
+/// https://openethereum.github.io/Service-transaction-checker-contract.html for details).
 contract Registry is Owned, IMetadataRegistry, IOwnerRegistry, IReverseRegistry {
     struct Entry {
         address owner;

contracts/ValidatorSetAuRa.sol

@@ -210,7 +210,7 @@ contract ValidatorSetAuRa is UpgradeabilityAdmin, IValidatorSetAuRa {
         _;
     }
 
-    /// @dev Ensures the caller is the SYSTEM_ADDRESS. See https://openethereum.github.io/wiki/Validator-Set.html
+    /// @dev Ensures the caller is the SYSTEM_ADDRESS. See https://openethereum.github.io/Validator-Set.html
     modifier onlySystem() {
         require(msg.sender == 0xffffFFFfFFffffffffffffffFfFFFfffFFFfFFfE);
         _;
@@ -230,10 +230,15 @@ contract ValidatorSetAuRa is UpgradeabilityAdmin, IValidatorSetAuRa {
     }
 
     /// @dev Makes a request to change validator's mining address or changes the mining address of a candidate pool
-    /// immediately. Will fail if there is already another request. Must be called by pool's staking address.
+    /// immediately. Will fail if there is already another request. Can be called by pool's staking address.
     /// If this is called by a validator pool, the function emits `InitiateChange` event,
     /// so the mining address change is actually applied once the `finalizeChange` function is invoked.
-    /// @param _newMiningAddress The new mining address to set for the pool that called this function.
+    /// A validator cannot call this function at the end of a staking epoch during the last
+    /// two randomness collection rounds (see the `RandomAuRa` contract).
+    /// A candidate can call this function at any time.
+    /// @param _newMiningAddress The new mining address to set for the pool
+    /// whose staking address called this function. The new mining address shouldn't be a former
+    /// delegator or a pool (staking address or mining address).
     function changeMiningAddress(address _newMiningAddress) external onlyInitialized {
         address stakingAddress = msg.sender;
         address oldMiningAddress = miningByStakingAddress[stakingAddress];
@@ -293,8 +298,11 @@ contract ValidatorSetAuRa is UpgradeabilityAdmin, IValidatorSetAuRa {
     }
 
     /// @dev Changes the staking address of a pool. Will fail if there is already another request
-    /// to change mining address. Must be called by pool's staking address.
-    /// @param _newStakingAddress The new staking address to set for the pool that called this function.
+    /// to change mining address (see `changeMiningAddress` code). Can be called by pool's staking address.
+    /// Can be called at any time during a staking epoch.
+    /// @param _newStakingAddress The new staking address to set for the pool
+    /// whose old staking address called this function. The new staking address shouldn't be a former
+    /// delegator or a pool (staking address or mining address).
     function changeStakingAddress(address _newStakingAddress) external onlyInitialized {
         address oldStakingAddress = msg.sender;
 
@@ -357,6 +365,7 @@ contract ValidatorSetAuRa is UpgradeabilityAdmin, IValidatorSetAuRa {
     /// The `finalizeChange` is only called once for each `InitiateChange` event emitted. The next `InitiateChange`
     /// event is not emitted until the previous one is not yet finalized by the `finalizeChange`
     /// (see the code of `emitInitiateChangeCallable` getter).
+    /// The function has unlimited gas (according to OpenEthereum and/or Nethermind client code).
     function finalizeChange() external onlySystem {
         if (_finalizeValidators.forNewEpoch) {
             // Apply a new validator set formed by the `newValidatorSet` function

contracts/base/BlockRewardAuRaBase.sol

@@ -147,7 +147,7 @@ contract BlockRewardAuRaBase is UpgradeableOwned, IBlockRewardAuRa {
     }
 
     /// @dev Ensures the caller is the SYSTEM_ADDRESS.
-    /// See https://openethereum.github.io/wiki/Block-Reward-Contract.html
+    /// See https://openethereum.github.io/Block-Reward-Contract.html
     modifier onlySystem {
         require(msg.sender == 0xffffFFFfFFffffffffffffffFfFFFfffFFFfFFfE);
         _;
@@ -230,6 +230,7 @@ contract BlockRewardAuRaBase is UpgradeableOwned, IBlockRewardAuRa {
     /// accumulating block producing statistics, starting a new staking epoch, snapshotting staking amounts
     /// for the upcoming staking epoch, rewards distributing at the end of a staking epoch, and minting
     /// native coins needed for the `erc-to-native` bridge.
+    /// The function has unlimited gas (according to OpenEthereum and/or Nethermind client code).
     function reward(address[] calldata benefactors, uint16[] calldata kind)
         external
         onlySystem