Implement generic Receiver::cancel() method

This exposes a public API for canceling an active Payjoin session. This
serves both manual triggers such as user action to "accelerate" a
payment by immediately broadcasting the fallback, or automatic ones such
as receiver wallet incapable of providing suitable inputs for a Payjoin.

When applicable, it returns the fallback transaction both as a
convenience and as a "hint" for the implementer to broadcast it now that
the Payjoin is canceled.

Author: spacebear21

payjoin/src/core/persist.rs

@@ -460,6 +460,40 @@ impl<Event, NextState> NextStateTransition<Event, NextState> {
     }
 }
 
+/// A transition that unconditionally terminates the session.
+///
+/// Unlike other transition types, this always succeeds at the protocol level
+/// (the only possible error is from the persister's storage layer).
+/// After saving, the session is closed and no further events can be appended.
+///
+/// The `T` parameter carries a value that is returned after saving without
+/// being persisted. This lets callers receive derived data (e.g. a fallback
+/// transaction) through the same `.save()` call pattern used by every other
+/// transition type.
+pub struct TerminalTransition<Event, T>(Event, T);
+
+impl<Event, T> TerminalTransition<Event, T> {
+    pub(crate) fn new(event: Event, value: T) -> Self { Self(event, value) }
+
+    pub fn save<P>(self, persister: &P) -> Result<T, P::InternalStorageError>
+    where
+        P: SessionPersister<SessionEvent = Event>,
+    {
+        PersistActions::SaveAndClose(self.0).execute(persister)?;
+        Ok(self.1)
+    }
+
+    pub async fn save_async<P>(self, persister: &P) -> Result<T, P::InternalStorageError>
+    where
+        P: AsyncSessionPersister<SessionEvent = Event>,
+        Event: Send,
+        T: Send,
+    {
+        PersistActions::SaveAndClose(self.0).execute_async(persister).await?;
+        Ok(self.1)
+    }
+}
+
 /// A transition that can result in a succession completion, fatal error, or transient error.
 /// The transition can also result in no state change.
 pub enum MaybeFatalOrSuccessTransition<Event, CurrentState, Err> {

payjoin/src/core/receive/common/mod.rs

@@ -31,7 +31,7 @@ use crate::receive::{InternalPayloadError, OriginalPayload, PsbtContext};
 /// Call [`Self::commit_outputs`] to proceed.
 #[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
 pub struct WantsOutputs {
-    original_psbt: Psbt,
+    pub(super) original_psbt: Psbt,
     pub(super) payjoin_psbt: Psbt,
     pub(super) params: Params,
     change_vout: usize,

payjoin/src/core/receive/v2/mod.rs

@@ -55,7 +55,7 @@ use crate::ohttp::{
 use crate::output_substitution::OutputSubstitution;
 use crate::persist::{
     MaybeFatalOrSuccessTransition, MaybeFatalTransition, MaybeFatalTransitionWithNoResults,
-    MaybeSuccessTransition, MaybeTransientTransition, NextStateTransition,
+    MaybeSuccessTransition, MaybeTransientTransition, NextStateTransition, TerminalTransition,
 };
 use crate::receive::{parse_payload, InputPair, OriginalPayload, PsbtContext};
 use crate::time::Time;
@@ -232,20 +232,73 @@ impl ReceiveSession {
 }
 
 mod sealed {
-    pub trait State {}
+    pub trait State {
+        fn fallback_tx(&self) -> Option<bitcoin::Transaction> { None }
+    }
 
     impl State for super::Initialized {}
-    impl State for super::UncheckedOriginalPayload {}
-    impl State for super::MaybeInputsOwned {}
-    impl State for super::MaybeInputsSeen {}
-    impl State for super::OutputsUnknown {}
-    impl State for super::WantsOutputs {}
-    impl State for super::WantsInputs {}
-    impl State for super::WantsFeeRange {}
-    impl State for super::ProvisionalProposal {}
-    impl State for super::PayjoinProposal {}
+
+    impl State for super::UncheckedOriginalPayload {
+        fn fallback_tx(&self) -> Option<bitcoin::Transaction> {
+            Some(self.original.psbt.clone().extract_tx_unchecked_fee_rate())
+        }
+    }
+
+    impl State for super::MaybeInputsOwned {
+        fn fallback_tx(&self) -> Option<bitcoin::Transaction> {
+            Some(self.original.psbt.clone().extract_tx_unchecked_fee_rate())
+        }
+    }
+
+    impl State for super::MaybeInputsSeen {
+        fn fallback_tx(&self) -> Option<bitcoin::Transaction> {
+            Some(self.original.psbt.clone().extract_tx_unchecked_fee_rate())
+        }
+    }
+
+    impl State for super::OutputsUnknown {
+        fn fallback_tx(&self) -> Option<bitcoin::Transaction> {
+            Some(self.original.psbt.clone().extract_tx_unchecked_fee_rate())
+        }
+    }
+
+    impl State for super::WantsOutputs {
+        fn fallback_tx(&self) -> Option<bitcoin::Transaction> {
+            Some(self.inner.original_psbt.clone().extract_tx_unchecked_fee_rate())
+        }
+    }
+
+    impl State for super::WantsInputs {
+        fn fallback_tx(&self) -> Option<bitcoin::Transaction> {
+            Some(self.inner.original_psbt.clone().extract_tx_unchecked_fee_rate())
+        }
+    }
+
+    impl State for super::WantsFeeRange {
+        fn fallback_tx(&self) -> Option<bitcoin::Transaction> {
+            Some(self.inner.original_psbt.clone().extract_tx_unchecked_fee_rate())
+        }
+    }
+
+    impl State for super::ProvisionalProposal {
+        fn fallback_tx(&self) -> Option<bitcoin::Transaction> {
+            Some(self.psbt_context.original_psbt.clone().extract_tx_unchecked_fee_rate())
+        }
+    }
+
+    impl State for super::PayjoinProposal {
+        fn fallback_tx(&self) -> Option<bitcoin::Transaction> {
+            Some(self.psbt_context.original_psbt.clone().extract_tx_unchecked_fee_rate())
+        }
+    }
+
     impl State for super::HasReplyableError {}
-    impl State for super::Monitor {}
+
+    impl State for super::Monitor {
+        fn fallback_tx(&self) -> Option<bitcoin::Transaction> {
+            Some(self.psbt_context.original_psbt.clone().extract_tx_unchecked_fee_rate())
+        }
+    }
 }
 
 /// Sealed trait for V2 receive session states.
@@ -255,6 +308,8 @@ mod sealed {
 /// can implement this trait, ensuring type safety and protocol integrity.
 pub trait State: sealed::State {}
 
+impl<S: sealed::State> State for S {}
+
 /// A higher-level receiver construct which will be taken through different states through the
 /// protocol workflow.
 ///
@@ -285,6 +340,20 @@ impl<State> core::ops::DerefMut for Receiver<State> {
     fn deref_mut(&mut self) -> &mut Self::Target { &mut self.state }
 }
 
+impl<S: State> Receiver<S> {
+    /// Cancel the Payjoin session immediately.
+    ///
+    /// Returns a [`TerminalTransition`] that, once persisted, yields the fallback
+    /// transaction when applicable. The fallback transaction is the sender's original
+    /// transaction that should be broadcast to complete the payment without Payjoin.
+    ///
+    /// This is a terminal transition — the session cannot be used after cancellation.
+    pub fn cancel(self) -> TerminalTransition<SessionEvent, Option<bitcoin::Transaction>> {
+        let fallback = self.state.fallback_tx();
+        TerminalTransition::new(SessionEvent::Closed(SessionOutcome::Cancel), fallback)
+    }
+}
+
 #[derive(Debug, Clone)]
 pub struct ReceiverBuilder(SessionContext);
 
@@ -1830,4 +1899,26 @@ pub mod test {
         let psbt = receiver.psbt_to_sign();
         assert_eq!(psbt, PARSED_PAYJOIN_PROPOSAL.clone());
     }
+
+    #[test]
+    fn cancel_from_initialized_returns_no_fallback() {
+        let persister = InMemoryTestPersister::<SessionEvent>::default();
+        let receiver = Receiver { state: Initialized {}, session_context: SHARED_CONTEXT.clone() };
+        let fallback = receiver.cancel().save(&persister).expect("save should succeed");
+        assert!(fallback.is_none());
+        assert!(persister.inner.read().expect("lock should not be poisoned").is_closed);
+    }
+
+    #[tokio::test]
+    async fn cancel_from_maybe_inputs_owned_returns_fallback() {
+        let persister = InMemoryTestPersister::<SessionEvent>::default();
+        let receiver = Receiver {
+            state: maybe_inputs_owned_v2_from_test_vector(),
+            session_context: SHARED_CONTEXT.clone(),
+        };
+        let expected_fallback = receiver.extract_tx_to_schedule_broadcast();
+        let fallback = receiver.cancel().save(&persister).expect("save should succeed");
+        assert_eq!(fallback, Some(expected_fallback));
+        assert!(persister.inner.read().expect("lock should not be poisoned").is_closed);
+    }
 }