refactor(wallet)!: rename method to last_unused_address

As per both out-of-band discussions, and the latest discussion at weekly
development call, the semantics of this method can be misleading, as
it's not guaranteed you get a next one on every call, that'd only happen
if the address has been used and the application synced with latest
blockchain state.

Renaming it to `last_unused_address` gives it a better semantics, as
you'll always get the last derived address which still unused. As per
usage where the user needs always a new derived address on every call,
you should still use the `reveal_next_address`, nothing changed.

crates/wallet/examples/compiler.rs

@@ -64,7 +64,7 @@ fn main() -> Result<(), Box<dyn Error>> {
 
     println!(
         "First derived address from the descriptor: \n{}",
-        wallet.next_unused_address(KeychainKind::External),
+        wallet.last_unused_address(KeychainKind::External),
     );
 
     // BDK also has it's own `Policy` structure to represent the spending condition in a more

crates/wallet/src/test_utils.rs

@@ -245,7 +245,7 @@ pub fn receive_output(
     value: u64,
     pos: ChainPosition<ConfirmationBlockTime>,
 ) -> OutPoint {
-    let addr = wallet.next_unused_address(KeychainKind::External).address;
+    let addr = wallet.last_unused_address(KeychainKind::External).address;
     receive_output_to_address(wallet, addr, value, pos)
 }
 

crates/wallet/src/wallet/mod.rs

@@ -737,15 +737,15 @@ impl Wallet {
         })
     }
 
-    /// Get the next unused address for the given `keychain`, i.e. the address with the lowest
+    /// Get the last 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).
     ///
     /// **WARNING**: To avoid address reuse you must persist the changes resulting from one or more
     /// calls to this method before closing the wallet. See [`Wallet::reveal_next_address`].
-    pub fn next_unused_address(&mut self, keychain: KeychainKind) -> AddressInfo {
+    pub fn last_unused_address(&mut self, keychain: KeychainKind) -> AddressInfo {
         let keychain = self.map_keychain(keychain);
         let index = &mut self.indexed_graph.index;
 

example-crates/example_wallet_electrum/src/main.rs

@@ -37,7 +37,7 @@ fn main() -> Result<(), anyhow::Error> {
             .create_wallet(&mut db)?,
     };
 
-    let address = wallet.next_unused_address(KeychainKind::External);
+    let address = wallet.last_unused_address(KeychainKind::External);
     wallet.persist(&mut db)?;
     println!("Generated Address: {}", address);
 

example-crates/example_wallet_esplora_async/src/main.rs

@@ -35,7 +35,7 @@ async fn main() -> Result<(), anyhow::Error> {
             .create_wallet(&mut conn)?,
     };
 
-    let address = wallet.next_unused_address(KeychainKind::External);
+    let address = wallet.last_unused_address(KeychainKind::External);
     wallet.persist(&mut conn)?;
     println!("Next unused address: ({}) {}", address.index, address);
 

example-crates/example_wallet_esplora_blocking/src/main.rs

@@ -34,7 +34,7 @@ fn main() -> Result<(), anyhow::Error> {
             .create_wallet(&mut db)?,
     };
 
-    let address = wallet.next_unused_address(KeychainKind::External);
+    let address = wallet.last_unused_address(KeychainKind::External);
     wallet.persist(&mut db)?;
     println!(
         "Next unused address: ({}) {}",