Skip to content

Instantly share code, notes, and snippets.

@adrianhopebailie

adrianhopebailie/ilsp-interface.md

Last active August 31, 2017 21:36
Show Gist options
  • Star 0 You must be signed in to star a gist
  • Fork 0 You must be signed in to fork a gist
  • Save adrianhopebailie/c91ad4e6fd760dda8f365ac1f96319b6 to your computer and use it in GitHub Desktop.
Save adrianhopebailie/c91ad4e6fd760dda8f365ac1f96319b6 to your computer and use it in GitHub Desktop.
Download ZIP
Raw
ilsp-interface.md

Interledger Service Provider Interface

The Interledger is a network of interconnected payment networks operating under a universal address space. To send a payment over the Interledger a sender has some practical prerequisites they must meet:

  1. A source of funds
  2. A connection to at least one other node on the network

For the majority of use cases, an Interledger payment will originate from, and terminate at, an entity that is on the limits of the network graph. That entity may have more than a single connection to other nodes but will not be operating as an intermediary node. For clarity the node(s) that this entity connects to is/are defined as an Interledger Service provider (ILSP).

The ILSP provides services to senders and receivers that allow them to send and receive payments via ILP without needing to be fully functioning ILP nodes. These services include one or more of:

  1. Allocating the sender/receiver an ILP address prefix
  2. Accepting transfers from senders to initiate an ILP payment
  3. Passing fulfillments to senders to confirm an ILP payment
  4. Making transfers to receivers to complete an ILP payment
  5. Passing fulfillments from receivers back along the incoming payment path

Example Ecosystem

In the following example diagram, 5 different ILSPs are shown that offer different mixes of services and illustrate the various roles an ILSP may take in an ILP payment.

Example Ecosystem

Light ILSP

The first two ILSPs (with the Interledger addresses g.crypto.blue and g.crypto.red) are offering ILSP services to User A but don't control any of the User's funds. To use the services, User A must run wallet software that is capable of interfacing with the ILSPs and also capable of establishing a peering relationship with the ILSPs using a ledger that they support. In this example we assume the ILSPs support peering over XRP Ledger (likely using an XRP payment channel).

When User A signed up for ILSP services from these ILSPs she would have created an account (not a financial account just a user account) and been allocated an ILP address prefix (different at each ILSP). Using that account User A would be able to get authentication credentials (API keys/secret) that allow her to connect her wallet software to the ILSP and consume their APIs.

To send and receive payments User A and the ILSP need to establish a payment channel on the XRP Ledger. User A's wallet and the ILSP will need to be capable of doing this (sending the appropriate transactions to the XRP ledger) and then submitting payments via that channel.

The expected journey for a new user would be:

  1. Download an ILP-capable wallet that supports sending via XRP Ledger
  2. Register with an ILSP and get API keys
  3. Configure wallet with API keys and connect to ILSP.
  4. Wallet and ILSP exchange messages to co-ordinate establishment of XRP payment channels in both directions and for ILSP to notify wallet of it's ILP Address prefix.

Now the wallet can use whatever protocol it likes to setup either an incoming or outgoing payment.

Following setup of an outgoing payment the wallet will have the ILP-address of the receiver, the condition, and the required expiry. It can then submit that payment via the XRP payment channel to the ILSP

Following setup of an incoming payment the wallet will have provided a condition, an appropriate expiry and an ILP address to the sender. When a payment is received via the XRP payment channel the wallet will generate the fulfillment and return this to the ILSP.

Full-service ILSP

Users C and D have signed up with full-service ILSPs. In this case the users have a balance controlled by the ILSP and so the wallet is simply holding credentials that allow it to use a secure API hosted by the ILSP.

The most likely candidates to be a full-service ILSP will be entities that already hold balances for users such as banks, exchanges and pre-paid wallets.

The expected journey for a new user would be:

  1. Download an ILP-capable wallet.
  2. Register with the ILSP and get API keys.
  3. Configure wallet with API keys and connect to ILSP.
  4. Wallet and ILSP exchange messages to establish user's current balance and get user's ILP Address prefix.

Now the wallet can use whatever protocol it likes to setup either an incoming or outgoing payment.

Following setup of an outgoing payment the wallet will have the ILP-address of the receiver, the condition, and the required expiry. It can then submit that to the ILSP and request that it makes the payment.

Following setup of an incoming payment the wallet will have provided a condition, an appropriate expiry and an ILP address to the sender. When a payment is received at the ILSP it will notify the wallet so that it can generate the fulfillment and return this to the ILSP to complete the payment.

ILP-enabled Payment Service Provider

A third possible deployment is one in which the user's wallet plays no part in the ILP payment at all. The deployment would look similar to that of Users C and D but the interface between the wallet and service provider would be quite different.

In this scenario the service provider generates the conditions and fulfillments and the wallet could be a disconnected component (i.e. not always online).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment