Merge bitcoindevkit/bdk#1420: Bump bdk version to 1.0.0-alpha.10

2cda9f44ee Bump bdk version to 1.0.0-alpha.10 (Daniela Brozzoni)

Pull request description:

  ### Description

  bdk_chain to 0.13.0
  bdk_bitcoind_rpc to 0.9.0
  bdk_electrum to 0.12.0
  bdk_esplora to 0.12.0
  bdk_file_store to 0.10.0
  bdk_testenv to 0.3.0
  bdk_persist to 0.2.0

  ### Checklists
  #### All Submissions:
  - [x] I've signed all my commits
  - [x] I followed the [contribution guidelines](https://github.com/bitcoindevkit/bdk/blob/master/CONTRIBUTING.md)
  - [x] I ran cargo fmt and cargo clippy before committing

ACKs for top commit:
  storopoli:
    ACK 2cda9f44ee

Tree-SHA512: 7d3e5f2c9b9da13713e3bb1e6a11d07e9c381221c837a002aefb780698b1d45d64f2582bd0445ecdf7432bf3fe0ba5d6dadd43aa413cf4e5e557f7334a02fa06

Cargo.toml

@@ -8,6 +8,7 @@ members = [
     "crates/esplora",
     "crates/bitcoind_rpc",
     "crates/hwi",
+    "crates/persist",
     "crates/testenv",
     "example-crates/example_cli",
     "example-crates/example_electrum",

README.md

@@ -41,6 +41,7 @@ The project is split up into several crates in the `/crates` directory:
 
 - [`bdk`](./crates/bdk): Contains the central high level `Wallet` type that is built from the low-level mechanisms provided by the other components
 - [`chain`](./crates/chain): Tools for storing and indexing chain data
+- [`persist`](./crates/persist): Types that define data persistence of a BDK wallet
 - [`file_store`](./crates/file_store): A (experimental) persistence backend for storing chain data in a single file.
 - [`esplora`](./crates/esplora): Extends the [`esplora-client`] crate with methods to fetch chain data from an esplora HTTP server in the form that [`bdk_chain`] and `Wallet` can consume.
 - [`electrum`](./crates/electrum): Extends the [`electrum-client`] crate with methods to fetch chain data from an electrum server in the form that [`bdk_chain`] and `Wallet` can consume.

crates/bdk/Cargo.toml

@@ -1,7 +1,7 @@
 [package]
 name = "bdk"
 homepage = "https://bitcoindevkit.org"
-version = "1.0.0-alpha.9"
+version = "1.0.0-alpha.10"
 repository = "https://github.com/bitcoindevkit/bdk"
 documentation = "https://docs.rs/bdk"
 description = "A modern, lightweight, descriptor-based wallet library"
@@ -13,12 +13,14 @@ edition = "2021"
 rust-version = "1.63"
 
 [dependencies]
+anyhow = { version = "1", default-features = false }
 rand = "^0.8"
 miniscript = { version = "11.0.0", features = ["serde"], default-features = false }
 bitcoin = { version = "0.31.0", features = ["serde", "base64", "rand-std"], default-features = false }
 serde = { version = "^1.0", features = ["derive"] }
 serde_json = { version = "^1.0" }
-bdk_chain = { path = "../chain", version = "0.12.0", features = ["miniscript", "serde"], default-features = false }
+bdk_chain = { path = "../chain", version = "0.13.0", features = ["miniscript", "serde"], default-features = false }
+bdk_persist = { path = "../persist", version = "0.1.0" }
 
 # Optional dependencies
 bip39 = { version = "2.0", optional = true }

crates/bdk/README.md

@@ -219,7 +219,7 @@ license, shall be dual licensed as above, without any additional terms or
 conditions.
 
 [`Wallet`]: https://docs.rs/bdk/1.0.0-alpha.7/bdk/wallet/struct.Wallet.html
-[`PersistBackend`]: https://docs.rs/bdk_chain/latest/bdk_chain/trait.PersistBackend.html
+[`PersistBackend`]: https://docs.rs/bdk_persist/latest/bdk_persist/trait.PersistBackend.html
 [`bdk_chain`]: https://docs.rs/bdk_chain/latest
 [`bdk_file_store`]: https://docs.rs/bdk_file_store/latest
 [`bdk_electrum`]: https://docs.rs/bdk_electrum/latest

crates/bdk/examples/compiler.rs

@@ -21,7 +21,6 @@ use bitcoin::Network;
 use miniscript::policy::Concrete;
 use miniscript::Descriptor;
 
-use bdk::wallet::AddressIndex::New;
 use bdk::{KeychainKind, Wallet};
 
 /// Miniscript policy is a high level abstraction of spending conditions. Defined in the
@@ -51,7 +50,7 @@ fn main() -> Result<(), Box<dyn Error>> {
 
     println!(
         "First derived address from the descriptor: \n{}",
-        wallet.get_address(New)
+        wallet.next_unused_address(KeychainKind::External)?,
     );
 
     // BDK also has it's own `Policy` structure to represent the spending condition in a more

crates/bdk/src/descriptor/template.rs

@@ -74,7 +74,7 @@ impl<T: DescriptorTemplate> IntoWalletDescriptor for T {
 /// ```
 /// # use bdk::bitcoin::{PrivateKey, Network};
 /// # use bdk::Wallet;
-/// # use bdk::wallet::AddressIndex::New;
+/// # use bdk::KeychainKind;
 /// use bdk::template::P2Pkh;
 ///
 /// let key =
@@ -82,7 +82,9 @@ impl<T: DescriptorTemplate> IntoWalletDescriptor for T {
 /// let mut wallet = Wallet::new_no_persist(P2Pkh(key), None, Network::Testnet)?;
 ///
 /// assert_eq!(
-///     wallet.get_address(New).to_string(),
+///     wallet
+///         .next_unused_address(KeychainKind::External)?
+///         .to_string(),
 ///     "mwJ8hxFYW19JLuc65RCTaP4v1rzVU8cVMT"
 /// );
 /// # Ok::<_, Box<dyn std::error::Error>>(())
@@ -102,15 +104,17 @@ impl<K: IntoDescriptorKey<Legacy>> DescriptorTemplate for P2Pkh<K> {
 /// ```
 /// # use bdk::bitcoin::{PrivateKey, Network};
 /// # use bdk::Wallet;
+/// # use bdk::KeychainKind;
 /// use bdk::template::P2Wpkh_P2Sh;
-/// use bdk::wallet::AddressIndex;
 ///
 /// let key =
 ///     bitcoin::PrivateKey::from_wif("cTc4vURSzdx6QE6KVynWGomDbLaA75dNALMNyfjh3p8DRRar84Um")?;
 /// let mut wallet = Wallet::new_no_persist(P2Wpkh_P2Sh(key), None, Network::Testnet)?;
 ///
 /// assert_eq!(
-///     wallet.get_address(AddressIndex::New).to_string(),
+///     wallet
+///         .next_unused_address(KeychainKind::External)?
+///         .to_string(),
 ///     "2NB4ox5VDRw1ecUv6SnT3VQHPXveYztRqk5"
 /// );
 /// # Ok::<_, Box<dyn std::error::Error>>(())
@@ -131,15 +135,17 @@ impl<K: IntoDescriptorKey<Segwitv0>> DescriptorTemplate for P2Wpkh_P2Sh<K> {
 /// ```
 /// # use bdk::bitcoin::{PrivateKey, Network};
 /// # use bdk::{Wallet};
+/// # use bdk::KeychainKind;
 /// use bdk::template::P2Wpkh;
-/// use bdk::wallet::AddressIndex::New;
 ///
 /// let key =
 ///     bitcoin::PrivateKey::from_wif("cTc4vURSzdx6QE6KVynWGomDbLaA75dNALMNyfjh3p8DRRar84Um")?;
 /// let mut wallet = Wallet::new_no_persist(P2Wpkh(key), None, Network::Testnet)?;
 ///
 /// assert_eq!(
-///     wallet.get_address(New).to_string(),
+///     wallet
+///         .next_unused_address(KeychainKind::External)?
+///         .to_string(),
 ///     "tb1q4525hmgw265tl3drrl8jjta7ayffu6jf68ltjd"
 /// );
 /// # Ok::<_, Box<dyn std::error::Error>>(())
@@ -159,7 +165,7 @@ impl<K: IntoDescriptorKey<Segwitv0>> DescriptorTemplate for P2Wpkh<K> {
 /// ```
 /// # use bdk::bitcoin::{PrivateKey, Network};
 /// # use bdk::Wallet;
-/// # use bdk::wallet::AddressIndex::New;
+/// # use bdk::KeychainKind;
 /// use bdk::template::P2TR;
 ///
 /// let key =
@@ -167,7 +173,9 @@ impl<K: IntoDescriptorKey<Segwitv0>> DescriptorTemplate for P2Wpkh<K> {
 /// let mut wallet = Wallet::new_no_persist(P2TR(key), None, Network::Testnet)?;
 ///
 /// assert_eq!(
-///     wallet.get_address(New).to_string(),
+///     wallet
+///         .next_unused_address(KeychainKind::External)?
+///         .to_string(),
 ///     "tb1pvjf9t34fznr53u5tqhejz4nr69luzkhlvsdsdfq9pglutrpve2xq7hps46"
 /// );
 /// # Ok::<_, Box<dyn std::error::Error>>(())
@@ -192,7 +200,6 @@ impl<K: IntoDescriptorKey<Tap>> DescriptorTemplate for P2TR<K> {
 /// # use std::str::FromStr;
 /// # use bdk::bitcoin::{PrivateKey, Network};
 /// # use bdk::{Wallet,  KeychainKind};
-/// # use bdk::wallet::AddressIndex::New;
 /// use bdk::template::Bip44;
 ///
 /// let key = bitcoin::bip32::Xpriv::from_str("tprv8ZgxMBicQKsPeZRHk4rTG6orPS2CRNFX3njhUXx5vj9qGog5ZMH4uGReDWN5kCkY3jmWEtWause41CDvBRXD1shKknAMKxT99o9qUTRVC6m")?;
@@ -202,7 +209,7 @@ impl<K: IntoDescriptorKey<Tap>> DescriptorTemplate for P2TR<K> {
 ///     Network::Testnet,
 /// )?;
 ///
-/// assert_eq!(wallet.get_address(New).to_string(), "mmogjc7HJEZkrLqyQYqJmxUqFaC7i4uf89");
+/// assert_eq!(wallet.next_unused_address(KeychainKind::External)?.to_string(), "mmogjc7HJEZkrLqyQYqJmxUqFaC7i4uf89");
 /// assert_eq!(wallet.public_descriptor(KeychainKind::External).unwrap().to_string(), "pkh([c55b303f/44'/1'/0']tpubDCuorCpzvYS2LCD75BR46KHE8GdDeg1wsAgNZeNr6DaB5gQK1o14uErKwKLuFmeemkQ6N2m3rNgvctdJLyr7nwu2yia7413Hhg8WWE44cgT/0/*)#5wrnv0xt");
 /// # Ok::<_, Box<dyn std::error::Error>>(())
 /// ```
@@ -229,7 +236,6 @@ impl<K: DerivableKey<Legacy>> DescriptorTemplate for Bip44<K> {
 /// # use std::str::FromStr;
 /// # use bdk::bitcoin::{PrivateKey, Network};
 /// # use bdk::{Wallet,  KeychainKind};
-/// # use bdk::wallet::AddressIndex::New;
 /// use bdk::template::Bip44Public;
 ///
 /// let key = bitcoin::bip32::Xpub::from_str("tpubDDDzQ31JkZB7VxUr9bjvBivDdqoFLrDPyLWtLapArAi51ftfmCb2DPxwLQzX65iNcXz1DGaVvyvo6JQ6rTU73r2gqdEo8uov9QKRb7nKCSU")?;
@@ -240,7 +246,7 @@ impl<K: DerivableKey<Legacy>> DescriptorTemplate for Bip44<K> {
 ///     Network::Testnet,
 /// )?;
 ///
-/// assert_eq!(wallet.get_address(New).to_string(), "miNG7dJTzJqNbFS19svRdTCisC65dsubtR");
+/// assert_eq!(wallet.next_unused_address(KeychainKind::External)?.to_string(), "miNG7dJTzJqNbFS19svRdTCisC65dsubtR");
 /// assert_eq!(wallet.public_descriptor(KeychainKind::External).unwrap().to_string(), "pkh([c55b303f/44'/1'/0']tpubDDDzQ31JkZB7VxUr9bjvBivDdqoFLrDPyLWtLapArAi51ftfmCb2DPxwLQzX65iNcXz1DGaVvyvo6JQ6rTU73r2gqdEo8uov9QKRb7nKCSU/0/*)#cfhumdqz");
 /// # Ok::<_, Box<dyn std::error::Error>>(())
 /// ```
@@ -267,7 +273,6 @@ impl<K: DerivableKey<Legacy>> DescriptorTemplate for Bip44Public<K> {
 /// # use std::str::FromStr;
 /// # use bdk::bitcoin::{PrivateKey, Network};
 /// # use bdk::{Wallet,  KeychainKind};
-/// # use bdk::wallet::AddressIndex::New;
 /// use bdk::template::Bip49;
 ///
 /// let key = bitcoin::bip32::Xpriv::from_str("tprv8ZgxMBicQKsPeZRHk4rTG6orPS2CRNFX3njhUXx5vj9qGog5ZMH4uGReDWN5kCkY3jmWEtWause41CDvBRXD1shKknAMKxT99o9qUTRVC6m")?;
@@ -277,7 +282,7 @@ impl<K: DerivableKey<Legacy>> DescriptorTemplate for Bip44Public<K> {
 ///     Network::Testnet,
 /// )?;
 ///
-/// assert_eq!(wallet.get_address(New).to_string(), "2N4zkWAoGdUv4NXhSsU8DvS5MB36T8nKHEB");
+/// assert_eq!(wallet.next_unused_address(KeychainKind::External)?.to_string(), "2N4zkWAoGdUv4NXhSsU8DvS5MB36T8nKHEB");
 /// assert_eq!(wallet.public_descriptor(KeychainKind::External).unwrap().to_string(), "sh(wpkh([c55b303f/49'/1'/0']tpubDDYr4kdnZgjjShzYNjZUZXUUtpXaofdkMaipyS8ThEh45qFmhT4hKYways7UXmg6V7het1QiFo9kf4kYUXyDvV4rHEyvSpys9pjCB3pukxi/0/*))#s9vxlc8e");
 /// # Ok::<_, Box<dyn std::error::Error>>(())
 /// ```
@@ -304,7 +309,6 @@ impl<K: DerivableKey<Segwitv0>> DescriptorTemplate for Bip49<K> {
 /// # use std::str::FromStr;
 /// # use bdk::bitcoin::{PrivateKey, Network};
 /// # use bdk::{Wallet,  KeychainKind};
-/// # use bdk::wallet::AddressIndex::New;
 /// use bdk::template::Bip49Public;
 ///
 /// let key = bitcoin::bip32::Xpub::from_str("tpubDC49r947KGK52X5rBWS4BLs5m9SRY3pYHnvRrm7HcybZ3BfdEsGFyzCMzayi1u58eT82ZeyFZwH7DD6Q83E3fM9CpfMtmnTygnLfP59jL9L")?;
@@ -315,7 +319,7 @@ impl<K: DerivableKey<Segwitv0>> DescriptorTemplate for Bip49<K> {
 ///     Network::Testnet,
 /// )?;
 ///
-/// assert_eq!(wallet.get_address(New).to_string(), "2N3K4xbVAHoiTQSwxkZjWDfKoNC27pLkYnt");
+/// assert_eq!(wallet.next_unused_address(KeychainKind::External)?.to_string(), "2N3K4xbVAHoiTQSwxkZjWDfKoNC27pLkYnt");
 /// assert_eq!(wallet.public_descriptor(KeychainKind::External).unwrap().to_string(), "sh(wpkh([c55b303f/49'/1'/0']tpubDC49r947KGK52X5rBWS4BLs5m9SRY3pYHnvRrm7HcybZ3BfdEsGFyzCMzayi1u58eT82ZeyFZwH7DD6Q83E3fM9CpfMtmnTygnLfP59jL9L/0/*))#3tka9g0q");
 /// # Ok::<_, Box<dyn std::error::Error>>(())
 /// ```
@@ -342,7 +346,6 @@ impl<K: DerivableKey<Segwitv0>> DescriptorTemplate for Bip49Public<K> {
 /// # use std::str::FromStr;
 /// # use bdk::bitcoin::{PrivateKey, Network};
 /// # use bdk::{Wallet,  KeychainKind};
-/// # use bdk::wallet::AddressIndex::New;
 /// use bdk::template::Bip84;
 ///
 /// let key = bitcoin::bip32::Xpriv::from_str("tprv8ZgxMBicQKsPeZRHk4rTG6orPS2CRNFX3njhUXx5vj9qGog5ZMH4uGReDWN5kCkY3jmWEtWause41CDvBRXD1shKknAMKxT99o9qUTRVC6m")?;
@@ -352,7 +355,7 @@ impl<K: DerivableKey<Segwitv0>> DescriptorTemplate for Bip49Public<K> {
 ///     Network::Testnet,
 /// )?;
 ///
-/// assert_eq!(wallet.get_address(New).to_string(), "tb1qhl85z42h7r4su5u37rvvw0gk8j2t3n9y7zsg4n");
+/// assert_eq!(wallet.next_unused_address(KeychainKind::External)?.to_string(), "tb1qhl85z42h7r4su5u37rvvw0gk8j2t3n9y7zsg4n");
 /// assert_eq!(wallet.public_descriptor(KeychainKind::External).unwrap().to_string(), "wpkh([c55b303f/84'/1'/0']tpubDDc5mum24DekpNw92t6fHGp8Gr2JjF9J7i4TZBtN6Vp8xpAULG5CFaKsfugWa5imhrQQUZKXe261asP5koDHo5bs3qNTmf3U3o4v9SaB8gg/0/*)#6kfecsmr");
 /// # Ok::<_, Box<dyn std::error::Error>>(())
 /// ```
@@ -379,7 +382,6 @@ impl<K: DerivableKey<Segwitv0>> DescriptorTemplate for Bip84<K> {
 /// # use std::str::FromStr;
 /// # use bdk::bitcoin::{PrivateKey, Network};
 /// # use bdk::{Wallet,  KeychainKind};
-/// # use bdk::wallet::AddressIndex::New;
 /// use bdk::template::Bip84Public;
 ///
 /// let key = bitcoin::bip32::Xpub::from_str("tpubDC2Qwo2TFsaNC4ju8nrUJ9mqVT3eSgdmy1yPqhgkjwmke3PRXutNGRYAUo6RCHTcVQaDR3ohNU9we59brGHuEKPvH1ags2nevW5opEE9Z5Q")?;
@@ -390,7 +392,7 @@ impl<K: DerivableKey<Segwitv0>> DescriptorTemplate for Bip84<K> {
 ///     Network::Testnet,
 /// )?;
 ///
-/// assert_eq!(wallet.get_address(New).to_string(), "tb1qedg9fdlf8cnnqfd5mks6uz5w4kgpk2pr6y4qc7");
+/// assert_eq!(wallet.next_unused_address(KeychainKind::External)?.to_string(), "tb1qedg9fdlf8cnnqfd5mks6uz5w4kgpk2pr6y4qc7");
 /// assert_eq!(wallet.public_descriptor(KeychainKind::External).unwrap().to_string(), "wpkh([c55b303f/84'/1'/0']tpubDC2Qwo2TFsaNC4ju8nrUJ9mqVT3eSgdmy1yPqhgkjwmke3PRXutNGRYAUo6RCHTcVQaDR3ohNU9we59brGHuEKPvH1ags2nevW5opEE9Z5Q/0/*)#dhu402yv");
 /// # Ok::<_, Box<dyn std::error::Error>>(())
 /// ```
@@ -417,7 +419,6 @@ impl<K: DerivableKey<Segwitv0>> DescriptorTemplate for Bip84Public<K> {
 /// # use std::str::FromStr;
 /// # use bdk::bitcoin::{PrivateKey, Network};
 /// # use bdk::{Wallet,  KeychainKind};
-/// # use bdk::wallet::AddressIndex::New;
 /// use bdk::template::Bip86;
 ///
 /// let key = bitcoin::bip32::Xpriv::from_str("tprv8ZgxMBicQKsPeZRHk4rTG6orPS2CRNFX3njhUXx5vj9qGog5ZMH4uGReDWN5kCkY3jmWEtWause41CDvBRXD1shKknAMKxT99o9qUTRVC6m")?;
@@ -427,7 +428,7 @@ impl<K: DerivableKey<Segwitv0>> DescriptorTemplate for Bip84Public<K> {
 ///     Network::Testnet,
 /// )?;
 ///
-/// assert_eq!(wallet.get_address(New).to_string(), "tb1p5unlj09djx8xsjwe97269kqtxqpwpu2epeskgqjfk4lnf69v4tnqpp35qu");
+/// assert_eq!(wallet.next_unused_address(KeychainKind::External)?.to_string(), "tb1p5unlj09djx8xsjwe97269kqtxqpwpu2epeskgqjfk4lnf69v4tnqpp35qu");
 /// assert_eq!(wallet.public_descriptor(KeychainKind::External).unwrap().to_string(), "tr([c55b303f/86'/1'/0']tpubDCiHofpEs47kx358bPdJmTZHmCDqQ8qw32upCSxHrSEdeeBs2T5Mq6QMB2ukeMqhNBiyhosBvJErteVhfURPGXPv3qLJPw5MVpHUewsbP2m/0/*)#dkgvr5hm");
 /// # Ok::<_, Box<dyn std::error::Error>>(())
 /// ```
@@ -454,7 +455,6 @@ impl<K: DerivableKey<Tap>> DescriptorTemplate for Bip86<K> {
 /// # use std::str::FromStr;
 /// # use bdk::bitcoin::{PrivateKey, Network};
 /// # use bdk::{Wallet,  KeychainKind};
-/// # use bdk::wallet::AddressIndex::New;
 /// use bdk::template::Bip86Public;
 ///
 /// let key = bitcoin::bip32::Xpub::from_str("tpubDC2Qwo2TFsaNC4ju8nrUJ9mqVT3eSgdmy1yPqhgkjwmke3PRXutNGRYAUo6RCHTcVQaDR3ohNU9we59brGHuEKPvH1ags2nevW5opEE9Z5Q")?;
@@ -465,7 +465,7 @@ impl<K: DerivableKey<Tap>> DescriptorTemplate for Bip86<K> {
 ///     Network::Testnet,
 /// )?;
 ///
-/// assert_eq!(wallet.get_address(New).to_string(), "tb1pwjp9f2k5n0xq73ecuu0c5njvgqr3vkh7yaylmpqvsuuaafymh0msvcmh37");
+/// assert_eq!(wallet.next_unused_address(KeychainKind::External)?.to_string(), "tb1pwjp9f2k5n0xq73ecuu0c5njvgqr3vkh7yaylmpqvsuuaafymh0msvcmh37");
 /// assert_eq!(wallet.public_descriptor(KeychainKind::External).unwrap().to_string(), "tr([c55b303f/86'/1'/0']tpubDC2Qwo2TFsaNC4ju8nrUJ9mqVT3eSgdmy1yPqhgkjwmke3PRXutNGRYAUo6RCHTcVQaDR3ohNU9we59brGHuEKPvH1ags2nevW5opEE9Z5Q/0/*)#2p65srku");
 /// # Ok::<_, Box<dyn std::error::Error>>(())
 /// ```

crates/bdk/src/wallet/coin_selection.rs

@@ -28,7 +28,7 @@
 //! # use bitcoin::*;
 //! # use bdk::wallet::{self, ChangeSet, coin_selection::*, coin_selection};
 //! # use bdk::wallet::error::CreateTxError;
-//! # use bdk_chain::PersistBackend;
+//! # use bdk_persist::PersistBackend;
 //! # use bdk::*;
 //! # use bdk::wallet::coin_selection::decide_change;
 //! # use anyhow::Error;

crates/bdk/src/wallet/error.rs

@@ -47,11 +47,11 @@ impl std::error::Error for MiniscriptPsbtError {}
 /// Error returned from [`TxBuilder::finish`]
 ///
 /// [`TxBuilder::finish`]: crate::wallet::tx_builder::TxBuilder::finish
-pub enum CreateTxError<P> {
+pub enum CreateTxError {
     /// There was a problem with the descriptors passed in
     Descriptor(DescriptorError),
-    /// We were unable to write wallet data to the persistence backend
-    Persist(P),
+    /// We were unable to load wallet data from or write wallet data to the persistence backend
+    Persist(anyhow::Error),
     /// There was a problem while extracting and manipulating policies
     Policy(PolicyError),
     /// Spending policy is not compatible with this [`KeychainKind`]
@@ -119,17 +119,14 @@ pub enum CreateTxError<P> {
     MiniscriptPsbt(MiniscriptPsbtError),
 }
 
-impl<P> fmt::Display for CreateTxError<P>
-where
-    P: fmt::Display,
-{
+impl fmt::Display for CreateTxError {
     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
         match self {
             Self::Descriptor(e) => e.fmt(f),
             Self::Persist(e) => {
                 write!(
                     f,
-                    "failed to write wallet data to persistence backend: {}",
+                    "failed to load wallet data from or write wallet data to persistence backend: {}",
                     e
                 )
             }
@@ -214,38 +211,38 @@ where
     }
 }
 
-impl<P> From<descriptor::error::Error> for CreateTxError<P> {
+impl From<descriptor::error::Error> for CreateTxError {
     fn from(err: descriptor::error::Error) -> Self {
         CreateTxError::Descriptor(err)
     }
 }
 
-impl<P> From<PolicyError> for CreateTxError<P> {
+impl From<PolicyError> for CreateTxError {
     fn from(err: PolicyError) -> Self {
         CreateTxError::Policy(err)
     }
 }
 
-impl<P> From<MiniscriptPsbtError> for CreateTxError<P> {
+impl From<MiniscriptPsbtError> for CreateTxError {
     fn from(err: MiniscriptPsbtError) -> Self {
         CreateTxError::MiniscriptPsbt(err)
     }
 }
 
-impl<P> From<psbt::Error> for CreateTxError<P> {
+impl From<psbt::Error> for CreateTxError {
     fn from(err: psbt::Error) -> Self {
         CreateTxError::Psbt(err)
     }
 }
 
-impl<P> From<coin_selection::Error> for CreateTxError<P> {
+impl From<coin_selection::Error> for CreateTxError {
     fn from(err: coin_selection::Error) -> Self {
         CreateTxError::CoinSelection(err)
     }
 }
 
 #[cfg(feature = "std")]
-impl<P: core::fmt::Display + core::fmt::Debug> std::error::Error for CreateTxError<P> {}
+impl std::error::Error for CreateTxError {}
 
 #[derive(Debug)]
 /// Error returned from [`Wallet::build_fee_bump`]

crates/bdk/src/wallet/export.rs

@@ -53,9 +53,9 @@
 //! # Ok::<_, Box<dyn std::error::Error>>(())
 //! ```
 
+use alloc::string::String;
+use core::fmt;
 use core::str::FromStr;
-
-use alloc::string::{String, ToString};
 use serde::{Deserialize, Serialize};
 
 use miniscript::descriptor::{ShInner, WshInner};
@@ -80,9 +80,9 @@ pub struct FullyNodedExport {
     pub label: String,
 }
 
-impl ToString for FullyNodedExport {
-    fn to_string(&self) -> String {
-        serde_json::to_string(self).unwrap()
+impl fmt::Display for FullyNodedExport {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        write!(f, "{}", serde_json::to_string(self).unwrap())
     }
 }
 
@@ -110,8 +110,8 @@ impl FullyNodedExport {
     ///
     /// If the database is empty or `include_blockheight` is false, the `blockheight` field
     /// returned will be `0`.
-    pub fn export_wallet<D>(
-        wallet: &Wallet<D>,
+    pub fn export_wallet(
+        wallet: &Wallet,
         label: &str,
         include_blockheight: bool,
     ) -> Result<Self, &'static str> {
@@ -214,6 +214,7 @@ impl FullyNodedExport {
 mod test {
     use core::str::FromStr;
 
+    use crate::std::string::ToString;
     use bdk_chain::{BlockId, ConfirmationTime};
     use bitcoin::hashes::Hash;
     use bitcoin::{transaction, BlockHash, Network, Transaction};
@@ -225,7 +226,7 @@ mod test {
         descriptor: &str,
         change_descriptor: Option<&str>,
         network: Network,
-    ) -> Wallet<()> {
+    ) -> Wallet {
         let mut wallet = Wallet::new_no_persist(descriptor, change_descriptor, network).unwrap();
         let transaction = Transaction {
             input: vec![],

crates/bdk/src/wallet/mod.rs

@@ -26,10 +26,12 @@ use bdk_chain::{
     local_chain::{
         self, ApplyHeaderError, CannotConnectError, CheckPoint, CheckPointIter, LocalChain,
     },
+    spk_client::{FullScanRequest, FullScanResult, SyncRequest, SyncResult},
     tx_graph::{CanonicalTx, TxGraph},
     Append, BlockId, ChainPosition, ConfirmationTime, ConfirmationTimeHeightAnchor, FullTxOut,
-    IndexedTxGraph, Persist, PersistBackend,
+    IndexedTxGraph,
 };
+use bdk_persist::{Persist, PersistBackend};
 use bitcoin::constants::genesis_block;
 use bitcoin::secp256k1::{All, Secp256k1};
 use bitcoin::sighash::{EcdsaSighashType, TapSighashType};
@@ -82,12 +84,12 @@ const COINBASE_MATURITY: u32 = 100;
 ///
 /// [`signer`]: crate::signer
 #[derive(Debug)]
-pub struct Wallet<D = ()> {
+pub struct Wallet {
     signers: Arc<SignersContainer>,
     change_signers: Arc<SignersContainer>,
     chain: LocalChain,
     indexed_graph: IndexedTxGraph<ConfirmationTimeHeightAnchor, KeychainTxOutIndex<KeychainKind>>,
-    persist: Persist<D, ChangeSet>,
+    persist: Persist<ChangeSet>,
     network: Network,
     secp: SecpCtx,
 }
@@ -107,7 +109,27 @@ pub struct Update {
     /// Update for the wallet's internal [`LocalChain`].
     ///
     /// [`LocalChain`]: local_chain::LocalChain
-    pub chain: Option<local_chain::Update>,
+    pub chain: Option<CheckPoint>,
+}
+
+impl From<FullScanResult<KeychainKind>> for Update {
+    fn from(value: FullScanResult<KeychainKind>) -> Self {
+        Self {
+            last_active_indices: value.last_active_indices,
+            graph: value.graph_update,
+            chain: Some(value.chain_update),
+        }
+    }
+}
+
+impl From<SyncResult> for Update {
+    fn from(value: SyncResult) -> Self {
+        Self {
+            last_active_indices: BTreeMap::new(),
+            graph: value.graph_update,
+            chain: Some(value.chain_update),
+        }
+    }
 }
 
 /// The changes made to a wallet by applying an [`Update`].
@@ -178,28 +200,6 @@ impl
     }
 }
 
-/// The address index selection strategy to use to derived an address from the wallet's external
-/// descriptor. See [`Wallet::get_address`]. If you're unsure which one to use use `WalletIndex::New`.
-#[derive(Debug)]
-pub enum AddressIndex {
-    /// Return a new address after incrementing the current descriptor index.
-    New,
-    /// Return the address for the current descriptor index if it has not been used in a received
-    /// transaction. Otherwise return a new address as with [`AddressIndex::New`].
-    ///
-    /// Use with caution, if the wallet has not yet detected an address has been used it could
-    /// return an already used address. This function is primarily meant for situations where the
-    /// caller is untrusted; for example when deriving donation addresses on-demand for a public
-    /// web page.
-    LastUnused,
-    /// Return the address for a specific descriptor index. Does not change the current descriptor
-    /// index used by `AddressIndex::New` and `AddressIndex::LastUsed`.
-    ///
-    /// Use with caution, if an index is given that is less than the current descriptor index
-    /// then the returned address may have already been used.
-    Peek(u32),
-}
-
 /// A derived address and the index it was found at.
 /// For convenience this automatically derefs to `Address`
 #[derive(Debug, PartialEq, Eq)]
@@ -236,7 +236,7 @@ impl Wallet {
         Self::new(descriptor, change_descriptor, (), network).map_err(|e| match e {
             NewError::NonEmptyDatabase => unreachable!("mock-database cannot have data"),
             NewError::Descriptor(e) => e,
-            NewError::Write(_) => unreachable!("mock-write must always succeed"),
+            NewError::Persist(_) => unreachable!("mock-write must always succeed"),
         })
     }
 
@@ -251,44 +251,11 @@ impl Wallet {
             .map_err(|e| match e {
                 NewError::NonEmptyDatabase => unreachable!("mock-database cannot have data"),
                 NewError::Descriptor(e) => e,
-                NewError::Write(_) => unreachable!("mock-write must always succeed"),
+                NewError::Persist(_) => unreachable!("mock-write must always succeed"),
             })
     }
 }
 
-impl<D> Wallet<D>
-where
-    D: PersistBackend<ChangeSet, WriteError = core::convert::Infallible>,
-{
-    /// Infallibly return a derived address using the external descriptor, see [`AddressIndex`] for
-    /// available address index selection strategies. If none of the keys in the descriptor are derivable
-    /// (i.e. does not end with /*) then the same address will always be returned for any [`AddressIndex`].
-    ///
-    /// # Panics
-    ///
-    /// This panics when the caller requests for an address of derivation index greater than the
-    /// BIP32 max index.
-    pub fn get_address(&mut self, address_index: AddressIndex) -> AddressInfo {
-        self.try_get_address(address_index).unwrap()
-    }
-
-    /// Infallibly return a derived address using the internal (change) descriptor.
-    ///
-    /// If the wallet doesn't have an internal descriptor it will use the external descriptor.
-    ///
-    /// see [`AddressIndex`] for available address index selection strategies. If none of the keys
-    /// in the descriptor are derivable (i.e. does not end with /*) then the same address will always
-    /// be returned for any [`AddressIndex`].
-    ///
-    /// # Panics
-    ///
-    /// This panics when the caller requests for an address of derivation index greater than the
-    /// BIP32 max index.
-    pub fn get_internal_address(&mut self, address_index: AddressIndex) -> AddressInfo {
-        self.try_get_internal_address(address_index).unwrap()
-    }
-}
-
 /// The error type when constructing a fresh [`Wallet`].
 ///
 /// Methods [`new`] and [`new_with_genesis_hash`] may return this error.
@@ -296,19 +263,16 @@ where
 /// [`new`]: Wallet::new
 /// [`new_with_genesis_hash`]: Wallet::new_with_genesis_hash
 #[derive(Debug)]
-pub enum NewError<W> {
+pub enum NewError {
     /// Database already has data.
     NonEmptyDatabase,
     /// There was problem with the passed-in descriptor(s).
     Descriptor(crate::descriptor::DescriptorError),
     /// We were unable to write the wallet's data to the persistence backend.
-    Write(W),
+    Persist(anyhow::Error),
 }
 
-impl<W> fmt::Display for NewError<W>
-where
-    W: fmt::Display,
-{
+impl fmt::Display for NewError {
     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
         match self {
             NewError::NonEmptyDatabase => write!(
@@ -316,13 +280,13 @@ where
                 "database already has data - use `load` or `new_or_load` methods instead"
             ),
             NewError::Descriptor(e) => e.fmt(f),
-            NewError::Write(e) => e.fmt(f),
+            NewError::Persist(e) => e.fmt(f),
         }
     }
 }
 
 #[cfg(feature = "std")]
-impl<W> std::error::Error for NewError<W> where W: core::fmt::Display + core::fmt::Debug {}
+impl std::error::Error for NewError {}
 
 /// The error type when loading a [`Wallet`] from persistence.
 ///
@@ -330,11 +294,11 @@ impl<W> std::error::Error for NewError<W> where W: core::fmt::Display + core::fm
 ///
 /// [`load`]: Wallet::load
 #[derive(Debug)]
-pub enum LoadError<L> {
+pub enum LoadError {
     /// There was a problem with the passed-in descriptor(s).
     Descriptor(crate::descriptor::DescriptorError),
     /// Loading data from the persistence backend failed.
-    Load(L),
+    Persist(anyhow::Error),
     /// Wallet not initialized, persistence backend is empty.
     NotInitialized,
     /// Data loaded from persistence is missing network type.
@@ -343,14 +307,11 @@ pub enum LoadError<L> {
     MissingGenesis,
 }
 
-impl<L> fmt::Display for LoadError<L>
-where
-    L: fmt::Display,
-{
+impl fmt::Display for LoadError {
     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
         match self {
             LoadError::Descriptor(e) => e.fmt(f),
-            LoadError::Load(e) => e.fmt(f),
+            LoadError::Persist(e) => e.fmt(f),
             LoadError::NotInitialized => {
                 write!(f, "wallet is not initialized, persistence backend is empty")
             }
@@ -361,7 +322,7 @@ where
 }
 
 #[cfg(feature = "std")]
-impl<L> std::error::Error for LoadError<L> where L: core::fmt::Display + core::fmt::Debug {}
+impl std::error::Error for LoadError {}
 
 /// Error type for when we try load a [`Wallet`] from persistence and creating it if non-existent.
 ///
@@ -370,13 +331,11 @@ impl<L> std::error::Error for LoadError<L> where L: core::fmt::Display + core::f
 /// [`new_or_load`]: Wallet::new_or_load
 /// [`new_or_load_with_genesis_hash`]: Wallet::new_or_load_with_genesis_hash
 #[derive(Debug)]
-pub enum NewOrLoadError<W, L> {
+pub enum NewOrLoadError {
     /// There is a problem with the passed-in descriptor.
     Descriptor(crate::descriptor::DescriptorError),
-    /// Writing to the persistence backend failed.
-    Write(W),
-    /// Loading from the persistence backend failed.
-    Load(L),
+    /// Either writing to or loading from the persistence backend failed.
+    Persist(anyhow::Error),
     /// Wallet is not initialized, persistence backend is empty.
     NotInitialized,
     /// The loaded genesis hash does not match what was provided.
@@ -395,16 +354,15 @@ pub enum NewOrLoadError<W, L> {
     },
 }
 
-impl<W, L> fmt::Display for NewOrLoadError<W, L>
-where
-    W: fmt::Display,
-    L: fmt::Display,
-{
+impl fmt::Display for NewOrLoadError {
     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
         match self {
             NewOrLoadError::Descriptor(e) => e.fmt(f),
-            NewOrLoadError::Write(e) => write!(f, "failed to write to persistence: {}", e),
-            NewOrLoadError::Load(e) => write!(f, "failed to load from persistence: {}", e),
+            NewOrLoadError::Persist(e) => write!(
+                f,
+                "failed to either write to or load from persistence, {}",
+                e
+            ),
             NewOrLoadError::NotInitialized => {
                 write!(f, "wallet is not initialized, persistence backend is empty")
             }
@@ -419,12 +377,7 @@ where
 }
 
 #[cfg(feature = "std")]
-impl<W, L> std::error::Error for NewOrLoadError<W, L>
-where
-    W: core::fmt::Display + core::fmt::Debug,
-    L: core::fmt::Display + core::fmt::Debug,
-{
-}
+impl std::error::Error for NewOrLoadError {}
 
 /// An error that may occur when inserting a transaction into [`Wallet`].
 #[derive(Debug)]
@@ -488,17 +441,14 @@ impl fmt::Display for ApplyBlockError {
 #[cfg(feature = "std")]
 impl std::error::Error for ApplyBlockError {}
 
-impl<D> Wallet<D> {
+impl Wallet {
     /// Initialize an empty [`Wallet`].
     pub fn new<E: IntoWalletDescriptor>(
         descriptor: E,
         change_descriptor: Option<E>,
-        db: D,
+        db: impl PersistBackend<ChangeSet> + Send + Sync + 'static,
         network: Network,
-    ) -> Result<Self, NewError<D::WriteError>>
-    where
-        D: PersistBackend<ChangeSet>,
-    {
+    ) -> Result<Self, NewError> {
         let genesis_hash = genesis_block(network).block_hash();
         Self::new_with_genesis_hash(descriptor, change_descriptor, db, network, genesis_hash)
     }
@@ -510,13 +460,10 @@ impl<D> Wallet<D> {
     pub fn new_with_genesis_hash<E: IntoWalletDescriptor>(
         descriptor: E,
         change_descriptor: Option<E>,
-        mut db: D,
+        mut db: impl PersistBackend<ChangeSet> + Send + Sync + 'static,
         network: Network,
         genesis_hash: BlockHash,
-    ) -> Result<Self, NewError<D::WriteError>>
-    where
-        D: PersistBackend<ChangeSet>,
-    {
+    ) -> Result<Self, NewError> {
         if let Ok(changeset) = db.load_from_persistence() {
             if changeset.is_some() {
                 return Err(NewError::NonEmptyDatabase);
@@ -538,7 +485,7 @@ impl<D> Wallet<D> {
             indexed_tx_graph: indexed_graph.initial_changeset(),
             network: Some(network),
         });
-        persist.commit().map_err(NewError::Write)?;
+        persist.commit().map_err(NewError::Persist)?;
 
         Ok(Wallet {
             signers,
@@ -555,14 +502,11 @@ impl<D> Wallet<D> {
     pub fn load<E: IntoWalletDescriptor>(
         descriptor: E,
         change_descriptor: Option<E>,
-        mut db: D,
-    ) -> Result<Self, LoadError<D::LoadError>>
-    where
-        D: PersistBackend<ChangeSet>,
-    {
+        mut db: impl PersistBackend<ChangeSet> + Send + Sync + 'static,
+    ) -> Result<Self, LoadError> {
         let changeset = db
             .load_from_persistence()
-            .map_err(LoadError::Load)?
+            .map_err(LoadError::Persist)?
             .ok_or(LoadError::NotInitialized)?;
         Self::load_from_changeset(descriptor, change_descriptor, db, changeset)
     }
@@ -570,12 +514,9 @@ impl<D> Wallet<D> {
     fn load_from_changeset<E: IntoWalletDescriptor>(
         descriptor: E,
         change_descriptor: Option<E>,
-        db: D,
+        db: impl PersistBackend<ChangeSet> + Send + Sync + 'static,
         changeset: ChangeSet,
-    ) -> Result<Self, LoadError<D::LoadError>>
-    where
-        D: PersistBackend<ChangeSet>,
-    {
+    ) -> Result<Self, LoadError> {
         let secp = Secp256k1::new();
         let network = changeset.network.ok_or(LoadError::MissingNetwork)?;
         let chain =
@@ -608,12 +549,9 @@ impl<D> Wallet<D> {
     pub fn new_or_load<E: IntoWalletDescriptor>(
         descriptor: E,
         change_descriptor: Option<E>,
-        db: D,
+        db: impl PersistBackend<ChangeSet> + Send + Sync + 'static,
         network: Network,
-    ) -> Result<Self, NewOrLoadError<D::WriteError, D::LoadError>>
-    where
-        D: PersistBackend<ChangeSet>,
-    {
+    ) -> Result<Self, NewOrLoadError> {
         let genesis_hash = genesis_block(network).block_hash();
         Self::new_or_load_with_genesis_hash(
             descriptor,
@@ -633,21 +571,20 @@ impl<D> Wallet<D> {
     pub fn new_or_load_with_genesis_hash<E: IntoWalletDescriptor>(
         descriptor: E,
         change_descriptor: Option<E>,
-        mut db: D,
+        mut db: impl PersistBackend<ChangeSet> + Send + Sync + 'static,
         network: Network,
         genesis_hash: BlockHash,
-    ) -> Result<Self, NewOrLoadError<D::WriteError, D::LoadError>>
-    where
-        D: PersistBackend<ChangeSet>,
-    {
-        let changeset = db.load_from_persistence().map_err(NewOrLoadError::Load)?;
+    ) -> Result<Self, NewOrLoadError> {
+        let changeset = db
+            .load_from_persistence()
+            .map_err(NewOrLoadError::Persist)?;
         match changeset {
             Some(changeset) => {
                 let wallet =
                     Self::load_from_changeset(descriptor, change_descriptor, db, changeset)
                         .map_err(|e| match e {
                             LoadError::Descriptor(e) => NewOrLoadError::Descriptor(e),
-                            LoadError::Load(e) => NewOrLoadError::Load(e),
+                            LoadError::Persist(e) => NewOrLoadError::Persist(e),
                             LoadError::NotInitialized => NewOrLoadError::NotInitialized,
                             LoadError::MissingNetwork => {
                                 NewOrLoadError::LoadedNetworkDoesNotMatch {
@@ -688,7 +625,7 @@ impl<D> Wallet<D> {
                     unreachable!("database is already checked to have no data")
                 }
                 NewError::Descriptor(e) => NewOrLoadError::Descriptor(e),
-                NewError::Write(e) => NewOrLoadError::Write(e),
+                NewError::Persist(e) => NewOrLoadError::Persist(e),
             }),
         }
     }
@@ -703,116 +640,146 @@ impl<D> Wallet<D> {
         self.indexed_graph.index.keychains()
     }
 
-    /// Return a derived address using the external descriptor, see [`AddressIndex`] for
-    /// available address index selection strategies. If none of the keys in the descriptor are derivable
-    /// (i.e. does not end with /*) then the same address will always be returned for any [`AddressIndex`].
+    /// Peek an address of the given `keychain` at `index` without revealing it.
     ///
-    /// A `PersistBackend<ChangeSet>::WriteError` will result if unable to persist the new address
-    /// to the `PersistBackend`.
+    /// For non-wildcard descriptors this returns the same address at every provided index.
     ///
     /// # Panics
     ///
     /// This panics when the caller requests for an address of derivation index greater than the
-    /// BIP32 max index.
-    pub fn try_get_address(
-        &mut self,
-        address_index: AddressIndex,
-    ) -> Result<AddressInfo, D::WriteError>
-    where
-        D: PersistBackend<ChangeSet>,
-    {
-        self._get_address(KeychainKind::External, address_index)
-    }
-
-    /// Return a derived address using the internal (change) descriptor.
-    ///
-    /// If the wallet doesn't have an internal descriptor it will use the external descriptor.
-    ///
-    /// A `PersistBackend<ChangeSet>::WriteError` will result if unable to persist the new address
-    /// to the `PersistBackend`.
-    ///
-    /// see [`AddressIndex`] for available address index selection strategies. If none of the keys
-    /// in the descriptor are derivable (i.e. does not end with /*) then the same address will always
-    /// be returned for any [`AddressIndex`].
-    ///
-    /// # Panics
-    ///
-    /// This panics when the caller requests for an address of derivation index greater than the
-    /// BIP32 max index.
-    pub fn try_get_internal_address(
-        &mut self,
-        address_index: AddressIndex,
-    ) -> Result<AddressInfo, D::WriteError>
-    where
-        D: PersistBackend<ChangeSet>,
-    {
-        self._get_address(KeychainKind::Internal, address_index)
-    }
-
-    /// Return a derived address using the specified `keychain` (external/internal).
-    ///
-    /// If `keychain` is [`KeychainKind::External`], external addresses will be derived (used for
-    /// receiving funds).
-    ///
-    /// If `keychain` is [`KeychainKind::Internal`], internal addresses will be derived (used for
-    /// creating change outputs). If the wallet does not have an internal keychain, it will use the
-    /// external keychain to derive change outputs.
-    ///
-    /// See [`AddressIndex`] for available address index selection strategies. If none of the keys
-    /// in the descriptor are derivable (i.e. does not end with /*) then the same address will
-    /// always be returned for any [`AddressIndex`].
-    ///
-    /// # Panics
-    ///
-    /// This panics when the caller requests for an address of derivation index greater than the
-    /// BIP32 max index.
-    fn _get_address(
-        &mut self,
-        keychain: KeychainKind,
-        address_index: AddressIndex,
-    ) -> Result<AddressInfo, D::WriteError>
-    where
-        D: PersistBackend<ChangeSet>,
-    {
+    /// [BIP32](https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki) max index.
+    pub fn peek_address(&self, keychain: KeychainKind, mut index: u32) -> AddressInfo {
         let keychain = self.map_keychain(keychain);
-        let txout_index = &mut self.indexed_graph.index;
-        let (index, spk, changeset) = match address_index {
-            AddressIndex::New => {
-                let ((index, spk), index_changeset) = txout_index.reveal_next_spk(&keychain);
-                (index, spk.into(), Some(index_changeset))
-            }
-            AddressIndex::LastUnused => {
-                let ((index, spk), index_changeset) = txout_index.next_unused_spk(&keychain);
-                (index, spk.into(), Some(index_changeset))
-            }
-            AddressIndex::Peek(mut peek_index) => {
-                let mut spk_iter = txout_index.unbounded_spk_iter(&keychain);
-                if !spk_iter.descriptor().has_wildcard() {
-                    peek_index = 0;
-                }
-                let (index, spk) = spk_iter
-                    .nth(peek_index as usize)
-                    .expect("derivation index is out of bounds");
-                (index, spk, None)
-            }
-        };
-
-        if let Some(changeset) = changeset {
-            self.persist
-                .stage(ChangeSet::from(indexed_tx_graph::ChangeSet::from(
-                    changeset,
-                )));
-            self.persist.commit()?;
+        let mut spk_iter = self.indexed_graph.index.unbounded_spk_iter(&keychain);
+        if !spk_iter.descriptor().has_wildcard() {
+            index = 0;
         }
+        let (index, spk) = spk_iter
+            .nth(index as usize)
+            .expect("derivation index is out of bounds");
+
+        AddressInfo {
+            index,
+            address: Address::from_script(&spk, self.network).expect("must have address form"),
+            keychain,
+        }
+    }
+
+    /// Attempt to reveal the next address of the given `keychain`.
+    ///
+    /// This will increment the internal derivation index. If the keychain's descriptor doesn't
+    /// contain a wildcard or every address is already revealed up to the maximum derivation
+    /// index defined in [BIP32](https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki),
+    /// then returns the last revealed address.
+    ///
+    /// # Errors
+    ///
+    /// If writing to persistent storage fails.
+    pub fn reveal_next_address(&mut self, keychain: KeychainKind) -> anyhow::Result<AddressInfo> {
+        let keychain = self.map_keychain(keychain);
+        let ((index, spk), index_changeset) = self.indexed_graph.index.reveal_next_spk(&keychain);
+
+        self.persist
+            .stage_and_commit(indexed_tx_graph::ChangeSet::from(index_changeset).into())?;
 
         Ok(AddressInfo {
             index,
-            address: Address::from_script(&spk, self.network)
-                .expect("descriptor must have address form"),
+            address: Address::from_script(spk, self.network).expect("must have address form"),
             keychain,
         })
     }
 
+    /// Reveal addresses up to and including the target `index` and return an iterator
+    /// of newly revealed addresses.
+    ///
+    /// If the target `index` is unreachable, we make a best effort to reveal up to the last
+    /// possible index. If all addresses up to the given `index` are already revealed, then
+    /// no new addresses are returned.
+    ///
+    /// # Errors
+    ///
+    /// If writing to persistent storage fails.
+    pub fn reveal_addresses_to(
+        &mut self,
+        keychain: KeychainKind,
+        index: u32,
+    ) -> anyhow::Result<impl Iterator<Item = AddressInfo> + '_> {
+        let keychain = self.map_keychain(keychain);
+        let (spk_iter, index_changeset) =
+            self.indexed_graph.index.reveal_to_target(&keychain, index);
+
+        self.persist
+            .stage_and_commit(indexed_tx_graph::ChangeSet::from(index_changeset).into())?;
+
+        Ok(spk_iter.map(move |(index, spk)| AddressInfo {
+            index,
+            address: Address::from_script(&spk, self.network).expect("must have address form"),
+            keychain,
+        }))
+    }
+
+    /// Get the next unused address for the given `keychain`, i.e. the address with the lowest
+    /// derivation index that hasn't been used.
+    ///
+    /// This will attempt to derive and reveal a new address if no newly revealed addresses
+    /// are available. See also [`reveal_next_address`](Self::reveal_next_address).
+    ///
+    /// # Errors
+    ///
+    /// If writing to persistent storage fails.
+    pub fn next_unused_address(&mut self, keychain: KeychainKind) -> anyhow::Result<AddressInfo> {
+        let keychain = self.map_keychain(keychain);
+        let ((index, spk), index_changeset) = self.indexed_graph.index.next_unused_spk(&keychain);
+
+        self.persist
+            .stage_and_commit(indexed_tx_graph::ChangeSet::from(index_changeset).into())?;
+
+        Ok(AddressInfo {
+            index,
+            address: Address::from_script(spk, self.network).expect("must have address form"),
+            keychain,
+        })
+    }
+
+    /// Marks an address used of the given `keychain` at `index`.
+    ///
+    /// Returns whether the given index was present and then removed from the unused set.
+    pub fn mark_used(&mut self, keychain: KeychainKind, index: u32) -> bool {
+        self.indexed_graph.index.mark_used(keychain, index)
+    }
+
+    /// Undoes the effect of [`mark_used`] and returns whether the `index` was inserted
+    /// back into the unused set.
+    ///
+    /// Since this is only a superficial marker, it will have no effect if the address at the given
+    /// `index` was actually used, i.e. the wallet has previously indexed a tx output for the
+    /// derived spk.
+    ///
+    /// [`mark_used`]: Self::mark_used
+    pub fn unmark_used(&mut self, keychain: KeychainKind, index: u32) -> bool {
+        self.indexed_graph.index.unmark_used(keychain, index)
+    }
+
+    /// List addresses that are revealed but unused.
+    ///
+    /// Note if the returned iterator is empty you can reveal more addresses
+    /// by using [`reveal_next_address`](Self::reveal_next_address) or
+    /// [`reveal_addresses_to`](Self::reveal_addresses_to).
+    pub fn list_unused_addresses(
+        &self,
+        keychain: KeychainKind,
+    ) -> impl DoubleEndedIterator<Item = AddressInfo> + '_ {
+        let keychain = self.map_keychain(keychain);
+        self.indexed_graph
+            .index
+            .unused_keychain_spks(&keychain)
+            .map(move |(index, spk)| AddressInfo {
+                index,
+                address: Address::from_script(spk, self.network).expect("must have address form"),
+                keychain,
+            })
+    }
+
     /// Return whether or not a `script` is part of this wallet (either internal or external)
     pub fn is_mine(&self, script: &Script) -> bool {
         self.indexed_graph.index.index_of_spk(script).is_some()
@@ -918,10 +885,7 @@ impl<D> Wallet<D> {
     /// [`list_unspent`]: Self::list_unspent
     /// [`list_output`]: Self::list_output
     /// [`commit`]: Self::commit
-    pub fn insert_txout(&mut self, outpoint: OutPoint, txout: TxOut)
-    where
-        D: PersistBackend<ChangeSet>,
-    {
+    pub fn insert_txout(&mut self, outpoint: OutPoint, txout: TxOut) {
         let additions = self.indexed_graph.insert_txout(outpoint, txout);
         self.persist.stage(ChangeSet::from(additions));
     }
@@ -938,7 +902,7 @@ impl<D> Wallet<D> {
     /// ```rust, no_run
     /// # use bitcoin::Txid;
     /// # use bdk::Wallet;
-    /// # let mut wallet: Wallet<()> = todo!();
+    /// # let mut wallet: Wallet = todo!();
     /// # let txid:Txid = todo!();
     /// let tx = wallet.get_tx(txid).expect("transaction").tx_node.tx;
     /// let fee = wallet.calculate_fee(&tx).expect("fee");
@@ -947,7 +911,7 @@ impl<D> Wallet<D> {
     /// ```rust, no_run
     /// # use bitcoin::Psbt;
     /// # use bdk::Wallet;
-    /// # let mut wallet: Wallet<()> = todo!();
+    /// # let mut wallet: Wallet = todo!();
     /// # let mut psbt: Psbt = todo!();
     /// let tx = &psbt.clone().extract_tx().expect("tx");
     /// let fee = wallet.calculate_fee(tx).expect("fee");
@@ -969,7 +933,7 @@ impl<D> Wallet<D> {
     /// ```rust, no_run
     /// # use bitcoin::Txid;
     /// # use bdk::Wallet;
-    /// # let mut wallet: Wallet<()> = todo!();
+    /// # let mut wallet: Wallet = todo!();
     /// # let txid:Txid = todo!();
     /// let tx = wallet.get_tx(txid).expect("transaction").tx_node.tx;
     /// let fee_rate = wallet.calculate_fee_rate(&tx).expect("fee rate");
@@ -978,7 +942,7 @@ impl<D> Wallet<D> {
     /// ```rust, no_run
     /// # use bitcoin::Psbt;
     /// # use bdk::Wallet;
-    /// # let mut wallet: Wallet<()> = todo!();
+    /// # let mut wallet: Wallet = todo!();
     /// # let mut psbt: Psbt = todo!();
     /// let tx = &psbt.clone().extract_tx().expect("tx");
     /// let fee_rate = wallet.calculate_fee_rate(tx).expect("fee rate");
@@ -1000,7 +964,7 @@ impl<D> Wallet<D> {
     /// ```rust, no_run
     /// # use bitcoin::Txid;
     /// # use bdk::Wallet;
-    /// # let mut wallet: Wallet<()> = todo!();
+    /// # let mut wallet: Wallet = todo!();
     /// # let txid:Txid = todo!();
     /// let tx = wallet.get_tx(txid).expect("tx exists").tx_node.tx;
     /// let (sent, received) = wallet.sent_and_received(&tx);
@@ -1009,13 +973,13 @@ impl<D> Wallet<D> {
     /// ```rust, no_run
     /// # use bitcoin::Psbt;
     /// # use bdk::Wallet;
-    /// # let mut wallet: Wallet<()> = todo!();
+    /// # let mut wallet: Wallet = todo!();
     /// # let mut psbt: Psbt = todo!();
     /// let tx = &psbt.clone().extract_tx().expect("tx");
     /// let (sent, received) = wallet.sent_and_received(tx);
     /// ```
     pub fn sent_and_received(&self, tx: &Transaction) -> (u64, u64) {
-        self.indexed_graph.index.sent_and_received(tx)
+        self.indexed_graph.index.sent_and_received(tx, ..)
     }
 
     /// Get a single transaction from the wallet as a [`CanonicalTx`] (if the transaction exists).
@@ -1031,7 +995,7 @@ impl<D> Wallet<D> {
     /// ```rust, no_run
     /// use bdk::{chain::ChainPosition, Wallet};
     /// use bdk_chain::Anchor;
-    /// # let wallet: Wallet<()> = todo!();
+    /// # let wallet: Wallet = todo!();
     /// # let my_txid: bitcoin::Txid = todo!();
     ///
     /// let canonical_tx = wallet.get_tx(my_txid).expect("panic if tx does not exist");
@@ -1087,10 +1051,7 @@ impl<D> Wallet<D> {
     pub fn insert_checkpoint(
         &mut self,
         block_id: BlockId,
-    ) -> Result<bool, local_chain::AlterCheckPointError>
-    where
-        D: PersistBackend<ChangeSet>,
-    {
+    ) -> Result<bool, local_chain::AlterCheckPointError> {
         let changeset = self.chain.insert_block(block_id)?;
         let changed = !changeset.is_empty();
         self.persist.stage(changeset.into());
@@ -1118,10 +1079,7 @@ impl<D> Wallet<D> {
         &mut self,
         tx: Transaction,
         position: ConfirmationTime,
-    ) -> Result<bool, InsertTxError>
-    where
-        D: PersistBackend<ChangeSet>,
-    {
+    ) -> Result<bool, InsertTxError> {
         let (anchor, last_seen) = match position {
             ConfirmationTime::Confirmed { height, time } => {
                 // anchor tx to checkpoint with lowest height that is >= position's height
@@ -1231,7 +1189,7 @@ impl<D> Wallet<D> {
     /// # use bdk::*;
     /// # use bdk::wallet::ChangeSet;
     /// # use bdk::wallet::error::CreateTxError;
-    /// # use bdk_chain::PersistBackend;
+    /// # use bdk_persist::PersistBackend;
     /// # use anyhow::Error;
     /// # let descriptor = "wpkh(tpubD6NzVbkrYhZ4Xferm7Pz4VnjdcDPFyjVu5K4iZXQ4pVN8Cks4pHVowTBXBKRhX64pkRyJZJN5xAKj4UDNnLPb5p2sSKXhewoYx5GbTdUFWq/*)";
     /// # let mut wallet = doctest_wallet!();
@@ -1248,7 +1206,7 @@ impl<D> Wallet<D> {
     /// ```
     ///
     /// [`TxBuilder`]: crate::TxBuilder
-    pub fn build_tx(&mut self) -> TxBuilder<'_, D, DefaultCoinSelectionAlgorithm, CreateTx> {
+    pub fn build_tx(&mut self) -> TxBuilder<'_, DefaultCoinSelectionAlgorithm, CreateTx> {
         TxBuilder {
             wallet: alloc::rc::Rc::new(core::cell::RefCell::new(self)),
             params: TxParams::default(),
@@ -1261,10 +1219,7 @@ impl<D> Wallet<D> {
         &mut self,
         coin_selection: Cs,
         params: TxParams,
-    ) -> Result<Psbt, CreateTxError<D::WriteError>>
-    where
-        D: PersistBackend<ChangeSet>,
-    {
+    ) -> Result<Psbt, CreateTxError> {
         let external_descriptor = self
             .indexed_graph
             .index
@@ -1283,7 +1238,7 @@ impl<D> Wallet<D> {
         let internal_policy = internal_descriptor
             .as_ref()
             .map(|desc| {
-                Ok::<_, CreateTxError<D::WriteError>>(
+                Ok::<_, CreateTxError>(
                     desc.extract_policy(&self.change_signers, BuildSatisfaction::None, &self.secp)?
                         .unwrap(),
                 )
@@ -1320,7 +1275,7 @@ impl<D> Wallet<D> {
         )?;
         let internal_requirements = internal_policy
             .map(|policy| {
-                Ok::<_, CreateTxError<D::WriteError>>(
+                Ok::<_, CreateTxError>(
                     policy.get_condition(
                         params
                             .internal_policy_path
@@ -1616,7 +1571,7 @@ impl<D> Wallet<D> {
     /// # use bdk::*;
     /// # use bdk::wallet::ChangeSet;
     /// # use bdk::wallet::error::CreateTxError;
-    /// # use bdk_chain::PersistBackend;
+    /// # use bdk_persist::PersistBackend;
     /// # use anyhow::Error;
     /// # let descriptor = "wpkh(tpubD6NzVbkrYhZ4Xferm7Pz4VnjdcDPFyjVu5K4iZXQ4pVN8Cks4pHVowTBXBKRhX64pkRyJZJN5xAKj4UDNnLPb5p2sSKXhewoYx5GbTdUFWq/*)";
     /// # let mut wallet = doctest_wallet!();
@@ -1647,7 +1602,7 @@ impl<D> Wallet<D> {
     pub fn build_fee_bump(
         &mut self,
         txid: Txid,
-    ) -> Result<TxBuilder<'_, D, DefaultCoinSelectionAlgorithm, BumpFee>, BuildFeeBumpError> {
+    ) -> Result<TxBuilder<'_, DefaultCoinSelectionAlgorithm, BumpFee>, BuildFeeBumpError> {
         let graph = self.indexed_graph.graph();
         let txout_index = &self.indexed_graph.index;
         let chain_tip = self.chain.tip().block_id();
@@ -1791,7 +1746,7 @@ impl<D> Wallet<D> {
     /// # use bdk::*;
     /// # use bdk::wallet::ChangeSet;
     /// # use bdk::wallet::error::CreateTxError;
-    /// # use bdk_chain::PersistBackend;
+    /// # use bdk_persist::PersistBackend;
     /// # let descriptor = "wpkh(tpubD6NzVbkrYhZ4Xferm7Pz4VnjdcDPFyjVu5K4iZXQ4pVN8Cks4pHVowTBXBKRhX64pkRyJZJN5xAKj4UDNnLPb5p2sSKXhewoYx5GbTdUFWq/*)";
     /// # let mut wallet = doctest_wallet!();
     /// # let to_address = Address::from_str("2N4eQYCbKUHCCTUjBJeHcJp9ok6J2GZsTDt").unwrap().assume_checked();
@@ -2158,10 +2113,7 @@ impl<D> Wallet<D> {
         tx: Transaction,
         selected: Vec<Utxo>,
         params: TxParams,
-    ) -> Result<Psbt, CreateTxError<D::WriteError>>
-    where
-        D: PersistBackend<ChangeSet>,
-    {
+    ) -> Result<Psbt, CreateTxError> {
         let mut psbt = Psbt::from_unsigned_tx(tx)?;
 
         if params.add_global_xpubs {
@@ -2242,10 +2194,7 @@ impl<D> Wallet<D> {
         utxo: LocalOutput,
         sighash_type: Option<psbt::PsbtSighashType>,
         only_witness_utxo: bool,
-    ) -> Result<psbt::Input, CreateTxError<D::WriteError>>
-    where
-        D: PersistBackend<ChangeSet>,
-    {
+    ) -> Result<psbt::Input, CreateTxError> {
         // Try to find the prev_script in our db to figure out if this is internal or external,
         // and the derivation index
         let (keychain, child) = self
@@ -2335,10 +2284,8 @@ impl<D> Wallet<D> {
     /// transactions related to your wallet into it.
     ///
     /// [`commit`]: Self::commit
-    pub fn apply_update(&mut self, update: Update) -> Result<(), CannotConnectError>
-    where
-        D: PersistBackend<ChangeSet>,
-    {
+    pub fn apply_update(&mut self, update: impl Into<Update>) -> Result<(), CannotConnectError> {
+        let update = update.into();
         let mut changeset = match update.chain {
             Some(chain_update) => ChangeSet::from(self.chain.apply_update(chain_update)?),
             None => ChangeSet::default(),
@@ -2354,7 +2301,6 @@ impl<D> Wallet<D> {
         changeset.append(ChangeSet::from(
             self.indexed_graph.apply_update(update.graph),
         ));
-
         self.persist.stage(changeset);
         Ok(())
     }
@@ -2365,20 +2311,14 @@ impl<D> Wallet<D> {
     /// This returns whether the `update` resulted in any changes.
     ///
     /// [`staged`]: Self::staged
-    pub fn commit(&mut self) -> Result<bool, D::WriteError>
-    where
-        D: PersistBackend<ChangeSet>,
-    {
+    pub fn commit(&mut self) -> anyhow::Result<bool> {
         self.persist.commit().map(|c| c.is_some())
     }
 
     /// Returns the changes that will be committed with the next call to [`commit`].
     ///
     /// [`commit`]: Self::commit
-    pub fn staged(&self) -> &ChangeSet
-    where
-        D: PersistBackend<ChangeSet>,
-    {
+    pub fn staged(&self) -> &ChangeSet {
         self.persist.staged()
     }
 
@@ -2404,10 +2344,7 @@ impl<D> Wallet<D> {
     /// with `prev_blockhash` and `height-1` as the `connected_to` parameter.
     ///
     /// [`apply_block_connected_to`]: Self::apply_block_connected_to
-    pub fn apply_block(&mut self, block: &Block, height: u32) -> Result<(), CannotConnectError>
-    where
-        D: PersistBackend<ChangeSet>,
-    {
+    pub fn apply_block(&mut self, block: &Block, height: u32) -> Result<(), CannotConnectError> {
         let connected_to = match height.checked_sub(1) {
             Some(prev_height) => BlockId {
                 height: prev_height,
@@ -2438,10 +2375,7 @@ impl<D> Wallet<D> {
         block: &Block,
         height: u32,
         connected_to: BlockId,
-    ) -> Result<(), ApplyHeaderError>
-    where
-        D: PersistBackend<ChangeSet>,
-    {
+    ) -> Result<(), ApplyHeaderError> {
         let mut changeset = ChangeSet::default();
         changeset.append(
             self.chain
@@ -2468,9 +2402,7 @@ impl<D> Wallet<D> {
     pub fn apply_unconfirmed_txs<'t>(
         &mut self,
         unconfirmed_txs: impl IntoIterator<Item = (&'t Transaction, u64)>,
-    ) where
-        D: PersistBackend<ChangeSet>,
-    {
+    ) {
         let indexed_graph_changeset = self
             .indexed_graph
             .batch_insert_relevant_unconfirmed(unconfirmed_txs);
@@ -2478,7 +2410,32 @@ impl<D> Wallet<D> {
     }
 }
 
-impl<D> AsRef<bdk_chain::tx_graph::TxGraph<ConfirmationTimeHeightAnchor>> for Wallet<D> {
+/// Methods to construct sync/full-scan requests for spk-based chain sources.
+impl Wallet {
+    /// Create a partial [`SyncRequest`] for this wallet for all revealed spks.
+    ///
+    /// This is the first step when performing a spk-based wallet partial sync, the returned
+    /// [`SyncRequest`] collects all revealed script pubkeys from the wallet keychain needed to
+    /// start a blockchain sync with a spk based blockchain client.
+    pub fn start_sync_with_revealed_spks(&self) -> SyncRequest {
+        SyncRequest::from_chain_tip(self.chain.tip())
+            .populate_with_revealed_spks(&self.indexed_graph.index, ..)
+    }
+
+    /// Create a [`FullScanRequest] for this wallet.
+    ///
+    /// This is the first step when performing a spk-based wallet full scan, the returned
+    /// [`FullScanRequest] collects iterators for the wallet's keychain script pub keys needed to
+    /// start a blockchain full scan with a spk based blockchain client.
+    ///
+    /// This operation is generally only used when importing or restoring a previously used wallet
+    /// in which the list of used scripts is not known.
+    pub fn start_full_scan(&self) -> FullScanRequest<KeychainKind> {
+        FullScanRequest::from_keychain_txout_index(self.chain.tip(), &self.indexed_graph.index)
+    }
+}
+
+impl AsRef<bdk_chain::tx_graph::TxGraph<ConfirmationTimeHeightAnchor>> for Wallet {
     fn as_ref(&self) -> &bdk_chain::tx_graph::TxGraph<ConfirmationTimeHeightAnchor> {
         self.indexed_graph.graph()
     }
@@ -2572,7 +2529,7 @@ macro_rules! doctest_wallet {
     () => {{
         use $crate::bitcoin::{BlockHash, Transaction, absolute, TxOut, Network, hashes::Hash};
         use $crate::chain::{ConfirmationTime, BlockId};
-        use $crate::wallet::{AddressIndex, Wallet};
+        use $crate::{KeychainKind, wallet::Wallet};
         let descriptor = "tr([73c5da0a/86'/0'/0']tprv8fMn4hSKPRC1oaCPqxDb1JWtgkpeiQvZhsr8W2xuy3GEMkzoArcAWTfJxYb6Wj8XNNDWEjfYKK4wGQXh3ZUXhDF2NcnsALpWTeSwarJt7Vc/0/*)";
         let change_descriptor = "tr([73c5da0a/86'/0'/0']tprv8fMn4hSKPRC1oaCPqxDb1JWtgkpeiQvZhsr8W2xuy3GEMkzoArcAWTfJxYb6Wj8XNNDWEjfYKK4wGQXh3ZUXhDF2NcnsALpWTeSwarJt7Vc/1/*)";
 
@@ -2582,7 +2539,7 @@ macro_rules! doctest_wallet {
             Network::Regtest,
         )
         .unwrap();
-        let address = wallet.get_address(AddressIndex::New).address;
+        let address = wallet.peek_address(KeychainKind::External, 0).address;
         let tx = Transaction {
             version: transaction::Version::ONE,
             lock_time: absolute::LockTime::ZERO,

crates/bdk/src/wallet/tx_builder.rs

@@ -20,7 +20,7 @@
 //! # use bdk::wallet::ChangeSet;
 //! # use bdk::wallet::error::CreateTxError;
 //! # use bdk::wallet::tx_builder::CreateTx;
-//! # use bdk_chain::PersistBackend;
+//! # use bdk_persist::PersistBackend;
 //! # use anyhow::Error;
 //! # let to_address = Address::from_str("2N4eQYCbKUHCCTUjBJeHcJp9ok6J2GZsTDt").unwrap().assume_checked();
 //! # let mut wallet = doctest_wallet!();
@@ -45,13 +45,12 @@ use core::cell::RefCell;
 use core::fmt;
 use core::marker::PhantomData;
 
-use bdk_chain::PersistBackend;
 use bitcoin::psbt::{self, Psbt};
 use bitcoin::script::PushBytes;
 use bitcoin::{absolute, FeeRate, OutPoint, ScriptBuf, Sequence, Transaction, Txid};
 
 use super::coin_selection::{CoinSelectionAlgorithm, DefaultCoinSelectionAlgorithm};
-use super::{ChangeSet, CreateTxError, Wallet};
+use super::{CreateTxError, Wallet};
 use crate::collections::{BTreeMap, HashSet};
 use crate::{KeychainKind, LocalOutput, Utxo, WeightedUtxo};
 
@@ -85,7 +84,7 @@ impl TxBuilderContext for BumpFee {}
 /// # use core::str::FromStr;
 /// # use bdk::wallet::ChangeSet;
 /// # use bdk::wallet::error::CreateTxError;
-/// # use bdk_chain::PersistBackend;
+/// # use bdk_persist::PersistBackend;
 /// # use anyhow::Error;
 /// # let mut wallet = doctest_wallet!();
 /// # let addr1 = Address::from_str("2N4eQYCbKUHCCTUjBJeHcJp9ok6J2GZsTDt").unwrap().assume_checked();
@@ -124,8 +123,8 @@ impl TxBuilderContext for BumpFee {}
 /// [`finish`]: Self::finish
 /// [`coin_selection`]: Self::coin_selection
 #[derive(Debug)]
-pub struct TxBuilder<'a, D, Cs, Ctx> {
-    pub(crate) wallet: Rc<RefCell<&'a mut Wallet<D>>>,
+pub struct TxBuilder<'a, Cs, Ctx> {
+    pub(crate) wallet: Rc<RefCell<&'a mut Wallet>>,
     pub(crate) params: TxParams,
     pub(crate) coin_selection: Cs,
     pub(crate) phantom: PhantomData<Ctx>,
@@ -176,7 +175,7 @@ impl Default for FeePolicy {
     }
 }
 
-impl<'a, D, Cs: Clone, Ctx> Clone for TxBuilder<'a, D, Cs, Ctx> {
+impl<'a, Cs: Clone, Ctx> Clone for TxBuilder<'a, Cs, Ctx> {
     fn clone(&self) -> Self {
         TxBuilder {
             wallet: self.wallet.clone(),
@@ -188,7 +187,7 @@ impl<'a, D, Cs: Clone, Ctx> Clone for TxBuilder<'a, D, Cs, Ctx> {
 }
 
 // methods supported by both contexts, for any CoinSelectionAlgorithm
-impl<'a, D, Cs, Ctx> TxBuilder<'a, D, Cs, Ctx> {
+impl<'a, Cs, Ctx> TxBuilder<'a, Cs, Ctx> {
     /// Set a custom fee rate.
     ///
     /// This method sets the mining fee paid by the transaction as a rate on its size.
@@ -560,7 +559,7 @@ impl<'a, D, Cs, Ctx> TxBuilder<'a, D, Cs, Ctx> {
     pub fn coin_selection<P: CoinSelectionAlgorithm>(
         self,
         coin_selection: P,
-    ) -> TxBuilder<'a, D, P, Ctx> {
+    ) -> TxBuilder<'a, P, Ctx> {
         TxBuilder {
             wallet: self.wallet,
             params: self.params,
@@ -615,16 +614,13 @@ impl<'a, D, Cs, Ctx> TxBuilder<'a, D, Cs, Ctx> {
     }
 }
 
-impl<'a, D, Cs: CoinSelectionAlgorithm, Ctx> TxBuilder<'a, D, Cs, Ctx> {
+impl<'a, Cs: CoinSelectionAlgorithm, Ctx> TxBuilder<'a, Cs, Ctx> {
     /// Finish building the transaction.
     ///
     /// Returns a new [`Psbt`] per [`BIP174`].
     ///
     /// [`BIP174`]: https://github.com/bitcoin/bips/blob/master/bip-0174.mediawiki
-    pub fn finish(self) -> Result<Psbt, CreateTxError<D::WriteError>>
-    where
-        D: PersistBackend<ChangeSet>,
-    {
+    pub fn finish(self) -> Result<Psbt, CreateTxError> {
         self.wallet
             .borrow_mut()
             .create_tx(self.coin_selection, self.params)
@@ -715,7 +711,7 @@ impl fmt::Display for AllowShrinkingError {
 #[cfg(feature = "std")]
 impl std::error::Error for AllowShrinkingError {}
 
-impl<'a, D, Cs: CoinSelectionAlgorithm> TxBuilder<'a, D, Cs, CreateTx> {
+impl<'a, Cs: CoinSelectionAlgorithm> TxBuilder<'a, Cs, CreateTx> {
     /// Replace the recipients already added with a new list
     pub fn set_recipients(&mut self, recipients: Vec<(ScriptBuf, u64)>) -> &mut Self {
         self.params.recipients = recipients;
@@ -762,7 +758,7 @@ impl<'a, D, Cs: CoinSelectionAlgorithm> TxBuilder<'a, D, Cs, CreateTx> {
     /// # use bdk::wallet::ChangeSet;
     /// # use bdk::wallet::error::CreateTxError;
     /// # use bdk::wallet::tx_builder::CreateTx;
-    /// # use bdk_chain::PersistBackend;
+    /// # use bdk_persist::PersistBackend;
     /// # use anyhow::Error;
     /// # let to_address =
     /// Address::from_str("2N4eQYCbKUHCCTUjBJeHcJp9ok6J2GZsTDt")
@@ -793,7 +789,7 @@ impl<'a, D, Cs: CoinSelectionAlgorithm> TxBuilder<'a, D, Cs, CreateTx> {
 }
 
 // methods supported only by bump_fee
-impl<'a, D> TxBuilder<'a, D, DefaultCoinSelectionAlgorithm, BumpFee> {
+impl<'a> TxBuilder<'a, DefaultCoinSelectionAlgorithm, BumpFee> {
     /// Explicitly tells the wallet that it is allowed to reduce the amount of the output matching this
     /// `script_pubkey` in order to bump the transaction fee. Without specifying this the wallet
     /// will attempt to find a change output to shrink instead.

crates/bdk/tests/common.rs

@@ -1,6 +1,6 @@
 #![allow(unused)]
 
-use bdk::{wallet::AddressIndex, KeychainKind, LocalOutput, Wallet};
+use bdk::{KeychainKind, LocalOutput, Wallet};
 use bdk_chain::indexed_tx_graph::Indexer;
 use bdk_chain::{BlockId, ConfirmationTime};
 use bitcoin::hashes::Hash;
@@ -20,7 +20,7 @@ pub fn get_funded_wallet_with_change(
     change: Option<&str>,
 ) -> (Wallet, bitcoin::Txid) {
     let mut wallet = Wallet::new_no_persist(descriptor, change, Network::Regtest).unwrap();
-    let change_address = wallet.get_address(AddressIndex::New).address;
+    let change_address = wallet.peek_address(KeychainKind::External, 0).address;
     let sendto_address = Address::from_str("bcrt1q3qtze4ys45tgdvguj66zrk4fu6hq3a3v9pfly5")
         .expect("address")
         .require_network(Network::Regtest)

crates/bdk/tests/psbt.rs

@@ -1,7 +1,5 @@
 use bdk::bitcoin::{Amount, FeeRate, Psbt, TxIn};
-use bdk::wallet::AddressIndex;
-use bdk::wallet::AddressIndex::New;
-use bdk::{psbt, SignOptions};
+use bdk::{psbt, KeychainKind, SignOptions};
 use core::str::FromStr;
 mod common;
 use common::*;
@@ -14,7 +12,7 @@ const PSBT_STR: &str = "cHNidP8BAKACAAAAAqsJSaCMWvfEm4IS9Bfi8Vqz9cM9zxU4IagTn4d6
 fn test_psbt_malformed_psbt_input_legacy() {
     let psbt_bip = Psbt::from_str(PSBT_STR).unwrap();
     let (mut wallet, _) = get_funded_wallet(get_test_wpkh());
-    let send_to = wallet.get_address(AddressIndex::New);
+    let send_to = wallet.peek_address(KeychainKind::External, 0);
     let mut builder = wallet.build_tx();
     builder.add_recipient(send_to.script_pubkey(), 10_000);
     let mut psbt = builder.finish().unwrap();
@@ -31,7 +29,7 @@ fn test_psbt_malformed_psbt_input_legacy() {
 fn test_psbt_malformed_psbt_input_segwit() {
     let psbt_bip = Psbt::from_str(PSBT_STR).unwrap();
     let (mut wallet, _) = get_funded_wallet(get_test_wpkh());
-    let send_to = wallet.get_address(AddressIndex::New);
+    let send_to = wallet.peek_address(KeychainKind::External, 0);
     let mut builder = wallet.build_tx();
     builder.add_recipient(send_to.script_pubkey(), 10_000);
     let mut psbt = builder.finish().unwrap();
@@ -47,7 +45,7 @@ fn test_psbt_malformed_psbt_input_segwit() {
 #[should_panic(expected = "InputIndexOutOfRange")]
 fn test_psbt_malformed_tx_input() {
     let (mut wallet, _) = get_funded_wallet(get_test_wpkh());
-    let send_to = wallet.get_address(AddressIndex::New);
+    let send_to = wallet.peek_address(KeychainKind::External, 0);
     let mut builder = wallet.build_tx();
     builder.add_recipient(send_to.script_pubkey(), 10_000);
     let mut psbt = builder.finish().unwrap();
@@ -63,7 +61,7 @@ fn test_psbt_malformed_tx_input() {
 fn test_psbt_sign_with_finalized() {
     let psbt_bip = Psbt::from_str(PSBT_STR).unwrap();
     let (mut wallet, _) = get_funded_wallet(get_test_wpkh());
-    let send_to = wallet.get_address(AddressIndex::New);
+    let send_to = wallet.peek_address(KeychainKind::External, 0);
     let mut builder = wallet.build_tx();
     builder.add_recipient(send_to.script_pubkey(), 10_000);
     let mut psbt = builder.finish().unwrap();
@@ -84,7 +82,7 @@ fn test_psbt_fee_rate_with_witness_utxo() {
     let expected_fee_rate = FeeRate::from_sat_per_kwu(310);
 
     let (mut wallet, _) = get_funded_wallet("wpkh(tprv8ZgxMBicQKsPd3EupYiPRhaMooHKUHJxNsTfYuScep13go8QFfHdtkG9nRkFGb7busX4isf6X9dURGCoKgitaApQ6MupRhZMcELAxTBRJgS/*)");
-    let addr = wallet.get_address(New);
+    let addr = wallet.peek_address(KeychainKind::External, 0);
     let mut builder = wallet.build_tx();
     builder.drain_to(addr.script_pubkey()).drain_wallet();
     builder.fee_rate(expected_fee_rate);
@@ -109,7 +107,7 @@ fn test_psbt_fee_rate_with_nonwitness_utxo() {
     let expected_fee_rate = FeeRate::from_sat_per_kwu(310);
 
     let (mut wallet, _) = get_funded_wallet("pkh(tprv8ZgxMBicQKsPd3EupYiPRhaMooHKUHJxNsTfYuScep13go8QFfHdtkG9nRkFGb7busX4isf6X9dURGCoKgitaApQ6MupRhZMcELAxTBRJgS/*)");
-    let addr = wallet.get_address(New);
+    let addr = wallet.peek_address(KeychainKind::External, 0);
     let mut builder = wallet.build_tx();
     builder.drain_to(addr.script_pubkey()).drain_wallet();
     builder.fee_rate(expected_fee_rate);
@@ -133,7 +131,7 @@ fn test_psbt_fee_rate_with_missing_txout() {
     let expected_fee_rate = FeeRate::from_sat_per_kwu(310);
 
     let (mut wpkh_wallet,  _) = get_funded_wallet("wpkh(tprv8ZgxMBicQKsPd3EupYiPRhaMooHKUHJxNsTfYuScep13go8QFfHdtkG9nRkFGb7busX4isf6X9dURGCoKgitaApQ6MupRhZMcELAxTBRJgS/*)");
-    let addr = wpkh_wallet.get_address(New);
+    let addr = wpkh_wallet.peek_address(KeychainKind::External, 0);
     let mut builder = wpkh_wallet.build_tx();
     builder.drain_to(addr.script_pubkey()).drain_wallet();
     builder.fee_rate(expected_fee_rate);
@@ -145,7 +143,7 @@ fn test_psbt_fee_rate_with_missing_txout() {
     assert!(wpkh_psbt.fee_rate().is_none());
 
     let (mut pkh_wallet,  _) = get_funded_wallet("pkh(tprv8ZgxMBicQKsPd3EupYiPRhaMooHKUHJxNsTfYuScep13go8QFfHdtkG9nRkFGb7busX4isf6X9dURGCoKgitaApQ6MupRhZMcELAxTBRJgS/*)");
-    let addr = pkh_wallet.get_address(New);
+    let addr = pkh_wallet.peek_address(KeychainKind::External, 0);
     let mut builder = pkh_wallet.build_tx();
     builder.drain_to(addr.script_pubkey()).drain_wallet();
     builder.fee_rate(expected_fee_rate);
@@ -174,7 +172,7 @@ fn test_psbt_multiple_internalkey_signers() {
 
     let (mut wallet, _) = get_funded_wallet(&desc);
     let to_spend = wallet.get_balance().total();
-    let send_to = wallet.get_address(AddressIndex::New);
+    let send_to = wallet.peek_address(KeychainKind::External, 0);
     let mut builder = wallet.build_tx();
     builder.drain_to(send_to.script_pubkey()).drain_wallet();
     let mut psbt = builder.finish().unwrap();

crates/bdk/tests/wallet.rs

@@ -7,8 +7,8 @@ use bdk::signer::{SignOptions, SignerError};
 use bdk::wallet::coin_selection::{self, LargestFirstCoinSelection};
 use bdk::wallet::error::CreateTxError;
 use bdk::wallet::tx_builder::AddForeignUtxoError;
-use bdk::wallet::{AddressIndex, AddressInfo, Balance, Wallet};
-use bdk::wallet::{AddressIndex::*, NewError};
+use bdk::wallet::NewError;
+use bdk::wallet::{AddressInfo, Balance, Wallet};
 use bdk::KeychainKind;
 use bdk_chain::COINBASE_MATURITY;
 use bdk_chain::{BlockId, ConfirmationTime};
@@ -26,12 +26,13 @@ mod common;
 use common::*;
 
 fn receive_output(wallet: &mut Wallet, value: u64, height: ConfirmationTime) -> OutPoint {
+    let addr = wallet.next_unused_address(KeychainKind::External).unwrap();
     let tx = Transaction {
         version: transaction::Version::ONE,
         lock_time: absolute::LockTime::ZERO,
         input: vec![],
         output: vec![TxOut {
-            script_pubkey: wallet.get_address(LastUnused).script_pubkey(),
+            script_pubkey: addr.script_pubkey(),
             value: Amount::from_sat(value),
         }],
     };
@@ -76,7 +77,7 @@ fn load_recovers_wallet() {
         let mut wallet = Wallet::new(get_test_tr_single_sig_xprv(), None, db, Network::Testnet)
             .expect("must init wallet");
 
-        wallet.try_get_address(New).unwrap();
+        wallet.reveal_next_address(KeychainKind::External).unwrap();
         wallet.spk_index().clone()
     };
 
@@ -343,7 +344,7 @@ fn test_create_tx_empty_recipients() {
 #[should_panic(expected = "NoUtxosSelected")]
 fn test_create_tx_manually_selected_empty_utxos() {
     let (mut wallet, _) = get_funded_wallet(get_test_wpkh());
-    let addr = wallet.get_address(New);
+    let addr = wallet.next_unused_address(KeychainKind::External).unwrap();
     let mut builder = wallet.build_tx();
     builder
         .add_recipient(addr.script_pubkey(), 25_000)
@@ -354,7 +355,7 @@ fn test_create_tx_manually_selected_empty_utxos() {
 #[test]
 fn test_create_tx_version_0() {
     let (mut wallet, _) = get_funded_wallet(get_test_wpkh());
-    let addr = wallet.get_address(New);
+    let addr = wallet.next_unused_address(KeychainKind::External).unwrap();
     let mut builder = wallet.build_tx();
     builder
         .add_recipient(addr.script_pubkey(), 25_000)
@@ -365,7 +366,7 @@ fn test_create_tx_version_0() {
 #[test]
 fn test_create_tx_version_1_csv() {
     let (mut wallet, _) = get_funded_wallet(get_test_single_sig_csv());
-    let addr = wallet.get_address(New);
+    let addr = wallet.next_unused_address(KeychainKind::External).unwrap();
     let mut builder = wallet.build_tx();
     builder
         .add_recipient(addr.script_pubkey(), 25_000)
@@ -376,7 +377,7 @@ fn test_create_tx_version_1_csv() {
 #[test]
 fn test_create_tx_custom_version() {
     let (mut wallet, _) = get_funded_wallet(get_test_wpkh());
-    let addr = wallet.get_address(New);
+    let addr = wallet.next_unused_address(KeychainKind::External).unwrap();
     let mut builder = wallet.build_tx();
     builder
         .add_recipient(addr.script_pubkey(), 25_000)
@@ -390,7 +391,7 @@ fn test_create_tx_custom_version() {
 fn test_create_tx_default_locktime_is_last_sync_height() {
     let (mut wallet, _) = get_funded_wallet(get_test_wpkh());
 
-    let addr = wallet.get_address(New);
+    let addr = wallet.next_unused_address(KeychainKind::External).unwrap();
     let mut builder = wallet.build_tx();
     builder.add_recipient(addr.script_pubkey(), 25_000);
     let psbt = builder.finish().unwrap();
@@ -403,7 +404,7 @@ fn test_create_tx_default_locktime_is_last_sync_height() {
 #[test]
 fn test_create_tx_fee_sniping_locktime_last_sync() {
     let (mut wallet, _) = get_funded_wallet(get_test_wpkh());
-    let addr = wallet.get_address(New);
+    let addr = wallet.next_unused_address(KeychainKind::External).unwrap();
     let mut builder = wallet.build_tx();
     builder.add_recipient(addr.script_pubkey(), 25_000);
 
@@ -419,7 +420,7 @@ fn test_create_tx_fee_sniping_locktime_last_sync() {
 #[test]
 fn test_create_tx_default_locktime_cltv() {
     let (mut wallet, _) = get_funded_wallet(get_test_single_sig_cltv());
-    let addr = wallet.get_address(New);
+    let addr = wallet.next_unused_address(KeychainKind::External).unwrap();
     let mut builder = wallet.build_tx();
     builder.add_recipient(addr.script_pubkey(), 25_000);
     let psbt = builder.finish().unwrap();
@@ -430,7 +431,7 @@ fn test_create_tx_default_locktime_cltv() {
 #[test]
 fn test_create_tx_custom_locktime() {
     let (mut wallet, _) = get_funded_wallet(get_test_wpkh());
-    let addr = wallet.get_address(New);
+    let addr = wallet.next_unused_address(KeychainKind::External).unwrap();
     let mut builder = wallet.build_tx();
     builder
         .add_recipient(addr.script_pubkey(), 25_000)
@@ -447,7 +448,7 @@ fn test_create_tx_custom_locktime() {
 #[test]
 fn test_create_tx_custom_locktime_compatible_with_cltv() {
     let (mut wallet, _) = get_funded_wallet(get_test_single_sig_cltv());
-    let addr = wallet.get_address(New);
+    let addr = wallet.next_unused_address(KeychainKind::External).unwrap();
     let mut builder = wallet.build_tx();
     builder
         .add_recipient(addr.script_pubkey(), 25_000)
@@ -460,7 +461,7 @@ fn test_create_tx_custom_locktime_compatible_with_cltv() {
 #[test]
 fn test_create_tx_custom_locktime_incompatible_with_cltv() {
     let (mut wallet, _) = get_funded_wallet(get_test_single_sig_cltv());
-    let addr = wallet.get_address(New);
+    let addr = wallet.next_unused_address(KeychainKind::External).unwrap();
     let mut builder = wallet.build_tx();
     builder
         .add_recipient(addr.script_pubkey(), 25_000)
@@ -473,7 +474,7 @@ fn test_create_tx_custom_locktime_incompatible_with_cltv() {
 #[test]
 fn test_create_tx_no_rbf_csv() {
     let (mut wallet, _) = get_funded_wallet(get_test_single_sig_csv());
-    let addr = wallet.get_address(New);
+    let addr = wallet.next_unused_address(KeychainKind::External).unwrap();
     let mut builder = wallet.build_tx();
     builder.add_recipient(addr.script_pubkey(), 25_000);
     let psbt = builder.finish().unwrap();
@@ -484,7 +485,7 @@ fn test_create_tx_no_rbf_csv() {
 #[test]
 fn test_create_tx_with_default_rbf_csv() {
     let (mut wallet, _) = get_funded_wallet(get_test_single_sig_csv());
-    let addr = wallet.get_address(New);
+    let addr = wallet.next_unused_address(KeychainKind::External).unwrap();
     let mut builder = wallet.build_tx();
     builder
         .add_recipient(addr.script_pubkey(), 25_000)
@@ -498,7 +499,7 @@ fn test_create_tx_with_default_rbf_csv() {
 #[test]
 fn test_create_tx_with_custom_rbf_csv() {
     let (mut wallet, _) = get_funded_wallet(get_test_single_sig_csv());
-    let addr = wallet.get_address(New);
+    let addr = wallet.next_unused_address(KeychainKind::External).unwrap();
     let mut builder = wallet.build_tx();
     builder
         .add_recipient(addr.script_pubkey(), 25_000)
@@ -511,7 +512,7 @@ fn test_create_tx_with_custom_rbf_csv() {
 #[test]
 fn test_create_tx_no_rbf_cltv() {
     let (mut wallet, _) = get_funded_wallet(get_test_single_sig_cltv());
-    let addr = wallet.get_address(New);
+    let addr = wallet.next_unused_address(KeychainKind::External).unwrap();
     let mut builder = wallet.build_tx();
     builder.add_recipient(addr.script_pubkey(), 25_000);
     let psbt = builder.finish().unwrap();
@@ -522,7 +523,7 @@ fn test_create_tx_no_rbf_cltv() {
 #[test]
 fn test_create_tx_invalid_rbf_sequence() {
     let (mut wallet, _) = get_funded_wallet(get_test_wpkh());
-    let addr = wallet.get_address(New);
+    let addr = wallet.next_unused_address(KeychainKind::External).unwrap();
     let mut builder = wallet.build_tx();
     builder
         .add_recipient(addr.script_pubkey(), 25_000)
@@ -533,7 +534,7 @@ fn test_create_tx_invalid_rbf_sequence() {
 #[test]
 fn test_create_tx_custom_rbf_sequence() {
     let (mut wallet, _) = get_funded_wallet(get_test_wpkh());
-    let addr = wallet.get_address(New);
+    let addr = wallet.next_unused_address(KeychainKind::External).unwrap();
     let mut builder = wallet.build_tx();
     builder
         .add_recipient(addr.script_pubkey(), 25_000)
@@ -546,7 +547,7 @@ fn test_create_tx_custom_rbf_sequence() {
 #[test]
 fn test_create_tx_default_sequence() {
     let (mut wallet, _) = get_funded_wallet(get_test_wpkh());
-    let addr = wallet.get_address(New);
+    let addr = wallet.next_unused_address(KeychainKind::External).unwrap();
     let mut builder = wallet.build_tx();
     builder.add_recipient(addr.script_pubkey(), 25_000);
     let psbt = builder.finish().unwrap();
@@ -557,7 +558,7 @@ fn test_create_tx_default_sequence() {
 #[test]
 fn test_create_tx_change_policy_no_internal() {
     let (mut wallet, _) = get_funded_wallet(get_test_wpkh());
-    let addr = wallet.get_address(New);
+    let addr = wallet.next_unused_address(KeychainKind::External).unwrap();
     let mut builder = wallet.build_tx();
     builder
         .add_recipient(addr.script_pubkey(), 25_000)
@@ -580,7 +581,7 @@ macro_rules! check_fee {
 #[test]
 fn test_create_tx_drain_wallet_and_drain_to() {
     let (mut wallet, _) = get_funded_wallet(get_test_wpkh());
-    let addr = wallet.get_address(New);
+    let addr = wallet.next_unused_address(KeychainKind::External).unwrap();
     let mut builder = wallet.build_tx();
     builder.drain_to(addr.script_pubkey()).drain_wallet();
     let psbt = builder.finish().unwrap();
@@ -599,7 +600,7 @@ fn test_create_tx_drain_wallet_and_drain_to_and_with_recipient() {
     let addr = Address::from_str("2N4eQYCbKUHCCTUjBJeHcJp9ok6J2GZsTDt")
         .unwrap()
         .assume_checked();
-    let drain_addr = wallet.get_address(New);
+    let drain_addr = wallet.next_unused_address(KeychainKind::External).unwrap();
     let mut builder = wallet.build_tx();
     builder
         .add_recipient(addr.script_pubkey(), 20_000)
@@ -625,7 +626,7 @@ fn test_create_tx_drain_wallet_and_drain_to_and_with_recipient() {
 #[test]
 fn test_create_tx_drain_to_and_utxos() {
     let (mut wallet, _) = get_funded_wallet(get_test_wpkh());
-    let addr = wallet.get_address(New);
+    let addr = wallet.next_unused_address(KeychainKind::External).unwrap();
     let utxos: Vec<_> = wallet.list_unspent().map(|u| u.outpoint).collect();
     let mut builder = wallet.build_tx();
     builder
@@ -646,7 +647,7 @@ fn test_create_tx_drain_to_and_utxos() {
 #[should_panic(expected = "NoRecipients")]
 fn test_create_tx_drain_to_no_drain_wallet_no_utxos() {
     let (mut wallet, _) = get_funded_wallet(get_test_wpkh());
-    let drain_addr = wallet.get_address(New);
+    let drain_addr = wallet.next_unused_address(KeychainKind::External).unwrap();
     let mut builder = wallet.build_tx();
     builder.drain_to(drain_addr.script_pubkey());
     builder.finish().unwrap();
@@ -655,7 +656,7 @@ fn test_create_tx_drain_to_no_drain_wallet_no_utxos() {
 #[test]
 fn test_create_tx_default_fee_rate() {
     let (mut wallet, _) = get_funded_wallet(get_test_wpkh());
-    let addr = wallet.get_address(New);
+    let addr = wallet.next_unused_address(KeychainKind::External).unwrap();
     let mut builder = wallet.build_tx();
     builder.add_recipient(addr.script_pubkey(), 25_000);
     let psbt = builder.finish().unwrap();
@@ -667,7 +668,7 @@ fn test_create_tx_default_fee_rate() {
 #[test]
 fn test_create_tx_custom_fee_rate() {
     let (mut wallet, _) = get_funded_wallet(get_test_wpkh());
-    let addr = wallet.get_address(New);
+    let addr = wallet.next_unused_address(KeychainKind::External).unwrap();
     let mut builder = wallet.build_tx();
     builder
         .add_recipient(addr.script_pubkey(), 25_000)
@@ -681,7 +682,7 @@ fn test_create_tx_custom_fee_rate() {
 #[test]
 fn test_create_tx_absolute_fee() {
     let (mut wallet, _) = get_funded_wallet(get_test_wpkh());
-    let addr = wallet.get_address(New);
+    let addr = wallet.next_unused_address(KeychainKind::External).unwrap();
     let mut builder = wallet.build_tx();
     builder
         .drain_to(addr.script_pubkey())
@@ -701,7 +702,7 @@ fn test_create_tx_absolute_fee() {
 #[test]
 fn test_create_tx_absolute_zero_fee() {
     let (mut wallet, _) = get_funded_wallet(get_test_wpkh());
-    let addr = wallet.get_address(New);
+    let addr = wallet.next_unused_address(KeychainKind::External).unwrap();
     let mut builder = wallet.build_tx();
     builder
         .drain_to(addr.script_pubkey())
@@ -722,7 +723,7 @@ fn test_create_tx_absolute_zero_fee() {
 #[should_panic(expected = "InsufficientFunds")]
 fn test_create_tx_absolute_high_fee() {
     let (mut wallet, _) = get_funded_wallet(get_test_wpkh());
-    let addr = wallet.get_address(New);
+    let addr = wallet.next_unused_address(KeychainKind::External).unwrap();
     let mut builder = wallet.build_tx();
     builder
         .drain_to(addr.script_pubkey())
@@ -736,7 +737,7 @@ fn test_create_tx_add_change() {
     use bdk::wallet::tx_builder::TxOrdering;
 
     let (mut wallet, _) = get_funded_wallet(get_test_wpkh());
-    let addr = wallet.get_address(New);
+    let addr = wallet.next_unused_address(KeychainKind::External).unwrap();
     let mut builder = wallet.build_tx();
     builder
         .add_recipient(addr.script_pubkey(), 25_000)
@@ -755,7 +756,7 @@ fn test_create_tx_add_change() {
 #[test]
 fn test_create_tx_skip_change_dust() {
     let (mut wallet, _) = get_funded_wallet(get_test_wpkh());
-    let addr = wallet.get_address(New);
+    let addr = wallet.next_unused_address(KeychainKind::External).unwrap();
     let mut builder = wallet.build_tx();
     builder.add_recipient(addr.script_pubkey(), 49_800);
     let psbt = builder.finish().unwrap();
@@ -770,7 +771,7 @@ fn test_create_tx_skip_change_dust() {
 #[should_panic(expected = "InsufficientFunds")]
 fn test_create_tx_drain_to_dust_amount() {
     let (mut wallet, _) = get_funded_wallet(get_test_wpkh());
-    let addr = wallet.get_address(New);
+    let addr = wallet.next_unused_address(KeychainKind::External).unwrap();
     // very high fee rate, so that the only output would be below dust
     let mut builder = wallet.build_tx();
     builder
@@ -783,7 +784,7 @@ fn test_create_tx_drain_to_dust_amount() {
 #[test]
 fn test_create_tx_ordering_respected() {
     let (mut wallet, _) = get_funded_wallet(get_test_wpkh());
-    let addr = wallet.get_address(New);
+    let addr = wallet.next_unused_address(KeychainKind::External).unwrap();
     let mut builder = wallet.build_tx();
     builder
         .add_recipient(addr.script_pubkey(), 30_000)
@@ -804,7 +805,7 @@ fn test_create_tx_ordering_respected() {
 #[test]
 fn test_create_tx_default_sighash() {
     let (mut wallet, _) = get_funded_wallet(get_test_wpkh());
-    let addr = wallet.get_address(New);
+    let addr = wallet.next_unused_address(KeychainKind::External).unwrap();
     let mut builder = wallet.build_tx();
     builder.add_recipient(addr.script_pubkey(), 30_000);
     let psbt = builder.finish().unwrap();
@@ -815,7 +816,7 @@ fn test_create_tx_default_sighash() {
 #[test]
 fn test_create_tx_custom_sighash() {
     let (mut wallet, _) = get_funded_wallet(get_test_wpkh());
-    let addr = wallet.get_address(New);
+    let addr = wallet.next_unused_address(KeychainKind::External).unwrap();
     let mut builder = wallet.build_tx();
     builder
         .add_recipient(addr.script_pubkey(), 30_000)
@@ -834,7 +835,7 @@ fn test_create_tx_input_hd_keypaths() {
     use core::str::FromStr;
 
     let (mut wallet, _) = get_funded_wallet("wpkh([d34db33f/44'/0'/0']tpubDEnoLuPdBep9bzw5LoGYpsxUQYheRQ9gcgrJhJEcdKFB9cWQRyYmkCyRoTqeD4tJYiVVgt6A3rN6rWn9RYhR9sBsGxji29LYWHuKKbdb1ev/0/*)");
-    let addr = wallet.get_address(New);
+    let addr = wallet.next_unused_address(KeychainKind::External).unwrap();
     let mut builder = wallet.build_tx();
     builder.drain_to(addr.script_pubkey()).drain_wallet();
     let psbt = builder.finish().unwrap();
@@ -856,7 +857,7 @@ fn test_create_tx_output_hd_keypaths() {
 
     let (mut wallet, _) = get_funded_wallet("wpkh([d34db33f/44'/0'/0']tpubDEnoLuPdBep9bzw5LoGYpsxUQYheRQ9gcgrJhJEcdKFB9cWQRyYmkCyRoTqeD4tJYiVVgt6A3rN6rWn9RYhR9sBsGxji29LYWHuKKbdb1ev/0/*)");
 
-    let addr = wallet.get_address(New);
+    let addr = wallet.next_unused_address(KeychainKind::External).unwrap();
     let mut builder = wallet.build_tx();
     builder.drain_to(addr.script_pubkey()).drain_wallet();
     let psbt = builder.finish().unwrap();
@@ -878,7 +879,7 @@ fn test_create_tx_set_redeem_script_p2sh() {
 
     let (mut wallet, _) =
         get_funded_wallet("sh(pk(cVpPVruEDdmutPzisEsYvtST1usBR3ntr8pXSyt6D2YYqXRyPcFW))");
-    let addr = wallet.get_address(New);
+    let addr = wallet.next_unused_address(KeychainKind::External).unwrap();
     let mut builder = wallet.build_tx();
     builder.drain_to(addr.script_pubkey()).drain_wallet();
     let psbt = builder.finish().unwrap();
@@ -901,7 +902,7 @@ fn test_create_tx_set_witness_script_p2wsh() {
 
     let (mut wallet, _) =
         get_funded_wallet("wsh(pk(cVpPVruEDdmutPzisEsYvtST1usBR3ntr8pXSyt6D2YYqXRyPcFW))");
-    let addr = wallet.get_address(New);
+    let addr = wallet.next_unused_address(KeychainKind::External).unwrap();
     let mut builder = wallet.build_tx();
     builder.drain_to(addr.script_pubkey()).drain_wallet();
     let psbt = builder.finish().unwrap();
@@ -922,7 +923,7 @@ fn test_create_tx_set_witness_script_p2wsh() {
 fn test_create_tx_set_redeem_witness_script_p2wsh_p2sh() {
     let (mut wallet, _) =
         get_funded_wallet("sh(wsh(pk(cVpPVruEDdmutPzisEsYvtST1usBR3ntr8pXSyt6D2YYqXRyPcFW)))");
-    let addr = wallet.get_address(New);
+    let addr = wallet.next_unused_address(KeychainKind::External).unwrap();
     let mut builder = wallet.build_tx();
     builder.drain_to(addr.script_pubkey()).drain_wallet();
     let psbt = builder.finish().unwrap();
@@ -940,7 +941,7 @@ fn test_create_tx_set_redeem_witness_script_p2wsh_p2sh() {
 fn test_create_tx_non_witness_utxo() {
     let (mut wallet, _) =
         get_funded_wallet("sh(pk(cVpPVruEDdmutPzisEsYvtST1usBR3ntr8pXSyt6D2YYqXRyPcFW))");
-    let addr = wallet.get_address(New);
+    let addr = wallet.next_unused_address(KeychainKind::External).unwrap();
     let mut builder = wallet.build_tx();
     builder.drain_to(addr.script_pubkey()).drain_wallet();
     let psbt = builder.finish().unwrap();
@@ -953,7 +954,7 @@ fn test_create_tx_non_witness_utxo() {
 fn test_create_tx_only_witness_utxo() {
     let (mut wallet, _) =
         get_funded_wallet("wsh(pk(cVpPVruEDdmutPzisEsYvtST1usBR3ntr8pXSyt6D2YYqXRyPcFW))");
-    let addr = wallet.get_address(New);
+    let addr = wallet.next_unused_address(KeychainKind::External).unwrap();
     let mut builder = wallet.build_tx();
     builder
         .drain_to(addr.script_pubkey())
@@ -969,7 +970,7 @@ fn test_create_tx_only_witness_utxo() {
 fn test_create_tx_shwpkh_has_witness_utxo() {
     let (mut wallet, _) =
         get_funded_wallet("sh(wpkh(cVpPVruEDdmutPzisEsYvtST1usBR3ntr8pXSyt6D2YYqXRyPcFW))");
-    let addr = wallet.get_address(New);
+    let addr = wallet.next_unused_address(KeychainKind::External).unwrap();
     let mut builder = wallet.build_tx();
     builder.drain_to(addr.script_pubkey()).drain_wallet();
     let psbt = builder.finish().unwrap();
@@ -981,7 +982,7 @@ fn test_create_tx_shwpkh_has_witness_utxo() {
 fn test_create_tx_both_non_witness_utxo_and_witness_utxo_default() {
     let (mut wallet, _) =
         get_funded_wallet("wsh(pk(cVpPVruEDdmutPzisEsYvtST1usBR3ntr8pXSyt6D2YYqXRyPcFW))");
-    let addr = wallet.get_address(New);
+    let addr = wallet.next_unused_address(KeychainKind::External).unwrap();
     let mut builder = wallet.build_tx();
     builder.drain_to(addr.script_pubkey()).drain_wallet();
     let psbt = builder.finish().unwrap();
@@ -996,8 +997,11 @@ fn test_create_tx_add_utxo() {
     let small_output_tx = Transaction {
         input: vec![],
         output: vec![TxOut {
+            script_pubkey: wallet
+                .next_unused_address(KeychainKind::External)
+                .unwrap()
+                .script_pubkey(),
             value: Amount::from_sat(25_000),
-            script_pubkey: wallet.get_address(New).address.script_pubkey(),
         }],
         version: transaction::Version::non_standard(0),
         lock_time: absolute::LockTime::ZERO,
@@ -1042,8 +1046,11 @@ fn test_create_tx_manually_selected_insufficient() {
     let small_output_tx = Transaction {
         input: vec![],
         output: vec![TxOut {
+            script_pubkey: wallet
+                .next_unused_address(KeychainKind::External)
+                .unwrap()
+                .script_pubkey(),
             value: Amount::from_sat(25_000),
-            script_pubkey: wallet.get_address(New).address.script_pubkey(),
         }],
         version: transaction::Version::non_standard(0),
         lock_time: absolute::LockTime::ZERO,
@@ -1094,8 +1101,11 @@ fn test_create_tx_policy_path_no_csv() {
         lock_time: absolute::LockTime::ZERO,
         input: vec![],
         output: vec![TxOut {
+            script_pubkey: wallet
+                .next_unused_address(KeychainKind::External)
+                .unwrap()
+                .script_pubkey(),
             value: Amount::from_sat(50_000),
-            script_pubkey: wallet.get_address(New).script_pubkey(),
         }],
     };
     wallet
@@ -1167,7 +1177,7 @@ fn test_create_tx_global_xpubs_with_origin() {
     use bitcoin::hex::FromHex;
 
     let (mut wallet, _) = get_funded_wallet("wpkh([73756c7f/48'/0'/0'/2']tpubDCKxNyM3bLgbEX13Mcd8mYxbVg9ajDkWXMh29hMWBurKfVmBfWAM96QVP3zaUcN51HvkZ3ar4VwP82kC8JZhhux8vFQoJintSpVBwpFvyU3/0/*)");
-    let addr = wallet.get_address(New);
+    let addr = wallet.next_unused_address(KeychainKind::External).unwrap();
     let mut builder = wallet.build_tx();
     builder
         .add_recipient(addr.script_pubkey(), 25_000)
@@ -1430,7 +1440,7 @@ fn test_get_psbt_input() {
 )]
 fn test_create_tx_global_xpubs_origin_missing() {
     let (mut wallet, _) = get_funded_wallet("wpkh(tpubDCKxNyM3bLgbEX13Mcd8mYxbVg9ajDkWXMh29hMWBurKfVmBfWAM96QVP3zaUcN51HvkZ3ar4VwP82kC8JZhhux8vFQoJintSpVBwpFvyU3/0/*)");
-    let addr = wallet.get_address(New);
+    let addr = wallet.next_unused_address(KeychainKind::External).unwrap();
     let mut builder = wallet.build_tx();
     builder
         .add_recipient(addr.script_pubkey(), 25_000)
@@ -1444,7 +1454,7 @@ fn test_create_tx_global_xpubs_master_without_origin() {
     use bitcoin::hex::FromHex;
 
     let (mut wallet, _) = get_funded_wallet("wpkh(tpubD6NzVbkrYhZ4Y55A58Gv9RSNF5hy84b5AJqYy7sCcjFrkcLpPre8kmgfit6kY1Zs3BLgeypTDBZJM222guPpdz7Cup5yzaMu62u7mYGbwFL/0/*)");
-    let addr = wallet.get_address(New);
+    let addr = wallet.next_unused_address(KeychainKind::External).unwrap();
     let mut builder = wallet.build_tx();
     builder
         .add_recipient(addr.script_pubkey(), 25_000)
@@ -1465,7 +1475,7 @@ fn test_create_tx_global_xpubs_master_without_origin() {
 #[should_panic(expected = "IrreplaceableTransaction")]
 fn test_bump_fee_irreplaceable_tx() {
     let (mut wallet, _) = get_funded_wallet(get_test_wpkh());
-    let addr = wallet.get_address(New);
+    let addr = wallet.next_unused_address(KeychainKind::External).unwrap();
     let mut builder = wallet.build_tx();
     builder.add_recipient(addr.script_pubkey(), 25_000);
     let psbt = builder.finish().unwrap();
@@ -1482,7 +1492,7 @@ fn test_bump_fee_irreplaceable_tx() {
 #[should_panic(expected = "TransactionConfirmed")]
 fn test_bump_fee_confirmed_tx() {
     let (mut wallet, _) = get_funded_wallet(get_test_wpkh());
-    let addr = wallet.get_address(New);
+    let addr = wallet.next_unused_address(KeychainKind::External).unwrap();
     let mut builder = wallet.build_tx();
     builder.add_recipient(addr.script_pubkey(), 25_000);
     let psbt = builder.finish().unwrap();
@@ -1506,7 +1516,7 @@ fn test_bump_fee_confirmed_tx() {
 #[test]
 fn test_bump_fee_low_fee_rate() {
     let (mut wallet, _) = get_funded_wallet(get_test_wpkh());
-    let addr = wallet.get_address(New);
+    let addr = wallet.next_unused_address(KeychainKind::External).unwrap();
     let mut builder = wallet.build_tx();
     builder
         .add_recipient(addr.script_pubkey(), 25_000)
@@ -1540,7 +1550,7 @@ fn test_bump_fee_low_fee_rate() {
 #[should_panic(expected = "FeeTooLow")]
 fn test_bump_fee_low_abs() {
     let (mut wallet, _) = get_funded_wallet(get_test_wpkh());
-    let addr = wallet.get_address(New);
+    let addr = wallet.next_unused_address(KeychainKind::External).unwrap();
     let mut builder = wallet.build_tx();
     builder
         .add_recipient(addr.script_pubkey(), 25_000)
@@ -1563,7 +1573,7 @@ fn test_bump_fee_low_abs() {
 #[should_panic(expected = "FeeTooLow")]
 fn test_bump_fee_zero_abs() {
     let (mut wallet, _) = get_funded_wallet(get_test_wpkh());
-    let addr = wallet.get_address(New);
+    let addr = wallet.next_unused_address(KeychainKind::External).unwrap();
     let mut builder = wallet.build_tx();
     builder
         .add_recipient(addr.script_pubkey(), 25_000)
@@ -1777,8 +1787,11 @@ fn test_bump_fee_drain_wallet() {
         lock_time: absolute::LockTime::ZERO,
         input: vec![],
         output: vec![TxOut {
+            script_pubkey: wallet
+                .next_unused_address(KeychainKind::External)
+                .unwrap()
+                .script_pubkey(),
             value: Amount::from_sat(25_000),
-            script_pubkey: wallet.get_address(New).script_pubkey(),
         }],
     };
     wallet
@@ -1842,7 +1855,10 @@ fn test_bump_fee_remove_output_manually_selected_only() {
         lock_time: absolute::LockTime::ZERO,
         input: vec![],
         output: vec![TxOut {
-            script_pubkey: wallet.get_address(New).script_pubkey(),
+            script_pubkey: wallet
+                .next_unused_address(KeychainKind::External)
+                .unwrap()
+                .script_pubkey(),
             value: Amount::from_sat(25_000),
         }],
     };
@@ -1896,7 +1912,10 @@ fn test_bump_fee_add_input() {
         lock_time: absolute::LockTime::ZERO,
         input: vec![],
         output: vec![TxOut {
-            script_pubkey: wallet.get_address(New).script_pubkey(),
+            script_pubkey: wallet
+                .next_unused_address(KeychainKind::External)
+                .unwrap()
+                .script_pubkey(),
             value: Amount::from_sat(25_000),
         }],
     };
@@ -2378,7 +2397,7 @@ fn test_fee_amount_negative_drain_val() {
 #[test]
 fn test_sign_single_xprv() {
     let (mut wallet, _) = get_funded_wallet("wpkh(tprv8ZgxMBicQKsPd3EupYiPRhaMooHKUHJxNsTfYuScep13go8QFfHdtkG9nRkFGb7busX4isf6X9dURGCoKgitaApQ6MupRhZMcELAxTBRJgS/*)");
-    let addr = wallet.get_address(New);
+    let addr = wallet.next_unused_address(KeychainKind::External).unwrap();
     let mut builder = wallet.build_tx();
     builder.drain_to(addr.script_pubkey()).drain_wallet();
     let mut psbt = builder.finish().unwrap();
@@ -2393,7 +2412,7 @@ fn test_sign_single_xprv() {
 #[test]
 fn test_sign_single_xprv_with_master_fingerprint_and_path() {
     let (mut wallet, _) = get_funded_wallet("wpkh([d34db33f/84h/1h/0h]tprv8ZgxMBicQKsPd3EupYiPRhaMooHKUHJxNsTfYuScep13go8QFfHdtkG9nRkFGb7busX4isf6X9dURGCoKgitaApQ6MupRhZMcELAxTBRJgS/*)");
-    let addr = wallet.get_address(New);
+    let addr = wallet.next_unused_address(KeychainKind::External).unwrap();
     let mut builder = wallet.build_tx();
     builder.drain_to(addr.script_pubkey()).drain_wallet();
     let mut psbt = builder.finish().unwrap();
@@ -2408,7 +2427,7 @@ fn test_sign_single_xprv_with_master_fingerprint_and_path() {
 #[test]
 fn test_sign_single_xprv_bip44_path() {
     let (mut wallet, _) = get_funded_wallet("wpkh(tprv8ZgxMBicQKsPd3EupYiPRhaMooHKUHJxNsTfYuScep13go8QFfHdtkG9nRkFGb7busX4isf6X9dURGCoKgitaApQ6MupRhZMcELAxTBRJgS/44'/0'/0'/0/*)");
-    let addr = wallet.get_address(New);
+    let addr = wallet.next_unused_address(KeychainKind::External).unwrap();
     let mut builder = wallet.build_tx();
     builder.drain_to(addr.script_pubkey()).drain_wallet();
     let mut psbt = builder.finish().unwrap();
@@ -2423,7 +2442,7 @@ fn test_sign_single_xprv_bip44_path() {
 #[test]
 fn test_sign_single_xprv_sh_wpkh() {
     let (mut wallet, _) = get_funded_wallet("sh(wpkh(tprv8ZgxMBicQKsPd3EupYiPRhaMooHKUHJxNsTfYuScep13go8QFfHdtkG9nRkFGb7busX4isf6X9dURGCoKgitaApQ6MupRhZMcELAxTBRJgS/*))");
-    let addr = wallet.get_address(New);
+    let addr = wallet.next_unused_address(KeychainKind::External).unwrap();
     let mut builder = wallet.build_tx();
     builder.drain_to(addr.script_pubkey()).drain_wallet();
     let mut psbt = builder.finish().unwrap();
@@ -2439,7 +2458,7 @@ fn test_sign_single_xprv_sh_wpkh() {
 fn test_sign_single_wif() {
     let (mut wallet, _) =
         get_funded_wallet("wpkh(cVpPVruEDdmutPzisEsYvtST1usBR3ntr8pXSyt6D2YYqXRyPcFW)");
-    let addr = wallet.get_address(New);
+    let addr = wallet.next_unused_address(KeychainKind::External).unwrap();
     let mut builder = wallet.build_tx();
     builder.drain_to(addr.script_pubkey()).drain_wallet();
     let mut psbt = builder.finish().unwrap();
@@ -2454,7 +2473,7 @@ fn test_sign_single_wif() {
 #[test]
 fn test_sign_single_xprv_no_hd_keypaths() {
     let (mut wallet, _) = get_funded_wallet("wpkh(tprv8ZgxMBicQKsPd3EupYiPRhaMooHKUHJxNsTfYuScep13go8QFfHdtkG9nRkFGb7busX4isf6X9dURGCoKgitaApQ6MupRhZMcELAxTBRJgS/*)");
-    let addr = wallet.get_address(New);
+    let addr = wallet.next_unused_address(KeychainKind::External).unwrap();
     let mut builder = wallet.build_tx();
     builder.drain_to(addr.script_pubkey()).drain_wallet();
     let mut psbt = builder.finish().unwrap();
@@ -2539,7 +2558,7 @@ fn test_remove_partial_sigs_after_finalize_sign_option() {
     let (mut wallet, _) = get_funded_wallet("wpkh(tprv8ZgxMBicQKsPd3EupYiPRhaMooHKUHJxNsTfYuScep13go8QFfHdtkG9nRkFGb7busX4isf6X9dURGCoKgitaApQ6MupRhZMcELAxTBRJgS/*)");
 
     for remove_partial_sigs in &[true, false] {
-        let addr = wallet.get_address(New);
+        let addr = wallet.next_unused_address(KeychainKind::External).unwrap();
         let mut builder = wallet.build_tx();
         builder.drain_to(addr.script_pubkey()).drain_wallet();
         let mut psbt = builder.finish().unwrap();
@@ -2569,7 +2588,7 @@ fn test_try_finalize_sign_option() {
     let (mut wallet, _) = get_funded_wallet("wpkh(tprv8ZgxMBicQKsPd3EupYiPRhaMooHKUHJxNsTfYuScep13go8QFfHdtkG9nRkFGb7busX4isf6X9dURGCoKgitaApQ6MupRhZMcELAxTBRJgS/*)");
 
     for try_finalize in &[true, false] {
-        let addr = wallet.get_address(New);
+        let addr = wallet.next_unused_address(KeychainKind::External).unwrap();
         let mut builder = wallet.build_tx();
         builder.drain_to(addr.script_pubkey()).drain_wallet();
         let mut psbt = builder.finish().unwrap();
@@ -2603,7 +2622,7 @@ fn test_sign_nonstandard_sighash() {
     let sighash = EcdsaSighashType::NonePlusAnyoneCanPay;
 
     let (mut wallet, _) = get_funded_wallet("wpkh(tprv8ZgxMBicQKsPd3EupYiPRhaMooHKUHJxNsTfYuScep13go8QFfHdtkG9nRkFGb7busX4isf6X9dURGCoKgitaApQ6MupRhZMcELAxTBRJgS/*)");
-    let addr = wallet.get_address(New);
+    let addr = wallet.next_unused_address(KeychainKind::External).unwrap();
     let mut builder = wallet.build_tx();
     builder
         .drain_to(addr.script_pubkey())
@@ -2649,12 +2668,25 @@ fn test_unused_address() {
     let mut wallet = Wallet::new_no_persist("wpkh(tpubEBr4i6yk5nf5DAaJpsi9N2pPYBeJ7fZ5Z9rmN4977iYLCGco1VyjB9tvvuvYtfZzjD5A8igzgw3HeWeeKFmanHYqksqZXYXGsw5zjnj7KM9/*)",
                                  None, Network::Testnet).unwrap();
 
+    // `list_unused_addresses` should be empty if we haven't revealed any
+    assert!(wallet
+        .list_unused_addresses(KeychainKind::External)
+        .next()
+        .is_none());
+
     assert_eq!(
-        wallet.get_address(LastUnused).to_string(),
+        wallet
+            .next_unused_address(KeychainKind::External)
+            .unwrap()
+            .to_string(),
         "tb1q6yn66vajcctph75pvylgkksgpp6nq04ppwct9a"
     );
     assert_eq!(
-        wallet.get_address(LastUnused).to_string(),
+        wallet
+            .list_unused_addresses(KeychainKind::External)
+            .next()
+            .unwrap()
+            .to_string(),
         "tb1q6yn66vajcctph75pvylgkksgpp6nq04ppwct9a"
     );
 }
@@ -2666,24 +2698,46 @@ fn test_next_unused_address() {
     assert_eq!(wallet.derivation_index(KeychainKind::External), None);
 
     assert_eq!(
-        wallet.get_address(LastUnused).to_string(),
+        wallet
+            .next_unused_address(KeychainKind::External)
+            .unwrap()
+            .to_string(),
         "tb1q6yn66vajcctph75pvylgkksgpp6nq04ppwct9a"
     );
     assert_eq!(wallet.derivation_index(KeychainKind::External), Some(0));
+    // calling next_unused again gives same address
     assert_eq!(
-        wallet.get_address(LastUnused).to_string(),
+        wallet
+            .next_unused_address(KeychainKind::External)
+            .unwrap()
+            .to_string(),
         "tb1q6yn66vajcctph75pvylgkksgpp6nq04ppwct9a"
     );
     assert_eq!(wallet.derivation_index(KeychainKind::External), Some(0));
 
+    // test mark used / unused
+    assert!(wallet.mark_used(KeychainKind::External, 0));
+    let next_unused_addr = wallet.next_unused_address(KeychainKind::External).unwrap();
+    assert_eq!(next_unused_addr.index, 1);
+
+    assert!(wallet.unmark_used(KeychainKind::External, 0));
+    let next_unused_addr = wallet.next_unused_address(KeychainKind::External).unwrap();
+    assert_eq!(next_unused_addr.index, 0);
+
     // use the above address
     receive_output_in_latest_block(&mut wallet, 25_000);
 
     assert_eq!(
-        wallet.get_address(LastUnused).to_string(),
+        wallet
+            .next_unused_address(KeychainKind::External)
+            .unwrap()
+            .to_string(),
         "tb1q4er7kxx6sssz3q7qp7zsqsdx4erceahhax77d7"
     );
     assert_eq!(wallet.derivation_index(KeychainKind::External), Some(1));
+
+    // trying to mark index 0 unused should return false
+    assert!(!wallet.unmark_used(KeychainKind::External, 0));
 }
 
 #[test]
@@ -2692,49 +2746,55 @@ fn test_peek_address_at_index() {
                                  None, Network::Testnet).unwrap();
 
     assert_eq!(
-        wallet.get_address(Peek(1)).to_string(),
+        wallet.peek_address(KeychainKind::External, 1).to_string(),
         "tb1q4er7kxx6sssz3q7qp7zsqsdx4erceahhax77d7"
     );
 
     assert_eq!(
-        wallet.get_address(Peek(0)).to_string(),
+        wallet.peek_address(KeychainKind::External, 0).to_string(),
         "tb1q6yn66vajcctph75pvylgkksgpp6nq04ppwct9a"
     );
 
     assert_eq!(
-        wallet.get_address(Peek(2)).to_string(),
+        wallet.peek_address(KeychainKind::External, 2).to_string(),
         "tb1qzntf2mqex4ehwkjlfdyy3ewdlk08qkvkvrz7x2"
     );
 
     // current new address is not affected
     assert_eq!(
-        wallet.get_address(New).to_string(),
+        wallet
+            .reveal_next_address(KeychainKind::External)
+            .unwrap()
+            .to_string(),
         "tb1q6yn66vajcctph75pvylgkksgpp6nq04ppwct9a"
     );
 
     assert_eq!(
-        wallet.get_address(New).to_string(),
+        wallet
+            .reveal_next_address(KeychainKind::External)
+            .unwrap()
+            .to_string(),
         "tb1q4er7kxx6sssz3q7qp7zsqsdx4erceahhax77d7"
     );
 }
 
 #[test]
 fn test_peek_address_at_index_not_derivable() {
-    let mut wallet = Wallet::new_no_persist("wpkh(tpubEBr4i6yk5nf5DAaJpsi9N2pPYBeJ7fZ5Z9rmN4977iYLCGco1VyjB9tvvuvYtfZzjD5A8igzgw3HeWeeKFmanHYqksqZXYXGsw5zjnj7KM9/1)",
+    let wallet = Wallet::new_no_persist("wpkh(tpubEBr4i6yk5nf5DAaJpsi9N2pPYBeJ7fZ5Z9rmN4977iYLCGco1VyjB9tvvuvYtfZzjD5A8igzgw3HeWeeKFmanHYqksqZXYXGsw5zjnj7KM9/1)",
                                  None, Network::Testnet).unwrap();
 
     assert_eq!(
-        wallet.get_address(Peek(1)).to_string(),
+        wallet.peek_address(KeychainKind::External, 1).to_string(),
         "tb1q4er7kxx6sssz3q7qp7zsqsdx4erceahhax77d7"
     );
 
     assert_eq!(
-        wallet.get_address(Peek(0)).to_string(),
+        wallet.peek_address(KeychainKind::External, 0).to_string(),
         "tb1q4er7kxx6sssz3q7qp7zsqsdx4erceahhax77d7"
     );
 
     assert_eq!(
-        wallet.get_address(Peek(2)).to_string(),
+        wallet.peek_address(KeychainKind::External, 2).to_string(),
         "tb1q4er7kxx6sssz3q7qp7zsqsdx4erceahhax77d7"
     );
 }
@@ -2746,7 +2806,7 @@ fn test_returns_index_and_address() {
 
     // new index 0
     assert_eq!(
-        wallet.get_address(New),
+        wallet.reveal_next_address(KeychainKind::External).unwrap(),
         AddressInfo {
             index: 0,
             address: Address::from_str("tb1q6yn66vajcctph75pvylgkksgpp6nq04ppwct9a")
@@ -2758,7 +2818,7 @@ fn test_returns_index_and_address() {
 
     // new index 1
     assert_eq!(
-        wallet.get_address(New),
+        wallet.reveal_next_address(KeychainKind::External).unwrap(),
         AddressInfo {
             index: 1,
             address: Address::from_str("tb1q4er7kxx6sssz3q7qp7zsqsdx4erceahhax77d7")
@@ -2770,7 +2830,7 @@ fn test_returns_index_and_address() {
 
     // peek index 25
     assert_eq!(
-        wallet.get_address(Peek(25)),
+        wallet.peek_address(KeychainKind::External, 25),
         AddressInfo {
             index: 25,
             address: Address::from_str("tb1qsp7qu0knx3sl6536dzs0703u2w2ag6ppl9d0c2")
@@ -2782,7 +2842,7 @@ fn test_returns_index_and_address() {
 
     // new index 2
     assert_eq!(
-        wallet.get_address(New),
+        wallet.reveal_next_address(KeychainKind::External).unwrap(),
         AddressInfo {
             index: 2,
             address: Address::from_str("tb1qzntf2mqex4ehwkjlfdyy3ewdlk08qkvkvrz7x2")
@@ -2808,7 +2868,7 @@ fn test_sending_to_bip350_bech32m_address() {
 fn test_get_address() {
     use bdk::descriptor::template::Bip84;
     let key = bitcoin::bip32::Xpriv::from_str("tprv8ZgxMBicQKsPcx5nBGsR63Pe8KnRUqmbJNENAfGftF3yuXoMMoVJJcYeUw5eVkm9WBPjWYt6HMWYJNesB5HaNVBaFc1M6dRjWSYnmewUMYy").unwrap();
-    let mut wallet = Wallet::new_no_persist(
+    let wallet = Wallet::new_no_persist(
         Bip84(key, KeychainKind::External),
         Some(Bip84(key, KeychainKind::Internal)),
         Network::Regtest,
@@ -2816,7 +2876,7 @@ fn test_get_address() {
     .unwrap();
 
     assert_eq!(
-        wallet.get_address(AddressIndex::New),
+        wallet.peek_address(KeychainKind::External, 0),
         AddressInfo {
             index: 0,
             address: Address::from_str("bcrt1qrhgaqu0zvf5q2d0gwwz04w0dh0cuehhqvzpp4w")
@@ -2827,7 +2887,7 @@ fn test_get_address() {
     );
 
     assert_eq!(
-        wallet.get_internal_address(AddressIndex::New),
+        wallet.peek_address(KeychainKind::Internal, 0),
         AddressInfo {
             index: 0,
             address: Address::from_str("bcrt1q0ue3s5y935tw7v3gmnh36c5zzsaw4n9c9smq79")
@@ -2837,11 +2897,11 @@ fn test_get_address() {
         }
     );
 
-    let mut wallet =
+    let wallet =
         Wallet::new_no_persist(Bip84(key, KeychainKind::External), None, Network::Regtest).unwrap();
 
     assert_eq!(
-        wallet.get_internal_address(AddressIndex::New),
+        wallet.peek_address(KeychainKind::Internal, 0),
         AddressInfo {
             index: 0,
             address: Address::from_str("bcrt1qrhgaqu0zvf5q2d0gwwz04w0dh0cuehhqvzpp4w")
@@ -2853,6 +2913,28 @@ fn test_get_address() {
     );
 }
 
+#[test]
+fn test_reveal_addresses() {
+    let desc = get_test_tr_single_sig_xprv();
+    let mut wallet = Wallet::new_no_persist(desc, None, Network::Signet).unwrap();
+    let keychain = KeychainKind::External;
+
+    let last_revealed_addr = wallet
+        .reveal_addresses_to(keychain, 9)
+        .unwrap()
+        .last()
+        .unwrap();
+    assert_eq!(wallet.derivation_index(keychain), Some(9));
+
+    let unused_addrs = wallet.list_unused_addresses(keychain).collect::<Vec<_>>();
+    assert_eq!(unused_addrs.len(), 10);
+    assert_eq!(unused_addrs.last().unwrap(), &last_revealed_addr);
+
+    // revealing to an already revealed index returns nothing
+    let mut already_revealed = wallet.reveal_addresses_to(keychain, 9).unwrap();
+    assert!(already_revealed.next().is_none());
+}
+
 #[test]
 fn test_get_address_no_reuse_single_descriptor() {
     use bdk::descriptor::template::Bip84;
@@ -2865,10 +2947,16 @@ fn test_get_address_no_reuse_single_descriptor() {
     let mut used_set = HashSet::new();
 
     (0..3).for_each(|_| {
-        let external_addr = wallet.get_address(AddressIndex::New).address;
+        let external_addr = wallet
+            .reveal_next_address(KeychainKind::External)
+            .unwrap()
+            .address;
         assert!(used_set.insert(external_addr));
 
-        let internal_addr = wallet.get_internal_address(AddressIndex::New).address;
+        let internal_addr = wallet
+            .reveal_next_address(KeychainKind::Internal)
+            .unwrap()
+            .address;
         assert!(used_set.insert(internal_addr));
     });
 }
@@ -2877,7 +2965,7 @@ fn test_get_address_no_reuse_single_descriptor() {
 fn test_taproot_remove_tapfields_after_finalize_sign_option() {
     let (mut wallet, _) = get_funded_wallet(get_test_tr_with_taptree());
 
-    let addr = wallet.get_address(New);
+    let addr = wallet.next_unused_address(KeychainKind::External).unwrap();
     let mut builder = wallet.build_tx();
     builder.drain_to(addr.script_pubkey()).drain_wallet();
     let mut psbt = builder.finish().unwrap();
@@ -2902,7 +2990,7 @@ fn test_taproot_remove_tapfields_after_finalize_sign_option() {
 #[test]
 fn test_taproot_psbt_populate_tap_key_origins() {
     let (mut wallet, _) = get_funded_wallet(get_test_tr_single_sig_xprv());
-    let addr = wallet.get_address(AddressIndex::New);
+    let addr = wallet.reveal_next_address(KeychainKind::External).unwrap();
 
     let mut builder = wallet.build_tx();
     builder.add_recipient(addr.script_pubkey(), 25_000);
@@ -2937,7 +3025,7 @@ fn test_taproot_psbt_populate_tap_key_origins() {
 #[test]
 fn test_taproot_psbt_populate_tap_key_origins_repeated_key() {
     let (mut wallet, _) = get_funded_wallet(get_test_tr_repeated_key());
-    let addr = wallet.get_address(AddressIndex::New);
+    let addr = wallet.reveal_next_address(KeychainKind::External).unwrap();
 
     let path = vec![("rn4nre9c".to_string(), vec![0])]
         .into_iter()
@@ -3003,7 +3091,7 @@ fn test_taproot_psbt_input_tap_tree() {
     use bitcoin::taproot;
 
     let (mut wallet, _) = get_funded_wallet(get_test_tr_with_taptree());
-    let addr = wallet.get_address(AddressIndex::Peek(0));
+    let addr = wallet.next_unused_address(KeychainKind::External).unwrap();
 
     let mut builder = wallet.build_tx();
     builder.drain_to(addr.script_pubkey()).drain_wallet();
@@ -3046,7 +3134,7 @@ fn test_taproot_psbt_input_tap_tree() {
 #[test]
 fn test_taproot_sign_missing_witness_utxo() {
     let (mut wallet, _) = get_funded_wallet(get_test_tr_single_sig());
-    let addr = wallet.get_address(New);
+    let addr = wallet.next_unused_address(KeychainKind::External).unwrap();
     let mut builder = wallet.build_tx();
     builder.drain_to(addr.script_pubkey()).drain_wallet();
     let mut psbt = builder.finish().unwrap();
@@ -3086,7 +3174,7 @@ fn test_taproot_sign_missing_witness_utxo() {
 #[test]
 fn test_taproot_sign_using_non_witness_utxo() {
     let (mut wallet, prev_txid) = get_funded_wallet(get_test_tr_single_sig());
-    let addr = wallet.get_address(New);
+    let addr = wallet.next_unused_address(KeychainKind::External).unwrap();
     let mut builder = wallet.build_tx();
     builder.drain_to(addr.script_pubkey()).drain_wallet();
     let mut psbt = builder.finish().unwrap();
@@ -3154,7 +3242,7 @@ fn test_taproot_foreign_utxo() {
 }
 
 fn test_spend_from_wallet(mut wallet: Wallet) {
-    let addr = wallet.get_address(AddressIndex::New);
+    let addr = wallet.next_unused_address(KeychainKind::External).unwrap();
 
     let mut builder = wallet.build_tx();
     builder.add_recipient(addr.script_pubkey(), 25_000);
@@ -3178,7 +3266,7 @@ fn test_spend_from_wallet(mut wallet: Wallet) {
 #[test]
 fn test_taproot_no_key_spend() {
     let (mut wallet, _) = get_funded_wallet(get_test_tr_with_taptree_both_priv());
-    let addr = wallet.get_address(AddressIndex::New);
+    let addr = wallet.next_unused_address(KeychainKind::External).unwrap();
 
     let mut builder = wallet.build_tx();
     builder.add_recipient(addr.script_pubkey(), 25_000);
@@ -3213,7 +3301,7 @@ fn test_taproot_script_spend() {
 fn test_taproot_script_spend_sign_all_leaves() {
     use bdk::signer::TapLeavesOptions;
     let (mut wallet, _) = get_funded_wallet(get_test_tr_with_taptree_both_priv());
-    let addr = wallet.get_address(AddressIndex::New);
+    let addr = wallet.next_unused_address(KeychainKind::External).unwrap();
 
     let mut builder = wallet.build_tx();
     builder.add_recipient(addr.script_pubkey(), 25_000);
@@ -3244,7 +3332,7 @@ fn test_taproot_script_spend_sign_include_some_leaves() {
     use bitcoin::taproot::TapLeafHash;
 
     let (mut wallet, _) = get_funded_wallet(get_test_tr_with_taptree_both_priv());
-    let addr = wallet.get_address(AddressIndex::New);
+    let addr = wallet.next_unused_address(KeychainKind::External).unwrap();
 
     let mut builder = wallet.build_tx();
     builder.add_recipient(addr.script_pubkey(), 25_000);
@@ -3284,7 +3372,7 @@ fn test_taproot_script_spend_sign_exclude_some_leaves() {
     use bitcoin::taproot::TapLeafHash;
 
     let (mut wallet, _) = get_funded_wallet(get_test_tr_with_taptree_both_priv());
-    let addr = wallet.get_address(AddressIndex::New);
+    let addr = wallet.next_unused_address(KeychainKind::External).unwrap();
 
     let mut builder = wallet.build_tx();
     builder.add_recipient(addr.script_pubkey(), 25_000);
@@ -3322,7 +3410,7 @@ fn test_taproot_script_spend_sign_exclude_some_leaves() {
 fn test_taproot_script_spend_sign_no_leaves() {
     use bdk::signer::TapLeavesOptions;
     let (mut wallet, _) = get_funded_wallet(get_test_tr_with_taptree_both_priv());
-    let addr = wallet.get_address(AddressIndex::New);
+    let addr = wallet.next_unused_address(KeychainKind::External).unwrap();
 
     let mut builder = wallet.build_tx();
     builder.add_recipient(addr.script_pubkey(), 25_000);
@@ -3345,7 +3433,7 @@ fn test_taproot_script_spend_sign_no_leaves() {
 fn test_taproot_sign_derive_index_from_psbt() {
     let (mut wallet, _) = get_funded_wallet(get_test_tr_single_sig_xprv());
 
-    let addr = wallet.get_address(AddressIndex::New);
+    let addr = wallet.next_unused_address(KeychainKind::External).unwrap();
 
     let mut builder = wallet.build_tx();
     builder.add_recipient(addr.script_pubkey(), 25_000);
@@ -3366,7 +3454,7 @@ fn test_taproot_sign_derive_index_from_psbt() {
 #[test]
 fn test_taproot_sign_explicit_sighash_all() {
     let (mut wallet, _) = get_funded_wallet(get_test_tr_single_sig());
-    let addr = wallet.get_address(New);
+    let addr = wallet.next_unused_address(KeychainKind::External).unwrap();
     let mut builder = wallet.build_tx();
     builder
         .drain_to(addr.script_pubkey())
@@ -3386,7 +3474,7 @@ fn test_taproot_sign_non_default_sighash() {
     let sighash = TapSighashType::NonePlusAnyoneCanPay;
 
     let (mut wallet, _) = get_funded_wallet(get_test_tr_single_sig());
-    let addr = wallet.get_address(New);
+    let addr = wallet.next_unused_address(KeychainKind::External).unwrap();
     let mut builder = wallet.build_tx();
     builder
         .drain_to(addr.script_pubkey())
@@ -3470,8 +3558,11 @@ fn test_spend_coinbase() {
             ..Default::default()
         }],
         output: vec![TxOut {
+            script_pubkey: wallet
+                .next_unused_address(KeychainKind::External)
+                .unwrap()
+                .script_pubkey(),
             value: Amount::from_sat(25_000),
-            script_pubkey: wallet.get_address(New).address.script_pubkey(),
         }],
     };
     wallet
@@ -3559,7 +3650,7 @@ fn test_spend_coinbase() {
 fn test_allow_dust_limit() {
     let (mut wallet, _) = get_funded_wallet(get_test_single_sig_cltv());
 
-    let addr = wallet.get_address(New);
+    let addr = wallet.next_unused_address(KeychainKind::External).unwrap();
 
     let mut builder = wallet.build_tx();
 
@@ -3585,7 +3676,7 @@ fn test_fee_rate_sign_no_grinding_high_r() {
     // instead of 70). We then check that our fee rate and fee calculation is
     // alright.
     let (mut wallet, _) = get_funded_wallet("wpkh(tprv8ZgxMBicQKsPd3EupYiPRhaMooHKUHJxNsTfYuScep13go8QFfHdtkG9nRkFGb7busX4isf6X9dURGCoKgitaApQ6MupRhZMcELAxTBRJgS/*)");
-    let addr = wallet.get_address(New);
+    let addr = wallet.next_unused_address(KeychainKind::External).unwrap();
     let fee_rate = FeeRate::from_sat_per_vb_unchecked(1);
     let mut builder = wallet.build_tx();
     let mut data = PushBytesBuf::try_from(vec![0]).unwrap();
@@ -3651,7 +3742,7 @@ fn test_fee_rate_sign_grinding_low_r() {
     // We then check that our fee rate and fee calculation is alright and that our
     // signature is 70 bytes.
     let (mut wallet, _) = get_funded_wallet("wpkh(tprv8ZgxMBicQKsPd3EupYiPRhaMooHKUHJxNsTfYuScep13go8QFfHdtkG9nRkFGb7busX4isf6X9dURGCoKgitaApQ6MupRhZMcELAxTBRJgS/*)");
-    let addr = wallet.get_address(New);
+    let addr = wallet.next_unused_address(KeychainKind::External).unwrap();
     let fee_rate = FeeRate::from_sat_per_vb_unchecked(1);
     let mut builder = wallet.build_tx();
     builder
@@ -3684,8 +3775,8 @@ fn test_taproot_load_descriptor_duplicated_keys() {
     //
     // Having the same key in multiple taproot leaves is safe and should be accepted by BDK
 
-    let (mut wallet, _) = get_funded_wallet(get_test_tr_dup_keys());
-    let addr = wallet.get_address(New);
+    let (wallet, _) = get_funded_wallet(get_test_tr_dup_keys());
+    let addr = wallet.peek_address(KeychainKind::External, 0);
 
     assert_eq!(
         addr.to_string(),

crates/bitcoind_rpc/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "bdk_bitcoind_rpc"
-version = "0.8.0"
+version = "0.9.0"
 edition = "2021"
 rust-version = "1.63"
 homepage = "https://bitcoindevkit.org"
@@ -16,7 +16,7 @@ readme = "README.md"
 # For no-std, remember to enable the bitcoin/no-std feature
 bitcoin = { version = "0.31", default-features = false }
 bitcoincore-rpc = { version = "0.18" }
-bdk_chain = { path = "../chain", version = "0.12", default-features = false }
+bdk_chain = { path = "../chain", version = "0.13", default-features = false }
 
 [dev-dependencies]
 bdk_testenv = { path = "../testenv", default_features = false }

crates/bitcoind_rpc/tests/test_emitter.rs

@@ -4,7 +4,7 @@ use bdk_bitcoind_rpc::Emitter;
 use bdk_chain::{
     bitcoin::{Address, Amount, Txid},
     keychain::Balance,
-    local_chain::{self, CheckPoint, LocalChain},
+    local_chain::{CheckPoint, LocalChain},
     Append, BlockId, IndexedTxGraph, SpkTxOutIndex,
 };
 use bdk_testenv::TestEnv;
@@ -47,10 +47,7 @@ pub fn test_sync_local_chain() -> anyhow::Result<()> {
         );
 
         assert_eq!(
-            local_chain.apply_update(local_chain::Update {
-                tip: emission.checkpoint,
-                introduce_older_blocks: false,
-            })?,
+            local_chain.apply_update(emission.checkpoint,)?,
             BTreeMap::from([(height, Some(hash))]),
             "chain update changeset is unexpected",
         );
@@ -95,10 +92,7 @@ pub fn test_sync_local_chain() -> anyhow::Result<()> {
         );
 
         assert_eq!(
-            local_chain.apply_update(local_chain::Update {
-                tip: emission.checkpoint,
-                introduce_older_blocks: false,
-            })?,
+            local_chain.apply_update(emission.checkpoint,)?,
             if exp_height == exp_hashes.len() - reorged_blocks.len() {
                 core::iter::once((height, Some(hash)))
                     .chain((height + 1..exp_hashes.len() as u32).map(|h| (h, None)))
@@ -168,10 +162,7 @@ fn test_into_tx_graph() -> anyhow::Result<()> {
 
     while let Some(emission) = emitter.next_block()? {
         let height = emission.block_height();
-        let _ = chain.apply_update(local_chain::Update {
-            tip: emission.checkpoint,
-            introduce_older_blocks: false,
-        })?;
+        let _ = chain.apply_update(emission.checkpoint)?;
         let indexed_additions = indexed_tx_graph.apply_block_relevant(&emission.block, height);
         assert!(indexed_additions.is_empty());
     }
@@ -232,10 +223,7 @@ fn test_into_tx_graph() -> anyhow::Result<()> {
     {
         let emission = emitter.next_block()?.expect("must get mined block");
         let height = emission.block_height();
-        let _ = chain.apply_update(local_chain::Update {
-            tip: emission.checkpoint,
-            introduce_older_blocks: false,
-        })?;
+        let _ = chain.apply_update(emission.checkpoint)?;
         let indexed_additions = indexed_tx_graph.apply_block_relevant(&emission.block, height);
         assert!(indexed_additions.graph.txs.is_empty());
         assert!(indexed_additions.graph.txouts.is_empty());
@@ -294,8 +282,7 @@ fn process_block(
     block: Block,
     block_height: u32,
 ) -> anyhow::Result<()> {
-    recv_chain
-        .apply_update(CheckPoint::from_header(&block.header, block_height).into_update(false))?;
+    recv_chain.apply_update(CheckPoint::from_header(&block.header, block_height))?;
     let _ = recv_graph.apply_block(block, block_height);
     Ok(())
 }

crates/chain/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "bdk_chain"
-version = "0.12.0"
+version = "0.13.0"
 edition = "2021"
 rust-version = "1.63"
 homepage = "https://bitcoindevkit.org"

crates/chain/src/keychain/txout_index.rs

@@ -268,15 +268,14 @@ impl<K: Clone + Ord + Debug> KeychainTxOutIndex<K> {
         self.inner.unmark_used(&(keychain, index))
     }
 
-    /// Computes total input value going from script pubkeys in the index (sent) and the total output
-    /// value going to script pubkeys in the index (received) in `tx`. For the `sent` to be computed
-    /// correctly, the output being spent must have already been scanned by the index. Calculating
-    /// received just uses the [`Transaction`] outputs directly, so it will be correct even if it has
-    /// not been scanned.
-    ///
-    /// This calls [`SpkTxOutIndex::sent_and_received`] internally.
-    pub fn sent_and_received(&self, tx: &Transaction) -> (u64, u64) {
-        self.inner.sent_and_received(tx)
+    /// Computes the total value transfer effect `tx` has on the script pubkeys belonging to the
+    /// keychains in `range`. Value is *sent* when a script pubkey in the `range` is on an input and
+    /// *received* when it is on an output. For `sent` to be computed correctly, the output being
+    /// spent must have already been scanned by the index. Calculating received just uses the
+    /// [`Transaction`] outputs directly, so it will be correct even if it has not been scanned.
+    pub fn sent_and_received(&self, tx: &Transaction, range: impl RangeBounds<K>) -> (u64, u64) {
+        self.inner
+            .sent_and_received(tx, Self::map_to_inner_bounds(range))
     }
 
     /// Computes the net value that this transaction gives to the script pubkeys in the index and
@@ -286,8 +285,8 @@ impl<K: Clone + Ord + Debug> KeychainTxOutIndex<K> {
     /// This calls [`SpkTxOutIndex::net_value`] internally.
     ///
     /// [`sent_and_received`]: Self::sent_and_received
-    pub fn net_value(&self, tx: &Transaction) -> i64 {
-        self.inner.net_value(tx)
+    pub fn net_value(&self, tx: &Transaction, range: impl RangeBounds<K>) -> i64 {
+        self.inner.net_value(tx, Self::map_to_inner_bounds(range))
     }
 }
 
@@ -390,24 +389,32 @@ impl<K: Clone + Ord + Debug> KeychainTxOutIndex<K> {
             .collect()
     }
 
-    /// Iterate over revealed spks of all keychains.
-    pub fn revealed_spks(&self) -> impl DoubleEndedIterator<Item = (K, u32, &Script)> + Clone {
-        self.keychains.keys().flat_map(|keychain| {
-            self.revealed_keychain_spks(keychain)
-                .map(|(i, spk)| (keychain.clone(), i, spk))
+    /// Iterate over revealed spks of keychains in `range`
+    pub fn revealed_spks(
+        &self,
+        range: impl RangeBounds<K>,
+    ) -> impl DoubleEndedIterator<Item = (&K, u32, &Script)> + Clone {
+        self.keychains.range(range).flat_map(|(keychain, _)| {
+            let start = Bound::Included((keychain.clone(), u32::MIN));
+            let end = match self.last_revealed.get(keychain) {
+                Some(last_revealed) => Bound::Included((keychain.clone(), *last_revealed)),
+                None => Bound::Excluded((keychain.clone(), u32::MIN)),
+            };
+
+            self.inner
+                .all_spks()
+                .range((start, end))
+                .map(|((keychain, i), spk)| (keychain, *i, spk.as_script()))
         })
     }
 
     /// Iterate over revealed spks of the given `keychain`.
-    pub fn revealed_keychain_spks(
-        &self,
-        keychain: &K,
-    ) -> impl DoubleEndedIterator<Item = (u32, &Script)> + Clone {
-        let next_i = self.last_revealed.get(keychain).map_or(0, |&i| i + 1);
-        self.inner
-            .all_spks()
-            .range((keychain.clone(), u32::MIN)..(keychain.clone(), next_i))
-            .map(|((_, i), spk)| (*i, spk.as_script()))
+    pub fn revealed_keychain_spks<'a>(
+        &'a self,
+        keychain: &'a K,
+    ) -> impl DoubleEndedIterator<Item = (u32, &Script)> + 'a {
+        self.revealed_spks(keychain..=keychain)
+            .map(|(_, i, spk)| (i, spk))
     }
 
     /// Iterate over revealed, but unused, spks of all keychains.
@@ -617,38 +624,40 @@ impl<K: Clone + Ord + Debug> KeychainTxOutIndex<K> {
         }
     }
 
-    /// Iterate over all [`OutPoint`]s that point to `TxOut`s with script pubkeys derived from
+    /// Iterate over all [`OutPoint`]s that have `TxOut`s with script pubkeys derived from
     /// `keychain`.
-    ///
-    /// Use [`keychain_outpoints_in_range`](KeychainTxOutIndex::keychain_outpoints_in_range) to
-    /// iterate over a specific derivation range.
-    pub fn keychain_outpoints(
-        &self,
-        keychain: &K,
-    ) -> impl DoubleEndedIterator<Item = (u32, OutPoint)> + '_ {
-        self.keychain_outpoints_in_range(keychain, ..)
+    pub fn keychain_outpoints<'a>(
+        &'a self,
+        keychain: &'a K,
+    ) -> impl DoubleEndedIterator<Item = (u32, OutPoint)> + 'a {
+        self.keychain_outpoints_in_range(keychain..=keychain)
+            .map(move |(_, i, op)| (i, op))
     }
 
-    /// Iterate over [`OutPoint`]s that point to `TxOut`s with script pubkeys derived from
-    /// `keychain` in a given derivation `range`.
-    pub fn keychain_outpoints_in_range(
-        &self,
-        keychain: &K,
-        range: impl RangeBounds<u32>,
-    ) -> impl DoubleEndedIterator<Item = (u32, OutPoint)> + '_ {
-        let start = match range.start_bound() {
-            Bound::Included(i) => Bound::Included((keychain.clone(), *i)),
-            Bound::Excluded(i) => Bound::Excluded((keychain.clone(), *i)),
-            Bound::Unbounded => Bound::Unbounded,
-        };
-        let end = match range.end_bound() {
-            Bound::Included(i) => Bound::Included((keychain.clone(), *i)),
-            Bound::Excluded(i) => Bound::Excluded((keychain.clone(), *i)),
-            Bound::Unbounded => Bound::Unbounded,
-        };
+    /// Iterate over [`OutPoint`]s that have script pubkeys derived from keychains in `range`.
+    pub fn keychain_outpoints_in_range<'a>(
+        &'a self,
+        range: impl RangeBounds<K> + 'a,
+    ) -> impl DoubleEndedIterator<Item = (&'a K, u32, OutPoint)> + 'a {
+        let bounds = Self::map_to_inner_bounds(range);
         self.inner
-            .outputs_in_range((start, end))
-            .map(|((_, i), op)| (*i, op))
+            .outputs_in_range(bounds)
+            .map(move |((keychain, i), op)| (keychain, *i, op))
+    }
+
+    fn map_to_inner_bounds(bound: impl RangeBounds<K>) -> impl RangeBounds<(K, u32)> {
+        let start = match bound.start_bound() {
+            Bound::Included(keychain) => Bound::Included((keychain.clone(), u32::MIN)),
+            Bound::Excluded(keychain) => Bound::Excluded((keychain.clone(), u32::MAX)),
+            Bound::Unbounded => Bound::Unbounded,
+        };
+        let end = match bound.end_bound() {
+            Bound::Included(keychain) => Bound::Included((keychain.clone(), u32::MAX)),
+            Bound::Excluded(keychain) => Bound::Excluded((keychain.clone(), u32::MIN)),
+            Bound::Unbounded => Bound::Unbounded,
+        };
+
+        (start, end)
     }
 
     /// Returns the highest derivation index of the `keychain` where [`KeychainTxOutIndex`] has

crates/chain/src/lib.rs

@@ -35,8 +35,6 @@ pub use tx_data_traits::*;
 pub use tx_graph::TxGraph;
 mod chain_oracle;
 pub use chain_oracle::*;
-mod persist;
-pub use persist::*;
 
 #[doc(hidden)]
 pub mod example_utils;
@@ -51,6 +49,7 @@ pub use descriptor_ext::DescriptorExt;
 mod spk_iter;
 #[cfg(feature = "miniscript")]
 pub use spk_iter::*;
+pub mod spk_client;
 
 #[allow(unused_imports)]
 #[macro_use]

crates/chain/src/local_chain.rs

@@ -96,16 +96,6 @@ impl CheckPoint {
             .expect("must construct checkpoint")
     }
 
-    /// Convenience method to convert the [`CheckPoint`] into an [`Update`].
-    ///
-    /// For more information, refer to [`Update`].
-    pub fn into_update(self, introduce_older_blocks: bool) -> Update {
-        Update {
-            tip: self,
-            introduce_older_blocks,
-        }
-    }
-
     /// Puts another checkpoint onto the linked list representing the blockchain.
     ///
     /// Returns an `Err(self)` if the block you are pushing on is not at a greater height that the one you
@@ -187,6 +177,82 @@ impl CheckPoint {
                 core::ops::Bound::Unbounded => true,
             })
     }
+
+    /// Inserts `block_id` at its height within the chain.
+    ///
+    /// The effect of `insert` depends on whether a height already exists. If it doesn't the
+    /// `block_id` we inserted and all pre-existing blocks higher than it will be re-inserted after
+    /// it. If the height already existed and has a conflicting block hash then it will be purged
+    /// along with all block followin it. The returned chain will have a tip of the `block_id`
+    /// passed in. Of course, if the `block_id` was already present then this just returns `self`.
+    #[must_use]
+    pub fn insert(self, block_id: BlockId) -> Self {
+        assert_ne!(block_id.height, 0, "cannot insert the genesis block");
+
+        let mut cp = self.clone();
+        let mut tail = vec![];
+        let base = loop {
+            if cp.height() == block_id.height {
+                if cp.hash() == block_id.hash {
+                    return self;
+                }
+                // if we have a conflict we just return the inserted block because the tail is by
+                // implication invalid.
+                tail = vec![];
+                break cp.prev().expect("can't be called on genesis block");
+            }
+
+            if cp.height() < block_id.height {
+                break cp;
+            }
+
+            tail.push(cp.block_id());
+            cp = cp.prev().expect("will break before genesis block");
+        };
+
+        base.extend(core::iter::once(block_id).chain(tail.into_iter().rev()))
+            .expect("tail is in order")
+    }
+
+    /// Apply `changeset` to the checkpoint.
+    fn apply_changeset(mut self, changeset: &ChangeSet) -> Result<CheckPoint, MissingGenesisError> {
+        if let Some(start_height) = changeset.keys().next().cloned() {
+            // changes after point of agreement
+            let mut extension = BTreeMap::default();
+            // point of agreement
+            let mut base: Option<CheckPoint> = None;
+
+            for cp in self.iter() {
+                if cp.height() >= start_height {
+                    extension.insert(cp.height(), cp.hash());
+                } else {
+                    base = Some(cp);
+                    break;
+                }
+            }
+
+            for (&height, &hash) in changeset {
+                match hash {
+                    Some(hash) => {
+                        extension.insert(height, hash);
+                    }
+                    None => {
+                        extension.remove(&height);
+                    }
+                };
+            }
+
+            let new_tip = match base {
+                Some(base) => base
+                    .extend(extension.into_iter().map(BlockId::from))
+                    .expect("extension is strictly greater than base"),
+                None => LocalChain::from_blocks(extension)?.tip(),
+            };
+            self = new_tip;
+        }
+
+        Ok(self)
+    }
 }
 
 /// Iterates over checkpoints backwards.
@@ -199,7 +265,7 @@ impl Iterator for CheckPointIter {
 
     fn next(&mut self) -> Option<Self::Item> {
         let current = self.current.clone()?;
-        self.current = current.prev.clone();
+        self.current.clone_from(&current.prev);
         Some(CheckPoint(current))
     }
 }
@@ -215,31 +281,6 @@ impl IntoIterator for CheckPoint {
     }
 }
 
-/// Used to update [`LocalChain`].
-///
-/// This is used as input for [`LocalChain::apply_update`]. It contains the update's chain `tip` and
-/// a flag `introduce_older_blocks` which signals whether this update intends to introduce missing
-/// blocks to the original chain.
-///
-/// Block-by-block syncing mechanisms would typically create updates that builds upon the previous
-/// tip. In this case, `introduce_older_blocks` would be `false`.
-///
-/// Script-pubkey based syncing mechanisms may not introduce transactions in a chronological order
-/// so some updates require introducing older blocks (to anchor older transactions). For
-/// script-pubkey based syncing, `introduce_older_blocks` would typically be `true`.
-#[derive(Debug, Clone, PartialEq)]
-pub struct Update {
-    /// The update chain's new tip.
-    pub tip: CheckPoint,
-
-    /// Whether the update allows for introducing older blocks.
-    ///
-    /// Refer to [struct-level documentation] for more.
-    ///
-    /// [struct-level documentation]: Update
-    pub introduce_older_blocks: bool,
-}
-
 /// This is a local implementation of [`ChainOracle`].
 #[derive(Debug, Clone, PartialEq)]
 pub struct LocalChain {
@@ -318,7 +359,7 @@ impl LocalChain {
     /// The [`BTreeMap`] enforces the height order. However, the caller must ensure the blocks are
     /// all of the same chain.
     pub fn from_blocks(blocks: BTreeMap<u32, BlockHash>) -> Result<Self, MissingGenesisError> {
-        if blocks.get(&0).is_none() {
+        if !blocks.contains_key(&0) {
             return Err(MissingGenesisError);
         }
 
@@ -347,36 +388,22 @@ impl LocalChain {
 
     /// Applies the given `update` to the chain.
     ///
-    /// The method returns [`ChangeSet`] on success. This represents the applied changes to `self`.
+    /// The method returns [`ChangeSet`] on success. This represents the changes applied to `self`.
     ///
     /// There must be no ambiguity about which of the existing chain's blocks are still valid and
     /// which are now invalid. That is, the new chain must implicitly connect to a definite block in
     /// the existing chain and invalidate the block after it (if it exists) by including a block at
     /// the same height but with a different hash to explicitly exclude it as a connection point.
     ///
-    /// Additionally, an empty chain can be updated with any chain, and a chain with a single block
-    /// can have it's block invalidated by an update chain with a block at the same height but
-    /// different hash.
-    ///
     /// # Errors
     ///
     /// An error will occur if the update does not correctly connect with `self`.
     ///
-    /// Refer to [`Update`] for more about the update struct.
-    ///
     /// [module-level documentation]: crate::local_chain
-    pub fn apply_update(&mut self, update: Update) -> Result<ChangeSet, CannotConnectError> {
-        let changeset = merge_chains(
-            self.tip.clone(),
-            update.tip.clone(),
-            update.introduce_older_blocks,
-        )?;
-        // `._check_index_is_consistent_with_tip` and `._check_changeset_is_applied` is called in
-        // `.apply_changeset`
-        self.apply_changeset(&changeset)
-            .map_err(|_| CannotConnectError {
-                try_include_height: 0,
-            })?;
+    pub fn apply_update(&mut self, update: CheckPoint) -> Result<ChangeSet, CannotConnectError> {
+        let (new_tip, changeset) = merge_chains(self.tip.clone(), update)?;
+        self.tip = new_tip;
+        self._check_changeset_is_applied(&changeset);
         Ok(changeset)
     }
 
@@ -428,11 +455,8 @@ impl LocalChain {
             conn => Some(conn),
         };
 
-        let update = Update {
-            tip: CheckPoint::from_block_ids([conn, prev, Some(this)].into_iter().flatten())
-                .expect("block ids must be in order"),
-            introduce_older_blocks: false,
-        };
+        let update = CheckPoint::from_block_ids([conn, prev, Some(this)].into_iter().flatten())
+            .expect("block ids must be in order");
 
         self.apply_update(update)
             .map_err(ApplyHeaderError::CannotConnect)
@@ -471,43 +495,10 @@ impl LocalChain {
 
     /// Apply the given `changeset`.
     pub fn apply_changeset(&mut self, changeset: &ChangeSet) -> Result<(), MissingGenesisError> {
-        if let Some(start_height) = changeset.keys().next().cloned() {
-            // changes after point of agreement
-            let mut extension = BTreeMap::default();
-            // point of agreement
-            let mut base: Option<CheckPoint> = None;
-
-            for cp in self.iter_checkpoints() {
-                if cp.height() >= start_height {
-                    extension.insert(cp.height(), cp.hash());
-                } else {
-                    base = Some(cp);
-                    break;
-                }
-            }
-
-            for (&height, &hash) in changeset {
-                match hash {
-                    Some(hash) => {
-                        extension.insert(height, hash);
-                    }
-                    None => {
-                        extension.remove(&height);
-                    }
-                };
-            }
-
-            let new_tip = match base {
-                Some(base) => base
-                    .extend(extension.into_iter().map(BlockId::from))
-                    .expect("extension is strictly greater than base"),
-                None => LocalChain::from_blocks(extension)?.tip(),
-            };
-            self.tip = new_tip;
-
-            debug_assert!(self._check_changeset_is_applied(changeset));
-        }
-
+        let old_tip = self.tip.clone();
+        let new_tip = old_tip.apply_changeset(changeset)?;
+        self.tip = new_tip;
+        debug_assert!(self._check_changeset_is_applied(changeset));
         Ok(())
     }
 
@@ -730,14 +721,17 @@ impl core::fmt::Display for ApplyHeaderError {
 #[cfg(feature = "std")]
 impl std::error::Error for ApplyHeaderError {}
 
+/// Applies `update_tip` onto `original_tip`.
+///
+/// On success, a tuple is returned `(changeset, can_replace)`. If `can_replace` is true, then the
+/// `update_tip` can replace the `original_tip`.
 fn merge_chains(
     original_tip: CheckPoint,
     update_tip: CheckPoint,
-    introduce_older_blocks: bool,
-) -> Result<ChangeSet, CannotConnectError> {
+) -> Result<(CheckPoint, ChangeSet), CannotConnectError> {
     let mut changeset = ChangeSet::default();
-    let mut orig = original_tip.into_iter();
-    let mut update = update_tip.into_iter();
+    let mut orig = original_tip.iter();
+    let mut update = update_tip.iter();
     let mut curr_orig = None;
     let mut curr_update = None;
     let mut prev_orig: Option<CheckPoint> = None;
@@ -746,6 +740,12 @@ fn merge_chains(
     let mut prev_orig_was_invalidated = false;
     let mut potentially_invalidated_heights = vec![];
 
+    // If we can, we want to return the update tip as the new tip because this allows checkpoints
+    // in multiple locations to keep the same `Arc` pointers when they are being updated from each
+    // other using this function. We can do this as long as long as the update contains every
+    // block's height of the original chain.
+    let mut is_update_height_superset_of_original = true;
+
     // To find the difference between the new chain and the original we iterate over both of them
     // from the tip backwards in tandem. We always dealing with the highest one from either chain
     // first and move to the next highest. The crucial logic is applied when they have blocks at the
@@ -771,6 +771,8 @@ fn merge_chains(
                 prev_orig_was_invalidated = false;
                 prev_orig = curr_orig.take();
 
+                is_update_height_superset_of_original = false;
+
                 // OPTIMIZATION: we have run out of update blocks so we don't need to continue
                 // iterating because there's no possibility of adding anything to changeset.
                 if u.is_none() {
@@ -793,12 +795,20 @@ fn merge_chains(
                     }
                     point_of_agreement_found = true;
                     prev_orig_was_invalidated = false;
-                    // OPTIMIZATION 1 -- If we know that older blocks cannot be introduced without
-                    // invalidation, we can break after finding the point of agreement.
                     // OPTIMIZATION 2 -- if we have the same underlying pointer at this point, we
                     // can guarantee that no older blocks are introduced.
-                    if !introduce_older_blocks || Arc::as_ptr(&o.0) == Arc::as_ptr(&u.0) {
-                        return Ok(changeset);
+                    if Arc::as_ptr(&o.0) == Arc::as_ptr(&u.0) {
+                        if is_update_height_superset_of_original {
+                            return Ok((update_tip, changeset));
+                        } else {
+                            let new_tip =
+                                original_tip.apply_changeset(&changeset).map_err(|_| {
+                                    CannotConnectError {
+                                        try_include_height: 0,
+                                    }
+                                })?;
+                            return Ok((new_tip, changeset));
+                        }
                     }
                 } else {
                     // We have an invalidation height so we set the height to the updated hash and
@@ -832,5 +842,10 @@ fn merge_chains(
         }
     }
 
-    Ok(changeset)
+    let new_tip = original_tip
+        .apply_changeset(&changeset)
+        .map_err(|_| CannotConnectError {
+            try_include_height: 0,
+        })?;
+    Ok((new_tip, changeset))
 }

crates/chain/src/spk_client.rs

@@ -0,0 +1,387 @@
+//! Helper types for spk-based blockchain clients.
+
+use core::{fmt::Debug, marker::PhantomData, ops::RangeBounds};
+
+use alloc::{boxed::Box, collections::BTreeMap, vec::Vec};
+use bitcoin::{OutPoint, Script, ScriptBuf, Txid};
+
+use crate::{local_chain::CheckPoint, ConfirmationTimeHeightAnchor, TxGraph};
+
+/// Data required to perform a spk-based blockchain client sync.
+///
+/// A client sync fetches relevant chain data for a known list of scripts, transaction ids and
+/// outpoints. The sync process also updates the chain from the given [`CheckPoint`].
+pub struct SyncRequest {
+    /// A checkpoint for the current chain [`LocalChain::tip`].
+    /// The sync process will return a new chain update that extends this tip.
+    ///
+    /// [`LocalChain::tip`]: crate::local_chain::LocalChain::tip
+    pub chain_tip: CheckPoint,
+    /// Transactions that spend from or to these indexed script pubkeys.
+    pub spks: Box<dyn ExactSizeIterator<Item = ScriptBuf> + Send>,
+    /// Transactions with these txids.
+    pub txids: Box<dyn ExactSizeIterator<Item = Txid> + Send>,
+    /// Transactions with these outpoints or spent from these outpoints.
+    pub outpoints: Box<dyn ExactSizeIterator<Item = OutPoint> + Send>,
+}
+
+impl SyncRequest {
+    /// Construct a new [`SyncRequest`] from a given `cp` tip.
+    pub fn from_chain_tip(cp: CheckPoint) -> Self {
+        Self {
+            chain_tip: cp,
+            spks: Box::new(core::iter::empty()),
+            txids: Box::new(core::iter::empty()),
+            outpoints: Box::new(core::iter::empty()),
+        }
+    }
+
+    /// Set the [`Script`]s that will be synced against.
+    ///
+    /// This consumes the [`SyncRequest`] and returns the updated one.
+    #[must_use]
+    pub fn set_spks(
+        mut self,
+        spks: impl IntoIterator<IntoIter = impl ExactSizeIterator<Item = ScriptBuf> + Send + 'static>,
+    ) -> Self {
+        self.spks = Box::new(spks.into_iter());
+        self
+    }
+
+    /// Set the [`Txid`]s that will be synced against.
+    ///
+    /// This consumes the [`SyncRequest`] and returns the updated one.
+    #[must_use]
+    pub fn set_txids(
+        mut self,
+        txids: impl IntoIterator<IntoIter = impl ExactSizeIterator<Item = Txid> + Send + 'static>,
+    ) -> Self {
+        self.txids = Box::new(txids.into_iter());
+        self
+    }
+
+    /// Set the [`OutPoint`]s that will be synced against.
+    ///
+    /// This consumes the [`SyncRequest`] and returns the updated one.
+    #[must_use]
+    pub fn set_outpoints(
+        mut self,
+        outpoints: impl IntoIterator<
+            IntoIter = impl ExactSizeIterator<Item = OutPoint> + Send + 'static,
+        >,
+    ) -> Self {
+        self.outpoints = Box::new(outpoints.into_iter());
+        self
+    }
+
+    /// Chain on additional [`Script`]s that will be synced against.
+    ///
+    /// This consumes the [`SyncRequest`] and returns the updated one.
+    #[must_use]
+    pub fn chain_spks(
+        mut self,
+        spks: impl IntoIterator<
+            IntoIter = impl ExactSizeIterator<Item = ScriptBuf> + Send + 'static,
+            Item = ScriptBuf,
+        >,
+    ) -> Self {
+        self.spks = Box::new(ExactSizeChain::new(self.spks, spks.into_iter()));
+        self
+    }
+
+    /// Chain on additional [`Txid`]s that will be synced against.
+    ///
+    /// This consumes the [`SyncRequest`] and returns the updated one.
+    #[must_use]
+    pub fn chain_txids(
+        mut self,
+        txids: impl IntoIterator<
+            IntoIter = impl ExactSizeIterator<Item = Txid> + Send + 'static,
+            Item = Txid,
+        >,
+    ) -> Self {
+        self.txids = Box::new(ExactSizeChain::new(self.txids, txids.into_iter()));
+        self
+    }
+
+    /// Chain on additional [`OutPoint`]s that will be synced against.
+    ///
+    /// This consumes the [`SyncRequest`] and returns the updated one.
+    #[must_use]
+    pub fn chain_outpoints(
+        mut self,
+        outpoints: impl IntoIterator<
+            IntoIter = impl ExactSizeIterator<Item = OutPoint> + Send + 'static,
+            Item = OutPoint,
+        >,
+    ) -> Self {
+        self.outpoints = Box::new(ExactSizeChain::new(self.outpoints, outpoints.into_iter()));
+        self
+    }
+
+    /// Add a closure that will be called for [`Script`]s previously added to this request.
+    ///
+    /// This consumes the [`SyncRequest`] and returns the updated one.
+    #[must_use]
+    pub fn inspect_spks(
+        mut self,
+        mut inspect: impl FnMut(&Script) + Send + Sync + 'static,
+    ) -> Self {
+        self.spks = Box::new(self.spks.inspect(move |spk| inspect(spk)));
+        self
+    }
+
+    /// Add a closure that will be called for [`Txid`]s previously added to this request.
+    ///
+    /// This consumes the [`SyncRequest`] and returns the updated one.
+    #[must_use]
+    pub fn inspect_txids(mut self, mut inspect: impl FnMut(&Txid) + Send + Sync + 'static) -> Self {
+        self.txids = Box::new(self.txids.inspect(move |txid| inspect(txid)));
+        self
+    }
+
+    /// Add a closure that will be called for [`OutPoint`]s previously added to this request.
+    ///
+    /// This consumes the [`SyncRequest`] and returns the updated one.
+    #[must_use]
+    pub fn inspect_outpoints(
+        mut self,
+        mut inspect: impl FnMut(&OutPoint) + Send + Sync + 'static,
+    ) -> Self {
+        self.outpoints = Box::new(self.outpoints.inspect(move |op| inspect(op)));
+        self
+    }
+
+    /// Populate the request with revealed script pubkeys from `index` with the given `spk_range`.
+    ///
+    /// This consumes the [`SyncRequest`] and returns the updated one.
+    #[cfg(feature = "miniscript")]
+    #[must_use]
+    pub fn populate_with_revealed_spks<K: Clone + Ord + Debug + Send + Sync>(
+        self,
+        index: &crate::keychain::KeychainTxOutIndex<K>,
+        spk_range: impl RangeBounds<K>,
+    ) -> Self {
+        use alloc::borrow::ToOwned;
+        self.chain_spks(
+            index
+                .revealed_spks(spk_range)
+                .map(|(_, _, spk)| spk.to_owned())
+                .collect::<Vec<_>>(),
+        )
+    }
+}
+
+/// Data returned from a spk-based blockchain client sync.
+///
+/// See also [`SyncRequest`].
+pub struct SyncResult<A = ConfirmationTimeHeightAnchor> {
+    /// The update to apply to the receiving [`TxGraph`].
+    pub graph_update: TxGraph<A>,
+    /// The update to apply to the receiving [`LocalChain`](crate::local_chain::LocalChain).
+    pub chain_update: CheckPoint,
+}
+
+/// Data required to perform a spk-based blockchain client full scan.
+///
+/// A client full scan iterates through all the scripts for the given keychains, fetching relevant
+/// data until some stop gap number of scripts is found that have no data. This operation is
+/// generally only used when importing or restoring previously used keychains in which the list of
+/// used scripts is not known. The full scan process also updates the chain from the given [`CheckPoint`].
+pub struct FullScanRequest<K> {
+    /// A checkpoint for the current [`LocalChain::tip`].
+    /// The full scan process will return a new chain update that extends this tip.
+    ///
+    /// [`LocalChain::tip`]: crate::local_chain::LocalChain::tip
+    pub chain_tip: CheckPoint,
+    /// Iterators of script pubkeys indexed by the keychain index.
+    pub spks_by_keychain: BTreeMap<K, Box<dyn Iterator<Item = (u32, ScriptBuf)> + Send>>,
+}
+
+impl<K: Ord + Clone> FullScanRequest<K> {
+    /// Construct a new [`FullScanRequest`] from a given `chain_tip`.
+    #[must_use]
+    pub fn from_chain_tip(chain_tip: CheckPoint) -> Self {
+        Self {
+            chain_tip,
+            spks_by_keychain: BTreeMap::new(),
+        }
+    }
+
+    /// Construct a new [`FullScanRequest`] from a given `chain_tip` and `index`.
+    ///
+    /// Unbounded script pubkey iterators for each keychain (`K`) are extracted using
+    /// [`KeychainTxOutIndex::all_unbounded_spk_iters`] and is used to populate the
+    /// [`FullScanRequest`].
+    ///
+    /// [`KeychainTxOutIndex::all_unbounded_spk_iters`]: crate::keychain::KeychainTxOutIndex::all_unbounded_spk_iters
+    #[cfg(feature = "miniscript")]
+    #[must_use]
+    pub fn from_keychain_txout_index(
+        chain_tip: CheckPoint,
+        index: &crate::keychain::KeychainTxOutIndex<K>,
+    ) -> Self
+    where
+        K: Debug,
+    {
+        let mut req = Self::from_chain_tip(chain_tip);
+        for (keychain, spks) in index.all_unbounded_spk_iters() {
+            req = req.set_spks_for_keychain(keychain, spks);
+        }
+        req
+    }
+
+    /// Set the [`Script`]s for a given `keychain`.
+    ///
+    /// This consumes the [`FullScanRequest`] and returns the updated one.
+    #[must_use]
+    pub fn set_spks_for_keychain(
+        mut self,
+        keychain: K,
+        spks: impl IntoIterator<IntoIter = impl Iterator<Item = (u32, ScriptBuf)> + Send + 'static>,
+    ) -> Self {
+        self.spks_by_keychain
+            .insert(keychain, Box::new(spks.into_iter()));
+        self
+    }
+
+    /// Chain on additional [`Script`]s that will be synced against.
+    ///
+    /// This consumes the [`FullScanRequest`] and returns the updated one.
+    #[must_use]
+    pub fn chain_spks_for_keychain(
+        mut self,
+        keychain: K,
+        spks: impl IntoIterator<IntoIter = impl Iterator<Item = (u32, ScriptBuf)> + Send + 'static>,
+    ) -> Self {
+        match self.spks_by_keychain.remove(&keychain) {
+            // clippy here suggests to remove `into_iter` from `spks.into_iter()`, but doing so
+            // results in a compilation error
+            #[allow(clippy::useless_conversion)]
+            Some(keychain_spks) => self
+                .spks_by_keychain
+                .insert(keychain, Box::new(keychain_spks.chain(spks.into_iter()))),
+            None => self
+                .spks_by_keychain
+                .insert(keychain, Box::new(spks.into_iter())),
+        };
+        self
+    }
+
+    /// Add a closure that will be called for every [`Script`] previously added to any keychain in
+    /// this request.
+    ///
+    /// This consumes the [`SyncRequest`] and returns the updated one.
+    #[must_use]
+    pub fn inspect_spks_for_all_keychains(
+        mut self,
+        inspect: impl FnMut(K, u32, &Script) + Send + Sync + Clone + 'static,
+    ) -> Self
+    where
+        K: Send + 'static,
+    {
+        for (keychain, spks) in core::mem::take(&mut self.spks_by_keychain) {
+            let mut inspect = inspect.clone();
+            self.spks_by_keychain.insert(
+                keychain.clone(),
+                Box::new(spks.inspect(move |(i, spk)| inspect(keychain.clone(), *i, spk))),
+            );
+        }
+        self
+    }
+
+    /// Add a closure that will be called for every [`Script`] previously added to a given
+    /// `keychain` in this request.
+    ///
+    /// This consumes the [`SyncRequest`] and returns the updated one.
+    #[must_use]
+    pub fn inspect_spks_for_keychain(
+        mut self,
+        keychain: K,
+        mut inspect: impl FnMut(u32, &Script) + Send + Sync + 'static,
+    ) -> Self
+    where
+        K: Send + 'static,
+    {
+        if let Some(spks) = self.spks_by_keychain.remove(&keychain) {
+            self.spks_by_keychain.insert(
+                keychain,
+                Box::new(spks.inspect(move |(i, spk)| inspect(*i, spk))),
+            );
+        }
+        self
+    }
+}
+
+/// Data returned from a spk-based blockchain client full scan.
+///
+/// See also [`FullScanRequest`].
+pub struct FullScanResult<K> {
+    /// The update to apply to the receiving [`LocalChain`](crate::local_chain::LocalChain).
+    pub graph_update: TxGraph<ConfirmationTimeHeightAnchor>,
+    /// The update to apply to the receiving [`TxGraph`].
+    pub chain_update: CheckPoint,
+    /// Last active indices for the corresponding keychains (`K`).
+    pub last_active_indices: BTreeMap<K, u32>,
+}
+
+/// A version of [`core::iter::Chain`] which can combine two [`ExactSizeIterator`]s to form a new
+/// [`ExactSizeIterator`].
+///
+/// The danger of this is explained in [the `ExactSizeIterator` docs]
+/// (https://doc.rust-lang.org/core/iter/trait.ExactSizeIterator.html#when-shouldnt-an-adapter-be-exactsizeiterator).
+/// This does not apply here since it would be impossible to scan an item count that overflows
+/// `usize` anyway.
+struct ExactSizeChain<A, B, I> {
+    a: Option<A>,
+    b: Option<B>,
+    i: PhantomData<I>,
+}
+
+impl<A, B, I> ExactSizeChain<A, B, I> {
+    fn new(a: A, b: B) -> Self {
+        ExactSizeChain {
+            a: Some(a),
+            b: Some(b),
+            i: PhantomData,
+        }
+    }
+}
+
+impl<A, B, I> Iterator for ExactSizeChain<A, B, I>
+where
+    A: Iterator<Item = I>,
+    B: Iterator<Item = I>,
+{
+    type Item = I;
+
+    fn next(&mut self) -> Option<Self::Item> {
+        if let Some(a) = &mut self.a {
+            let item = a.next();
+            if item.is_some() {
+                return item;
+            }
+            self.a = None;
+        }
+        if let Some(b) = &mut self.b {
+            let item = b.next();
+            if item.is_some() {
+                return item;
+            }
+            self.b = None;
+        }
+        None
+    }
+}
+
+impl<A, B, I> ExactSizeIterator for ExactSizeChain<A, B, I>
+where
+    A: ExactSizeIterator<Item = I>,
+    B: ExactSizeIterator<Item = I>,
+{
+    fn len(&self) -> usize {
+        let a_len = self.a.as_ref().map(|a| a.len()).unwrap_or(0);
+        let b_len = self.b.as_ref().map(|a| a.len()).unwrap_or(0);
+        a_len + b_len
+    }
+}

crates/chain/src/spk_iter.rs

@@ -260,6 +260,7 @@ mod test {
     }
 
     // The following dummy traits were created to test if SpkIterator is working properly.
+    #[allow(unused)]
     trait TestSendStatic: Send + 'static {
         fn test(&self) -> u32 {
             20

crates/chain/src/spk_txout_index.rs

@@ -229,7 +229,7 @@ impl<I: Clone + Ord> SpkTxOutIndex<I> {
     /// Here, "unused" means that after the script pubkey was stored in the index, the index has
     /// never scanned a transaction output with it.
     pub fn is_used(&self, index: &I) -> bool {
-        self.unused.get(index).is_none()
+        !self.unused.contains(index)
     }
 
     /// Marks the script pubkey at `index` as used even though it hasn't seen an output spending to it.
@@ -270,36 +270,39 @@ impl<I: Clone + Ord> SpkTxOutIndex<I> {
         self.spk_indices.get(script)
     }
 
-    /// Computes total input value going from script pubkeys in the index (sent) and the total output
-    /// value going to script pubkeys in the index (received) in `tx`. For the `sent` to be computed
-    /// correctly, the output being spent must have already been scanned by the index. Calculating
-    /// received just uses the [`Transaction`] outputs directly, so it will be correct even if it has
-    /// not been scanned.
-    pub fn sent_and_received(&self, tx: &Transaction) -> (u64, u64) {
+    /// Computes the total value transfer effect `tx` has on the script pubkeys in `range`. Value is
+    /// *sent* when a script pubkey in the `range` is on an input and *received* when it is on an
+    /// output. For `sent` to be computed correctly, the output being spent must have already been
+    /// scanned by the index. Calculating received just uses the [`Transaction`] outputs directly,
+    /// so it will be correct even if it has not been scanned.
+    pub fn sent_and_received(&self, tx: &Transaction, range: impl RangeBounds<I>) -> (u64, u64) {
         let mut sent = 0;
         let mut received = 0;
 
         for txin in &tx.input {
-            if let Some((_, txout)) = self.txout(txin.previous_output) {
-                sent += txout.value.to_sat();
+            if let Some((index, txout)) = self.txout(txin.previous_output) {
+                if range.contains(index) {
+                    sent += txout.value.to_sat();
+                }
             }
         }
         for txout in &tx.output {
-            if self.index_of_spk(&txout.script_pubkey).is_some() {
-                received += txout.value.to_sat();
+            if let Some(index) = self.index_of_spk(&txout.script_pubkey) {
+                if range.contains(index) {
+                    received += txout.value.to_sat();
+                }
             }
         }
 
         (sent, received)
     }
 
-    /// Computes the net value that this transaction gives to the script pubkeys in the index and
-    /// *takes* from the transaction outputs in the index. Shorthand for calling
-    /// [`sent_and_received`] and subtracting sent from received.
+    /// Computes the net value transfer effect of `tx` on the script pubkeys in `range`. Shorthand
+    /// for calling [`sent_and_received`] and subtracting sent from received.
     ///
     /// [`sent_and_received`]: Self::sent_and_received
-    pub fn net_value(&self, tx: &Transaction) -> i64 {
-        let (sent, received) = self.sent_and_received(tx);
+    pub fn net_value(&self, tx: &Transaction, range: impl RangeBounds<I>) -> i64 {
+        let (sent, received) = self.sent_and_received(tx, range);
         received as i64 - sent as i64
     }
 

crates/chain/src/tx_graph.rs

@@ -89,8 +89,8 @@
 //! [`insert_txout`]: TxGraph::insert_txout
 
 use crate::{
-    collections::*, keychain::Balance, local_chain::LocalChain, Anchor, Append, BlockId,
-    ChainOracle, ChainPosition, FullTxOut,
+    collections::*, keychain::Balance, Anchor, Append, BlockId, ChainOracle, ChainPosition,
+    FullTxOut,
 };
 use alloc::collections::vec_deque::VecDeque;
 use alloc::sync::Arc;
@@ -759,69 +759,6 @@ impl<A: Clone + Ord> TxGraph<A> {
 }
 
 impl<A: Anchor> TxGraph<A> {
-    /// Find missing block heights of `chain`.
-    ///
-    /// This works by scanning through anchors, and seeing whether the anchor block of the anchor
-    /// exists in the [`LocalChain`]. The returned iterator does not output duplicate heights.
-    pub fn missing_heights<'a>(&'a self, chain: &'a LocalChain) -> impl Iterator<Item = u32> + 'a {
-        // Map of txids to skip.
-        //
-        // Usually, if a height of a tx anchor is missing from the chain, we would want to return
-        // this height in the iterator. The exception is when the tx is confirmed in chain. All the
-        // other missing-height anchors of this tx can be skipped.
-        //
-        // * Some(true)  => skip all anchors of this txid
-        // * Some(false) => do not skip anchors of this txid
-        // * None        => we do not know whether we can skip this txid
-        let mut txids_to_skip = HashMap::<Txid, bool>::new();
-
-        // Keeps track of the last height emitted so we don't double up.
-        let mut last_height_emitted = Option::<u32>::None;
-
-        self.anchors
-            .iter()
-            .filter(move |(_, txid)| {
-                let skip = *txids_to_skip.entry(*txid).or_insert_with(|| {
-                    let tx_anchors = match self.txs.get(txid) {
-                        Some((_, anchors, _)) => anchors,
-                        None => return true,
-                    };
-                    let mut has_missing_height = false;
-                    for anchor_block in tx_anchors.iter().map(Anchor::anchor_block) {
-                        match chain.get(anchor_block.height) {
-                            None => {
-                                has_missing_height = true;
-                                continue;
-                            }
-                            Some(chain_cp) => {
-                                if chain_cp.hash() == anchor_block.hash {
-                                    return true;
-                                }
-                            }
-                        }
-                    }
-                    !has_missing_height
-                });
-                #[cfg(feature = "std")]
-                debug_assert!({
-                    println!("txid={} skip={}", txid, skip);
-                    true
-                });
-                !skip
-            })
-            .filter_map(move |(a, _)| {
-                let anchor_block = a.anchor_block();
-                if Some(anchor_block.height) != last_height_emitted
-                    && chain.get(anchor_block.height).is_none()
-                {
-                    last_height_emitted = Some(anchor_block.height);
-                    Some(anchor_block.height)
-                } else {
-                    None
-                }
-            })
-    }
-
     /// Get the position of the transaction in `chain` with tip `chain_tip`.
     ///
     /// Chain data is fetched from `chain`, a [`ChainOracle`] implementation.
@@ -1330,8 +1267,6 @@ impl<A> ChangeSet<A> {
     ///
     /// This is useful if you want to find which heights you need to fetch data about in order to
     /// confirm or exclude these anchors.
-    ///
-    /// See also: [`TxGraph::missing_heights`]
     pub fn anchor_heights(&self) -> impl Iterator<Item = u32> + '_
     where
         A: Anchor,
@@ -1346,24 +1281,6 @@ impl<A> ChangeSet<A> {
                 !duplicate
             })
     }
-
-    /// Returns an iterator for the [`anchor_heights`] in this changeset that are not included in
-    /// `local_chain`. This tells you which heights you need to include in `local_chain` in order
-    /// for it to conclusively act as a [`ChainOracle`] for the transaction anchors this changeset
-    /// will add.
-    ///
-    /// [`ChainOracle`]: crate::ChainOracle
-    /// [`anchor_heights`]: Self::anchor_heights
-    pub fn missing_heights_from<'a>(
-        &'a self,
-        local_chain: &'a LocalChain,
-    ) -> impl Iterator<Item = u32> + 'a
-    where
-        A: Anchor,
-    {
-        self.anchor_heights()
-            .filter(move |&height| local_chain.get(height).is_none())
-    }
 }
 
 impl<A: Ord> Append for ChangeSet<A> {

crates/chain/tests/common/mod.rs

@@ -32,12 +32,9 @@ macro_rules! local_chain {
 macro_rules! chain_update {
     [ $(($height:expr, $hash:expr)), * ] => {{
         #[allow(unused_mut)]
-        bdk_chain::local_chain::Update {
-            tip: bdk_chain::local_chain::LocalChain::from_blocks([$(($height, $hash).into()),*].into_iter().collect())
-                .expect("chain must have genesis block")
-                .tip(),
-            introduce_older_blocks: true,
-        }
+        bdk_chain::local_chain::LocalChain::from_blocks([$(($height, $hash).into()),*].into_iter().collect())
+            .expect("chain must have genesis block")
+            .tip()
     }};
 }
 

crates/chain/tests/test_local_chain.rs

@@ -3,7 +3,7 @@ use std::ops::{Bound, RangeBounds};
 use bdk_chain::{
     local_chain::{
         AlterCheckPointError, ApplyHeaderError, CannotConnectError, ChangeSet, CheckPoint,
-        LocalChain, MissingGenesisError, Update,
+        LocalChain, MissingGenesisError,
     },
     BlockId,
 };
@@ -17,7 +17,7 @@ mod common;
 struct TestLocalChain<'a> {
     name: &'static str,
     chain: LocalChain,
-    update: Update,
+    update: CheckPoint,
     exp: ExpectedResult<'a>,
 }
 
@@ -577,6 +577,77 @@ fn checkpoint_query() {
     }
 }
 
+#[test]
+fn checkpoint_insert() {
+    struct TestCase<'a> {
+        /// The name of the test.
+        name: &'a str,
+        /// The original checkpoint chain to call [`CheckPoint::insert`] on.
+        chain: &'a [(u32, BlockHash)],
+        /// The `block_id` to insert.
+        to_insert: (u32, BlockHash),
+        /// The expected final checkpoint chain after calling [`CheckPoint::insert`].
+        exp_final_chain: &'a [(u32, BlockHash)],
+    }
+
+    let test_cases = [
+        TestCase {
+            name: "insert_above_tip",
+            chain: &[(1, h!("a")), (2, h!("b"))],
+            to_insert: (4, h!("d")),
+            exp_final_chain: &[(1, h!("a")), (2, h!("b")), (4, h!("d"))],
+        },
+        TestCase {
+            name: "insert_already_exists_expect_no_change",
+            chain: &[(1, h!("a")), (2, h!("b")), (3, h!("c"))],
+            to_insert: (2, h!("b")),
+            exp_final_chain: &[(1, h!("a")), (2, h!("b")), (3, h!("c"))],
+        },
+        TestCase {
+            name: "insert_in_middle",
+            chain: &[(2, h!("b")), (4, h!("d")), (5, h!("e"))],
+            to_insert: (3, h!("c")),
+            exp_final_chain: &[(2, h!("b")), (3, h!("c")), (4, h!("d")), (5, h!("e"))],
+        },
+        TestCase {
+            name: "replace_one",
+            chain: &[(3, h!("c")), (4, h!("d")), (5, h!("e"))],
+            to_insert: (5, h!("E")),
+            exp_final_chain: &[(3, h!("c")), (4, h!("d")), (5, h!("E"))],
+        },
+        TestCase {
+            name: "insert_conflict_should_evict",
+            chain: &[(3, h!("c")), (4, h!("d")), (5, h!("e")), (6, h!("f"))],
+            to_insert: (4, h!("D")),
+            exp_final_chain: &[(3, h!("c")), (4, h!("D"))],
+        },
+    ];
+
+    fn genesis_block() -> impl Iterator<Item = BlockId> {
+        core::iter::once((0, h!("_"))).map(BlockId::from)
+    }
+
+    for (i, t) in test_cases.into_iter().enumerate() {
+        println!("Running [{}] '{}'", i, t.name);
+
+        let chain = CheckPoint::from_block_ids(
+            genesis_block().chain(t.chain.iter().copied().map(BlockId::from)),
+        )
+        .expect("test formed incorrectly, must construct checkpoint chain");
+
+        let exp_final_chain = CheckPoint::from_block_ids(
+            genesis_block().chain(t.exp_final_chain.iter().copied().map(BlockId::from)),
+        )
+        .expect("test formed incorrectly, must construct checkpoint chain");
+
+        assert_eq!(
+            chain.insert(t.to_insert.into()),
+            exp_final_chain,
+            "unexpected final chain"
+        );
+    }
+}
+
 #[test]
 fn local_chain_apply_header_connected_to() {
     fn header_from_prev_blockhash(prev_blockhash: BlockHash) -> Header {
@@ -601,9 +672,9 @@ fn local_chain_apply_header_connected_to() {
 
     let test_cases = [
         {
-            let header = header_from_prev_blockhash(h!("A"));
+            let header = header_from_prev_blockhash(h!("_"));
             let hash = header.block_hash();
-            let height = 2;
+            let height = 1;
             let connected_to = BlockId { height, hash };
             TestCase {
                 name: "connected_to_self_header_applied_to_self",

crates/chain/tests/test_spk_txout_index.rs

@@ -20,11 +20,13 @@ fn spk_txout_sent_and_received() {
         }],
     };
 
-    assert_eq!(index.sent_and_received(&tx1), (0, 42_000));
-    assert_eq!(index.net_value(&tx1), 42_000);
+    assert_eq!(index.sent_and_received(&tx1, ..), (0, 42_000));
+    assert_eq!(index.sent_and_received(&tx1, ..1), (0, 42_000));
+    assert_eq!(index.sent_and_received(&tx1, 1..), (0, 0));
+    assert_eq!(index.net_value(&tx1, ..), 42_000);
     index.index_tx(&tx1);
     assert_eq!(
-        index.sent_and_received(&tx1),
+        index.sent_and_received(&tx1, ..),
         (0, 42_000),
         "shouldn't change after scanning"
     );
@@ -51,8 +53,10 @@ fn spk_txout_sent_and_received() {
         ],
     };
 
-    assert_eq!(index.sent_and_received(&tx2), (42_000, 50_000));
-    assert_eq!(index.net_value(&tx2), 8_000);
+    assert_eq!(index.sent_and_received(&tx2, ..), (42_000, 50_000));
+    assert_eq!(index.sent_and_received(&tx2, ..1), (42_000, 30_000));
+    assert_eq!(index.sent_and_received(&tx2, 1..), (0, 20_000));
+    assert_eq!(index.net_value(&tx2, ..), 8_000);
 }
 
 #[test]

crates/chain/tests/test_tx_graph.rs

@@ -1087,139 +1087,6 @@ fn update_last_seen_unconfirmed() {
     assert_eq!(graph.full_txs().next().unwrap().last_seen_unconfirmed, 2);
 }
 
-#[test]
-fn test_missing_blocks() {
-    /// An anchor implementation for testing, made up of `(the_anchor_block, random_data)`.
-    #[derive(Debug, Clone, Eq, PartialEq, PartialOrd, Ord, core::hash::Hash)]
-    struct TestAnchor(BlockId);
-
-    impl Anchor for TestAnchor {
-        fn anchor_block(&self) -> BlockId {
-            self.0
-        }
-    }
-
-    struct Scenario<'a> {
-        name: &'a str,
-        graph: TxGraph<TestAnchor>,
-        chain: LocalChain,
-        exp_heights: &'a [u32],
-    }
-
-    const fn new_anchor(height: u32, hash: BlockHash) -> TestAnchor {
-        TestAnchor(BlockId { height, hash })
-    }
-
-    fn new_scenario<'a>(
-        name: &'a str,
-        graph_anchors: &'a [(Txid, TestAnchor)],
-        chain: &'a [(u32, BlockHash)],
-        exp_heights: &'a [u32],
-    ) -> Scenario<'a> {
-        Scenario {
-            name,
-            graph: {
-                let mut g = TxGraph::default();
-                for (txid, anchor) in graph_anchors {
-                    let _ = g.insert_anchor(*txid, anchor.clone());
-                }
-                g
-            },
-            chain: {
-                let (mut c, _) = LocalChain::from_genesis_hash(h!("genesis"));
-                for (height, hash) in chain {
-                    let _ = c.insert_block(BlockId {
-                        height: *height,
-                        hash: *hash,
-                    });
-                }
-                c
-            },
-            exp_heights,
-        }
-    }
-
-    fn run(scenarios: &[Scenario]) {
-        for scenario in scenarios {
-            let Scenario {
-                name,
-                graph,
-                chain,
-                exp_heights,
-            } = scenario;
-
-            let heights = graph.missing_heights(chain).collect::<Vec<_>>();
-            assert_eq!(&heights, exp_heights, "scenario: {}", name);
-        }
-    }
-
-    run(&[
-        new_scenario(
-            "2 txs with the same anchor (2:B) which is missing from chain",
-            &[
-                (h!("tx_1"), new_anchor(2, h!("B"))),
-                (h!("tx_2"), new_anchor(2, h!("B"))),
-            ],
-            &[(1, h!("A")), (3, h!("C"))],
-            &[2],
-        ),
-        new_scenario(
-            "2 txs with different anchors at the same height, one of the anchors is missing",
-            &[
-                (h!("tx_1"), new_anchor(2, h!("B1"))),
-                (h!("tx_2"), new_anchor(2, h!("B2"))),
-            ],
-            &[(1, h!("A")), (2, h!("B1"))],
-            &[],
-        ),
-        new_scenario(
-            "tx with 2 anchors of same height which are missing from the chain",
-            &[
-                (h!("tx"), new_anchor(3, h!("C1"))),
-                (h!("tx"), new_anchor(3, h!("C2"))),
-            ],
-            &[(1, h!("A")), (4, h!("D"))],
-            &[3],
-        ),
-        new_scenario(
-            "tx with 2 anchors at the same height, chain has this height but does not match either anchor",
-            &[
-                (h!("tx"), new_anchor(4, h!("D1"))),
-                (h!("tx"), new_anchor(4, h!("D2"))),
-            ],
-            &[(4, h!("D3")), (5, h!("E"))],
-            &[],
-        ),
-        new_scenario(
-            "tx with 2 anchors at different heights, one anchor exists in chain, should return nothing",
-            &[
-                (h!("tx"), new_anchor(3, h!("C"))),
-                (h!("tx"), new_anchor(4, h!("D"))),
-            ],
-            &[(4, h!("D")), (5, h!("E"))],
-            &[],
-        ),
-        new_scenario(
-            "tx with 2 anchors at different heights, first height is already in chain with different hash, iterator should only return 2nd height",
-            &[
-                (h!("tx"), new_anchor(5, h!("E1"))),
-                (h!("tx"), new_anchor(6, h!("F1"))),
-            ],
-            &[(4, h!("D")), (5, h!("E")), (7, h!("G"))],
-            &[6],
-        ),
-        new_scenario(
-            "tx with 2 anchors at different heights, neither height is in chain, both heights should be returned",
-            &[
-                (h!("tx"), new_anchor(3, h!("C"))),
-                (h!("tx"), new_anchor(4, h!("D"))),
-            ],
-            &[(1, h!("A")), (2, h!("B"))],
-            &[3, 4],
-        ),
-    ]);
-}
-
 #[test]
 /// The `map_anchors` allow a caller to pass a function to reconstruct the [`TxGraph`] with any [`Anchor`],
 /// even though the function is non-deterministic.

crates/electrum/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "bdk_electrum"
-version = "0.11.0"
+version = "0.12.0"
 edition = "2021"
 homepage = "https://bitcoindevkit.org"
 repository = "https://github.com/bitcoindevkit/bdk"
@@ -12,11 +12,11 @@ readme = "README.md"
 # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
 
 [dependencies]
-bdk_chain = { path = "../chain", version = "0.12.0", default-features = false }
+bdk_chain = { path = "../chain", version = "0.13.0", default-features = false }
 electrum-client = { version = "0.19" }
 #rustls = { version = "=0.21.1", optional = true, features = ["dangerous_configuration"] }
 
 [dev-dependencies]
 bdk_testenv = { path = "../testenv", default-features = false }
 electrsd = { version= "0.27.1", features = ["bitcoind_25_0", "esplora_a33e97e1", "legacy"] }
-anyhow = "1"
+anyhow = "1"

crates/electrum/src/electrum_ext.rs

@@ -1,6 +1,6 @@
 use bdk_chain::{
     bitcoin::{OutPoint, ScriptBuf, Transaction, Txid},
-    local_chain::{self, CheckPoint},
+    local_chain::CheckPoint,
     tx_graph::{self, TxGraph},
     Anchor, BlockId, ConfirmationHeightAnchor, ConfirmationTimeHeightAnchor,
 };
@@ -124,7 +124,7 @@ impl RelevantTxids {
 #[derive(Debug)]
 pub struct ElectrumUpdate {
     /// Chain update
-    pub chain_update: local_chain::Update,
+    pub chain_update: CheckPoint,
     /// Transaction updates from electrum
     pub relevant_txids: RelevantTxids,
 }
@@ -232,10 +232,7 @@ impl<A: ElectrumApi> ElectrumExt for A {
                 continue; // reorg
             }
 
-            let chain_update = local_chain::Update {
-                tip,
-                introduce_older_blocks: true,
-            };
+            let chain_update = tip;
 
             let keychain_update = request_spks
                 .into_keys()

crates/esplora/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "bdk_esplora"
-version = "0.11.0"
+version = "0.12.0"
 edition = "2021"
 homepage = "https://bitcoindevkit.org"
 repository = "https://github.com/bitcoindevkit/bdk"
@@ -12,7 +12,7 @@ readme = "README.md"
 # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
 
 [dependencies]
-bdk_chain = { path = "../chain", version = "0.12.0", default-features = false }
+bdk_chain = { path = "../chain", version = "0.13.0", default-features = false }
 esplora-client = { version = "0.7.0", default-features = false }
 async-trait = { version = "0.1.66", optional = true }
 futures = { version = "0.3.26", optional = true }
@@ -25,11 +25,13 @@ miniscript = { version = "11.0.0", optional = true, default-features = false }
 bdk_testenv = { path = "../testenv", default_features = false }
 electrsd = { version= "0.27.1", features = ["bitcoind_25_0", "esplora_a33e97e1", "legacy"] }
 tokio = { version = "1", features = ["rt", "rt-multi-thread", "macros"] }
+anyhow = "1"
 
 [features]
-default = ["std", "async-https", "blocking"]
+default = ["std", "async-https", "blocking-https-rustls"]
 std = ["bdk_chain/std"]
 async = ["async-trait", "futures", "esplora-client/async"]
 async-https = ["async", "esplora-client/async-https"]
 async-https-rustls = ["async", "esplora-client/async-https-rustls"]
 blocking = ["esplora-client/blocking"]
+blocking-https-rustls = ["esplora-client/blocking-https-rustls"]

crates/esplora/src/async_ext.rs

@@ -1,12 +1,15 @@
+use std::collections::BTreeSet;
+
 use async_trait::async_trait;
-use bdk_chain::collections::btree_map;
+use bdk_chain::spk_client::{FullScanRequest, FullScanResult, SyncRequest, SyncResult};
+use bdk_chain::Anchor;
 use bdk_chain::{
-    bitcoin::{Amount, BlockHash, OutPoint, ScriptBuf, TxOut, Txid},
+    bitcoin::{BlockHash, OutPoint, ScriptBuf, TxOut, Txid},
     collections::BTreeMap,
-    local_chain::{self, CheckPoint},
+    local_chain::CheckPoint,
     BlockId, ConfirmationTimeHeightAnchor, TxGraph,
 };
-use esplora_client::TxStatus;
+use esplora_client::{Amount, TxStatus};
 use futures::{stream::FuturesOrdered, TryStreamExt};
 
 use crate::anchor_from_status;
@@ -22,36 +25,15 @@ type Error = Box<esplora_client::Error>;
 #[cfg_attr(target_arch = "wasm32", async_trait(?Send))]
 #[cfg_attr(not(target_arch = "wasm32"), async_trait)]
 pub trait EsploraAsyncExt {
-    /// Prepare a [`LocalChain`] update with blocks fetched from Esplora.
-    ///
-    /// * `local_tip` is the previous tip of [`LocalChain::tip`].
-    /// * `request_heights` is the block heights that we are interested in fetching from Esplora.
-    ///
-    /// The result of this method can be applied to [`LocalChain::apply_update`].
-    ///
-    /// ## Consistency
-    ///
-    /// The chain update returned is guaranteed to be consistent as long as there is not a *large* re-org
-    /// during the call. The size of re-org we can tollerate is server dependent but will be at
-    /// least 10.
-    ///
-    /// [`LocalChain`]: bdk_chain::local_chain::LocalChain
-    /// [`LocalChain::tip`]: bdk_chain::local_chain::LocalChain::tip
-    /// [`LocalChain::apply_update`]: bdk_chain::local_chain::LocalChain::apply_update
-    async fn update_local_chain(
-        &self,
-        local_tip: CheckPoint,
-        request_heights: impl IntoIterator<IntoIter = impl Iterator<Item = u32> + Send> + Send,
-    ) -> Result<local_chain::Update, Error>;
-
-    /// Full scan the keychain scripts specified with the blockchain (via an Esplora client) and
-    /// returns a [`TxGraph`] and a map of last active indices.
+    /// Scan keychain scripts for transactions against Esplora, returning an update that can be
+    /// applied to the receiving structures.
     ///
+    /// * `local_tip`: the previously seen tip from [`LocalChain::tip`].
     /// * `keychain_spks`: keychains that we want to scan transactions for
     ///
-    /// The full scan for each keychain stops after a gap of `stop_gap` script pubkeys with no associated
-    /// transactions. `parallel_requests` specifies the max number of HTTP requests to make in
-    /// parallel.
+    /// The full scan for each keychain stops after a gap of `stop_gap` script pubkeys with no
+    /// associated transactions. `parallel_requests` specifies the max number of HTTP requests to
+    /// make in parallel.
     ///
     /// ## Note
     ///
@@ -65,19 +47,19 @@ pub trait EsploraAsyncExt {
     /// and [Sparrow](https://www.sparrowwallet.com/docs/faq.html#ive-restored-my-wallet-but-some-of-my-funds-are-missing).
     ///
     /// A `stop_gap` of 0 will be treated as a `stop_gap` of 1.
+    ///
+    /// [`LocalChain::tip`]: bdk_chain::local_chain::LocalChain::tip
     async fn full_scan<K: Ord + Clone + Send>(
         &self,
-        keychain_spks: BTreeMap<
-            K,
-            impl IntoIterator<IntoIter = impl Iterator<Item = (u32, ScriptBuf)> + Send> + Send,
-        >,
+        request: FullScanRequest<K>,
         stop_gap: usize,
         parallel_requests: usize,
-    ) -> Result<(TxGraph<ConfirmationTimeHeightAnchor>, BTreeMap<K, u32>), Error>;
+    ) -> Result<FullScanResult<K>, Error>;
 
     /// Sync a set of scripts with the blockchain (via an Esplora client) for the data
     /// specified and return a [`TxGraph`].
     ///
+    /// * `local_tip`: the previously seen tip from [`LocalChain::tip`].
     /// * `misc_spks`: scripts that we want to sync transactions for
     /// * `txids`: transactions for which we want updated [`ConfirmationTimeHeightAnchor`]s
     /// * `outpoints`: transactions associated with these outpoints (residing, spending) that we
@@ -86,210 +68,214 @@ pub trait EsploraAsyncExt {
     /// If the scripts to sync are unknown, such as when restoring or importing a keychain that
     /// may include scripts that have been used, use [`full_scan`] with the keychain.
     ///
+    /// [`LocalChain::tip`]: bdk_chain::local_chain::LocalChain::tip
     /// [`full_scan`]: EsploraAsyncExt::full_scan
     async fn sync(
         &self,
-        misc_spks: impl IntoIterator<IntoIter = impl Iterator<Item = ScriptBuf> + Send> + Send,
-        txids: impl IntoIterator<IntoIter = impl Iterator<Item = Txid> + Send> + Send,
-        outpoints: impl IntoIterator<IntoIter = impl Iterator<Item = OutPoint> + Send> + Send,
+        request: SyncRequest,
         parallel_requests: usize,
-    ) -> Result<TxGraph<ConfirmationTimeHeightAnchor>, Error>;
+    ) -> Result<SyncResult, Error>;
 }
 
 #[cfg_attr(target_arch = "wasm32", async_trait(?Send))]
 #[cfg_attr(not(target_arch = "wasm32"), async_trait)]
 impl EsploraAsyncExt for esplora_client::AsyncClient {
-    async fn update_local_chain(
-        &self,
-        local_tip: CheckPoint,
-        request_heights: impl IntoIterator<IntoIter = impl Iterator<Item = u32> + Send> + Send,
-    ) -> Result<local_chain::Update, Error> {
-        // Fetch latest N (server dependent) blocks from Esplora. The server guarantees these are
-        // consistent.
-        let mut fetched_blocks = self
-            .get_blocks(None)
-            .await?
-            .into_iter()
-            .map(|b| (b.time.height, b.id))
-            .collect::<BTreeMap<u32, BlockHash>>();
-        let new_tip_height = fetched_blocks
-            .keys()
-            .last()
-            .copied()
-            .expect("must have atleast one block");
-
-        // Fetch blocks of heights that the caller is interested in, skipping blocks that are
-        // already fetched when constructing `fetched_blocks`.
-        for height in request_heights {
-            // do not fetch blocks higher than remote tip
-            if height > new_tip_height {
-                continue;
-            }
-            // only fetch what is missing
-            if let btree_map::Entry::Vacant(entry) = fetched_blocks.entry(height) {
-                // ❗The return value of `get_block_hash` is not strictly guaranteed to be consistent
-                // with the chain at the time of `get_blocks` above (there could have been a deep
-                // re-org). Since `get_blocks` returns 10 (or so) blocks we are assuming that it's
-                // not possible to have a re-org deeper than that.
-                entry.insert(self.get_block_hash(height).await?);
-            }
-        }
-
-        // Ensure `fetched_blocks` can create an update that connects with the original chain by
-        // finding a "Point of Agreement".
-        for (height, local_hash) in local_tip.iter().map(|cp| (cp.height(), cp.hash())) {
-            if height > new_tip_height {
-                continue;
-            }
-
-            let fetched_hash = match fetched_blocks.entry(height) {
-                btree_map::Entry::Occupied(entry) => *entry.get(),
-                btree_map::Entry::Vacant(entry) => {
-                    *entry.insert(self.get_block_hash(height).await?)
-                }
-            };
-
-            // We have found point of agreement so the update will connect!
-            if fetched_hash == local_hash {
-                break;
-            }
-        }
-
-        Ok(local_chain::Update {
-            tip: CheckPoint::from_block_ids(fetched_blocks.into_iter().map(BlockId::from))
-                .expect("must be in height order"),
-            introduce_older_blocks: true,
-        })
-    }
-
     async fn full_scan<K: Ord + Clone + Send>(
         &self,
-        keychain_spks: BTreeMap<
-            K,
-            impl IntoIterator<IntoIter = impl Iterator<Item = (u32, ScriptBuf)> + Send> + Send,
-        >,
+        request: FullScanRequest<K>,
         stop_gap: usize,
         parallel_requests: usize,
-    ) -> Result<(TxGraph<ConfirmationTimeHeightAnchor>, BTreeMap<K, u32>), Error> {
-        type TxsOfSpkIndex = (u32, Vec<esplora_client::Tx>);
-        let parallel_requests = Ord::max(parallel_requests, 1);
-        let mut graph = TxGraph::<ConfirmationTimeHeightAnchor>::default();
-        let mut last_active_indexes = BTreeMap::<K, u32>::new();
-        let stop_gap = Ord::max(stop_gap, 1);
-
-        for (keychain, spks) in keychain_spks {
-            let mut spks = spks.into_iter();
-            let mut last_index = Option::<u32>::None;
-            let mut last_active_index = Option::<u32>::None;
-
-            loop {
-                let handles = spks
-                    .by_ref()
-                    .take(parallel_requests)
-                    .map(|(spk_index, spk)| {
-                        let client = self.clone();
-                        async move {
-                            let mut last_seen = None;
-                            let mut spk_txs = Vec::new();
-                            loop {
-                                let txs = client.scripthash_txs(&spk, last_seen).await?;
-                                let tx_count = txs.len();
-                                last_seen = txs.last().map(|tx| tx.txid);
-                                spk_txs.extend(txs);
-                                if tx_count < 25 {
-                                    break Result::<_, Error>::Ok((spk_index, spk_txs));
-                                }
-                            }
-                        }
-                    })
-                    .collect::<FuturesOrdered<_>>();
-
-                if handles.is_empty() {
-                    break;
-                }
-
-                for (index, txs) in handles.try_collect::<Vec<TxsOfSpkIndex>>().await? {
-                    last_index = Some(index);
-                    if !txs.is_empty() {
-                        last_active_index = Some(index);
-                    }
-                    for tx in txs {
-                        let _ = graph.insert_tx(tx.to_tx());
-                        if let Some(anchor) = anchor_from_status(&tx.status) {
-                            let _ = graph.insert_anchor(tx.txid, anchor);
-                        }
-
-                        let previous_outputs = tx.vin.iter().filter_map(|vin| {
-                            let prevout = vin.prevout.as_ref()?;
-                            Some((
-                                OutPoint {
-                                    txid: vin.txid,
-                                    vout: vin.vout,
-                                },
-                                TxOut {
-                                    script_pubkey: prevout.scriptpubkey.clone(),
-                                    value: Amount::from_sat(prevout.value),
-                                },
-                            ))
-                        });
-
-                        for (outpoint, txout) in previous_outputs {
-                            let _ = graph.insert_txout(outpoint, txout);
-                        }
-                    }
-                }
-
-                let last_index = last_index.expect("Must be set since handles wasn't empty.");
-                let gap_limit_reached = if let Some(i) = last_active_index {
-                    last_index >= i.saturating_add(stop_gap as u32)
-                } else {
-                    last_index + 1 >= stop_gap as u32
-                };
-                if gap_limit_reached {
-                    break;
-                }
-            }
-
-            if let Some(last_active_index) = last_active_index {
-                last_active_indexes.insert(keychain, last_active_index);
-            }
-        }
-
-        Ok((graph, last_active_indexes))
+    ) -> Result<FullScanResult<K>, Error> {
+        let latest_blocks = fetch_latest_blocks(self).await?;
+        let (graph_update, last_active_indices) = full_scan_for_index_and_graph(
+            self,
+            request.spks_by_keychain,
+            stop_gap,
+            parallel_requests,
+        )
+        .await?;
+        let chain_update = chain_update(
+            self,
+            &latest_blocks,
+            &request.chain_tip,
+            graph_update.all_anchors(),
+        )
+        .await?;
+        Ok(FullScanResult {
+            chain_update,
+            graph_update,
+            last_active_indices,
+        })
     }
 
     async fn sync(
         &self,
-        misc_spks: impl IntoIterator<IntoIter = impl Iterator<Item = ScriptBuf> + Send> + Send,
-        txids: impl IntoIterator<IntoIter = impl Iterator<Item = Txid> + Send> + Send,
-        outpoints: impl IntoIterator<IntoIter = impl Iterator<Item = OutPoint> + Send> + Send,
+        request: SyncRequest,
         parallel_requests: usize,
-    ) -> Result<TxGraph<ConfirmationTimeHeightAnchor>, Error> {
-        let mut graph = self
-            .full_scan(
-                [(
-                    (),
-                    misc_spks
-                        .into_iter()
-                        .enumerate()
-                        .map(|(i, spk)| (i as u32, spk)),
-                )]
-                .into(),
-                usize::MAX,
-                parallel_requests,
-            )
-            .await
-            .map(|(g, _)| g)?;
+    ) -> Result<SyncResult, Error> {
+        let latest_blocks = fetch_latest_blocks(self).await?;
+        let graph_update = sync_for_index_and_graph(
+            self,
+            request.spks,
+            request.txids,
+            request.outpoints,
+            parallel_requests,
+        )
+        .await?;
+        let chain_update = chain_update(
+            self,
+            &latest_blocks,
+            &request.chain_tip,
+            graph_update.all_anchors(),
+        )
+        .await?;
+        Ok(SyncResult {
+            chain_update,
+            graph_update,
+        })
+    }
+}
+
+/// Fetch latest blocks from Esplora in an atomic call.
+///
+/// We want to do this before fetching transactions and anchors as we cannot fetch latest blocks AND
+/// transactions atomically, and the checkpoint tip is used to determine last-scanned block (for
+/// block-based chain-sources). Therefore it's better to be conservative when setting the tip (use
+/// an earlier tip rather than a later tip) otherwise the caller may accidentally skip blocks when
+/// alternating between chain-sources.
+async fn fetch_latest_blocks(
+    client: &esplora_client::AsyncClient,
+) -> Result<BTreeMap<u32, BlockHash>, Error> {
+    Ok(client
+        .get_blocks(None)
+        .await?
+        .into_iter()
+        .map(|b| (b.time.height, b.id))
+        .collect())
+}
+
+/// Used instead of [`esplora_client::BlockingClient::get_block_hash`].
+///
+/// This first checks the previously fetched `latest_blocks` before fetching from Esplora again.
+async fn fetch_block(
+    client: &esplora_client::AsyncClient,
+    latest_blocks: &BTreeMap<u32, BlockHash>,
+    height: u32,
+) -> Result<Option<BlockHash>, Error> {
+    if let Some(&hash) = latest_blocks.get(&height) {
+        return Ok(Some(hash));
+    }
+
+    // We avoid fetching blocks higher than previously fetched `latest_blocks` as the local chain
+    // tip is used to signal for the last-synced-up-to-height.
+    let &tip_height = latest_blocks
+        .keys()
+        .last()
+        .expect("must have atleast one entry");
+    if height > tip_height {
+        return Ok(None);
+    }
+
+    Ok(Some(client.get_block_hash(height).await?))
+}
+
+/// Create the [`local_chain::Update`].
+///
+/// We want to have a corresponding checkpoint per anchor height. However, checkpoints fetched
+/// should not surpass `latest_blocks`.
+async fn chain_update<A: Anchor>(
+    client: &esplora_client::AsyncClient,
+    latest_blocks: &BTreeMap<u32, BlockHash>,
+    local_tip: &CheckPoint,
+    anchors: &BTreeSet<(A, Txid)>,
+) -> Result<CheckPoint, Error> {
+    let mut point_of_agreement = None;
+    let mut conflicts = vec![];
+    for local_cp in local_tip.iter() {
+        let remote_hash = match fetch_block(client, latest_blocks, local_cp.height()).await? {
+            Some(hash) => hash,
+            None => continue,
+        };
+        if remote_hash == local_cp.hash() {
+            point_of_agreement = Some(local_cp.clone());
+            break;
+        } else {
+            // it is not strictly necessary to include all the conflicted heights (we do need the
+            // first one) but it seems prudent to make sure the updated chain's heights are a
+            // superset of the existing chain after update.
+            conflicts.push(BlockId {
+                height: local_cp.height(),
+                hash: remote_hash,
+            });
+        }
+    }
+
+    let mut tip = point_of_agreement.expect("remote esplora should have same genesis block");
+
+    tip = tip
+        .extend(conflicts.into_iter().rev())
+        .expect("evicted are in order");
+
+    for anchor in anchors {
+        let height = anchor.0.anchor_block().height;
+        if tip.get(height).is_none() {
+            let hash = match fetch_block(client, latest_blocks, height).await? {
+                Some(hash) => hash,
+                None => continue,
+            };
+            tip = tip.insert(BlockId { height, hash });
+        }
+    }
+
+    // insert the most recent blocks at the tip to make sure we update the tip and make the update
+    // robust.
+    for (&height, &hash) in latest_blocks.iter() {
+        tip = tip.insert(BlockId { height, hash });
+    }
+
+    Ok(tip)
+}
+
+/// This performs a full scan to get an update for the [`TxGraph`] and
+/// [`KeychainTxOutIndex`](bdk_chain::keychain::KeychainTxOutIndex).
+async fn full_scan_for_index_and_graph<K: Ord + Clone + Send>(
+    client: &esplora_client::AsyncClient,
+    keychain_spks: BTreeMap<
+        K,
+        impl IntoIterator<IntoIter = impl Iterator<Item = (u32, ScriptBuf)> + Send> + Send,
+    >,
+    stop_gap: usize,
+    parallel_requests: usize,
+) -> Result<(TxGraph<ConfirmationTimeHeightAnchor>, BTreeMap<K, u32>), Error> {
+    type TxsOfSpkIndex = (u32, Vec<esplora_client::Tx>);
+    let parallel_requests = Ord::max(parallel_requests, 1);
+    let mut graph = TxGraph::<ConfirmationTimeHeightAnchor>::default();
+    let mut last_active_indexes = BTreeMap::<K, u32>::new();
+
+    for (keychain, spks) in keychain_spks {
+        let mut spks = spks.into_iter();
+        let mut last_index = Option::<u32>::None;
+        let mut last_active_index = Option::<u32>::None;
 
-        let mut txids = txids.into_iter();
         loop {
-            let handles = txids
+            let handles = spks
                 .by_ref()
                 .take(parallel_requests)
-                .filter(|&txid| graph.get_tx(txid).is_none())
-                .map(|txid| {
-                    let client = self.clone();
-                    async move { client.get_tx_status(&txid).await.map(|s| (txid, s)) }
+                .map(|(spk_index, spk)| {
+                    let client = client.clone();
+                    async move {
+                        let mut last_seen = None;
+                        let mut spk_txs = Vec::new();
+                        loop {
+                            let txs = client.scripthash_txs(&spk, last_seen).await?;
+                            let tx_count = txs.len();
+                            last_seen = txs.last().map(|tx| tx.txid);
+                            spk_txs.extend(txs);
+                            if tx_count < 25 {
+                                break Result::<_, Error>::Ok((spk_index, spk_txs));
+                            }
+                        }
+                    }
                 })
                 .collect::<FuturesOrdered<_>>();
 
@@ -297,38 +283,315 @@ impl EsploraAsyncExt for esplora_client::AsyncClient {
                 break;
             }
 
-            for (txid, status) in handles.try_collect::<Vec<(Txid, TxStatus)>>().await? {
-                if let Some(anchor) = anchor_from_status(&status) {
-                    let _ = graph.insert_anchor(txid, anchor);
+            for (index, txs) in handles.try_collect::<Vec<TxsOfSpkIndex>>().await? {
+                last_index = Some(index);
+                if !txs.is_empty() {
+                    last_active_index = Some(index);
                 }
+                for tx in txs {
+                    let _ = graph.insert_tx(tx.to_tx());
+                    if let Some(anchor) = anchor_from_status(&tx.status) {
+                        let _ = graph.insert_anchor(tx.txid, anchor);
+                    }
+
+                    let previous_outputs = tx.vin.iter().filter_map(|vin| {
+                        let prevout = vin.prevout.as_ref()?;
+                        Some((
+                            OutPoint {
+                                txid: vin.txid,
+                                vout: vin.vout,
+                            },
+                            TxOut {
+                                script_pubkey: prevout.scriptpubkey.clone(),
+                                value: Amount::from_sat(prevout.value),
+                            },
+                        ))
+                    });
+
+                    for (outpoint, txout) in previous_outputs {
+                        let _ = graph.insert_txout(outpoint, txout);
+                    }
+                }
+            }
+
+            let last_index = last_index.expect("Must be set since handles wasn't empty.");
+            let gap_limit_reached = if let Some(i) = last_active_index {
+                last_index >= i.saturating_add(stop_gap as u32)
+            } else {
+                last_index + 1 >= stop_gap as u32
+            };
+            if gap_limit_reached {
+                break;
             }
         }
 
-        for op in outpoints.into_iter() {
-            if graph.get_tx(op.txid).is_none() {
-                if let Some(tx) = self.get_tx(&op.txid).await? {
-                    let _ = graph.insert_tx(tx);
-                }
-                let status = self.get_tx_status(&op.txid).await?;
-                if let Some(anchor) = anchor_from_status(&status) {
-                    let _ = graph.insert_anchor(op.txid, anchor);
-                }
-            }
+        if let Some(last_active_index) = last_active_index {
+            last_active_indexes.insert(keychain, last_active_index);
+        }
+    }
 
-            if let Some(op_status) = self.get_output_status(&op.txid, op.vout as _).await? {
-                if let Some(txid) = op_status.txid {
-                    if graph.get_tx(txid).is_none() {
-                        if let Some(tx) = self.get_tx(&txid).await? {
-                            let _ = graph.insert_tx(tx);
-                        }
-                        let status = self.get_tx_status(&txid).await?;
-                        if let Some(anchor) = anchor_from_status(&status) {
-                            let _ = graph.insert_anchor(txid, anchor);
-                        }
+    Ok((graph, last_active_indexes))
+}
+
+async fn sync_for_index_and_graph(
+    client: &esplora_client::AsyncClient,
+    misc_spks: impl IntoIterator<IntoIter = impl Iterator<Item = ScriptBuf> + Send> + Send,
+    txids: impl IntoIterator<IntoIter = impl Iterator<Item = Txid> + Send> + Send,
+    outpoints: impl IntoIterator<IntoIter = impl Iterator<Item = OutPoint> + Send> + Send,
+    parallel_requests: usize,
+) -> Result<TxGraph<ConfirmationTimeHeightAnchor>, Error> {
+    let mut graph = full_scan_for_index_and_graph(
+        client,
+        [(
+            (),
+            misc_spks
+                .into_iter()
+                .enumerate()
+                .map(|(i, spk)| (i as u32, spk)),
+        )]
+        .into(),
+        usize::MAX,
+        parallel_requests,
+    )
+    .await
+    .map(|(g, _)| g)?;
+
+    let mut txids = txids.into_iter();
+    loop {
+        let handles = txids
+            .by_ref()
+            .take(parallel_requests)
+            .filter(|&txid| graph.get_tx(txid).is_none())
+            .map(|txid| {
+                let client = client.clone();
+                async move { client.get_tx_status(&txid).await.map(|s| (txid, s)) }
+            })
+            .collect::<FuturesOrdered<_>>();
+
+        if handles.is_empty() {
+            break;
+        }
+
+        for (txid, status) in handles.try_collect::<Vec<(Txid, TxStatus)>>().await? {
+            if let Some(anchor) = anchor_from_status(&status) {
+                let _ = graph.insert_anchor(txid, anchor);
+            }
+        }
+    }
+
+    for op in outpoints.into_iter() {
+        if graph.get_tx(op.txid).is_none() {
+            if let Some(tx) = client.get_tx(&op.txid).await? {
+                let _ = graph.insert_tx(tx);
+            }
+            let status = client.get_tx_status(&op.txid).await?;
+            if let Some(anchor) = anchor_from_status(&status) {
+                let _ = graph.insert_anchor(op.txid, anchor);
+            }
+        }
+
+        if let Some(op_status) = client.get_output_status(&op.txid, op.vout as _).await? {
+            if let Some(txid) = op_status.txid {
+                if graph.get_tx(txid).is_none() {
+                    if let Some(tx) = client.get_tx(&txid).await? {
+                        let _ = graph.insert_tx(tx);
+                    }
+                    let status = client.get_tx_status(&txid).await?;
+                    if let Some(anchor) = anchor_from_status(&status) {
+                        let _ = graph.insert_anchor(txid, anchor);
                     }
                 }
             }
         }
-        Ok(graph)
+    }
+
+    Ok(graph)
+}
+
+#[cfg(test)]
+mod test {
+    use std::{collections::BTreeSet, time::Duration};
+
+    use bdk_chain::{
+        bitcoin::{hashes::Hash, Txid},
+        local_chain::LocalChain,
+        BlockId,
+    };
+    use bdk_testenv::TestEnv;
+    use electrsd::bitcoind::bitcoincore_rpc::RpcApi;
+    use esplora_client::Builder;
+
+    use crate::async_ext::{chain_update, fetch_latest_blocks};
+
+    macro_rules! h {
+        ($index:literal) => {{
+            bdk_chain::bitcoin::hashes::Hash::hash($index.as_bytes())
+        }};
+    }
+
+    /// Ensure that update does not remove heights (from original), and all anchor heights are included.
+    #[tokio::test]
+    pub async fn test_finalize_chain_update() -> anyhow::Result<()> {
+        struct TestCase<'a> {
+            name: &'a str,
+            /// Initial blockchain height to start the env with.
+            initial_env_height: u32,
+            /// Initial checkpoint heights to start with.
+            initial_cps: &'a [u32],
+            /// The final blockchain height of the env.
+            final_env_height: u32,
+            /// The anchors to test with: `(height, txid)`. Only the height is provided as we can fetch
+            /// the blockhash from the env.
+            anchors: &'a [(u32, Txid)],
+        }
+
+        let test_cases = [
+            TestCase {
+                name: "chain_extends",
+                initial_env_height: 60,
+                initial_cps: &[59, 60],
+                final_env_height: 90,
+                anchors: &[],
+            },
+            TestCase {
+                name: "introduce_older_heights",
+                initial_env_height: 50,
+                initial_cps: &[10, 15],
+                final_env_height: 50,
+                anchors: &[(11, h!("A")), (14, h!("B"))],
+            },
+            TestCase {
+                name: "introduce_older_heights_after_chain_extends",
+                initial_env_height: 50,
+                initial_cps: &[10, 15],
+                final_env_height: 100,
+                anchors: &[(11, h!("A")), (14, h!("B"))],
+            },
+        ];
+
+        for (i, t) in test_cases.into_iter().enumerate() {
+            println!("[{}] running test case: {}", i, t.name);
+
+            let env = TestEnv::new()?;
+            let base_url = format!("http://{}", &env.electrsd.esplora_url.clone().unwrap());
+            let client = Builder::new(base_url.as_str()).build_async()?;
+
+            // set env to `initial_env_height`
+            if let Some(to_mine) = t
+                .initial_env_height
+                .checked_sub(env.make_checkpoint_tip().height())
+            {
+                env.mine_blocks(to_mine as _, None)?;
+            }
+            while client.get_height().await? < t.initial_env_height {
+                std::thread::sleep(Duration::from_millis(10));
+            }
+
+            // craft initial `local_chain`
+            let local_chain = {
+                let (mut chain, _) = LocalChain::from_genesis_hash(env.genesis_hash()?);
+                // force `chain_update_blocking` to add all checkpoints in `t.initial_cps`
+                let anchors = t
+                    .initial_cps
+                    .iter()
+                    .map(|&height| -> anyhow::Result<_> {
+                        Ok((
+                            BlockId {
+                                height,
+                                hash: env.bitcoind.client.get_block_hash(height as _)?,
+                            },
+                            Txid::all_zeros(),
+                        ))
+                    })
+                    .collect::<anyhow::Result<BTreeSet<_>>>()?;
+                let update = chain_update(
+                    &client,
+                    &fetch_latest_blocks(&client).await?,
+                    &chain.tip(),
+                    &anchors,
+                )
+                .await?;
+                chain.apply_update(update)?;
+                chain
+            };
+            println!("local chain height: {}", local_chain.tip().height());
+
+            // extend env chain
+            if let Some(to_mine) = t
+                .final_env_height
+                .checked_sub(env.make_checkpoint_tip().height())
+            {
+                env.mine_blocks(to_mine as _, None)?;
+            }
+            while client.get_height().await? < t.final_env_height {
+                std::thread::sleep(Duration::from_millis(10));
+            }
+
+            // craft update
+            let update = {
+                let anchors = t
+                    .anchors
+                    .iter()
+                    .map(|&(height, txid)| -> anyhow::Result<_> {
+                        Ok((
+                            BlockId {
+                                height,
+                                hash: env.bitcoind.client.get_block_hash(height as _)?,
+                            },
+                            txid,
+                        ))
+                    })
+                    .collect::<anyhow::Result<_>>()?;
+                chain_update(
+                    &client,
+                    &fetch_latest_blocks(&client).await?,
+                    &local_chain.tip(),
+                    &anchors,
+                )
+                .await?
+            };
+
+            // apply update
+            let mut updated_local_chain = local_chain.clone();
+            updated_local_chain.apply_update(update)?;
+            println!(
+                "updated local chain height: {}",
+                updated_local_chain.tip().height()
+            );
+
+            assert!(
+                {
+                    let initial_heights = local_chain
+                        .iter_checkpoints()
+                        .map(|cp| cp.height())
+                        .collect::<BTreeSet<_>>();
+                    let updated_heights = updated_local_chain
+                        .iter_checkpoints()
+                        .map(|cp| cp.height())
+                        .collect::<BTreeSet<_>>();
+                    updated_heights.is_superset(&initial_heights)
+                },
+                "heights from the initial chain must all be in the updated chain",
+            );
+
+            assert!(
+                {
+                    let exp_anchor_heights = t
+                        .anchors
+                        .iter()
+                        .map(|(h, _)| *h)
+                        .chain(t.initial_cps.iter().copied())
+                        .collect::<BTreeSet<_>>();
+                    let anchor_heights = updated_local_chain
+                        .iter_checkpoints()
+                        .map(|cp| cp.height())
+                        .collect::<BTreeSet<_>>();
+                    anchor_heights.is_superset(&exp_anchor_heights)
+                },
+                "anchor heights must all be in updated chain",
+            );
+        }
+
+        Ok(())
     }
 }

crates/esplora/tests/async_ext.rs

@@ -1,8 +1,9 @@
+use bdk_chain::spk_client::{FullScanRequest, SyncRequest};
 use bdk_esplora::EsploraAsyncExt;
 use electrsd::bitcoind::anyhow;
 use electrsd::bitcoind::bitcoincore_rpc::RpcApi;
 use esplora_client::{self, Builder};
-use std::collections::{BTreeMap, HashSet};
+use std::collections::{BTreeSet, HashSet};
 use std::str::FromStr;
 use std::thread::sleep;
 use std::time::Duration;
@@ -52,15 +53,31 @@ pub async fn test_update_tx_graph_without_keychain() -> anyhow::Result<()> {
         sleep(Duration::from_millis(10))
     }
 
-    let graph_update = client
-        .sync(
-            misc_spks.into_iter(),
-            vec![].into_iter(),
-            vec![].into_iter(),
-            1,
-        )
-        .await?;
+    // use a full checkpoint linked list (since this is not what we are testing)
+    let cp_tip = env.make_checkpoint_tip();
 
+    let sync_update = {
+        let request = SyncRequest::from_chain_tip(cp_tip.clone()).set_spks(misc_spks);
+        client.sync(request, 1).await?
+    };
+
+    assert!(
+        {
+            let update_cps = sync_update
+                .chain_update
+                .iter()
+                .map(|cp| cp.block_id())
+                .collect::<BTreeSet<_>>();
+            let superset_cps = cp_tip
+                .iter()
+                .map(|cp| cp.block_id())
+                .collect::<BTreeSet<_>>();
+            superset_cps.is_superset(&update_cps)
+        },
+        "update should not alter original checkpoint tip since we already started with all checkpoints",
+    );
+
+    let graph_update = sync_update.graph_update;
     // Check to see if we have the floating txouts available from our two created transactions'
     // previous outputs in order to calculate transaction fees.
     for tx in graph_update.full_txs() {
@@ -121,8 +138,6 @@ pub async fn test_async_update_tx_graph_stop_gap() -> anyhow::Result<()> {
         .enumerate()
         .map(|(i, addr)| (i as u32, addr.script_pubkey()))
         .collect();
-    let mut keychains = BTreeMap::new();
-    keychains.insert(0, spks);
 
     // Then receive coins on the 4th address.
     let txid_4th_addr = env.bitcoind.client.send_to_address(
@@ -140,14 +155,33 @@ pub async fn test_async_update_tx_graph_stop_gap() -> anyhow::Result<()> {
         sleep(Duration::from_millis(10))
     }
 
+    // use a full checkpoint linked list (since this is not what we are testing)
+    let cp_tip = env.make_checkpoint_tip();
+
     // A scan with a gap limit of 3 won't find the transaction, but a scan with a gap limit of 4
     // will.
-    let (graph_update, active_indices) = client.full_scan(keychains.clone(), 3, 1).await?;
-    assert!(graph_update.full_txs().next().is_none());
-    assert!(active_indices.is_empty());
-    let (graph_update, active_indices) = client.full_scan(keychains.clone(), 4, 1).await?;
-    assert_eq!(graph_update.full_txs().next().unwrap().txid, txid_4th_addr);
-    assert_eq!(active_indices[&0], 3);
+    let full_scan_update = {
+        let request =
+            FullScanRequest::from_chain_tip(cp_tip.clone()).set_spks_for_keychain(0, spks.clone());
+        client.full_scan(request, 3, 1).await?
+    };
+    assert!(full_scan_update.graph_update.full_txs().next().is_none());
+    assert!(full_scan_update.last_active_indices.is_empty());
+    let full_scan_update = {
+        let request =
+            FullScanRequest::from_chain_tip(cp_tip.clone()).set_spks_for_keychain(0, spks.clone());
+        client.full_scan(request, 4, 1).await?
+    };
+    assert_eq!(
+        full_scan_update
+            .graph_update
+            .full_txs()
+            .next()
+            .unwrap()
+            .txid,
+        txid_4th_addr
+    );
+    assert_eq!(full_scan_update.last_active_indices[&0], 3);
 
     // Now receive a coin on the last address.
     let txid_last_addr = env.bitcoind.client.send_to_address(
@@ -167,16 +201,32 @@ pub async fn test_async_update_tx_graph_stop_gap() -> anyhow::Result<()> {
 
     // A scan with gap limit 5 won't find the second transaction, but a scan with gap limit 6 will.
     // The last active indice won't be updated in the first case but will in the second one.
-    let (graph_update, active_indices) = client.full_scan(keychains.clone(), 5, 1).await?;
-    let txs: HashSet<_> = graph_update.full_txs().map(|tx| tx.txid).collect();
+    let full_scan_update = {
+        let request =
+            FullScanRequest::from_chain_tip(cp_tip.clone()).set_spks_for_keychain(0, spks.clone());
+        client.full_scan(request, 5, 1).await?
+    };
+    let txs: HashSet<_> = full_scan_update
+        .graph_update
+        .full_txs()
+        .map(|tx| tx.txid)
+        .collect();
     assert_eq!(txs.len(), 1);
     assert!(txs.contains(&txid_4th_addr));
-    assert_eq!(active_indices[&0], 3);
-    let (graph_update, active_indices) = client.full_scan(keychains, 6, 1).await?;
-    let txs: HashSet<_> = graph_update.full_txs().map(|tx| tx.txid).collect();
+    assert_eq!(full_scan_update.last_active_indices[&0], 3);
+    let full_scan_update = {
+        let request =
+            FullScanRequest::from_chain_tip(cp_tip.clone()).set_spks_for_keychain(0, spks.clone());
+        client.full_scan(request, 6, 1).await?
+    };
+    let txs: HashSet<_> = full_scan_update
+        .graph_update
+        .full_txs()
+        .map(|tx| tx.txid)
+        .collect();
     assert_eq!(txs.len(), 2);
     assert!(txs.contains(&txid_4th_addr) && txs.contains(&txid_last_addr));
-    assert_eq!(active_indices[&0], 9);
+    assert_eq!(full_scan_update.last_active_indices[&0], 9);
 
     Ok(())
 }

crates/esplora/tests/blocking_ext.rs

@@ -1,10 +1,9 @@
-use bdk_chain::local_chain::LocalChain;
-use bdk_chain::BlockId;
+use bdk_chain::spk_client::{FullScanRequest, SyncRequest};
 use bdk_esplora::EsploraExt;
 use electrsd::bitcoind::anyhow;
 use electrsd::bitcoind::bitcoincore_rpc::RpcApi;
 use esplora_client::{self, Builder};
-use std::collections::{BTreeMap, BTreeSet, HashSet};
+use std::collections::{BTreeSet, HashSet};
 use std::str::FromStr;
 use std::thread::sleep;
 use std::time::Duration;
@@ -12,20 +11,6 @@ use std::time::Duration;
 use bdk_chain::bitcoin::{Address, Amount, Txid};
 use bdk_testenv::TestEnv;
 
-macro_rules! h {
-    ($index:literal) => {{
-        bdk_chain::bitcoin::hashes::Hash::hash($index.as_bytes())
-    }};
-}
-
-macro_rules! local_chain {
-    [ $(($height:expr, $block_hash:expr)), * ] => {{
-        #[allow(unused_mut)]
-        bdk_chain::local_chain::LocalChain::from_blocks([$(($height, $block_hash).into()),*].into_iter().collect())
-            .expect("chain must have genesis block")
-    }};
-}
-
 #[test]
 pub fn test_update_tx_graph_without_keychain() -> anyhow::Result<()> {
     let env = TestEnv::new()?;
@@ -68,13 +53,31 @@ pub fn test_update_tx_graph_without_keychain() -> anyhow::Result<()> {
         sleep(Duration::from_millis(10))
     }
 
-    let graph_update = client.sync(
-        misc_spks.into_iter(),
-        vec![].into_iter(),
-        vec![].into_iter(),
-        1,
-    )?;
+    // use a full checkpoint linked list (since this is not what we are testing)
+    let cp_tip = env.make_checkpoint_tip();
 
+    let sync_update = {
+        let request = SyncRequest::from_chain_tip(cp_tip.clone()).set_spks(misc_spks);
+        client.sync(request, 1)?
+    };
+
+    assert!(
+        {
+            let update_cps = sync_update
+                .chain_update
+                .iter()
+                .map(|cp| cp.block_id())
+                .collect::<BTreeSet<_>>();
+            let superset_cps = cp_tip
+                .iter()
+                .map(|cp| cp.block_id())
+                .collect::<BTreeSet<_>>();
+            superset_cps.is_superset(&update_cps)
+        },
+        "update should not alter original checkpoint tip since we already started with all checkpoints",
+    );
+
+    let graph_update = sync_update.graph_update;
     // Check to see if we have the floating txouts available from our two created transactions'
     // previous outputs in order to calculate transaction fees.
     for tx in graph_update.full_txs() {
@@ -136,8 +139,6 @@ pub fn test_update_tx_graph_stop_gap() -> anyhow::Result<()> {
         .enumerate()
         .map(|(i, addr)| (i as u32, addr.script_pubkey()))
         .collect();
-    let mut keychains = BTreeMap::new();
-    keychains.insert(0, spks);
 
     // Then receive coins on the 4th address.
     let txid_4th_addr = env.bitcoind.client.send_to_address(
@@ -155,14 +156,33 @@ pub fn test_update_tx_graph_stop_gap() -> anyhow::Result<()> {
         sleep(Duration::from_millis(10))
     }
 
+    // use a full checkpoint linked list (since this is not what we are testing)
+    let cp_tip = env.make_checkpoint_tip();
+
     // A scan with a stop_gap of 3 won't find the transaction, but a scan with a gap limit of 4
     // will.
-    let (graph_update, active_indices) = client.full_scan(keychains.clone(), 3, 1)?;
-    assert!(graph_update.full_txs().next().is_none());
-    assert!(active_indices.is_empty());
-    let (graph_update, active_indices) = client.full_scan(keychains.clone(), 4, 1)?;
-    assert_eq!(graph_update.full_txs().next().unwrap().txid, txid_4th_addr);
-    assert_eq!(active_indices[&0], 3);
+    let full_scan_update = {
+        let request =
+            FullScanRequest::from_chain_tip(cp_tip.clone()).set_spks_for_keychain(0, spks.clone());
+        client.full_scan(request, 3, 1)?
+    };
+    assert!(full_scan_update.graph_update.full_txs().next().is_none());
+    assert!(full_scan_update.last_active_indices.is_empty());
+    let full_scan_update = {
+        let request =
+            FullScanRequest::from_chain_tip(cp_tip.clone()).set_spks_for_keychain(0, spks.clone());
+        client.full_scan(request, 4, 1)?
+    };
+    assert_eq!(
+        full_scan_update
+            .graph_update
+            .full_txs()
+            .next()
+            .unwrap()
+            .txid,
+        txid_4th_addr
+    );
+    assert_eq!(full_scan_update.last_active_indices[&0], 3);
 
     // Now receive a coin on the last address.
     let txid_last_addr = env.bitcoind.client.send_to_address(
@@ -182,194 +202,32 @@ pub fn test_update_tx_graph_stop_gap() -> anyhow::Result<()> {
 
     // A scan with gap limit 5 won't find the second transaction, but a scan with gap limit 6 will.
     // The last active indice won't be updated in the first case but will in the second one.
-    let (graph_update, active_indices) = client.full_scan(keychains.clone(), 5, 1)?;
-    let txs: HashSet<_> = graph_update.full_txs().map(|tx| tx.txid).collect();
+    let full_scan_update = {
+        let request =
+            FullScanRequest::from_chain_tip(cp_tip.clone()).set_spks_for_keychain(0, spks.clone());
+        client.full_scan(request, 5, 1)?
+    };
+    let txs: HashSet<_> = full_scan_update
+        .graph_update
+        .full_txs()
+        .map(|tx| tx.txid)
+        .collect();
     assert_eq!(txs.len(), 1);
     assert!(txs.contains(&txid_4th_addr));
-    assert_eq!(active_indices[&0], 3);
-    let (graph_update, active_indices) = client.full_scan(keychains, 6, 1)?;
-    let txs: HashSet<_> = graph_update.full_txs().map(|tx| tx.txid).collect();
+    assert_eq!(full_scan_update.last_active_indices[&0], 3);
+    let full_scan_update = {
+        let request =
+            FullScanRequest::from_chain_tip(cp_tip.clone()).set_spks_for_keychain(0, spks.clone());
+        client.full_scan(request, 6, 1)?
+    };
+    let txs: HashSet<_> = full_scan_update
+        .graph_update
+        .full_txs()
+        .map(|tx| tx.txid)
+        .collect();
     assert_eq!(txs.len(), 2);
     assert!(txs.contains(&txid_4th_addr) && txs.contains(&txid_last_addr));
-    assert_eq!(active_indices[&0], 9);
-
-    Ok(())
-}
-
-#[test]
-fn update_local_chain() -> anyhow::Result<()> {
-    const TIP_HEIGHT: u32 = 50;
-
-    let env = TestEnv::new()?;
-    let blocks = {
-        let bitcoind_client = &env.bitcoind.client;
-        assert_eq!(bitcoind_client.get_block_count()?, 1);
-        [
-            (0, bitcoind_client.get_block_hash(0)?),
-            (1, bitcoind_client.get_block_hash(1)?),
-        ]
-        .into_iter()
-        .chain((2..).zip(env.mine_blocks((TIP_HEIGHT - 1) as usize, None)?))
-        .collect::<BTreeMap<_, _>>()
-    };
-    // so new blocks can be seen by Electrs
-    let env = env.reset_electrsd()?;
-    let base_url = format!("http://{}", &env.electrsd.esplora_url.clone().unwrap());
-    let client = Builder::new(base_url.as_str()).build_blocking();
-
-    struct TestCase {
-        name: &'static str,
-        chain: LocalChain,
-        request_heights: &'static [u32],
-        exp_update_heights: &'static [u32],
-    }
-
-    let test_cases = [
-        TestCase {
-            name: "request_later_blocks",
-            chain: local_chain![(0, blocks[&0]), (21, blocks[&21])],
-            request_heights: &[22, 25, 28],
-            exp_update_heights: &[21, 22, 25, 28],
-        },
-        TestCase {
-            name: "request_prev_blocks",
-            chain: local_chain![(0, blocks[&0]), (1, blocks[&1]), (5, blocks[&5])],
-            request_heights: &[4],
-            exp_update_heights: &[4, 5],
-        },
-        TestCase {
-            name: "request_prev_blocks_2",
-            chain: local_chain![(0, blocks[&0]), (1, blocks[&1]), (10, blocks[&10])],
-            request_heights: &[4, 6],
-            exp_update_heights: &[4, 6, 10],
-        },
-        TestCase {
-            name: "request_later_and_prev_blocks",
-            chain: local_chain![(0, blocks[&0]), (7, blocks[&7]), (11, blocks[&11])],
-            request_heights: &[8, 9, 15],
-            exp_update_heights: &[8, 9, 11, 15],
-        },
-        TestCase {
-            name: "request_tip_only",
-            chain: local_chain![(0, blocks[&0]), (5, blocks[&5]), (49, blocks[&49])],
-            request_heights: &[TIP_HEIGHT],
-            exp_update_heights: &[49],
-        },
-        TestCase {
-            name: "request_nothing",
-            chain: local_chain![(0, blocks[&0]), (13, blocks[&13]), (23, blocks[&23])],
-            request_heights: &[],
-            exp_update_heights: &[23],
-        },
-        TestCase {
-            name: "request_nothing_during_reorg",
-            chain: local_chain![(0, blocks[&0]), (13, blocks[&13]), (23, h!("23"))],
-            request_heights: &[],
-            exp_update_heights: &[13, 23],
-        },
-        TestCase {
-            name: "request_nothing_during_reorg_2",
-            chain: local_chain![
-                (0, blocks[&0]),
-                (21, blocks[&21]),
-                (22, h!("22")),
-                (23, h!("23"))
-            ],
-            request_heights: &[],
-            exp_update_heights: &[21, 22, 23],
-        },
-        TestCase {
-            name: "request_prev_blocks_during_reorg",
-            chain: local_chain![
-                (0, blocks[&0]),
-                (21, blocks[&21]),
-                (22, h!("22")),
-                (23, h!("23"))
-            ],
-            request_heights: &[17, 20],
-            exp_update_heights: &[17, 20, 21, 22, 23],
-        },
-        TestCase {
-            name: "request_later_blocks_during_reorg",
-            chain: local_chain![
-                (0, blocks[&0]),
-                (9, blocks[&9]),
-                (22, h!("22")),
-                (23, h!("23"))
-            ],
-            request_heights: &[25, 27],
-            exp_update_heights: &[9, 22, 23, 25, 27],
-        },
-        TestCase {
-            name: "request_later_blocks_during_reorg_2",
-            chain: local_chain![(0, blocks[&0]), (9, h!("9"))],
-            request_heights: &[10],
-            exp_update_heights: &[0, 9, 10],
-        },
-        TestCase {
-            name: "request_later_and_prev_blocks_during_reorg",
-            chain: local_chain![(0, blocks[&0]), (1, blocks[&1]), (9, h!("9"))],
-            request_heights: &[8, 11],
-            exp_update_heights: &[1, 8, 9, 11],
-        },
-    ];
-
-    for (i, t) in test_cases.into_iter().enumerate() {
-        println!("Case {}: {}", i, t.name);
-        let mut chain = t.chain;
-
-        let update = client
-            .update_local_chain(chain.tip(), t.request_heights.iter().copied())
-            .map_err(|err| {
-                anyhow::format_err!("[{}:{}] `update_local_chain` failed: {}", i, t.name, err)
-            })?;
-
-        let update_blocks = update
-            .tip
-            .iter()
-            .map(|cp| cp.block_id())
-            .collect::<BTreeSet<_>>();
-
-        let exp_update_blocks = t
-            .exp_update_heights
-            .iter()
-            .map(|&height| {
-                let hash = blocks[&height];
-                BlockId { height, hash }
-            })
-            .chain(
-                // Electrs Esplora `get_block` call fetches 10 blocks which is included in the
-                // update
-                blocks
-                    .range(TIP_HEIGHT - 9..)
-                    .map(|(&height, &hash)| BlockId { height, hash }),
-            )
-            .collect::<BTreeSet<_>>();
-
-        assert_eq!(
-            update_blocks, exp_update_blocks,
-            "[{}:{}] unexpected update",
-            i, t.name
-        );
-
-        let _ = chain
-            .apply_update(update)
-            .unwrap_or_else(|err| panic!("[{}:{}] update failed to apply: {}", i, t.name, err));
-
-        // all requested heights must exist in the final chain
-        for height in t.request_heights {
-            let exp_blockhash = blocks.get(height).expect("block must exist in bitcoind");
-            assert_eq!(
-                chain.get(*height).map(|cp| cp.hash()),
-                Some(*exp_blockhash),
-                "[{}:{}] block {}:{} must exist in final chain",
-                i,
-                t.name,
-                height,
-                exp_blockhash
-            );
-        }
-    }
+    assert_eq!(full_scan_update.last_active_indices[&0], 9);
 
     Ok(())
 }

crates/file_store/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "bdk_file_store"
-version = "0.9.0"
+version = "0.10.0"
 edition = "2021"
 license = "MIT OR Apache-2.0"
 repository = "https://github.com/bitcoindevkit/bdk"
@@ -11,7 +11,9 @@ authors = ["Bitcoin Dev Kit Developers"]
 readme = "README.md"
 
 [dependencies]
-bdk_chain = { path = "../chain", version = "0.12.0", features = [ "serde", "miniscript" ] }
+anyhow = { version = "1", default-features = false }
+bdk_chain = { path = "../chain", version = "0.13.0", features = [ "serde", "miniscript" ] }
+bdk_persist = { path = "../persist", version = "0.1.0"}
 bincode = { version = "1" }
 serde = { version = "1", features = ["derive"] }
 

crates/file_store/README.md

@@ -1,10 +1,10 @@
 # BDK File Store
 
 This is a simple append-only flat file implementation of
-[`Persist`](`bdk_chain::Persist`).
+[`PersistBackend`](bdk_persist::PersistBackend).
 
-The main structure is [`Store`](`crate::Store`), which can be used with [`bdk`]'s
+The main structure is [`Store`](crate::Store), which can be used with [`bdk`]'s
 `Wallet` to persist wallet data into a flat file.
 
 [`bdk`]: https://docs.rs/bdk/latest
-[`bdk_chain`]: https://docs.rs/bdk_chain/latest
+[`bdk_persist`]: https://docs.rs/bdk_persist/latest

crates/file_store/src/store.rs

@@ -1,21 +1,22 @@
+use crate::{bincode_options, EntryIter, FileError, IterError};
+use anyhow::anyhow;
+use bdk_chain::Append;
+use bdk_persist::PersistBackend;
+use bincode::Options;
 use std::{
-    fmt::Debug,
+    fmt::{self, Debug},
     fs::{File, OpenOptions},
     io::{self, Read, Seek, Write},
     marker::PhantomData,
     path::Path,
 };
 
-use bdk_chain::{Append, PersistBackend};
-use bincode::Options;
-
-use crate::{bincode_options, EntryIter, FileError, IterError};
-
 /// Persists an append-only list of changesets (`C`) to a single file.
-///
-/// The changesets are the results of altering a tracker implementation (`T`).
 #[derive(Debug)]
-pub struct Store<C> {
+pub struct Store<C>
+where
+    C: Sync + Send,
+{
     magic_len: usize,
     db_file: File,
     marker: PhantomData<C>,
@@ -23,24 +24,30 @@ pub struct Store<C> {
 
 impl<C> PersistBackend<C> for Store<C>
 where
-    C: Append + serde::Serialize + serde::de::DeserializeOwned,
+    C: Append
+        + serde::Serialize
+        + serde::de::DeserializeOwned
+        + core::marker::Send
+        + core::marker::Sync,
 {
-    type WriteError = std::io::Error;
-
-    type LoadError = IterError;
-
-    fn write_changes(&mut self, changeset: &C) -> Result<(), Self::WriteError> {
+    fn write_changes(&mut self, changeset: &C) -> anyhow::Result<()> {
         self.append_changeset(changeset)
+            .map_err(|e| anyhow!(e).context("failed to write changes to persistence backend"))
     }
 
-    fn load_from_persistence(&mut self) -> Result<Option<C>, Self::LoadError> {
-        self.aggregate_changesets().map_err(|e| e.iter_error)
+    fn load_from_persistence(&mut self) -> anyhow::Result<Option<C>> {
+        self.aggregate_changesets()
+            .map_err(|e| anyhow!(e.iter_error).context("error loading from persistence backend"))
     }
 }
 
 impl<C> Store<C>
 where
-    C: Append + serde::Serialize + serde::de::DeserializeOwned,
+    C: Append
+        + serde::Serialize
+        + serde::de::DeserializeOwned
+        + core::marker::Send
+        + core::marker::Sync,
 {
     /// Create a new [`Store`] file in write-only mode; error if the file exists.
     ///
@@ -144,7 +151,7 @@ where
     ///
     /// You should usually check the error. In many applications, it may make sense to do a full
     /// wallet scan with a stop-gap after getting an error, since it is likely that one of the
-    /// changesets it was unable to read changed the derivation indices of the tracker.
+    /// changesets was unable to read changes of the derivation indices of a keychain.
     ///
     /// **WARNING**: This method changes the write position of the underlying file. The next
     /// changeset will be written over the erroring entry (or the end of the file if none existed).
@@ -182,7 +189,7 @@ where
         bincode_options()
             .serialize_into(&mut self.db_file, changeset)
             .map_err(|e| match *e {
-                bincode::ErrorKind::Io(inner) => inner,
+                bincode::ErrorKind::Io(error) => error,
                 unexpected_err => panic!("unexpected bincode error: {}", unexpected_err),
             })?;
 
@@ -212,7 +219,7 @@ impl<C> std::fmt::Display for AggregateChangesetsError<C> {
     }
 }
 
-impl<C: std::fmt::Debug> std::error::Error for AggregateChangesetsError<C> {}
+impl<C: fmt::Debug> std::error::Error for AggregateChangesetsError<C> {}
 
 #[cfg(test)]
 mod test {
@@ -232,9 +239,6 @@ mod test {
 
     type TestChangeSet = BTreeSet<String>;
 
-    #[derive(Debug)]
-    struct TestTracker;
-
     /// Check behavior of [`Store::create_new`] and [`Store::open`].
     #[test]
     fn construct_store() {

crates/hwi/src/lib.rs

@@ -6,7 +6,6 @@
 //! # use bdk::bitcoin::Network;
 //! # use bdk::signer::SignerOrdering;
 //! # use bdk_hwi::HWISigner;
-//! # use bdk::wallet::AddressIndex::New;
 //! # use bdk::{KeychainKind, SignOptions, Wallet};
 //! # use hwi::HWIClient;
 //! # use std::sync::Arc;

crates/persist/Cargo.toml

@@ -0,0 +1,19 @@
+[package]
+name = "bdk_persist"
+homepage = "https://bitcoindevkit.org"
+version = "0.1.0"
+repository = "https://github.com/bitcoindevkit/bdk"
+documentation = "https://docs.rs/bdk_persist"
+description = "Types that define data persistence of a BDK wallet"
+keywords = ["bitcoin", "wallet", "persistence", "database"]
+readme = "README.md"
+license = "MIT OR Apache-2.0"
+authors = ["Bitcoin Dev Kit Developers"]
+edition = "2021"
+rust-version = "1.63"
+
+[dependencies]
+anyhow = { version = "1", default-features = false }
+bdk_chain = { path = "../chain", version = "0.13.0", default-features = false }
+
+

crates/persist/README.md

@@ -0,0 +1,3 @@
+# BDK Persist
+
+This crate is home to the [`PersistBackend`](crate::PersistBackend) trait which defines the behavior of a database to perform the task of persisting changes made to BDK data structures. The [`Persist`](crate::Persist) type provides a convenient wrapper around a `PersistBackend` that allows staging changes before committing them.

crates/persist/src/lib.rs

@@ -0,0 +1,5 @@
+#![doc = include_str!("../README.md")]
+#![no_std]
+#![warn(missing_docs)]
+mod persist;
+pub use persist::*;

crates/persist/src/persist.rs

@@ -1,26 +1,33 @@
-use core::convert::Infallible;
+extern crate alloc;
+use alloc::boxed::Box;
+use bdk_chain::Append;
+use core::fmt;
 
-use crate::Append;
-
-/// `Persist` wraps a [`PersistBackend`] (`B`) to create a convenient staging area for changes (`C`)
+/// `Persist` wraps a [`PersistBackend`] to create a convenient staging area for changes (`C`)
 /// before they are persisted.
 ///
 /// Not all changes to the in-memory representation needs to be written to disk right away, so
 /// [`Persist::stage`] can be used to *stage* changes first and then [`Persist::commit`] can be used
 /// to write changes to disk.
-#[derive(Debug)]
-pub struct Persist<B, C> {
-    backend: B,
+pub struct Persist<C> {
+    backend: Box<dyn PersistBackend<C> + Send + Sync>,
     stage: C,
 }
 
-impl<B, C> Persist<B, C>
+impl<C: fmt::Debug> fmt::Debug for Persist<C> {
+    fn fmt(&self, fmt: &mut core::fmt::Formatter<'_>) -> Result<(), core::fmt::Error> {
+        write!(fmt, "{:?}", self.stage)?;
+        Ok(())
+    }
+}
+
+impl<C> Persist<C>
 where
-    B: PersistBackend<C>,
     C: Default + Append,
 {
     /// Create a new [`Persist`] from [`PersistBackend`].
-    pub fn new(backend: B) -> Self {
+    pub fn new(backend: impl PersistBackend<C> + Send + Sync + 'static) -> Self {
+        let backend = Box::new(backend);
         Self {
             backend,
             stage: Default::default(),
@@ -46,7 +53,7 @@ where
     /// # Error
     ///
     /// Returns a backend-defined error if this fails.
-    pub fn commit(&mut self) -> Result<Option<C>, B::WriteError> {
+    pub fn commit(&mut self) -> anyhow::Result<Option<C>> {
         if self.stage.is_empty() {
             return Ok(None);
         }
@@ -63,7 +70,7 @@ where
     ///
     /// [`stage`]: Self::stage
     /// [`commit`]: Self::commit
-    pub fn stage_and_commit(&mut self, changeset: C) -> Result<Option<C>, B::WriteError> {
+    pub fn stage_and_commit(&mut self, changeset: C) -> anyhow::Result<Option<C>> {
         self.stage(changeset);
         self.commit()
     }
@@ -74,12 +81,6 @@ where
 /// `C` represents the changeset; a datatype that records changes made to in-memory data structures
 /// that are to be persisted, or retrieved from persistence.
 pub trait PersistBackend<C> {
-    /// The error the backend returns when it fails to write.
-    type WriteError: core::fmt::Debug;
-
-    /// The error the backend returns when it fails to load changesets `C`.
-    type LoadError: core::fmt::Debug;
-
     /// Writes a changeset to the persistence backend.
     ///
     /// It is up to the backend what it does with this. It could store every changeset in a list or
@@ -88,22 +89,18 @@ pub trait PersistBackend<C> {
     /// changesets had been applied sequentially.
     ///
     /// [`load_from_persistence`]: Self::load_from_persistence
-    fn write_changes(&mut self, changeset: &C) -> Result<(), Self::WriteError>;
+    fn write_changes(&mut self, changeset: &C) -> anyhow::Result<()>;
 
     /// Return the aggregate changeset `C` from persistence.
-    fn load_from_persistence(&mut self) -> Result<Option<C>, Self::LoadError>;
+    fn load_from_persistence(&mut self) -> anyhow::Result<Option<C>>;
 }
 
 impl<C> PersistBackend<C> for () {
-    type WriteError = Infallible;
-
-    type LoadError = Infallible;
-
-    fn write_changes(&mut self, _changeset: &C) -> Result<(), Self::WriteError> {
+    fn write_changes(&mut self, _changeset: &C) -> anyhow::Result<()> {
         Ok(())
     }
 
-    fn load_from_persistence(&mut self) -> Result<Option<C>, Self::LoadError> {
+    fn load_from_persistence(&mut self) -> anyhow::Result<Option<C>> {
         Ok(None)
     }
 }

crates/testenv/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "bdk_testenv"
-version = "0.2.0"
+version = "0.3.0"
 edition = "2021"
 rust-version = "1.63"
 homepage = "https://bitcoindevkit.org"
@@ -14,7 +14,7 @@ readme = "README.md"
 
 [dependencies]
 bitcoincore-rpc = { version = "0.18" }
-bdk_chain = { path = "../chain", version = "0.12", default-features = false }
+bdk_chain = { path = "../chain", version = "0.13", default-features = false }
 electrsd = { version= "0.27.1", features = ["bitcoind_25_0", "esplora_a33e97e1", "legacy"] }
 anyhow = { version = "1" }
 

crates/testenv/src/lib.rs

@@ -1,7 +1,11 @@
-use bdk_chain::bitcoin::{
-    address::NetworkChecked, block::Header, hash_types::TxMerkleNode, hashes::Hash,
-    secp256k1::rand::random, transaction, Address, Amount, Block, BlockHash, CompactTarget,
-    ScriptBuf, ScriptHash, Transaction, TxIn, TxOut, Txid,
+use bdk_chain::{
+    bitcoin::{
+        address::NetworkChecked, block::Header, hash_types::TxMerkleNode, hashes::Hash,
+        secp256k1::rand::random, transaction, Address, Amount, Block, BlockHash, CompactTarget,
+        ScriptBuf, ScriptHash, Transaction, TxIn, TxOut, Txid,
+    },
+    local_chain::CheckPoint,
+    BlockId,
 };
 use bitcoincore_rpc::{
     bitcoincore_rpc_json::{GetBlockTemplateModes, GetBlockTemplateRules},
@@ -234,6 +238,24 @@ impl TestEnv {
             .send_to_address(address, amount, None, None, None, None, None, None)?;
         Ok(txid)
     }
+
+    /// Create a checkpoint linked list of all the blocks in the chain.
+    pub fn make_checkpoint_tip(&self) -> CheckPoint {
+        CheckPoint::from_block_ids((0_u32..).map_while(|height| {
+            self.bitcoind
+                .client
+                .get_block_hash(height as u64)
+                .ok()
+                .map(|hash| BlockId { height, hash })
+        }))
+        .expect("must craft tip")
+    }
+
+    /// Get the genesis hash of the blockchain.
+    pub fn genesis_hash(&self) -> anyhow::Result<BlockHash> {
+        let hash = self.bitcoind.client.get_block_hash(0)?;
+        Ok(hash)
+    }
 }
 
 #[cfg(test)]

example-crates/example_bitcoind_rpc_polling/src/main.rs

@@ -188,10 +188,7 @@ fn main() -> anyhow::Result<()> {
                 let mut db = db.lock().unwrap();
 
                 let chain_changeset = chain
-                    .apply_update(local_chain::Update {
-                        tip: emission.checkpoint,
-                        introduce_older_blocks: false,
-                    })
+                    .apply_update(emission.checkpoint)
                     .expect("must always apply as we receive blocks in order from emitter");
                 let graph_changeset = graph.apply_block_relevant(&emission.block, height);
                 db.stage((chain_changeset, graph_changeset));
@@ -301,12 +298,8 @@ fn main() -> anyhow::Result<()> {
                 let changeset = match emission {
                     Emission::Block(block_emission) => {
                         let height = block_emission.block_height();
-                        let chain_update = local_chain::Update {
-                            tip: block_emission.checkpoint,
-                            introduce_older_blocks: false,
-                        };
                         let chain_changeset = chain
-                            .apply_update(chain_update)
+                            .apply_update(block_emission.checkpoint)
                             .expect("must always apply as we receive blocks in order from emitter");
                         let graph_changeset =
                             graph.apply_block_relevant(&block_emission.block, height);

example-crates/example_cli/Cargo.toml

@@ -7,6 +7,7 @@ edition = "2021"
 
 [dependencies]
 bdk_chain = { path = "../../crates/chain", features = ["serde", "miniscript"]}
+bdk_persist = { path = "../../crates/persist" }
 bdk_file_store = { path = "../../crates/file_store" }
 bdk_tmp_plan = { path = "../../nursery/tmp_plan" }
 bdk_coin_select = { path = "../../nursery/coin_select" }

example-crates/example_cli/src/lib.rs

@@ -19,9 +19,10 @@ use bdk_chain::{
         descriptor::{DescriptorSecretKey, KeyMap},
         Descriptor, DescriptorPublicKey,
     },
-    Anchor, Append, ChainOracle, DescriptorExt, FullTxOut, Persist, PersistBackend,
+    Anchor, Append, ChainOracle, DescriptorExt, FullTxOut,
 };
 pub use bdk_file_store;
+use bdk_persist::{Persist, PersistBackend};
 pub use clap;
 
 use clap::{Parser, Subcommand};
@@ -31,7 +32,6 @@ pub type KeychainChangeSet<A> = (
     local_chain::ChangeSet,
     indexed_tx_graph::ChangeSet<A, keychain::ChangeSet<Keychain>>,
 );
-pub type Database<C> = Persist<Store<C>, C>;
 
 #[derive(Parser)]
 #[clap(author, version, about, long_about = None)]
@@ -440,7 +440,7 @@ pub fn planned_utxos<A: Anchor, O: ChainOracle, K: Clone + bdk_tmp_plan::CanDeri
 
 pub fn handle_commands<CS: clap::Subcommand, S: clap::Args, A: Anchor, O: ChainOracle, C>(
     graph: &Mutex<KeychainTxGraph<A>>,
-    db: &Mutex<Database<C>>,
+    db: &Mutex<Persist<C>>,
     chain: &Mutex<O>,
     keymap: &BTreeMap<DescriptorPublicKey, DescriptorSecretKey>,
     network: Network,
@@ -667,7 +667,7 @@ pub struct Init<CS: clap::Subcommand, S: clap::Args, C> {
     /// Keychain-txout index.
     pub index: KeychainTxOutIndex<Keychain>,
     /// Persistence backend.
-    pub db: Mutex<Database<C>>,
+    pub db: Mutex<Persist<C>>,
     /// Initial changeset.
     pub init_changeset: C,
 }
@@ -679,7 +679,13 @@ pub fn init<CS: clap::Subcommand, S: clap::Args, C>(
     db_default_path: &str,
 ) -> anyhow::Result<Init<CS, S, C>>
 where
-    C: Default + Append + Serialize + DeserializeOwned,
+    C: Default
+        + Append
+        + Serialize
+        + DeserializeOwned
+        + core::marker::Send
+        + core::marker::Sync
+        + 'static,
 {
     if std::env::var("BDK_DB_PATH").is_err() {
         std::env::set_var("BDK_DB_PATH", db_default_path);
@@ -715,7 +721,7 @@ where
         args,
         keymap,
         index,
-        db: Mutex::new(Database::new(db_backend)),
+        db: Mutex::new(Persist::new(db_backend)),
         init_changeset,
     })
 }

example-crates/example_electrum/src/main.rs

@@ -210,8 +210,8 @@ fn main() -> anyhow::Result<()> {
             if all_spks {
                 let all_spks = graph
                     .index
-                    .revealed_spks()
-                    .map(|(k, i, spk)| (k, i, spk.to_owned()))
+                    .revealed_spks(..)
+                    .map(|(k, i, spk)| (k.to_owned(), i, spk.to_owned()))
                     .collect::<Vec<_>>();
                 spks = Box::new(spks.chain(all_spks.into_iter().map(|(k, i, spk)| {
                     eprintln!("scanning {}:{}", k, i);

example-crates/example_esplora/src/main.rs

@@ -1,14 +1,15 @@
 use std::{
-    collections::{BTreeMap, BTreeSet},
+    collections::BTreeSet,
     io::{self, Write},
     sync::Mutex,
 };
 
 use bdk_chain::{
-    bitcoin::{constants::genesis_block, Address, Network, OutPoint, ScriptBuf, Txid},
+    bitcoin::{constants::genesis_block, Address, Network, Txid},
     indexed_tx_graph::{self, IndexedTxGraph},
     keychain,
     local_chain::{self, LocalChain},
+    spk_client::{FullScanRequest, SyncRequest},
     Append, ConfirmationTimeHeightAnchor,
 };
 
@@ -60,6 +61,7 @@ enum EsploraCommands {
         esplora_args: EsploraArgs,
     },
 }
+
 impl EsploraCommands {
     fn esplora_args(&self) -> EsploraArgs {
         match self {
@@ -149,63 +151,66 @@ fn main() -> anyhow::Result<()> {
     };
 
     let client = esplora_cmd.esplora_args().client(args.network)?;
-    // Prepare the `IndexedTxGraph` update based on whether we are scanning or syncing.
+    // Prepare the `IndexedTxGraph` and `LocalChain` updates based on whether we are scanning or
+    // syncing.
+    //
     // Scanning: We are iterating through spks of all keychains and scanning for transactions for
     //   each spk. We start with the lowest derivation index spk and stop scanning after `stop_gap`
     //   number of consecutive spks have no transaction history. A Scan is done in situations of
     //   wallet restoration. It is a special case. Applications should use "sync" style updates
     //   after an initial scan.
+    //
     // Syncing: We only check for specified spks, utxos and txids to update their confirmation
     //   status or fetch missing transactions.
-    let indexed_tx_graph_changeset = match &esplora_cmd {
+    let (local_chain_changeset, indexed_tx_graph_changeset) = match &esplora_cmd {
         EsploraCommands::Scan {
             stop_gap,
             scan_options,
             ..
         } => {
-            let keychain_spks = graph
-                .lock()
-                .expect("mutex must not be poisoned")
-                .index
-                .all_unbounded_spk_iters()
-                .into_iter()
-                // This `map` is purely for logging.
-                .map(|(keychain, iter)| {
-                    let mut first = true;
-                    let spk_iter = iter.inspect(move |(i, _)| {
-                        if first {
-                            eprint!("\nscanning {}: ", keychain);
-                            first = false;
+            let request = {
+                let chain_tip = chain.lock().expect("mutex must not be poisoned").tip();
+                let indexed_graph = &*graph.lock().expect("mutex must not be poisoned");
+                FullScanRequest::from_keychain_txout_index(chain_tip, &indexed_graph.index)
+                    .inspect_spks_for_all_keychains({
+                        let mut once = BTreeSet::<Keychain>::new();
+                        move |keychain, spk_i, _| {
+                            if once.insert(keychain) {
+                                eprint!("\nscanning {}: ", keychain);
+                            }
+                            eprint!("{} ", spk_i);
+                            // Flush early to ensure we print at every iteration.
+                            let _ = io::stderr().flush();
                         }
-                        eprint!("{} ", i);
-                        // Flush early to ensure we print at every iteration.
-                        let _ = io::stderr().flush();
-                    });
-                    (keychain, spk_iter)
-                })
-                .collect::<BTreeMap<_, _>>();
+                    })
+            };
 
             // The client scans keychain spks for transaction histories, stopping after `stop_gap`
             // is reached. It returns a `TxGraph` update (`graph_update`) and a structure that
             // represents the last active spk derivation indices of keychains
             // (`keychain_indices_update`).
-            let (mut graph_update, last_active_indices) = client
-                .full_scan(keychain_spks, *stop_gap, scan_options.parallel_requests)
+            let mut update = client
+                .full_scan(request, *stop_gap, scan_options.parallel_requests)
                 .context("scanning for transactions")?;
 
             // We want to keep track of the latest time a transaction was seen unconfirmed.
             let now = std::time::UNIX_EPOCH.elapsed().unwrap().as_secs();
-            let _ = graph_update.update_last_seen_unconfirmed(now);
+            let _ = update.graph_update.update_last_seen_unconfirmed(now);
 
             let mut graph = graph.lock().expect("mutex must not be poisoned");
+            let mut chain = chain.lock().expect("mutex must not be poisoned");
             // Because we did a stop gap based scan we are likely to have some updates to our
             // deriviation indices. Usually before a scan you are on a fresh wallet with no
             // addresses derived so we need to derive up to last active addresses the scan found
             // before adding the transactions.
-            let (_, index_changeset) = graph.index.reveal_to_target_multi(&last_active_indices);
-            let mut indexed_tx_graph_changeset = graph.apply_update(graph_update);
-            indexed_tx_graph_changeset.append(index_changeset.into());
-            indexed_tx_graph_changeset
+            (chain.apply_update(update.chain_update)?, {
+                let (_, index_changeset) = graph
+                    .index
+                    .reveal_to_target_multi(&update.last_active_indices);
+                let mut indexed_tx_graph_changeset = graph.apply_update(update.graph_update);
+                indexed_tx_graph_changeset.append(index_changeset.into());
+                indexed_tx_graph_changeset
+            })
         }
         EsploraCommands::Sync {
             mut unused_spks,
@@ -226,30 +231,28 @@ fn main() -> anyhow::Result<()> {
                 unused_spks = false;
             }
 
+            let local_tip = chain.lock().expect("mutex must not be poisoned").tip();
             // Spks, outpoints and txids we want updates on will be accumulated here.
-            let mut spks: Box<dyn Iterator<Item = ScriptBuf>> = Box::new(core::iter::empty());
-            let mut outpoints: Box<dyn Iterator<Item = OutPoint>> = Box::new(core::iter::empty());
-            let mut txids: Box<dyn Iterator<Item = Txid>> = Box::new(core::iter::empty());
+            let mut request = SyncRequest::from_chain_tip(local_tip.clone());
 
             // Get a short lock on the structures to get spks, utxos, and txs that we are interested
             // in.
             {
                 let graph = graph.lock().unwrap();
                 let chain = chain.lock().unwrap();
-                let chain_tip = chain.tip().block_id();
 
                 if *all_spks {
                     let all_spks = graph
                         .index
-                        .revealed_spks()
-                        .map(|(k, i, spk)| (k, i, spk.to_owned()))
+                        .revealed_spks(..)
+                        .map(|(k, i, spk)| (k.to_owned(), i, spk.to_owned()))
                         .collect::<Vec<_>>();
-                    spks = Box::new(spks.chain(all_spks.into_iter().map(|(k, i, spk)| {
-                        eprintln!("scanning {}:{}", k, i);
+                    request = request.chain_spks(all_spks.into_iter().map(|(k, i, spk)| {
+                        eprint!("scanning {}:{}", k, i);
                         // Flush early to ensure we print at every iteration.
                         let _ = io::stderr().flush();
                         spk
-                    })));
+                    }));
                 }
                 if unused_spks {
                     let unused_spks = graph
@@ -257,17 +260,18 @@ fn main() -> anyhow::Result<()> {
                         .unused_spks()
                         .map(|(k, i, spk)| (k, i, spk.to_owned()))
                         .collect::<Vec<_>>();
-                    spks = Box::new(spks.chain(unused_spks.into_iter().map(|(k, i, spk)| {
-                        eprintln!(
-                            "Checking if address {} {}:{} has been used",
-                            Address::from_script(&spk, args.network).unwrap(),
-                            k,
-                            i,
-                        );
-                        // Flush early to ensure we print at every iteration.
-                        let _ = io::stderr().flush();
-                        spk
-                    })));
+                    request =
+                        request.chain_spks(unused_spks.into_iter().map(move |(k, i, spk)| {
+                            eprint!(
+                                "Checking if address {} {}:{} has been used",
+                                Address::from_script(&spk, args.network).unwrap(),
+                                k,
+                                i,
+                            );
+                            // Flush early to ensure we print at every iteration.
+                            let _ = io::stderr().flush();
+                            spk
+                        }));
                 }
                 if utxos {
                     // We want to search for whether the UTXO is spent, and spent by which
@@ -276,14 +280,14 @@ fn main() -> anyhow::Result<()> {
                     let init_outpoints = graph.index.outpoints().iter().cloned();
                     let utxos = graph
                         .graph()
-                        .filter_chain_unspents(&*chain, chain_tip, init_outpoints)
+                        .filter_chain_unspents(&*chain, local_tip.block_id(), init_outpoints)
                         .map(|(_, utxo)| utxo)
                         .collect::<Vec<_>>();
-                    outpoints = Box::new(
+                    request = request.chain_outpoints(
                         utxos
                             .into_iter()
                             .inspect(|utxo| {
-                                eprintln!(
+                                eprint!(
                                     "Checking if outpoint {} (value: {}) has been spent",
                                     utxo.outpoint, utxo.txout.value
                                 );
@@ -299,60 +303,61 @@ fn main() -> anyhow::Result<()> {
                     // `EsploraExt::update_tx_graph_without_keychain`.
                     let unconfirmed_txids = graph
                         .graph()
-                        .list_chain_txs(&*chain, chain_tip)
+                        .list_chain_txs(&*chain, local_tip.block_id())
                         .filter(|canonical_tx| !canonical_tx.chain_position.is_confirmed())
                         .map(|canonical_tx| canonical_tx.tx_node.txid)
                         .collect::<Vec<Txid>>();
-                    txids = Box::new(unconfirmed_txids.into_iter().inspect(|txid| {
-                        eprintln!("Checking if {} is confirmed yet", txid);
+                    request = request.chain_txids(unconfirmed_txids.into_iter().inspect(|txid| {
+                        eprint!("Checking if {} is confirmed yet", txid);
                         // Flush early to ensure we print at every iteration.
                         let _ = io::stderr().flush();
                     }));
                 }
             }
 
-            let mut graph_update =
-                client.sync(spks, txids, outpoints, scan_options.parallel_requests)?;
+            let total_spks = request.spks.len();
+            let total_txids = request.txids.len();
+            let total_ops = request.outpoints.len();
+            request = request
+                .inspect_spks({
+                    let mut visited = 0;
+                    move |_| {
+                        visited += 1;
+                        eprintln!(" [ {:>6.2}% ]", (visited * 100) as f32 / total_spks as f32)
+                    }
+                })
+                .inspect_txids({
+                    let mut visited = 0;
+                    move |_| {
+                        visited += 1;
+                        eprintln!(" [ {:>6.2}% ]", (visited * 100) as f32 / total_txids as f32)
+                    }
+                })
+                .inspect_outpoints({
+                    let mut visited = 0;
+                    move |_| {
+                        visited += 1;
+                        eprintln!(" [ {:>6.2}% ]", (visited * 100) as f32 / total_ops as f32)
+                    }
+                });
+            let mut update = client.sync(request, scan_options.parallel_requests)?;
 
             // Update last seen unconfirmed
             let now = std::time::UNIX_EPOCH.elapsed().unwrap().as_secs();
-            let _ = graph_update.update_last_seen_unconfirmed(now);
+            let _ = update.graph_update.update_last_seen_unconfirmed(now);
 
-            graph.lock().unwrap().apply_update(graph_update)
+            (
+                chain.lock().unwrap().apply_update(update.chain_update)?,
+                graph.lock().unwrap().apply_update(update.graph_update),
+            )
         }
     };
 
     println!();
 
-    // Now that we're done updating the `IndexedTxGraph`, it's time to update the `LocalChain`! We
-    // want the `LocalChain` to have data about all the anchors in the `TxGraph` - for this reason,
-    // we want retrieve the blocks at the heights of the newly added anchors that are missing from
-    // our view of the chain.
-    let (missing_block_heights, tip) = {
-        let chain = &*chain.lock().unwrap();
-        let missing_block_heights = indexed_tx_graph_changeset
-            .graph
-            .missing_heights_from(chain)
-            .collect::<BTreeSet<_>>();
-        let tip = chain.tip();
-        (missing_block_heights, tip)
-    };
-
-    println!("prev tip: {}", tip.height());
-    println!("missing block heights: {:?}", missing_block_heights);
-
-    // Here, we actually fetch the missing blocks and create a `local_chain::Update`.
-    let chain_changeset = {
-        let chain_update = client
-            .update_local_chain(tip, missing_block_heights)
-            .context("scanning for blocks")?;
-        println!("new tip: {}", chain_update.tip.height());
-        chain.lock().unwrap().apply_update(chain_update)?
-    };
-
     // We persist the changes
     let mut db = db.lock().unwrap();
-    db.stage((chain_changeset, indexed_tx_graph_changeset));
+    db.stage((local_chain_changeset, indexed_tx_graph_changeset));
     db.commit()?;
     Ok(())
 }

example-crates/wallet_electrum/src/main.rs

@@ -8,8 +8,8 @@ use std::str::FromStr;
 
 use bdk::bitcoin::Address;
 use bdk::wallet::Update;
-use bdk::SignOptions;
 use bdk::{bitcoin::Network, Wallet};
+use bdk::{KeychainKind, SignOptions};
 use bdk_electrum::{
     electrum_client::{self, ElectrumApi},
     ElectrumExt, ElectrumUpdate,
@@ -29,7 +29,7 @@ fn main() -> Result<(), anyhow::Error> {
         Network::Testnet,
     )?;
 
-    let address = wallet.try_get_address(bdk::wallet::AddressIndex::New)?;
+    let address = wallet.next_unused_address(KeychainKind::External)?;
     println!("Generated Address: {}", address);
 
     let balance = wallet.get_balance();

example-crates/wallet_esplora_async/src/main.rs

@@ -1,9 +1,8 @@
-use std::{io::Write, str::FromStr};
+use std::{collections::BTreeSet, io::Write, str::FromStr};
 
 use bdk::{
-    bitcoin::{Address, Network},
-    wallet::{AddressIndex, Update},
-    SignOptions, Wallet,
+    bitcoin::{Address, Network, Script},
+    KeychainKind, SignOptions, Wallet,
 };
 use bdk_esplora::{esplora_client, EsploraAsyncExt};
 use bdk_file_store::Store;
@@ -27,7 +26,7 @@ async fn main() -> Result<(), anyhow::Error> {
         Network::Testnet,
     )?;
 
-    let address = wallet.try_get_address(AddressIndex::New)?;
+    let address = wallet.next_unused_address(KeychainKind::External)?;
     println!("Generated Address: {}", address);
 
     let balance = wallet.get_balance();
@@ -37,35 +36,44 @@ async fn main() -> Result<(), anyhow::Error> {
     let client =
         esplora_client::Builder::new("https://blockstream.info/testnet/api").build_async()?;
 
-    let prev_tip = wallet.latest_checkpoint();
-    let keychain_spks = wallet
-        .all_unbounded_spk_iters()
-        .into_iter()
-        .map(|(k, k_spks)| {
-            let mut once = Some(());
-            let mut stdout = std::io::stdout();
-            let k_spks = k_spks
-                .inspect(move |(spk_i, _)| match once.take() {
-                    Some(_) => print!("\nScanning keychain [{:?}]", k),
-                    None => print!(" {:<3}", spk_i),
-                })
-                .inspect(move |_| stdout.flush().expect("must flush"));
-            (k, k_spks)
+    fn generate_inspect(kind: KeychainKind) -> impl FnMut(u32, &Script) + Send + Sync + 'static {
+        let mut once = Some(());
+        let mut stdout = std::io::stdout();
+        move |spk_i, _| {
+            match once.take() {
+                Some(_) => print!("\nScanning keychain [{:?}]", kind),
+                None => print!(" {:<3}", spk_i),
+            };
+            stdout.flush().expect("must flush");
+        }
+    }
+    let request = wallet
+        .start_full_scan()
+        .inspect_spks_for_all_keychains({
+            let mut once = BTreeSet::<KeychainKind>::new();
+            move |keychain, spk_i, _| {
+                match once.insert(keychain) {
+                    true => print!("\nScanning keychain [{:?}]", keychain),
+                    false => print!(" {:<3}", spk_i),
+                }
+                std::io::stdout().flush().expect("must flush")
+            }
         })
-        .collect();
-    let (mut update_graph, last_active_indices) = client
-        .full_scan(keychain_spks, STOP_GAP, PARALLEL_REQUESTS)
-        .await?;
+        .inspect_spks_for_keychain(
+            KeychainKind::External,
+            generate_inspect(KeychainKind::External),
+        )
+        .inspect_spks_for_keychain(
+            KeychainKind::Internal,
+            generate_inspect(KeychainKind::Internal),
+        );
 
+    let mut update = client
+        .full_scan(request, STOP_GAP, PARALLEL_REQUESTS)
+        .await?;
     let now = std::time::UNIX_EPOCH.elapsed().unwrap().as_secs();
-    let _ = update_graph.update_last_seen_unconfirmed(now);
-    let missing_heights = update_graph.missing_heights(wallet.local_chain());
-    let chain_update = client.update_local_chain(prev_tip, missing_heights).await?;
-    let update = Update {
-        last_active_indices,
-        graph: update_graph,
-        chain: Some(chain_update),
-    };
+    let _ = update.graph_update.update_last_seen_unconfirmed(now);
+
     wallet.apply_update(update)?;
     wallet.commit()?;
     println!();

example-crates/wallet_esplora_blocking/src/main.rs

@@ -3,12 +3,11 @@ const SEND_AMOUNT: u64 = 1000;
 const STOP_GAP: usize = 5;
 const PARALLEL_REQUESTS: usize = 1;
 
-use std::{io::Write, str::FromStr};
+use std::{collections::BTreeSet, io::Write, str::FromStr};
 
 use bdk::{
     bitcoin::{Address, Network},
-    wallet::{AddressIndex, Update},
-    SignOptions, Wallet,
+    KeychainKind, SignOptions, Wallet,
 };
 use bdk_esplora::{esplora_client, EsploraExt};
 use bdk_file_store::Store;
@@ -26,7 +25,7 @@ fn main() -> Result<(), anyhow::Error> {
         Network::Testnet,
     )?;
 
-    let address = wallet.try_get_address(AddressIndex::New)?;
+    let address = wallet.next_unused_address(KeychainKind::External)?;
     println!("Generated Address: {}", address);
 
     let balance = wallet.get_balance();
@@ -36,35 +35,20 @@ fn main() -> Result<(), anyhow::Error> {
     let client =
         esplora_client::Builder::new("https://blockstream.info/testnet/api").build_blocking();
 
-    let prev_tip = wallet.latest_checkpoint();
-    let keychain_spks = wallet
-        .all_unbounded_spk_iters()
-        .into_iter()
-        .map(|(k, k_spks)| {
-            let mut once = Some(());
-            let mut stdout = std::io::stdout();
-            let k_spks = k_spks
-                .inspect(move |(spk_i, _)| match once.take() {
-                    Some(_) => print!("\nScanning keychain [{:?}]", k),
-                    None => print!(" {:<3}", spk_i),
-                })
-                .inspect(move |_| stdout.flush().expect("must flush"));
-            (k, k_spks)
-        })
-        .collect();
-
-    let (mut update_graph, last_active_indices) =
-        client.full_scan(keychain_spks, STOP_GAP, PARALLEL_REQUESTS)?;
+    let request = wallet.start_full_scan().inspect_spks_for_all_keychains({
+        let mut once = BTreeSet::<KeychainKind>::new();
+        move |keychain, spk_i, _| {
+            match once.insert(keychain) {
+                true => print!("\nScanning keychain [{:?}]", keychain),
+                false => print!(" {:<3}", spk_i),
+            };
+            std::io::stdout().flush().expect("must flush")
+        }
+    });
 
+    let mut update = client.full_scan(request, STOP_GAP, PARALLEL_REQUESTS)?;
     let now = std::time::UNIX_EPOCH.elapsed().unwrap().as_secs();
-    let _ = update_graph.update_last_seen_unconfirmed(now);
-    let missing_heights = update_graph.missing_heights(wallet.local_chain());
-    let chain_update = client.update_local_chain(prev_tip, missing_heights)?;
-    let update = Update {
-        last_active_indices,
-        graph: update_graph,
-        chain: Some(chain_update),
-    };
+    let _ = update.graph_update.update_last_seen_unconfirmed(now);
 
     wallet.apply_update(update)?;
     wallet.commit()?;