1 of 5

System Contracts

System contracts are the Energy Web Chain's that implement OpenEthereum's protocols for .

Energy Web's smart contracts are open-sourced, and you can see them on github

- manage validator permissioning and behavior
- manages validator block rewards
- manages the initial disbursement of pre-mined energy web tokens

Implementing Client Protocol

System contracts are the Energy Web Chain’s smart contracts that implement . These protocols determine what actions can be taken on the network.

In order to adhere to the expected protocol, the Energy Web Chain’s system contracts must implement the interfaces that are expected by the AuRa consensus engine, so that it can conform to the client’s protocols.

Let’s take contract as an example.

The OpenEthereum documentation specifies that “A simple validator contract has to have the following interface”

You can see that this smart contract implements all of the functions of the Validator-Set protocol interface that was specified above.

Energy Web System Contracts

Name Registry

Energy Web has deployed This contract is identical to OpenEthereum's original contract, with the exception that it was made Ownable by Energy Web Foundation. Only Energy Web can reserve a name or drain funds from this contract.

There are two reasons for making this contract Ownable:

OpenEthereum's name registry might be needed for other OpenEthereum related system contracts later: e.g. , or .
We will have the official system set up on the chain, so this contract is only needed for internal purposes and will not be used publicly.

The name registry is a placeholder for now. The contract can be found in our repo:

Interacting with the Name Registry Contract

Contract Address and ABI

Callable Functions

Holding Contract

Overview

The Holding Contract holds tokens for initial investors. These tokens are "pre-mined", and do not enter the pool through block validation. Tokens are held for affiliates until a specific point of time that is specified in the contract, at which point they can be released to the specified address. The constructor of the holding contract and its initial balance is part of the chainspec file. This allows the investors' tokens to be locked at the first block.

The mapping between the account address and the token amount is hard coded into the contract and cannot be changed after deployment. After a block that has a later timestamp than the holding timestamp of an address is created, the tokens for that address can be transferred to the address by calling the realeaseFunds method. This method can be called by anyone, not only by the address that holds that balance.

Documentation and Source Code

Energy Web Holding Contract

Check a Balance and Withdraw Funds

If you're an investor and want to see your balance, you can use the Balance Viewer interface: http://balance.energyweb.org/.

You will need MetaMask pointed to a local or a remote node

To learn how to connect via remote RPC, go here
To learn how to run a local node go here

Enter your address in the lookup field to see your holding balance
If the release period has ended, press the "Withdraw" button to release the funds to the address it belongs to. Make sure you trigger the withdraw function with an account that has some ethers to cover transaction costs

Mapping Between Address and Tokens

The mapping between addresses and tokens/release timestamp is kept in the storage of this contract. This mapping data structure was filled at the deploy time of the contract and cannot be changed.

mapping (address => Holder) public holders;

// -- snip --

struct Holder {
    uint256 availableAmount;
    uint256 lockedUntilBlocktimestamp;
}

// -- snip --

// in the constructor
addHolding(0x120470000000000000000000000000000000000a, 10000000000000000000000000, 1564509540);

Interacting with the Holding Contract

Contract Address and ABI

Callable Functions

Block Reward Contract

Overview

The Block Reward contract manages block reward payouts to validators. Block rewards are issued as native Energy Web tokens that are minted by the engine.

Two entities are rewarded by each created block:

The block author (validator)

Documentation and Source Code

Block Reward Payouts

Block Authors

Block authors are rewarded each time they seal a block. The amount issued to block authors decreases over time, as depicted by the Discreet S Curve.

Energy Web Community Fund

A portion of block rewards goes to the Community Fund. Unlike the amount awarded to block authors, the amount that goes to the Community Fund remains constant over time.

The amount is chosen to add up to roughly 37.9 million tokens over a 10 year period. The community fund can change its own address and set a payout address too.

With 5 second step size: Payout-per-block = 600900558100000000 wei

Visual representation of the community reward distribution is depicted below in Fig. 3.

Interaction with Block Reward Contract

Contract Address and ABI

Callable functions

Validator-Set Contracts

Overview

Validator Set contracts provide information on current validators and private functionality to add and remove validators.

Documentation and Source Code

Components

For upgradeability purposes, the contracts are divided into 2 parts. See below Fig. 1.

RelaySet Contract

This contract implements the required reporting ValidatorSet interface expected by the engine and it is the contract defined in the chainspec seen by the engine. It relays most of the function calls to the RelayedSet contract, which holds the actual logic. The logic contract can be replaced (upgraded), so it is possible to change the behavior of validator management without conducting a hard fork.

RelayedSet Contract

This contract implements the logic and manages the validator list. The owner of the validator set interacts with this contract for managing the validators. This contract maintains two validator sets:

The current validator set (the validators who are actively sealing)
The migration validator set, which is the new set we migrate to in case of a change (validator addition or removal).

Validator States

Validators and potential validators have four states in these contracts:

Active validator: Validator is in the active validator set, sealing new blocks
Not a validator: The address nothing has to do with validation.
Pending To Be Added Validator: Validator is already added by the owner and their acceptance is pending, but not active yet until it is finalized. This implies that the validator cannot report, be reported, or produce blocks yet.
Pending To Be Removed Validator: Validator is pending to be removed (removed by the owner), but it is not finalized, and so is still active as a validator. This implies that as long as the removal is not finalized, the validator is actively producing blocks, can report and can be reported on.

Reporting

The RelayedSet contract logs malicious or benign reports by emitting corresponding log events that can be seen by anyone. Reporting can only be on and about active sealing validators.

event ReportedMalicious(address indexed reporter, address indexed reported, uint indexed blocknum);
event ReportedBenign(address indexed reporter, address indexed reported, uint indexed blocknum);

The events contain the reporter- and reported address, and the block number which the validator was reported on.

Interaction with RelayedSet (logic) Contract

Callable functions

Events you can listen to, in addition to report events:

event ChangeFinalized(address[] validatorSet);
event NewRelay(address indexed relay);

Interaction with Relay Contract

Callable functions

Events you can listen to:

event NewRelayed(address indexed old, address indexed current);

Validator-Set Contracts

Overview

Validator Set contracts provide information on current validators and private functionality to add and remove validators.

Documentation and Source Code

Components

For upgradeability purposes, the contracts are divided into 2 parts. See below Fig. 1.

RelaySet Contract

RelayedSet Contract

This contract implements the logic and manages the validator list. The owner of the validator set interacts with this contract for managing the validators. This contract maintains two validator sets:

The current validator set (the validators who are actively sealing)
The migration validator set, which is the new set we migrate to in case of a change (validator addition or removal).

Validator States

Validators and potential validators have four states in these contracts:

Active validator: Validator is in the active validator set, sealing new blocks
Not a validator: The address nothing has to do with validation.
Pending To Be Added Validator: Validator is already added by the owner and their acceptance is pending, but not active yet until it is finalized. This implies that the validator cannot report, be reported, or produce blocks yet.
Pending To Be Removed Validator: Validator is pending to be removed (removed by the owner), but it is not finalized, and so is still active as a validator. This implies that as long as the removal is not finalized, the validator is actively producing blocks, can report and can be reported on.

Reporting

The RelayedSet contract logs malicious or benign reports by emitting corresponding log events that can be seen by anyone. Reporting can only be on and about active sealing validators.

event ReportedMalicious(address indexed reporter, address indexed reported, uint indexed blocknum);
event ReportedBenign(address indexed reporter, address indexed reported, uint indexed blocknum);

The events contain the reporter- and reported address, and the block number which the validator was reported on.

Interaction with RelayedSet (logic) Contract

Callable functions

Events you can listen to, in addition to report events:

event ChangeFinalized(address[] validatorSet);
event NewRelay(address indexed relay);

Interaction with Relay Contract

Callable functions

Events you can listen to:

event NewRelayed(address indexed old, address indexed current);

Holding Contract

Overview

Documentation and Source Code

Energy Web Holding Contract

Check a Balance and Withdraw Funds

If you're an investor and want to see your balance, you can use the Balance Viewer interface: http://balance.energyweb.org/.

You will need MetaMask pointed to a local or a remote node

To learn how to connect via remote RPC, go here
To learn how to run a local node go here

Enter your address in the lookup field to see your holding balance
If the release period has ended, press the "Withdraw" button to release the funds to the address it belongs to. Make sure you trigger the withdraw function with an account that has some ethers to cover transaction costs

Mapping Between Address and Tokens

The mapping between addresses and tokens/release timestamp is kept in the storage of this contract. This mapping data structure was filled at the deploy time of the contract and cannot be changed.

mapping (address => Holder) public holders;

// -- snip --

struct Holder {
    uint256 availableAmount;
    uint256 lockedUntilBlocktimestamp;
}

// -- snip --

// in the constructor
addHolding(0x120470000000000000000000000000000000000a, 10000000000000000000000000, 1564509540);

Interacting with the Holding Contract

Contract Address and ABI

Callable Functions

System Contracts

System contracts are the Energy Web Chain's that implement OpenEthereum's protocols for .

Energy Web's smart contracts are open-sourced, and you can see them on github

- manage validator permissioning and behavior
- manages validator block rewards
- manages the initial disbursement of pre-mined energy web tokens

Implementing Client Protocol

System contracts are the Energy Web Chain’s smart contracts that implement . These protocols determine what actions can be taken on the network.

Let’s take contract as an example.

The OpenEthereum documentation specifies that “A simple validator contract has to have the following interface”

Now let’s look at Energy Web’s .

You can see that this smart contract implements all of the functions of the Validator-Set protocol interface that was specified above.

pragma solidity 0.5.8;

import "../misc/Ownable.sol";
import "../interfaces/IValidatorSetRelay.sol";
import "../interfaces/IValidatorSet.sol";
import "../interfaces/IValidatorSetRelayed.sol";


/// @title Validator Set Relay contract
/// @notice This owned contract is present in the chainspec file. The Relay contract
/// relays the function calls to a logic contract called Relayed for upgradeability
contract ValidatorSetRelay is IValidatorSet, IValidatorSetRelay, Ownable {

    /// System address, used by the block sealer
    /// Not constant cause it is changed for testing
    address public systemAddress = 0xffffFFFfFFffffffffffffffFfFFFfffFFFfFFfE;
    
    /// Address of the inner validator set contract
    IValidatorSetRelayed public relayedSet;

    /// Emitted in case a new Relayed contract is set
    event NewRelayed(address indexed old, address indexed current);

    modifier nonDefaultAddress(address _address) {
        require(_address != address(0), "Address cannot be 0x0");
        _;
    }

    modifier onlySystem() {
        require(msg.sender == systemAddress, "Sender is not system");
        _;
    }

    modifier onlyRelayed() {
        require(msg.sender == address(relayedSet), "Sender is not the Relayed contract");
        _;
    }

    constructor(address _owner, address _relayedSet)
        public
    {
        _transferOwnership(_owner);
        _setRelayed(_relayedSet);
    }

    /// @notice This function is used by the Relayed logic contract
    /// to iniate a change in the active validator set
    /// @dev emits `InitiateChange` which is listened by the Parity client
    /// @param _parentHash Blockhash of the parent block
    /// @param _newSet List of addresses of the desired active validator set
    /// @return True if event was emitted
    function callbackInitiateChange(bytes32 _parentHash, address[] calldata _newSet)
        external
        onlyRelayed
        returns (bool)
    {
        emit InitiateChange(_parentHash, _newSet);
        return true;
    }

    /// @notice Finalizes changes of the active validator set.
    /// Called by SYSTEM
    function finalizeChange()
        external
        onlySystem
    {
        relayedSet.finalizeChange();
    }

    /// @notice This function is used by validators to submit Benign reports
    /// on other validators. Can only be called by the validator who submits
    /// the report
    /// @dev emits `ReportedBenign` event in the Relayed logic contract
    /// @param _validator The validator to report
    /// @param _blockNumber The blocknumber to report on
    function reportBenign(address _validator, uint256 _blockNumber)
        external
    {
        relayedSet.reportBenign(
            msg.sender,
            _validator,
            _blockNumber
        );
    }

    /// @notice This function is used by validators to submit Malicious reports
    /// on other validators. Can only be called by the validator who submits
    /// the report
    /// @dev emits `ReportedMalicious` event in the Relayed logic contract
    /// @param _validator The validator to report
    /// @param _blockNumber The blocknumber to report on
    /// @param _proof Proof to submit. Right now it is not used for anything
    function reportMalicious(address _validator, uint256 _blockNumber, bytes calldata _proof)
        external
    {
        relayedSet.reportMalicious(
            msg.sender,
            _validator,
            _blockNumber,
            _proof
        );
    }

    /// @notice Sets the Relayed logic contract address. Only callable by the owner.
    /// The address is assumed to belong to a contract that implements the
    /// `IValidatorSetRelayed` interface
    /// @param _relayedSet The contract address
    function setRelayed(address _relayedSet)
        external
        onlyOwner
    {
        _setRelayed(_relayedSet);
    }

    /// @notice Returns the currently active validators
    /// @return The list of addresses of currently active validators
    function getValidators()
        external
        view
        returns (address[] memory)
    {
        return relayedSet.getValidators();
    }

    /// @dev The actual logic of setting the Relayed contract
    function _setRelayed(address _relayedSet)
        private
        nonDefaultAddress(_relayedSet)
    {
        require(
            _relayedSet != address(relayedSet),
            "New relayed contract address cannot be the same as the current one"
        );
        address oldRelayed = address(relayedSet);
        relayedSet = IValidatorSetRelayed(_relayedSet);
        emit NewRelayed(oldRelayed, _relayedSet);
    }
}

Energy Web System Contracts

- manage validator behavior
- manages validator block rewards
- manages the initial disbursement of pre-mined energy web tokens to a group of initial supporting affiliates

pragma solidity 0.5.8;

import "../misc/Ownable.sol";
import "../interfaces/IValidatorSetRelay.sol";
import "../interfaces/IValidatorSet.sol";
import "../interfaces/IValidatorSetRelayed.sol";


/// @title Validator Set Relay contract
/// @notice This owned contract is present in the chainspec file. The Relay contract
/// relays the function calls to a logic contract called Relayed for upgradeability
contract ValidatorSetRelay is IValidatorSet, IValidatorSetRelay, Ownable {

    /// System address, used by the block sealer
    /// Not constant cause it is changed for testing
    address public systemAddress = 0xffffFFFfFFffffffffffffffFfFFFfffFFFfFFfE;
    
    /// Address of the inner validator set contract
    IValidatorSetRelayed public relayedSet;

    /// Emitted in case a new Relayed contract is set
    event NewRelayed(address indexed old, address indexed current);

    modifier nonDefaultAddress(address _address) {
        require(_address != address(0), "Address cannot be 0x0");
        _;
    }

    modifier onlySystem() {
        require(msg.sender == systemAddress, "Sender is not system");
        _;
    }

    modifier onlyRelayed() {
        require(msg.sender == address(relayedSet), "Sender is not the Relayed contract");
        _;
    }

    constructor(address _owner, address _relayedSet)
        public
    {
        _transferOwnership(_owner);
        _setRelayed(_relayedSet);
    }

    /// @notice This function is used by the Relayed logic contract
    /// to iniate a change in the active validator set
    /// @dev emits `InitiateChange` which is listened by the Parity client
    /// @param _parentHash Blockhash of the parent block
    /// @param _newSet List of addresses of the desired active validator set
    /// @return True if event was emitted
    function callbackInitiateChange(bytes32 _parentHash, address[] calldata _newSet)
        external
        onlyRelayed
        returns (bool)
    {
        emit InitiateChange(_parentHash, _newSet);
        return true;
    }

    /// @notice Finalizes changes of the active validator set.
    /// Called by SYSTEM
    function finalizeChange()
        external
        onlySystem
    {
        relayedSet.finalizeChange();
    }

    /// @notice This function is used by validators to submit Benign reports
    /// on other validators. Can only be called by the validator who submits
    /// the report
    /// @dev emits `ReportedBenign` event in the Relayed logic contract
    /// @param _validator The validator to report
    /// @param _blockNumber The blocknumber to report on
    function reportBenign(address _validator, uint256 _blockNumber)
        external
    {
        relayedSet.reportBenign(
            msg.sender,
            _validator,
            _blockNumber
        );
    }

    /// @notice This function is used by validators to submit Malicious reports
    /// on other validators. Can only be called by the validator who submits
    /// the report
    /// @dev emits `ReportedMalicious` event in the Relayed logic contract
    /// @param _validator The validator to report
    /// @param _blockNumber The blocknumber to report on
    /// @param _proof Proof to submit. Right now it is not used for anything
    function reportMalicious(address _validator, uint256 _blockNumber, bytes calldata _proof)
        external
    {
        relayedSet.reportMalicious(
            msg.sender,
            _validator,
            _blockNumber,
            _proof
        );
    }

    /// @notice Sets the Relayed logic contract address. Only callable by the owner.
    /// The address is assumed to belong to a contract that implements the
    /// `IValidatorSetRelayed` interface
    /// @param _relayedSet The contract address
    function setRelayed(address _relayedSet)
        external
        onlyOwner
    {
        _setRelayed(_relayedSet);
    }

    /// @notice Returns the currently active validators
    /// @return The list of addresses of currently active validators
    function getValidators()
        external
        view
        returns (address[] memory)
    {
        return relayedSet.getValidators();
    }

    /// @dev The actual logic of setting the Relayed contract
    function _setRelayed(address _relayedSet)
        private
        nonDefaultAddress(_relayedSet)
    {
        require(
            _relayedSet != address(relayedSet),
            "New relayed contract address cannot be the same as the current one"
        );
        address oldRelayed = address(relayedSet);
        relayedSet = IValidatorSetRelayed(_relayedSet);
        emit NewRelayed(oldRelayed, _relayedSet);
    }
}