All pages
Powered by GitBook
1 of 5

Loading...

Loading...

Loading...

Loading...

Loading...

Name Registry

Energy Web has deployed OpenEthereum's Name Registry contract. 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:

  1. OpenEthereum's name registry might be needed for other OpenEthereum related system contracts later: e.g. service transaction checker, or auto updater.

  2. We will have the official Ethereum Name Service 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

Returns an unsigned integer data value from an entry, given its key.

getOwner(bytes32)

Returns the owner of an entry.

hasReverse(bytes32)

Returns true if entry has a reverse address registered.

getReverse(bytes32)

Returns reverse address of an entry.

canReverse(address)

Returns true if address can have a reverse.

reverse(address)

Returns the reverse value of an address.

reserved(bytes32)

Returns true if the name (its sha3 hash) is already reserved.

Contract

Address

JSON ABI

SimpleRegistry

0x1204700000000000000000000000000000000006

https://gist.github.com/ngyam/255a461e2241085a6530d455f7c15529

Function

Description

entries(bytes32)

Returns an entry based on the sha3 hash of the name registered.

reverse(address)

Reverse resolution of an address.

fee()

Returns the fee for reserving a name (not really relevant to public).

getData(bytes32,string)

Returns a string data value from an entry, given its key.

getAddress(bytes32,string)

Returns an address data value from an entry, given its key.

https://github.com/energywebfoundation/ewc-system-contracts/tree/master/contracts/registry

getUint(bytes32,string)

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:

  1. 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.

Calculator:

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

Returns how much was minted for a certain account in a certain block in wei

communityFundAmount()

Returns the constant payout for the community per block in wei

communityFund()

Returns community fund address

payoutAddresses(address)

Returns an address' payout address

setPayoutAddress(address)

Sets payout address for sender

resetPayoutAddress()

Resets payout address for sender

getBlockReward(uint256)

Returns blockreward amount for a certain block number

checkRewardPeriodEnded()

Returns true if blockreward period has ended (based on blocknumber), false otherwise. The blockreward period right now ends after 10 years. After that no blockrewards or community fund payouts are minted.

Name

Address

JSON ABI

RewardContract

0x1204700000000000000000000000000000000002

https://gist.github.com/ngyam/07d34631fa0e899e5896303b5ec92a3c

Function Name

Description

mintedTotally()

Returns the token amount that was minted totally in wei

mintedForCommunity()

Return the token amount that was totally minted for the community fund in wei

mintedForCommunityForAccount(address)

Returns the total token amount that was minted for a certain address for the community so far in wei

mintedForAccount(address)

Return how much was minted for an account so far in wei

mintedInBlock(uint256)

Returns how much was minted in certain block in wei

The community fund
Energy Web Block Reward Contract
OpenEthereum documentation on Block Reward Contract
https://github.com/energywebfoundation/discrete-scurve-calculator
Interaction graph for the block reward contract
Fig. 2.: Discrete inverse S curve use for block rewards. Calculated for a 5 second step size, 10 million ethers total payout over 10 years
Fig. 3.: Community reward distribution.

mintedForAccountInBlock(address, uint256)

System Contracts

System contracts are the Energy Web Chain's smart contracts that implement OpenEthereum's protocols for Aura Proof-of-Authority consensus mechanism.

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

  • Validator Set Contracts - manage validator permissioning and behavior

  • Reward Contract - 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”

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.

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

Validator-Set Contracts

Overview

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

Holding Contract
OpenEthereum’s permissioning protocols
OpenEthereum's Validator-Set
ValidatorSetRelay smart contract
Validator Set Contracts
Reward Contract
Holding Contract
[
    {
        "constant": false,
        "inputs": [],
        "name": "finalizeChange",
        "outputs": [],
        "payable": false,
        "type": "function"
    },
    {
        "constant": true,
        "inputs": [],
        "name": "getValidators",
        "outputs": [
            {
                "name": "_validators",
                "type": "address[]"
            }
        ],
        "payable": false,
        "type": "function"
    },
    {
        "anonymous": false,
        "inputs": [
            {
                "indexed": true,
                "name": "_parent_hash",
                "type": "bytes32"
            },
            {
                "indexed": false,
                "name": "_new_set",
                "type": "address[]"
            }
        ],
        "name": "InitiateChange",
        "type": "event"
    }
]
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);
    }
}
Documentation and Source Code
  • Energy Web Validator Set Contracts

  • OpenEthereum documentation on Validator Set contracts

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:

  1. The current validator set (the validators who are actively sealing)

  2. 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:

  1. Active validator: Validator is in the active validator set, sealing new blocks

  2. Not a validator: The address nothing has to do with validation.

  3. 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.

  4. 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.

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

Interaction with RelayedSet (logic) Contract

Name

Address

JSON ABI

ValidatorSetRelayed

0x1204700000000000000000000000000000000001

Callable functions

Function

Description

finalized()

Returns true if there are ongoing changes to the active set, false otherwise. If true, implies that current validators list equals migration validators list.

addressStatus(address)

Returns the state of an address, two integers: an integer representing the validator state, and an index value. The index is the position of the validator address in the currentValidators array. It is only relevant if the address is an active validator, should be ignored otherwise.

The validator state mappings are:

  • NonValidator: 0

  • Finalized: 1

getValidators()

Returns currently active block producing validators

getMigrationValidators()

Returns the migration validator set. If there are no changes, it returns the same list as getValidators().

getUnion()

Returns the union of current and migration sets. Useful for tracking the statuses of all affected validators in case of an ongoing change

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

Interaction with Relay Contract

Callable functions

Function Name

Description

getSystemAddress()

Returns the system address

getValidators()

Same as RelayedSet getValidators()

relayedSet()

Returns the address of the Relayed contract

Events you can listen to:

Validator set components
event ReportedMalicious(address indexed reporter, address indexed reported, uint indexed blocknum);
event ReportedBenign(address indexed reporter, address indexed reported, uint indexed blocknum);
event ChangeFinalized(address[] validatorSet);
event NewRelay(address indexed relay);
event NewRelayed(address indexed old, address indexed current);
PendingToBeAdded: 2
  • PendingToBeRemoved: 3

  • getValidatorsNum()

    Returns the number of currently active validators

    isPendingToBeAdded(address)

    Returns true if address is pending to be added to the active list.

    isPendingToBeRemoved(address)

    Returns true if address is pending to be removed from the active list.

    isPending(address)

    Returns true if address is pending to be added or removed.

    isActiveValidator(address)

    Returns true if address is an active validator, meaning it partakes in producing new blocks. Note that a validator who is pending to be removed is still active.

    isFinalizedValidator(address)

    Returns true if address is a finalized validator, meaning it is active and NOT pending to be removed either.

    https://gist.github.com/ngyam/62a6702dc32edbad9b4421179cfaad30

    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.

    Interaction with Holding Contract

    Documentation and Source Code

    Check a Balance and Withdraw Funds

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

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

    • To learn how to connect via remote RPC, go

    • To learn how to run a local node go

    1. Enter your address in the lookup field to see your holding balance

    2. 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.

    Interacting with the Holding Contract

    Contract Address and ABI

    Callable Functions

    Contract

    Address

    JSON ABI

    Holding

    0x1204700000000000000000000000000000000004

    https://gist.github.com/ngyam/4393eb96ada896b62afc922b760c6802

    Function Name

    Description

    releaseFunds(address)

    Releases funds for a holding address if it is present in the contract and the holding period is over

    holders(address)

    Returns the holding data for an address, the available amount and the holding-period-end blocktimestamp

    TARGET_AMOUNT()

    Returns the total amount initially held by the contract

    Energy Web Holding Contract
    http://balance.energyweb.org/
    .
    here
    here
    Holding Contract User Interface
    mapping (address => Holder) public holders;
    
    // -- snip --
    
    struct Holder {
        uint256 availableAmount;
        uint256 lockedUntilBlocktimestamp;
    }
    
    // -- snip --
    
    // in the constructor
    addHolding(0x120470000000000000000000000000000000000a, 10000000000000000000000000, 1564509540);