Five Bells ledger reference implementation
npm install five-bells-ledger> 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:
`` sh`
git clone https://github.com/interledgerjs/five-bells-ledger.git
cd five-bells-ledger
` sh`
npm install
To run it using an in-memory database (the simplest option), run:
` sh`
LEDGER_ADMIN_PASS=mypassword LEDGER_DB_URI=sqlite://:memory: npm start
Or run:
`sh`
npm start
See "Environment Variables" in the generated documentation for config options.
After installation:
`sh`
npm run docs
Open apidocs-out/index.html in a web browser to see the generated API documentation.
This project can be run in a Docker container.
You need to start a postgres container:
` sh`
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:
` sh`
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
* Use the five-bells-ledger Docker image
Now open http://localhost:1337/health in your browser.
To create a user, you can run:
`sh`
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:
`sh`
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.
To run tests using an in-memory database, run:
` sh`
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:
`sh`
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:
`sh`
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.
` sh`
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:
` sh`
docker run -it --rm --name fbl-pg-test postgres
Then, in another terminal, run the tests:
` shdocker inspect --format '{{ .NetworkSettings.IPAddress }}' fbl-pg-test
LEDGER_UNIT_DB_URI=postgres://postgres@/postgres npm test``
This software is under development and no guarantees are made regarding reliability.