The Interledger network, since adopting v4 of the protocol, has moved to a model where individual payments are almost always broken up into multiple smaller packets making it impractical to use IPR. As such this spec has been deprecated.

Interledger Payment Request (IPR)

The Interledger Payment Request (IPR) transport protocol is an end-to-end protocol in which the receiver of an Interledger payment first communicates a request for payment to the sender. This document also recommends a method for receivers to generate payment requests such that they can verify incoming payments without storing all outstanding requests.

Introduction

Motivation

The Interledger Protocol uses holds based on cryptographic conditions and expiries to ensure a sender's funds are delivered to the destination or returned to the sender's account.

One approach is for conditions to be generated and fulfilled by the receivers of Interledger payments. When the sender of the payment receives the fulfillment, they can be certain that the receiver received the payment.

Receiver-generated conditions are also useful in building non-repudiable application layer protocols. The receiver would generate the condition and cryptographically sign a statement that the preimage of the specified hash indicates the sender has settled a particular debt. The receiver would only disclose the hash preimage upon receipt of payment. Once the sender gets the preimage, they would be able to demonstrate to third parties that they paid the receiver using the preimage and the original signed statement.

In most cases, non-repudiability is unnecessary, as it is sufficient for the sender to get proof that the receiver received the payment even if that proof cannot be used to convince third parties. In such cases, the Pre-Shared Key transport protocol is recommended because it does not require end-to-end communication for every payment.

Scope

This document defines a suggested format for representing payment requests and an approach for receiver-generated conditions. Protocols built on top of IPR MAY use the format provided here, though they can use any format they choose instead.

While this document also provides a recommendation for generating transfer conditions, conditions are often opaque to all parties aside from the receiver. Receivers MAY use any condition they choose, however this specification includes best practices that receivers SHOULD take into consideration.

This document does not specify how payment requests are communicated from a receiver to a sender.

Model of Operation

Interledger Payment Requests are intended to be used in higher-level protocols as follows:

  1. The receiver creates the ILP Packet and generates the condition using one of algorithms outlined in Condition Generation Recommendations.
  2. The receiver communicates the payment request, which includes the ILP Packet and condition, to the sender.
  3. The sender quotes the requested ILP packet and initiates an ILP payment with the packet and execution condition from the payment request. The sender uses the account and amount from the packet but they MUST treat the data as opaque. The sender MUST NOT modify the packet at all, or the receiver will reject the payment.
  4. When the receiver gets a notification of the incoming transfer, they check the transfer amount against the ILP Packet and check the payment request has not expired.
  5. The receiver regenerates the condition and fulfillment from the ILP Packet attached to the incoming transfer, using the same algorithm as before, and fulfills the transfer's condition.
  6. If the condition generated by the receiver matches the one in the incoming transfer, they submit the fulfillment to execute the transfer. If the condition does not match, it means that the ILP Packet has been tampered with and the receiver rejects the incoming transfer.

Condition Generation Recommendations

It is RECOMMENDED that receivers use an implementation of the Pre-Shared Key transport protocol to generate the packet and condition, because it will already include the best practices for generating conditions and enable the receiver to avoid keeping state of all outstanding payment requests.

Note the receiver's method for generating the condition or encoding data in the ILP packet does not matter to the sender. The sender treats the data in the ILP packet as opaque and uses the condition from the payment request without needing to know how the fulfillment is generated.

Using a PSK Implementation

The Pre-Shared Key protocol uses the payment condition as a MAC of the payment details by setting the fulfillment to be an HMAC of the ILP packet with a key derived from a secret shared between the sender and receiver. In IPR there is no shared secret and the condition is only generated by the receiver. Nevertheless, an IPR receiver can use the same methods to generate the condition and regenerate the fulfillment on receipt of the incoming transfer.

To use a PSK implementation, the receiver follows these steps:

  1. The receiver MAY derive a receiver secret and address as detailed in PSK: Shared Secret Generation but in IPR the receiver MUST NOT share the secret key.
  2. The receiver creates the payment packet and condition using the steps normally executed by the sender: PSK: Payment Creation.
  3. The receiver communicates the payment request, including the packet and condition, to the sender.
  4. If the receiver used the derived secret from step 1, they regenerate that secret from the packet as specified in PSK: Shared Secret Regeneration.
  5. The receiver generates the fulfillment from the secret and packet as specified in PSK: Payment Fulfillment.

Alternative Methods and General Best Practices

Receivers MAY use any method they choose for generating the condition, such as using a random fulfillment for each request. The receiver MUST be able to identify and verify the ILP Packet for every outstanding payment and produce the corresponding fulfillment. A PSK implementation handles these requirements without storing every fulfillment and packet in a database, by using the condition as a Message Authentication Code (MAC) of the payment request.

Receivers SHOULD follow these guidelines if implementing a custom system: * Receivers SHOULD include a payment request-specific nonce in the ILP packet to ensure that conditions are unique even when multiple payments would otherwise have identical packets. * Receivers SHOULD include an expiry date so that they do not accept incoming payments that are paid too long after their creation.

Interledger Payment Request Format

Here is a summary of the fields in the Interledger Payment Request format:

Field Type Short Description
version UInt8 IPR Version, 2 for now
packet OCTET STRING ILP Payment packet including the destination address and amount
condition UInt256 Execution condition for the payment

version

UInt8 ::= INTEGER (0..127)

IPR version. This document specifies version 2.

packet

OCTET STRING (SIZE(0..65535))

The ILP Payment Packet .

In IPR the sender only uses the account and amount from the ILP packet and MUST treat the data as opaque.

The sender MUST NOT modify the ILP packet at all, or the receiver will reject the payment.

condition

UInt256 ::= OCTET STRING (SIZE(32))

The ILP payment condition, which is the SHA-256 hash of the fulfillment that will be used to trigger the execution of the payment.