Struct AddressBook

pub struct AddressBook { /* private fields */ }

A database of peer listener addresses, their advertised services, and information on when they were last seen.

Security

Address book state must be based on outbound connections to peers.

If the address book is updated incorrectly:

• malicious peers can interfere with other peers’ AddressBook state, or
• Zebra can advertise unreachable addresses to its own peers.

Adding Addresses

The address book should only contain Zcash listener port addresses from peers on the configured network. These addresses can come from:

• DNS seeders
• addresses gossiped by other peers
• the canonical address (Version.address_from) provided by each peer, particularly peers on inbound connections.

The remote addresses of inbound connections must not be added to the address book, because they contain ephemeral outbound ports, not listener ports.

Isolated connections must not add addresses or update the address book.

Updating Address State

Updates to address state must be based on outbound connections to peers.

Updates must not be based on:

• the remote addresses of inbound connections, or
• the canonical address of any connection.

Implementations

impl AddressBook

pub fn new( local_listener: SocketAddr, network: &Network, max_connections_per_ip: usize, span: Span, ) -> AddressBook

Construct an AddressBook with the given local_listener on network.

Uses the supplied tracing::Span for address book operations.

pub fn address_metrics_watcher(&self) -> Receiver<AddressMetrics>

Return a watch channel for the address book metrics.

The metrics in the watch channel are only updated when the address book updates, so they can be significantly outdated if Zebra is disconnected or hung.

The current metrics value is marked as seen. So Receiver::changed will only return after the next address book update.

pub fn local_listener_meta_addr(&self, now: DateTime<Utc>) -> MetaAddr

Get the local listener address.

This address contains minimal state, but it is not sanitized.

pub fn local_listener_socket_addr(&self) -> SocketAddr

Get the local listener SocketAddr.

pub fn fresh_get_addr_response(&self) -> Vec<MetaAddr>

Get the active addresses in self in random order with sanitized timestamps, including our local listener address.

Limited to the number of peer addresses Zebra should give out per GetAddr request.

pub fn cacheable(&self, now: DateTime<Utc>) -> Vec<MetaAddr>

Get the active addresses in self, in preferred caching order, excluding our local listener address.

pub fn get(&mut self, addr: PeerSocketAddr) -> Option<MetaAddr>

Look up addr in the address book, and return its MetaAddr.

Converts addr to a canonical address before looking it up.

pub fn update(&mut self, change: MetaAddrChange) -> Option<MetaAddr>

Apply change to the address book, returning the updated MetaAddr, if the change was valid.

Correctness

All changes should go through update, so that the address book only contains valid outbound addresses.

Change addresses must be canonical PeerSocketAddrs. This makes sure that each address book entry has a unique IP address.

Security

This function must apply every attempted, responded, and failed change to the address book. This prevents rapid reconnections to the same peer.

As an exception, this function can ignore all changes for specific PeerSocketAddrs. Ignored addresses will never be used to connect to peers.

pub fn pending_reconnection_addr(&mut self, addr: PeerSocketAddr) -> bool

Returns true if the given PeerSocketAddr is pending a reconnection attempt.

pub fn peers(&self) -> impl DoubleEndedIterator<Item = MetaAddr> + '_

Return an iterator over all peers.

Returns peers in reconnection attempt order, including recently connected peers.

pub fn reconnection_peers( &self, instant_now: Instant, chrono_now: DateTime<Utc>, ) -> impl DoubleEndedIterator<Item = MetaAddr> + '_

Return an iterator over peers that are due for a reconnection attempt, in reconnection attempt order.

pub fn state_peers( &self, state: PeerAddrState, ) -> impl DoubleEndedIterator<Item = MetaAddr> + '_

Return an iterator over all the peers in state, in reconnection attempt order, including recently connected peers.

pub fn maybe_connected_peers( &self, instant_now: Instant, chrono_now: DateTime<Utc>, ) -> impl DoubleEndedIterator<Item = MetaAddr> + '_

Return an iterator over peers that might be connected, in reconnection attempt order.

pub fn bans(&self) -> Arc<IndexMap<IpAddr, Instant>>

Returns banned IP addresses.

pub fn len(&self) -> usize

Returns the number of entries in this address book.

Trait Implementations

impl AddressBookPeers for AddressBook

fn recently_live_peers(&self, now: DateTime<Utc>) -> Vec<MetaAddr>

Return an Vec of peers we’ve seen recently, in reconnection attempt order.

impl Clone for AddressBook

fn clone(&self) -> AddressBook

Clone the addresses, address limit, local listener address, and span.

Cloned address books have a separate metrics struct watch channel, and an empty last address log.

All address books update the same prometheus metrics.

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

Performs copy-assignment from source.

impl Debug for AddressBook

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

Formats the value using the given formatter.