Implement PayjoinPayment ..

Payjoin [`BIP77`] implementation. Compatible with previous Payjoin version [`BIP78`].

Should be retrieved by calling [`Node::payjoin_payment`].

Payjoin transactions can be used to improve privacy by breaking the common-input-ownership
heuristic when Payjoin receivers contribute input(s) to the transaction. They can also be used
to save on fees, as the Payjoin receiver can direct the incoming funds to open a lightning
channel, forwards the funds to another address, or simply consolidate UTXOs.

In a Payjoin transaction, both the sender and receiver contribute inputs to the transaction in
a coordinated manner. The Payjoin mechanism is also called pay-to-endpoint(P2EP).  The Payjoin
receiver endpoint address is communicated through a [`BIP21`] URI, along with the payment
address and an optional amount parameter.  In the Payjoin process, parties edit, sign and pass
iterations of the transaction between each other, before a final version is broadcasted by the
Payjoin sender.  [`BIP77`] codifies a protocol with 2 iterations (or one round of interaction
beyond address sharing).

[`BIP77`] Defines the Payjoin process to happen asynchronously, with the Payjoin receiver
enrolling with a Payjoin Directory to receive Payjoin requests. The Payjoin sender can then
make requests through a proxy server, Payjoin Relay, to the Payjoin receiver even if the
receiver is offline. This mechanism requires the Payjoin sender to regularly check for response
from the Payjoin receiver as implemented in [`Node::payjoin_payment::send`].

A Payjoin Relay is a proxy server that forwards Payjoin requests from the Payjoin sender to the
Payjoin receiver subdirectory. A Payjoin Relay can be run by anyone. Public Payjoin Relay
servers are:
- <https://pj.bobspacebkk.com>

A Payjoin directory is a service that allows Payjoin receivers to receive Payjoin requests
offline. A Payjoin directory can be run by anyone. Public Payjoin Directory servers are:
- <https://payjo.in>

Author: jbesraa

Cargo.toml

@@ -69,6 +69,7 @@ tokio = { version = "1.37", default-features = false, features = [ "rt-multi-thr
 esplora-client = { version = "0.6", default-features = false }
 libc = "0.2"
 uniffi = { version = "0.26.0", features = ["build"], optional = true }
+payjoin = { version = "0.16.0", default-features = false, features = ["send", "v2"] }
 
 [target.'cfg(vss)'.dependencies]
 vss-client = "0.2"

src/config.rs

@@ -40,6 +40,15 @@ pub(crate) const RESOLVED_CHANNEL_MONITOR_ARCHIVAL_INTERVAL: u32 = 6;
 // The time in-between peer reconnection attempts.
 pub(crate) const PEER_RECONNECTION_INTERVAL: Duration = Duration::from_secs(10);
 
+// The time before a payjoin http request is considered timed out.
+pub(crate) const PAYJOIN_REQUEST_TIMEOUT: Duration = Duration::from_secs(30);
+
+// The duration between retries of a payjoin http request.
+pub(crate) const PAYJOIN_RETRY_INTERVAL: Duration = Duration::from_secs(3);
+
+// The total duration of retrying to send a payjoin http request.
+pub(crate) const PAYJOIN_REQUEST_TOTAL_DURATION: Duration = Duration::from_secs(24 * 60 * 60);
+
 // The time in-between RGS sync attempts.
 pub(crate) const RGS_SYNC_INTERVAL: Duration = Duration::from_secs(60 * 60);
 

src/error.rs

@@ -99,6 +99,18 @@ pub enum Error {
 	LiquiditySourceUnavailable,
 	/// The given operation failed due to the LSP's required opening fee being too high.
 	LiquidityFeeTooHigh,
+	/// Failed to access Payjoin object.
+	PayjoinUnavailable,
+	/// Payjoin URI is invalid.
+	PayjoinUriInvalid,
+	/// Amount is neither user-provided nor defined in the URI.
+	PayjoinRequestMissingAmount,
+	/// Failed to build a Payjoin request.
+	PayjoinRequestCreationFailed,
+	/// Failed to send Payjoin request.
+	PayjoinRequestSendingFailed,
+	/// Payjoin response processing failed.
+	PayjoinResponseProcessingFailed,
 }
 
 impl fmt::Display for Error {
@@ -168,6 +180,30 @@ impl fmt::Display for Error {
 			Self::LiquidityFeeTooHigh => {
 				write!(f, "The given operation failed due to the LSP's required opening fee being too high.")
 			},
+			Self::PayjoinUnavailable => {
+				write!(
+					f,
+					"Failed to access Payjoin object. Make sure you have enabled Payjoin support."
+				)
+			},
+			Self::PayjoinRequestMissingAmount => {
+				write!(
+					f,
+					"Amount is neither user-provided nor defined in the provided Payjoin URI."
+				)
+			},
+			Self::PayjoinRequestCreationFailed => {
+				write!(f, "Failed construct a Payjoin request")
+			},
+			Self::PayjoinUriInvalid => {
+				write!(f, "The provided Payjoin URI is invalid")
+			},
+			Self::PayjoinRequestSendingFailed => {
+				write!(f, "Failed to send Payjoin request")
+			},
+			Self::PayjoinResponseProcessingFailed => {
+				write!(f, "Payjoin receiver responded to our request with an invalid response")
+			},
 		}
 	}
 }

src/event.rs

@@ -142,6 +142,66 @@ pub enum Event {
 		/// This will be `None` for events serialized by LDK Node v0.2.1 and prior.
 		reason: Option<ClosureReason>,
 	},
+	/// This event is emitted when we have successfully negotiated a Payjoin transaction with the
+	/// receiver and are waiting for the transaction to be confirmed onchain.
+	PayjoinPaymentAwaitingConfirmation {
+		/// Transaction ID of the finalised Payjoin transaction. i.e., the final transaction after
+		/// we have successfully negotiated with the receiver.
+		txid: bitcoin::Txid,
+		/// Transaction amount as specified in the Payjoin URI in case of using
+		/// [`PayjoinPayment::send`] or as specified by the user if using
+		/// [`PayjoinPayment::send_with_amount`].
+		///
+		/// [`PayjoinPayment::send`]: crate::PayjoinPayment::send
+		/// [`PayjoinPayment::send_with_amount`]: crate::PayjoinPayment::send_with_amount
+		amount_sats: u64,
+	},
+	/// This event is emitted when a Payjoin transaction has been successfully confirmed onchain.
+	///
+	/// This event is emitted only after one onchain confirmation. To determine the current number
+	/// of confirmations, refer to [`PaymentStore::best_block`]:.
+	///
+	/// [`PaymentStore::best_block`]: crate::payment::store::PaymentStore::best_block
+	PayjoinPaymentSuccessful {
+		/// This can refer to the original PSBT or to the finalised Payjoin transaction.
+		///
+		/// If [`is_original_psbt_modified`] field is `true`, this refers to the finalised Payjoin
+		/// transaction. Otherwise, it refers to the original PSBT.
+		///
+		/// In case of this being the original PSBT, the transaction will be a regular transaction
+		/// and not a Payjoin transaction but will be considered successful as the receiver decided
+		/// to broadcast the original PSBT or to respond with a Payjoin proposal that was identical
+		/// to the original PSBT, and they have successfully received the funds.
+		txid: bitcoin::Txid,
+		/// Transaction amount as specified in the Payjoin URI in case of using
+		/// [`PayjoinPayment::send`] or as specified by the user if using
+		/// [`PayjoinPayment::send_with_amount`].
+		///
+		/// [`PayjoinPayment::send`]: crate::PayjoinPayment::send
+		/// [`PayjoinPayment::send_with_amount`]: crate::PayjoinPayment::send_with_amount
+		amount_sats: u64,
+		/// Indicates whether the Payjoin negotiation was successful or the receiver decided to
+		/// broadcast the original PSBT.
+		is_original_psbt_modified: bool,
+	},
+	/// Failed to send a Payjoin transaction.
+	///
+	/// Payjoin payment can fail in different stages due to various reasons, such as network
+	/// issues, insufficient funds, irresponsive receiver, etc.
+	PayjoinPaymentFailed {
+		/// This can refer to the original PSBT or to the finalised Payjoin transaction. Depending
+		/// on the stage of the Payjoin process when the failure occurred.
+		txid: bitcoin::Txid,
+		/// Transaction amount as specified in the Payjoin URI in case of using
+		/// [`PayjoinPayment::send`] or as specified by the user if using
+		/// [`PayjoinPayment::send_with_amount`].
+		///
+		/// [`PayjoinPayment::send`]: crate::PayjoinPayment::send
+		/// [`PayjoinPayment::send_with_amount`]: crate::PayjoinPayment::send_with_amount
+		amount_sats: u64,
+		/// Failure reason.
+		reason: PayjoinPaymentFailureReason,
+	},
 }
 
 impl_writeable_tlv_based_enum!(Event,
@@ -183,9 +243,52 @@ impl_writeable_tlv_based_enum!(Event,
 		(2, payment_id, required),
 		(4, claimable_amount_msat, required),
 		(6, claim_deadline, option),
+	},
+	(7, PayjoinPaymentAwaitingConfirmation) => {
+		(0, txid, required),
+		(2, amount_sats, required),
+	},
+	(9, PayjoinPaymentSuccessful) => {
+		(0, txid, required),
+		(2, amount_sats, required),
+		(4, is_original_psbt_modified, required),
+	},
+	(10, PayjoinPaymentFailed) => {
+		(0, amount_sats, required),
+		(2, txid, required),
+		(4, reason, required),
 	};
 );
 
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum PayjoinPaymentFailureReason {
+	/// The request failed in the sending process, i.e., either no funds were available to send or
+	/// the provided Payjoin URI is invalid or network problem encountered while communicating with
+	/// the Payjoin relay/directory.  The exact reason can be determined by inspecting the logs.
+	RequestSendingFailed,
+	/// The received response was invalid, i.e., the receiver responded with an invalid Payjoin
+	/// proposal that does not adhere to the [`BIP78`] specification.
+	///
+	/// This is considered a failure but the receiver can still broadcast the original PSBT, in
+	/// which case a `PayjoinPaymentSuccessful` event will be emitted with
+	/// `is_original_psbt_modified` set to `false` and the `txid` of the original PSBT.
+	///
+	/// [`BIP78`]: https://github.com/bitcoin/bips/blob/master/bip-0078.mediawiki
+	ResponseProcessingFailed,
+	/// The request failed as we did not receive a response in time.
+	///
+	/// This is considered a failure but the receiver can still broadcast the original PSBT, in
+	/// which case a `PayjoinPaymentSuccessful` event will be emitted with
+	/// `is_original_psbt_modified` set to `false` and the `txid` of the original PSBT.
+	Timeout,
+}
+
+impl_writeable_tlv_based_enum!(PayjoinPaymentFailureReason,
+	(0, Timeout) => {},
+	(1, RequestSendingFailed) => {},
+	(2, ResponseProcessingFailed) => {};
+);
+
 pub struct EventQueue<L: Deref>
 where
 	L::Target: Logger,

src/payment/mod.rs

@@ -3,10 +3,12 @@
 mod bolt11;
 mod bolt12;
 mod onchain;
+pub(crate) mod payjoin;
 mod spontaneous;
 pub(crate) mod store;
 mod unified_qr;
 
+pub use self::payjoin::PayjoinPayment;
 pub use bolt11::Bolt11Payment;
 pub use bolt12::Bolt12Payment;
 pub use onchain::OnchainPayment;

src/payment/payjoin/handler.rs

@@ -0,0 +1,168 @@
+use bitcoin::address::NetworkChecked;
+use bitcoin::psbt::Psbt;
+use bitcoin::{Script, Transaction, Txid};
+
+use crate::config::PAYJOIN_REQUEST_TIMEOUT;
+use crate::error::Error;
+use crate::event::PayjoinPaymentFailureReason;
+use crate::logger::FilesystemLogger;
+use crate::payment::store::PaymentDetailsUpdate;
+use crate::payment::PaymentKind;
+use crate::payment::{PaymentDirection, PaymentStatus};
+use crate::types::{ChainSource, EventQueue, PaymentStore, Wallet};
+use crate::Event;
+use crate::PaymentDetails;
+
+use lightning::chain::Filter;
+use lightning::ln::channelmanager::PaymentId;
+use lightning::log_error;
+use lightning::util::logger::Logger;
+
+use std::sync::Arc;
+
+pub(crate) struct PayjoinHandler {
+	chain_source: Arc<ChainSource>,
+	event_queue: Arc<EventQueue>,
+	logger: Arc<FilesystemLogger>,
+	payjoin_relay: payjoin::Url,
+	payment_store: Arc<PaymentStore>,
+	wallet: Arc<Wallet>,
+}
+
+impl PayjoinHandler {
+	pub(crate) fn new(
+		chain_source: Arc<ChainSource>, event_queue: Arc<EventQueue>,
+		logger: Arc<FilesystemLogger>, payjoin_relay: payjoin::Url,
+		payment_store: Arc<PaymentStore>, wallet: Arc<Wallet>,
+	) -> Self {
+		Self { chain_source, event_queue, logger, payjoin_relay, payment_store, wallet }
+	}
+
+	pub(crate) fn start_request(
+		&self, payjoin_uri: payjoin::Uri<'_, NetworkChecked>,
+	) -> Result<Psbt, Error> {
+		let amount = payjoin_uri.amount.ok_or(Error::PayjoinRequestMissingAmount)?;
+		let receiver = payjoin_uri.address.clone();
+		let original_psbt =
+			self.wallet.build_payjoin_transaction(amount, receiver.clone().into())?;
+		let tx = original_psbt.clone().unsigned_tx;
+		let payment_id = self.payment_id(&original_psbt.unsigned_tx.txid());
+		self.payment_store.insert(PaymentDetails::new(
+			payment_id,
+			PaymentKind::Payjoin,
+			Some(amount.to_sat()),
+			PaymentDirection::Outbound,
+			PaymentStatus::Pending,
+		))?;
+		let mut update_payment = PaymentDetailsUpdate::new(payment_id);
+		update_payment.txid = Some(tx.txid());
+		let _ = self.payment_store.update(&update_payment);
+		self.chain_source.register_tx(&tx.txid(), Script::empty());
+		Ok(original_psbt)
+	}
+
+	pub(crate) async fn send_request(
+		&self, payjoin_uri: payjoin::Uri<'_, NetworkChecked>, original_psbt: &mut Psbt,
+	) -> Result<Option<Psbt>, Error> {
+		let (request, context) = payjoin::send::RequestBuilder::from_psbt_and_uri(
+			original_psbt.clone(),
+			payjoin_uri.clone(),
+		)
+		.and_then(|b| b.build_non_incentivizing())
+		.and_then(|mut c| c.extract_v2(self.payjoin_relay.clone()))
+		.map_err(|e| {
+			log_error!(self.logger, "Failed to create Payjoin request: {}", e);
+			Error::PayjoinRequestCreationFailed
+		})?;
+		let mut headers = reqwest::header::HeaderMap::new();
+		headers.insert(
+			reqwest::header::CONTENT_TYPE,
+			reqwest::header::HeaderValue::from_static("message/ohttp-req"),
+		);
+		let response = reqwest::Client::new()
+			.post(request.url.clone())
+			.body(request.body.clone())
+			.timeout(PAYJOIN_REQUEST_TIMEOUT)
+			.headers(headers)
+			.send()
+			.await
+			.and_then(|r| r.error_for_status())
+			.map_err(|e| {
+				log_error!(self.logger, "Failed to send Payjoin request: {}", e);
+				Error::PayjoinRequestSendingFailed
+			})?;
+		let response = response.bytes().await.map_err(|e| {
+			log_error!(
+				self.logger,
+				"Failed to send Payjoin request, receiver invalid response: {}",
+				e
+			);
+			Error::PayjoinRequestSendingFailed
+		})?;
+		let response = response.to_vec();
+		context.process_response(&mut response.as_slice()).map_err(|e| {
+			log_error!(self.logger, "Failed to process Payjoin response: {}", e);
+			Error::PayjoinResponseProcessingFailed
+		})
+	}
+
+	pub(crate) fn process_response(
+		&self, payjoin_proposal: &mut Psbt, original_psbt: &mut Psbt,
+	) -> Result<Transaction, Error> {
+		let wallet = self.wallet.clone();
+		wallet.sign_payjoin_proposal(payjoin_proposal, original_psbt)?;
+		let proposal_tx = payjoin_proposal.clone().extract_tx();
+		let payment_store = self.payment_store.clone();
+		let payment_id = self.payment_id(&original_psbt.unsigned_tx.txid());
+		let payment_details = payment_store.get(&payment_id);
+		if let Some(payment_details) = payment_details {
+			let txid = proposal_tx.txid();
+			let mut payment_update = PaymentDetailsUpdate::new(payment_id);
+			payment_update.txid = Some(txid);
+			payment_store.update(&payment_update)?;
+			self.chain_source.register_tx(&txid, Script::empty());
+			self.event_queue.add_event(Event::PayjoinPaymentAwaitingConfirmation {
+				txid,
+				amount_sats: payment_details
+					.amount_msat
+					.ok_or(Error::PayjoinRequestMissingAmount)?,
+			})?;
+			Ok(proposal_tx)
+		} else {
+			log_error!(self.logger, "Failed to process Payjoin response: transaction not found");
+			Err(Error::PayjoinResponseProcessingFailed)
+		}
+	}
+
+	fn payment_id(&self, original_psbt_txid: &Txid) -> PaymentId {
+		let payment_id: [u8; 32] =
+			original_psbt_txid[..].try_into().expect("Unreachable, Txid is 32 bytes");
+		PaymentId(payment_id)
+	}
+
+	pub(crate) fn handle_request_failure(
+		&self, original_psbt: &Psbt, reason: PayjoinPaymentFailureReason,
+	) -> Result<(), Error> {
+		let payment_store = self.payment_store.clone();
+		let payment_id = &self.payment_id(&original_psbt.unsigned_tx.txid());
+		let payment_details = payment_store.get(payment_id);
+		if let Some(payment_details) = payment_details {
+			let mut update_details = PaymentDetailsUpdate::new(payment_id.clone());
+			update_details.status = Some(PaymentStatus::Failed);
+			let _ = payment_store.update(&update_details);
+			self.event_queue.add_event(Event::PayjoinPaymentFailed {
+				txid: original_psbt.unsigned_tx.txid(),
+				amount_sats: payment_details
+					.amount_msat
+					.ok_or(Error::PayjoinRequestMissingAmount)?,
+				reason,
+			})
+		} else {
+			log_error!(
+				self.logger,
+				"Failed to handle request failure for Payjoin payment: transaction not found"
+			);
+			Err(Error::PayjoinRequestSendingFailed)
+		}
+	}
+}