- Add flow overview image

- Make Abstract more readable
- Update Sender definition and acronym descriptions
- Added comments to ReturnPaymentRequest definition
- Bold ECDH and AES Setup notes and added "(see below)" for reference

Author: Matt David

bip-invoicerequest-extension.mediawiki

@@ -11,9 +11,9 @@
 
 ==Abstract==
 
-This BIP is an extension to BIP70 the extends the payment protocol to prevent PaymentRequet interception / modification 
-during transmission using ephemeral key encryption, allow permissioned release of PaymentRequests to PaymentRequest requestors 
-and, allow a requestor to supply a certificate and signature to the PaymentRequest creator.
+This BIP is an extension to BIP70 that extends the payment protocol to prevent PaymentRequet interception / modification 
+during transmission using ephemeral key encryption. This also allows permissioned release of a PaymentRequest to a requestor 
+and allows a requestor to supply a certificate and signature to the PaymentRequest creator.
 
 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED",  "MAY", and 
 "OPTIONAL" in this document are to be interpreted as described in RFC 2119.
@@ -27,7 +27,7 @@ to facilitate identification for address release.
 
 ==Definitions==
 {| class="wikitable"
-| Sender    || Entity wishes to transfer value that they control
+| Sender    || Entity wishing to transfer value that they control
 |-
 | Receiver  || Entity receiving a value transfer
 |}
@@ -36,15 +36,15 @@ to facilitate identification for address release.
 {| class="wikitable"
 ! Acronym !! Expanded !! Description
 |-
-| IR || InvoiceRequest || A request to create a PaymentRequest
+| IR || InvoiceRequest || A request to create and return an encrypted PaymentRequest
 |-
-| RPR || ReturnPaymentRequest  || A ReturnPaymentRequest returned based on a submitted InvoiceRequest
+| RPR || ReturnPaymentRequest  || A message returned based on a submitted InvoiceRequest containing an encrypted PaymentRequest
 |}
 
 ==New Messages==
 
 ===InvoiceRequest===
-The new InvoiceRequest message allows a requestor to send information to the responder such that they can return a ReturnPaymentRequest.
+The InvoiceRequest message allows a Sender to send information to the Receiver such that they can create and return a ReturnPaymentRequest.
 
 <pre>
 message InvoiceRequest {
@@ -75,15 +75,15 @@ message InvoiceRequest {
 
 ===ReturnPaymentRequest===
 
-The new ReturnPaymentRequest message is an encapsulating message that allows the transmission of an encrypted, serialized PaymentRequest.
+The ReturnPaymentRequest message is an encapsulating message that allows the transmission of an encrypted, serialized PaymentRequest.
 
 <pre>
- message ReturnPaymentRequest {
-         required bytes encrypted_payment_request = 1;
-         required bytes receiver_public_key = 2;
-         required bytes ephemeral_public_key = 3;
-         required bytes payment_request_hash = 4;
- }
+message ReturnPaymentRequest {
+        required bytes encrypted_payment_request = 1;      // Encrypted, Serialized PaymentRequest
+        required bytes receiver_public_key = 2;            // Receiver's EC Public Key
+        required bytes ephemeral_public_key = 3;           // Public Key of keypair created with ECDH-derived secret point
+        required bytes payment_request_hash = 4;           // SHA256 of Serialized PaymentRequest
+}
 </pre>
 {| class="wikitable"
 ! Field Name</b> !! Description
@@ -111,6 +111,10 @@ The new ReturnPaymentRequest message is an encapsulating message that allows the
 # Sender validates ReturnPaymentRequest
 # Sender decrypts and validates encrypted PaymentRequest
 
+This overview flow is illustrated below:
+
+<img src=bip-ir/overview_flow.png></img>
+
 ===Message Interaction Details===
 
 ====InvoiceRequest====
@@ -146,7 +150,7 @@ should be done through standard HTTP Status Code messaging ([https://tools.ietf.
 * If pki_type is x509+sha256 and signature is valid for the serialized InvoiceRequest where signature is set to "", InvoiceRequest is VALID
 
 ===ReturnPaymentRequest Message Creation and PaymentRequest Encryption===
-* Encrypt the serialized PaymentRequest using AES-256-CBC setup as described in ECDH Point Generation and AES-256 (CBC Mode) Setup
+* Encrypt the serialized PaymentRequest using AES-256-CBC setup as described in <b>ECDH Point Generation and AES-256 (CBC Mode) Setup (see below)</b>
 * Create ReturnPaymentRequest message
 * Set encrypted_payment_request to be the encrypted value of the PaymentRequest
 * Set receiver_public_key to the Receiver's EC public key (of which the private key was previously used in ECDH secret point calculation)
@@ -155,7 +159,7 @@ should be done through standard HTTP Status Code messaging ([https://tools.ietf.
 
 ===ReturnPaymentRequest Validation and Decryption===
 * Validate ephemeral_public_key matches public key of an EC keypair created using the secret point's X value.
-* Decrypt the serialized PaymentRequest using AES-256-CBC setup as described in ECDH Point Generation and AES-256 (CBC Mode) Setup
+* Decrypt the serialized PaymentRequest using AES-256-CBC setup as described in <b>ECDH Point Generation and AES-256 (CBC Mode) Setup (see below)</b>
 * Validate payment_request_hash matches SHA256 of the decrypted, serialized PaymentRequest
 * Deserialize the serialized PaymentRequest