Skip to content

Update receiver typestate documentation for functions shared between v1 and v2 (and some InputPair documentation) #769

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
nothingmuch merged 2 commits into from
Jul 10, 2025
Merged

Update receiver typestate documentation for functions shared between v1 and v2 (and some InputPair documentation) #769

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
ea6ab29
Add documentation for InputPair functions
mehmetefeumit Jun 13, 2025
ac341b7
Update receiver function documentation for version-agnostic functions
mehmetefeumit Jun 13, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 4 additions & 1 deletion payjoin/src/core/psbt/mod.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -105,7 +105,7 @@ pub(crate) struct InternalInputPair<'a> {
}

impl InternalInputPair<'_> {
/// Returns TxOut associated with the input
/// Returns the [`TxOut`] associated with the input.
pub fn previous_txout(&self) -> Result<&TxOut, PrevTxOutError> {
match (&self.psbtin.non_witness_utxo, &self.psbtin.witness_utxo) {
(None, None) => Err(PrevTxOutError::MissingUtxoInformation),
Expand All @@ -125,6 +125,7 @@ impl InternalInputPair<'_> {
}
}

/// Validates that [`TxIn`] and the applicable UTXO field(s) of the [`psbt::Input`] refer to the same UTXO.
pub fn validate_utxo(&self) -> Result<(), InternalPsbtInputError> {
match (&self.psbtin.non_witness_utxo, &self.psbtin.witness_utxo) {
(None, None) =>
Expand Down Expand Up @@ -172,6 +173,7 @@ impl InternalInputPair<'_> {
}
}

/// Returns the scriptPubKey address type of the UTXO this input is pointing to.
pub fn address_type(&self) -> Result<AddressType, AddressTypeError> {
let txo = self.previous_txout()?;
// HACK: Network doesn't matter for our use case of only getting the address type
Expand All @@ -181,6 +183,7 @@ impl InternalInputPair<'_> {
.ok_or(AddressTypeError::UnknownAddressType)
}

/// Returns the expected weight of this input based on the address type of the UTXO it is pointing to.
Copy link
Contributor

@DanGould DanGould Jul 2, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is true at the time of writing, but will need to change when #583 is addressed to handle weight to specify that additional info other than the address type is used to describe it.

pub fn expected_input_weight(&self) -> Result<Weight, InputWeightError> {
use bitcoin::AddressType::*;

Expand Down
15 changes: 9 additions & 6 deletions payjoin/src/core/receive/mod.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -43,7 +43,8 @@ pub(crate) mod v1;
#[cfg_attr(docsrs, doc(cfg(feature = "v2")))]
pub mod v2;

/// Helper to construct a pair of (txin, psbtin) with some built-in validation
/// A pair of ([`TxIn`], [`psbt::Input`]) with some built-in validation.
///
/// Use with [`InputPair::new`] to contribute receiver inputs.
#[derive(Clone, Debug, Serialize, Deserialize, PartialEq, Eq)]
pub struct InputPair {
Expand All @@ -53,6 +54,8 @@ pub struct InputPair {
}

impl InputPair {
/// Creates a new InputPair while validating that the passed [`TxIn`] and [`psbt::Input`]
/// refer to the same and the correct UTXO.
pub fn new(
txin: TxIn,
psbtin: psbt::Input,
Expand Down Expand Up @@ -119,7 +122,7 @@ impl InputPair {
}
}

/// Constructs a new ['InputPair'] for spending a legacy P2PKH output
/// Constructs a new [`InputPair`] for spending a legacy P2PKH output.
pub fn new_p2pkh(
non_witness_utxo: Transaction,
outpoint: OutPoint,
Expand All @@ -132,7 +135,7 @@ impl InputPair {
Self::new_legacy_input_pair(non_witness_utxo, outpoint, sequence, None)
}

/// Constructs a new ['InputPair'] for spending a legacy P2SH output
/// Constructs a new [`InputPair`] for spending a legacy P2SH output.
pub fn new_p2sh(
non_witness_utxo: Transaction,
outpoint: OutPoint,
Expand Down Expand Up @@ -168,7 +171,7 @@ impl InputPair {
Self::new(txin, psbtin, expected_weight)
}

/// Constructs a new ['InputPair'] for spending a native SegWit P2WPKH output
/// Constructs a new [`InputPair`] for spending a native SegWit P2WPKH output.
pub fn new_p2wpkh(
txout: TxOut,
outpoint: OutPoint,
Expand All @@ -181,7 +184,7 @@ impl InputPair {
Self::new_segwit_input_pair(txout, outpoint, sequence, None)
}

/// Constructs a new ['InputPair'] for spending a native SegWit P2WSH output
/// Constructs a new [`InputPair`] for spending a native SegWit P2WSH output.
pub fn new_p2wsh(
txout: TxOut,
outpoint: OutPoint,
Expand All @@ -195,7 +198,7 @@ impl InputPair {
Self::new_segwit_input_pair(txout, outpoint, sequence, Some(expected_weight))
}

/// Constructs a new ['InputPair'] for spending a native SegWit P2TR output
/// Constructs a new [`InputPair`] for spending a native SegWit P2TR output.
pub fn new_p2tr(
txout: TxOut,
outpoint: OutPoint,
Expand Down
Loading
Loading