ElementsProject / ElementsProject/lightning

bkpr-listbalances takes lightningd down when an account's debits exceed its credits

Open
#9,487 1 comment 0 reactions 0 assignees View on GitHub
Dominant language
C
Stars
3.1k
Forks
1k
Avg merge
4d 10h
Merged PRs (30d)
13

Description

bkpr-listbalances calls plugin_err when an account's debit sum exceeds its credit sum. The bookkeeper is an important plugin, so lightningd shuts down with it.

1. An account's ledger goes inconsistent. Here: a closed channel whose debits exceed its credits by 12,551,175 msat. Cause not established; an onchain fee counted twice is the likely culprit.
2. No other bkpr command checks the sums, so nothing notices.
3. The operator runs bkpr-listbalances.
4. do_list_balances fails amount_msat_sub for that account and calls plugin_err.
5. lightningd logs "Killing plugin: exited during normal operation" then "Plugin marked as important, shutting down lightningd!" and exits.

This is the third distinct accounting bug to reach this exit. #5557 (lease fee counted twice), #6534 (negative balance on signet) and #8549 / #8582 (duplicate chain_moves after the accounts.db migration, fixed in #8574) were each closed by fixing that instance's accounting cause, and the exit stayed. This node runs v26.06.7, which includes the #8574 dedup, so the cause here is yet another one. 29e0a1ddf turned the same kind of assertion in find_txo_chain into a BROKEN log; this check should log and continue as well, whatever the next cause turns out to be. PR to follow.

Hit on my node, ledger going back to 2024. The check is unchanged on master. Workaround until then: don't call bkpr-listbalances. The account's listchainmoves / listchannelmoves events are available on request.

----
```
plugin-bookkeeper: Account balance underflow for account 906c4056... (credit 25339109661msat, debit 25351660836msat)
plugin-bookkeeper: Killing plugin: exited during normal operation
Plugin marked as important, shutting down lightningd!
```

Related: #5557, #6534, #8549, #8582, #8574

Contributor guide

No contributing guide indexed for this repository

Research direction

Start at the bkpr-listbalances entry point and follow do_list_balances through amount_msat_sub; compare its underflow handling with the BROKEN log behavior in find_txo_chain. Done means an account whose debits exceed credits is logged and skipped without causing the important bookkeeper plugin or lightningd to exit.

Written by the indexing model from the issue text.

Assessment

Tech stack
c
Domain
backend
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
64/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.