central-settlements

The Central Settlements service is part of the Mojaloop project and deployment.

The central settlements service exposes Settlement API to manage the settlements between FSPs and the Central Hub. The service manages Settlement Windows and Settlements Event Triggers and provides information about FSPs accounts and settlements.

Contents:

• central-settlements
  • Contents:
  • Deployment
  • Configuration
  • Environmental variables
  • API
  • Logging
  • Tests
    • Running Integration Tests interactively
  • Auditing Dependencies
  • Container Scans

Deployment

TBA

Configuration

Currently the only configuration, necessary is kept here

Environmental variables

Most settings are taken from the config file. The one exception is the error mapping flag below.

ERROR_HANDLING_AJV_JOI_PARITY

Set ERROR_HANDLING_AJV_JOI_PARITY=true for this service.

The API was migrated from hapi-openapi (joi request validation) to openapi-backend (ajv), and @mojaloop/central-services-error-handling was updated from 13.1.6 to 13.2.0. 13.2.0 makes the ajv mapping that matches joi's opt-in behind this environment variable (central-services-error-handling#216), so leaving it unset changes the FSPIOP error code this service returns for requests that used to fail joi validation:

ajv keyword (openapi-backend)	unset / false	ERROR_HANDLING_AJV_JOI_PARITY=true	joi (before the migration)
enum, const, format, pattern	3100 Generic validation error	3101 Malformed syntax	3101 Malformed syntax
type	3101 Malformed syntax	3101 Malformed syntax	3101 Malformed syntax
required	3102 Missing mandatory element	3102 Missing mandatory element	3102 Missing mandatory element
additionalProperties	3103 Too many elements	3103 Too many elements	3103 Too many elements

Why it matters here: src/interface/swagger.json constrains the settlement window and settlement state query parameters with enum (OPEN, CLOSED, PENDING_SETTLEMENT, ...), the settlement update payload state with enum (ABORTED, INVALID), and fromDateTime/toDateTime with format: date-time. Those requests returned 3101 before the migration; with the flag unset they return 3100.

With the flag set, both errorInformation.errorCode and the errorDescription prefix (Malformed syntax - ...) match the pre-migration responses. The detail after the dash is generated by ajv and is worded differently to joi's.

The variable is read from process.env on every call and has no config/default.json equivalent, so set it in the service's runtime environment - the container env in the deployment values, or the environment: block of docker-compose.yml:

ERROR_HANDLING_AJV_JOI_PARITY=true

API

The Markdown version of API is available here The actual Swagger API documentation can be found here

Logging

Logs are sent to standard output by default.

Tests

Includes unit tests at the moment. Functional and integration are outstanding.

Running the tests:

npm run test:all

Tests include code coverage via istanbul. See the test/ folder for testing scripts.

Running integration tests (narrow)

npm run test:int:narrow

Running Integration Tests interactively

If you want to run integration tests in a repetitive manner, you can startup the test containers using docker-compose, login to running central-settlement container like so:

npm run docker:build && npm run docker:up

#first time only (in a new shell):
docker exec -it cs_central-ledger sh
npm run migrate

#in a new shell
docker exec -it cs_central-settlement sh
npm run test:int

Auditing Dependencies

We use audit-ci along with npm audit to check dependencies for node vulnerabilities, and keep track of resolved dependencies with an audit-ci.jsonc file.

To start a new resolution process, run:

npm run audit:fix

You can then check to see if the CI will pass based on the current dependencies with:

npm run audit:check

The audit-ci.jsonc contains any audit-exceptions that cannot be fixed to ensure that CircleCI will build correctly.

Container Scans

As part of our CI/CD process, we use anchore-cli to scan our built docker container for vulnerabilities upon release.

If you find your release builds are failing, refer to the container scanning in our shared Mojaloop CI config repo. There is a good chance you simply need to update the mojaloop-policy-generator.js file and re-run the circleci workflow.

For more information on anchore and anchore-cli, refer to:

• Anchore CLI
• Circle Orb Registry