Enum Request

pub enum Request {
    Peers,
    BlocksByHash(HashSet<Hash>),
    TransactionsById(HashSet<UnminedTxId>),
    FindBlocks {
        known_blocks: Vec<Hash>,
        stop: Option<Hash>,
    },
    FindHeaders {
        known_blocks: Vec<Hash>,
        stop: Option<Hash>,
    },
    PushTransaction(UnminedTx),
    AdvertiseTransactionIds(HashSet<UnminedTxId>),
    AdvertiseBlock(Hash),
    MempoolTransactionIds,
    // some variants omitted
}

A network request, represented in internal format.

The network layer aims to abstract away the details of the Bitcoin wire protocol into a clear request/response API. Each Request documents the possible Responses it can generate; it is fine (and recommended!) to match on the expected responses and treat the others as unreachable!(), since their return indicates a bug in the network code.

Cancellations

The peer set handles cancelled requests (i.e., requests where the future returned by Service::call is dropped before it resolves) on a best-effort basis. Requests are routed to a particular peer connection, and then translated into Zcash protocol messages and sent over the network. If a request is cancelled after it is submitted but before it is processed by a peer connection, no messages will be sent. Otherwise, if it is cancelled while waiting for a response, the peer connection resets its state and makes a best-effort attempt to ignore any messages responsive to the cancelled request, subject to limitations in the underlying Zcash protocol.

Variants

Peers

Requests additional peers from the server.

Response

Returns Response::Peers.

BlocksByHash(HashSet<Hash>)

Request block data by block hashes.

This uses a HashSet rather than a Vec for two reasons. First, it automatically deduplicates the requested blocks. Second, the internal protocol translator needs to maintain a HashSet anyways, in order to keep track of which requested blocks have been received and when the request is ready. Rather than force the internals to always convert into a HashSet, we require the caller to pass one, so that if the caller didn’t start with a Vec but with, e.g., an iterator, they can collect directly into a HashSet and save work.

If this requests a recently-advertised block, the peer set will make a best-effort attempt to route the request to a peer that advertised the block. This routing is only used for request sets of size 1. Otherwise, it is routed using the normal load-balancing strategy.

The list contains zero or more block hashes.

Returns

Returns Response::Blocks.

TransactionsById(HashSet<UnminedTxId>)

Request transactions by their unmined transaction ID.

v4 transactions use a legacy transaction ID, and v5 transactions use a witnessed transaction ID.

This uses a HashSet for the same reason as Request::BlocksByHash.

If this requests a recently-advertised transaction, the peer set will make a best-effort attempt to route the request to a peer that advertised the transaction. This routing is only used for request sets of size 1. Otherwise, it is routed using the normal load-balancing strategy.

The list contains zero or more unmined transaction IDs.

Returns

Returns Response::Transactions.

FindBlocks

Request block hashes of subsequent blocks in the chain, given hashes of known blocks.

The known blocks list contains zero or more block hashes.

Returns

Returns Response::BlockHashes.

Warning

This is implemented by sending a getblocks message. Bitcoin nodes respond to getblocks with an inv message containing a list of the subsequent blocks. However, Bitcoin nodes also send inv messages unsolicited in order to gossip new blocks to their peers. These gossip messages can race with the response to a getblocks request, and there is no way for the network layer to distinguish them. For this reason, the response may occasionally contain a single hash of a new chain tip rather than a list of hashes of subsequent blocks. We believe that unsolicited inv messages will always have exactly one block hash.

Fields

known_blocks: Vec<Hash>

Hashes of known blocks, ordered from highest height to lowest height.

stop: Option<Hash>

Optionally, the last block hash to request.

FindHeaders

Request headers of subsequent blocks in the chain, given hashes of known blocks.

The known blocks list contains zero or more block hashes.

Returns

Returns Response::BlockHeaders.

Fields

known_blocks: Vec<Hash>

Hashes of known blocks, ordered from highest height to lowest height.

stop: Option<Hash>

Optionally, the last header to request.

PushTransaction(UnminedTx)

Push an unmined transaction to a remote peer, without advertising it to them first.

This is implemented by sending an unsolicited tx message.

Returns

Returns Response::Nil.

AdvertiseTransactionIds(HashSet<UnminedTxId>)

Advertise a set of unmined transactions to all peers.

Both Zebra and zcashd sometimes advertise multiple transactions at once.

This is implemented by sending an inv message containing the unmined transaction IDs, allowing the remote peer to choose whether to download them. Remote peers who choose to download the transaction will generate a Request::TransactionsById against the “inbound” service passed to init.

v4 transactions use a legacy transaction ID, and v5 transactions use a witnessed transaction ID.

The list contains zero or more transaction IDs.

The peer set routes this request specially, sending it to half of the available peers.

Returns

Returns Response::Nil.

AdvertiseBlock(Hash)

Advertise a block to all peers.

This is implemented by sending an inv message containing the block hash, allowing the remote peer to choose whether to download it. Remote peers who choose to download the block will generate a Request::BlocksByHash against the “inbound” service passed to init.

The peer set routes this request specially, sending it to half of the available peers.

Returns

Returns Response::Nil.

MempoolTransactionIds

Request the contents of this node’s mempool.

Returns

Returns Response::TransactionIds.

Implementations

impl Request

pub fn command(&self) -> &'static str

Returns the Zebra internal request type as a string.

pub fn is_inventory_download(&self) -> bool

Returns true if the request is for block or transaction inventory downloads.

pub fn block_hash_inventory(&self) -> HashSet<Hash>

Returns the block hash inventory downloads from the request, if any.

pub fn transaction_id_inventory(&self) -> HashSet<UnminedTxId>

Returns the transaction ID inventory downloads from the request, if any.

Trait Implementations

impl Arbitrary for Request

type Parameters = (<Nonce as Arbitrary>::Parameters, <HashSet<Hash> as Arbitrary>::Parameters, <HashSet<UnminedTxId> as Arbitrary>::Parameters, (<Vec<Hash> as Arbitrary>::Parameters, <Option<Hash> as Arbitrary>::Parameters), (<Vec<Hash> as Arbitrary>::Parameters, <Option<Hash> as Arbitrary>::Parameters), <UnminedTx as Arbitrary>::Parameters, <HashSet<UnminedTxId> as Arbitrary>::Parameters, <Hash as Arbitrary>::Parameters)

The type of parameters that arbitrary_with accepts for configuration of the generated Strategy. Parameters must implement Default.

type Strategy = TupleUnion<((u32, Arc<fn() -> Request>), (u32, Arc<Map<<Nonce as Arbitrary>::Strategy, fn(_: Nonce) -> Request>>), (u32, Arc<Map<<HashSet<Hash> as Arbitrary>::Strategy, fn(_: HashSet<Hash>) -> Request>>), (u32, Arc<Map<<HashSet<UnminedTxId> as Arbitrary>::Strategy, fn(_: HashSet<UnminedTxId>) -> Request>>), (u32, Arc<Map<(<Vec<Hash> as Arbitrary>::Strategy, <Option<Hash> as Arbitrary>::Strategy), fn(_: (Vec<Hash>, Option<Hash>)) -> Request>>), (u32, Arc<Map<(<Vec<Hash> as Arbitrary>::Strategy, <Option<Hash> as Arbitrary>::Strategy), fn(_: (Vec<Hash>, Option<Hash>)) -> Request>>), (u32, Arc<Map<<UnminedTx as Arbitrary>::Strategy, fn(_: UnminedTx) -> Request>>), (u32, Arc<Map<<HashSet<UnminedTxId> as Arbitrary>::Strategy, fn(_: HashSet<UnminedTxId>) -> Request>>), (u32, Arc<Map<<Hash as Arbitrary>::Strategy, fn(_: Hash) -> Request>>), (u32, Arc<fn() -> Request>))>

The type of Strategy used to generate values of type Self.

fn arbitrary_with(_top: Self::Parameters) -> Self::Strategy

Generates a Strategy for producing arbitrary values of type the implementing type (Self). The strategy is passed the arguments given in args.

fn arbitrary() -> Self::Strategy

Generates a Strategy for producing arbitrary values of type the implementing type (Self).

impl Clone for Request

fn clone(&self) -> Request

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for Request

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

Formats the value using the given formatter.

impl Display for Request

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

Formats the value using the given formatter.

impl From<Request> for InboundMessage

fn from(request: Request) -> Self

Converts to this type from the input type.

impl PartialEq for Request

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

Tests for self and other values to be equal, and is used by ==.

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Service<Request> for Client

type Response = Response

Responses given by the service.

type Error = SharedPeerError

Errors produced by the service.

type Future = Pin<Box<dyn Future<Output = Result<<Client as Service<Request>>::Response, <Client as Service<Request>>::Error>> + Send>>

The future response value.

fn poll_ready(&mut self, cx: &mut Context<'_>) -> Poll<Result<(), Self::Error>>

Returns Poll::Ready(Ok(())) when the service is able to process requests.

fn call(&mut self, request: Request) -> Self::Future

Process the request and return the response asynchronously.

impl<D, C> Service<Request> for PeerSet<D, C>

where D: Discover<Key = PeerSocketAddr, Service = LoadTrackedClient> + Unpin, D::Error: Into<BoxError>, C: ChainTip,

type Response = Response

Responses given by the service.

type Error = Box<dyn Error + Sync + Send>

Errors produced by the service.

type Future = Pin<Box<dyn Future<Output = Result<<PeerSet<D, C> as Service<Request>>::Response, <PeerSet<D, C> as Service<Request>>::Error>> + Send>>

The future response value.

fn poll_ready(&mut self, cx: &mut Context<'_>) -> Poll<Result<(), Self::Error>>

Returns Poll::Ready(Ok(())) when the service is able to process requests.

fn call(&mut self, req: Request) -> Self::Future

Process the request and return the response asynchronously.

impl Eq for Request

impl StructuralPartialEq for Request