docs(wallet): for electrum, esplora examples use sqlite+testnet4, and mempool.space

notmandatory · notmandatory · commit 11bfc2f64943 · 2025-08-05T18:02:16.000-05:00
For electrum, esplora examples print mempool.space tx URLs and add delay before RBF.
For rpc example also add justfile to help testing with regtest bitcoind.
diff --git a/examples/example_wallet_electrum/Cargo.toml b/examples/example_wallet_electrum/Cargo.toml
@@ -4,6 +4,6 @@ version = "0.2.0"
 edition = "2021"
 
 [dependencies]
-bdk_wallet = { path = "../../wallet", features = ["file_store"] }
+bdk_wallet = { path = "../../wallet", features = ["rusqlite"] }
 bdk_electrum = { version = "0.23.0" }
 anyhow = "1"
diff --git a/examples/example_wallet_electrum/src/main.rs b/examples/example_wallet_electrum/src/main.rs
@@ -1,31 +1,29 @@
-use bdk_wallet::bitcoin::FeeRate;
-use bdk_wallet::file_store::Store;
-use bdk_wallet::psbt::PsbtUtils;
-use bdk_wallet::Wallet;
-use std::io::Write;
-
 use bdk_electrum::electrum_client;
 use bdk_electrum::BdkElectrumClient;
 use bdk_wallet::bitcoin::Amount;
+use bdk_wallet::bitcoin::FeeRate;
 use bdk_wallet::bitcoin::Network;
 use bdk_wallet::chain::collections::HashSet;
+use bdk_wallet::psbt::PsbtUtils;
+use bdk_wallet::rusqlite::Connection;
+use bdk_wallet::Wallet;
 use bdk_wallet::{KeychainKind, SignOptions};
+use std::io::Write;
+use std::thread::sleep;
+use std::time::Duration;
 
-const DB_MAGIC: &str = "bdk_wallet_electrum_example";
 const SEND_AMOUNT: Amount = Amount::from_sat(5000);
 const STOP_GAP: usize = 50;
 const BATCH_SIZE: usize = 5;
 
-const NETWORK: Network = Network::Testnet;
+const DB_PATH: &str = "bdk-example-electrum.sqlite";
+const NETWORK: Network = Network::Testnet4;
 const EXTERNAL_DESC: &str = "wpkh(tprv8ZgxMBicQKsPdy6LMhUtFHAgpocR8GC6QmwMSFpZs7h6Eziw3SpThFfczTDh5rW2krkqffa11UpX3XkeTTB2FvzZKWXqPY54Y6Rq4AQ5R8L/84'/1'/0'/0/*)";
 const INTERNAL_DESC: &str = "wpkh(tprv8ZgxMBicQKsPdy6LMhUtFHAgpocR8GC6QmwMSFpZs7h6Eziw3SpThFfczTDh5rW2krkqffa11UpX3XkeTTB2FvzZKWXqPY54Y6Rq4AQ5R8L/84'/1'/0'/1/*)";
-const ELECTRUM_URL: &str = "ssl://electrum.blockstream.info:60002";
+const ELECTRUM_URL: &str = "ssl://mempool.space:40002";
 
 fn main() -> Result<(), anyhow::Error> {
-    let db_path = "bdk-electrum-example.db";
-
-    let (mut db, _) = Store::<bdk_wallet::ChangeSet>::load_or_create(DB_MAGIC.as_bytes(), db_path)?;
-
+    let mut db = Connection::open(DB_PATH)?;
     let wallet_opt = Wallet::load()
         .descriptor(KeychainKind::External, Some(EXTERNAL_DESC))
         .descriptor(KeychainKind::Internal, Some(INTERNAL_DESC))
@@ -86,8 +84,11 @@ fn main() -> Result<(), anyhow::Error> {
         println!("Please send at least {SEND_AMOUNT} to the receiving address");
         std::process::exit(0);
     }
+
+    let target_fee_rate = FeeRate::from_sat_per_vb(1).unwrap();
     let mut tx_builder = wallet.build_tx();
     tx_builder.add_recipient(address.script_pubkey(), SEND_AMOUNT);
+    tx_builder.fee_rate(target_fee_rate);
 
     let mut psbt = tx_builder.finish()?;
     let finalized = wallet.sign(&mut psbt, SignOptions::default())?;
@@ -97,7 +98,7 @@ fn main() -> Result<(), anyhow::Error> {
     let tx = psbt.extract_tx()?;
     client.transaction_broadcast(&tx)?;
     let txid = tx.compute_txid();
-    println!("Tx broadcasted! Txid: {txid}");
+    println!("Tx broadcasted! Txid: https://mempool.space/testnet4/tx/{txid}");
 
     println!("Partial Sync...");
     print!("SCANNING: ");
@@ -120,8 +121,8 @@ fn main() -> Result<(), anyhow::Error> {
     wallet.apply_update(sync_update)?;
     wallet.persist(&mut db)?;
 
-    // bump fee tx
-    let feerate = FeeRate::from_sat_per_kwu(tx_feerate.to_sat_per_kwu() + 250);
+    // bump fee rate for tx by at least 1 sat per vbyte
+    let feerate = FeeRate::from_sat_per_vb(tx_feerate.to_sat_per_vb_ceil() + 1).unwrap();
     let mut builder = wallet.build_fee_bump(txid).expect("failed to bump tx");
     builder.fee_rate(feerate);
     let mut bumped_psbt = builder.finish().unwrap();
@@ -141,14 +142,18 @@ fn main() -> Result<(), anyhow::Error> {
     );
     assert!(
         new_fee > original_fee,
-        "New fee ({}) should be higher than original ({})",
-        new_fee,
-        original_fee
+        "New fee ({new_fee}) should be higher than original ({original_fee})"
     );
+
+    // wait for first transaction to make it into the mempool and be indexed on mempool.space
+    sleep(Duration::from_secs(10));
     client.transaction_broadcast(&bumped_tx)?;
-    println!("Broadcasted bumped tx. Txid: {}", bumped_tx.compute_txid());
+    println!(
+        "Broadcasted bumped tx. Txid: https://mempool.space/testnet4/tx/{}",
+        bumped_tx.compute_txid()
+    );
 
-    print!("Syncing after bumped tx broadcast...");
+    println!("Syncing after bumped tx broadcast...");
     let sync_request = wallet.start_sync_with_revealed_spks().inspect(|_, _| {});
     let sync_update = client.sync(sync_request, BATCH_SIZE, false)?;
 
@@ -157,12 +162,10 @@ fn main() -> Result<(), anyhow::Error> {
         evicted_txs.push((*txid, *last_seen));
     }
 
+    wallet.apply_update(sync_update)?;
     if !evicted_txs.is_empty() {
-        wallet.apply_evicted_txs(evicted_txs.clone());
         println!("Applied {} evicted transactions", evicted_txs.len());
     }
-
-    wallet.apply_update(sync_update)?;
     wallet.persist(&mut db)?;
 
     let balance_after_sync = wallet.balance();
diff --git a/examples/example_wallet_esplora_async/src/main.rs b/examples/example_wallet_esplora_async/src/main.rs
@@ -7,35 +7,36 @@ use bdk_wallet::{
     KeychainKind, SignOptions, Wallet,
 };
 use std::{collections::BTreeSet, io::Write};
+use tokio::time::{sleep, Duration};
 
 const SEND_AMOUNT: Amount = Amount::from_sat(5000);
 const STOP_GAP: usize = 5;
 const PARALLEL_REQUESTS: usize = 5;
 
 const DB_PATH: &str = "bdk-example-esplora-async.sqlite";
-const NETWORK: Network = Network::Signet;
+const NETWORK: Network = Network::Testnet4;
 const EXTERNAL_DESC: &str = "wpkh(tprv8ZgxMBicQKsPdy6LMhUtFHAgpocR8GC6QmwMSFpZs7h6Eziw3SpThFfczTDh5rW2krkqffa11UpX3XkeTTB2FvzZKWXqPY54Y6Rq4AQ5R8L/84'/1'/0'/0/*)";
 const INTERNAL_DESC: &str = "wpkh(tprv8ZgxMBicQKsPdy6LMhUtFHAgpocR8GC6QmwMSFpZs7h6Eziw3SpThFfczTDh5rW2krkqffa11UpX3XkeTTB2FvzZKWXqPY54Y6Rq4AQ5R8L/84'/1'/0'/1/*)";
-const ESPLORA_URL: &str = "http://signet.bitcoindevkit.net";
+const ESPLORA_URL: &str = "https://mempool.space/testnet4/api";
 
 #[tokio::main]
 async fn main() -> Result<(), anyhow::Error> {
-    let mut conn = Connection::open(DB_PATH)?;
+    let mut db = Connection::open(DB_PATH)?;
     let wallet_opt = Wallet::load()
         .descriptor(KeychainKind::External, Some(EXTERNAL_DESC))
         .descriptor(KeychainKind::Internal, Some(INTERNAL_DESC))
         .extract_keys()
         .check_network(NETWORK)
-        .load_wallet(&mut conn)?;
+        .load_wallet(&mut db)?;
     let mut wallet = match wallet_opt {
         Some(wallet) => wallet,
         None => Wallet::create(EXTERNAL_DESC, INTERNAL_DESC)
             .network(NETWORK)
-            .create_wallet(&mut conn)?,
+            .create_wallet(&mut db)?,
     };
 
     let address = wallet.next_unused_address(KeychainKind::External);
-    wallet.persist(&mut conn)?;
+    wallet.persist(&mut db)?;
     println!("Next unused address: ({}) {address}", address.index);
 
     let balance = wallet.balance();
@@ -63,7 +64,7 @@ async fn main() -> Result<(), anyhow::Error> {
         .await?;
 
     wallet.apply_update(update)?;
-    wallet.persist(&mut conn)?;
+    wallet.persist(&mut db)?;
     println!();
 
     let balance = wallet.balance();
@@ -78,8 +79,11 @@ async fn main() -> Result<(), anyhow::Error> {
         println!("Please send at least {SEND_AMOUNT} to the receiving address");
         std::process::exit(0);
     }
+
+    let target_fee_rate = FeeRate::from_sat_per_vb(1).unwrap();
     let mut tx_builder = wallet.build_tx();
     tx_builder.add_recipient(address.script_pubkey(), SEND_AMOUNT);
+    tx_builder.fee_rate(target_fee_rate);
 
     let mut psbt = tx_builder.finish()?;
     let finalized = wallet.sign(&mut psbt, SignOptions::default())?;
@@ -89,7 +93,7 @@ async fn main() -> Result<(), anyhow::Error> {
     let tx = psbt.extract_tx()?;
     client.broadcast(&tx).await?;
     let txid = tx.compute_txid();
-    println!("Tx broadcasted! Txid: {txid}");
+    println!("Tx broadcasted! Txid: https://mempool.space/testnet4/tx/{txid}");
 
     println!("Partial Sync...");
     print!("SCANNING: ");
@@ -109,9 +113,10 @@ async fn main() -> Result<(), anyhow::Error> {
     let sync_update = client.sync(sync_request, PARALLEL_REQUESTS).await?;
     println!();
     wallet.apply_update(sync_update)?;
-    wallet.persist(&mut conn)?;
+    wallet.persist(&mut db)?;
 
-    let feerate = FeeRate::from_sat_per_kwu(tx_feerate.to_sat_per_kwu() + 250);
+    // bump fee rate for tx by at least 1 sat per vbyte
+    let feerate = FeeRate::from_sat_per_vb(tx_feerate.to_sat_per_vb_ceil() + 1).unwrap();
     let mut builder = wallet.build_fee_bump(txid).expect("failed to bump tx");
     builder.fee_rate(feerate);
     let mut bumped_psbt = builder.finish().unwrap();
@@ -133,8 +138,14 @@ async fn main() -> Result<(), anyhow::Error> {
         new_fee > original_fee,
         "New fee ({new_fee}) should be higher than original ({original_fee})",
     );
+
+    // wait for first transaction to make it into the mempool and be indexed on mempool.space
+    sleep(Duration::from_secs(10)).await;
     client.broadcast(&bumped_tx).await?;
-    println!("Broadcasted bumped tx. Txid: {}", bumped_tx.compute_txid());
+    println!(
+        "Broadcasted bumped tx. Txid: https://mempool.space/testnet4/tx/{}",
+        bumped_tx.compute_txid()
+    );
 
     println!("syncing after broadcasting bumped tx...");
     print!("SCANNING: ");
@@ -155,26 +166,17 @@ async fn main() -> Result<(), anyhow::Error> {
 
     let mut evicted_txs = Vec::new();
 
-    let last_seen = wallet
-        .tx_graph()
-        .full_txs()
-        .find(|full_tx| full_tx.txid == txid)
-        .map_or(0, |full_tx| full_tx.last_seen.unwrap_or(0));
-    if !evicted_txs
-        .iter()
-        .any(|(evicted_txid, _)| evicted_txid == &txid)
-    {
-        evicted_txs.push((txid, last_seen));
+    for (txid, last_seen) in &sync_update.tx_update.evicted_ats {
+        evicted_txs.push((*txid, *last_seen));
     }
 
+    wallet.apply_update(sync_update)?;
+
     if !evicted_txs.is_empty() {
-        let evicted_count = evicted_txs.len();
-        wallet.apply_evicted_txs(evicted_txs);
-        println!("Applied {evicted_count} evicted transactions");
+        println!("Applied {} evicted transactions", evicted_txs.len());
     }
 
-    wallet.apply_update(sync_update)?;
-    wallet.persist(&mut conn)?;
+    wallet.persist(&mut db)?;
 
     let balance_after_sync = wallet.balance();
     println!("Wallet balance after sync: {}", balance_after_sync.total());
diff --git a/examples/example_wallet_esplora_blocking/Cargo.toml b/examples/example_wallet_esplora_blocking/Cargo.toml
@@ -7,6 +7,6 @@ publish = false
 # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
 
 [dependencies]
-bdk_wallet = { path = "../../wallet", features = ["file_store"] }
+bdk_wallet = { path = "../../wallet", features = ["rusqlite"] }
 bdk_esplora = { version = "0.22.0", features = ["blocking"] }
 anyhow = "1"
diff --git a/examples/example_wallet_esplora_blocking/src/main.rs b/examples/example_wallet_esplora_blocking/src/main.rs
@@ -1,26 +1,26 @@
 use bdk_esplora::{esplora_client, EsploraExt};
+use bdk_wallet::rusqlite::Connection;
 use bdk_wallet::{
     bitcoin::{Amount, FeeRate, Network},
-    file_store::Store,
     psbt::PsbtUtils,
     KeychainKind, SignOptions, Wallet,
 };
+use std::thread::sleep;
+use std::time::Duration;
 use std::{collections::BTreeSet, io::Write};
 
-const DB_MAGIC: &str = "bdk_wallet_esplora_example";
-const DB_PATH: &str = "bdk-example-esplora-blocking.db";
 const SEND_AMOUNT: Amount = Amount::from_sat(5000);
 const STOP_GAP: usize = 5;
 const PARALLEL_REQUESTS: usize = 5;
 
-const NETWORK: Network = Network::Signet;
+const DB_PATH: &str = "bdk-example-esplora-blocking.sqlite";
+const NETWORK: Network = Network::Testnet4;
 const EXTERNAL_DESC: &str = "wpkh(tprv8ZgxMBicQKsPdy6LMhUtFHAgpocR8GC6QmwMSFpZs7h6Eziw3SpThFfczTDh5rW2krkqffa11UpX3XkeTTB2FvzZKWXqPY54Y6Rq4AQ5R8L/84'/1'/0'/0/*)";
 const INTERNAL_DESC: &str = "wpkh(tprv8ZgxMBicQKsPdy6LMhUtFHAgpocR8GC6QmwMSFpZs7h6Eziw3SpThFfczTDh5rW2krkqffa11UpX3XkeTTB2FvzZKWXqPY54Y6Rq4AQ5R8L/84'/1'/0'/1/*)";
-const ESPLORA_URL: &str = "http://signet.bitcoindevkit.net";
+const ESPLORA_URL: &str = "https://mempool.space/testnet4/api";
 
 fn main() -> Result<(), anyhow::Error> {
-    let (mut db, _) = Store::<bdk_wallet::ChangeSet>::load_or_create(DB_MAGIC.as_bytes(), DB_PATH)?;
-
+    let mut db = Connection::open(DB_PATH)?;
     let wallet_opt = Wallet::load()
         .descriptor(KeychainKind::External, Some(EXTERNAL_DESC))
         .descriptor(KeychainKind::Internal, Some(INTERNAL_DESC))
@@ -74,8 +74,10 @@ fn main() -> Result<(), anyhow::Error> {
         std::process::exit(0);
     }
 
+    let target_fee_rate = FeeRate::from_sat_per_vb(1).unwrap();
     let mut tx_builder = wallet.build_tx();
     tx_builder.add_recipient(address.script_pubkey(), SEND_AMOUNT);
+    tx_builder.fee_rate(target_fee_rate);
 
     let mut psbt = tx_builder.finish()?;
     let finalized = wallet.sign(&mut psbt, SignOptions::default())?;
@@ -85,7 +87,7 @@ fn main() -> Result<(), anyhow::Error> {
     let tx = psbt.extract_tx()?;
     client.broadcast(&tx)?;
     let txid = tx.compute_txid();
-    println!("Tx broadcasted! Txid: {txid}");
+    println!("Tx broadcasted! Txid: https://mempool.space/testnet4/tx/{txid}");
 
     println!("Partial Sync...");
     print!("SCANNING: ");
@@ -108,7 +110,8 @@ fn main() -> Result<(), anyhow::Error> {
     wallet.persist(&mut db)?;
     println!();
 
-    let feerate = FeeRate::from_sat_per_kwu(tx_feerate.to_sat_per_kwu() + 200);
+    // bump fee rate for tx by at least 1 sat per vbyte
+    let feerate = FeeRate::from_sat_per_vb(tx_feerate.to_sat_per_vb_ceil() + 1).unwrap();
     let mut builder = wallet.build_fee_bump(txid).unwrap();
     builder.fee_rate(feerate);
     let mut new_psbt = builder.finish().unwrap();
@@ -130,9 +133,12 @@ fn main() -> Result<(), anyhow::Error> {
         new_fee > original_fee,
         "Replacement tx fee ({new_fee}) should be higher than original ({original_fee})",
     );
+
+    // wait for first transaction to make it into the mempool and be indexed on mempool.space
+    sleep(Duration::from_secs(10));
     client.broadcast(&bumped_tx)?;
     println!(
-        "Broadcast replacement transaction. Txid: {}",
+        "Broadcast replacement transaction. Txid: https://mempool.space/testnet4/tx/{}",
         bumped_tx.compute_txid()
     );
 
@@ -142,25 +148,14 @@ fn main() -> Result<(), anyhow::Error> {
     println!();
 
     let mut evicted_txs = Vec::new();
-    let last_seen = wallet
-        .tx_graph()
-        .full_txs()
-        .find(|full_tx| full_tx.txid == txid)
-        .map_or(0, |full_tx| full_tx.last_seen.unwrap_or(0));
-    if !evicted_txs
-        .iter()
-        .any(|(evicted_txid, _)| evicted_txid == &txid)
-    {
-        evicted_txs.push((txid, last_seen));
+    for (txid, last_seen) in &sync_update.tx_update.evicted_ats {
+        evicted_txs.push((*txid, *last_seen));
     }
 
+    wallet.apply_update(sync_update)?;
     if !evicted_txs.is_empty() {
-        let evicted_count = evicted_txs.len();
-        wallet.apply_evicted_txs(evicted_txs);
-        println!("Applied {evicted_count} evicted transactions");
+        println!("Applied {} evicted transactions", evicted_txs.len());
     }
-
-    wallet.apply_update(sync_update)?;
     wallet.persist(&mut db)?;
 
     let balance_after_sync = wallet.balance();
diff --git a/examples/example_wallet_rpc/.gitignore b/examples/example_wallet_rpc/.gitignore
@@ -0,0 +1 @@
+test_data/
diff --git a/examples/example_wallet_rpc/Cargo.toml b/examples/example_wallet_rpc/Cargo.toml
@@ -6,7 +6,7 @@ edition = "2021"
 # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
 
 [dependencies]
-bdk_wallet = { path = "../../wallet", features = ["file_store"] }
+bdk_wallet = { path = "../../wallet", features = ["rusqlite"] }
 bdk_bitcoind_rpc = { version = "0.20.0" }
 
 anyhow = "1"
diff --git a/examples/example_wallet_rpc/README.md b/examples/example_wallet_rpc/README.md
diff --git a/examples/example_wallet_rpc/justfile b/examples/example_wallet_rpc/justfile
diff --git a/examples/example_wallet_rpc/src/main.rs b/examples/example_wallet_rpc/src/main.rs
