0.2.2 accept stale monitors

[ovitrif]

Summary

Adds accept_stale_channel_monitors to ChannelManagerReadArgs, allowing nodes to recover from monitor desync (e.g. a migration or backup restore that overwrote a newer monitor with older data). When enabled, stale monitors have their update_id force-synced to the ChannelManager's expected value and their BOLT-3 commitment secrets tree reset, so the channel can self-heal on the next commitment round-trip.

Changes

1. accept_stale_channel_monitors field (channelmanager.rs)

New bool field on ChannelManagerReadArgs (default: false). When a monitor's update_id is behind the ChannelManager's, instead of returning DecodeError::DangerousValue, the deserialization path:

• Logs a warning with both update_id values
• Calls monitor.force_set_latest_update_id(target_id) to resync

2. force_set_latest_update_id with secrets tree reset (channelmonitor.rs)

New public method that:

• Sets latest_update_id to the given value (skipping sequential validation)
• Resets commitment_secrets to CounterpartyCommitmentSecrets::new() — clearing stale secrets that would fail cross-tree BOLT-3 derivation validation against new secrets from healing round-trips

3. Sentinel skip in provide_secret (chan_utils.rs)

Skip uninitialized sentinel slots (old_idx == 1 << 48) in the cross-check loop. Without this, ~50% of channels crash on the first post-reset provide_secret call — when the first secret index lands at position > 0, derive_secret checks against the all-zeros sentinel and always fails.

4. Test scaffolding (functional_test_utils.rs, reload_tests.rs)

Added accept_stale_channel_monitors: false to existing ChannelManagerReadArgs construction sites to compile with the new field.

Security analysis

Resetting the secrets tree

Concern	Assessment
Loss of penalty capability for pre-stale revoked commitments	The stale monitor lacks commitment transaction data for the gap period — it cannot construct penalty transactions even with the old secrets. The secrets alone provide no actionable security benefit.
Pre-stale commitments where monitor has HTLC data	Monitor loses secrets for these. However, the alternative (keeping stale secrets) causes a crash making the node completely non-functional, which is strictly worse.
Post-recovery exposure	After recovery, the channel should be closed as soon as practical to minimize the window where old secrets are unavailable.

Sentinel skip in provide_secret

Concern	Assessment
Could a normal channel hit the sentinel skip?	No. During sequential provision, sentinel slots at position P are always overwritten before position P+1 is first checked — the binary counting pattern guarantees this. The skip never triggers for non-stale channels.
Could an attacker craft index 1 << 48?	No. Valid indices are 0 to (1<<48)-1. The commitment number determines the index via (1<<48) - 1 - C, and C starts at 0. Even at 1 commitment/second it takes ~9 million years to exhaust the space.
Are real cross-checks weakened?	No. Cross-checks between real (non-sentinel) slots remain fully enforced. The skip only applies to slots with the impossible sentinel index 1 << 48.
When does the skip trigger?	Only after an explicit CounterpartyCommitmentSecrets::new() reset in force_set_latest_update_id.

Test plan

• cargo build --all-targets — compiles without errors
• cargo test --lib -p lightning — unit tests pass (includes existing CounterpartyCommitmentSecrets tests)
• cargo fmt --check — no formatting issues in changed files
• Manual test in bitkit app via ldk-node: restore a stale monitor, send a healing payment, verify no crash