Rack::Lightning - micropayments for your rack app

Rack middleware for requesting Bitcoin Lightning payments for HTTP request.

Status: alpha - proof of concept

1. On the first request a Lightning invoice is created and th 402 Payment Required HTTP status code is returend with a application/vnd.lightning.bolt11 content type header and a Lightning invoice as a body.
2. Once the client has paid the invoice it does a second request providing the proof of payment / the preimage of the Lightning payment in a X-Preimage header. The middleware checks the if the invoice was paid and continues with the rack app stack

Have a look at the Faraday HTTP client middleware to automatically handle the payment of the requested invoice.

The middleware uses the gRPC service provided by the Lightning Network Daemon(lnd). A running node with is required which is used to generate and validate invoices.

Details about lnd can be found on their github page

Add this line to your application's Gemfile:

gem 'rack-lightning'

Simply add the Rack::Lightning middleware:

require "rack/lightning"

Example = Rack::Builder.new {
  use Rack::Lightning, { price: 100 } 
  run Proc.new { |env| ['200', {'Content-Type' => 'text/html'}, ['get rack\'d']] }
}.to_app

The middleware accepts the following configuration options:

• price: the price in satoshi (default: 100)
• address: the address of the lnd gRPC service( default: localhost:10009)
• credentials_path: path to the tls.cert (default: ~/.lnd/tls.cert)
• macaroon_path: path to the macaroon path (default: ~/.lnd/data/chain/bitcoin/testnet/admin.macaroon)
• credentials: instead of configuring a credentials_path you can pass the content of the tls.cert directly
• macaroon: instead of configuring a macaroon_path you can pass the hex content of the macaroon directly

The tls.cert and the macaroon config can be loaded from a variable:

ENV['LND_CREDENTIALS'] = "the content of your tls.cert file"
ENV['LND_MACAROON'] = "the hex encoded content of your macaroon file"
# you can get the macaroon content like this: xxd -p -c2000 admin.macaroon
# or ::File.read(::File.expand_path("/path/to/admin.macaroon")).each_byte.map { |b| b.to_s(16).rjust(2,'0') }.join

Example = Rack::Builder.new {
  use Rack::Lightning, { macaroon: ENV['LND_MACAROON'], credentials: ENV['LND_CREDENTIALS'] } 
  run Proc.new { |env| ['200', {'Content-Type' => 'text/html'}, ['get rack\'d']] }
}.to_app

The Lightning Network allows to send real near-instant microtransactions with extremely low fees. It is a second layer on top of the Bitcoin network (and other crypto currencies). Thanks to this properties it can be used to monetize APIs.

• philippgille/ln-paywall - middleware for Go frameworks. looks great and very well designed!
• ElementsProject/paypercall - express.js middelware for node.js applications

Bug reports and pull requests are welcome on GitHub at https://github.com/bumi/rack-lightning.

The gem is available as open source under the terms of the MIT License.