Tonic LND client

Rust implementation of LND RPC client using async gRPC library tonic.

About

Warning: this crate is in early development and may have unknown problems! Review it before using with mainnet funds!

This crate supports the following LND RPC APIs (from LND v0.19.1-beta):

• Lightning
• WalletKit
• Signer
• Peer
• Router
• Invoices
• State
• Versioner

This crate implements LND gRPC using tonic and prost, providing async usage and vendored *.proto files (LND source not required by default). You can override the proto files at build time by setting the LND_REPO_DIR environment variable, to test against unreleased LND features.

Features & Cargo Flags

Each RPC API is behind a Cargo feature flag. All features are enabled by default, but you can select a subset for slimmer builds. See the [features] section in Cargo.toml for details. Example features:

• lightningrpc (core Lightning API)
• walletrpc (WalletKit, depends on signrpc)
• signrpc (Signer)
• peersrpc (Peers)
• routerrpc (Router)
• invoicesrpc (Invoices)
• staterpc (State)
• versionrpc (Versioner)
• all (enables all RPCs)
• TLS backend selection: ring, aws-lc,
• TLS root CA selection: tls-native-roots, tls-webpki-roots, tls

At least one TLS backend is required. ring is currently used as the default.

See Cargo.toml for the full list and combinations.

Usage

Since most of the LND RPCs supported by this crate can be used in isolation, and your project likely only needs a subset of these RPCs, we expose each RPC under Cargo feature gates. See the Cargo manifest for the latest supported features

All features are included by default, but you can explicitly select the features you want for a slimmer dependency and faster compilations.

Usage

Add the crate to your Cargo.toml:

voltage-tonic-lnd = "0.1"

By default, all features are enabled. To customize, specify features:

voltage-tonic-lnd = { version = "0.1", default-features = false, features = ["lightningrpc", "routerrpc", "aws-lc", "tls-native-roots"] }

If you need to override the proto files, set the LND_REPO_DIR environment variable to a directory with a cloned lnd repo during build.

Example: Connect and Get Info

You can use the builder API for flexible connection:

#[tokio::main]
async fn main() -> voltage_tonic_lnd::Result<()> {
    let client = voltage_tonic_lnd::Client::builder()
        .address("https://localhost:10009")
        .macaroon_path("/path/to/admin.macaroon")
        .cert_path("/path/to/tls.cert")
        .build()
        .await?;

    let info = client.lightning().get_info(voltage_tonic_lnd::lnrpc::GetInfoRequest {}).await?;
    println!("{:#?}", info);
    Ok(())
}

See more examples in the repo for advanced usage (router, invoices, payments, intercept HTLCs, etc).

Alternative: In-Memory Credentials

let client = voltage_tonic_lnd::Client::builder()
    .address("https://localhost:10009")
    .macaroon_contents(hex_macaroon_string)
    .cert_contents(pem_cert_string)
    .build()
    .await?;

Minimum Supported Rust Version (MSRV)

1.75.0

License

MITNFA