lnurl, a protocol for seamless interaction between services and Lightning wallets

lnurl is a protocol for communication between Lightning wallets and third-party services. It simplifies complicated common flows into standard subprotocols carried on between the user wallet and the service over simple HTTP JSON calls, leveraging the fact that the third-party services have the luxury of offering an https:// endpoint the user wallet can freely call.

In doing so lnurl also takes into account the fact that a big part of all Lightning wallets, present and future, are mobile wallets (either standalone or clients to a remote node), and many times interacting with services in untrusted environments different from a home computer, so the URL that initiates the protocol is always encoded in a QR code that is displayed to the user by the service somehow (after being bech32-encoded with the lnurl tag).

Basically it goes like this:

1. The wallet reads a QR code;
2. If it has the lnurl prefix it is decoded and the the resulting URL is called;
3. From the server response for that URL the wallet knows what subprotocol it should proceed with;
4. In the case of lnurl-withdraw, for example, the server response will contain some parameters (min/max, default description) for the invoice that will be generated in the user wallet;
5. The wallet proceeds with the subprotocol. In the case of lnurl-withdraw, for example, it will display an invoice generation window prefilled with the parameters returned by the server, and, upon confirmation by the user, send the invoice back to the server, which will pay it.

Demo of lnurl-withdraw:

There's a spec and a collection of resources, including a list of compliant wallets and services.

lnurl-withdraw

If your wallet is on a phone and you're using a Lightning app on a desktop computer it can be really hard to get an invoice generated on your wallet to the website on the computer. That's even impossible to do if you're buying satoshis on a Lightning ATM machine.

lnurl-withdraw allows a wallet to withdraw easily from a service by just scanning a QR code.

lnurl-pay

Static invoices QR codes are impossible on Lightning as each payment must be presented with a different combination of hash and preimage (that serve both to prove a payment was done and to secure the HTLCs involved in the payment path). Without these, it's impossible to have simple donation pages or to print QR codes on paper.

The idea of lnurl-pay is to enable such use cases and many many others. You scan a QR code (that could be on a static website, printed on a paper or even carved in a rock) and your wallet will get metadata from it from a server -- after choosing to pay or not (and depending on the service you may have the option to choose how much to pay) you'll get an invoice from the server with the correct amount and pay it. The service will then act and provide you with the service you paid for, if that's the case.

That simple flow is able to

1. simplify architectures by decoupling the Lightning node from the website that is service the QR code;
2. enable seamless interactivity between mobile wallets and real-world devices or services (pay and use scooters, buy things from a menu by just scanning a code etc.), like the things enabled by China's WeChat and similar centralized services;
3. allow services to present users with the option to choose how much they will pay for a service without having to present them with an UI for typing the numbers, they will do that from their wallets.

lnurl-channel

If your node is running on a phone or behind NAT, you can't have a public IP address so other nodes can't connect directly to you. That's necessary when someone wants to open a channel with you. How do you solve it? You connect to them first.

lnurl-channel automatizes that process: you scan a QR code, then your wallet will automatically connect to the service and wait for the service to open a channel back to it.

lnurl-auth

Typing passwords is a pain, keeping them in a safe place is worse. But you already have to keep your wallet mnemonic safe and you are already storing a private key on your phone: why not leverage that?

Similar to SQRL (but instead of having 36 pages of technical documentation lnurl-auth is very simple and can be implemented in two minutes), lnurl-auth allows you to scan a QR code and automatically creates an identity and communicates that with the service. Each service gets a different identity so they know you are the correct person, but don't know who you are.

A video showing an lnurl-powered physical Bitcoin faucet in action (beware, it has bad rock music in the background).