# `bdk_electrum` with merkle proofs

The ticket: https://github.com/bitcoindevkit/bdk/issues/980

## Goals

* Do Electrum properly.
* Check PoW of the chain, find the best chain.
* Check tx is part of the block (merkle-proofing).
* Do Electrum checkpointing (minimize headers to download).

## The Architecture

* The new `ChainOracle`
* To construct: Initial blocks (`Vec<{Height, BlockHash, Difficulty}>`) with difficulty.
* To update: Takes in blocks that is connected to something it already has, and is in direct sequence.
* Responsibilities:
* Verifies PoW. Discard blocks that don't meet difficulty target.
* Determines the best chain.
* Keeps track of multiple competing chains.
* Details:
* Keep track of all chain tips.
* Store difficulty of each block in a map. `HashMap<BlockHash, Difficulty>`. `ChainOracle` needs to calculate this (except for the starting blocks).
* The chain source.
* To initialize emission: `CheckPoint<Header>` chain from `ChainOracle`.
* 2 types of emission:
* Latest blocks: Emits `Checkpoint<Header>` in sequence.
* Relevant below-highest-checkpoint blocks: Emits `CheckPoint` from relevant block, up to checkpoint.

## Steps

* Build the new `ChainOracle`.
* Construct initial `CheckPoint`s from electrum's `.json`.

---

* Change `LocalChain` to take in a generic so we can store whole headers.
* Why? So we don't have to re-download headers, since we need headers for merkle proofs.
* Introduce a new anchor type that contains the tx merkle proof.
* Why? So we can present all data to the caller (the caller can choose what to do with it).
* Struct name `TxMerkleAnchor`: contains merkle proof, confirmation time, and anchor block.
* Implement header-checkpointing so clients do not have to download every single header from genesis (check Electrum docs). Allow caller to specify these *checkpoints* (not the same as our local chain checkpoints).

## The Logic

* Fetch txid histories
* Fetch headers
* Fetch merkle proofs
* Fetch full transactions

## Questions

* Should we switch to use the subscription-based API ?

## Action Steps

- [x] ~~Add method that does merkle proof~~ ([already avaliable here](https://github.com/bitcoindevkit/rust-electrum-client/pull/122)).
- [x] Change `LocalChain` to be generic so we can have a linked list of headers (instead of just `BlockId`s).
- [ ] Test: Since we can use anything that obtains `BlockId` in the checkpoints, we need to test whether we can replace `B` under the same `BlockId`, but is different data. We should allow this behavior. The `PartialEq` impl of `CheckPoint` needs to take into account of this.
- [ ] Introduce new anchor type `TxMerkleAnchor`