A Simple Payjoin Proposal

  BIP: 78
  Layer: Applications
  Title: A Simple Payjoin Proposal
  Authors: Nicolas Dorier 
  Status: Draft
  Type: Specification
  Assigned: 2019-05-01
  License: BSD-2-Clause
  Replaces: 79

Introduction

Abstract

This document proposes a protocol for two parties to negotiate a coinjoin transaction during a payment between them.

Copyright

This BIP is licensed under the 2-clause BSD license.

Motivation

When two parties (later referred to as sender and receiver) want to transact, most of the time, the sender creates a transaction spending their own Unspent Transaction Outputs (UTXOs), signs it and broadcasts it on the network.

This simple model gave birth to several heuristics impacting the privacy of the parties and of the network as a whole.

• Common input ownership heuristic: In most transactions, all the inputs belong to the same party.
• Change identification from scriptPubKey type: If all inputs are spending UTXOs of a certain scriptPubKey type, then the change output is likely to have the same scriptPubKey type, too.
• Change identification from round amount: If an output in the transaction has a round amount, it is likely an output belonging to the receiver.

We will designate these three heuristics as common-input, change-scriptpubkey, change-round-amount.

The problems we aim to solve are:

• For the receiver, there is a missed opportunity to consolidate their own UTXOs or making payment in the sender's transaction.
• For the sender, there are privacy leaks regarding their wallet that happen when someone applies the heuristics detailed above to their transaction.

Our proposal gives an opportunity for the receiver to consolidate their UTXOs while also batching their own payments, without creating a new transaction. (Saving fees in the process) For the sender, it allows them to invalidate the three heuristics above. With the receiver's involvement, the heuristics can even be poisoned. (ie, using the heuristics to intentionally mislead blockchain analysis)

Note that the existence of this proposal is also improving the privacy of parties who are not using it by making the three heuristics unreliable to the network as a whole.

Relation to BIP79 (Bustapay)

Another implementation proposal has been written: BIP79 Bustapay.

We decided to deviate from it for several reasons:

• It was not using PSBT, so if the receiver wanted to bump the fee, they would need the full UTXO set.
• Inability to change the payment output to match scriptPubKey type.
• Lack of basic versioning negotiation if the protocol evolves.
• No standardization of error condition for proper feedback to the sender.

Other than that, our proposal is very similar.

Specification

Protocol

In a payjoin payment, the following steps happen:

• The receiver of the payment, presents a BIP 21 URI to the sender with a parameter pj= describing a payjoin endpoint.
• The sender creates a signed, finalized PSBT with witness UTXO or previous transactions of the inputs. We call this PSBT the original.
• The receiver replies back with a signed PSBT containing his own signed inputs/outputs and those of the sender. We call this PSBT Payjoin proposal.
• The sender verifies the proposal, re-signs his inputs and broadcasts the transaction to the Bitcoin network. We call this transaction Payjoin transaction.

+----------+                        +--------+         +-----------------+
| Receiver |                        | Sender |         | Bitcoin Network |
+----+-----+                        +---+----+         +-------+---------+
     |       +-----------------+        |                      |
     +-------+ BIP21 with ?pj= +------->+                      |
     |       +-----------------+        |                      |
     |                                  |                      |
     |        +---------------+         |                      |
     +<-------+ Original PSBT +---------+                      |
     |        +---------------+         |                      |
     |                                  |                      |
     |       +------------------+       |                      |
     |       | Payjoin Proposal |       |                      |
     +-------+      PSBT        +------>+                      |
     |       +------------------+       |                      |
     |                                  |   +--------------+   |
     |                                  |---+ Payjoin      |   |
     |                                  |   | transaction  +-->+
     |                                  |   +--------------+   |
     +                                  +                      +

The original PSBT is sent in the HTTP POST request body, base64 serialized, with text/plain in the Content-Type HTTP header and Content-Length set correctly. The payjoin proposal PSBT is sent in the HTTP response body, base64 serialized with HTTP code 200.

To ensure compatibility with web-wallets and browser-based-tools, all responses (including errors) must contain the HTTP header Access-Control-Allow-Origin: *.

The sender must ensure that the URL refers to a scheme or protocol using authenticated encryption, for example TLS with certificate validation, or a .onion link to a hidden service whose public key identifier has already been communicated via a TLS connection. Senders SHOULD NOT accept a URL representing an unencrypted or unauthenticated connection.

The original PSBT MUST:

• Have all the witnessUTXO or nonWitnessUTXO information filled in.
• Be finalized.
• Not include fields unneeded for the receiver such as global xpubs or keypath information.
• Be broadcastable.

The original PSBT MAY:

• Have outputs unrelated to the payment for batching purpose.

The original PSBT SHOULD NOT:

• Include mixed input types until September 2024. Mixed inputs were previously completely disallowed so this gives some grace period for receivers to update.

The payjoin proposal MUST:

• Use all the inputs from the original PSBT.
• Use all the outputs which do not belong to the receiver from the original PSBT.
• Only finalize the inputs added by the receiver. (Referred later as additional inputs)
• Only fill the witnessUTXO or nonWitnessUTXO for the additional inputs.

The payjoin proposal MAY:

• Add, or replace the outputs belonging to the receiver unless output substitution is disabled.

The payjoin proposal SHOULD NOT:

• Include mixed input types until September 2024. Mixed inputs were previously completely disallowed so this gives some grace period for senders to update.

The payjoin proposal MUST NOT:

• Shuffle the order of inputs or outputs, the additional outputs or additional inputs must be inserted at a random index.
• Decrease the absolute fee of the original transaction.

BIP21 payjoin parameters

This proposal is defining the following new BIP 21 URI parameters:

• pj=: Represents an http(s) endpoint which the sender can POST the original PSBT.
• pjos=0: Signal to the sender that they MUST disallow payment output substitution. (See Unsecured payjoin server)

Note: the amount parameter is *not* required.

Optional parameters

When the payjoin sender posts the original PSBT to the receiver, he can optionally specify the following HTTP query string parameters:

• v=, the version number of the payjoin protocol that the sender is using. The current version is 1.

This can be used in the future so the receiver can reject a payjoin if the sender is using a version which is not supported via an error HTTP 400, version-unsupported. If not specified, the receiver will assume the sender is v=1.

If the receiver does not support the version of the sender, they should send an error with the list of supported versions:

{
    "errorCode": "version-unsupported",
    "supported" : [ 2, 3, 4 ],
    "message": "The version is not supported anymore"
}

• additionalfeeoutputindex=, if the sender is willing to pay for increased fee, this indicate output can have its value subtracted to pay for it.

If the additionalfeeoutputindex is out of bounds or pointing to the payment output meant for the receiver, the receiver should ignore the parameter. See fee output for more information.

• maxadditionalfeecontribution=, if the sender is willing to pay for increased fee, an integer defining the maximum amount in satoshis that the sender is willing to contribute towards fees for the additional inputs. maxadditionalfeecontribution must be ignored if set to less than zero. See fee output for more information.

Note that both maxadditionalfeecontribution= and additionalfeeoutputindex= must be specified and valid for the receiver to be allowed to decrease an output belonging to the sender. This fee contribution can't be used to pay for anything else than additional input's weight.

• minfeerate=, a decimal in satoshi per vbyte that the sender can use to constraint the receiver to not drop the minimum fee rate too much.

• disableoutputsubstitution=, a boolean indicating if the sender forbids the receiver to substitute the receiver's output, see payment output substitution. (default to false)

Receiver's well known errors

If for some reason the receiver is unable to create a payjoin proposal, it will reply with a HTTP code different than 200. The receiver is not constrained to specific set of errors, some are specified in this proposal.

The errors have the following format:

{
    "errorCode": "leaking-data",
    "message": "Key path information or GlobalXPubs should not be included in the original PSBT."
}

The well-known error codes are:

Error code	Meaning
unavailable	The payjoin endpoint is not available for now.
not-enough-money	The receiver added some inputs but could not bump the fee of the payjoin proposal.
version-unsupported	This version of payjoin is not supported.
original-psbt-rejected	The receiver rejected the original PSBT.

The receiver is allowed to return implementation-specific errors which may assist the sender to diagnose any issue.

However, it is important that error codes that are not well-known and that the message do not appear on the sender's software user interface. Such error codes or messages could be used maliciously to phish a non-technical user. Instead those errors or messages can only appear in debug logs.

It is advised to hard code the description of the well known error codes into the sender's software.

Fee output

In some situation, the sender might want to pay some additional fee in the payjoin proposal. If such is the case, the sender must use both optional parameters additionalfeeoutputindex= and maxadditionalfeecontribution= to indicate which output and how much the receiver can subtract fee.

There are several cases where a fee output is useful:

• The sender's original transaction's fee rate is at the minimum accepted by the network, aka minimum relay transaction fee rate, which is typically 1 satoshi per vbyte.

In such case, the receiver will need to increase the fee of the transaction after adding his own inputs to not drop below the minimum relay transaction fee rate.

• The sender's wallet software is using round fee rate.

If the sender's fee rate is always round, then a blockchain analyst can easily spot the transactions of the sender involving payjoin by checking if, when removing a single input to the suspected payjoin transaction, the resulting fee rate is round. To prevent this, the sender can agree to pay more fee so the receiver make sure that the payjoin transaction fee is also round.

• The sender's transaction is time sensitive.

When a sender picks a specific fee rate, the sender expects the transaction to be confirmed after a specific amount of time. But if the receiver adds an input without bumping the fee of the transaction, the payjoin transaction fee rate will be lower, and thus, longer to confirm.

Our recommendation for maxadditionalfeecontribution= is originalPSBTFeeRate * 110.

Receiver's original PSBT checklist

The receiver needs to do some check on the original PSBT before proceeding:

• Non-interactive receivers (like a payment processor) need to check that the original PSBT is broadcastable. *
• If the sender included inputs in the original PSBT owned by the receiver, the receiver must either return error original-psbt-rejected or make sure they do not sign those inputs in the payjoin proposal.
• Make sure that the inputs included in the original transaction have never been seen before.

** This prevents probing attacks. ** This prevents reentrant payjoin, where a sender attempts to use payjoin transaction as a new original transaction for a new payjoin.

*: Interactive receivers are not required to validate the original PSBT because they are not exposed to probing attacks.

Sender's payjoin proposal checklist

The sender should check the payjoin proposal before signing it to prevent a malicious receiver from stealing money.

• Verify that the absolute fee of the payjoin proposal is equals or higher than the original PSBT.
• If the receiver's BIP21 signalled pjos=0, disable payment output substitution.
• Verify that the transaction version, and the nLockTime are unchanged.
• Check that the sender's inputs' sequence numbers are unchanged.
• For each input in the proposal:

** Verify that no keypaths are in the PSBT input ** Verify that no partial signature has been filled ** If it is one of the sender's inputs: *** Verify that input's sequence is unchanged. *** Verify the PSBT input is not finalized ** If it is one of the receiver's inputs: *** Verify the PSBT input is finalized *** Verify that non_witness_utxo or witness_utxo are filled in. ** Verify that the payjoin proposal inputs all specify the same sequence value. ** Verify that all of sender's inputs from the original PSBT are in the proposal.

• For each output in the proposal:

** Verify that no keypaths are in the PSBT output ** If the output is the [[#fee-output|fee out