diff --git a/README.md b/README.md index 0dba1f7..1bb279a 100644 --- a/README.md +++ b/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 ``` -- `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. diff --git a/contracts/Certifier.sol b/contracts/Certifier.sol index 873deef..19fdbb8 100644 --- a/contracts/Certifier.sol +++ b/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 ======================================================== diff --git a/contracts/Registry.sol b/contracts/Registry.sol index 00df39f..b3735c8 100644 --- a/contracts/Registry.sol +++ b/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; diff --git a/contracts/ValidatorSetAuRa.sol b/contracts/ValidatorSetAuRa.sol index 7fadc06..b839269 100644 --- a/contracts/ValidatorSetAuRa.sol +++ b/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 diff --git a/contracts/base/BlockRewardAuRaBase.sol b/contracts/base/BlockRewardAuRaBase.sol index 0137e59..5beade0 100644 --- a/contracts/base/BlockRewardAuRaBase.sol +++ b/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