Add LUD-22: Payee Data.

22.md

@@ -0,0 +1,70 @@
+LUD-22: Payee identity data in `payRequest` protocol.
+================================================
+
+`author: onthedeklein` `discussion: https://t.me/lnurl/36488`
+
+---
+
+This is the payee-side equivalent of [LUD-18](18.md). It gives the opportunity for the payer to request that the payee provide identitifying information before the payment is made. This allows the sending `WALLET` to show information about the receiver in order to allow the payer to verify that they are paying the correct entity. This also gives the opportunity for the payee to authorize themselves via a challenge-response mechanism to provide some assurance that `SERVICE` has not been compromised.
+
+## 1. `payeeData` record
+
+If `WALLET` wants to get one or more types of payee identities/data from `SERVICE` then it MUST alter its JSON request to the second callback to include a `payeeData` query param, as follows (notice that the `payeeData` record below has a bunch of fields only for completion, an actual response will likely contain just a subset of these):
+
+```typescript
+ {
+  "name": { "mandatory": boolean },
+  "pubkey": { "mandatory": boolean },
+  "identifier": { "mandatory": boolean },
+  "email": { "mandatory": boolean },
+  "auth": {
+     "mandatory": boolean,
+     "k1": string // hex encoded 32 bytes of challenge
+  },
+  "countryCode": { "mandatory": boolean },
+  ...other fields may be negotiated
+},
+```
+
+This record is url-encoded and appended to the callback url as a query string, as follows:
+
+```diff
+- <callback><?|&>amount=<milliSatoshi>
++ <callback><?|&>amount=<milliSatoshi>&payeedata=<urlencode({payeeData json object})>
+```
+
+Notice that just including the payee id kind ("name", "pubkey" etc.) in the `payeeData` record is enough to signal acceptance of that kind.
+
+## 2. Responding with payee identity
+
+In response to seeing a `payeeData` record in the `payRequest` request from `WALLET`, `SERVICE` adds a `payeeData` field to the response as follows:
+
+```diff
+{
+    "pr": string,
+    "routes": [],
++   "payeeData": {
++     "name": string, // free form string
++     "pubkey": string, // hex(<randomly generated secp256k1 pubkey>),
++     "auth": {
++       "k1": string, // same as received from wallet on section 1
++       "sig": string, // hex(sign(hexToBytes(<k1>)))
++     },
++     "email": string,
++     "identifier": string,
++     "countryCode": string,
++     ...other fields may be included if supported by service and requested by wallet
++   }
+}
+
+```
+
+Each key in this JSON object should correspond to a requested payerdata from the `payerData` record received from `SERVICE`.
+
+`SERVICE` CAN send any of the payee id kinds if they are listed in the `payeeData` record. But if any is marked as `"mandatory": true` then `SERVICE` MUST send or otherwise do not proceed with the payment flow.
+
+`SERVICE` may choose to avoid sending any payee identity information for privacy reasons, which may cause the payment to fail if the `WALLET` requires it. For that reason, `WALLET` SHOULD NOT require any payee identity information to be sent by `SERVICE` unless it is absolutely necessary.
+
+`SERVICE` SHOULD NOT send payee identity types omitted in `payeeData` record, none at all if the record is not present.
+
+Note that LUD-22 can be used in conjunction with [LUD-18](18.md) to allow the payer to request that the payee provide identitifying information (which can be optionally verified by `SERVICE`) before sharing payee identity information.