grpc-lnd

library2.0.3jsnpmunverified

A lightweight JavaScript/TypeScript library to instantiate a gRPC client for LND (Lightning Network Daemon) nodes. Version 2.0.3 is current; maintained with sporadic updates. Simplifies TLS/macaroon authentication and connection setup for LND's gRPC API. Differentiated by minimal dependencies and promise-based client generation, targeting Node.js environments.

payments

npm install grpc-lnd

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · GRPC-LND

grpc-lnd

paymentsjavascriptv2.0.3

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

default

✓ import LndGrpc from 'grpc-lnd'

✗ const LndGrpc = require('grpc-lnd')

Package exports a default class (ESM-only). CommonJS require is not supported natively—must use dynamic import or transpile.

LndGrpc

✓ import LndGrpc from 'grpc-lnd'

✗ import { LndGrpc } from 'grpc-lnd'

The class is the default export, not a named export. Named import will cause undefined.

connect

✓ const client = await lnd.connect()

✗ lnd.connect() // missing await

The connect method is async; common mistake is forgetting to await, resulting in a Promise.

Shows initialization of LndGrpc with credentials, async connection, and a simple wallet balance RPC call.

import LndGrpc from 'grpc-lnd'; const lnd = new LndGrpc({ host: 'localhost:10009', cert: process.env.LND_CERT ?? '', macaroon: process.env.LND_MACAROON ?? '' }); async function main() { const client = await lnd.connect(); const { walletBalance } = client; const balance = await walletBalance({}); console.log('Balance:', balance); lnd.close(); } main();

Debug

Known issues

breakingVersion 2.0.0 switched from callback-based to promise-based API. All client methods now return Promises.

fix

Use async/await or .then() on all RPC calls. Old callback patterns will hang.

affects: >=2.0.0

breakingIn version 2.0.0, the constructor options object changed: 'cert' replaces 'tls', 'macaroon' replaces 'macaroonPath'. Previous keys are ignored.

fix

Update options to use 'cert' and 'macaroon' keys.

affects: >=2.0.0

deprecatedThe 'host' option without port defaults to 10009. This default may change in future versions.

fix

Always specify host as 'host:port' explicitly.

affects: >=1.1.0

gotchaIf LND's TLS certificate or macaroon is invalid, the connect() call may hang indefinitely (no timeout).

fix

Wrap connect() in a promise with a timeout using Promise.race or use a custom gRPC deadline.

affects: >=2.0.0

gotchaThe close() method must be called after each connect() to release resources, especially in long-lived processes.

fix

Use try/finally or ensure lnd.close() in cleanup handlers.

affects: all

Errors

Common errors & fixes

Cannot find module 'grpc-lnd'

Package not installed or ESM-only import used in a CommonJS context without transformation.

fix

Install the package: npm install grpc-lnd. For CommonJS, use dynamic import: const LndGrpc = (await import('grpc-lnd')).default;

TypeError: lnd.connect is not a function

Using named import instead of default import: 'import { LndGrpc }' yields undefined.

fix

Use default import: import LndGrpc from 'grpc-lnd'.

Deadline Exceeded (deadline-exceeded) — gRPC call timeout

LND node unreachable or firewall blocking port, or missing await on connect.

fix

Verify LND is running and reachable. Ensure you await lnd.connect() before making calls.

Upgrade

Version history

2.0.3latest on npm

Audit

Dependencies

@grpc/grpc-jsrequiredCore gRPC implementation used for client creation

@grpc/proto-loaderrequiredLoads LND proto files for gRPC service definitions

google-protobufrequiredProtobuf runtime for message serialization

Agent activity

28 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/chm-diederichs/grpc-lnd ↗

packagegrpc-lnd ↗

homepagehttps://github.com/chm-diederichs/grpc-lnd#readme ↗