Struct BlockLocators 

pub struct BlockLocators<N: Network> {
    pub recents: IndexMap<u32, N::BlockHash>,
    pub checkpoints: IndexMap<u32, N::BlockHash>,
}

Block locator maps.

This data structure is used by validators to advertise the blocks that they have and can provide to other validators to help them sync. Periodically, each validator broadcasts a [PrimaryPing], which contains a BlockLocators instance. Recall that blocks are indexed by their u32 height, starting with 0 for the genesis block. The keys of the recents and checkpoints maps are the block heights; the values of the maps are the corresponding block hashes.

If a validator has N blocks, the recents and checkpoints maps are as follows:

• The recents map contains entries for blocks at heights N - 1 - (NUM_RECENT_BLOCKS - 1) * RECENT_INTERVAL, N - 1 - (NUM_RECENT_BLOCKS - 2) * RECENT_INTERVAL, …, N - 1. If any of the just listed heights are negative, there are no entries for them of course, and the recents map has fewer than NUM_RECENT_BLOCKS entries. If RECENT_INTERVAL is 1, the recents map contains entries for the last NUM_RECENT_BLOCKS blocks, i.e. from N - NUM_RECENT_BLOCKS to N - 1; if additionally N < NUM_RECENT_BLOCKS, the recents map contains entries for all the blocks, from 0 to N - 1.
• The checkpoints map contains an entry for every CHECKPOINT_INTERVAL-th block, starting with 0 and not exceeding N, i.e. it has entries for blocks 0, CHECKPOINT_INTERVAL, 2 * CHECKPOINT_INTERVAL, …, k * CHECKPOINT_INTERVAL, where k is the maximum integer such that k * CHECKPOINT_INTERVAL <= N.

The recents and checkpoints maps may have overlapping entries, e.g. if N-1 is a multiple of CHECKPOINT_INTERVAL; but if CHECKPOINT_INTERVAL is much larger than NUM_RECENT_BLOCKS, there is no overlap most of the time.

We call BlockLocators with the form described above ‘well-formed’.

Well-formed BlockLocators instances are built by [BlockSync::get_block_locators()]. When a BlockLocators instance is received (in a [PrimaryPing]) by a validator, the maps may not be well-formed (if the sending validator is faulty), but the receiving validator ensures that they are well-formed by calling BlockLocators::ensure_is_valid() from BlockLocators::new(), when deserializing in BlockLocators::read_le(). So this well-formedness is an invariant of BlockLocators instances.

Fields

recents: IndexMap<u32, N::BlockHash>

The map of recent blocks.

checkpoints: IndexMap<u32, N::BlockHash>

The map of block checkpoints.

Implementations

impl<N: Network> BlockLocators<N>

pub fn new( recents: IndexMap<u32, N::BlockHash>, checkpoints: IndexMap<u32, N::BlockHash>, ) -> Result<Self>

Initializes a new instance of the block locators, checking the validity of the block locators.

pub fn new_genesis(genesis_hash: N::BlockHash) -> Self

Initializes a new genesis instance of the block locators.

impl<N: Network> BlockLocators<N>

pub fn latest_locator_height(&self) -> u32

Returns the latest locator height.

pub fn get_hash(&self, height: u32) -> Option<N::BlockHash>

Returns the block hash for the given block height, if it exists.

pub fn is_valid(&self) -> bool

Returns true if the block locators are well-formed.

pub fn is_consistent_with(&self, other: &Self) -> bool

Returns true if the given block locators are consistent with this one. This function assumes the given block locators are well-formed.

pub fn ensure_is_valid(&self) -> Result<()>

Checks that this block locators instance is well-formed.

pub fn ensure_is_consistent_with(&self, other: &Self) -> Result<()>

Returns true if the given block locators are consistent with this one. This function assumes the given block locators are well-formed.

impl<N: Network> BlockLocators<N>

pub fn check_consistent_block_locators( old_locators: &BlockLocators<N>, new_locators: &BlockLocators<N>, ) -> Result<()>

Checks the old and new block locators share a consistent view of block history. This function assumes the given block locators are well-formed.

pub fn check_block_locators( recents: &IndexMap<u32, N::BlockHash>, checkpoints: &IndexMap<u32, N::BlockHash>, ) -> Result<()>

Checks that the block locators are well-formed.

Trait Implementations

impl<N: Clone + Network> Clone for BlockLocators<N>

where N::BlockHash: Clone,

fn clone(&self) -> BlockLocators<N>

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<N: Debug + Network> Debug for BlockLocators<N>

where N::BlockHash: Debug,

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

Formats the value using the given formatter.

impl<'de, N: Network> Deserialize<'de> for BlockLocators<N>

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl<N: Network> FromBytes for BlockLocators<N>

fn read_le<R: Read>(reader: R) -> IoResult<Self>

Reads Self from reader as little-endian bytes.

fn from_bytes_le(bytes: &[u8]) -> Result<Self, Error>

where Self: Sized,

Returns Self from a byte array in little-endian order.

fn from_bytes_le_unchecked(bytes: &[u8]) -> Result<Self, Error>

where Self: Sized,

Same behavior as Self::from_bytes_le but avoids costly checks. This shall only be called when deserializing from a trusted source, such as local storage.

fn read_le_unchecked<R>(reader: R) -> Result<Self, Error>

where R: Read, Self: Sized,

Same behavior as Self::read_le but avoids costly checks. This shall only be called when deserializing from a trusted source, such as local storage.

fn read_le_with_unchecked<R>(reader: R, unchecked: bool) -> Result<Self, Error>

where R: Read, Self: Sized,

Helper function that deserializes either unchecked or checked based on the given boolean flag.

impl<N: Network> IntoIterator for BlockLocators<N>

type IntoIter = IntoIter<u32, <N as Network>::BlockHash>

Which kind of iterator are we turning this into?

type Item = (u32, <N as Network>::BlockHash)

The type of the elements being iterated over.

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl<N: PartialEq + Network> PartialEq for BlockLocators<N>

where N::BlockHash: PartialEq,

fn eq(&self, other: &BlockLocators<N>) -> 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<N: Network> Serialize for BlockLocators<N>

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

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl<N: Network> ToBytes for BlockLocators<N>

fn write_le<W: Write>(&self, writer: W) -> IoResult<()>

Writes self into writer as little-endian bytes.

fn to_bytes_le(&self) -> Result<Vec<u8>, Error>

where Self: Sized,

Returns self as a byte array in little-endian order.

impl<N: Eq + Network> Eq for BlockLocators<N>

where N::BlockHash: Eq,

impl<N: Network> StructuralPartialEq for BlockLocators<N>