Address PR feedback from @TheBlueMatt

- Detail normative section to clarify that `contact_secret`s are
  bidirectional and set by the first payer.
- Remove automatic matching of incoming payments using distinct secrets.
- Expand the contact secrets section with UX examples.

Author: t-bast

blip-0042.md

@@ -62,10 +62,20 @@ to allow contacts to pay them back:
 
 #### Requirements
 
-The writer of `invoice_request`, when paying one of their contacts:
-
-- If it wants the payer to be able to identify who paid them:
-  - MUST include the `invreq_contact_secret` associated with that contact.
+The writer of `invoice_request`:
+
+- If they want the recipient to be able to identify who paid them:
+  - If the recipient is not yet part of their contacts list:
+    - If they have previously received a payment from this recipient including
+      the `invreq_contact_secret` field:
+      - MUST associate the received `invreq_contact_secret` with this contact.
+      - MUST include this `invreq_contact_secret` whenever paying this contact.
+    - Otherwise:
+      - MUST generate a unique `invreq_contact_secret` for that contact.
+      - MUST associate this `invreq_contact_secret` with this contact.
+      - MUST include this `invreq_contact_secret` whenever paying this contact.
+  - Otherwise:
+    - MUST include the `invreq_contact_secret` associated with this contact.
   - MUST include either `invreq_payer_offer` or `invreq_payer_bip_353_name`.
   - If it includes `invreq_payer_bip_353_name`:
     - MUST set `name` to the post-₿, pre-@ part of the BIP 353 HRN.
@@ -84,21 +94,27 @@ The reader of `invoice_request`:
 - MUST send back an `invoice` including the `invoice_request` contact fields
   provided by the sender, as specified in Bolt 12.
 - After the invoice has been paid, if `invreq_contact_secret` was included:
-  - If it matches one of its contacts:
+  - If it matches one of their contacts:
     - SHOULD display the `invreq_payer_note`, if one is provided.
+    - MUST ignore `invreq_payer_offer` and `invreq_bip_353_name`.
   - Otherwise:
     - MAY use the `contact_secret`, `payer_offer` and `payer_bip_353_name` to
-      create a new contact.
-      - If it creates a new contact based on this received payment, the
-        received `contact_secret` MUST be used when paying that contact.
-    - MAY associate the received `contact_secret` with an existing contact.
-    - MUST ignore `invreq_payer_offer` and `invreq_bip_353_name` if it already
-      has an offer for this contact.
+      create a new contact. If they do:
+      - MUST use the received `contact_secret` whenever paying that contact.
+      - MUST use the received `payer_offer` whenever paying that contact.
+      - If `payer_bip_353_name` was included:
+        - MUST use it to fetch a `payer_offer` if none was included.
+        - MUST use it to refresh the `payer_offer` when it expires.
+        - MAY use it to refresh the `payer_offer` periodically.
+    - MAY manually associate the received `contact_secret` with an existing
+      contact, if the user verified that the payment came from this contact.
 
 #### Rationale
 
-The `contact_secret` field is used for mutual identification: its usage is
-detailed in the [Contact Secrets](#contact-secrets) section below.
+The `contact_secret` field is used for mutual identification: it is set by the
+node sending the first payment and must be reused by the recipient when sending
+payments in the other direction. Its usage and edge cases are detailed in the
+[Contact Secrets](#contact-secrets) section below.
 
 Nodes generally don't store every `invoice_request` they receive, because that
 would expose them to DoS. They instead include the fields they would like to
@@ -123,18 +139,23 @@ own offers.
 
 The main mechanism of this proposal is the exchange of `contact_secret`s.
 This section details various scenarios that may occur and how to correctly
-deal with each of them.
+deal with each of them, along with a recommended UX.
 
 #### Adding contacts
 
-When Alice adds Bob to her contacts list from an offer she received from Bob,
-she generates a random `contact_secret`. For all future payments made to Bob
-where she wants to reveal that she's the payer, Alice will include this same
-`contact_secret`.
-
-Once Bob has received a payment that includes a `contact_secret`, he may add
-the payer to its own contacts list. If he knows that this payment came from
-Alice, he's able to add Alice to his contacts and pay her back using the
+When Alice wants to pay Bob, her wallet should offer an option to add him to
+her contacts list (using a checkbox or a dedicated button). If she chooses
+that option, she generates a random `contact_secret`. For all future payments
+made to Bob where she wants to reveal that she's the payer, Alice will include
+this same `contact_secret`. Wallets should always offer the option to pay a
+contact privately, in which case the `contact_secret` and payer information
+will not be included in the `invoice_request`.
+
+Once Bob has received a payment that includes a `contact_secret`, his wallet
+should display an option to add the payer to its own contacts list (e.g. via
+a dedicated button the received payment page). If he knows that this payment
+came from Alice (because Alice verifiably told him that it indeed came from
+her), he's able to add Alice to his contacts and pay her back using the
 `payer_offer` or `payer_bip_353_name` she provided. For all future payments
 made to Alice where Bob wants to reveal that he's the payer, Bob will include
 the `contact_secret` generated by Alice. Note that in this case, Bob doesn't
@@ -148,12 +169,14 @@ than the one used to receive Alice's payment, Bob will generate a different
 random `contact_secret`. For all payments made to Alice where he wants to
 reveal that he's the payer, he will use that new `contact_secret`. When Alice
 receives those payments, she won't be able to automatically identify that it's
-coming from Bob based on the `contact_secret` alone. But Alice is usually able
-to know that a specific payment came from Bob: she can then detect that Bob
-used a different `contact_secret` from the one she initially created, and she
-can store that additional `contact_secret` to the list of secrets Bob may use
-when paying her. This action automatically reconciles past and future payments
-made from Bob.
+coming from Bob based on the `contact_secret` alone, because it is different
+from the one she generated. But if Alice knows that a specific payment came
+from Bob (because he verifiably told her so), her wallet should allow her to
+attribute this payment to an existing contact (e.g. by clicking an "add to
+contacts" button on the received payment and then choosing an "add to existing
+contact" option). Her wallet will then add that additional `contact_secret` to
+the list of secrets Bob may use when paying her. This action automatically
+reconciles past and future payments made from Bob.
 
 A contact entry thus contains the following information:
 
@@ -165,10 +188,6 @@ A contact entry thus contains the following information:
   that our contact may use when paying us, obtained by manually associating
   payments with our existing contact.
 
-Note that wallets can also automatically reconcile payments when they detect
-that the `payer_offer` or `payer_bip_353_name` received matches an existing
-contact but uses a different `contact_secret`.
-
 #### Leaked contact secrets
 
 Contact secrets shouldn't be shared publicly, as that would let other people