Open-source reference ledger optimized for use with the Interledger protocol
JavaScript PLpgSQL Shell
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.
docs docs: update with new cc format example Mar 1, 2017
scripts fix #207 (comment) Jun 13, 2017
src fix: update ws (#438) Feb 9, 2018
test feat: add GET /fulfillment2 Nov 23, 2017
.eslintignore [TEST] Run integration test module. Feb 23, 2016
.eslintrc [TASK] Switch to JavaScript Standard Style. Jul 12, 2015
.gitignore chore: auto-update gh-pages May 26, 2016
.npmignore [FIX] Add .npmignore Oct 15, 2015 chore: update license Nov 2, 2016
Dockerfile build: run npm install during docker build (#423) May 19, 2017
LICENSE docs: fix instructions for specifying admin pass Jul 31, 2017
apidoc.json feat: remove byExecutionCondition endpoint Mar 1, 2017
circle.yml chore: update dependencies (esp. koa 2) Apr 13, 2017
dockercfg-template [TASK] Prepare for publication Oct 31, 2015
npmrc-env [FIX] Fix Docker build with new NPM private module. May 21, 2015
package-lock.json 21.2.5 Mar 6, 2018
package.json 21.2.5 Mar 6, 2018
wallaby.js [FIX] Better way to integrate co-mocha with Wallaby. Nov 25, 2015
yarn.lock chore: update dependencies (esp. koa 2) Apr 13, 2017

Five Bells Ledger npm circle codecov Known Vulnerabilities

A reference implementation of the Five Bells Ledger API


You can see the ledger in action as part of the five-bells-demo!

To run the ledger as a standalone server:

Step 1: Clone repo

git clone
cd five-bells-ledger

Step 2: Install dependencies

npm install

Step 3: Run it!

To run it using an in-memory database (the simplest option), run:

LEDGER_ADMIN_PASS=mypassword LEDGER_DB_URI=sqlite://:memory: npm start

Or run:

npm start

See "Environment Variables" in the generated documentation for config options.

Building Docs

After installation:

npm run docs

Open apidocs-out/index.html in a web browser to see the generated API documentation.

Running with Docker (Alternative Method)

This project can be run in a Docker container.

You need to start a postgres container:

docker run --name five-bells-ledger-db -e POSTGRES_PASSWORD=password -d postgres

After giving postgres a few seconds to start up, you can run a five-bells-ledger Docker container, linking to that database:

docker run -d -e LEDGER_PORT=1337 -e LEDGER_ADMIN_PASS=admin -e LEDGER_DB_URI=postgres://postgres:password@db --link five-bells-ledger-db:db -p 1337:1337 -h localhost --name fivebells interledger/five-bells-ledger

Breaking down that command:

  • -d Run in the background
  • -e LEDGER_PORT=1337 Set the ledger's port to 1337. This is just an example for how to set a config option.
  • -e LEDGER_ADMIN_PASS=admin Create an "admin" user with password "admin" at startup
  • -e LEDGER_DB_URI=postgres://postgres:password@db Set the database URL. Here, 'db' is a host that is Docker-linked:
  • --link five-bells-ledger-db:db This allows Five Bells Ledger to see the database that we set up above.
  • -p 1337:1337 Expose port 1337 to localhost
  • -h localhost makes the ledger use 'localhost' as its hostname in the endpoint URLs it announces
  • --name fivebells This allows you to refer to this container in for instance docker inspect fivebells
  • interledger/five-bells-ledger Use the five-bells-ledger Docker image

Now open http://localhost:1337/health in your browser.

To create a user, you can run:

curl -i -sS -X PUT --user admin:admin -H "Content-Type: application/json" -d'{ "name" : "alice", "password" : "alice", "balance" : "20000" }' http://localhost:1337/accounts/alice

To see the database contents, you can create a postgres container that interactively runs psql:

docker run -it --rm --link five-bells-ledger-db:db postgres psql postgres://postgres:password@db

You can then use ilp-plugin-bells to develop a client that connects to this ledger. Make sure you use the matching plugin version to connect to the ledger.

In particular, ledger version 20 can be accessed using ilp-plugin-bells version 12.

Running tests

To run tests using an in-memory database, run:

npm test

By default, stdout from the app process is buffered up, and only shown after a test fails. That way, you can easily debug a failing test:

DEBUG=ledger:* npm test

If you want to see the output for passing tests as well, and not buffered until the test is over, use the SHOW_STDOUT environment variable for this:

SHOW_STDOUT=true DEBUG=ledger:transfers npm test

If you wish to specify the database against which the tests are run, use the LEDGER_UNIT_DB_URI environment variable.

LEDGER_UNIT_DB_URI=postgres://root:password@localhost:5432/ledger_test_db npm test

For example, to run against a Postgres instance in Docker, first start the database server:

docker run -it --rm --name fbl-pg-test postgres

Then, in another terminal, run the tests:

LEDGER_UNIT_DB_URI=postgres://postgres@`docker inspect --format '{{ .NetworkSettings.IPAddress }}' fbl-pg-test`/postgres npm test

A word of warning

This software is under development and no guarantees are made regarding reliability.