Chantools

What Is Chantools?

Chantools is an open-source command-line utility created by Oliver Gugger (guggero), a Lightning Labs developer. It provides a collection of tools for diagnosing, repairing, and recovering Lightning Network channels, primarily for LND (Lightning Network Daemon) users.

The name comes from "channel tools" and it has become the go-to recovery toolkit for Lightning node operators. When you see people on X (Twitter) sharing how they recovered stuck funds or rescued a corrupted node, chantools is often the solution they used.

Chantools is available on GitHub and can be installed on Linux, macOS, and Windows. It operates independently of a running LND instance, meaning you can use it even when your node is completely broken or offline.

Why Chantools Exists

Lightning Network channels are stateful. Unlike on-chain bitcoin where your seed phrase alone can recover all funds, Lightning channels require tracking the current channel state: who holds how much, pending HTLCs, and commitment transactions. If this state gets corrupted or lost, you can lose access to funds.

Several scenarios can leave users with inaccessible funds:

• Database corruption: Power failures, disk errors, or software bugs can corrupt the LND database (channel.db), making channels unreadable.
• Unresponsive channel partners: If your channel peer goes offline permanently or refuses to cooperate, you cannot close the channel cooperatively.
• Lost channel state: Restoring from an old backup or running two nodes with the same seed can create state conflicts that brick channels.
• Stuck pending channels: Channels can get stuck in a pending state if funding transactions do not confirm or if there are edge cases in channel opening.
• Upgrade failures: LND version upgrades occasionally fail mid-migration, leaving the database in an inconsistent state.

LND itself cannot always recover from these situations. Chantools fills the gap by providing low-level access to channel data and the ability to craft recovery transactions manually.

Core Capabilities

Channel Recovery

The primary use case is recovering funds from channels that cannot be closed normally. Chantools can extract channel information from backups, reconstruct commitment transactions, and broadcast force-close transactions to recover your balance.

Database Repair

Several commands help repair or extract data from corrupted LND databases. You can dump channel information, compact databases, and migrate data between different formats.

Key Derivation

Chantools can derive all keys associated with your LND wallet from just the seed phrase. This includes channel keys, on-chain keys, and the various derivation paths LND uses. This is essential for recovery when you have lost everything except your seed.

Zombie Channel Handling

"Zombie" channels are channels where the peer has been offline so long they have been forgotten by the network. Chantools provides specific commands to handle these scenarios, including force-closing channels to peers that no longer exist in the public graph.

SCB (Static Channel Backup) Operations

Chantools can work with LND's Static Channel Backup files. It can decode SCB files, trigger the DLP (Data Loss Protection) recovery protocol, and use SCB data to initiate force-closes when your database is gone but you have the backup file.

Common Recovery Scenarios

Scenario 1: Corrupted Database with SCB Available

Your LND database is corrupted but you have a recent SCB file. Using chantools, you can trigger the Data Loss Protection protocol which asks your channel peers to force-close channels and return your funds. The chantools triggerforceclose command initiates this process.

Scenario 2: No Database, No SCB, Only Seed

The most difficult recovery scenario. With only your seed phrase, chantools can scan the blockchain for channels that belong to your keys using chantools genimportscript to generate addresses and chantools rescueclosed to find and sweep funds from channels that have already been force-closed by the other party.

Scenario 3: Peer Offline Forever

Your channel partner has disappeared. Their node has been offline for months and shows no signs of returning. You need to force-close to recover your funds. Chantools forceclose command can broadcast your latest commitment transaction even without the peer's cooperation.

Scenario 4: Stuck Pending Channel

A channel is stuck in "pending open" state because the funding transaction has issues. The chantools rescuefunding command can help recover funds from channels that never fully opened, including situations where you need to double-spend the funding output.

How to Use Chantools

Chantools is a command-line tool with many subcommands. Here are the most commonly used operations:

Installation

# Download from GitHub releases
# https://github.com/lightninglabs/chantools/releases

# Or build from source
git clone https://github.com/lightninglabs/chantools
cd chantools
make install

Basic Recovery Commands

# Show all available commands
chantools --help

# Derive keys from seed to verify wallet
chantools showrootkey

# Trigger force-close using SCB file
chantools triggerforceclose \
  --channeldb /path/to/channel.backup \
  --publish

# Rescue funds from already closed channels
chantools rescueclosed \
  --channeldb /path/to/channel.db \
  --publish

# Sweep time-locked outputs after force-close
chantools sweeptimelock \
  --channeldb /path/to/channel.db \
  --publish

Database Operations

# Dump channel information from database
chantools dumpchannels \
  --channeldb /path/to/channel.db

# Compact a bloated database
chantools compactdb \
  --sourcedb /path/to/channel.db \
  --destdb /path/to/channel-compacted.db

# Delete specific payment data
chantools deletepayments \
  --channeldb /path/to/channel.db

Seed and Key Operations

# Generate address import script for Electrum/Bitcoin Core
chantools genimportscript \
  --format electrum \
  --derivationpath "m/84'/0'/0'"

# Derive specific keys from seed
chantools derivekey \
  --path "m/1017'/0'/0'/0/0"

# Recover from aezeed seed phrase
chantools showrootkey

Safety and Precautions

Understand the Consequences

Many chantools commands will permanently close channels. Force-closing is a one-way operation. Once you broadcast a force-close transaction, that channel is gone forever. Make absolutely sure you need to use chantools before proceeding.

Never Enter Seed Phrase Online

Chantools will ask for your seed phrase for most recovery operations. Only run chantools on a secure, offline machine when entering your seed. Your seed phrase controls all your funds, not just Lightning channels.

Wait for Time Locks

Force-closed channels have time locks (typically 144 blocks, about 1 day, but can be up to 2016 blocks, about 2 weeks). You must wait for these time locks to expire before you can sweep your funds. Chantools sweeptimelock command handles this, but you need patience.

Keep Backups

Before running any chantools command that modifies data, make complete backups of your LND data directory. Some operations are destructive and cannot be undone.

Verify Before Publishing

Most commands have a --publish flag that broadcasts transactions. Run commands without this flag first to see what transactions would be created. Only add --publish when you are certain the output is correct.

Seek Help for Complex Cases

For complicated recovery scenarios, consider seeking help from the community. The Lightning Labs Slack, Reddit r/lightningnetwork, and the LND GitHub issues are good places to ask. Provide transaction IDs and channel points (never your seed!) when asking for help.

FAQ