Introduction to Interledger and Rafiki

Issue
Please give your comments and feedback at this issue.

The Interledger protocol arranges the actual payments that monetized users make to sites. Rafiki is a standardized implementation of Interledger meant for web services. Neither is of prime importance to web developers, but it's useful to have a broad overview of what they are and do.

Ledgers and Interledger

Interledger is an open protocol for secure and private money exchange between ledgers.

A ledger is any larger organization that holds money, both for itself and for other people. A bank or a credit card company is a ledger, but many other companies have things like gift cards that also make them a ledger. Although the term is mostly associated with cryptocurrency, it is in fact much older, going back to the 16th century in the meaning "book of accounts". That is the meaning it's being used in here.

Individuals and companies can have an account at one or more of these ledgers, and — in theory — can send money from their account at a ledger to another account at the same or another ledger.

In practice there are a lot of bumps and hurdles. All these institutions use separate systems that generally don't communicate well with one another. The major exception are traditional banks, which have learned to send money to one another, but even there, the further your money has to go, the more complicated it gets. Anyone who’s ever done an international money transfer knows about this.

All ledgers that implement the Interledger protocol can exchange money. In addition, ledgers can convert any currency into any other currency. In the case of web monetization your account at a ledger transfers money, in your currency, to the account of the creators of the pages you visit, in their currency. The How a monetization stream works page gives more details. Here we'll focus on the technical underpinnings.

How Interledger works

Web developers do not have to worry about Interledger, just as they don't have to worry about TCP/IP. It just works and fulfills its function when you pull some relatively easy strings. Nonetheless, we'll dive a little deeper for those who like such things.

An Interledger network is a set of connected nodes that implement the protocol, with every node representing a ledger, such as the accounts managed by a bank. In fact, in order to be an Interledger node you must be a ledger.

The protocol describes how these nodes exchange money. Thus, like in TCP/IP, it all boils down to finding the right node to talk to and making sure all messages are transmitted without errors — we can't have a $1000 payment going missing on the network.

The layers

The Interledger protocol mirrors TCP/IP, and that's by design. TCP/IP is robust and well-tested, and the analogies that exist between TCP/IP and Interledger make it easy to explain what's going on.

Interledger layers fulfill roughly the same functions as the ones in the simplified OSI model, except that the protocol transports Interledger packages (ILPs) that contain encrypted payments and receipts (proofs of payment).

Interledger has the following layers:

  1. SPSP (Simple Payment Setup Protocol) fulfills the same function as DNS plus a bit of IP. It finds the correct current node for the account you're trying to send money to. This addresses can change frequently, but SPSP keeps track of that and solves any addressing issues for you. It also creates a shared secret for security and privacy purposes.
  2. STREAM manages the transmission of data. It is similar to TCP in that it values accuracy over speed, and contains error correction mechanisms and transport checks. Also, any payment request or response is split into multiple packets by the sender and reassembled by the receiver, just as TCP does with HTTP requests and responses.
  3. ILPv4 is akin to IP in that it actually finds the fastest path from sender to receiver moves and the packages from node to node. The actual transfer can go over TCP/IP, but also over Web Sockets.
  4. BTP is a layer for connecting Interledger with other networks, such as regular TCP/IP or specialized banking networks. It also handles currency conversion, if necessary. Every ledger must use BTP to connect to Interledger. Ledgers must support BTP; but no one else has to.

When you place a <link rel="monetization"> tag in your page you ask the browser (or the Coil extension) to download a JSON file that contains SPSP information. This information is used to send out actual SPSP requests.

SPSP crates an Interledger package that consists of an envelope with the destination ledger, and the actual encrypted package that states the amount to be paid, the currency, and a shared secret (think of it as a unique ID).

This package is handed over to STREAM for transmission. STREAM handles the transmission speed, error correction, grouping of similar packages to a destination, and it resends packages if necessary.

ILP does the actual sending of packages from Interledger node to node until it reaches its destination. There the package is received by BTP, which converts it to something a specialized banking network, for instance, can read, and sends it on into that network.

These packacges cannot be opened until it reaches its destination. Thus, while STREAM and ILPv4 know they're transmitting payment information from A to B, they do not know any further details.

Implementing Interledger: Rafiki

Any ledger that wants to participate in the Interledger network should implement the full protocol. Since writing the entire Interledger by hand time and again is time-consuming and tricky, the Interledger Foundation released Rafiki to help.

Rafiki is an Interledger wallet back-end that implements protocol such as Web Monetization. It is designed so that wallet providers can put it in front of their ledgers and establish communication with Interledger. It's essentially a service that exposes useful APIs for working with Interledger.

You can compare it to a web server application such as Apache. Instead of manually implementing HTTP, TCP, IP, and other required protocols, it's much easier to download and install Apache. That's the sort of service Rafiki aims to provide.

Rafiki also makes it easier to update the Interledger protocol. If the next version comes around Rafiki is updated, and interested parties can download the next version — just as happens with web servers when, for instance, HTTP is updated.

Rafiki does not help browser vendors or web developers. It's meant for organizations that wish to create an Interledger node. Thus web developers can safely ignore Rafiki.