Updated HTTP-ILP (Continuation of #149) #306

michielbdejong · 2017-09-27T09:23:58Z

rebased on master
filename corrected
doc version header added
Headers renamed from e.g. X-Pay to just Pay

emschwartz · 2017-09-27T15:13:12Z

0014-http-ilp/0014-http-ilp.md

+}
+```
+
+The HTTP-ILP server module now knows the ILP address and caches it in memory for a certain period (depending on the cache header of the above request.) The reason we had Ankita enter the SPSP address and not the ILP address is because the ILP address may change over time as ILP providers change their routing structure. Note that ILP may support multihoming (this is still being debated as of this writing), so there may also be more than one ILP address.


Note that ILP may support multihoming (this is still being debated as of this writing), so there may also be more than one ILP address.

This can be removed

emschwartz · 2017-09-27T15:14:04Z

0014-http-ilp/0014-http-ilp.md

+
+### 2.2. Server rejects request, because token is new and unfunded
+
+The server returns an HTTP error of `402 Payment Required` and includes response headers showing the amount (how much the request would have cost), an ILP address and a condition seed.


It says it will show the amount the request would have cost but the example doesn't show that

emschwartz · 2017-09-27T15:14:49Z

0014-http-ilp/0014-http-ilp.md

+
+The condition_seed is now a shared secret between the client and server, but will be unknown to any third-party connectors between them.
+
+That means that if the payment fails, the client can blame the server (assuming it considers itself honest and not compromised.) The client can't prove any wrongdoing to a third party, but since amounts are likely to be very low, this probably wouldn't be worth doing anyway. Also, proving wrongdoing would also involve proving that the server did not provide the agreed-upon service, which is probably near impossible in most cases anyway. However, since it can detect malicious behavior, the client can blacklist malicious hosts and not deal with them in the future.


I don't think we need this explanation. It's more confusing than helpful

emschwartz · 2017-09-27T15:15:54Z

0014-http-ilp/0014-http-ilp.md

+
+The `fulfillment` is generated as:
+
+* Fulfillment: `HMAC(SHA256, condition_seed, destination_account || destination_amount)`


Shouldn't it also include the pay_token?

Is there a reason why this protocol doesn't use standard PSK?

emschwartz · 2017-09-27T15:19:48Z

0014-http-ilp/0014-http-ilp.md

+
+When the prepared payment reaches the receiving wallet, the webhook that is registered with the ankita+filepay@nexus.justmoon.com receiver is triggered. Note that the wallet does not fulfill the payment yet.
+
+### 2.4. Wallet POSTs a payment notification


Why not just have the server connect to the ILSP using something like BTP, rather than creating yet another encoding for ILP payment details? Websockets might not be ideal but I think it would be better if the server itself were a standard ILP receiver using some ledger protocol to talk to the ILSP.

sharafian · 2017-09-27T20:37:59Z

This should describe what /~https://github.com/justmoon/koa-ilp does now. A lot of the contents seem dated

michielbdejong · 2017-10-06T19:33:09Z

In the updated version, the Pay header which superagent-ilp expects is:
[ destinationAmount, destinationAccount, sharedSecret ].join(' ')

And that's also the header that koa-ilp produces.

So that's probably the one we want to document in this RFC and use in the streaming payments tutorial

comments all addressed

michielbdejong · 2017-10-07T17:29:53Z

Updated the documentation to remove the webhooks stuff (koa-ilp now just uses a plugin).
Also replaced the condition seed with standard PSK, and added a stub description of streaming http-ilp in section 3.

sharafian · 2017-10-09T17:17:50Z

0014-http-ilp/0014-http-ilp.md

+
+### 1.1. Server admin installs an ILP payment module
+
+After deciding to use HTTP-ILP, Ankita searches the web on instructions on how to set this up. She finds an open-source HTTP-ILP server module which is compatible with the REST framework ([Koa](https://koajs.com)) that she is already using.


This should include a link to the koa-ilp module too

sharafian · 2017-10-09T17:18:57Z

0014-http-ilp/0014-http-ilp.md

+
+Next, Ankita logs back into her server and edits a config file of the HTTP-ILP server module to enter the plugin type and credentials she obtained:
+
+``` ini


Right now this is configured through the environment, not an ini file.

It feels weird that an rfc describes one specific implementation in such exact detail, but at the same time if the only current implementation uses env vars, then ok let's follow that example in the rfc too.

I changed it to env vars, but not sure it now matches koa-ilp, because of interledgerjs/koa-ilp#4

sharafian · 2017-10-09T17:19:41Z

0014-http-ilp/0014-http-ilp.md

+
+### 1.4. Paid HTTP server fetches receiver information
+
+When the HTTP-ILP server module loads up, it uses [plugin#getAccount](../0004-ledger-plugin-interface/0004-ledger-plugin-interface.md) to look up the Interledger address from the plugin.


The plugin also gets a subscription to its ledger in order to listen for incoming payments

sharafian · 2017-10-09T17:21:01Z

0014-http-ilp/0014-http-ilp.md

+
+### 2.1. Client generates a server-specific token from the hostname and its local secret:
+
+The uploader tool contains an HTTP-ILP client module. This client module may for instance generate and locally save a `client_secret` using 256 bits of cryptographically secure randomness.


Might be worth mentioning the existing client tools, superagent-ilp and ilp-curl

sharafian · 2017-10-09T17:22:16Z

0014-http-ilp/0014-http-ilp.md

+
+### 2.2. Server responds with payment details
+
+The server returns an HTTP error of `402 Payment Required` and includes response headers showing the amount, an ILP address and a shared secret.


The server doesn't respond with 402 to an OPTIONS request; it uses a 204. 402 is returned if the actual API call is attempted without payment.

sharafian · 2017-10-09T17:23:21Z

0014-http-ilp/0014-http-ilp.md

+Pay-Balance: 0
+```
+
+The client can now use the shared secret to create a condition to pay this host. The shared secret may for instance be generated by the server as follows:


Should explain that the destinationAccount and sharedSecret are used as the parameters to PSK

sharafian · 2017-10-09T17:24:02Z

0014-http-ilp/0014-http-ilp.md

+
+When the prepared payment reaches the server, it is fulfilled and the token's balance is increased.
+
+There is a chance that the HTTP-ILP server module will process the payment, but the fulfillment doesn't make it all te way back to the sender.


sharafian · 2017-10-09T17:25:25Z

0014-http-ilp/sequence.mmd

+participant Payee
+activate Payer
+Payer->>+Payee: Attempt Request
+Payee-->>-Payer: 402 Payment Required


If this is describing the OPTIONS flow, it should begin with an OPTIONS request that ends with a 204, rather than a regular request that ends with a 402.

sharafian · 2017-10-09T17:26:40Z

0014-http-ilp/0014-http-ilp.md

+
+``` http
+HTTP/1.1 200 OK
+Pay: 10 us.nexus.ankita.~recv.filepay SkTcFTZCBKgP6A6QOUVcwWCCgYIP4rJPHlIzreavHdU


Unhash might make a better example application, because we know exactly what the API calls look like for it. For instance, an Unhash OPTIONS request includes the Unhash-Content-Length header to calculate the price.

ok, I'll add Unhash-Content-Length to the OPTIONS call and explain that other services would have other product descriptors which the client can add to help determine the price for a request.

sharafian · 2017-10-09T17:27:45Z

0014-http-ilp/0014-http-ilp.md

+
+Notice how the 100 units credit from the payment was added to the balance and the 10 unit cost for the current request was subtracted.
+
+### 3. Streaming flow


I think the streaming flow is different enough that it should go in another proposal. The HTTP-ILP described here is pretty strictly request/response rather than streaming

ok, I'll move that to a separate PR.

Unfortunately, Github doesn't seem to link it correctly otherwise.

comments addressed

michielbdejong requested a review from justmoon September 27, 2017 09:24

This was referenced Sep 27, 2017

Initial version of a spec providing ILP payments for HTTP calls #149

Closed

Ideas for improving HTTP-ILP #307

Closed

emschwartz previously requested changes Sep 27, 2017

View reviewed changes

emschwartz changed the title ~~Continuation of #149~~ Updated HTTP-ILP (Continuation of #149) Sep 29, 2017

emschwartz mentioned this pull request Sep 29, 2017

ILQPv2: Replace ILQP with End-to-End Quoting #309

Closed

michielbdejong force-pushed the mj-pay-header branch from ff6e28c to 417388c Compare October 7, 2017 16:50

michielbdejong requested a review from sharafian October 7, 2017 17:30

sharafian previously requested changes Oct 9, 2017

View reviewed changes

justmoon and others added 7 commits October 23, 2017 12:19

docs: http-ilp rough draft

8829cf9

docs(0014): convert sequence diagram to png

bce7f81

Unfortunately, Github doesn't seem to link it correctly otherwise.

fix: correct filename 0004 -> 0014

a4bf6cf

chore: add doc version header

dad2e30

fix: remove X- prefix from header names

19866ef

update

ce37e55

chore: apply review comments

58d8dcb

michielbdejong force-pushed the mj-pay-header branch from 9caf6ca to 58d8dcb Compare October 23, 2017 10:40

michielbdejong requested a review from sharafian October 23, 2017 10:41

sharafian approved these changes Oct 30, 2017

View reviewed changes

Merge branch 'master' into mj-pay-header

4c04e7e

michielbdejong merged commit e9e797a into master Oct 30, 2017

adrianhopebailie deleted the mj-pay-header branch August 14, 2018 15:47

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Updated HTTP-ILP (Continuation of #149) #306

Updated HTTP-ILP (Continuation of #149) #306

michielbdejong commented Sep 27, 2017

emschwartz Sep 27, 2017

emschwartz Sep 27, 2017

emschwartz Sep 27, 2017

emschwartz Sep 27, 2017

emschwartz Sep 27, 2017

sharafian commented Sep 27, 2017 •

edited

Loading

michielbdejong commented Oct 6, 2017

michielbdejong commented Oct 7, 2017

sharafian Oct 9, 2017

sharafian Oct 9, 2017

michielbdejong Oct 20, 2017 •

edited

Loading

michielbdejong Oct 23, 2017

sharafian Oct 9, 2017

sharafian Oct 9, 2017

sharafian Oct 9, 2017

sharafian Oct 9, 2017

sharafian Oct 9, 2017

sharafian Oct 9, 2017

sharafian Oct 9, 2017

michielbdejong Oct 20, 2017

sharafian Oct 9, 2017

michielbdejong Oct 20, 2017


		### 2.2. Server rejects request, because token is new and unfunded

		The server returns an HTTP error of `402 Payment Required` and includes response headers showing the amount (how much the request would have cost), an ILP address and a condition seed.


		The condition_seed is now a shared secret between the client and server, but will be unknown to any third-party connectors between them.

		That means that if the payment fails, the client can blame the server (assuming it considers itself honest and not compromised.) The client can't prove any wrongdoing to a third party, but since amounts are likely to be very low, this probably wouldn't be worth doing anyway. Also, proving wrongdoing would also involve proving that the server did not provide the agreed-upon service, which is probably near impossible in most cases anyway. However, since it can detect malicious behavior, the client can blacklist malicious hosts and not deal with them in the future.


		The `fulfillment` is generated as:

		* Fulfillment: `HMAC(SHA256, condition_seed, destination_account \|\| destination_amount)`


		When the prepared payment reaches the receiving wallet, the webhook that is registered with the ankita+filepay@nexus.justmoon.com receiver is triggered. Note that the wallet does not fulfill the payment yet.

		### 2.4. Wallet POSTs a payment notification


		### 1.1. Server admin installs an ILP payment module

		After deciding to use HTTP-ILP, Ankita searches the web on instructions on how to set this up. She finds an open-source HTTP-ILP server module which is compatible with the REST framework ([Koa](https://koajs.com)) that she is already using.


		Next, Ankita logs back into her server and edits a config file of the HTTP-ILP server module to enter the plugin type and credentials she obtained:

		``` ini


		### 1.4. Paid HTTP server fetches receiver information

		When the HTTP-ILP server module loads up, it uses [plugin#getAccount](../0004-ledger-plugin-interface/0004-ledger-plugin-interface.md) to look up the Interledger address from the plugin.


		### 2.1. Client generates a server-specific token from the hostname and its local secret:

		The uploader tool contains an HTTP-ILP client module. This client module may for instance generate and locally save a `client_secret` using 256 bits of cryptographically secure randomness.


		### 2.2. Server responds with payment details

		The server returns an HTTP error of `402 Payment Required` and includes response headers showing the amount, an ILP address and a shared secret.


		When the prepared payment reaches the server, it is fulfilled and the token's balance is increased.

		There is a chance that the HTTP-ILP server module will process the payment, but the fulfillment doesn't make it all te way back to the sender.


		Notice how the 100 units credit from the payment was added to the balance and the 10 unit cost for the current request was subtracted.

		### 3. Streaming flow

Updated HTTP-ILP (Continuation of #149) #306

Updated HTTP-ILP (Continuation of #149) #306

Conversation

michielbdejong commented Sep 27, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

sharafian commented Sep 27, 2017 • edited Loading

michielbdejong commented Oct 6, 2017

michielbdejong commented Oct 7, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

michielbdejong Oct 20, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

sharafian commented Sep 27, 2017 •

edited

Loading

michielbdejong Oct 20, 2017 •

edited

Loading