lnd_grpc_rust 2.15.0

# LND gRPC Client in Rust.

Rust 🦀 implementation of LND RPC client using async gRPC library `tonic_openssl`.

## About

This crate implements LND GRPC using [`tonic_openssl`](https://docs.rs/tonic-openssl/latest/tonic_openssl/) and [`prost`](https://docs.rs/prost/).
Apart from being up-to-date at the time of writing (:D) it also allows `async` usage.
It contains vendored `*.proto` files so LND source code is not *required*
but accepts an environment variable `LND_REPO_DIR` which overrides the vendored `*.proto` files.
This can be used to test new features in non-released `lnd`.

## Adding to your Rust 🦀 project
```
cargo add lnd_grpc_rust
```

This crate uses OpenSSL through `tonic_openssl`. By default it links against a
system OpenSSL installation. On Windows, or in CI environments where OpenSSL is
not installed or not discoverable, enable the vendored OpenSSL feature so Cargo
builds OpenSSL from source:

```
cargo add lnd_grpc_rust --features vendored-openssl
```

Or add it manually:

```toml
lnd_grpc_rust = { version = "2.14", features = ["vendored-openssl"] }
```

The vendored feature makes setup more portable, but it increases build time.

## Usage

There's no setup needed beyond adding the crate to your `Cargo.toml`.
If you need to change the `*.proto` files from which the client is generated, set the environment variable `LND_REPO_DIR` to a directory with cloned [`lnd`](https://github.com/lightningnetwork/lnd.git) during build.

Here's an example of retrieving information from LND (`[getinfo](https://api.lightning.community/#getinfo)` call).
You can find the same example in crate root for your convenience.

Connect function takes cert and macaroon in hex format.

```rust
use std::fs;

#[tokio::main]
async fn main() {
        // Read the contents of the file into a vector of bytes
        let cert_bytes = fs::read("/path/to/tls.cert").expect("FailedToReadTlsCertFile");
        let mac_bytes = fs::read("path/to/macaroon").expect("FailedToReadMacaroonFile");

       // Convert the bytes to a hex string
        let cert = buffer_as_hex(cert_bytes);
        let macaroon = buffer_as_hex(mac_bytes);
        let socket = "localhost:10001".to_string();

        let mut client = lnd_grpc_rust::connect(cert, macaroon, socket)
        .await
        .expect("failed to connect");

    let info = client
        .lightning()
        // All calls require at least empty parameter
        .get_info(lnd_grpc_rust::lnrpc::GetInfoRequest {})
        .await
        .expect("failed to get info");

    // We only print it here, note that in real-life code
    // you may want to call `.into_inner()`
    // on the response to get the message.
    println!("{:#?}", info);
}

fn buffer_as_hex(bytes: Vec<u8>) -> String {
    let hex_str = bytes.iter().map(|b| format!("{:02x}", b)).collect::<String>();

    return hex_str;
}
```

### Connecting to multiple nodes

Use `connect_nodes` when you want to manage several LND connections at once.
Each node gets an alias, and the returned registry can look clients up by that
alias.

```rust
let nodes = vec![
    lnd_grpc_rust::LndNodeConfig::new(
        "alice",
        alice_cert,
        alice_macaroon,
        "localhost:10001",
    ),
    lnd_grpc_rust::LndNodeConfig::new(
        "bob",
        bob_cert,
        bob_macaroon,
        "localhost:10002",
    ),
];

let mut clients = lnd_grpc_rust::connect_nodes(nodes)
    .await
    .expect("failed to connect nodes");

let alice_info = clients
    .get_mut("alice")
    .expect("missing alice node")
    .lightning()
    .get_info(lnd_grpc_rust::lnrpc::GetInfoRequest {})
    .await
    .expect("failed to get alice info");

println!("{:#?}", alice_info);
```

## License

MIT