EWAI ROLES AND SWITCHBOARD INTEGRATION

EWAI utilizes EnergyWeb Name Service (EWNS) identifiers to identify various entities and EW-Switchboard roles for authorization.

With regards to terminology. A DID represents a decentralized identifier, typically an eth or ewc address in the case of EWAI. An example of a DID is did:ethr:0x1234... A DER is a distributed energy resource IOT device; DERs have their own DID address also. There are also what EWAI refers to as external DIDs, such as an Ocean Data Asset DID; an Ocean Protocol DID is in the form did:op:0x1234...

An overall diagram of how roles work in EWAI is given here. While fairly busy diagram it is important to review for it contains all the items which are managed and interfaced with by EWAI:

MARKETPLACE

Each clean energy data marketplace (hereafter simply called marketplace) is composed of either a Web3 dApp (e.g. EWAI-MARKET for Ocean Protocol) or a Web2 App which is paired with an attendant EWAI-SERVER instance. Each marketplace is given and identified by a unique EWNS. This EWNS is also called the "Ewai Instance Name" see config setup. This EWNS must be setup in EW-Switchboard as an app.

Example: energymarket1.apps.bigco.iam.ewc

EWAI-SERVER

The EWAI-SERVER instance is the server-side PTD message storage subsystem which is paired with the marketplace dApp, and which caches, stores and assembles streams of PTD (power telemetry data) packets which are sent to the marketplace via EW messaging from DERs. EWAI also performs other functions such as validating the PTD message signature, data schema, and then groups them into data asset “datasets.” EWAI uses PostgreSQL to do the storage at this time. The EW-Messaging channel for an EWAI-SERVER instance is constructed by a munged form of the EWAI Instance EWNS (e.g. energymarket1_apps_bigco_iam_ewc). It is through that messaging channel that DERs send PTD messages to a given EWAI asset on a given EWAI-SERVER (marketplace).

The EWAI-SERVER exposes both a REST API and a GraphQL API which the marketplace dApp and EWAI-LISTEN use to communicate with it. Example:

https://ewai14.bigco.org:3001/ewai/api (REST API) https://ewai14.bigco.org:3000/graphql (GraphQL API)

MARKETPLACE OWNER/OPERATOR

It is assumed there is a “marketplace owner”, which is a DID that owns the marketplace App EWNS. It is envisioned that this DID could also be properly called the “operator” of the marketplace. As the operator, they have a responsibility for setting up EWAI-SERVER and EWAI-MARKET in a proper production environment as they will also be acting as a custodian for the energy data asset “data” which is stored by EWAI. Further discussion of those matters is not the scope of this doc.

EWAI-SERVER checks that the marketplace EWNS is owned by the DID private key set in the EWAI-SERVER config file. There is a setting to disable this check, but that is not recommended.

MARKETPLACE ADMIN

It is assumed there are also a “marketplace admin” App role created under the marketplace EWNS:

Example: admin.roles.energymarket1.apps.bigco.iam.ewc

It is further assumed there could be multiple DIDs enrolled to that role.

DATA ASSET PUBLISHER

A Data Asset Creator (Publisher) is someone who creates energy data assets on the marketplace. The data asset publisher is a DID which has been enrolled in a “data asset publisher” App role created under the marketplace EWNS (presumably by the marketplace admins). A data asset publisher is identified by a DID. Example:

DID: did:eth:0x1234… enrolled in: publisher.roles.energymarket1.apps.bigco.iam.ewc

It is further assumed there could be multiple DIDs enrolled with that data asset publisher role. There is only one data asset publisher role per marketplace. It would be reasonable to set the roles up so that the marketplace admins can approve enrollments of DIDs (marketplace users who want to create energy data assets) into the Data Asset Publisher role.

There could be also requirements for identification in this enrollment (which may differ by marketplace) such as Name, Company, Email, etc. as deemed necessary for the proper operation (and administration and support) of the marketplace. For example, who does someone contact if they have a problem with a particular data asset? There may (but need not be) some relationship with Data Asset Publishers and network operators/installers of the DER networks.

It is assumed further that a DID may need to meet additional claim(s) for enrollment as a data asset publisher; however, that is not a matter controlled or needed by EWAI. An example, perhaps only licensed or certified “network installers” or operators approved by the operator of the marketplace can create data assets. There is a lot of responsibility in creating data assets, as one must also have further technical knowledge, such as setting up EW messaging, Provisioning DERs, setting up Switchboard roles, data asset schema specification, etc. One must also know how to provision DERs to send data to this data asset.

Note that data asset publisher(s) may or may not be affiliated with the owner/operator of the marketplace.

ENERGY DATA ASSET

Each marketplace is composed of one or more (hopefully many) energy data assets. These are what end users, called “data consumers,” will purchase and subscribe to (via Ocean Protocol in the case of EWAI-MARKET). These data assets contain the actual Power Telemetry Data from a certain set of DERs. Conceptually, each data asset is a time-series set of PTD data packets aggregated from all the DERs sending data into it, typically with a uniform data-schema, which can be specified by the Data Asset Publisher and then enforced by EWAI. Schema validation can help ensure homogenous data in each data asset (i.e. not filled with random junk packets sent in by DERS, even if they are approved).

Each Data Asset is uniquely identified by 3 things:

  1. An EWNS: Example: windarm1.bigco.ewc. Note that the EWNS for a data asset need not be under the marketplace EWNS. The EWNS simply uniquely identifies a particular energy data asset. Note in particular that these Data Asset EWNS may be completely unrelated to the marketplace dApp domain, EWNS, etc. They are more conceptually tied to the “data asset” being created, which would make sense for data consumers.
  2. A UUID, which uniquely identifies the asset in the EWAI instance db, and
  3. An “External DID”, which in the case of EWAI-MARKET is the Ocean “Data asset” DID (e.g. did:op:0x1234…).

EWAI requires that the EWNS of a Data Asset is owned by the Data Asset Creator DID; the Data Asset Creator DID is taken from the Web3 wallet account which is connected.

The data asset publisher must also specify what role is required in order for a DER to send PTD messages into this data asset. This role must be specified when the data asset is created on the marketplace. Note again, that this role need not be under the organization/app of the marketplace. It may not even be related to the EWNS of the data asset itself. It is simply a role which DERs must possess in order for messages they send to be accepted into the data asset.

DATA CONSUMER

These are end-users of the marketplace dApp which search for, purchase, and subsequently (presumably) analyze energy data asset “datasets”. This can be for A.I. analysis or other reasons. Each Data Consumer is only identified by an ETH web3 address. The data consumer purchases access to a data asset on the marketplace, which in the case of EWAI-MARKET is via Ocean Protocol technologies.

DER

A DER is a distributed energy resource which desires to send PTD message data into a data asset on a marketplace, presumably in return for financial or other compensation of some kind (that’s beyond the scope of this doc). A DER is uniquely identified by its DID address.

Note that a DER/DID must have three roles in order to successfully publish to a data asset:

  1. Verify has messaging user role access
  2. Verify has marketplace messaging channel role access
  3. Verify has asset role access