refactor!: Implement generics for CheckPoint, LocalChain, and spk_client types

[LagginTimes]

Implements #1937.

Description

This PR is a step towards header checkpointing for bdk_electrum. The goal is to be able to store whole headers in CheckPoint so they do not have to be re-downloaded. Storing headers this way would be a prerequisite for caching of merkle proofs and for median time passed.

TODO:

• Change CheckPoint to take in a generic.
• Change LocalChange to take in a generic.
• Change spk_client types to take in generics.

Notes to the reviewers

Changelog notice

• CheckPoint takes in a generic.
• LocalChain and ChangeSet take in generics.
• spk_client types can take in generics.

Checklists

All Submissions:

• I've signed all my commits
• I followed the contribution guidelines
• I ran cargo fmt and cargo clippy before committing

[luisschwab]

Dropping in to note that this would be incredible useful for bdk_kyoto. It is likely that a LocalChain generic over Header would allow the CBF system to simply use the LocalChain the chain backend, and the persistence may be shared between a Wallet and the node.

+1 for this feature, bdk_floresta could share persistence with bdk_wallet as well.

[ValuedMammal]

At a high level I think the API would be cleaner if the generic methods had the simpler names (new, push, extend, insert) and the old methods were renamed push_block_id, extend_block_ids, etc.

CheckPoint::data method can be two methods:

fn data_ref(&self) -> &B {}

fn data(&self) -> B where B: Clone {} // or Copy

LocalChain should have more of a unified interface. Most of the methods should be generic and the only methods under impl LocalChain<BlockHash> {} should be the ones that only make sense in the old design (from_genesis_hash, insert_block, etc). Having two versions of apply_changeset and _check_changeset_is_applied isn't very helpful.

Remaining questions:

1. Will it be possible to migrate an existing sqlite database to one that persists a local chain of headers, or will it require adding a new SQL table?
2. Are there plans to enable syncing a local chain of headers using bdk_electrum / esplora?

Edit: I added my review with some API suggestions in LagginTimes#5

[evanlinjin]

@LagginTimes is this ready to review again? Remember to mark it as so and request reviewers, otherwise no one will know about it.

[evanlinjin]

What was the discussion around breaking changes? Were we okay to break the API?

[LagginTimes]

What was the discussion around breaking changes? Were we okay to break the API?

Iirc the consensus was for this to be a breaking change to be a cleaner API.

[evanlinjin]

Thanks for pushing this forward.

Please double check (brownie points for triple check) over all the methods of a struct to see whether they are coherent, whether any more methods can be made generic and whether the method names and generic parameter names are coherent and make sense.

Let's make all generic parameter names for block data be consistent across the board. I'm in favor of B.

[evanlinjin]

I would use B (as in block) or D (as in data) for the type generic instead of H (which I'm assuming stands for header, but we aren't necessarily using headers here).

[evanlinjin]

I would remove this and have from_genesis(data: B) instead which would work with all types.

[evanlinjin]

Let's make these following methods generic for all Hs.

impl LocalChain<D> {
    pub fn from_genesis(data: D) -> (Self, ChangeSet<D>);
    pub fn from_changeset(changeset: ChangeSet<D>) -> Result<Self>;
    pub fn from_blocks(blocks: BTreeMap<u32, D>) -> Result<Self>;
    pub fn apply_update(&mut self, update: CheckPoint<D>) -> Result<ChangeSet>;

[evanlinjin]

This doesn't look helpful as .apply_changeset does the exact same thing.

[evanlinjin]

This method is no longer useful as .insert_data does the same thing. Just rename .insert_data to .insert_block.

[evanlinjin]

Let's rework this method to be generic over D:

Suggested change

	pub fn from_block_ids(
	block_ids: impl IntoIterator<Item = BlockId>,
	) -> Result<Self, Option<Self>> {
	pub fn from_blocks(
	blocks: impl IntoIterator<Item = (u32, D)>,
	) -> Result<Self, Option<Self>> {

[evanlinjin]

Let's remove this as extend does the same thing.

[evanlinjin]

Remove.

[evanlinjin]

Remove.

[evanlinjin]

I know this is a breaking change, but introducing a generic parameter before one that already exists can be really annoying. Introduce it at the end please.