Configuration - EWAI (Energy Web Clean Energy Data Marketplace Subsystem)

EWAI-SERVER CONFIG FILE SETUP

EWAI-SERVER utilizes a .env based config file for various settings. A sample file is provided (.env.sample) and shown below. Each item is explained further below. To get started, copy the sample file to .env and then adjust the options. You will have needed to setup EWNS, EW-Messaging and EW-Switchboard also to get the values used herein.

$cp .env.sample .env

Some of these settings are reported up to the EWAI-MARKET application layer also via various GraphQL Api Calls (ewaiInstance, ewaiCanCreateAsset, ewaiCanPublishAssetsOnMarketplace, etc). The only options left in the EWAI-MARKET repo config files are ones specific to the actual dApp/App configuration itself (e.g. Ocean Protocol and React settings, etc.). Therefore, all EWAI options are controlled from this one file.

CONFIG OPTIONS LIST

The options are listed below with some example sample values. These sample values generally are setup to use the EnergyWeb Volta test chain, etc.

EWAI_INSTANCE_NAME="market1.apps.bigco.iam.ewc"
EWAI_ASSET_PUBLISH_ROLE="assetpub.roles.${EWAI_INSTANCE_NAME}"
EWAI_ASSET_PUBLISH_ROLE_ENROL_URL="https://volta-switchboard.energyweb.org/#/enrol?app=${EWAI_INSTANCE_NAME}&roleName=publisher"
EWAI_ENFORCE_ASSET_PUBLISH_ROLE=true
EWAI_ENFORCE_DOMAIN_OWNERSHIP=true
EWAI_SWITCHBOARD_URL="https://volta-switchboard.energyweb.org"
EWAI_EWC_PRIVATE_KEY="abcdefgxxxx"
EWAI_EWC_RPC_URL="https://volta-rpc.energyweb.org"
EWAI_EWC_CHAIN_ID=73799
EWAI_DBCONN="postgresql://postgres:password@localhost:5432/ewai?schema=public"
EWAI_API_VERSION=v1
EWAI_API_BASE_URL="/ewai/${EWAI_API_VERSION}"
EWAI_API_HTTP_PORT=3001
EWAI_API_URL="http://localhost:${EWAI_API_HTTP_PORT}${EWAI_API_BASE_URL}"
EWAI_API_GRAPHQL_URL="http://localhost:${EWAI_API_HTTP_PORT}/graphql"
EWAI_HOLDING_PEN_ENABLED=true
EWAI_ALLOW_RESET_DATA=true
EWAI_API_DATA_ALLOW_GET_BY_EWNS=true
EWAI_API_DATA_RECORD_LIMIT_FALLBACK=10
EWAI_API_DATA_DAY_LIMIT_FALLBACK=30
EWAI_API_DUMP_SQL=false
EWAI_API_USERNAME="CoolUsernameGoesHere"
EWAI_API_PASSWORD="CoolStrongPasswordGoesHere"
EWAI_API_AUTH_ENABLED=true
EWAI_API_AUTH_RETRY_INTERVAL=5
EWAI_CACHE_SCHEMA_VALIDATORS=false
JWT_ACCESS_TOKEN_SECRET="somethinghere"
JWT_ACCESS_TOKEN_EXPIRATION_TIME=300
EWAI_SPAM_ASSET_FILTER_KEY="enter some string here you keep private"
#EWAI_EWC_IAM_CACHE_URL="https://volta-iam-cacheserver.energyweb.org/"
EWAI_EWC_IAM_CACHE_URL="https://volta-identitycache.energyweb.org/"
EWAI_MESSAGING_SERVER="http://localhost:3000/graphql"
EWAI_MESSAGING_BROKER_ROLE="messagebroker.roles.messaging.apps.energyweb.iam.ewc"
EWAI_MESSAGING_CHANNEL_PUB_ROLE="datapub.roles.${EWAI_INSTANCE_NAME}"
EWAI_MESSAGING_CHANNEL_SUB_ROLE="datasub.roles.${EWAI_INSTANCE_NAME}"
# TODO: This item should ideally be reported from the messaging server itself,
# TODO: but there currently is no call to allow that so it must be entered here
MESSAGING_USER_ROLE="user.roles.messaging.apps.energyweb.iam.ewc"

OPTION DESCRIPTIONS

EWAI_INSTANCE_NAME (string, required)

This is the unique EWNS name for this EWAI instance (an instance belongs to a single marketplace). Typically one instance will be paired with one marketplace dApp. EWAI uses unique EWNS names to identify both itself (it's instance) as well as each EWAI Data Asset defined. The use of valid EWNS names allows authentication, authorization and verification of permissions. Example: market1.apps.bigco.iam.ewc

NOTE: You can use something like market1-dev.apps.bigco.iam.ewc so that data-sets created are tagged with that on-chain and they won't appear later in your production marketplace. All Ocean energy data assets are tagged on-chain with meta-data field service.attributes.additionalInformation.energyweb.ewai.instance set to the EWAI_INSTANCE_NAME. This is how your EWAI marketplace instance finds the data assets which belong to your own marketplace, as ALL ocean data sets are out there on-chain. There is also a spam filter/hashcode check field added to prevent someone else spamming your marketplace with fake data assets they created. Since all this data is public on-chain in Ocean, anyone could theoretically create a data asset with that same meta-data tag, but they won't be able to provide a correct hash to go with it.

EWAI_ASSET_PUBLISH_ROLE (string, required)

Users of the marketplace site must have this role in their DID in order to create (publish) energy data assets. Example: assetpub.roles.market1.apps.bigco.iam.ewc

EWAI_ASSET_PUBLISH_ROLE_ENROL_URL (string, required)

The default EW-Switchboard Enrol Url to return (used only if an Enrol Url is not found for the marketplace publish role). Example:https://volta-switchboard.energyweb.org/#/enrol?app=market1.apps.bigco.iam.ewc&roleName=assetpub

EWAI_ENFORCE_ASSET_PUBLISH_ROLE (boolean, required)

If true, EWAI will check EW Switchboard to determine if an address has the proper publish role before they are allowed to publish datasets on the site. You can set this to false for dev (not recommended for production)

EWAI_ENFORCE_DOMAIN_OWNERSHIP (boolean, required)

This flag specifies whether EWAI enforces proper domain ownership in two areas:

Ensures that the the EWNS domain specified in EWAI_INSTANCE_NAME is actually owned by the EWAI_EWC_PRIVATE_KEY EWC address. This ensures that a marketplace cannot be started without a proper owner address (and private key) to match it.
Ensures that any datasets being created (which are also identified by an EWNS name) are also owned by the user address creating them on the site (from the web3 wallet they connected). This again ensures that datasets cannot be created for an EWNS name that is not owned by the one creating it.

This flag should always be true for production environments. The false setting is only helpful (and safe to use) when doing dev.

EWAI_SWITCHBOARD_URL (string, required)

Enter the URL for the EW-Switchboard site you will be using. Example: https://volta-switchboard.energyweb.org

EWAI_EWC_PRIVATE_KEY (string, required)

The private key for the EWC address that will be used in this EWAI instance for signing messages, etc.

EWAI_EWC_RPC_URL (string, required)

RPC Url for the EWC network you want to connect to. use https://volta-rpc.energyweb.org for Volta test net.

EWAI_EWC_CHAIN_ID (integer, required)

EWC Chain ID to connect to. Use 73799 for the Volta test net.

EWAI_DBCONN (string, required)

The database connection string to the PostgreSQL database for this EWAI instance.

EWAI_API_VERSION (string, required)

The current API version. Fixed at v1 for now.

EWAI_API_BASE_URL (string, optional)

The prefix url from the root domain used to serve EWAI REST API requests on. Leave blank to map REST routes to the root of the domain.

EWAI_API_HTTP_PORT (integer, optional, default=3001)

The HTTP Port that EWAI REST API will listen on. The default is 3001 to avoid conflicts with other node package/platform defaults of 3000.

EWAI_API_URL (string, required)

The fully constructed EWAI REST API Url. Most often, you only need to change the domain to match your EWAI instance and leave the rest alone.

EWAI_API_GRAPHQL_URL (string, required)

The fully constructed EWAI GraphQL Url. Most often, you only need to change the domain to match your EWAI instance and leave the rest alone. The /graphql part at the end is actually required.

EWAI_HOLDING_PEN_ENABLED (boolean, required)

The EWAI holding pen is a place where messages are stored which are received by EWAI which have no matching EWAI data asset defined for them. If this flag is true, the messages are stored in a "holding pen" table. If false, the messages are discarded (not stored and lost).

EWAI_ALLOW_RESET_DATA (boolean, required)

Set to true if you want to allow data resets on assets (erasing all data to an empty state for the asset, but leaving the asset defined as it was)

EWAI_API_DATA_ALLOW_GET_BY_EWNS (boolean, optional, default=false)

If true, data consumers can specify Data asset by EWNS. If false (the default recommended), they must specify the Data asset UUID (which is nearly impossible to guess).

EWAI_API_DATA_RECORD_LIMIT_FALLBACK (number, required)

The number of records returned for a data asset preview, if not set by the data asset record

EWAI_API_DATA_DAY_LIMIT_FALLBACK (number, required)

The number of days of data returned for a data asset, if not set by the data asset record

EWAI_API_DUMP_SQL (boolean, optional, default=false)

If true, the EWAI REST API data message store calls will return a log of event status strings about the processing of the message. This is helpful if you want EWAI Listen to dump status to the console during message handling (for debug).

JWT_ACCESS_TOKEN_SECRET (string, required)

The unique passphrase used to generate (and validate) JWT packets for authenticating to the API.

JWT_ACCESS_TOKEN_EXPIRATION_TIME (integer, optional, default=60)

The time (in seconds) which JWT tokens are valid for.

EWAI_API_USERNAME (string, required)

The username by which clients must authenticate to this EWAI api instance (both REST and GraphQL). API clients must authenticate via username/password and get a JWT token to then call subsequent API calls (both REST and GraphQL). You must specify this field even if you have auth temporarily disabled (e.g. for debug mode, see EWAI_API_AUTH_ENABLED).

NOTE 1: There is only one user that will be created in the EWAI instance db, matching this username/password. This is the user by which all API clients must authenticate. The register route in the REST/GraphQL API's is disabled. We actually don't want new random users to be able to register with EWAI as the only client(s) of an EWAI API instance that should be calling it are the (controlled) EWAI Listen and the dApp which are paired with it in an instance deployment.

NOTE 2: This db user (username/password) will be automatically created by the EWAI API process when it starts for the first time if it doesn't exist in the db - you don't have to seed the database with the user.

EWAI_API_PASSWORD (string, required)

The password by which clients must authenticate to this EWAI api instance (both REST and GraphQL). API clients must authenticate via username/password and get a JWT token to then call subsequent API calls (both REST and GraphQL). You must specify this field even if you have auth temporarily disabled (e.g. for debug mode, see EWAI_API_AUTH_ENABLED).

EWAI_API_AUTH_ENABLED (boolean, optional, default=true)

This setting can be used to temporarily disable JWT authentication requirements on all API calls (REST and GraphQL). This is only suggested for debug/dev mode convenience. All other instances should have AUTH enabled.

EWAI_API_AUTH_RETRY_INTERVAL (integer, optional, default=5)

This specifies how long (in seconds) EWAI Listen will wait if it cannot connect to the EWAI API before retrying again.

EWAI_CACHE_SCHEMA_VALIDATORS (boolean, optional, default=false)

If true, asset schema's will be cached. This requires a restart of the EWAI Server process if schema's an asset schema is updated however. Only set true if performance becomes an issue.

EWAI_SPAM_ASSET_FILTER_KEY (string, required)

Enter some string (like a password) that you keep private. This key will be used to encrypt a field in the Ocean on-chain asset meta-data. This field is to help prevent spam data assets on-chain from showing up in the marketplace. Once you set this value, you can not ever change it, or all the assets already created on-chain will not appear in the marketplace any longer.

EWAI_EWC_IAM_CACHE_URL (string, required)

Enter the EnergyWeb I AM cache server url you will be using.

EWAI_MESSAGING_SERVER (string, required)

Enter the url of the EW-Messaging server GraphQL API that this EWAI instance will be connecting to, e.g.: http://localhost:3000/graphql

EWAI_MESSAGING_BROKER_ROLE (string, required)

Enter the role which identifies the messaging server as a broker, e.g.: messagebroker.roles.messaging.apps.energyweb.iam.ewc

MESSAGING_USER_ROLE (string, required)

TODO: This item should ideally be reported from the messaging server, but there currently is no call to allow that, so it must be entered here, e.g.: user.roles.messaging.apps.energyweb.iam.ewc

EWAI_MESSAGING_CHANNEL_PUB_ROLE (string, required)

Enter the role that a DER must have in order to send messages into the EW-Messaging channel for this EWAI instance, e.g.: datapub.roles.market1.apps.bigco.iam.ewc

working...

EWAI_MESSAGING_CHANNEL_SUB_ROLE (string, required)

Enter the role that is used by this EWAI instance to pull messages from the EW-Messaging channel for this EWAI instance, e.g: datasub.roles.market1.apps.bigco.iam.ewc

The DID address for the EWAI_EWC_PRIVATE_KEY you specify for this marketplace must have this verified role in their DDO (DID Document). This must be setup in EW-Switchboard prior to starting EWAI.