Crate spawn_lnd

Expand description

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 Docker resource 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.
ManagedNetwork: Metadata for a Docker network managed by this crate.
NetworkSpec: Docker network creation parameters used by DockerClient.
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_CLUSTER_SUBNET: Environment variable overriding the Docker network IPv4 subnet.
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.
managed_network_labels: Build the Docker labels applied to every managed network.
managed_network_name: Build the Docker network name for a cluster.

Crate spawn_lnd

Crate spawn_lnd Copy item path

§Example

Structs§

Enums§

Constants§

Functions§

Crate spawn_lnd