Crate zebra_network

Networking code for Zebra.

Network Protocol Design

The Zcash network protocol is inherited from Bitcoin, which uses a stateful network protocol in which messages can arrive in any order (even before a handshake is complete!). The same Bitcoin message may be a request or a response depending on context.

Achieving Concurrency

This crate translates the legacy Zcash network protocol into a stateless, request-response oriented protocol defined by the Request and Response enums. zebra-network completely encapsulates all peer handling code behind a single [tower::Service] representing “the network”, which load-balances outbound Requests over available peers.

Unlike the underlying legacy network protocol, Zebra’s PeerSet [tower::Service] guarantees that each Request future will resolve to the correct Response, rather than an unrelated Response message.

Each peer connection is handled by a distinct peer::Connection task. The Zcash network protocol is bidirectional, so Zebra interprets incoming Zcash messages as either:

• Responses to previously sent outbound Requests, or
• inbound Requests to an internal [tower::Service] representing “this node”.

All connection state is isolated to individual peers, so this design is structurally immune to the recent ping attack.

Connection Pool

Because [tower::Service]s provide backpressure information, we can dynamically manage the size of the connection pool according to inbound and outbound demand. The inbound service can shed load when it is not ready for requests, causing those peer connections to close, and the outbound service can connect to additional peers when it is overloaded.

zebra-network Structure

[zebra-network::init] is the main entry point for zebra-network. It uses the following services, tasks, and endpoints:

Low-Level Network Connections

Inbound Zcash Listener Task:

• accepts inbound connections on the listener port
• initiates Zcash peer::Handshakes, which creates peer::Connection tasks for each inbound connection

Outbound Zcash Connector Service:

• initiates outbound connections to peer addresses
• initiates Zcash peer::Handshakes, which creates peer::Connection tasks for each outbound connection

Zebra uses direct TCP connections to share blocks and mempool transactions with other peers.

The isolated APIs provide anonymised TCP and Tor connections to individual peers. These isolated connections can be used to send user-generated transactions anonymously. Tor connections are currently disabled until arti-client’s dependency x25519-dalek v1.2.0 is updated to a higher version. See #5492.

Individual Peer Connections

Each new peer connection spawns the following tasks:

peer::Client Service:

• provides an interface for outbound requests to an individual peer
  • accepts Requests assigned to this peer by the PeerSet
  • sends each request to the peer as Zcash Message
  • waits for the inbound response Message from the peer, and returns it as a Response

peer::Connection Service:

• manages connection state: awaiting a request, or handling an inbound or outbound response
• provides an interface for inbound requests from an individual peer
  • accepts inbound Zcash Messages from this peer
  • handles each message as a Request to the inbound service
  • sends the Response to the peer as Zcash Messages
• drops peer connections if the inbound request queue is overloaded

Since the Zcash network protocol is bidirectional, inbound and outbound connections are handled using the same logic.

Connection Pool

PeerSet Network Service:

• provides an interface for other services and tasks running within this node to make requests to remote peers (“the rest of the network”)
  • accepts Requests from the local node
  • sends each request to a peer::Client using randomised load-balancing
  • returns the Response from the peer::Client

Inbound Network Service:

• provides an interface for remote peers to request data held by this node
  • accepts inbound Zcash Requests from peer::Connections
  • handles each message as a Request to the local node
  • sends the Response to the peer::Connection

Note: the inbound service is implemented by the [zebra-network::init] caller.

Peer Inventory Service:

• tracks gossiped inv advertisements for each peer
• updated before each PeerSet request is processed
• tracks missing inventory for each peer
• used by the PeerSet to route block and transaction requests to peers that have the requested data

Peer Discovery

AddressBook Service:

• maintains a list of peer addresses and associated connection attempt metadata
• address book metadata is used to prioritise peer connection attempts
• updated by an independent thread based on peer connection status changes
• caches peer addresses to disk regularly using an independent task

Initial Seed Peer Task: On startup:

• loads seed peers from the config, resolving them via DNS if required
• loads cached peer addresses from disk
• initiates new outbound peer connections to seed and cached peers
• adds seed and cached peer addresses to the AddressBook

Peer Crawler Task:

• discovers new peer addresses by sending Addr requests to connected peers
• initiates new outbound peer connections in response to application demand

Re-exports

• pub use crate::address_book_peers::AddressBookPeers;
• pub use crate::config::CacheDir;
• pub use crate::config::Config;

Modules

• address_book 🔒
  The AddressBook manages information about what peers exist, when they were seen, and what services they provide.
• address_book_peers
  A AddressBookPeers trait for getting the MetaAddr of recently live peers.
• address_book_updater 🔒
  The timestamp collector collects liveness information from peers.
• config
  Configuration for Zebra’s network communication.
• constants
  Definitions of Zebra network constants, including:
• isolated 🔒
  Creating isolated connections to specific peers.
• meta_addr 🔒
  An address-with-metadata type used in Bitcoin networking.
• peer 🔒
  Peer connection handling.
• peer_cache_updater 🔒
  An async task that regularly updates the peer cache on disk from the current address book.
• peer_set 🔒
• policies 🔒
• protocol 🔒
  Zcash network protocol handling.
• types
  Types used in the definition of Request, Response, and VersionMessage.

Structs

• AddressBook
  A database of peer listener addresses, their advertised services, and information on when they were last seen.
• Client
  The “client” duplex half of a peer connection.
• ConnectionInfo
  The metadata for a peer connection.
• PeerSocketAddr
  A thin wrapper for SocketAddr which hides peer IP addresses in logs and metrics.
• RetryLimit
  A very basic retry policy with a limited number of retry attempts.
• SharedPeerError
  A wrapper around Arc<PeerError> that implements Error.
• Version
  A protocol version number.
• VersionMessage
  A version message.

Enums

• ConnectedAddr
  The peer address that we are handshaking with.
• HandshakeError
  An error during a handshake with a remote peer.
• InventoryResponse
  A generic peer inventory response status.
• PeerAddrState
  Peer connection state, based on our interactions with the peer.
• PeerError
  An error related to peer connection handling.
• Request
  A network request, represented in internal format.
• Response
  A response to a network request, represented in internal format.

Constants

• MAX_TX_INV_IN_SENT_MESSAGE
  The maximum number of transaction inventory items in a network message received from a peer.

Functions

• canonical_peer_addr
  Transform a PeerSocketAddr into a canonical Zebra PeerSocketAddr, converting IPv6-mapped IPv4 addresses, and removing IPv6 scope IDs and flow information.
• connect_isolated
  Creates a Zcash peer connection using the provided data stream. This connection is completely isolated from all other node state.
• connect_isolated_tcp_direct
  Creates a direct TCP Zcash peer connection to addr. This connection is completely isolated from all other node state.
• connect_isolated_tcp_direct_with_inbound
  Creates an isolated Zcash peer connection using the provided data stream. This function is for testing purposes only.
• connect_isolated_with_inbound
  Creates an isolated Zcash peer connection using the provided data stream. This function is for testing purposes only.
• init
  Initialize a peer set, using a network config, inbound_service, and latest_chain_tip.

Type Aliases

• BoxError
  Type alias to make working with tower traits easier.