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 also supports Taproot Assets RPC APIs (from Taproot Assets v0.6.1):

• TaprootAssets (core Taproot Assets API)
• AssetWallet (asset wallet management)
• Mint (asset minting)
• PriceOracle (price oracle service)
• RFQ (request for quote)
• TapChannel (Taproot Asset channels)
• TapDev (development tools)
• Universe (universe server)

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:

LND Features:

• lightningrpc (core Lightning API)
• walletrpc (WalletKit, depends on signrpc)
• signrpc (Signer)
• peersrpc (Peers)
• routerrpc (Router)
• invoicesrpc (Invoices)
• staterpc (State)
• versionrpc (Versioner)
• lightning (enables all LND RPCs)

Taproot Assets Features:

• taprpc (core Taproot Assets API)
• assetwalletrpc (asset wallet management)
• mintrpc (asset minting)
• priceoraclerpc (price oracle service)
• rfqrpc (request for quote)
• tapchannelrpc (Taproot Asset channels)
• tapdevrpc (development tools)
• universerpc (universe server)
• taprootassets (enables all Taproot Assets RPCs)

Meta Features:

• all (enables all LND and Taproot Assets RPCs)

TLS Configuration:

• 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"] }

To use Taproot Assets features:

voltage-tonic-lnd = { version = "0.1", default-features = false, features = ["lightningrpc", "taprootassets", "ring", "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. For Taproot Assets proto files, set the TAPROOT_ASSETS_REPO_DIR environment variable to a directory with a cloned taproot-assets repo.

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