Crate spawn_lnd 

Docker-backed LND and Bitcoin Core regtest clusters for Rust integration tests.

The crate is library-first: integration tests should use the public API from here, while binaries and examples stay thin wrappers over the library.

Example

use spawn_lnd::SpawnLnd;

let mut cluster = SpawnLnd::builder()
    .nodes(["alice", "bob"])
    .spawn()
    .await?;

cluster.fund_nodes(["alice", "bob"]).await?;
let channel = cluster.open_channel("alice", "bob").await?;
let mut clients = cluster.connect_nodes().await?;

let alice_info = clients
    .get_mut("alice")
    .expect("alice client")
    .lightning()
    .get_info(lnd_grpc_rust::lnrpc::GetInfoRequest {})
    .await?
    .into_inner();

assert!(alice_info.synced_to_chain);
assert!(channel.from_channel.active);

cluster.shutdown().await?;

Structs

BitcoinCore

A running Bitcoin Core container and its RPC handles.

BitcoinCoreConfig

Configuration for one spawned Bitcoin Core regtest backend.

BitcoinRpcAuth

RPC credentials for Bitcoin Core.

BitcoinRpcClient

Minimal async JSON-RPC client for Bitcoin Core regtest nodes.

BlockInfo

Subset of Bitcoin Core getblock response used by this crate.

BlockchainInfo

Subset of Bitcoin Core getblockchaininfo used by this crate.

ChannelReport

Result of opening and confirming a public Lightning channel.

CleanupFailure

Failure for one container cleanup operation.

CleanupReport

Summary of a cleanup operation.

ContainerSpec

Docker container creation parameters used by DockerClient.

CreateWallet

Response from Bitcoin Core createwallet.

DockerClient

Thin async wrapper around a Bollard Docker client.

FundingReport

Result of funding an LND wallet.

LndConfig

Configuration for one spawned LND node.

LndDaemon

A running LND container and authenticated connection material.

LoadWallet

Response from Bitcoin Core loadwallet.

NodeConfig

Per-node LND configuration.

PeerConnection

Result of connecting one LND node to another.

RetryPolicy

Retry parameters for startup and readiness polling.

SpawnLnd

Entry point for building and spawning a cluster.

SpawnLndBuilder

Builder for SpawnLndConfig.

SpawnLndConfig

Complete cluster configuration.

SpawnedCluster

A running regtest cluster containing Bitcoin Core and LND containers.

SpawnedContainer

Metadata for a container created by this crate.

SpawnedNode

A spawned LND node and its placement in the cluster.

StartupRollback

Tracks containers that should be removed if startup fails.

Enums

BitcoinCoreError

Error returned while spawning or preparing Bitcoin Core.

BitcoinRpcError

Error returned by the Bitcoin Core JSON-RPC client.

ConfigError

Configuration validation error.

ContainerRole

Role label for a managed container.

DockerError

Error returned by Docker operations.

ImageStatus

Result of ensuring an image is available locally.

LndError

Error returned by LND lifecycle and RPC helpers.

SpawnError

Error returned by cluster lifecycle and orchestration operations.

Constants

BITCOIND_P2P_PORT

Regtest P2P port exposed by Bitcoin Core inside the Docker container.

BITCOIND_RPC_PORT

Regtest RPC port exposed by Bitcoin Core inside the Docker container.

DEFAULT_BITCOIND_IMAGE

Default Bitcoin Core Docker image used for new clusters.

DEFAULT_BITCOIN_RPC_USER

Default RPC user configured for spawned Bitcoin Core nodes.

DEFAULT_BITCOIN_WALLET_MATURITY_BLOCKS

Number of blocks mined to mature the default wallet’s coinbase outputs.

DEFAULT_BITCOIN_WALLET_NAME

Default wallet name used for mining and funding operations.

DEFAULT_CHANNEL_CAPACITY_SAT

Default public channel capacity opened by SpawnedCluster::open_channel.

DEFAULT_CHANNEL_CONFIRMATION_BLOCKS

Default number of blocks mined after opening a channel.

DEFAULT_FUNDING_AMOUNT_BTC

Default on-chain funding amount sent to each LND node.

DEFAULT_FUNDING_CONFIRMATION_BLOCKS

Default number of blocks mined after funding transactions.

DEFAULT_GENERATE_ADDRESS

Static regtest address used for internal block generation.

DEFAULT_LND_IMAGE

Default LND Docker image used for new clusters.

DEFAULT_NODES_PER_BITCOIND

Default number of LND nodes assigned to each Bitcoin Core regtest backend.

DEFAULT_NODE_ALIAS

Default node alias used when a builder is spawned without explicit nodes.

DEFAULT_STARTUP_RETRY_ATTEMPTS

Default retry count for Docker and daemon readiness polling.

DEFAULT_STARTUP_RETRY_INTERVAL_MS

Default delay between readiness retry attempts.

ENV_BITCOIND_IMAGE

Environment variable overriding the Bitcoin Core image.

ENV_KEEP_CONTAINERS

Environment variable preserving containers after failure or shutdown.

ENV_LND_IMAGE

Environment variable overriding the LND image.

ENV_NODES_PER_BITCOIND

Environment variable overriding the number of LND nodes per Bitcoin Core.

ENV_STARTUP_RETRY_ATTEMPTS

Environment variable overriding readiness retry attempts.

ENV_STARTUP_RETRY_INTERVAL_MS

Environment variable overriding readiness retry interval milliseconds.

LABEL_CLUSTER

Docker label key storing the generated cluster id.

LABEL_MANAGED

Docker label key marking containers managed by this crate.

LABEL_MANAGED_VALUE

Docker label value used with LABEL_MANAGED.

LABEL_NODE

Docker label key storing an LND node alias when applicable.

LABEL_ROLE

Docker label key storing the managed container role.

LND_ADMIN_MACAROON_PATH

Path to the admin macaroon inside the LND container.

LND_GRPC_PORT

LND gRPC port exposed inside the Docker container.

LND_P2P_PORT

LND P2P port exposed inside the Docker container.

LND_TLS_CERT_PATH

Path to the TLS certificate inside the LND container.

LND_WALLET_PASSWORD

Fixed wallet password used for spawned regtest LND nodes.

VERSION

Current crate version as declared by Cargo.

Functions

bitcoin_core_auth_hmac

Compute Bitcoin Core’s HMAC-SHA256 rpcauth digest.

bitcoin_core_rpcauth

Build the value for Bitcoin Core’s -rpcauth flag.

cluster_label_filters

Build Docker list filters that match containers for a specific cluster.

managed_container_labels

Build the Docker labels applied to every managed container.

managed_label_filters

Build Docker list filters that match all containers managed by this crate.