Tooling for Invoices in Lightning Network Applications

André Neves
Nov 8, 2018 · 4 min read

Lightning Decoder — the first of (hopefully) many development tools

Image for post
Image for post
Lightning Decoder —

Throughout my quest of bringing Lightwork to production on Bitcoin’s mainnet, I’ve come across some gaps in the current development workflow of Lightning Network-powered applications. One of the larger gaps I saw was in relation to the use and understanding of the Invoice Protocol (BOLT11 spec), which is core to the network.

The Invoice Protocol is a simple, extendable QR-code-ready protocol for requesting payments over the Lightning Network.

BOLT11 Encoding

The creator of an LN invoice must encode the payment request in bech32 as specified in BIP-0173. The only exception is that the bech32 string can be longer than the 90-character limit specified in the BIP. The receiver of an LN invoice must parse the address as bech32 (without character limit), and must fail if the checksum of the hash is incorrect.

Invoice URI Scheme


Note, it’s not lightning:// but just lightning: .

Given that Lightning payments can sometimes fail (due to routing or capacity issues), application developers should also have fallback support for moving transactions onchain. For that, one should leverage the bitcoin: URI scheme, as per BIP-21, with the key lightning and the value equal to the BOLT11 invoice encoding.

Lightning Decoder

Image for post
Image for post
Lightning Decoder —

Lightning Decoder is meant to be a one-stop solution for your Lightning Network invoice-decoding needs. It’s where you can decode payment requests and learn all of the information bits involved in its creation. This is key to not only understand how this payment request came about, but also to drill into the details of the payment to ensure parity with your application’s own database of records.

Below is an example of an invoice being decoded through Lightning Decoder:

Image for post
Image for post
Decoded Lightning Network Invoice —

It provides clear information about which underlying chain this invoice was created in/for, what the desired payment amount is (in satoshis), as well as a timestamp of its creation. This also helps in identifying payee public node keys, transaction signatures and payment hashes which can be verified further.

LN Node & Application State Sync

For Lightwork I decided to leverage the ‘description’ field. This is a blank field in the LN payment request that allows for the user to input any text/data/string (similar to a memo field). After being encoded, that information is invisible to the naked eye. But when decoded you see something along the lines of:

Image for post
Image for post
Description field for LN invoice inside Lightwork —

My approach is to enter an identifier string, in this case Lightwork which allows me to split the string precisely and predictably. The following 5bdd9d… is the ID of the database document this invoice belongs to. This make is easier to connect an LN invoice to its related document when subscribing to payments over the network. I’ve personally heard this approach being used in other applications that accept Lightning payments, which is even further validation of this implementation.

UX for Development Tools

My goal with Lightning Decoder was to bring pleasant design and utility together, so that developers can not only depend on its functional capabilities, but can also enjoy the experience of using and relying on it daily.

This is the first of (hopefully) many tools that I’ll be deploying as I continue my efforts in building Lightwork. I have already outlined a couple of other gaps in the LN development workflow that seem to allow for the creation of other tools like this. Lightning Decoder is entirely open source, and I aim to introduce new features and capabilities as the Lightning Network continues to evolve and mature.


Hashtag Reckless


Lightning Network Development

Medium is an open platform where 170 million readers come to find insightful and dynamic thinking. Here, expert and undiscovered voices alike dive into the heart of any topic and bring new ideas to the surface. Learn more

Follow the writers, publications, and topics that matter to you, and you’ll see them on your homepage and in your inbox. Explore

If you have a story to tell, knowledge to share, or a perspective to offer — welcome home. It’s easy and free to post your thinking on any topic. Write on Medium

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store