GRPC

Use gRPC for generated clients, typed request and response messages, and streaming calls to the LND node behind a Node-backed deployment.

Collect the node host, the current gRPC endpoint and port, compatible LND proto files, a least-privilege macaroon, and the TLS credentials required by the client.

Use ConfigurationConfiguration for the complete connection checklist. Verify connection material against the current node instead of copying a port, certificate override, or dashboard path from historical documentation.

Generate client code from LND proto files that are compatible with the node version and the services your application uses.

Pin the proto source and generation toolchain in the application build. Regenerate and retest clients deliberately when the node or LND dependency changes.

Do not assume that an example generated from a different LND version exposes the same fields, methods, or service definitions.

Encode the macaroon as a hex string and attach it to each call as macaroon metadata.

Keep read-only monitoring credentials separate from credentials that can create invoices, send funds, change channels, or administer the node. Do not log metadata or complete errors that can expose credentials.

Use TLS credentials that validate the endpoint presented by the current node. Keep certificate material in protected runtime configuration and fail closed when validation does not succeed.

Older client guidance may mention language-specific cipher-suite or certificate workarounds. Treat those instructions as version- and environment-specific until they are verified against the current client, LND version, and endpoint.

Do not disable TLS verification in production.

Begin with a read-only node-information request.

Verify the node identity and Bitcoin network in the response. Confirm that missing macaroon, invalid macaroon, TLS, timeout, and unavailable-service failures are handled without exposing secrets.

Only enable payment, channel, or wallet write calls after the read-only connection is stable.

Use explicit deadlines and cancellation for unary calls. For streams, implement reconnect with bounded backoff, detect gaps or duplicate events, and reconcile state with an independent read after reconnect.

Track connection state, stream age, reconnect count, authentication failures, TLS failures, and the age of the last successfully processed event.