Make Receiver generic over its typestate

This commit updates the `v2::Receiver` to be generic over its
typestate (e.g., `UncheckedProposal`, `InputsSeen`, etc.). The
motivation:

* Improves readability and maintainability: Each typestate now
  clearly belongs to the receiver session. This makes the code easier
  to reason about, without runtime cost. It also sets us up to
  define a shared pattern between v2, NS1R and future state machines.

* Decouples typestate data from transition logic: NS1R typesates can now
  consume state structs without being tied to the transition machinery.
  This keeps state transitions encapsulated and makes the underlying
  session data easier to use in other contexts.

This commit renames the original `Receiver` struct to `WithContext`.
This type now represents the receiver session once the HPKE context has been
created. The Receiver name is re-purposed for the new generic wrapper
over typestate.

For the UniFFI exported receiver we monomorphizes the exported structs over a
specific typestate. UniFFI doesn't support exporting generic structs, so
we expose a concrete type to the FFI.

Author: arminsabouri

payjoin-cli/src/app/v2/mod.rs

@@ -4,7 +4,9 @@ use anyhow::{anyhow, Context, Result};
 use payjoin::bitcoin::consensus::encode::serialize_hex;
 use payjoin::bitcoin::psbt::Psbt;
 use payjoin::bitcoin::{Amount, FeeRate};
-use payjoin::receive::v2::{NewReceiver, Receiver, UncheckedProposal};
+use payjoin::receive::v2::{
+    NewReceiver, PayjoinProposal, Receiver, UncheckedProposal, WithContext,
+};
 use payjoin::receive::{Error, ReplyableError};
 use payjoin::send::v2::{Sender, SenderBuilder};
 use payjoin::{ImplementationError, Uri};
@@ -151,7 +153,7 @@ impl App {
     #[allow(clippy::incompatible_msrv)]
     async fn spawn_payjoin_receiver(
         &self,
-        mut session: Receiver,
+        mut session: Receiver<WithContext>,
         amount: Option<Amount>,
     ) -> Result<()> {
         println!("Receive session established");
@@ -241,8 +243,8 @@ impl App {
 
     async fn long_poll_fallback(
         &self,
-        session: &mut payjoin::receive::v2::Receiver,
-    ) -> Result<payjoin::receive::v2::UncheckedProposal> {
+        session: &mut payjoin::receive::v2::Receiver<WithContext>,
+    ) -> Result<payjoin::receive::v2::Receiver<UncheckedProposal>> {
         let ohttp_relay = self.unwrap_relay_or_else_fetch().await?;
 
         loop {
@@ -261,8 +263,8 @@ impl App {
 
     fn process_v2_proposal(
         &self,
-        proposal: payjoin::receive::v2::UncheckedProposal,
-    ) -> Result<payjoin::receive::v2::PayjoinProposal, Error> {
+        proposal: payjoin::receive::v2::Receiver<UncheckedProposal>,
+    ) -> Result<payjoin::receive::v2::Receiver<PayjoinProposal>, Error> {
         let wallet = self.wallet();
 
         // in a payment processor where the sender could go offline, this is where you schedule to broadcast the original_tx
@@ -313,7 +315,7 @@ impl App {
 /// Handle request error by sending an error response over the directory
 async fn handle_recoverable_error(
     e: ReplyableError,
-    mut receiver: UncheckedProposal,
+    mut receiver: Receiver<UncheckedProposal>,
     ohttp_relay: &payjoin::Url,
 ) -> anyhow::Error {
     let to_return = anyhow!("Replied with error: {}", e);
@@ -340,9 +342,12 @@ async fn handle_recoverable_error(
 }
 
 fn try_contributing_inputs(
-    payjoin: payjoin::receive::v2::WantsInputs,
+    payjoin: payjoin::receive::v2::Receiver<payjoin::receive::v2::WantsInputs>,
     wallet: &BitcoindWallet,
-) -> Result<payjoin::receive::v2::ProvisionalProposal, ImplementationError> {
+) -> Result<
+    payjoin::receive::v2::Receiver<payjoin::receive::v2::ProvisionalProposal>,
+    ImplementationError,
+> {
     let candidate_inputs = wallet.list_unspent()?;
 
     let selected_input =

payjoin-cli/src/db/v2.rs

@@ -2,7 +2,7 @@ use std::sync::Arc;
 
 use bitcoincore_rpc::jsonrpc::serde_json;
 use payjoin::persist::{Persister, Value};
-use payjoin::receive::v2::{Receiver, ReceiverToken};
+use payjoin::receive::v2::{Receiver, ReceiverToken, WithContext};
 use payjoin::send::v2::{Sender, SenderToken};
 use sled::Tree;
 use url::Url;
@@ -38,31 +38,35 @@ impl ReceiverPersister {
     pub fn new(db: Arc<Database>) -> Self { Self(db) }
 }
 
-impl Persister<Receiver> for ReceiverPersister {
+impl Persister<Receiver<WithContext>> for ReceiverPersister {
     type Token = ReceiverToken;
     type Error = crate::db::error::Error;
-    fn save(&mut self, value: Receiver) -> std::result::Result<ReceiverToken, Self::Error> {
+    fn save(
+        &mut self,
+        value: Receiver<WithContext>,
+    ) -> std::result::Result<ReceiverToken, Self::Error> {
         let recv_tree = self.0 .0.open_tree("recv_sessions")?;
         let key = value.key();
         let value = serde_json::to_vec(&value).map_err(Error::Serialize)?;
         recv_tree.insert(key.clone(), value.as_slice())?;
         recv_tree.flush()?;
         Ok(key)
     }
-    fn load(&self, key: ReceiverToken) -> std::result::Result<Receiver, Self::Error> {
+    fn load(&self, key: ReceiverToken) -> std::result::Result<Receiver<WithContext>, Self::Error> {
         let recv_tree = self.0 .0.open_tree("recv_sessions")?;
         let value = recv_tree.get(key.as_ref())?.ok_or(Error::NotFound(key.to_string()))?;
         serde_json::from_slice(&value).map_err(Error::Deserialize)
     }
 }
 
 impl Database {
-    pub(crate) fn get_recv_sessions(&self) -> Result<Vec<Receiver>> {
+    pub(crate) fn get_recv_sessions(&self) -> Result<Vec<Receiver<WithContext>>> {
         let recv_tree = self.0.open_tree("recv_sessions")?;
         let mut sessions = Vec::new();
         for item in recv_tree.iter() {
             let (_, value) = item?;
-            let session: Receiver = serde_json::from_slice(&value).map_err(Error::Deserialize)?;
+            let session: Receiver<WithContext> =
+                serde_json::from_slice(&value).map_err(Error::Deserialize)?;
             sessions.push(session);
         }
         Ok(sessions)