Add invalidate block method and invalidated_blocks field to NonFinalizedState

[elijahhampton]

Motivation

This PR implements a new method invalidate_block to invalidate a block based on the block::Hash along with the blocks descendants. This PR closes the following issue: #8840 , #8841

Specifications & References

Reference: #8634

Solution

• Adds invalidate_block method to NonFinalizedState
• Changes visibility to pub(crate) for UpdateWith / RevertPosition in chain.rs
• Adds test for invalidate_block in vectors.rs
• Adds new invalidated_blocks state to NonFinalizedState

Tests

Follow-up Work

PR Author's Checklist

• The PR name will make sense to users.
• The PR provides a CHANGELOG summary.
• The solution is tested.
• The documentation is up to date.
• The PR has a priority label.

PR Reviewer's Checklist

• The PR Author's checklist is complete.
• The PR resolves the issue.

[elijahhampton]

Closes #8840 , #8841

[arya2]

Thank you for getting this done.

This looks excellent. I left some optional suggestions, but none of them are blockers so feel free to resolve them without making changes if you'd like this to merge as-is.

[arya2]

Optional/Nitpick: Ideally this hash map or its values would be in an Arc, because Zebra clones the non-finalized state fairly frequently. It shouldn't be possible to update this field without access to the RPC server, so this would be cleanup, not a security issue.

I'm also wondering if this could be simplified to be HashMap<Hash, Arc<Vec<ContextuallyValidatedBlock>>> where the first item in the value is the explicitly invalidated block?

Suggested change

	/// Invalidated blocks and descendants
	invalidated_blocks: HashMap<block::Hash, InvalidatedBlockData>,
	/// Blocks that have been invalidated in, and removed from, the non-finalized state
	/// via the `invalidate` RPC method.
	invalidated_blocks: Arc<HashMap<block::Hash, InvalidatedBlockData>>,

[arya2]

It should update the metrics whenever chain_set is modified.

Optional/Nitpick: This method could drop the chain and return early when the invalidated block is the non-finalized chain root block.

Suggested change

	self.update_metrics_for_chains();
	self.update_metrics_bars();
	}
	}
	self.update_metrics_for_chains();
	self.update_metrics_bars();

[arya2]

There's a suggestion below for removing this struct altogether, but if we're keeping it, minor documentation update:

Suggested change

	/// Data related to an invalidated block including the [`ContextuallyVerifiedBlock`] and
	/// descendants.
	#[derive(Clone, Debug)]
	pub struct InvalidatedBlockData {
	/// The block that was invalidated.
	pub block: ContextuallyVerifiedBlock,
	/// All descendant blocks that were also removed in order by [`block::Height`].
	pub descendants: BTreeMap<block::Height, ContextuallyVerifiedBlock>,
	/// [`ContextuallyVerifiedBlock`]s that were invalidated via the `invalidate` RPC method
	/// and removed from the non-finalized state, as well as any of their descendants that may
	/// have also been removed.
	#[derive(Clone, Debug)]
	pub struct InvalidatedBlockData {
	/// The block that was invalidated.
	pub block: ContextuallyVerifiedBlock,
	/// All child blocks of the invalidated block that were removed in order by [`block::Height`].
	pub descendants: BTreeMap<block::Height, ContextuallyVerifiedBlock>,

[arya2]

What's the intended purpose of this timestamp?

[arya2]

Nitpick/Optional: Ideally we could move this to a Chain method, like pop_tip() but which accepts a block hash and returns a list of ContextuallyValidatedBlocks.