emschwartz/ilp

ILP client for browsers/Node.js

ILP Client

A low-level JS Interledger sender/receiver library

This is a low-level interface to ILP, largely intended for building ILP into other Application layer protocols.

The ILP Client does:

• Generate Interledger Payment Requests on the receiving side, including handling Crypto Condition generation and fulfillment)
• Pay for payment requests on the sending side
• Quote and send payments through multiple ledger types (using ilp-core)

The ILP Client does not handle:

• Account discovery
• Amount negotiation
• Communication of requests from recipient to sender

For a higher-level interface that includes the above features, see the Wallet Client.

Installation

npm install --save ilp ilp-plugin-bells

Note that ledger plugins must be installed alongside this module

Interledger Payment Request / Pay Flow

The client uses recipient-generated Interledger Payment Requests, which include the condition for the payment. This means that the recipient must first generate a payment request, which the sender then fulfills.

This library handles the generation of payment requests, but not the communication of the request details from the recipient to the sender. In some cases, the sender and receiver might be HTTP servers, in which case HTTP would be used. In other cases, they might be using a different medium of communication.

Requesting + Handling Incoming Payments

'use strict'

const ILP = require('ilp')
const FiveBellsLedgerPlugin = require('ilp-plugin-bells')
const receiver = ILP.createReceiver({
  _plugin: FiveBellsLedgerPlugin,
  prefix: 'ilpdemo.blue.',
  account: 'https://blue.ilpdemo.org/ledger/accounts/receiver',
  password: 'receiver'
})
receiver.listen()

const paymentRequest = receiver.createRequest({
  amount: 10
})

// XXX: user implements this
sendRequestToPayer(paymentRequest)

// This automatically checks the incoming transfer and fulfills the condition
receiver.on('incoming', (transfer, fulfillment) => {
  console.log('Got paid ' + paymentRequest.destinationAmount + ' for ' + paymentRequest.destinationMemo.thisIsFor)
})

Paying

'use strict'

const ILP = require('ilp')
const FiveBellsLedgerPlugin = require('ilp-plugin-bells')
const sender = ILP.createSender({
  _plugin: FiveBellsLedgerPlugin,
  prefix: 'ilpdemo.red.',
  account: 'https://red.ilpdemo.org/ledger/accounts/alice',
  password: 'alice',
  connectors: ['connie', 'otherconnectoronmyledger']
})

// XXX: user implements this
const paymentRequest = { /* request from recipient */ }

sender.quoteRequest(paymentRequest)
  .then((paymentParams) => {
    return sender.payRequest(paymentParams)
  })

Combined Example

'use strict'

const co = require('co')
const ILP = require('ilp')
const FiveBellsLedgerPlugin = require('ilp-plugin-bells')

const sender = ILP.createSender({
  _plugin: FiveBellsLedgerPlugin,
  prefix: 'ilpdemo.red.',
  account: 'https://red.ilpdemo.org/ledger/accounts/alice',
  password: 'alice'
})

const receiver = ILP.createReceiver({
  _plugin: FiveBellsLedgerPlugin,
  prefix: 'ilpdemo.blue.',
  account: 'https://blue.ilpdemo.org/ledger/accounts/bob',
  password: 'bobbob'
})

co(function * () {
  yield receiver.listen()
  receiver.on('incoming', (transfer, fulfillment) => {
    console.log('received transfer:', transfer)
    console.log('fulfilled transfer hold with fulfillment:', fulfillment)
  })

  const request = receiver.createRequest({
    amount: '10',
  })
  console.log('request:', request)

  const paymentParams = yield sender.quoteRequest(request)
  console.log('paymentParams', paymentParams)

  const result = yield sender.payRequest(paymentParams)
  console.log('sender result:', result)
}).catch((err) => {
  console.log(err)
})

API Reference

Sender~createSender(opts) ⇒ Sender

Returns an ILP Sender to quote and pay for payment requests.

Kind: inner method of Sender

Param	Type	Default	Description
opts._plugin	LedgerPlugin		Ledger plugin used to connect to the ledger, passed to ilp-core
opts	Objct		Plugin parameters, passed to ilp-core
[opts.client]	ilp-core.Client	create a new instance with the plugin and opts	ilp-core Client, which can optionally be supplied instead of the previous options
[opts.connectors]	Array	[]	Array of connectors to use, specified by account name on the local ledger (e.g. "connie"). Some ledgers provide recommended connectors while others do not, in which case this would be required to send Interledger payments.
[opts.maxHoldDuration]	Number	10	Maximum time in seconds to allow money to be held for
[opts.uuidSeed]	Buffer	crypto.randomBytes(32)	Seed to use for generating transfer UUIDs

• ~createSender(opts) ⇒ Sender
  • ~quoteSourceAmount(destinationAddress, sourceAmount) ⇒ Promise.<String>
  • ~quoteDestinationAmount(destinationAddress, destinationAmount) ⇒ Promise.<String>
  • ~quoteRequest(paymentRequest) ⇒ Promise.<PaymentParams>
  • ~payRequest(paymentParams) ⇒ Promise.<String>
  • ~stopListening() ⇒ Promise.<null>

createSender~quoteSourceAmount(destinationAddress, sourceAmount) ⇒ Promise.<String>

Get a fixed source amount quote

Kind: inner method of createSender
Returns: Promise.<String> - destinationAmount

Param	Type	Description
destinationAddress	String	ILP Address of the receiver
sourceAmount	String | Number	Amount the sender wants to send

createSender~quoteDestinationAmount(destinationAddress, destinationAmount) ⇒ Promise.<String>

Get a fixed destination amount quote

Kind: inner method of createSender
Returns: Promise.<String> - sourceAmount

Param	Type	Description
destinationAddress	String	ILP Address of the receiver
destinationAmount	String	Amount the receiver should recieve

createSender~quoteRequest(paymentRequest) ⇒ Promise.<PaymentParams>

Quote a request from a receiver

Kind: inner method of createSender
Returns: Promise.<PaymentParams> - Resolves with the parameters that can be passed to payRequest

Param	Type	Description
paymentRequest	Object	Payment request generated by an ILP Receiver

createSender~payRequest(paymentParams) ⇒ Promise.<String>

Pay for a payment request. Uses a determinstic transfer id so that paying is idempotent (as long as ledger plugins correctly reject multiple transfers with the same id)

Kind: inner method of createSender
Returns: Promise.<String> - Resolves with the condition fulfillment

Param	Type	Description
paymentParams	PaymentParams	Respose from quoteRequest

createSender~stopListening() ⇒ Promise.<null>

Disconnect from the ledger and stop listening for events.

Kind: inner method of createSender
Returns: Promise.<null> - Resolves when the sender is disconnected.

Receiver~createReceiver(opts) ⇒ Receiver

Returns an ILP Receiver to create payment requests, listen for incoming transfers, and automatically fulfill conditions of transfers paying for the payment requests created by the Receiver.

Kind: inner method of Receiver

Param	Type	Default	Description
opts._plugin	LedgerPlugin		Ledger plugin used to connect to the ledger, passed to ilp-core
opts	Object		Plugin parameters, passed to ilp-core
[opts.client]	ilp-core.Client	create a new instance with the plugin and opts	ilp-core Client, which can optionally be supplied instead of the previous options
[opts.hmacKey]	Buffer	crypto.randomBytes(32)	32-byte secret used for generating request conditions
[opts.defaultRequestTimeout]	Number	30	Default time in seconds that requests will be valid for
[opts.allowOverPayment]	Boolean	false	Allow transfers where the amount is greater than requested
[opts.roundingMode]	String		Round request amounts with too many decimal places, possible values are "UP", "DOWN", "HALF_UP", "HALF_DOWN" as described in https://mikemcl.github.io/bignumber.js/#constructor-properties
[opts.connectionTimeout]	Number	10	Time in seconds to wait for the ledger to connect

• ~createReceiver(opts) ⇒ Receiver
  • ~getAddress() ⇒ String
  • ~createRequest() ⇒ Object
  • ~listen() ⇒ Promise.<null>
  • ~stopListening() ⇒ Promise.<null>

createReceiver~getAddress() ⇒ String

Get ILP address

Kind: inner method of createReceiver

createReceiver~createRequest() ⇒ Object

Create a payment request

Kind: inner method of createReceiver

Param	Type	Default	Description
params.amount	String		Amount to request. It will throw an error if the amount has too many decimal places or significant digits, unless the receiver option roundRequestsAmounts is set
[params.account]	String	client.getAccount()	Optionally specify an account other than the one the receiver would get from the connected plugin
[params.id]	String	uuid.v4()	Unique ID for the request (used to ensure conditions are unique per request)
[params.expiresAt]	String	30 seconds from now	Expiry of request
[params.data]	Object		Additional data to include in the request
[params.roundingMode]	String	receiver.roundingMode	Round request amounts with too many decimal places, possible values are "UP", "DOWN", "HALF_UP", "HALF_DOWN" as described in https://mikemcl.github.io/bignumber.js/#constructor-properties

createReceiver~listen() ⇒ Promise.<null>

Listen for incoming transfers and automatically fulfill conditions for transfers corresponding to requests this receiver created.

Kind: inner method of createReceiver
Returns: Promise.<null> - Resolves when the receiver is connected
Emits: incoming, incoming:requestid

createReceiver~stopListening() ⇒ Promise.<null>

Disconnect from the ledger and stop listening for events.

Kind: inner method of createReceiver
Returns: Promise.<null> - Resolves when the receiver is disconnected.

"incoming"

IncomingTransfer from the ledger plugin and the fulfillment string

Kind: event emitted by Receiver

"incoming:requestid"

IncomingTransfer from the ledger plugin and the fulfillment string for a specific request

Kind: event emitted by Receiver