Struct BlockSync

pub struct BlockSync<N: Network> { /* private fields */ }

A struct that keeps track of synchronizing blocks with other nodes.

It generates requests to send to other peers and processes responses to those requests. The struct also keeps track of block locators, which indicate which peers it can fetch blocks from.

Notes

• The actual network communication happens in snarkos_node::Client (for clients and provers) and in snarkos_node_bft::Sync (for validators).

• Validators only sync from other nodes using this struct if they fall behind, e.g., because they experience a network partition. In the common case, validators will generate blocks from the DAG after an anchor certificate has been approved by a supermajority of the committee.

Implementations

impl<N: Network> BlockSync<N>

pub fn new(ledger: Arc<dyn LedgerService<N>>) -> Self

Initializes a new block sync module.

pub async fn wait_for_update(&self)

pub fn is_block_synced(&self) -> bool

Returns true if the node is synced up to the latest block (within the given tolerance).

pub fn can_block_sync(&self) -> bool

Returns true if there a blocks to fetch or responses to process.

This will always return true if Self::is_block_synced returns false, but it can return true when Self::is_block_synced returns true (due to the latter having a tolerance of one block).

pub fn num_blocks_behind(&self) -> Option<u32>

Returns the number of blocks the node is behind the greatest peer height, or None if no peers are connected yet.

pub fn greatest_peer_block_height(&self) -> Option<u32>

Returns the greatest block height of any connected peer.

pub fn get_sync_height(&self) -> u32

Returns the current sync height of this node. The sync height is always greater or equal to the ledger height.

pub fn num_outstanding_block_requests(&self) -> usize

Returns the number of blocks we requested from peers, but have not received yet.

pub fn num_total_block_requests(&self) -> usize

The total number of block request, including the ones that have been answered already but not processed yet.

pub fn get_peer_heights(&self) -> HashMap<SocketAddr, u32>

pub fn get_block_requests_info(&self) -> BTreeMap<u32, BlockRequestInfo>

pub fn get_block_requests_summary(&self) -> BlockRequestsSummary

Returns a summary of all in-flight requests.

impl<N: Network> BlockSync<N>

pub fn get_block_locators(&self) -> Result<BlockLocators<N>>

Returns the block locators.

pub fn has_pending_responses(&self) -> bool

Returns true if there are pending responses to block requests that need to be processed.

pub async fn send_block_requests<C: CommunicationService>( &self, communication: &C, sync_peers: &IndexMap<SocketAddr, BlockLocators<N>>, requests: &[(u32, PrepareSyncRequest<N>)], ) -> bool

Send a batch of block requests.

pub fn insert_block_responses( &self, peer_ip: SocketAddr, blocks: Vec<Block<N>>, ) -> Result<()>

Inserts a new block response from the given peer IP.

Returns an error if the block was malformed, or we already received a different block for this height. This function also removes all block requests from the given peer IP on failure.

Note, that this only queues the response. After this, you most likely want to call Self::try_advancing_block_synchronization.

pub fn peek_next_block(&self, next_height: u32) -> Option<Block<N>>

Returns the next block for the given next_height if the request is complete, or None otherwise. This does not remove the block from the responses map.

pub async fn try_advancing_block_synchronization(&self) -> Result<bool>

Attempts to advance synchronization by processing completed block responses.

Returns true, if new blocks were added to the ledger.

Usage

This is only called in [Client::try_block_sync] and should not be called concurrently by multiple tasks. Validators do not call this function, and instead invoke [snarkos_node_bft::Sync::try_advancing_block_synchronization] which also updates the BFT state.

impl<N: Network> BlockSync<N>

pub fn find_sync_peers(&self) -> Option<(IndexMap<SocketAddr, u32>, u32)>

Returns the sync peers with their latest heights, and their minimum common ancestor, if the node can sync. This function returns peers that are consistent with each other, and have a block height that is greater than the ledger height of this node.

Locking

This will read-lock common_ancestors and sync_state, but not at the same time.

pub fn update_peer_locators( &self, peer_ip: SocketAddr, locators: BlockLocators<N>, ) -> Result<()>

Updates the block locators and common ancestors for the given peer IP.

This function does not need to check that the block locators are well-formed, because that is already done in BlockLocators::new(), as noted in BlockLocators.

This function does not check that the block locators are consistent with the peer’s previous block locators or other peers’ block locators.

pub fn remove_peer(&self, peer_ip: &SocketAddr)

TODO (howardwu): Remove the common_ancestor entry. But check that this is safe (that we don’t rely upon it for safety when we re-connect with the same peer). Removes the peer from the sync pool, if they exist.

impl<N: Network> BlockSync<N>

pub fn prepare_block_requests(&self) -> BlockRequestBatch<N>

Returns a list of block requests and the sync peers, if the node needs to sync.

You usually want to call remove_timed_out_block_requests before invoking this function.

Concurrency

This should be called by at most one task at a time.

Usage

• For validators, the primary spawns one task that periodically calls bft::Sync::try_block_sync. There is no possibility of multiple calls to it at a time.
• For clients, Client::initialize_sync also spawns exactly one task that periodically calls this function.
• Provers do not call this function.

pub fn set_sync_height(&self, new_height: u32)

Set the sync height to a the given value. This is a no-op if new_height is equal or less to the current sync height.

pub fn remove_block_response(&self, height: u32)

Removes the block request and response for the given height This may only be called after peek_next_block, which checked if the request for the given height was complete.

Precondition: This may only be called after peek_next_block has returned Some, which has checked if the request for the given height is complete and there is a block with the given height in the responses map.

pub fn handle_block_request_timeouts<C: CommunicationService>( &self, communication: &C, ) -> Option<BlockRequestBatch<N>>

Removes block requests that have timed out, i.e, requests we sent that did not receive a response in time.

This removes the corresponding block responses and returns the set of peers/addresses that timed out. It will ask the communication service to ban any timed-out peers.

Finally, it will return a set of new of block requests that replaced the timed-out requests (if needed).