Skip to content

Commit

Permalink
Add invreq_payer_bip_353_signature field
Browse files Browse the repository at this point in the history
When including a BIP 353 HRN, we also require including a signature of
the `invoice_request` using one of the keys from the offer stored in the
BIP 353 DNS record.
  • Loading branch information
t-bast committed Jan 7, 2025
1 parent b37d046 commit 2347f2c
Showing 1 changed file with 27 additions and 0 deletions.
27 changes: 27 additions & 0 deletions blip-0042.md
Original file line number Diff line number Diff line change
Expand Up @@ -60,6 +60,15 @@ to allow contacts to pay them back:
- [`u8`:`domain_len`]
- [`domain_len*byte`:`domain`]

The `invreq_payer_bip_353_signature` field lets payers provide a signature of
the `invoice_request` using one of the signing keys of the offer associated
with their BIP 353 name, thus proving ownership of this BIP 353 name.

1. type: 2000001735 (`invreq_payer_bip_353_signature`)
2. data:
- [`point`:`offer_signing_key`]
- [`bip340sig`:`signature`]

#### Requirements

The writer of `invoice_request`:
Expand All @@ -80,6 +89,12 @@ The writer of `invoice_request`:
- If it includes `invreq_payer_bip_353_name`:
- MUST set `name` to the post-₿, pre-@ part of the BIP 353 HRN.
- MUST set `domain` to the post-@ part of the BIP 353 HRN.
- MUST include `invreq_payer_bip_353_signature` using the private key of
its `offer_issuer_id` or, if its offer doesn't include `offer_issuer_id`,
the private key of the `blinded_node_id` of one of its `offer_paths`.
The signed data should be computed as detailed in [Bolt 12][bolt12-sig],
with "lightning" || "invoice_request" || "invreq_payer_bip_353_signature"
as signature tag.
- If it includes `invreq_payer_offer`:
- MUST encode `payer_offer` as a TLV stream of its individual records.
- If the encoded offer is more than 300 bytes long:
Expand All @@ -91,6 +106,9 @@ The writer of `invoice_request`:

The reader of `invoice_request`:

- If `invreq_bip_353_name` is provided:
- MUST ignore the `invoice_request` if `invreq_payer_bip_353_signature` is
missing or invalid.
- 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:
Expand All @@ -104,6 +122,8 @@ The reader of `invoice_request`:
- MUST use the received `payer_offer` whenever paying that contact.
- If `payer_bip_353_name` was included:
- SHOULD use it to fetch a `payer_offer` if none was included.
- MUST verify that the received offer matches the `offer_signing_key`
provided in `invreq_payer_bip_353_signature`.
- SHOULD use it to refresh the `payer_offer` if it expires.
- MAY use it to refresh the `payer_offer` periodically.
- MAY manually associate the received `contact_secret` with an existing
Expand All @@ -125,6 +145,11 @@ large, which would constrain the payment paths that can be used by the payer.
We thus recommend only including offers that are smaller than 300 bytes in
`invreq_payer_offer`, or a small BIP 353 HRN.

When a BIP 353 HRN is included, the node receiving `invoice_request` does not
know whether it really belongs to the sender. This is why the sender must also
include a signature that proves that they control one of the private keys of
the offer stored in the BIP 353 record.

When payments are coming from known contacts, there is less risk that the
`payer_note` that is optionally included contains spam. It is thus recommended
to display it, while we generally don't recommend displaying `payer_note`s
Expand Down Expand Up @@ -259,3 +284,5 @@ section.

- lightning-kmp: <https://github.com/ACINQ/lightning-kmp/pull/719>
- phoenix wallet: <https://github.com/ACINQ/phoenix/pull/645>

[bolt12-sig]: https://github.com/lightning/bolts/blob/master/12-offer-encoding.md#signature-calculation

0 comments on commit 2347f2c

Please sign in to comment.