sc-client: expose pinning API

[ordian]

Required for #623.

I've considered another design with RAAI similar to lock_block, but opted for a lower-level albeit less safe API. The reason is that the caller can provide a safer abstraction on top (see the follow-up PR).

[eskimor]

Awesome, thanks!

[eskimor]

With regards to the safe abstraction, I would strongly consider to also provide it alongside and recommend its usage or something similar - otherwise people will have to implement it themselves or more likely - they don't use safe abstraction.

Personally I would even prefer to only expose a safe API.

EDIT: What happens if a blocks are never unpined?

[bkchr]

polkadot-sdk/substrate/client/api/src/client.rs

Lines 359 to 364 in 4252e48

	/// Consume this notification and extract the unpin handle.
	///
	/// Note: Only use this if you want to keep the block pinned in the backend.
	pub fn into_unpin_handle(self) -> UnpinHandle<Block> {
	self.unpin_handle
	}

this what you want to use to keep the blocks alive. There is no guarantee that the block is still valid when you try to call pin_block.

[ordian]

@bkchr

• are we guaranteed to receive BlockImportNotification for every block? I think not, which is why we have this function determine_new_blocks
• we want to pin only inclusion blocks with f+1 against votes, this happens much later after import, but before the dispute concludes and they are pruned

[ordian]

What happens if a blocks are never unpined?

Substrate has its own LruMap and will unpin it eventually. But you can see ChainAPI API in #1220 prevents that from happening.

[bkchr]

• we want to pin only inclusion blocks with f+1 against votes, this happens much later after import, but before the dispute concludes and they are pruned

Fair point, but then just forward the backend. No need to blow up the client even more.

[ordian]

Closing this in favor of using UnpinHandle and #1220 (comment)