lightning-blips/blip-0032.md

```
bLIP: 32
Title: Onion Message DNS Resolution
Status: Active
Author: Matt Corallo <blmmesg@bluematt.me>
Created: 2024-02-10
License: CC0
```

## Abstract

This bLIP defines a simple protocol by which a node can request a DNSSEC proof of TXT records at a
given domain in the global DNS.

## Copyright

This bLIP is licensed under the CC0 license.

## Specification

Two new onion messages are defined, `dnssec_query` and `dnssec_proof`.

1. type: 65536 (`dnssec_query`)
2. data:
    * [`u8`:`domain_name_len`]
    * [`domain_name_len*byte`:`domain_name`]

1. type: 65538 (`dnssec_proof`)
2. data:
    * [`u8`:`domain_name_len`]
    * [`domain_name_len*byte`:`domain_name`]
    * [`u16`:`proof_len`]
    * [`proof_len*byte`:`proof`]

Nodes which accept and reply to `dnssec_query`-containing onion messages from any sender:
 * SHOULD set the `dns_resolver` feature flag in their `node_announcement`.

Senders of a `dnssec_query`-containing onion message:
 * MUST set `reply_path` in the `onionmsg_tlv` stream.
 * MUST set `domain_name` to a canonical DNS name, i.e. it MUST be entirely printable ASCII and
   MUST end in a ".".

Recipients of a `dnssec_query`-containing onion message:
 * SHOULD attempt to resolve the given `domain_name` into a TXT record response, considering any
   relevant CNAME or DNAME records.
 * MAY (but certainly are not required to) validate the required DNSSEC signatures required to
   validate the query responses.
 * SHOULD attempt to resolve the given `domain_name` into an RFC 9102-formatted DNSSEC proof (a
   concatenated series of `AuthenticationChain` records, not including the `ExtSupportLifetime`
   field at the start of a `DnssecChainExtension`).
 * SHOULD return the RFC 9102-formatted DNSSEC proof proving the resulting TXT records in a
   `dnssec_proof`-containing onion message to the sender using the provided `reply_path`.

Senders of a `dnssec_proof`-containing onion message:
 * MUST set the `domain_name` to the `domain_name` included in the `dnssec_query`-containing onion
   message being responded to.

Recipients of a `dnssec_proof`-containing onion message:
 * MUST validate all DNSSEC signatures to ensure any contained records are signed in an unbroken
   chain from the DNSSEC root trust anchor.
 * MUST NOT rely on any signatures which rely on SHA-1 or RSA keys shorter than 1024 bits but MAY
   accept SHA-1 DS records.
 * MUST validate the inception and expiration timestamps of all signatures in the proof.

## Discussion

When resolving DNS-based payment instructions, lightning payers wish to resolve DNS names to TXT
records (and associated DNSSEC proofs) in a private way. This bLIP defines a protocol by which
payers can do so utilizing lightning's built-in onion messages, avoiding introducing any
dependencies on native DNS resolution or directly-connected public DNS resolvers.

### Overall Lightning Name Resolution Protocol

The overall DNS-based lightning payment instruction resolution protocol is broken across three
separate documents as parts are relevant to different stakeholders. The protocol was originally
sketched in a mailing list post by Bastien at
<https://lists.linuxfoundation.org/pipermail/lightning-dev/2023-November/004204.html>

First of all, the DNSSEC name resolution is defined in a BIP as it is generic across Bitcoin
payment instructions. A current draft may be found at
<https://github.com/bitcoin/bips/blob/master/bip-0353.mediawiki>.

Secondly, this document describes a method of fetching DNSSEC proofs without exiting the lightning
network.

Finally, a forthcoming bLIP will define a method to include the `user` part of the human-readable
name used to look up an `offer` in the `invoice_request`.

#### Payer Protocol

A payer wishing to use these protocols to pay human-readable `user`-`domain` pairs first needs to
be configured with resolver(s) implementing this bLIP. The payer could alternatively find such
nodes by searching the lightning gossip network for nodes announcing the `dns_resolver` feature.

To look up payment instructions given a `user`, `domain` pair, a payer sends their configured
resolver a `dnssec_query`-containing onion message with a `domain_name` of
`user`.user._bitcoin-payment.`domain`.

Upon receipt of the responding `dnssec_proof` the payer validates the `proof` against the DNSSEC
root trust anchor and if it passes parses any TXT records which
`user`.user._bitcoin-payment.`domain` resolves to as a `bitcoin:` URI.

From there, a lightning payer will search for (case-insensitive) the `lno` query parameter in the
resulting URI. If it finds an `lno` query parameter, its value should contain a full offer, which
the payer can simply pay.

In order to allow for a static offer receiving funds on behalf of many users, the payer should
include the `user` from their original query in the `invoice_request` they send the recipient.

#### Recipient Configuration

Recipient configuration is quite straightforward. For a recipient owning their own domain with a
personal offer, they simply add a TXT record at `user`.user._bitcoin-payment.`domain` with the
contents `bitcoin:?lno=OFFER`.

Alternatively, for recipients which do not wish to publish a unique offer for all possible payees,
a wildcard record may be provisioned as *.user._bitcoin-payment.`domain` with the same contents.
The node receiving the `invoice_request` can use the `user` field to determine for which user the
payment is intended and generate an `invoice` specific to that `user`.

## Reference Implementation
* LDK-based resolver: <https://git.bitcoin.ninja/index.cgi?p=lightning-resolver;a=summary>