refactor(chain): replace the ChainSource enum with a pluggable chain ability seam

[tonible14012002]

Replaces the ChainSource enum with a seam: three pluggable chain ability slots plus an explicit sync-engine axis. Behaviour-neutral — no new feature, no config change, no public API change.

Based on logging-reduction (677e116), the rev the consuming monorepo pins today, so this diff is exactly the five commits below.

Why

The abstraction boundary was drawn at the chain source, not the chain ability. One closed enum decided fee estimation, lookup, broadcast and wallet-sync strategy together, so a backend could not be swapped for one ability without swapping all four. It also forced four unreachable!() arms, because each sync strategy had to exist on the other and panic.

What

  BEFORE   enum ChainSource          AFTER   struct ChainLayer
    Esplora  { 11 fields }             fee:       Arc<dyn FeeAdapter>
    Electrum { 11 fields }             lookup:    Arc<dyn LookupAdapter>
    Bitcoind { 11 fields }             broadcast: Arc<dyn BroadcastAdapter>
    (wallet, estimator, broadcaster,   engine:    Arc<dyn SyncEngine>
     kv_store, logger, metrics         shared:    held ONCE
     duplicated into all three)
  impl 1555 lines, 20x `match self`  0 matches on backend kind

src/chain/mod.rs: 2176 → 519 lines; the layer is now ~2833 lines across 11 focused files.

commit
d08a4b1	P1.1 ChainLayer wrapper — pure indirection
1911cb6	P1.2 FEE slot
0646abc	P1.3 BROADCAST slot
2dffd51	P1.4 LOOKUP slot
23b826f	P1.5 sync engines split out, ChainSource deleted

Design decisions the code forced

FeeAdapter is target-shaped, not block-count-shaped. bitcoind selects Conservative vs Economical estimation per ConfirmationTarget, not per block count. A block-count-keyed contract loses that and silently changes bitcoind's fee behaviour.

Adapters own their wire timeout and error classification; the seam owns only installing the result. Electrum's client already has its own timeout, batching and completeness policy, and Esplora's "HTTP 400 is benign" rule has no analogue elsewhere. Hoisting either changes behaviour.

FeeUpdate::Skip exists for one pre-seam line. bitcoind's soft testnet failure was a bare return Ok(()) that left both the fee cache and the metrics timestamp untouched. A plain Result<HashMap, _> would have advanced the timestamp as though an update had landed.

SyncEngine is a trait, not an enum. There are three types, not two: esplora and electrum are both transaction-based but share no code. An enum keeps the three-way matches and the four unreachable!() arms this change exists to remove.

LOOKUP is a narrow query ability, not a sync engine. Its consumers are swap_query_tx, derive_tx_status and the gossip UTXO verifier. Wallet sync is a separate explicit axis, selected but deliberately not abstracted.

Background loops refresh fees through the SLOT, not through the backend — otherwise a swapped fee adapter would apply to foreground calls and silently not to background ones.

Reviewing the moved code

The relocated bodies are byte-identical. Each method re-binds its state with let Self { .. } = self; so the moved lines match the match arms they came from exactly; the diff reads as a relocation, not a rewrite. The shared transaction-based background loop is lifted once into run_tx_based_sync_loop rather than copied into both tx engines.

Behaviour

Intended to be identical. Preserved deliberately:

• per-engine sync order (transaction-based syncs the Lightning wallet before the on-chain wallet)
• broadcast stays lossy — failures logged and dropped, never propagated. An ordered fallback across adapters is a later change and is not here.
• exact ldk_node::Error variants at the boundary
• exactly one timeout owner per call path

Two intended additions, both log_info at startup:

Chain ability slots: fee=esplora lookup=esplora broadcast=esplora (sync engine: esplora-tx-sync)
Chain lookup adapter 'esplora' cannot verify BOLT-7 channel announcements; the routing graph will carry unverified channel capacities.

The second surfaces an existing, previously silent condition: as_utxo_source() returns None for esplora and electrum, so add_utxo_lookup is never called and channel announcements are accepted unverified. That was true before this PR; it just said nothing.

One accepted deviation: the four unreachable!() arms no longer exist — panics that could never fire.

Testing

  cargo check --lib             0 errors, 0 new warnings, cargo fmt clean
  cargo test --lib              34 passed
  cargo test --test integration_tests_rust
                                23 passed, 0 failed  (311s)

The integration suite runs against real bitcoind 27.2 + electrs + esplora and covers all four backends:

  channel_full_cycle                     esplora
  channel_full_cycle_electrum            electrum
  channel_full_cycle_bitcoind_rpc_sync   bitcoind
  channel_full_cycle_bitcoind_rest_sync  bitcoind
  + force_close, force_close_trusted_no_reserve, 0conf,
    legacy_staticremotekey, multi_hop_sending, onchain_send_receive,
    onchain_send_all_retains_reserve, onchain_wallet_recovery,
    start_stop_reinit, simple_bolt12_send_receive,
    test_node_announcement_propagation, unified_qr_send_receive,
    lsps2_client_service_integration, connection_restart_behavior, ...

A channel full cycle cannot complete unless Filter::register_tx/register_output still reach the tx-sync client — the funding transaction would never confirm — so this exercises the highest-risk path of the refactor on every transaction-based backend.

Also verified: the consuming app builds against this branch unchanged, confirming the public builder API is untouched.

Not covered: the swaps/cycles primitives have unit coverage only; there is no integration test for swap_query_tx in this suite.

Adds one dependency

async-trait — required for object-safe async methods on Arc<dyn FeeAdapter> and friends. Already present in the consuming monorepo's graph, so it costs no additional crates downstream.

🤖 Generated with Claude Code

https://claude.ai/code/session_01UFffyxzPikJsaiFYUcxezB