From 5a21e81a06cb485782e2023500466cc261c8223f Mon Sep 17 00:00:00 2001 From: Jeremy Klein Date: Thu, 14 Dec 2023 23:01:34 -0800 Subject: [PATCH 1/2] Add LUD-22: Payee Data. 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 ensurance that `SERVICE` has not been compromised. --- 22.md | 70 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 70 insertions(+) create mode 100644 22.md diff --git a/22.md b/22.md new file mode 100644 index 0000000..b332c17 --- /dev/null +++ b/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 +- amount= ++ amount=&payeedata= +``` + +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(), ++ "auth": { ++ "k1": string, // same as received from wallet on section 1 ++ "sig": string, // hex(sign(hexToBytes())) ++ }, ++ "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. From 83dde80ea659d6fc08775aab366ba7eb7e348b29 Mon Sep 17 00:00:00 2001 From: Jeremy Klein Date: Wed, 14 Feb 2024 14:09:31 -0800 Subject: [PATCH 2/2] Fix copypasta --- 22.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/22.md b/22.md index b332c17..46d9b5e 100644 --- a/22.md +++ b/22.md @@ -59,7 +59,7 @@ In response to seeing a `payeeData` record in the `payRequest` request from `WAL ``` -Each key in this JSON object should correspond to a requested payerdata from the `payerData` record received from `SERVICE`. +Each key in this JSON object should correspond to a requested payeedata from the `payeeData` 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.