Skip to content

Commit 98a3bc5

Browse files
CamillarhiCamillarhi
committed
Add payjoin v2 receiver flow
Implements the receiver side of the BIP 77 Payjoin v2 protocol, allowing LDK Node users to receive payjoin payments via a payjoin directory and OHTTP relay. - Adds a `PayjoinPayment` handler exposing a `receive()` method that returns a BIP 21 URI the sender can use to initiate the payjoin flow. The full receiver state machine is implemented covering all `ReceiveSession` states: polling the directory, validating the sender's proposal, contributing inputs, finalizing the PSBT, and monitoring the mempool. - Session state is persisted via `KVStorePayjoinReceiverPersister` and survives node restarts through event log replay. Sender inputs are tracked by `OutPoint` across polling attempts to prevent replay attacks. The sender's fallback transaction is broadcast on cancellation or failure to ensure the receiver still gets paid. - Adds `PaymentKind::Payjoin` to the payment store, `PayjoinConfig` for configuring the payjoin directory and OHTTP relay via `Builder::set_payjoin_config`, and background tasks for session resumption every 15 seconds and cleanup of terminal sessions after 24 hours.
1 parent 9e0a812 commit 98a3bc5

File tree

20 files changed

+1947
-19
lines changed

20 files changed

+1947
-19
lines changed

‎Cargo.toml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -81,6 +81,8 @@ prost = { version = "0.11.6", default-features = false}
8181
#bitcoin-payment-instructions = { version = "0.6" }
8282
bitcoin-payment-instructions = { git = "https://github.com/jkczyz/bitcoin-payment-instructions", rev = "0138feb7acefb1e49102a6fb46d7b776bf43265e" }
8383

84+
payjoin = { git = "https://github.com/payjoin/rust-payjoin.git", rev= "dd21835e55116c681fddae29bf3cd363dd177745", package = "payjoin", default-features = false, features = ["v2", "io"] }
85+
8486
[target.'cfg(windows)'.dependencies]
8587
winapi = { version = "0.3", features = ["winbase"] }
8688

‎bindings/ldk_node.udl‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -97,6 +97,7 @@ interface Node {
9797
SpontaneousPayment spontaneous_payment();
9898
OnchainPayment onchain_payment();
9999
UnifiedPayment unified_payment();
100+
PayjoinPayment payjoin_payment();
100101
LSPS1Liquidity lsps1_liquidity();
101102
[Throws=NodeError]
102103
void lnurl_auth(string lnurl);
@@ -161,6 +162,8 @@ interface FeeRate {
161162

162163
typedef interface UnifiedPayment;
163164

165+
typedef interface PayjoinPayment;
166+
164167
typedef interface LSPS1Liquidity;
165168

166169
[Error]
@@ -188,6 +191,8 @@ enum NodeError {
188191
"OnchainTxSigningFailed",
189192
"TxSyncFailed",
190193
"TxSyncTimeout",
194+
"TxLookupFailed",
195+
"TxLookupTimeout",
191196
"GossipUpdateFailed",
192197
"GossipUpdateTimeout",
193198
"LiquidityRequestFailed",
@@ -225,6 +230,10 @@ enum NodeError {
225230
"LnurlAuthFailed",
226231
"LnurlAuthTimeout",
227232
"InvalidLnurl",
233+
"PayjoinNotConfigured",
234+
"PayjoinSessionCreationFailed",
235+
"PayjoinSessionFailed",
236+
"UnsupportedChainSource"
228237
};
229238

230239
typedef dictionary NodeStatus;

‎src/builder.rs‎

Lines changed: 58 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -45,8 +45,8 @@ use vss_client::headers::VssHeaderProvider;
4545
use crate::chain::ChainSource;
4646
use crate::config::{
4747
default_user_config, may_announce_channel, AnnounceError, AsyncPaymentsRole,
48-
BitcoindRestClientConfig, Config, ElectrumSyncConfig, EsploraSyncConfig, TorConfig,
49-
DEFAULT_ESPLORA_SERVER_URL, DEFAULT_LOG_FILENAME, DEFAULT_LOG_LEVEL,
48+
BitcoindRestClientConfig, Config, ElectrumSyncConfig, EsploraSyncConfig, PayjoinConfig,
49+
TorConfig, DEFAULT_ESPLORA_SERVER_URL, DEFAULT_LOG_FILENAME, DEFAULT_LOG_LEVEL,
5050
};
5151
use crate::connection::ConnectionManager;
5252
use crate::entropy::NodeEntropy;
@@ -56,12 +56,13 @@ use crate::gossip::GossipSource;
5656
use crate::io::sqlite_store::SqliteStore;
5757
use crate::io::utils::{
5858
read_event_queue, read_external_pathfinding_scores_from_cache, read_network_graph,
59-
read_node_metrics, read_output_sweeper, read_payments, read_peer_info, read_pending_payments,
60-
read_scorer, write_node_metrics,
59+
read_node_metrics, read_output_sweeper, read_payjoin_sessions, read_payments, read_peer_info,
60+
read_pending_payments, read_scorer, write_node_metrics,
6161
};
6262
use crate::io::vss_store::VssStoreBuilder;
6363
use crate::io::{
64-
self, PAYMENT_INFO_PERSISTENCE_PRIMARY_NAMESPACE, PAYMENT_INFO_PERSISTENCE_SECONDARY_NAMESPACE,
64+
self, PAYJOIN_SESSION_STORE_PRIMARY_NAMESPACE, PAYJOIN_SESSION_STORE_SECONDARY_NAMESPACE,
65+
PAYMENT_INFO_PERSISTENCE_PRIMARY_NAMESPACE, PAYMENT_INFO_PERSISTENCE_SECONDARY_NAMESPACE,
6566
PENDING_PAYMENT_INFO_PERSISTENCE_PRIMARY_NAMESPACE,
6667
PENDING_PAYMENT_INFO_PERSISTENCE_SECONDARY_NAMESPACE,
6768
};
@@ -72,13 +73,14 @@ use crate::lnurl_auth::LnurlAuth;
7273
use crate::logger::{log_error, LdkLogger, LogLevel, LogWriter, Logger};
7374
use crate::message_handler::NodeCustomMessageHandler;
7475
use crate::payment::asynchronous::om_mailbox::OnionMessageMailbox;
76+
use crate::payment::payjoin::manager::PayjoinManager;
7577
use crate::peer_store::PeerStore;
7678
use crate::runtime::{Runtime, RuntimeSpawner};
7779
use crate::tx_broadcaster::TransactionBroadcaster;
7880
use crate::types::{
7981
AsyncPersister, ChainMonitor, ChannelManager, DynStore, DynStoreWrapper, GossipSync, Graph,
80-
KeysManager, MessageRouter, OnionMessenger, PaymentStore, PeerManager, PendingPaymentStore,
81-
Persister, SyncAndAsyncKVStore,
82+
KeysManager, MessageRouter, OnionMessenger, PayjoinSessionStore, PaymentStore, PeerManager,
83+
PendingPaymentStore, Persister, SyncAndAsyncKVStore,
8284
};
8385
use crate::wallet::persist::KVStoreWalletPersister;
8486
use crate::wallet::Wallet;
@@ -604,6 +606,15 @@ impl NodeBuilder {
604606
Ok(self)
605607
}
606608

609+
/// Configures the [`Node`] instance to enable payjoin payments.
610+
///
611+
/// The `payjoin_config` specifies the PayJoin directory and OHTTP relay URLs required
612+
/// for payjoin V2 protocol.
613+
pub fn set_payjoin_config(&mut self, payjoin_config: PayjoinConfig) -> &mut Self {
614+
self.config.payjoin_config = Some(payjoin_config);
615+
self
616+
}
617+
607618
/// Configures the [`Node`] to resync chain data from genesis on first startup, recovering any
608619
/// historical wallet funds.
609620
///
@@ -1072,6 +1083,14 @@ impl ArcedNodeBuilder {
10721083
self.inner.write().unwrap().set_async_payments_role(role).map(|_| ())
10731084
}
10741085

1086+
/// Configures the [`Node`] instance to enable payjoin payments.
1087+
///
1088+
/// The `payjoin_config` specifies the PayJoin directory and OHTTP relay URLs required
1089+
/// for payjoin V2 protocol.
1090+
pub fn set_payjoin_config(&self, payjoin_config: PayjoinConfig) {
1091+
self.inner.write().unwrap().set_payjoin_config(payjoin_config);
1092+
}
1093+
10751094
/// Configures the [`Node`] to resync chain data from genesis on first startup, recovering any
10761095
/// historical wallet funds.
10771096
///
@@ -1260,12 +1279,13 @@ fn build_with_store_internal(
12601279

12611280
let kv_store_ref = Arc::clone(&kv_store);
12621281
let logger_ref = Arc::clone(&logger);
1263-
let (payment_store_res, node_metris_res, pending_payment_store_res) =
1282+
let (payment_store_res, node_metris_res, pending_payment_store_res, payjoin_session_store_res) =
12641283
runtime.block_on(async move {
12651284
tokio::join!(
12661285
read_payments(&*kv_store_ref, Arc::clone(&logger_ref)),
12671286
read_node_metrics(&*kv_store_ref, Arc::clone(&logger_ref)),
1268-
read_pending_payments(&*kv_store_ref, Arc::clone(&logger_ref))
1287+
read_pending_payments(&*kv_store_ref, Arc::clone(&logger_ref)),
1288+
read_payjoin_sessions(&*kv_store_ref, Arc::clone(&logger_ref))
12691289
)
12701290
});
12711291

@@ -1954,6 +1974,34 @@ fn build_with_store_internal(
19541974

19551975
let pathfinding_scores_sync_url = pathfinding_scores_sync_config.map(|c| c.url.clone());
19561976

1977+
let payjoin_session_store = match payjoin_session_store_res {
1978+
Ok(payjoin_sessions) => Arc::new(PayjoinSessionStore::new(
1979+
payjoin_sessions,
1980+
PAYJOIN_SESSION_STORE_PRIMARY_NAMESPACE.to_string(),
1981+
PAYJOIN_SESSION_STORE_SECONDARY_NAMESPACE.to_string(),
1982+
Arc::clone(&kv_store),
1983+
Arc::clone(&logger),
1984+
)),
1985+
Err(e) => {
1986+
log_error!(logger, "Failed to read payjoin session data from store: {}", e);
1987+
return Err(BuildError::ReadFailed);
1988+
},
1989+
};
1990+
1991+
let payjoin_manager = Arc::new(PayjoinManager::new(
1992+
Arc::clone(&payjoin_session_store),
1993+
Arc::clone(&logger),
1994+
Arc::clone(&config),
1995+
Arc::clone(&wallet),
1996+
Arc::clone(&fee_estimator),
1997+
Arc::clone(&chain_source),
1998+
Arc::clone(&channel_manager),
1999+
stop_sender.subscribe(),
2000+
Arc::clone(&payment_store),
2001+
Arc::clone(&pending_payment_store),
2002+
Arc::clone(&tx_broadcaster),
2003+
));
2004+
19572005
#[cfg(cycle_tests)]
19582006
let mut _leak_checker = crate::LeakChecker(Vec::new());
19592007
#[cfg(cycle_tests)]
@@ -2001,6 +2049,7 @@ fn build_with_store_internal(
20012049
hrn_resolver,
20022050
#[cfg(cycle_tests)]
20032051
_leak_checker,
2052+
payjoin_manager,
20042053
})
20052054
}
20062055

‎src/chain/bitcoind.rs‎

Lines changed: 97 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -33,7 +33,7 @@ use serde::Serialize;
3333
use super::WalletSyncStatus;
3434
use crate::config::{
3535
BitcoindRestClientConfig, Config, DEFAULT_FEE_RATE_CACHE_UPDATE_TIMEOUT_SECS,
36-
DEFAULT_TX_BROADCAST_TIMEOUT_SECS,
36+
DEFAULT_TX_BROADCAST_TIMEOUT_SECS, DEFAULT_TX_LOOKUP_TIMEOUT_SECS,
3737
};
3838
use crate::fee_estimator::{
3939
apply_post_estimation_adjustments, get_all_conf_targets, get_num_block_defaults_for_target,
@@ -620,6 +620,57 @@ impl BitcoindChainSource {
620620
}
621621
}
622622
}
623+
624+
pub(crate) async fn can_broadcast_transaction(&self, tx: &Transaction) -> Result<bool, Error> {
625+
let timeout_fut = tokio::time::timeout(
626+
Duration::from_secs(DEFAULT_TX_LOOKUP_TIMEOUT_SECS),
627+
self.api_client.test_mempool_accept(tx),
628+
);
629+
630+
match timeout_fut.await {
631+
Ok(res) => res.map_err(|e| {
632+
log_error!(
633+
self.logger,
634+
"Failed to test mempool accept for transaction {}: {}",
635+
tx.compute_txid(),
636+
e
637+
);
638+
Error::WalletOperationFailed
639+
}),
640+
Err(e) => {
641+
log_error!(
642+
self.logger,
643+
"Failed to test mempool accept for transaction {} due to timeout: {}",
644+
tx.compute_txid(),
645+
e
646+
);
647+
log_trace!(
648+
self.logger,
649+
"Failed test mempool accept transaction bytes: {}",
650+
log_bytes!(tx.encode())
651+
);
652+
Err(Error::WalletOperationTimeout)
653+
},
654+
}
655+
}
656+
657+
pub(crate) async fn get_transaction(&self, txid: &Txid) -> Result<Option<Transaction>, Error> {
658+
let timeout_fut = tokio::time::timeout(
659+
Duration::from_secs(DEFAULT_TX_LOOKUP_TIMEOUT_SECS),
660+
self.api_client.get_raw_transaction(txid),
661+
);
662+
663+
match timeout_fut.await {
664+
Ok(res) => res.map_err(|e| {
665+
log_error!(self.logger, "Failed to get transaction {}: {}", txid, e);
666+
Error::TxLookupFailed
667+
}),
668+
Err(e) => {
669+
log_error!(self.logger, "Failed to get transaction {} due to timeout: {}", txid, e);
670+
Err(Error::TxLookupTimeout)
671+
},
672+
}
673+
}
623674
}
624675

625676
#[derive(Clone)]
@@ -1179,6 +1230,34 @@ impl BitcoindClient {
11791230
.collect();
11801231
Ok(evicted_txids)
11811232
}
1233+
1234+
/// Tests whether the provided transaction would be accepted by the mempool.
1235+
pub(crate) async fn test_mempool_accept(
1236+
&self, tx: &Transaction,
1237+
) -> Result<bool, RpcClientError> {
1238+
match self {
1239+
BitcoindClient::Rpc { rpc_client, .. } => {
1240+
Self::test_mempool_accept_inner(Arc::clone(rpc_client), tx).await
1241+
},
1242+
BitcoindClient::Rest { rpc_client, .. } => {
1243+
// We rely on the internal RPC client to make this call, as this
1244+
// operation is not supported by Bitcoin Core's REST interface.
1245+
Self::test_mempool_accept_inner(Arc::clone(rpc_client), tx).await
1246+
},
1247+
}
1248+
}
1249+
1250+
async fn test_mempool_accept_inner(
1251+
rpc_client: Arc<RpcClient>, tx: &Transaction,
1252+
) -> Result<bool, RpcClientError> {
1253+
let tx_serialized = bitcoin::consensus::encode::serialize_hex(tx);
1254+
let tx_array = serde_json::json!([tx_serialized]);
1255+
1256+
rpc_client
1257+
.call_method::<TestMempoolAcceptResponse>("testmempoolaccept", &[tx_array])
1258+
.await
1259+
.map(|resp| resp.0)
1260+
}
11821261
}
11831262

11841263
impl BlockSource for BitcoindClient {
@@ -1334,6 +1413,23 @@ impl TryInto<GetMempoolEntryResponse> for JsonResponse {
13341413
}
13351414
}
13361415

1416+
pub(crate) struct TestMempoolAcceptResponse(pub bool);
1417+
1418+
impl TryInto<TestMempoolAcceptResponse> for JsonResponse {
1419+
type Error = String;
1420+
fn try_into(self) -> Result<TestMempoolAcceptResponse, String> {
1421+
let array =
1422+
self.0.as_array().ok_or("Failed to parse testmempoolaccept response".to_string())?;
1423+
let first =
1424+
array.first().ok_or("Empty array response from testmempoolaccept".to_string())?;
1425+
let allowed = first
1426+
.get("allowed")
1427+
.and_then(|v| v.as_bool())
1428+
.ok_or("Missing 'allowed' field in testmempoolaccept response".to_string())?;
1429+
Ok(TestMempoolAcceptResponse(allowed))
1430+
}
1431+
}
1432+
13371433
#[derive(Debug, Clone)]
13381434
pub(crate) struct MempoolEntry {
13391435
/// The transaction id

‎src/chain/electrum.rs‎

Lines changed: 50 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -18,13 +18,16 @@ use bdk_wallet::{KeychainKind as BdkKeyChainKind, Update as BdkUpdate};
1818
use bitcoin::{FeeRate, Network, Script, ScriptBuf, Transaction, Txid};
1919
use electrum_client::{
2020
Batch, Client as ElectrumClient, ConfigBuilder as ElectrumConfigBuilder, ElectrumApi,
21+
Error as ElectrumError,
2122
};
2223
use lightning::chain::{Confirm, Filter, WatchedOutput};
2324
use lightning::util::ser::Writeable;
2425
use lightning_transaction_sync::ElectrumSyncClient;
2526

2627
use super::WalletSyncStatus;
27-
use crate::config::{Config, ElectrumSyncConfig, BDK_CLIENT_STOP_GAP};
28+
use crate::config::{
29+
Config, ElectrumSyncConfig, BDK_CLIENT_STOP_GAP, DEFAULT_TX_LOOKUP_TIMEOUT_SECS,
30+
};
2831
use crate::error::Error;
2932
use crate::fee_estimator::{
3033
apply_post_estimation_adjustments, get_all_conf_targets, get_num_block_defaults_for_target,
@@ -288,6 +291,21 @@ impl ElectrumChainSource {
288291
electrum_client.broadcast(tx).await;
289292
}
290293
}
294+
295+
pub(crate) async fn get_transaction(&self, txid: &Txid) -> Result<Option<Transaction>, Error> {
296+
let electrum_client: Arc<ElectrumRuntimeClient> =
297+
if let Some(client) = self.electrum_runtime_status.read().unwrap().client().as_ref() {
298+
Arc::clone(client)
299+
} else {
300+
debug_assert!(
301+
false,
302+
"We should have started the chain source before getting transactions"
303+
);
304+
return Err(Error::TxLookupTimeout);
305+
};
306+
307+
electrum_client.get_transaction(txid).await
308+
}
291309
}
292310

293311
impl Filter for ElectrumChainSource {
@@ -652,6 +670,37 @@ impl ElectrumRuntimeClient {
652670

653671
Ok(new_fee_rate_cache)
654672
}
673+
674+
async fn get_transaction(&self, txid: &Txid) -> Result<Option<Transaction>, Error> {
675+
let electrum_client = Arc::clone(&self.electrum_client);
676+
let txid_copy = *txid;
677+
678+
let spawn_fut =
679+
self.runtime.spawn_blocking(move || electrum_client.transaction_get(&txid_copy));
680+
let timeout_fut =
681+
tokio::time::timeout(Duration::from_secs(DEFAULT_TX_LOOKUP_TIMEOUT_SECS), spawn_fut);
682+
683+
match timeout_fut.await {
684+
Ok(res) => match res {
685+
Ok(inner_res) => match inner_res {
686+
Ok(tx) => Ok(Some(tx)),
687+
Err(ElectrumError::Protocol(_)) => Ok(None),
688+
Err(e) => {
689+
log_error!(self.logger, "Failed to get transaction {}: {}", txid, e);
690+
Err(Error::TxLookupFailed)
691+
},
692+
},
693+
Err(e) => {
694+
log_error!(self.logger, "Failed to get transaction {}: {}", txid, e);
695+
Err(Error::TxLookupFailed)
696+
},
697+
},
698+
Err(e) => {
699+
log_error!(self.logger, "Failed to get transaction {} due to timeout: {}", txid, e);
700+
Err(Error::TxLookupTimeout)
701+
},
702+
}
703+
}
655704
}
656705

657706
impl Filter for ElectrumRuntimeClient {

‎src/chain/esplora.rs‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -422,6 +422,13 @@ impl EsploraChainSource {
422422
}
423423
}
424424
}
425+
426+
pub(crate) async fn get_transaction(&self, txid: &Txid) -> Result<Option<Transaction>, Error> {
427+
self.esplora_client.get_tx(txid).await.map_err(|e| {
428+
log_error!(self.logger, "Failed to get transaction {}: {}", txid, e);
429+
Error::TxLookupFailed
430+
})
431+
}
425432
}
426433

427434
impl Filter for EsploraChainSource {

0 commit comments

Comments
 (0)