Add LUD-22: Lightning address request specification

[mandelmonkey]

Introduces a new protocol for services to request a user's Lightning address without manual input. Particularly useful for games, kiosks, and interactive experiences where typing creates friction.

Example use case: A kart racing game at a conference that streams sats to players as they collect coins - users simply scan a QR code instead of typing their Lightning address.

[DULUKTZ]

Hi

[andrerfneves]

Thanks for writing this up — the use case is solid and something the ecosystem genuinely needs. Before this can merge there are a few things worth addressing:

---

1. Numbering: this should be LUD-23, not LUD-22

PR #251 (bipa-app) proposes currency denomination on payRequest and has 69 reviews and 21 comments — it has the strongest community mandate for LUD-22 by a wide margin. Assigning this spec the same number will create a conflict. Please rename the file to 23.md, update the README entry to [23], and update all self-references in the document from "LUD-22" to "LUD-23".

---

2. Callback method: POST → GET (or explicitly justify POST)

Every existing LUD callback uses GET with query parameters:

• LUD-06 (payRequest): GET <callback>?amount=<milliSatoshi>
• LUD-18 (payerData): GET <callback>?amount=X&payerdata=<urlencode(json)>
• LUD-04 (auth): GET <url>?sig=<hex>&key=<hex>

This PR is the only one in the ecosystem that uses POST with a JSON body. That is not necessarily wrong, but it creates implementation friction:

• Wallet developers have a single HTTP client pattern for all LUD callbacks; introducing POST breaks that
• CORS preflight (OPTIONS) is required for cross-origin POST + JSON, whereas GET is preflight-free
• Existing LNURL infrastructure (proxies, middleware) is built around GET callbacks

Recommendation: Change the callback to a GET:

GET <callback>?k1=<hex(32 bytes)>&address=<user@domain.com>

This is consistent with how LUD-18 handles sending PII (name, email, identifier) — it uses payerdata=<urlencode(json)> as a query param. A Lightning address is no more sensitive than what LUD-18 already sends over GET.

If you have a strong reason to keep POST (e.g. logging/privacy concerns), please add an explicit rationale section in the spec explaining the deviation from convention.

---

3. metadata field: rename to description — naming collision with LUD-06

LUD-06 already defines a metadata field as a structured JSON array:

"metadata": "[[\"text/plain\",\"Pay me\"],[\"image/png;base64\",\"...\"]]"

Your metadata is a plain string:

"metadata": "Share your Lightning address with AwesomeGame to receive rewards"

Same field name, completely different shape. This will cause confusion for implementors parsing LUD-06 responses who encounter this field. Please rename to description:

{
    "tag": "addressRequest",
    "callback": "https://yourapp.com/receive-address",
    "k1": "hex(32 bytes of random data)",
    "description": "Share your Lightning address with AwesomeGame to receive rewards"
}

Update the wallet display requirement accordingly:

LN WALLET displays a confirmation dialog which must include:

• The domain name extracted from the callback URL
• The description text explaining why the address is being requested
• A clear indication that the Lightning address will be shared
• Approve / Deny options

---

4. Address format validation: reference LUD-16 explicitly

The validation regex in the example (/^[\w\-\.]+@[\w\-\.]+\.\w+$/) is too permissive. LUD-16 defines the exact allowed character set:

The <username> is limited to a-z0-9-_. (and + if the SERVICE supports tags). Note this is stricter than common email addresses — only lowercase characters.

Reference: LUD-16

Replace the example regex with one that matches LUD-16:

// Validate per LUD-16: username is a-z0-9-_. (plus optional + for tags)
if (!/^[a-z0-9\-_.+]+@[a-z0-9\-_.]+\.[a-z]{2,}$/.test(address)) {
    return res.json({
        status: "ERROR",
        reason: "Invalid Lightning address format. Must conform to LUD-16: lowercase a-z, 0-9, and -_. only"
    });
}

Also add a normative note in the spec body:

LN SERVICE MUST validate that the submitted address conforms to the Lightning address format defined in LUD-16: <local-part>@<domain> where <local-part> is restricted to [a-z0-9\-_.] (with optional + for tag support).

---

Summary of changes needed

#	Change
1	Rename 22.md → 23.md, update README [22] → [23], update all "LUD-22" refs in doc
2	Change callback from POST JSON body to GET query params: ?k1=<hex>&address=<user@domain>
3	Rename metadata → description throughout
4	Replace address validation regex with LUD-16-compliant pattern; add normative reference to LUD-16

Happy to help iterate on the revised draft if useful.

[mandelmonkey]

@andrerfneves Thank you for the feedback, I have implemeted your requested changes, let me know if they need further attention