arrow-left

All pages
gitbookPowered by GitBook
1 of 5

Loading...

Loading...

Loading...

Loading...

Loading...

Holding Contract

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

hashtag
Documentation and Source Code

hashtag
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

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

hashtag
Interacting with the Holding Contract

hashtag
Contract Address and ABI

hashtag
Callable Functions

Contract

Address

JSON ABI

Holding

0x1204700000000000000000000000000000000004

https://gist.github.com/ngyam/4393eb96ada896b62afc922b760c6802arrow-up-right

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 arrow-up-right
http://balance.energyweb.org/arrow-up-right
.arrow-up-right
here
here
Interaction with Holding Contract
Holding Contract User Interface
mapping (address => Holder) public holders;

// -- snip --

struct Holder {
    uint256 availableAmount;
    uint256 lockedUntilBlocktimestamp;
}

// -- snip --

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

Validator-Set Contracts

hashtag
Overview

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

Validator set components

hashtag
Documentation and Source Code

hashtag
Components

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

hashtag
RelaySet Contract

This contract implements the required 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.

hashtag
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).

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

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

hashtag
Interaction with RelayedSet (logic) Contract

hashtag
Callable functions

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

hashtag
Interaction with Relay Contract

hashtag
Callable functions

hashtag
Events you can listen to:

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.

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.

Name

Address

JSON ABI

ValidatorSetRelayed

0x1204700000000000000000000000000000000001

https://gist.github.com/ngyam/62a6702dc32edbad9b4421179cfaad30arrow-up-right

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

  • PendingToBeAdded: 2

  • PendingToBeRemoved: 3

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

Function Name

Description

getSystemAddress()

Returns the system address

getValidators()

Same as RelayedSet getValidators()

relayedSet()

Returns the address of the Relayed contract

Energy Web Validator Set Contractsarrow-up-right
OpenEthereum documentation on Validator Set contractsarrow-up-right
reporting ValidatorSetarrow-up-right

getValidatorsNum()

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);

Name Registry

Energy Web has deployed OpenEthereum's Name Registry contract.arrow-up-right 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 checkerarrow-up-right, or auto updaterarrow-up-right.

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

hashtag
Interacting with the Name Registry Contract

hashtag
Contract Address and ABI

hashtag
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/255a461e2241085a6530d455f7c15529arrow-up-right

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.

Ethereum Name Servicearrow-up-right
https://github.com/energywebfoundation/ewc-system-contracts/tree/master/contracts/registryarrow-up-right

getUint(bytes32,string)

Block Reward Contract

hashtag
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)

hashtag
Documentation and Source Code

hashtag
Block Reward Payouts

hashtag
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:

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

hashtag
Interaction with Block Reward Contract

hashtag
Contract Address and ABI

hashtag
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/07d34631fa0e899e5896303b5ec92a3carrow-up-right

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 fundarrow-up-right
Energy Web Block Reward Contractarrow-up-right
OpenEthereum documentation on Block Reward Contractarrow-up-right
https://github.com/energywebfoundation/discrete-scurve-calculatorarrow-up-right
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 contractsarrow-up-right that implement OpenEthereum's protocols for Aura Proof-of-Authority consensus mechanismarrow-up-right.

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

  • Validator Set Contracts - manage validator permissioning and behavior

  • - manages validator block rewards

  • - manages the initial disbursement of pre-mined energy web tokens

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

hashtag
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

Reward Contract
Holding Contract
OpenEthereum’s permissioning protocolsarrow-up-right
OpenEthereum's Validator-Setarrow-up-right
ValidatorSetRelay smart contractarrow-up-right
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);
    }
}