Skip to content

Latest commit

 

History

History
108 lines (81 loc) · 4.06 KB

06.md

File metadata and controls

108 lines (81 loc) · 4.06 KB
Raw

LUD-06: payRequest base spec.

author: fiatjaf author: akumaigorodski discussion: https://t.me/lnurl/139

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:

    {
    callback: String, // The URL from LN SERVICE which will accept the pay request parameters
    maxSendable: MilliSatoshi, // Max amount LN SERVICE is willing to receive
    minSendable: MilliSatoshi, // Min 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

    {"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.

    [
    [
        "text/plain", // must always be present
        content // actual metadata content
    ],
    [
        "image/png;base64", // optional 512x512px PNG thumbnail which will represent this lnurl in a list or grid
        content // base64 string, up to 136536 characters (100Kb of image data in base-64 encoding)
    ],
    [
        "image/jpeg;base64", // optional 512x512px JPG thumbnail which will represent this lnurl in a list or grid
        content // base64 string, up to 136536 characters (100Kb of image data in base-64 encoding)
    ],
    ... // more objects for future types
]

    and be sent as a string:

    "[[\"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:

    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

    <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:

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

    or

    {"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 an amount previously specified by user.

  9. LN WALLET pays the invoice, no additional user confirmation is required at this point.

  10. Once payment is fulfilled LN WALLET executes a non-null successAction. For message, a toaster or popup is sufficient. For url, the wallet should give the user a popup which displays description, url, and a 'open' button to open the url in a new browser tab. For aes, LN WALLET must attempt to decrypt a ciphertext with payment preimage. LN WALLET should also store successAction data on the transaction record.

Notes on metadata for server-side LNURL-PAY

When client makes a first call:

Construct a metadata object, turn it into json, then include in into parent json as string.

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.