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.

You can read more about the validator process below.

Energy Web Chain Validators

In other consensus mechanisms, such as Proof-of-Work or Proof-of-Stake, miners can remain anonymous. So long as they meet the proof-of-work or staking requirements, they can process transactions on the blockchain and in many cases do so anonymously.

Validators are not anonymous. They have applied to become a validator and have undergone a a KYC (“Know Your Customer”) process as part of their application. Our validators are well-known members of the energy community, meet the eligibility requirements and the hardware/software installation specifications to become a validator, and they have a vested interest in the Energy Web Chain’s performance. You can see a full list of Energy Web Chain validators here.

Validator Functions

1. Validators create blocks: The fundamental role of the Proof-of-Authority validator is to validate transactions, compile valid transactions into blocks and propagate new blocks to the network.

2. Validators provide network security: By storing the current and historical state of the Energy Web Chain, each validator contributes to the overall integrity and security of the network. Since at least 51% of validators are required to sign each block before it is finalized on the chain, validators provide checks and balances against any erroneous or malicious attempts to publish falsified transactions or alter historical data. Physical decentralization of validator nodes provides redundancy in the event that one or more validators is unavailable due to technical reasons or otherwise compromised.

3. Validators participate in the the Energy Web Chain's governance: Validators will be asked to offer opinions and contribute to technical and non-technical decisions relating to modifications of the Energy Web client, protocol and validator set.

Why Proof-of-Authority?

Energy Web uses Proof-of-Authority consensus for three primary reasons that benefit the Energy Web’s digital infrastructure, the energy sector that will use the technology, and the environment as a whole.

1. To enable transaction capacity on the order of hundreds to thousands of transactions per second: we estimate that the Energy Web Chain has the ability to achieve 30x greater throughput capacity than the Ethereum Mainnet;

2. To minimize resource (i.e. electricity and computation) consumption, and subsequently, transaction costs: Eliminating competitive Proof-of-Work results in 54,000x less energy consumption and 350x lower network costs (i.e. costs incurred by organizations hosting validator nodes) which translates into lower and more stable transaction costs;

3. To improve compliance with relevant regulations and business requirements in the energy sector: substituting fully anonymous miners for vetted validators enhances the ability of decentralized applications to comply with various regulations, including data-protection regulations like GDPR, and increases the likelihood of widespread user and enterprise adoption.

To improve compliance with relevant regulations and business requirements in the energy sector: substituting fully anonymous miners for vetted validators enhances the ability of decentralized applications to comply with various regulations, including data-protection regulations like GDPR, and increases the likelihood of widespread user and enterprise adoption.

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

The Energy Web Chain is comprised of different components that provide the functionalities determined by the blockchain’s protocol.

Broadly speaking, protocols are defined rules and standards. Internet protocols, like HTTP protocol for example, define standard procedures for the transfer of data over the internet.

A blockchain network is no different. In a decentralized and self-executing system like a public blockchain, protocols are of significant importance in establishing how the system works, and then ensuring that the system continues to self-execute as designed.

Protocols exist to determine specific aspects of blockchain behavior, such as:

• How transactions are validated

• Who gets to validate transactions and when

• How validators are compensated

• How peer nodes interact with each other

The system components below ensure that the Energy Web blockchain adheres to Ethereum's protocols, and the protocols established by OpenEthereum's Proof-of-Authority consensus engine. (OpenEthereum is the Ethereum client that is used by the Energy Web Chain. You can read more about the purpose of Ethereum clients here.)

System Components

1. System Contracts

System Contracts are smart contracts that implement the Authority Roundtable Proof-of-Authority consensus engine protocols. Read more about Energy Web's system contracts here.

2. Validator Node Architecture

The validator node architecture monitors validator behavior to ensure consistent and secure blockchain operation. Read more about the validator node architecture here.

Related Content

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

There are two reasons for making this contract Ownable:

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

2. We will have the official Ethereum Name Service system set up on the chain, so this contract is only needed for internal purposes and will not be used publicly.

The name registry is a placeholder for now. The contract can be found in our repo: https://github.com/energywebfoundation/ewc-system-contracts/tree/master/contracts/registry

Interacting with the Name Registry Contract

Contract Address and ABI

Callable Functions

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

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

• - manage validator permissioning and behavior

• - manages validator block rewards

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

Implementing Client Protocol

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

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

Let’s take contract as an example.

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

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

Energy Web System Contracts

Overview

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

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

Documentation and Source Code

Check a Balance and Withdraw Funds

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

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

2. If the release period has ended, press the "Withdraw" button to release the funds to the address it belongs to. Make sure you trigger the withdraw function with an account that has some ethers to cover transaction costs

Mapping Between Address and Tokens

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

Interacting with the Holding Contract

Contract Address and ABI

Callable Functions

Host Machine Requirements

Validator nodes for Volta and the Energy Web Chain must run on a dedicated server or Virtual Machine only for the purpose of running the client; do not use hosts that already perform other tasks.

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: netops@energyweb.org

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

Operating System Requirements

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 netops@energyweb.org 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 https://www.ubuntu.com/download/server.

• 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 update && sudo apt dist- upgrade -y'

Amazon AWS

Ubuntu AMI's are listed at https://cloud-images.ubuntu.com/locator/ec2/. Search for "ebs 18.04 amd64" to get the right version.

Microsoft Azure

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

Debian 9.8

On-Premise

• Download the NetInst ISO from https://www.debian.org/distrib/netinst

• 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

The AMI Id's can be found at https://wiki.debian.org/Cloud/AmazonEC2Image/Stretch

Microsoft Azure

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

CentOS 7

On-Premise

• Download the minimal ISO from https://www.centos.org/download/

• 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

The AMI Id's can be found at https://wiki.centos.org/Cloud/AWS#head-78d1e3a4e6ba5c5a3847750d88266916ffe69648

Microsoft Azure

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

Recommended Security Settings

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

• OpenEthereum or 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 AWS Security guide.

The system architecture of a validator node on the Energy Web Chain is made up of two components:

1. The OpenEthereum Client

2. Telemetry monitoring system

Together these two components allow validators to run a local node of the chain, validate transactions, seal blocks, and monitor validator behavior and metrics.

OpenEthereum Client

A client is software that allows you to run a local node on your machine and interact directly with the blockchain. Every validator must run a full node in order to participate in validation.

Remember that the Energy Web Chain is derived from the Ethereum blockchain. Because of this we use an Ethereum client to connect with the chain called OpenEthereum. Anyone can create a client, as long as it implements the protocols laid out in Ethereum’s yellow paper, and there are a number of Ethereum clients to choose from.

Energy Web uses the OpenEthereum client because it supports the Authority Roundtable (AuRa), which is a consensus algorithm specifically for Proof-ofAuthority blockchains. OpenEthereum allows validators to connect to the chain, collect transactions and seal blocks according the AuRa consensus algorithm.

To read more about OpenEthereum, you can visit their wiki.

To read more about Ethereum clients, see the Ethereum documentation.

Telemetry Monitoring system

The monitoring system collects comprehensive, real-time data and metrics on validator performance and provides a user interface for viewing the data. It is important to gather as much data about the validator nodes as possible in order to ensure a secure and performant blockchain. To do so, we rely on well established industry solutions to transfer these metrics off the validator node to protect the sensitive nature of the data.

The use of the telemetry monitoring system 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 Architecture

There are four components involved in the data collection process:

• OpenEthereum client - monitors validator node behavior

• Telegraf: open-source server agent that collects data from the OpenEthereum client

• InfluxDB - open source database that stores the data collected from Telegraf

• Grafana - data visualization tool that queries the InfluxDB for data and provides graphical interface for data visualization

All components are run in separate docker containers managed by docker compose. For additional information on docker visit: https://docs.docker.com/ and https://docs.docker.com/compose/.

Data Collection Process Overview

1. The OpenEthereum client collects data on the validator node. Collected data includes:

   • CPU usage

   • Memory usage

   • Disk usage

   • Number of connected peers

   • List of visible P2P peers

   • Current block

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

   • Network throughput

   • Network error rate

   • Number of SSH keys

   • Service status for SSH, docker and the parity container

   • SHA256 hashes of key system components/binaries

   • Current chain specification file (or hash)

2. Telegraf collects relevant metrics from the host machine and the custom-built OpenEthereum metrics collector. The metrics collector allows Telegraf to receive the metrics from the OpenEthereum client

3. The collected metrics are stored in an InfluxDB database and can be visualized using Grafana

The Energy Web Chain (EWC) is the foundational “trust layer” of the stack. The Energy Web Chain (EW Chain) is an open-source, Proof-of-Authority public blockchain derived from Ethereum blockchain technology. It is the foundational trust and persistence layer of EW-DOS.

The blockchain performs three key functions in EW-DOS:

1. Provides the smart contract mechanism to store decentralized identities (DIDS)

2. Facilitates on-chain verification and transactions between parties

3. Executes smart contracts that are used by EW-DOS's decentralized applications, SDKs and utility packages.‌

The blockchain provides trust in several ways that allow for a decentralized system that is self-executing and without central authority or oversight of on-chain transactions:

1. The data in each block is immutable and unchangeable. Each block in a blockchain is linked to the previous block by a cryptographically created hash. If one block is tampered with, the hash of every subsequent block in the chain would be need to be updated. Because Validators' consensus is required to create new blocks, a block with an alternative transaction history would be rejected by Validators.

2. Smart contracts provide automated logic for on-chain actions. Transactions on the chain are governed by code called smart contracts that contain explicit logic and requirements for actions to occur. When specific conditions are met, the code will self-execute. Once a smart contract is deployed on the blockchain, it cannot be changed or reversed, removing the risk that anyone can update the logic of the contract for personal gain.

3. Cryptographic verification is required for on-chain transactions. In order for an individual to verify any on-chain transaction, they must sign the transaction using their private key. This makes it impossible to perform a transaction unless you have the private key.

Persistence on the Energy Web Chain

The Energy Web Chain stores the following information:

• Smart contracts for Decentralized Identities (DIDs) that are created through EW-DOS's identity and access management library.

• Smart contracts that govern validator consensus behavior and remuneration. These are known as system contracts.

• Smart contracts that implement other Ethereum network protocols, such as permissioning and the OpenEthereum client protocols.

• Smart contracts that contain logic and functionality specific to applications deployed on the Energy Web Chain and the utility packages that connect them and their users to the Energy Web Chain.

Related Content

REVIEWER FEEDBACK

Overview

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

Documentation and Source Code

• Energy Web Validator Set Contracts

• OpenEthereum documentation on Validator Set contracts

Components

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

RelaySet Contract

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

RelayedSet Contract

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

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

2. The migration validator set, which is the new set we migrate to in case of a change (validator addition or removal).

Validator States

Validators and potential validators have four states in these contracts:

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

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

3. Pending To Be Added Validator: Validator is already added by the owner and their acceptance is pending, but not active yet until it is finalized. This implies that the validator cannot report, be reported, or produce blocks yet.

4. Pending To Be Removed Validator: Validator is pending to be removed (removed by the owner), but it is not finalized, and so is still active as a validator. This implies that as long as the removal is not finalized, the validator is actively producing blocks, can report and can be reported on.

Reporting

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

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

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

Interaction with RelayedSet (logic) Contract

Callable functions

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

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

Interaction with Relay Contract

Callable functions

Events you can listen to:

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

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)

2. The community fund

Documentation and Source Code

• Energy Web Block Reward Contract

• OpenEthereum documentation on Block Reward Contract

Block Reward Payouts

Block Authors

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

Calculator: https://github.com/energywebfoundation/discrete-scurve-calculator

Energy Web Community Fund

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

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

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

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

Interaction with Block Reward Contract

Contract Address and ABI

Callable functions

The block explorer interface provides the most important on-chain information about blocks, transactions, accounts and Energy Web Token (EWT). Below is an overview of what information you can view on the Block Explorer.

Note that there is a separate site for the Volta Testnet Block Explorer.

• Volta Testnet Block Explorer: https://volta-explorer.energyweb.org/

• Main Network Block Explorer: https://explorer.energyweb.org/

Block Explorer Overview

Blocks

• Blocks - block details for all sealed blocks

  • Block Height

  • Num transactions

  • Hash

  • Parent Hash

  • Difficulty

  • Total Difficulty

  • Gas Used

  • Gas Limit

  • Block Rewards

  • Miner (validator)

  • Transactions

Transactions

• Validated - transaction details for all validated transactions

  • Transaction address

  • Status

  • Block Number

  • Nonce

  • Transaction fee

  • Transaction Speed

  • Raw input

  • Gas

  • Internal Transactions

• Pending - transaction details for all pending transactions

  • Transaction address

  • Nonce

  • Gas limit

  • Internal Transactions

Accounts

Account details for all external and smart contract account addresses with balances and associated transactions

• Address

• Token balance

• Num. transactions

• Last balance update

• Gas used

• All transactions

• Coin balance history

Tokens

• All

• Bridged from Ethereum

• Bridged from Binance Smart Chain

APIs

• GraphQL: GraphQL interface which you can use to query specific information that are on chain: https://explorer.energyweb.org/graphiql. To find out more about the possible queries visit: https://github.com/ConsenSys/ethql#query-handbook

1. Choose a hosting provider (on-premise or qualified cloud provider) and favored operating system.

2. Install operating system and prepare host according to the OS Installation Guide (see previous lesson)

3. Find the Client installation script matching the installed OS on the energyweb github: and copy it from the volta-affiliate/openethereum or volta-affiliate/nethermind directory to the host

4. Make sure the latest system updates are installed by running apt-get update

   (debian/ubuntu) or

   (centos)

5. Make the script executable with

6. Run the script (please do not use the

   parameter which can be used to take default for node-name and generate a random key)

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

   • If the issue is not already known, email to troubleshoot.

7. If the installation was successful, it should generate a .txt file (named install-summary.txt) that lists the node address, IP address, , 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.

8. Submit the Volta node installation details .

   1. After submitting the installation details, you will receive another email with instructions for proceeding to the main EW Chain.

1. Install MetaMask

You will need to (or another Ethereum wallet) to connect to EW-DOS applications on the Volta test network or the main network, and to sign transactions on the blockchain.

Read more about using MetaMask .

2. Get Tokens

If you are using applications or smart contracts on the , you will need .

• Learn how to get Volta Tokens .

• Once you have Volta tokens, you will need to .

If you are using or developing applications or smart contracts deployed on the , you will need to have .

• Learn how to get EWT .

• Once you have EWT, you will need to .

3. Using EW-DOS

Learn about Volta Testnet and Energy Web Mainnet

See an Overview of the EW-DOS Tech Stack

Energy Web supports two distinct blockchain networks:

1. The Volta Test Network (Testnet)

2. The Energy Web Production Network (Mainnet)

These networks are independent of each other. They each have their own chain specifications that the uses to configure the blockchain. You can .

You cannot transfer tokens between these two blockchains. They each use their own unique utility token that pays for transaction fees on the blockchain (read more about this ).

The Energy Web Chain's main network utility token is the , which has real fiat value. The Volta Test Network's token is the , and it has no real value. They are not interchangeable - if you have Volta tokens, this does not mean you have Energy Web Tokens, and vice versa.

Developing on Volta Test Network

Volta is the pre-production test network (testnet) of the Energy Web Chain. It’s the blockchain equivalent of a test server or test environment in traditional software development. Most blockchains have at least one test network. Ethereum, for example, for pre-deployment testing.

Volta is used as a staging network to:

• Test before they are deployed on the production chain. If you write your own smart contract, you will want to deploy it and test it on Volta first to make sure it works as expected. Because tokens on the testnet () have no real value, you can test thoroughly and incur no cost.

• Test protocol updates before they are deployed on the production chain. Each time there is an , we test it on the Volta Network first.

The utility token for the Volta Test Network is the . Volta tokens have no real value, but you will need them to "pay" for transaction costs associated with interacting with smart contracts on the Volta network. Read more about the Volta Token and how to get some

Get Started Using Volta

• - you will need to connect to the Volta network in order to access applications and smart contracts deployed on Volta

• - you have the option to run your own local node of the Volta network. You can read about the purpose and benefits of running a local node .

Developing on Energy Web Main Network

Get Started Using the Energy Web Chain

Related Content

2. Full specification for Nethermind configuration options can be found here:

3. Run the following command in your terminal -

Run RPC node in Volta Network

Run RPC node in EWC Network

Your local node should start:

Run a local node using Docker with Nethermind client

This section describes minimal setup to run an RPC node locally or on the server using Docker container run with docker-compose. This is solely for development purposes, it's not a production grade recommendation.

Set up

1. Verify that prerequisites are installed:

1. Create working directory

1. Create docker-compose.yaml file

1. Start container:

1. Examine logs:

The log output should be similar to the following

Nethermind Configuration

You have the option of running a full node of the Energy Web Chain main network or Volta test network locally. Running a local node does requires a degree of technical capability. It helps to understand the benefits of doing so, and the alternatives to running a full local node.

There are a number of benefits to running your own node, which are .

What does it mean to run a node?

A 'client' is software that implements a blockchain's protocols and allows you to connect directly with the blockchain - that is to read data from the blockchain or initiate transactions on the blockchain, such as transferring tokens. Anyone can create client software, as long as it implements that blockchain's official protocols. Ethereum's protocols are specified in their , and there are a number of Ethereum clients to choose from.

A node is any machine that is actively running client software and is connected to the blockchain. Blockchain is often called a “peer-to-peer” network, because its network is made up of many peers running nodes simultaneously that are connected to each other.

Depending on if you are running a full node, a light node, or an archive node (see the differences between these nodes ), your client will sync with the current state of blockchain and then continue to execute every transaction that is added to the blockchain. Essentially it is having a live copy or version of the blockchain running locally on your machine.

Depending on the blockchain you are you connecting to, this can take up large amounts of space and take a long time to retrieve and sync the history of the chain on your machine. For example, synching with the Energy Web chain will require much less resources than syncing with the Ethereum mainnet, as it is a much larger and longer-running blockchain.

What do I need to run a node?

To run a node, you need to install the client software. The Energy Web mainnet and Volta testnet both use the client (formally known as Parity), because it supports the , which is a consensus algorithm specifically for Proof-of-Authority (PoA) blockchains. You can read more about the PoA consensus algorithm and why we implemented it for the Energy Web Chain .

Benefits to Running a Local Node

1. The more nodes there are, the more secure the system is as a whole. Blockchains are decentralized technology, so by design the system performs better if there are multiple instances of it rather than just one. The more nodes there are, the less points of failure or opportunities for malicious action.

Alternatives to Running a Local Node

Running a local node is not necessary to use applications that run on the blockchain or transfer tokens.

Run a local node using the command line

Hardware Requirements

• Multi-core CPU

• 4GB RAM

• SSD drive and free space

  • EWC RPC node - 150 GB

  • Volta RPC node - 200 GB

• A decent DSL connection is required

Download Chainspec file

Download and save the chain config to your local machine.

Volta Testnet chainspec:

Energy Web Chain (production) chainspec:

Using OpenEthereum Client

3. Run the following command in your terminal. Provide the path to the chain config that you want to use. The following command references the Volta chain config.

Your local node should start:

Connect your local node to MetaMask

Get the URL of your MetaMask account. You can do this by clicking the settings dropdown and selecting "Expand View."

When the view is expanded, copy the URL in the browser

Run the following command in your terminal

Run a local node using Docker with OpenEthereum client

This section describes minimal setup to run an RPC node locally or on the server using Docker container run with docker-compose. This is solely for development purposes, it's not a production grade recommendation.

Prerequisites

Set up

1. Verify that prerequisites are installed:

2. Create working directory

3. Create docker-compose.yaml file

4. Download database snapshot - this takes some time and requires resources due to the size of the .tar file, but it will speed up synchronization process.

*Note that this step is optional. If you do not download the database snapshot, move to Step 6.

Volta (depending on your internet connection ~1 hour download time for us):

Energy Web Chain (production) (30 minutes download time for us):

5. Unpack database snapshot. This snapshot only works with OpenEthereum client.

*Note that this step is optional. If you did not complete Step 5, skip this step and move to Step 6.

Volta:

Energy Web Chain (production):

6. Set permissions:

8. Start container:

9. Examine logs:

The log output should be similar to the following (sometimes the logging output does not appear immediately, wait some time):

10. After some, you will sync with the network. Until a full sync, you will see be in a "syncing" state:

The output will show current synchronization status:

It will take some time to fully sync with the current state of the blockchain. When the synchronization is finished status will be:

Additional Resources

Summary

As a , the Energy Web Chain is governed by its community of known, vetted validators:

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.

EWC Validator Roles & Responsibilities

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.

EWC Validator Eligibility

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

EWC Validator Node Operational Functions

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;

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.

EWC Governance Processes

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.

Validator Code of Conduct

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;

Blockchain Oracles

By themselves, smart contracts cannot access data outside of the blockchain or send its data to services outside of the blockchain. To do this, smart contracts use middleware called an oracles, which are third-party services that fetch and send data to and from smart contracts. Oracles are similar to traditional web-based API services.

Smart contracts can contain logic that triggers certain changes or actions based on external data from an Oracle. Without oracles, blockchains and their applications that cater to specific industries that rely on real-time changes such as finance, commodity trading, or IoT, would not have access to the data necessary to react to real-time external factors.

It's important to keep in mind that oracles are agnostic of the data they transmit - they are only responsible for fetching, verifying and relaying the data to and from the blockchain.

Inbound vs. Outbound Oracles

Inbound oracles send data to the blockchain. This is the most common type of oracle. Like traditional API services, the inbound data that the oracle provides can be anything that your smart contract needs for internal logic that it cannot access from the blockchain or the smart contract itself.

For example, you want to send 10 EWT to a friend's address when the price of a specific stock goes above $10 per share. An oracle will provide you with the data about stock price, and the blockchain logic will trigger the send when the oracle delivers data indicating that the price of a stock goes above $10.

Outbound oracles send data about events that happen on the blockchain to third party applications. For example, an account could receive a payment and trigger an outbound oracle to a mechanism that activates a pv solar panel.

Oracle Data Sources

Oracles can gather data from software and hardware. A software oracle interacts with and fetches data available from any web source that exposes its data. Some common examples are weather APIs, real-time stock information and exchange rates.

Hardware oracles interact with 'physical' data sources like sensors from IoT devices, QR codes or bar codes. Some examples could be reading the temperature from a smart thermostat or fetching data from a flood sensor..

Centralized Vs. Decentralized Oracles

Centralized oracles are developed, maintained and controlled by a single entity. One oracle is responsible for fetching data from one or many data sources, and then transmitting that data to the smart contract on the blockchain. You could liken this to using a centralized database for your smart contract's external data sources.

Decentralized oracles aggregate data from multiple sources using multiple oracle nodes, so that there is no single point of failure for data retrieval, and no single point of failure for the oracle itself. Decentralized oracles are more aligned with the wider community of public blockchain.

Fundamental Oracle Functionality

Regardless of the data source, or if it is centralized or decentralized, all oracles provide three main functionalities:

1. Listen to the blockchain network for incoming requests for off-chain data

2. Fetch data from the requested off-chain source

3. Transfer the data to the blockchain via a signed transaction

4. Insert the data into a smart contract’s local storage. Once the data is in the smart contract's storage, it can be used to trigger logic within that smart contract, or it can be available for other smart contract's to use

Oracle Design Patterns: Communicating Data To Smart Contracts

Depending on the nature of the data itself and how the smart contract uses the data, oracles can be designed to communicate with smart contracts using three main patterns:

1. Publish-subscribe: An oracle broadcasts data, and certain smart contracts are polling or "listening to" that oracle for changes in data. An example: "Poll the temperature of region X every 10 minutes. If the temperature is above 70 degrees celsius, turn the smart thermostat to 'on'."

2. Immediate-read: Oracles hold data in their storage and provide this data on request. Users or devices query the oracle for this data at the same time that it is needed. An example: "Is device X in a list of authorized devices to provide solar power to region Y."

3. Request-response: External accounts (via decentralized applications) interact with a smart contract and necessitate data from the oracle. The smart contract sends the data parameters to the oracle and performs the third-party data query. When the data is fetched, it sends the result back to the smart contract for the decentralized application to use. Because the decentralized application cannot always wait for the data, this occurs asynchronously. An example: A user selects from a dropdown on a decentralized application a date range to determine the average temperature of each day during the range. The start and end date are sent to the data oracle to fetch the temperatures for the days in the given date range. The data is sent back to the smart contract to perform necessary logic based on the data.

Tutorial: Using Chainlink with the Volta Test Network

Chainlink provides decentralized oracle networks. This tutorial covers:

• Setting up a Chainlink node and using it from a smart contract on the Volta test network

• Aggregating data from multiple Oracles, and how to use the public EWT/EUR Price Pair Oracle infrastructure on Volta

• Design principles of Chainlink oracles

• Scenarios where it makes sense to use Chainlink

EW-DOS utility layer packages and SDKs interact with smart contracts that are deployed on the Energy Web Chain. To do this, they use API Client Libraries to connect to the blockchain and create instances of smart contracts to access their public functions.

Below we provide an overview of API Client libraries and a some code examples. Note that exact implementation varies in each package or SDK, but the fundamental concepts remain the same.

API Client Libraries

You can interact with smart contracts (i.e. call their public read and write functions) on the the Energy Web Chain and the Volta Test Network using any Ethereum API client library. Client libraries allow you to connect to and interact with the blockchain network. You can read about all the functionalities of Ethereum API client libraries in the Ethereum documentation here.

The most popular JavaScript libraries for interacting with Ethereum networks are ethers.js and web3.js. EW-DOS uses ethers.js, so below we will provide ethers.js examples, however concepts will be similar among different client libraries.

When interacting with a contract, you use a library to first create a Provider, which is a connection the blockchain. You then use the provider to create an instance of the smart contract that you want to interact with. Once this instance is created, you can call the public methods that are exposed in the smart contract.

1. Instantiate a Provider

A provider is a connection to the blockchain. It gives you an interface to interact with the network. To create a JSONRpcProvider, you will need the JSON RPC Url. To create an IPCProvider, you will need the path local IPC filename (this is only available in node.js).

You can see the full ethers.js documentation on Providers here.

import { providers, Signer, utils, errors, Wallet } from "ethers";
const { JsonRpcProvider } = providers;

this._provider = new JsonRpcProvider({ url: rpcUrl });

See source code here

2. Instantiate a Contract

To create a new instance of a contract that is already deployed on the blockchain, you need three pieces of information:

1. The contract's ABI- the ABI (Application Binary Interface). The ABI is a JSON object that provides the interface to your smart contract. It defines the contract's constructor, events and the behavior of its public functions. The contract's ABI is generated with the smart contract is compiled.

2. The contract's address - every smart contract has an address when it is deployed to the blockchain. You can deploy the same contract on multiple blockchains, but each contract will have a different address.

3. The provider

You can see the ethers.js documentation **** for creating a new instance of a deployed Contract here.

//pass in the smart contract address, smart contract ABI, provider:
this._contract = new Contract(settings.address, this.settings.abi, this._provider);

See source code here

2. Implement Contract Methods

The Contract method returns a new instance of that contract at the address passed in. Now that we have an instance of this contract, we can interact with its public methods:

    try {
      valid = await this._contract.validDelegate(identityAddress, bytesType, delegateAddress);
    } catch (error) {
      throw new Error(error);
    }

See source code here

EW-DOS Smart Contracts

For a tutorial on how to deploy a smart contract on the Volta Test Network or Energy Web Main Network, go here.

The Energy Web blockchain uses the Ethereum Name Service (ENS) for name-spacing assets that are anchored on our blockchain. ENS is a critical part of providing user-friendly dApps. You can interact with the ENS contracts that are deployed on the Energy Web Chain in several ways.

Below we explain:

• The benefits of ENS

• The main components of ENS (Registry and Resolvers)

• Interacting with ENS on Energy Web Chain

Benefits of Ethereum Name Service

The Ethereum Name Service (ENS) is a distributed, open, and extensible naming system based on the Ethereum blockchain.

Machine-readable blockchain identifiers such as Ethereum addresses, content hashes and metadata are difficult to interact with in a user interface. ENS was developed to provide human-readable, user-friendly mapping for these identifiers, and to give users the ability to reserve domain names for our applications. To date, it is the most widely used blockchain naming standard.

ENS solves a similar problem that Domain Name Systems (DNS) provide. DNS lets us navigate to a website using human language and an intuitive format (www.energyweb.org), rather than using an IP address that is impractical to remember and has no association with the content that it directs you to (104.26.13.227). Similar to DNS, ENS supports a structure of dot notation for hierarchy and nesting.

Using ENS, you can create identifiers for the following blockchain content types:

• Address

• Reverse address (e.g. an address resolves to alice.eth)

• Content hash (e.g.: IPFS/Swarm hashes)

• ABI definitions

• DNS records

• Public keys

• Smart contract interfaces (see EIP 165)

• Text (email, physical address, geo location, metadata)

You can see a full list here in the ENS documentation, as well as the specifications for resolving each type.

Examples:

As a simple example, if you want to send funds to your friend Alice, you can specify the recipient as “alice.eth” instead of “0x0052569B2d787bB89d711e4aFB56F9C1E420a2a6”.

If you want to refer to a content hash of a report listed at your custom domain, you can refer to it has “myReport.myDomain”, instead of by the hash identifier.

The two main components of ENS, explained below, are responsible for storing the human-readable address in smart contract registry, and resolving it to its original content.

Main Components of ENS

ENS has two primary components: the Registry and the Resolvers.

Registry

A smart contract that holds all of the domains/subdomains, the owner of the domain, and the domain resolver (the method used to map it back to its original address.) You can see the ENS Registry smart contract here.

Resolvers

Methods that translate the human-readable names to their original address. A resolver has multiple methods, each of which are responsible for resolving different types identifiers (for example, one method is responsible for resolving contract ABI definitions , one method is responsible for resolving content hashes.)

• You can see the ENS smart contracts for all of the resolver types here

• You can read more about the Registry and Resolvers in the original documentation here

What’s important to take away is that the two primary components for ENS are smart contracts that hold a mapping for all domains/subdomains, and provide resolver methods for translating different address types to a human readable form. These contracts are extendible, so you can add your own resolvers for different address types.

ENS on the Energy Web Chain

Energy Web has deployed the ENS smart contracts on the Energy Web mainnet and Volta testnet. You have several options for interacting with ENS, depending on your use case.

Interact directly with the smart contracts on the blockchain

Use the Energy Web ENS Manager app

You can use this interface to search for available names in the Energy Web domain and register them to your address. Note that you will need to have sufficient funds in your wallet to do so as there is a fee for name registration.

Our management app is forked from the Ethereum Name Service Manager app.

Use a JavaScript library

There are a number of libraries that support ENS. These libraries have methods to configure your registry, and manage and resolve names. The IAM client library and IAM Cache server both connect to ENS using the ethers library. You can see the Ethers API support for ENS here.

For a full list of libraries that support ENS, see the ENS documentation here.

Additional Resources

• Ethereum Name Service (ENS) is now available for the Energy Web

What is the Energy Web Token?

The Energy Web Token (EWT) is the native utility token of the Energy Web Decentralized Operating System (EW-DOS). Tokens are used in EW-DOS to pay for gas fees on the Energy Web Chain, and for staking to secure the Energy Web X blockchain as well as Worker Node Networks. You will need EWT in your digital wallet (we recommend using MetaMask) if you want to make transactions or use applications or smart contracts that are deployed on the Energy Web Chain main network.

EWT on the Energy Web Chain

Like other public blockchains, the Energy Web Chain uses EWT as a utility token to access services and orchestrate stakeholders within its blockchain system. In the context of the Energy Web Chain, EWT compensate validators for processing transactions, and are used to pay for transactions - for example, registering a new asset or organization in Switchboard.

Utility tokens like EWT are different from other digital assets in the blockchain sphere such as coins, non-fungible tokens, and stablecoins. To learn more about the distinctions between these assets, see this article, The ultimate cryptocurrency explainer: Bitcoin, utility tokens, and stablecoins .

EWT on Energy Web X

Energy Web X will leverage and complement the existing Energy Web Chain by introducing new technical capabilities that streamline the deployment and operation of Worker Node networks.

To maximize the security of every Energy Web solution using worker nodes, EWT will be required to interact with worker nodes and Energy Web X. Most notably, Energy Web Tokens will be required to:

• Reward worker node networks: worker nodes are software packages that need to be run by individuals and/or businesses. In order to attract entities to run worker nodes, enterprises will need to include rewards, paid in EWT, that compensate worker node operators for their work.

• Operate worker nodes: in order to become a trusted party to run worker nodes, individuals and/or businesses will be required to stake EWT. Staking requirements and reward schedules are mass customizable—enterprises launching worker node networks can configure different thresholds and award schedules at their discretion.

• Validate Energy Web X: Energy Web X validators will need to stake a significant number of Energy Web Tokens in order to become validators on Energy Web X.

For clarity, instead of launching a new token with the Energy Web X blockchain, Energy Web X will be powered by the existing or EWT. Users have the ability to “lift” Energy Web Tokens from the existing Energy Web Chain onto Energy Web X. Lifted Energy Web Tokens can then be used for the functions described above. With this mechanism in place, EWT holders will be able to “lower” Energy Web Tokens back to the main Energy Web Chain at their discretion. Over time, token holders will be able to lower EWT to other layer one blockchains (for example, main net Ethereum) making Energy Web solutions interoperable with any blockchain ecosystem.

Get EWT

You can buy EWT on any of the exchanges listed here. You can also bridge EWTB ERC20 tokens acquired on Ethereum mainnet back to EW Chain by following this guide.

Related Content

• Transactions and Transaction Costs

• Energy Web Token

• Volta Testnet Token

• Token Bridge

• Cryptocurrency Wallets

Additional Resources:

• ****The utility of the utility token for utilities - how companies can use the Energy Web Token to build and operate enterprise-grade decentralized applications on a public digital infrastructure

Below are steps to deploy a smart contract on the Volta Test Network (the test network for the Energy Web Chain) using Remix. Remix is a web application used to compile, deploy and test smart contracts on Ethereum networks.

In order to deploy a smart contract to the Energy Web Chain Main Network, rather than the Volta Test Network, the steps are identical, except that you will connect your MetaMask to the Energy Web Chain rather than to Volta. We recommend that you always deploy and test your smart contracts to Volta first to make sure they behave as expected.

Once your smart contract is deployed, you can use the contract's ABI and address on the blockchain to interact with its public methods. For more information on how to interact with smart contracts, go here.

1. Configure MetaMask to connect to the Volta Test Network

You can see steps for doing this are here. If you do not have a MetaMask installed, you can do so here.

2. Get Volta Tokens

You will need Volta tokens to to pay for the transaction fee for deploying the smart contract to the blockchain. For directions on how to get Volta Tokens, go here. To learn more about what transaction fees are, you can go here.

*Note that if you are deploying to the Energy Web Main Network, you will need to have EWT.

3. Navigate to remix.ethereum.org

4. Navigate to the "Deploy and Run Transactions" icon on the left panel (shown below).

In the "Environment" dropdown, selected "Injected Web3". Notice that when you select this, "Custom (73799) network shows up. 73799 is the Volta Test Network - this confirms that we are connected to the Volta network via MetaMask.

5. Confirm the connection on MetaMask

You will need to confirm the connection to MetaMask.

6. Create a simple smart contract

Go to the file explorer panel (select the first icon on the left panel). Add a new .sol file in the 'Contracts' folder. Below it is called VoltaContract.sol.

In the .sol file, add the following code:

pragma solidity >=0.4.0 <0.7.0;

contract SimpleReturn {
    function get() public pure returns (string) {
        return "Volta";
    }
}

7. Compile the smart contract

If there are no errors, click "Compile VoltaContract.sol" (make sure that the 'Language' selected is 'Solidity').

8. Copy the deployed contract's ABI (Application Binary Interface)

If you want to interact with your contract in the future using an API client, you will need the contract's ABI. The ABI is in the bottom right hand corner of the Solidity Compiler page after it is compiled.

9. Deploy the smart contract

Click 'Deploy' to deploy the contract to Volta Test Network.

Confirm the transaction in MetaMask. Make sure that you have some gwei as a gas price by doing the following:

Select EDIT

Select "Edit suggested gas fee"

Make sure you have a Gas price of 6e-8 GWEI (this should be autofilled)

Confirm the transaction in MetaMask

10. See and test the deployed transaction

Once your contract is deployed, you can see it in the "Deployed Contracts" section of the same page ("Deploy and Run Transactions")

Click on "get" to test our contract's functionality. Remember from the code that is should just return a string "Volta".

11. See deployed contract on the Volta Block Explorer

Copy the address of the contract by clicking the copy icon.

Go to the Volta Block Explorer (volta-explorer.energyweb.org). If you are deploying to the main network, the block explorer is explorer.energyweb.org.

Paste the contract address in the search bar at the top right:

You can see the smart contract address details, the block it was created in, and the byte code. The block explorer contract details from the example above is here.

12. Use your smart contract in dapps

Now that you have your smart contract's address on the blockchain and its ABI, you can use an Ethereum API client to interact with your contract in your decentralized applications. For a tutorial on how to do this, go here.

Connect MetaMask to the Energy Web blockchain

Prerequisite: Metamask plugin is installed in the browser; this section explains how to add the Energy Web blockchain to it.

Option1: Automatic configurator

To configure Metamask to connect to the Energy Web blockchain or to Volta, the fastest way to do that is using the Energy Web MetaMask configuration toolbox or Chainlist

Option2: Manual configuration

Video Tutorial