Cleanup for 0.23 release (payjoin#622)

Ahead of the feature-freeze for 0.23, do some cleanup and bring doc
strings up to date.

Closes payjoin#591 and payjoin#503.

Author: spacebear21

README.md

@@ -6,9 +6,7 @@ Supercharged payment batching to save you fees and preserve your privacy.
 
 ### `payjoin`
 
-The Payjoin Dev Kit `payjoin` library implements both [BIP 78 Payjoin V1](https://github.com/shesek/bips/blob/master/bip-0078.mediawiki) and [BIP 77 Payjoin V2](https://github.com/bitcoin/bips/pull/1483).
-
-The `payjoin` crate is compatible with many wallets like LND in [nolooking](https://github.com/chaincase-app/nolooking) and Bitcoin Dev Kit in [Mutiny Wallet](https://github.com/MutinyWallet/mutiny-node) and in [BitMask](https://github.com/diba-io/bitmask-core)
+The Payjoin Dev Kit `payjoin` library implements both [BIP 78 Payjoin V1](https://github.com/bitcoin/bips/blob/master/bip-0078.mediawiki) and [BIP 77 Payjoin V2](https://github.com/bitcoin/bips/pull/1483).
 
 ### `payjoin-cli`
 
@@ -18,6 +16,10 @@ The [`payjoin-cli`](https://github.com/payjoin/rust-payjoin/tree/master/payjoin-
 
 The [`payjoin-directory`](https://github.com/payjoin/rust-payjoin/tree/master/payjoin-directory) crate implements the Payjoin Directory store-and-forward server required for Payjoin V2's asynchronous operation.
 
+### `payjoin-test-utils`
+
+The [`payjoin-test-utils`](https://github.com/payjoin/rust-payjoin/tree/master/payjoin-test-utils) crate provides commonly used testing fixtures such as a local OHTTP relay and payjoin directory, bitcoind node and wallets, and official test vectors.
+
 ### Disclaimer ⚠️ WIP
 
 **Use at your own risk. This crate has not yet been reviewed by independent Rust and Bitcoin security professionals.**

payjoin-cli/src/app/v2.rs

@@ -175,7 +175,7 @@ impl App {
             Err(e) => return Err(e.into()),
         };
         let (req, ohttp_ctx) = payjoin_proposal
-            .extract_v2_req(&self.config.v2()?.ohttp_relay)
+            .extract_req(&self.config.v2()?.ohttp_relay)
             .map_err(|e| anyhow!("v2 req extraction failed {}", e))?;
         println!("Got a request from the sender. Responding with a Payjoin proposal.");
         let res = post_request(req).await?;

payjoin/src/receive/v1/mod.rs

@@ -763,10 +763,12 @@ pub struct PayjoinProposal {
 }
 
 impl PayjoinProposal {
+    /// The UTXOs that would be spent by this Payjoin transaction
     pub fn utxos_to_be_locked(&self) -> impl '_ + Iterator<Item = &bitcoin::OutPoint> {
         self.payjoin_psbt.unsigned_tx.input.iter().map(|input| &input.previous_output)
     }
 
+    /// The Payjoin Proposal PSBT
     pub fn psbt(&self) -> &Psbt { &self.payjoin_psbt }
 }
 

payjoin/src/receive/v2/mod.rs

@@ -71,15 +71,14 @@ fn subdir_path_from_pubkey(pubkey: &HpkePublicKey) -> ShortId {
     sha256::Hash::hash(&pubkey.to_compressed_bytes()).into()
 }
 
-/// A payjoin V2 receiver, allowing for polled requests to the
-/// payjoin directory and response processing.
+/// A new payjoin receiver, which must be persisted before initiating the payjoin flow.
 #[derive(Debug)]
 pub struct NewReceiver {
     context: SessionContext,
 }
 
 impl NewReceiver {
-    /// Creates a new `Receiver` with the provided parameters.
+    /// Creates a new [`NewReceiver`] with the provided parameters.
     ///
     /// # Parameters
     /// - `address`: The Bitcoin address for the payjoin session.
@@ -88,7 +87,7 @@ impl NewReceiver {
     /// - `expire_after`: The duration after which the session expires.
     ///
     /// # Returns
-    /// A new instance of `Receiver`.
+    /// A new instance of [`NewReceiver`].
     ///
     /// # References
     /// - [BIP 77: Payjoin Version 2: Serverless Payjoin](https://github.com/bitcoin/bips/pull/1483)
@@ -113,6 +112,7 @@ impl NewReceiver {
         Ok(receiver)
     }
 
+    /// Saves the new [`Receiver`] using the provided persister and returns the storage token.
     pub fn persist<P: Persister<Receiver>>(
         &self,
         persister: &mut P,
@@ -122,6 +122,8 @@ impl NewReceiver {
     }
 }
 
+/// A payjoin V2 receiver, allowing for polled requests to the
+/// payjoin directory and response processing.
 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
 pub struct Receiver {
     context: SessionContext,
@@ -150,6 +152,7 @@ impl persist::Value for Receiver {
 }
 
 impl Receiver {
+    /// Loads a [`Receiver`] from the provided persister using the storage token.
     pub fn load<P: Persister<Receiver>>(
         token: P::Token,
         persister: &P,
@@ -361,7 +364,7 @@ impl UncheckedProposal {
 
 /// Typestate to validate that the Original PSBT has no receiver-owned inputs.
 ///
-/// Call [`check_no_receiver_owned_inputs()`](struct.UncheckedProposal.html#method.check_no_receiver_owned_inputs) to proceed.
+/// Call [`Self::check_inputs_not_owned`] to proceed.
 #[derive(Debug, Clone)]
 pub struct MaybeInputsOwned {
     v1: v1::MaybeInputsOwned,
@@ -384,7 +387,7 @@ impl MaybeInputsOwned {
 
 /// Typestate to validate that the Original PSBT has no inputs that have been seen before.
 ///
-/// Call [`check_no_inputs_seen`](struct.MaybeInputsSeen.html#method.check_no_inputs_seen_before) to proceed.
+/// Call [`Self::check_no_inputs_seen_before`] to proceed.
 #[derive(Debug, Clone)]
 pub struct MaybeInputsSeen {
     v1: v1::MaybeInputsSeen,
@@ -407,7 +410,7 @@ impl MaybeInputsSeen {
 /// The receiver has not yet identified which outputs belong to the receiver.
 ///
 /// Only accept PSBTs that send us money.
-/// Identify those outputs with `identify_receiver_outputs()` to proceed
+/// Identify those outputs with [`Self::identify_receiver_outputs`] to proceed.
 #[derive(Debug, Clone)]
 pub struct OutputsUnknown {
     inner: v1::OutputsUnknown,
@@ -426,6 +429,8 @@ impl OutputsUnknown {
 }
 
 /// A checked proposal that the receiver may substitute or add outputs to
+///
+/// Call [`Self::commit_outputs`] to proceed.
 #[derive(Debug, Clone)]
 pub struct WantsOutputs {
     v1: v1::WantsOutputs,
@@ -468,6 +473,8 @@ impl WantsOutputs {
 }
 
 /// A checked proposal that the receiver may contribute inputs to to make a payjoin
+///
+/// Call [`Self::commit_inputs`] to proceed.
 #[derive(Debug, Clone)]
 pub struct WantsInputs {
     v1: v1::WantsInputs,
@@ -513,13 +520,21 @@ impl WantsInputs {
 
 /// A checked proposal that the receiver may sign and finalize to make a proposal PSBT that the
 /// sender will accept.
+///
+/// Call [`Self::finalize_proposal`] to return a finalized [`PayjoinProposal`].
 #[derive(Debug, Clone)]
 pub struct ProvisionalProposal {
     v1: v1::ProvisionalProposal,
     context: SessionContext,
 }
 
 impl ProvisionalProposal {
+    /// Return a Payjoin Proposal PSBT that the sender will find acceptable.
+    ///
+    /// This attempts to calculate any network fee owed by the receiver, subtract it from their output,
+    /// and return a PSBT that can produce a consensus-valid transaction that the sender will accept.
+    ///
+    /// wallet_process_psbt should sign and finalize receiver inputs
     pub fn finalize_proposal(
         self,
         wallet_process_psbt: impl Fn(&Psbt) -> Result<Psbt, ImplementationError>,
@@ -532,7 +547,8 @@ impl ProvisionalProposal {
     }
 }
 
-/// A mutable checked proposal that the receiver may contribute inputs to to make a payjoin.
+/// A finalized payjoin proposal, complete with fees and receiver signatures, that the sender
+/// should find acceptable.
 #[derive(Clone)]
 pub struct PayjoinProposal {
     v1: v1::PayjoinProposal,
@@ -541,18 +557,21 @@ pub struct PayjoinProposal {
 
 impl PayjoinProposal {
     #[cfg(feature = "_multiparty")]
-    // TODO hack to get multi party working. A better solution would be to allow extract_v2_req to be separate from the rest of the v2 context
+    // TODO hack to get multi party working. A better solution would be to allow extract_req to be separate from the rest of the v2 context
     pub(crate) fn new(v1: v1::PayjoinProposal, context: SessionContext) -> Self {
         Self { v1, context }
     }
 
+    /// The UTXOs that would be spent by this Payjoin transaction
     pub fn utxos_to_be_locked(&self) -> impl '_ + Iterator<Item = &bitcoin::OutPoint> {
         self.v1.utxos_to_be_locked()
     }
 
+    /// The Payjoin Proposal PSBT
     pub fn psbt(&self) -> &Psbt { self.v1.psbt() }
 
-    pub fn extract_v2_req(
+    /// Extract an OHTTP Encapsulated HTTP POST request for the Proposal PSBT
+    pub fn extract_req(
         &mut self,
         ohttp_relay: impl IntoUrl,
     ) -> Result<(Request, ohttp::ClientResponse), Error> {
@@ -594,7 +613,6 @@ impl PayjoinProposal {
         Ok((req, ctx))
     }
 
-    #[cfg(feature = "v2")]
     /// Processes the response for the final POST message from the receiver client in the v2 Payjoin protocol.
     ///
     /// This function decapsulates the response using the provided OHTTP context. If the response status is successful,

payjoin/src/send/v1.rs

@@ -32,6 +32,7 @@ use crate::psbt::PsbtExt;
 use crate::request::Request;
 pub use crate::PjUri;
 
+/// A builder to construct the properties of a `Sender`.
 #[derive(Clone)]
 pub struct SenderBuilder<'a> {
     pub(crate) psbt: Psbt,
@@ -210,12 +211,14 @@ impl<'a> SenderBuilder<'a> {
     }
 }
 
+/// A payjoin V1 sender, allowing the construction of a payjoin V1 request
+/// and the resulting `V1Context`
 #[derive(Clone, PartialEq, Eq, Debug)]
 #[cfg_attr(feature = "v2", derive(serde::Serialize, serde::Deserialize))]
 pub struct Sender {
     /// The original PSBT.
     pub(crate) psbt: Psbt,
-    /// The payjoin directory subdirectory to send the request to.
+    /// The endpoint in the Payjoin URI
     pub(crate) endpoint: Url,
     /// Whether the receiver is allowed to substitute original outputs.
     pub(crate) output_substitution: OutputSubstitution,
@@ -251,13 +254,14 @@ impl Sender {
         )
     }
 
+    /// The endpoint in the Payjoin URI
     pub fn endpoint(&self) -> &Url { &self.endpoint }
 }
 
 /// Data required to validate the response.
 ///
 /// This type is used to process a BIP78 response.
-/// Then call [`Self::process_response`] on it to continue BIP78 flow.
+/// Call [`Self::process_response`] on it to continue the BIP78 flow.
 #[derive(Debug, Clone)]
 pub struct V1Context {
     psbt_context: PsbtContext,

payjoin/src/send/v2/mod.rs

@@ -41,6 +41,7 @@ use crate::{HpkeKeyPair, HpkePublicKey, IntoUrl, OhttpKeys, PjUri, Request};
 
 mod error;
 
+/// A builder to construct the properties of a [`Sender`].
 #[derive(Clone)]
 pub struct SenderBuilder<'a>(pub(crate) v1::SenderBuilder<'a>);
 
@@ -123,13 +124,15 @@ impl<'a> SenderBuilder<'a> {
     }
 }
 
+/// A new payjoin sender, which must be persisted before initiating the payjoin flow.
 #[derive(Debug)]
 pub struct NewSender {
     pub(crate) v1: v1::Sender,
     pub(crate) reply_key: HpkeSecretKey,
 }
 
 impl NewSender {
+    /// Saves the new [`Sender`] using the provided persister and returns the storage token.
     pub fn persist<P: Persister<Sender>>(
         &self,
         persister: &mut P,
@@ -139,6 +142,8 @@ impl NewSender {
     }
 }
 
+/// A payjoin V2 sender, allowing the construction of a payjoin V2 request
+/// and the resulting [`V2PostContext`].
 #[derive(Clone, PartialEq, Eq, Serialize, Deserialize)]
 pub struct Sender {
     /// The v1 Sender.
@@ -170,6 +175,7 @@ impl Value for Sender {
 }
 
 impl Sender {
+    /// Loads a [`Sender`] from the provided persister using the storage token.
     pub fn load<P: Persister<Sender>>(
         token: P::Token,
         persister: &P,
@@ -236,6 +242,7 @@ impl Sender {
         self.v1.endpoint.receiver_pubkey()
     }
 
+    /// The endpoint in the Payjoin URI
     pub fn endpoint(&self) -> &Url { self.v1.endpoint() }
 }
 
@@ -289,15 +296,29 @@ pub(crate) fn serialize_v2_body(
     Ok(format!("{}\n{}", base64, query_params).into_bytes())
 }
 
+/// Data required to validate the POST response.
+///
+/// This type is used to process a BIP77 POST response.
+/// Call [`Self::process_response`] on it to continue the BIP77 flow.
 pub struct V2PostContext {
-    /// The payjoin directory subdirectory to send the request to.
+    /// The endpoint in the Payjoin URI
     pub(crate) endpoint: Url,
     pub(crate) psbt_ctx: PsbtContext,
     pub(crate) hpke_ctx: HpkeContext,
     pub(crate) ohttp_ctx: ohttp::ClientResponse,
 }
 
 impl V2PostContext {
+    /// Processes the response for the initial POST message from the sender
+    /// client in the v2 Payjoin protocol.
+    ///
+    /// This function decapsulates the response using the provided OHTTP
+    /// context. If the encapsulated response status is successful, it
+    /// indicates that the the Original PSBT been accepted. Otherwise, it
+    /// returns an error with the encapsulated response status code.
+    ///
+    /// After this function is called, the sender can poll for a Proposal PSBT
+    /// from the receiver using the returned [`V2GetContext`].
     pub fn process_response(self, response: &[u8]) -> Result<V2GetContext, EncapsulationError> {
         let response_array: &[u8; crate::directory::ENCAPSULATED_MESSAGE_BYTES] = response
             .try_into()
@@ -318,15 +339,20 @@ impl V2PostContext {
     }
 }
 
+/// Data required to validate the GET response.
+///
+/// This type is used to make a BIP77 GET request and process the response.
+/// Call [`Self::process_response`] on it to continue the BIP77 flow.
 #[derive(Debug, Clone)]
 pub struct V2GetContext {
-    /// The payjoin directory subdirectory to send the request to.
+    /// The endpoint in the Payjoin URI
     pub(crate) endpoint: Url,
     pub(crate) psbt_ctx: PsbtContext,
     pub(crate) hpke_ctx: HpkeContext,
 }
 
 impl V2GetContext {
+    /// Extract an OHTTP Encapsulated HTTP GET request for the Proposal PSBT
     pub fn extract_req(
         &self,
         ohttp_relay: impl IntoUrl,
@@ -354,6 +380,16 @@ impl V2GetContext {
         Ok((Request::new_v2(&url, &body), ohttp_ctx))
     }
 
+    /// Processes the response for the final GET message from the sender client
+    /// in the v2 Payjoin protocol.
+    ///
+    /// This function decapsulates the response using the provided OHTTP
+    /// context. A successful response can either be a Proposal PSBT or an
+    /// ACCEPTED message indicating no Proposal PSBT is available yet.
+    /// Otherwise, it returns an error with the encapsulated status code.
+    ///
+    /// After this function is called, the sender can sign and finalize the
+    /// PSBT and broadcast the resulting Payjoin transaction to the network.
     pub fn process_response(
         &self,
         response: &[u8],

payjoin/tests/integration.rs

@@ -371,7 +371,7 @@ mod integration {
                     .process_res(response.bytes().await?.to_vec().as_slice(), ctx)?
                     .expect("proposal should exist");
                 let mut payjoin_proposal = handle_directory_proposal(&receiver, proposal, None)?;
-                let (req, ctx) = payjoin_proposal.extract_v2_req(&ohttp_relay)?;
+                let (req, ctx) = payjoin_proposal.extract_req(&ohttp_relay)?;
                 let response = agent
                     .post(req.url)
                     .header("Content-Type", req.content_type)
@@ -560,7 +560,7 @@ mod integration {
                             .map_err(|e| e.to_string())?;
                     // Respond with payjoin psbt within the time window the sender is willing to wait
                     // this response would be returned as http response to the sender
-                    let (req, ctx) = payjoin_proposal.extract_v2_req(&ohttp_relay)?;
+                    let (req, ctx) = payjoin_proposal.extract_req(&ohttp_relay)?;
                     let response = agent_clone
                         .post(req.url)
                         .header("Content-Type", req.content_type)
@@ -831,7 +831,7 @@ mod integration {
 
                 // Send the payjoin proposals to the senders
                 for mut proposal in multi_sender_payjoin_proposal.sender_iter() {
-                    let (req, ctx) = proposal.extract_v2_req(&ohttp_relay)?;
+                    let (req, ctx) = proposal.extract_req(&ohttp_relay)?;
                     let response = agent
                         .post(req.url)
                         .header("Content-Type", req.content_type)