
Withdrawal of funds from a service
LNURL-WITHDRAW #
This flow used in the case where a recipient (LN WALLET
) needs to initiate payment to themselves from some payer/service (LN SERVICE
). It is useful in cases where for e.g. a user of a service needs to withdraw some balance held by the service to their own user wallet.
Traditionally this would be a 2-step process that consists of:
- The
LN WALLET
generating an LN-invoice and passing it to theLN SERVICE
out-of-band somehow (likely a copy-paste operation) - The
LN SERVICE
actively paying the invoice received
This process is particularly tricky for the LN WALLET
when they have to figure out how to communicate the generated invoice to the LN SERVICE
if for e.g. the LN SERVICE
is a website or some service on a separate device (e.g. desktop) from where the LN WALLET
is (e.g. mobile).
The LNURL-withdraw flow standardises the communication of this LN invoice and payment of the invoice into a single UX action initiated by the LN WALLET
.
Use-cases:
- user withdrawing a balance from some service
LN primitives involved:
- LN Invoice
An Example Flow #
-
LN SERVICE
: Generate a unique LNURL endpointThe first step is for the
LN SERVICE
to setup and encode a unique LNURL endpoint for theLN WALLET
user.// The params for the endpoint are determined var params = { "minWithdrawable": 10000, "maxWithdrawable": 20000, "defaultDescription": "lnurl-toolbox: withdrawRequest" } // An endpoint is setup to generate a response which will include the 'params' "https://lnurl-toolbox.degreesofzero.com/u?q=a7dd031e0506e8da6da3cef92970fab4d61f099051b4941e8a2ce9d338963aad" // Endpoint gets bech32 encoded "lnurl1dp68gurn8ghj7mrww4exctt5dahkccn00qhxget8wfjk2um0veax2un09e3k7mf0w5lhz0tpxajxgvpnx9jnqdfsxejnserpxejxzvmrv4nrjv3exucxvctzx3jrvvtxxqunjvp4x93rgwf5x9jnscfjvdjnjepnxvurjd3nv9skg4e9eg2"
-
LN WALLET
: Scan the LNURL QR Code (or copy-paste the LNURL bech32 string)The user opens an LNURL-enabled wallet and scans or pastes the LNURL invoice. The wallet then calls the endpoint and receives a response with parameters required to be filled into an LN invoice by the
LN SERVICE
. The response also contains a secretk1
that theLN WALLET
must also send along in the subsequent withdrawal request later on.# Wallet decodes the LNURL invoice and sends a GET request to decoded url GET https://lnurl-toolbox.degreesofzero.com/u?q=a7dd031e0506e8da6da3cef92970fab4d61f099051b4941e8a2ce9d338963aad
// Wallet receives a response { "minWithdrawable":10000, "maxWithdrawable":20000, "defaultDescription":"lnurl-toolbox: withdrawRequest", "callback":"https://lnurl-toolbox.degreesofzero.com/u", "k1":"a7dd031e0506e8da6da3cef92970fab4d61f099051b4941e8a2ce9d338963aad", "tag":"withdrawRequest" }
-
LN WALLET
: Enter amount and confirm withdrawal via in-wallet payment dialogThe
LN WALLET
should present a dialog at this point where the user can enter an amount (constrained to a given valid range). -
LN WALLET
: Generate LN invoice to send in requestThe
LN WALLET
uses the amount from the user input to generate a valid LN invoice in the traditional way internally.lnbc150n1ps875y7pp5jv886ulk50nt0dm94sgr6q7zquv3qv5h8dnxkvn022fhtlp8x40sdqlf38925jv94mkjargv3exzaeqw3jhxaqcqzpgxqyz5vqsp5w33wl0jwkmrjqjkptz05c3rlwumgzt0gr2z2vg5pg6ctcdj4426q9qyyssqdrsph679ra7vuk5exkemtjhx0f3ee3xk2nf7egj0dapn5erwzjr404x0z6580c4wrgxnnwv8kcgwwc0z396rmnk4u35xms7temlpxvsqstsqn9
-
LN WALLET
: Sends withdrawal details toLN SERVICE
The
LN WALLET
adds the generated LN invoice and the original secretk1
to a request object and then calls the callback url with this object.GET https://lnurl-toolbox.degreesofzero.com/u?k1=a7dd031e0506e8da6da3cef92970fab4d61f099051b4941e8a2ce9d338963aad&pr=lnbc150n1ps875y7pp5jv886ulk50nt0dm94sgr6q7zquv3qv5h8dnxkvn022fhtlp8x40sdqlf38925jv94mkjargv3exzaeqw3jhxaqcqzpgxqyz5vqsp5w33wl0jwkmrjqjkptz05c3rlwumgzt0gr2z2vg5pg6ctcdj4426q9qyyssqdrsph679ra7vuk5exkemtjhx0f3ee3xk2nf7egj0dapn5erwzjr404x0z6580c4wrgxnnwv8kcgwwc0z396rmnk4u35xms7temlpxvsqstsqn9
-
LN SERVICE
: Receive request, verify, payThe
LN SERVICE
decodes the received LN invoice and verifies the amount and validity of the invoice against the original request sent to theLN WALLET
.The
LN SERVICE
then responds with an appropriate message once the request is verified and then it attempts to pay the LN invoice.// Response sent back to `LN WALLET` {"status":"OK"}