destenson / interledger--five-bells-connector

An implementation of an Interledger connector.

ILP Connector

A reference implementation of the ILP Connector API

Usage

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

To run the connector as a standalone server, follow these directions.

Note: You need two five-bells-ledger instances to trade between.

Step 1: Clone repo

git clone https://github.com/interledger/js-ilp-connector.git

cd js-ilp-connector

Step 2: Install dependencies

npm install

Step 3: Run it!

npm start

Configuration

General

• CONNECTOR_BIND_IP (default: 0.0.0.0) IP that ILP Connector will bind to.
• CONNECTOR_PORT (default: 4000) Port that ILP Connector will listen on.
• CONNECTOR_HOSTNAME (default: [your hostname]) Publicly visible hostname. This is important for things like generating globally unique IDs. Make sure this is a hostname that all your clients will be able to see. The default should be fine for local testing.
• CONNECTOR_PUBLIC_PORT (default: $PORT) Publicly visible port. You can set this if your public port differs from the listening port, e.g. because the connector is running behind a proxy.
• CONNECTOR_PUBLIC_HTTPS (default: '') Whether or not the publicly visible instance of ILP Connector is using HTTPS.
• CONNECTOR_LOG_LEVEL (default: info) the allowed levels in order of verbosity are fatal, error, warn, info, debug, and trace

Trading

• CONNECTOR_LEDGERS (default: []) Ledgers where this connector has accounts. Used to auto-generate CONNECTOR_PAIRS.

[
  "[email protected].",
  "[email protected]."
]

• CONNECTOR_CREDENTIALS (default: {}) Connector's login credentials for various ledgers, ex.

{
  // Using Basic Auth
  "<ledger_address>": {
    "account": "...",
    "username": "...",
    "password": "..."
    "ca": "...", // Optional
  },

  // Using Client Certificate Auth
  "<ledger_address_2>": {
    "account": "...",
    "username": "...",
    "cert": "...",
    "key": "...",
    "ca": "...", // Optional
  }
}

• CONNECTOR_PAIRS (default: [all possible combinations]) Pairs to trade on, ex.

[
  [
    '[email protected].',
    '[email protected].'
  ],[
    '[email protected].',
    '[email protected].'
  ]
]

• CONNECTOR_PEERS (default: '') Provide a basic comma-separated list of peers.

• CONNECTOR_AUTOLOAD_PEERS (default: false) Whether to automatically populate the list of peers by calling getConnectors on all ledger plugins

• CONNECTOR_FX_SPREAD (default: 0.002 =.2%) How much of a spread to add on top of the reference exchange rate. This determines the connector's margin.

• CONNECTOR_SLIPPAGE (default: 0.001 = 0.1%) The ratio for overestimating exchange rates to prevent payment failure if the rate changes.

• CONNECTOR_MIN_MESSAGE_WINDOW (default: 1) Minimum time the connector wants to budget for getting a message to the ledgers its trading on. In seconds.

• CONNECTOR_MAX_HOLD_TIME (default: 10) Maximum duration (seconds) the connector is willing to place funds on hold while waiting for the outcome of a transaction.

• CONNECTOR_AUTH_CLIENT_CERT_ENABLED (default 0) whether or not to enable TLS Client Certificate authentication (requires HTTPS).

• CONNECTOR_USE_HTTPS (default 0) whether or not to run the server using HTTPS.

• CONNECTOR_TLS_KEY (default: none) the path to the server private key file. Required if using HTTPS.

• CONNECTOR_TLS_CERTIFICATE (default: none) the path to the server certificate file. Required if using HTTPS.

• CONNECTOR_TLS_CRL (default: none) the path to the server certificate revokation list file. Optional if using HTTPS.

• CONNECTOR_TLS_CA (default: none) the path to a trusted certificate to be used in addition to using the default list. Optional if using HTTPS.

• CONNECTOR_ROUTE_BROADCAST_ENABLED (default: 1) whether or not to broadcast known routes.

• CONNECTOR_ROUTE_BROADCAST_INTERVAL (default: 30000) the frequency at which the connector broadcasts its routes to adjacent connectors.

• CONNECTOR_ROUTE_CLEANUP_INTERVAL (default: 1000) the frequency at which the connector checks for expired routes.

• CONNECTOR_ROUTE_EXPIRY (default: 45000) the maximum age of a route.

Running with Docker

This project can be run in a Docker container.

docker run -it --rm -e CONNECTOR_PORT=4000 interledger/js-ilp-connector

Breaking down that command:

• -it Run ILP Connector in an interactive terminal.
• --rm Delete container when it's done running.
• -e CONNECTOR_PORT=4000 Set the connector's port to 4000. This is just an example for how to set a config option.

Payments

The connector will facilitate an interledger payment upon receiving a notification for a transfer in which it is credited. That "source" transfer must have a ilp_header in its credit's memo that specifies the payment's destination and amount. As soon as the source transfer is prepared, the connector will authorize the debits from its account(s) on the destination ledger.