Add optional esplora wallet setup for payjoin-cli backend

This adds a new esplora feature to use a bdk wallet as the supporting
backend for payjoin-cli to reduce the need for a bitcoind rpc
connection when testing against integrations.  This does retain the
bitcoind functionality so we can continue to run local e2e tests during
the payjoin-cli CI tests.

Author: benalleng

Cargo-minimal.lock

@@ -434,11 +434,11 @@ dependencies = [
  "bitcoin 0.30.2",
  "core-rpc",
  "electrum-client",
- "esplora-client",
+ "esplora-client 0.6.0",
  "getrandom 0.2.15",
  "js-sys",
  "log",
- "miniscript",
+ "miniscript 10.2.3",
  "rand 0.8.5",
  "serde",
  "serde_json",
@@ -457,6 +457,55 @@ dependencies = [
  "syn 1.0.109",
 ]
 
+[[package]]
+name = "bdk_chain"
+version = "0.23.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c290eff038799a8ac0c5a82b6160a9ca456baa299a6f22b262c771342d2846c0"
+dependencies = [
+ "bdk_core",
+ "bitcoin 0.32.8",
+ "miniscript 12.3.5",
+ "serde",
+]
+
+[[package]]
+name = "bdk_core"
+version = "0.6.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cb3028782f6bf14a6df987244333d34e6b272b5a40a53e4879ec2dfd82275a3a"
+dependencies = [
+ "bitcoin 0.32.8",
+ "hashbrown 0.14.5",
+ "serde",
+]
+
+[[package]]
+name = "bdk_esplora"
+version = "0.22.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "83986307ea92997c3d051e8c306af8115a05add601e22acb7c1903008e6b614e"
+dependencies = [
+ "async-trait",
+ "bdk_core",
+ "esplora-client 0.12.3",
+ "futures",
+]
+
+[[package]]
+name = "bdk_wallet"
+version = "3.0.0-rc.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9b989a12f0398a844bf22b14a197e2676aea2775aabca52057627f596ad3a0ef"
+dependencies = [
+ "bdk_chain",
+ "bitcoin 0.32.8",
+ "miniscript 12.3.5",
+ "rand_core 0.6.4",
+ "serde",
+ "serde_json",
+]
+
 [[package]]
 name = "bech32"
 version = "0.9.1"
@@ -1425,6 +1474,21 @@ dependencies = [
  "ureq",
 ]
 
+[[package]]
+name = "esplora-client"
+version = "0.12.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f19e3ea99dbfbef0c1ec26d83e69de0c579f6aa6aaac4f44597805fcc27e97af"
+dependencies = [
+ "bitcoin 0.32.8",
+ "hex-conservative 0.2.2",
+ "log",
+ "reqwest",
+ "serde",
+ "serde_json",
+ "tokio",
+]
+
 [[package]]
 name = "extend"
 version = "1.2.0"
@@ -1743,6 +1807,7 @@ checksum = "e5274423e17b7c9fc20b6e7e208532f9b19825d82dfd615708b70edd83df41f1"
 dependencies = [
  "ahash",
  "allocator-api2",
+ "serde",
 ]
 
 [[package]]
@@ -2398,6 +2463,17 @@ dependencies = [
  "serde",
 ]
 
+[[package]]
+name = "miniscript"
+version = "12.3.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "487906208f38448e186e3deb02f2b8ef046a9078b0de00bdb28bf4fb9b76951c"
+dependencies = [
+ "bech32 0.11.0",
+ "bitcoin 0.32.8",
+ "serde",
+]
+
 [[package]]
 name = "miniz_oxide"
 version = "0.8.9"
@@ -2753,10 +2829,13 @@ version = "0.2.0"
 dependencies = [
  "anyhow",
  "async-trait",
+ "bdk_esplora",
+ "bdk_wallet",
  "bitcoind-async-client",
  "clap 4.5.46",
  "config",
  "dirs",
+ "esplora-client 0.12.3",
  "http-body-util",
  "hyper",
  "hyper-util",

Cargo-recent.lock

@@ -7,6 +7,8 @@ cargo llvm-cov clean --workspace
 # exclude payjoin-ffi because bindings are tested in their native language and fuzz because these tests are not coverage worthy
 cargo llvm-cov --no-report --workspace --all-features --exclude payjoin-ffi --exclude payjoin-fuzz
 # Explicitly run payjoin-cli v1 e2e tests
-cargo llvm-cov --no-report --package payjoin-cli --no-default-features --features=v1,_manual-tls
+cargo llvm-cov --no-report --package payjoin-cli --no-default-features --features=v1,_manual-tls,bitcoind
+# Explicitly run payjoin-cli esplora tests
+cargo llvm-cov --no-report --package payjoin-cli --no-default-features --features=v1,v2,_manual-tls,esplora
 # generate report without tests
 cargo llvm-cov report --lcov --output-path lcov.info

contrib/coverage.sh

@@ -19,22 +19,20 @@ path = "src/main.rs"
 
 # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
 [features]
-default = ["v2"]
+default = ["v2", "esplora"]
 native-certs = ["reqwest/rustls-tls-native-roots"]
 _manual-tls = ["reqwest/rustls-tls", "payjoin/_manual-tls", "tokio-rustls"]
 v1 = ["payjoin/v1", "hyper", "hyper-util", "http-body-util"]
 v2 = ["payjoin/v2", "payjoin/io"]
+esplora = ["bdk_wallet", "bdk_esplora", "esplora-client"]
+bitcoind = ["bitcoind-async-client"]
 
 [dependencies]
 anyhow = "1.0.99"
 async-trait = "0.1.89"
-bitcoind-async-client = "0.10.2"
 clap = { version = "4.5.45", features = ["derive"] }
 config = "0.15.14"
 dirs = "6.0.0"
-http-body-util = { version = "0.1.3", optional = true }
-hyper = { version = "1.6.0", features = ["http1", "server"], optional = true }
-hyper-util = { version = "0.1.16", optional = true }
 payjoin = { version = "0.25.0", default-features = false }
 r2d2 = "0.8.10"
 r2d2_sqlite = "0.22.0"
@@ -46,13 +44,31 @@ rusqlite = { version = "0.29.0", features = ["bundled"] }
 serde = { version = "1.0.219", features = ["derive"] }
 serde_json = "1.0.149"
 tokio = { version = "1.47.1", features = ["full"] }
-tokio-rustls = { version = "0.26.2", features = [
-  "ring",
-], default-features = false, optional = true }
 tracing = "0.1.41"
 tracing-subscriber = { version = "0.3.19", features = ["env-filter"] }
 url = { version = "2.5.4", features = ["serde"] }
 
+# Optional dependencies based on features
+bdk_esplora = { version = "0.22", default-features = false, features = [
+  "async-https-rustls",
+  "std",
+  "tokio",
+], optional = true }
+bdk_wallet = { version = "3.0.0-rc.2", optional = true }
+bitcoind-async-client = { version = "0.10.2", optional = true }
+esplora-client = { version = "0.12", default-features = false, features = [
+  "async-https-rustls",
+  "tokio",
+], optional = true }
+
+# TLS support
+http-body-util = { version = "0.1.3", optional = true }
+hyper = { version = "1.6.0", features = ["http1", "server"], optional = true }
+hyper-util = { version = "0.1.16", optional = true }
+tokio-rustls = { version = "0.26.2", features = [
+  "ring",
+], default-features = false, optional = true }
+
 [dev-dependencies]
 nix = { version = "0.30.1", features = ["aio", "process", "signal"] }
 payjoin-test-utils = { version = "0.0.1" }

payjoin-cli/Cargo.toml

@@ -1,10 +1,14 @@
 #!/usr/bin/env bash
 set -e
 
-# Individual features with no defaults.
-features=("v1" "v2")
+# Protocol versions and wallet backends are orthogonal; every version must
+# build against every backend, so lint them as a matrix.
+versions=("v1" "v2")
+backends=("bitcoind" "esplora")
 
-for feature in "${features[@]}"; do
-    # Don't duplicate --all-targets clippy. Clilppy end-user code, not tests.
-    cargo clippy --no-default-features --features "$feature" -- -D warnings
+for version in "${versions[@]}"; do
+    for backend in "${backends[@]}"; do
+        # Don't duplicate --all-targets clippy. Clippy end-user code, not tests.
+        cargo clippy --no-default-features --features "$version,$backend" -- -D warnings
+    done
 done

payjoin-cli/contrib/lint.sh

@@ -1,4 +1,4 @@
 #!/usr/bin/env bash
 set -e
 
-cargo test --locked --package payjoin-cli --verbose --all-features
+cargo test --locked --package payjoin-cli --verbose --no-default-features --features "v1,v2,_manual-tls,bitcoind,native-certs"

payjoin-cli/contrib/test.sh

@@ -0,0 +1,47 @@
+##
+## Payjoin config.toml configuration file. Lines beginning with # are comments.
+##
+
+# Common Settings
+# --------------
+
+# The path to the database file
+db_path = "payjoin.sqlite"
+
+# The maximum fee rate that the receiver is willing to pay (in sat/vB)
+max_fee_rate = 2.0
+
+# Wallet Configuration
+# -------------------
+# Choose ONE backend: esplora or bitcoind
+# 
+# Esplora backend (uses bdk_wallet with esplora API - no full node required):
+# [wallet.esplora]
+# descriptor = "wpkh(tprv8ZgxMBicQKsPd3EupYiPRhaMooHKUHJxNsTfYuScep13go8QFfHdtkG9nRkFGb7busX4isf6X9dURGCoKgitaApQ6MupRhZMcELAxTBRJgS/84'/1'/0'/0/*)"
+# # Optional: change descriptor (auto-derived if not specified)
+# # change_descriptor = "wpkh(tprv8ZgxMBicQKsPd3EupYiPRhaMooHKUHJxNsTfYuScep13go8QFfHdtkG9nRkFGb7busX4isf6X9dURGCoKgitaApQ6MupRhZMcELAxTBRJgS/84'/1'/0'/1/*)"
+# esplora_url = "https://blockstream.info/api"
+# network = "testnet"
+#
+# Bitcoind backend (uses Bitcoin Core RPC - requires full node):
+# [wallet.bitcoind]
+# rpchost = "http://localhost:18443/wallet/payjoin"
+# # Optional: cookie file path (if not using rpcuser/rpcpassword)
+# # cookie = "~/.bitcoin/testnet4/.cookie"
+# # Optional: RPC credentials (if not using cookie)
+# # rpcuser = "user"
+# # rpcpassword = "password"
+
+# Version Configuration
+# -------------------
+# Uncomment ONE of the following version configurations depending on which version you want to use
+
+# Version 1 Configuration
+# [v1]
+# port = 3000
+# pj_endpoint = "https://localhost:3000"
+
+# Version 2 Configuration
+# [v2]
+# pj_directory = "https://payjo.in"
+# ohttp_relays = ["https://pj.benalleng.com", "https://pj.bobspacebkk.com", "https://ohttp.achow101.com"]

payjoin-cli/example.config.toml payjoin-cli/example.bitcoind.config.tomlpayjoin-cli/example.config.toml renamed to payjoin-cli/example.bitcoind.config.toml

@@ -15,6 +15,7 @@ const CONFIG_DIR: &str = "payjoin-cli";
 
 type Builder = config::builder::ConfigBuilder<DefaultState>;
 
+#[cfg(all(feature = "bitcoind", not(feature = "esplora")))]
 #[derive(Debug, Clone, Deserialize)]
 pub struct BitcoindConfig {
     pub rpchost: Url,
@@ -23,6 +24,15 @@ pub struct BitcoindConfig {
     pub rpcpassword: String,
 }
 
+#[cfg(feature = "esplora")]
+#[derive(Debug, Clone, Deserialize)]
+pub struct BdkWalletConfig {
+    pub descriptor: Option<String>,
+    pub change_descriptor: Option<String>,
+    pub esplora_url: Option<String>,
+    pub network: Option<String>,
+}
+
 #[cfg(feature = "v1")]
 #[derive(Debug, Clone, Deserialize)]
 pub struct V1Config {
@@ -55,7 +65,10 @@ pub enum VersionConfig {
 pub struct Config {
     pub db_path: PathBuf,
     pub max_fee_rate: Option<FeeRate>,
+    #[cfg(all(feature = "bitcoind", not(feature = "esplora")))]
     pub bitcoind: BitcoindConfig,
+    #[cfg(feature = "esplora")]
+    pub wallet: Option<BdkWalletConfig>,
     #[serde(skip)]
     pub version: Option<VersionConfig>,
     #[cfg(feature = "_manual-tls")]
@@ -102,7 +115,7 @@ impl Config {
 
     pub(crate) fn new(cli: &Cli) -> Result<Self, ConfigError> {
         let mut config = config::Config::builder();
-        config = add_bitcoind_defaults(config, cli)?;
+        config = add_wallet_defaults(config, cli)?;
         config = add_common_defaults(config, cli)?;
 
         let version = Self::determine_version(cli)?;
@@ -143,7 +156,10 @@ impl Config {
         let mut config = Config {
             db_path: built_config.get("db_path")?,
             max_fee_rate: built_config.get("max_fee_rate").ok(),
+            #[cfg(all(feature = "bitcoind", not(feature = "esplora")))]
             bitcoind: built_config.get("bitcoind")?,
+            #[cfg(feature = "esplora")]
+            wallet: built_config.get("wallet").ok(),
             version: None,
             #[cfg(feature = "_manual-tls")]
             root_certificate: built_config.get("root_certificate").ok(),
@@ -223,16 +239,35 @@ impl Config {
     }
 }
 
-/// Set up default values and CLI overrides for Bitcoin RPC connection settings
-fn add_bitcoind_defaults(config: Builder, cli: &Cli) -> Result<Builder, ConfigError> {
-    // Set default values
+/// Set up default values and CLI overrides for wallet settings
+#[cfg(feature = "esplora")]
+fn add_wallet_defaults(config: Builder, cli: &Cli) -> Result<Builder, ConfigError> {
+    let config = config
+        .set_default("wallet.descriptor", None::<String>)?
+        .set_default("wallet.change_descriptor", None::<String>)?
+        .set_default("wallet.esplora_url", None::<String>)?
+        .set_default("wallet.network", None::<String>)?;
+
+    let descriptor = cli.descriptor.as_deref();
+    let change_descriptor = cli.change_descriptor.as_deref();
+    let esplora_url = cli.esplora_url.as_deref();
+    let network = cli.network.as_deref();
+
+    config
+        .set_override_option("wallet.descriptor", descriptor)?
+        .set_override_option("wallet.change_descriptor", change_descriptor)?
+        .set_override_option("wallet.esplora_url", esplora_url)?
+        .set_override_option("wallet.network", network)
+}
+
+#[cfg(all(feature = "bitcoind", not(feature = "esplora")))]
+fn add_wallet_defaults(config: Builder, cli: &Cli) -> Result<Builder, ConfigError> {
     let config = config
         .set_default("bitcoind.rpchost", "http://localhost:18443")?
         .set_default("bitcoind.cookie", None::<String>)?
         .set_default("bitcoind.rpcuser", "bitcoin")?
         .set_default("bitcoind.rpcpassword", "")?;
 
-    // Override config values with command line arguments if applicable
     let rpchost = cli.rpchost.as_ref().map(|s| s.as_str());
     let cookie_file = cli.cookie_file.as_ref().map(|p| p.to_string_lossy().into_owned());
     let rpcuser = cli.rpcuser.as_deref();
@@ -245,6 +280,9 @@ fn add_bitcoind_defaults(config: Builder, cli: &Cli) -> Result<Builder, ConfigEr
         .set_override_option("bitcoind.rpcpassword", rpcpassword)
 }
 
+#[cfg(all(not(feature = "esplora"), not(feature = "bitcoind")))]
+fn add_wallet_defaults(config: Builder, _cli: &Cli) -> Result<Builder, ConfigError> { Ok(config) }
+
 fn add_common_defaults(config: Builder, cli: &Cli) -> Result<Builder, ConfigError> {
     let db_path = cli.db_path.as_ref().map(|p| p.to_string_lossy().into_owned());
     config.set_default("db_path", db::DB_PATH)?.set_override_option("db_path", db_path)