LUD-06: `payRequest` base spec.

​

Pay to static QR/NFC/link

​

Wallet to service interaction flow:

1. User scans a LNURL QR code or pastes/shares an lightning:LNURL.. link with LN WALLET and LN WALLET decodes LNURL.
2. LN WALLET makes a GET request to LN SERVICE using the decoded LNURL.
3. LN WALLET gets JSON response from LN SERVICE of form:
   Copy

   {
       "callback": string, // The URL from LN SERVICE which will accept the pay request parameters
       "maxSendable": number, // Max millisatoshi amount LN SERVICE is willing to receive
       "minSendable": number, // Min millisatoshi amount LN SERVICE is willing to receive, can not be less than 1 or more than `maxSendable`
       "metadata": string, // Metadata json which must be presented as raw string here, this is required to pass signature verification at a later step
       "tag": "payRequest" // Type of LNURL
   }
   
   or
   Copy

   {"status": "ERROR", "reason": "error details..."}
   
   metadata json array must contain one text/plain entry, all other types of entries are optional. metadata json array must contain either one image/png;base64 entry or one image/jpeg;base64 entry or neither. The metadata json array is only allowed to contain arrays. The first item of an array inside the metadata array is always a string representing the metadata type while any item that follows can be of any JSON type. Implementors MUST NOT assume it will always be a string.
   Copy

   [
       [
           "text/plain", // mandatory,
           string // short description displayed when paying and in transaction log
       ],
       [
           "text/long-desc", // optional
           string // longer description of the payment, MAY contain newlines
       ],
       [
           "image/png;base64", // optional
           string // base64 string, optional 512x512px PNG thumbnail which will represent this lnurl in a list or grid. Up to 136536 characters (100Kb of image data in base-64 encoding)
       ],
       [
           "image/jpeg;base64", // optional
           string // base64 string, 512x512px JPG thumbnail which will represent this lnurl in a list or grid. Up to 136536 characters (100Kb of image data in base-64 encoding)
       ],
       // future entries:
       [
           string,
           any
       ]
   ]
   
   and be sent as a string:
   Copy

   "[[\"text/plain\", \"lorem ipsum blah blah\"]]"
   
4. LN WALLET displays a payment dialog where user can specify an exact sum to be sent which would be bounded by:
   Copy

   max can send = min(maxSendable, local estimation of how much can be sent from wallet)
   min can send = max(minSendable, local minimal value allowed by wallet)
   
   Additionally, a payment dialog must include:
   • Domain name extracted from LNURL query string.
   • A way to view the metadata sent of text/plain format.
   And it may include:
   • An image element with the contents of image/png or image/jpeg.
5. LN WALLET makes a GET request using
   Copy

   <callback><?|&>amount=<milliSatoshi>
   
   amount being the amount specified by the user in millisatoshis.
6. LN Service takes the GET request and returns JSON response of form:
   Copy

   {
       pr: string, // bech32-serialized lightning invoice
       routes: [] // an empty array
   }
   
   or
   Copy

   {"status":"ERROR", "reason":"error details..."}
   
7. LN WALLET Verifies that h tag in provided invoice is a hash of metadata string converted to byte array in UTF-8 encoding.
8. LN WALLET Verifies that amount in provided invoice equals the amount previously specified by user.
9. LN WALLET pays the invoice, no additional user confirmation is required at this point.

​

Notes on metadata for server-side LNURL-PAY

​

When client makes a first call:

​

When client makes a second call

1. Make a hash as follows: sha256(utf8ByteArray(unescaped_metadata_string)).
2. Generate a payment request using an obtained hash.