What payjoin is trying to change

A normal Bitcoin payment lets a chain observer guess that every input belongs to a single spender. Payjoin attacks that guess by having the receiver contribute its own inputs, so the common-input-ownership heuristic stops being reliable. BIP78 defines one way to negotiate this. The sender starts from a signed, finalized, broadcastable original transaction packaged as a PSBT, then evaluates the receiver’s counter-proposal before signing a second time.

The receiver’s permission is narrow

BIP78 does not hand the receiver a blank check. The original inputs and every non-receiver output must survive the negotiation, with one exception: an authorized fee contribution drawn from a designated output. The receiver may add inputs and, unless substitution is disabled, add or replace its own outputs. It may not reorder existing inputs or outputs, and it may not reduce the transaction’s absolute fee.

Output substitution is a separate permission. The URI signal pjos=0 or the sender’s disableoutputsubstitution=true turns it off. When it is off, receiver outputs may grow but not shrink or disappear. Substitution should be treated as an explicit authorization decision rather than a formatting detail.

The sender-side checklist

Before accepting the proposal, BIP78 expects the sender to confirm several points against the original transaction:

  • Original inputs and non-receiver outputs are preserved, allowing only the fee-contribution and substitution exceptions.
  • Transaction version, locktime and sender-input sequence numbers are unchanged.
  • Sender inputs stay unfinalized, while receiver-added inputs are finalized and carry UTXO information.
  • The absolute fee has not decreased.
  • Signing covers only inputs that existed in the original PSBT, with any specified minimum fee rate checked afterward.

These are comparisons against the original, not a readability check on the PSBT format. A well-formed proposal can still violate the sender’s authorization.

Three limits on one fee contribution

A contribution requires a valid additionalfeeoutputindex and maxadditionalfeecontribution before the receiver may reduce a sender-owned output. The sender then checks the deduction against three bounds: the authorized maximum, the increase in absolute fees, and the weight allowance for added inputs at the original fee rate. Each bound answers a different question, and a deduction can pass one while failing another.

What signing does not prove

PSBT signing is not the same as a payjoin check. A hardware signer that displays destination, amount and fee may never have compared the proposal against the original. BIP78 warns of double-payment risk when compromised sender software collects hardware-wallet signatures without the intended checks. A valid signature is not evidence that the comparison took place.

Fallback means two competing spends

The original transaction remains broadcastable, and a receiver may broadcast it after a timeout. The original and the negotiated transaction spend the same inputs, so they are competing transactions rather than two independent payments. After a timeout the correct move is to reconcile the two instead of assuming the payment vanished and sending a fresh one.

What success does not prove

A receiver can return a proposal with no added inputs, and a sender without payjoin support can ignore the optional pj parameter and pay normally. Payment success therefore does not establish that payjoin was used, that inputs were mixed, or that the privacy benefit was realized. An ordinary payment, the signed-original fallback, a no-input proposal, and a true mixed negotiation are distinct outcomes.

Source: BTCUSA.