@interledger/pay

pay 💸

Send payments over Interledger using STREAM

Install

npm i @interledger/pay

Or using Yarn:

yarn add @interledger/pay

Guide

Flow

1. Call setupPayment to resolve the payment details, destination asset, and/or Incoming Payment
2. Add custom logic before continuing, or catch error
3. Call startQuote to probe the exchange rate, discover the max packet amount, and compute payment limits
4. Add custom logic to authorize payment for maximum source amount, or catch error
5. Call pay to execute the payment
6. Add custom logic to handle payment outcome or error

Pay an Incoming Payment

Fixed delivery amount payment

import { setupPayment, startQuote, pay, closeConnection } from '@interledger/pay'

async function run() {
  let plugin /* Plugin instance */

  const destination = await setupPayment({
    plugin,
    destinationPayment:
      'https://mywallet.example/accounts/alice/incoming-payments/04ef492f-94af-488e-8808-3ea95685c992',
  })

  const quote = await startQuote({
    plugin,
    destination,
    sourceAsset: {
      assetCode: 'USD',
      assetScale: 9,
    },
  })
  // {
  //   maxSourceAmount: 1_950n,
  //   lowEstimatedExchangeRate: 115,
  //   highEstimatedExchangeRate: 135,
  //   minExchangeRate: 110,
  // }

  // Verify the max source amount is appropriate and perform or cancel the payment
  const receipt = await pay({ plugin, destination, quote })
  console.log(receipt)
  // {
  //    amountSent: 1_910n,
  //    amountDelivered: BigInt(234_000),
  //    ...
  // }

  await closeConnection(plugin, destination)
}

Pay an Incoming Payment via a Connection URL

Fixed delivery amount payment

import { setupPayment, startQuote, pay, closeConnection } from '@interledger/pay'

async function run() {
  let plugin /* Plugin instance */

  const destination = await setupPayment({
    plugin,
    destinationConnection: 'https://mywallet.example/bddcc820-c8a1-4a15-b768-95ea2a4ed37b',
  })

  const quote = await startQuote({
    plugin,
    destination,
    sourceAsset: {
      assetCode: 'USD',
      assetScale: 9,
    },
  })
  // {
  //   maxSourceAmount: 1_950n,
  //   lowEstimatedExchangeRate: 115,
  //   highEstimatedExchangeRate: 135,
  //   minExchangeRate: 110,
  // }

  // Verify the max source amount is appropriate and perform or cancel the payment
  const receipt = await pay({ plugin, destination, quote })

  await closeConnection(plugin, destination)
}

Pay to a Payment Pointer

Fixed source amount payment

import { setupPayment, startQuote, pay, closeConnection } from '@interledger/pay'

async function run() {
  let plugin /* Plugin instance */

  const destination = await setupPayment({
    plugin,
    paymentPointer: '$rafiki.money/p/example',
  })

  const quote = await startQuote(
    plugin,
    amountToSend: '314159',
    sourceAmount: {
      assetCode: 'EUR',
      assetScale: 6,
    },
    destination
  })

  const receipt = await pay({ plugin, destination, quote })

  await closeConnection(plugin, destination)
}

Units

On Interledger assets and denominations:

Asset amounts may be represented using any arbitrary denomination. For example, one U.S. dollar may be represented as $1 or 100 cents, each of which is equivalent in value. Likewise, one Bitcoin may be represented as 1 BTC or 100,000,000 satoshis.

A standard unit is the typical unit of value for a particular asset, such as $1 in the case of U.S. dollars, or 1 BTC in the case of Bitcoin.

A fractional unit represents some unit smaller than the standard unit, but with greater precision. Examples of fractional monetary units include one cent ($0.01 USD), or 1 satoshi (0.00000001 BTC).

An asset scale is the difference in orders of magnitude between the standard unit and a corresponding fractional unit. More formally, the asset scale is a non-negative integer (0, 1, 2, …) such that one standard unit equals the value of 10^(scale) corresponding fractional units. If the fractional unit equals the standard unit, then the asset scale is 0.

For example, one cent represents an asset scale of 2 in the case of USD, whereas one satoshi represents an asset scale of 8 in the case of Bitcoin.

To simplify accounting, all amounts are represented as unsigned integers in a fractional unit of the asset corresponding to the source asset scale provided, or the destination asset scale resolved from the receiver.

Since applications need to debit the source amount in their own system before executing a payment, this assumes they also know their own source asset and denomination. Therefore, it's not useful to resolve this information dynamically, such as using IL-DCP, which also delays connection establishment.

Amounts

Pay leverages JavaScript BigInt for arbitrarily large integers using its own wrapper for strongly-typed arithmetic operations.

Amounts returned by Pay use these exported classes and interfaces:

• Int — Class representing non-negative integers.
• PositiveInt — Interface narrowing Int, representing non-negative, non-zero integers. (In this context, zero is not considered signed).
• Ratio — Class representing a ratio of two integers: a non-negative numerator, and a non-negative, non-zero denominator.
• PositiveRatio — Interface narrowing Ratio, representing a ratio of two non-negative, non-zero integers.

Int and Ratio offer utility methods for integer operations and comparisons. They may also be converted to/from number, string, bigint, and Long.

Int and Ratio prevent divide-by-zero errors and enforce the internal bigint is always non-negative. They also provide type guards for PositiveInt to reduce unnecessary code paths. For example, if one integer is greater than another, that integer must always be non-zero, and can be safely used as a ratio denominator without any divide-by-zero branch.

Exchange Rates

Pay is designed to provide strict guarantees of the amount that will be delivered.

During the quote step, the application provides Pay with prices for the source and destination assets and its own acceptable slippage percentage, which Pay uses to calculate a minimum exchange rate and corresponding minimum destination amount it will enforce for the payment. Exchange rates are represented as the ratio between a destination amount and a source amount, in fractional units.

Then, Pay probes the recipient to determine the real exchange rate over that path. If it sufficiently exceeds the minimum exchange rate, Pay will allow the payment to proceed. Otherwise, it's not possible to complete the payment. For instance, connectors may have applied a poor rate or charged too much in fees, the max packet size might be too small to avoid rounding errors, or incorrect assets/scales were provided.

Since STREAM payments are packetized, Pay may not be able to complete a payment if, for instance, the sender and receiver become disconnected during the payment. However, Pay guarantees payments never exhaust their quoted maximum source amount without satisfying their quoted minimum delivery amount. Every delivered packet meets or exceeds the quoted minimum exchange rate (*with the exception of the final one, as necessary).

Error Handling

If setup or quoting fails, Pay will reject the Promise with a variant of the PaymentError enum. For example:

import { setupPayment, PaymentError } from '@interledger/pay'

try {
  await setupPayment({ ... })
} catch (err) {
  if (err === PaymentError.InvalidPaymentPointer) {
    console.log('Payment pointer is invalid!')
  }

  // ...
}

Similarly, if an error was encountered during the payment itself, it will include an error property on the result which is a PaymentError variant.

A predicate function, isPaymentError, is also exported to check if any value is a variant of the enum.

Payment Pointers

Pay exports the AccountUrl utility to validate payment pointers and SPSP/Open Payments account URLs. Since payment pointers identify unique Interledger accounts, Pay parses them so they can be compared against external references to the same account.

Connection Security

Some applications may find it useful for multiple Pay library instances to send over a single STREAM connection, such as quoting in one process, and sending money in another.

In this case, the client application must track key security parameters, such as the request count, which STREAM relies on for monotonically increasing sequence numbers and secure acknowledgements of each request.

Pay uses a Counter instance, passed in-process via the ResolvedPayment object, to track how many packets have been sent. Applications that resume connections MUST use the counter instance to fetch how many packets have been sent, then create a new counter with the existing request count to pass to new Pay instances that use the same connection.

Other connection invariants applications should enforce:

1. Only one Pay instance (any actively running call to startQuote, pay, or closeConnection) can send over a single connection at one time.
2. After a connection is closed via calling closeConnection, those connection details may no longer be used for sending.

API

setupPayment

(options:SetupOptions) => Promise<ResolvedPayment>

Resolve destination details and asset of the payment in order to establish a STREAM connection.

startQuote

(options:QuoteOptions) => Promise<Quote>

Perform a rate probe: discover path max packet amount, probe the real exchange rate, and compute the minimum exchange rate and bounds of the payment.

pay

(options:PayOptions) => Promise<PaymentProgress>

Send the payment: send a series of packets to attempt the payment within the completion criteria and limits of the provided quote.

closeConnection

(plugin:Plugin, destination:ResolvedPayment) => Promise<void>

If the connection was established, notify receiver to close the connection. For stateless receivers, this may have no effect.

SetupOptions

Interface

Parameters to setup and resolve payment details from the recipient.

ResolvedPayment

Interface

Resolved destination details of a proposed payment, such as the destination asset, Incoming Payment, and STREAM credentials, ready to perform a quote.

QuoteOptions

Interface

Limits and target to quote a payment and probe the rate.

Quote

Interface

Parameters of payment execution and the projected outcome of a payment.

PayOptions

Interface

Payment execution parameters.

PaymentProgress

Interface

Intermediate state or outcome of the payment, to account for sent/delivered amounts. If the payment failed, the error property is included.

IncomingPayment

Interface

Open Payments Incoming Payment metadata

Amount

Interface

Amount details of an IncomingPayment.

AssetDetails

Interface

Asset and denomination for an Interledger account (source or destination asset)

PaymentType

String enum

Completion criteria of the payment

PaymentError

String enum

Payment error states

Errors likely caused by the user

Errors likely caused by the receiver, connectors, or other externalities