feat!: add wallet birthday

[luisschwab]

WIP, needs bitcoindevkit/bdk#2097

This PR adds a birthday to the wallet, as a BlockId. Block-by-Block and CBF scanning can use this as a hint to only scan from the birthday onwards, saving time and bandwidth on full-scans where the birthday is previously known.

Client code should be updated to automatically set the birthday when performing a full-scan.

TODO

• Add new bitcoind_rpc example that uses the birthday as the start_height

[luisschwab]

I wonder if this should be public. It gives the user the freedom to set whatever value he wants, even if they're incorrect. @ValuedMammal or @evanlinjin can you shed some light on what would happen if I create a CheckPoint with a height+hash pair that doesn't exist on the chain, and then synched from genesis?

[ValuedMammal]

Good question and probably requires testing before going ahead with this feature. The hope is that the bad block will be "reorged out" of the wallet, but that'll depend on which block IDs the chain source decides to return.

[luisschwab]

I think the best approach would be to not allow manually setting the birthday, and instead rely on the result of a full-scan to define it.

[ValuedMammal]

I was more in favor of the approach in #348 which provided an option on CreateParams to simply add a checkpoint to the local chain during Wallet creation.

[luisschwab]

I was more in favor of the approach in #348 which provided an option on CreateParams to simply add a checkpoint to the local chain during Wallet creation.

Indeed, this would be a better flow, but may conflict with a possibly inexistent BlockId set during wallet creation. I need to do some testing to see what would happen.

[evanlinjin]

I was more in favor of the approach in #348 which provided an option on CreateParams to simply add a checkpoint to the local chain during Wallet creation.

Indeed, this would be a better flow, but may conflict with a possibly inexistent BlockId set during wallet creation. I need to do some testing to see what would happen.

Some thoughts:

• Birthdays are only useful for block-based chain sources.
• bitcoind_rpc emitters trace back from a no-longer-existing-block to a block that is currently in chain (which is the correct behavior) - so no conflict at all!

The only fear is if the chain source has never even seen the no-longer-existing-block - in which case, the chain source starts syncing from genesis (as that would be the closest checkpoint that connects).

So if the user creates a wallet just before a reorg, that would be non-ideal.

My suggestion:

bitcoind_rpc::Emitter::new has a start_height parameter. This is used in the case the closest block that connects is below the start_height. So if the tip is reorged out, and we only have tip + genesis, we will start from start_height instead. To convey the wallet birthday with the checkpoint tip, while still taking into account reorgs, we can use tip_height - FINAL_DEPTH as the start_height parameter. FINAL_DEPTH can be as conservative as you want.

bitcoind_rpc::FilterIter::new does not have such a parameter. We can add it?

Then we provide docs as how to convey the wallet's birthday to the chain source using the checkpoint tip.