lightning-backends

Node.js module to integrate with various Lightning Network node software and service providers.

• List of Backends
• Installation
• Usage
  • Backend Configuration Options
  • Custom Backend
• Tests
• Changelog
• License

List of Backends

The following list includes all the Lightning Network node software and service providers which are supported:

• Lightning Network Daemon (lnd)
• Core Lightning - JSON-RPC interface over unix sock or HTTP-RPC interface made available by Sparko plugin
• LNBits
• GetAlby
• LndHub - first implemented by BlueWallet, but now used as a standard interface by other wallets and services
• OpenNode

Installation

Add to your application via npm:

npm install lightning-backends

Usage

const { checkBackend, prepareBackend } = require('lightning-backends');

const backend = 'lnd';
const config = {
	hostname: '127.0.0.1:8080',
	protocol: 'https',
	cert: '/path/to/lnd/tls.cert',
	macaroon: '/path/to/lnd/admin.macaroon',
};

const ln = prepareBackend(backend, config);

// Pay a Lightning invoice.
ln.payInvoice(invoice).then(result => {
	// `{ id: null }`
	// `{ id: 'custom-unique-identifier' }`
	console.log('payInvoice OK', { result });
}).catch(error => {
	console.error('payInvoice FAILED:', { error });
});

// Request a new Lightning invoice from the backend.
ln.addInvoice(21000/* msat */).then(result => {
	// `{ id: null, invoice: <bolt11-invoice> }`
	// `{ id: 'custom-unique-identifier', invoice: <bolt11-invoice> }`
	console.log('addInvoice OK', { result });
}).catch(error => {
	console.error('addInvoice FAILED:', { error });
});

// Get the current status of an invoice by its payment hash or unique identifier.
// Some backends require the use of a unique identifier instead of payment hash.
// If the `addInvoice` method returns an `id` then use tha instead of the payment hash here.
ln.getInvoiceStatus(paymentHash).then(result => {
	// `{ preimage: null, settled: false }`
	// `{ preimage: '23b1a130cdc61f869674fdc4a64e8de5da1d4666', settled: true }`
	console.log('getInvoiceStatus OK', { result });
}).catch(error => {
	console.error('getInvoiceStatus FAILED:', { error });
});

// Get current spendable Lightning balance.
ln.getBalance().then(result => {
	// `result` will be the balance in millisatoshis.
	console.log('getBalance OK', { result });
}).catch(error => {
	console.error('getBalance FAILED:', { error });
});

// Open a new channel.
// Most backends do not support this method.
ln.openChannel(remoteId, localAmt, pushAmt, makePrivate).then(result => {
	// `result` can vary depending upon the backend used.
	console.log('openChannel OK', { result });
}).catch(error => {
	console.error('openChannel FAILED:', { error });
});

// Attempt to pay a 1000 msat invoice for a randomly generated node private key.
// Since the node doesn't exist, it will always fail.
// If the error is "no_route" or some other similar error, then the check is passed.
// Failed authentication or any unexpected errors are considered a failed check.
checkBackend(backend, config, { method: 'payInvoice' }).then(result => {
	console.log('Backend configuration check', result.ok ? 'OK' : 'FAILED', { result });
});

Backend Configuration Options

Lightning Network Daemon (lnd):

• hostname - The host and port of the node's REST API. Examples:
  • 127.0.0.1:8080
  • esdlkvxdkwxz6yqs6rquapg4xxt4pt4guj24k75pdnquo5nau135ugyd.onion
• protocol - "http" or "https" - Must be "https" unless an onion address is used.
• baseUrl - The full URL and path of the node's REST API. Can be used instead of the hostname and protocol options above. Examples:
  • https://127.0.0.1:8080/custom/path
  • http://esdlkvxdkwxz6yqs6rquapg4xxt4pt4guj24k75pdnquo5nau135ugyd.onion/custom/path
• cert - The TLS certificate of the lnd node. Examples:
  • /path/to/lnd/tls.cert - As a file path.
  • { data: 'STRING_UTF8_ENCODED' } - As a string.
  • { data: Buffer.from('STRING_UTF8_ENCODED', 'utf8') } - As a buffer.
• macaroon - The authentication macaroon to access the lnd node's REST API. Examples:
  • /path/to/lnd/admin.macaroon - As a file path.
  • { data: 'STRING_HEX_ENCODED' } - As a string.
  • { data: Buffer.from('STRING_HEX_ENCODED', 'hex') } - As a buffer.
• torSocksProxy - If hostname contains an onion address, the backend will try to connect to it using the the TOR socks proxy. Default:
  • 127.0.0.1:9050

Core Lightning (unix sock):

• unixSockPath - The absolute file path to the unix sock of core lightning. Example:
  • /path/to/unix/sock/.lightning/lightning-rpc

Core Lightning (Sparko):

• baseUrl - Full URL and path of the Sparko plugin's HTTP-RPC API. Onion addresses are supported. Examples:
  • https://127.0.0.1:9737/rpc
  • http://esdlkvxdkwxz6yqs6rquapg4xxt4pt4guj24k75pdnquo5nau135ugyd.onion/rpc
• cert - The TLS certificate used by the Sparko plugin.
• accessKey - See --sparko-keys= in your lightningd config.

LNBits:

• baseUrl - The URL of the LNBits instance. Example:
  • https://legend.lnbits.com
• adminKey - From an account page, open "API info" to view the "Admin key".

GetAlby:

• secret - Go to the GetAlby website, login to your account (link in top-right corner), then go to "Wallet" page (top-center), then scroll down until you see "Show your connection credentials". Click that button to reveal your lndhub secret. Copy and paste it here.
  • lndhub://login:password@https://ln.getalby.com

LndHub:

• secret - If using LNBits: Go to Extensions to enable the LndHub extension; then open the LndHub extension page and copy the LndHub Admin URL. Example:
  • lndhub://admin:xxx@https://your-lnbits-instance/lndhub/ext/

OpenNode:

• apiKey

Custom Backend

It is possible to define your own custom backend to use with this module. To do so, create a new file and save it in your project:

// ./backends/custom.js

const { LightningBackend } = require('lightning-backends/lib');

class Backend extends LightningBackend {

	static name = 'custom';

	constructor(options) {
		super(Backend.name, options, {
			defaultOptions: {
				customOption1: 'a default value',
			},
			requiredOptions: ['customOption1'],
		});
	}

	checkOptions(options) {
		// This is called by the constructor.
		// Throw an error if any problems are found with the given options.
	}

	getNodeUri() {
		// Options are available as follows:
		const { customOption1 } = this.options;
		return Promise.reject('Not implemented');
	}

	openChannel(remoteId, localAmt, pushAmt, makePrivate) {
		return Promise.reject('Not implemented');
	}

	payInvoice(invoice) {
		return Promise.reject('Not implemented');
	}

	addInvoice(amount, extra) {
		return Promise.reject('Not implemented');
	}

	getInvoiceStatus(paymentHash) {
		return Promise.reject('Not implemented');
	}
};

module.exports = Backend;

Then to use your custom backend:

const { prepareBackend } = require('lightning-backends');

const backend = './backends/custom.js';
const config = {};

const ln = prepareBackend(backend, config);

ln.payInvoice(invoice).then(() => {
	console.log('payInvoice OK', { result });
}).catch(error => {
	console.error('payInvoice FAILED:', { error });
});

Tests

Run automated tests as follows:

npm test

To run only end-to-end tests:

npm run test:e2e

Configurations for each backend are loaded from environment variables from the ".env" file. Create one by copying the example file:

cp test/e2e/example.env test/e2e/.env

Tests are skipped for backends whose configurations are missing (or commented-out).

Changelog

See CHANGELOG.md

License

This software is MIT licensed:

A short, permissive software license. Basically, you can do whatever you want as long as you include the original copyright and license notice in any copy of the software/source. There are many variations of this license in use.