[DO NOT MERGE] Erlay: bandwidth-efficient transaction relay protocol (Full implementation) #35591

Erlay Project Tracking: #30249 Conceptual Discussion: #34542

---

This is a full implementation of Erlay. Its purpose is to check the integrity and correctness of the implementation against changes/additions that may originate from the review process and/or rebases on top of newer functionality.

This is not to be merged. Functionality will be spread across multiple smaller PRs to ease the review process.

---

Approach

This approach uses Erlay as a fallback mechanism for transaction propagation. Instead of mixing fanout and reconciliation into a single connection type, the current approach leaves the existing connections as they are, and adds additional low-bandwidth connections to be used in case the node is being eclipsed. This connections should have minimal cost under normal circumstances, and only undergo real traffic in case other 8 full-outbound connections are being captured.

outbound-full-reconciliation connections

For now, we are adding 4 additional reconciliation-only connections to the node while we test it's impact on real node running the approach. Further analysis may be needed to pick a meaningful value for this. The number of inbound connections should also be scaled based on how many connections we are adding.

<!--e57a25ab6845829454e8d69fc972939a-->

The following sections might be updated with supplementary metadata relevant to reviewers and maintainers.

<!--006a51241073e994b41acfe9ec718e94-->

Code Coverage & Benchmarks

For details see: https://corecheck.dev/bitcoin/bitcoin/pulls/35591.

<!--021abf342d371248e50ceaed478a90ca-->

Reviews

See the guideline for information on the review process. A summary of reviews will appear here.

<!--174a7506f384e20aa4161008e828411d-->

Conflicts

Reviewers, this pull request conflicts with the following ones:

• #35561 (net: move some CNodeState fields to Peer by Crypt-iQ)
• #35522 (refactor: Extract per-message helpers from SendMessages() (move-only) by pablomartin4btc)
• #35502 (refactor: extract per-message helpers from ProcessMessage (move-only) by w0xlt)
• #34824 (net: encapsulate TxRelay state and replace recursive mutexes by w0xlt)
• #34628 (p2p: Replace per-peer transaction rate-limiting with global rate limits by ajtowns)
• #34565 (refactor: extract BlockDownloadManager from PeerManagerImpl by w0xlt)
• #28690 (build: Introduce internal kernel library by sedited)
• #28463 (p2p: Increase inbound capacity for block-relay only connections by mzumsande)

If you consider this pull request important, please also help to review the conflicting pull requests. Ideally, start with the one that should be merged first.

<!--5faf32d7da4f0f540f40219e4f7537a3-->

LLM Linter (✨ experimental)

Possible typos and grammar issues:

• based on it's char[] representation -> based on its char[] representation [“it's” should be the possessive “its”]
• the peer have no transactions for us -> the peer has no transactions for us [subject-verb agreement is broken]

Possible places where comparison-specific test macros should replace generic comparisons:

• [test/functional/p2p_txrecon_disabled.py] assert self.nodes[0].process.poll() is None, f"node crashed handling {msgname}" -> replace with assert_equal(self.nodes[0].process.poll(), None)

^{2026-06-24 18:52:05}

Rebased on master.

Opening this so it can be tested against CI and to make sure nothing obvious is missing. Next step will be testing with real nodes (most likely in Warnet).

Things to consider/add:

• This is currently using sendtxrcncl as a way, for outbound nodes, to signal they want to establish a full-reconciliation connection, plus adding a limit on the number of full-reconcilition inbounds that will be accepted by a node. This is not the originally intended way of using sendtxrcncl. It may be worth considering an approach based on BIP-434.
• The extension phase was designed so peers with an ongoing reconciliation that had underpredicted the sketch capacity could still reconcile without having to directly fallback to fanout. Given reconciliation is now used as fallback, and the extra bandwidth may not be as problematic, it may be worth considering overshooting the initial sketch capacity and getting rid of the extension phase.
• Fuzz tests are missing

Fixed some typos and addressed some of the linter suggestions

6554707...e63db1a

Fixed several bugs and added a new test for receiving reconciliation messages when reconciliation is not enabled.

e63db1a...35bcd04

Addressed some issues pointed out by corecheck.

35bcd04...d08f127

**Testing report (LLM/experimental) based on the results of an incremental mutation testing run for this PR - full result is avaliable at: https://bitcoincore.space**

---

The overall result is mixed. The PR already has useful coverage for the happy-path reconciliation flow, basic protocol violations, and some queue/timer behavior. However, the survivors show that the tests still leave several important behaviors only weakly specified, especially where reconciliation falls back, extends, or interacts with INV relay bookkeeping.

What the current tests do well

The existing tests cover the basic handshake and some normal flows reasonably well:

• unit coverage for peer registration, queue rotation, set insertion/removal, and non-extension reconciliation in src/test/txreconciliation_tests.cpp
• functional coverage for initiator/responder happy paths in test/functional/p2p_txrecon_initiator.py and test/functional/p2p_txrecon_responder.py
• protocol-violation checks for clearly invalid message ordering and unsupported peers

That baseline is good enough to kill most straightforward mutations. The survivors are mostly about what happens around the edges of the protocol, not the central flow.

Main gaps exposed by the surviving mutants

1. Extension handling is under-tested

This is the clearest gap. Several survivors change extension behavior without being detected:

• not sending REQSKETCHEXT after an undecodable sketch in net_processing
• not snapshotting state before the extension round
• accepting/rejecting malformed extension sizes incorrectly
• flipping success/failure outcomes of extension decoding
• using the wrong transaction set after extension failure
• not clearing peer state after extension completion

This lines up with the current functional tests: both initiator and responder tests explicitly stop short of extension coverage and even leave TODOs for it in test/functional/p2p_txrecon_initiator.py and test/functional/p2p_txrecon_responder.py.

What should be improved:

• add end-to-end functional tests that force an extension round and assert the exact message sequence: REQTXRCNCL -> SKETCH -> REQSKETCHEXT -> SKETCH -> RECONCILDIFF
• assert both extension success and extension failure behavior
• verify that extension failure falls back to announcing the snapshotted set, not the live set
• verify that state is cleared after extension completion and that a second reconciliation starts cleanly

2. Boundary conditions are not pinned down tightly enough

Several survivors change strict inequalities to inclusive ones and still pass:

• remote_sketch_capacity > MAX_SKETCH_CAPACITY changed to >=
• extended_capacity > MAX_SKETCH_CAPACITY * 2 changed to >=
• peer_q > Q_PRECISION changed to >=

This means the tests exercise invalid-above-limit cases, but not the exact boundary values that should remain valid. There is already a good example of this style for rounded q formatting in src/test/txreconciliation_tests.cpp, but the same precision is missing for protocol acceptance thresholds.

What should be improved:

• add exact-boundary tests for MAX_SKETCH_CAPACITY, 2 * MAX_SKETCH_CAPACITY, and Q_PRECISION
• check both sides of each threshold: limit must pass, limit + 1 must fail

3. INV relay side effects are only partially asserted

Many survivors in PeerManagerImpl::AnnounceTxs() and the send path in SendMessages() remove or alter important side effects without breaking tests:

• skipping heap construction/pop order
• changing continue to break when one candidate should not be sent
• not inserting into m_tx_inventory_known_filter
• not erasing from m_tx_inventory_to_send
• not flushing INV batches at MAX_INV_SZ
• not clearing the batch after sending

The current tests mostly check that transactions eventually arrive. They do not strongly check how they are batched, filtered, or suppressed from future re-announcement. That leaves a lot of bookkeeping mutations alive.

What should be improved:

• add tests with a mix of sendable and unsendable transactions and assert that later eligible transactions are still announced
• assert that transactions already known to the peer are not re-announced in the next round
• add a case above MAX_INV_SZ and verify the number and sizes of INV messages
• verify that reconciliation and fanout paths do not duplicate announcements after internal state should have been cleared

4. Some state-management behaviors are observable in principle, but not asserted

Survivors also show weak checking around reconciliation state transitions:

• not clearing m_short_id_mapping
• not clearing peer state after handling a result
• always taking the “removed” branch in TryRemovingFromSet
• not recording m_announced_while_reconciling
• returning success from queue-selection paths that should be false

These are not all equally severe, but together they indicate that the tests often validate the final external effect of a single round without checking the follow-up round that would expose stale state.

What should be improved:

• add two-step tests that perform one reconciliation round and then immediately start another to detect stale snapshots, stale mappings, or stale queue state
• specifically verify the “received while reconciling” behavior across the extension path, not just the non-extension path

Bottom line

The current tests are good at proving that the basic txreconciliation flow works. They are not yet strong enough to fully specify the extension path, the exact protocol boundaries, or the internal bookkeeping that prevents duplicate, truncated, or stale announcements.

If I had to prioritize follow-up work, I would do it in this order:

1. Add full initiator/responder extension-path functional tests.
2. Add exact boundary tests for sketch capacity and q.
3. Add stronger assertions around INV batching, filtering, and duplicate suppression.
4. Add second-round/state-cleanup tests to catch stale reconciliation state.

That would likely eliminate most of the meaningful survivors from this run and materially improve confidence in the PR’s tests.