diff --git a/.github/workflows/nodejs.ubuntu.test.yaml b/.github/workflows/nodejs.ubuntu.test.yaml index a27bd04..b962aa0 100644 --- a/.github/workflows/nodejs.ubuntu.test.yaml +++ b/.github/workflows/nodejs.ubuntu.test.yaml @@ -10,7 +10,7 @@ jobs: strategy: matrix: os: [ubuntu-22.04, ubuntu-latest] - node-version: [20, 22, 24, 25] + node-version: [22, 24, 25] steps: - uses: actions/checkout@v2 - name: Setup Node.js ${{ matrix.node-version }} diff --git a/.github/workflows/nodejs.windows.test.yaml b/.github/workflows/nodejs.windows.test.yaml index 13d3114..f7170a8 100644 --- a/.github/workflows/nodejs.windows.test.yaml +++ b/.github/workflows/nodejs.windows.test.yaml @@ -10,7 +10,7 @@ jobs: strategy: matrix: os: [windows-latest] - node-version: [20.x, 22.x, 24.x, 25.x] + node-version: [22.x, 24.x, 25.x] steps: - uses: actions/checkout@v2 - name: Setup Node.js ${{ matrix.node-version }} diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f0f8a01..f7abfef 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -13,24 +13,25 @@ Please report bugs and file requests by creating an issue in the [GitHub reposit [NPM](https://www.npmjs.com/) is used to manage the code and all external library packages. This is done with the [`package.json`](https://docs.npmjs.com/getting-started/using-a-package.json) file in the project root. The main program file is `main.js` in the -project root. The file `index.js` is reserved for later addition when creating -an NPM package exposing Whiteflag functions to be integrated in larger -Node.js projects. +project root. -All other files are organised in the directory structure shown +All other files are organized in the directory structure shown in the following table. -| Directory | Purpose | -|-----------------|----------------------------------------------| -|`config/` | Configuration files; must be [TOML](https://github.com/toml-lang/toml) formatted | -|`etc/` | OS-specific configuration files | -|`docs/` | Documentation; must be [markdown](https://en.wikipedia.org/wiki/Markdown) formatted | -|`lib/` | Source code modules | -|`static/` | Static content, such as json schemas | -|`test/` | Scripts for automated testing | - -The project is not yet organised as an npm module to be used as a library -for integration with other projects. +| Directory | Purpose | +|-----------|-------------------------------------------------------------------------------------| +| `config/` | Configuration files; must be [TOML](https://github.com/toml-lang/toml) formatted | +| `etc/` | OS-specific configuration files | +| `docs/` | Documentation; must be [markdown](https://en.wikipedia.org/wiki/Markdown) formatted | +| `lib/` | Source code modules | +| `static/` | Static content, such as JSON schemas | +| `test/` | Scripts for automated testing | + +Starting from version 1.3.0, the API will be gradually refactored. All +protocol functionality will be transferred to the [Whiteflag JavaScript Library (WFJSL)](https://js.whiteflagprotocol.org/), +which will become the new reference implementation. The WFJSL is available as +an [NPM package](https://www.npmjs.com/package/@whiteflagprotocol/main) +and will be added to this project as a dependency. ## Versioning @@ -38,7 +39,7 @@ for integration with other projects. For available versions, see the [version tags](https://github.com/WhiteflagProtocol/whiteflag-api/tags) on this repository. -Versions in development use `-dev` as pre-release identifier, +Versions in development use `-dev` as pre-release identifier, e.g. `1.2.4-dev` indicates that this is a "work in progress" snapshot from a development branch in between versions 1.2.3 and 1.2.4. Multiple pre-release identifiers may be used way, e.g. `1.0.0-alpha.3-dev`. @@ -57,11 +58,11 @@ There are two main branches with infinite lifetime: In addition, a number of support branches with the following naming conventions may be used: -* `patch-` is a branch from `master` in which problems and bugs +* `patch/` is a branch from `master` in which problems and bugs are fixed and then pulled into `master` for a bugfix release (with the `` being `1.0.z` for example); a hotfix should also be merged into `develop`. -* `release-` is a branch from `develop` used, as required, for +* `rel/` is a branch from `develop` used, as required, for integration and testing of a specific major or minor release (with the `` being `x.y.0`); upon completion the release is pulled into `master` and should also be merged into `develop`. @@ -100,12 +101,12 @@ npm run count-all ### Main Style Guide -The Whiteflag API project is written for NodeJS using +The Whiteflag API project is written for Node.js using [JavaScript Standard Style](https://standardjs.com/), with the exceptions and additional coding guidance below. The `.eslintrc.json` file contains the style rules for usage with -[ESLInt](https://eslint.org/). +[ESLint](https://eslint.org/). Modules, classes and functions must be documented in code using [JSDoc](http://usejsdoc.org/). A comment starting with a `/**` sequence is a JSDoc comment. Non-JSDoc comments @@ -130,13 +131,13 @@ The project style has the following deviations from StandardJS: 2. Declarations: use `const` and `let` for constants and variables; do not use `var` 3. Variable naming: - * capitalise primitive constants: `const BINENCODING = 'hex';` + * capitalize primitive constants: `const BINENCODING = 'hex';` * use camelCase, e.g. `wfMessage`, except for classes * use an underscore prefix to indicate module scoped variables, e.g. `let _config = {}` 4. Variable checks in order of preference: * use default parameter syntax in function definitions where possible - * use a conditional expression, e.g `query = wfMessage.MetaHeader || {}` + * use a conditional expression, e.g. `query = wfMessage.MetaHeader || {}` * use an `if` statement with coercion: `if (!query) return callback(err);` 5. Use literal syntax for array and object creation: `let log = {};` @@ -148,7 +149,7 @@ The project style has the following deviations from StandardJS: 9. Use template strings instead of concatenation 10. Use asynchronous code (callbacks or promises) to process results: * Functions exposed by a module MUST be asynchronous, except: - * Functions in so called common project modules + * Functions in so-called common project modules (i.e. either in a directory `_common/` or a single module `common.js`) MAY be synchronous and MAY ONLY require other common project modules * Private functions inside a module may be synchronous @@ -157,7 +158,7 @@ The project style has the following deviations from StandardJS: 12. Do not use `console.log`, but use the functions from the `logger.js` module 13. It is better to use multiple lines if a line is longer than 100 characters: * except for strings: do not break strings - * put logical and concatination operators at the beginning of a new line + * put logical and concatenation operators at the beginning of a new line 14. Comment your code, but avoid commenting the obvious: * modules, classes, and functions must be described using JSDoc * use an empty line before a comment, diff --git a/README.md b/README.md index ea37095..9c4311a 100644 --- a/README.md +++ b/README.md @@ -29,15 +29,21 @@ two methods are used: The current version is based on **v1-draft.6** of the Whiteflag protocol. The supported Whiteflag protocol features are described in `SCOPE.md`. -Note that the Whiteflag API is a so called Minimum Viable Product (MVP). -This means that it only supports the core features of the Whiteflag protocol -and nothing more. As such, it serves as the reference implementation of the -Whiteflag protocol, but it is not designed and tested for secure usage +Note that the Whiteflag API is a so-called Minimum Viable Product (MVP). +This means that it only supports the development and testing of the +Whiteflag protocol. It currently still serves as the reference implementation +of the protocol, but it is not designed and tested for secure usage and performance in a production environment. +Starting from version 1.3.0, the API will be gradually refactored. All +protocol functionality will be transferred to the [Whiteflag JavaScript Library (WFJSL)](https://js.whiteflagprotocol.org/), +which will become the new reference implementation. The WFJSL is available as +an [NPM package](https://www.npmjs.com/package/@whiteflagprotocol/main) +and will be added to this project as a dependency. + ## Documentation -More detailed documentation of the API is available at [Github Pages](https://whiteflagprotocol.github.io/whiteflag-api/) +More detailed documentation of the API is available at [GitHub Pages](https://whiteflagprotocol.github.io/whiteflag-api/) This documentation is also found in the markdown files in the `docs/` directory. When the API is running, the server will also provide the OpenAPI @@ -53,7 +59,7 @@ under the [Creative Commons CC0-1.0 Universal Public Domain Dedication](http://c statement. See `LICENSE.md` for details. The Whiteflag API software requires third party software packages, which are -not part of this distribution and may be licenced differently. +not part of this distribution and may be licensed differently. ## Installation @@ -67,7 +73,7 @@ is installed: Since version 1.0.1, the Whiteflag API has a lightweight embedded datastore, making MongoDB an optional dependency: -* [MongoDB](https://www.mongodb.com/what-is-mongodb), currently only fullt tested with legacy [verson 3.6](https://www.mongodb.com/evolved#mdbthreesix), but higher versions seem to work as well +* [MongoDB](https://www.mongodb.com/what-is-mongodb), currently only fully tested with legacy [version 3.6](https://www.mongodb.com/evolved#mdbthreesix), but higher versions seem to work as well ### Deployment and Testing @@ -120,8 +126,8 @@ wfapi Using the `npm start` command in the deployment directory will also work. Alternatively, a service may be created. An example `whiteflag-api.service` -for linux systems using `systemctl` cound be found in `etc/`. Enable the -and start the service with: +for Linux systems using `systemctl` can be found in `etc/`. Enable and start +the service with: ```shell sudo systemctl enable ./etc/whiteflag-api.service @@ -131,39 +137,69 @@ sudo service whiteflag-api start ## API Functionality The detailed [OpenAPI](https://swagger.io/specification/) definition can be -found in `static/openapi.json`. The API definition is provided in human -readible format at the root endpoint by the running API; just go to +found in `static/openapi.json`. The API definition is provided in +human-readable format at the root endpoint by the running API; just go to `http://localhost:5746/` with a browser. -Some of the endpoint functionalities -(see the API defintion for all details): +The API has two sorts of operations: on collections and on singletons. +An operation on a collection shows or changes the current state. For example, +a GET request to `/orginators` provides the currently known originators, +and a POST request to `/tokens` stores a token that will be used for +authentication. + +An operation on a singleton returns a result for the provided input data, but +does not change anything in the current state. For example, providing an +encoded message to `/message/decode` returns a decoded message, but does +not store or alter anything in the state. + +A general overview of the endpoints since version 1.2.0 +(see the API definition for all details): + +### Collections -### Messages +#### Message resource operations -* `/messages`: endpoint to GET an array of all messages contained in the API database -* `/messages/send`: endpoint to POST a new Whiteflag message to be transmitted on the blockchain -* `/messages/send`: endpoint to POST a new Whiteflag as if received the blockchain -* `/messages/encode`: endpoint to POST a Whiteflag message to be encoded -* `/messages/decode`: endpoint to POST a Whiteflag message to be decoded -* `/messages/validate`: endpoint to POST a Whiteflag message to be checked for valid format and reference -* `/messages?transactionHash=`: endpoint to GET a specific message by its transaction hash +* `/messages`: endpoint to GET all messages contained in the API database, or perform a query +* `/messages`: endpoint to POST a new Whiteflag message to be transmitted on the blockchain +* `/messages/{transactionHash}`: endpoint to GET or PUT a specific Whiteflag message in the API database -### Blockchains +#### Blockchain resource operations * `/blockchains`: endpoint to GET the current configuration and state of all blockchains * `/blockchains/{blockchain}`: endpoint to GET the configuration and state of the specified blockchain +* `/blockchains/{blockchain}/scan?from={block}&to={block}`: endpoint to GET messages from a range of blocks + +#### Account resource operations + * `/blockchains/{blockchain}/accounts`: endpoint to GET account details or POST a new blockchain account * `/blockchains/{blockchain}/accounts/{address}` endpoint to PATCH or DELETE to update or remove the specified blockchain account * `/blockchains/{blockchain}/accounts/{address}/sign`: endpoint to POST a payload to be signed as a Whiteflag authentication signature * `/blockchains/{blockchain}/accounts/{address}/transfer`: endpoint to POST a transaction to transfer value to another account -* `/blockchains/{blockchain}/scan?from={block}&to={block}`: endpoint to GET messages from a range of blocks -### Originators +#### Originator resource operations -* `/originators`: endpoint to GET the currently known originators +* `/originators`: endpoint to GET all currently known originators * `/originators/{address}`: endpoint to GET details of the specified originator -### Signature operations +#### Token resource operations + +* `/tokens`: endpoint to GET all pre-shared authentication tokens +* `/tokens`: endpoint to POST a pre-shared authentication token +* `/tokens/{tokenId}`: endpoint to GET or DELETE a pre-shared authentication token + +### Singletons + +#### Message operations + +* `/message/encode`: endpoint to POST a Whiteflag message to be encoded +* `/message/decode`: endpoint to POST a Whiteflag message to be decoded +* `/message/validate`: endpoint to POST a Whiteflag message to be checked for valid format and reference + +#### Tokens operations + +* `/token/verify`: endpoint to POST a pre-shared authentication token to generate verification data + +#### Signature operations * `/signature/decode`: endpoint to POST a Whiteflag authentication signature to be decoded * `/signature/validate`: endpoint to POST a Whiteflag authentication signature to be validated @@ -183,7 +219,7 @@ can be used for manual testing. This is a simple example using cURL from the command line, sending an `A1` message from a file: ```shell -curl http://localhost:5746/messages/send -X POST -H "Content-Type:application/json" -d @A1.message.json +curl http://localhost:5746/messages -X POST -H "Content-Type:application/json" -d @A1.message.json ``` The API also exposes a webpage with an embedded client side socket listener diff --git a/SCOPE.md b/SCOPE.md index d4a7b5f..94b00f4 100644 --- a/SCOPE.md +++ b/SCOPE.md @@ -4,11 +4,17 @@ This Whiteflag Application Programming Interface (API) is a [Node.js](https://no software implementation of the API layer that provides an interface with the Whiteflag messaging network on one or more underlying blockchains. -This Whiteflag API is a so called Minumum Viable Product (MVP). This means +This Whiteflag API is a so-called Minimum Viable Product (MVP), meaning that it only supports the core features of the Whiteflag protocol and nothing more. The features that are considered in scope for this MVP API are described below. +Starting from version 1.3.0, the API will be gradually refactored. All +protocol functionality will be transferred to the [Whiteflag JavaScript Library (WFJSL)](https://js.whiteflagprotocol.org/), +which will become the new reference implementation. The WFJSL is available as +an [NPM package](https://www.npmjs.com/package/@whiteflagprotocol/main) +and will be added to this project as a dependency. + ## In scope ### Message handling @@ -24,12 +30,12 @@ The API should provide all message handling i.a.w. the standard: ### Blockchains -The API should demonstrate blockchain agnosticy of the protocol by -interfacing with the following blockchains: +The API should demonstrate that the protocol is blockchain agnostic by +using multiple different blockchains: -* ethereum (v0.8) -* bitcoin (v1.0) -* fennel/polkadot (v1.1) +* Ethereum (v0.8) +* Bitcoin (v1.0) +* Fennel/Polkadot (v1.1) The API is able to read Whiteflag history from the blockchain into database. @@ -51,7 +57,7 @@ Advanced protocol features: * Whiteflag authentication method 2 (token-based) (v1.0) - issue #3 * manage encryption keys for different originators: * pre-shared encryption keys (v0.9) - * ECDH negotated encryption keys (v0.9) + * ECDH negotiated encryption keys (v0.9) ### API functions @@ -79,5 +85,5 @@ The following Whiteflag protocol features are not implemented: The API is not capable of: -* usage of the api by multiple users/originators +* usage of the API by multiple users/originators * advanced queries & filtering diff --git a/docs/index.md b/docs/index.md index 53ecfb8..0656b5a 100644 --- a/docs/index.md +++ b/docs/index.md @@ -43,6 +43,6 @@ The Whiteflag Protocol and API specifications are also available at * [JavaScript Modules](md/modules.md) * [Logging](md/logging.md) -* [Events](md/events.md) +* [Events Handling](md/events.md) * [Error Handling](md/errors.md) * [Static Components](md/static.md) diff --git a/docs/jsdoc/blockchains.js.html b/docs/jsdoc/blockchains.js.html index c07443c..a48ce23 100644 --- a/docs/jsdoc/blockchains.js.html +++ b/docs/jsdoc/blockchains.js.html @@ -138,7 +138,7 @@

Source: blockchains.js

/** * @callback bcInitCb * @param {Error} err any error - * @param {string} blockchain the nemae of the blockchain + * @param {string} blockchain the name of the blockchain */ bcInstance._module.init(bcInstance, function bcInitCb(err, blockchain) { if (err) return log.error(MODULELOG, `Could not intialise ${blockchain}: ${err.message}`); @@ -810,13 +810,13 @@

Source: blockchains.js


- Documentation generated by JSDoc 4.0.5 on Wed Oct 22 2025 21:45:24 GMT+0200 (Central European Summer Time) + Documentation generated by JSDoc 4.0.5 on Sat Jan 03 2026 10:48:28 GMT+0100 (Central European Standard Time)
diff --git a/docs/jsdoc/blockchains_bitcoin.js.html b/docs/jsdoc/blockchains_bitcoin.js.html index dca7fbb..a632a85 100644 --- a/docs/jsdoc/blockchains_bitcoin.js.html +++ b/docs/jsdoc/blockchains_bitcoin.js.html @@ -357,13 +357,13 @@

Source: blockchains/bitcoin.js


- Documentation generated by JSDoc 4.0.5 on Wed Oct 22 2025 21:45:24 GMT+0200 (Central European Summer Time) + Documentation generated by JSDoc 4.0.5 on Sat Jan 03 2026 10:48:28 GMT+0100 (Central European Standard Time)
diff --git a/docs/jsdoc/blockchains_bitcoin_accounts.js.html b/docs/jsdoc/blockchains_bitcoin_accounts.js.html index 213b5d6..4304e19 100644 --- a/docs/jsdoc/blockchains_bitcoin_accounts.js.html +++ b/docs/jsdoc/blockchains_bitcoin_accounts.js.html @@ -74,7 +74,7 @@

Source: blockchains/bitcoin/accounts.js

const MODULELOG = 'bitcoin'; const DEFAULTSCRIPT = 'p2pkh' const SYNCTIMER = 10000; -const SYNCDELAY = 600000; +const SYNCDELAY = 120000; const SATOSHI = 100000000; const INITBLOCKHEIGHT = 900000; const HEXENCODING = 'hex'; @@ -667,13 +667,13 @@

Source: blockchains/bitcoin/accounts.js


- Documentation generated by JSDoc 4.0.5 on Wed Oct 22 2025 21:45:24 GMT+0200 (Central European Summer Time) + Documentation generated by JSDoc 4.0.5 on Sat Jan 03 2026 10:48:28 GMT+0100 (Central European Standard Time)
diff --git a/docs/jsdoc/blockchains_bitcoin_listener.js.html b/docs/jsdoc/blockchains_bitcoin_listener.js.html index 9c482c9..34fa630 100644 --- a/docs/jsdoc/blockchains_bitcoin_listener.js.html +++ b/docs/jsdoc/blockchains_bitcoin_listener.js.html @@ -414,13 +414,13 @@

Source: blockchains/bitcoin/listener.js


- Documentation generated by JSDoc 4.0.5 on Wed Oct 22 2025 21:45:24 GMT+0200 (Central European Summer Time) + Documentation generated by JSDoc 4.0.5 on Sat Jan 03 2026 10:48:28 GMT+0100 (Central European Standard Time)
diff --git a/docs/jsdoc/blockchains_bitcoin_rpc.js.html b/docs/jsdoc/blockchains_bitcoin_rpc.js.html index 194fd54..6b10533 100644 --- a/docs/jsdoc/blockchains_bitcoin_rpc.js.html +++ b/docs/jsdoc/blockchains_bitcoin_rpc.js.html @@ -48,6 +48,7 @@

Source: blockchains/bitcoin/rpc.js

/* Common internal functions and classes */ const log = require('../../_common/logger'); const { ProcessingError } = require('../../_common/errors'); +const { retryPromise } = require('../../_common/processing'); /* Whiteflag modules */ const wfState = require('../../protocol/state'); @@ -59,7 +60,8 @@

Source: blockchains/bitcoin/rpc.js

/* Module constants */ const MODULELOG = 'bitcoin'; const DEFAULTPORT = '8332'; -const STATUSINTERVAL = 1200000; // Every two minutes +const CONNECTRETRIES = 5; +const STATUSINTERVAL = 120000; // Every two minutes const INFOINTERVAL = 3600000; // Every hour /* Module variables */ @@ -100,7 +102,7 @@

Source: blockchains/bitcoin/rpc.js

log.trace(MODULELOG, `Setting up connection with ${_btcChain} node: ${rpcCleanURL}`); _rpcInit = true; return new Promise((resolve, reject) => { - getBlockChainInfo() + retryPromise(getBlockChainInfo(), CONNECTRETRIES, STATUSINTERVAL) .then(btcInfo => { // Check for correct chain configuration const chain = btcInfo.chain; @@ -124,7 +126,7 @@

Source: blockchains/bitcoin/rpc.js

}) .catch(err => { _rpcInit = false; - reject(new Error(`Could not connect to ${_btcChain} node: ${err.message}`), _btcChain) + reject(new Error(`Could not connect to ${_btcChain} node after ${CONNECTRETRIES} retires: ${err.message}`), _btcChain) }); }); } @@ -297,13 +299,13 @@

Source: blockchains/bitcoin/rpc.js


- Documentation generated by JSDoc 4.0.5 on Wed Oct 22 2025 21:45:24 GMT+0200 (Central European Summer Time) + Documentation generated by JSDoc 4.0.5 on Sat Jan 03 2026 10:48:28 GMT+0100 (Central European Standard Time)
diff --git a/docs/jsdoc/blockchains_bitcoin_transactions.js.html b/docs/jsdoc/blockchains_bitcoin_transactions.js.html index b3800be..b41ef61 100644 --- a/docs/jsdoc/blockchains_bitcoin_transactions.js.html +++ b/docs/jsdoc/blockchains_bitcoin_transactions.js.html @@ -378,13 +378,13 @@

Source: blockchains/bitcoin/transactions.js


- Documentation generated by JSDoc 4.0.5 on Wed Oct 22 2025 21:45:24 GMT+0200 (Central European Summer Time) + Documentation generated by JSDoc 4.0.5 on Sat Jan 03 2026 10:48:28 GMT+0100 (Central European Standard Time)
diff --git a/docs/jsdoc/blockchains_ethereum.js.html b/docs/jsdoc/blockchains_ethereum.js.html index b858aa2..64dce27 100644 --- a/docs/jsdoc/blockchains_ethereum.js.html +++ b/docs/jsdoc/blockchains_ethereum.js.html @@ -88,6 +88,7 @@

Source: blockchains/ethereum.js

let _ethState = {}; let _ethApi; let _transactionValue = '0'; +let _accountScheduleId; /** * Initialises the Ethereum blockchain @@ -112,7 +113,10 @@

Source: blockchains/ethereum.js

// Initialise sub-modules ethAccounts.init(ethConfig, _ethState) - .then(() => ethRpc.init(ethConfig, _ethState)) + .then((accountScheduleId) => { + _accountScheduleId = accountScheduleId; + ethRpc.init(ethConfig, _ethState) + }) .then(ethApi => { _ethApi = ethApi }) .then(() => ethTransactions.init(ethConfig, _ethState, _ethApi)) .then(() => ethListener.init(ethConfig, _ethState)) @@ -120,7 +124,10 @@

Source: blockchains/ethereum.js

wfState.updateBlockchainData(_ethChain, _ethState); return callback(null, _ethChain); }) - .catch(err => callback(err, _ethChain)); + .catch(err => { + clearInterval(_accountScheduleId); + return callback(err, _ethChain) + }); }); } @@ -349,13 +356,13 @@

Source: blockchains/ethereum.js


- Documentation generated by JSDoc 4.0.5 on Wed Oct 22 2025 21:45:24 GMT+0200 (Central European Summer Time) + Documentation generated by JSDoc 4.0.5 on Sat Jan 03 2026 10:48:28 GMT+0100 (Central European Standard Time)
diff --git a/docs/jsdoc/blockchains_ethereum_accounts.js.html b/docs/jsdoc/blockchains_ethereum_accounts.js.html index 2db9386..9f66a14 100644 --- a/docs/jsdoc/blockchains_ethereum_accounts.js.html +++ b/docs/jsdoc/blockchains_ethereum_accounts.js.html @@ -101,10 +101,7 @@

Source: blockchains/ethereum/accounts.js

.catch(err => log.warn(MODULELOG, err.message)); } // Periodically update account balances - scheduleAccountsUpdate(); - - // Succesfully completed initialisation - return Promise.resolve(); + return scheduleAccountsUpdate(); } /** @@ -256,6 +253,7 @@

Source: blockchains/ethereum/accounts.js

function scheduleAccountsUpdate() { if (_accountScheduleId) clearInterval(_accountScheduleId); _accountScheduleId = setInterval(updateAccounts, STATUSINTERVAL); + return _accountScheduleId; } @@ -362,13 +360,13 @@

Source: blockchains/ethereum/accounts.js


- Documentation generated by JSDoc 4.0.5 on Wed Oct 22 2025 21:45:24 GMT+0200 (Central European Summer Time) + Documentation generated by JSDoc 4.0.5 on Sat Jan 03 2026 10:48:28 GMT+0100 (Central European Standard Time)
diff --git a/docs/jsdoc/blockchains_ethereum_listener.js.html b/docs/jsdoc/blockchains_ethereum_listener.js.html index 34f9e94..581f709 100644 --- a/docs/jsdoc/blockchains_ethereum_listener.js.html +++ b/docs/jsdoc/blockchains_ethereum_listener.js.html @@ -420,13 +420,13 @@

Source: blockchains/ethereum/listener.js


- Documentation generated by JSDoc 4.0.5 on Wed Oct 22 2025 21:45:24 GMT+0200 (Central European Summer Time) + Documentation generated by JSDoc 4.0.5 on Sat Jan 03 2026 10:48:28 GMT+0100 (Central European Standard Time)
diff --git a/docs/jsdoc/blockchains_ethereum_rpc.js.html b/docs/jsdoc/blockchains_ethereum_rpc.js.html index 5ce0271..7f2f46d 100644 --- a/docs/jsdoc/blockchains_ethereum_rpc.js.html +++ b/docs/jsdoc/blockchains_ethereum_rpc.js.html @@ -56,8 +56,9 @@

Source: blockchains/ethereum/rpc.js

/* Common internal functions and classes */ const log = require('../../_common/logger'); const { ProcessingError } = require('../../_common/errors'); -const { timeoutPromise } = require('../../_common/processing'); const { withHexPrefix } = require('../../_common/format'); +const { timeoutPromise, + retryPromise } = require('../../_common/processing'); /* Whiteflag modules */ const wfState = require('../../protocol/state'); @@ -68,6 +69,7 @@

Source: blockchains/ethereum/rpc.js

/* Module constants */ const MODULELOG = 'ethereum'; const DEFAULTPORT = '8545'; +const CONNECTRETRIES = 5; const STATUSINTERVAL = 60000; // Every minute const INFOINTERVAL = 3600000; // Every hour @@ -107,7 +109,7 @@

Source: blockchains/ethereum/rpc.js

log.trace(MODULELOG, `Setting up connection with ${_ethChain} node: ${rpcCleanURL}`); return new Promise((resolve, reject) => { // Check Ethereum chain identifier - getChainId() + retryPromise(getChainId(), CONNECTRETRIES, STATUSINTERVAL) .then(chainID => { // Check for correct chain configuration if (Object.hasOwn(ethConfig, 'chainID')) _chainID = ethConfig.chainID; @@ -125,7 +127,7 @@

Source: blockchains/ethereum/rpc.js

// Succesfully completed initialisation return resolve(_ethApi); }) - .catch(err => reject(new Error(`Could not connect to ${_ethChain} node: ${err.message}`), _ethChain)); + .catch(err => reject(new Error(`Could not connect to ${_ethChain} node after ${CONNECTRETRIES} retries: ${err.message}`), _ethChain)); }); } @@ -374,13 +376,13 @@

Source: blockchains/ethereum/rpc.js


- Documentation generated by JSDoc 4.0.5 on Wed Oct 22 2025 21:45:24 GMT+0200 (Central European Summer Time) + Documentation generated by JSDoc 4.0.5 on Sat Jan 03 2026 10:48:28 GMT+0100 (Central European Standard Time)
diff --git a/docs/jsdoc/blockchains_ethereum_transactions.js.html b/docs/jsdoc/blockchains_ethereum_transactions.js.html index daf7cd6..e6aa542 100644 --- a/docs/jsdoc/blockchains_ethereum_transactions.js.html +++ b/docs/jsdoc/blockchains_ethereum_transactions.js.html @@ -260,13 +260,13 @@

Source: blockchains/ethereum/transactions.js


- Documentation generated by JSDoc 4.0.5 on Wed Oct 22 2025 21:45:24 GMT+0200 (Central European Summer Time) + Documentation generated by JSDoc 4.0.5 on Sat Jan 03 2026 10:48:28 GMT+0100 (Central European Standard Time)
diff --git a/docs/jsdoc/blockchains_fennel.js.html b/docs/jsdoc/blockchains_fennel.js.html index a9d085a..b7fa08d 100644 --- a/docs/jsdoc/blockchains_fennel.js.html +++ b/docs/jsdoc/blockchains_fennel.js.html @@ -80,6 +80,7 @@

Source: blockchains/fennel.js

/* Module variables */ let _fnlChain; let _fnlState = {}; +let _accountScheduleId; /* MAIN MODULE FUNCTIONS */ /** @@ -104,7 +105,10 @@

Source: blockchains/fennel.js

// Initialise sub-modules fnlAccounts.init(fnConfig, _fnlState) - .then(() => fnlRpc.init(fnConfig, _fnlState)) + .then((accountScheduleId) => { + _accountScheduleId = accountScheduleId; + return fnlRpc.init(fnConfig, _fnlState) + }) .then((fnlAPI) => { if (fnlAPI) log.info(MODULELOG, `Using ${fnlAPI.libraryInfo}`); return fnlListener.init(fnConfig, _fnlState, fnlAPI) @@ -114,7 +118,10 @@

Source: blockchains/fennel.js

wfState.updateBlockchainData(_fnlChain, _fnlState); return callback(null, _fnlChain); }) - .catch((err) => callback(err, _fnlChain)); + .catch((err) => { + clearInterval(_accountScheduleId); + return callback(err, _fnlChain); + }); }); } @@ -329,13 +336,13 @@

Source: blockchains/fennel.js


- Documentation generated by JSDoc 4.0.5 on Wed Oct 22 2025 21:45:24 GMT+0200 (Central European Summer Time) + Documentation generated by JSDoc 4.0.5 on Sat Jan 03 2026 10:48:28 GMT+0100 (Central European Standard Time)
diff --git a/docs/jsdoc/blockchains_fennel_accounts.js.html b/docs/jsdoc/blockchains_fennel_accounts.js.html index 0a9fe74..ff5bfe7 100644 --- a/docs/jsdoc/blockchains_fennel_accounts.js.html +++ b/docs/jsdoc/blockchains_fennel_accounts.js.html @@ -114,10 +114,7 @@

Source: blockchains/fennel/accounts.js

.catch(err => log.warn(MODULELOG, err.message)); } // Periodically update account balances - scheduleAccountsUpdate(); - - // Succesfully completed initialisation - return Promise.resolve(); + return scheduleAccountsUpdate(); } /** @@ -419,6 +416,7 @@

Source: blockchains/fennel/accounts.js

function scheduleAccountsUpdate() { if (_accountScheduleId) clearInterval(_accountScheduleId); _accountScheduleId = setInterval(updateAccounts, STATUSINTERVAL); + return _accountScheduleId; } /** @@ -549,13 +547,13 @@

Source: blockchains/fennel/accounts.js


- Documentation generated by JSDoc 4.0.5 on Wed Oct 22 2025 21:45:24 GMT+0200 (Central European Summer Time) + Documentation generated by JSDoc 4.0.5 on Sat Jan 03 2026 10:48:28 GMT+0100 (Central European Standard Time)
diff --git a/docs/jsdoc/blockchains_fennel_listener.js.html b/docs/jsdoc/blockchains_fennel_listener.js.html index 42abd93..f04b262 100644 --- a/docs/jsdoc/blockchains_fennel_listener.js.html +++ b/docs/jsdoc/blockchains_fennel_listener.js.html @@ -440,13 +440,13 @@

Source: blockchains/fennel/listener.js


- Documentation generated by JSDoc 4.0.5 on Wed Oct 22 2025 21:45:24 GMT+0200 (Central European Summer Time) + Documentation generated by JSDoc 4.0.5 on Sat Jan 03 2026 10:48:28 GMT+0100 (Central European Standard Time)
diff --git a/docs/jsdoc/blockchains_fennel_rpc.js.html b/docs/jsdoc/blockchains_fennel_rpc.js.html index c028a82..8dcd044 100644 --- a/docs/jsdoc/blockchains_fennel_rpc.js.html +++ b/docs/jsdoc/blockchains_fennel_rpc.js.html @@ -66,7 +66,8 @@

Source: blockchains/fennel/rpc.js

const log = require('../../_common/logger'); const { ignore } = require('../../_common/processing') const { ProcessingError } = require('../../_common/errors'); -const { timeoutPromise } = require('../../_common/processing'); +const { timeoutPromise, + retryPromise } = require('../../_common/processing'); /* Whiteflag modules */ const wfState = require('../../protocol/state'); @@ -78,6 +79,7 @@

Source: blockchains/fennel/rpc.js

/* Module constants */ const MODULELOG = 'fennel'; const DEFAULTPORT = '8844'; +const CONNECTRETRIES = 5; const TOKENPRECISION = 1e12; const STATUSINTERVAL = 60000; // Every minute const INFOINTERVAL = 3600000; // Every hour @@ -126,7 +128,10 @@

Source: blockchains/fennel/rpc.js

case 'wss': { log.trace(MODULELOG, `Setting up web socket connection with ${_fnlChain} node: ${rpcCleanURL}`); const wsProvider = new WsProvider(_rpcAuthURL); - timeoutPromise(ApiPromise.create({ provider: wsProvider }), _rpcTimeout) + retryPromise(timeoutPromise( + ApiPromise.create({ provider: wsProvider }), + _rpcTimeout + ), CONNECTRETRIES, STATUSINTERVAL) .then(api => { _fnlApi = api; log.info(MODULELOG, `Connected to ${_fnlApi.runtimeVersion.specName} through ${_fnlChain} node: ${rpcCleanURL}`); @@ -141,7 +146,7 @@

Source: blockchains/fennel/rpc.js

.catch(err => { _rpcInit = false; wsProvider.disconnect(); - return reject(new Error(`Could not make a web socket connection with ${_fnlChain} node: ${err.message}`), _fnlChain); + return reject(new Error(`Could not make a web socket connection with ${_fnlChain} node after ${CONNECTRETRIES} retries: ${err.message}`), _fnlChain); }); break; } @@ -149,7 +154,7 @@

Source: blockchains/fennel/rpc.js

case 'http': case 'https': { log.trace(MODULELOG, `Setting up web connection with ${_fnlChain} node: ${rpcCleanURL}`); - getRuntimeVersion() + retryPromise(getRuntimeVersion(), CONNECTRETRIES, STATUSINTERVAL) .then(fnlRuntime => { log.info(MODULELOG, `Connected to ${fnlRuntime.specName} through ${_fnlChain} node: ${rpcCleanURL}`); @@ -162,7 +167,7 @@

Source: blockchains/fennel/rpc.js

}) .catch(err => { _rpcInit = false; - reject(new Error(`Could not make web connection with ${_fnlChain} node: ${err.message}`), _fnlChain)} + reject(new Error(`Could not make web connection with ${_fnlChain} node after ${CONNECTRETRIES} retries: ${err.message}`), _fnlChain)} ); break; } @@ -340,7 +345,7 @@

Source: blockchains/fennel/rpc.js

* @returns {Promise} resolves to array with node roles */ function getNodeRoles() { - // BUG: websocket does not return does not return correct value + // BUG: websocket does not return correct value // if (_fnlApi) return _fnlApi.rpc.system.nodeRoles(); return rpc('system_nodeRoles'); } @@ -623,13 +628,13 @@

Source: blockchains/fennel/rpc.js


- Documentation generated by JSDoc 4.0.5 on Wed Oct 22 2025 21:45:24 GMT+0200 (Central European Summer Time) + Documentation generated by JSDoc 4.0.5 on Sat Jan 03 2026 10:48:28 GMT+0100 (Central European Standard Time)
diff --git a/docs/jsdoc/blockchains_fennel_transactions.js.html b/docs/jsdoc/blockchains_fennel_transactions.js.html index 4eed2b3..80a8d93 100644 --- a/docs/jsdoc/blockchains_fennel_transactions.js.html +++ b/docs/jsdoc/blockchains_fennel_transactions.js.html @@ -187,13 +187,13 @@

Source: blockchains/fennel/transactions.js


- Documentation generated by JSDoc 4.0.5 on Wed Oct 22 2025 21:45:24 GMT+0200 (Central European Summer Time) + Documentation generated by JSDoc 4.0.5 on Sat Jan 03 2026 10:48:28 GMT+0100 (Central European Standard Time)
diff --git a/docs/jsdoc/config.js.html b/docs/jsdoc/config.js.html index fea230f..e6493cc 100644 --- a/docs/jsdoc/config.js.html +++ b/docs/jsdoc/config.js.html @@ -125,13 +125,13 @@

Source: config.js


- Documentation generated by JSDoc 4.0.5 on Wed Oct 22 2025 21:45:24 GMT+0200 (Central European Summer Time) + Documentation generated by JSDoc 4.0.5 on Sat Jan 03 2026 10:48:28 GMT+0100 (Central European Standard Time)
diff --git a/docs/jsdoc/datastores.js.html b/docs/jsdoc/datastores.js.html index ed3c9d9..fc55cc6 100644 --- a/docs/jsdoc/datastores.js.html +++ b/docs/jsdoc/datastores.js.html @@ -452,13 +452,13 @@

Source: datastores.js


- Documentation generated by JSDoc 4.0.5 on Wed Oct 22 2025 21:45:24 GMT+0200 (Central European Summer Time) + Documentation generated by JSDoc 4.0.5 on Sat Jan 03 2026 10:48:28 GMT+0100 (Central European Standard Time)
diff --git a/docs/jsdoc/datastores_embeddb.js.html b/docs/jsdoc/datastores_embeddb.js.html index c3c0f11..1e6900f 100644 --- a/docs/jsdoc/datastores_embeddb.js.html +++ b/docs/jsdoc/datastores_embeddb.js.html @@ -235,13 +235,13 @@

Source: datastores/embeddb.js


- Documentation generated by JSDoc 4.0.5 on Wed Oct 22 2025 21:45:24 GMT+0200 (Central European Summer Time) + Documentation generated by JSDoc 4.0.5 on Sat Jan 03 2026 10:48:28 GMT+0100 (Central European Standard Time)
diff --git a/docs/jsdoc/datastores_mongodb.js.html b/docs/jsdoc/datastores_mongodb.js.html index 422eb90..4557e29 100644 --- a/docs/jsdoc/datastores_mongodb.js.html +++ b/docs/jsdoc/datastores_mongodb.js.html @@ -246,13 +246,13 @@

Source: datastores/mongodb.js


- Documentation generated by JSDoc 4.0.5 on Wed Oct 22 2025 21:45:24 GMT+0200 (Central European Summer Time) + Documentation generated by JSDoc 4.0.5 on Sat Jan 03 2026 10:48:28 GMT+0100 (Central European Standard Time)
diff --git a/docs/jsdoc/index.html b/docs/jsdoc/index.html index af41b8f..67938ec 100644 --- a/docs/jsdoc/index.html +++ b/docs/jsdoc/index.html @@ -69,13 +69,18 @@

Introduction

The current version is based on v1-draft.6 of the Whiteflag protocol. The supported Whiteflag protocol features are described in SCOPE.md.

-

Note that the Whiteflag API is a so called Minimum Viable Product (MVP). -This means that it only supports the core features of the Whiteflag protocol -and nothing more. As such, it serves as the reference implementation of the -Whiteflag protocol, but it is not designed and tested for secure usage +

Note that the Whiteflag API is a so-called Minimum Viable Product (MVP). +This means that it only supports the development and testing of the +Whiteflag protocol. It currently still serves as the reference implementation +of the protocol, but it is not designed and tested for secure usage and performance in a production environment.

+

Starting from version 1.3.0, the API will be gradually refactored. All +protocol functionality will be transferred to the Whiteflag JavaScript Library (WFJSL), +which will become the new reference implementation. The WFJSL is available as +an NPM package +and will be added to this project as a dependency.

Documentation

-

More detailed documentation of the API is available at Github Pages

+

More detailed documentation of the API is available at GitHub Pages

This documentation is also found in the markdown files in the docs/ directory. When the API is running, the server will also provide the OpenAPI definition at the URL root (e.g. http://localhost:5746/).

@@ -86,7 +91,7 @@

License

under the Creative Commons CC0-1.0 Universal Public Domain Dedication statement. See LICENSE.md for details.

The Whiteflag API software requires third party software packages, which are -not part of this distribution and may be licenced differently.

+not part of this distribution and may be licensed differently.

Installation

Prerequisites

To deploy the Whiteflag API, make sure the following prerequisite software @@ -97,7 +102,7 @@

Prerequisites

Since version 1.0.1, the Whiteflag API has a lightweight embedded datastore, making MongoDB an optional dependency:

    -
  • MongoDB, currently only fullt tested with legacy verson 3.6, but higher versions seem to work as well
    • +
  • MongoDB, currently only fully tested with legacy version 3.6, but higher versions seem to work as well

Deployment and Testing

First, copy the repository to the deployment directory, such as @@ -135,44 +140,70 @@

Running the API

Using the npm start command in the deployment directory will also work.

Alternatively, a service may be created. An example whiteflag-api.service -for linux systems using systemctl cound be found in etc/. Enable the -and start the service with:

+for Linux systems using systemctl can be found in etc/. Enable and start +the service with:

sudo systemctl enable ./etc/whiteflag-api.service
 sudo service whiteflag-api start

API Functionality

The detailed OpenAPI definition can be -found in static/openapi.json. The API definition is provided in human -readible format at the root endpoint by the running API; just go to +found in static/openapi.json. The API definition is provided in +human-readable format at the root endpoint by the running API; just go to http://localhost:5746/ with a browser.

-

Some of the endpoint functionalities -(see the API defintion for all details):

-

Messages

+

The API has two sorts of operations: on collections and on singletons. +An operation on a collection shows or changes the current state. For example, +a GET request to /orginators provides the currently known originators, +and a POST request to /tokens stores a token that will be used for +authentication.

+

An operation on a singleton returns a result for the provided input data, but +does not change anything in the current state. For example, providing an +encoded message to /message/decode returns a decoded message, but does +not store or alter anything in the state.

+

A general overview of the endpoints since version 1.2.0 +(see the API definition for all details):

+

Collections

+

Message resource operations

    -
  • /messages: endpoint to GET an array of all messages contained in the API database
    • -
  • /messages/send: endpoint to POST a new Whiteflag message to be transmitted on the blockchain
    • -
  • /messages/send: endpoint to POST a new Whiteflag as if received the blockchain
    • -
  • /messages/encode: endpoint to POST a Whiteflag message to be encoded
    • -
  • /messages/decode: endpoint to POST a Whiteflag message to be decoded
    • -
  • /messages/validate: endpoint to POST a Whiteflag message to be checked for valid format and reference
    • -
  • /messages?transactionHash=<transaction hash>: endpoint to GET a specific message by its transaction hash
    • +
  • /messages: endpoint to GET all messages contained in the API database, or perform a query
    • +
  • /messages: endpoint to POST a new Whiteflag message to be transmitted on the blockchain
    • +
  • /messages/{transactionHash}: endpoint to GET or PUT a specific Whiteflag message in the API database
-

Blockchains

+

Blockchain resource operations

  • /blockchains: endpoint to GET the current configuration and state of all blockchains
  • /blockchains/{blockchain}: endpoint to GET the configuration and state of the specified blockchain
    • +
  • /blockchains/{blockchain}/scan?from={block}&to={block}: endpoint to GET messages from a range of blocks
    • +
+

Account resource operations

+
  • /blockchains/{blockchain}/accounts: endpoint to GET account details or POST a new blockchain account
  • /blockchains/{blockchain}/accounts/{address} endpoint to PATCH or DELETE to update or remove the specified blockchain account
  • /blockchains/{blockchain}/accounts/{address}/sign: endpoint to POST a payload to be signed as a Whiteflag authentication signature
  • /blockchains/{blockchain}/accounts/{address}/transfer: endpoint to POST a transaction to transfer value to another account
    • -
  • /blockchains/{blockchain}/scan?from={block}&to={block}: endpoint to GET messages from a range of blocks
-

Originators

+

Originator resource operations

    -
  • /originators: endpoint to GET the currently known originators
    • +
  • /originators: endpoint to GET all currently known originators
  • /originators/{address}: endpoint to GET details of the specified originator
-

Signature operations

+

Token resource operations

+
    +
  • /tokens: endpoint to GET all pre-shared authentication tokens
    • +
  • /tokens: endpoint to POST a pre-shared authentication token
    • +
  • /tokens/{tokenId}: endpoint to GET or DELETE a pre-shared authentication token
    • +
+

Singletons

+

Message operations

+
    +
  • /message/encode: endpoint to POST a Whiteflag message to be encoded
    • +
  • /message/decode: endpoint to POST a Whiteflag message to be decoded
    • +
  • /message/validate: endpoint to POST a Whiteflag message to be checked for valid format and reference
    • +
+

Tokens operations

+
    +
  • /token/verify: endpoint to POST a pre-shared authentication token to generate verification data
    • +
+

Signature operations

@@ -195,13 +197,13 @@

Guideline for errors, logging and responses


- Documentation generated by JSDoc 4.0.5 on Wed Oct 22 2025 21:45:24 GMT+0200 (Central European Summer Time) + Documentation generated by JSDoc 4.0.5 on Sat Jan 03 2026 10:48:29 GMT+0100 (Central European Standard Time)
diff --git a/docs/jsdoc/tutorial-ethereum.html b/docs/jsdoc/tutorial-ethereum.html index d627094..5b9df54 100644 --- a/docs/jsdoc/tutorial-ethereum.html +++ b/docs/jsdoc/tutorial-ethereum.html @@ -28,11 +28,12 @@

ethereum

-

Whiteflag API Connector for Ethereum

+

Connector for Ethereum

+

| WF API Documentation Home | WF API JSDoc Reference | WF API Interface | Whiteflag Specification |

+

Blockchain specifications

+

NOTE - The Ethereum module needs updating.

The Whiteflag API natively supports the Ethereum blockchain.

-

NOTE - The Ethereum module needs updating.

-

Blockchain specifications

@@ -63,7 +64,7 @@

Blockchain specifications

-

Note that curve secp256k1 for the ECDSA signature algorthm is officially not +

Note that curve secp256k1 for the ECDSA signature algorithm is officially not specified to be used with JWS for Whiteflag authentication method 1. Instead, the JWS specification in RFC 7518 requires curve secp256r1 a.k.a. prime256v1. However, Whiteflag is using @@ -76,7 +77,7 @@

Ethereum configuration

the Ethereum specific parameters in one of its [[blockchains]] sections.

  • name: the name according to the naming convention: {name}-{network}, e.g. ethereum-main or ethereum-rinkeby
    • -
  • module: the Ethereum module in lib/blockchains, which should be "ethereum"
    • +
  • module: the Ethereum module in lib/blockchains, which should be ethereum
  • chainID: the appropriate Chain ID for the Ethereum network that is used
  • active: whether the blockchain is active or should be ignored
@@ -87,7 +88,7 @@

Ethereum configuration

For retrieving transactions containing Whiteflag messages from the blockchain, these parameters may be provided, otherwise default values are used:

    -
  • blockRetrievalInterval: the time in milliseconds before the Ethereum listener tries to retireve the next block; the default is 6000 ms
    • +
  • blockRetrievalInterval: the time in milliseconds before the Ethereum listener tries to retrieve the next block; the default is 6000 ms
  • blockRetrievalStart: the starting block from where to retrieve transactions; if 0 (default) the API resumes a number of blocks before the highest block as configured below
  • blockRetrievalEnd: the last block from where to retrieve transactions; if 0 (default) the API catches up with the highest block on the node
  • blockRetrievalRestart: how many blocks before the current highest block the API should look back when (re)starting the API; this prevents that blocks are missed when the API is stopped for a short period
    • @@ -96,9 +97,9 @@

    Ethereum configuration

  • transactionValue: the value of a transaction when sending a Whiteflag message; default is 0 ether
  • traceRawTransaction: whether to show each individual transaction when the loglevel is set to 6 (trace); default is false because this results in massive logging
-

To send and receive Whiteflag messages, the API must be connected to a Ethereum -node exposing the standard Ethereum RPC interface. These parameters are used to -configure the connection:

+

To send and receive Whiteflag messages, the API must be connected to an +Ethereum node exposing the standard Ethereum RPC interface. These parameters +are used to configure the connection:

-

Specifically, this inludes:

+

Specifically, this includes:

  • authentication of originators upon reception of authentication messages
  • automatically sending ECDH public keys after an own authentication message
  • processing received ECDH public keys to compute shared secret
    • -
  • automatically sending initialisation vectors with encrypted messages
    • -
  • processing received initialisation vectors
    • +
  • automatically sending initialization vectors with encrypted messages
    • +
  • processing received initialization vectors

Authentication

The authenticity of an originator is validated with the information from @@ -157,10 +159,10 @@

Authentication

Encryption

The codec.js module always passes outgoing and incoming message to the crypto.js module for encryption and decryption. If no encryption or -decrytpion is required, i.e. when the EncryptionIndicator in the message +decryption is required, i.e. when the EncryptionIndicator in the message header is set to 0, the crypto.js just passes the message to the callback.

-

If the encyrption indicator is set to a valid value, the crypto module encrypts +

If the encryption indicator is set to a valid value, the crypto module encrypts or decrypts the message. The recipientAddress in the MetaHeader is used to determine which encryption secret is to be used as input key material:

    @@ -172,11 +174,11 @@

    Encryption

    authentication message is encrypted or sent under duress. The module also handles incoming ECDH public keys.

    The API has an endpoint to provide a pre-shared secret key for each originator. -Instead of specifing the recipient in the metaheader, the pre-shared key for +Instead of specifying the recipient in the metaheader, the pre-shared key for method 2 may also be provided with the encryptionKeyInput in the metaheader, or otherwise the default key in config/whiteflag.toml is used.

    -

    The management.js module automatically sends initialisation vectors with -encrypted messages and also manages incoming initialisation vectors.

    +

    The management.js module automatically sends initialization vectors with +encrypted messages and also manages incoming initialization vectors.

@@ -184,13 +186,13 @@

Encryption


- Documentation generated by JSDoc 4.0.5 on Wed Oct 22 2025 21:45:24 GMT+0200 (Central European Summer Time) + Documentation generated by JSDoc 4.0.5 on Sat Jan 03 2026 10:48:29 GMT+0100 (Central European Standard Time)
diff --git a/docs/jsdoc/tutorial-state.html b/docs/jsdoc/tutorial-state.html index 40249ea..8aad3a9 100644 --- a/docs/jsdoc/tutorial-state.html +++ b/docs/jsdoc/tutorial-state.html @@ -28,8 +28,10 @@

state

-

Whiteflag API Protocol State

-

The API has to keep its state of the Whiteflag protocol. This inludes keeping +

Whiteflag Protocol State

+

| WF API Documentation Home | WF API JSDoc Reference | WF API Interface | Whiteflag Specification |

+

Description

+

The API has to keep its state of the Whiteflag protocol. This includes keeping track of its blockchain status and accounts, known originators, encryption keys etc. The state is implemented as an in-memory object which is managed by lib/protocol/state.js. The structure of the state is defined in @@ -39,7 +41,7 @@

State configuration

config/whiteflag.toml configuration file.

State preservation

To preserve the state across restarts of the API, the state object is stored in -the primary datastore. When the API starts and initialises the state, the state +the primary datastore. When the API starts and initializes the state, the state is restored from the primary datastore. If no state is found in the datastore, the API starts with an empty state.

State encryption

@@ -53,11 +55,11 @@

State encryption

key specific attributes such as blockchain account and originator address.

The state as a whole can (and should) also be encrypted when stored in a file or in the primary datastore if encryption parameter is set to true in the -configuration file. The state will then be encrytpted with a Data Encryption +configuration file. The state will then be encrypted with a Data Encryption Key (DEK) which is also derived from the MEK.

-

Currently it is not possible to change the MEK without losing the state. Also, -please be aware that losing the MEK results in unobtainable keys, including -private blockchain keys and pre-shared encryption keys!

+

Currently, it is not possible to change the MEK without losing the state. +Also, please be aware that losing the MEK results in unobtainable keys, +including private blockchain keys and pre-shared encryption keys!

@@ -65,13 +67,13 @@

State encryption


- Documentation generated by JSDoc 4.0.5 on Wed Oct 22 2025 21:45:24 GMT+0200 (Central European Summer Time) + Documentation generated by JSDoc 4.0.5 on Sat Jan 03 2026 10:48:29 GMT+0100 (Central European Standard Time)
diff --git a/docs/jsdoc/tutorial-static.html b/docs/jsdoc/tutorial-static.html index c1788e6..55e1ef4 100644 --- a/docs/jsdoc/tutorial-static.html +++ b/docs/jsdoc/tutorial-static.html @@ -28,24 +28,26 @@

static

-

Whiteflag API Static Components

+

Static Components

+

| WF API Documentation Home | WF API JSDoc Reference | WF API Interface | Whiteflag Specification |

+

Description

The directory static/ contains static data provided by the API when running. This data consists of the Whiteflag API definition, a socket listener for Whiteflag messages and a Whiteflag signs and signals icon set. The server provides the static content on the / root endpoint, e.g. http://localhost:5746/.

-

In addition, protocol specific static content, such as json schemas, are in +

In addition, protocol specific static content, such as JSON schemas, are in static/protocol/. The server provides the static protocol data on the /protocol endpoint, e.g. http://localhost:5746/protocol/.

-

Other static data in static/ subdirectories may also exists, but this data is +

Other static data in static/ subdirectories may also exist, but this data is not provided by the server to clients. For example, there is also a test/static/ directory, which contains static data for testing, such as the JSON core schema meta-schema to validate the Whiteflag JSON schemas, which is done by the test/static.js test script.

-

Whitflag API Definition

+

Whiteflag API Definition

The API definition is specified in static/openapi.json in accordance with the OpenAPI specification. The index.html uses a standalone JavaScript version of Redoc -to render the API defintion into a human readible webpage.

+to render the API definition into a human-readable webpage.

Redoc is not maintained as an NPM package and the following files must therefore be manually be updated from the source repository (see the Redoc documentation):

@@ -53,7 +55,7 @@

Whitflag API Definition

  • static/js/redoc.standalone.js
  • static/js/redoc.standalone.js.map
    • -

    Whitflag API Message Listener

    +

    Whiteflag API Message Listener

    A simple web based message listener is available in static/listen/. The server provides the listener on the /listen endpoint, e.g. http://localhost:5746/listen. The listener uses the socket.io @@ -76,13 +78,13 @@

    Whiteflag Icons


    - Documentation generated by JSDoc 4.0.5 on Wed Oct 22 2025 21:45:24 GMT+0200 (Central European Summer Time) + Documentation generated by JSDoc 4.0.5 on Sat Jan 03 2026 10:48:29 GMT+0100 (Central European Standard Time)
    diff --git a/docs/md/bitcoin.md b/docs/md/bitcoin.md index 3fe88e2..247ea88 100644 --- a/docs/md/bitcoin.md +++ b/docs/md/bitcoin.md @@ -1,28 +1,30 @@ -# Whiteflag API Connector for Bitcoin +# Connector for Bitcoin -The Whiteflag API natively supports the [Bitcoin](https://bitcoin.org/) -blockchain. +| [WF API Documentation Home](../index.md) | [WF API JSDoc Reference](jsdoc/index.html) | [WF API Interface](openapi.md) | [Whiteflag Specification](https://standard.whiteflagprotocol.org) | + +## Blockchain specifications **NOTE** - *The Bitcoin module needs updating.* -## Blockchain specifications +The Whiteflag API natively supports the [Bitcoin](https://bitcoin.org/) +blockchain. -| | | -|-------------------------------|-------------| -| Whiteflag message embedding: | `OP_RETURN` | -| Script for address derivation | `P2PKH` | -| Maximum message length: | 80 bytes | -| Signature algorithm: | ECDSA secp256k1 | +| | | +|-------------------------------|----------------------------| +| Whiteflag message embedding: | `OP_RETURN` | +| Script for address derivation | `P2PKH` | +| Maximum message length: | 80 bytes | +| Signature algorithm: | ECDSA secp256k1 | | Transaction hash: | 256 bits (64 hexadecimals) | | Secret for account creation: | Wallet Import Format (WIF) | -Note that curve `secp256k1` for the ECDSA signature algorthm is officially not -specified to be used with JWS for Whiteflag authentication method 1. Instead, -the JWS specification in [RFC 7518](https://www.rfc-editor.org/rfc/rfc7518) +Note that curve `secp256k1` for the ECDSA signature algorithm is officially +not specified to be used with JWS for Whiteflag authentication method 1. +Instead, the JWS specification in [RFC 7518](https://www.rfc-editor.org/rfc/rfc7518) requires curve `secp256r1` a.k.a. `prime256v1`. However, Whiteflag is using JSON Web Tokens just as a structure. For Whiteflag authentication method 1 to -work, it is essential that the key pair and curve of the blockchain is used for -the signature to prove possession of the associated secret key. +work, it is essential that the key pair and curve of the blockchain is used +for the signature to prove possession of the associated secret key. See also [Issue 28](https://github.com/WhiteflagProtocol/whiteflag-api/issues/28). ## Accounts @@ -36,7 +38,7 @@ is referred to as a "wallet". For the purposes of (testing) Whiteflag, the same account, i.e. Bitcoin address, is reused. This is not a good practice for several reasons, such as -anonimity. However, for Whiteflag it is necessary that different transactions +anonymity. However, for Whiteflag it is necessary that different transactions can be linked to the same originator. Therefore, it is strongly recommended NOT to use the Whiteflag account for anything else, such as payments or transfers. @@ -48,7 +50,7 @@ the Bitcoin specific parameters in one of its `[[blockchains]]` sections. * `name`: the name according to the naming convention: `{name}-{network}`, e.g. `bitcoin-main` or `bitcoin-testnet` * `module`: the Bitcoin module in `lib/blockchains`, which should be "bitcoin" -* `testnet`: whether the Bitcoin testnet is used insted of the main network +* `testnet`: whether the Bitcoin testnet is used instead of the main network * `active`: whether the blockchain is active or should be ignored These parameters manage Bitcoin blockchain accounts (i.e. wallets): @@ -58,14 +60,14 @@ These parameters manage Bitcoin blockchain accounts (i.e. wallets): For retrieving transactions containing Whiteflag messages from the blockchain, these parameters may be provided, otherwise default values are used: -* `blockRetrievalInterval`: the time in milliseconds before the Bitcoin listener tries to retireve the next block; the default is `60000` ms +* `blockRetrievalInterval`: the time in milliseconds before the Bitcoin listener tries to retrieve the next block; the default is `60000` ms * `blockRetrievalStart`: the starting block from where to retrieve transactions; if `0` (default) the API resumes a number of blocks before the highest block as configured below * `blockRetrievalEnd`: the last block from where to retrieve transactions; if `0` (default) the API catches up with the highest block on the node * `blockRetrievalRestart`: how many blocks before the current highest block the API should look back when (re)starting the API; this prevents that blocks are missed when the API is stopped for a short period * `blockMaxRetries`: how many times the API should retry to process a block if it fails, e.g. because of a node timeout; default is `0`, which means unlimited retries * `transactionBatchSize`: how many transactions from a single block the API may process in parallel; default is `128` -* `transactionFee`: the (minimum) value of a transaction fee when sending a Whiteflag message, used if the fee cannot be estimated or if the estimated fee is lower; default is 1000 satoshis -* `transactionPriority`: the priority used to estimate the transaction fee and defined by the number of blocks by which confirmation is desired: `1` is highest priority, but also a higher transaction fee, if `0` the fixed transaction fee is used +* `transactionFee`: the (minimum) value of a transaction fee when sending a Whiteflag message, used if the fee cannot be estimated or if the estimated fee is lower; default is 1000 Satoshi +* `transactionPriority`: the priority used to estimate the transaction fee and defined by the number of blocks by which confirmation is desired: `1` is the highest priority, but also a higher transaction fee; if `0` the fixed transaction fee is used * `traceRawTransaction`: whether to show each individual transaction when the loglevel is set to `6` (trace); default is `false` because this results in massive logging To send and receive Whiteflag messages, the API must be connected to a Bitcoin diff --git a/docs/md/configuration.md b/docs/md/configuration.md index dd17947..cccfd89 100644 --- a/docs/md/configuration.md +++ b/docs/md/configuration.md @@ -1,4 +1,6 @@ -# Whiteflag API Configuration +# Configuration + +| [WF API Documentation Home](../index.md) | [WF API JSDoc Reference](jsdoc/index.html) | [WF API Interface](openapi.md) | [Whiteflag Specification](https://standard.whiteflagprotocol.org) | ## Environment variables @@ -27,21 +29,21 @@ The configuration files are formatted in [TOML](https://github.com/toml-lang/tom ### General API configuration -This configuration file provides global configuration parameters for the api. +This configuration file provides global configuration parameters for the API. The `[logger]` section parameters are: -* `loglevel`: the log level of the api: +* `loglevel`: the log level of the API: 1=fatal, 2=error, 3=warning, 4=info, 5=debug, 6=trace The following `[server]` section parameters may be defined: * `protocol`: either `http` or `https`, default is `http` -* `hostname`: the hostname used by the api, default is no hostname -* `port`: the port on which the api is listening, default is `5746`; may be overriden by the `WFPORT` environment variable +* `hostname`: the hostname used by the API, default is no hostname +* `port`: the port on which the API is listening, default is `5746`; may be overridden by the `WFPORT` environment variable In the `[authorization]` section, basic http authorization can be enabled -by setting a `username` and `password`. Levae empty to disable basic auth. +by setting a `username` and `password`. Leave 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 @@ -60,11 +62,11 @@ messages are emitted: * `enable`: if true, the web socket will be available, otherwise not -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. +The parameters in the `[endpoints]` section are booleans that allow enabling +or disabling specific API operations. See the API documentation for a +description of all operations. Note that the `receiveMessage` operation 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 @@ -73,7 +75,7 @@ parameters. The `[state]` section parameters control the storage of the Whiteflag state: -* `masterKey`: hex representation of the 256 bit key used for encrytpion of keys and state data +* `masterKey`: hex representation of the 256-bit key used for encryption of keys and state data * `encryption`: boolean indicating if the state needs to be encrypted The `[tx]` section contains message transmit behaviour parameters: @@ -89,17 +91,17 @@ The `[rx]` message contains message receiving behaviour parameters: The `[authentication]` section controls the behaviour for all authentication methods * `strict`: if `true`, then unauthenticated messages are rejected; - if `false`, then unauthenticated messages are flagged in MetaHeader (default) + if `false`, then unauthenticated messages are flagged in the metaheader (default) The behaviour parameters for authentication method 1 are in the `[authentication.1]` section: * `validDomains`: array of domain names that are considered to hold valid authentication signatures; if empty, all domain names are accepted -Encryption paramaters for encryption method X are in +Encryption parameters for encryption method X are in the `[encryption.X]` section: -* `psk`: a pre-shared key, i.e. a secret from which the message encyption key is derived if no other input key material is available; should only be used for testing +* `psk`: a pre-shared key, i.e. a secret from which the message encryption key is derived if no other input key material is available; should only be used for testing ### Blockchain configuration @@ -111,7 +113,7 @@ The `[confirmation]` section contains the following parameters that affect all blockchains: * `enabled`: boolean whether to track block depth of message for confirmation -* `interval`: interval in ms to check blockdepth of message +* `interval`: interval in ms to check block depth of message * `maxBlockDepth`: maximum block depth after which a message is confirmed * `updateEachBlock`: if true, the block depth of messages on the confirmation queue is updated upon each new block, otherwise only when confirmed * `doubleCheck`: if true, a message duplicate is retrieved from the blockchain for double check upon confirmation @@ -121,8 +123,8 @@ 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: +At a minimum, the following parameters must be defined for each blockchain in +the respective `[[blockchains]]` section: * `name`: the name by which the blockchain is identified in the software and in loggings; naming convention: `{name}-{network}`, e.g. `bitcoin-testnet` or `ethereum-rinkeby` * `module`: module that implements the specific logic of the blockchain; modules are located in `./lib/blockchains` and to minimally implement the module methods as described in `./lib/blockchains/static/blockchains-template.js`. @@ -134,11 +136,11 @@ blockchain module, such as connection details to a full node. ### Datastores configuration -This datastores configuration file allows to define which datastores should be +This datastores configuration file allows defining which datastores should be used to store data. The embedded datastore is the default. Multiple stores may be defined with multiple -`[[databases]]` sections. At a minumum, the following parameters must be defined +`[[databases]]` sections. At a minimum, the following parameters must be defined for each datastore as detailed in `./lib/datastores/static/datastores.config.schema.json`. * `name`: the name by which the datastore is identified in the software and in loggings @@ -148,5 +150,5 @@ for each datastore as detailed in `./lib/datastores/static/datastores.config.sch * `rxStoreEvent`: array of rx events on which a message should be stored in datastore, normally `["messageProcessed"]` * `txStoreEvent`: array of tx events on which a message should be stored in datastore, normally `["messageProcessed"]` -Additional parameters may be rquired depending on the database, as shown in the +Additional parameters may be required depending on the database, as shown in the default configuration file. diff --git a/docs/md/errors.md b/docs/md/errors.md index e2122e8..683b23e 100644 --- a/docs/md/errors.md +++ b/docs/md/errors.md @@ -1,4 +1,8 @@ -# Whiteflag API Error Handling +# Error Handling + +| [WF API Documentation Home](../index.md) | [WF API JSDoc Reference](jsdoc/index.html) | [WF API Interface](openapi.md) | [Whiteflag Specification](https://standard.whiteflagprotocol.org) | + +## Description In addition to the standard Node.js JavaScript `Error` class, two additional classes are exposed by `lib/common/errors.js` to handle processing and protocol @@ -23,10 +27,10 @@ err = new ProcessingError(message, causes, code); err = new ProtocolError(message, causes, code); ``` -with the folloing arguments: +with the following arguments: -* `message` is similar to the property of the generic Error class, i.e. a string with a human readable description of the error -* `causes` is an additional property in the form of an array that may contain a human readable stack of underlying causes +* `message` is similar to the property of the generic Error class, i.e. a string with a human-readable description of the error +* `causes` is an additional property in the form of an array that may contain a human-readable stack of underlying causes * `code` is a property of type string, identifying the type of error as described below for both classes ### `ProcessingError` class error codes @@ -35,8 +39,8 @@ with the folloing arguments: * `WF_API_BAD_REQUEST`: the request was incomplete or incorrect syntax * `WF_API_NOT_ALLOWED`: the request is not allowed * `WF_API_NO_DATA`: the request did not return any (valid) data -* `WF_API_NO_RESOURCE`: could not processess because resource does not exist -* `WF_API_RESOURCE_CONFLICT`: could not process because resource alreasy exists +* `WF_API_NO_RESOURCE`: could not process because resource does not exist +* `WF_API_RESOURCE_CONFLICT`: could not process because the resource is in a conflicting state * `WF_API_NOT_IMPLEMENTED`: the function is not supported * `WF_API_NOT_AVAILABLE`: the function is currently not available diff --git a/docs/md/ethereum.md b/docs/md/ethereum.md index 35bf8f0..c4dd5e4 100644 --- a/docs/md/ethereum.md +++ b/docs/md/ethereum.md @@ -1,21 +1,23 @@ -# Whiteflag API Connector for Ethereum +# Connector for Ethereum -The Whiteflag API natively supports the [Ethereum](https://www.ethereum.org/) -blockchain. +| [WF API Documentation Home](../index.md) | [WF API JSDoc Reference](jsdoc/index.html) | [WF API Interface](openapi.md) | [Whiteflag Specification](https://standard.whiteflagprotocol.org) | + +## Blockchain specifications **NOTE** - *The Ethereum module needs updating.* -## Blockchain specifications +The Whiteflag API natively supports the [Ethereum](https://www.ethereum.org/) +blockchain. -| | | -|--------------------------------|--------------| -| Whiteflag message embedding: | `data` field | -| Maximum message length: | dynamic | -| Signature algorithm: | ECDSA secp256k1 | -| Transaction hash: | 256 bits (64 hexadecimals) | -| Secret for account creation: | private key | +| | | +|------------------------------|----------------------------| +| Whiteflag message embedding: | `data` field | +| Maximum message length: | dynamic | +| Signature algorithm: | ECDSA secp256k1 | +| Transaction hash: | 256 bits (64 hexadecimals) | +| Secret for account creation: | private key | -Note that curve `secp256k1` for the ECDSA signature algorthm is officially not +Note that curve `secp256k1` for the ECDSA signature algorithm is officially not specified to be used with JWS for Whiteflag authentication method 1. Instead, the JWS specification in [RFC 7518](https://www.rfc-editor.org/rfc/rfc7518) requires curve `secp256r1` a.k.a. `prime256v1`. However, Whiteflag is using @@ -30,7 +32,7 @@ The blockchains configuration file `config/blockchains.toml` should contain the Ethereum specific parameters in one of its `[[blockchains]]` sections. * `name`: the name according to the naming convention: `{name}-{network}`, e.g. `ethereum-main` or `ethereum-rinkeby` -* `module`: the Ethereum module in `lib/blockchains`, which should be "ethereum" +* `module`: the Ethereum module in `lib/blockchains`, which should be `ethereum` * `chainID`: the appropriate Chain ID for the Ethereum network that is used * `active`: whether the blockchain is active or should be ignored @@ -41,7 +43,7 @@ These parameters manage Ethereum blockchain accounts: For retrieving transactions containing Whiteflag messages from the blockchain, these parameters may be provided, otherwise default values are used: -* `blockRetrievalInterval`: the time in milliseconds before the Ethereum listener tries to retireve the next block; the default is `6000` ms +* `blockRetrievalInterval`: the time in milliseconds before the Ethereum listener tries to retrieve the next block; the default is `6000` ms * `blockRetrievalStart`: the starting block from where to retrieve transactions; if `0` (default) the API resumes a number of blocks before the highest block as configured below * `blockRetrievalEnd`: the last block from where to retrieve transactions; if `0` (default) the API catches up with the highest block on the node * `blockRetrievalRestart`: how many blocks before the current highest block the API should look back when (re)starting the API; this prevents that blocks are missed when the API is stopped for a short period @@ -50,9 +52,9 @@ these parameters may be provided, otherwise default values are used: * `transactionValue`: the value of a transaction when sending a Whiteflag message; default is `0` ether * `traceRawTransaction`: whether to show each individual transaction when the loglevel is set to `6` (trace); default is `false` because this results in massive logging -To send and receive Whiteflag messages, the API must be connected to a Ethereum -node exposing the standard Ethereum RPC interface. These parameters are used to -configure the connection: +To send and receive Whiteflag messages, the API must be connected to an +Ethereum node exposing the standard Ethereum RPC interface. These parameters +are used to configure the connection: * `rpcTimeout`: the timeout for an RPC request in milliseconds; the default is `10000` * `rpcProtocol`: the protocol via which the RPC interface is available, usually `http` or `https` diff --git a/docs/md/events.md b/docs/md/events.md index ec69617..7f7a7d1 100644 --- a/docs/md/events.md +++ b/docs/md/events.md @@ -1,4 +1,8 @@ -# Whiteflag API Events +# Events Handling + +| [WF API Documentation Home](../index.md) | [WF API JSDoc Reference](jsdoc/index.html) | [WF API Interface](openapi.md) | [Whiteflag Specification](https://standard.whiteflagprotocol.org) | + +## Description The Whiteflag API uses events internally for modules to know when protocol actions must be triggered. Three main event types are defined in the @@ -22,22 +26,22 @@ incoming and outgoing messages. The `lib/datastores.js` module listens for these events to store messages as configured in the `config/datastores.toml` configuration file. -Currently defined rx and tx events are: +Currently, defined rx and tx events are: | Event | Direction | Description | |---------------------|-----------|--------------------------------------------------------------------------------------------| -| `error` | RX, TX | An error occured when processing the message | +| `error` | RX, TX | An error occurred when processing the message | | `messageReceived` | RX | A new incoming message has been received from the blockchain or from the REST interface | | `messageCommitted` | TX | A new outgoing message has been posted on the REST interface or is generated automatically | | `metadataVerified` | RX, TX | The message metadata has been verified and is valid | | `messageEncrypted` | RX | The received message has been encrypted and cannot be decoded immediately | -| `messageDecoded` | RX | The incoming message has been succesfully decrypted/decoded | -| `messageEncoded` | TX | The outgoing message has been succesfully encoded/encrypted | +| `messageDecoded` | RX | The incoming message has been successfully decrypted/decoded | +| `messageEncoded` | TX | The outgoing message has been successfully encoded/encrypted | | `originatorVerified`| RX | The originator of the incoming message has been verified | | `originatorSkipped` | RX | Verification of the originator of the incoming message has been skipped | | `referenceVerified` | RX, TX | The message correctly references other messages | | `referenceSkipped` | RX, TX | The way the message references other messages has not been verified | -| `messageSent` | TX | The outgoing message has been sucessfully transmitted on the blockchain | +| `messageSent` | TX | The outgoing message has been successfully transmitted on the blockchain | | `messageProcessed` | RX, TX | The processing of the message has been completed | | `messageUpdated` | RX, TX | The message metadata has been updated after initial processing | diff --git a/docs/md/fennel.md b/docs/md/fennel.md index cef3f0b..0bce2ab 100644 --- a/docs/md/fennel.md +++ b/docs/md/fennel.md @@ -1,19 +1,21 @@ -# Whiteflag API Connector for the Fennel parachain +# Connector for the Fennel parachain -The Whiteflag API natively supports the Fennel blockchain, which is based on -the [Substrate/Polkadot SDK](https://polkadot.com/platform/sdk/). +| [WF API Documentation Home](../index.md) | [WF API JSDoc Reference](jsdoc/index.html) | [WF API Interface](openapi.md) | [Whiteflag Specification](https://standard.whiteflagprotocol.org) | ## Blockchain specifications -| | | -|--------------------------------|---------------| -| Whiteflag message embedding: | `signal` pallet | -| Maximum message length: | (t.b.d.) | -| Signature algorithm: | sr25519 | -| Transaction hash: | 256 bits (64 hexadecimals) | -| Address encoding: | SS58 address format | -| Address prefix: | 42 (substrate) | -| Secret for account creation: | 32 byte seed | +The Whiteflag API natively supports the Fennel blockchain, which is based on +the [Substrate/Polkadot SDK](https://polkadot.com/platform/sdk/). + +| | | +|------------------------------|----------------------------| +| Whiteflag message embedding: | `signal` pallet | +| Maximum message length: | (t.b.d.) | +| Signature algorithm: | sr25519 | +| Transaction hash: | 256 bits (64 hexadecimals) | +| Address encoding: | SS58 address format | +| Address prefix: | 42 (substrate) | +| Secret for account creation: | 32 byte seed | NOTE: The signature algorithm `sr25519` is officially not specified to be used with JWS in [RFC 7518](https://www.rfc-editor.org/rfc/rfc7518) for Whiteflag @@ -39,16 +41,16 @@ These parameters manage Fennel parachain accounts: For retrieving transactions containing Whiteflag messages from the blockchain, these parameters may be provided, otherwise default values are used: -* `blockRetrievalInterval`: the time in milliseconds before the Fennel listener tries to retireve the next block; the default is `6000` ms +* `blockRetrievalInterval`: the time in milliseconds before the Fennel listener tries to retrieve the next block; the default is `6000` ms * `blockRetrievalStart`: the starting block from where to retrieve transactions; if `0` (default) the API resumes a number of blocks before the highest block as configured below * `blockRetrievalEnd`: the last block from where to retrieve transactions; if `0` (default) the API catches up with the highest block on the node * `blockRetrievalRestart`: how many blocks before the current highest block the API should look back when (re)starting the API; this prevents that blocks are missed when the API is stopped for a short period * `blockMaxRetries`: how many times the API should retry to process a block if it fails, e.g. because of a node timeout; default is `0`, which means unlimited retries -* `blockBatchSize`: how many blocks the API may process in parellel to balance balance speed and node RPC overload +* `blockBatchSize`: how many blocks the API may process in parallel to balance speed and node RPC overload * `traceRawTransaction`: whether to show each individual transaction when the loglevel is set to `6` (trace); default is `false` because this results in massive logging To send and receive Whiteflag messages, the API must be connected to a Fennel -parachain node exposing the [Substrate/Polkadot RPC interface](https://docs.polkadot.com/develop/toolkit/parachains/rpc-calls/) +parachain node exposing the [Substrate/Polkadot RPC](https://docs.polkadot.com/develop/toolkit/parachains/rpc-calls/) interface. These parameters are used to configure the connection: * `rpcTimeout`: the timeout for an RPC request in milliseconds; the default is `10000` diff --git a/docs/md/installation.md b/docs/md/installation.md index b26ba4f..92c55fd 100644 --- a/docs/md/installation.md +++ b/docs/md/installation.md @@ -1,4 +1,6 @@ -# Whiteflag API Installation and Running +# Installation and Running + +| [WF API Documentation Home](../index.md) | [WF API JSDoc Reference](jsdoc/index.html) | [WF API Interface](openapi.md) | [Whiteflag Specification](https://standard.whiteflagprotocol.org) | ## Prerequisites @@ -41,7 +43,7 @@ the software before running. Using the `npm start` command in the deployment directory will start the Whiteflag API service. -Creating a global link to the package will allow to start the Whiteflag API +Creating a global link to the package will allow starting the Whiteflag API from the command line with a single command `wfapi`. Create the link with: ```shell @@ -49,7 +51,7 @@ npm link ``` Alternatively, a service may be created that starts the service at boot. -An example `whiteflag-api.service` for linux systems using `systemctl` can be +An example `whiteflag-api.service` for Linux systems using `systemctl` can be found in `etc/`. Enable and start the service with: ```shell diff --git a/docs/md/logging.md b/docs/md/logging.md index a520507..1af0a27 100644 --- a/docs/md/logging.md +++ b/docs/md/logging.md @@ -1,11 +1,12 @@ -# Whiteflag API Logging +# Logging -The common module `lib/common/logger.js` exposes functions to be used -throughout the source code for logging messages from the running API. +| [WF API Documentation Home](../index.md) | [WF API JSDoc Reference](jsdoc/index.html) | [WF API Interface](openapi.md) | [Whiteflag Specification](https://standard.whiteflagprotocol.org) | ## Loglevel functions -The logging module exposes a logging function for each loglevel. +The common module `lib/common/logger.js` exposes functions to be used +throughout the source code for logging messages from the running API +for each loglevel. | Level | Name | Usage | |-------|---------|-------------------------------------------------------------------------------------------| diff --git a/docs/md/modules.md b/docs/md/modules.md index c57891c..b0d1a2b 100644 --- a/docs/md/modules.md +++ b/docs/md/modules.md @@ -1,7 +1,11 @@ -# Whiteflag API JavaScript Modules +# Modules + +| [WF API Documentation Home](../index.md) | [WF API JSDoc Reference](jsdoc/index.html) | [WF API Interface](openapi.md) | [Whiteflag Specification](https://standard.whiteflagprotocol.org) | + +## Overview The Whiteflag API is written in JavaScript to run on [Node.js](https://nodejs.org/en/about/). -The source code of the Whiteflag API is organised in modules. Each module +The source code of the Whiteflag API is organized in modules. Each module corresponds with a `.js` source code file. The source code files / modules are structured in the following directory tree: @@ -20,10 +24,10 @@ development guidelines for the source code. ## Main modules -The main Whiteflag API module is `whiteflag.js`, which initialises all +The main Whiteflag API module is `whiteflag.js`, which initializes all other main modules in `lib/`: -* `config.js`: the module that reads the api configuration from `config/api.toml` +* `config.js`: the module that reads the API configuration from `config/api.toml` * `server.js`: the module that opens the network connections and connects the routes and methods to the correct handlers in the endpoints modules * `blockchains.js`: the module that implements the blockchain abstraction layer, and handles all requests to the configured blockchains * `datastores.js`: the module that implements the datastores abstraction layer, and handles all requests to the configured databases @@ -31,7 +35,7 @@ other main modules in `lib/`: ## Common modules Common modules in `lib/_common` are used for function and class definitions -shared by multiple modules across the project. Common modules may not require +shared by multiple modules across the project. These modules may not require other project modules outside `lib/_common` to function. Submodules may also have a `_common/` subdirectory, and a `_static/` subdirectory for static data. @@ -46,7 +50,7 @@ methods. ## Protocol modules All Whiteflag protocol features and logic is implemented in the protocol -modules in `lib/protocol`. The protocol implementation is described seperately +modules in `lib/protocol`. The protocol implementation is described separately in [`protocol.md`](protocol.md). ## Blockchain modules @@ -63,16 +67,16 @@ blockchain through the callback function is correct. A template for creating a new blockchain module to connect to a specific database is available with `lib/blockchains/static/blockchain.template.js`. Note that the function names in a blockchain module should reflect the function -names in de main `blockchains.js` module. +names in the main `blockchains.js` module. -The configuration of the blcockchains and the blockchain modules can be found in +The configuration of the blockchains and the blockchain modules can be found in `config/blockchains.toml`. This configuration file has a section `[[blockchains]]` for each blockchain. ## Datastore modules The datastore modules in lib/datastores implement the connections with the -unbderlying blockchains. There is one module per supported datastore. +underlying blockchains. There is one module per supported datastore. Functions in a specific datastore module are called by the main module `datastores.js`, which forms the datastore abstraction layer. @@ -83,7 +87,7 @@ datastore through the callback function is correct. A template for creating a new datastore module to connect to a specific database is available with `lib/datastores/static/datastore.template.js`. Note that the function names in a datastore module should reflect the function -names in de main `datastores.js` module. +names in the main `datastores.js` module. The configuration of the datastores and the datastore modules can be found in `config/datastores.toml`. This configuration file has a section `[[databases]]` diff --git a/docs/md/openapi.md b/docs/md/openapi.md index af2a375..87a1835 100644 --- a/docs/md/openapi.md +++ b/docs/md/openapi.md @@ -1,5 +1,5 @@ --- -title: Whiteflag API v1.1.0 +title: Whiteflag API v1.2.0 language_tabs: - shell: Shell - http: HTTP @@ -19,7 +19,7 @@ headingLevel: 2 -

    Whiteflag API v1.1.0

    +

    Whiteflag API v1.2.0

    > Scroll down for code samples, example requests and responses. Select a language for code samples from the tabs above or the mobile navigation menu. @@ -134,7 +134,7 @@ HTTP Authentication -`POST /messages/send` +`POST /messages` Transmits a Whiteflag message on a blockchain and returns the result. This operation may be disabled in the configuration. @@ -205,11 +205,68 @@ To perform this operation, you must be authenticated by means of one of the foll HTTP Authentication +## getMessage + + + +`GET /messages/{transactionHash}` + +Returns the specified message. This operation may be disabled in the configuration. This operation may be disabled in the configuration. + +> Example responses + +> 200 Response + +```json +{ + "meta": { + "additionalProperties": null, + "operationId": "string", + "request": { + "client": "string", + "method": "string", + "endpoint": "string" + }, + "info": [ + "string" + ], + "warnings": [ + "string" + ], + "errors": [ + "string" + ] + }, + "data": { + "MetaHeader": null, + "MessageHeader": null, + "MessageBody": null + } +} +``` + +

    Responses

    + +|Status|Meaning|Description|Schema| +|---|---|---|---| +|200|[OK](https://tools.ietf.org/html/rfc7231#section-6.3.1)|Successfully processed the Whiteflag message and returning the message with updated MetaHeader|Inline| +|401|[Unauthorized](https://tools.ietf.org/html/rfc7235#section-3.1)|Authentication is required and was either not provided or has failed|[responseBodyErrors](#schemaresponsebodyerrors)| +|403|[Forbidden](https://tools.ietf.org/html/rfc7231#section-6.5.3)|Request is not allowed, typically because the operation is disabled in the configuration|[responseBodyErrors](#schemaresponsebodyerrors)| +|404|[Not Found](https://tools.ietf.org/html/rfc7231#section-6.5.4)|Requested resource not found or no data available|[responseBodyErrors](#schemaresponsebodyerrors)| +|500|[Internal Server Error](https://tools.ietf.org/html/rfc7231#section-6.6.1)|Internal error preventing the running API instance to process the request|[responseBodyErrors](#schemaresponsebodyerrors)| + +

    Response Schema

    + + + ## receiveMessage -`POST /messages/receive` +`PUT /messages/{transactionHash}` Accepts a Whiteflag message as if received from a blockchain. This may be done for simulation of incoming messages or if a direct connection with a blockchain node is not possible. Typically only used for testing. This operation may be disabled in the configuration. @@ -269,6 +326,7 @@ Accepts a Whiteflag message as if received from a blockchain. This may be done f |403|[Forbidden](https://tools.ietf.org/html/rfc7231#section-6.5.3)|Request is not allowed, typically because the operation is disabled in the configuration|[responseBodyErrors](#schemaresponsebodyerrors)| |500|[Internal Server Error](https://tools.ietf.org/html/rfc7231#section-6.6.1)|Internal error preventing the running API instance to process the request|[responseBodyErrors](#schemaresponsebodyerrors)| |501|[Not Implemented](https://tools.ietf.org/html/rfc7231#section-6.6.2)|Function not implemented, such as a missing protocol feature or not implemented blockchain|[responseBodyErrors](#schemaresponsebodyerrors)| +|503|[Service Unavailable](https://tools.ietf.org/html/rfc7231#section-6.6.4)|Function currently not available, such as unavailable blockchain connection|[responseBodyErrors](#schemaresponsebodyerrors)|

    Response Schema

    @@ -277,29 +335,20 @@ To perform this operation, you must be authenticated by means of one of the foll HTTP Authentication -## encodeMessage +## getMsgReferences - - -`POST /messages/encode` + -Encodes a Whiteflag message and returns the result. Typically used for validation and testing, because this is automatically done for outgoing messages. This operation may be disabled in the configuration. +`GET /references` -> Body parameter - -```json -{ - "MetaHeader": null, - "MessageHeader": null, - "MessageBody": null -} -``` +Returns an array of all Whiteflag messages referencing the message with the given transaction hash. This operation may be disabled in the configuration. -

    Parameters

    +

    Parameters

    |Name|In|Type|Required|Description| |---|---|---|---|---| -|body|body|[wfMessage](#schemawfmessage)|false|Whiteflag message to be send, encoded/ecrypted, or validated| +|transactionHash|query|string|false|The hash of a blockchain transaction| +|blockchain|query|string|false|The name of a blockchain| > Example responses @@ -325,53 +374,49 @@ Encodes a Whiteflag message and returns the result. Typically used for validatio "string" ] }, - "data": { - "MetaHeader": null, - "MessageHeader": null, - "MessageBody": null - } + "data": [ + { + "MetaHeader": null, + "MessageHeader": null, + "MessageBody": null + } + ] } ``` -

    Responses

    +

    Responses

    |Status|Meaning|Description|Schema| |---|---|---|---| -|200|[OK](https://tools.ietf.org/html/rfc7231#section-6.3.1)|Successfully processed the Whiteflag message and returning the message with updated MetaHeader|Inline| +|200|[OK](https://tools.ietf.org/html/rfc7231#section-6.3.1)|Successfully processed Whiteflag message query or blockchain scan and returning an array of messages|Inline| |400|[Bad Request](https://tools.ietf.org/html/rfc7231#section-6.5.1)|Invalid request, typically because of a malformed syntax or protocol error|[responseBodyErrors](#schemaresponsebodyerrors)| |401|[Unauthorized](https://tools.ietf.org/html/rfc7235#section-3.1)|Authentication is required and was either not provided or has failed|[responseBodyErrors](#schemaresponsebodyerrors)| |403|[Forbidden](https://tools.ietf.org/html/rfc7231#section-6.5.3)|Request is not allowed, typically because the operation is disabled in the configuration|[responseBodyErrors](#schemaresponsebodyerrors)| |500|[Internal Server Error](https://tools.ietf.org/html/rfc7231#section-6.6.1)|Internal error preventing the running API instance to process the request|[responseBodyErrors](#schemaresponsebodyerrors)| |501|[Not Implemented](https://tools.ietf.org/html/rfc7231#section-6.6.2)|Function not implemented, such as a missing protocol feature or not implemented blockchain|[responseBodyErrors](#schemaresponsebodyerrors)| +|503|[Service Unavailable](https://tools.ietf.org/html/rfc7231#section-6.6.4)|Function currently not available, such as unavailable blockchain connection|[responseBodyErrors](#schemaresponsebodyerrors)| -

    Response Schema

    +

    Response Schema

    -## decodeMessage - - - -`POST /messages/decode` +## getMsgSequence -Decodes a Whiteflag message and returns the result. Typically used for validation and testing, because this is automatically done for incoming messages. This operation may be disabled in the configuration. + -> Body parameter +`GET /sequence` -```json -{ - "MetaHeader": null -} -``` +Returns an array with the Whiteflag messages in a sequence starting with the message with the given transaction hash. This operation may be disabled in the configuration. -

    Parameters

    +

    Parameters

    |Name|In|Type|Required|Description| |---|---|---|---|---| -|body|body|object|false|Whiteflag message to be decoded/decrypted| +|transactionHash|query|string|false|The hash of a blockchain transaction| +|blockchain|query|string|false|The name of a blockchain| > Example responses @@ -397,39 +442,42 @@ Decodes a Whiteflag message and returns the result. Typically used for validatio "string" ] }, - "data": { - "MetaHeader": null, - "MessageHeader": null, - "MessageBody": null - } + "data": [ + { + "MetaHeader": null, + "MessageHeader": null, + "MessageBody": null + } + ] } ``` -

    Responses

    +

    Responses

    |Status|Meaning|Description|Schema| |---|---|---|---| -|200|[OK](https://tools.ietf.org/html/rfc7231#section-6.3.1)|Successfully processed the Whiteflag message and returning the message with updated MetaHeader|Inline| +|200|[OK](https://tools.ietf.org/html/rfc7231#section-6.3.1)|Successfully processed Whiteflag message query or blockchain scan and returning an array of messages|Inline| |400|[Bad Request](https://tools.ietf.org/html/rfc7231#section-6.5.1)|Invalid request, typically because of a malformed syntax or protocol error|[responseBodyErrors](#schemaresponsebodyerrors)| |401|[Unauthorized](https://tools.ietf.org/html/rfc7235#section-3.1)|Authentication is required and was either not provided or has failed|[responseBodyErrors](#schemaresponsebodyerrors)| |403|[Forbidden](https://tools.ietf.org/html/rfc7231#section-6.5.3)|Request is not allowed, typically because the operation is disabled in the configuration|[responseBodyErrors](#schemaresponsebodyerrors)| |500|[Internal Server Error](https://tools.ietf.org/html/rfc7231#section-6.6.1)|Internal error preventing the running API instance to process the request|[responseBodyErrors](#schemaresponsebodyerrors)| |501|[Not Implemented](https://tools.ietf.org/html/rfc7231#section-6.6.2)|Function not implemented, such as a missing protocol feature or not implemented blockchain|[responseBodyErrors](#schemaresponsebodyerrors)| +|503|[Service Unavailable](https://tools.ietf.org/html/rfc7231#section-6.6.4)|Function currently not available, such as unavailable blockchain connection|[responseBodyErrors](#schemaresponsebodyerrors)| -

    Response Schema

    +

    Response Schema

    -## validateMessage +## encodeMessage - + -`POST /messages/validate` +`POST /message/encode` -Validates the format and reference of a Whiteflag message and returns the result. Typically used for validation and testing, because this is automatically done for incoming and outgoing messages. This operation may be disabled in the configuration. +Encodes a Whiteflag message and returns the result. Typically used for validation and testing, because this is automatically done for outgoing messages. This operation may be disabled in the configuration. > Body parameter @@ -441,7 +489,7 @@ Validates the format and reference of a Whiteflag message and returns the result } ``` -

    Parameters

    +

    Parameters

    |Name|In|Type|Required|Description| |---|---|---|---|---| @@ -471,47 +519,53 @@ Validates the format and reference of a Whiteflag message and returns the result "string" ] }, - "data": [ - { - "MetaHeader": null, - "MessageHeader": null, - "MessageBody": null - } - ] + "data": { + "MetaHeader": null, + "MessageHeader": null, + "MessageBody": null + } } ``` -

    Responses

    +

    Responses

    |Status|Meaning|Description|Schema| |---|---|---|---| -|200|[OK](https://tools.ietf.org/html/rfc7231#section-6.3.1)|Successfully processed Whiteflag message query or blockchain scan and returning an array of messages|Inline| +|200|[OK](https://tools.ietf.org/html/rfc7231#section-6.3.1)|Successfully processed the Whiteflag message and returning the message with updated MetaHeader|Inline| |400|[Bad Request](https://tools.ietf.org/html/rfc7231#section-6.5.1)|Invalid request, typically because of a malformed syntax or protocol error|[responseBodyErrors](#schemaresponsebodyerrors)| |401|[Unauthorized](https://tools.ietf.org/html/rfc7235#section-3.1)|Authentication is required and was either not provided or has failed|[responseBodyErrors](#schemaresponsebodyerrors)| |403|[Forbidden](https://tools.ietf.org/html/rfc7231#section-6.5.3)|Request is not allowed, typically because the operation is disabled in the configuration|[responseBodyErrors](#schemaresponsebodyerrors)| |500|[Internal Server Error](https://tools.ietf.org/html/rfc7231#section-6.6.1)|Internal error preventing the running API instance to process the request|[responseBodyErrors](#schemaresponsebodyerrors)| +|503|[Service Unavailable](https://tools.ietf.org/html/rfc7231#section-6.6.4)|Function currently not available, such as unavailable blockchain connection|[responseBodyErrors](#schemaresponsebodyerrors)| -

    Response Schema

    +

    Response Schema

    -## getMessageReferences +## decodeMessage - + -`GET /messages/references` +`POST /message/decode` -Returns an array of all Whiteflag messages referencing the message with the given transaction hash. This operation may be disabled in the configuration. +Decodes a Whiteflag message and returns the result. Typically used for validation and testing, because this is automatically done for incoming messages. This operation may be disabled in the configuration. -

    Parameters

    +> Body parameter + +```json +{ + "MetaHeader": null +} +``` + +

    Parameters

    |Name|In|Type|Required|Description| |---|---|---|---|---| -|transactionHash|query|string|false|The hash of a blockchain transaction| -|blockchain|query|string|false|The name of a blockchain| +|body|body|object|false|Whiteflag message to be decoded/decrypted| > Example responses @@ -537,49 +591,55 @@ Returns an array of all Whiteflag messages referencing the message with the give "string" ] }, - "data": [ - { - "MetaHeader": null, - "MessageHeader": null, - "MessageBody": null - } - ] + "data": { + "MetaHeader": null, + "MessageHeader": null, + "MessageBody": null + } } ``` -

    Responses

    +

    Responses

    |Status|Meaning|Description|Schema| |---|---|---|---| -|200|[OK](https://tools.ietf.org/html/rfc7231#section-6.3.1)|Successfully processed Whiteflag message query or blockchain scan and returning an array of messages|Inline| +|200|[OK](https://tools.ietf.org/html/rfc7231#section-6.3.1)|Successfully processed the Whiteflag message and returning the message with updated MetaHeader|Inline| |400|[Bad Request](https://tools.ietf.org/html/rfc7231#section-6.5.1)|Invalid request, typically because of a malformed syntax or protocol error|[responseBodyErrors](#schemaresponsebodyerrors)| |401|[Unauthorized](https://tools.ietf.org/html/rfc7235#section-3.1)|Authentication is required and was either not provided or has failed|[responseBodyErrors](#schemaresponsebodyerrors)| |403|[Forbidden](https://tools.ietf.org/html/rfc7231#section-6.5.3)|Request is not allowed, typically because the operation is disabled in the configuration|[responseBodyErrors](#schemaresponsebodyerrors)| |500|[Internal Server Error](https://tools.ietf.org/html/rfc7231#section-6.6.1)|Internal error preventing the running API instance to process the request|[responseBodyErrors](#schemaresponsebodyerrors)| -|501|[Not Implemented](https://tools.ietf.org/html/rfc7231#section-6.6.2)|Function not implemented, such as a missing protocol feature or not implemented blockchain|[responseBodyErrors](#schemaresponsebodyerrors)| |503|[Service Unavailable](https://tools.ietf.org/html/rfc7231#section-6.6.4)|Function currently not available, such as unavailable blockchain connection|[responseBodyErrors](#schemaresponsebodyerrors)| -

    Response Schema

    +

    Response Schema

    -## getMessageSequence +## validateMessage - + -`GET /messages/sequence` +`POST /message/validate` -Returns an array with the Whiteflag messages in a sequence starting with the message with the given transaction hash. This operation may be disabled in the configuration. +Validates the format and reference of a Whiteflag message and returns the result. Typically used for validation and testing, because this is automatically done for incoming and outgoing messages. This operation may be disabled in the configuration. -

    Parameters

    +> Body parameter + +```json +{ + "MetaHeader": null, + "MessageHeader": null, + "MessageBody": null +} +``` + +

    Parameters

    |Name|In|Type|Required|Description| |---|---|---|---|---| -|transactionHash|query|string|false|The hash of a blockchain transaction| -|blockchain|query|string|false|The name of a blockchain| +|body|body|[wfMessage](#schemawfmessage)|false|Whiteflag message to be send, encoded/ecrypted, or validated| > Example responses @@ -605,29 +665,25 @@ Returns an array with the Whiteflag messages in a sequence starting with the mes "string" ] }, - "data": [ - { - "MetaHeader": null, - "MessageHeader": null, - "MessageBody": null - } - ] + "data": { + "MetaHeader": null, + "MessageHeader": null, + "MessageBody": null + } } ``` -

    Responses

    +

    Responses

    |Status|Meaning|Description|Schema| |---|---|---|---| -|200|[OK](https://tools.ietf.org/html/rfc7231#section-6.3.1)|Successfully processed Whiteflag message query or blockchain scan and returning an array of messages|Inline| +|200|[OK](https://tools.ietf.org/html/rfc7231#section-6.3.1)|Successfully processed the Whiteflag message and returning the message with updated MetaHeader|Inline| |400|[Bad Request](https://tools.ietf.org/html/rfc7231#section-6.5.1)|Invalid request, typically because of a malformed syntax or protocol error|[responseBodyErrors](#schemaresponsebodyerrors)| |401|[Unauthorized](https://tools.ietf.org/html/rfc7235#section-3.1)|Authentication is required and was either not provided or has failed|[responseBodyErrors](#schemaresponsebodyerrors)| |403|[Forbidden](https://tools.ietf.org/html/rfc7231#section-6.5.3)|Request is not allowed, typically because the operation is disabled in the configuration|[responseBodyErrors](#schemaresponsebodyerrors)| |500|[Internal Server Error](https://tools.ietf.org/html/rfc7231#section-6.6.1)|Internal error preventing the running API instance to process the request|[responseBodyErrors](#schemaresponsebodyerrors)| -|501|[Not Implemented](https://tools.ietf.org/html/rfc7231#section-6.6.2)|Function not implemented, such as a missing protocol feature or not implemented blockchain|[responseBodyErrors](#schemaresponsebodyerrors)| -|503|[Service Unavailable](https://tools.ietf.org/html/rfc7231#section-6.6.4)|Function currently not available, such as unavailable blockchain connection|[responseBodyErrors](#schemaresponsebodyerrors)| -

    Response Schema

    +

    Response Schema

    +

    Accounts

    + +Endpoints for operations related to a specific blockchain accounts, such as creating, updating and deleting accounts. + ## getAccounts @@ -1373,7 +1434,7 @@ HTTP Authentication -`POST /originators/tokens` +`POST /tokens` Stores a unique pre-shared secret authentication token together with the provided Whiteflag originator data, used for authentication method 2. This operation may be disabled in the configuration. @@ -1448,7 +1509,7 @@ HTTP Authentication -`GET /originators/tokens/{authTokenId}` +`GET /tokens/{authTokenId}` Checks for the existence of a pre-shared secret authentication token and originator data with the specified token id. This data is used for authentication method 2. This operation may be disabled in the configuration. @@ -1501,7 +1562,7 @@ HTTP Authentication -`DELETE /originators/tokens/{authTokenId}` +`DELETE /tokens/{authTokenId}` Deletes the pre-shared secret authentication token and originator data with the specified token id. This data is used for authentication method 2. Please BE CAREFUL as the authentication token will be unrecoverably deleted. This operation may be disabled in the configuration. @@ -1550,13 +1611,13 @@ To perform this operation, you must be authenticated by means of one of the foll HTTP Authentication -## createToken +## verifyToken - + -`POST /token/create` +`POST /token/verify` -Creates the non-secret Whiteflag verification token for the provided pre-shared secret authentication token used for authentication method 2. The verification token is to be used in, or to validate, the `VerificationData` field of an `A2` authentication message. This operation may be disabled in the configuration. +Returns the non-secret Whiteflag verification data for the provided pre-shared secret authentication token used for authentication method 2. The verification token is to be used in, or to validate, the `VerificationData` field of an `A2` authentication message. This operation may be disabled in the configuration. > Body parameter @@ -1568,7 +1629,7 @@ Creates the non-secret Whiteflag verification token for the provided pre-shared } ``` -

    Parameters

    +

    Parameters

    |Name|In|Type|Required|Description| |---|---|---|---|---| @@ -1607,7 +1668,7 @@ Creates the non-secret Whiteflag verification token for the provided pre-shared } ``` -

    Responses

    +

    Responses

    |Status|Meaning|Description|Schema| |---|---|---|---| @@ -1619,7 +1680,7 @@ Creates the non-secret Whiteflag verification token for the provided pre-shared |501|[Not Implemented](https://tools.ietf.org/html/rfc7231#section-6.6.2)|Function not implemented, such as a missing protocol feature or not implemented blockchain|[responseBodyErrors](#schemaresponsebodyerrors)| |503|[Service Unavailable](https://tools.ietf.org/html/rfc7231#section-6.6.4)|Function currently not available, such as unavailable blockchain connection|[responseBodyErrors](#schemaresponsebodyerrors)| -

    Response Schema

    +

    Response Schema