Add STREAM receipts #570

wilsonianb · 2020-02-27T17:02:39Z

Signed-off-by: Brandon Wilson <brandon@coil.com>

sharafian · 2020-03-13T20:37:42Z

0029-stream/0029-stream.md

+| Receipt Nonce | UInt128 | A random nonce pre-shared between the verifying party and the receiver used to identify the STREAM connection. |
+| Stream ID | UInt8 | Identifier of the stream this receipt refers to. |
+| Total Received | UInt64 | Total amount, denominated in the units of the receiver, that the receiver has received on this stream thus far. |
+| Stream Start Time | UInt64 | A UNIX timestamp referring to the time that the stream was established at the receiver. |


It's worth considering whether we should use an InterledgerTimestamp here. It still is fixed length, and although it is a little trickier to parse it solves things like leap seconds. That said a unix timestamp is gonna be easier to use in a lot of different environments.

sharafian · 2020-03-13T20:38:50Z

0029-stream/0029-stream.md

+
+| Field | Type | Description |
+|---|---|---|
+| HMAC | UInt256 | HMAC-SHA256 over all other fields using a secret pre-shared between the verifying party and the receiver. |


we should explicitly name this pre-shared secret the Receipt Secret and be explicit that it's an additional optional parameter to create a STREAM connection. I could imagine someone reading this and thinking we're referring to the shared secret here

bc04d01 adds more details on Receipt Secret and Receipt Nonce

sharafian · 2020-03-13T20:40:56Z

0029-stream/0029-stream.md

@@ -192,6 +193,8 @@ Client streams MUST be odd-numbered starting with 1 and server-initiated streams

 Money can be sent for a given stream by sending an ILP Prepare packet with a non-zero `amount` and a `StreamMoney` frame in the STREAM packet to indicate which stream the money is for. A single ILP Prepare can carry value destined for multiple streams and the `shares` field in each of the `StreamMoney` frames indicates what portion of the Prepare amount should go to each stream.

+The receiver SHOULD include `StreamReceipt` frames in the ILP Fulfill packet indicating the total amount of money received in each stream, unless a secret key with which to generate receipts was not pre-shared with the receiver. Receipts can be verified, in order to confirm payment, using the pre-shared secret.


A Receipt Secret to generate receipts and a Receipt Nonce to include in those receipts. Also did we land on whether there's a required length for the Receipt Secret & Receipt Nonce? Might make sense to say they're both 32 bytes to prevent someone from DoSing an SPSP server with a massive Receipt Secret

Right now, it's 16 byte nonce and 32 byte secret (https://github.com/interledger/rfcs/pull/570/files#diff-0bbc536b39826341170954e2675f765cR72-R73).
Is it worth making the nonce 32 bytes?

Well for the nonce we only need uniqueness, given it's public. So 16 is probably fine. 32 byte secret is good because it's often gonna be output of sha256. I think those values are good, but open to hear any other opinions

sharafian · 2020-03-16T17:49:19Z

0029-stream/0029-stream.md

@@ -192,6 +195,8 @@ Client streams MUST be odd-numbered starting with 1 and server-initiated streams

 Money can be sent for a given stream by sending an ILP Prepare packet with a non-zero `amount` and a `StreamMoney` frame in the STREAM packet to indicate which stream the money is for. A single ILP Prepare can carry value destined for multiple streams and the `shares` field in each of the `StreamMoney` frames indicates what portion of the Prepare amount should go to each stream.

+The receiver SHOULD include `StreamReceipt` frames in the ILP Fulfill packet indicating the total amount of money received in each stream, unless a Receipt Secret and Receipt Nonce were not pre-shared with the receiver. Receipts can be verified, in order to confirm payment, using the Receipt Secret.


I think it's worth explaining a little bit how this works because I think the first thing someone reading this will get tripped up on is that the verifying party (who they may imagine to be the sender) can sign new receipts.

Something like: "To use STREAM receipts, the Receipt Secret is pre-shared between the verifier and the receiver. The sender presents the STREAM receipts to the verifier, which the verifier can trust because only verifier and receiver know the Receipt Secret."

included more details in 694f2d7

sharafian · 2020-03-16T17:54:34Z

0029-stream/0029-stream.md

@@ -192,6 +193,8 @@ Client streams MUST be odd-numbered starting with 1 and server-initiated streams

 Money can be sent for a given stream by sending an ILP Prepare packet with a non-zero `amount` and a `StreamMoney` frame in the STREAM packet to indicate which stream the money is for. A single ILP Prepare can carry value destined for multiple streams and the `shares` field in each of the `StreamMoney` frames indicates what portion of the Prepare amount should go to each stream.

+The receiver SHOULD include `StreamReceipt` frames in the ILP Fulfill packet indicating the total amount of money received in each stream, unless a secret key with which to generate receipts was not pre-shared with the receiver. Receipts can be verified, in order to confirm payment, using the pre-shared secret.


Well for the nonce we only need uniqueness, given it's public. So 16 is probably fine. 32 byte secret is good because it's often gonna be output of sha256. I think those values are good, but open to hear any other opinions

sharafian

My last concern is the timestamp format. Do you think we should use unix timestamp or the Interledger timestamp? Both are fixed-length which is good, Interledger timestamp has some advantages of a string date-time (like handling leap-seconds). Although that might not be an issue, with many systems 'smearing' leap-seconds.

Interledger timestamps are a little harder to parse (https://github.com/interledgerjs/interledgerjs/blob/master/packages/ilp-packet/src/utils/date.ts#L27-L43) but it'd feel a little odd to use InterledgerTime in the prepare packets and Unix timestamps in the receipt.

Anyone have thoughts here?

sharafian · 2020-03-19T21:15:39Z

#481

This suggests that leap second support isn't really a valid reason to use InterledgerTime, making me lean towards just a Unix timestamp.

0009-simple-payment-setup-protocol/0009-simple-payment-setup-protocol.md

0029-stream/0029-stream.md

kincaidoneil · 2020-03-19T18:33:07Z

0029-stream/0029-stream.md

+
+| Field | Type | Description |
+|---|---|---|
+| HMAC | UInt256 | HMAC-SHA256 over all other fields using the 32 byte Receipt Secret, which is pre-shared between the verifying party and the receiver. |


Could we explain the inputs to the MAC more precisely, e.g., "the message is the concatenation of each of the following fields, in this order"?

Updated the description in 8df9304

kincaidoneil · 2020-03-19T20:48:09Z

0029-stream/0029-stream.md

+| Field | Type | Description |
+|---|---|---|
+| Stream ID | VarUInt | Identifier of the stream this frame refers to. |
+| Receipt | 65-Byte OctetString | Proof provided by the receiver of the total amount received on this stream |


Why doesn't the frame individually enumerate the fields of the receipt? Are they not intended to be exposed at the STREAM layer...?

The receipt is kinda treated as a whole object that's passed around, for instance the receipt would be emitted in WM. So I think "grouping" like this can be helpful

0009-simple-payment-setup-protocol/0009-simple-payment-setup-protocol.md

sentientwaffle · 2020-03-20T17:12:02Z

0029-stream/0029-stream.md

+
+| Field | Type | Description |
+|---|---|---|
+| HMAC | UInt256 | HMAC-SHA256 over all other fields using the 32 byte Receipt Secret, which is pre-shared between the verifying party and the receiver. |


Nit: if the HMAC was the last field instead of the first, it would be easy to implement serialization with one fewer allocation.

I think I put the hmac first with verification in mind, but it makes sense to me to optimize the serialization.

addressed in 8df9304

Clarify HMAC message

0029-stream/0029-stream.md

sentientwaffle · 2020-03-20T20:56:21Z

0029-stream/0029-stream.md

+| Field | Type | Description |
+|---|---|---|
+| Stream ID | VarUInt | Identifier of the stream this frame refers to. |
+| Receipt | 65-Byte OctetString | Proof provided by the receiver of the total amount received on this stream |


Why mandate the exact size of the receipt instead of leaving it open-ended for possible extension?

👍
Should we also consider including a receipt version number?
Or could the receipt size be used to check compatibility, such as with receipt support discovery (#570 (comment))?

Perhaps the receipt itself could have a version byte? Size might not be good enough if a future version is variable length. And if the receipt contains its own version info then STREAM doesn't need to emit extra information about receipt version

changed receipt to VarOctetString and added version number: 1633e86

add receipt version number make receipt variable length indicate receipt support in SPSP response

remove stream start time from receipt update fixtures and asn

kincaidoneil · 2020-03-25T16:53:13Z

Since money can be sent over multiple streams, the verifier's accounting might be more complicated since they have to support tracking and totaling the amount received over each stream.

What if receipts attested the amount received over the whole connection instead? What are the arguments for/against a per-connection receipt vs a per-stream receipt?

wilsonianb · 2020-03-25T18:28:28Z

https://github.com/wilsonianb/receipt-verifier/
👆 The current verifier implementation aggregates receipt amounts by a specified id (not necessarily the receipt nonce), so per-connection receipts wouldn't save it that much complexity.

I think it's still worth considering though. Would one type of accounting be easier to add to the Rust and Java STREAM implementations than the other?

wilsonianb · 2020-03-25T19:40:28Z

On second thought now that I'm trying to update the verifier for receipts without the timestamp, per-connection receipts would simplify things.
The verifier can create a cache entry with an expiry for the receipt nonce when the SPSP query happens. This entry can be used to store the latest receipt amount as well as determining when a submitted receipt is too old (the entry will have expired).

sharafian · 2020-03-27T17:52:13Z

Since money can be sent over multiple streams, the verifier's accounting might be more complicated since they have to support tracking and totaling the amount received over each stream.

I was imagining that the key in the verifier's store would be the receipt nonce concatenated to stream ID. I'm not seeing right now how it's significantly simpler to just key with the receipt nonce.

The verifier can create a cache entry with an expiry for the receipt nonce when the SPSP query happens. This entry can be used to store the latest receipt amount as well as determining when a submitted receipt is too old (the entry will have expired).

Gotcha, so it saves a lookup because we don't need a separate key tracking the expiration of the connection as a whole?

In general I'm not hugely opposed to dropping the STREAM id but I want to make sure it doesn't mess anything else up in the future. STREAM was designed with multiplexing as a 'first-class' feature, where the idea is everything is done on streams and you might have long-lived connections on which you do many streams (like a long-lived QUIC connection with several HTTP calls over it).

We always have the option of making a new version of the receipt format but I think it could save us from future work if the receipts conceptually make sense with the rest of STREAM by working with the Stream abstraction

wilsonianb · 2020-03-27T18:18:40Z

so it saves a lookup because we don't need a separate key tracking the expiration of the connection as a whole?

More or less yeah. This gives an idea of how the verifier might change from using a redis hash to a single value for per-connection receipts:
interledger/receipt-verifier@13f77b9

I don't have a strong opinion either way.

0009-simple-payment-setup-protocol/0009-simple-payment-setup-protocol.md

0029-stream/0029-stream.md

asn1/Stream.asn

0009-simple-payment-setup-protocol/0009-simple-payment-setup-protocol.md

change SPSP response field to "receipts_enabled" Co-Authored-By: David Fuelling <sappenin@gmail.com>

asn1/Stream.asn

proposals/0000-stream-receipts.md

sharafian · 2020-04-02T19:05:02Z

proposals/0000-stream-receipts.md

+
+4. Sender MUST give the Receipt directly or indirectly to the Verifier.
+
+5. Verifier MUST verify the Receipt before crediting the Sender with the Receipt amount.


crediting makes me think of wallet balances where the Sender will get that money back. Can we clarify, something like accepting the Receipt amount as payment for services

sharafian · 2020-04-02T19:07:40Z

proposals/0000-stream-receipts.md

+
+### Stateless Receiver
+
+Before a STREAM connection is established, the Receiver MAY use the Receipt Nonce and Receipt Secret as parameters to generate connection details (ILP Address and shared secret). The Receiver MAY encode the Receipt Nonce and Receipt Secret in the STREAM server ILP Address to allow the STREAM receiver to avoid persisting state. If doing so, the Receipt Secret MUST be encrypted. The Receipt Nonce MUST be unique each time STREAM parameters are generated, since it MUST be unique per STREAM connection.


since it MUST be unique per STREAM connection the receipt nonce must be unique globally

nonce is random -> unique

sappenin

Just a few more questions, but 99% there from my end.

0029-stream/0029-stream.md

sappenin · 2020-04-21T15:01:00Z

asn1/Stream.asn

 }

 StreamFrame ::= SEQUENCE {
  type FRAME.&typeId ({FrameSet}),
  data FRAME.&Type ({FrameSet}{@type})
 }

+RECEIPT ::= CLASS {


This is a minor nit, but can we move these definitions to the bottom of this file? As they are now, they sort of break the flow of the STREAM and frame definitions themselves, which makes the ASN harder to read.

We could even put these directly above the StreamReceipt frame definition on line 209? Or pull the receipt definitions themselves into a separate file? (I can't think of a use-case, but I suppose lines 80-109 can technically stand on their own independent of STREAM and be imported into this file).

Moved to a separate file 7dd4111
(force pushed because the commit wasn't originally appearing in the pull request, likely due to earlier github incident)

Co-Authored-By: David Fuelling <sappenin@gmail.com>

wilsonianb added 5 commits February 26, 2020 20:25

Add STREAM receipts

2d964ba

Signed-off-by: Brandon Wilson <brandon@coil.com>

[FOLD] Make receipt fields fixed length

e54f648

[FOLD] Make receipt stream id 1 byte

b447302

[FOLD] Clarify receipts requirements

896f7bc

[FOLD] Specify receipt header base64 encoding

9a50ffa

wilsonianb force-pushed the receipts branch from a709382 to 9a50ffa Compare March 13, 2020 18:18

wilsonianb requested a review from sharafian March 13, 2020 18:35

wilsonianb marked this pull request as ready for review March 13, 2020 18:35

wilsonianb mentioned this pull request Mar 13, 2020

feat: add receipts interledgerjs/ilp-protocol-stream#133

Merged

sharafian requested review from kincaidoneil and sentientwaffle March 13, 2020 20:26

sharafian requested changes Mar 13, 2020

View reviewed changes

[FOLD] Explicitly name Receipt Secret and Receipt Nonce

bc04d01

sharafian self-requested a review March 16, 2020 17:45

sharafian reviewed Mar 16, 2020

View reviewed changes

[FOLD] Expand receipt explanation details

694f2d7

sharafian requested changes Mar 18, 2020

View reviewed changes

kincaidoneil reviewed Mar 19, 2020

View reviewed changes

0009-simple-payment-setup-protocol/0009-simple-payment-setup-protocol.md Show resolved Hide resolved

sentientwaffle reviewed Mar 20, 2020

View reviewed changes

[FOLD] Move HMAC to the end of receipt

8df9304

Clarify HMAC message

sentientwaffle reviewed Mar 20, 2020

View reviewed changes

0029-stream/0029-stream.md Outdated Show resolved Hide resolved

sentientwaffle reviewed Mar 20, 2020

View reviewed changes

wilsonianb added 2 commits March 23, 2020 16:50

[FOLD] review feedback

1633e86

add receipt version number make receipt variable length indicate receipt support in SPSP response

[FOLD] review feedback

ff2617a

remove stream start time from receipt update fixtures and asn

sappenin requested changes Mar 27, 2020

View reviewed changes

wilsonianb and others added 4 commits March 27, 2020 19:03

[FOLD] Apply suggestions from code review

7ea0ad8

change SPSP response field to "receipts_enabled" Co-Authored-By: David Fuelling <sappenin@gmail.com>

[FOLD] add StreamReceipt ASN.1 definition

a307987

[FOLD] fix ASN.1 definitions

cabe1be

[FOLD] Add STREAM Receipts RFC

a9a8cdb

sharafian requested changes Apr 2, 2020

View reviewed changes

[FOLD] review feedback

fccbb3b

nonce is random -> unique

sharafian approved these changes Apr 6, 2020

View reviewed changes

[FOLD] fix typo

17e753c

wilsonianb requested a review from sappenin April 8, 2020 18:08

sappenin requested changes Apr 9, 2020

View reviewed changes

wilsonianb added 2 commits April 9, 2020 18:56

[FOLD] Define receipt as VarOctetString in frame

09172b7

[FOLD] define receipt version via asn.1 class

43039f7

wilsonianb requested a review from sappenin April 20, 2020 21:16

sappenin requested changes Apr 21, 2020

View reviewed changes

wilsonianb and others added 2 commits April 21, 2020 10:29

Update 0029-stream/0029-stream.md

67e7dce

Co-Authored-By: David Fuelling <sappenin@gmail.com>

[FOLD] move receipt asn.1 definition to separate file

7dd4111

wilsonianb force-pushed the receipts branch from b4952fd to 7dd4111 Compare April 21, 2020 17:09

wilsonianb requested a review from sappenin April 22, 2020 20:06

sappenin approved these changes Apr 22, 2020

View reviewed changes

wilsonianb merged commit 17011c4 into interledger:master Apr 22, 2020

This was referenced Apr 23, 2020

Add Support for STREAM Receipt Frame hyperledger-archives/quilt#451

Open

Add STREAM Receipts #568

Closed

wilsonianb mentioned this pull request May 8, 2020

add STREAM receipts interledger/web-monetization-projects#533

Merged

sublimator mentioned this pull request Dec 2, 2021

Add example of how to verify a receipt WICG/webmonetization#237

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add STREAM receipts #570

Add STREAM receipts #570

wilsonianb commented Feb 27, 2020

sharafian Mar 13, 2020

sharafian Mar 13, 2020

wilsonianb Mar 13, 2020

sharafian Mar 13, 2020

wilsonianb Mar 13, 2020

sharafian Mar 16, 2020

sharafian Mar 16, 2020

wilsonianb Mar 16, 2020

sharafian Mar 16, 2020

sharafian left a comment

sharafian commented Mar 19, 2020

kincaidoneil Mar 19, 2020

wilsonianb Mar 20, 2020

kincaidoneil Mar 19, 2020

sharafian Mar 19, 2020

sentientwaffle Mar 20, 2020

wilsonianb Mar 20, 2020

wilsonianb Mar 20, 2020

sentientwaffle Mar 20, 2020

wilsonianb Mar 20, 2020

sharafian Mar 23, 2020

wilsonianb Mar 23, 2020

kincaidoneil commented Mar 25, 2020

wilsonianb commented Mar 25, 2020

wilsonianb commented Mar 25, 2020

sharafian commented Mar 27, 2020

wilsonianb commented Mar 27, 2020

sharafian Apr 2, 2020

sharafian Apr 2, 2020

sappenin left a comment

sappenin Apr 21, 2020

wilsonianb Apr 21, 2020

		@@ -192,6 +193,8 @@ Client streams MUST be odd-numbered starting with 1 and server-initiated streams

		Money can be sent for a given stream by sending an ILP Prepare packet with a non-zero `amount` and a `StreamMoney` frame in the STREAM packet to indicate which stream the money is for. A single ILP Prepare can carry value destined for multiple streams and the `shares` field in each of the `StreamMoney` frames indicates what portion of the Prepare amount should go to each stream.

		The receiver SHOULD include `StreamReceipt` frames in the ILP Fulfill packet indicating the total amount of money received in each stream, unless a secret key with which to generate receipts was not pre-shared with the receiver. Receipts can be verified, in order to confirm payment, using the pre-shared secret.

		@@ -192,6 +195,8 @@ Client streams MUST be odd-numbered starting with 1 and server-initiated streams

		Money can be sent for a given stream by sending an ILP Prepare packet with a non-zero `amount` and a `StreamMoney` frame in the STREAM packet to indicate which stream the money is for. A single ILP Prepare can carry value destined for multiple streams and the `shares` field in each of the `StreamMoney` frames indicates what portion of the Prepare amount should go to each stream.

		The receiver SHOULD include `StreamReceipt` frames in the ILP Fulfill packet indicating the total amount of money received in each stream, unless a Receipt Secret and Receipt Nonce were not pre-shared with the receiver. Receipts can be verified, in order to confirm payment, using the Receipt Secret.


		4. Sender MUST give the Receipt directly or indirectly to the Verifier.

		5. Verifier MUST verify the Receipt before crediting the Sender with the Receipt amount.


		### Stateless Receiver

		Before a STREAM connection is established, the Receiver MAY use the Receipt Nonce and Receipt Secret as parameters to generate connection details (ILP Address and shared secret). The Receiver MAY encode the Receipt Nonce and Receipt Secret in the STREAM server ILP Address to allow the STREAM receiver to avoid persisting state. If doing so, the Receipt Secret MUST be encrypted. The Receipt Nonce MUST be unique each time STREAM parameters are generated, since it MUST be unique per STREAM connection.

Add STREAM receipts #570

Add STREAM receipts #570

Conversation

wilsonianb commented Feb 27, 2020

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 left a comment

Choose a reason for hiding this comment

sharafian commented Mar 19, 2020

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

kincaidoneil commented Mar 25, 2020

wilsonianb commented Mar 25, 2020

wilsonianb commented Mar 25, 2020

sharafian commented Mar 27, 2020

wilsonianb commented Mar 27, 2020

Choose a reason for hiding this comment

Choose a reason for hiding this comment

sappenin left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment