Assets in EW-DOS

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

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

Asset Smart Contracts

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

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

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

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

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

Asset Owners

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

Asset Chain-of-Custody

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

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

Register Asset

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

Transfer Asset Ownership

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

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

1. Offer Asset

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

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

2a. Accept Asset

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

2b. Reject Asset

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

Asset Enrolment

An Asset can take on . If their enrolment request is approved by the role issuer, the Asset is issued a role-based .

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

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

provides the high-level methods to request and issue enrolments. See the API documentation .

Using and Managing Assets in EW-DOS

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

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

Use Case: Stedin Decentralized Asset Management

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

The goal of this collaboration was to:

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

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

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

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

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.

provides semantic disbiguation by requiring that terms be IRIs.

Linked Data Contexts

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

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

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

Open API Schema

SHACL

SHACL is the W3C standard for validating RDF graphs.

SHACL is being .

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

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.

Data Display

The specification describes how a credential can be displayed.

Governance

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

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

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

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

Governance Frameworks

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

Energy Web IAM Governance Framework

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

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

Role-based Hierarchies

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

The namespace hierarchy is built on four levels:

1. Organization: a top-level organizing body

2. Sub-organization(s)

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

Role-definition properties

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

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

Verifiable Credentials

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

See more extensive documentation on credentials in the IAM stack .

IAM Stack Governance Components

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

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

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

Additional Resources

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 . This protocol continues to evolve. Verifiable credentials are one of the three core pillars of , along with 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 that is anchored on the . Energy Web's application provides a user interface for creating, requesting, issuing and revoking role-based credentials. facilitate the full lifecycle of verifiable credentials. The serves as the trust or verification layer for digital proof. This documentation provides references to these libraries, and to supporting 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 is an assertion that is made about a A claim could assert, for example, that a battery meets specific manufacturing standards.

A is a claim(s) made by an about a subject. When the credential issuer makes a claim about a subject, they issue a . 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 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. , such as .

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 . 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 . Verifiable Credentials expressed as JSON Web Tokens in the IAM stack is discussed.

2. Embedded proofs, in which the proof is included directly in the credential's JSON data. To be compatible with , the credential JSON Verifiable credentials expressed as JSON/JSON Linked Data in the IAM stack are discussed .

Credentials in the Energy Web Stack

The Energy Web IAM stack provides API methods to , , and credentials.

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

• Credentials that are persisted on the Energy Web Chain are referred to as

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

The distinctions are discussed in the following section.

'On-Chain' Credentials

On-chain credentials are registered on the in the Claim Manager . The contract source code can be found . A credential is registered in the contract when the credential is 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 .

'Off-Chain' Credentials

Off-Chain credentials are not referenced on the blockchain. Off-chain credential data is persisted as a on , 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 that points to its location on the file system. This CID is linked to the credential's corresponding through a . 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, issues two credentials of different format and proof type.

Both signature mechanisms can be performed by .

1. JSON Web Token with EIP-191 signature

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

• Proof Mechanism: 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 .

• Persistence: The issued token is included in an object that contains other data about the issued credential request. (Read more about claim issuance

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

• Proof Mechanism: 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 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 .

• Persistence: The verifiable presentation is included in an object that contains other data about the issued credential. This object is persisted in 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 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 ‘.

contains high-level methods to initiate credential requests. These methods indicate whether a credential should be registered or .

Claim requests are persisted in the .

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

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 **** 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 ) with their digital signature using an .

Issuing

If a credential has an **'**on-chain' , the verified credential is registered in the .

Issuing

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

1. A ****

2. A signed ****

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

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 and/or . Persistence for on-chain credentials is discussed above . Persistence for off-chain credentials is discussed above .

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 to revoke a credential after it has been issued.

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

Revoking

When an on-chain credential is revoked, the revocation is registered in the . This smart contract holds a reference to every revoked credential. The ClaimsRevocationRegistry contract references the to ensure that the revoker has the right authority to execute revocation and 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 .

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

When an off-chain credential is revoked, the credential JSON is updated with a "credentialStatus" property that is conformant to 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 .

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

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

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 . provides verification methods that evaluates these criteria, namely:

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

2. The credential is not .

3. The credential is not expired.

Beyond the scope of basic verification, 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) resolution.

Off-Chain Verification Sequence:

Related Content