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.

BlockLocators instances are built, in the form described above, by [BlockSync::get_block_locators()]. When a BlockLocators instance is received (in a [PrimaryPing]) by a validator, the maps may not have the form described below; the deserializer does not enforce that. However, before incorporating the BlockLocators instance information into its state, the validator checks that the maps have the correct form, via BlockLocators::ensure_is_valid().

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_unchecked( recents: IndexMap<u32, N::BlockHash>, checkpoints: IndexMap<u32, N::BlockHash>, ) -> Self

Initializes a new instance of the block locators, without 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 are 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 copy 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.

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>