Easy to use gRPC wrapper for lnd. ⚡️
This package provides and easy to use gRPC wrapper for lnd.
- Supports all lnd versions
- Supports all lnd gRPC sub services
- Automatic async/promise support
- Automatic lnd version detection
- lndconnect support
Table of Contents
Install via npm:
npm install lnd-grpc --save
Then import in your code:
Create a new instance of the service using the
const grpc = options
The constructor accepts the following options:
An lndconnect uri that encodes the lnd connection details (host, cert, and macaroon). If
lndconnectUriis set it will override the
Hostname and port of lnd gRPC. (extracted from
TLS certificate of the lnd node. This can be a path to the TLS cert or PEM ended cert data. (extracted from
Macaroon for the lnd node. This can be a path to the macaroon file or hex encoded macaroon data. (extracted from
Time (ms) to wait for TLS certificate before aborting connection attempt.
This is useful in the case where you can not guarantee that the TLS certificate exists at the time when you attempt to establish the connection.
trueto use the default of 10 seconds.
Time (ms) to wait for macaroon before aborting connection attempt.
This is useful in the case where you are connecting to a local node where a wallet does not already exist. After calling lnd's
initWalletmethod to create a new wallet, it can take some time for lnd to initialize and create the wallet's macaroons.
trueto use the default of 10 seconds.
If you know which version of lnd you are connecting to in advance you can specify that here.
By default, we use the latest proto files available when connecting to lnd. As soon as the wallet is unlocked, we call lnd's
getInfomethod in order to determine which version of lnd is running. If needed, we will reconnect using a more appropriate proto version.
Custom path to rpc proto files. advanced
Custom gRPC options. advanced
host: 'localhost:10009'cert: '~/.lnd/tls.cert'macaroon: '~/.lnd/data/chain/bitcoin/mainnet/admin.macaroon'
host: 'localhost:10009'cert: '~/.lnd/tls.cert'macaroon: '~/.lnd/data/chain/bitcoin/mainnet/admin.macaroon'version: '0.6.0-beta'waitForMacaroon: 30 * 1000 // 30 secondswaitForCert: trueprotoDir: '~/path/to/proto/files' // useful when running in electron environment, for example
After initializing a new
LndGrpc instance, call its
connect method to establish a connection to lnd.
const grpc = host cert macaroonawait grpcconsole // active|locked
After establishing a connection you can access all available lnd gRPC interfaces under the
Unlock & Activate
If the wallet state was determined to be
locked when the connection was established you must first unlock the wallet and then activate the Lightning service in order to access methods on the Lightnig service or any other grpc subservice that requires the node to be unlocked.
const WalletUnlocker = grpcservicesif grpcstate === 'locked'await WalletUnlockerawait grpcconsole // active
Disconnect from all gRPC services. It's important to disconnect from the lnd node once you have finished using it. This will free up any open handles that could prevent your application from properly closing.
const grpc =host: 'localhost:10009'cert: '~/.lnd/tls.cert'macaroon: '~/.lnd/data/chain/bitcoin/mainnet/admin.macaroon'waitForCert: truewaitForMacaroon: true// Establish a connection.await grpc// Do something cool if we detect that the wallet is locked.grpc// Do something cool when the wallet gets unlocked.grpc// Do something cool when the connection gets disconnected.grpc// Check if the wallet is locked and unlock if needed.if grpcstate === 'locked'const WalletUnlocker = grpcservicesawait WalletUnlocker// After unlocking the wallet, activate the Lightning service and all of it's subservices.await WalletUnlocker// Make some api calls...const Lightning Autopilot Invoices = grpcservices// Fetch current balance.const balance = await Lightning// Enable autopilot.const modifyStatusRes = await Autopilot// Cancel an invoice.const cancelInvoiceRes = await Invoices// Disconnect from all services.await grpc
The grpc service will be in one of the following states at all times.
ready state is the initial state of all new lnd-grpc service instances and indicates that a connection has not yet been established.
locked state indicates that a connection has been established and the node was last known to be in a locked state.
active state indicates that a connection has been established and the node was last known to be in an active (unlocked) state.
locked event is emitted when it has been determined that the wallet is locked and the
WalletUnlocker interface is active.
active event is emitted when it has been determined that the wallet is unlocked and the
Lightning interface is active.
disconnected event is emitted after calling
disconnect, once the connection has been fully closed.
Checks wether the service is in a given state.
// test wether the service state is active.
Checks wether the service can carry out a given state transition.
// test wether the service can activate the lightning service
Wait for the service to enter a particular state.
await grpcconsole // active
Under the hood we use the
grpc-js library for the gRPC handling. By default we use the following options to control its behaviour.
keepCase: truelongs: Numberenums: Stringdefaults: trueoneofs: true
These settings can be overridden by passing
grpcOptions to the constructor. Custom settings will be merged in with the above defaults.
host: 'localhost:10009'grpcOptions:keepCase: false
gRPC Proto Files
This repository hosts a copy of the lnd gRPC proto files for all official lnd releases. We attempt to select the most appropriate version of these files when connecting by calling lnd's
getInfo method and parsing the version string.
In some situations you may want to load these files from an alternate location - such as in an Electron environment where you may need to bundle up the proto files as additional package resources for distribution. You can tell us to read the proto files from an alternate location by passing the
protoDir option to the constructor.
Run the tests suite:
Run with debugging output on:
DEBUG=lnrpc* npm test
Feel free to dive in! Open an issue or submit PRs.
lnd-grpc follows the Contributor Covenant Code of Conduct.
MIT © Tom Kirkpatrick