[blockchain] Add traits to reuse Blockchains across multiple wallets

Add three new traits:
- `StatelessBlockchain` is used to tag `Blockchain`s that don't have any
  wallet-specic state, i.e. they can be used as-is to sync multiple wallets.
- `StatefulBlockchain` is the opposite of `StatelessBlockchain`: it
  provides a method to "clone" a `Blockchain` with an updated internal
  state (a new wallet checksum and, optionally, a different number of
  blocks to skip from genesis). Potentially this also allows reusing the
  underlying connection on `Blockchain` types that support it.
- `MultiBlockchain` is a generalization of this concept: it's
  implemented automatically for every type that implements
  `StatefulBlockchain` and for every `Arc<T>` where `T` is a
  `StatelessBlockchain`. This allows a piece of code that deals with
  multiple sub-wallets to just get a `&B: MultiBlockchain` without having
  to deal with stateful and statless blockchains individually.

These new traits have been implemented for Electrum, Esplora and RPC
(the first two being stateless and the latter stateful). It hasn't been
implemented on the CBF blockchain, because I don't think it would work
in its current form (it throws away old block filters, so it's hard to
go back and rescan).

This is the first step for bitcoindevkit#549, as BIP47 needs to sync many different
descriptors internally.

It's also very useful for bitcoindevkit#486.

Author: afilini

CHANGELOG.md

@@ -11,6 +11,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Add `get_internal_address` to allow you to get internal addresses just as you get external addresses.
 - added `ensure_addresses_cached` to `Wallet` to let offline wallets load and cache addresses in their database
 - Add `is_spent` field to `LocalUtxo`; when we notice that a utxo has been spent we set `is_spent` field to true instead of deleting it from the db.
+- Add traits to reuse `Blockchain`s across multiple wallets (`MultiBlockchain`, `StatefulBlockchain`, `StatelessBlockchain`).
 
 ### Sync API change
 

src/blockchain/electrum.rs

@@ -79,6 +79,8 @@ impl Blockchain for ElectrumBlockchain {
     }
 }
 
+impl StatelessBlockchain for ElectrumBlockchain {}
+
 impl GetHeight for ElectrumBlockchain {
     fn get_height(&self) -> Result<u32, Error> {
         // TODO: unsubscribe when added to the client, or is there a better call to use here?

src/blockchain/esplora/reqwest.rs

@@ -101,6 +101,8 @@ impl Blockchain for EsploraBlockchain {
     }
 }
 
+impl StatelessBlockchain for EsploraBlockchain {}
+
 #[maybe_async]
 impl GetHeight for EsploraBlockchain {
     fn get_height(&self) -> Result<u32, Error> {

src/blockchain/esplora/ureq.rs

@@ -98,6 +98,8 @@ impl Blockchain for EsploraBlockchain {
     }
 }
 
+impl StatelessBlockchain for EsploraBlockchain {}
+
 impl GetHeight for EsploraBlockchain {
     fn get_height(&self) -> Result<u32, Error> {
         Ok(self.url_client._get_height()?)

src/blockchain/mod.rs

@@ -164,6 +164,57 @@ pub trait ConfigurableBlockchain: Blockchain + Sized {
     fn from_config(config: &Self::Config) -> Result<Self, Error>;
 }
 
+/// Trait for blockchains that don't contain any state
+///
+/// Statless blockchains can be used to sync multiple wallets with different descriptors
+pub trait StatelessBlockchain: WalletSync + GetHeight {}
+
+/// Trait for blockchains that have a wallet-dependent state
+///
+/// This trait provides [`StatefulBlockchain::clone_with`] to clone the blockchain and update its
+/// internal state to point to a different wallet checksum and optionally a different number of
+/// blocks to skip when syncing.
+///
+/// If `override_skip_blocks` is `None`, the returned blockchain will inherit the number of blocks
+/// to skip from `self`. Since it's not possible to override the value to `None`, set it to
+/// `Some(0)` to rescan from the genesis.
+pub trait StatefulBlockchain: WalletSync + GetHeight {
+    /// The type returned when cloning this blockchain
+    type Cloned: WalletSync + GetHeight;
+
+    /// Clone `self` with a different internal state
+    fn clone_with(
+        &self,
+        checksum: &str,
+        override_skip_blocks: Option<u32>,
+    ) -> Result<Self::Cloned, Error>;
+}
+
+/// Trait for collections of blockchains that share an underlying connection
+pub trait MultiBlockchain {
+    /// The type returned when cloning this blockchain
+    type Inner: WalletSync + GetHeight;
+
+    /// Clone `self` with a different internal state
+    fn get(&self, checksum: &str, override_skip_blocks: Option<u32>) -> Result<Self::Inner, Error>;
+}
+
+impl<T: StatelessBlockchain> MultiBlockchain for Arc<T> {
+    type Inner = Self;
+
+    fn get(&self, _checksum: &str, _override_skip_blocks: Option<u32>) -> Result<Self, Error> {
+        Ok(Arc::clone(self))
+    }
+}
+
+impl<T: StatefulBlockchain> MultiBlockchain for T {
+    type Inner = <T as StatefulBlockchain>::Cloned;
+
+    fn get(&self, checksum: &str, override_skip_blocks: Option<u32>) -> Result<Self::Inner, Error> {
+        self.clone_with(checksum, override_skip_blocks)
+    }
+}
+
 /// Data sent with a progress update over a [`channel`]
 pub type ProgressData = (f32, Option<String>);
 

src/blockchain/rpc.rs

@@ -61,6 +61,9 @@ pub struct RpcBlockchain {
     /// Skip this many blocks of the blockchain at the first rescan, if None the rescan is done from the genesis block
     skip_blocks: Option<u32>,
 
+    /// Keep track of the config used to build this blockchain so that we can tweak it and reuse it
+    config: RpcConfig,
+
     /// This is a fixed Address used as a hack key to store information on the node
     _storage_address: Address,
 }
@@ -155,6 +158,21 @@ impl Blockchain for RpcBlockchain {
     }
 }
 
+impl StatefulBlockchain for RpcBlockchain {
+    type Cloned = Self;
+
+    fn clone_with(&self, checksum: &str, override_skip_blocks: Option<u32>) -> Result<Self, Error> {
+        let mut new_config = self.config.clone();
+
+        new_config.wallet_name = checksum.to_string();
+        if let Some(skip_blocks) = override_skip_blocks {
+            new_config.skip_blocks = Some(skip_blocks);
+        }
+
+        RpcBlockchain::from_config(&new_config)
+    }
+}
+
 impl GetTx for RpcBlockchain {
     fn get_tx(&self, txid: &Txid) -> Result<Option<Transaction>, Error> {
         Ok(Some(self.client.get_raw_transaction(txid, None)?))
@@ -420,6 +438,7 @@ impl ConfigurableBlockchain for RpcBlockchain {
             network,
             capabilities,
             _storage_address: storage_address,
+            config: config.clone(),
             skip_blocks: config.skip_blocks,
         })
     }