Leading examples of Data Exchange Implementations include:

• Digital Spine for Electricity Markets

• E-Mobility Management [coming soon]

Energy Web is an independent nonprofit accelerating the global energy transition by developing open-source Web3 software solutions that help companies unlock business value from clean and distributed energy resources. This site provides an overview of the foundational concepts, technical components, and use cases of the Energy Web Decentralized Operating System (EW-DOS).

EW-DOS gives companies simple tools to deploy custom applications and business networks that combine established protocols and platforms with pioneering technologies and novel architectures.

Get Started

Learn More about EW Solutions

Energy Web's tech stack is designed to address two primary challenges in the current energy and renewables market:

• Helping electricity market participants share information and coordinate operations to maximize the value of clean and distributed energy resources

• Create open, scalable marketplaces for transparent and efficient renewable energy purchasing

Learn More about EW-DOS Components

Click on any of the boxes below to learn more about the EW-DOS technical components.

Learn about EW-DOS foundational concepts

• Self-Sovereign Identity

• Open-Source Software

• Ethereum Blockchain Technology

Develop with the Energy Web Chain

• Getting started with EW-DOS

• Connect to the Energy Web Chain using MetaMask

• Run a local node of the Volta Test Network or production network

• Get Energy Web Tokens

• Get Volta Testnet Tokens

• Deploy a smart contract on Volta Test Network

A Note on this Site's Documentation

EW-DOS builds on the foundations of other open-source technologies and uses many well-known libraries and technologies in the stack, so this documentation provides references and links to other articles and sources of documentation throughout.

We encourage you to become familiar with the core concepts of blockchain technology and self-sovereign identity if you are new to this space. The Foundational Concepts section provides brief explainers for what we think is essential to understand our technology. They point you toward more in-depth resources and documentation.

We are an open-source foundation and we want our solutions to be accessible and our community to be wide. Please provide feedback or questions on the documentation by reaching out on Telegram, Twitter, or Discord.

Background

Decarbonizing electric grids around the world is the single most impactful step we can take to mitigate climate change. Luckily, we are headed in the right direction: renewables and small scale clean energy assets called distributed energy resources or DERs—assets like electric vehicles, rooftop solar systems, batteries, and other flexible electric loads—are being deployed at an unprecedented rate. Unfortunately, it’s not fast enough: to achieve net-zero emissions by 2050, annual clean energy deployment needs to be three times higher than it is today through at least 2030. And if we want to get there, we have to overcome a serious obstacle: today’s electric utilities are not equipped with the tools needed to manage a renewable grid populated with millions upon millions of DERs.

The grid works by maintaining a precise balance between supply and demand. Today, utilities achieve this via a century-old model: generate power in large, centralized stations and feed it one-way to customers. This model assumes 1) utilities have direct visibility and control over generation (supply) and 2) customer demand for electricity is both passive and predictable. These axioms are no longer valid: renewable energy output is variable and largely a function of weather while demand for electricity from customers—who now own DERs capable of storing electricity, shifting when it’s used, or even injecting power back into the grid— is anything but predictable. A grid composed of vast amounts of renewables and DERs presents a complete paradigm shift for electric utilities.

Utilities have never faced a challenge like this before, nor are they equipped with the tools needed to manage this new paradigm. We aim to change this with a Digital Spine.

Digital Spine Overview

In its simplest form, a Digital Spine is a thin layer of interoperability that connects and communicates information between all of the hardware, software, and organizational systems comprising a grid in near real time. In contrast to the existing information technology landscape that utilities rely on today (which features limited information sharing between isolated and fragmented systems) a Digital Spine offers an open-access, cohesive infrastructure that is jointly governed and operated as a public good.

Today the concept of a Digital Spine - a common digital layer for transactions and interoperability for all actors and processes in an energy system - is being developed in multiple energy markets globally, most notably the UK.

Energy Web's Digital Spine toolkit includes four elements:

• Identity and Access Management (IAM): this component implements a unified authentication and authorization framework using self-managed, sovereign digital identities. This gives utilities and other grid participants the ability to mutually authenticate each other’s identity and authorize selective disclosure or communication of information based on their respective roles and responsibilities. A key benefit of this approach, in contrast to existing piecemeal systems, is delivering a “single sign on” user experience that improves interoperability and streamlines trusted integrations between devices, systems, and organizations without relying on a central administrator.

• Data and Message Exchange Module: this component is a secure, open-access messaging infrastructure that 1) allows market participants to send, receive, and authenticate messages based on the roles that have been issued to and associated with their self-managed identity; 2) allows market participants to exchange diverse datasets, ranging from real-time telemetry to bulk file uploads; and 3) requires only a single integration mechanism with a central infrastructure in order to communicate via one:one (unicast), one:many (broadcast), and many:many (multicast) channels.

• Data Hub Client Gateway: this component is an independent application that Digital Spine participants deploy in order to access the shared message broker. The Client Gateway provides a standardized interface to read and write messages in specific channels within the message broker.

• Joint Business Processing: for DERs to be fully utilized, in many instances information needs to be transmitted amongst three or more parties in a way that does not reveal all data to all parties. In these instances, Energy Web has developed an open source, decentralized technology called “Worker Nodes” that ingest data from external sources, execute custom workflows based on predefined business logic, and vote on results in order to establish consensus without revealing or modifying the underlying data. This technology borrows concepts from public distributed ledger solutions, namely distributed consensus protocols which use cryptographic techniques to establish provably correct and timely results.

Digital Spine Use Cases

Collectively, these four components provide a shared digital infrastructure that facilitates communication and coordination between utility hardware and software systems–from smart meters to network planning tools–and DERs and the companies who manage them. Ultimately, a Digital Spine exists to enable new applications provided by other software vendors and utilities themselves, including:

• Demand Response / Transactive Energy / Virtual Power Plants: Though there are many different names for it, the concept of using market mechanisms and dynamic pricing to influence DER behavior is well established globally. The Digital Spine enables distribution utilities to construct sophisticated transactive energy programs that procure grid services from DERs at specific locations and/or at specific times of day. For this use case, the role of the Spine is to facilitate data exchange and validation between the utility’s operations center and multiple third-party DER operators.

• Network Optimization via Operating Envelopes: Operating envelopes (also called Dynamic Line Ratings) are an emerging solution for dynamically modifying import (consumption) or export (generation) of DERs to the distribution network. The core function of an operating envelope is to define limits on how much power can be injected or drawn by DER based on physical constraints within the distribution system. For this use case, the role of a Digital Spine is to ingest and partition (i.e. route) operating envelopes to the appropriate DER operators so DER can safely sell services wholesale and to the distribution utility.

Moving forward, our full vision for a Digital Spine includes additional applications where consortium building and technology integrations with existing vendors is critical:

• Distribution network modeling / analytics solutions: Utilities need partners that can ingest both traditional system data and DER data to construct digital twins of entire networks in different ways and provide advanced analytical capabilities to utilities to support both operations and planning.

• Optimization solutions: Dynamic line ratings (also called operating envelopes) are one way of optimizing dispatch of DER at the distribution level. There are many other companies that offer solutions to help optimize dispatch and management of DER who can use a Digital Spine to efficiently communicate distribution network conditions and constraints to other market participants.

• Forecasting solutions: Today many companies offer forecasting capabilities (e.g. system demand, power flows within specific network lines, renewable output, etc.). A Spine can enhance forecasting capabilities by making additional datasets that are currently too complex or costly to integrate available to forecasting providers.

• Real time operations solutions: Today there are many companies offering DER management systems and advanced distribution network management systems, but they are not ubiquitous. A Spine could make it easier to bring these solutions to utilities who currently lack them.

Background

Adoption of electric vehicles (EVs) is growing exponentially around the world, and . Collectively, EVs represent an opportunity to both accelerate decarbonization in the energy sector and introduce innovative new business models. Emerging opportunities for EVs include:

1. Grid balancing and demand response: EVs can provide multiple grid services (e.g. peak shaving, voltage support, etc.) by adjusting their charging patterns based on grid conditions. Smart charging systems can optimize charging schedules to avoid overloading the grid during peak demand periods, or consume excess variable renewable energy duriong periods of low demand. By acting as demand response resources EVs can help flatten demand peaks and reduce strain on the grid, thus enhancing its efficiency and reliability.

2. Grid flexibility and storage: EVs can act as distributed energy storage units. With smart charging infrastructure and vehicle-to-grid (V2G) technology, EV batteries can be used to store excess electricity during times of high renewable energy production. This stored energy can then be fed back into the grid during periods of high demand or when renewable generation is low. V2G technology allows bidirectional power flow between the grid and EVs, enhancing the grid's flexibility and stability.

3. Accelerating deployment and increasing utilization of renewables: As a major consumer of electricity, EVs can drive demand for carbon-free electricity through clean energy tariffs, purchases of environmental attribute certificates, or even carbon-optimized charging. EV charging infrastructure can be colocated and powered directly by renewable energy installations, and EV charging strategies can be optimized to charge EVs during hours with plentiful supply of renewables.

While these opportunities are promising, fully realizing their potential is challenging due to complex relationships between multiple stakeholders, the highly distributed and diverse nature of EV and EV charging infrastructure, and the sheer volume of EVs.

EW Data Exchange builds on the capabilities first introduced in the Open Charging Network to deliver EV drivers, grid operators, charge point operators, vehicle manufacturers, retailers, and other EV service providers with a comprehensive and cohesive solution for sharing and validating data.

Reference Implementations

• Open Charging Network 2.0: A next-generation implementation of the OCN is currently under development. OCN2.0 will share many architectural features with the , but include several e-mobility specific features including built-in standards (e.g. OCPI) within the , as well as the ability to run the gateway within EV and EVSE equipment, to simplify integration between EV equipment and hosted in the . OCN2.0 will also feature dedicated Worker Node networks to verify and validate message routing between participants, as well as execute custom business logic involving multiple companies (e.g. smart charging, V2G, etc.).

• Real-time Locational Green Charging: Combining the Data Exchange solution with the enables advanced green charging tariffs and programs that match locally-available carbon-free generation with specific EV charging events in near real-time.

Contents

1. Prerequisite Check

1.1. Configure MetaMask settings

Go to Settings > Networks and click Add Network button to add Energy Web Chain. Enter the details below to add Energy Web Chain as a new network.

• Select Energy Web Chain from the dropdown (by default, the Ethereum Mainnet will be selected) before navigating to the Switchboard dApp homepage.

1.1.a Funding Account

1.2. Secret Engine credentials

Azure KeyVault

Suppose you have a role-based-access-control service principle (sp) created, which is granted full Read and Write permissions to the KeyVault, your sp details may look like

You will need above details and the KeyVault uri on the resource creation page.

Learn more about

Hashicorp Vault

You just need

• vault server url

• The access token

2. Resource Provisioning.

2.1 Launching Digital Spine Integration Client instance

Login to Azure portal and go to ‘Marketplace’ page.

On the marketplace page, search ‘energyweb’ in the search box as shown below:

You will see the ‘Digital Spine Integration Client by EnergyWeb’ in the search results.

Click ‘Create’ on the Offer tile. It will take you to the resource creation page.

Follow the user guide on the UI to fill in the required fields for ‘Basics’ and ‘Virtual Machine Settings’.

On the ‘Digital Spine Integration Client Settings’ tab, you can set the configuration for the DSI Client.

Most configurations are pre populated, you just need to select the desired application to integrate with from the `Application Name` dropdown .

At the 'Vault Configuration' put in the secret engine details, below is the example for KeyVault.

Once all the required fields have been filled. You can proceed to ‘Review + create’ tab, you can double check all the inputs. Then click ‘Create’ to start creating the resources.

After a couple of minutes, the resource creation will complete. You'll find a Virtual Machine under the resource group.

On the VM’s overview page like below, the Digital Spine Integration Client can be accessed at the VM’s DNS in the browser.

2.2 Config DSI Client.

2.2.a Visit Client Application

Open a browser and type in the DSI VM’s DNS; you will be directed to the DSI Client landing page as shown below:

2.3 Configure DID on the DSI Client

On DSI Client landing page, enter the private key for your DID you will use for enrollment (note: the wallet address will be the DID) and hit ‘Import’.

Once you have a sufficient balance of EWT to cover the transaction cost, the application will proceed to the next stage of access validation.

2.4 Enroll the DSI Client with DID

To proceed, click ‘Enroll’ to submit the enrollment request.

When the user role for your selected application is approved, you will see the status is changed to ‘waiting for role to sync’.

2.5 Manually sync role on Switchboard (dApp)

After submitting the enrollment request for your DID, the Energy Web team will contact you via email to notify you of approval. Upon receipt of the approval email, you can publish the newly issued role(s) to your DID document by following the instructions below.

The MetaMask plug-in will pop up in the top right corner of the browser and request a signature to log in.

• If you are logging in with a MetaMask account, you will be prompted to sign the message in the MetaMask Extension.

• If you are logging in with a hardware wallet account (via MetaMask), you will also be prompted to connect to your hardware wallet and sign the message on that device.

After providing the signature, you will be logged in into Switchboard dApp.

The top right menu icon has a notification. Click to open, you will find one publication available.

Click ‘publish’, on the confirmation modal click ‘CONFIRM’.

The MetaMask plug-in will pop up in the top right corner of the browser and request a signature for the transaction.

Follow along to sign the transaction in Metamask, then you'll see the ‘publish is successful ‘ notification.

When the publish is completed, you can return to the the DSI Client browser tab.

3. Client UI walk through.

When you can see ‘Application refresh’ and ‘Topic Refresh’ with ‘Success’ status, you can navigate to ‘Topic management’ OR ‘Channels’ > ‘My apps and topics’ from the left navigation menu.

Your application will be shown on the list. There is one sample topic created for the application (*one is available at the time of writing, but additional topics will be added over time. You may see more topics available for your application).

If you click on the application, it will show you all the topics

You can also view the topic by clicking on it

Topic is a definition of the data schema. Which will be strictly validated during data exchanging.

Next we'll explain how to use the topic.

4. Creating Channels.

• "Publish" type channel is for sending data and "Subscribe" type channel is used for retrieving data

• Channels can be configured to enable one:one, one:many, and/or many:many communications by changing settings for who can receive or send data in the channel scope

• Topics are used by channels, and it defines what kind of data can be send/retrieved to/from a channel, A channel can have multiple different topics

On the UI, from the left navigation menu, under ‘Channels’, navigate to the ‘Channel management’. Here is the section you manage all your channels

4.1 Creating a Publish Channel

To create a channel, simply click ‘Create’ on the page.

In the pop-up modal, you can define the channel details.

The example below shows creating a ‘Messaging’ Publish channel named ‘demo.pub’; when you have defined your channel details click ‘Next’,

At the ‘Restrictions’ tab, you are able to restrict the recipients by `DID` or ‘Role’, this will make sure only defined recipients will receive messages from this channel.

Make sure you click the ‘Save’ button after you put in the recipient DID or Role. To add multiple recipients, repeat this step as necessary.

To proceed to the next step, click “Next”.

On the next screen, you will define what topics to add to this channel.

You can select your desired application from the ‘Select Application’ dropdown, then the available topics belonging to the application will be shown in the ‘topics’ dropdown, click on the topic to add, you can select multiple topics to this channel.

At the last step you can review all the channel details; if you need to revise any settings, click back. When you have confirmed all settings, click "submit" to create the channel.

After clicking ‘submit’, The channel will be shown on the channel list.

4.2 Creating a Subscribe Channel

Creating a ‘Subscribe’ channel is exactly the same process as 'Publish' channel, but selecting the channel type ‘Subscribe’

And at the ‘Restrictions’ section, we can restrict whom we only want to receive data from.

For demonstration purposes, we restrict to only receive data from senders who has role ‘‘admin.roles.marketplace.energyweb.iam.ewc’

On the Topics tab, same concept as above publish channel, here we restrict what kind of data we want to retrieve from this channel.

And review all the details and submit our ‘Subscribe’ channel.

We should have both channels shown under ‘Channel management’

This is all about channel creating and how to implement a topic.

5. Demo Integration - test Sending / Receiving data.

The Digital Spine Integration Client has an API swagger page, which shows you the list of endpoints available for integration.

You can access the swagger integration APIs page from ‘Integration APIs’ from the left side nav.

Click ‘Open’ Rest API.

On the swagger page, scroll down to the ‘Messaging’ section

You can find detailed information about how to integrate with those endpoints.

5.1 Example Post data to a Channel

To post a message to the newly created ‘demo.pub’ channel, the example payload will be formatted as shown below:

You can POST above payload to the D.S.I Client’s endpoint `/api/v2/messages`

You can get all the payload info from the channel details on the D.S.I Client’s UI, click to open the 'demo.pub' channel from the channel list under ‘Channels’ > ‘Channel management’

Here are the channel and topic details

So payload info has below relationship with what is shown on the channel detail and topic detail modals.

5.2 Example Get data from a Channel

To receive data from a channel, by following the documentation, You can retrieve data from GET endpoint '/api/v2/messages'

An example request path can be /api/v2/messages?fqcn=demo.sub&amount=10&topicName=sample_topic&topicOwner=marketplace.apps.energyweb.iam.ewc&clientId=demo_user

Query breakdown will be

• fqcn = demo.sub

• amount = 10

• topicName = sample_topic

• topicOwner = marketplace.apps.energyweb.iam.ewc

• clientId = demo_user

6. Conclusion

Those are the main steps to get you started with the Digital Spine Integration interface, You can start communicating with other DSI clients integrated with the same application.

Data Exchange Context Diagram

Enterprise Data Exchange is a customizable solution for authorizing, delegating, and delivering messages between a multiplicity of companies, systems, and assets operating in a common market environment without relying on a central administrator or broker. It is an extension of electricity market flexibility and e-mobility solutions developed in the Energy Web community over the last five years.

The following are the most important libraries in the core Green Proofs software development kit:

• React: Used to build the user interface of our application. React allows us to create reusable components, manage state efficiently, and ensure fast updates with its virtual DOM.

• Typescript: Used in every part of the Green Proofs stack. TypeScript enhances JavaScript with static type definitions, which helps catch errors early during development and improves code maintainability and readability.

• Postgres: Used for the back-end database storage. Industry-standard relational SQL-compliant database that is used for most of the off-chain data.

• Kysely: a type-safe and autocompletion-friendly typescript SQL query builder. Inspired by knex. Mainly developed for node.js but also runs on deno and in the browser. Used to query Postgres DB.

• Nest.JS: Nest (NestJS) is a framework for building efficient, scalable Node.js server-side applications. It uses progressive JavaScript, is built with and fully supports TypeScript (yet still enables developers to code in pure JavaScript) and combines elements of OOP (Object Oriented Programming), FP (Functional Programming), and FRP (Functional Reactive Programming). Under the hood, Nest makes use of robust HTTP Server frameworks like Express (the default) and optionally can be configured to use Fastify as well.

• X-state: Used for managing the state of our application (both for UI and backend processes), allowing us to model the state logic using finite state machines and state charts. XState provides robust state management with clear and predictable state transitions, making complex state logic easier to understand, maintain, and test.

EW Green Proofs is a customizable solution for registering and tracking the environmental attributes of commodities, including renewable energy certificates (guarantees of origin), the carbon content of sustainable jet fuel or maritime shipping fuel, or green hydrogen.

Today it’s challenging to create standard procurement tools and establish mature markets for emerging clean commodities and products that span multiple geographies and jurisdictions because it's really difficult to establish a unifying framework, and deploy a common software solution, to measure, verify, and track energy attributes and sustainability claims throughout supply chains. This especially applies for products that have complex, global supply chains like aviation fuel, or steel, or even finished products, but also applies to electricity in many contexts (particularly deregulated markets and e-mobility).

What problem is Green Proofs solving?

In these settings (and to an extent, even in situations where established registries exist), it’s challenging for external stakeholders to independently verify anything about the process by which sustainability reporting and clean energy tracking is done. This makes it costly to audit, difficult to get buy-in from the general public, and challenging to grow markets.

Markets need a simple way for everyone involved to be able to verify that the data processing and the business logic and the data itself is all being handled in a proper way. This can help build trust and credibility, so that clean commodities can be truly differentiated and marketed as a value-added solution.

At a macro level, the goal of Green Proofs is to help energy markets and supply chains accelerate decarbonization by following the playbook that electricity markets used over the last decade to advance renewables: using voluntary purchasing of renewable electricity from large electricity buyers through various instruments like PPAs, RECs, and other procurement instruments that are widely recognized, easily implemented, and trusted. The main problem that we aim to solve is that in markets and commodities and supply chains where it's not practical for one single entity to be the sole administrator (or registry operator, or authority to govern the entire market) Green Proofs provide a solution that allows many different participants to mutually authenticate and engage in transactions while knowing that a set of rules and business logic that defines how the clean commodities will work is being executed correctly and securely and transparently.

What are the use cases for Green Proofs?

In 2023 Energy Web is focusing Green Proofs development on three specific use cases:

• 24x7 Clean Energy Matching for independent power producers, energy retailers / suppliers, e-mobility providers, and distribution utilities.

• Sustainable Aviation Fuel tracking for fuel producers, airlines, and institutional aviation buyers.

• Green Proofs for Bitcoin, an initiative to bring an independent, standardized energy measurement system to the Bitcoin mining industry.

Looking ahead to 2024 and beyond, there are many other emerging sectors like green steel, green hydrogen, some other heavy industries in the hard-to-decarbonize sectors that could leverage Green Proofs.

Green Proofs addresses two challenges currently facing clean energy supply chains:

1. In complex, multi-stakeholder environmental commodity markets, central administrators create bottlenecks. Well-intentioned regulators and standards bodies understandably want to increase their oversight of commodity markets to ensure that sustainability claims are accurate. However, given the inherent complexity and geographic scope of the supply chains targeted in this proposal, it is very costly and cumbersome if not impossible for a single entity to take on the responsibility of qualifying producers, administering transactions, and accounting for all market activity. For environmental commodity markets to scale and accommodate thousands of producers and facilities meeting demand from millions of buyers, methods to trace and verify data associated with these products need to evolve.

2. Because data is siloed across multiple participants, markets are opaque and commodities are difficult to differentiate. The supply chain for many emerging environmental products is inherently complex from an accounting and data reconciliation perspective. Data needed to establish that something is true about each of these products is fractured across multiple market participants, each of whom has limited information that is narrowly related to their specific role in the supply chain. This approach makes it difficult for interested buyers to trace products from cradle to grave, trust associated attributes, and as a result dampens demand. This problem is largely by design; historically, commodity markets have been optimized to produce interchangeable, identical products, so there was no need for full transparency. Yet differentiating sustainable vs. conventional aviation fuel, renewably produced vs. fossil fuel-produced cryptocurrencies, or hydrogen made from renewables vs. natural gas requires harmonizing multiple datasets across multiple organizations. These entities need a way to jointly share and process trusted data without revealing trade secrets or other confidential information; legacy technologies such as centralized databases offered as-a-service by large technology companies are not capable of meeting these requirements.

Green Proofs provides the simple user experience of a traditional book-and-claim registry platform, but leverages decentralized, open-source technology to unlock advantages over conventional alternatives in three key ways:

1. Streamlined auditing and verification capabilities enhance transparency and trust: In Green Proofs, user identities (and their associated credentials, roles, and permissions), low-carbon commodities, and the business logic that defines their various interactions and lifecycles are anchored as unique digital assets on a blockchain. No single party can unilaterally delete or tamper with these data. At the same time, many parties can quickly and independently verify the data, eliminating complex and costly data reconciliation processes. This enables a robust and transparent tracking system that improves confidence among stakeholders that emissions claims associated with registry activity are legitimate and unique.

2. Shared ownership and governance creates incentives for industry adoption: Green Proofs offers a unique commercial and governance model in which producers and buyers not only own the IP underpinning the registry (and capture value from its adoption) but also have the ability to jointly make decisions about its operation, as well as the creation and assignment of roles and permissions for users within the system. This supports traditional models of standards creation and administration (i.e., a single entity writes the standard and updates it from time to time) as well as decentralized models in which several organizations collaborate on this task. It can also support multiple companies serving as issuing bodies (while remaining subject to oversight and audits rights from other stakeholders), and a multilateral governance approach to transaction and other fees (where a consortium of relevant stakeholders can set and update fees on an ongoing basis).

3. Scalable and secure identity and access management: Green Proofs streamlines enrollment processes for users by leveraging a self-sovereign approach to identity and access management. In this approach, every participant manages their own identity, but acquires roles and permissions through credentialing processes that are jointly established by relevant stakeholders. Embedding identity and access management logic in this way obviates the need for a central administrator to review and approve users and improves security by eliminating a central repository of user data and credentials.

Green Proofs is built to provide maximum customizability while maintaining the simple user experience of traditional registry platforms. As an open-source solution, Green Proofs benefits from continual improvements and enhancements contributed to its codebase by Energy Web’s global community of members and customers.

Bitcoin mining is a major global energy user, estimated by the Cambridge Centre for Alternative Finance to have consumed over 121 TWh of electricity in 2023. This energy use translates into negative climate impact - but not all mining operations contribute equally to it. Climate-conscious mining operations are contributing to grid decarbonization by purchasing renewable energy, strategically locating mining operations in low-carbon grids, and participating in demand flexibility programs.

The Green Proofs for Bitcoin (GP4BTC) platform is a solution to bring consistent metrics and much-needed transparency into the climate impacts of individual Bitcoin mining companies so industry stakeholders can make better decisions to align with a net-zero future. GP4BTC offers a certification program for climate-conscious miners and one-stop shop for companies seeking to transact with them. Using GP4BTC's self-sovereign approach to data-sharing, market participants such as exchanges and payment processors can discover, validate, and compare the sustainability credentials of participating miners and launch innovative programs to recognize and reward climate-aligned mining.

In April, 2024, Energy Web announced a strategic collaboration with PayPal's Blockchain Research Group to deliver cryptoeconomic incentives to climate-aligned miners using the GP4BTC platform. For more details, please read the project whitepaper here.

GP4BTC Application Context Diagram

EW Green Proofs is a customizable solution for registering and tracking low-carbon products and their attributes throughout complex supply chains.

• Green Proofs Overview

• Green Proofs Architecture

• Use Cases and Reference Implementations

Building a registry for clean commodity certificates: Today many commodities—from electricity to liquid fuels, steel or aluminum, or even digital assets—are adopting technologies to reduce their carbon footprint. Commodities that are produced in a sustainable manner can be differentiated from conventionally produced alternatives if they can be digitally tracked throughout their lifecycles.

Green Proofs has been implemented in several of these use cases already:

• 24*7 Renewable Electricity

• Sustainable aviation fuel

• Green Proofs for Bitcoin

• Sustainable maritime shipping fuels

Background

The SAFc Registry was the first production Green Proofs registry launched in Q4'2023 as a collaboration between Energy Web, SABA, RMI, and EDF to decarbonize the aviation industry.

Sustainable aviation fuel (SAF) is jet fuel produced from renewable feedstocks that emits significantly less carbon than petroleum-based jet fuel. For SAF producers, it is important to track the origin and attributes of the SAF to create new revenues by selling these attributes to environmentally conscious airlines and corporations. For airlines and consumers of air transport services, having a verifiable audit trail of SAF origin and attributes helps them implement credible decarbonization strategies.

The SAFc Registry follows the "book-and-claim" chain of custody model, once the SAF is "booked" in the registry, its environmental attributes are may move separately from the physical fuel. The registry tracks key information about the underlying SAF production, including who produced the fuel, what sustainability certifications they hold, the fuel's feedstock (e.g., waste cooking oil), how much SAF was produced (measured in tonnes), its estimated carbon savings per unit of fuel, when the SAF was blended with conventional aviation fuel, etc.

The SAFc Registry offers the following to its users:

• Organizations and individuals can easily join the platform and create accounts with specific abilities based on the type of company they represent

• "Fuel Providers" are special organizations - that produce SAF and hold 3rd party certifications - that can provide generation / production data to the platform for to issue SAF certificates (SAFc)

• All data fields represented on the platform stem from 3rd-party verified information and certifications, and SAFc may only be issued by accounts holding the proper credentials

• The Registry's web-interface is very user-friendly and familiar to corporate users; power users may interact with the platform via API

• Worker nodes on Energy Web X provide transparency into the inner-workings of certificate issuances, transfers, and redemptions. This allows registry users, stakeholders, and the public to trust that the registry is operating with integrity.

Worker Nodes

The role of workers in a SAF registry is to govern the lifecycle of SAF certificates, which are linked to each tonne of SAF produced.

Certificate Issuance:

• The volume of SAF certificates must precisely match the actual volume of SAF produced in the real world. Accordingly, to issue certificates a Fuel Provider must first prove that they are an accredited producer and then prove that it really produced some volume of SAF. Workers need to verify both elements, and then introduce the correct number of certificates to the system.

• First, workers establish a registry of accredited producers using pseudonymous identifiers. In this architecture, each worker only “knows” the list of approved IDs, not the real-world information about the company.

• Fuel Providers submit requests to issue a volume of SAF certificates using a “Proof of Sustainability” document, which contains all of the important data about the SAF (e.g., number of tonnes or 'units' of SAF, origin, LCA GHG value...). Workers first check if the requestor’s ID matches an active ID in the accredited registry. Then, workers query the POS document and share the production volume via precise proof to check if the request to issue certificates matches the volume in the POS document.

• Workers vote to determine if the requestor is valid and the volume is correct; if consensus is reached, the approval triggers a workflow to issue certificate(s). When issuing a certificate the merkle tree root hash of the worker node voting round becomes part of that certificate hash so the consensus of the worker voting is inherently tied to the issuance of the certificate.

Selling & Transfer of Certificates:

• Once certificates are issued to Fuel Providers, they want to sell them to buyers like airlines. To transfer a certificate to a buyer, a producer sends a request to the worker pool with the volume to be transferred and the recipient (buyer) ID.

• Workers first check to verify that the volume requested in the transfer is equal to or less than the balance held by the producer. For example Producer A has 100 units and wants to sell 50 to Buyer B; workers check that the transfer request is 100 or less and submit votes on the result to approve (or deny) the transfer.

• Once the transfer is executed, the workers then vote to update the balance of the producer and buyer. Using pseudonymous IDs, workers can prove that the sum balance of transfers is correct without revealing parties involved (just like one can create many addresses from a public key, you create a bunch of random IDs for participants that link back to a core identifier).

• Each issued SAFc has a unique identifier, like an NFT; so the transfers always link back to original issuance. Transfers aren't reflected on-chain though the results of worker votes are.

Certificate Retirement:

• Eventually, a buyer wants to publicly claim the use of a SAFc and take credit for its avoided emissions. Buyers can claim either whole or fractional portions of SAFc units. Upon executing a process to claim a certificate, workers reference the unique identifier of the certificate and remove it out of the pool of transfers of “active” certificates. Through this process the certificate remains visible but it’s “frozen” and linked to a specific ID and consumption event.

• Similar to the selling and transfer process, the role of workers in retirement is to validate that the volume requested is equal to or less than the current balance of the requestor, and then establish consensus on precisely which certificate(s) are being retired.

There are two primary benefits of using worker nodes for SAFc:

• Providing full transparency on the total volume of SAFc in the system (keeping track of volumes that are issued, “active”, and retired) without revealing the real-world identities of the entities holding them, or their individual balances.

• By linking the voting events to the issuance, transfer, and retirement of each certificate (which itself has a unique identifier) the system provides real-time, continuous auditing of a cohesive balance sheet with double-entry accounting.

Energy Web Data Exchange simplifies communication and business logic execution in complex markets by replacing heterogeneous point-to-point integrations among participants with a hub-and-spoke model in which all participants maintain a single integration to communicate with all other parties. Unlike conventional hub architectures that rely on a central broker to administer access and host the infrastructure, EW Data Exchange combines multiple open-source technologies to establish a shared platform that is owned, operated, and governed by multiple participants.

EW Data Exchange is tailored to execute high-volume, business-critical communications in electricity markets and e-mobility applications, but can be customized to support any business process involving data exchange between multiple organizations. Enterprise Data Exchange is protocol agnostic, and supports established standards including IEEE 2030.5, XML, OADR, and OCCP.

In its simplest form, Data Exchange is a secure, open-access messaging infrastructure that:

• Allows multiple parties to send, receive, and authenticate messages based on the roles that have been issued to and associated with their self-managed identity;

• Allows parties to exchange diverse datasets, ranging from real-time telemetry to bulk file uploads, in support of multiple DER and e-mobility use cases;

• Provides end-to-end encryption for all messages and data transfers, using cryptographic signatures from self-managed identities;

• Requires only a single integration mechanism with a central infrastructure in order to communicate via one:one (bilateral), one:many (broadcast), and many:many (multicast) channels.

Data Exchange can support a wide variety of use cases, including:

• Coordinating DER installation data among installers grid operators

• Streamlining DER registration in wholesale and/or local markets

• Enabling seamless roaming and advanced tariffs for electric vehicles

• Coordinating real-time grid operations between transmission and distribution system operators (operating envelopes, local constraints)

• Facilitating customer switching between retailers in deregulated markets

• Consolidating disparate market operations communications channels and processes (e.g. registration, nomination, bids/offers, dispatch, settlement)

• Establishing dynamic registries for DERs and EVs

A use case is defined by a particular configuration of a messaging channel (i.e. who is allowed to read/write, how messages are routed) and data schema (the format, frequency, and logic governing messages). Thus Data Exchange is a practically infinitely customizable solution; much like the way a road supports many types of transportation (from cars, to bicycles, scooters, trucks, etc.) Data Exchange provides a foundation for many types of business processes in electricity markets.

Who is it for?

EW Data Exchange can be applied in any energy market context where many-to-many data exchanges are critical. Companies or consortia can design how user roles are defined and acquired; what data structures and protocols are supported; and what types of integration options are made available to participants.

• Wholesale market & transmission system operators who need a solution to facilitate data exchange among market participants and distribution system operators in order.

• Distribution utilities who need to coordinate local services and non-wires alternatives with multiple vendors or aggregators.

• E-mobility service providers and charge point operators who want to reduce the cost and complexity of managing e-roaming and advanced charging programs.

• Industry consortia

EW Data Exchange allows companies seeking to offer / build / operate market-wide data exchange hubs to define the following aspects:

• Onboarding and issuing roles to organizations, systems, assets and users with DIDs, via the SSI-Hub

• Configuring role-based permissions, conditions, and restrictions for users

• Defining data structures and protocols

• Defining hosting and integration patterns (e.g. self-hosting clients, exposing APIs)

• Establishing communication channels between participants

• Scheduling jobs for batch processing and caching of data

• Use the channels for passing data between participants

Building a traceability platform for 24/7 renewable electricity tracking and matching: Enterprise energy consumers are interested in accurately measuring (and mitigating) their carbon footprint through the procurement of renewable electricity. One strategy to accomplish this is to track their electricity consumption and match it with locally available renewable electricity on an hourly basis. Many established tracking systems for renewable electricity fail to provide this level granularity: today most renewable certificates are issued at a monthly interval at best, and often annually. Green Proofs can be used to create a digital platform with the following functionalities:

· Digital onboarding of all parties

· Collection of granular (e.g. hourly, sub-hourly) generation and consumption data 24/7

· Verification of the sources of data by checking the DID of the data provider

· Performing of matching of generation and consumption data based on predefined logic (e.g. preferences of buyers, prioritization of assignment of available supply)

· Decentralized validation of the matching results by multiple eligible actors (worker nodes)

· Issuance, transfer and redemption of EACs via immutable, tamper-proof, and auditable digital certificates

· Reporting: customizable user interfaces and reporting tools to visualize and export different metrics for generators and consumers.

Historically, the easiest way for an organization to claim it is powered by clean energy is to purchase renewable energy certificates (RECs) from third party renewable energy generators. RECs represent the environmental attributes of the renewable energy produced and are sold separately from the actual electricity, typically on an annual basis. RECs have been beneficial for the development of renewables, but they fail to truly account for the carbon impact of an organization’s electricity consumption. A more accurate way to decarbonize operations is to match actual electricity consumption with available renewable generation within the same grid on a real-time, continuous basis. Energy Web’s 24/7 Green Proof solution is capable of tracking and matching consumption and generation within a granular time frame, moving from a yearly or monthly basis (with RECs) to an hourly or sub-hourly basis.

Example: Performing matching for 24x7 renewable energy applications

The role of workers in a 24x7 solution is to execute a matching algorithm that assigns renewable generation to specific customers (consumption centers) to improve accuracy and reliability of clean energy accounting.

Onboard Renewable Generators and Consumption Centers

• First, workers establish a registry of known renewable generators (or data providers who own/operate multiple generators) and end-customers (i.e. individual load centers that want to account for their electricity consumption) using pseudonymous identifiers. In this architecture, each worker only “knows” the list of approved IDs, not the real-world information about the entities.

Execute Matching Between Supply & Demand

• Upon authentication, eligible workers fetch consumption and generation data independently from external data sources via API. The frequency of this process depends on the desired granularity for matching (hourly is most common, but currently workers can support matching at one minute intervals).

• Workers run the matching logic to match consumption and generation data based on the predefined algorithm. The matching algorithm factors in parameters such as the volume of renewable generation in the current time step, the volume of electricity consumption, consumer preferences (e.g. price they are willing to pay for renewables, preferences for specific types of generation like solar vs. wind, etc.), and any other rules that govern matching within that market.

• The consensus among workers triggers the issuance of granular renewable electricity certificates for that time interval and transfer / retirement of these certificates to the given consumer.

Reporting

Every worker creates a hash of the result using the keccak256 (SHA-3) hash algorithm. Thus, every single match is transformed into a Merkle Tree. Then from all transformed matches are nested within another top-level Merkle Tree - the hashed result of each voting round. The advantage of using this technique is the ability to verify what's inside each hash without revealing any properties to the public.

The purpose of using worker nodes for 24x7 matching is to have a robust system for being able to verify computations and results without having to trust one single party. The idea is to allow multiple parties to process the same data and logic independently. If a majority of these parties arrive at the same result, then the computations are very likely to be true and can be trusted. These events (consensus and derived results) can then be anchored on the blockchain to have an audit trail for further verifiability of results. Another advantage is redundancy. If one worker is down for whatever reason, then there are multiple other parties to fetch and process the data. This helps avoid downtime of a system and smooth user experience.

{coming soon}

The diagram below shows the default architecture of a Green Proofs solution. This default architecture can be customized for a given Green Proofs implementation.

Overview

The most common use case of the Open Charging Network describes an eMobility Service Provider (eMSP) or Charge Point Operator (CPO) connecting their backend service to an OCN Node. An OCN node provides an entry point into the system, so a party must connect to an OCN node in order to participate in the network.

Follow these steps in order to successfully connect your own backend service.

1. Make your backend service OCN-ready (implement the OCPI 2.2 API and OCN Signature)

2. Select an OCN Node and enter details in OCN Registry

3. Manage your White- and Blacklist

4. Connect your service to an OCN Node

*Note that not only MSPs and CPOs can use the Open Charging Network, but these are the most common roles.

This Miner User Guide walks through the steps required to connect with the GP4BTC dApp, apply for certification, and share your certification publicly.

Contents:

1. Configure MetaMask settings

GP4BTC users must use the MetaMask wallet to log into the GP4BTC dApp and sign transactions (including the submission of certification data).

• Go to Settings > Networks and click Add Network button to add Energy Web Chain. Enter the details below to add Energy Web Chain as a new network.

• Select Energy Web Chain from the dropdown (by default, the Ethereum Mainnet will be selected) before navigating to the GP4BTC dApp homepage.

Funding Account

2. Log in to the GP4BTC dApp using MetaMask Wallet

• After navigating to the URL above, click on the Use MetaMask button on the welcome screen of the GP4BTC dApp to log in.

• The MetaMask plug-in will pop up in the top right corner of the browser and request a signature to log in.

  • If you are logging in with a MetaMask account, you will be prompted to sign the message in the MetaMask Extension.

  • If you are logging in with a hardware wallet account (via MetaMask), you will also be prompted to connect to your hardware wallet and sign the message on that device.

• After providing the signature, you will be logged in into GP4BTC dApp.

3. Verify your email

The first step in applying for GP4BTC certification is to verify your email address.

Steps

• The GP4BTC dApp requires registering and verifying a valid email address in order to log in.

• After entering your email on the dedicated text input area, click the Submit button. This will initiate another prompt to sign a message in order to trigger a verifiable credential request.

• After signing the message, you will receive an email in your inbox that will prompt you to confirm your email address:

• After clicking the “Confirm My Email Address” button in the email, an email verification credential will be issued to the user and you will be redirected to a confirmation landing page. From there, click the Return to Homepage button to navigate to the GP4BTC homepage.

• When you return to the GP4BTC homepage, it should now show the Credential Inbox page and the other pages you will need to access to move forward with your certification application.

4. Submit your company’s KYC Credential request

Once you have confirmed your email address, GP4BTC will ask for basic Know-Your-Customer details about your organization.

Steps

• Navigate to the “Apply for Credentials” page from the navigation bar on the left to access the Company KYC credential request form.

• Descriptions of each field can be found in the table below. Fields marked “( * )” are mandatory.

• After filling all the mandatory fields, click Submit button and use the MetaMask wallet to sign and send the credential request.

• Once you have submitted the Company KYC form, an Energy Web auditor will review your information and issue a Company KYC Credential to your account.

• After issuance, you can view the details of this credential on the Credential Inbox page.

5. Submit your Energy Evaluation Credential request

Once you have received your Company KYC Credential, you can proceed with the Energy Evaluation. In the Energy Evaluation, you will provide details about your company’s energy use during the years for which you are applying to be certified.

• Navigate to the “Apply for Credentials” page from the navigation bar on the left to access the Energy Evaluation credential request form.

• Descriptions of each field can be found in the table below. Fields marked “( * )” are mandatory.

• After filling in all the mandatory fields, click the Submit button and use MetaMask to sign and send the credential request.

• Once you have submitted the Energy Evaluation form, an Energy Web auditor will review your information and issue an Energy Evaluation Credential.

• After issuance, you can view the details of this credential on the Credential Inbox page.

6. Submit your Mining Evaluation Credential request

The final step in the certification application process is to provide details on your mining activities. GP4BTC uses this information to validate that the energy consumption you have reported for a given year aligns with the mining rewards you have received in that year. This section is not required for companies that exclusively provide hosting services to other companies.

• Navigate to the “Apply for Credentials” page from the navigation bar on the left to access the Mining Evaluation credential request form.

• The user should fill all the inputs marked with ( * ). Descriptions about each field can be found on the table below.

• After filling all the mandatory fields, click the Submit button and use MetaMask to sign and send the credential request.

• Once you have submitted the Mining Evaluation form, an Energy Web auditor will review your information and issue a Mining Evaluation Credential.

• After issuance, you can view the details of this credential on the Credential Inbox page.

7. Request your Green Proofs for Bitcoin certification

Once you have competed the Company KYC, Energy Evaluation, and Mining Evaluation forms, the GP4BTC auditor will review your application and determine your Clean Energy and Grid Impact Scores for the certification year. If either score is equal to or greater than 50, you will be eligible for GP4BTC certification and will be prompted to complete the following steps.

• After navigating to the “Certifications” page, select the year for which to request certification from the dropdown menu.

• Clicks the Request Certification button to send a certification request.

• After issuance, you can view your certificate details along with your Clean Energy and Grid Impact scores.

8. Create your public profile

Once your organization has been certified, you will be given the option to share your certification(s) and/or underlying data via a public profile page.

• After navigating to the “Data Sharing” page, select a year for which to create a public page.

• On the form, you can select which information should be listed on the public profile. To create a public profile, you must share your company’s name, website, logo (if provided), and certification status. Sharing of all other data (including scores, facility locations, energy use, etc) is at your discretion.

• After setting your profile preferences, you can preview the profile page before publishing it.

9. Update your public profile

After you created a public profile page for your organization you have an option to update the data sharing settings any time.

• After navigating to the “Data Sharing” page, you may create and manage a public page for each year that you have earned certification.

• On the form, select which information should be included/hidden from the public profile page including company’s name, website and logo (if provided).

• After updating your preferences, you can preview the public profile page before publishing it.

Frequently Asked Questions (FAQ)

• Why I need to sign two times when sending a credential request?

• Why I need to sign to share my profile settings?

→ GP4BTC requires a signature to store user’s data sharing settings into a verifiable credential and another signature to transport user’s data to backend application to serve the data publicly. GP4BTC only transports the data that a miner has agreed to share in the data sharing settings for her public profile. Miners may update data sharing settings any time. Updating your profile will remove old data from the GP4BTC backend.

Being part of the Open Charging Network requires participants to set up and manage a self-sovereign identity (OCN Identity).

A 'self-sovereign identity’ is an identity where an individual maintains control over their own credentials, as opposed to having them stored in a centralized server by a third-party. A user's self-sovereign identity could, for example, be partially derived from their cryptocurrency wallet address, which the user maintains control of at all times.

Secure identities are critical for the automated routing of OCPI-messages, and for being able to use applications on top of the Open Charging Network.

Below are details on how to complete the steps necessary to create your OCN identity:

1. (not required for node operators)

1. Select and register your country_code and party_id

* This step is NOT required for OCN Node Operators

Your unique identity on the Open Charging Network is based on an compliant name constructed from a country_code (e.g. “CH”) and party_id (e.g. “SNC”).

Today, in many countries, national registries exist to ensure uniqueness of IDs. Please refer to the OCPI documentation for further information both on the Provider and Operator abbreviation as well as for a list of existing authorities: .

Note that currently not all countries have a national registry. To see a list of countries that currently have a national registry,

2. Create a private/public key pair

A public-private key pair is generated programmatically by a wallet through a cryptographic algorithm. The algorithm produces a private key and a corresponding public key. The public key can be exposed and shared with others (it is used to identify participants in the OCN Registry smart contract), but the private key should not be shared with anyone. The algorithm used to generate the key-pair makes it virtually impossible for any outsider to guess your private key.

3. Register and Manage your OCN Identity with the OCN Registry

As a neutral platform, the Energy Web Foundation holds the administration key to this smart contract. The initial implementation requires a centralized authority to have administration rights (e.g. for updates). As the governance of the OCN Registry is a crucial piece to ensure openness of the Open Charging Network, Energy Web Foundation will further develop this governance together with the community (e.g. enable decentralized administration).

3.1 Gather Required Information

The required information varies according to your role within the network and whether you are running a node or not.

You will need to determine your party's role. The most common roles are "CPO" (Charge Point Operator) and "MSP" (Mobility Service Provider).

3.2 Fund your Ethereum-Compatible Wallet

3.3 Create, read, update and delete your OCN Identity

4. Store your private key safely - and don’t lose it

If you have any issues with your OCN Identity, please reach out to us.

In order to connect a service to the OCN, you must choose which OCN node you want to connect to, and know the node's public wallet address. You will then request a registration token (Token_A) from your selected node.

1. Select a node

In order to connect a service to the Open Charging Network, you must decide which OCN Node you want to connect to.

Test Network

To view public nodes available on the public test network and their wallet address, see "".

Production Network

To view public nodes available on the public test network and their wallet address, see "".

2. Request a Token

Once you select a node operator that you want to connect to, you must:

1. Know the OCN Identity (wallet address) of that OCN Node Operator ().

2. Request a registration token (TOKEN_A in OCPI terms). Note that this token is only temporary and will become invalid once the registration is complete.

3. Enter Node details in OCN Registry

One implementation of Green Proofs is the Maritime Book and Claim (MBC) registry created by the Energy Web Foundation in collaboration with and . The MBC registry brings transparency and credibility to claims about the carbon impacts of maritime shipping voyages that use lower-carbon shipping fuels.

Decarbonizing maritime shipping is a critical effort because the sector accounts for some three percent of global emissions.

The registry includes the following main functionalities:

1. Issuance: The operator or owner of a ship can register the usage of low-emissions fuel. Multiple admins verify the request and approve the issuance of a ceritifcate representing the carbon impact of the fuel.

2. Transfer: The certificate can be transferred to any actors involved in shipping, including freight forwarders or cargo owners.

3. Retirement: actors can retire the certificate, which means that they can claim in their sustainability reporting that low-emission fuels have been used in transportation.

4. Transparency: After actors have retired the certificates, the information becomes public (after sensitive information is removed).

An OCN Service Provider develops and provides OCN services that can be used by CPOs, eMSPs and other parties to improve their charging services - such as contracting, billing, payment systems etc.

The OCN Service is - similar to any other OCPI role - an OCN Party. We make this distinction from other "Services" that might only require customers to send OCPI messages (including custom OCPI modules) directly.

Offer your OCN Service

To offer your OCN Service via the OCN Service Interface, make sure the following prerequisites are met:

Now you are ready to publish your OCN Service on the OCN Registry.

Set Service Permissions

An OCN Service is an OCPI party that requires additional permissions from their customers. Such permissions could include the forwarding of session or charge detail record data, for example in a payment service.

Once a customer/user has agreed to the Service's permissions, the OCN Node tied to the customer will automate any such required permissions, lessening the cost of integration with a service.

To be granted the aforementioned permissions, you must then list your OCN Service and the permissions required in a separate smart contract, entitled "Permissions". Thereafter, a user can make their agreement explicit in the same smart contract. Learn more on how to list your OCN Service on our .

You can find a full list of currently implemented OCN Permissions .

If you have followed the previous steps in this tutorial you should now have the following things ready for making your connection to the Open Charging Network:

• (TOKEN_A in OCPI Terms)

Follow the steps listed below to connect to your OCN Node

1. Get the Public URL of your selected OCN node from the OCN Registry

There are three methods of interacting with the OCN Registry:

Using the CLI

ocn-registry get-node 0xEada1b2521115e07578DBD9595B52359E9900104

Where 0xEada1b2521115e07578DBD9595B52359E9900104 is the operator's public address.

Using the Typescript Library

The Public URL could look something like this: https://test-node.emobilify.com

Once connected to the registry, you can use the getNode method to return the operator's public URL:

Using the Java Library

2. Get OCN Node versions and endpoints

We will first send a GET request to the OCN Node’s versions endpoint, using the TOKEN_A we received from the faucet. Note that curl requests can be imported into e.g. Postman or Insomnia if desired.

Do the same for this endpoint:

You should see a long list of OCPI version 2.2 endpoints implemented by the OCN Node. You will want to save these endpoints for future reference in your application’s database.

For now though, we just need one endpoint. Find the endpoint URL for the module identifier “credentials”. This will be the one we use to connect to the node:

3. Ensure OCN Node can access our versions and endpoints

The OCN Node needs to know where to contact us in case there is a message from another party that needs to be routed to us. It can also help to filter requests, in the case that we have not implemented a specific OCPI module that another party is requesting from us.

This will create an authorization token that the OCN Node should use to access our own endpoints. It is logged on start. Be sure to make a note of the authorization token as we will need it later.

Note also the PUBLIC_IP. We want the OCN Node to be able to access these endpoints from the outside, so we should make sure that the server is reachable via the public IP we set.

4. Credentials handshake

Now we are ready to connect to the OCN Node.

The credentials request is detailed below. Make sure to replace the variables TOKEN_A, TOKEN_B and PUBLIC_IP, PARTY_ID and COUNTRY_CODE where described:

• TOKEN_A should match the one generated for you by the faucet

• TOKEN_B should match the authorization token that you have created

• PUBLIC_IP should point to your publicly accessible web service

If the request is successful, you should see a response with OCPI status code 1000 and the OCN Node’s credentials returned in the body.

Now that we have connected to the Open Charging Network we can make use of OCPI to find point of interest data, issue remote commands at charge points and authorize RFID cards of any other OCPI party that is connected to the network.

In order for your backend service to be OCN-ready, it must:

1. , the shared communication protocol for the OCN

2. in order to sign and verify OCN messages

1. Implement the

The OCPI protocol is the common communication protocol for the OCN. Each OCN node implements the OCPI 2.2 API (see, for example, the Kotlin implementation of the OCPI 2.2 API for the OCN node ), and every backend-service that communicates with an OCN node must also implement the OCPI 2.2 API.

Using the OCN Bridge

Using the is an alternative to implementing the full OCPI 2.2 API in your backend service. The OCN Bridge provides an OCPI interface using pluggable backend APIs. You can instantiate an instance of the Bridge, which will proxy your requests and responses with other OCN parties.

In addition to the OCPI 2.2 implementation, the OCN Bridge also provides services to interact with an OCN node (i.e. register with a node, get connection status to a node) and the OCN Registry.

Examples:

You can view documentation on how to to implement the OCN Bridge .

The OCN Bridge simplifies the implementation of the OCPI interface, but it is not required to use in your backend service. Note that the OCN Bridge can only be implemented in JavaScript environments.

The OCN Notary is a package that enables the verification of OCN signature, which are used to sign and verify OCN requests using public/private key-pairs.

OCN Signatures

Taking a cue from the blockchain community, we have developed a message signing and verifying system for the Open Charging Network.

Under the hood it uses the Elliptic Curve Digital Signature Algorithm (ECDSA) as implemented by Ethereum. The signature itself holds a JSON Object containing all the necessary data for the recipient to verify the data it is receiving.

Not only do requests need to be signed, but responses too.

Signing Requests

For requests, the signature is appended to the outgoing OCPI 2.2 headers:

Authorization: Token 0ea32164-515f-418b-8bef-39f3817ea090

X-Request-ID: 71d62c5b-5017-493e-be00-3f5ad4e34fff

X-Correlation-ID: 9881b6f7-63aa-40d2-b9c2-d6daa69c11fb

OCPI-From-Country-Code: CH OCPI-From-Party-Id:

MSP OCPI-To-Country-Code: CH OCPI-To-Party-Id:

CPO OCN-Signature: eyJmaWVsZHMiOlsiJFsnaGVhZGVycyddWyd4L (truncated)...

Signing Responses

For responses, the signature is appended to the outgoing OCPI 2.2 JSON response body:

{

"status_code": 1000,

"data": { "result": "ACCEPTED" },

"timestamp": "2020-03-02T12:48:33.005Z",

"ocn_signature": "eyJmaWVsZHMiOlsiJFsnaGVhZGVycyddWyd4L (truncated)..."

}

The idea is that the recipient can use this signature to verify that the message has been signed correctly and has not been modified by an unauthorized party.

What do we mean by unauthorized?

For the OCN to function properly, there are cases where an intermediary (i.e. an OCN node) needs to modify the request/response. Such an example would be the response_url in the JSON body of requests made to the receiver interface of the OCPI commands module. As the recipient does not have access to the response_url defined by the sender, the OCN Node must modify the value. In an OCN signature, this is known as “stashing”. The signature object contains the history of rewrites, with the previous signature being stashed by the party modifying the data. When a recipient then verifies a signature, the rewrites are also verified.

Let’s take a closer look at what the signature actually is:

interface Signature {

val fields: Array val hash: String

val rsv: String

val signatory: String

val rewrites: Array

}

interface Rewrite {

val rewrittenFields: Map<String, Any?>

val hash: String

val rsv: String

val signatory: String

}

The signature itself contains everything needed to verify the most-recent version of the sent data, i.e. by the sender or OCN node depending on whether any values needed to be modified. Provided is a list of jsonpath fields which can be used to recreate the message as signed by the sender, with the original order of values preserved. The values are hashed using keccak-256, as implemented by Ethereum. The resultant hash is actually the message which is signed. The RSV is the signature, produced by ECDSA using an Ethereum wallet’s private key. The signatory refers to the address of the wallet that was used to sign the message.

The list of rewrites contains an object containing the previous hash, rsv and signatory. It also allows the original message to be recreated by storing the fields which have been rewritten. For example, a commands receiver request might have the following rewrite by the OCN node:

1Rewrite( 2 rewrittenFields = mapOf("$['body']['response_url']" to "https://emsp.net/ocpi/2.2/sender/commands/START_SESSION/acfbb8d2-bd49-4837-97e2-d2c38f6bae55"), 3 hash = "0x1ce93f156bc5b3a5c26c5f2499db7bfa2b38c37fd32616fc6487175b86f41eb2", 4 rsv = "0x16e8b9c4e44f4646235fca85a594b5a31057930676d338d111ae985a4f0d9d4214705a0a2ae18c4dfd014581e96eb4625137a937853d4b2d17a0f3a22750f6ac1c", 5 signatory = "0x25e4fca0a0e5107d06d71ed78f687827208d5ff9" 6)

The Signatory

Of course, the signatory of both the OCN Signature and its rewrites should be independently validated. The verification of the signature only tells us that the message was signed by the signatory provided. The signatory itself could be any Ethereum wallet address. The address of both the original sender and their OCN node can be found in the OCN Registry[link to repo].

Implementing the OCN Notary

The OCN Notary implements the above Signature and Rewrite interfaces. It can deserialize an incoming OCN Signature and verify its contents. It can be used to sign an OCPI request, and likewise to stash/rewrite values in a request.

OCN Network v1.0 Open API 3.0 Specs

Note that this document was generated using unmodified source code in the master branch. As such, certain features of the specification format might be missing, such as examples for HTTP requests and responses.

The Public Test Network is the pre-production test network of the Open Charging Network.

It should be used to test services and features in a robust quality assurance environment. To develop on the test network, you can connect to an OCN test node and the OCN Registry that is deployed on the Volta Test Network. See more details on this below:

OCN Registry on Volta Test Network

The Volta Test Network is the pre-production test network (testnet) of the Energy Web Chain. It is the blockchain equivalent of a test server or test environment in traditional software development.

The for the test network can be found on Volta under the following public key: 0xd57595D5FA1F94725C426739C449b15D92758D55.

You can view transactions and the log history for this contract on the Volta Block Explorer . If you're unfamiliar with the Block Explorer, you can read more .

Connect your Service to an OCN Test Node

The Public Test Network of the Open Charging Network provides you with some public test OCN Nodes that you can use for testing the features of the Open Charging Network.

The following test OCN test nodes are currently known to Energy Web Foundation:

Run a Node in a Test Environment

The Public Test Network should give you the option to test your OCN Node operation in a QA environment.

Testing Tools

The Open Charging Network provides mock OCPI parties for exchanging simple OCPI requests over the Public Test Network.

One Mock CPO and one Mock eMSP are available on the Public Test Network (i.e. registered in the Registry contract that is deployed on the Volta Testnet)

The Open Charging Network allows you to exchange OCPI messages with anybody on the network with just one single OCPI connection, regardless of the OCN Node that you or your counterpart are connected to.

There are some cases in which you want to restrict the list of parties that can communicate with you. For this, the OCN Node provides you with a white- and blacklisting module, called OCN Rules.

Note: This service is an optional feature that needs to be enabled in your own OCN Node or by your OCN Node Operator.

Example: add party to blacklist

• You can find a documentation of how you can use this service on the under OcnRules module.

• See the source code for the OCN node Rules service .

Overview

The OCN Service Interface enables third-party services (such as billing, settlement, location data enrichment) to offer their products to the OCPI community by accessing communication between two OCPI parties on the Open Charging Network without the need for endless API development work.

This is done using OCN Permissions, and requires no additional integration work to be done by the OCPI parties.

It reduces the cost for integration work beyond the EV roaming use-case, helping everyone involved climbing the API mountain of Electric Vehicle charging.

We consider this as crucial to a seamless mass-consumer experience and an efficient EV charging value-chain.

Get Started

As an OCN Service Provider

Learn how to connect your OCN Service to the OCN and to define what OCPI-based information your service needs from OCN Parties / Service Users (OCN Permissions).

As an OCN Party / Service User

Learn how to sign up for an OCN Service by agreeing to OCN Permissions.

Demo

Overview

The Open Charging Network is a decentralized implementation of the hub concept. Unlike traditional, centralized hub architecture, the OCN does not rely on a centralized server - the network is made up of a distributed network of server nodes. Anybody can run an OCN node.

Why Run a Node?

There are several benefits to running your own node of the network.

• From an individual perspective, running a node makes you less dependent on external service providers

• From a network perspective, the Open Charging Network becomes more reliable the more nodes that are running

The following steps below help you to successfully set up and run your own OCN Node:

1. Setup and Configuration

Before running a node and connecting it to a local, test or production environment, it is recommended to become acquainted with how the network operates first.

2. Administration of Node and Connected Parties

After you have set up and configured your OCN Node, you can now set up administration and access restrictions, and allow others to access your node using the OCN Node APIs.

Outside of the full OCPI v2.2 API, OCN Nodes provide additional features, such as the custom OCPI module, OcnRules, as well as ways for admins to restrict use and users to query the OCN Registry.

3. Keep your OCN Node up to date

Every OCN Node is a crucial part of the overall Open Charging Network. As soon as you run your own node, you are responsible for keeping it up to date. This helps to keep the Open Charging Network efficient and secure.

The Energy Web Foundation is steering the development of all Open Charging Network Open Source components, and will release regular updates.

The Production Network is the live network of the Open Charging Network. Services and features should only be used in a production network after performing robust quality assurance environment.

OCN Registry on Energy Web Main Network

The Energy Web Main Network (mainnet) is the production network of the

The for the main network can be found under the following public key: 0x184aeD70F2aaB0Cd1FC62261C1170560cBfd0776

You can view transactions and the log history for this contract on the Block Explorer If you're unfamiliar with the Block Explorer, you can read more .

Connect your Service to an OCN Production Node

Follow the steps outlined in the in order to connect your service to one of the nodes listed below.

The following test OCN production network nodes are currently known to Energy Web Foundation:

• eMobilify GmbH with OCN-Identity 0x34F160573b96D3Db5928Ae804D7d99DdD0aF222c Reach out to eMobilify GmbH via to get connected.

• eMobility Easy with OCN-Identity 0x79d2D88A1F668296c96150139366ff507eFeD618 Reach out to eMobility East via to get connected.

Follow the steps outlined in the in order to connect your service to one of the nodes listed above.

Run a Node in a Production Environment

For the running of a production node, we advise that a few extra steps are taken. These include configuring HTTPS, enabling message signing, and running against a relational database.

1. Configure HTTPS

2. Enable Message Signing

By default message signing is turned on, but it can also be set with ocn.node.signatures=true if it is not.

3. Configure a Database

The default dev properties configuration file only connects to an in-memory database, for ease of quickly testing the OCN Node. When running a Node on the test or production environment, a database should be set up to persist data across restarts. The example application.prod.properties file provided with the OCN Node provides the configuration necessary to use PostgreSQL.

4. Configure Load Balancing

If necessary, the OCN Node can be load balanced. To do so, the nodes operating under the load balancer should have the same configuration:

The operator should also list the load balancer as the domain name using the same private key in the registry listing:

Legal Setup of eRoaming via the OCN

The OCN allows you to have simple, cost-efficient and secure technical connections to other EV charging players like Charge Point Operators and eMobility Service Providers. To run your EV charging service in production, you may need to enter into different legal relationships.

You might want to consider establishing the following agreements when setting up your charging service:

Service Level Agreement (SLA) with Your OCN Node Operator

The OCN Node is responsible for your technical connection to other parties on the OCN. If you are not running your own OCN Node, but using the OCN Node of a third party (OCN Node Operator), you might want to sign a Service Level Agreement (SLA) with the OCN Node Operator. The agreement should make sure the OCN Node is hosted properly and has a high uptime.

eRoaming Agreement with Other Players on the OCN

Engaging with other parties on the Open Charging Network (like charge points or electric vehicles) requires in many cases a formal legal relationship between you and your counter party. An eRoaming Agreement stipulates the terms and conditions for the eRoaming connections between you and your counter party.

If an OCN user wants to make use a particular OCN Service, it has to agree on to the Service's permissions. The OCN Node tied to the customer will automate any such required permissions, lessening the cost of integration with a service

To make use of an OCN OCN Service via the OCN Service Interface, make sure the following pre-requisites are met

3. Your preferred OCN Service is connected to the OCN

You are now ready to give the OCN Service its required permissions.

Learn more about how to do that on our .

The Open Charging Network is a community project by and for the Electric Vehicle Charging community. Its mission is to provide the EV Charging industry players an open, secure and decentralized network for digital interoperability. This is why the core components are developed open source under the .

The development of the Open Charging Network is driven and steered by the non-profit Energy We Foundation. Many users and community members are contributing to it in the form of feedback, raised issues, pull requests and dedicated working groups. This article should provide you with some guidance on how you can contribute to this project.

Version Management

The production-ready version of every Open Charging Network component can be found in its MASTER BRANCH

Development of each component can be found in its DEVELOP BRANCH. Pull requests should therefore generally derive from the develop branch, which will be eventually merged into the master branch to coincide with the release of a new version.

Bare in mind that new features that are big enough may warrant their own feature branch so that multiple contributors can work on them before being merged into the development branch.

Maturity Model, Feature Roadmap and Releases

• The current state of development is made transparent with a maturity model, which describes the current and planned feature set:

• Monthly Developer Community Calls are being hosted to align the development of all software components. Anyone is invited to join. Learn more about it

Community support

If you need support in using or contributing to the Open Charging Network, use our .

Reporting bugs and contribute with coding

Before we can include your contributions to the Open Charging Network code, you need to give us permission. As the author of any creative work (including source code, or documentation), you control the copyright for that work. Energy Web Foundation Foundation can’t legally use your contribution unless you allow us to.

Please take the following steps so that we can include your work:

1. Each source file must include the following header:

2. Each commit must include your sign-off

Your sign-off certifies that you are either the author of the contribution or have the right to submit it under the Apache 2.0 license used by the Share&Charge project. The sign-off is done by adding the following line to your source code:

You must use your real name. Pseudonyms or anonymous contributions are not allowed.

If you set your user.name and user.email as part of your Git configuration, you can sign your commit automatically with git commit -s.

The full text of the DCO is:

The development of the Open Charging Network is steered by community needs with the non-profit Energy Web Foundation curating the development.

For this purpose, transparency about the current feature set is required, which the following OCN maturity model (inspired by ) shall provide. The maturity model and the roadmap of the Open Charging Network development is discussed quarterly during the Share&Charge Foundation and Tech Call.

The maturity model is based on different categories (columns):

• Messaging: How messages between OCN Parties are transmitted and secured

• Service interfaces: Interfaces that can be used by OCN Parties to connect their services to the OCN

• Connection & Community: Tools for the community to test and use the OCN

Maturity is indicated with different-sized black boxes or a heart:

Planned: Requirements are getting defined

Minimal: First implementations are tested

Viable: Can be used in production

Lovable: Functionality set is complete and used by community

A reference to the open source repositories is provided in parenthesis after the feature description.

The Energy Web Decentralized Operating System gives companies simple tools to deploy custom applications and business networks that combine established protocols and platforms with pioneering technologies and novel architectures.

Reaching Consensus

Voting Manager

Caching Results

The worker node is containerized and can be run on a virtual machine.

Requirement

• CPU: 2 vCPUs

• Memory: 4 GB

• Disk Space: 100 GB

• Operating System: Ubuntu 20.04 LTS

Create a Virtual machine

To create a virtual machine in your cloud provider. Ensure the virtual machine matches the minimum requirements listed in the above section.

Deployment Guide

Clone the following repository -

It contains the guide and files required to run the worker image.

Deploying Worker Image to Virtual Machine

Once connected to the VM. Follow the steps to run the container image.

Install docker

sudo snap install docker

Confirm docker and docker-compose are installed

docker -v docker-compose -v

Application setup

Once done, ensure to the .env file contains all environment variables required in the same directory as the docker-compose.yml file.

Finally, run the command

docker-compose up -d

The EV Dashboard is an application which aggregates OCPI data (via the OCN) and Blockchain data for both EVs and charge points. It also facilitate the request and issuance process for credentials relating to a flexibility market.

The dashboard client is available on Github at

Sign-in with Ethereum (SIWE) is an open standard for decentralized authentication that allows users to sign in to websites and applications using their Ethereum accounts. Unlike traditional centralized authentication methods, this innovative approach allows users to access various online services and applications using their Ethereum wallet address and cryptographic keys. This groundbreaking login solution represents a significant step forward in the evolution of decentralized identity management, empowering users with enhanced privacy and ownership of their digital identities.

Why SIWE?

The Ethereum Foundation and Ethereum Name Service (ENS) had put forward a for Sign-in with Ethereum in 2021, based on EIP-4361 (). The reference implementation of Sign-In with Ethereum by SpruceID ( ) provides an easy integration with Application’s Identity services and assures smooth Sign-In user experience. It has numerous benefits over other PKI based signatures, such as :

1. A standard human readable verifiable message to confirm signatures.

2. An EIP-standard message schema to incorporate all the information needed for a secure authentication.

3. Verification for domain and uri, this assures the authenticity of the requester / verifier. Users can validate the domain the transaction was initiated from and the URI to which the access would be provided to (redirection) upon signing for authentication / authorization.

4. Preventing replay attacks with a nonce, which could be a challenge from a server or a random token .

SIWE message template

Message Field Descriptions

authority is the RFC 3986 authority that is requesting the signing. address is the Ethereum address performing the signing conformant to capitalization encoded checksum specified in EIP-55 where applicable. statement (optional) is a human-readable ASCII assertion that the user will sign, and it must not contain '\n' (the byte 0x0a). uri is an RFC 3986 URI referring to the resource that is the subject of the signing (as in the subject of a claim). version is the current version of the message, which MUST be 1 for this specification. chain-id is the EIP-155 Chain ID to which the session is bound, and the network where Contract Accounts must be resolved. nonce is a randomized token used to prevent replay attacks, at least 8 alphanumeric characters. issued-at is the ISO 8601 datetime string of the current time. expiration-time (optional) is the ISO 8601 datetime string that, if present, indicates when the signed authentication message is no longer valid. not-before (optional) is the ISO 8601 datetime string that, if present, indicates when the signed authentication message will become valid. request-id (optional) is an system-specific identifier that may be used to uniquely refer to the sign-in request. resources (optional) is a list of information or references to information the user wishes to have resolved as part of authentication by the relying party. They are expressed as RFC 3986 URIs separated by "\n- ".

Sample SIWE Message :

Given all these advantages, Sign in with Ethereum proved to be an ideal choice for Energy Web in implementing authentication for our decentralized applications (DApps). Authentication with SIWE is supported by our Passport strategy (available in passport-did-auth from v2.0.0 ).

How it works?

A signature request with Metamask SIWE will look something like :

Note: The text block in the above MetaMask pop-up for signing is the SIWE message.

Major security considerations for SIWE

Preventing replay attacks

• During each session initiation, it is crucial to select a nonce with sufficient entropy to thwart replay attacks – a type of man-in-the-middle attack where an adversary intercepts the user's signature and uses it to initiate a new session on their behalf.

• To ensure security, implementers have the option to utilize privacy-preserving but readily accessible nonce values. For instance, they may consider using a nonce derived from a recent Ethereum block hash or a recent Unix timestamp. These methods offer a balance between safeguarding privacy and ensuring widespread applicability.

Verification of domain binding

• Wallets are required to verify that the domain aligns with the actual source of the signing request.

• It is recommended to cross-check this value with a trusted data source, such as the browser window, or through another reliable protocol. By doing so, wallets can enhance security and mitigate potential risks associated with fraudulent or unauthorized signing requests.

SIWE with Federated Identity service

Current scope for SIWE-OIDC

SpruceID has deployed an OpenID Connect Provider (OP) which has support for SIWE and hosted under SIWE Open ID Connect . This deployment is a DAO-governed OP supported by ENS DAO.

To use the hosted OIDC server it is required to register the application as an OIDC client using the OIDC client registration of SIWE Open ID Connect . Currently, no user interface for OIDC client registration is supported. For that reason, developers will need to use the REST API.

The following is an example response:

A client can then be updated or deleted using the registration_client_uri with the registration_access_token as a Bearer token. The authentication could be similar to

Note : This flow is just a possible flow, it could be different for a different use case.

Apart from the existing functionalities offered by SIWE, there is potential for future extensions, including support for Decentralized Identifiers and Verifiable Credentials, as well as integration with EIP-712 for Type structured data hashing and signing.

Monthly Developer Community Calls are being hosted to align the development of all Open Charging Network software components.

Anyone is invited to jointly discuss current status of development, upcoming releases, development contributions from the community, and other related topics.

Calls will take place every second Tuesday of the month via the video conferencing platform Zoom. The call will be recorded and published on this page.

Join the call via Zoom:

• Join Zoom Meeting https://us02web.zoom.us/j/81939801778?pwd=N3RzSHF2dEVBNXhWVE10OVZIUzcwUT09

• Meeting ID: 819 3980 1778

• Passcode: 009142

Dial by your location

Recordings of previous calls:

13.04.2021 - Watch recording on Youtube

09.03.2021 - Watch recording on Youtube

09.02.2021 - Watch recording on Youtube

12.01.2021 - Watch recording on Youtube

08.12.2020 - Watch recording on Youtube

10.11.2020 - Watch recording on Youtube

13.10.2020 - Watch recording on Youtube

08.09.2020 - Watch recording on Youtube

11.08.2020 - Watch recording on Youtube

Assets in EW-DOS

In the context of EW-DOS, an Asset is a digital representation of a physical or virtual device on the Energy Web Chain. An Asset could represent, for example, a solar photovoltaic panel, a battery, an electric vehicle, or an IOT device.

Assets must have a Decentralized Identifier - DID in the Energy Web Chain's DID Registry in order to participate in applications and marketplace activities. Once an Asset has a DID, it can take on roles within an organization or application. This is discussed further below.

Asset Smart Contracts

Assets and their chain of custody are managed by smart contracts that are deployed on the Energy Web Chain.

IdentityManager smart contract

When an Asset is first created, it is registered in the IdentityManager smart contract as an owned identity (the owner address being the Asset owner, discussed below).

The main purpose of the IdentityManager smart contract is to have a on-chain location which aggregates known assets. In other words, it provides a kind of "asset-registry" functionality. This can allow one for instance, to more easily answer questions such as "how many assets have been registered in total?".

While there are many OfferableIdentity smart contracts, there is intended to be fewer IdentityManager smart contracts as the IdentityManager's main purpose is the aggregation of OfferableIdentity information. For instance, an enterprise could have a single IdentityManager to all assets which are registered by their employees.

OfferableIdentity smart contract

The Asset owner can offer ownership to another DID. The OfferableIdentity smart contract provides methods to verify, offer and transfer ownership of Assets (these concepts are discussed in further detail below).

Asset Owners

Every Asset must have an owner. Asset owners initiate the registration, transference and enrolment activity of their Assets. This requires them to make transactions on behalf of their Asset, so the owner must have an address on the Energy Web Chain that is connected to an Ethereum-compatible crypto-currency wallet such as MetaMask. The owner of an Asset is recorded in the Asset's identity on-chain.

Asset Chain-of-Custody

The iam-client-library Asset service provides high-level methods to facilitate the chain of custody for an Asset.

Chain-of-custody events (registration, ofference and transference) for an Asset are emitted from the IdentityManager smart contract. SSI Hub listens for and persists the details of these events. All historical owners of an Asset and the dates of offer, transference and acceptance are accessible through SSI Hub's API.

Register Asset

Registering as Asset involves creating an OfferableIdentity smart contract for the Asset on the Energy Web Chain, and registering its identity in the IdentityManager smart contract. This is initiated by the Asset owner. Because each Energy Web Chain address is a valid DID under the did:ethr DID method, each asset inherently has a DID.

Transfer Asset Ownership

The owner of a registered Asset can transfer ownership to another address on the Energy Web Chain. (The new owner's address must have signing capabilities in order to sign transactions associated with asset management).

The OfferableIdentity smart contract provides methods to facilitate Asset transferance. This contract makes calls to the IdentityManager smart contract so that the state of the Asset is updated at each phase of the transfer.

1. Offer Asset

When a transfer is initialized, an 'offer' of transfer is made to the recipient DID.

The state of the Asset identity is marked as 'offered' in the IdentityManager smart contract.

2a. Accept Asset

The DID that the Asset was offered to must accept the Offer before it is transferred to them. iam-client-library provides a method to accept the transfer. The Asset's owner is updated in the IdentityManager smart contract to reflect the new ownership.

2b. Reject Asset

The DID that the Asset was offered to has the option to reject the transfer. The Asset's 'offered' status in the IdentityManager smart contract is set to 'false'.

Asset Enrolment

An Asset can take on (enrol to) roles within an organization or an application. If their enrolment request is approved by the role issuer, the Asset is issued a role-based verifiable credential.

• If the Asset's owner is an authorized issuer of the desired role, the Asset owner can directly issue a role-based verifiable credential to their Asset.

• If the Asset's owner is not an authorized issuer of the desired role, the owner can submit an enrolment request on behalf of their Asset to the issuer.

iam-client-library provides the high-level methods to request and issue enrolments. See the API documentation here.

Using and Managing Assets in EW-DOS

Switchboard provides an interface for users to register, transfer and enroll Assets. If you are logged into Switchboard, you can view the Asset management interface here.

iam-client-library contains the high-level functions for managing (registering, fetching, transferring, etc.) assets and their corresponding data. You can view the service API documentation for Assets in the library here.

Use Case: Stedin Decentralized Asset Management

Energy Web and the distribution system operator (DSO) Stedin jointly developed a decentralized energy asset management system leveraging the EW-DOS components and architecture discussed above.

The goal of this collaboration was to:

• Facilitate secure, encrypted communication between distributed energy resources (DERs) (i.e. solar panels, batteries, etc) and the grid

• Enable DERs to provide grid services (e.g. selling excess energy back to the grid)

Grid assets (e.g, smart meters, distribution automation devices), and distrubuted energy resources (DERs) were assigned DIDs. The DID is anchored on the asset's pre-existing SIM cards. Each asset exists as an identity in the IdentityManager smart contract on the Energy Web Chain. Cryptographically signed information (such as control signals and commands) from the DSO (Stedin) can then be sent to targeted assets. This allows for an awareness and exchange of grid services between the DSO and DERs.

You can read more about this use case in the official press release here.

Worker Nodes are a new technology developed by Energy Web that enable enterprises to construct distributed computing networks that securely execute sensitive business operations impacting multiple companies.

What are Worker Node Networks?

Worker Nodes were originally developed to solve a paradox that hinders advanced renewable energy tracking solutions like 24x7 matching and green electric vehicle charging: credibility relies on accurate, publicly verifiable results (e.g., proof that digital representations of renewables are not double-counted). But inputs from separate organizations, such as granular renewable energy production and electricity demand data, are commercially sensitive and need to remain private. Complex commercial, legal, and technical requirements often make it challenging for a single actor to unilaterally access and process all requisite data. The ability to establish a shared source of truth from segregated, individual information sources has been an ongoing challenge in multilateral settings; the challenge is even greater for energy market participants seeking to exchange and process granular data in order to procure services from distributed energy resources.

The Energy Web Worker Node toolkit solves these challenges by enabling enterprises to configure, launch, and maintain distributed computing networks that ingest data from external sources, execute custom workflows based on business logic, and vote on results in order to establish consensus without revealing or modifying the underlying data. Worker Nodes apply concepts and components from blockchain technology in a novel, enterprise-friendly architecture to provide all stakeholders with cryptographic proof that mutually-agreed rules and and processes are followed correctly, ensure computational outputs from business processes are correct, and preserve the privacy and integrity of underlying data for auditing purposes.

Why are Worker Nodes beneficial for the energy sector?

Decarbonizing the global energy sector is the most important solution to mitigate climate change. Worker Nodes can help accelerate decarbonization in two specific areas that require coordination and information sharing among multiple independent actors. The first is helping electric utilities digitize and integrate distributed energy resources (e.g., rooftop solar systems, batteries, electric vehicles, electric vehicle charging stations, heat pumps) to the grid. The second is bringing deep levels of transparency and verifiability to emerging green product supply chains—including but not limited to 24/7 matched renewable electricity, sustainable aviation fuel, and sustainably produced bitcoin.

The solutions we apply to these areas, dubbed Data Exchange and Green Proofs, are powered by a brand-new web 3 technology that has significant business value for energy enterprises: worker node networks. Each worker node network is a decentralized group of computers that jointly execute sensitive business processes that involve or impact multiple companies. Though worker nodes establish consensus about the results of a business process, they are not blockchains. Whereas the “work” performed by traditional blockchain miners or validators—validating and sealing blocks—has limited value for energy enterprises, worker node networks are fine-tuned to execute custom logic that is specific to an actual business problem. Worker node networks are only useful in cases where multiple businesses need the capability to transmit complex datasets amongst three or more parties in a way that does not reveal all data to all parties, and/or the capability to provide public verification of outputs while maintaining privacy and integrity of inputs.

How do Worker Nodes actually work?

Today worker nodes are implemented as independent off-chain computing nodes that communicate with a smart contract deployed on the Energy Web Chain. Worker nodes can be implemented in any development framework, including node.js, python, and rust.

Each worker node is programmed to execute a specific conditional logic workflow based on a predefined dataset (i.e. source and schema) and event trigger (e.g. a regular time interval, or a specific external event). Workers are given read-only access to one or more external data sources via API or message broker. When the workflow “event” is triggered, the workers initiate a round of calculation and voting (worker nodes can be configured to either poll an external data source at regular intervals, or “listen” to an external source for a specific trigger).

In the calculation step, each worker node independently executes the conditional logic based on the data it received during the trigger. Then, each worker submits its results (i.e. output of the logic workflow) to the smart contract, which collates the worker nodes’ votes into a unique voting round and keeps track of each round to maintain continuity. The smart contract defines a voting threshold (typically a simple majority, such as 2 of 3, or 4 of 7, etc.) that must be reached in order to establish consensus on the results of each voting round. Each voting round is defined by a voting ID, the number of unique votes (from worker nodes), and a consensus result. If the threshold is reached (i.e. a majority of nodes independently reach the same conclusion and submit identical results to the vote), then the voting round is closed and the result is hashed on the Energy Web Chain; this creates a connected tree of results that can be queried and validated for auditing purposes. If consensus is not reached in the voting round, the entire process from event trigger through voting is repeated; if a second round fails, a custom workflow is executed (this can include alerts, failover to other nodes, or acceptance of results from a plurality of workers).

In addition to collating the voting results, the smart contract is configured to issue rewards for workers in the pool based on performance criteria. A base reward can be issued simply for workers being available in the pool, and additional rewards can be issued based on metrics such as consistency (i.e. availability for all voting rounds), accuracy (i.e. being part of the winning consensus), and speed (i.e. being fastest to submit voting results following the event trigger).

In a verifiable credential ecosystem, there are various metadata that are useful for effectively using the data in the credentials. This page aims to describe possible metadata specifications and technologies that may be used with credential data.

Note: Not all of the following metadata is available for all credentials within the Energy Web credentials ecosystem.

Data Semantics

Data semantics refers to the meaning of the data. This includes semantic disambugation (know precisely what a term is refering to) as well as data descriptions and relationships.

Linked Data provides semantic disbiguation by requiring that terms be IRIs.

Linked Data Contexts

Linked Data context maps terms to IRIs. This allows JSON-LD documents to be written in more concise, readable manner, without sacrificing accuracy.

The VC Implementation Guide also has instructions on how to create new contexts for verifiable credentials.

Linked Data Vocabulary/Ontologies

Linked Data can also be used to provide further information about the semantics of a term. This is provided in a data vocabulary or ontology.

For example, the RDF Schema comment property can be used to provide further description of a resource.

Note that vocabularies can be used to infer data validation but this is non-standard and violates the open-world assumption of W3C ontology languages.

This point is made in SHACL and OWL Compared

Although data validation is an important practical use case for the RDF stack, until SHACL came around, there was no W3C standard mechanism for defining data constraints. Over time, people became creative in working around this limitation. Many tools simply decided that for all practical purposes, the open-world and non-unique-name assumptions should simply be ignored. OWL-aware tools including TopBraid and Protégé, for example, provide data entry forms that restrict users from entering more than one value if there is a corresponding owl:maxCardinality 1 restriction, or require the selection of a specific instance of ex:Person if that class is the rdfs:range of the property. The GAIA-X FAQ makes a similar point SHACL shapes are not an ontological models. They serve a different purpose. Ontologies describe concepts and help in inferring additional knowledge. Firstly, the W3C ontology languages follow the Open World Assumption, secondly SHACL follows the Closed World Assumption. If a self-description is missing an attribute, it is an error in the shape validation (and that’s how it should be!). From the ontology’s point of view, the attribute could be defined somewhere else in the WWW, if not in the JSON-LD file at hand (but this extremely decentralised view is not compatible with Gaia-X’s trust-building approach).

Data Structure Validation

Data structure validation is used to validate that data, for example, contains specific properties or that properties have specific values.

There does not seem to be a single way of describing data structures in the Verifiable Credentials ecosystem as different methods have different tradeoffs.

For verifiable credentials, the schema of a credential can optionally be linked using the credentialSchema property.

JSON Schema

JSON Schema can be used to describe the precise shape required by the a credential.

The JsonSchemaValidator2018 credentialSchema type is defined in the Verifiable Credentials Vocabulary

Open API Schema

SHACL

SHACL is the W3C standard for validating RDF graphs.

SHACL is being used by GAIA-X for their self-descriptions.

To check whether the claims in a Self-Description follow all constraints, such as including all mandatory attributes, the claims are validated against a shape. Technically, these shapes follow the W3C Shapes Constraint Language (SHACL). The claims themselves are represented as an RDF graph, serialised in the W3C JSON-LD format, where JSON is a data interchange format widely supported by programming languages, and JSON-LD (LD = “linked data”) makes it compatible with RDF.

JSON-LD Schema

JSON-LD Schema is a pre-alpha project that attempts to reconcile the trade-offs of JSON Schema and SHACL.

It notes:

JSON-LD documents can be seen from two points of view: as regular JSON documents following certain conventions or as RDF graphs encoded using JSON syntax. Validation mechanisms indeed exist for both ways of looking at the information in a JSON-LD document, but each of them has important drawbacks when working with JSON-LD:

• JSON-Schema can be used to validate JSON-LD as plain JSON documents. However, the information in a JSON-LD document can be encoded through multiple, syntactically different, documents, so it is hard to write a generic JSON-Schema validation without going through a normalisation step, and even if the validation is written for a normalised JSON-LD document, the description of the validation becomes verbose and complex to write, relying, for example, on the usage fo fully expanded URIs. There is also the issue of the implications for the validity of the RDF information encoded in the document when we are just validating the JSON syntax.

• SHACL can be used to validate the RDF graph encoded in the JSON-LD document. SHACL is powerful and expressive but difficult to write and learn, especially for users that do not want to work with JSON-LD as an RDF format. Additionally, the performance of SHACL validators is far from the performance of syntactical JSON-Schema validators

Data Display

The Wallet Rendering specification describes how a credential can be displayed.

Identity and Access Management (IAM)

Identity and access management (IAM) refers to the frameworks and procedures that provide the users of a technology with appropriate access to the technology’s resources (i.e. what a user is allowed to do and access within a system). It includes the processes for validating user identities and establishing the hierarchies they exist in.

IAM plays a critical role in Energy Web tech stack. The IAM components are responsible for creating user identities and defining and enforcing governance structures that identities participate in. These governance structures define criteria that users must have in order to take on roles within an application or organization, and provide the mechanisms to request, verify and issue these roles.

Energy Web's Approach to IAM (Self-Sovereign Identity)

The Energy Web IAM architecture is informed by and implements the principles of self-sovereign identity (SSI). SSI is a paradigm that promotes an individual’s control over their digital identity and how it is used. This is in contrast to traditional, centralized IAM approaches, where a third party is responsible for storing a user's identity and/or their data in a proprietary database.

Self-sovereign identity exists to address the shortcomings and vulnerabilities of centralized identity approaches. Some of these include:

1. Users lack custody over their digital identity and its associated data (what data is shared and with whom).

2. Applications and systems do not provide interoperability or portability of user data. User identifiers and data are typically sequestered within an application and are not accessible to the user outside of that context.

3. Centralized systems are vulnerable to attack, resulting in exposure and dissemination of sensitive user data.

The two fundamental components of SSI (Decentralized Identifiers (DIDs) and Verifiable Credentials (VCs) serve as the fundamental components of Energy Web's IAM framework.

• Similar to a traditional 'username', A DID is a user's primary identifier in the Energy Web ecosystem. A DID is derived from the user's public key, and is anchored on the Energy Web Chain in the DID Registry. See further documentation on DIDs in self-sovereign identity and the IAM stack here.

• Verifiable credentials are digital credentials that can be verified cryptographically using public-key infrastructure. In the Energy Web ecosystem, verifiable credentials are used to authorize a user's or asset's enrolment into an application or organization. See further documentation on verifiable credentials in self-sovereign identity and the IAM stack here

DIDs and Verifiable Credentials are used together within a framework of role-based hierarchies to create permissioning systems. You can read more about the role of DIDs and verifiable credentials in our governance framework here.

EW SSI Toolkit Architecture Diagram

Further Documentation

For further documentation on our IAM stacks:

• Guides (how to use IAM stack apps)

• Patterns (cross-cutting concepts across the IAM stack):

  • Credentials: the role and lifecycle of verifiable credentials in the IAM stack

  • Assets as Ownable Smart Contracts: defining and managing digital identities for assets (digital representation of a physical or virtual device)

  • SSI Credential Governance using ENS Domains: Energy Web's role-based governance frameworks

In EW Data Exchange, the DDHub Message Broker is analogous to a computer - it is foundational infrastructure upon which participants gain the ability to establish their own “profiles”, exchange messages, and run their own applications. The DDHub Message Broker routes and translates messages between participants. Messages are structured and organised in distinct channels corresponding to specific use cases or business processes, and formatted in topics which define data formats and schemas.

In order to access certain channels and gain permissions to send and/or receive specific message types, participants must acquire roles that reflect their role within the market (or use case), using credentials attached to their self-determined identity. Credentials are granted by a platform governing body and determine the ability to send messages to other participants using channels (what messages are sent and received) and topics (data schemas that define the payload of a message).

Channels

Channels are defined at the client gateway, and are what messages are sent and received on. Participants define a channel as:

• Type: Publish/Subscribe

• Topics: Any that the DID has visibility of

• Restrictions: Who will receive a message on a publish channel, or who I will receive a message from on a sub channel. Channels can be restricted by DID or role

An example of a channel definition object is provided below. In this example, the channel will receive RealTimePricing or DayAheadPricing from any DID with the role: user.roles.internal.apps.operator.iam.ewc and does not specify that payload encryption is required.

// Market Pricing Channel Example
 {
        "fqcn": "pricingtopics.sub",
        "type": "sub",
        "conditions": {
            "topics": [
                {
                    "topicName": "RealTimePricing",
                    "owner": "internal.apps.operator.iam.ewc",
                    "topicId": "62f9b4123bef104db2264f2b",
                    "schemaType": "JSD7"
                },
                {
                    "topicName": "DayAheadPricing",
                    "owner": "internal.apps.operator.iam.ewc",
                    "topicId": "62f9b4644bfe104db22642c0",
                    "schemaType": "JSD7"
                }
            ],
            "dids": [],
            "roles": [
                "user.roles.internal.apps.operator.iam.ewc"
            ],
            "qualifiedDids": [
                "did:ethr:volta:0x135ebb63ab839bef3e292e55dcF4A98Bfe38Ba47A9",
                "did:ethr:volta:0x87795f53b443ece663986f46e6747fb10dbc6745fC"
            ]
        },
        "payloadEncryption": false,
        "createdDate": "2022-08-16T00:03:46.164Z",
        "updatedDate": "2022-09-04T22:33:43.313Z"
    }

Topics

Topics are data schemas that define the payload of a message within a channel. They are grouped under owners that are used as an authorization unit for visibility. Two examples of Topics for publishing and acknowledging a distribution network line constraint are provided below:

// Constraint Publication Example
{
    "participantId": "string",
    "submissionTimestamp": "string",
    "networkConstraints": [
        {
            "meterID": "string:",
            "intervals": [
                {
                    "activePowerExportLimit": 0.0,
                    "activePowerImportLimit": 0.0,
                    "diEndtime": "string",
                    "diStarttime": "string"
                }
            ]
        }
    ]
}

// Constraint Acknowledgement Example
{
    "data": {
        "initiatingMessageId": "string",
        "initiatingTransactionId": "string",
        "systemProcessedDttm": "datetime"
    },
    "acknowledgements": [
        {
            "code": "string",
            "title": "string",
            "detail": "string",
            "source": "string"
        }
    ],
    "errors": [
        {
            "code": "string",
            "title": "string",
            "detail": "string",
            "source": "string"
        }
    ],
    "warnings": [
        {
            "code": "string",
            "title": "string",
            "detail": "string",
            "source": "string"
        }
    ]
}

\

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

Governance

Governance provides the rules and procedures to establish behavior, expectations and trust within an environment. While governance is a critical component of any multi-party network, it is especially critical in decentralized environments, where there is no central authority to define and orchestrate governance mechanisms over every component of the ecosystem.

As an example, consider an application built on top of the Energy Web Chain. Each application must ensure that:

• Components are in compliance with existing digital frameworks that their application depends on (e.g. cryptocurrency wallets, peer-to-peer protocols or smart contracts)

• The application has a governance framework that is robust enough to garner stakeholder trust and compliant participation within the application itself (i.e. defining and enforcing who is allowed to do what within the application)

Governance Frameworks

Governance in a network is established through a governance framework (also referred to as a trust framework). The framework provides concrete policies, rules and expectations for the stakeholders within the network.

Energy Web IAM Governance Framework

Energy Web’s IAM governance relies on two systems: role-based hierarchies and verifiable credentials. Used together, these components provide a governance framework for users to interact with the digital infrastructure, and with other users in a secure and self-sovereign manner.

Role credentials are associated with a user’s Decentralized Identifier (DID), which is anchored on the Energy Web Chain in the DID registry. This means that a user’s roles and credentials are not siloed within any one application; because a user can use their DID to register with any application built on top of the Energy Web Chain, their roles and credentials are portable.

Role-based Hierarchies

In the Energy Web IAM ecoystem, role-based hierarchies are defined by organizations, applications, and designated roles within them. The tech stack leverages Energy Web’s Ethereum Name Service to define and namespace relational hierarchies within a system. We decided to deploy our own copy of ENS on the Energy Web Chain as it provides a standard set of widely-used, well-tested smart contracts. Read more about the ENS smart contracts deployed on the Energy Web Chain here.

The namespace hierarchy is built on four levels:

1. Organization: a top-level organizing body

2. Sub-organization(s)

3. Application: a distinct service or functionality provided by an organization or sub-organization

4. Role: a distinct functionality within an application or within an organization

Role-definition properties

When roles are created within an organization or an application, the creator can define conditions or criteria that restrict who is qualified to take on the role. The role creator can also determine which users (by DID or role) are authorized to issue or revoke a role.

Below is a resolved role definition for a role of "install lead". Note that it contains an enrollment precondition that the subject already has the role (credential) of 'project installer'. The role definition also specifies an expiration date, and asserts that only users that have the role of 'install manager' can issue or revoke this role.

{   
    roleName: "installlead",
    defaultValidityPeriod: 31536000000,
    enrolmentPreconditions: [{
        conditions: ['projectinstaller.roles.testdidproject.apps.suborgs.whitney.iam.ewc'],
        type: role 
    }],
    issuer: {
        issuerType: "ROLE",
        rolename: "installmanager.roles.suborgs.whitney.iam.ewc"
    },
    revoker: {
        issuerType: "ROLE",
        rolename: "installmanager.roles.suborgs.whitney.iam.ewc"
    },
    
    roleType: "org",
    version: 1,
    issuerFields: [],
    requestorFields: []
}

Verifiable Credentials

Verifiable Credentials enable users and their assets to take on roles within a system (that is, within an organization, a sub-organization or an application within a hierarchy, as discussed above).

See more extensive documentation on credentials in the IAM stack here.

IAM Stack Governance Components

Switchboard provides the user interface for creating and defining these hierarchies. See the Switchboard guide on Governance and role creation here.

The supporting IAM libraries provide the functionality for persisting and resolving namespaced domains Namespace domains that are registered and managed in the Energy Web Ethereum Namespace smart contracts. Read more about the role of Ethereum Name Space in Energy Web Digital Infrastructure here.

These libraries also support governance by providing credential verification mechanisms. This is discussed further in the Credential documentation.

Additional Resources

• "Unlocking the Potential of Self-Sovereign Identity for Enterprise with Energy Web Switchboard" on Medium

• "How Switchboard Tackles the Challenge of Enterprise Identity Management" on Medium

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

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