roasbeef/eclair

Eclair Lightning Network Skill

Eclair is a Scala implementation of the Lightning Network. This skill helps you run eclair in Docker for development and testing, primarily on regtest.

Prerequisites

• Docker and Docker Compose installed
• (Optional) Bitcoin Core if not using the bundled docker-compose

Quick Start

Start the full regtest stack (Bitcoin Core + Eclair):

cd ~/.claude/skills/eclair/templates
docker-compose up -d --build   # First time: builds eclair from source (~5-10 min)
docker-compose up -d           # Subsequent runs: uses cached image

This starts:

• bitcoind: Bitcoin Core 30 in regtest mode with ZMQ
• eclair: Eclair 0.14.0-SNAPSHOT (built from local source)

Notes:

• Eclair is built from source at /Users/roasbeef/codez/eclair because Docker Hub images have a "kill switch" for older versions
• Eclair 0.14+ requires Bitcoin Core 29+, so we use lightninglabs/bitcoin-core:30
• First build takes ~5-10 minutes to compile Scala code

Check status:

docker exec eclair eclair-cli -p devpassword getinfo

Docker Management

Build Image (from eclair source)

~/.claude/skills/eclair/scripts/docker-build.sh [--source /path/to/eclair]

Or pull pre-built image:

docker pull acinq/eclair:latest

Start Containers

Using docker-compose (recommended for regtest):

cd ~/.claude/skills/eclair/templates
docker-compose up -d

Using a custom image (e.g., from PR build):

cd ~/.claude/skills/eclair/templates
ECLAIR_IMAGE=eclair:pr-3144 docker-compose up -d

Single eclair container (requires external bitcoind):

~/.claude/skills/eclair/scripts/docker-start.sh --network regtest

Stop Containers

cd ~/.claude/skills/eclair/templates
docker-compose down

# To also remove volumes:
docker-compose down -v

View Logs

docker logs -f eclair
docker logs -f bitcoind

Execute Commands

docker exec eclair eclair-cli -p devpassword <command>
docker exec bitcoind bitcoin-cli -regtest <command>

Essential API Operations

All commands use the eclair REST API. Default password in regtest: devpassword

Node Information

# Get node info (nodeId, alias, blockHeight, etc.)
docker exec eclair eclair-cli -p devpassword getinfo

# List connected peers
docker exec eclair eclair-cli -p devpassword peers

Connect to Peers

# Connect by URI
docker exec eclair eclair-cli -p devpassword connect --uri=<nodeId>@<host>:<port>

# Connect by nodeId (requires DNS or known address)
docker exec eclair eclair-cli -p devpassword connect --nodeId=<nodeId>

# Disconnect
docker exec eclair eclair-cli -p devpassword disconnect --nodeId=<nodeId>

Channel Management

# Open channel (amount in satoshis)
docker exec eclair eclair-cli -p devpassword open \
  --nodeId=<pubkey> \
  --fundingSatoshis=1000000

# List all channels
docker exec eclair eclair-cli -p devpassword channels

# List channels (short format)
docker exec eclair eclair-cli -p devpassword -s channels

# Get specific channel
docker exec eclair eclair-cli -p devpassword channel --channelId=<id>

# Get channel balances
docker exec eclair eclair-cli -p devpassword channelbalances

# Close channel gracefully
docker exec eclair eclair-cli -p devpassword close --channelId=<id>

# Force close channel
docker exec eclair eclair-cli -p devpassword forceclose --channelId=<id>

Payments

# Create invoice (amount in millisatoshis)
docker exec eclair eclair-cli -p devpassword createinvoice \
  --description="test payment" \
  --amountMsat=100000000

# Parse invoice to see details
docker exec eclair eclair-cli -p devpassword parseinvoice --invoice=<bolt11>

# Pay invoice
docker exec eclair eclair-cli -p devpassword payinvoice --invoice=<bolt11>

# Check sent payment status
docker exec eclair eclair-cli -p devpassword getsentinfo --paymentHash=<hash>

# Check received payment status
docker exec eclair eclair-cli -p devpassword getreceivedinfo --paymentHash=<hash>

On-Chain Wallet

# Get new address
docker exec eclair eclair-cli -p devpassword getnewaddress

# Get on-chain balance
docker exec eclair eclair-cli -p devpassword onchainbalance

# Get global balance (on-chain + channels)
docker exec eclair eclair-cli -p devpassword globalbalance

# Send on-chain
docker exec eclair eclair-cli -p devpassword sendonchain \
  --address=<btc_address> \
  --amountSatoshis=50000 \
  --confirmationTarget=6

Usable Balances

# Check how much you can send across all channels
docker exec eclair eclair-cli -p devpassword usablebalances

Regtest Development Workflow

1. Start the Stack

cd ~/.claude/skills/eclair/templates
docker-compose up -d

2. Fund the Eclair Wallet

# Generate blocks to have spendable coins
docker exec bitcoind bitcoin-cli -regtest -rpcuser=bitcoin -rpcpassword=bitcoin generatetoaddress 101 $(docker exec bitcoind bitcoin-cli -regtest -rpcuser=bitcoin -rpcpassword=bitcoin getnewaddress)

# Get eclair address
ECLAIR_ADDR=$(docker exec eclair eclair-cli -p devpassword getnewaddress)

# Send funds to eclair
docker exec bitcoind bitcoin-cli -regtest -rpcuser=bitcoin -rpcpassword=bitcoin sendtoaddress $ECLAIR_ADDR 10

# Mine a block to confirm
docker exec bitcoind bitcoin-cli -regtest -rpcuser=bitcoin -rpcpassword=bitcoin generatetoaddress 1 $(docker exec bitcoind bitcoin-cli -regtest -rpcuser=bitcoin -rpcpassword=bitcoin getnewaddress)

# Verify eclair balance
docker exec eclair eclair-cli -p devpassword onchainbalance

3. Open a Channel (with second node)

To test channels, you'll need a second Lightning node. You can start another eclair instance or use a different implementation.

# Connect to peer
docker exec eclair eclair-cli -p devpassword connect --uri=<nodeId>@<host>:9735

# Open 1M sat channel
docker exec eclair eclair-cli -p devpassword open --nodeId=<nodeId> --fundingSatoshis=1000000

# Mine blocks to confirm channel
docker exec bitcoind bitcoin-cli -regtest -rpcuser=bitcoin -rpcpassword=bitcoin generatetoaddress 6 $(docker exec bitcoind bitcoin-cli -regtest -rpcuser=bitcoin -rpcpassword=bitcoin getnewaddress)

# Check channel status
docker exec eclair eclair-cli -p devpassword -s channels

4. Send a Payment

# On receiving node: create invoice
INVOICE=$(docker exec eclair2 eclair-cli -p devpassword createinvoice --amountMsat=50000000 --description="test" | jq -r .serialized)

# On sending node: pay invoice
docker exec eclair eclair-cli -p devpassword payinvoice --invoice=$INVOICE

Using the Helper Scripts

docker-build.sh

Build eclair Docker image from source (useful for ARM64/Apple Silicon):

~/.claude/skills/eclair/scripts/docker-build.sh --source /path/to/eclair

Build from a specific branch, commit, or GitHub PR (for interop testing):

# Build from a specific branch
~/.claude/skills/eclair/scripts/docker-build.sh --branch taproot-feature-bit

# Build from a GitHub PR (requires gh CLI)
~/.claude/skills/eclair/scripts/docker-build.sh --pr 3144

# Build from a specific commit
~/.claude/skills/eclair/scripts/docker-build.sh --commit ea9c4ca8dc1403bca6c6dcbe9bc4f3bd81d76513

# Combine with custom tag
~/.claude/skills/eclair/scripts/docker-build.sh --pr 3144 --tag eclair:taproot

build-pr.sh

Quick convenience wrapper for building from a GitHub PR:

~/.claude/skills/eclair/scripts/build-pr.sh 3144   # Builds and tags as eclair:pr-3144

docker-start.sh

Start eclair with custom configuration:

~/.claude/skills/eclair/scripts/docker-start.sh \
  --network regtest \
  --api-password mypassword \
  --data-dir /tmp/eclair-data

docker-stop.sh

Stop and optionally clean up:

~/.claude/skills/eclair/scripts/docker-stop.sh
~/.claude/skills/eclair/scripts/docker-stop.sh --clean  # Also removes volumes

eclair-cli.sh

Convenient wrapper for eclair API:

~/.claude/skills/eclair/scripts/eclair-cli.sh getinfo
~/.claude/skills/eclair/scripts/eclair-cli.sh channels
~/.claude/skills/eclair/scripts/eclair-cli.sh createinvoice --amountMsat=100000000 --description="test"

regtest-setup.sh

Initialize regtest environment with funded wallet:

~/.claude/skills/eclair/scripts/regtest-setup.sh

mine.sh

Mine blocks in regtest:

~/.claude/skills/eclair/scripts/mine.sh        # Mine 1 block
~/.claude/skills/eclair/scripts/mine.sh 6      # Mine 6 blocks (confirm channel)
~/.claude/skills/eclair/scripts/mine.sh 100    # Mine 100 blocks (coinbase maturity)

bitcoin-cli.sh

Wrapper for Bitcoin Core commands:

~/.claude/skills/eclair/scripts/bitcoin-cli.sh getblockchaininfo
~/.claude/skills/eclair/scripts/bitcoin-cli.sh getbalance
~/.claude/skills/eclair/scripts/bitcoin-cli.sh sendtoaddress <address> <amount>

Bitcoin Core Control

The bitcoind container is fully accessible for controlling the regtest blockchain.

Mining Blocks

# Using the helper script
~/.claude/skills/eclair/scripts/mine.sh 6

# Or directly
docker exec bitcoind bitcoin-cli -regtest -rpcuser=bitcoin -rpcpassword=bitcoin \
  generatetoaddress 6 $(docker exec bitcoind bitcoin-cli -regtest -rpcuser=bitcoin -rpcpassword=bitcoin getnewaddress)

Blockchain Info

~/.claude/skills/eclair/scripts/bitcoin-cli.sh getblockchaininfo
~/.claude/skills/eclair/scripts/bitcoin-cli.sh getmempoolinfo
~/.claude/skills/eclair/scripts/bitcoin-cli.sh getblockcount

Wallet Operations

# Get balance
~/.claude/skills/eclair/scripts/bitcoin-cli.sh getbalance

# Generate address
~/.claude/skills/eclair/scripts/bitcoin-cli.sh getnewaddress

# Send funds
~/.claude/skills/eclair/scripts/bitcoin-cli.sh sendtoaddress <address> 1.0

Connecting Other Lightning Nodes (lnd, c-lightning)

The bitcoind container exposes all ports to the host, allowing other Lightning implementations to connect:

| Port | Protocol | Usage | |------|----------|-------| | 18443 | RPC | Bitcoin Core RPC (regtest) | | 18444 | P2P | Bitcoin Core P2P (regtest) | | 28332 | ZMQ | Block notifications | | 28333 | ZMQ | Transaction notifications |

Example lnd configuration to connect to the shared bitcoind:

[Bitcoin]
bitcoin.active=1
bitcoin.regtest=1
bitcoin.node=bitcoind

[Bitcoind]
bitcoind.rpchost=localhost:18443
bitcoind.rpcuser=bitcoin
bitcoind.rpcpass=bitcoin
bitcoind.zmqpubrawblock=tcp://localhost:28332
bitcoind.zmqpubrawtx=tcp://localhost:28333

Example c-lightning/CLN configuration:

network=regtest
bitcoin-rpcconnect=localhost
bitcoin-rpcport=18443
bitcoin-rpcuser=bitcoin
bitcoin-rpcpassword=bitcoin

Configuration

Key configuration options (set via environment variables or eclair.conf):

| Option | Description | Default | |--------|-------------|---------| | eclair.chain | Network: mainnet, testnet, signet, regtest | regtest | | eclair.api.enabled | Enable REST API | true | | eclair.api.password | API authentication password | (required) | | eclair.api.port | API port | 8080 | | eclair.node-alias | Node name visible on network | eclair | | eclair.bitcoind.host | Bitcoin Core host | bitcoind | | eclair.bitcoind.rpcuser | Bitcoin Core RPC user | bitcoin | | eclair.bitcoind.rpcpassword | Bitcoin Core RPC password | bitcoin |

See templates/eclair.conf.template for full configuration.

Ports

| Port | Service | Description | |------|---------|-------------| | 9735 | Lightning | Peer-to-peer Lightning protocol | | 8080 | API | REST API and WebSocket | | 18443 | Bitcoin RPC | Bitcoin Core RPC (regtest) | | 28332 | Bitcoin ZMQ | Bitcoin Core ZMQ notifications |

Troubleshooting

"Connection refused" to API

• Ensure eclair container is running: docker ps
• Check logs: docker logs eclair
• Verify API is enabled in config

"Unauthorized" API response

• Check password matches eclair.api.password in config
• Default regtest password: devpassword

Channel stuck in "WAIT_FOR_FUNDING_CONFIRMED"

• Mine more blocks: docker exec bitcoind bitcoin-cli -regtest -rpcuser=bitcoin -rpcpassword=bitcoin generatetoaddress 6 $(docker exec bitcoind bitcoin-cli -regtest -rpcuser=bitcoin -rpcpassword=bitcoin getnewaddress)

"Insufficient funds"

• Check on-chain balance: eclair-cli onchainbalance
• Fund wallet from bitcoind (see regtest workflow above)

Bitcoin Core connection failed

• Verify bitcoind is running: docker ps
• Check ZMQ is enabled and ports match
• Verify RPC credentials match between bitcoind and eclair config

Building on Apple Silicon (ARM64)

Use the docker-build.sh script which handles ARM64 builds:

~/.claude/skills/eclair/scripts/docker-build.sh --source /path/to/eclair

Interop Testing with Custom Branches/PRs

For testing in-development features across Lightning implementations:

Testing a GitHub PR

# Build and tag from PR #3144 (taproot feature bit)
~/.claude/skills/eclair/scripts/build-pr.sh 3144

# Or manually with docker-build.sh
~/.claude/skills/eclair/scripts/docker-build.sh --pr 3144 --tag eclair:taproot

# Start the stack with the PR image
cd ~/.claude/skills/eclair/templates
ECLAIR_IMAGE=eclair:pr-3144 docker-compose up -d --build

Testing a Feature Branch

# Build from taproot-feature-bit branch
~/.claude/skills/eclair/scripts/docker-build.sh --branch taproot-feature-bit --tag eclair:taproot

# Start the stack
cd ~/.claude/skills/eclair/templates
ECLAIR_IMAGE=eclair:taproot docker-compose up -d

Environment Variables for docker-compose

| Variable | Description | Default | |----------|-------------|---------| | ECLAIR_SOURCE | Path to eclair source directory | /Users/roasbeef/codez/eclair | | ECLAIR_IMAGE | Docker image tag to use | eclair:local |

Further Reading

• API Reference - Complete API endpoint documentation
• Eclair GitHub - Official repository
• BOLT Specifications - Lightning Network protocol specs