Proposal for tutorial order

[emschwartz]

Here's the way I would think of laying out the tutorials in terms of what you learn from each of them:

1. It's easy to build apps that accept payments with Interledger (for this one I'd almost focus more on how easy it is to use the existing modules rather than rolling things from scratch)
2. It's easy to accept money from people even if they're on a different ledger (in that one I would focus on plugins, hashlocks, and the ILP packet)
3. You can build fancier things with this type of payment method (streaming payments and the Pay header)
4. You can make your payments faster by using trustlines and payment channels (also introduce the HTLA concept)

...etc

Thoughts?

[adrianhopebailie]

I've given this some thought, although more in the context of expressing the value of the standard, not how to build tutorials. This relates to how I see this being part of the Web Payments work but I think applies generally to payment on the Web with ILP.

So here is the order of importance of the messaging I think we need to get across, perhaps we can align the tutorials?

1. ILP Addresses, two-phase commit and SHA-256 Condition/Fulfillments: ILP is an abstraction that could be overlaid on almost any payment. It defines a standard way to address any account (ILP Address), a simple two phase commit flow (payments are always rejected, expired or committed) and standard primitives that should be included in all quotes/invoices (condition - or key for creating a condition) and receipts (fulfillments). If both the payer and payee follow those standards they get the following benefits (without even considering multi-hop payments):

   • Easy assessment of if they are able to deliver a payment to a given address (any number of methods for doing this can be developed if there is a standard addressing scheme)
   • Per payment addressing
   • Easy reconciliation of the payment request and the payment (with cryptographic proof that they match)
   • Cryptographic evidence that a payment was completed (if using IPR)
   • Cryptographic binding of receipt to payment details including address and amount (if the fulfillment is derived from the payment details like with PSK)

2. Simple Payment Setup Protocol: SPSP defines a WebFinger profile for discovering payment information and a standard schema for that data-set. It allows the payee to provide the payer with either a URL where they can retrieve the payment data in that standard format or an account@provider style account name that can be used to discover the endpoint.

3. Conditional payments: If both the payer and payee follow those standards then they can use a payment network that protects them from bad-actors (i.e. it uses conditional payments). This applies even if they just transact directly (over XRP Escrow for example).

4. Multi-hop: Taking this a step further, by following this standard the payer can make the payment via multiple networks because it can be routed reliably by intermediaries (using the ILP address) and each intermediary can protect themselves from bad behaviour by the rest of the participants in the route by using conditional payments.

[emschwartz]

@adrianhopebailie I think those are all good things to explain, particularly in the context of the W3C and other standards bodies.

I think the goal of the tutorials is slightly different. In my opinion, the tutorials should be targeted at average web developers who might want to build ILP into their app or service. It should give just enough understanding of how ILP works and then focus on what you can do with it. I would see the main benefit as "make money", rather than focusing on details of how this compares to traditional payment methods.

[adrianhopebailie]

In my opinion, the tutorials should be targeted at average web developers who might want to build ILP into their app or service.

👍

[michielbdejong]

@emschwartz proposes:

1. It's easy to build apps that accept payments with Interledger

@adrianhopebailie proposes:

1. ILP Addresses, two-phase commit and SHA-256 Condition/Fulfillments

So then the letter shop tutorial is a good balance between those two priorities, I think? It shows how to build an app that accepts payments, and along the way it explains ILP addresses and the ILP hashlock (I think showing raw low-level code calling crypto.something works well for that, better than an opaque 'getCondition' function). And it allows you to buy letters! ;)

@emschwartz proposes:
3. You can build fancier things with this type of payment method (streaming payments and the Pay header)
4. You can make your payments faster by using trustlines and payment channels (also introduce the HTLA concept

That's #2, I'm fine with splitting that up in a Pay-header part and a BTP trustlines part, so that it's not too much information in one tutorial. We can mention payment channels and HTLA there, and also show how to use paychan-based plugins, as long as we don't include actual code snippets about how payment channels work under the hood (that would be a much more advanced tutorial, right?).

@emschwartz proposes:

2. It's easy to accept money from people even if they're on a different ledger

@adrianhopebailie proposes:

4. Multi-hop

For this, the shop and the proxy from the letter-shop tutorial both need to connect to Amundsen. I was going to do that in the third tutorial, but I'm open to switching the order.

@adrianhopebailie proposes:

3. Conditional payments

I don't really know what code example to write about that. It's already in the Letter Shop, where the hashlock is explained. I can't really write about 'the ledger will reject an incorrect fulfillment from the shop' there, because the shop chose the fulfillment, and there are no connectors involved. But I will obviously discuss the 'trustless connector' topic in the connect-to-Amundsen tutorial. Is that enough?

@adrianhopebailie proposes:

2. Simple Payment Setup Protocol

As you know, I'm not a big fan of SPSP, since it's not useful for setting up paid web apps like unhash, and its reliance on DNS is not very compatible with the decentralized architecture of blockchains. SPSP is very high-layer, and specifically for human-to-human negotiation.

It allows the payee to provide the payer with either a URL where they can retrieve the payment data in that standard format

Having a user go to their internet banking website and type in an SPSP address into the recipient field is still a very common flow now (see for instance paypal), but if machines negotiate the payment (which I think is the case in some of the more interesting and futuristic applications of Interledger), they don't need the WebFinger redirect. So I didn't have an SPSP tutorial on my todo list (yet).

I would say, let's publish the Letter Shop tutorial, then I'll split the streaming payments tutorials into two parts (a HTTP-ILP part and a BTP part), and add a connect-to-testnet tutorial. I can write the connect-to-testnet tutorial in such a way that it only relies on the Letter Shop, so the learning tree becomes:

Letter Shop -----\
     |           |
     v           v
 HTTP-ILP      Connectors
     |           |
     v           v
    BTP ------> (...)

[adrianhopebailie]

@michielbdejong can you provide a short summary of your latest thinking around the flow of tutorials?

[michielbdejong]

Yes! It's still pretty much what I wrote in #5 (comment). Basically:

1. Letter Shop - conditional transfers, hashlocks, Interledger addresses, Pay header.
2. http-ilp - PSK and more in-depth discussion of the Pay header.
3. Streaming Payments - light on theory, but tries to excite enthusiasm about paying for resource as-you-stream.
4. Hosted Ledgers (previously called 'trustlines') - BTP, tries to excite enthusiasm for the use of (off-ledger) trustlines.
5. Multi-Hop Payments. Includes ILQP
6. Testnet of Testnets.
7. Connectors. Includes route broadcasts

[michielbdejong]

Superseded by #34