View on GitHub

Whiteflag API

Reference implementation of the Whiteflag protocol as a web API in Node.js to connect applications with the underlying blockchains

Whiteflag API Configuration

Environment variables

The following optional environment variables may be used, e.g. when using different configurations in development environments or when running the API in a container:

Configuration files

The API is configured with four configuration files in the config/ directory. An alternative directory for the configuration files may be set with the WFCONFDIR environment variable.

Config file Purpose
api.toml General API configuration parameters
blockchains.toml Blockchain specific configuration parameters
datastores.toml Datastore specific configuration parameters
whiteflag.toml Protocol specific configuration parameters

The configuration files are formatted in TOML.

General API configuration

This configuration file provides global configuration parameters for the api.

The [logger] section parameters are:

The following [server] section parameters may be defined:

In the [authorization] section, basic http authorization can be enabled by setting a username and password. Levae empty to disable basic auth. Please do note that the API is not designed to be directly exposed externally.

The following [ssl] parameters are required if the API server protocol is https:

The following http(s) security options can be set in the [http] section:

The [socket] section options control the web socket on which incoming messages are emitted:

The operationId parameters in the [endpoints] section are booleans that allow to enable or disable specific API operations. See the API documentation for a description of all operations. Note that the receiveMessage operationId only controls the injection of messages through the REST API, and has nothing to do with receiving messages directly from a blockchain.

Whiteflag protocol configuration

This configuration file contains Whiteflag protocol related configuration parameters.

The [state] section parameters control the storage of the Whiteflag state:

The [tx] section contains message transmit behaviour parameters:

The [rx] message contains message receiving behaviour parameters:

The [authentication] section controls the behaviour for all authentication methods

The behaviour parameters for authentication method 1 are in the [authentication.1] section:

Encryption paramaters for encryption method X are in the [encryption.X] section:

Blockchain configuration

The blockchains configuration file contains both general and specific blockchain configuration parameters. The ./lib/blockchains/static/blockchains.config.schema.json contains a validation schema for the blockchain configuration.

The [confirmation] section contains the following parameters that affect all blockchains:

Furthermore, the configuration file defines which blockchains are supported, and the specific parameters for each supported blockchain. Multiple blockchains with their configurations may be defined with multiple [[blockchains]] sections.

At a minumum, the following parameters must be defined for each blockchain in the repsective [[blockchains]] section:

Additional blockchain specific parameters may be required by the specific blockchain module, such as connection details to a full node.

Datastores configuration

This datastores configuration file allows to define which datastores should be used to store data. Multiple stores may be defined with multiple [[databases]] sections. At a minumum, the following parameters must be defined for each datastore as detailed in ./lib/datastores/static/datastores.config.schema.json. Additional parameters may be added depending on the database.