discv5::discv5_client¶

Discovery v5 protocol client. More...

#include <discv5_client.hpp>

Public Functions¶

	Name
	discv5_client(asio::io_context & io_context, const discv5Config & config) Construct the client.
	~discv5_client()
	discv5_client(const discv5_client & ) =delete
discv5_client &	operator=(const discv5_client & ) =delete
	discv5_client(discv5_client && ) =delete
discv5_client &	operator=(discv5_client && ) =delete
void	add_bootnode(const std::string & enr_uri) Add a single bootstrap ENR URI.
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.
VoidResult	start() Bind the UDP socket and start the receive + crawler loops.
void	stop() Close the UDP socket and signal the crawler to stop.
CrawlerStats	stats() const Return a snapshot of current crawler activity counters.
const NodeId &	local_node_id() const Return the local node identifier (64-byte public key).
bool	is_running() const Returns true when the client has been started and not yet stopped.
uint16_t	bound_port() const Return the local UDP port the socket is currently bound to. Useful in tests when bind_port is 0 (ephemeral OS-assigned port).
size_t	received_packet_count() const Return the number of non-undersized UDP packets accepted by the receive loop.
size_t	dropped_undersized_packet_count() const Return the number of undersized UDP packets dropped by the receive loop.
size_t	send_findnode_failure_count() const Return the number of FINDNODE send attempts that failed.
size_t	whoareyou_packet_count() const Return the number of valid WHOAREYOU packets parsed by the receive path.
size_t	handshake_packet_count() const Return the number of successfully decrypted handshake packets.
size_t	outbound_handshake_attempt_count() const Return the number of outbound handshake send attempts.
size_t	outbound_handshake_failure_count() const Return the number of outbound handshake send attempts that failed.
size_t	inbound_handshake_reject_auth_count() const Return the number of inbound handshake packets rejected during auth parsing.
size_t	inbound_handshake_reject_challenge_count() const Return the number of inbound handshake packets rejected due to missing/mismatched challenge state.
size_t	inbound_handshake_reject_record_count() const Return the number of inbound handshake packets rejected during ENR/identity validation.
size_t	inbound_handshake_reject_crypto_count() const Return the number of inbound handshake packets rejected during shared-secret/key derivation.
size_t	inbound_handshake_reject_decrypt_count() const Return the number of inbound handshake packets rejected due to message decrypt failure.
size_t	inbound_handshake_seen_count() const Return the number of inbound handshake packets observed before validation.
size_t	inbound_message_seen_count() const Return the number of inbound MESSAGE packets observed before validation/decrypt.
size_t	inbound_message_decrypt_fail_count() const Return the number of inbound MESSAGE packets that failed decrypt with a matching session.
size_t	nodes_packet_count() const Return the number of successfully decoded NODES packets.

Detailed Description¶

class discv5::discv5_client;

Discovery v5 protocol client.

Owns the UDP socket, drives the receive loop, and delegates peer lifecycle management to an internal discv5_crawler.

The public interface is deliberately narrow and mirrors the discv4_client shape so that callers can adopt either protocol with minimal friction:

discv5::discv5Config cfg;
cfg.bootstrap_enrs = ChainBootnodeRegistry::for_chain(ChainId::kEthereumSepolia)->fetch();
auto client = std::make_unique<discv5::discv5_client>(io, cfg);
client->set_peer_discovered_callback([](const discovery::ValidatedPeer& p){ … });
client->start();
io.run();

¶

Thread safety¶

All public methods must be called from the thread that drives the supplied io_context. The peer-discovered callback is invoked on that same thread.

Public Functions Documentation¶

function discv5_client¶

explicit discv5_client(
    asio::io_context & io_context,
    const discv5Config & config
)

Construct the client.

Parameters:

io_context Boost.Asio io_context. Must outlive this object.
config Client configuration. A copy is taken.

Does NOT bind the socket or start the receive loop. Call start().

function ~discv5_client¶

~discv5_client()

function discv5_client¶

discv5_client(
    const discv5_client & 
) =delete

function operator=¶

discv5_client & operator=(
    const discv5_client & 
) =delete

function discv5_client¶

discv5_client(
    discv5_client && 
) =delete

function operator=¶

discv5_client & operator=(
    discv5_client && 
) =delete

function add_bootnode¶

void add_bootnode(
    const std::string & enr_uri
)

Add a single bootstrap ENR URI.

Parameters:

enr_uri "enr:…" or "enode://…" string.

May be called before or after start().

function set_peer_discovered_callback¶

void set_peer_discovered_callback(
    PeerDiscoveredCallback callback
)

Register the callback invoked for each newly discovered peer.

Parameters:

callback Called with a ValidatedPeer on every new discovery.

function set_error_callback¶

void set_error_callback(
    ErrorCallback callback
)

Register the error callback.

Parameters:

callback Called with a diagnostic string on non-fatal errors.

function start¶

VoidResult start()

Bind the UDP socket and start the receive + crawler loops.

Return: success, or a discv5Error on socket/bind failure.

function stop¶

void stop()

Close the UDP socket and signal the crawler to stop.

function stats¶

CrawlerStats stats() const

Return a snapshot of current crawler activity counters.

function local_node_id¶

const NodeId & local_node_id() const

Return the local node identifier (64-byte public key).

function is_running¶

bool is_running() const

Returns true when the client has been started and not yet stopped.

function bound_port¶

uint16_t bound_port() const

Return the local UDP port the socket is currently bound to. Useful in tests when bind_port is 0 (ephemeral OS-assigned port).

function received_packet_count¶

size_t received_packet_count() const

Return the number of non-undersized UDP packets accepted by the receive loop.

function dropped_undersized_packet_count¶

size_t dropped_undersized_packet_count() const

Return the number of undersized UDP packets dropped by the receive loop.

function send_findnode_failure_count¶

size_t send_findnode_failure_count() const

Return the number of FINDNODE send attempts that failed.

function whoareyou_packet_count¶

size_t whoareyou_packet_count() const

Return the number of valid WHOAREYOU packets parsed by the receive path.

function handshake_packet_count¶

size_t handshake_packet_count() const

Return the number of successfully decrypted handshake packets.

function outbound_handshake_attempt_count¶

size_t outbound_handshake_attempt_count() const

Return the number of outbound handshake send attempts.

function outbound_handshake_failure_count¶

size_t outbound_handshake_failure_count() const

Return the number of outbound handshake send attempts that failed.

function inbound_handshake_reject_auth_count¶

size_t inbound_handshake_reject_auth_count() const

Return the number of inbound handshake packets rejected during auth parsing.

function inbound_handshake_reject_challenge_count¶

size_t inbound_handshake_reject_challenge_count() const

Return the number of inbound handshake packets rejected due to missing/mismatched challenge state.

function inbound_handshake_reject_record_count¶

size_t inbound_handshake_reject_record_count() const

Return the number of inbound handshake packets rejected during ENR/identity validation.

function inbound_handshake_reject_crypto_count¶

size_t inbound_handshake_reject_crypto_count() const

Return the number of inbound handshake packets rejected during shared-secret/key derivation.

function inbound_handshake_reject_decrypt_count¶

size_t inbound_handshake_reject_decrypt_count() const

Return the number of inbound handshake packets rejected due to message decrypt failure.

function inbound_handshake_seen_count¶

size_t inbound_handshake_seen_count() const

Return the number of inbound handshake packets observed before validation.

function inbound_message_seen_count¶

size_t inbound_message_seen_count() const

Return the number of inbound MESSAGE packets observed before validation/decrypt.

function inbound_message_decrypt_fail_count¶

size_t inbound_message_decrypt_fail_count() const

Return the number of inbound MESSAGE packets that failed decrypt with a matching session.

function nodes_packet_count¶

size_t nodes_packet_count() const

Return the number of successfully decoded NODES packets.

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