Overhaul architecture overview, separate ledger requirements #181

emschwartz · 2017-03-29T19:54:39Z

RFC 1 missed or did not emphasize a lot of key details of the interledger architecture, while repeating certain content and including too much detail about the ledger requirement. this moves the ledger requirements to a separate RFC and restructures the architecture overview to highlight the key aspects of interledger that newcomers should understand

Based on feedback from @professorhantzen

emschwartz · 2017-03-29T21:08:46Z

0001-interledger-architecture/0001-interledger-architecture.md


-All electronic transfers have to be recorded in stateful systems. Otherwise the same instance of an asset could be sent to two different destinations, essentially duplicating the asset. This is also known as a double-spend. We call these stateful systems *ledgers*.
+[diagram]


We need a diagram here that ideally shows a sender, 2 connectors, 3 ledgers, and a receiver

emschwartz · 2017-03-29T21:11:29Z

0001-interledger-architecture/0001-interledger-architecture.md

-All Interledger transport protocols use the [Interledger Protocol (ILP)](#interledger-protocol-ilp) to communicate with connectors about transfer requests. This may include requesting a quote or requesting a transfer on another ledger.
-
-The Interledger layer defines a standard way to refer to ledgers, accounts and amounts. This is used in routing as well as to try and make quotes comparable.
+![Interledger architecture layers](../shared/graphs/interledger-model.svg)


The SVG doesn't render because of github/markup#556, we should either find a workaround or render a PNG file as well from the graph. The only issue with doing that is the node libraries that do that include PhantomJS, which is a pretty heavy dependency just for rendering 1-2 PNG files.

sappenin · 2017-03-30T01:24:09Z

0001-interledger-architecture/0001-interledger-architecture.md

@@ -1,252 +1,135 @@
 # Interledger Architecture

-This document outlines the Interledger architecture and explains how the different layers relate to each other. The [Interledger Protocol (ILP)](#interledger-protocol-ilp) is one layer in the Interledger architecture.
+The Interledger protocol suite provides for secure payments across multiple assets on different ledgers.


I like the usage of these grouping terms like Interledger Architecture and Interledger Protocol Suite, but I'm not sure the document clearly differentiates between the two terms. Are these meant to be synonymous, or is “Interledger Protocol Suite” a component of the “Interledger Architecture”, which actually has more to it than just the protocol suite?

sappenin · 2017-03-30T01:28:54Z

0001-interledger-architecture/0001-interledger-architecture.md


-The Interledger architecture is heavily inspired by the Internet architecture described in [RFC 1122](https://tools.ietf.org/html/rfc1122), [RFC 1123](https://tools.ietf.org/html/rfc1123) and [RFC 1009](https://tools.ietf.org/html/rfc1009).
+The [Interledger Protocol (ILP)](#interledger-layer) is the core of the Interledger protocol suite.


I still find our colloquial usage of ILP to be unclear. Let's assume there's some proper name for the collection of all Interledger protocols (the suite). One of those protocols (the thing in RFC-3) is called “ILP”, or “Interledger Protocol”. If you put it all together, it reduces to the following: there’s a collection of Interledger protocols, one of which is the "Interledger Protocol.”

Wouldn’t it make more sense to start calling the thing defined by RFC-3 something else, like ILPC, which expanded would read Interledger Protocol Core or just Interledger Core Protocol?

(I'm open to the argument that this naming "ship" has already sailed, but figured I'd give it another try)

As an outsider coming to this - I agree. "ILP" seems to be the widely used term to reference the entire suite/stack. It's certainly the term used by everyone I know outside the dev circle who discusses, well... ILP. The current situation that one layer of the stack also shares the same name as the whole stack is confusing to newcomers and a hinderance to unambiguous discussion. The ILPC distinction suggested here is a good solution, I would take it further and drop the "protocol". We know it's a protocol already given the suite would be/is referred to as the Interledger Protocol, so we could simply refer to that layer as Interledger Core.

So, the Interledger Protocol (ILP) is the entire stack of protocols, one layer of which is Interledger Core, or ILC.

emschwartz · 2017-03-30T14:52:58Z

I still find our colloquial usage of ILP to be unclear. Let's assume there's some proper name for the collection of all Interledger protocols (the suite). One of those protocols (the thing in RFC-3) is called “ILP”, or “Interledger Protocol”. If you put it all together, it reduces to the following: there’s a collection of Interledger protocols, one of which is the "Interledger Protocol.”

@sappenin @professorhantzen I added a note that tries to clarify the colloquial use of the term ILP. Does that help?

Some of that confusion comes from how closely the architecture (and terminology) mirrors that of the Internet. The Internet Protocol is the part that defines the IP address and packet format, but people often describe the whole stack (and even the Web) as the Internet or using the Internet Protocol / IP.

Technically it is correct to call only the part that specifies the address and packet format and the flow the "Interledger Protocol" and the stack is the "Interledger stack" or "Interledger protocol suite", but I wouldn't expect that distinction to make it into normal conversation.

Another way to look at it is: if you start taking away layers of the stack and saying "I don't want to use those", at what point is what you've got no longer using the Interledger Protocol? I'd say it's when you're no longer using what's defined in IL-RFC 3.

sappenin · 2017-03-30T17:01:46Z

Another way to look at it is: if you start taking away layers of the stack and saying "I don't want to use those", at what point is what you've got no longer using the Interledger Protocol? I'd say it's when you're no longer using what's defined in IL-RFC 3.

@emschwartz That's a helpful distinction. Perhaps consider adding more of your rationale to the doc, like some adaptation of your paragraph above? Might be helpful for future readers to know a bit more about why the colloquialism exists.

emschwartz · 2017-03-31T09:16:55Z

Perhaps consider adding more of your rationale to the doc, like some adaptation of your paragraph above? Might be helpful for future readers to know a bit more about why the colloquialism exists.

I tried adding another sentence to that intro with that explanation but it felt like too much explanation, given that the intended audience presumably doesn't understand Interledger very well yet.

sappenin · 2017-03-31T15:08:10Z

That's a fair point - perhaps that "more explanation" might make sense in an FAQ or maybe in the glossary that @michielbdejong is proposing in #180.

mDuo13

This is a big improvement over the existing doc. Moving ledger requirements out to its own RFC is a good idea. I noticed a few things that need to be corrected, but I'm happy with the direction of these changes.

mDuo13 · 2017-03-29T19:56:14Z

0001-interledger-architecture/0001-interledger-architecture.md


-All electronic transfers have to be recorded in stateful systems. Otherwise the same instance of an asset could be sent to two different destinations, essentially duplicating the asset. This is also known as a double-spend. We call these stateful systems *ledgers*.
+[diagram]


don't forget to replace this with an actual diagram before merging

mDuo13 · 2017-03-31T16:20:22Z

0001-interledger-architecture/0001-interledger-architecture.md


-![Interledger architecture layers](../shared/graphs/interledger-model.svg)
+**Interledger uses *conditional transfers* to secure payments across multiple hops and even through untrusted connectors.**
+Senders are guaranteed proof that the receiver got the payment or their money back.


Without a blank line between, this is interpreted by most Markdown parsers as a hard-wrapped continuation of the previous sentence's paragraph. You should probably set it off with a separate line, and maybe even make it into bullet points.

Also, we can strengthen this sentence:

Senders are guaranteed proof that the receiver got the payment or their money back.

Suggested rephrase:

Senders are guaranteed cryptographic proof that the receiver got the payment or their money back, no matter how many ledgers and connectors are in between.

I actually intended for that to be a single paragraph

mDuo13 · 2017-03-31T16:21:34Z

0001-interledger-architecture/0001-interledger-architecture.md

-The application layer is the top layer of the Interledger protocol suite. Protocols on this layer are responsible for negotiating the key properties of a payment:
+Each local transfer is first *prepared* and then either *executed* or *rejected*.
+When a transfer is prepared, the ledger puts the funds of the source account on hold with a *cryptographic condition* and *timeout*.
+If the condition is fulfilled before the timeout, the transfer is executed and the funds are transferred.


Again, this should either be bullet points (numbered list?), a separate paragraph with a blank line between it and the previous one, or actually a continuation of the previous line.

mDuo13 · 2017-03-31T16:21:59Z

0001-interledger-architecture/0001-interledger-architecture.md

-* Source Account
-* Destination Account
-* Destination Amount
+Inspired by the [Lightning Network](http://lightning.network), Interledger uses the digest of the [SHA-256](https://en.wikipedia.org/wiki/SHA-2) hash function as the condition for transfers. The fulfillment is a valid 32-byte preimage for the hash specified when the transfer was prepared. Ledgers are responsible for validating fulfillments. [Transport Layer](#transport-layer) protocols are used by the sender and receiverto generate the condition for a particular payment.


typo: "receiverto"

mDuo13 · 2017-03-31T16:28:26Z

0001-interledger-architecture/0001-interledger-architecture.md


-A reference implementation of a ledger using 5BLP can be found [here](https://github.com/interledger/five-bells-ledger).
+Most implementations of Interledger use a plugin architecture to abstract the differences between different ledgers. For an example of this, see [IL-RFC 4](../0004-ledger-plugin-interface/0004-ledger-plugin-interface), which defines the interface for the Javascript implementation.


Broken link: ../0004-ledger-plugin-interface/0004-ledger-plugin-interface is missing the .md on the end

mDuo13 · 2017-03-31T16:35:10Z

0001-interledger-architecture/0001-interledger-architecture.md


-#### Legacy Protocols (e.g. ACH, ISO 20022)
+[Interledger Addresses](../0015-interledger-addresses/0015-interledger-addresses.md) provide a ledger-agnostic way to address ledgers and accounts. Interledger addresses are dot-separated strings that contain prefixes to group ledgers. An example address might look like:


Broken link: IL-RFC 15 is named "ILP Addresses", not "Interledger Addresses"

(I think the name ILP is technically accurate here, because the addressing is used within the core Interledger Protocol itself?)

mDuo13 · 2017-03-31T16:55:43Z

0001-interledger-architecture/0001-interledger-architecture.md


-For example, Bitcoin supports SHA-256 hashlocked escrow transfers which means it can participate in ILP Interledger transactions. Bitcoin's [BIP-65](https://github.com/bitcoin/bips/blob/master/bip-0065.mediawiki) proposal provided the timeouts required for Basic level support.
+The [Interledger Protocol (ILP)](../0003-interledger-protocol/0003-interledger-protocol.md) is the core of the Interledger stack and defines a standard address packet format that instruct connectors where to send a payment.


Instead of "standard address packet format" I would just say "packet format"

That phrase was meant to read "standard address and packet format"

mDuo13 · 2017-03-31T17:05:59Z

Do you think it's useful to have an "extended" version of the protocol diagram? For example:

mDuo13

🎉

RFC 1 missed or did not emphasize a lot of key details of the interledger architecture, while repeating certain content and including too much detail about the ledger requirement. this moves the ledger requirements to a separate RFC and restructures the architecture overview to highlight the key aspects of interledger that newcomers should understand

emschwartz · 2017-04-03T07:35:11Z

I'm going to merge this PR now. If anyone has more comments we can add further changes to the docs later. cc @justmoon

emschwartz requested review from justmoon and mDuo13 March 29, 2017 19:54

emschwartz commented Mar 29, 2017

View reviewed changes

sappenin mentioned this pull request Mar 30, 2017

establish names for hops etc. #180

Closed

sappenin reviewed Mar 30, 2017

View reviewed changes

emschwartz force-pushed the es-improve-explanation branch from 3a8eb3d to f930ac7 Compare March 31, 2017 09:17

emschwartz mentioned this pull request Mar 31, 2017

Add RFC 18: Connector Risk Mitigations #183

Merged

mDuo13 suggested changes Mar 31, 2017

View reviewed changes

mDuo13 approved these changes Apr 1, 2017

View reviewed changes

sappenin mentioned this pull request Apr 1, 2017

Initial discussion-point commit of proposed InterledgerAddress per IL-RFC 15 interledger-deprecated/java-ilp-core#18

Merged

emschwartz added 3 commits April 3, 2017 09:24

docs(graphs): add model, old model -> protocol suite

5c80cc5

docs: Add interledger.js link to readme

a94024b

emschwartz force-pushed the es-improve-explanation branch from 20f23b2 to a94024b Compare April 3, 2017 07:24

emschwartz merged commit b2d899c into master Apr 3, 2017

emschwartz deleted the es-improve-explanation branch October 30, 2017 19:02


		All electronic transfers have to be recorded in stateful systems. Otherwise the same instance of an asset could be sent to two different destinations, essentially duplicating the asset. This is also known as a double-spend. We call these stateful systems ledgers.
		[diagram]


		The Interledger architecture is heavily inspired by the Internet architecture described in [RFC 1122](https://tools.ietf.org/html/rfc1122), [RFC 1123](https://tools.ietf.org/html/rfc1123) and [RFC 1009](https://tools.ietf.org/html/rfc1009).
		The [Interledger Protocol (ILP)](#interledger-layer) is the core of the Interledger protocol suite.


		A reference implementation of a ledger using 5BLP can be found [here](https://github.com/interledger/five-bells-ledger).
		Most implementations of Interledger use a plugin architecture to abstract the differences between different ledgers. For an example of this, see [IL-RFC 4](../0004-ledger-plugin-interface/0004-ledger-plugin-interface), which defines the interface for the Javascript implementation.


		#### Legacy Protocols (e.g. ACH, ISO 20022)
		[Interledger Addresses](../0015-interledger-addresses/0015-interledger-addresses.md) provide a ledger-agnostic way to address ledgers and accounts. Interledger addresses are dot-separated strings that contain prefixes to group ledgers. An example address might look like:


		For example, Bitcoin supports SHA-256 hashlocked escrow transfers which means it can participate in ILP Interledger transactions. Bitcoin's [BIP-65](https://github.com/bitcoin/bips/blob/master/bip-0065.mediawiki) proposal provided the timeouts required for Basic level support.
		The [Interledger Protocol (ILP)](../0003-interledger-protocol/0003-interledger-protocol.md) is the core of the Interledger stack and defines a standard address packet format that instruct connectors where to send a payment.

Overhaul architecture overview, separate ledger requirements #181

Overhaul architecture overview, separate ledger requirements #181

Uh oh!

Conversation

emschwartz commented Mar 29, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

emschwartz commented Mar 30, 2017

Uh oh!

sappenin commented Mar 30, 2017

Uh oh!

emschwartz commented Mar 31, 2017

Uh oh!

sappenin commented Mar 31, 2017

Uh oh!

mDuo13 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mDuo13 commented Mar 31, 2017

Uh oh!

mDuo13 left a comment

Choose a reason for hiding this comment

Uh oh!

emschwartz commented Apr 3, 2017

Uh oh!

Uh oh!

emschwartz commented Mar 29, 2017 •

edited

Loading