Skip to content

getting-started.md

Latest commit

 

History

History
163 lines (112 loc) · 3.97 KB

getting-started.md

File metadata and controls

163 lines (112 loc) · 3.97 KB
Raw

Getting Started

This guide walks you through building, configuring, and running your first LDK Server node.

Prerequisites

  • Rust 1.85.0 or later
  • A Bitcoin chain backend (one of):

Build

git clone https://github.com/lightningdevkit/ldk-server.git
cd ldk-server
cargo build --release

The binaries are placed in target/release/:

  • ldk-server (the node daemon)
  • ldk-server-cli (the command-line client)

Build Features

experimental-lsps2-support — Enables the LSPS2 liquidity service provider. Experimental — for testing only. Requires [liquidity.lsps2_service] in config.

cargo build --release --features experimental-lsps2-support

Configure

Copy the annotated config template and edit it:

cp contrib/ldk-server-config.toml my-config.toml

The only required decision is which Bitcoin backend to use. Keep exactly one of the [bitcoind], [electrum], or [esplora] sections and remove the others.

Minimal regtest example (using Bitcoin Core):

[node]
network = "regtest"

[bitcoind]
rpc_address = "127.0.0.1:18443"
rpc_user = "user"
rpc_password = "pass"

Everything else has sensible defaults. See Configuration for the full reference.

Start the Server

./target/release/ldk-server my-config.toml

On first startup, watch the logs for:

gRPC service listening on 127.0.0.1:3536
NODE_URI: <node_id>@<address>

The server creates these files on first run:

File Location Purpose
Admin macaroon <storage_dir>/<network>/macaroons/admin.macaroon Full API access
TLS certificate <storage_dir>/tls.crt Secure client connections

The default storage directory is ~/.ldk-server/ on Linux and ~/Library/Application Support/ldk-server/ on macOS.

Client Macaroons

The CLI reads admin.macaroon automatically. This file contains a hex token. Keep it private, and never give clients files from macaroons/roots/.

Create a restricted token for each application:

ldk-server-cli create-macaroon my-app --preset readonly
ldk-server-cli create-macaroon invoice-app --preset invoice

First Commands

If the CLI and server share the same machine and use the default storage directory, the CLI auto-discovers the macaroon and TLS certificate, so no flags are needed:

# Check the node is running
ldk-server-cli get-node-info

# Generate an on-chain funding address
ldk-server-cli onchain-receive

# Check balances
ldk-server-cli get-balances

When running on a different machine or using a non-default storage path, pass the connection details explicitly:

ldk-server-cli \
  --base-url localhost:3536 \
  --macaroon <hex_macaroon> \
  --tls-cert /path/to/tls.crt \
  get-node-info

CLI Tips

Amount Syntax

Commands that accept amounts support sat and msat suffixes:

ldk-server-cli bolt11-receive --amount 50000sat
ldk-server-cli bolt11-receive --amount 50000000msat  # same as above

Shell Completions

Generate completions for your shell:

# Bash (add to ~/.bashrc)
eval "$(ldk-server-cli completions bash)"

# Zsh (add to ~/.zshrc)
eval "$(ldk-server-cli completions zsh)"

# Fish (add to ~/.config/fish/config.fish)
ldk-server-cli completions fish | source

PowerShell and Elvish are also supported. Run ldk-server-cli completions --help for details.

Per-Command Help

Every command supports --help for detailed argument descriptions:

ldk-server-cli open-channel --help

Next Steps

  • Configuration: all config options, environment variables, and Bitcoin backend tradeoffs
  • API Guide: gRPC transport, authentication, and endpoint reference
  • Operations: production deployment, backups, and monitoring