claytantor / lnurlpos

Offline lightning PoS

LNURLPoS

Cheap, offline(!), DIY bitcoin lightning-network PoS

Lightning-network uses hot wallets and real-world payments are made from phones. The burden of connectivity can be taken away from the point-of-sale and given to the phone.

For a traditional PoS experience see my LNPoS project.

LNURLPoS uses the LNURL-pay protocol. LNURL-pay allows your lightning-wallet to make a secure request to a server to get a lightning-network invoice. So instead of scanning a massive ugly lightning-network invoice QR, you can scan a lovely little LNURL QR (if you decode an LNURL you'll see its just a URL).

For online stuff I suppose massive QR codes are not an issue, but when fiddling with hardware devices they are. LNURLPoS using the LNURL-pay protocol, it can use a smaller screen for displaying the QR.

Setup workflow

• LNURLPoS server set up and register PoS in a few clicks on LNbits using the LNURLPoS extension
• Copy credentials (including a secret key) from server to the physical LNURLPoS device

Payment workflow

• Merchant enters amount into LNURLPoS device
• LNURL is generated in device and displayed for scanning (LNURL includes a unique pin encrypted using the secret key shared with the server)
• Customer scans and pays
• When the payment has cleared the customer is sent the decrypted unique pin
• Merchant can compare and verify using the same pin displayed on the lNURLPoS

Credit/props

Stepan Snigerev for creating beautiful crypto and LNURL encoding functions.

Fiatjafs incredible OfflineShop extension. LNURLPoS is the same concept, but can run at scale, and is dependent on a device.

Belskomat for pironeering the idea of a shared secret for the microcontroller to encrypt data with.

⚡⚡⚡⚡⚡⚡ LNURLPoS Tutorial ⚡⚡⚡⚡⚡⚡

Hardware needed

• Lilygo TTGO T-Display
• Keypad membrane (these big ones are easy to find, these smaller ones will be used for workshops by arcbtc).
• Angled male/male GPIO pins

Arduino software install

• Download/install latest Arduino IDE
• Install ESP32 boards, using boards manager
• Copy these libraries into your Arduino IDE library folder
• Plug in T-Display, from Tools>Board>ESP32 Boards select TTGO LoRa32 OLED V1

Note: If using MacOS, you will need the CP210x USB to UART Bridge VCP Drivers available here https://www.silabs.com/developers/usb-to-uart-bridge-vcp-drivers

Note: You may need to roll your ESP32 boards back to an earlier version in the Arduino IDE, by using tools>boards>boards manager, searching for esp. I use v1.0.5(rc6), and have also used v1.0.4 which worked.

LNbits extension

To make things easy (usually a few clicks on things like Raspiblitz), there is an LNbits extension. If you want to make your own stand-alone server software that would be fairly easy to do, by replicating the lnurl.py file in the extennsion.

Future updates

At the beginning of this article I said "LNURLPoS (currently) only uses LNURL-Pay". The next stage will be for the PoS to also create LNURL-Withdraws, which are essentially faucets. This means merchants can offer refunds, and also sell bitcoin over the counter, which creates an extremely powerful tool for local economies on-ramping and off-ramping from their local fiat currency.

At Adopting Bitcoin in San Salvador I will distribute 40 kits over x2 workshops, so hopefully some locals will start producing, selling and teaching others how to make these useful little units.

---

Deeper Dive

LNURL

Much of the innovation that happens on lightning-network uses an additional protocol layer called LNURL.

LNURL is just a bech32 encoded URL string, that is a link to an LNURL server that your lightning wallet can request information from. By your wallet being able to communicate with a server, developers are no longer bound by the payee-generate-invoice workflow. There are many different types of LNURL. LNURLPoS (currently) only uses LNURL-Pay.

This is an LNURL-pay QR code:

This is the data in that QR code:

LNURL1DP68GURN8GHJ7MRWVF5HGUEWVDHK6TMVDE6HYMRS9ASHQ6F0WCCJ7MRWW4EXCTECXVUQR8PUDZ

If we decode the LNURL we get this URL:

https://lnbits.com/lnurlp/api/v1/lnurl/838

If you do a GET request to the URL this data will be returned (you can test this by just visiting the URL in a browser):

{
  "callback": "https://lnbits.com/lnurlp/api/v1/lnurl/cb/838", 
  "maxSendable": 10000000000, 
  "metadata": "[[\"text/plain\", \"Lovely little QR\"]]", 
  "minSendable": 10000, 
  "tag": "payRequest"
}

When your wallet gets this json it asks you how much you want to send between the minSendable and maxSendable.

After a moment you get a “payment sent” confirmation and receipt.

So what happened?

When you verify you want to send say 10sats, your wallet sends that data (as a json) to the callback URL. The server then generates an invoice for that amount and sends it back to your wallet, which pays it. Once the payment has cleared, the wallet reveals a receipt to you.

LNURLPoS workflow

LNURLPoS generates and encodes the LNURL in the device, which means we can pass some data in the URL.

The LNURLPoS stores four important pieces of data:

• URL to your LNURL server (we’re using an LNbits install, with dedicated extension)
• PoS ID (Unique ID generated in the LNbits extension)
• Secret (Secret shared with the LNURL server)
• Currency denomination (being offline sats becomes too volatile)

LNURLPoS could use any LNURL server that performs some certain functions, but to make things easy I made an extension in LNbits specifically for LNURLPoS

Once a PoS has been generated the extension gives you this data:

String server = "https://lnbits.com";
String posId = "L4aJNiQZyPxCREoB3KXiiU";
String key = "4TPLxRmv82yEFjUgWKdfPh";
String currency = "EUR";

The data can then be passed to the device when uploading its software through the Arduino IDE

When an amount is entered into the LNURLPoS, the device generates a unique pin, then encrypts the amount+pin using the shared secret and a nonce. The server endpoint, nonce, encypted data, and PoS ID are built into into the LNURL.

https://lnbits.com/lnurlpos/api/v1/lnurl/<nonce>/<encrypted-data>/<pos-id>

LNURL1DP68GURN8GHJ7MRWVF5HGUEWVDHK6TMVDE6HYMRSDAEJ7CTSDYHHVVF0D3H82UNV9U7XUMMWVDJNUTEUV4HXXUNEWP6X2EPDV3SHGCF79U78QMMN945KG0S2PG6GTWSK

When that first GET request happens from the wallet, the LNURL server can find the PoS record, fetch its secret use the secret to decrypt the amount+pin. The amount is converted from the fiat currency to sats, and sent back to the wallet as minSendable and maxSendable.

If the invoice passed to the wallet is paid the customer is given access to the decrypted pin.