discv4/chain_peers.hpp¶

Namespaces¶

Name
discv4

Classes¶

	Name
struct	discv4::ChainPeerCacheRefreshResult Result of refreshing the local chain peer cache from a remote URL.
struct	discv4::ChainPeerConfig Parsed chain configuration shared across peer discovery and ETH session setup.
struct	discv4::ChainPeerCacheSignatureVerificationResult Verification result for a signed chain peer cache JSON document.

Types¶

	Name
enum class	ChainDiscoveryDefault
enum class	DiscoveryForkFilter

Functions¶

	Name
std::filesystem::path	chain_peer_cache_json_path(const std::string & argv0) Return the default local cache path for `chain_enodes.json` next to the executable.
std::optional< std::filesystem::path >	find_chain_peer_cache_json_path(const std::string & argv0, const std::string & override_path) Locate a local chain peer cache JSON file.
std::optional< std::string >	download_chain_peer_cache_json(const std::string & url) Download the chain peer cache JSON payload from a remote URL. Supports either raw JSON or gzip-compressed JSON bodies.
bool	write_chain_peer_cache_json_if_changed(const std::filesystem::path & json_path, const std::string & json_text) Write the chain peer JSON cache only when the contents changed.
std::optional< ChainPeerCacheRefreshResult >	refresh_chain_peer_cache_json(const std::filesystem::path & json_path, const std::string & url) Refresh a local chain peer cache from a remote URL.
std::optional< ValidatedPeer >	make_validated_peer_from_enode(const std::string & enode) Parse an `enode://` peer URI into a validated peer entry.
std::optional< ValidatedPeer >	make_validated_peer_from_enr(const std::string & enr_uri) Parse an `enr:` peer URI into a validated peer entry.
std::vector< ValidatedPeer >	load_chain_peers_from_json_text(const std::string & chain_name, const std::string & json_text) Load cached peers for a specific chain from JSON text.
std::vector< ValidatedPeer >	load_chain_peers_from_json(const std::string & chain_name, const std::filesystem::path & json_path) Load cached peers for a specific chain from a JSON or gzip-compressed JSON file.
std::optional< std::array< uint8_t, 4 > >	load_chain_fork_id_hash_from_json_text(const std::string & chain_name, const std::string & json_text) Load the first available peer fork hash for a specific chain from JSON text.
std::optional< std::array< uint8_t, 4 > >	load_chain_fork_id_hash_from_json(const std::string & chain_name, const std::filesystem::path & json_path) Load the first available peer fork hash for a specific chain from a JSON or gzip-compressed JSON file.
std::optional< ChainPeerConfig >	load_chain_peer_config_from_json_text(const std::string & chain_name, const std::string & json_text) Load the parsed chain configuration from JSON text.
std::optional< ChainPeerConfig >	load_chain_peer_config_from_json(const std::string & chain_name, const std::filesystem::path & json_path) Load the parsed chain configuration from a JSON or gzip-compressed JSON file.
ChainPeerCacheSignatureVerificationResult	verify_chain_peer_cache_json_signature(const std::string & json_text, const std::string & expected_signer_address) Verify the top-level `chain_enodes.json` signature.

Types Documentation¶

enum ChainDiscoveryDefault¶

Enumerator	Value	Description
kAuto
kDiscv4
kCacheEnrDiscv5
kEnrTree

enum DiscoveryForkFilter¶

Enumerator	Value	Description
kRequire
kDisabled

Functions Documentation¶

function chain_peer_cache_json_path¶

std::filesystem::path chain_peer_cache_json_path(
    const std::string & argv0
)

Return the default local cache path for chain_enodes.json next to the executable.

Parameters:

argv0 Program path used to locate the executable directory.

Return: Cache file path.

function find_chain_peer_cache_json_path¶

std::optional< std::filesystem::path > find_chain_peer_cache_json_path(
    const std::string & argv0,
    const std::string & override_path
)

Locate a local chain peer cache JSON file.

Parameters:

argv0 Program path used to locate the executable directory.
override_path Optional explicit file path.

Return: Existing JSON or gzip-compressed JSON file path, or std::nullopt if none exists.

function download_chain_peer_cache_json¶

std::optional< std::string > download_chain_peer_cache_json(
    const std::string & url
)

Download the chain peer cache JSON payload from a remote URL. Supports either raw JSON or gzip-compressed JSON bodies.

Parameters:

url Source URL.

Return: Decoded JSON text, or std::nullopt on failure.

function write_chain_peer_cache_json_if_changed¶

bool write_chain_peer_cache_json_if_changed(
    const std::filesystem::path & json_path,
    const std::string & json_text
)

Write the chain peer JSON cache only when the contents changed.

Parameters:

json_path Destination cache path.
json_text JSON text to store.

Return: true when the cache contents changed and were rewritten.

function refresh_chain_peer_cache_json¶

std::optional< ChainPeerCacheRefreshResult > refresh_chain_peer_cache_json(
    const std::filesystem::path & json_path,
    const std::string & url
)

Refresh a local chain peer cache from a remote URL.

Parameters:

json_path Destination cache path.
url Source URL.

Return: Refresh metadata when download succeeded, or std::nullopt on failure.

function make_validated_peer_from_enode¶

std::optional< ValidatedPeer > make_validated_peer_from_enode(
    const std::string & enode
)

Parse an enode:// peer URI into a validated peer entry.

Parameters:

enode Peer URI.

Return: Parsed validated peer, or std::nullopt when the URI is malformed.

function make_validated_peer_from_enr¶

std::optional< ValidatedPeer > make_validated_peer_from_enr(
    const std::string & enr_uri
)

Parse an enr: peer URI into a validated peer entry.

Parameters:

enr_uri Peer ENR URI.

Return: Parsed validated peer, or std::nullopt when the URI is malformed.

function load_chain_peers_from_json_text¶

std::vector< ValidatedPeer > load_chain_peers_from_json_text(
    const std::string & chain_name,
    const std::string & json_text
)

Load cached peers for a specific chain from JSON text.

Parameters:

chain_name Canonical top-level JSON key.
json_text JSON document contents.

Return: Parsed validated peers.

function load_chain_peers_from_json¶

std::vector< ValidatedPeer > load_chain_peers_from_json(
    const std::string & chain_name,
    const std::filesystem::path & json_path
)

Load cached peers for a specific chain from a JSON or gzip-compressed JSON file.

Parameters:

chain_name Canonical top-level JSON key.
json_path JSON file path.

Return: Parsed validated peers.

function load_chain_fork_id_hash_from_json_text¶

std::optional< std::array< uint8_t, 4 > > load_chain_fork_id_hash_from_json_text(
    const std::string & chain_name,
    const std::string & json_text
)

Load the first available peer fork hash for a specific chain from JSON text.

Parameters:

chain_name Canonical top-level JSON key.
json_text JSON document contents.

Return: 4-byte fork hash when present, or std::nullopt.

function load_chain_fork_id_hash_from_json¶

std::optional< std::array< uint8_t, 4 > > load_chain_fork_id_hash_from_json(
    const std::string & chain_name,
    const std::filesystem::path & json_path
)

Load the first available peer fork hash for a specific chain from a JSON or gzip-compressed JSON file.

Parameters:

chain_name Canonical top-level JSON key.
json_path JSON file path.

Return: 4-byte fork hash when present, or std::nullopt.

function load_chain_peer_config_from_json_text¶

std::optional< ChainPeerConfig > load_chain_peer_config_from_json_text(
    const std::string & chain_name,
    const std::string & json_text
)

Load the parsed chain configuration from JSON text.

Parameters:

chain_name Canonical top-level JSON key.
json_text JSON document contents.

Return: Parsed chain config, or std::nullopt when missing or invalid.

function load_chain_peer_config_from_json¶

std::optional< ChainPeerConfig > load_chain_peer_config_from_json(
    const std::string & chain_name,
    const std::filesystem::path & json_path
)

Load the parsed chain configuration from a JSON or gzip-compressed JSON file.

Parameters:

chain_name Canonical top-level JSON key.
json_path JSON file path.

Return: Parsed chain config, or std::nullopt when missing or invalid.

function verify_chain_peer_cache_json_signature¶

ChainPeerCacheSignatureVerificationResult verify_chain_peer_cache_json_signature(
    const std::string & json_text,
    const std::string & expected_signer_address
)

Verify the top-level chain_enodes.json signature.

Parameters:

json_text JSON document contents.
expected_signer_address Expected Ethereum signer address.

Return: Verification result.

Source code¶

// Copyright 2026 Genius Ventures, Inc.
// SPDX-License-Identifier: MIT

#ifndef EVMRELAY_INCLUDE_DISCV4_CHAIN_PEERS_HPP
#define EVMRELAY_INCLUDE_DISCV4_CHAIN_PEERS_HPP

#include <discv4/dial_scheduler.hpp>
#include <eth/eth_types.hpp>
#include <filesystem>
#include <optional>
#include <string>
#include <vector>

namespace discv4
{

enum class ChainDiscoveryDefault
{
    kAuto,
    kDiscv4,
    kCacheEnrDiscv5,
    kEnrTree
};

enum class DiscoveryForkFilter
{
    kRequire,
    kDisabled
};

struct ChainPeerCacheRefreshResult
{
    std::filesystem::path cache_path;
    bool                  cache_available = false;
    bool                  cache_updated = false;
};

struct ChainPeerConfig
{
    std::string                canonical_name;
    uint64_t                   network_id = 0;
    eth::Hash256               genesis_hash{};
    std::vector<ValidatedPeer> nodes;
    std::vector<ValidatedPeer> bootnodes;
    std::vector<std::string>   discv5_bootnodes;
    std::vector<std::string>   enr_trees;
    ChainDiscoveryDefault      discovery_default = ChainDiscoveryDefault::kAuto;
    DiscoveryForkFilter        discovery_fork_filter = DiscoveryForkFilter::kRequire;
    std::optional<eth::ForkId> fork_id;
    std::vector<eth::EthMessageSchema> eth_message_schemas;
    std::string                signature;
    std::string                signer_address;
};

struct ChainPeerCacheSignatureVerificationResult
{
    bool        has_signature = false;
    bool        signature_valid = false;
    std::string signer_address;
};

std::filesystem::path chain_peer_cache_json_path(const std::string& argv0);

std::optional<std::filesystem::path> find_chain_peer_cache_json_path(
    const std::string& argv0,
    const std::string& override_path);

std::optional<std::string> download_chain_peer_cache_json(const std::string& url);

bool write_chain_peer_cache_json_if_changed(
    const std::filesystem::path& json_path,
    const std::string&           json_text);

std::optional<ChainPeerCacheRefreshResult> refresh_chain_peer_cache_json(
    const std::filesystem::path& json_path,
    const std::string&           url);

std::optional<ValidatedPeer> make_validated_peer_from_enode(const std::string& enode);

std::optional<ValidatedPeer> make_validated_peer_from_enr(const std::string& enr_uri);

std::vector<ValidatedPeer> load_chain_peers_from_json_text(
    const std::string& chain_name,
    const std::string& json_text);

std::vector<ValidatedPeer> load_chain_peers_from_json(
    const std::string&            chain_name,
    const std::filesystem::path&  json_path);

std::optional<std::array<uint8_t, 4>> load_chain_fork_id_hash_from_json_text(
    const std::string& chain_name,
    const std::string& json_text);

std::optional<std::array<uint8_t, 4>> load_chain_fork_id_hash_from_json(
    const std::string&           chain_name,
    const std::filesystem::path& json_path);

std::optional<ChainPeerConfig> load_chain_peer_config_from_json_text(
    const std::string& chain_name,
    const std::string& json_text);

std::optional<ChainPeerConfig> load_chain_peer_config_from_json(
    const std::string&           chain_name,
    const std::filesystem::path& json_path);

ChainPeerCacheSignatureVerificationResult verify_chain_peer_cache_json_signature(
    const std::string& json_text,
    const std::string& expected_signer_address);

} // namespace discv4

#endif // EVMRELAY_INCLUDE_DISCV4_CHAIN_PEERS_HPP

Updated on 2026-06-05 at 17:22:18 -0700