Five Bells Wallet

• Prerequisites
• Installation
• Usage
  • Running Dev Wallet
  • Building Production Wallet
  • Running Production Wallet
  • Port Forwarding
  • Running a ledger instance in the five-bells-wallet process
  • Environment variables
• Interledger Setup
  • Hosts File
  • Database
  • Apache Virtual Hosts
  • Wallet 1 + Ledger 1 Instance
  • Wallet 2 + Ledger 2 Instance
  • Setup five-bells-connector
• Architecture
  • Backend (REST API)
    • API docs
    • SPSP
      • Webfinger
  • Client
    • Using Redux DevTools
    • Theme Customization

• Five Bells Ledger instance

git clone [email protected]:interledgerjs/five-bells-wallet.git
cd five-bells-wallet
npm install

npm run configure

You must specify the required environment variables before running below commands

Build the vendor files (run this every time package dependencies change)

npm run build-dlls 

Run a development server

npm run dev

npm run build

You must specify the required environment variables before running the below command

npm run start

In most cases it makes sense to expose the wallet through 443 (or 80) port, in which case you need to setup a port forwarding that will forward API_PORT requests to API_PUBLIC_PORT (443 or 80). Note that the port forwarding should work for both http(s) and websocket connections.

Here's an example of an Apache 2.4 virtual host with enabled port forwarding.

NOTE: Current webfinger implementation will not work if the public port is not 443 or 80.

NOTE: At the moment you need to have a 443 virtual host in addition to 80 virtual host if you're use 80 as a public port. 443 virtual host is used for the webfinger lookups. This is a reported issue in the webfinger lib used by the five-bells-wallet.

<VirtualHost *:443> 
  ServerName wallet.com
  
  RewriteEngine On
  RewriteCond %{HTTP:Connection} Upgrade [NC]
  RewriteRule /(.*) ws://wallet.com:3000/$1 [P,L]

  ProxyPass / http://wallet.com:3000/ retry=0
  ProxyPassReverse / http://wallet.com:3000/
  
  SSLEngine on
  SSLCertificateFile /etc/apache2/ssl/wallet.com.crt
  SSLCertificateKeyFile /etc/apache2/ssl/wallet.com.key
</VirtualHost> 

Unless you're hosting an external ledger, you can optionally run a five-bells-ledger instance inside the five-bells-wallet. To do so, all you need to do is leave the API_LEDGER_URI environment variable empty, and the software will automatically run a five-bells-ledger instance.

Five-bells-ledger instance comes with default environment variables, but you can change them specifying any of the five-bells-ledger environment variables.

(used if the API_LEDGER_URI is not specified). You can read more about these variables in the five-bells-ledger readme.

You might want to do an interledger setup to test interledger transfers. In this case you will need at least two wallet instances and a connector. Below is an example setup instructions for two wallets and a connector on a personal machine (development/testing use).

Edit your hosts file (/private/etc/hosts on OSX). Add these two lines

127.0.0.1   wallet1.com
127.0.0.1   wallet2.com

Create 4 postgres databases. wallet1, wallet1-ledger, wallet2, wallet2-ledger.

Note: The wallet instances are running on port 80, but we also need to setup virtual hosts on port 443 for the webfinger lookups (issue mentioned above).

<VirtualHost *:80> 
  ServerName wallet1.com

  RewriteEngine On
  RewriteCond %{HTTP:Connection} Upgrade [NC]  
  RewriteRule /(.*) ws://wallet1.com:3010/$1 [P,L]

  ProxyPass / http://wallet1.com:3010/ retry=0
  ProxyPassReverse / http://wallet1.com:3010/  
</VirtualHost> 

<VirtualHost *:443> 
  ServerName wallet1.com
  ProxyPass / http://wallet1.com:3010/ retry=0
  ProxyPassReverse / http://wallet1.com:3010/
  RedirectMatch ^/$ https://wallet1.com
  
  SSLEngine on
  SSLCertificateFile /etc/apache2/ssl/wallet1.com.crt
  SSLCertificateKeyFile /etc/apache2/ssl/wallet1.com.key
</VirtualHost>

<VirtualHost *:80> 
  ServerName wallet2.com

  RewriteEngine On
  RewriteCond %{HTTP:Connection} Upgrade [NC]
  RewriteRule /(.*) ws://wallet2.com:3020/$1 [P,L]

  ProxyPass / http://wallet2.com:3020/ retry=0
  ProxyPassReverse / http://wallet2.com:3020/
</VirtualHost> 

<VirtualHost *:443> 
  ServerName wallet2.com
  ProxyPass / http://wallet2.com:3020/ retry=0
  ProxyPassReverse / http://wallet2.com:3020/
  RedirectMatch ^/$ https://wallet2.com
  
  SSLEngine on
  SSLCertificateFile /etc/apache2/ssl/wallet2.com.crt
  SSLCertificateKeyFile /etc/apache2/ssl/wallet2.com.key
</VirtualHost> 

Note: You can use self signed certificates.

Run with these environment variables

API_PRIVATE_HOSTNAME=localhost
API_HOSTNAME=wallet1.com
API_PORT=3100
API_PUBLIC_PORT=80 
API_PUBLIC_PATH=/api 
API_DB_URI=postgres://localhost/wallet1
API_LEDGER_ADMIN_NAME=admin
API_LEDGER_ADMIN_PASS=admin
API_RELOAD=true
CLIENT_HOST=wallet1.com
CLIENT_PORT=3010
CLIENT_PUBLIC_PORT=80
API_SECRET=qO2UX+fdl+tg0a1bYtXoBVQHN4pkn2hFB5Ont6CYj50=
LEDGER_ILP_PREFIX=wallet1.

Note: Use LEDGER_DB_SYNC=true environment variable for both wallet1 and wallet2 to create the ledger db tables first time when you run each of the instances.

Run with these environment variables

API_PRIVATE_HOSTNAME=localhost
API_HOSTNAME=wallet2.com
API_PORT=3200
API_PUBLIC_PORT=80 
API_PUBLIC_PATH=/api 
API_DB_URI=postgres://localhost/wallet2
API_LEDGER_ADMIN_NAME=admin
API_LEDGER_ADMIN_PASS=admin
API_RELOAD=true
CLIENT_HOST=wallet2.com
CLIENT_PORT=3020
CLIENT_PUBLIC_PORT=80
API_SECRET=qO2UX+fdl+tg0a1bYtXoBVQHN4pkn2hFB5Ont6CYj50=
LEDGER_ILP_PREFIX=wallet2.

Note: five-bells-wallet currently works with five-bells-connector v8.1.0

• Create a trader user on both wallet1 and wallet2 instances with username: trader, password: trader.

Environment Variables

CONNECTOR_HOSTNAME=localhost
CONNECTOR_PORT=5000
CONNECTOR_LEDGERS='["USD@http://wallet1.com/ledger","EUR@http://wallet2.com/ledger"]' CONNECTOR_PAIRS='[["USD@http://wallet1.com/ledger", "EUR@http://wallet2.com/ledger"],["EUR@http://wallet2.com/ledger", "USD@http://wallet1.com/ledger"]]'
CONNECTOR_ADMIN_USER=admin 
CONNECTOR_ADMIN_PASS=admin 
CONNECTOR_CREDENTIALS='{"http://wallet1.com/ledger":{"account_uri":"http://wallet1.com/ledger/accounts/trader","username":"trader","password":"trader"},"http://wallet2.com/ledger":{"account_uri":"http://wallet2.com/ledger/accounts/trader","username":"trader","password":"trader"}}'
CONNECTOR_QUOTE_FULL_PATH=true

Five Bells Wallet consists of a Node.js (developed on v5.6) backend (REST API) and a client built using React.

The backend is responsible for communicating with the ILP ledger, creating accounts, sending payments and keeping the payment history.

http://interledger.org/five-bells-wallet/apidoc

The wallet implements SPSP for initiating and receiving payments.

Webfinger is used to lookup account/user identifiers.

Example request

curl -X GET
https://wallet.example/.well-known/webfinger?resource=acct:[email protected]

Example response

HTTP/1.1 200 OK
{
  "subject": "acct:[email protected]",
  "links": [
    {
      "rel": "https://interledger.org/rel/ledgerUri",
      "href": "https://red.ilpdemo.org/ledger"
    },
    {
      "rel": "https://interledger.org/rel/socketIOUri",
      "href": "https://red.ilpdemo.org/api/socket.io"
    },
    {
      "rel": "https://interledger.org/rel/ledgerAccount",
      "href": "https://red.ilpdemo.org/ledger/accounts/alice"
    },
    {
      "rel": "https://interledger.org/rel/sender/payment",
      "href": "https://red.ilpdemo.org/api/payments"
    },
    {
      "rel": "https://interledger.org/rel/sender/pathfind",
      "href": "https://red.ilpdemo.org/api/payments/findPath"
    },
    {
      "rel": "https://interledger.org/rel/receiver",
      "href": "https://red.ilpdemo.org/api/receivers/alice"
    }
  ]
}

The client is a web app built on React that implements user signup/signin, sending payments and payment history.

Client state management is handled by Redux.

In development, Redux Devtools are enabled by default. You can toggle visibility and move the dock around using the following keyboard shortcuts:

• Ctrl+H Toggle DevTools Dock
• Ctrl+Q Move Dock Position
• see redux-devtools-dock-monitor for more detail information.

npm install generates a src/theme/variables.scss which contains the theme colors. You can manually edit it.

Database has two tables: Users and Payments.