Skip to content

Latest commit

 

History

History
256 lines (198 loc) · 8.62 KB

README.md

File metadata and controls

256 lines (198 loc) · 8.62 KB
Raw

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.