Struct BlockTreeSingleton

pub struct BlockTreeSingleton<K: KVStore>(K);

Read and write handle into the block tree that should be owned exclusively by the algorithm thread.

Categories of methods

BlockTreeSingleton has a large number of methods. To improve understandability, these methods are grouped into five categories, with methods in each separate category being defined in a separate impl block. These five categories are:

1. Lifecycle methods.
2. Top-level state updaters.
3. Helper functions called by BlockTree::update.
4. Basic state getters.
5. Extra state getters.

Tuple Fields

0: K

Implementations

impl<K: KVStore> BlockTreeSingleton<K>

Lifecycle methods.

These are methods for creating and initializing a BlockTreeSingleton, as well as for using it to create and consume other block tree-related types, namely, BlockTreeSnapshot, BlockTreeWriteBatch, and AppBlockTreeView.

pub(crate) fn new(kv_store: K) -> Self

Create a new instance of BlockTreeSingleton on top of kv_store.

This constructor is private (pub(crate)). To create an instance of BlockTreeSingleton as a library user, use new_unsafe.

pub unsafe fn new_unsafe(kv_store: K) -> Self

Create a new instance of BlockTreeSingleton on top of kv_store.

Safety

Read mutating the block tree directly from user code.

pub fn initialize( &mut self, initial_app_state: &AppStateUpdates, initial_validator_set_state: &ValidatorSetState, ) -> Result<(), BlockTreeError>

Initialize the block tree variables listed in initial state.

This function must be called exactly once on a BlockTreeSingleton with an empty backing kv_store, before any of the other functions (except the constructors new or new_unsafe) are called.

pub fn snapshot(&self) -> BlockTreeSnapshot<K::Snapshot<'_>>

Create a BlockTreeSnapshot.

pub fn write(&mut self, write_batch: BlockTreeWriteBatch<K::WriteBatch>)

Atomically write the changes in write_batch into the BlockTreeSingleton.

pub fn app_view<'a>( &'a self, parent: Option<&CryptoHash>, ) -> Result<AppBlockTreeView<'a, K>, BlockTreeError>

Create an AppBlockTreeView which sees the app state as it will be right after parent becomes committed.

impl<K: KVStore> BlockTreeSingleton<K>

Top-level state updaters.

These are the methods that mutate the block tree that are called directly by code in the subprotocols (i.e., hotstuff, block_sync, and pacemaker). Mutating methods outside of this impl and the lifecycle methods impl above are only used internally in this module.

pub fn insert( &mut self, block: &Block, app_state_updates: Option<&AppStateUpdates>, validator_set_updates: Option<&ValidatorSetUpdates>, ) -> Result<(), BlockTreeError>

Insert into the block tree a block that will cause the provided app_state_updates and validator_set_updates to be applied when it is committed in the future.

Relationship with update

insert does not internally call update. Calling code is responsible for calling update on block.justify after calling insert.

Precondition

safe_block is true for block.

pub(crate) fn update( &mut self, justify: &PhaseCertificate, event_publisher: &Option<Sender<Event>>, ) -> Result<Option<ValidatorSetUpdates>, BlockTreeError>

Update the block tree upon seeing a safe justify in a Nudge or a Block.

Updates

Depending on the specific Phase Certificate received and the state of the Block Tree, the updates that this function performs will include:

1. Updating the Highest PC if justify.view > highest_pc.view.
2. Updating the Locked PC if appropriate, as determined by the pc_to_lock helper.
3. Committing a block and all of its ancestors if appropriate, as determined by the block_to_commit helper.
4. Marking the latest validator set updates as decided if justify is a Decide PC.

Preconditions

The Block or Nudge containing justify must satisfy safe_block or safe_nudge, respectively.

pub fn set_highest_tc( &mut self, tc: &TimeoutCertificate, ) -> Result<(), BlockTreeError>

Set the highest TimeoutCertificate to be tc.

Preconditions

TODO.

pub fn set_highest_view_entered( &mut self, view: ViewNumber, ) -> Result<(), BlockTreeError>

Set the highest view entered to be view.

Preconditions

view >= self.highest_view_entered().

pub fn set_highest_view_phase_voted( &mut self, view: ViewNumber, ) -> Result<(), BlockTreeError>

Set the highest view phase-voted to be view.

Preconditions

view >= self.highest_view_voted().

impl<K: KVStore> BlockTreeSingleton<K>

Helper functions called by [BlockTree::update].

pub fn commit( &mut self, wb: &mut BlockTreeWriteBatch<K::WriteBatch>, block: &CryptoHash, ) -> Result<Vec<(CryptoHash, Option<ValidatorSetUpdates>)>, BlockTreeError>

Commit block and all of its ancestors, if they have not already been committed.

Return value

Returns the hashes of the newly committed blocks, along with the updates each caused to the validator set, in order from the newly committed block with the lowest height to the newly committed block with the highest height.

Preconditions

block_to_commit returns block.

pub fn delete_siblings( &mut self, wb: &mut BlockTreeWriteBatch<K::WriteBatch>, block: &CryptoHash, ) -> Result<(), BlockTreeError>

Delete the “siblings” of the specified block, along with all of its associated data (e.g., pending app state updates, validator set updates).

“Siblings” refer to other blocks that share the same parent as the specified block.

Precondition

block is in its parents’ (or the genesis) children list.

Error

Returns an error if the block is not in the block tree, or if the block’s parent (or genesis) does not have a children list.

pub fn delete_branch( &mut self, wb: &mut BlockTreeWriteBatch<K::WriteBatch>, root: &CryptoHash, )

Deletes all data of blocks in a branch starting from (and including) a given root block.

pub fn blocks_in_branch( &self, root: CryptoHash, ) -> impl Iterator<Item = CryptoHash>

Perform depth-first search to collect the hashes of all blocks in the branch rooted at root into a single iterator.

fn publish_update_block_tree_events( event_publisher: &Option<Sender<Event>>, update_highest_pc: Option<PhaseCertificate>, update_locked_pc: Option<PhaseCertificate>, committed_blocks: &Vec<(CryptoHash, Option<ValidatorSetUpdates>)>, )

Publish all events resulting from calling update. These events have to do with changing persistent state, and possibly include: UpdateHighestPCEvent, UpdateLockedPCEvent, PruneBlockEvent, CommitBlockEvent, UpdateValidatorSetEvent.

Invariant: this method must only be invoked after the associated changes are persistently written to the BlockTreeSingleton.

impl<K: KVStore> BlockTreeSingleton<K>

“Basic” state getters.

Each basic state getter calls a corresponding provided method of KVGet and return whatever they return.

The exact same set of basic state getters are also defined on BlockTreeSnapshot.

pub fn block(&self, block: &CryptoHash) -> Result<Option<Block>, BlockTreeError>

pub fn block_height( &self, block: &CryptoHash, ) -> Result<Option<BlockHeight>, BlockTreeError>

pub fn block_data_hash( &self, block: &CryptoHash, ) -> Result<Option<CryptoHash>, BlockTreeError>

pub fn block_justify( &self, block: &CryptoHash, ) -> Result<PhaseCertificate, BlockTreeError>

pub fn block_data_len( &self, block: &CryptoHash, ) -> Result<Option<DataLen>, BlockTreeError>

pub fn block_data( &self, block: &CryptoHash, ) -> Result<Option<Data>, BlockTreeError>

pub fn block_datum(&self, block: &CryptoHash, datum_index: u32) -> Option<Datum>

pub fn block_at_height( &self, height: BlockHeight, ) -> Result<Option<CryptoHash>, BlockTreeError>

pub fn children( &self, block: &CryptoHash, ) -> Result<ChildrenList, BlockTreeError>

pub fn committed_app_state(&self, key: &[u8]) -> Option<Vec<u8>>

pub fn pending_app_state_updates( &self, block: &CryptoHash, ) -> Result<Option<AppStateUpdates>, BlockTreeError>

pub fn committed_validator_set(&self) -> Result<ValidatorSet, BlockTreeError>

pub fn validator_set_updates_status( &self, block: &CryptoHash, ) -> Result<ValidatorSetUpdatesStatus, BlockTreeError>

pub fn locked_pc(&self) -> Result<PhaseCertificate, BlockTreeError>

pub fn highest_view_entered(&self) -> Result<ViewNumber, BlockTreeError>

pub fn highest_pc(&self) -> Result<PhaseCertificate, BlockTreeError>

pub fn highest_committed_block( &self, ) -> Result<Option<CryptoHash>, BlockTreeError>

pub fn highest_tc(&self) -> Result<Option<TimeoutCertificate>, BlockTreeError>

pub fn validator_set_state(&self) -> Result<ValidatorSetState, BlockTreeError>

pub fn highest_view_voted(&self) -> Result<Option<ViewNumber>, BlockTreeError>

impl<K: KVStore> BlockTreeSingleton<K>

“Extra” state getters.

Extra state getters call basic state getters and aggregate or modify what they return into forms that are more convenient to use.

Unlike basic state getters, these functions are not defined on BlockTreeSnapshot.

pub fn contains(&self, block: &CryptoHash) -> bool

Check whether block exists on the block tree.

pub fn highest_view_with_progress(&self) -> Result<ViewNumber, BlockTreeError>

Get the maximum of:

• self.highest_view_entered().
• self.highest_pc().
• self.highest_tc().

This is useful for deciding which view to initially enter after starting or restarting a replica.

pub fn highest_committed_block_height( &self, ) -> Result<Option<BlockHeight>, BlockTreeError>

Get the height of the highest committed block.