Awesome

ILP Connector

A reference implementation of the ILP Connector

Overview
- What is this?
- Who is this for?
Quickstart
Guides
Reference
Development

Overview

What is this?

This is a JavaScript reference implementation of an Interledger connector. Find out more about the Interledger architecture and Interledger protocol.

An Interledger connector forwards Interledger packets, just like an Internet router forward Internet packets. The difference is that Interledger packets represent value in addition to data. Interledger connectors do not actually move the money, they rely on plugins for settlement. Plugins may settle by making a payment on an external payment system like ACH or they may use payments channels over a digital asset ledger like XRP Ledger or Bitcoin. Some plugins may not settle at all - this is useful for example when the plugin connects two hosts owned by the same person.

Who is this for?

Just like IP routers can be found anywhere from your home wifi router to a small business network to the large Internet backbones, an Interledger connector is a versatile component that appears in a lot of different context. Here are some example use cases:

Your personal connector

You could be a developer who runs an Interledger connector so you can point all of your apps to it. This would allow you to change Interledger providers just by reconfiguring your connector without having to update the credentials in every single one of your apps.

It also gives you a single place to manage your money. This version of the connector is pretty rudimentary, but in the future it will be able to tell you which app spent how much and when they sent it, how much each app earned etc.

The heart of an Interledger Service Provider (ILSP)

An Interledger Service Provider (ILSP) is the Interledger equivalent of an Internet Service Provider (ISP). It's an entity that provides access to the Interledger network for its users.

Each ILSP needs to have one or more connectors to route the ILP packets from its customers to the Interledger and vice versa.

Some ILSPs are simply customers of a larger ILSP. Others are so-called tier-1 ILSPs. Tier-1 ILSPs have a special responsibility, they provide routing services for the network.

This implementation of the connector contains a routing protocol implementation for tier-1 connectors. Please note that in order to become a tier-1 connector you need to have a relationship with one or more existing tier-1 connectors and they need to trust you not to overwhelm them with traffic or harbor malicious customers on your network.

Timekeeping

Timekeeping is an important part of processing transactions. Your node must have the right time set to make sure it can handle packets from peers correctly. If you drift too far from the current time, your node will have a different time to your peers and might start to experience strange issues and/or accept/reject packets incorrectly.

It is highly recommended you run some kind of time synchronisation service on your server. If you need help to install tools for keeping your clock in sync, this article describes how to do it: https://www.techrepublic.com/blog/data-center/syncing-time-in-linux-and-windows-with-ntp/

Quickstart

npm install -g ilp-connector ilp-plugin-btp
CONNECTOR_STORE_PATH=~/.connector-data CONNECTOR_ACCOUNTS='{}' CONNECTOR_ADMIN_API=true CONNECTOR_ILP_ADDRESS=test.quickstart ilp-connector

You are now running a connector!

What's next?

Connect your connector to the Interledger
Allow your apps to connect to your connector
Embed a connector in another JavaScript app
Create a tier-1 connector
Run the connector in Docker

Guides

Connect your connector to the Interledger

In order to connect your connector to the Interledger, you need to configure a plugin representing your account with an Interledger Service Provider (ILSP).

You will configure this plugin as a parent plugin, which means that your connector will automatically fetch its ILP address from this ILSP and send all its traffic through it. Your ILSP will tell you the other settings you need to use.

From here on your configuration will get more complicated. So let's use the PM2 process manager, which allows us to specify our configuration in one tidy JavaScript config file.

launch.config.js

'use strict'

const path = require('path')

const parentConnector = {
  // This tells our connector that this is our main upstream link which will
  // automatically make it our default route and load our ILP address from it.
  relation: 'parent',
  assetScale: 6,
  assetCode: 'XRP',
  plugin: 'ilp-plugin-xrp-asym',
  options: {

  }
}

const connectorApp = {
  name: 'connector',
  env: {
    // The one-to-one backend will use an exchange rate of 1:1 for everything
    CONNECTOR_BACKEND: 'one-to-one',

    // We don't want to charge any fee
    CONNECTOR_SPREAD: '0',

    // Where is our database stored
    CONNECTOR_STORE_PATH: '/home/bob/connector',

    // Configure our plugins
    CONNECTOR_ACCOUNTS: JSON.stringify({
      // `up` is an arbitrary name we give to our parent connector
      up: parentConnector
    })
  },
  script: path.resolve(process.execPath, '../../lib/node_modules/ilp-connector/dist/index.js')
}

module.exports = { apps: [ connectorApp ] }

Now we can run our connector with:

npm install -g pm2
pm2 start launch.config.js

Run the connector in Docker

This project can be run in a Docker container.

docker run -it --rm -e CONNECTOR_SPREAD='0.005' interledgerjs/ilp-connector

Breaking down that command:

-it Run ILP Connector in an interactive terminal.
--rm Delete container when it's done running.
-e CONNECTOR_SPREAD='0.005' Set the connector's spread to 0.5%. This is an example for how to pass configuration to the connector.

Reference

Configuration Variables

`env`

Environment: CONNECTOR_ENV
Type: string
Default: "test"

Determines what type of network the connector is a part of. Can be: 'production', 'test'. Default: 'test'

`ilpAddress`

Environment: CONNECTOR_ILP_ADDRESS
Type: string
Default: "unknown"

ILP address of the connector. This property can be omitted if an account with relation=parent is configured under accounts.

`ilpAddressInheritFrom`

Environment: CONNECTOR_ILP_ADDRESS_INHERIT_FROM
Type: string
Default: ""

If there are multiple parents, and ilpAddress is not set explicit, specify the account ID of the parent that we should load our address from. Defaults to the first parent in the accounts map.

`accounts`

Environment: CONNECTOR_ACCOUNTS
Type: object
Default: {}

Name	Type	Description
`*`	object	Description of individual account.
`*.relation`	string	Relationship between the connector and the counterparty that the account is with.
`*.plugin`	string	Name or instance of the ILP plugin that should be used for this account. A plugin instance can only be passed when instantiating the connector from JavaScript.
`*.assetCode`	string	Currency code or other asset identifier that will be passed to the backend to select the correct rate for this account.
`*.assetScale`	integer	Interledger amounts are integers, but most currencies are typically represented as fractional units, e.g. cents. This property defines how many Interledger units make up one regular units. For dollars, this would usually be set to 9, so that Interledger amounts are expressed in nanodollars.
`*.balance`	object	Optional Defines whether the connector should maintain and enforce a balance for this account. The balance is always from the connector's perspective. Therefore, a negative balance implies the connector owes money to the counterparty and a positive balance implies the counterparty owes money to the connector. This setting is enforced by the built-in `balance` middleware.
`*.balance.maximum`	string	Maximum balance (in this account's indivisible base units) the connector will allow. The connector will reject incoming packets if they would put it above this balance. The format is a string containing an integer (which may be prefixed with `-` to indicate a negative value), `"-Infinity"` or `"Infinity"`.
`*.balance.minimum`	string	Optional Minimum balance (in this account's indivisible base units) the connector must maintain. The connector will reject outgoing packets if they would put it below this balance. The format is a string containing an integer (which may be prefixed with `-` to indicate a negative value), `"-Infinity"` or `"Infinity"`.
`*.balance.settleThreshold`	string	Optional Balance (in this account's indivisible base units) numerically below which the connector will automatically initiate a settlement. The format is a string containing an integer (which may be prefixed with `-` to indicate a negative value) or `"-Infinity"`.
`*.balance.settleTo`	string	Optional Balance (in this account's indivisible base units) the connector will attempt to reach when settling. The format is an integer (which may be prefixed with `-` to indicate a negative value) as a string.
`*.deduplicate.cleanupInterval`	integer	Optional Frequency at which the connector removes old deduplicate records. (in milliseconds; defaults to 30 seconds)
`*.deduplicate.packetLifetime`	integer	Optional Lifetime of a cache record. (in milliseconds; defaults to 30 seconds)
`*.ilpAddressSegment`	string	Optional What segment will be appended to the connector's ILP address to form this account's ILP address. Only applicable to accounts with `relation=child`. Defaults to the id of the account, i.e. the key used in the `accounts` config object.
`*.maxPacketAmount`	string	Optional Maximum amount per packet for incoming prepare packets. Connector will reject any incoming prepare packets from this account with a higher amount. Amount should be provided as an integer in a string (in atomic units). This setting is enforced by the built-in `maxPacketAmount` middleware.
`.options.`	object	Optional
`*.rateLimit`	object	Optional Maximum rate of incoming packets. Limit is implemented as a token bucket with a constant refill rate. When the token bucket is empty, all requests are immediately rejected. This setting is enforced by the built-in `rateLimit` middleware.
`*.rateLimit.capacity`	integer	Optional Maximum number of tokens in the bucket.
`*.rateLimit.refillCount`	integer	Optional How many tokens are refilled per period. The default refill period is one second, so this would be the average number of requests per second.
`*.rateLimit.refillPeriod`	integer	Optional Length of time (in milliseconds) during which the token balance increases by `refillCount` tokens. Defaults to one second.
`*.receiveRoutes`	boolean	Optional Whether we should receive and process route broadcasts from this peer. Defaults to `false` for `relation=child` and `true` otherwise.
`*.sendRoutes`	boolean	Optional Whether we should broadcast routes to this peer. Defaults to `false` for `relation=child` and `true` otherwise.
`*.throughput`	object	Optional Configuration to limit the total amount sent via Interledger per unit of time. This setting is enforced by the built-in `throughput` middleware.
`*.throughput.incomingAmount`	string	Optional Maximum incoming throughput amount (in atomic units; per second) for incoming packets. If this setting is not set, the incoming throughput limit is disabled.
`*.throughput.outgoingAmount`	string	Optional Maximum throughput amount (in atomic units; per second) for outgoing packets. If this setting is not set, the outgoing throughput limit is disabled.
`*.throughput.refillPeriod`	integer	Optional Length of time (in milliseconds) during which the token balance increases by `incomingAmount`/`outgoingAmount` tokens. Defaults to one second.

`defaultRoute`

Environment: CONNECTOR_DEFAULT_ROUTE
Type: string
Default: "auto"

Which account should be used as the default route for all other traffic. Can be set to empty string to disable the default route or 'auto' to automatically use the first parent in the accounts map. Default: 'auto'

`routes`

Environment: CONNECTOR_ROUTES
Type: array
Default: []

Name	Type	Description
`[]`	object	Description of a route entry.
`[].targetPrefix`	string	ILP address prefix that this route applies to. Configured routes take precedence over the same or shorter prefixes that are local or published by peers. More specific prefixes will still take precedence. Prefixes should NOT include a trailing period.
`[].peerId`	string	ID of the account that destinations matching `targetPrefix` should be forwarded to. Must be one of the accounts in `accounts`.

`spread`

Environment: CONNECTOR_SPREAD
Type: number
Default: 0.002

How much of a spread to add on top of the reference exchange rate. Determines the connector's margin.

`minMessageWindow`

Environment: CONNECTOR_MIN_MESSAGE_WINDOW
Type: integer
Default: 1000

Minimum time the connector wants to budget for getting a message to the accounts its trading on. In milliseconds.

`maxHoldTime`

Environment: CONNECTOR_MAX_HOLD_TIME
Type: integer
Default: 30000

Maximum duration (in milliseconds) the connector is willing to place funds on hold while waiting for the outcome of a transaction.

`routeBroadcastEnabled`

Environment: CONNECTOR_ROUTE_BROADCAST_ENABLED
Type: boolean
Default: true

Whether to broadcast known routes.

`routeBroadcastInterval`

Environment: CONNECTOR_ROUTE_BROADCAST_INTERVAL
Type: integer
Default: 30000

Frequency at which the connector broadcasts its routes to adjacent connectors. (in milliseconds)

`routeCleanupInterval`

Environment: CONNECTOR_ROUTE_CLEANUP_INTERVAL
Type: integer
Default: 1000

The frequency at which the connector checks for expired routes. (in milliseconds)

`routeExpiry`

Environment: CONNECTOR_ROUTE_EXPIRY
Type: integer
Default: 45000

The maximum age of a route provided by this connector. (in milliseconds)

`routingSecret`

Environment: CONNECTOR_ROUTING_SECRET
Type: string
Default: ""

Seed used for generating routing table auth values.

`backend`

Environment: CONNECTOR_BACKEND
Type: string
Default: "ecb"

Name of the backend (can be built-in or a require-able module name). Built-in modules are: ecb, ecb-plus-xrp, ecb-plus-coinmarketcap, one-to-one

`backendConfig`

Environment: CONNECTOR_BACKEND_CONFIG
Type: object
Default: {}

Additional configuration for the backend.

`store`

Environment: CONNECTOR_STORE
Type: string
Default: "memory"

Name of the store (can be built-in or a require-able module name). Built-in modules are: memory

`storePath`

Environment: CONNECTOR_STORE_PATH
Type: string
Default: ""

Shorthand for config.storeConfig.path.

`storeConfig`

Environment: CONNECTOR_STORE_CONFIG
Type: object
Default: {}

Additional options to be passed to the store's constructor.

`middlewares`

Environment: CONNECTOR_MIDDLEWARES
Type: object
Default: {}

Name	Type	Description
`*`	object	Object describing middleware instance.
`*.type`	string	NPM module that should be `require`d to load the middleware constructor.
`.options.`	object	Optional

`disableMiddleware`

Environment: CONNECTOR_DISABLE_MIDDLEWARE
Type: array
Default: []

Name	Type	Description
`[]`	string	Name of the middleware to be removed.

`reflectPayments`

Environment: CONNECTOR_REFLECT_PAYMENTS
Type: boolean
Default: true

Whether to allow routing payments back to the account that sent them.

`initialConnectTimeout`

Environment: CONNECTOR_INITIAL_CONNECT_TIMEOUT
Type: integer
Default: 10000

How long the connector should wait for account plugins to connect before launching other subsystems. (in milliseconds)

`adminApi`

Environment: CONNECTOR_ADMIN_API
Type: boolean
Default: false

Whether the admin API is enabled or not. Default: false (disabled)

`adminApiPort`

Environment: CONNECTOR_ADMIN_API_PORT
Type: integer
Default: 7780

Which port the admin API should listen on. Default: 7780

`adminApiHost`

Environment: CONNECTOR_ADMIN_API_HOST
Type: string
Default: "127.0.0.1"

Host to bind to. Warning: The admin API interface should never be made public! Default: '127.0.0.1'

`collectDefaultMetrics`

Environment: CONNECTOR_COLLECT_DEFAULT_METRICS
Type: boolean
Default: false

Whether the Prometheus exporter should include system metrics or not. Default: false (no)

API Reference

Extensibility: Plugins

Plugins represent different ways to link senders, receivers and connectors together. Most plugins use Bilateral Transfer Protocol (BTP) in order to communicate. The main differences between plugins are whether they are multi-user and which settlement ledger they use.

Multi-user plugins are plugins which connect to multiple counterparties, rather than just one. They are usually used as server-side plugins to serve a large number of clients. An example is ilp-plugin-mini-accounts. Multi-user plugins actually contain a little mini connector internally which knows how to route packets to the correct client.

Plugins implement the Ledger Plugin Interface (LPI). To write your own plugin, consider extending ilp-plugin-btp for single-user plugins and ilp-plugin-mini-accounts for multi-user plugins. Check the list below for plugins you can copy as a starting point.

ilp-plugin-btp

Multi-user: No
Settlement: None
Github: interledgerjs/ilp-plugin-btp
NPM: ilp-plugin-btp

Plain BTP plugin, used to connect two parties without settling. Often used as a client for ilp-plugin-mini-accounts.

ilp-plugin-mini-accounts

Multi-user: Yes
Settlement: None
Github: interledgerjs/ilp-plugin-mini-accounts
NPM: ilp-plugin-mini-accounts

Plain BTP multi-user plugin. You could run mini-accounts on your connector and then connect all of your own clients to it.

ilp-plugin-xrp-paychan

Multi-user: No
Settlement: XRP Payment Channels
Github: interledgerjs/ilp-plugin-xrp-paychan
NPM: ilp-plugin-xrp-paychan

Basic plugin for peering with settlement over XRP payment channels.

ilp-plugin-lightning

Multi-user: No
Settlement: Lightning Network
Github: interledgerjs/ilp-plugin-lightning
NPM: ilp-plugin-lightning

ILP peering using settlement over Lightning.

Extensibility: Stores

Stores represent different means for persistence for the connector.

Built-in: memory

Pure in-memory store. Resets every time the connector is run. Useful for development and testing.

Extensibility: Middlewares

Built-in: errorHandler

Pipelines: incomingData, incomingMoney

First middleware in the pipeline. Handles any errors that occur anywhere else and converts them into ILP rejections.

The errorHandler middleware will check the thrown error for a field called ilpErrorCode which should contain a three-character ILP error code. Otherwise it uses 'F00' by default. For the message it uses the error message and for triggeredBy the connector's address. If the error object has a field ilpErrorData which is a Buffer, it will also attach the provided data to the error. Otherwise, it will attach an empty data buffer.

Built-in: deduplicate

Pipelines: startup, teardown, outgoingData

Prevents sending duplicate packets which helps reduce the impact of routing loops.

This middleware keeps track of all prepared transfers. If there is a transfer with the same destination, executionCondition, data and an equal or greater amount and expiresAt already prepared, then we simply link the new packet to the existing packet's outcome. If a packet is being routed in a loop, it will fulfill these requirements, the loop will be terminated, and the packet will time out.

Built-in: rateLimit

Pipelines: incomingData, incomingMoney, outgoingData, outgoingMoney

Reduces the maximum number of total requests incoming from or outgoing to any account.

Used for basic rate limiting and to help with DoS.

Built-in: maxPacketAmount

Pipelines: incomingData, outgoingData

Rejects packets with an amount greater than the specified value.

Built-in: throughput

Pipelines: incomingData, outgoingData

Limits the throughput for a given account. Throughput is the amount of money transferred per time.

Built-in: balance

Pipelines: startup, incomingData, incomingMoney, outgoingData, outgoingMoney

Tracks the balance of a given account from the perspective of the connector. This is also the subsystem that triggers settlements.

Built-in: validateFulfillment

Pipelines: outgoingData

Validates fulfillments in incoming ILP fulfill responses. If the fulfillment is invalid, it converts the fulfillment into a rejection.

Built-in: echo

Pipelines: incomingData

The ECHO protocol enables a bidirectional test of connectivity between an initiator and a recipient. The middleware handles "ping" packets and forwards a corresponding "pong" packet to a new destination address.

Built-in: expire

Pipelines: outgoingData

Expires outgoing ILP packets at their designated expiresAt time. Returns a rejection when this occurs.

Built-in: stats

Pipelines: incomingData, incomingMoney, outgoingData, outgoingMoney

Tracks throughput by account. Results are accessible through the admin API.

Extensibility: Backends

Backends provide fee policies and exchange rates. For a professionally run connector, just should create your own backend, using exchange rates that come directly from the exchange or broker where you plan to trade to re-balance your accounts.

Built-in: one-to-one

Supported currencies: any

The one-to-one backend applies the CONNECTOR_SPREAD setting, the assetScale settings, and otherwise uses a 1:1 exchange rate for all assets. This is the simplest backend, recommended for connectors that deal in only one currency.

Built-in: ecb

Supported currencies: see Euro foreign exchange reference rates

The ecb backend loads fiat exchange rates from Euro foreign exchange reference rates. Suitable for development and experimental use only.

Built-in: ecb-plus-xrp

Supported currencies: see Euro foreign exchange reference rates, XRP

The ecb-plus-xrp backend loads fiat exchange rates from Euro foreign exchange reference rates and XRP exchange rates from the Ripple Data API. Suitable for development and experimental use only.

Development

If you would like to contribute back to this project, please follow these steps:

Step 1: Clone repo

git clone https://github.com/interledgerjs/ilp-connector.git
cd ilp-connector

Step 2: Install dependencies

npm install

Step 3: Run it!

CONNECTOR_STORE_PATH=~/.connector-data CONNECTOR_ACCOUNTS='{}' CONNECTOR_ILP_ADDRESS=test.quickstart npm start

Step 4: Read the contributor guidelines

See CONTRIBUTING.md.