Extend finality notifications to include displaced leaves

[andresilva]

The client provides a stream for listening for finality notifications, thus allowing other clients to hook into the finality pipeline. Currently it sends a notification for each block that gets finalized with the following format:

substrate/client/api/src/client.rs

Lines 273 to 280 in 7409589

	/// Summary of a finalized block.
	#[derive(Clone, Debug)]
	pub struct FinalityNotification<Block: BlockT> {
	/// Imported block header hash.
	pub hash: Block::Hash,
	/// Imported block header.
	pub header: Block::Header,
	}

Finalizing a block can lead to a bunch of forks becoming stale (i.e. they cannot progress any further). In such cases, it might be useful to know that these forks can be abandoned so that potentially some data can be pruned (e.g. BABE block weight). Currently, this is handled in the backend where we keep track of the open leaves but this information is not exposed back to the client. I propose updating the finality notifcation struct to include this data:

pub struct FinalityNotification<Block: BlockT> {
    pub finalized_hash: Block::Hash,
    pub finalized_header: Block::Header,
    pub previous_finalized_number: NumberFor<Block>,
    pub stale_heads: Vec<Block::Hash>,
}

stale_heads would include the latest block of each of these forks, all stale fork blocks could then be found by traversing these heads back until reaching the finalized chain.

Additionally, I suggest that the notification should also include the block number of the previously best finalized block. This is because currently the client will create notifications for all intermediary finalized blocks, e.g. if block 5 is the current best finalized and we then finalize block 10 then the client will send notifications for 6, 7, 8, 9 and 10. By passing along the last finalized number in the notification we can avoid having to create all these intermediary notifications and instead the consumer of the notification can decide whether it needs to do anything on the intermediary blocks or not. The current implementation also has a edge case where we don't send more than 256 notifications, which can lead to some unexpected results (https://github.com/paritytech/substrate/blob/master/client/service/src/client/client.rs#L833-L842).

[bkchr]

stale_heads would include the latest block of each of these forks, all stale fork blocks could then be found by traversing these heads back until reaching the finalized chain.

Aren't we directly prune these stale forks? Aka you can not iterate them anymore? We would need to include the entire fork to iterate them.

[andresilva]

Good point. AFAIR the blocks themselves are not pruned from the disk, instead we only prune the stale head hashes from the LeafSet. But it needs to be checked as I am not sure.