Add STREAM receipts

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

@@ -1,6 +1,6 @@
 ---
 title: The Simple Payment Setup Protocol (SPSP)
-draft: 9
+draft: 10
 ---
 # Simple Payment Setup Protocol (SPSP)
 
@@ -24,6 +24,7 @@ SPSP provides for exchanging basic server details needed by a client to set up a
 * **SPSP Server** - The application that handles incoming SPSP requests from the SPSP Client.
 * **SPSP Endpoint** - The specific HTTPS endpoint on the SPSP Server used for setting up a payment.
 * **STREAM Module** - Software included in the SPSP Client and Server that implements the [STREAM](../0029-stream/0029-stream.md) protocol.
+* **STREAM Receipt** - Proof provided by the payment recipient of the total amount received on a stream.
 
 ### Interfaces
 
@@ -62,6 +63,17 @@ Host: example.com
 Accept: application/spsp4+json, application/spsp+json
 ```
 
+##### Request Headers
+
+The request MAY contain at least the following headers in order to pre-share STREAM Receipt details between the SPSP Server and a party verifying payments sent to the SPSP Server:
+
+| Header          | Description                                                |
+|:----------------|:-----------------------------------------------------------|
+| `Receipt-Nonce`  | A base64-encoded 16-byte random nonce used to identify the STREAM connection in STREAM Receipts. |
+| `Receipt-Secret` | A base64-encoded 32-byte key used to generate a STREAM Receipt's HMAC. |
+
+The SPSP Client MAY be provided with an SPSP Endpoint belonging to the receipt verifier, which would add the receipt headers and proxy the query to the SPSP Server.
+
 #### Response
 ``` http
 HTTP/1.1 200 OK

0029-stream/0029-stream.md

@@ -1,6 +1,6 @@
 ---
 title: STREAM - A Multiplexed Money and Data Transport for ILP
-draft: 8 
+draft: 9
 ---
 
 # STREAM: A Multiplexed Money and Data Transport for ILP
@@ -55,6 +55,7 @@ This document specifies the STREAM Interledger Transport protocol, which provide
     - [5.3.12. `StreamMaxData` Frame](#5312-streammaxdata-frame)
     - [5.3.13. `StreamDataBlocked` Frame](#5313-streamdatablocked-frame)
     - [5.3.14. `ConnectionAssetDetails` Frame](#5314-connectionassetdetails-frame)
+    - [5.3.15. `StreamReceipt` Frame](#5315-streamreceipt-frame)
   - [5.4. Error Codes](#54-error-codes)
 - [6. Condition and Fulfillment Generation](#6-condition-and-fulfillment-generation)
   - [6.1. Unfulfillable Condition](#61-unfulfillable-condition)
@@ -158,6 +159,8 @@ A server MUST communicate the following values to a client using an **authentica
 
 To avoid storing a 32 byte secret for each connection, a server MAY deterministically generate the shared secret for each connection from a single server secret and a nonce appended to the ILP Address given to a particular client, for example by using an HMAC.
 
+For each new connection, a server MAY be provided with a pre-shared 32 byte Receipt Secret to generate receipts and 16 byte Receipt Nonce to include in those receipts. To avoid storing these for each connection, a server MAY deterministically append them to the ILP Address given to a particular client. If doing so, the server MUST encrypt the Receipt Secret.
+
 ### 4.2. Matching Packets to Connections
 
 Incoming packets can either be associated with an existing connection, or, for servers, potentially create a new connection. Endpoints MAY append extra segments to the ILP addresses assigned to them by their upstream connectors to help direct incoming packets.
@@ -192,6 +195,10 @@ 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.
+
+To use STREAM receipts, the Receipt Secret and Receipt Nonce are pre-shared between the receiver and a receipt verifier party. Receipts are generated by the receiver and passed to the sender, who may submit the receipts directly or indirectly to the verifier. This allows the verifier to confirm the payment, as only the receiver and the verifier know the Receipt Secret.
+
 #### 4.4.3. Sending Data
 
 Data can be sent for a given stream by sending an ILP Prepare packet with a `StreamData` frame in the STREAM packet. A single ILP Prepare can carry data destined for multiple streams.
@@ -313,6 +320,7 @@ The frame types are as follows and each is described in greater detail below:
 | `0x14` | Stream Data |
 | `0x15` | Stream Data Max |
 | `0x16` | Stream Data Blocked |
+| `0x17` | Stream Receipt |
 
 #### 5.3.1. `ConnectionClose` Frame
 
@@ -436,6 +444,24 @@ In other words, if a sender resends data (e.g. because a packet was lost), it MU
 
 Asset details exposed by this frame MUST NOT change during the lifetime of a Connection.
 
+#### 5.3.15. `StreamReceipt` Frame
+
+| 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 |
+
+The `Receipt` MUST contain the following fields encoded using the [Octet Encoding Rules (OER)](http://www.oss.com/asn1/resources/books-whitepapers-pubs/Overview_of_OER.pdf):
+
+| 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. |
+| 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. |
+
+
 ### 5.4. Error Codes
 
 Error codes are sent in `StreamClose` and `ConnectionClose` frames to indicate what caused the stream or connection to be closed.

0029-stream/test-vectors/StreamPacketFixtures.json

@@ -790,6 +790,23 @@
     },
     "buffer": "AQwBAAEAAQEWCwF7CP//////////"
   },
+  {
+    "name": "frame:stream_receipt",
+    "packet": {
+      "sequence": "0",
+      "packetType": 12,
+      "amount": "0",
+      "frames": [
+        {
+          "type": 23,
+          "name": "StreamReceipt",
+          "streamId": "123",
+          "receipt": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA="
+        }
+      ]
+    },
+    "buffer": "AQwBAAEAAQEXQwF7AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA="
+  },
   {
     "name": "frame:stream_max_money:receive_max:too_big",
     "packet": {

asn1/Stream.asn

@@ -67,7 +67,8 @@ FrameSet FRAME ::= {
   {19 StreamMoneyBlocked} |
   {20 StreamData} |
   {21 StreamMaxData} |
-  {22 StreamDataBlocked}
+  {22 StreamDataBlocked} |
+  {23 StreamReceipt]}
 }
 
 StreamFrame ::= SEQUENCE {
@@ -174,4 +175,12 @@ StreamDataBlocked ::= SEQUENCE {
   maxOffset VarUInt
 }
 
+StreamReceipt ::= SEQUENCE {
+  -- Identifier of the stream
+  streamId VarUInt,
+
+  -- Receipt for verifying the total amount received on this stream
+  receipt OCTET STRING (SIZE(65))
+}
+
 END