Struct Config 

pub struct Config {

    pub listen_addr: SocketAddr,
    pub external_addr: Option<SocketAddr>,
    pub network: Network,
    pub initial_mainnet_peers: IndexSet<String>,
    pub initial_testnet_peers: IndexSet<String>,
    pub cache_dir: CacheDir,
    pub identity_dir: PathBuf,
    pub zakura_node_secret_key: Option<ZakuraNodeSecretKey>,
    pub p2p_stack: P2pStack,
    pub zakura: ZakuraConfig,
    pub peerset_initial_target_size: usize,
    pub crawl_new_peer_interval: Duration,
    pub max_connections_per_ip: usize,
}

Configuration for networking code.

Fields

listen_addr: SocketAddr

The address on which this node should listen for connections.

Can be address:port or just address. If there is no configured port, Zakura will use the default port for the configured network.

address can be an IP address or a DNS name. DNS names are only resolved once, when Zakura starts up.

By default, Zakura listens on [::] (all IPv6 and IPv4 addresses). This enables dual-stack support, accepting both IPv4 and IPv6 connections.

If a specific listener address is configured, Zakura will advertise it to other nodes. But by default, Zakura uses an unspecified address (“[::]:port”), which is not advertised to other nodes.

Zakura does not currently support:

• Advertising a different external IP address #1890, or
• Auto-discovering its own external IP address #1893.

However, other Zakura instances compensate for unspecified or incorrect listener addresses by adding the external IP addresses of peers to their address books.

external_addr: Option<SocketAddr>

The external address of this node if any.

Zakura binds to listen_addr, but this can be an internal address if the node is behind a firewall, load balancer or NAT. This field can be used to advertise a different address to peers making it possible to receive inbound connections and contribute to the P2P network from behind a firewall, load balancer, or NAT.

network: Network

The network to connect to.

initial_mainnet_peers: IndexSet<String>

A list of initial peers for the peerset when operating on mainnet.

initial_testnet_peers: IndexSet<String>

A list of initial peers for the peerset when operating on testnet.

cache_dir: CacheDir

An optional root directory for storing cached peer address data.

Configuration

Set to:

• true to read and write peer addresses to disk using the default cache path,
• false to disable reading and writing peer addresses to disk,
• '/custom/cache/directory' to read and write peer addresses to a custom directory.

By default, all Zakura instances run by the same user will share a single peer cache. If you use a custom cache path, you might also want to change state.cache_dir.

Functionality

The peer cache is a list of the addresses of some recently useful peers.

For privacy reasons, the cache does not include any other information about peers, such as when they were connected to the node.

Deleting or modifying the peer cache can impact your node’s:

• reliability: if DNS or the Zcash DNS seeders are unavailable or broken
• security: if DNS is compromised with malicious peers

If you delete it, Zakura will replace it with a fresh set of peers from the DNS seeders.

Defaults

The default directory is platform dependent, based on dirs::cache_dir():

Platform	Value	Example
Linux	$XDG_CACHE_HOME/zakura or $HOME/.cache/zakura	/home/alice/.cache/zakura
macOS	$HOME/Library/Caches/zakura	/Users/Alice/Library/Caches/zakura
Windows	{FOLDERID_LocalAppData}\zakura	C:\Users\Alice\AppData\Local\zakura
Other	std::env::current_dir()/cache/zakura	/cache/zakura

Security

If you are running Zakura with elevated permissions (“root”), create the directory for this file before running Zakura, and make sure the Zakura user account has exclusive access to that directory, and other users can’t modify its parent directories.

Implementation Details

Each network has a separate peer list, which is updated regularly from the current address book. These lists are stored in network/mainnet.peers and network/testnet.peers files, underneath the cache_dir path.

Previous peer lists are automatically loaded at startup, and used to populate the initial peer set and address book.

identity_dir: PathBuf

The directory for long-term network identity secrets.

The auto-generated Zakura iroh identity key is stored under this directory as <network>.zakura-iroh-secret-key. Keep this directory outside state or cache snapshot paths, or snapshots can clone the node’s long-term P2P identity.

The default is ~/.zakura.

zakura_node_secret_key: Option<ZakuraNodeSecretKey>

An optional persistent iroh secret key for Zakura P2P identity.

This is reserved for Zakura endpoint construction. If unset, a future Zakura endpoint implementation will generate an ed25519 iroh SecretKey on first use and persist it under identity_dir, outside Zakura’s cache and state directories by default.

This value is not used by the legacy TCP peer set.

p2p_stack: P2pStack

The peer-to-peer stack Zakura runs.

zakura.toml value	Stack
"default"	The configured network’s binary default
"legacy"	The legacy TCP Zcash P2P stack only
"zakura"	The experimental native Zakura P2P v2 stack only
"dual"	Both stacks, enabling experimental v2 with legacy fallback

Leave this at "default" so Zakura can change the per-network default during upgrades. See P2pStack::resolve for the current defaults, and legacy_p2p and v2_p2p for the resolved stack.

zakura: ZakuraConfig

Native Zakura endpoint, connection, and bootstrap settings.

When v2_p2p is false, these settings are parsed but no iroh endpoint is started. The total intended connection budget is roughly peerset_initial_target_size + zakura.max_connections; tune both together.

peerset_initial_target_size: usize

The initial target size for the peer set.

Also used to limit the number of inbound and outbound connections made by Zakura, and the size of the cached peer list.

If you have a slow network connection, and Zakura is having trouble syncing, try reducing the peer set size. You can also reduce the peer set size to reduce Zakura’s bandwidth usage.

crawl_new_peer_interval: Duration

How frequently we attempt to crawl the network to discover new peer addresses.

Zakura asks its connected peers for more peer addresses:

• regularly, every time crawl_new_peer_interval elapses, and
• if the peer set is busy, and there aren’t any peer addresses for the next connection attempt.

max_connections_per_ip: usize

The maximum number of legacy TCP peer connections Zakura will keep for a given IP address before it drops any additional legacy peer connections with that IP.

The default and minimum value are 1.

Zakura uses ZakuraConfig::max_connections_per_ip for native v2 admission.

Security

Increasing this config above 1 reduces Zakura’s network security.

If this config is greater than 1, Zakura can initiate multiple outbound handshakes to the same IP address.

This config does not currently limit the number of inbound connections that Zakura will accept from the same IP address.

If Zakura makes multiple inbound or outbound connections to the same IP, they will be dropped after the handshake, but before adding them to the peer set. The total numbers of inbound and outbound connections are also limited to a multiple of peerset_initial_target_size.

Implementations

impl Config

pub fn peerset_outbound_connection_limit(&self) -> usize

The maximum number of outbound connections that Zakura will open at the same time. When this limit is reached, Zakura stops opening outbound connections.

Security

See the note at INBOUND_PEER_LIMIT_MULTIPLIER.

Performance

Zakura’s peer set should be limited to a reasonable size, to avoid queueing too many in-flight block downloads. A large queue of in-flight block downloads can choke a constrained local network connection.

We assume that Zakura nodes have at least 10 Mbps bandwidth. Therefore, a maximum-sized block can take up to 2 seconds to download. So the initial outbound peer set adds up to 100 seconds worth of blocks to the queue. If Zakura has reached its outbound peer limit, that adds an extra 200 seconds of queued blocks.

But the peer set for slow nodes is typically much smaller, due to the handshake RTT timeout. And Zakura responds to inbound request overloads by dropping peer connections.

pub fn peerset_inbound_connection_limit(&self) -> usize

The maximum number of inbound connections that Zakura will accept at the same time. When this limit is reached, Zakura drops new inbound connections, without handshaking on them.

Security

See the note at INBOUND_PEER_LIMIT_MULTIPLIER.

pub fn peerset_total_connection_limit(&self) -> usize

The maximum number of inbound and outbound connections that Zakura will have at the same time.

pub fn initial_peer_hostnames(&self) -> IndexSet<String>

Returns the initial seed peer hostnames for the configured network.

pub async fn initial_peers(&self) -> HashSet<PeerSocketAddr>

Resolve initial seed peer IP addresses, based on the configured network, and load cached peers from disk, if available.

Panics

If a configured address is an invalid SocketAddr or DNS name.

pub async fn load_peer_cache(&self) -> Result<HashSet<PeerSocketAddr>>

Returns the addresses in the peer list cache file, if available.

pub async fn update_peer_cache( &self, peer_list: HashSet<PeerSocketAddr>, ) -> Result<()>

Atomically writes a new peer_list to the peer list cache file, if configured. If the list is empty, keeps the previous cache file.

Also creates the peer cache directory, if it doesn’t already exist.

Atomic writes avoid corrupting the cache if Zakura panics or crashes, or if multiple Zakura instances try to read and write the same cache file.

pub fn zakura_secret_key(&self) -> Result<SecretKey, ZakuraSecretKeyError>

Resolves the Zakura native iroh SecretKey for this node, persisting a freshly generated key on first use so the node keeps a stable NodeId across restarts.

Resolution order:

1. If zakura_node_secret_key is configured, it is parsed and used verbatim. An unparsable value is a hard error.
2. Otherwise, the persisted key file under identity_dir is loaded; when it is missing or unreadable a fresh key is generated and written atomically with owner-only (0o600) permissions, so every later startup reuses the same identity.
3. If the key cannot be persisted, the freshly generated identity is used ephemerally for this run.

Security

The persisted key file is the node’s long-term private identity. It is written outside the cache and state directories and restricted to owner read/write on Unix.

pub fn legacy_p2p(&self) -> bool

Returns true if Zakura should run the legacy TCP Zcash P2P listener, initial peer dialing, and peer crawler on the configured network.

pub fn v2_p2p(&self) -> bool

Returns true if Zakura should run the native Zakura P2P v2 endpoint on the configured network, advertise the P2P v2 service bit during the legacy Zcash handshake, and route mutually capable peers to the Zakura upgrade hook.

Trait Implementations

impl Clone for Config

fn clone(&self) -> Config

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Config

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Config

fn default() -> Config

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for Config

fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>

where D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Eq for Config

impl PartialEq for Config

fn eq(&self, other: &Config) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl Serialize for Config

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl StructuralPartialEq for Config