Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: add settlement engine RFC #536

Merged
merged 35 commits into from
Oct 20, 2019
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
35 commits
Select commit Hold shift + click to select a range
4e742ae
docs: add settlement engine RFC
kincaidoneil Jun 20, 2019
5ea7edd
fix: initial edit batch, accounting explanation
kincaidoneil Jul 10, 2019
4236171
docs: flesh out bookkeeping and peer messaging
kincaidoneil Aug 2, 2019
8ecad82
docs: highlight settlement engine spec, hide LPIv2
kincaidoneil Aug 2, 2019
536932d
fix: more general asset/unit definitions
kincaidoneil Aug 5, 2019
036311a
Merge branch 'ko-settlement-engine' of https://github.com/interledger…
kincaidoneil Aug 5, 2019
2da9cbd
fix: misc edits, async settlement design
kincaidoneil Aug 6, 2019
579e27c
fix: increment interledger arch draft
kincaidoneil Aug 6, 2019
18f2eec
fix: explain rationale to support different scales
kincaidoneil Aug 6, 2019
43cfa06
fix: clarify asset amount not tied to denomination
kincaidoneil Aug 6, 2019
93e476c
fix: clarify pre-payment, minor changes
kincaidoneil Aug 6, 2019
fa37819
fix: clarify account, improve settlement symmetry
kincaidoneil Aug 7, 2019
5b49313
fix: plural settlement engines
kincaidoneil Aug 7, 2019
3a495b4
docs: add idempotence behavior
kincaidoneil Aug 7, 2019
b5d88d1
fix: no idempotence for sending messages
kincaidoneil Aug 8, 2019
f0349fc
fix: minor edits
kincaidoneil Aug 8, 2019
1497868
docs(settlement): clean up api docs, webhooks
kincaidoneil Aug 8, 2019
cca172f
fix: clarify rounding to 0 behavior
kincaidoneil Aug 9, 2019
61baa23
fix: minor edits, address comments
kincaidoneil Aug 9, 2019
69dd834
fix: simplify, address comments, add diagram
kincaidoneil Aug 12, 2019
ace4c0c
fix: update flow diagram for readability
kincaidoneil Aug 12, 2019
6aea82c
fix: smaller margins on flow diagram
kincaidoneil Aug 12, 2019
ef8d974
fix: even smaller diagram margins
kincaidoneil Aug 12, 2019
b57c4b8
fix: minor diagram edits
kincaidoneil Aug 12, 2019
3330782
fix: apply suggestions
kincaidoneil Aug 15, 2019
76c7176
fix: apply suggestion
kincaidoneil Aug 18, 2019
9d5e5cf
fix: bring inline with existing implementations
kincaidoneil Sep 11, 2019
ee6f48b
fix: merge with remote changes
kincaidoneil Sep 11, 2019
07a2be9
fix: safer idempotency/retry behavior
kincaidoneil Sep 11, 2019
a8a0426
fix: apply suggestions
kincaidoneil Sep 24, 2019
79d6c19
docs(se): remove refunds, simplify, final edits
kincaidoneil Oct 19, 2019
c9f3a63
Merge branch 'master' into ko-settlement-engine
kincaidoneil Oct 19, 2019
07cf997
fix: add settlement engine link to website sidebar
kincaidoneil Oct 19, 2019
c74b71a
docs(se): minor edits
kincaidoneil Oct 20, 2019
3a4b528
docs(se): fix create account json payload
kincaidoneil Oct 20, 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
18 changes: 5 additions & 13 deletions 0001-interledger-architecture/0001-interledger-architecture.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,8 @@
---
title: Interledger Architecture
draft: 6
draft: 7
---

# Interledger Architecture

Interledger provides for secure payments across multiple assets on different ledgers. The architecture consists of a conceptual model for interledger payments, a mechanism for securing payments, and a suite of protocols that implement this design.
Expand Down Expand Up @@ -38,8 +39,6 @@ Like the Internet protocol stack that inspired it, the Interledger protocol suit

> **Aside:** Not pictured in the diagram are configuration protocols including [IL-RFC-31: Interledger Dynamic Configuration Protocol](../0031-dynamic-configuration-protocol/0031-dynamic-configuration-protocol.md) and **Route Broadcasting Protocol**. These protocols are built on top of the Interledger Protocol layer and support it, but are not considered to be transport or application-layer protocols.

<!-- TODO: Add a link to [RBP](https://github.com/interledger/rfcs/pull/455)'s final location. -->

The following sections describe the general functions of each layer in the protocol suite. For an alternate explanation with detailed depictions of the protocols' data formats, see [IL-RFC-33: Relationship Between Protocols](../0033-relationship-between-protocols/0033-relationship-between-protocols.md).

#### Ledger Protocols
Expand All @@ -58,8 +57,7 @@ If settlement of one account in the Interledger is contingent on the status of a

Nodes can also choose never to settle their obligations. This configuration may be useful when several nodes representing different pieces of software or devices are all owned by the same person or business, and all their traffic with the outside world goes through a single "home router" connector. This is the model of [moneyd](https://github.com/interledgerjs/moneyd), one of the current implementations of Interledger.

Most implementations of Interledger use a plugin architecture to settle obligations automatically while abstracting the differences between different ledger layer protocols. For an example of this, see [IL-RFC-24: JavaScript Ledger Plugin Interface version 2](../0024-ledger-plugin-interface-2/0024-ledger-plugin-interface-2.md).

Implementations of Interledger are recommended to use settlement engines as defined in [IL-RFC-00: Settlement Engines](../0038-settlement-engines/0038-settlement-engines.md) to settle obligations automatically while abstracting the differences between different settlement systems and ledgers.

#### Link Protocols

Expand All @@ -72,7 +70,6 @@ Peers in the Interledger Protocol require a way to communicate securely with one

The implementation of a Link protocol may be incorporated into a ledger plugin, since the Link protocol has to communicate settlements that occur in the underlying ledger.


#### Interledger Protocol

The Interledger Protocol version 4 (ILPv4) is the core protocol of the entire Interledger Protocol suite. This protocol's packets pass through all participants in the chain: from the sender, through one or more connectors, to the receiver. This protocol is compatible with any variety of currencies and underlying ledger systems.
Expand All @@ -81,7 +78,6 @@ This level is concerned with currency amounts, routing, and whether each step in

This layer abstracts the layers above and below it from one another, so there can be only one protocol at this layer. Other protocols, including older versions of the Interledger Protocol, are incompatible. The current protocol is defined by [IL-RFC-27: Interledger Protocol version 4](../0027-interledger-protocol-4/0027-interledger-protocol-4.md).


#### Transport Protocols

Transport layer protocols are used for **end-to-end communication** between sender and receiver; connectors are not expected to be involved. This layer is responsible for:
Expand All @@ -94,7 +90,6 @@ Transport layer protocols are used for **end-to-end communication** between send

For an example, see the STREAM protocol, defined by [IL-RFC-29: STREAM](../0029-stream/0029-stream.md). STREAM creates a bidirectional connection between a sender and receiver that consists of many individual Interledger packets.


#### Application Protocols

Protocols at the application level communicate details outside of the minimum information that is technically necessary to complete a payment. For example, application protocols may check that participants are interested in conducting a transaction and are legally allowed to do so.
Expand All @@ -110,7 +105,6 @@ An example of an application layer protocol is the [Simple Payment Setup Protoco

Many different messaging protocols can be defined on and above the Application level of the Interledger clearing system.


#### Comparison to Traditional Financial Infrastructure

The layers of Interledger are similar to the different layers of traditional inter-bank systems:
Expand All @@ -120,7 +114,6 @@ The layers of Interledger are similar to the different layers of traditional int
- Interledger's _Link protocols_ don't have a direct banking equivalent, but they provide authenticated messaging to enable the Interledger Protocol layer, and they also associate settlement events in the underlying ledgers to balances in the Interledger Protocol layer.
- The underlying _Ledger_ systems are equivalent of _settlement_ in banking terms.


### Interledger Protocol Flow

Interledger moves money by relaying _packets_. In the Interledger Protocol, a "prepare" packet represents a possible movement of some money and comes with a condition for releasing it. As the packet moves forward through the chain of connectors, the sender and connectors prepare balance changes for the accounts between them. The connectors also adjust the amount for any currency conversions and fees subtracted.
Expand All @@ -145,7 +138,6 @@ A packet does not have to represent the full amount of a real-world payment. _Tr

The Interledger Protocol does not have a specific definition of "small", nor a size limit on packets. Each connector can choose minimum and maximum packet sizes they are willing to relay; as a result, any path's maximum packet size is the smallest maximum packet size among the connectors in that path. To be compatible with as much of the network as possible, one should choose packet sizes that fit between the minimum and maximum values of as many connectors as possible.


### Addresses

_Interledger addresses_ (also called _ILP addresses_) provide a universal way to address senders, receivers and connectors. These addresses are used in several different protocol layers, but their most important feature is to enable routing on the Interleder Protocol layer. Interledger addresses are hierarchical, dot-separated strings where the left-most segment is most significant. An example address might look like:
Expand All @@ -157,9 +149,9 @@ If two parties in the Interledger have a "parent/child" connection rather than a

## Interledger Security

**Interledger uses *conditional transfers* to secure payments across multiple hops and even through untrusted connectors.** Everyone only needs to trust their direct peers, no matter how many connectors are involved in forwarding a given packet. Connectors take some risk, but this risk can be managed and is primarily based upon the connector's chosen peers.
**Interledger uses _conditional transfers_ to secure payments across multiple hops and even through untrusted connectors.** Everyone only needs to trust their direct peers, no matter how many connectors are involved in forwarding a given packet. Connectors take some risk, but this risk can be managed and is primarily based upon the connector's chosen peers.

> **Hint:** Conditional transfers or *authorization holds* are the financial equivalent of a [two-phase commit](http://foldoc.org/two-phase%20commit).
> **Hint:** Conditional transfers or _authorization holds_ are the financial equivalent of a [two-phase commit](http://foldoc.org/two-phase%20commit).

Because each party is isolated from risks beyond their immediate peers, longer paths are not inherently more risky than shorter paths. This enables longer paths to compete with shorter paths to convey money from any given sender to any given receiver, while reducing the risk to the sender.

Expand Down
Loading