npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

lightning-backends

v1.7.0

Published

Module to integrate with various Lightning Network node software and service providers

Downloads

1,255

Readme

lightning-backends

Build Status

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

List of Backends

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

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.

Blink:

  • connectionString - Contains the server URL, account API key, and wallet ID. Example:
    • type=blink;server=https://api.blink.sv/graphql;api-key=blink_XXX;wallet-id=xxx-yyyy-zzzz-0000-xyz123

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.