24/7 Clean Energy

An initiative for purchasing clean, carbon-free energy every hour on a regional grid where consumption occurs. An entity's clean energy demands are correlated with its energy generation on an hourly basis.

Aggregator

A new role in energy service provision that groups local participants in a power system (energy consumers, energy producers, energy prosumers) to determine and moderate how much energy they will need to consume from the grid, and, in some cases help them sell their excess electricity from distributed energy resources (DERs) back to the regional or wholesale electricity market.

The aggregator is an intermediary between prosumers, Transmission System Operators (TSOs), and Distribution System Operators (DSOs) that want to serve this group or use their DER services on the grid.

Application Registries

Application registries are the logic to manage permissions, enrollments, and relationships between market participants in an automated way.

Charge Point Operator (CPO)

The Charge Point Operator (CPO) is responsible for technical operation and maintenance of (public and semi-public) charging stations. Its revenue comes mainly from providing electrical energy to EVs.

Crypto Climate Accord (CCA)

The Crypto Climate Accord (CCA) is a global private sector-led initiative co-launched by Energy Web to build, test, and implement digital solutions that will decarbonize the crypto and blockchain industry by 2040. Learn more here.

dApp

A decentralized application (dApp) is an application built on a decentralized network that combines a smart contract and a frontend user interface.

Decentralized Identifier (DID)

DIDs **** are persistent identifiers that identify DID subjects such as assets, customers, organizations, and other market participants. DIDs allow the controller of a DID to prove control over it without requiring permission from any other party. DIDs associate a DID subject with a DID document to allow trustable interactions with that subject.

Decentralized Service Bus (DSB)

The DSB is the messaging service of the Energy Web Decentralized Operating System’s (EW-DOS) utility layer. Unlike any other centralised and managed pub/sub messaging systems, EW-DSB is designed and implemented to be fully decentralised and scalable. Messages shared on EW-DSB can be traced back to its original sender using cryptographic signatures; it adds extra security to data exchanges. One of the key benefits of the EW-DSB is to be schema agnostic, meaning any type of schema can be shared as a message between users/systems.

Distributed Energy Resources (DER)

Physical and virtual assets that are deployed across the distribution grid can be used individually or in aggregate to provide value to the grid, individual customers, or both.

DERs can for example include solar, batteries, flexible loads and are also often referred to as “devices” or “assets”.

Distribution System Operator (DSO)

The operating managers (and sometimes owners) of energy distribution networks that operate at a regional or local level. DSOs manage high-voltage incoming electricity from larger transmission grids (via TSOs), convert it to a lower voltage, and distribute it throughout the local network. They are, in essence, the middle-man between the raw, high-voltage electricity from transmission grids and the local consumers of electricity.

E-Mobility Service Provider (eSMP)

The eMobility Service Provider (eMSP) provides e-mobility services such as access to charging services, payment and more to EV drivers. It requires certain data exchange for those services, e.g. charging locations for routing.

Electric Power Distribution

The movement of high-voltage electricity from sub-stations to customers through distribution lines.

Electric Power Transmission

The movement of high-voltage electricity from initial generation sites to substations.

Energy Attribute Certificates (EACs)

Energy Attribute Certificates (EACs) describe global instruments which certify that a specific unit (historically 1 MWh, but sometimes 1 KWh) of electricity was produced from a renewable source.

Globally there are various EAC systems to claim the use of renewable or low-carbon energy. Some well-known standards include Guarantees of Origin (EU), I-RECs (global), and RECs (US/Canada).

• Redeemed EAC = an EAC that has been bought by someone can't be resold to anyone else

• Claimed or Cancelled EAC = other ways of calling Redeemed EACs

• Bundled Certificates = contracts that sell consumable energy + EACs together

• Unbundled Certificates = contracts that sell EACs separately from the energy that produced them

Energy Web Chain (EWC)

The EWC is a public, enterprise-grade blockchain platform designed for the energy sector’s regulatory, operational, and market needs. Launched in mid-2019, it serves as a foundational digital infrastructure on which companies can build and run blockchain-based decentralized applications (dApps). Learn more here.

Energy Web Decentralized Operating System (EW-DOS)

EW-DOS is the acronym for Energy Web Decentralized Operating System. EW-DOS is an open-source stack of decentralized software and standards. **** Learn more here.

Energy Web Token (EWT)

The EWT is the Energy Web Chain native first-layer utility token.

Grid Flexibility

The ability of the grid to balance how much power it generates with how much demand there is for it. Flexibility services include any service that meets a requirement to provide more or less demand on the system. ****

At a basic level, Transmission System Officers (TSOs) and Distribution Service Operators (DSOs) procure flexibility services. Aggregators and prosumers offer flexibility services using distributed energy resources.

Message Broker

A distributed messaging node which can send OCPI messages between OCN Parties.

Open Charging Network (OCN)

A decentralized network for enabling use-cases in the EV charging domain. Consists of many OCN Nodes and a single OCN Registry. Can also be considered as an implementation of the OCPI 2.2 Hub concept.

Open Charge Network (OCN) Identity

A self-sovereign identity of a party on the Open Charging Network based on an Energy Web Chain public/private key-pair.

Open Charge Network (OCN) Node

**Open Charge Network (**OCN )Node

A single node of the Open Charging Network which forwards OCPI/OCN messages between parties based on a routing system. Consists of a message broker, a connection to an Energy Web Chain Node, a blockchain wallet and more. A network of nodes constructs the Open Charging Network.

Open Charge Point Interface (OCPI)

A protocol that allows for a scalable, automated roaming setup between Charge Point Operators and eMobility Service Providers. See OCPI documentation here.

Open Charge Network (OCN) Registry

Smart contracts on the Energy Web Chain that contain important information about registered OCN Nodes, OCN Parties and OCN Services. These contracts act as the addressing, identity, and permissions system of the OCN. A command line interface and libraries are provided for interaction.

Original Equipment Manufacturer (OEM)

A company that manufactures and sells products or parts of a product that their buyer, another company, sells to its own customers while putting the products under its own branding.

Prosumer

Anyone who both consumes and produces energy. Prosumers produce energy through Distributed Energy Resources (DER), such as rooftop solar panels.

Self Sovereign Identity (SSI)

SSI is a digital paradigm that promotes an individual’s control over their identity and their data. This is in contrast to the current paradigm where most of our official identifiers (driver’s license, birth certificate, usernames, etc.) are given to us and maintained by a central authority, and where our data can be shared without our knowledge or consent.

DIDs and VCs are the two most critical components of SSI. Together they allow users to have control over both their identity and any data associated with them.

Software Development Toolkit (SDK)

An SDK is a collection of software development tools in one installable package. They facilitate the creation of applications. In the context of Energy Web, they are open-source “blueprints” for building apps on EW-DOS.

Staking

Energy Web launched staking on the Volta Test Network in August 2021. This is a first step towards a Decentralized Software as a Service (dSaaS) infrastructure, allowing for decentralized, community-driven service provision for Energy Web utility services and applications.

The Energy Web staking model extends blockchain tokens staking to SaaS provisioning. Ultimately, anyone will be able to stake tokens with service providers of their choosing, and both parties will be rewarded for providing fast, stable and secure services based on EW's decentralized, open-source software. Staking in the way Energy Web is implementing it, applies the benefits of decentralization and network resiliency of blockchain technology to software and IT services more broadly.

Supervisory Control And Data Acquisition (SCADA)

Supervisory control and data acquisition (SCADA) is a system of software and hardware elements that allows industrial organizations to i) control industrial processes locally or at remote locations; ii) monitor, gather, and process real-time data; iii) directly interact with devices such as sensors, valves, pumps, motors, and more through human-machine interface (HMI) software; and iv) record events into a log file.

Switchboard

Switchboard is an identity and access management dApp (decentralized app). Switchboard allows for the definition of organization and application structures to be used for role-based permissioning within applications that relate to decarbonization.

It enables a user-centric, decentralized approach where users are in control of their identity (identifier, keys, credentials). Switchboard enables the digitization of assets by giving them unique identities and allowing them to interact with the decentralized operating system and decarbonization use cases.

Transmission System Operator (TSO)

Responsible for transmitting electrical power from power generation plants to distribution local or regional operators (Distribution Service Operators) via the electrical grid. This involves determining how much electricity needs to be on the grid at any given time, and managing reserve capacity and ancillary energy providers to keep the grid balanced.

Utility Layer (UL)

The UL is composed of decentralized cloud services like messaging, key manager, and storage that form the “middle” layer of the EW-DOS tech stack.

Validators

"Validators" refer to both a node and an organization; the companies operating the EWC. Validators on the Energy Web Chain have three main responsibilities: i) Create Blocks, ii) Provide Network Security, and iii) Participate in the EWC Governance.

Verifiable Credentials (VC)

VCs are a set of statements made about a subject (such as a DID) by an authority. They can be used to convince others (who trust the authority) of the truth of the statements and can be linked from a DID document.

Leading examples of Data Exchange Implementations include:

• Digital Spine for Electricity Markets

• E-Mobility Management [coming soon]

Background

Adoption of electric vehicles (EVs) is growing exponentially around the world, and EVs are on pace to represent a significant share of the global transportation sector this decade. 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 Digital Spine toolkit, but include several e-mobility specific features including built-in standards (e.g. OCPI) within the DDHub Client Gateway, as well as the ability to run the gateway within EV and EVSE equipment, to simplify integration between EV equipment and channels hosted in the DDHub Message Broker. 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 24x7 Green Proofs toolkit enables advanced green charging tariffs and programs that match locally-available carbon-free generation with specific EV charging events in near real-time.

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

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.

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.

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.

• Data Exchange Overview

• Data Exchange Architecture

• Channels and Topics

• Use Cases and Reference Implementations

  • Digital Spine for Electricity markets

  • E-Mobility Management

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:

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

• Scheduling jobs for batch processing and caching of data

• Use the channels for passing data between participants

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.

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 .

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

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

1. Implement the OCPI 2.2 API, the shared communication protocol for the OCN

2. Implement the OCN Notary in order to sign and verify OCN messages

1. Implement the OCPI 2.2 API

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 here), and every backend-service that communicates with an OCN node must also implement the OCPI 2.2 API.

Using the OCN Bridge

Using the OCN Bridge 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:

public async getNodeInfo(nodeURL: string): Promise<INodeInfo> {
    const res = await fetch(new URL("/ocn/registry/node-info", nodeURL).href)
    return res.json()
}

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

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.

2. Implement the OCN Notary

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

Now that we know how the signature functions, how do we actually use it? Enter the OCN Notary.

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.

Currently the Notary library is available as an NPM package and as a Maven package for languages targeting the JVM. See the OCN Notary repository to find more information for each package.

OCN Network v1.0 Open API 3.0 Specs

You can find the API specification document in the OCN Node repository, here: Open API 3.0 specs

Using this specification, it is possible to generate client code and test implementations. For more information, see https://swagger.io/docs/specification/about/.

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.

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). Get started here.

As an OCN Party / Service User

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

Demo

To get started with the OCN Service Interface and to see how the above given example works in action, see our OCN Demo. It mocks a full set-up of an Open Charging Network with two OCN Nodes, two CPOs, one eMSP and one billing service and allows developers to run through the scenario outlined in this article. Get started here.

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 Energy Web Chain.

The OCN Registry 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 here. If you're unfamiliar with the Block Explorer, you can read more here.

Connect your Service to an OCN Production Node

Follow the steps outlined in the "Connect your Service to an OCN Node" 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 info@emobilify.com to get connected.

• eMobility Easy with OCN-Identity 0x79d2D88A1F668296c96150139366ff507eFeD618 Reach out to eMobility East via info@emobility-east.de to get connected.

Follow the steps outlined in the "Connect your Service to an OCN Node" 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.

You can see all OCN node configuration settings here.

1. Configure HTTPS

Running the OCN Node in production mode (by default or with the configuration setting ocn.node.dev=false) will require HTTPS. On startup in this mode, the OCN Node will look to see if HTTPS is enabled and properly working. If not, the node will shutdown.

We recommend using an Nginx reverse proxy and Let’s Encrypt certificate, but other solutions are not discouraged.

2. Enable Message Signing

This feature allows recipients to verify the integrity of the data they are receiving. When the configuration setting ocn.node.signatures=true, request senders should include an OCN-Signature header that all entities that the request passes through (i.e. OCN Nodes and the recipient) sign to verify that the data has not been modified without consent. Likewise, for responses, an ”ocn_signature” property should be placed in the JSON response body by the recipient.

Read more about OCN signatures here.

In some cases an OCN Node will need to modify data (typically to make URLs work for recipients). The signature can be modified by an OCN Node, but they must state the properties that they changed, and sign any new data. More information about message signing and verification can be found here.

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:

ocn.node.url = https://balancer.server.net
ocn.node.privatekey = 0x...45d1
ocn.node.apikey = supersecretkey

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

ocn-registry set-node https://balancer.server.net --signer 0x...45d1

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.

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

{coming soon}

Overview

The Open Charging Network (OCN) is a decentralized eRoaming hub.

Using the Open Charge Point Interface 2.2, the OCN provides the network for communication between Charge Point Operators (CPOs), eMobility Service Providers (eMSPs), and other industry players involved in EV charging services.

The primary purpose of the OCN is to make technical connection between these EV charging industry players as simple and secure as possible, without creating technical and commercial lock-in effects.

The two primary actors are eMobility Service Provider (eMSP) and Charge Point Operator.

• eMobility Service Providers (eMSPs) provide EV drivers with network access to electric vehicle charge points, typically through software applications and platforms. Their primary end-user is the EV driver.

• Charge Point Operators (CPOs) install and manage the physical charge point operation infrastructure and the network operations that allow for EV-charging. Their primary end-users are e-MSPs, who in turn make these charge points available to EV drivers through their products and services.

The OCN is made up of a distributed network of server nodes running the OCN Node software. These nodes share a registry that stores network participant data, which exists as a smart contract that is deployed on the Energy Web Chain.

Below you will find an overview of OCN functionality and technical components, as well as how to get started using the OCN.

• Use Cases

• Implementing the Open Charge Point Interface Protocol

• The OCN as a decentralized solution

• Get started using the OCN

• OCN technical components

OCN Use Cases

The OCN supports all use-cases described in the OCPI 2.2 protocol, including:

• Authorization

• Reservation

• Tariff Information

• Billing Stating Charge Point Information

• Real-time charge point status information

• Real-time charge session information

• Charge Detail Record (CDR) information

• Remote start/stop

• Smart charging

• Calibration law (eichrect) support

• Platform monitoring

Implementing the Open Charge Point Interface Protocol

The OCN implements the Open Charge Point Interface (OCPI) 2.2 protocol. This protocol provides a common communication infrastructure for e-mobility service providers, Charge Point Operators and other market participants involved in supplying and delivering electric vehicle charging services.

These actors implement the OCPI on their back-end IT infrastructure.

OCPI Hub Concept

The OCPI protocol can be used for peer-to-peer (bilateral) communication, but is more widely used as a communication hub that connects multiple CPOs with multiple eMSPs.

This allows end-users to, for example, locate and use EV chargers that are managed by one CPO, even if they are using an application created by a different CPO or eMSP. It provides a broader network of access to services and charge points that are critical for eRoaming.

The OCPI is broken down into modules that provide the protocol's core functionality, which includes:

1. Bilateral (peer-to-peer) and multilateral communication

2. Real-time information about charge point locations, availability and pricing

3. Exchange of data related to charging services (i.e. Charging Data Records)

4. Mobile access to Charge Points

The OCN as a Decentralized Solution

The OCN performs the role of communication hub as described by the OCPI 2.2, meaning OCN nodes handle the communication and message routing between relevant parties (CPOs, eMSPs, service providers).

The primary difference between the OCN and traditional hub networks is that the OCN is an open and decentralized network:

1. There is no centralized server that participants must connect to in order to use the network. The OCN is comprised of a distributed network of server nodes, and anyone is able to run or connect their service to a node. Nodes are responsible for brokering messages between parties.

2. There is no centralized database for storing participant user information. This data is stored in a smart contract on the Energy Web Chain, which is a public, decentralized blockchain. Anyone is able to register with this contract, provided they have required information. The OCN provides a whitelisting/blacklisting permissioning system to manage messaging preferences.

OCN Nodes

In the context of the OCN, a 'node' is a server running an instance of the OCN node software. Each node of the OCN forwards OCPI and OCN messages between parties based on a routing system and a shared registry that is anchored on the Energy Web Chain in a smart contract. As mentioned above, these parties are typically Charge Point Operators or eMobility Service Providers.

A node consists of a message broker, blockchain wallet, and connection to an Energy Web Chain node. The network of nodes together constructs the Open Charging Network.

Anyone can run a node if they choose, or connect to a node remotely.

The OCN Registry

OCN parties (those who are using the network - eMSPs, CPOs, third party service providers) are identified in the registry smart contract that is deployed on the Energy Web Chain. Every node on the OCN has access to this smart contract.

A participant is identified in the Registry by their public key, which is mapped to the public url of the OCN node that they are registered with:

// address => domain name/url
mapping(address => string) private nodeOf;

source code

Users can interact with the Registry smart contract to fetch, set or update their registered node or their party information.

Parties are required to sign messages that they send through the OCN with their private key as a means for security and verification. Learn more about how to create a public/private key pair and register as an OCN party here.

Benefits of a Decentralized Network

Most implementations of OCPI are centralized applications, where a third-party platform provides the 'hub' network connection between multiple eMSPs and CPOs that enable actors to send and receive information.

This approach brings certain advantages and convenience, but also creates commercial and technical limitations:

• Participant identities are siloed within a network, creating a lock-in effect to that specific network

• Network service providers can choose to not provide particular services on a proprietary platform, creating commercial restraints for the network's users

• Centralized networks are typically less resilient and scalable than decentralized networks

• Participation can be restrictive due to cost or commercial agreements

A decentralized, open source architecture provides a solution for some of these challenges:

• Network participant identities are accessible to anyone on the network through a public, shared registry, reducing network and user silos.

• Anyone can register and use the network for free. (Read more about how to create an OCN identity here)

• Anyone can run a node. This makes the network scalable, resilient, and reduces potential points of failure. Read more about how to run a node here

• The OCN is open-source. Anyone can build applications and provide services on top of the network for all to use. Read more about the OCN Service interface here

Getting Started

Create an OCN Identity

To get started with the OCN, you first need to create your own OCN Identity. Follow the steps outlined here: Create and manage an OCN Identity.

Connect your service to a node

To connect your EV charging service to an OCN Node (as a Charge Point Operator or an eMobility Service Provider), follow the steps outlined here: Connecting an OCPI/OCN Party to a Node.

Run your own OCN node

To operate your own OCN Node, follow the steps outlined here: Run an OCN node.

Offer a third-party service via the OCN Service Interface

To provide a service like settlement, payment, smart charging, etc. (OCN Service) to OCN Parties (Charge Point Operators, eMobility Service Providers, etc.), follow the steps outlined here: Use the OCN Service Interface.

OCN Technical Components

OCN Node

Provides an entry point to the network, which enables communication with other eRoaming parties using the Open Charge Point Interface 2.2.

Repository: https://github.com/energywebfoundation/ocn-node

OCN Bridge

A pluggable OCPI API interface for eRoaming parties with no OCPI API.

The OCN bridge can be used by CPO/eMSP backends to implement the OCPI protocol, which is a required step in connecting a backend to an OCN node, however it is not required to use the OCN Bridge to do so. Manages the OCPI interfaces, connection to an OCN client and registration with the OCN registry. JavaScript implementation only.

Repository: https://github.com/energywebfoundation/ocn-bridge

OCN Registry

The shared address, identity and permissions system of the OCN.

The OCN Registry is a smart contract on the Energy Web Chain that contains important identifying information about registered OCN Nodes, Parties and Services. It acts as the shared address, identity and permissions system of the OCN.

Repository: https://github.com/energywebfoundation/ocn-registry

Utilities to securely verify and sign OCN messages using public/private cryptographic key-pairs.

Currently targeting JavaScript and JVM only.

Note that the OCN Bridge already implements the OCN Notary. If you are connecting a party to an OCN node, and you are not implementing the OCN Bridge, you will need to implement the OCN Notary in your backend setup.

Repository: https://github.com/energywebfoundation/ocn-notary

OCN Tools

Common tools for aiding development of applications built on top of the OCN.

You can run a mock E-Mobility Service Provider (MSP) or Charge Point Operator (CPO) with these tools, which can be helpful for local development. Uses the OCN Bridge as a dependency.

Repository: https://github.com/energywebfoundation/ocn-tools

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:

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

1. You have an OCN Identity

2. Your backend is connected to the OCN

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 OCN Registry repository.

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:

1. The OCN Service has a OCN Identity

2. The OCN Service is connected to the OCN

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 OCN Registry Repository.

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

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.

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

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. Select your country_code and party_id* (and register at your country’s national registry**) (not required for node operators)

2. Create a private/public key pair

3. Create, read, update and delete your OCN Identity

4. Store your private key safely

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 eMI3 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: OCPI 2.2 Documentation.

Note that currently not all countries have a national registry. To see a list of countries that currently have a national registry, see the OCPI 2.2 documentation, section 2.5. Provider and Operator abbreviation.

2. Create a private/public key pair

The Open Charging Network uses a cryptographic wallet structure to provide security and unique identities. Wallets are used to construct your OCN identity, and to sign (authorize) actions on the OCN, such as sending and receiving messages. Your wallet (or private/public key-pair), along with your country_code and party_id (Step 1) form your identity on the Open Charging Network.

As such, you must have an Ethereum-compatible wallet to create your OCN identity. If you do not already have an Ethereum-compatible cryptocurrency wallet, we recommend using MetaMask.

You can read more about what cryptocurrency wallets are, and how they are used in the context of the Energy Web Chain here.

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

After completing Step 1 and Step 2, you are now ready to register your OCN Identity with the OCN Registry. This registry serves as the address book for all OCN Identities.

The OCN Registry is implemented as a smart contract deployed on the Energy Web Chain. Anyone is allowed to register 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).

There are several ways to manage your OCN Registry entry. We recommend using the Command Line Interface, Java or TypeScript library provided in the OCN Registry repository on GitHub.

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

You can see a full list of supported roles within OCPI 2.2 in the documentation at 6.4.2 Role.

3.2 Fund your Ethereum-Compatible Wallet

As a a final preparation step, you need to fund your Ethereum wallet that you created in Step 2. The funds will be used to enter our data into the registry. The transaction cost associated with entering the data into the registry is very low - less than 1 EWT.

Depending on whether you want to connect to the Energy Web Public Test Network (Volta) or the Energy Web Production Network (Energy Web Mainnet) there are two ways of getting funds for your wallet:

3.3 Create, read, update and delete your OCN Identity

After funding your wallet, you are now ready to make OCN Registry entries. Please follow the technical instructions on the OCN Registry repository on GitHub "Listing a Party" for more detailed steps on how to do this using the CLI library, TypeScript library or Java library.

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

Your OCN Identity is your key to participate in the Open Charging Network. Your private key from your cryptographic wallet (Step 2) is required for managing your OCN Registry entry (your self-sovereign identity). Keep your private key safe! It is advised to follow best-practices for secure storage and usage (similar to API Token Management, management of cryptocurrencies, etc.)

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

Contents

1. Prerequisite Check

   1. Configure MetaMask settings

   2. Secret Engine credentials

2. Resource Provisioning

   1. Launching Digital Spine Integration Client instance

   2. Config DSI Client

3. Client UI walk through

4. Creating Channels

   1. Creating a Publish Channel

   2. Creating a Subscribe Channel

5. Demo Integration - test Sending / Receiving data

   1. Example Post data to a Channel

6. Conclusion

1. Prerequisite Check

1.1. Configure MetaMask settings

To integrate the DSI Client with the Energy Web-hosted message broker, you will need to acquire and manage roles on Switchboard (https://switchboard.energyweb.org/). Metamask is used to log into the Switchboard dApp and sign transactions.

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.

You can also use ChainList to quickly add Energy Web Chain as a new network to your MetaMask. To use this tool, please follow this link and click “Add to MetaMask” button.

• 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

The Switchboard dApp does require users to use Energy Web Tokens (EWT) in order send transactions, sign messages or acquire credentials on the Energy Web Chain.

To learn how to acquire EWT in your wallet, click here

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

{
 “appId”: “32xxx725-7xx9-46d1-b288-c552xxxxxab35",
 “displayName”: “vault-demo-sp”,
 “password”: “SLxxQ~2ul1J~4wxxNZ-o~sb65l4KuNhxxXaK9c4j”,
 “tenant”: “14e3fxx-fd1f-4exx9-a2aa-4a9xxxxxxx129"
}

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

Learn more about

• Azure Key Vault documentation

• Azure Service principle

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

It can take up to a minute for the DID to be verified and configured (assuming that your DID already has the role 'user'; if not, complete the enrollment form here).

If your wallet does not have sufficient balance (a minimum of 0.1 EWT is recommended) you may receive an ‘insufficient fund’ error message. To learn about transactions and transactions costs, click here; to learn how to acquire EWT in your wallet, click here.

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

If your DID doesn't have the required 'user' role to the application you selected for the Integration Client at resource creation step. You'll see an ‘Unauthorized’ error.

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.

In a new browser tab, visit Switchboard (https://switchboard.energyweb.org/), click on the Use MetaMask button on the welcome screen of the Switchboard 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 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.

At the time of revisiting the DSI Client, it should successfully redirect you to the dashboard page. If not, check to make sure your Metamask extension is connected to the correct (enrolled) account. If the correct account is active, you may need to refresh the DSI Client landing page and re-enter your private key as described in the previous section.

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.

You can learn more about topics here

Next we'll explain how to use the topic.

4. Creating Channels.

You can have a better understanding about Digital Spine channels here. Few summarised Key points to bear in mind.

• "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:

{
    "fqcn": "demo.pub",
    "topicName": "sample_topic",
    "topicVersion": "0.0.1",
    "topicOwner": "marketplace.apps.energyweb.iam.ewc",
    "payload": "{ \"message\": \"This is my first demo message\" }"
}

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

The query information can also be retrieved from the channel detail as explained in the previous step.

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.

And contact us at digital-spine.support@energweb.org to acquire the 'topiccreator' role to create topics to test scenarios based on your business requirement.

Overview

The Open Charging Network is a decentralized implementation of the OCPI 2.2 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?

In the context of OCN, running a node means running and hosting an instance of the OCN node software.

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

2. Administration of Node and Connected Parties

3. Keep Your OCN Node Up to Date

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.

For this, a demonstration of a network simulation with two OCN Nodes and mock parties (CPO and eMSP) has been provided. Please visit this page to learn more and to find the necessary repositories for running the demo: Examples

If you are familiar with the concept behind the Open Charging Network you can start the setup and configuration of your OCN Node. We recommend first running the node on the Test Environment before moving to Production.

Visit the OCN Node README page in the GitHub repository for a step-by-step guide and all necessary resources: OCN Node Repository

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.

The HTTP API Documentation for the OCN Node describes the available endpoints which can be used by administrators and parties.

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 release date of an update will be announced on our Gitter community at least two weeks before it will come into effect (be pushed from its DEVELOP BRANCH to the MASTER BRANCH). It is planned to keep the components downwards compatible at least one version, but this may not always be possible. Please make sure that you update your OCN Node within 24 hours after the publication of a new release.

This page documents the role and lifecycle of credentials in the IAM stack.

Credentials are documents that allow individuals to show that they possess certain accreditations (this is discussed further in depth below - 'Credentials Overview'). Credentials are traditionally document or paper-based, such as a driver's license or a passport, and are typically registered in a centralized repository under the stewardship of the issuing body.

Verifiable credentials are purely digital components that can be verified cryptographically. Verifiable credentials are a secure and self-sovereign alternative to traditional paper-based credentials or documents, which typically must be physically or electronically transmitted for verification, and have the potential to be intercepted, altered or tampered with.

In general, verifiable credentials do not rely on Decentralized Identifiers (DIDs) but they are often used together. If DIDs are used, decentralized ledger technology (i.e. a blockchain) can provide the public key infrastructure for the cryptographic verification.

The specification that defines verifiable credentials was established and is maintained by the World Wide Web Consortium (W3C). This protocol continues to evolve. Verifiable credentials are one of the three core pillars of self-sovereign identity, along with decentralized identifiers (DID) and distributed ledger technology.

Verifiable credentials are a key component of Energy Web's Identity, authorization and access management. In current use cases, credentials are used to authorize users' or assets' enrolment into applications and organizations. Each credential is associated with the subject's DID that is anchored on the Energy Web Chain. Energy Web's Switchboard application provides a user interface for creating, requesting, issuing and revoking role-based credentials. Energy Web's IAM libraries and APIs facilitate the full lifecycle of verifiable credentials. The Energy Web blockchain serves as the trust or verification layer for digital proof. This documentation provides references to these libraries, and to supporting W3C documentation that is used to guide and inform the development of Energy Web's IAM solution.

Click below to see a current diagram of Energy Web IAM architecture:

Credentials Overview

A claim is an assertion that is made about a subject. A claim could assert, for example, that a battery meets specific manufacturing standards.

A credential is a claim(s) made by an issuer about a subject. When the credential issuer makes a claim about a subject, they issue a verifiable credential. For example_,_ an issuer can issue a credential for a battery that asserts that it was manufactured on a specific date in a specific location.

In order for a credential to be verifiable, it must contain a proof mechanism and supporting information to evaluate the proof. The proof must be able to be verified through cryptographic (i.e. algorithmic) means, typically through a digital signature. Energy Web's IAM libraries support digital signatures of Ethereum-compatible wallets, such as MetaMask.

Proofs provide two primary functions:

1. To verify the authorship of a credential

2. To detect tampering or alteration to the credential/presentation

In the example of the battery mentioned directly above, the proof will verify that

1. The issuer is authorized to assert that the battery was manufactured on a specific date and in a specific location

2. That the credential data and digital signature has not been changed or compromised

Note that proof mechanisms do not validate the facts that the claim asserts (in the example above, the providence of the battery). It only verifies the issuer of the claim and the integrity of the claim's data over time (i.e. has the data been altered or tampered with).

Proof Mechanisms

There are two main proof mechanisms for verifying credentials, both of which are used in the IAM stack. These will be discussed further below.

1. External proofs, which are commonly expressed by JSON Web Tokens. An external proof is one that wraps an expression of the credential data model, such as a JSON Web Token. See the W3C JSON payload encoding standards for verifiable credentials here. Verifiable Credentials expressed as JSON Web Tokens in the IAM stack is discussed below.

2. Embedded proofs, in which the proof is included directly in the credential's JSON data. To be compatible with W3C Verifiable Credentials standard, the credential JSON must have a property of 'proof'. Verifiable credentials expressed as JSON/JSON Linked Data in the IAM stack are discussed below.

Credentials in the Energy Web Stack

The Energy Web IAM stack provides API methods to request, issue, publish, verify and revoke credentials.

Our ecosystem offers persistence for credentials on the Energy Web blockchain, and off the blockchain using the decentralized file system IPFS.

• Credentials that are persisted on the Energy Web Chain are referred to as 'on-chain' credentials

• Credentials that are persisted off-chain are referred to as 'off-chain' credentials

The distinctions are discussed in the following section.

'On-Chain' Credentials

On-chain credentials are registered on the Energy Web blockchain in the Claim Manager smart contract. The contract source code can be found here. A credential is registered in the contract when the credential is published by the holder.

Credential Smart Contracts

There are currently two smart contracts deployed on the Energy Web Chain that are used for verifying and persisting verifiable credential data (for 'on-chain credentials' only). The source code for these contracts can be found in the @energyweb/onchain-claims package.

'Off-Chain' Credentials

Off-Chain credentials are not referenced on the blockchain. Off-chain credential data is persisted as a JSON web token on IPFS, a decentralized public filesystem. IPFS, like a blockchain, is a decentralized system and relies on a network of peer nodes to create a distributed system.

When a token is stored on IPFS, it has a content identifier (CID) that points to its location on the file system. This CID is linked to the credential's corresponding DID Document through a service endpoint. A service endpoint points to any service that supports or acts on behalf of a DID. The CID is used to fetch and resolve the full credential from IPFS when necessary.

Off-Chain Credential Schema

For each off-chain credential request, iam-client-library issues two credentials of different format and proof type.

Both signature mechanisms can be performed by Ethereum-based wallets such as MetaMask.

1. JSON Web Token with EIP-191 signature

A JSON web token is a common standard for transferring encoded, verifiable data between parties. The JSON web token payload is generated from the claim data.

• Proof Mechanism: EIP-191 signature standard

• Data Model: The JWT payload partially conforms to the properties established by W3C for verifiable credentials as a JWT. You can view these properties here.

• Persistence: The issued token is included in an object that contains other data about the issued credential request. (Read more about claim issuance below). The token is persisted in the SSI Hub's database when the credential is issued, and persisted in IPFS when a credential is published by the subject. The credential's location in IPFS is referenced in the user's DID Document's service endpoints.

2. JSON-LD Verifiable Credential with EIP-712 signature

• Proof Mechanism: EIP-712 signature specification. This allows the credential data to be displayed in a human-readable format when digitally signing the message:

• Data Model/Interface: The Verifiable Presentation interface conforms to W3C credential schema, which includes JSON-LD (JSON Linked Data) data format. JSON linked data ensure that credentials and presentations are universally machine readable and compatible. Read more about JSON-LD formatting in verifiable presentations and credentials in the W3C documentation here.

• Persistence: The verifiable presentation is included in an object that contains other data about the issued credential. This object is persisted in SSI Hub database.

On-Chain vs. Off-Chain Registration Rationale

In addition to the above, there are a few distinctions to consider when deciding to register credentials off-chain or on-chain.

• On-chain credentials can be read by any smart contract deployed on the Energy Web Chain, and thus used in many decentralized applications. This allows for greater application interoperability.

• Off-chain credentials in IPFS do not require any transaction costs that are associated with a blockchain, and can be resolved by an IPFS client in any application.

IAM Stack Credential Lifecycle

1. Request Credential

A credential request occurs when a user requests to enrol to an organization or application’s pre-defined role. The role may have specified criteria that the subject must meet in order to take on the role. The user who is requesting to take on the role is the claim ‘subject’.

iam-client-library contains high-level methods to initiate credential requests. These methods indicate whether a credential should be registered 'on-chain' or 'off-chain'.

Claim requests are persisted in the SSI Hub.

Example

A user makes a request to the credential issuer to enrol into Organization A as a 'Battery Installer'. This role is pre-defined by Organization A, and has a designated set of issuers (each with a DID) who are authorized to approve and issue a credential for the 'Battery Installer' role. At the time of request, the subject must specify if they want this credential to be persisted on-chain or off-chain.

2. Issue Credential

The credential's issuer approves and issues (or rejects) a subject’s credential request. By issuing the credential, they are verifying that the subjects meets the requirements needed to obtain the credential.

Using the example **** above, the issuer is issuing a credential of 'Battery Installer' to the subject. In doing so they are asserting that the subject meets the requirements to hold this credential. They are signing the credential (providing proof) with their digital signature using an Ethereum- compatible wallet such as MetaMask.

Issuing On-Chain Credentials

If a credential has an **'**on-chain' registration type, the verified credential is registered in the Claim Manager smart contract.

Issuing Off-Chain Credentials

As discussed above, off-chain credentials are issued in two formats:

1. A verifiable presentation ****

2. A signed JSON Web token****

The verifiable presentation and issued token are appended to the claim data, which is updated in the SSI Hub.

3. Publish Credential

Once an issuer has issued a credential, the subject has the option to publish (persist) the credential. The persistence location depend on if the credential is registered on-chain and/or off-chain. Persistence for on-chain credentials is discussed above here. Persistence for off-chain credentials is discussed above here.

4. Revoke Credential

The W3C Verifiable Credential protocol includes revocation as a standard operation in the credential lifecycle. Credentials can be revoked due to a breach in proof integrity (digital signature), or because the subject no longer meets the requirements to hold the credential.

The IAM stack provides methods for a revoker to revoke a credential after it has been issued.

Revocation for Energy Web credentials is executed based on the Role Governance. Only an authorised revoker (a DID or any DID with specific role credential) can revoke a credential.

Revoking On-Chain Credentials

When an on-chain credential is revoked, the revocation is registered in the ClaimsRevocationRegistry smart contract. This smart contract holds a reference to every revoked credential. The ClaimsRevocationRegistry contract references the ENSRegistry contracts to ensure that the revoker has the right authority to execute revocation and ClaimManager contract to validate if the subject has the role credential (to be revoked) and if revoker's authoritative credential has either expired or revoked (for the case where revoker's authority is based on a specific role credential).

For a revoker to be able to revoke an on-chain credential, their authoritative credential should also be published on-chain.

On-Chain Revocation Sequence:

Design Rationale

For a credential to be verifiable on-chain, a verifier should be able to check the revocation status of the issued credential along with the issuance.

It should be possible to get a single source of truth for a revocation status i.e. a verifier should be able to get a valid revocation from a registry without the need to verify it again.

For a revocation to be registered on-chain it is necessary that the credential first be registered on-chain with ClaimManager, where holder has provided their consent to make the credential publicly available.

The publishing of a holder's credential reduces the privacy and allows someone to determine if a holder has been issued a role credential or not.

In other words, revocation of a credential which has not been published yet would imply that the holder holds the role credential reducing the privacy of the holder's credential.

Therefore, the revocation registry requires that the holder consent to their credential being on-chain and publishing it to the ClaimManager registry.

Having the credential in the ClaimManager allows the ClaimsRevocationRegistry to provide verifiability of:

1. Only verified and valid credential being revoked, ClaimManager verifies credential's integrity and its issuer's authority before registration.

2. Credential's validity with regards to expiration.

3. Revoker's authority who revoked Holder's credential.

Thus establishing a design which provides Verifier with a trusted mechanism for revocation status check which ensures that a valid credential can only be revoked by an authoritative revoker.

Revoking Off-Chain Credentials

When an off-chain credential is revoked, the credential JSON is updated with a "credentialStatus" property that is conformant to W3C's StatusList2021 data model. This data model provides a link for verifiers to use to see the status of a credential (i.e. if a credential has been revoked by the revoker). The verifier can verify this credentialStatus property and derive the revocation status of the credential. You can view the properties of the StatusList2021 data model here.

When a credential is revoked using iam-client-library, which utilises status-list module to append this credentialStatus property to credentials, the credentialStatus will have a statusPurpose that reflects it has been revoked:

credentialStatus: {
    id: 'https://credential-status/admin',
    type: StatusListEntryType.Entry2021,
    statusPurpose: CredentialStatusPurpose.REVOCATION,
    statusListCredential:
      'https://isc.energyweb.org/api/v1/status-list/700xxxxx-5xxx-4xxx-bxxx-43acfaxxxxxx',
    statusListIndex: '0',
  }

Status list credentials are persisted in SSI Hub. The credentialStatus object has an attribute statusListCredential that provides a URL thorugh to fetch the credential's status for verification purposes.

More detailed documentation around StatusList2021 can be found here

5. Verify Credential

A verifier is responsible for verifying the authenticity of a credential. The criteria for this evaluation is specified by the W3C Verification standards here. iam-client-library provides verification methods that evaluates these criteria, namely:

1. The credential proof (typically the digital signature) is valid.

2. The credential is not revoked.

3. The credential is not expired.

Beyond the scope of basic verification, iam-client-library's verification methods also validate the issuer's authorization to issue the credential and does this for all the issuers in the hierarchy.

This verification is executed for off-chain credentials and relies on the subject's (holder or issuer) DID Document resolution.

Off-Chain Verification Sequence:

Related Content

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.

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

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

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 Request for Proposal for Sign-in with Ethereum in 2021, based on EIP-4361 (ERC-4361: Sign-In with Ethereum). The reference implementation of Sign-In with Ethereum by SpruceID (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

${domain} wants you to sign in with your Ethereum account:
${address}

${statement}

URI: ${uri}
Version: ${version}
Chain ID: ${chain-id}
Nonce: ${nonce}
Issued At: ${issued-at}
Expiration Time: ${expiration-time}
Not Before: ${not-before}
Request ID: ${request-id}
Resources:
- ${resources[0]}
- ${resources[1]}
...
- ${resources[n]}

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 :

switchboard-dev.energyweb.org wants you to sign in with your Ethereum account:
0x09622D91d6aA98385f40D3D0713BaA66baF3281A


URI: https://identitycache-dev.energyweb.org/v1/login/siwe/verify
Version: 1
Chain ID: 73799
Nonce: wRiKroUIa9LuYWWeG
Issued At: 2023-03-07T09:07:46.050Z

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

Many organizations aim to deploy a unified Identity Service that can be utilized across all federated services, employing OpenID Connect for efficient user session management. Thanks to SIWE-OIDC (OpenID Connect Identity Provider for Sign-In with Ethereum), this objective has now become achievable.

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.

curl -X POST https://oidc.signinwithethereum.org/register
   -H 'Content-Type: application/json'
   -d '{"redirect_uris": ["<https://<your.comaind>/cb"]}'>

The following is an example response:

{
"client_id": "9b49de48-d198-47e7-afff-7ee26cbcbc95",
"client_secret": "er...",
"registration_access_token": "2a...",
"registration_client_uri": "https://oidc.signinwithethereum.org/client/9b49de48-d198-47e7-afff-7ee26cbcbc95",
"redirect_uris": ["https://<your.domain>/cb"]
}

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.

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

The blockchain performs three key functions in EW-DOS:

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

2. Facilitates on-chain verification and transactions between parties

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

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

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

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

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

Persistence on the Energy Web Chain

The Energy Web Chain stores the following information:

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

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

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

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

Related Content

REVIEWER FEEDBACK

When using Switchboard, users can create and update data that is stored in smart contracts on the Energy Web Chain. These actions require users to pay a small transaction cost. Users pay transaction costs using their cryptocurrency wallet such as MetaMask. Transaction costs on the Energy Web Chain are in Energy Web Token. Transaction costs on the Volta Test Network on are in Volta Tokens.

The transaction cost amount depends on what action the user is performing, and the current gas cost. Actions and their estimated associated total transaction cost are listed below. They are organized according to the three main domains of Switchboard: Enrolments, Governance and Assets.

Calculating Transaction Costs

The total costs calculated below is the sum of the cost to process the metadata and the current gas cost. The costs below are approximate values per operation. The total cost can change:

• Based on the user input data (e.g. number of input fields)

• Based on congestion (i.e. how many transaction requests are currently in the pool to be processed), which affects gas price

Enrolments

Switchboard is used to request, issue, publish and revoke role-based credentials. These credentials are persisted on the Energy Web Chain (read more about on-chain credentials here). As such, they require transaction costs to cover their on-chain lifecycle events.

My Enrolments

Revocable Enrolments

Governance

Switchboard is used to create and manage organizations, applications, and roles associated with them. These elements are persisted in Energy Web's Ethereum Name Service smart contract. ٍ Each time a user creates or updates one of these entities, they must pay a small transaction cost

Organizations

Applications

Assets

Switchboard is used to create (register), manage and transfer Assets. Each Asset is registered in a smart contract on the Energy Web Chain (read more about Assets as ownable smart contracts here.) Each time a user interacts with these contracts for Asset management, they must pay a small transaction cost:

Related Content

VC-API is specification of a data model and HTTP protocols to issue, verify, present, and manage data in a Verifiable Credentials ecosystem.

Energy Web provides an implementation of VC-API to reduce difficulties for organizations to start issuing and verifying Verifiable Credentials. Using these APIs it becomes easy for anyone to do Proof of Concepts for SSI use cases.

VC-API can be easily integrated with existing systems and are configurable for complex exchanges. Implementers can choose to implement APIs that fits their use case. One can keep it simple with minimal set of APIs even for complex data exchanges (presentation).

Refer VC-API specification for more information.

Advantages of EW implementation of VC-API :

1. Portable, can be easily deployed to any environment and can be kept generic.

2. Easy integration and configuration.

3. Selective implementation of APIs based on the use case. For an application that provides feature to issue a credential only need to consume APIs specific to issuance.

4. Supports both Mediated and Unmediated exchange.

Entities of VC-API

The Verifiable Credentials data model introduces three actors Issuers, Holders and Verifier. VC-API defines components that these actors may use for credential issuance, verification and exchange.

Each actors can have their own set of components to participate in the credential exchange.

1. Coordinators : execute the business rules and policies set by the actors. Also acts as mediator between these actors.

2. Services : enable general VC-API functionality.

3. Status Service : facilitate publishing and checking of status of Verifiable Credentials.

4. Admin : responsible for configuring and managing all the other components.

5. Storage Services : provide mechanisms to store and manage Verifiable Credential of the associated actor.

Energy Web's implementation of VC-API only provides services which enable VC-API functionality. A developer can implement their own components that are mentioned above.

Use-case functionalities

Applications can perform authorisation, issuance, verification and presentation exchanges using VC-API.

1. Authorisation

Servers implementing VC-API can confirm clients to utilise authorisation mechanism when performing certain requests. The request APIs endpoint can specify whether authorisation is needed or not.

1. Issuance

For issuance of Verifiable Credentials, a holder can request any authority (Issuer) to issue a credential or can self-sign a credential.

1. Verification

A Holder can present their Verifiable Credential to the Verifier for verification. The Verifier can request the required credential from the holder using presentation-exchange protocol.

1. Presentation

The sharing / exchange of Verifiable Credentials happen through presentation. These exchanges are executed based on the exchange-definition that are configured at run time.

A general exchange flow would look like :

Exchange Definition

The VC-API implementation can be easily deployed to any environment and can be kept generic, in other words exchanges are configured rather than coded in the application. This configuration is done at runtime via the use of Exchange Definitions.

In order to configure the credential exchange, you can use the exchange definition data transfer object. For reference see the Exchange Definition Data Transfer Object implemented by Energy Web.

Some different types of exchange definitions are :

Sample DIDAuth query VP Request

{
  "verifiablePresentationRequest": {
    "query": [{
        "type": "DIDAuthentication"
      }, {
        "type": "QueryByExample",
        "credentialQuery": {
          "reason": "We need to see your existing University Degree credential.",
          "example": {
            "@context": [
              "https://www.w3.org/2018/credentials/v1",
              "https://www.w3.org/2018/credentials/examples/v1"
            ],
            "type": "UniversityDegreeCredential"
          }
        }
      }],
      "challenge": "3182bdea-63d9-11ea-b6de-3b7c1404d57f",
      "domain": "example.edu",
      "interact": {
        "service": [{
          "type": "UnmediatedPresentationService2021",
          "serviceEndpoint": "https://example.edu/exchanges/refresh-degree/0bc42ece-89f7-11ec-9af0-136dfa9e4dbb"
        }]
    }
  }
}

Sample PresentationDefinition query VP request

{
"exchangeId":"<SOME UNIQUE ID>",
    "query":[
      {
         "type":"PresentationDefinition",
         "credentialQuery":[
            {
               "presentationDefinition":{
                  "id":"286bc1e0-f1bd-488a-a873-8d71be3c690e",
                  "submission_requirements":[
                     {
                        "name":"Consent and Resident-card Exchange",
                        "rule":"pick",
                        "min":2,
                        "from":"A"
                     }
                  ],
                  "input_descriptors":[
                     {
                        "id":"PermanentResidentCard",
                        "name":"PermanentResidentCard",
                        "purpose":"PermanentResidentCard",
                        "group":[
                           "A"
                        ],
                        "constraints":{
                           "fields":[
                              {
                                 "path":[
                                    "$.type"
                                 ],
                                 "filter":{
                                    "type":"array",
                                    "contains":{
                                       "type":"string",
                                       "const":"PermanentResidentCard"
                                    }
                                 }
                              }
                           ]
                        }
                     }
                  ]
               }
            }
         ]
      }
   ],
   "interactServices":[
      {
         "type":"UnmediatedHttpPresentationService2021"
      }
   ],
   "isOneTime":true,
   "callback":[
      {
         "url":"FILL YOUR CALLBACK URL, for example 'https://webhook.site/efb19fb8-2579-4e1b-8614-d5a03edaaa7a'"
      }
   ]
}

Exchange Definition Structure and Properties

exchangeId

exchangeId is definition identifier, used to fetch exchange-definition

Exchange Queries

The Exchange Definition has a query property that tells which data needs to be requested. The type of queries that are supported are defined by VerifiablePresentationQueryType, for reference see VpRequestQueryType.

The DIDAuth query type is used for exchange needed for authorisation, while PresentationDefinition could be used to request certain data from the Holder.

Exchange Callbacks

When defining an exchange, callbacks can be configured to allow parties to receive notice of a VP submitted in response to an exchange. Notifications consist of POST requests to the configured URLs. A callback is configured by adding an entry to the callback array in the Exchange Definition.

Exchange Interact Services

The exchange interaction types used by this VC-API implementation are directly related to Verifiable Presentation Request Interaction Types. The interaction types indicate to the receiver of the presentation request how they can expect to interact further with the issuer/verifier.

1. Mediated Exchange Interactions

Mediated exchange interactions signal to the receiver of the presentation request that the exchange is mediated by an additional component and may not be automatically processed. Mediated exchanges therefore allow for a review of presentation submission by a human or automated process as well as the issuance of credentials based on this review.

Due to the duration of the mediation process being unknown, the submitter of the verifiable presentation may have to query repeatedly in order to check if the result of the mediation is available.

"interact": {
            "service": [
                {
                    "type": "MediatedHttpPresentationService2021",
                    "serviceEndpoint": "http://localhost:3000/exchanges/resident-card-issuance-82793/55fb5bc5-4f5f-40c8-aa8d-f3a1991637fc"
                }
            ]
        }

1. Unmediated Exchange Interactions

Mediated exchange interactions signal to the receiver of the presentation request that the exchange is not mediated by an additional component and can be automatically processed.

"interact": {
      "service": [
        {
          "type": "UnmediatedHttpPresentationService2021",
          "serviceEndpoint": "https://vc-api-dev.energyweb.org/v1/vc-api/exchanges/b6754fca-f123-43ce-8bd2-92074f05a29b/25390400-e995-4f34-8f59-5820a8ce7816"
        }
      ]
    }

serviceEndpoint

serviceEndpoint is used to continue exchanges

Presentation Definitions.

These presentation exchange take place on the basis of presentation-definition. Verifiers articulate these definitions of what they require for proofs. The issuer then wraps their Verifiable Credentials on the basis of presentation-definition in a VP and provide a response to the Verifier.

The presentation_definition are constructed of inputs, that describe the format and details for proofs required. They may also contain selection or filter rules for the presented Verifiable Credentials.

{
  "presentation_definition": {
    "id": "Scalable trust example",
    "input_descriptors": [
      {
        "id": "any type of credit card from any bank",
        "name": "any type of credit card from any bank",
        "purpose": "Please provide your credit card details",
        "constraints": {
          "fields": [
            {
              "path": [
                "$.termsOfUse.type"
              ],
              "filter": {
                "type": "string",
                "pattern": "https://train.trust-scheme.de/info"
              }
            },
            {
              "path": [
                "$.termsOfUse.trustScheme"
              ],
              "filter": {
                "type": "string",
                "pattern": "worldbankfederation.com"
              }
            },
            {
              "path": [
                "$.type"
              ],
              "filter": {
                "type": "string",
                "pattern": "creditCard"
              }
            }
          ]
        }
      }
    ]
  }
}

A presentation_definition has input_descriptors property which has an array of objects with properties describing what type of input data (credential) or sub-fields are required for submission.

See input_descriptors to know more.

Let's understand different workflows with VC-API

Presentation exchange between Holder and Issuer

Presentation exchange between Holder and Verifier

Example for a VC issuance and presentation using VC-API can be seen in Resident Card Tutorial.

Overview

The Block Reward contract manages block reward payouts to validators. Block rewards are issued as native Energy Web tokens that are minted by the engine.

Two entities are rewarded by each created block:

1. The block author (validator)

2. The community fund

Documentation and Source Code

• Energy Web Block Reward Contract

• OpenEthereum documentation on Block Reward Contract

Block Reward Payouts

Block Authors

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

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

Energy Web Community Fund

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

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

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

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

Interaction with Block Reward Contract

Contract Address and ABI

Callable functions

The 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

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 that identities participate in. These governance structures 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 . 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 (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 , and is anchored on the in the DID Registry. See further documentation on DIDs in self-sovereign identity and the IAM stack .

• 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 enrolment into an application or organization. See further documentation on verifiable credentials in self-sovereign identity and the IAM stack

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 .

EW SSI Toolkit Architecture Diagram

Further Documentation

For further documentation on our IAM stacks:

1. Install MetaMask

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

Read more about using MetaMask .

2. Get Tokens

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