Skip to content

Make bitcoind optional: add transaction-sync as an alternative chain backend#126

Open
bitwalt wants to merge 1 commit into
RGB-Tools:masterfrom
bitwalt:bitcoind-removal-indexer
Open

Make bitcoind optional: add transaction-sync as an alternative chain backend#126
bitwalt wants to merge 1 commit into
RGB-Tools:masterfrom
bitwalt:bitcoind-removal-indexer

Conversation

@bitwalt

@bitwalt bitwalt commented May 1, 2026

Copy link
Copy Markdown
Contributor

Implements #125.

Reworked per @zoedberg's review: instead of replacing lightning-block-sync with lightning-transaction-sync, this adds transaction-sync as an alternative chain backend and keeps block-sync intact. The sync mode is chosen explicitly at unlock time.

Sync modes

The /unlock payload gains a sync_mode tag:

  • block_sync (default): consume full blocks from a trusted/local bitcoind over JSON-RPC (lightning-block-sync). The bitcoind_rpc_* parameters live inside this variant, so they are required exactly when this mode is selected and rejected otherwise — no manual "all or none" validation. This is the more trust-minimized / local-first option.
  • transaction_sync: sync through the configured electrum/esplora indexer_url (lightning-transaction-sync). No bitcoind required — lighter to deploy for indexer-based setups.

Cargo features

Each backend is gated behind a feature (block-sync, transaction-sync), both enabled by default, so a user who wants only one sync type can build with only the dependency they need. Both single-feature builds compile cleanly, and requesting a mode that wasn't compiled in returns a clear error.

Implementation notes

  • LDK is wired against trait objects for the fee estimator, broadcaster and gossip UTXO lookup, so a single set of type aliases serves both backends.
  • Because lightning-block-sync's GossipVerifier requires the P2PGossipSync to be typed with Arc<Self>, a small BlockSyncGossipVerifier provides the block-sync gossip UTXO lookup against the shared trait-object gossip sync (mirroring the transaction-sync IndexerGossipVerifier).

Tests

Adds an integration test for the transaction-sync backend (as suggested): two nodes are unlocked in transaction-sync mode, an RGB asset channel is opened, a node is restarted (re-establishing the channel after syncing via the indexer) and the channel is cooperatively closed. The existing block-sync tests continue to pass unchanged.

@bitwalt bitwalt force-pushed the bitcoind-removal-indexer branch from 0e5ad71 to 9500239 Compare May 4, 2026 11:41
@bitwalt bitwalt marked this pull request as ready for review May 4, 2026 15:04

@zoedberg zoedberg left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please check my comment #125 (comment), I explained why we should not replace the block-sync with the transaction-sync but add it instead as an alternative sync mode. Please update this PR accordingly

@zoedberg

zoedberg commented Jul 2, 2026

Copy link
Copy Markdown
Member

Hi @bitwalt, here #125 (comment) you said you agreed in updating this PR to add this as an alternative sync mode. Are you still willing to complete this PR?

@bitwalt

bitwalt commented Jul 2, 2026

Copy link
Copy Markdown
Contributor Author

Hi Zoe, sure I'll try to complete this

…backend

Adds `lightning-transaction-sync` (electrum/esplora) as an alternative to the
existing `lightning-block-sync` (bitcoind) chain backend, rather than replacing
it (addresses the review on RGB-Tools#126 / RGB-Tools#125).

The sync mode is selected explicitly at unlock time via a new `sync_mode` tag on
the unlock request:

  - `block_sync` (default): consume full blocks from a trusted/local bitcoind
    over JSON-RPC. The bitcoind RPC parameters now live inside this variant, so
    they are required exactly when this mode is selected and rejected otherwise,
    with no manual "all or none" validation.
  - `transaction_sync`: sync through the configured electrum/esplora
    `indexer_url` only; no bitcoind required.

Each backend is gated behind a Cargo feature (`block-sync`, `transaction-sync`),
both enabled by default, so a user can build with only the sync dependency they
need. A single mode is still fully functional on its own.

LDK is wired against trait objects for the fee estimator, broadcaster and gossip
UTXO lookup so one set of type aliases serves both backends. Because
`lightning-block-sync`'s `GossipVerifier` requires the `P2PGossipSync` to be
typed with `Arc<Self>`, a `BlockSyncGossipVerifier` provides the block-sync
gossip UTXO lookup against the shared trait-object gossip sync.

Adds an integration test for the transaction-sync backend: two nodes are
unlocked in transaction-sync mode, an RGB asset channel is opened, a node is
restarted (re-establishing the channel after syncing via the indexer) and the
channel is cooperatively closed.

Closes RGB-Tools#125

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@bitwalt bitwalt force-pushed the bitcoind-removal-indexer branch from 9500239 to 536b29f Compare July 2, 2026 15:27
@bitwalt bitwalt changed the title Remove direct bitcoind dependency, sync via electrum/esplora indexer Make bitcoind optional: add transaction-sync as an alternative chain backend Jul 2, 2026
@bitwalt

bitwalt commented Jul 2, 2026

Copy link
Copy Markdown
Contributor Author

Thanks @zoedberg — I've reworked the PR along the lines you suggested.

Rather than replacing block-sync, it now keeps lightning-block-sync and adds lightning-transaction-sync as an alternative, selectable via an explicit sync_mode on the unlock request:

  • block_sync (default) — full blocks from a trusted/local bitcoind. The bitcoind_rpc_* params are embedded in this variant so they're required exactly when this mode is chosen (no manual all-or-none checking).
  • transaction_sync — sync through the configured electrum/esplora indexer only, no bitcoind.

Both are behind Cargo features (block-sync, transaction-sync), enabled by default, so a user can compile just the sync dependency they want; both single-feature builds compile cleanly.

I added the integration test you described (unlock 2 nodes, open a channel, restart a node, close the channel) exercising the transaction-sync path, and the existing block-sync tests still pass.

Two notes for review:

  1. The /unlock payload shape changes (the bitcoind params now sit under the sync_mode: block_sync variant). You mentioned not worrying about existing setups in this phase, but happy to reshape if you'd prefer a different layout.
  2. For the block-sync gossip UTXO lookup I added a small BlockSyncGossipVerifier instead of lightning-block-sync's GossipVerifier, because the latter requires the P2PGossipSync to be typed with Arc<Self>, which is incompatible with the trait-object gossip sync needed to serve both backends from one PeerManager type. Let me know if you'd rather approach that differently.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants