docs(wallet): for electrum, esplora examples use sqlite+testnet, print mempool.space URLs

For rpc example also add justfile to help testing with regtest bitcoind.

Author: notmandatory

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"

examples/example_wallet_electrum/src/main.rs

@@ -1,5 +1,4 @@
 use bdk_wallet::bitcoin::FeeRate;
-use bdk_wallet::file_store::Store;
 use bdk_wallet::psbt::PsbtUtils;
 use bdk_wallet::Wallet;
 use std::io::Write;
@@ -9,23 +8,21 @@ use bdk_electrum::BdkElectrumClient;
 use bdk_wallet::bitcoin::Amount;
 use bdk_wallet::bitcoin::Network;
 use bdk_wallet::chain::collections::HashSet;
+use bdk_wallet::rusqlite::Connection;
 use bdk_wallet::{KeychainKind, SignOptions};
 
-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 DB_PATH: &str = "bdk-example-electrum.sqlite";
 const NETWORK: Network = Network::Testnet;
 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";
 
 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))
@@ -97,7 +94,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/testnet/tx/{txid}");
 
     println!("Partial Sync...");
     print!("SCANNING: ");
@@ -120,8 +117,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,12 +138,13 @@ 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})"
     );
     client.transaction_broadcast(&bumped_tx)?;
-    println!("Broadcasted bumped tx. Txid: {}", bumped_tx.compute_txid());
+    println!(
+        "Broadcasted bumped tx. Txid: https://mempool.space/testnet/tx/{}",
+        bumped_tx.compute_txid()
+    );
 
     print!("Syncing after bumped tx broadcast...");
     let sync_request = wallet.start_sync_with_revealed_spks().inspect(|_, _| {});

examples/example_wallet_esplora_async/src/main.rs

@@ -13,29 +13,29 @@ 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::Testnet;
 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://blockstream.info/testnet/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 +63,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 +78,15 @@ async fn main() -> Result<(), anyhow::Error> {
         println!("Please send at least {SEND_AMOUNT} to the receiving address");
         std::process::exit(0);
     }
+
+    // set fee rate for inclusion in 3 blocks so we can bump it later
+    let fee_rate_estimates = client.get_fee_estimates().await?;
+    let target_fee_rate =
+        FeeRate::from_sat_per_vb(fee_rate_estimates.get(&3).unwrap().round() as u64).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 +96,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/testnet/tx/{txid}");
 
     println!("Partial Sync...");
     print!("SCANNING: ");
@@ -109,9 +116,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();
@@ -134,7 +142,10 @@ async fn main() -> Result<(), anyhow::Error> {
         "New fee ({new_fee}) should be higher than original ({original_fee})",
     );
     client.broadcast(&bumped_tx).await?;
-    println!("Broadcasted bumped tx. Txid: {}", bumped_tx.compute_txid());
+    println!(
+        "Broadcasted bumped tx. Txid: https://mempool.space/testnet/tx/{}",
+        bumped_tx.compute_txid()
+    );
 
     println!("syncing after broadcasting bumped tx...");
     print!("SCANNING: ");
@@ -155,16 +166,8 @@ 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));
     }
 
     if !evicted_txs.is_empty() {
@@ -174,7 +177,7 @@ async fn main() -> Result<(), anyhow::Error> {
     }
 
     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());

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"

examples/example_wallet_esplora_blocking/src/main.rs

@@ -1,26 +1,24 @@
 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::{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::Testnet;
 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://blockstream.info/testnet/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 +72,14 @@ fn main() -> Result<(), anyhow::Error> {
         std::process::exit(0);
     }
 
+    // set fee rate for inclusion in 3 blocks so we can bump it later
+    let fee_rate_estimates = client.get_fee_estimates()?;
+    let target_fee_rate =
+        FeeRate::from_sat_per_vb(fee_rate_estimates.get(&3).unwrap().round() as u64).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 +89,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/testnet/tx/{txid}");
 
     println!("Partial Sync...");
     print!("SCANNING: ");
@@ -108,7 +112,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();
@@ -132,7 +137,7 @@ fn main() -> Result<(), anyhow::Error> {
     );
     client.broadcast(&bumped_tx)?;
     println!(
-        "Broadcast replacement transaction. Txid: {}",
+        "Broadcast replacement transaction. Txid: https://mempool.space/testnet/tx/{}",
         bumped_tx.compute_txid()
     );
 
@@ -142,16 +147,8 @@ 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));
     }
 
     if !evicted_txs.is_empty() {

examples/example_wallet_rpc/.gitignore

@@ -0,0 +1 @@
+test_data/

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"

examples/example_wallet_rpc/README.md

@@ -1,34 +1,34 @@
 # Wallet RPC Example 
 
-```
-$ cargo run --bin example_wallet_rpc -- --help
-
-Bitcoind RPC example using `bdk_wallet::Wallet`
-
-Usage: example_wallet_rpc [OPTIONS] <DESCRIPTOR> [CHANGE_DESCRIPTOR]
-
-Arguments:
-  <DESCRIPTOR>         Wallet descriptor [env: DESCRIPTOR=]
-  [CHANGE_DESCRIPTOR]  Wallet change descriptor [env: CHANGE_DESCRIPTOR=]
-
-Options:
-      --start-height <START_HEIGHT>  Earliest block height to start sync from [env: START_HEIGHT=] [default: 0]
-
-      --network <NETWORK>            Bitcoin network to connect to [env: BITCOIN_NETWORK=] [default: regtest]
-
-      --db-path <DB_PATH>            Where to store wallet data [env: BDK_DB_PATH=] [default: .bdk_wallet_rpc_example.db]
-
-      --url <URL>                    RPC URL [env: RPC_URL=] [default: 127.0.0.1:18443]
-
-      --rpc-cookie <RPC_COOKIE>      RPC auth cookie file [env: RPC_COOKIE=]
-
-      --rpc-user <RPC_USER>          RPC auth username [env: RPC_USER=]
-
-      --rpc-pass <RPC_PASS>          RPC auth password [env: RPC_PASS=]
-
-  -h, --help                         Print help
-  
-  -V, --version                      Print version
-
-```
+1. Install bitcoind
+2. Start bitcoind in regtest mode.
+   ```
+   just start
+   ```
+3. Create test bitcoind wallet and generate regtest blocks.
+   ```
+   just create
+   just generate 110 $(just address)
+   ```
+4. Run the example and note the wallet's address and balance.
+   ```
+   just run
+   ```
+5. Send regtest coins to the wallet address.
+   ```
+   just send 10 <wallet address>
+   just generate 6 $(just address)
+   ```
+6. Re-run example and note the new balance.
+   ```
+   just run 
+   ```
+7. Kill the regtest bitcoind.
+   ``` 
+   just kill
+   ```
+8. Cleanup test data (optional).
+   ``` 
+   just clean
+   ```