Boltwall — Middleware for Lightning Payments & Authorization

Boltwall makes it easy to add Lightning paywall and authorization to web applications. It’s an open source middleware, written in Typescript. Boltwall supports OpenNode’s API, serverless deployments with Zeit, and time-restricted authorization. Get a Lightning based paywall running in minutes with minimal code.

Example: A Simple Paywall

Imagine you want to make content behind the route /protected available only to users that have made a small lightning payment. You might want this to monetize the content or provide DDoS protections to API requests.

The process would look something like this:

• Any request made to this route by a client/user that has not paid, will be given a 402 error in response (a status code first proposed in the 90s but still not widely implemented due to the lack of a native payments protocol).
• Boltwall can then return a Lightning invoice based on what is being requested (usually by sending a POST request to /protected/invoice).
• The payment is then made, a step that can be done by a node that has no knowledge of the Boltwall server at all.
• Once the invoice is paid, the next time /protected is requested, Boltwall can independently verify the payment and authorize the request to be sent along the route.

All that you need to enable the above is add the following line of code before any route you want protected (this is assuming an Express.js server):

// require a minimum payment of 30 satoshis

app.use(boltwall({minAmount: 30})

// anything afterboltwallis protected

app.use('/protected', (req, res) => res.send('I am a protected route'))

Contextual Caveats with Macaroons

Boltwall’s flexibility distinguishes it from other Lightning paywall middleware. Because it is written in a modular way, with a minimal need for permissions, it can be run in a totally separate service or even server from the Lightning Node you would like to receive the payments. More importantly though it can be run independently of the service for which it is running the credentialing, like running a 3rd party authentication service.

Boltwall leverages an authorization credential protocol known as Macaroons, described in the original Google paper as “cookies with contextual caveats”. For those of you familiar with how Cookies and JWT (JSON Web Tokens) are used on the web, the idea is pretty similar. Again from the paper:

In particular, Boltwall leverages two important characteristics of what Macaroons can enable: delegation and third-party attenuation. To learn more about how Macaroons work, I recommend an article from Hacking, Distributed, Macaroons are Better Than Cookies! as well as the README for one of the first implementations, libmacaroons. Otherwise, read on to understand how they’re used in boltwall.

Be Your Own oAuth — Custom, Account-less Authorization

In Boltwall, the use of Macaroons allows for further separation than just from the LND service that processes payments. It also allows for separation between the authorization of payment and the service hosting the API you would like to protect. Think of it like running your own oAuth service. In the same way that Google’s oAuth allows a third-party service to sign you in to their platform by verifying your Google account, with boltwall, your API can act like Google, but instead of verifying your account, the service verifies that a sufficient payment has been made.

As an example, imagine you are hosting some content on a third-party platform, a service like Medium. You want your content to be behind the paywall but you don’t want to trust that third-party to be a custodian of the funds that users pay to view your content. Just like with the oAuth example above, this service would delegate a portion of the authorization to your boltwall server, and only authorize a user’s request once you, as the owner of the content and the Boltwall server, have confirmed payment.

In brief, the application issues what is known as a root macaroon that has a third-party caveat that only your Boltwall server can “unlock”. It does this by issuing a discharge macaroon that, when sent with the originating root macaroon, verifies to the application that payment was received.

This diagram demonstrates the authorization flow in more detail:

The architecture of Boltwall thus enables developers either to use it in the same process as the data being protected, in which case it is both the issuer of the root macaroon as well as the validator, or it can be run entirely independently. In the latter construction, with minimal coordination, an external service issues the root macaroon and the Boltwall service simply issues a corresponding third-party authorization.

Custom Caveats

Boltwall uses macaroons to create custom caveats that restrict authorization. For example, let’s look at a custom setup boltwall provides out of the box. The exposed TIMECAVEATCONFIGS are a set of configurations that add time-restricted authorization to your paywall. The configurations are also exposed to the request object and invoice details, meaning that the authorization can be tied to this data.

For example, with the TIMECAVEATCONFIGS, any authorization given by Boltwall will only be valid for a duration of seconds equal to the number of satoshis paid. So, if you only want to allow users to access an API for 30 seconds if they only paid 30 satoshis to your lightning node, this is all you need (extended from above):

// using the available time-restricted configs

import {boltwall, TIME_CAVEAT_CONFIGS } from 'boltwall'

app.use(boltwall(TIME_CAVEAT_CONFIGS)

// anything afterboltwallis protected

app.use('/protected', (req, res) => res.send('I am a protected route'))

The timer is only started after the first request after the invoice has been paid.

OpenNode Support

If you don’t want to run a lightning node, or want to avoid having direct exposure to cryptocurrencies, boltwall offers support for OpenNode’s API. OpenNode is a hosted solution for developers who want to accept Bitcoin payments either directly on-chain or via Lightning but don’t want the hassle of running their own node. This makes the setup for using boltwall even easier. Just signup to OpenNode, get a developer’s API key, set it as an environment variable when deploying your boltwall server and start accepting payments! OpenNode will give you access to easy to manage accounting tools as well as withdrawals into fiat, while still maintaining all the features of boltwall, even the time-restricted caveats. Note that at this time only testnet is supported.

Serverless Deployment Option

We offer an easy to deploy solution for running your boltwall service as a serverless lambda function using now by Zeit. With just a couple of lines of code and minimal configuration, you can have Boltwall running live behind https and accessible to the world wide web.

https://github.com/Tierion/now-boltwall

If you want a place to try out your boltwall server, Prism is a Medium-like service that was the initial impetus for developing boltwall. Prism needed a way for authors to directly receive payments for users viewing their posts without the app handling payments or requiring registration by readers.

Documentation

Technical details of the library, how it can be used in your project, as well as API information can be found on the documentation website: https://tierion.github.io/boltwall

The code is hosted on GitHub: https://github.com/Tierion/boltwall

Documentation on the REST API can be found on SwaggerHub https://app.swaggerhub.com/apis-docs/prism8/boltwall/1.0.0

What’s Next?

More Attenuation Models

One priority is to add more flexibility in the attenuation of the authorization. While time-based restrictions felt like the most immediately useful configuration, we could imagine other models having utility as well. Opportunities such as adjustable payment rates, IP-based restrictions, or authorization tied to a node’s public key all could be possibilities for new caveat configs.

LND API

We think Boltwall could be even more useful is by making the interactions with LND’s API more robust. For example, HODL Invoices could enable multi-stage payments via fidelity bonds. Support for more complex routing mechanisms could open up other opportunities as well.

If Boltwall sounds like something you’d be interested in working on, or there’s a feature you’d like to see, reach out and let us know!