title: discv5::discv5_crawler summary: Discv5 peer crawler: seed → FINDNODE loop → ValidatedPeer emission.

discv5::discv5_crawler¶

Discv5 peer crawler: seed → FINDNODE loop → ValidatedPeer emission. More...

#include <discv5_crawler.hpp>

Public Functions¶

	Name
	discv5_crawler(const discv5Config & config) Construct the crawler with a fully-populated configuration.
	~discv5_crawler() =default
	discv5_crawler(const discv5_crawler & ) =delete
discv5_crawler &	operator=(const discv5_crawler & ) =delete
	discv5_crawler(discv5_crawler && ) =delete
discv5_crawler &	operator=(discv5_crawler && ) =delete
void	add_bootstrap(const EnrRecord & record) Seed the crawler with an additional bootstrap ENR record.
void	set_peer_discovered_callback(PeerDiscoveredCallback callback) Register the callback invoked for each newly discovered peer.
void	set_error_callback(ErrorCallback callback) Register the error callback for non-fatal diagnostics.
VoidResult	start() Enqueue all bootstrap seeds and transition to running state.
VoidResult	stop() Stop the crawler and clear the running flag.
void	process_found_peers(const std::vector< ValidatedPeer > & peers) Manually enqueue a set of ValidatedPeer entries from an external source (e.g. a NODES reply decoded by the client layer).
void	ingest_discovered_peers(const std::vector< ValidatedPeer > & peers) Accept peers decoded from a live NODES response.
CrawlerStats	stats() const Return a snapshot of current activity counters (thread-safe).
bool	is_running() const Returns true if the crawler has been started and not yet stopped.
void	mark_measured(const NodeId & node_id) Mark a peer as measured (responded to a query).
void	mark_failed(const NodeId & node_id) Mark a peer as failed (query timed out or returned error).
std::optional< ValidatedPeer >	dequeue_next() Return the next queued NodeId to probe, or nullopt if queue empty.
bool	is_discovered(const NodeId & node_id) const True if node_id has already been forwarded to the callback.

Detailed Description¶

class discv5::discv5_crawler;

Discv5 peer crawler: seed → FINDNODE loop → ValidatedPeer emission.

Manages four peer sets that mirror the nim dcrawl pattern:

queued: nodes to be queried next (FINDNODE not yet sent)
measured: nodes that responded to at least one FINDNODE query
failed: nodes that timed out or returned an error
discovered: deduplication set; node_ids already forwarded downstream

¶

Protocol implementation note¶

The first iteration keeps the network I/O intentionally simple: it pings bootstrap nodes with ENR-sourced addresses and processes NODES replies. A full WHOAREYOU/HANDSHAKE session layer will be added in a future sprint.

¶

Thread safety¶

start() and stop() must be called from the same thread that drives the provided asio::io_context. The stats() accessor is lock-protected.

Public Functions Documentation¶

function discv5_crawler¶

explicit discv5_crawler(
    const discv5Config & config
)

Construct the crawler with a fully-populated configuration.

Parameters:

config Crawler parameters. A copy is taken.

function ~discv5_crawler¶

~discv5_crawler() =default

function discv5_crawler¶

discv5_crawler(
    const discv5_crawler & 
) =delete

function operator=¶

discv5_crawler & operator=(
    const discv5_crawler & 
) =delete

function discv5_crawler¶

discv5_crawler(
    discv5_crawler && 
) =delete

function operator=¶

discv5_crawler & operator=(
    discv5_crawler && 
) =delete

function add_bootstrap¶

void add_bootstrap(
    const EnrRecord & record
)

Seed the crawler with an additional bootstrap ENR record.

Parameters:

record Parsed and signature-verified EnrRecord.

May be called before or after start(). Records added after start() are processed in the next query round.

function set_peer_discovered_callback¶

void set_peer_discovered_callback(
    PeerDiscoveredCallback callback
)

Register the callback invoked for each newly discovered peer.

Parameters:

callback Function to call with a ValidatedPeer.

Replaces any previously registered callback. The callback is invoked synchronously from the crawler's internal processing loop; it must not block.

function set_error_callback¶

void set_error_callback(
    ErrorCallback callback
)

Register the error callback for non-fatal diagnostics.

Parameters:

callback Function to call with an error description string.

function start¶

VoidResult start()

Enqueue all bootstrap seeds and transition to running state.

Return: success or kCrawlerAlreadyRunning.

Seeds are taken from the discv5Config::bootstrap_enrs list.

function stop¶

VoidResult stop()

Stop the crawler and clear the running flag.

Return: success or kCrawlerNotRunning.

Does not drain the queued set — a subsequent start() will resume from where processing left off.

function process_found_peers¶

void process_found_peers(
    const std::vector< ValidatedPeer > & peers
)

Manually enqueue a set of ValidatedPeer entries from an external source (e.g. a NODES reply decoded by the client layer).

Parameters:

peers Peers to consider as FINDNODE candidates.

Deduplicates against the known node_id set before enqueueing.

function ingest_discovered_peers¶

void ingest_discovered_peers(
    const std::vector< ValidatedPeer > & peers
)

Accept peers decoded from a live NODES response.

Parameters:

peers Peers decoded from a live response packet.

Queues new peers for further crawling and also forwards them through the normal discovered-peer callback path.

function stats¶

CrawlerStats stats() const

Return a snapshot of current activity counters (thread-safe).

function is_running¶

bool is_running() const

Returns true if the crawler has been started and not yet stopped.

function mark_measured¶

void mark_measured(
    const NodeId & node_id
)

Mark a peer as measured (responded to a query).

function mark_failed¶

void mark_failed(
    const NodeId & node_id
)

Mark a peer as failed (query timed out or returned error).

function dequeue_next¶

std::optional< ValidatedPeer > dequeue_next()

Return the next queued NodeId to probe, or nullopt if queue empty.

function is_discovered¶

bool is_discovered(
    const NodeId & node_id
) const

True if node_id has already been forwarded to the callback.

Updated on 2026-04-13 at 23:22:46 -0700