Blockchain Consensus

In a centralized system, such as a bank or a broker, a designated authority or central operating system would be in charge of adding transactions or information to the system, making sure that each transaction is trustworthy, up to date with the whole system, and does not duplicate previous transactions.

In contrast, public blockchains are decentralized, peer-to-peer systems that have no central authority or oversight like this. Designated actors are responsible for processing transactions, creating new blocks and maintaining the integrity and history of previous blocks.

The system for determining these actors and how they are selected is called a consensus mechanism. These mechanisms determine the process of who can confirm transactions and create new blocks on the blockchain and the protocol for how they do so. Because there is no central oversight, consensus needs to be designed in a way that prevents or disincentivizes malicious or uninformed actors from corrupting the integrity of the chain.

There are many consensus algorithms. You may have heard of some widely used ones like Proof-of-Work or Proof-of-Stake. Each mechanism has its own way of determining who is eligible to process transactions and create new blocks, and how how actors are selected to do so.

The Energy Web Chain uses the Proof-of-Authority (PoA) consensus mechanism.

All consensus mechanisms have disadvantages and advantages and are chosen based on the purpose and use case of the blockchain it will be serving. You can read more about why Energy Web employs the Proof-of-Authority mechanisms below.

Proof-of-Authority Consensus

The Proof-of-Authority (PoA) consensus mechanism has a defined set of actors that validate transactions and propagate new blocks to the chain. Rather than competing or staking for a chance to add blocks, they take turns creating new blocks in a round-robin style. These actors are called validators.

Energy Web validators participate by running full nodes of the blockchain using OpenEthereum client software. Smart contracts called Validator-Set contracts have the functionality to add or remove validators. Anyone can run a full node of the blockchain, but only addresses that are included in the Validator-Set contracts can validate transactions and seal blocks. You can read about the Energy Web Chain's Validator Set Contracts here.

The Energy Web Chain uses a specific type of PoA called Authority Roundtable (AuRa). The AuRa Proof-of-Authority consensus mechanism can be used by blockchains that run the OpenEthereum client.

Proof-of-Authority Process

At a high level, the PoA mechanism works as follows:

1. All validator nodes maintain a complete list of the validators, identified by public keys. This list changes as validators are added or removed. In addition to storing the current and historical state of the network, all validators maintain essential information about the network (such as synchronized timing information and current data processing limits).

2. For a defined time window, one validator is assigned as the primary validator via the PoA algorithm. During this time, they are responsible for collecting the broadcasted transactions and proposing the new block. Only one validator is designated as primary at a time–based on a calculation derived from the timestamp on synchronized clocks among the validator nodes in the network and the number of validators–in order to prevent validators from arbitrarily creating blocks at irregular intervals.

3. If a validator fails to create a block when it is selected (e.g., because of hardware problems on the side of the validator) or its block fails to be validated by the pool of nodes (e.g., because of network connectivity problems), the next validator proceeds to create a block with whatever transactions haven’t been processed.

4. The remaining validator nodes verify that the transactions in each block are legitimate for that time window, sign the block with their private keys, and propagate the signed block to the network.

5. Once a simple majority of validators have authored a block on top of a given signed block, finality is achieved for that given block, and the block is confirmed by the network and added to the chain.

Additional Resources

• AuRa Proof-of-Authority white paper

• “What is "proof of work" and "proof of stake"? On CoinBase

• “Blockchain Consensus: A Simple Explanation Anyone Can Understand” on Blockgeeks

As a Proof-of-Authority network, the Energy Web Chain is governed by its community of known, vetted validators: https://validators.energyweb.org/

The fundamental tenet of the EW Chain governance mechanism is "one validator = one vote", so each validator is equal in terms of decision-making power. The primary function of the governance mechanism is to make decisions regarding:

• Validator eligibility & operational standards / procedures

• Technical changes & updates to the EW Chain (e.g. network upgrades, client updates, etc.)

• Utilization of the Energy Web Community Fund

• Evolution of the governance mechanism itself

All decisions are made via a formal voting process, with a simple majority of "yes" votes required to adopt a proposal.

Within the EW Chain validator set, there are three committees that provide leadership and recommendations in three areas as follows:

• The Technical Committee focuses on technical upgrades and modifications of the core EW Chain system components as well as the security and performance of validator nodes.

• The Community Fund Committee focuses the utilization of the EW Community Fund, including proposals and grants.

• The Operations Committee focuses on day-to-day operations of the EW Chain and validator community, including facilitating governance meetings/voting events and managing the governance process itself.

All governance decisions impacting the EW Chain begin with a formal proposal, which is reviewed and ultimately decided by a vote among all validators. The process for making and implementing decisions is as follows:

1. Validators coordinate proposals via monthly meetings and a dedicated governance forum (this is only available to active validators; a public summary of governance meetings and decisions is published separately).

2. Proposals are specific changes to the EW Chain protocol, governance mechanism, or operating procedures that require a collective decision by the EW Chain validators. All Proposals are evaluated on an individual, case-by-case basis. Any validator is free to make a Proposal by creating a new Proposal Page in the Governance Forum.

   1. When a Proposal is created, it is announced to the entire validator community via Slack, email, and meetings. It is then open for comment and review for a period of up to 10 days to provide the validators with an opportunity to offer feedback or revisions to the Proposal language. Once the feedback period expires, the language of the Proposal is finalized.

3. One or more Proposals are batched into a Voting Event; there is maximum of one Voting Event in any given month. When one or more Proposals are finalized and ready for a vote, the Operations Committee administers the voting process itself:

   1. On average there are 1-2 voting events per quarter (note: the frequency of voting events varies depending on the volume and complexity of proposals, but the intent is to maintain a voting schedule at regular intervals so all validators know in advance when they should expect to evaluate and decide on Proposals).

   2. A voting event is defined as a ten-day period during which Proposal polls will be open for voting.

   3. Each voting event will feature all Proposals that have not been formally decided since the preceding voting event (i.e. all new or pending Proposals).

   4. Voting events are announced at least one week in advance via the regular monthly validator governance call, and via Slack, email, and the Discuss Forum. This announcement will also specify which Proposal(s) shall be decided in the current voting event.

4. Voting is performed via a binary poll on each Proposal page in the Governance Forum. A “Yes” vote means adopting the proposal exactly as worded and a “No” vote means rejecting the proposal in its entirety.

5. For a Proposal to be accepted (i.e. a change will be implemented as described in the Proposal) greater than 50% of active validators must vote “Yes”. Any Proposal that does not achieve greater than 50% approval will be rejected; this means the status quo is the default position.

   1. Each validator organization is entitled to one vote, therefore the total number of votes is equal to the total number of validator nodes. The Operations Committee acts as an administrator capable of reviewing vote submissions and will delete any duplicate votes from validator organizations.

   2. Non-participation (i.e. a validator does not cast a vote) is counted as a “No” vote by default. This means that in order to implement the change as described in the Proposal, a majority of validators must proactively vote “Yes”.

      1. For example, if there are 20 validator nodes then there are 20 total votes in the current voting event. In this case a Proposal will only be adopted if 11 or more validators vote “Yes”.

   3. Validators are required to participate in at least 90% of voting events each year. During each voting event, all validators receive multiple instructions / reminders via email and Slack to ensure that they have the requisite knowledge and capacity for casting a vote. Failure to participate in at least 90% voting events violates the Validator Code of Conduct, and may result in penalties.

6. Each validator organization designates only one representative to cast its vote during the voting period. Each voting representative acknowledges that they are responsible for casting a vote on behalf of their company, and that their company’s vote will be shared with the other validators. Every validator organization is responsible for its own internal policies and procedures for voting event participation. Validators recognize that casting a vote for or against a given Proposal is binding for that Proposal only.

   1. If multiple users from a single validator organization accidentially cast congruent votes (i.e. all votes are aligned), the Operations Committee will automatically de-duplicate the results and the company’s vote will be recorded accordingly.

   2. If multiple users from a single validator organization cast conflicting votes (e.g. some “yes” and some “no”), the Operations Committee will attempt to contact the representative(s) of the validator to clarify which position is correct. If the validator’s position is not confirmed by the end of the voting period, then the conflicting votes shall be collectively be counted as a “No” vote by the validator for that Proposal.

7. The voting poll automatically closes 10 days after opening, giving validators two full business weeks to cast their vote. Upon closing of the voting period, the anonymized results (i.e. distribution of votes between “Yes” and “No”) will be automatically viewable on the Proposal Topic page.

Governance process

All governance decisions impacting the EW Chain begin with a formal proposal, which is reviewed and ultimately decided by a vote among all validators. The process for making and implementing decisions is as follows:

1. Validators coordinate proposals via monthly meetings and a dedicated governance forum (this is only available to active validators; a public summary of governance meetings and decisions is published separately).

2. Proposals are specific changes to the EW Chain protocol, governance mechanism, or operating procedures that require a collective decision by the EW Chain validators. All Proposals are evaluated on an individual, case-by-case basis. Any validator is free to make a Proposal by creating a new Proposal Page in the Governance Forum.

   1. When a Proposal is created, it is announced to the entire validator community via Slack, email, and meetings. It is then open for comment and review for a period of up to 10 days to provide the validators with an opportunity to offer feedback or revisions to the Proposal language. Once the feedback period expires, the language of the Proposal is finalized.

3. One or more Proposals are batched into a Voting Event; there is maximum of one Voting Event in any given month. When one or more Proposals are finalized and ready for a vote, the Operations Committee administers the voting process itself:

   1. On average there are 1-2 voting events per quarter (note: the frequency of voting events varies depending on the volume and complexity of proposals, but the intent is to maintain a voting schedule at regular intervals so all validators know in advance when they should expect to evaluate and decide on Proposals).

   2. A voting event is defined as a ten-day period during which Proposal polls will be open for voting.

   3. Each voting event will feature all Proposals that have not been formally decided since the preceding voting event (i.e. all new or pending Proposals).

   4. Voting events are announced at least one week in advance via the regular monthly validator governance call, and via Slack, email, and the Discuss Forum. This announcement will also specify which Proposal(s) shall be decided in the current voting event.

4. Voting is performed via a binary poll on each Proposal page in the Governance Forum. A “Yes” vote means adopting the proposal exactly as worded and a “No” vote means rejecting the proposal in its entirety.

5. For a Proposal to be accepted (i.e. a change will be implemented as described in the Proposal) greater than 50% of active validators must vote “Yes”. Any Proposal that does not achieve greater than 50% approval will be rejected; this means the status quo is the default position.

   1. Each validator organization is entitled to one vote, therefore the total number of votes is equal to the total number of validator nodes. The Operations Committee acts as an administrator capable of reviewing vote submissions and will delete any duplicate votes from validator organizations.

   2. Non-participation (i.e. a validator does not cast a vote) is counted as a “No” vote by default. This means that in order to implement the change as described in the Proposal, a majority of validators must proactively vote “Yes”.

      1. For example, if there are 20 validator nodes then there are 20 total votes in the current voting event. In this case a Proposal will only be adopted if 11 or more validators vote “Yes”.

   3. Validators are required to participate in at least 90% of voting events each year. During each voting event, all validators receive multiple instructions / reminders via email and Slack to ensure that they have the requisite knowledge and capacity for casting a vote. Failure to participate in at least 90% voting events violates the Validator Code of Conduct, and may result in penalties.

6. Each validator organization designates only one representative to cast its vote during the voting period. Each voting representative acknowledges that they are responsible for casting a vote on behalf of their company, and that their company’s vote will be shared with the other validators. Every validator organization is responsible for its own internal policies and procedures for voting event participation. Validators recognize that casting a vote for or against a given Proposal is binding for that Proposal only.

   1. If multiple users from a single validator organization accidentially cast congruent votes (i.e. all votes are aligned), the Operations Committee will automatically de-duplicate the results and the company’s vote will be recorded accordingly.

   2. If multiple users from a single validator organization cast conflicting votes (e.g. some “yes” and some “no”), the Operations Committee will attempt to contact the representative(s) of the validator to clarify which position is correct. If the validator’s position is not confirmed by the end of the voting period, then the conflicting votes shall be collectively be counted as a “No” vote by the validator for that Proposal.

7. The voting poll automatically closes 10 days after opening, giving validators two full business weeks to cast their vote. Upon closing of the voting period, the anonymized results (i.e. distribution of votes between “Yes” and “No”) will be automatically viewable on the Proposal Topic page.

• Following the close of the voting period, the Operations Committee reviews the votes to ensure that only one vote per validator organization is counted.

• Though the vote itself is “secret” voting, meaning no voters have knowledge of how other voters have cast their ballot, the final results indicating how each validator votes are shared with the rest of the validator set (and no other parties) after the voting period closes via documentation in the Proposal Topic page in order to maintain accountability, establish a robust audit trail for posterity, and reduce the potential for vote buying or collusion.

• For accepted proposals (defined as greater than 50% of total votes cast in favor / “Yes”):

  • The relevant validator Committee works with the validator(s) who initiated the proposal to formulate an implementation plan and timeline.

• For rejected proposals (defined as less than or equal to 50% of total votes cast in favor / “Yes”):

  • The validator(s) who initiated the proposal or who voted in favor of the failed proposal may revise the language and/or parameters of the proposal and present the revised proposal to the community for consideration. Revised proposals that materially differ from the original rejected proposals may be put to a vote the following month.

  • Rejected proposals that are not materially revised may be re-considered for a vote after a period of 6 months following the rejection vote has elapsed.

The defining feature of the Energy Web Chain is its Proof of Authority consensus mechanism, which relies on reputable entities with valid authority in the global energy sector (i.e. actual market influence) to credibly maintain trust in the network. The adoption and success of the EW Chain is dependent on maintaining an engaged, active community of validators.

Like any community, the EWC validators must be aligned on a common set of principles and follow mutually-agreed upon rules. This Code of Conduct defines the operational and governance expectations and responsibilities for EWC validator organizations. The Code was formally adopted by a supermajority vote in December 2020 and amended by majority vote in December 2021.

Community Expectations for EW Chain Validators

Organizations hosting validator nodes must:

• Proactively contribute to the EW Chain community in one or more of the following ways:

  • Developing Applications & projects: Building or participating in projects, applications, or markets that utilize the open-source EW-DOS technology stack.

  • Contribution to EW-DOS open-source code: Submitting pull requests to any of the open-source EW-DOS repositories, including the EW Chain, Utility Layer, and Toolkits.

  • Contributing to Community Fund Proposals: Identifying opportunities to leverage the Community Fund to support the development or integration of other relevant technologies/projects into the EW Chain or broader EW-DOS stack.

  • Contributing to Governance Proposals: Creating, responding to, and participating in threads (topic discussions) and formal voting proposals in the governance forum on a regular basis.

  • Community Building: Identifying and recruiting other organizations (e.g. energy market participants, regulators, researchers, technology partners) to participate in projects and/or the EWF community.

• Actively participate in the EWC Validator Community:

  • At least one representative from each validator organization should attend the monthly governance meetings on a regular basis.

  • At least one representative from each validator organization should regularly (at least monthly) engage in the EWC governance forum to create or respond to different topics and proposals.

  • Engaging in discussions and helping answer questions from peers in the dedicated validator communication and support channels.

• Hold themselves and peer validators accountable to:

  • Act with honesty, integrity, and openness in working in the best interest of the EWC community.

  • Comply with all applicable laws, rules, and regulations, particularly anti-bribery, anti-corruption, and anti-money-laundering laws, rules, and regulations.

  • Avoid conflicts of interest between the validator organization (and its core business) and the EWC (and EWC community).

• Refrain from the following unacceptable behavior:

  • Non-participation: Organizations cannot just “set it and forget it”; if an organization sets up a validator node and subsequently never joins calls, participates in discussions, or contributes the the EWC community in any way then they will face a penalty or be removed from the validator set.

  • Obvious rent-seeking: The EW Chain is operated by and designed for the energy industry; its purpose (i.e. utility) is to support novel digital solutions that help advance the global energy transition. Validators who are transparently motivated solely by EWT block rewards, abuse their position as validators to create deleterious effects on EWT markets, and/or do not contribute to the mission and success of the EWC ecosystem as described above, will face temporary suspension and/or expulsion from the validator set. Rent-seeking is defined as validators liquidating greater than 10% of their block reward balance within any given 30-day period.

  • Lack of communication: Organizations who do not respond to official validator communications in the event of an operational or governance task will face temporary suspension and/or possible expulsion.

EW Chain Validator Organizational Accountability

Organizations who host EW Chain validator nodes are responsible for the following:

• Keeping their node healthy and private keys secure. This includes implementing best practices for key management, regular maintenance / updates to the node host environment, and proactively alerting the EWC community if they identify any potential bugs, vulnerabilities, or risks that can impact validator nodes. Validator organizations are expected to perform node updates in a timely manner to support EWC network upgrades.

• Monitoring their node. Proactively monitoring their node for issues and identifying faults that result in the node failing to successfully seal blocks.

• Maintaining internal technical expertise to be self-sufficient. Each organization must possess sufficient internal technical resources to perform routine maintenance on the node / host environment as well as independent troubleshooting and fault diagnosis using the Wiki, Github, and the validator Slack channels (i.e. other validators in the community) as primary support tools.

• Responding to official EWC validator communications in a timely manner. Validator organizations are expected to maintain an accurate contact list and respond to communications related to the operation and governance of the EWC.

• Dedicating time to participate in meetings and governance decisions. At least one representative from each validator organization should plan on dedicating sufficient time each month to participate in calls, review documentation, and engage in the governance forum.

Code of Conduct Requirements & Enforcement

The following requirements were adopted by a majority vote in December 2021 and are effective immediately. These requirements are in addition to all existing terms of the Code and will be automatically monitored on a forward basis using the Validator dashboard (2022 onwards).

Validator Node Health Requirements

1. Each Validator node must achieve at least 95% uptime on a rolling 30-day basis (equivalent to no more than 36 hours of unplanned outages over the preceding 30-day period). A node is considered failed if it falls more than 120 blocks behind the latest block and/or fails to seal a block at its designated slot for 5 or more consecutive authority rounds. Node outages during regularly-scheduled network upgrades or planned maintenance windows are excluded from this requirement.

Governance & Community Participation Requirements

1. Energy Web Validators must participate in at least 75% of governance meetings and 90% of voting events on a rolling 6-month basis. Participation is defined as having one or more representatives from the Validator organization attending meetings and having one representative from the organization casting a vote in open proposals within the governance forum, respectively.

2. Each quarter, all Energy Web Validators must demonstrate at least one specific example of community participation as defined in the Code (i.e. Developing Projects & Applications, Contribution to open-source EW-DOS source code, Contributing to Governance Proposals, Contributing to Community Fund Proposals, Community Building).

Energy Web Token (EWT) Block Reward Requirements

As leaders and stewards of the EWC, Validators commit to responsibly managing liquidation of EWT reward balances so as to not create deleterious effects on EWT markets. Validators qualify to transfer block rewards from payout addresses to known exchanges if three requirements are met:

1. Time requirement: Validators must successfully host a node and comply with the Validator Code of Conduct for a period of 6 consecutive months following initial Validator node activation.

2. Balance requirement: Validators must maintain a minimum balance of block rewards equal to or greater than the trailing 6-month average reward earned per validator (for example, if the average validator earned 15,000 EWT total in block rewards in the preceding 6 months, all validators must maintain a balance of at least 15,000 EWT in their payout addresses to remain eligible).

3. Rent-seeking requirement: Once the time and balance requirements above are met, Validators may only transfer a maximum of 10% of their current block reward balance within any given 30-day period to known exchange addresses.

Current block reward balance is defined as the sum of EWT held in the Validator’s payout address(es) and EWT used in the Energy Web ecosystem on a rolling 12 month basis for business activity including but not limited to paying Energy Web Membership dues, Energy Web Chain transaction fees, procuring Utility Layer services, and staking EWT.

These requirements are designed to incentivize Validators to use EWT earned from block rewards in the Energy Web ecosystem.

Validator adherence to the Code of Conduct will be automatically monitored using the Energy Web Validator dashboard, which will collect data from the Validator governance forum, node telemetry, and the EWC itself to assign a quantitative performance score for each of the above categories.

The performance of each Validator will be made public via the dashboard so Validators and the wider community can hold each Validator accountable for maintaining compliance.

The Code will be enforced objectively as follows:

• Single violation, defined as an initial breach of any one of the above categories, will result in an immediate two-week suspension of the validator node.

• Secondary violation, defined as a breach of two categories concurrently, a breach of the code as listed below, or a second violation of a single category within a rolling 12-month period, will result in an immediate four-week suspension of the validator node. Reinstatement of the node is contingent upon the Validator submitting a written plan to remedy past violations and maintain compliance with the Code of Conduct within the governance forum.

  • Failure to perform necessary node updates as part of a planned network upgrade;

• Significant violation, defined as a breach of all three categories concurrently, a breach of the code as listed below, or two or more secondary violations within a rolling 12-month period, will result in permanent expulsion from the EW Chain validator community.

  • Experiencing a major security failure in which a validator node's host machine and/or private keys are compromised by unauthorized actors;

  • Engaging in illegal, unethical, or anticompetitive behavior;

EWC validator nodes can:

• Establish consensus about the state of the network by verifying the work / behavior of other validator nodes;

• Reject blocks / transactions that violate input/output protocols defined by AuRa and the EVM state transition function;

• Implement permissioning functions as described (note: permissoining functions can only be implemented via a majority governance decision).

EWC validator nodes CANNOT:

• Inspect or approve the contents of individual transactions;

• Unilaterally verify transactions (any given transaction is only finalized after n/2 blocks, with n=total validators);

• Associate identities with on-chain accounts;

• Unilaterally modify account permissions, network topology, or network state.

At the time of the launch of the EWC in June 2019, the initial cohort of 10 Validators (all of whom were founding EWF Affiliates) decided that organizations must meet the following criteria to be eligible to become EWC Validators:

1. Be legally registered organizations (not individuals);

2. Be an official Member of EWF (i.e. have an active Membership in good standing), and;

3. Demonstrate technical and security competence

In February 2020, the Validators asked for greater transparency and a formal structure for the EW membership program. The primary objective is to ensure that all members have sufficient reputation (i.e. good standing) and operational capabilities to strengthen the EW Chain and EW-DOS utility layer. Based on this feedback, the eligibility criteria for EW Membership was updated as follows:

To be eligible for EW Membership, organizations must:

1. Have legitimate operational activities that will contribute to the mission of EWF and the success of the EW Chain; this includes energy market participants (e.g. grid/market operators, utilities/retailers, aggregators), organizations who provide products and services to energy market participants (e.g. OEMs/technology providers, regulatory/research organizations, financial services), and organizations who actively contribute to the development of open-source technology that enhances the Energy Web Decentralized Operating System.

2. Have sufficient reputation (or “authority”) to credibly strengthen the Proof-of-Authority consensus mechanism (i.e. must have a minimum of three customer/project references that demonstrate the nature of the operational activities described above).

If you are part of an organization interested in becoming an Energy Web Member and EWC validator, please visit

Welcome to the homepage for Energy Web Chain validator technical documentation!

This space is organized into two primary groups:

• : Start here if you are new to the EWC validator community and setting up a node for the first time.

• : Here you will find step-by-step instructions for a variety of operational and maintenance tasks.

If you need further information or troubleshooting assistance, please use the dedicated .

Validators who opt to install and run their nodes externally can use to install and host their Validator Nodes. This presents major advantages as the platform will fully support your node and handle the technical requirements. Additionally, spinning up your nodes using Launchpad is a lot quicker and does not require a high technical proficiency.

Energy Web members still benefit from 1 EWC and 1 Volta node even when using Launchpad. There is the option to chose to bring your own cloud (BYOC) or to use a managed cloud in which case there is a hosting fee.

Find detailed instructions in our .

You can choose to run your validator node either On-Premise on your own hardware or on a virtual machine / cloud computing instance of your choosing. If you have any questions please contact the EWF NetOps team:

The following specifications are strongly recommended, but validators are free to configure their host machine at their discretion in accordance with relevant internal policies or requirements. Please note that hosting a node on a machine with insufficient CPU, storage, RAM, and/or networking capacity may result in node failure (e.g. unable to connect to peers, unable to synchronize, unable to seal blocks) and require extra labor to reconfigure the host machine.

On-Premise Hardware

A on-premise node should have these specs or higher. For security reasons these resources must be reserved for the validator node and not shared with other workloads.

1. Modern Multi-core x64 CPU (at least 4 threads, preferably Xeon-class)

2. 8GB RAM (preferably ECC)

3. Local SSD storage, 300 GB free capacity for blockchain, redundant in RAID-1

4. 1 GBit NIC

Cloud Environments

The following specifications are strongly recommended based on the most common cloud environments used by existing EW Chain validators. You may select any cloud provider of your choosing

Amazon AWS

The following EC2 instance sizes are appropriate to run validators. These resources should be reserved for the validator node and not shared with other workloads.

• m5.xlarge

• m5.2xlarge

• m5a.xlarge

• m5a.2xlarge

• c5.xlarge

• c5.2xlarge

The default EBS storage assigned (normally 8GB) is not large enough to run the node. Make sure to run the node with following EBS storage settings:

• General Purpose SSD (gp2)

• at least 300GB size

Microsoft Azure

The following Azure Virtual Machine sizes are suitable to run a validator. These resources should be reserved for the validator node and not shared with other workloads.

• D4s_v3

• DS3_v2

• B4ms

Use Premium SSD as attached storage with a size of at least 300GB.

Google Cloud

The following Google Cloud Virtual Machine sizes are suitable to run a validator node. These resources should be reserved for the validator node and not shared with other workloads.

• n2-standard-4 and above: https://cloud.google.com/compute/docs/general-purpose-machines#n2_machines

Digital Ocean

The following Digital Ocean Virtual Machine sizes are suitable to run a validator. These resources should be reserved for the validator node and not shared with other workloads.

• General Purpose Droplet: 16 GB memory, 4vCPU

• CPU-Optimized Droplet: 8 GB memory, 4vCPU

Use Block Storage as attached SSD storage with a size of at least 300 GB.

Connectivity Requirements

The following requirements should be met to ensure proper operation:

• Wired connection with 100 MBit/s symmetric link to the internet

• Low latency connection to next internet hop (<5ms)

• No data volume limitations

Even though we recommend a 100MBit/s connection, that connection will likely not be saturated by the node. You can expect 10-30MBit/s when the chain is under load. Traffic will mainly flow on port 30303 (udp/tcp).

The System architecture of a validator node on the Energy Web Chain is made up of two main components. (Note: the original node architecture featured a node control component, but it was never used and formally deprecated in 2020).

Client: The OpenEthereum or Nethermind client that connects the validator to the Energy Web Chain, collects transactions and proposes blocks according to the . Read the documentation of the OpenEthereum client , and the Nethermind client .

Telemetry: There is a monitoring system on the validator node that uses Telegraf to securely send telemetry to an that is connected to and the EWC Validator Data Warehouse & Dashboard. The use of telemetry is opt-in. Validators can disable it if they have their own monitoring system in place that allows for real time tracking of all relevant metrics.

Telemetry data includes:

• CPU usage of the host machine

• Memory usage of the host machine

• Disk usage of the host machine

• Number of connected peers

• List of visible P2P peers

• Current block (latest block synced by the node)

• Network latency to 3 different and major locations (e.g. cloudflare, google, amazon)

• Network throughput

• Network error rate

• Number of SSH keys for the host machine

• Service status for SSH, docker and the parity container

• SHA256 hashes of key system components/binaries

• Current chain specification file (or hash)

The use of telemetry is opt-in. Validators can disable it if they have their own monitoring system in place that allows for real time tracking of all relevant metrics.

Running a validator node requires raised awareness of host and node security as authorities are a main attack surface to disturb operation of the blockchain. The following security rules are strongly recommended:

• No services are permitted to run on the same host that are not part of the validator node package

• All incoming connections on all ports except SSH (22/tcp) and the P2P (30303/tcp, udp) port have to be firewalled on the host with DROP rules. To guarantee proper network etiquette, incoming ICMP has to be accepted.

• SSH access is only allowed for non-root users

• SSH access is only allowed through RSA keys

• Nethermind client RPC endpoints (HTTP, WebSocket) have to be disabled

• System updates have to applied regularly and in a timely manner

• Regular (monthly) run of rootkit detectors

• If you are using AWS please also check out the additional .

The following Linux-based Operating Systems are supported for running a validator node:

• Ubuntu Server 18.04 LTS or later

• Debian 9.8 or later

• CentOS 7 or later

• RedHat Enterprise Linux 7.4 or later

Validators can elect other operating systems at their discretion, but may need to customize the installation scripts. Contact for questions and support.

The following section provide a comprehensive guide for installation of one the supported operating systems. All further deployment procedures are based on the installation results.

Ubuntu Server 18.04 LTS

On-Premise

Procedure based on version 18.04.2.

• Download the ISO from .

• Boot the ISO

• Select English as language

• Choose a convenient keyboard layout

• Choose Install Ubuntu

• Let the network auto-configure -or- configure manually if needed. The system needs an internet connection.

• Select no proxy and keep the mirror address.

• Select Use an entire disk and confirm

• Choose user name and host name in next screen. Choose a strong password.

• Select Install OpenSSH Server but don’t import keys

• Don’t select any snaps and continue

• Finish installation and let it boot to the prompt

• Login as the created user and run a full system update using sudo apt-get update && sudo apt-get dist-upgrade -y

Amazon AWS

Microsoft Azure

The URN for the image is Canonical:UbuntuServer:18.04-LTS:latest

Debian 9.8

On-Premise

• Boot the ISO

• Select Install from the boot screen

• Select English as language

• Select Location based on actual location of the host

• Chose a convenient keyboard layout

• Let the network auto-configure -or- configure manually if needed. The system needs an internet connection.

• Name your host. Change it from debian to something else

• Choose a strong root password

• Create the user account and choose a strong password

• Select the proper timezone

• For the partitions use Guided - use entire disk

• Select All files in one partition

• Finish partitioning and write changes to disk

• Select No when ask to scan more disks

• Choose a mirror close to the host

• Opt-out of the package survey

• on the Software Selection select only SSH Server and standard system utilities

• Install the grub bootloader to MBR and use the primary disk for that

• Finish installation and let it boot to the prompt

• Login as root and run a full system update using 'apt update && apt dist-upgrade -y'

• Reboot

Amazon AWS

Microsoft Azure

The URN for the image is credativ:Debian:9:latest

CentOS 7

On-Premise

• Boot the ISO

• Confirm the automatic boot option Test this media & install CentOS 7

• Choose English as language

• On the installation summary choose Installation destination and confirm automatic partinioning

• Back on the installation summary screen click on Network & Hostname

• Change the hostname

• Enable the network interface and make sure it is configured properly

• Click Done to get back to the summary and click Begin Installation

• During installation set a root password

• Finish installation and let it boot to the prompt

• Login as root and run a system update with 'yum update'

Amazon AWS

Microsoft Azure

The URN for the image is OpenLogic:CentOS:7.5:latest

1. Install the operating system and prepare the host machine according to the requirements (Step 1 in the previous checklist).

2. Select the correct Client installation script matching the desired network and installed OS on the energyweb github:

   • For the VOLTA TEST NETWORK: , or copy the recommended client directory () from the volta-affiliate directory to the host

   • For the main ENERGY WEB CHAIN: , or copy the recommended client directory () from the ewc-affiliate directory to the host

3. Make sure the latest system updates are installed by running :

   • For Debian and Ubuntu:

     For CentOS:

4. Make the script executable with

5. Run the script (NOTE: please do not use the --auto parameter which can be used to take default for node-name and generate a random key).

6. If the installation was successful, it should generate a .txt file (named install-summary.txt) that lists the node address, IP address, and influxDB username/password. You will need to provide these details via a form in the next step to successfully add your validator node to the .

   • If you encounter issues with the installation or the install-summary.txt file is not generated:

     1. First review any to see if there is a known issue.

     2. If the issue is not already known, submit a question in the #validators or #technical_questions channels in the to troubleshoot.

7. Submit node installation details using the appropriate form below:

   1. For the VOLTA TEST NETWORK, enter details .

   2. For the main ENERGY WEB CHAIN, enter details .

8. After submitting the installation summary via the form, you will receive a confirmation email with next steps and links to helpful resources.

Pre-Installation Checklist:

1. Review the validator node , , and carefully. Then choose a host environment (on-premise hardware or qualified cloud provider) and favored operating system.

2. Assign a static public IP address to the host.

   • Make sure that the public IP will not change over time.

     • Additional information for AWS:

     • Additional information for Azure:

3. Verify that the host is dedicated only for the EW Chain Validator client.

   • If yes, proceed to the next step.

   • If no, remove all other processes / applications from the host, or create a new isolated instance.

4. Verify that you have the correct installation script for your chosen OS here:

   1. If yes, then proceed to the next step.

   2. If no, choose the correct installation script before proceeding.

5. Review the default safe firewall settings set up by the installation script.

   1. Do these settings comply with your company's firewall settings or will you have to adapt them afterwards?

      1. If the default settings comply with your company’s policies, proceed to the next step.

      2. If the default settings do not comply with your company’s policies, adapt the settings as necessary. If you encounter issues or conflicts with internal IT policies, you can post in the to discuss resolution options.

6. Review the installation script and verify that there are no errors or discrepancies with your system setup (link above).

   1. If errors are observed, open an Issue in the installation script Github repository or post to ta relevant topic in the to resolve.

7. Make sure you have read and understand the operational and governance rules and responsibilities as outlined in the .

8. Read the to ensure you have a robust understanding of the inner workings:

   • Optional: Read the to familiarize yourself with the overall system.

9. Confirm that you have at least two ways to contact EWF and the valdiator community if you encounter problems:

   • NetOps distribution list:

   • Join the #validator channel on Slack:

   • Join the #technical-discussions channel on Slack:

10. Ensure that you are prepared to receive and securely handle value-bearing Energy Web Tokens (“EWT”) from block rewards at the time your validator is added to the validator set.

    • EWF strongly recommends that your organization implements a robust internal governance process and security policy for managing the validator node private keys, accessing the node, and managing its EWT balance.

    • If you would like to hold block rewards in an address separate from the validator node, you can change the block reward payout address. Please see details. Please note that it is not possible to reallocate transaction fees to a separate account, so all validator nodes will accrue and maintain a balance of EWT from transaction fees.

11. Once all of the above steps are completed, install your validator node following the instructions .

The following commands can be run on a node to aid in daily operation.

Check if the stack is running

Run this command to see the status of all containers:

Restart the whole stack

Restarting after encountering problems

After encountering problems e.g. with the parity client, it is better to run

If after restarting the client you are still encountering problems, you can try to delete the database and re-sync the node (please only do this after trying to restart without deleting the database first; if you have any questions or need assistance please post in the ):

Update a component

Set the desired version in

save it and run

Update configurations

Make the configuration change in either .env or docker-compose.yml

and run

Show logfiles

In docker-stack run

to e.g. show the last 100 lines of the parity client logs run

Validator maintenance documentation is organized as follows:

• Validator Node Architecture

• Service Commands

• Updating the Client

• Changing the Config File

• Checking status & logs

• Migrating a node

• How to transfer EWT from a node

Rationale

In EnergyWebChain network, validator nodes are typically network's stakeholders and they are usually trusted organizations . These validator nodes are responsible for network consensus, verifying state transitions, validating transactions and adding them to the EWC blockchain.

Thus these validator nodes are responsible for maintaining the integrity of the network by ensuring that all transactions are valid. They also play an important role in preventing malicious actors from manipulating the network or adding fraudulent transactions to the blockchain.

Importance to secure the validator node

There are several reasons to secure and protect validator node:

• Validator nodes hold sensitive information, such as private keys, keystore file, secret etc which must be protected to ensure the security of the network.

• Trust is a critical aspect of any blockchain network, and if a validator node is compromised, it can lead to a loss of trust in the network among its users and stakeholders.

• If a validator node is compromised, it can potentially allow malicious actors to add fraudulent transactions to the blockchain, which can undermine the integrity of the entire network.

• A secure validator node is important for maintaining the performance and scalability of the network, as it ensures that the network can handle a high volume of transactions without any issues.

Securing a validator node is critical to the overall security and integrity of the network, and it is essential to maintaining the trust and confidence of its users, members and stakeholders.

For these the validator members' must have infrastructure to protect the validators from any kind of attacks.

Protect your validator node from unauthorized access

In EnergyWebChain (Proof of Authority) network, the validator nodes are run by recognized enterprises, organizations. These nodes are responsible for validating transactions and blocks. It's important to ensure that access to validator nodes is properly secured and controlled.

Here are some best practices for securing validator nodes from an access perspective

• Limit access to validator nodes to only those users who need it, as this helps to prevent unauthorized access and reduces the attack surface. This can be achieved by using role-based access control (RBAC) and granting access only to users with specific job functions.

• The principle of least privilege states that users should only have the minimum level of access necessary to perform their job function. This helps to prevent unauthorized access and misuse, as users are only able to access the nodes that they need to perform their job.

• Monitor and log access to validator nodes, this helps to detect and respond to any suspicious or malicious activity, and to identify potential security breaches. Access logs should be regularly reviewed and analyzed to identify any unusual activity, such as repeated login attempts or attempts to access nodes that the user does not have access to.

• Configure firewalls to block unauthorized access to validator nodes and restrict access to specific ports and IP addresses.

• It is important to train employees on the importance of security and on the proper procedures for accessing validator nodes. This helps to prevent accidental security breaches and to ensure that employees understand the importance of following security best practices.

Securing validator nodes from an access perspective requires a combination of technical and procedural measures. By limiting access to only necessary users, using RBAC, monitoring and logging access, organizations can ensure that validator nodes are secure.

These are just a few of the many best practices that organizations can use to secure their validator nodes.

It's important to mention that, even following all the steps mentioned above, there's no guarantee that a validator node will never be compromised; it's important to have an incident response plan in place and to be prepared to take action in the event of a security incident.

Secure your validator node

Securing validator nodes in a on-premise environment or cloud platform is always a complex process. Here are some steps that can be taken to secure validator nodes:

• Use virtual machines that have been configured to meet security best practices, such as using secure images, applying security patches, and limiting access to specific ports and IP addresses.

• Take advantage of cloud-native security features, such as firewalls, intrusion detection and prevention systems, and encryption services, to protect validator nodes from external threats.

• Firewalls can be used to block unauthorized access to validator nodes and to restrict access to specific ports and IP addresses, also control inbound and outbound traffic to validator nodes and to restrict access to specific ports and IP addresses.

  • It’s worth to note that validator node should listen only p2p port (30303); other than that node should not listen on any other port.

• Use a virtual private cloud (VPC) to create a private, isolated network for validator nodes, which can help prevent unauthorized access or eavesdropping.

• Use identity and access management (IAM) to control access to validator nodes and to ensure that only authorized users can access them.

• Use monitoring and logging tools to track and record activity on validator nodes, which can help detect and respond to any suspicious or malicious activity.

• Monitoring network activity can help detect and respond to any suspicious or malicious activity that may be targeting validator nodes.

• Regular security audit helps to identify and resolve any security weaknesses or vulnerabilities of validator nodes.

• Regularly updating software and applying security patches can help protect validator nodes from known vulnerabilities.

• Use a cloud security provider to manage and secure validator nodes, which can help to ensure that they are configured and maintained in accordance with security best practices.

• Follow Linux best practices like

  • Disable root login and password authentication for SSH

  • Disable non-essential SSH subsystems

  • Disable unwanted services and daemons

By following these practices, organizations can help prevent unauthorized access, reduce the attack surface, data breaches, and other security incidents and maintain the trustworthiness of the blockchain and ensure the security of their validator nodes.

It's important to mention that security in on-premise environment or cloud platforms is an ongoing process; it's worth to stay up-to-date with the latest security best practices and to continuously monitor and update the security of validator nodes.

EWF strongly recommends that your organization implements a robust internal governance process and security policy for managing the validator node private keys, accessing the node, and managing its EWT balance.

Recommended links to check

• AWS Best Practices for Security, Identity, & Compliance

• Azure security best practices and patterns

• Google Cloud security best practices center

• DigitalOcean - Recommended Security Measures to Protect Your Servers

• 23 Linux Server Security Tips and Best Practices

Wait a little bit longer

If you are not connected to any peers right away, often it can help to just wait a little longer and give the node a little time to connect to other peers. If the node is still not connected after a couple of minutes, there is probably a problem.

Sync your local time

If you have trouble connecting to peers you should first check if the local time on your device is exact. Go to http://time.is/ and ensure it says: “Your time is exact”. If your time is not exact, go to System Preferences and make sure it is synchronized.

To make sure that your clock is always synchronized you can also use the ntp-pool-project, a big virtual cluster of timeservers providing reliable easy to use NTP service for millions of clients: http://www.pool.ntp.org/en/

Basic instructions on how to set up ntp-pool can be found here: http://www.pool.ntp.org/en/use.html

More detailed instructions for different operating systems can be found here:

Mac: https://www.macworld.com/article/1140509/timeservers.html

Linux: https://www.digitalocean.com/community/tutorials/how-to-configure-ntp-for-use-in-the-ntp-pool-project-on-ubuntu-16-04

Windows: http://www.satsignal.eu/ntp/setup.html

Delete nodes.json

If your node cannot connect to other peers, it might help to remove your nodes.json file to reestablish a connection. You can find the nodes.js file at the same directory where you store your keys under chain/Volta/network. If you don't know where that is, you can look at the path specified at "Keys Path" when you start the client in the terminal.

Usually it sits at:

$HOME/Library/Application\ Support/io.parity.ethereum/chains/ewc/network/nodes.json

or

$HOME/.local/share/io.parity.ethereum/chains/ewc/network/nodes.json

or

$HOME\AppData\Local\Parity\Ethereum\chains\ewc\network\nodes.json

Make sure the client is not running. Delete the file and than restart the client. A new nodes.js file will be created and you will hopefully connect to peers again.

Manually add peers when starting the client

First download this file that contains the enodes of our new bootnodes here: Volta_bootnodes.txt . Afterwards you can start the client with the reserved-peers flag like this:

Or follow the below steps (recommended)

1. Download the Volta_bootnodes.txt file in the node instance and save it in $(pwd)/docker-stack/config/ directory

2. Edit the parity-signing.toml & parity-non-signing.toml file

   1. Add the following line in [network] section

   2. reserved_peers = "/parity/config/bootnodes"

   3. Recreate the containers. docker-compose up -d --force-recreate

Manually add peers

If you are not able to find any peers or you want to connect to a specific peer you can add peers manually.

Make sure that the parity API's are enabled by starting the client with the flag

To manually add a peer open your terminal and use the parity_addReservedPeer function. This adds the peer to the list of peers your node is trying to connect to (more info here):

The Peer ID that you need for this function are called enodes and have this format (this is one of our bootnodes, it should already be on your nodes list by default): enode://59c9250cb805409e84c9cd0038e97d8e5e4605b928663675869ebdfd4c251d80ccad76267a5eb2f4362ddceb5ec671f7595463adfc0a12e9f68dbf233072db41@54.70.158.106:30303

To get information about your peers you can use the parity_netPeers function (more info here):

The output will not be very easily readable, use this website to format it into something you can read: https://jsonformatter.curiousconcept.com/

At the very top it will give you the number oft active, connected and max peers. Active means, they are actively synchronizing the chain, a 0 basically means you are already fully synchronized or have no peers at all. Connected are all peers, which you are listening to for new blocks and transactions, ideally this should not be 0. Max is just the maximum number of peers you can connect to.

Below that you will see a list of peers your node is trying to connect to. Peers with non-empty protocols have completed handshake and are currently connected to you. You can find them quickly by searching for "difficulty" or "head".

Allow UDP traffic

If all this still does not resolve the problem, you should check if there is some firewall in place that causes the problem and make sure your network does not block UDP traffic.

Report Problem

Prerequisites

1. Check Docker Image, NPM Package

   1. Docker Image:

      1. ewf-validator-tool

      2. ewf-validator-tool:latest

   2. Github Repo of ewf-validator-tool

   3. NPM Package ewf-validator-tool

2. In the Validator Node - get the path of the following two files -

   1. keyfile - UTC--*

      1. In Parity/OpenEthereum Validator Node, the path of keyfile is -

         • $HOME/docker-stack/chain-data/keys/$CHAINNAME/UTC--* [CHAINNAME can be Volta or EnergyWeb]

   2. secret file - .secret

      1. In Parity/OpenEthereum Validator Node, the path of secret file is -

         • $HOME/docker-stack/.secret

Execution of ewf-validator-tool Using Docker

1. Put the the value before execution:

   1. KEYFILE_PATH : path of keyfile in old validator node

   2. SECRETFILE_PATH : path of secret file in old validator node

   3. NEW_ADDRESS : Address of wallet or new node address

   4. TOKEN_AMOUNT: Amount of token to be taken out

   5. HTTPS_RPC_URL :

      1. Volta HTTPS_RPC_URL: https://volta-rpc.energyweb.org

      2. EnergyWeb HTTPS_RPC_URL: https://rpc.energyweb.org

2. Command to transfer token

   1. Before execute take superuser privilege - sudo -s or run docker with sudo

docker run -it -v "$KEYFILE_PATH":/keyfile -v $SECRETFILE_PATH:/keypass aznagy/ewf-validator-tool:latest transferto $NEW_ADDRESS $TOKEN_AMOUNT -r $HTTPS_RPC_URL

Example:

Here is an example

(It is Nethermind validator node, that’s why the path of keyfile and secret file are different than Parity validator node)

1. Transfer token from Volta Validator Node to Hardware Wallet -

   1. KEYFILE_PATH : keyfile path of my Validator Node

      • /home/ubuntu/docker-stack/keystore/UTC--2020-12-21T16-47-06.412446000Z--5125254ec2e024d8226cf4c389512c43802a76a1

   2. SECRETFILE_PATH : secret file path of my Validator Node

      • /home/ubuntu/docker-stack/keystore/.secret

2. NEW_ADDRESS : Address of my wallet 0x4933915c40477Db3a9AccA3Fa12DaA8ba5D4fD35

3. TOKEN_AMOUNT: 0.01

4. HTTPS_RPC_URL : Volta HTTPS_RPC_URL: https://volta-rpc.energyweb.org

Command

Transfer Token

docker run -it -v "/home/ubuntu/docker-stack/keystore/UTC--2020-12-21T16-47-06.412446000Z--5125254ec2e024d8226cf4c389512c43802a76a1":/keyfile -v /home/ubuntu/docker-stack/keystore/.secret:/keypass aznagy/ewf-validator-tool:latest transferto 0x4933915c40477Db3a9AccA3Fa12DaA8ba5D4fD35 0.01 -r https://volta-rpc.energyweb.org1

Output

Connected to Volta (test network)
Successful transaction!
{
  "blockHash": "0xbca95daf204c80a6c1cf49005128213e0adb0803942ef34fba066f0c5e23f551",
  "blockNumber": 9763320,
  "contractAddress": null,
  "cumulativeGasUsed": 21000,
  "from": "0x5125254Ec2E024D8226cf4c389512c43802a76A1",
  "gasUsed": 21000,
  "logs": [],
  "logsBloom": "0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000",
  "status": true,
  "to": "0x4933915c40477Db3a9AccA3Fa12DaA8ba5D4fD35",
  "transactionHash": "0xef7fd88dff637b5528fd706500f855077eb8e88a29a2a0738e394d1459f56542",
  "transactionIndex": 0
}

Check in the Explorer

1. URL_Token_out => [Address of Old Validator Node] 0x5125254Ec2E024D8226cf4c389512c43802a76A1

1. URL Token_In => [Address of wallet] 0x4933915c40477Db3a9AccA3Fa12DaA8ba5D4fD35

Check with validator-tool command: payout check and payout changeto

1. payout check command

docker run -it -v "$KEYFILE_PATH":/keyfile -v $SECRETFILE_PATH:/keypass aznagy/ewf-validator-tool:latest payout check $OLD_NODE_ADDRESS -r $HTTPS_RPC_URL1

Example:

docker run -it -v "/home/ubuntu/docker-stack/keystore/UTC--2020-12-21T16-47-06.412446000Z--5125254ec2e024d8226cf4c389512c43802a76a1":/keyfile -v /home/ubuntu/docker-stack/keystore/.secret:/keypass aznagy/ewf-validator-tool:latest payout check 0x5125254Ec2E024D8226cf4c389512c43802a76A1 0.01 -r https://volta-rpc.energyweb.org1

Output:

Connected to Volta (test network) 
Successful call! Payout address of 0x5125254Ec2E024D8226cf4c389512c43802a76A1 is: 0x4933915c40477Db3a9AccA3Fa12DaA8ba5D4fD35

2. payout changeto command

docker run -it -v "$KEYFILE_PATH":/keyfile -v $SECRETFILE_PATH:/keypass aznagy/ewf-validator-tool:latest payout changeto $NEW_ADDRESS -r $HTTPS_RPC_URL

Example:

docker run -it -v "/home/ubuntu/docker-stack/keystore/UTC--2020-12-21T16-47-06.412446000Z--5125254ec2e024d8226cf4c389512c43802a76a1":/keyfile -v /home/ubuntu/docker-stack/keystore/.secret:/keypass aznagy/ewf-validator-tool:latest payout changeto 0x4933915c40477Db3a9AccA3Fa12DaA8ba5D4fD35 -r https://volta-rpc.energyweb.org

Output:

Connected to Volta (test network)
Change of payout address successful!
{
  "blockHash": "0xef89937584dcc102a3684431a9b46112b617b5d3a4d362e7e9eb4d90e4d6db32",
  "blockNumber": 9763698,
  "contractAddress": null,
  "cumulativeGasUsed": 23494,
  "from": "0x5125254Ec2E024D8226cf4c389512c43802a76A1",
  "gasUsed": 23494,
  "logsBloom": "0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000",
  "status": true,
  "to": "0x1204700000000000000000000000000000000002",
  "transactionHash": "0xd5206399f5a0b6227975720408af216abf4d090abc11e1753885eabfe5e55362",
  "transactionIndex": 0,
  "events": {}
}

Run Validator Tool using npm package

If you want to execute validator tool on host machine or local machine without using docker, follow the following process.

Prerequisite:

1. Install node and npm

   • nodejs v8 or higher and LTS (recommended)

   • npm comes with nodejs installation.

   • check nodejs and npm version

     • node -v

     • npm -v

2. Install ewf-validator-tool NPM Package on machine

   • npm install -g ewf-validator-tool

   • Check validator-tool is installed

validatortool --version 21.0.3

Execution of ewf-validator-tool

1. From the old (original) Validator Node - get the path or grab the value of the following two files - [If you want to run it on your local machine, just to collect the value of keyfile and .secret file.]

   1. keyfile - UTC--*

   2. In Parity/OpenEthereum Validator Node, the path of keyfile is -

      • $HOME/docker-stack/chain-data/keys/$CHAINNAME/UTC--* [CHAINNAME can be Volta or EnergyWeb]

   3. secret file - .secret

      1. In Parity/OpenEthereum Validator Node, the path of secret file is -

         • $HOME/docker-stack/.secret

   4. HTTPS_RPC_URL : Volta HTTPS_RPC_URL: https://volta-rpc.energyweb.org

2. Command

   1. Transfer Token

      1. You can directly give the path of the keyfile and .secret file Or

      2. the keyfile value is stored in UTC-keyfile and value of .secret is stored in Secretfile

validatortool transferto $NEW_ADDRESS -k "$PATH_OF_KEY_FILE" 0.05 -s $PATH_OF_SECRETFILE -r $HTTPS_RPC_URL

Example

validatortool transferto 0x4933915c40477Db3a9AccA3Fa12DaA8ba5D4fD35 -k "$HOME/docker-stack/chain-data/keys/$CHAINNAME/UTC--*" 0.05 -s $HOME/docker-stack/.secret -r https://volta-rpc.energyweb.org

or

validatortool transferto 0x4933915c40477Db3a9AccA3Fa12DaA8ba5D4fD35 -k "UTC-keyfile" 0.05 -s Secretfile -r https://volta-rpc.energyweb.org

b. payout check command

validatortool payout check $OLD_VALIDATOR_NODE -r $HTTPS_RPC_URL

Example

validatortool payout check 0x5125254Ec2E024D8226cf4c389512c43802a76A1 -r https://volta-rpc.energyweb.org

c. payout changeto command

validatortool payout changeto $NEW_ADDRESS -r $HTTPS_RPC_URL

Example

validatortool payout changeto $0x4933915c40477Db3a9AccA3Fa12DaA8ba5D4fD35 -r https://volta-rpc.energyweb.org

You should get similar output if you run the validator-tool using docker. To get a glimpse of output, please check the above section.

Check the block explorers!

The block explorers allow you to search the specific addresses of your Volta and EWC nodes to see how recently they validated a block.

• https://explorer.energyweb.org/

• http://volta-explorer.energyweb.org/

Once you’ve searched for your address in the block explorers (make sure to search for your EWC address in the EWC explorer and vice versa), navigate to the “Blocks Validated” page to see how recently it validated a block (ex: https://volta-explorer.energyweb.org/address/0xaa31f1988d6049f3e4b54136a261ed22a7e4cf27/validations). With ~30 validators and a 5 second block time, a functioning node validates a block once every ~2:30 minutes. Bookmark the “Block Validated” pages for both your Volta and EWC nodes to easily check if they’re validating.

Using the steps listed below, you can also view your validator node’s “Company Name” in each block it has sealed. The “Company Name” shows up in the extraData field of a block, but it's not shown directly in the explorer.

1. Determine the block number or block hash you want to check from the explorer

2. You can use the following commands to fetch block data:

curl --data '{"method":"eth_getBlockByNumber","params":["0x_blocknumber_in_hex_here",true],"id":1,"jsonrpc":"2.0"}' -H "Content-Type: application/json" -X POST https://volta-rpc.energyweb.org

curl --data '{"method":"eth_getBlockByHash","params":["0x_blockhash_here",true],"id":1,"jsonrpc":"2.0"}' -H "Content-Type: application/json" -X POST https://volta-rpc.energyweb.org

1. Find the extraData field and copy the value,

   • e.g: "extraData":"0x76616c696461746f722d35342e3135342e3130312e353454454f". [This is the company name (or whatever info) you set during the installation encoded as hex]

2. Paste the value here to convert to text: https://onlineutf8tools.com/convert-hexadecimal-to-utf8

SSH into your node and check the containers

Once you SSH into your node, you can use the following commands to check the status of your server and docker containers running validator services.

Use the following command to make sure you have admin rights before running other commands

Run this command to list all running docker containers:

You should see these three containers with STATUS “Up X hours”

• docker-stack_parity_1

• docker-stack_parity-telemetry_1

Check your node’s resources

If your node is hosted by a cloud provider, you will likely have access to a dashboard from that provider with information on the amount of disk space your node has available and other relevant info.

If you are SSH’d into your server, you can also run this command to check if your disk is nearing capacity:

And to see how much disk space your docker containers are using, run:

Check your node’s logs

Logs can give you a view into

sudo -s
cd docker-stack
docker-compose logs

To save your logs and transfer them to your local machine use the following commands

docker-compose logs > ~/YOURCOMPANY_logs.txt

You will likely need to stop (ctrl + c) this after a little while as it doesn’t seem to auto-complete.

Make sure the logs contain whatever timeframe you’re interested in (e.g., when your node stopped syncing).

Now transfer them to the Downloads folder on your personal computer using this command in a fresh terminal:

scp -P 2222 -i YOURKEYS.pem ubuntu@YOUR_INSTANCE:/home/ubuntu/YOURCOMPANY_logs.txt ~/Downloads/

If you were successful, you should see a download bar complete and have the file in your Downloads folder.

Validator Dashboard

[Coming Soon]

• Public-facing dash that only links node attributes to a public address

• Address, # of peers, latest block, list of unsynced nodes

Payout address:

A payout address, also known as a reward address, is the Ethereum address where a validator node receives its rewards for validating transactions and participating in consensus in the network.

The benefit of changing the payout address for a validator node is to allow the operator to receive rewards at a different address. This can be useful for several reasons, such as:

• Better fund management: Node operators can choose to receive rewards at a different address for better management of their funds.

• Security: Node operators can reduce the risk of losing funds in case the original address is compromised.

• Privacy: Node operators can choose to receive rewards at a different address to maintain privacy and separate their reward earnings from their other transactions.

Changing the payout address does not affect the node's ability to validate transactions and participate in consensus, but it will change the destination of the rewards received for participating in the network.

Change Validator Payout address

• See the instruction here - How To Transfer EWT from a Validator Node

EWF recommend that all validators set a separate payout address so that block rewards are issued to another secure wallet (preferably a multi-signature one) instead of the node address itself.

If validator members would like to receive block rewards in an address separate from the validator node, please see instructions for calling the setPayoutAddress function in the Reward Contract for further details.

Please note that it is not possible to reallocate transaction fees to a separate account, so all validator nodes will accrue and maintain a small balance of EWT from transaction fees. Based on historical data, total transaction fee balances are expected to be <1 EWT per month.

Multi-signature contract

A multi-signature contract or multisig contract, is a type of smart contract in the Ethereum network that requires multiple signatures or approvals before certain actions like transferring funds can be taken.

There are several ways to create a multisig contract. One of the example is using Gnosis Safe.

• Create Multi Signature contract address using Gnosis Safe

  • Gnosis Safe Tutorial | Multisig Wallet for DeFi

  • Creating a Safe on a Web browser.

The benefit of using a multi-signature contract for a payout address is that it adds an additional layer of security and control to the management of the rewards. With a multi-sig contract, multiple individuals or entities must be involved in the decision to transfer the rewards, which helps reduce the risk of theft or unauthorized access.

Validator members can have cold storage wallet like hardware wallet, paper wallet for the changed payout address.

To change parameters of the validator client you have to change the config file of your validator node.

In the host, make sure you have root access and go into the config folder

Now you can edit the parity-signing.toml file that should look similar to this:

[parity]
chain = "/parity/config/chainspec.json"
no_persistent_txqueue = true

[rpc]
disable = false
port = 8545
interface = "0.0.0.0"
cors = []
apis = ["eth", "net", "parity", "web3"]

[websockets]
disable = false
interface = "0.0.0.0"
port = 8546

[ipc]
disable = true

[secretstore]
disable = true

[network]
port = 30303
min_peers = 25
max_peers = 50
discovery = true
warp = false
allow_ips = "all"
snapshot_peers = 0
max_pending_peers = 64

[footprint]
db_compaction = "ssd"

[snapshots]
enable = false

[mining]
force_sealing = true
usd_per_tx = "0.000000000000000001"
usd_per_eth = "1"
price_update_period = "hourly"
min_gas_price = 1
gas_cap = "4000000"
gas_floor_target = "4000000"
tx_gas_limit = "4000000"
extra_data = "validator-XXX"
engine_signer = "0xXXX"

[account]
password = ["XXX"]
keys_iterations = XXX

Most parameters should not be changed. But there are several parameters that can be adapted.

Warp Sync

If your node is having trouble syncing after a client update, restarting the node, or an unplanned outage, you can speed up the syncing process by enabling warp sync:

• Under [network] change: warp = true

• Restart docker container: docker-compose up -d

For more information, see https://openethereum.github.io/Warp-Sync

Minimum Gas-Price

The minimum gas price defines the lowest price that you allow to be paid for a transaction in Wei/Gas to still be included into a block by your validator node. Every transaction that has a gas price below that will be ignored. What price to set should depend largely on the transaction volume at the current moment. Every validator can choose this parameter individually. If it is too low, there is little spam protection and spammers can just fill up the blocks for little cost. If it is too high, it unjustifiably increases the price per transaction and might deter usage.

usd_per_tx defines the amount of USD to be paid for a basic transaction of sending tokens. The minimum gas price is set accordingly.

usd_per_eth defines the USD value of one token.

price_update_period defines the time that is allowed to pass between each gas price update. T may be daily, hourly, a number of seconds, or a time string of the form "2 days", "30 minutes" etc.

min_gas_price defines the minimum gas price in Wei/Gas and overrides usd_per_tx.

Block Gas Limit

Validators can choose the size of the blocks and thereby the number of transactions to include in a block. The bigger the blocks, the higher the transaction throughput. But if the block is too big, executing all transactions in that block might create problems with latency. Therefore the EWF will advise on a target blockgas limit. Once the limit is changed in the config file it will slowly increase until it has reached the defined limit. If validators do not agree on a limit, it will increase and decrease depending on who proposed the block.

gas_cap defines the absolute maximum amount of gas that will be allowed in a block depending on the transaction volume.

gas_floor_target defines the block size that the validator node targets when creating a new block.

tx_gas_limit defines the maximum gas amount that is allowed for a single transaction.

You can read about all possible configurations here: https://openethereum.github.io/Configuring-OpenEthereum.html

To restart the validator node, run

The parity client should now be running with the new configurations.

The Energy Web Chain (EWC) is a public, Proof-of-Authority EVM blockchain.

Unlike other consensus mechanisms that depend on solving arbitrary difficult mathematical puzzles (Proof-of-Work) or locking up funds (Proof-of-Stake), (PoA) relies on a trusted set of "authorities" - nodes that are explicitly permissioned to create blocks and secure the network. The EWC uses a specific PoA algorithm called AuRa (for a technical specification of AuRa, see ).

In the EWC, these authorities are called validator nodes; the organizations who host these nodes are referred to as Validators. To maintain credibility and trust, EWC Validators must be known, reputable entities with valid market influence and/or activity in the global energy sector.

EWC Validators have three primary responsibilities:

1. Securely host validator nodes: Each Validator organization is expected to host a validator node on the main EWC as well as the Volta test network (maintaining both is critical to have a test environment that mirrors the production EWC as closely as possible). Hosting a node includes installing, maintaining, and monitoring their node while following best practices for key management, regular maintenance / updates to the node host environment, and proactively alerting the EWC community if they identify any potential bugs, vulnerabilities, or risks that can impact validator nodes.

2. Participate in the EWC Governance: Validators are expected to offer opinions and contribute to technical and non-technical decisions (i.e. voting) relating to modifications of the Energy Web client, protocol, and governance mechanism itself.

3. Actively participate and contribute to the EWC community: All validators are expected to proactively contribute to the EWC community in one or more of the following ways on a regular basis: Developing Applications & projects on the EWC; Contributing to open-source EW-DOS code; Contributing to Community Fund Proposals; Contributing to Governance Proposals; Community Building.

To view the current list of EWC validators, visit

Note: As of October 27, 2021, all EWC nodes should run a London-compatible client: OpenEthereum ( or later) or Nethermind ( or later)

The update schedule

OpenEthereum and Nethermind clients compatible with AuRa are released in a regular rhythm. The process for implementing regular updates is described below. Emergency updates (i.e. in the event of a known security vulnerability with a specific client version) will be accelerated.

All EWC client updates are tested by the Energy Web Chain Technical Committee to ensure compatibility with the EW Chain AuRa consensus mechanism. The Technical Committee strongly recommends validators and other node (e.g. RPC) operators refrain from updating their clients until compatibility with the current version is confirmed on this page. Once an update is tested, the Technical Committee will communicate to validators and the broader community via Slack and Telegram that it is safe to install the new version; this page will also be updated regularly. For security/stability reasons, we recommend rolling out the update in waves, first on Volta and then the production EW Chain.

Updating the client

Manual Upgrade

As the upgrade to OpenEthereum v3.3.0-rc.11 does not involve any config changes or require db resync, it should be relatively simple.

1. Download and verify the new image:

Download the node software (Openethereum v3.3.0-rc.11 or later)

docker pull openethereum/openethereum:v3.3.0-rc.11

Verify the downloaded software to make sure no one has changed something during data transfer

docker image inspect openethereum/openethereum:v3.3.0-rc.11 | jq -r '.[0].Id'

The result should be:

sha256:58ef9c2b1c475fe875fed8d291978bbaac6b19951aa9e8a4686342bbed086fab

If that's the case, proceed to the next step. If not, repeat the process above to download and verify the new image.

2. Make a backups & update image version

• Stop the containers:

• Make a backup of docker-compose.yml:

cp $HOME/docker-stack/docker-compose.yml $HOME/docker-stack/docker-compose.yml_backup

• Make a backup of .env file:

cp $HOME/docker-stack/.env $HOME/docker-stack/.env_backup

• Make a backup of DB [Optional]:

cp -r chain-data/chains/$CHAIN_NAME/ ./$CHAIN_NAME_backup

• Modify and save .env file (lines 3 & 9):

vim $HOME/docker-stack/.env

Modify and save docker-compose.yml file (line no.4):

vi $HOME/docker-stack/docker-compose.yml

New docker-compose.yml

Restart the containers

Check whether the node is running & syncing

Sometimes an organization needs to migrate their validator node into a new environment. Common reasons for this include:

• Changing infrastructure providers (e.g. switching cloud or on-premise vendors)

• Wanting to upgrade host environment configuration

• Rotating access due to security procedures or policies.

If you are currently operating a validator node on Volta of the EW Chain and need to migrate it from its existing host environment to a new one, there are two options:

Install a new node and retire the existing one

• This option requires provisioning a new host environment and following the installation procedures to establish an entirely new node (note: this will result in a new address, private key, EWT balance, etc.). Once your new node is installed, the current one will be removed from the network and you will be able to retire / deprecate the legacy node and host environment.

• The benefits of this approach are:

  • It is easy to replicate the node installation process, so the overall migration is simpler;

  • You don't have to worry about independently modifying the installation script;

  • You can maintain continuity by simultaneously retiring the original node and adding the new one to the network;

• The drawbacks of this approach are:

  • You must determine a secure way to maintain access to the legacy block rewards held on the original node address;

  • Depending on your organization's IT policies and procedures, it may be more complex and costly to procure multiple host environments during the migration.

  • You may need to replicate or modify access management policies and procedures for the new environment.

Migrate your existing node to a new environment

• This option involves migrating the existing node (i.e. maintaining the same address and private key) to a new host environment. To do this, you must extract the private key from the existing environment and then re-run a modified installation script in the new environment, using the private key of the validator node.

• The benefits of this approach are:

  • You maintain continuity by keeping the same address and private key;

  • You don't need to operate two validator nodes (and thus host environments) simultaneously.

• The drawbacks of this approach are:

  • Depending on the parameters of the existing vs. new environment, you may need to modify configurations and access management.

  • You must securely extract the private key from the existing node, temporarily store it, and import it into the new environment.

  • You will experience a period of "downtime" throughout the migration, during which your organization's validator node will not be operational.

Follow the steps to migrate existing nodes to new node:

1. 1. Migrate existing nodes: Follow the steps to migrate existing nodes to new node:

      1. Collect and store the following necessary info from Old Instance -

         1. You can stop containers in old instance. docker-compose down

         2. Value of Validator Address, InfluxDB Username, InfluxDB Password . You’ll find this info in install-summary.txt file.

         3. Value of docker-stack/keystore/.secret To copy the .secret key to your local instance:

            scp -P 2222 -i YOURKEYS.pem user@YOUR_INSTANCE:/home/user/docker-stack/keystore/.secret ~/Downloads/

         5. [optional] keep a backup of docker-stack/ dir.

      2. Commented out the following lines from script

         1. Volta validator installation script

         2. EWC validator installation script

   [line from 180-213] -

   from echo "Creating Account..." [line 180] till docker rm -f nethermind [line 213] .

   1. Then run the script in the new instance.

      1. The End Result would be the the following . Validator Address, Enode, InfluxDB Username and InfluxDB Password field would be empty

         ==== EWF Affiliate Node Install Summary ==== Company: Company_Name Validator Address: Enode: null IP Address: New_IP_ADDESSS InfluxDB Username: InfluxDB Password:

      2. In the new Instance, There is the docker-stack/ dir. Enter to the directory and run docker-compose ps and run docker-compose down to kill node and telemetry containers.

      3. The .secret file in docker-stack/keystoredir needs to be updated with the older one. [ .secret file is in only readonly mode. Change mode before updating with old value. chmod 644 .secret ]

      4. The .env file in docker-stack/ dir needs to be updated.

         1. Update the VALIDATOR_ADDRESS= field with old value.

         2. Update the NETHERMIND_KEY_FILE=./keystore/UTC--* with correct name.

      5. In the docker-stack/configs/volta.cfg or docker-stack/configs/energyweb.cfg, the following 2 value needs to be updated. In the new instance, this value would be empty. Update the value with old Validator Address

         "KeyStore": { "PasswordFiles": ["keystore/.secret"], "UnlockAccounts": ["Old Validator Address goes here..."], "BlockAuthorAccount": "Old Validator Address goes here..." },

      6. Copy the Validator’s mining private key to your new instance

         • Copy the UTC--* file from old instance to docker-stack/keystore dir or create that file in docker-stack/keystore/ dir with exact same name and same value. To copy the file to your local instance:

           scp -P 2222 -i YOURKEYS.pem user@YOUR_INSTANCE:/home/user/docker-stack/keystore/UTC_PART ~/Downloads/

         • [Optional] If you want a exact sync of database, you can copy db files from the old instance to the new instance -

           • DB Path - docker-stack/database/volta or docker-stack/database/energyweb

         • Run docker-compose up -d

         • Check logs of parity container -

           • docker-compose logs -f nethermind

           • docker-compose logs -f nethermind_telemetry

   The Validator’s IP address and enode will change. Once you have completed the migration, fill out the installation summary form (for Volta here, and for Energy Web Chain here) to provide the new IP and enode information. You can also contact netops@energyweb.org to provide notification of the migration.