Central Ledger hosted by a scheme to record and settle transfers





GitHub Stars



Last Commit

24d ago








Type Definitions






Git Commit Git Releases Docker pulls CircleCI

The central ledger is a series of services that facilitate clearing and settlement of transfers between DFSPs, including the following functions:

  • Brokering real-time messaging for funds clearing
  • Maintaining net positions for a deferred net settlement
  • Propagating scheme-level and off-transfer fees

The following documentation represents the services, APIs and endpoints responsible for various ledger functions.


Running Locally

Please follow the instruction in Onboarding Document to setup and run the service locally.


Environment variables

The Central Ledger has many options that can be configured through environment variables.

Environment variableDescriptionExample values
CLEDG_DATABASE_URIThe connection string for the database the central ledger will use. Postgres is currently the only supported database.postgres://\:\@localhost:5432/central_ledger
CLEDG_PORTThe port the API server will run on.3000
CLEDG_ADMIN_PORTThe port the Admin server will run on.3001
CLEDG_HOSTNAMEThe URI that will be used to create and validate links to resources on the central ledger.http://central-ledger
CLEDG_ENABLE_BASIC_AUTHFlag to enable basic auth protection on endpoints that require authorization. Username and password would be the account name and password.false
CLEDG_ENABLE_TOKEN_AUTHFlag to enable token protection on endpoints that require authorization. To create a token, reference the API documentation.false
CLEDG_LEDGER_ACCOUNT_NAMEName of the account setup to receive fees owed to the central ledger. If the account doesn't exist, it will be created on start up.LedgerName
CLEDG_LEDGER_ACCOUNT_PASSWORDPassword of the account setup to receive fees owed to the central ledger.LedgerPassword
CLEDG_ADMIN_KEYKey used for admin access to endpoints that require validation.AdminKey
CLEDG_ADMIN_SECRETSecret used for admin access to endpoints that require validation. Secret also used to sign JWTs used for Admin API.AdminSecret
CLEDG_TOKEN_EXPIRATIONTime in milliseconds for Admin API tokens to expire.3600000
CLEDG_EXPIRES_TIMEOUTTime in milliseconds to determine how often transfer expiration process runs.5000
CLEDG_AMOUNT__PRECISIONNumeric value used to determine precision recorded for transfer amounts on this ledger.10
CLEDG_AMOUNT__SCALENumeric value used to determine scale recorded for transfer amounts on this ledger.2


For endpoint documentation, see the API documentation.

For help preparing and executing transfers, see the Transfer Guide


Logs are sent to standard output by default.


Tests include unit, functional, and integration.

Running the tests:

    npm run test:all

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

Running Integration Tests interactively-ish

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

docker-compose -f docker-compose.yml -f docker-compose.integration.yml up kafka mysql central-ledger

#in a new shell
docker exec -it cl_central-ledger sh
npm run migrate #first time only
npm run test:int

Auditing Dependencies

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

To start a new resolution process, run:

npm run audit:resolve

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

npm run audit:check

And commit the changed audit-resolve.json 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:

Rate & Review

Great Documentation0
Easy to Use0
Highly Customizable0
Bleeding Edge0
Responsive Maintainers0
Poor Documentation0
Hard to Use0
Unwelcoming Community0