Skip to content

Warn when bitcoind has not whitelisted electrs#1291

Closed
PeterXMR wants to merge 1 commit into
romanz:masterfrom
PeterXMR:detect-not-whitelisted-400
Closed

Warn when bitcoind has not whitelisted electrs#1291
PeterXMR wants to merge 1 commit into
romanz:masterfrom
PeterXMR:detect-not-whitelisted-400

Conversation

@PeterXMR
Copy link
Copy Markdown

Summary

Closes #400.

If electrs is not granted the download permission by bitcoind, getheaders is silently ignored during IBD and the connection can be dropped once maxuploadtarget is reached — both leading to opaque sync failures (see #399 for the original report).

This change makes electrs detect that condition at startup and emit a single clear warning, modeled on NBXplorer's behavior (referenced in the issue thread):

WARN electrs::daemon] electrs is not whitelisted by bitcoind: it may be
disconnected during IBD or once `maxuploadtarget` is reached. Consider
adding `whitelist=download@127.0.0.1` to bitcoin.conf. See
https://github.com/romanz/electrs/issues/400 for details.

How it works

After the p2p version handshake completes, electrs calls getpeerinfo, finds its own peer entry by matching addr against the local socket address, and checks whether the permissions array contains "download". Any failure mode (RPC error, no matching peer, missing field, address mismatch) is logged at debug! only and never affects startup.

The parsing logic is factored into a pure check_whitelist_status(peers, local_addr) helper for unit testing.

Scope

Detection + warning only. The "ideally fall back to RPC" half of the original ask is out of scope here — that design space is already explored in #1274 (ZMQ+REST) and #1252 (bindex), so a third design in this PR would conflict.

Test plan

  • 8 new unit tests for check_whitelist_status (download present/absent, no matching peer, missing permissions field, IPv4-mapped-IPv6 normalization, outbound-peer skip, multi-peer, empty list)
  • cargo test --lib — 29/29 pass
  • cargo clippy --all-targets -- -D warnings — clean
  • cargo fmt --check — clean
  • Live tested against Bitcoin Core v31.0.0 on signet:
    • Without whitelist → warning fires
    • With whitelist=download@127.0.0.1 → no warning, startup proceeds normally
    • Verified getpeerinfo[].addr matches electrs's local_addr byte-for-byte (127.0.0.1:<ephemeral>) and permissions: ["download"] when whitelisted

If electrs is not whitelisted with `download` permission, bitcoind
silently ignores its `getheaders` messages during IBD and may
disconnect it when `maxuploadtarget` is reached, leading to opaque
sync failures.

After the p2p handshake, query `getpeerinfo`, locate electrs's own
peer entry by matching the local socket address, and `warn!` if the
`permissions` array does not contain `"download"`, suggesting
`whitelist=download@127.0.0.1` in bitcoin.conf.

Detection failures (RPC error, no matching peer, missing field) are
logged at `debug!` only and never affect startup.

Closes romanz#400
@romanz
Copy link
Copy Markdown
Owner

romanz commented May 31, 2026

#1252 will fetch blocks using REST API instead of p2p.

@romanz romanz closed this May 31, 2026
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.

Detect p2p not being whitelisted

2 participants