Skip to content
This repository was archived by the owner on Sep 22, 2023. It is now read-only.

Basic ILP flow #124

Open
pgarg-ripple wants to merge 2 commits into
base: master
Choose a base branch
from
Open

Basic ILP flow #124

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
37e5b9d
create a page for basic ILP flow
pgarg-ripple Sep 12, 2019
dd1e51a
Update ilp-flow.md
pgarg-ripple Sep 18, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Binary file added docs/images/ilp-flow.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
41 changes: 41 additions & 0 deletions docs/markdown/ilp-flow.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,41 @@
# Basic Interledger Payment Flow

This section helps you become more familiar with Interledger by outlining the parts of an Interledger payment system and explaining the steps involved in an Interledger payment.

## Interledger payment

The Interledger payment system consists of four main components:
- Sender - Initiates a value transfer.
- Router - Applies currency exchange and forwards packets of value.
- Receiver - Receives the value.
- ILP Packet - A binary data packet, which contains necessary information required for an ILP payment. ILPv4 has three packet types: Prepare, Fulfill, and Reject, which roughly correspond to request, response, and error messages.

In the following scenario, the sender sends a Prepare packet to the connecting router. The routers forward the packet until it reaches the receiver. The receiver then accepts or rejects the packet by sending a Fulfill packet or a Reject packet.

![ILP-packets](../images/ilp-packets.png)

## Interledger payment flow

### Prerequisites

To understand the Interledger payment flow, let's assume the following:
1. The sender and receiver have accounts with at least one router on the Interledger network.
2. The sender knows the receiver's payment pointer, which is required for exchanging necessary payment information.

### Payment flow

1. The sender initiates a payment by connecting with the receiver over an out-of-band authenticated channel and obtaining the receiver's ILP address and a secret hash condition.
Copy link
Collaborator

@sappenin sappenin Sep 18, 2019

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

While possible, are you actually trying to describe SPSP here? Or is this meant to be a more generic thing?

Copy link
Contributor Author

@pgarg-ripple pgarg-ripple Sep 18, 2019

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

My intention is to keep it generic. I didn't want to name SPSP or moneyd in this flow because similar applications can be created by anyone in the future but the general concept will remain the same (I guess?).

Copy link

@sharafian sharafian Oct 1, 2019

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We should make the prerequisites more generic in that case, because right now they say "payment pointer"

Copy link
Contributor

@LoisRP LoisRP Jan 31, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

(Lois here): I've taken this file over in Prachi's absence. How about persistent payment identifier then, as a payment pointer is meant to be a persistent identifier?

0. The sender constructs a Prepare packet with the destination ILP address, the secret hash condition, amount, and expiry.
Copy link
Contributor

@kincaidoneil kincaidoneil Sep 24, 2019

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nit: the sender and recipient are exchanging a shared secret they can use to derive fulfillments, but that secret isn't a "hash condition" itself (but it's fine if that simplifies the explanation)

Copy link
Collaborator

@sappenin sappenin Sep 24, 2019

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
0. The sender constructs a Prepare packet with the destination ILP address, the secret hash condition, amount, and expiry.
0. The sender constructs a Prepare packet with the destination ILP address, the derived hash condition, amount, and expiry.

Copy link

@sharafian sharafian Oct 1, 2019

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

derived could be confusing if we're not making the assumption that this is through STREAM

0. The sender sends the Prepare packet to the router it is connected to.
0. The router checks the expiry of the Prepare packet. If the router receives the packet after the expiry, the router sends a Reject packet to the sender. If the router receives the packet before the expiry, the following steps take place.
0. The router uses its local routing tables and the destination address from the Prepare packet to determine which next hop to forward the packet to. The next hop can be another router or the receiver.
0. The router determines the outgoing asset type based on the next hop it will forward the packet to and applies its exchange rate and fees to the Prepare amount.
Copy link

@sharafian sharafian Oct 1, 2019

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The router also moves the expiry of the packet a little bit earlier, to give it a window of time (called the min message window in the code) during which it can pass the fulfill backwards. That also means that when checking the expiry the router needs to ensure there's enough time left to take this min message window off. Typically min message window is around a second but could be configured to be more or less depending on network conditions

0. The router forwards the Prepare packet to the next hop, which may be another router. All subsequent routers go through steps 4-6 (treating the previous router as the sender) until the packet reaches the receiver.
0. The receiver receives the packet and checks the packet contents, for example, if the amount to be received is acceptable.
0. If the receiver accepts the Prepare packet, the receiver returns a Fulfill packet. If the receiver does not want the Prepare packet or it does not pass one of the checks, the receiver returns a Reject packet instead.
0. The router checks if the receiver returned a Fulfill before the expiry in the Prepare packet. If so, the router returns the same Fulfill packet to the previous router. If the receiver returned a Reject packet or the Prepare expired before the Fulfill was returned, the router returns the Reject packet to the preceding router. Each router repeats this step until the Fulfill or Reject packet reaches the sender.
Copy link
Contributor

@kincaidoneil kincaidoneil Sep 24, 2019

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The router also must check that the fulfillment is the preimage to the hash/execution condition, otherwise the Fulfill is invalid. This is an important part of the story: what's preventing any intermediary connector from just returning the Fulfill packet?

Copy link
Collaborator

@sappenin sappenin Sep 24, 2019

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
0. The router checks if the receiver returned a Fulfill before the expiry in the Prepare packet. If so, the router returns the same Fulfill packet to the previous router. If the receiver returned a Reject packet or the Prepare expired before the Fulfill was returned, the router returns the Reject packet to the preceding router. Each router repeats this step until the Fulfill or Reject packet reaches the sender.
0. The router checks if the receiver returned a Fulfill before the expiry in the Prepare packet. It also verifies that the fulfillment received from the receiver matches the original condition received in the Prepare packet from the sender. If both checks pass, the router returns the same Fulfill packet to the previous router. If the receiver returned a Reject packet or the Prepare expired before the Fulfill was returned or the fulfilment was invalid, the router returns the Reject packet to the preceding router. Each router repeats this step until the Fulfill or Reject packet reaches the sender.

0. Sender repeats the process, starting from step 2, as many times as is necessary to transfer the desired total amount of value.
Copy link

@sharafian sharafian Oct 1, 2019

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

if we're talking about a chunked payment then this leaves out some thing for instance determining the MTU


The following diagram shows the sequence of events that occur during an Interledger payment:

![ILP-flow](../images/ilp-flow.png)