interledgerjs / ilp

interledgerjs

ILP client for browsers/Node.js

132 Stars 22 Forks Last release: Not found Other 239 Commits 48 Releases

Available items

No Items, yet!

The developer of this repository has not created any items for sale yet. Need a bug fixed? Help with integration? A different license? Create a request here:

Readme

ILP

The Javascript client library for Interledger

The ILP module includes:

Simple Payment Setup Protocol (SPSP), a higher level interface for sending ILP payments, which requires the receiver to have an SPSP server.
Interledger Dynamic Configuration Protocol (ILDCP), a protocol for exchanging configuration between nodes.
STREAM, the recommended Transport Protocol to use for most Interledger applications.
createLogger, a function to create a name spaced logger.
createMiddleware, a function to create server middleware for an SPSP receiver.
createPlugin, a function to get an ILP plugin from the environment or testnet.
receive, a function to create an invoice representing a handle to a STREAM server waiting to receive a specific amount.
pay, a function to make a STREAM payment to either a Payment Pointer or an ILP Address using appropriate shared secret.

Installation

npm install --save ilp

Note that ilp plugins must be installed alongside this module unless you simply use BTP

Create Plugin

Using

ilp.createPlugin

is an alias for the deprecated

ilp-plugin

module. It creates an instance of a BTP plugin that will attempt to connect to a local

moneyd

instance by default. This can be overridden using environment variables.

The module looks for

ILP_PLUGIN_OPTIONS

(or

ILP_CREDENTIALS

however this is deprecated) and

ILP_PLUGIN

ILP_PLUGIN_OPTIONS

must contain a JSON object and will be passed into the constructor of a new plugin instance. The name of the plugin type to instantiate must be stored as a string in the environment variable

ILP_PLUGIN

or it will default to

ilp-plugin-btp

By default (i.e.

ILP_PLUGIN_OPTIONS

and

ILP_PLUGIN

are not set), a random secret will be generated and a new instance of

ilp-plugin-btp

will be configured to connect to btp+ws://localhost:7768.

Simple Payment Setup Protocol (SPSP)

If you are sending to an SPSPv4 receiver using a Payment Pointer, the SPSP module provides a high-level interface to

pay

and

query

the server:

'use strict'

const ilp = require('ilp')
;(async function () {
  await ilp.SPSP.pay(ilp.createPlugin(), {
    receiver: '$bob.example.com',
    sourceAmount: '1000'
  })
})()

ilp.SPSP

replaces the deprecated

ilp-protocol-spsp

module and no longer supports payments to servers using PSK2. Only responses from an SPSP server with the content-type of

application/spsp4+json

are accepted.

Create Middleware

The

ilp

module provides conveniences functions to create server middleware that can be used to host an SPSP endpoint for receiving payments.

Express example: ```js const ilp = require('ilp') const app = require('express')()

;(async () => { const spsp = await ilp.express.createMiddleware({receiver_info:{name: 'Bob Smith'}}) app.get('/.well-known/pay', spsp) app.listen(3000) })()

KOA and HAPI support to come...

Interledger Dynamic Configuration Protocol (ILDCP)
The ILDCP module allows clients to get their configured address, asset and scale from an upstream parent connector.
```js
'use strict'
const ilp = require('ilp')
;(async function () {
  const plugin = ilp.createPlugin()
  await plugin.connect()
  const { clientAddress, assetScale, assetCode } = await ilp.ILDCP.fetch(plugin.sendData.bind(plugin))
  console.log(Plugin connected and configured with address ${clientAddress} using asset ${assetCode} and scale ${assetScale})
})()

STREAM

The STREAM module provides an API to use the STREAM protocol to send and receive payments. STREAM is the recommended transport protocol for use with ILP.

The

ilp

module provides two abstractions over this module that make it simple to send and receive payments.

Receive

receive

creates an instance of a STREAM server wrapped around a given plugin (or calls

createPlugin

if none is provided). It returns an

Invoice

object which has an

address

and

secret

that can be shared with a sender, and a

receivePayment()

method to wait for the incoming payment.

Pay

pay

will either pay a valid SPSP receiver or an ILP address (assuming there is a STREAM server waiting for connections at that address).

To pay using an SPSP receiver, pass the payment pointer as the payee in the form of a string:

'use strict'

const ilp = require('ilp')
;(async function () {
  await ilp.pay(100, '$bob.example.com')
})()

To pay using a given ILP Address and shared secret pass these in as an object:

'use strict'

const ilp = require('ilp')
;(async function () {
  await ilp.pay(100, { destinationAccount: 'g.bob.1234', sharedSecret: Buffer.from('**', 'base64') })
})()

Examples are provided in

example.js

ilp

by interledgerjs