Merge PR 'Avoid overflow when averaging liquidity offsets in merge' (#5208)
What changed, and why it matters
This patch fixes an arithmetic overflow bug in rust-lightning's payment-path scoring logic. When the software merged two stored estimates of a Lightning channel's available liquidity, it added two large 64-bit numbers together and then divided by two to get an average. If both numbers were near the maximum a u64 can hold, the addition would overflow and wrap around, producing a tiny, wrong average. The fix computes the average safely by dividing each number first, then adding. The commit message and new test explicitly describe this as an overflow risk, especially when data is loaded from disk or untrusted external sources.
Treat as a low-to-moderate reliability/security fix. Upgrade to a release containing this commit. If running custom builds, backport the overflow-safe average to ChannelLiquidity::merge(). No immediate incident response is required unless node operators observe anomalous routing behavior after merging scorer state from untrusted or corrupted sources.
Security signals we found
Unchecked u64 addition in merge logic replaced with overflow-safe averaging
Commit message explicitly frames change as avoiding overflow
New regression test covers u64::MAX inputs and odd-bit rounding
Affected values feed into routing/scoring decisions
Comment states offsets can be u64::MAX when read from serialized or external sources
Evidence from the diff
In lightning/src/routing/scoring.rs, ChannelLiquidity::merge() previously computed (a + b) / 2 for min_liquidity_offset_msat and max_liquidity_offset_msat, both u64 values. This is an unchecked addition that can overflow. The patch replaces it with a branchless average: a/2 + b/2 + ((a & 1) & (b & 1)), which avoids overflow while preserving integer rounding semantics. A new unit test verifies behavior for u64::MAX inputs. The overflow could corrupt liquidity estimates used during route scoring, potentially causing pathfinding to ignore or prefer channels incorrectly. The commit notes that extreme offsets can come from serialized scorer state or external sources.
Changed components
lightning/src/routing/scoring.rsChannelLiquidity::merge()min_liquidity_offset_msat / max_liquidity_offset_msat handlingInspect captured patch +40 / −3
### lightning/src/routing/scoring.rs
@@ -1260,9 +1260,11 @@ impl ChannelLiquidity {
#[rustfmt::skip]
fn merge(&mut self, other: &Self) {
- // Take average for min/max liquidity offsets.
- self.min_liquidity_offset_msat = (self.min_liquidity_offset_msat + other.min_liquidity_offset_msat) / 2;
- self.max_liquidity_offset_msat = (self.max_liquidity_offset_msat + other.max_liquidity_offset_msat) / 2;
+ // Take average for min/max liquidity offsets, avoiding an addition that can
+ // overflow when the offsets are large.
+ let average = |a: u64, b: u64| a / 2 + b / 2 + ((a & 1) & (b & 1));
+ self.min_liquidity_offset_msat = average(self.min_liquidity_offset_msat, other.min_liquidity_offset_msat);
+ self.max_liquidity_offset_msat = average(self.max_liquidity_offset_msat, other.max_liquidity_offset_msat);
// Merge historical liquidity data.
self.liquidity_history.merge(&other.liquidity_history);
@@ -2925,6 +2927,41 @@ mod tests {
assert_eq!(liquidity.max_liquidity_msat(), 1000);
}
+ #[test]
+ #[rustfmt::skip]
+ fn merges_extreme_liquidity_offsets_without_overflow() {
+ // Offsets can be as large as `u64::MAX` when read back from a serialized
+ // scorer or taken from external sources.
+ let last_updated = Duration::ZERO;
+ let offset_history_last_updated = Duration::ZERO;
+ let last_datapoint_time = Duration::ZERO;
+ let mut liquidity = ChannelLiquidity {
+ min_liquidity_offset_msat: u64::MAX, max_liquidity_offset_msat: u64::MAX,
+ last_updated, offset_history_last_updated, last_datapoint_time,
+ liquidity_history: HistoricalLiquidityTracker::new(),
+ };
+ liquidity.merge(&ChannelLiquidity {
+ min_liquidity_offset_msat: u64::MAX, max_liquidity_offset_msat: u64::MAX,
+ last_updated, offset_history_last_updated, last_datapoint_time,
+ liquidity_history: HistoricalLiquidityTracker::new(),
+ });
+ assert_eq!(liquidity.min_liquidity_offset_msat, u64::MAX);
+ assert_eq!(liquidity.max_liquidity_offset_msat, u64::MAX);
+
+ let mut liquidity = ChannelLiquidity {
+ min_liquidity_offset_msat: u64::MAX, max_liquidity_offset_msat: u64::MAX,
+ last_updated, offset_history_last_updated, last_datapoint_time,
+ liquidity_history: HistoricalLiquidityTracker::new(),
+ };
+ liquidity.merge(&ChannelLiquidity {
+ min_liquidity_offset_msat: 1, max_liquidity_offset_msat: 1,
+ last_updated, offset_history_last_updated, last_datapoint_time,
+ liquidity_history: HistoricalLiquidityTracker::new(),
+ });
+ assert_eq!(liquidity.min_liquidity_offset_msat, u64::MAX / 2 + 1);
+ assert_eq!(liquidity.max_liquidity_offset_msat, u64::MAX / 2 + 1);
+ }
+
#[test]
#[rustfmt::skip]
fn resets_liquidity_upper_bound_when_crossed_by_lower_bound() {Why this scored 48/100
Community notes
Notes can correct, qualify, or add evidence to the AI analysis. Every note shown here has been validated by a human moderator.
The AI analysis stands alone for now. Submit a note if you can add evidence or important context.