Add optional esplora wallet setup for payjoin-cli backend

Cargo-recent.lock

@@ -433,12 +433,12 @@ dependencies = [
  "bip39",
  "bitcoin 0.30.2",
  "core-rpc",
- "electrum-client",
- "esplora-client",
+ "electrum-client 0.18.0",
+ "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"
@@ -1358,6 +1407,22 @@ version = "1.15.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "48c757948c5ede0e46177b7add2e67155f70e33c07fea8284df6576da70b3719"
 
+[[package]]
+name = "electrsd"
+version = "0.36.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d8926868af723c2819807809e54585992aaea0e26a6f5089ac8c2598eaec8d01"
+dependencies = [
+ "bitcoin_hashes 0.14.0",
+ "corepc-client",
+ "corepc-node",
+ "electrum-client 0.24.1",
+ "log",
+ "minreq",
+ "nix 0.25.1",
+ "zip",
+]
+
 [[package]]
 name = "electrum-client"
 version = "0.18.0"
@@ -1377,6 +1442,18 @@ dependencies = [
  "winapi",
 ]
 
+[[package]]
+name = "electrum-client"
+version = "0.24.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a5059f13888a90486e7268bbce59b175f5f76b1c55e5b9c568ceaa42d2b8507c"
+dependencies = [
+ "bitcoin 0.32.8",
+ "log",
+ "serde",
+ "serde_json",
+]
+
 [[package]]
 name = "encoding_rs"
 version = "0.8.35"
@@ -1425,6 +1502,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 +1835,7 @@ checksum = "e5274423e17b7c9fc20b6e7e208532f9b19825d82dfd615708b70edd83df41f1"
 dependencies = [
  "ahash",
  "allocator-api2",
+ "serde",
 ]
 
 [[package]]
@@ -2375,6 +2468,15 @@ version = "2.7.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "78ca9ab1a0babb1e7d5695e3530886289c18cf2f87ec19a575a0abdce112e3a3"
 
+[[package]]
+name = "memoffset"
+version = "0.6.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5aa361d4faea93603064a027415f07bd8e1d5c88c9fbf68bf56a285428fd79ce"
+dependencies = [
+ "autocfg",
+]
+
 [[package]]
 name = "mime"
 version = "0.3.17"
@@ -2398,6 +2500,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"
@@ -2459,6 +2572,20 @@ dependencies = [
  "tokio",
 ]
 
+[[package]]
+name = "nix"
+version = "0.25.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f346ff70e7dbfd675fe90590b92d59ef2de15a8779ae305ebcbfd3f0caf59be4"
+dependencies = [
+ "autocfg",
+ "bitflags 1.3.2",
+ "cfg-if",
+ "libc",
+ "memoffset",
+ "pin-utils",
+]
+
 [[package]]
 name = "nix"
 version = "0.26.4"
@@ -2753,10 +2880,14 @@ version = "0.2.0"
 dependencies = [
  "anyhow",
  "async-trait",
+ "bdk_esplora",
+ "bdk_wallet",
  "bitcoind-async-client",
  "clap 4.5.46",
  "config",
  "dirs",
+ "electrsd",
+ "esplora-client 0.12.3",
  "http-body-util",
  "hyper",
  "hyper-util",

contrib/coverage.sh

@@ -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

flake.nix

@@ -128,6 +128,12 @@
           }
         ) craneLibVersions;
 
+        # nixpkgs' blockstream-electrs build runs a flaky `test_electrum`
+        # integration test that fails on some sandboxes. Skip its checks.
+        blockstreamElectrs = pkgs.blockstream-electrs.overrideAttrs (_: {
+          doCheck = false;
+        });
+
         commonArgs = {
           inherit src;
           strictDeps = true;
@@ -140,6 +146,8 @@
 
           # tell bitcoind crate not to try to download during build
           BITCOIND_SKIP_DOWNLOAD = 1;
+          # same for electrsd (used in payjoin-cli esplora e2e tests)
+          ELECTRSD_SKIP_DOWNLOAD = 1;
         };
 
         # Per-toolchain common args that include pre-vendored deps
@@ -276,6 +284,8 @@
               ];
             BITCOIND_EXE = pkgs.lib.getExe' pkgs.bitcoind "bitcoind";
             BITCOIND_SKIP_DOWNLOAD = 1;
+            ELECTRS_EXE = pkgs.lib.getExe' blockstreamElectrs "electrs";
+            ELECTRSD_SKIP_DOWNLOAD = 1;
           }
         ) craneLibVersions;
 
@@ -375,8 +385,12 @@
                   partitionType = "count";
                   cargoExtraArgs = "--locked --workspace --all-features --exclude payjoin-fuzz";
                   BITCOIND_EXE = nixpkgs.lib.getExe' pkgs.bitcoind "bitcoind";
+                  ELECTRS_EXE = nixpkgs.lib.getExe' blockstreamElectrs "electrs";
                   NGINX_EXE = nixpkgs.lib.getExe' nginxWithStream "nginx";
-                  nativeBuildInputs = [ nginxWithStream ];
+                  nativeBuildInputs = [
+                    nginxWithStream
+                    blockstreamElectrs
+                  ];
                   doInstallCargoArtifacts = false;
                 }
               )

payjoin-cli/Cargo.toml

@@ -19,19 +19,31 @@ 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", "bitcoind"]
 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"
+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 }
 clap = { version = "4.5.45", features = ["derive"] }
 config = "0.15.14"
 dirs = "6.0.0"
+esplora-client = { version = "0.12", default-features = false, features = [
+  "async-https-rustls",
+  "tokio",
+], optional = true }
 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 }
@@ -57,3 +69,10 @@ url = { version = "2.5.4", features = ["serde"] }
 nix = { version = "0.30.1", features = ["aio", "process", "signal"] }
 payjoin-test-utils = { version = "0.0.1" }
 tempfile = "3.20.0"
+# End-to-end coverage for the esplora backend spins up electrs against
+# the bitcoind started by payjoin-test-utils. The `legacy` electrs
+# binary exposes an HTTP REST API compatible with bdk_esplora when
+# `http_enabled` is set on its Conf.
+electrsd = { version = "0.36.1", default-features = false, features = [
+  "esplora_a33e97e1",
+] }

payjoin-cli/contrib/lint.sh

@@ -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/test.sh

@@ -1,4 +1,6 @@
 #!/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,_esplora,native-certs"
+
+cargo test --locked --package payjoin-cli --verbose --no-default-features --features "v1,v2,_manual-tls,bitcoind,native-certs"

payjoin-cli/example.esplora.config.toml

@@ -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"]