Make a Chunked Payment on Interledger

One of the important concepts in Interledger is “chunked payments.” The idea is that you can split a payment into many Interledger packets, in the same way that a file is split into many Internet packets.

There are many reasons to split up a payment into chunks. It allows Interledger packets to be more homogenous, which makes routing easier. It lowers the liquidity requirements, because large payments are spread out across time. This makes the network safer and more competitive.

All of these points are pretty abstract, though. To many, chunked payments will sound bizarre. This tutorial aims to make these concepts more concrete.

You’ll send a chunked payment on your own machine to see it work.

Note: some of the modules used in this tutorial are still in flux. If the tools change, a future version of this tutorial may be released.

Prerequisites

• Node.js (v8.9.4 or higher)
• Moneyd should be installed and running on the ILP testnet. Read this tutorial if you don’t have it set up yet.
• (Recommended) Read our SPSP tutorial, because the same tools will be used in this tutorial.

If you don’t yet have it installed, get the ilp-spsp tool. Make sure you have permissions to install global node modules.

npm install -g ilp-spsp

Creating an Invoice

In order to make a chunked payment, you need some system that tracks the progress of the chunked payment. We use special SPSP endpoints that represent invoices.

We’ve deployed a publicly available server that tracks invoices. Create an invoice by running the command below:

curl -X POST 'https://invoices.ilp-test.com/' \
  -H 'Content-Type:application/json' \
  -H 'Authorization:Bearer test' \
  --data '{"amount":"1000000","reason":"tutorial invoice"}'

You’ll get an SPSP payment pointer as a response. Copy it to your clipboard, because you’ll use it in the next sections.

{
  "receiver":"$invoices.ilp-test.com/3ba054a0..."
}

Query the State of Your Invoice

You can verify the details of this invoice by using the ilp-spsp query command. Use the SPSP payment pointer that you copied in the last section.

ilp-spsp query --receiver '$invoices.ilp-test.com/3ba054a0...'

Your response contains the usual information about how to reach the receiver, as well as information about how much of the invoice has been paid:

{
  "destinationAccount": "test.amundsen.bmp.btp18q1...",
  "sharedSecret": "QtCs7in15pyHvqzFnQliLiyV...",
  "balance": {
    "current": "0",
    "maximum": "1000000"
  },
  "receiverInfo": {
    "reason": "tutorial invoice"
  }
}

The amount is denominated in micro-XRP, because this invoice server is connected to the testnet via XRP. That means you just created an invoice for 1 XRP.

Right now, 0 out of 1000000 µXRP have been paid.

Pay Your Invoice

It’s time to actually send a chunked payment. Use the SPSP payment pointer that you copied in the first section.

DEBUG=ilp* ilp-spsp invoice --receiver '$invoices.ilp-test.com/3ba054a0...'

Congratulations! You’ve sent your first chunked payment.

This command produced a lot of output because it split your payment up into chunks and sent them all individually. The debug messages give you an indication of its progress.

You can query the state of your invoice again, to make sure that it was paid.

ilp-spsp query --receiver '$invoices.ilp-test.com/3ba054a0...'

Despite the fact that the payment was split into pieces, it ended up with the exact correct amount.

{
  "destinationAccount": "test.amundsen.bmp.btp18q...",
  "sharedSecret": "z+8auUK0vzdnGRPM80FRpO...",
  "balance": {
    "current": "1000000",
    "maximum": "1000000"
  },
  "receiverInfo": {
    "reason": "tutorial invoice"
  }
}

It shouldn’t be that surprising, if you think about it. The internet can split up an executable file and have it come out intact, so why can’t we do the same for a payment?

If you want to go further with chunked payments

• Try out some different amounts. How big of an invoice can you pay before you exhaust your liquidity?
• Deploy your own instance of ILP SPSP Invoice Server.
• Use the webhook functionality in the invoice server to create an ILP checkout.

Make sure to share your experience and ask questions in our Gitter!