feat: add code examples for persistence pages

Author: notmandatory

docs/cookbook/persistence/flat-file.md

@@ -12,18 +12,14 @@ See our page on the [difference between the full scan and sync operations](../sy
 
 The in-memory wallet does _not_ require any additional dependencies beyond the `bdk_wallet` dependency:
 
-```toml
-[dependencies]
-bdk_wallet = { version = "1.0.0" }
+```toml title="Cargo.toml"
+--8<-- "examples/rust/persistence/memory/Cargo.toml:deps"
 ```
 
 To create an in-memory wallet, simply call `create_wallet_no_persist()` on the `Wallet` builder:
 
-```rust
-let mut wallet = Wallet::create(EXTERNAL_DESCRIPTOR, INTERNAL_DESCRIPTOR)
-    .network(Network::Signet)
-    .create_wallet_no_persist()
-    .expect("valid wallet");
+```rust title="main.rs"
+--8<-- "examples/rust/persistence/memory/src/main.rs:create"
 ```
 
 <br>

docs/cookbook/persistence/memory.md

@@ -19,28 +19,26 @@ See our page on the [difference between the full scan and sync operations](../sy
 
 The sqlite wallet does not require any additional dependencies above the `bdk_wallet` dependency:
 
-```toml
-[dependencies]
-bdk_wallet = { version = "1.0.0", features = ["rusqlite"] }
+```toml title="Cargo.toml"
+--8<-- "examples/rust/persistence/sqlite/Cargo.toml:deps"
 ```
 
-To create a sqlite-based persisted wallet, simply call the `create_wallet()` with a valid db connection on the wallet builder:
+To load an existing sqlite-based persisted wallet use `Wallet::load()`. You may then optionally verify the loaded descriptors match what you expect. If the provided descriptors contain private keys you can also extract these keys into the wallets keystore. Private keys are never stored in the wallet database. You may also verify the wallet network during loading.
 
 ```rust
-use bdk_wallet::rusqlite::Connection;
+--8<-- "examples/rust/persistence/sqlite/src/main.rs:load"
+```
+
+If during wallet loading no wallet database file is found you can create a sqlite-based persisted wallet with `Wallet::create()` with a valid db connection and other wallet builder parameters:
 
-let mut conn = Connection::open(file_path)?;
-let wallet = Wallet::create(EXTERNAL_DESCRIPTOR, INTERNAL_DESCRIPTOR)
-    .network(Network::Signet)
-    .create_wallet(&mut conn)
-    .expect("valid wallet and db connection");
+```rust
+--8<-- "examples/rust/persistence/sqlite/src/main.rs:create"
 ```
 
 After performing an operation that returns data that should be persisted, use the `persist()` method on the wallet:
 
 ```rust
-let address = wallet.next_unused_address(KeychainKind::External);
-wallet.persist(&mut conn)?;
+--8<-- "examples/rust/persistence/sqlite/src/main.rs:address"
 ```
 
 <br>

docs/cookbook/persistence/sqlite.md

@@ -1,10 +1,6 @@
 @default:
   just --list
 
-# build all rust examples
-build-rust:
-  cd rust && cargo build
-
-# format all rust examples
-fmt-rust:
-  cd rust && cargo fmt
+# Rust examples: fmt, clippy check, and build
+rust:
+  cd rust && cargo fmt && cargo clippy && cargo build

examples/justfile

@@ -1,8 +1,9 @@
 [workspace]
 resolver = "2"
 members = [
-    "descriptors", "full-wallet", "memory-wallet", "migrate-version", "quickstart", "seed-phrase",
-    "syncing/electrum", "syncing/esplora", "syncing/kyoto", "syncing/rpc"
+    "descriptors", "full-wallet", "migrate-version", "quickstart", "seed-phrase",
+    "syncing/electrum", "syncing/esplora", "syncing/kyoto", "syncing/rpc",
+    "persistence/memory", "persistence/sqlite"
 ]
 
 [workspace.package]

examples/rust/Cargo.toml

@@ -3,8 +3,8 @@ name = "memory-wallet"
 version = "0.1.0"
 edition = "2021"
 
-[dependencies]
 # --8<-- [start:deps]
-bdk_wallet = { version = "1.0.0", features = ["keys-bip39"] }
-# --8<-- [stop:deps]
-anyhow = "1"
+[dependencies]
+bdk_wallet = { version = "1.0.0" }
+# --8<-- [end:deps]
+anyhow = "1"

examples/rust/memory-wallet/.gitignore examples/rust/persistence/memory/.gitignore

@@ -0,0 +1 @@
+target/

examples/rust/memory-wallet/Cargo.toml examples/rust/persistence/memory/Cargo.toml

@@ -0,0 +1,10 @@
+[package]
+name = "sqlite-wallet"
+version = "0.1.0"
+edition = "2021"
+
+# --8<-- [start:deps]
+[dependencies]
+bdk_wallet = { version = "1.0.0", features = ["rusqlite"] }
+# --8<-- [end:deps]
+anyhow = "1"

examples/rust/memory-wallet/src/main.rs examples/rust/persistence/memory/src/main.rs

@@ -0,0 +1,52 @@
+use bdk_wallet::bitcoin::Network;
+use bdk_wallet::rusqlite;
+use bdk_wallet::KeychainKind;
+use bdk_wallet::Wallet;
+
+// --8<-- [start:descriptors]
+// const EXTERNAL_DESCRIPTOR: &str = "[your external descriptor here ...]";
+// const INTERNAL_DESCRIPTOR: &str = "[your internal descriptor here ...]";
+// Example private descriptors
+const EXTERNAL_DESCRIPTOR: &str = "tr(tprv8ZgxMBicQKsPdJuLWWArdBsWjqDA3W5WoREnfdgKEcCQB1FMKfSoaFz9JHZU71HwXAqTsjHripkLM62kUQar14SDD8brsmhFKqVUPXGrZLc/86'/1'/0'/0/*)#fv8tutn2";
+const INTERNAL_DESCRIPTOR: &str = "tr(tprv8ZgxMBicQKsPdJuLWWArdBsWjqDA3W5WoREnfdgKEcCQB1FMKfSoaFz9JHZU71HwXAqTsjHripkLM62kUQar14SDD8brsmhFKqVUPXGrZLc/86'/1'/0'/1/*)#ccz2p7rj";
+// --8<-- [end:descriptors]
+
+fn main() -> Result<(), anyhow::Error> {
+    // --8<-- [start:load]
+    let network = Network::Signet;
+    let file_path = "test_wallet.sqlite3";
+    let mut conn = rusqlite::Connection::open(file_path)?;
+
+    let wallet_opt = Wallet::load()
+        .descriptor(KeychainKind::External, Some(EXTERNAL_DESCRIPTOR))
+        .descriptor(KeychainKind::Internal, Some(INTERNAL_DESCRIPTOR))
+        .extract_keys() // only needed if using private key descriptors
+        .check_network(network)
+        .load_wallet(&mut conn)?;
+    // --8<-- [end:load]
+
+    // --8<-- [start:create]
+    let mut wallet = match wallet_opt {
+        Some(wallet) => {
+            println!("Loaded existing wallet database.");
+            wallet
+        }
+        None => {
+            println!("Creating new wallet database.");
+            Wallet::create(EXTERNAL_DESCRIPTOR, INTERNAL_DESCRIPTOR)
+                .network(network)
+                .create_wallet(&mut conn)?
+        }
+    };
+    // --8<-- [end:create]
+
+    // --8<-- [start:address]
+    // Reveal a new address from your external keychain
+    let address = wallet.reveal_next_address(KeychainKind::External);
+    wallet.persist(&mut conn)?;
+    // Only share new address with user after successfully persisting wallet
+    println!("Wallet address[{}]: {}", address.index, address.address);
+    // --8<-- [end:address]
+
+    Ok(())
+}

examples/rust/persistence/sqlite/.gitignore

@@ -1,8 +1,10 @@
 default:
   just --list
 
-rust:
-  cd examples/rust && cargo build
+# Build mkdocs
+build:
+  mkdocs build
 
+# Serve mkdocs
 serve:
   mkdocs serve

examples/rust/persistence/sqlite/Cargo.toml

@@ -95,7 +95,6 @@ nav:
     - Persistence:
       - In-Memory Wallet: cookbook/persistence/memory.md
       - SQLite Database: cookbook/persistence/sqlite.md
-      - Flat File Persistence: cookbook/persistence/flat-file.md
     - Keys and Descriptors:
       - Creating Descriptors: cookbook/keys-descriptors/descriptors.md
       - Seed Phrase to Descriptors: cookbook/keys-descriptors/seed-phrase.md