Struct NonFinalizedState

pub struct NonFinalizedState {
    chain_set: BTreeSet<Arc<Chain>>,
    pub network: Network,
    should_count_metrics: bool,
    chain_count_bar: Option<Tx>,
    chain_fork_length_bars: Vec<Tx>,
}

The state of the chains in memory, including queued blocks.

Clones of the non-finalized state contain independent copies of the chains. This is different from FinalizedState::clone(), which returns a shared reference to the database.

Most chain data is clone-on-write using Arc.

Fields

chain_set: BTreeSet<Arc<Chain>>

Verified, non-finalized chains, in ascending work order.

The best chain is NonFinalizedState::best_chain(), or chain_iter().next(). Using chain_set.last() or chain_set.iter().next_back() is deprecated, callers should migrate to chain_iter().next().

network: Network

The configured Zcash network.

should_count_metrics: bool

Configures the non-finalized state to count metrics.

Used for skipping metrics and progress bars when testing block proposals with a commit to a cloned non-finalized state.

chain_count_bar: Option<Tx>

Number of chain forks transmitter.

chain_fork_length_bars: Vec<Tx>

A chain fork length transmitter for each Chain in chain_set.

Because chain_set contains Arc<Chain>s, it is difficult to update the metrics state on each chain. (Arcs are read-only, and we don’t want to clone them just for metrics.)

Implementations

impl NonFinalizedState

pub fn new(network: &Network) -> NonFinalizedState

Returns a new non-finalized state for network.

pub fn eq_internal_state(&self, other: &NonFinalizedState) -> bool

Is the internal state of self the same as other?

Chain has a custom Eq implementation based on proof of work, which is used to select the best chain. So we can’t derive Eq for NonFinalizedState.

Unlike the custom trait impl, this method returns true if the entire internal state of two non-finalized states is equal.

If the internal states are different, it returns false, even if the chains and blocks are equal.

pub fn chain_iter(&self) -> impl Iterator<Item = &Arc<Chain>>

Returns an iterator over the non-finalized chains, with the best chain first.

fn insert_with<F>(&mut self, chain: Arc<Chain>, chain_filter: F)

where F: FnOnce(&mut BTreeSet<Arc<Chain>>),

Insert chain into self.chain_set, apply chain_filter to the chains, then limit the number of tracked chains.

fn insert(&mut self, chain: Arc<Chain>)

Insert chain into self.chain_set, then limit the number of tracked chains.

pub fn finalize(&mut self) -> FinalizableBlock

Finalize the lowest height block in the non-finalized portion of the best chain and update all side-chains to match.

pub fn commit_block( &mut self, prepared: SemanticallyVerifiedBlock, finalized_state: &ZebraDb, ) -> Result<(), ValidateContextError>

Commit block to the non-finalized state, on top of:

• an existing chain’s tip, or
• a newly forked chain.

pub fn commit_new_chain( &mut self, prepared: SemanticallyVerifiedBlock, finalized_state: &ZebraDb, ) -> Result<(), ValidateContextError>

Commit block to the non-finalized state as a new chain where its parent is the finalized tip.

fn validate_and_commit( &self, new_chain: Arc<Chain>, prepared: SemanticallyVerifiedBlock, finalized_state: &ZebraDb, ) -> Result<Arc<Chain>, ValidateContextError>

Contextually validate prepared using finalized_state. If validation succeeds, push prepared onto new_chain.

new_chain should start as a clone of the parent chain fork, or the finalized tip.

fn validate_and_update_parallel( new_chain: Arc<Chain>, contextual: ContextuallyVerifiedBlock, sprout_final_treestates: HashMap<Root, Arc<NoteCommitmentTree>>, ) -> Result<Arc<Chain>, ValidateContextError>

Validate contextual and update new_chain, doing CPU-intensive work in parallel batches.

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

Returns the length of the non-finalized portion of the current best chain or None if the best chain has no blocks.

pub fn any_chain_contains(&self, hash: &Hash) -> bool

Returns true if hash is contained in the non-finalized portion of any known chain.

pub fn find_chain<P>(&self, predicate: P) -> Option<Arc<Chain>>

where P: FnMut(&Chain) -> bool,

Returns the first chain satisfying the given predicate.

If multiple chains satisfy the predicate, returns the chain with the highest difficulty. (Using the tip block hash tie-breaker.)

pub fn any_utxo(&self, outpoint: &OutPoint) -> Option<Utxo>

Returns the transparent::Utxo pointed to by the given transparent::OutPoint if it is present in any chain.

UTXOs are returned regardless of whether they have been spent.

pub fn any_block_by_hash(&self, hash: Hash) -> Option<Arc<Block>>

Returns the block with the given hash in any chain.

pub fn any_prev_block_hash_for_hash(&self, hash: Hash) -> Option<Hash>

Returns the previous block hash for the given block hash in any chain.

pub fn best_hash(&self, height: Height) -> Option<Hash>

Returns the hash for a given block::Height if it is present in the best chain.

pub fn best_tip(&self) -> Option<(Height, Hash)>

Returns the tip of the best chain.

pub fn best_tip_block(&self) -> Option<&ContextuallyVerifiedBlock>

Returns the block at the tip of the best chain.

pub fn best_height_by_hash(&self, hash: Hash) -> Option<Height>

Returns the height of hash in the best chain.

pub fn any_height_by_hash(&self, hash: Hash) -> Option<Height>

Returns the height of hash in any chain.

pub fn best_contains_sprout_nullifier( &self, sprout_nullifier: &Nullifier, ) -> bool

Returns true if the best chain contains sprout_nullifier.

pub fn best_contains_sapling_nullifier( &self, sapling_nullifier: &Nullifier, ) -> bool

Returns true if the best chain contains sapling_nullifier.

pub fn best_contains_orchard_nullifier( &self, orchard_nullifier: &Nullifier, ) -> bool

Returns true if the best chain contains orchard_nullifier.

pub fn best_chain(&self) -> Option<&Arc<Chain>>

Return the non-finalized portion of the current best chain.

pub fn chain_count(&self) -> usize

Return the number of chains.

fn parent_chain( &self, parent_hash: Hash, ) -> Result<Arc<Chain>, ValidateContextError>

Return the chain whose tip block hash is parent_hash.

The chain can be an existing chain in the non-finalized state, or a freshly created fork.

fn should_count_metrics(&self) -> bool

Should this NonFinalizedState instance track metrics and progress bars?

fn update_metrics_for_committed_block(&self, height: Height, hash: Hash)

Update the metrics after block is committed

fn update_metrics_for_chains(&self)

Update the metrics after self.chain_set is modified

fn update_metrics_bars(&mut self)

Update the progress bars after any chain is modified. This includes both chain forks and committed blocks.

pub fn disable_metrics(&mut self)

Stop tracking metrics for this non-finalized state and all its chains.

Trait Implementations

impl Clone for NonFinalizedState

fn clone(&self) -> Self

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for NonFinalizedState

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

Formats the value using the given formatter.

impl Drop for NonFinalizedState

fn drop(&mut self)

Executes the destructor for this type.