BIP 77: Async Payjoin #1483

  21 | +
  22 | +==Motivation==
  23 | +
  24 | +Payjoin solves the sole privacy problem left open in the bitcoin paper, that transactions with multiple inputs "necessarily reveal that their inputs were owned by the same owner." Breaking that common-input ownership assumption and others requires input from multiple owners. Cooperative transaction construction also increases transaction throughput by providing new opportunity for payment batching and transaction cut-through.
  25 | +
  26 | +Version 1 coordinates payjoins over a public server endpoint secured by either TLS or Tor hidden service hosted by the receiver. Version 1 is synchronous, requiring both sender and reciever to be online simultaneously to payjoin. Both requirements present significant barriers for all but sophisticated server operators or those wallets with complex Tor integration. Wallet develoepers [[https://lists.linuxfoundation.org/pipermail/bitcoin-dev/2021-January/018358.html|regard]] these as limits to payjoin adoption.

---

  29 | +
  30 | +===Relation to BIP 78 (Payjoin version 1)===
  31 | +
  32 | +The message payloads in this version parallel those used in BIP 78 while being encapsulated in authenticated encryption. TLS and Tor security, which depend on third-party authorities, are replaced with Hybrid Public Key Encryption ([[https://www.rfc-editor.org/rfc/rfc9180|HPKE]]). The synchronous HTTP client-server model is replaced with an asynchronous store-and-forward mechanism. This protocol also upgrades to PSBT version 2 to simplify transaction construction.
  33 | +
  34 | +The BIP 78 standard allows for an [[https://github.com/bitcoin/bips/blob/master/bip-0078.mediawiki#unsecured-payjoin-server|unsecured payjoin server|]] to operate separately from the so-called "payment server" responsible for generating [[https://github.com/bitcoin/bips/blob/master/bip-0021.mediawiki|BIP 21]] request URIs. Because BIP 78 messages relayed over an unsecured server are neither end-to-end authenticated nor encrypted between sender and receiver, a malicious unsecured payjoin server is able to modify the Payjoin PSBT in flight, thus requiring payment output substitition to be disabled. Output substitition is useful for a number of block space optimizations, including payment batching and transaction cut-through. This proposal introduces authentication and encryption to secure output substition while using a directory relay without compromising sender or receiver privacy.

---

  37 | +
  38 | +The protocols in this document reuse BIP 78's BIP 21 URI parameters. A Original PSBT timeout parameter is introduced which may also help coordinate the synchronous version 1 protocol.
  39 | +
  40 | +===Relation to Stowaway===
  41 | +
  42 | +[[https://code.samourai.io/wallet/ExtLibJ/-/blob/develop/doc/cahoots/STOWAWAY.md|Stowaway]] is a payjoin coordination mechanism which depends on Tor, a third-party relay, and the [[https://samouraiwallet.com/paynym|PayNym]] [[https://github.com/bitcoin/bips/blob/master/bip-0047.mediawiki|BIP 47]] Payment codes directory for subdirectory identification and encryption. The payjoin version 2 protocol uses per-request public keys for relay subdirectory identification, authentication, and encryption instead of BIP 47 public keys derived from a wallet. Payjoin version 2 also supports asynchronous messaging, in contrast to Stowaway's synchronous messaging. Offline stowaway depends on manual message passing rather than an asynchronous network protocol. Successful Stowaway execution results in 2-output transactions, while BIP 78, and this work may produce batched transactions with many outputs.

---

  43 | +
  44 | +==Specification==
  45 | +
  46 | +===Overview===
  47 | +
  48 | +Payjoin requests are made using familiar BIP 21 URIs. Instead of a public HTTP endpoint, this scheme allows an HTTP client to enroll with a store-and-forward directory server to receive payjoin. Directories may optionally require an authorization credential before allocating resources in order to prevent DoS attacks. Sender and receiver payloads are buffered at the directory to support asynchronous interaction. Authenticated encryption prevents the directory from snooping on message contents or forging messages by way of HPKE. Oblivious HTTP is required for version 2 interactions in order to separate client IP addresses from the directory to prevent metadata attacks. Aside from a application layer authenticated encryption and relayed asynchronus networking, the version 2 messaging takes much the same form as the existing BIP 78 specification.

---

  69 | +- The sender continues to replay this request in order to await a response from the directory containing a <code>Payjoin PSBT</code>. It stops after expiry.
  70 | +- The request is stored in the subdirectory.
  71 | +- Once the receiver is online, it sends <code>/receive</code>requests to await updates from the subdirectory. The receiver decrypts and authenticates the response which it checks according to [[https://github.com/bitcoin/bips/blob/master/bip-0078#receivers-original-psbt-checklist|the receiver checklist]]. It updates the Original PSBT to include new signed inputs and outputs, invalidating sender signatures, and may adjust the fee. The result is called the <code>Payjoin PSBT</code>.
  72 | +- The <code>Payjoin PSBT</code> and HPKE keys are encrypted, authenticated, encapsulated in OHTTP, and sent to the directory's OHTTP Gateway.
  73 | +- The directory awaits a request from the sender if it goes offline. Upon request, it relays the encrypted <code>Payjoin PSBT</code>.
  74 | +- The sender validates the <code>Payjoin PSBT</code> according to [[#senders-payjoin-psbt-checklist|the sender checklist]], signs its inputs and broadcasts the transaction to the Bitcoin network.

---

  77 | +
  78 | +- Include complete UTXO data.
  79 | +- Be signed.
  80 | +- Exclude unnecessary fields such as global xpubs or keypath information. <!-- I believe PSBTv2 obviates this requirement -->
  81 | +- Set input and output Transaction Modifiable Flags to 1
  82 | +- Be broadcastable.

---

  82 | +- Be broadcastable.
  83 | +
  84 | +The Original PSBT MAY:
  85 | +
  86 | +- Include outputs unrelated to the sender-receiver transfer for batching purposes.
  87 | +- Set SIGHASH_SINGLE Transaction Modifiable Flags flags to 1

---

  88 | +
  89 | +The Payjoin PSBT MUST:
  90 | +
  91 | +- Include all inputs from the Original PSBT.
  92 | +- Include all outputs which do not belong to the receiver from the Original PSBT.
  93 | +- Include complete UTXO data.

---

  92 | +- Include all outputs which do not belong to the receiver from the Original PSBT.
  93 | +- Include complete UTXO data.
  94 | +
  95 | +The Payjoin PSBT sender MAY:
  96 | +
  97 | +- Add, remove or modify Original PSBT outputs under the control of the receiver (i.e. not sender change).

---

  97 | +- Add, remove or modify Original PSBT outputs under the control of the receiver (i.e. not sender change).
  98 | +
  99 | +The Payjoin PSBT MUST NOT:
 100 | +
 101 | +- Shuffle the order of inputs or outputs; the additional outputs or additional inputs must be inserted at a random index.
 102 | +- Decrease the absolute fee of the original transaction.

---

 101 | +- Shuffle the order of inputs or outputs; the additional outputs or additional inputs must be inserted at a random index.
 102 | +- Decrease the absolute fee of the original transaction.
 103 | +
 104 | +====Enroll Messaging====
 105 | +
 106 | +Receivers must enroll with a directory to a subdirectory allocated. 

---

 146 | +A major benefit of BIP 78 payjoin over other coordination mechanisms is its compatibility with the universal BIP 21 bitcoin URI standard.
 147 | +
 148 | +This proposal defines the following new [[https://github.com/bitcoin/bips/blob/master/bip-0021.mediawiki|BIP 21 URI]] parameters:
 149 | +
 150 | +- <code>ohttp</code> represents the OHTTP Key Configuration of the directory server. This is a base64URL encoded public key of the directory server's OHTTP Gateway. This parameter is required for version 2 payjoin URIs.
 151 | +- <code>exp</code>: represents a request expiration after which the receiver reserves the right to broadcast the transaction extracted from the Original PSBT and ignore requests. This is only necessary for receivers who only support synchonous execution of the protocol, like automated payment processors.

---

 152 | +
 153 | +===Optional sender parameters===
 154 | +
 155 | +When the payjoin sender posts the original PSBT to the receiver, it can optionally specify the following HTTP query string parameters:
 156 | +
 157 | +- <code>v</code>: represents the version number of the payjoin protocol that the sender is using. This version is <code>2</code>.

---

 180 | +
 181 | +All cyphertexts should be padded to the same length of 7168 bytes to prevent traffic analysis. This is sufficient size for most transaction PSBTs without exceeding the 8KB limit of many HTTP/1.1 web servers.
 182 | +
 183 | +===Secp256k1 Hybrid Public Key Encryption===
 184 | +
 185 | +Hybrid Public Key Encryption is a modern web standard for secure message exchange without TLS. Since client and server agree on a configuration out of band, we can pre-define the payjoin v2 appication specific configuration to use DHKEM(Secp256k1, HKDF-SHA256) and ChaCha20Poly1305 AEAD.

---

 212 | +
 213 | +===Network privacy=== 
 214 | +
 215 | +Oblivious HTTP must be used to protect the IP address of both sender and receiver from the directory. This requires an additional key configuration to be shared in the bip21 URI and for the directory to support Oblivious HTTP. A secp256k1 HPKE OHTTP configuration should be used to leverage the cryptography already available in bitcoin contexts.
 216 | +
 217 | +Unlike BIP 78 implementations, sender and receiver peers will only see the IP address of the directory, not their peers. Directories may aditionally be made available via Tor hidden service to allow either of the peers to protect their IP from the directory with without OHTTP.

---

   0 | @@ -0,0 +1,237 @@
   1 | +<pre>
   2 | +  BIP: 77
   3 | +  Layer: Applications
   4 | +  Title: Payjoin Version 2: Serverless Payjoin
   5 | +  Author: Dan Gould <d@ngould.dev>
   6 | +  Comments-URI: https://github.com/bitcoin/bips/wiki/Comments:BIP-0077
   7 | +  Status: Draft
   8 | +  Replaces: 78

---

  42 | +
  43 | +==Specification==
  44 | +
  45 | +===Overview===
  46 | +
  47 | +Payjoin requests are made using familiar BIP 21 URIs. Instead of a public HTTP endpoint, this scheme allows an HTTP client to enroll with a store-and-forward directory server to receive payjoin. Directories may optionally require an authorization credential before allocating resources in order to prevent DoS attacks. Sender and receiver payloads are buffered at the directory to support asynchronous interaction. Authenticated encryption prevents the directory from snooping on message contents or forging messages by way of HPKE. Oblivious HTTP is required for version 2 interactions in order to separate client IP addresses from the directory to prevent metadata attacks. Aside from a application layer authenticated encryption and relayed asynchronous networking, the version 2 messaging takes much the same form as the existing BIP 78 specification.

---

 174 | +
 175 | +The version 2 sender's checklist is largely the same as the [[https://github.com/bitcoin/bips/blob/master/bip-0078#senders-payjoin-proposal-checklist|the BIP 78 checklist]] with the exception that it expects ALL utxo data to be filled in. BIP 78 required sender inputs UTXO data to be excluded from the PSBT which has caused many headaches since it required the sender to add them back to the Payjoin proposal PSBT. Version 2 has no such requirement.
 176 | +
 177 | +===Directory interactions===
 178 | +
 179 | +The Payjoin Directory provides a rendezvous point for sender and receiver to meet. It stores Payjoin payloads to support asynchronous communication. It must only accept OHTTP requests with an OHTTP Gateway for Payjoin version 2, accepting encrypted payloads. It may optionally accept HTTP/1.1 POST requests without HTTP to enrolled subdirectories to support backwards compatible Payjoin version 1 requests.

---

 170 | +
 171 | +Other than requiring PSBTv2 the receiver checklist is the same as the [[https://github.com/bitcoin/bips/blob/master/bip-0078.mediawiki#receivers-original-psbt-checklist|the BIP 78 receiver checklist]]
 172 | +
 173 | +===Sender's Payjoin PSBT checklist===
 174 | +
 175 | +The version 2 sender's checklist is largely the same as the [[https://github.com/bitcoin/bips/blob/master/bip-0078#senders-payjoin-proposal-checklist|the BIP 78 checklist]] with the exception that it expects ALL utxo data to be filled in. BIP 78 required sender inputs UTXO data to be excluded from the PSBT which has caused many headaches since it required the sender to add them back to the Payjoin proposal PSBT. Version 2 has no such requirement.

---

 102 | +
 103 | +Payjoin v2 messages use [[https://github.com/bitcoin/bips/blob/master/bip-0370.mediawiki|BIP 370 PSBT v2]] format to fascilitate PSBT mutation.
 104 | +
 105 | +The payjoin version 2 protocol takes the following steps:
 106 | +
 107 | +* The recipient sends their payjoin pubkey and optional authentication credential according to [[#directory-enrollment|receiver directory enrollment]] protocol to receive a subdirectory allocation. It may go offline and replay enrollment to come back online.

---

 104 | +
 105 | +The payjoin version 2 protocol takes the following steps:
 106 | +
 107 | +* The recipient sends their payjoin pubkey and optional authentication credential according to [[#directory-enrollment|receiver directory enrollment]] protocol to receive a subdirectory allocation. It may go offline and replay enrollment to come back online.
 108 | +* Out of band, the receiver of the payment, shares a bitcoin URI with the sender including a <code>pj=</code> query parameter including the subdirectory as a base64URL encoded pubkey. To support version 1 senders the directory acts as an unsecured payjoin server so <code>pjos=0</code> must be specified in the URI. Version 2 senders may safely allow output substitution regardless. An <code>ohttp=</code> parameter containing the directory's base64URL Key Config should also be provided.
 109 | +* The sender creates a valid version 2 PSBT satisfying the [[https://github.com/bitcoin/bips/blob/master/bip-0078#receivers-original-psbt-checklist|the receiver checklist]]. We call this the <code>Original PSBT</code>. This <code>Original PSBT</code>, optional sender parameters, and HPKE keys are encrypted and authenticated, and encapsulated in OHTTP. This [[#original-psbt-request|Original PSBT Request]] is sent to the directory's OHTTP Gateway.

---

  98 | +|- - -> Polled transmission
  99 | +</pre>
 100 | +
 101 | +===Payjoin version 2 messaging===
 102 | +
 103 | +Payjoin v2 messages use [[https://github.com/bitcoin/bips/blob/master/bip-0370.mediawiki|BIP 370 PSBT v2]] format to fascilitate PSBT mutation.

---

 138 | +* Add, remove or modify Original PSBT outputs under the control of the receiver (i.e. not sender change).
 139 | +
 140 | +The Payjoin PSBT MUST NOT:
 141 | +
 142 | +* Shuffle the order of inputs or outputs; the additional outputs or additional inputs must be inserted at a random index.
 143 | +* Decrease the absolute fee of the original transaction.

---

 258 | +
 259 | +===Network privacy===
 260 | +
 261 | +Oblivious HTTP must be used to protect the IP address of both sender and receiver from the directory. This requires an additional key configuration to be shared in the bip21 URI and for the directory to support Oblivious HTTP. A secp256k1 HPKE OHTTP configuration should be used to leverage the cryptography already available in bitcoin contexts.
 262 | +
 263 | +Unlike BIP 78 implementations, sender and receiver peers will only see the IP address of the directory, not their peers. Directories may additionally be made available via Tor hidden service to allow either of the peers to protect their IP from the directory with without OHTTP.

---

 107 | +* The recipient sends their payjoin pubkey and optional authentication credential according to the [[#enroll-messaging|enroll messaging]] protocol to receive a subdirectory allocation. It may go offline and replay enrollment to come back online.
 108 | +* Out of band, the receiver of the payment, shares a bitcoin URI with the sender including a <code>pj=</code> query parameter including the subdirectory as a base64URL encoded pubkey. To support version 1 senders the directory acts as an unsecured payjoin server so <code>pjos=0</code> must be specified in the URI. Version 2 senders may safely allow output substitution regardless. An <code>ohttp=</code> parameter containing the directory's base64URL Key Config should also be provided.
 109 | +* The sender creates a valid version 2 PSBT satisfying the [[https://github.com/bitcoin/bips/blob/master/bip-0078.mediawiki#receivers-original-psbt-checklist the receiver checklist]]. We call this the <code>Original PSBT</code>. This <code>Original PSBT</code>, optional sender parameters, and HPKE keys are encrypted and authenticated, and encapsulated in OHTTP. This [[#send-messaging|Original PSBT Request send message]] is sent to the directory's OHTTP Gateway.
 110 | +* The sender continues to replay this request in order to await a response from the directory containing a <code>Payjoin PSBT</code>. It stops after expiry.
 111 | +* The request is stored in the subdirectory.
 112 | +* Once the receiver is online, it sends <code>/receive</code>requests to await updates from the subdirectory. The receiver decrypts and authenticates the response which it checks according to [[https://github.com/bitcoin/bips/blob/master/bip-0078.mediawiki#receivers-original-psbt-checklist the receiver checklist]]. It updates the Original PSBT to include new signed inputs and outputs, invalidating sender signatures, and may adjust the fee. The result is called the <code>Payjoin PSBT</code>.

---

 160 | +
 161 | +The directory's OHTTP Gateway decapsulates the OHTTP request, decrypts the payload, and forwards the BHTTP POST request to the receiver's internal subdirectory endpoint which stores the HPKE encrypted payload to be forwarded to the receiver. The directory's OHTTP Gateway then awaits a response from the receiver's subdirectory endpoint, encapsulates it, and responds according to OHTTP.
 162 | +
 163 | +====Receive Messaging====
 164 | +
 165 | +The receiver sends a GET request to the path of the subdirectory followed by `/receive`. This request is encapsulated in OHTTP. It awaits an OHTTP response from the directory containing the BHTTP request from the sender with status code 200 OK, or sends a new OHTTP request after receiving 202 ACCEPTED notifying the receiver that the directory has not yet received an request from the sender.

---

 162 | +
 163 | +====Receive Messaging====
 164 | +
 165 | +The receiver sends a GET request to the path of the subdirectory followed by `/receive`. This request is encapsulated in OHTTP. It awaits an OHTTP response from the directory containing the BHTTP request from the sender with status code 200 OK, or sends a new OHTTP request after receiving 202 ACCEPTED notifying the receiver that the directory has not yet received an request from the sender.
 166 | +
 167 | +Once an Original PSBT Payload is decrypted and checked according to the list, the receiver may respond with a Payjoin PSBT. The receiver encrypts the PSBT according to the HPKE protocol, generating an ephemeral keypair `e` from which it derives a shared secret `ee` with the sender's key `e` from the payload. It generates a nonce from sufficient randomness, and constructs a ciphertext containing the Payjoin PSBT and serialized receiver ephemeral key `e`'s pubkey as associated data using ChaCha20Poly1305. A payload is constructed by concatenating the ephemeral pubkey, the nonce, and the ciphertext. This payload is then sent to the directory in an OHTTP request encapsulating the binary payload as a POST message to the subdirectory followed by `/receive`.

---

  48 | +
  49 | +===Basic scheme===
  50 | +
  51 | +The receiver first generates a 256-bit keypair. This key will be the basis of end-to-end authenticated encryption and identification of a particular payjoin over the directory.
  52 | +
  53 | +Rather than hosting a public server, they start a session to receive messages and allocate a subdirectory from which to relay messages. The first message must include their pubkey to be enrolled as a subdirectory identifier. The next message from the directory to sender includes the enrolled subdirectory payjoin endpoint with the pubkey as identifying subdirectory. After enrollment, they await a payjoin request on a session identified by the subdirectory. Out of band, the receiver shares a [[https://github.com/bitcoin/bips/blob/master/bip-0021.mediawiki BIP 21]] payjoin uri including the directory endpoint in the <code>pj=</code> query parameter and a new <code>ohttp=</code> parameter including the payjoin directory's [[https://www.ietf.org/rfc/rfc9458.html#name-key-configuration OHTTP Key Configuration]].

---

  36 | +
  37 | +The protocols in this document reuse BIP 78's BIP 21 URI parameters. A Original PSBT timeout parameter is introduced which may also help coordinate the synchronous version 1 protocol.
  38 | +
  39 | +===Relation to Stowaway===
  40 | +
  41 | +[[https://code.samourai.io/wallet/ExtLibJ/-/blob/develop/doc/cahoots/STOWAWAY.md Stowaway]] is a payjoin coordination mechanism which depends on Tor, a third-party relay, and the [[https://samouraiwallet.com/paynym PayNym]] [[https://github.com/bitcoin/bips/blob/master/bip-0047.mediawiki BIP 47]] Payment codes directory for subdirectory identification and encryption. The payjoin version 2 protocol uses per-request public keys for relay subdirectory identification, authentication, and encryption instead of BIP 47 public keys derived from a wallet. Payjoin version 2 also supports asynchronous messaging, in contrast to Stowaway's synchronous messaging. Offline Stowaway depends on manual message passing rather than an asynchronous network protocol. Successful Stowaway execution results in 2-output transactions, while BIP 78, and this work may produce batched transactions with many outputs.

---

  22 | +
  23 | +Payjoin is the simplest case of interactive bitcoin batching, allowing two participants to combine their transaction intents. It solves the sole privacy problem left open in the bitcoin paper, that transactions with multiple inputs "necessarily reveal that their inputs were owned by the same owner," by enabling two owners to provide input in a transaction.
  24 | +
  25 | +The payjoin protocols automate cooperative transaction construction to break that common-input assumption. The increased the opportunity to batch payments and and execute transaction cut-through increases intent throughput, since multiple intents combined take up fewer bytes than independent transactions.
  26 | +
  27 | +Version 1's requirements have proven to be an obstacle to adoption. V1 coordinates payjoins over a public server endpoint secured by either TLS or Tor hidden service hosted by the receiver. Version 1 is also synchronous, requiring both sender and receiver to be online simultaneously to payjoin. Both requirements present significant barriers for all but sophisticated server operators or those wallets with complex Tor integration. Wallet developers [[https://lists.linuxfuihjknhoundation.org/pipermail/bitcoin-dev/2021-January/018358.html| regard]] these as limits to payjoin adoption.

---

  20 | +
  21 | +==Motivation==
  22 | +
  23 | +Payjoin is the simplest case of interactive bitcoin batching, allowing two participants to combine their transaction intents. It solves the sole privacy problem left open in the bitcoin paper, that transactions with multiple inputs "necessarily reveal that their inputs were owned by the same owner," by enabling two owners to provide input in a transaction.
  24 | +
  25 | +The payjoin protocols automate cooperative transaction construction to break that common-input assumption. The increased the opportunity to batch payments and and execute transaction cut-through increases intent throughput, since multiple intents combined take up fewer bytes than independent transactions.

---

 105 | +Payjoin v2 messages use [[https://github.com/bitcoin/bips/blob/master/bip-0370.mediawiki| BIP 370 PSBT v2]] format to facilitate PSBT mutation.
 106 | +
 107 | +The payjoin version 2 protocol takes the following steps:
 108 | +
 109 | +* The recipient sends their payjoin pubkey and optional authentication credential according to the [[#enroll-messaging|enroll messaging]] protocol to receive a subdirectory allocation. It may go offline and replay enrollment to come back online.
 110 | +* Out of band, the receiver of the payment, shares a bitcoin URI with the sender including a <code>pj=</code> query parameter including the subdirectory as a base64URL encoded pubkey. To support version 1 senders the directory acts as an unsecured payjoin server so <code>pjos=0</code> must be specified in the URI. Version 2 senders may safely allow output substitution regardless. An <code>ohttp=</code> parameter containing the directory's base64URL Key Config should also be provided.

---

  10 | +  License: BSD-2-Clause
  11 | +</pre>
  12 | +
  13 | +==Abstract==
  14 | +
  15 | +This document proposes a backwards-compatible second version of the payjoin protocol described in [[bip-0078.mediawiki|BIP 78]], allowing complete payjoin receiver functionality including payment output substitution without requiring one to host a secure public endpoint. This requirement is replaced with an untrusted third-party directory accessed via HTTP clients which communicate using an asynchronous protocol and authenticated, encrypted payloads. Authenticated encryption depends only on cryptographic primitives available in Bitcoin Core. Requests use [[https://www.ietf.org/rfc/rfc9458.html| Oblivious HTTP]] to prevent the directory and payjoin peers from linking requests to client IP addresses.

---

  22 | +
  23 | +Payjoin is the simplest case of interactive bitcoin batching, allowing two participants to combine their transaction intents. It solves the sole privacy problem left open in the bitcoin paper, that transactions with multiple inputs "necessarily reveal that their inputs were owned by the same owner," by enabling two owners to provide input in a transaction.
  24 | +
  25 | +The payjoin protocols automate cooperative transaction construction to break that common-input assumption. The increased opportunity to batch payments and execute transaction cut-through increases intent throughput, since multiple intents combined take up fewer bytes than independent transactions.
  26 | +
  27 | +Version 1's requirements have proven to be an obstacle to adoption. V1 coordinates payjoins over a public server endpoint secured by either TLS or Tor hidden service hosted by the receiver. Version 1 is also synchronous, requiring both sender and receiver to be online simultaneously to payjoin. Both requirements present significant barriers for all but sophisticated server operators or those wallets with complex Tor integration. Wallet developers [[https://lists.linuxfoundation.org/pipermail/bitcoin-dev/2021-January/018358.html| regard]] these as limits to payjoin adoption.

---

  24 | +
  25 | +The payjoin protocols automate cooperative transaction construction to break that common-input assumption. The increased opportunity to batch payments and execute transaction cut-through increases intent throughput, since multiple intents combined take up fewer bytes than independent transactions.
  26 | +
  27 | +Version 1's requirements have proven to be an obstacle to adoption. V1 coordinates payjoins over a public server endpoint secured by either TLS or Tor hidden service hosted by the receiver. Version 1 is also synchronous, requiring both sender and receiver to be online simultaneously to payjoin. Both requirements present significant barriers for all but sophisticated server operators or those wallets with complex Tor integration. Wallet developers [[https://lists.linuxfoundation.org/pipermail/bitcoin-dev/2021-January/018358.html| regard]] these as limits to payjoin adoption.
  28 | +
  29 | +The primary goal of this proposal is to provide a practical coordination mechanism viable to implement in a majority of bitcoin software environments. This is realized as a simple protocol built on bitcoin URI requests, web standards, common crypto, and minimal dependencies.

---

  28 | +
  29 | +The primary goal of this proposal is to provide a practical coordination mechanism viable to implement in a majority of bitcoin software environments. This is realized as a simple protocol built on bitcoin URI requests, web standards, common crypto, and minimal dependencies.
  30 | +
  31 | +===Relation to BIP 78 (Payjoin version 1)===
  32 | +
  33 | +The message payloads in this version parallel those used in BIP 78 while being encapsulated in authenticated encryption. TLS and Tor security, which depend on third-party authorities, are replaced with Hybrid Public Key Encryption ([[https://www.rfc-editor.org/rfc/rfc9180| HPKE]]). The synchronous HTTP client-server model is replaced with an asynchronous store-and-forward mechanism. This protocol also upgrades to PSBT version 2 to simplify transaction construction.

---

  34 | +
  35 | +The BIP 78 standard allows for an [[https://github.com/bitcoin/bips/blob/master/bip-0078.mediawiki#unsecured-payjoin-server| unsecured payjoin server|]] to operate separately from the so-called "payment server" responsible for generating [[https://github.com/bitcoin/bips/blob/master/bip-0021.mediawiki| BIP 21]] request URIs. Because BIP 78 messages relayed over an unsecured server are neither end-to-end authenticated nor encrypted between sender and receiver, a malicious unsecured payjoin server is able to modify the Payjoin PSBT in flight, thus requiring payment output substitution to be disabled. Output substitution is useful for a number of block space optimizations, including payment batching and transaction cut-through. This proposal introduces authentication and encryption to secure output substitution while using a directory relay without compromising sender or receiver privacy.
  36 | +
  37 | +Although unsecured payjoin server separation is mentioned in BIP 78, no known specification or implementation exists. This document specifies a way to use the payjoin directory as an unsecured backwards compatible server for version 1 senders. Receivers responding to version 1 senders must disable output substitution, since their payloads are saved in plaintext, so that they may payjoin without the risk of the directory stealing funds.
  38 | +
  39 | +The protocols in this document reuse BIP 78's BIP 21 URI parameters. A Original PSBT timeout parameter is introduced which may also help coordinate the synchronous version 1 protocol.

---

  38 | +
  39 | +The protocols in this document reuse BIP 78's BIP 21 URI parameters. A Original PSBT timeout parameter is introduced which may also help coordinate the synchronous version 1 protocol.
  40 | +
  41 | +===Relation to Stowaway===
  42 | +
  43 | +[[https://docs.samourai.io/en/spend-tools#stowaway| Stowaway]] was a payjoin coordination mechanism which depends on Tor, a third-party relay, and the [[https://paynym.is| PayNym]] [[https://github.com/bitcoin/bips/blob/master/bip-0047.mediawiki| BIP 47]] Payment codes directory for subdirectory identification and encryption. The payjoin version 2 protocol uses per-request public keys for relay subdirectory identification, authentication, and encryption instead of BIP 47 public keys derived from a wallet. Payjoin version 2 also supports asynchronous messaging, in contrast to Stowaway's synchronous messaging. Offline Stowaway depends on manual message passing rather than an asynchronous network protocol. Successful Stowaway execution results in 2-output transactions, while BIP 78, and this work may produce batched transactions with many outputs.

---

  50 | +
  51 | +===Basic scheme===
  52 | +
  53 | +The receiver first generates a 256-bit keypair. This key will be the basis of end-to-end authenticated encryption and identification of a particular payjoin over the directory.
  54 | +
  55 | +Rather than hosting a public server, they start a session to receive messages and allocate a subdirectory from which to relay messages. The first message must include their public key to be enrolled as a subdirectory identifier. The response message from the directory to receiver includes the newly enrolled subdirectory payjoin endpoint with the public key as identifying subdirectory. After enrollment, they await a payjoin request on a session identified by the subdirectory. Out of band, the receiver shares a [[https://github.com/bitcoin/bips/blob/master/bip-0021.mediawiki| BIP 21]] payjoin uri including the directory endpoint in the <code>pj=</code> query parameter and a new <code>ohttp=</code> parameter including the payjoin directory's [[https://www.ietf.org/rfc/rfc9458.html#name-key-configuration| OHTTP Key Configuration]].

---

  52 | +
  53 | +The receiver first generates a 256-bit keypair. This key will be the basis of end-to-end authenticated encryption and identification of a particular payjoin over the directory.
  54 | +
  55 | +Rather than hosting a public server, they start a session to receive messages and allocate a subdirectory from which to relay messages. The first message must include their public key to be enrolled as a subdirectory identifier. The response message from the directory to receiver includes the newly enrolled subdirectory payjoin endpoint with the public key as identifying subdirectory. After enrollment, they await a payjoin request on a session identified by the subdirectory. Out of band, the receiver shares a [[https://github.com/bitcoin/bips/blob/master/bip-0021.mediawiki| BIP 21]] payjoin uri including the directory endpoint in the <code>pj=</code> query parameter and a new <code>ohttp=</code> parameter including the payjoin directory's [[https://www.ietf.org/rfc/rfc9458.html#name-key-configuration| OHTTP Key Configuration]].
  56 | +
  57 | +The sender constructs an encrypted and authenticated payload containing a PSBT and optional parameters similar to BIP 78. The resulting ciphertext ensures message secrecy and integrity when passed to the recipient by the subdirectory <code>pj=</code> endpoint.

---

 100 | +|- - -> Polled transmission
 101 | +</pre>
 102 | +
 103 | +===Payjoin version 2 messaging===
 104 | +
 105 | +Payjoin v2 messages use [[https://github.com/bitcoin/bips/blob/master/bip-0370.mediawiki| BIP 370 PSBT v2]] format to facilitate PSBT mutation.

---

 104 | +
 105 | +Payjoin v2 messages use [[https://github.com/bitcoin/bips/blob/master/bip-0370.mediawiki| BIP 370 PSBT v2]] format to facilitate PSBT mutation.
 106 | +
 107 | +The payjoin version 2 protocol takes the following steps:
 108 | +
 109 | +* The recipient sends their payjoin public key and optional authentication credential according to the [[#enroll-messaging|enroll messaging]] protocol to receive a subdirectory allocation. It may go offline and replay enrollment to come back online.

---

 105 | +Payjoin v2 messages use [[https://github.com/bitcoin/bips/blob/master/bip-0370.mediawiki| BIP 370 PSBT v2]] format to facilitate PSBT mutation.
 106 | +
 107 | +The payjoin version 2 protocol takes the following steps:
 108 | +
 109 | +* The recipient sends their payjoin public key and optional authentication credential according to the [[#enroll-messaging|enroll messaging]] protocol to receive a subdirectory allocation. It may go offline and replay enrollment to come back online.
 110 | +* Out of band, the receiver of the payment shares a bitcoin URI with the sender including a <code>pj=</code> query parameter where the subdirectory is a base64URL encoded public key. To support version 1 senders the directory acts as an unsecured payjoin server so <code>pjos=0</code> must be specified in the URI. Version 2 senders may safely allow output substitution regardless. An <code>ohttp=</code> parameter containing the directory's base64URL Key Config must also be provided.

---

 109 | +* The recipient sends their payjoin public key and optional authentication credential according to the [[#enroll-messaging|enroll messaging]] protocol to receive a subdirectory allocation. It may go offline and replay enrollment to come back online.
 110 | +* Out of band, the receiver of the payment shares a bitcoin URI with the sender including a <code>pj=</code> query parameter where the subdirectory is a base64URL encoded public key. To support version 1 senders the directory acts as an unsecured payjoin server so <code>pjos=0</code> must be specified in the URI. Version 2 senders may safely allow output substitution regardless. An <code>ohttp=</code> parameter containing the directory's base64URL Key Config must also be provided.
 111 | +* The sender creates a valid version 2 PSBT satisfying the [[https://github.com/bitcoin/bips/blob/master/bip-0078.mediawiki#receivers-original-psbt-checklist| the receiver checklist]]. We call this the <code>Original PSBT</code>. This <code>Original PSBT</code>, optional sender parameters, and HPKE keys are encrypted and authenticated, and encapsulated in OHTTP. This [[#send-messaging|Original PSBT Request send message]] is sent to the directory's OHTTP Gateway.
 112 | +* The sender continues to replay this request in order to await a response from the directory containing a <code>Payjoin PSBT</code>. It stops after expiry.
 113 | +* The request is stored in the subdirectory.
 114 | +* Once the receiver is online, it sends <code>/receive</code> requests to await updates from the subdirectory. The receiver decrypts and authenticates the response which it checks according to [[https://github.com/bitcoin/bips/blob/master/bip-0078.mediawiki#receivers-original-psbt-checklist| the receiver checklist]]. It updates the Original PSBT to include new signed inputs and outputs, invalidating sender signatures, and may adjust the fee. The result is called the <code>Payjoin PSBT</code>.

---

 111 | +* The sender creates a valid version 2 PSBT satisfying the [[https://github.com/bitcoin/bips/blob/master/bip-0078.mediawiki#receivers-original-psbt-checklist| the receiver checklist]]. We call this the <code>Original PSBT</code>. This <code>Original PSBT</code>, optional sender parameters, and HPKE keys are encrypted and authenticated, and encapsulated in OHTTP. This [[#send-messaging|Original PSBT Request send message]] is sent to the directory's OHTTP Gateway.
 112 | +* The sender continues to replay this request in order to await a response from the directory containing a <code>Payjoin PSBT</code>. It stops after expiry.
 113 | +* The request is stored in the subdirectory.
 114 | +* Once the receiver is online, it sends <code>/receive</code> requests to await updates from the subdirectory. The receiver decrypts and authenticates the response which it checks according to [[https://github.com/bitcoin/bips/blob/master/bip-0078.mediawiki#receivers-original-psbt-checklist| the receiver checklist]]. It updates the Original PSBT to include new signed inputs and outputs, invalidating sender signatures, and may adjust the fee. The result is called the <code>Payjoin PSBT</code>.
 115 | +* The <code>Payjoin PSBT</code> and HPKE keys are encrypted, authenticated, encapsulated in OHTTP, and sent to the directory's OHTTP Gateway.
 116 | +* The directory awaits a request from the sender if it goes offline. Upon request, it relays the encrypted <code>Payjoin PSBT</code>.

---

 119 | +The Original PSBT MUST:
 120 | +
 121 | +* Include complete UTXO data.
 122 | +* Be signed.
 123 | +* Exclude unnecessary fields such as global xpubs or keypath information. <!-* I believe PSBTv2 obviates this requirement -->
 124 | +* Set input and output Transaction Modifiable Flags to 1

---

 118 | +
 119 | +The Original PSBT MUST:
 120 | +
 121 | +* Include complete UTXO data.
 122 | +* Be signed.
 123 | +* Exclude unnecessary fields such as global xpubs or keypath information. <!-* I believe PSBTv2 obviates this requirement -->

---

 144 | +* Shuffle the order of inputs or outputs; the additional outputs or additional inputs must be inserted at a random index.
 145 | +* Decrease the absolute fee of the original PSBT.
 146 | +
 147 | +====Enroll Messaging====
 148 | +
 149 | +Receivers must enroll with a directory to have a subdirectory allocated to them as follows.

---

 150 | +
 151 | +A receiver must first discover the directory's OHTTP gateway key configuration via an authenticated bootstrap mechanism before it can enroll to receive payjoin requests. This mechanism may vary by implementation but must follow [[https://datatracker.ietf.org/doc/html/draft-ietf-privacypass-key-consistency-01| OHTTP Consistency Requirements]] and should not reveal a receiver IP address to the directory. Some examples of suitable mechanisms include fetching over a VPN, using keys included with an application binary, https-in-http CONNECT method, https-in-WebSocket, or a Tor hidden service.
 152 | +
 153 | +Payjoin sessions begin by having a receiver send the static public key to the directory via OHTTP, receiving their subdirectory in a base64URL encoded directory url as response. Enrollment may be replayed in case the receiver goes offline and should result in the same response.
 154 | +
 155 | +Optionally, before returning the uri the receiver may request an authentication token by presenting a message containing only the word <code>Authenticate: <description></code> after which the receiver is required to submit an <code>Authenticate: <token></code> including the token from the directory out of band. If authentication fails an error is returned.

---

 152 | +
 153 | +Payjoin sessions begin by having a receiver send the static public key to the directory via OHTTP, receiving their subdirectory in a base64URL encoded directory url as response. Enrollment may be replayed in case the receiver goes offline and should result in the same response.
 154 | +
 155 | +Optionally, before returning the uri the receiver may request an authentication token by presenting a message containing only the word <code>Authenticate: <description></code> after which the receiver is required to submit an <code>Authenticate: <token></code> including the token from the directory out of band. If authentication fails an error is returned.
 156 | +
 157 | +In the case a directory is operated by an exchange, it may give out authentication tokens for users of its app, or may require some proof of work out of band. Tokens should be anonymous credentials from the directory describing the parameters of their authorization. Specific credentialing is out of the scope of this proposal.

---

 156 | +
 157 | +In the case a directory is operated by an exchange, it may give out authentication tokens for users of its app, or may require some proof of work out of band. Tokens should be anonymous credentials from the directory describing the parameters of their authorization. Specific credentialing is out of the scope of this proposal.
 158 | +
 159 | +====Send Messaging====
 160 | +
 161 | +The version 2 Original PSBT is placed in an HTTP POST request body as binary before being encoded into BHTTP and encrypted according to the HPKE protocol. This Original PSBT BHTTP Request is then encrypted according to the HPKE, generating an ephemeral keypair <code>e</code> from which it derives a shared secret <code>es</code> with the receiver's key <code>s</code>. It generates a nonce from sufficient randomness, and constructs a ciphertext containing the Original PSBT BHTTP Request and serialized ephemeral key <code>e</code>'s public key as associated data using ChaCha20Poly1305. A payload is constructed by concatenating the ephemeral public key, the nonce, and the ciphertext. This payload is then sent to the directory in an OHTTP request encapsulating the binary payload.

---

 158 | +
 159 | +====Send Messaging====
 160 | +
 161 | +The version 2 Original PSBT is placed in an HTTP POST request body as binary before being encoded into BHTTP and encrypted according to the HPKE protocol. This Original PSBT BHTTP Request is then encrypted according to the HPKE, generating an ephemeral keypair <code>e</code> from which it derives a shared secret <code>es</code> with the receiver's key <code>s</code>. It generates a nonce from sufficient randomness, and constructs a ciphertext containing the Original PSBT BHTTP Request and serialized ephemeral key <code>e</code>'s public key as associated data using ChaCha20Poly1305. A payload is constructed by concatenating the ephemeral public key, the nonce, and the ciphertext. This payload is then sent to the directory in an OHTTP request encapsulating the binary payload.
 162 | +
 163 | +The directory's OHTTP Gateway decapsulates the OHTTP request, decrypts the payload, and forwards the BHTTP POST request to the receiver's internal subdirectory endpoint which stores the HPKE encrypted payload to be forwarded to the receiver. The directory's OHTTP Gateway then awaits a response from the receiver's subdirectory endpoint, encapsulates it, and responds according to OHTTP.

---

 162 | +
 163 | +The directory's OHTTP Gateway decapsulates the OHTTP request, decrypts the payload, and forwards the BHTTP POST request to the receiver's internal subdirectory endpoint which stores the HPKE encrypted payload to be forwarded to the receiver. The directory's OHTTP Gateway then awaits a response from the receiver's subdirectory endpoint, encapsulates it, and responds according to OHTTP.
 164 | +
 165 | +====Receive Messaging====
 166 | +
 167 | +The receiver sends a GET request to the path of the subdirectory followed by <code>/receive</code>. This request is encapsulated in OHTTP. It awaits an OHTTP response from the directory containing the BHTTP request from the sender with status code 200 OK, or sends a new OHTTP request after receiving 202 ACCEPTED notifying the receiver that the directory has not yet received an request from the sender.

---

 164 | +
 165 | +====Receive Messaging====
 166 | +
 167 | +The receiver sends a GET request to the path of the subdirectory followed by <code>/receive</code>. This request is encapsulated in OHTTP. It awaits an OHTTP response from the directory containing the BHTTP request from the sender with status code 200 OK, or sends a new OHTTP request after receiving 202 ACCEPTED notifying the receiver that the directory has not yet received an request from the sender.
 168 | +
 169 | +Once an Original PSBT Payload is decrypted and checked according to the list, the receiver may respond with a Payjoin PSBT. The receiver encrypts the PSBT according to the HPKE protocol, generating an ephemeral keypair <code>e</code> from which it derives a shared secret <code>ee</code> with the sender's key <code>e</code> from the payload. It generates a nonce from sufficient randomness, and constructs a ciphertext containing the Payjoin PSBT and serialized receiver ephemeral key <code>e</code>'s public key as associated data using ChaCha20Poly1305. A payload is constructed by concatenating the ephemeral public key, the nonce, and the ciphertext. This payload is then sent to the directory in an OHTTP request encapsulating the binary payload as a POST message to the subdirectory followed by <code>/receive</code>.

---

 168 | +
 169 | +Once an Original PSBT Payload is decrypted and checked according to the list, the receiver may respond with a Payjoin PSBT. The receiver encrypts the PSBT according to the HPKE protocol, generating an ephemeral keypair <code>e</code> from which it derives a shared secret <code>ee</code> with the sender's key <code>e</code> from the payload. It generates a nonce from sufficient randomness, and constructs a ciphertext containing the Payjoin PSBT and serialized receiver ephemeral key <code>e</code>'s public key as associated data using ChaCha20Poly1305. A payload is constructed by concatenating the ephemeral public key, the nonce, and the ciphertext. This payload is then sent to the directory in an OHTTP request encapsulating the binary payload as a POST message to the subdirectory followed by <code>/receive</code>.
 170 | +
 171 | +===Receiver's Payjoin PSBT checklist===
 172 | +
 173 | +Other than requiring PSBTv2 the receiver checklist is the same as the [[https://github.com/bitcoin/bips/blob/master/bip-0078.mediawiki#receivers-original-psbt-checklist| the BIP 78 receiver checklist]]

---

 172 | +
 173 | +Other than requiring PSBTv2 the receiver checklist is the same as the [[https://github.com/bitcoin/bips/blob/master/bip-0078.mediawiki#receivers-original-psbt-checklist| the BIP 78 receiver checklist]]
 174 | +
 175 | +===Sender's Payjoin PSBT checklist===
 176 | +
 177 | +The version 2 sender's checklist is largely the same as the [[https://github.com/bitcoin/bips/blob/master/bip-0078.mediawiki#senders-payjoin-proposal-checklist| the BIP 78 checklist]] with the exception that it expects ALL utxo data to be filled in. BIP 78 required sender inputs UTXO data to be excluded from the PSBT which has caused many headaches since it required the sender to add them back to the Payjoin proposal PSBT. Version 2 has no such requirement.

---

 176 | +
 177 | +The version 2 sender's checklist is largely the same as the [[https://github.com/bitcoin/bips/blob/master/bip-0078.mediawiki#senders-payjoin-proposal-checklist| the BIP 78 checklist]] with the exception that it expects ALL utxo data to be filled in. BIP 78 required sender inputs UTXO data to be excluded from the PSBT which has caused many headaches since it required the sender to add them back to the Payjoin proposal PSBT. Version 2 has no such requirement.
 178 | +
 179 | +===Directory interactions===
 180 | +
 181 | +The payjoin directory provides a rendezvous point for sender and receiver to meet. It stores Payjoin payloads to support asynchronous communication. It must only accept OHTTP requests with an OHTTP Gateway for Payjoin version 2, accepting encrypted payloads. It may optionally accept HTTP/1.1 POST requests without HTTP to enrolled subdirectories to support backwards compatible Payjoin version 1 requests.

---

 180 | +
 181 | +The payjoin directory provides a rendezvous point for sender and receiver to meet. It stores Payjoin payloads to support asynchronous communication. It must only accept OHTTP requests with an OHTTP Gateway for Payjoin version 2, accepting encrypted payloads. It may optionally accept HTTP/1.1 POST requests without HTTP to enrolled subdirectories to support backwards compatible Payjoin version 1 requests.
 182 | +
 183 | +===Subdirectories===
 184 | +
 185 | +Each receiver subdirectory allocated on the directory has a buffer for requests and one for responses. Each buffer updates listeners through awaitable events so that updates are immediately apparent upon client request.

---

 193 | +* <code>ohttp</code> represents the OHTTP Key Configuration of the directory. This is a base64URL encoded public key of the directory's OHTTP Gateway. This parameter is required for version 2 payjoin URIs.
 194 | +* <code>exp</code>: represents a request expiration after which the receiver reserves the right to broadcast the transaction extracted from the Original PSBT and ignore requests. This is only necessary for receivers who only support synchonous execution of the protocol, like automated payment processors.
 195 | +
 196 | +===Optional sender parameters===
 197 | +
 198 | +When the payjoin sender posts the original PSBT to the receiver, it can optionally specify the following HTTP query string parameters:

---

 205 | +
 206 | +===Request expiration & Original PSBT===
 207 | +
 208 | +The directory may hold a request for an offline payjoin peer until that peer comes online. However, the BIP 78 spec recommends broadcasting request PSBTs in the case of an offline counterparty. Doing so exposes a naïve, surveillance-vulnerable transaction which payjoin intends to avoid.
 209 | +
 210 | +The existing BIP 78 protocol has to be synchronous only for automated endpoints which may be vulnerable to probing attacks. It can cover this tradeoff by demanding  Original PSBT from which a valid payment transaction may be extracted that would not preserve privacy the same way as a payjoin. BIP 21 URI can communicate a request expiration to alleviate both of these problems. Receivers may specify a deadline after which they will broadcast this original with a new expiration parameter <code>exp=</code>. <!-- I also like to for timeout, but it's hard to coordinate in an asynchronous way -->

---

 209 | +
 210 | +The existing BIP 78 protocol has to be synchronous only for automated endpoints which may be vulnerable to probing attacks. It can cover this tradeoff by demanding  Original PSBT from which a valid payment transaction may be extracted that would not preserve privacy the same way as a payjoin. BIP 21 URI can communicate a request expiration to alleviate both of these problems. Receivers may specify a deadline after which they will broadcast this original with a new expiration parameter <code>exp=</code>. <!-- I also like to for timeout, but it's hard to coordinate in an asynchronous way -->
 211 | +
 212 | +===HTTP===
 213 | +
 214 | +HTTP is ubiquitous. Using simple HTTP polling allows even Bitcoin Core to consider an implementation. Unlike a WebSockets protocol, plain HTTP is eligible to enjoy metadata protection from Oblivious HTTP.

---

 213 | +
 214 | +HTTP is ubiquitous. Using simple HTTP polling allows even Bitcoin Core to consider an implementation. Unlike a WebSockets protocol, plain HTTP is eligible to enjoy metadata protection from Oblivious HTTP.
 215 | +
 216 | +===Oblivious HTTP===
 217 | +
 218 | +OHTTP protects sender and receiver IP addresses from both one another and from the directory. This makes it more difficult for a directory to correlate many payjoin transactions with a specific IP addresses by intersection.

---

 156 | +
 157 | +If a directory is operated by an exchange, it may give out authentication tokens for users of its app, or may require some proof of work out of band. Tokens should be anonymous credentials from the directory describing the parameters of their authorization. Specific credentialing is out of the scope of this proposal.
 158 | +
 159 | +====Send Messaging====
 160 | +
 161 | +The version 2 Original PSBT is serialized in base64 followed by the query parameter string on a new line. This plaintext string encrypted according to the HPKE using a shared secret derived from a newly generated session keypair public key combined with the receiver's subdirectory session public key. The resulting HPKE payload body is then encapsulated according to Oblivious HTTP as a POST request to the directory's OHTTP Gateway.

---

 163 | +The directory's OHTTP Gateway decapsulates the OHTTP request, handles the POST request at the receiver's internal subdirectory endpoint, which stores the HPKE encrypted payload to be forwarded to the receiver. The directory's awaits a request from the receiver's to the subdirectory endpoint, encapsulates to responds with the HPKE encrypted Original PSBT payload acording to OHTTP.
 164 | +
 165 | +====Receive Messaging====
 166 | +
 167 | +The receiver sends a GET request to the path of the subdirectory followed by <code>/receive</code>. This request is encapsulated in OHTTP. 
 168 | +The recver then awaits an OHTTP response from the directory encapsulating a request from the sender with status code 200 OK, or sends a new OHTTP request after receiving an encapsulated 202 ACCEPTED response notifying the receiver that the directory has not yet received a request from the sender.

---

 158 | +
 159 | +====Send Messaging====
 160 | +
 161 | +The version 2 Original PSBT is serialized in base64 followed by the query parameter string on a new line. This plaintext string encrypted according to the HPKE using a shared secret derived from a newly generated session keypair public key combined with the receiver's subdirectory session public key. The resulting HPKE payload body is then encapsulated according to Oblivious HTTP as a POST request to the directory's OHTTP Gateway.
 162 | +
 163 | +The directory's OHTTP Gateway decapsulates the OHTTP request, handles the POST request at the receiver's internal subdirectory endpoint, which stores the HPKE encrypted payload to be forwarded to the receiver. The directory's awaits a request from the receiver's to the subdirectory endpoint, encapsulates to responds with the HPKE encrypted Original PSBT payload acording to OHTTP.

---

 173 | +
 174 | +Other than requiring PSBTv2, the receiver checklist is the same as the [[https://github.com/bitcoin/bips/blob/master/bip-0078.mediawiki#receivers-original-psbt-checklist| the BIP 78 receiver checklist]]
 175 | +
 176 | +===Sender's Payjoin PSBT checklist===
 177 | +
 178 | +The version 2 sender's checklist is largely the same as the [[https://github.com/bitcoin/bips/blob/master/bip-0078.mediawiki#senders-payjoin-proposal-checklist| the BIP 78 checklist]], with the exception that it expects all UTXO data to be filled in. BIP 78 required sender inputs UTXO data to be excluded from the PSBT which has caused many issues, as it required the sender to add them back to the Payjoin proposal PSBT. Version 2 has no such requirement.

---

 196 | +
 197 | +===Optional sender parameters===
 198 | +
 199 | +When the payjoin sender posts the original PSBT to the receiver, the sender should specify the following HTTP query string parameters:
 200 | +
 201 | +* <code>v</code>: represents the version number of the payjoin protocol that the sender is using. This version is <code>2</code>.

---

 204 | +
 205 | +==Rationale==
 206 | +
 207 | +===Request expiration & Original PSBT===
 208 | +
 209 | +The directory may hold a request for an offline payjoin peer until that peer comes online. However, the BIP 78 spec recommends broadcasting request PSBTs in the case of an offline counterparty. Doing so exposes a naïve, surveillance-vulnerable transaction which payjoin intends to avoid.

---

 206 | +
 207 | +===Request expiration & Original PSBT===
 208 | +
 209 | +The directory may hold a request for an offline payjoin peer until that peer comes online. However, the BIP 78 spec recommends broadcasting request PSBTs in the case of an offline counterparty. Doing so exposes a naïve, surveillance-vulnerable transaction which payjoin intends to avoid.
 210 | +
 211 | +The existing BIP 78 protocol has to be synchronous only for automated endpoints, which may be vulnerable to probing attacks. It can cover this tradeoff by demanding an Original PSBT, from which a valid payment transaction may be extracted that would not preserve privacy the same way as a payjoin. BIP 21 URIs can communicate a request expiration to alleviate both of these problems. Receivers may specify a deadline after which they will broadcast this original with a new expiration parameter <code>exp=</code>. <!-- I also like to for timeout, but it's hard to coordinate in an asynchronous way -->

---

 231 | +
 232 | +===Secp256k1 Hybrid Public Key Encryption===
 233 | +
 234 | +Hybrid Public Key Encryption is a modern web standard for secure message exchange without TLS. Since client and server agree on a configuration out of band, we can pre-define the payjoin v2 application specific configuration to use DHKEM(Secp256k1, HKDF-SHA256) and ChaCha20Poly1305 AEAD.
 235 | +
 236 | +The cryptographic handshake is conducted in parallel to the payjoin messaging inspired by the [[http://www.noiseprotocol.org/noise.html#zero-rtt-and-noise-protocols| zero-RTT]] version of the [[http://www.noiseprotocol.org/noise.html| Noise Framework]] [[https://noiseexplorer.com/patterns/NKpsk0/| IK]] pattern. A receiver shares its public key out of band in the BIP21 URI. Static keys shared in URIs must only for a single session. The key is encoded in [[https://datatracker.ietf.org/doc/html/rfc4648#section-5| base64url]] encoding as a payjoin directory subdirectory in the <code>pj=</code> parameter.

---

 229 | +
 230 | +All cyphertexts should be padded to the same length of 7168 bytes to prevent traffic analysis. This is sufficient size for most transaction PSBTs without exceeding the 8KB limit of many HTTP/1.1 web servers.
 231 | +
 232 | +===Secp256k1 Hybrid Public Key Encryption===
 233 | +
 234 | +Hybrid Public Key Encryption is a modern web standard for secure message exchange without TLS. Since client and server agree on a configuration out of band, we can pre-define the payjoin v2 application specific configuration to use DHKEM(Secp256k1, HKDF-SHA256) and ChaCha20Poly1305 AEAD.

---

 239 | +
 240 | +[[https://www.ietf.org/archive/id/draft-wahby-cfrg-hpke-kem-secp256k1-01.html| Secp256k1-based DHKEM for HPKE]] is most appropriate because of secp256k1's availability in bitcoin contexts.
 241 | +
 242 | +====ChaCha20Poly1305 AEAD====
 243 | +
 244 | +This authenticated encryption with additional data [[https://en.wikipedia.org/wiki/ChaCha20-Poly1305| algorithm]] is standardized in [[https://www.rfc-editor.org/rfc/rfc8439| RFC 8439]] and has high performance. ChaCha20Poly1305 AEAD seems to be making its way into bitcoin by way of [[https://github.com/bitcoin/bips/blob/master/bip-0324.mediawiki| BIP 324]] as well. The protocol has widespread support in browsers, OpenSSL and libsodium. AES-GCM is more widespread but is both older, slower, and not necessarily already a dependency in bitcoin software.

---

 247 | +
 248 | +SHA-256 is considered secure and is necessarily available in bitcoin contexts.
 249 | +
 250 | +===PSBT Version 2===
 251 | +
 252 | +The PSBT version 1 protocol was replaced because it was not designed to have inputs and outputs be mutated. Payjoin mutates the PSBT, so BIP 78 uses a hack where a new PSBT is created by the receiver instead of mutating it. This can cause some strange behaviors from signers who don't know where to look to find the scripts that they are accountable for. PSBT version 2 makes mutating a PSBT's inputs and outputs trivial. It also eliminates the transaction finalization step. Receivers who do not understand PSBT version 1 may choose to reject Payjoin version 1 requests and only support PSBT version 2.

---

 251 | +
 252 | +The PSBT version 1 protocol was replaced because it was not designed to have inputs and outputs be mutated. Payjoin mutates the PSBT, so BIP 78 uses a hack where a new PSBT is created by the receiver instead of mutating it. This can cause some strange behaviors from signers who don't know where to look to find the scripts that they are accountable for. PSBT version 2 makes mutating a PSBT's inputs and outputs trivial. It also eliminates the transaction finalization step. Receivers who do not understand PSBT version 1 may choose to reject Payjoin version 1 requests and only support PSBT version 2.
 253 | +
 254 | +===Attack vectors===
 255 | +
 256 | +Since directories store arbitrary encrypted payloads they are vulnerable to the tragedy of the commons and denial of service attacks. Directory operators may impose an authentication requirement before they allocate a subdirectory to receivers to mitigate such attacks.

---

 255 | +
 256 | +Since directories store arbitrary encrypted payloads they are vulnerable to the tragedy of the commons and denial of service attacks. Directory operators may impose an authentication requirement before they allocate a subdirectory to receivers to mitigate such attacks.
 257 | +
 258 | +Since we make use of 0-RTT HPKE, the first message containing the sender's original PSBT has minimal forward secrecy. If the receiver's key is compromised, this message containing the Original PSBT could be read by the compromiser.
 259 | +
 260 | +Since the Original PSBT is valid, even where <code>exp=</code> is specified, the receiver may broadcast it and lose out on savings from payment batching and  privacy protection from payjoin structure at any time. Though unfortunate, this failure mode is the typical bitcoin transaction flow today anyhow.

---

 259 | +
 260 | +Since the Original PSBT is valid, even where <code>exp=</code> is specified, the receiver may broadcast it and lose out on savings from payment batching and  privacy protection from payjoin structure at any time. Though unfortunate, this failure mode is the typical bitcoin transaction flow today anyhow.
 261 | +
 262 | +===Network privacy===
 263 | +
 264 | +Oblivious HTTP must be used to protect the IP address of both sender and receiver from the directory. This requires an additional key configuration to be shared in the bip21 URI and for the directory to support Oblivious HTTP. A secp256k1 HPKE OHTTP configuration should be used to leverage the cryptography already available in bitcoin contexts.

---

 261 | +
 262 | +===Network privacy===
 263 | +
 264 | +Oblivious HTTP must be used to protect the IP address of both sender and receiver from the directory. This requires an additional key configuration to be shared in the bip21 URI and for the directory to support Oblivious HTTP. A secp256k1 HPKE OHTTP configuration should be used to leverage the cryptography already available in bitcoin contexts.
 265 | +
 266 | +Unlike BIP 78 implementations, sender and receiver peers will only see the IP address of the directory, not their peers. Directories may additionally be made available via Tor hidden service to allow either of the peers to protect their IP from the directory without OHTTP.

---

 265 | +
 266 | +Unlike BIP 78 implementations, sender and receiver peers will only see the IP address of the directory, not their peers. Directories may additionally be made available via Tor hidden service to allow either of the peers to protect their IP from the directory without OHTTP.
 267 | +
 268 | +==Backwards compatibility==
 269 | +
 270 | +The receivers advertise payjoin capabilities through [[https://github.com/bitcoin/bips/blob/master/bip-0021.mediawiki| BIP21's URI Scheme]].

---

 267 | +
 268 | +==Backwards compatibility==
 269 | +
 270 | +The receivers advertise payjoin capabilities through [[https://github.com/bitcoin/bips/blob/master/bip-0021.mediawiki| BIP21's URI Scheme]].
 271 | +
 272 | +Senders not supporting payjoin will just ignore the <code>pj=</code> parameter and proceed to typical address-based transaction flows. <code>req-pj=</code> may be used to compel payjoin. 

---

 269 | +
 270 | +The receivers advertise payjoin capabilities through [[https://github.com/bitcoin/bips/blob/master/bip-0021.mediawiki| BIP21's URI Scheme]].
 271 | +
 272 | +Senders not supporting payjoin will just ignore the <code>pj=</code> parameter and proceed to typical address-based transaction flows. <code>req-pj=</code> may be used to compel payjoin. 
 273 | +
 274 | +Receivers may choose to support version 1 payloads. Version 2 payjoin URIs should enable <code>pjos=0</code> so that these v1 senders disable output substitution since the v1 messages are neither encrypted nor authenticated, putting them at risk for man-in-the-middle attacks otherwise. The directory protocol should carry on as normal, responding to payjoin requests instead with this version 1 request as BHTTP in an OHTTP response. The receiver should POST version 1 Payjoin PSBTs to the same subdirectory as in version 2 to respond to these version 1 senders within 30 seconds to respond to the sender's request.

---

 273 | +
 274 | +Receivers may choose to support version 1 payloads. Version 2 payjoin URIs should enable <code>pjos=0</code> so that these v1 senders disable output substitution since the v1 messages are neither encrypted nor authenticated, putting them at risk for man-in-the-middle attacks otherwise. The directory protocol should carry on as normal, responding to payjoin requests instead with this version 1 request as BHTTP in an OHTTP response. The receiver should POST version 1 Payjoin PSBTs to the same subdirectory as in version 2 to respond to these version 1 senders within 30 seconds to respond to the sender's request.
 275 | +
 276 | +==Reference implementation==
 277 | +
 278 | +An production reference implementation client can be found at https://crates.io/crates/payjoin-cli. Source code for the clients, the payjoin directory, and development kit may be found here: https://github.com/payjoin/rust-payjoin. Source code for an Oblivous HTTP relay implementation may be found here https://github.com/payjoin/ohttp-relay. The reference implementation implements an asynchronous payment flow using HTTP using PSBTv1 with encryption and Oblivious HTTP and may be configured to the following independent production relays:

---

 281 | +
 282 | +Independent Oblivious HTTP relays are run by Obscura VPN at https://ohttp-relay.obscuravpn.io/payjoin and by BOB Spaces at https://pj.bobspacebkk.com.
 283 | +
 284 | +==Acknowledgements==
 285 | +
 286 | +Thank you to  OpenSats for funding this pursuit, to Human Rights Foundation for putting a bounty on it and funding invaluable BOB Space support, who I owe a thank you to as well. Thank you to Ethan Heilman, Nicolas Dorier, Kukks, nopara73, Kristaps Kaupe, Kixunil, /dev/fd0/, Craig Raw, Mike Schmidt, Murch, Dávid Molnár, Lucas Ontiviero, Waxwing, Christopher Allen, Symphonic, Steve Meyers, Sjors Provost, Ava Chow, jbesraa, and countless plebs for feedback that has turned this idea from concept into draft, to Mike Jarmuz for suggesting that I write a BIP, and to Satsie for writing the "All About BIPS" zine which I've referenced a number of times in the drafting process. Thanks to Armin Sabouri, Ron Stoner, and Johns Beharry for hacking on the first iOS Payjoin receiver and uncovering the problem that this solves in the first place.

---

  22 | +
  23 | +Payjoin is the simplest case of interactive bitcoin batching, allowing two participants to combine their transaction intents. It solves the sole privacy problem left open in the bitcoin paper, that transactions with multiple inputs "necessarily reveal that their inputs were owned by the same owner," by enabling two owners to provide input in a transaction.
  24 | +
  25 | +The payjoin protocols automate cooperative transaction construction to break that common-input assumption. The increased opportunity to batch payments and execute transaction cut-through increases intent throughput, since multiple intents combined take up fewer bytes than independent transactions.
  26 | +
  27 | +Payjoin V1's requirements have proven to be an obstacle to adoption. V1 coordinates payjoins over a public server endpoint secured by either TLS or Tor hidden service hosted by the receiver. Version 1 is also synchronous, requiring both sender and receiver to be online simultaneously to payjoin. Both requirements present significant barriers for all but sophisticated server operators or those wallets with complex Tor integration. Wallet developers [[https://lists.linuxfoundation.org/pipermail/bitcoin-dev/2021-January/018358.html| regard]] these as limits to payjoin adoption.

---

  50 | +
  51 | +===Basic scheme===
  52 | +
  53 | +The receiver first generates a 256-bit keypair. This key will be the basis of end-to-end authenticated encryption and identification of a particular payjoin over the directory.
  54 | +
  55 | +Rather than hosting a public server, the receiver starts a session to receive messages and allocates a subdirectory from which to relay messages. The first message must include the receiver's public key to be enrolled as a subdirectory identifier. The response message from the directory to the receiver includes the newly enrolled subdirectory payjoin endpoint with the public key as identifying subdirectory. After enrollment, the receiver awaits a payjoin request on a session identified by the subdirectory. Out of band, the receiver shares a [[https://github.com/bitcoin/bips/blob/master/bip-0021.mediawiki| BIP 21]] payjoin URI including the directory endpoint in the <code>pj=</code> query parameter and a new Oblivious HTTP <code>ohttp=</code> parameter including the payjoin directory's [[https://www.ietf.org/rfc/rfc9458.html#name-key-configuration| OHTTP Key Configuration]].

---

  73 | +|                                  |                  |                |
  74 | +|      destination (address,       |                  |                |
  75 | +|        subdirectory)             |                  |                |
  76 | ++---------------------------------------------------->|                |
  77 | +|                                  |                  |                |
  78 | +|      Request Original PSBT       |                  |                |

---

 100 | +|- - -> Polled transmission
 101 | +</pre>
 102 | +
 103 | +===Payjoin version 2 messaging===
 104 | +
 105 | +Payjoin V2 messages use [[https://github.com/bitcoin/bips/blob/master/bip-0370.mediawiki| BIP 370 PSBT V2]] format to facilitate [[#psbt-version-2|PSBT mutation]].

---

 214 | +
 215 | +HTTP is ubiquitous. Using simple HTTP polling allows even Bitcoin Core to consider an implementation. Unlike a WebSockets protocol, plain HTTP can benefit from metadata protection by using Oblivious HTTP.
 216 | +
 217 | +===Oblivious HTTP===
 218 | +
 219 | +OHTTP protects sender and receiver IP addresses from both one another and from the directory. This makes it more difficult for a directory to correlate many payjoin transactions with specific IP addresses by intersection.

---

 148 | +
 149 | +Receivers must enroll with a directory to have a subdirectory allocated to them, as follows:
 150 | +
 151 | +A receiver must first discover the directory's OHTTP gateway key configuration via an authenticated bootstrap mechanism before it can enroll to receive payjoin requests. This mechanism may vary by implementation but must follow [[https://datatracker.ietf.org/doc/html/draft-ietf-privacypass-key-consistency-01| OHTTP Consistency Requirements]] and should not reveal a receiver IP address to the directory. Some examples of suitable mechanisms include fetching over a VPN, using keys included with an application binary, https-in-http CONNECT method, https-in-WebSocket, or a Tor hidden service.
 152 | +
 153 | +Payjoin sessions begin by having a receiver send the static public key to the directory via OHTTP, receiving their subdirectory in a base64url encoded directory url as response. Enrollment may be replayed in case the receiver goes offline and should result in the same response.

---

 105 | +Payjoin V2 messages use [[https://github.com/bitcoin/bips/blob/master/bip-0370.mediawiki| BIP 370 PSBT V2]] format to facilitate [[#psbt-version-2|PSBT mutation]].
 106 | +
 107 | +The payjoin version 2 protocol takes the following steps:
 108 | +
 109 | +* The receiver sends their payjoin public key and optional authentication credential according to the [[#enroll-messaging|enroll messaging]] protocol to receive a subdirectory allocation. The receiver may go offline and replay enrollment to come back online.
 110 | +* Out of band, the receiver shares a bitcoin URI with the sender, including a <code>pj=</code> query parameter where the subdirectory is the session public key. The key is encoded in [[https://datatracker.ietf.org/doc/html/rfc4648#section-5| base64url]] encoding. To support version 1 senders, the directory acts as an unsecured payjoin server, so <code>pjos=0</code> must be specified in the URI. Version 2 senders may safely allow output substitution regardless. An <code>ohttp=</code> parameter containing the directory's base64url encoded [[https://www.ietf.org/rfc/rfc9458.html#name-key-configuration| Oblivious HTTP Key Configuration]] must also be provided.

---

  85 | +|<---------------------------------|                  |                |
  86 | +|                                  |                  |                |
  87 | +|                                  |                  |                |
  88 | +|             Payjoin PSBT         |                  |                |
  89 | ++--------------------------------->|                  |                |
  90 | +|                                  |   Payjoin PSBT   |                |

---

 169 | +
 170 | +Once an Original PSBT Payload is decrypted and checked according to the [[#receivers-payjoin-psbt-checklist|checklist]], the receiver should respond with a Payjoin PSBT or an error. The receiver encrypts the PSBT according to the HPKE protocol, generating an ephemeral keypair <code>e</code> from which it derives a shared secret <code>ee</code> with the sender's key <code>e</code> from the payload. It generates a nonce from sufficient randomness, and constructs a ciphertext containing the Payjoin PSBT and serialized receiver ephemeral key <code>e</code>'s public key as associated data using ChaCha20Poly1305. A payload is constructed by concatenating the ephemeral public key, the nonce, and the ciphertext. This payload is then sent to the directory in an OHTTP request encapsulating the binary payload as a POST message to the subdirectory followed by <code>/receive</code>.
 171 | +
 172 | +===Receiver's Payjoin PSBT checklist===
 173 | +
 174 | +Other than requiring PSBTv2, the receiver checklist is the same as the [[https://github.com/bitcoin/bips/blob/master/bip-0078.mediawiki#receivers-original-psbt-checklist| the BIP 78 receiver checklist]]

---

 177 | +
 178 | +The version 2 sender's checklist is largely the same as the [[https://github.com/bitcoin/bips/blob/master/bip-0078.mediawiki#senders-payjoin-proposal-checklist| the BIP 78 checklist]], with the exception that it expects all UTXO data to be filled in. BIP 78 required sender inputs UTXO data to be excluded from the PSBT which has caused many issues, as it required the sender to add them back to the Payjoin proposal PSBT. Version 2 has no such requirement.
 179 | +
 180 | +===Directory interactions===
 181 | +
 182 | +The payjoin directory provides a rendezvous point for sender and receiver to meet. The directory stores Payjoin payloads to support asynchronous communication. The directory must only accept OHTTP requests with an OHTTP Gateway for Payjoin version 2, accepting encrypted payloads. The directory may optionally accept HTTP/1.1 POST requests without HTTP to enrolled subdirectories to support backwards compatible Payjoin version 1 requests.

---

---

 225 | +<img src=bip-0077/oblivious-http-sequence.png></img>
 226 | +
 227 | +
 228 | +===Message Padding===
 229 | +
 230 | +All cyphertexts should be padded to the same length of 7168 bytes to prevent traffic analysis. This is sufficient size for most transaction PSBTs without exceeding the 8KB limit of many HTTP/1.1 web servers.

---

 253 | +
 254 | +===Attack vectors===
 255 | +
 256 | +Since directories store arbitrary encrypted payloads they are vulnerable to the tragedy of the commons and denial of service attacks. Directory operators may impose an authentication requirement before they allocate a subdirectory to receivers to mitigate such attacks.
 257 | +
 258 | +Since we make use of 0-RTT HPKE, the first message containing the sender's original PSBT has minimal forward secrecy. If the receiver's key is compromised, this message containing the Original PSBT could be read by the compromiser.

---

 146 | +
 147 | +====Session Initiation====
 148 | +
 149 | +Receivers must initialize a Payjoin Session on a directory to have a Session subdirectory allocated to them, as follows:
 150 | +
 151 | +A receiver must first discover the directory's OHTTP Gateway Key Configuration via an authenticated bootstrap mechanism before it can initialilze a Session to receive payjoin requests. This mechanism may vary by implementation but must follow [[https://datatracker.ietf.org/doc/html/draft-ietf-privacypass-key-consistency-01| OHTTP Consistency Requirements]] and should not reveal a receiver IP address to the directory. Some examples of suitable mechanisms include fetching over a VPN, using keys included with an application binary, https-in-http CONNECT method, https-in-WebSocket, or a Tor hidden service.

---

 253 | +
 254 | +Since directories store arbitrary encrypted payloads they are vulnerable to the tragedy of the commons and denial of service attacks. To mitigate such attacks, directory operators may impose an authentication requirement before they allocate a Payjoin Session subdirectory to receivers.
 255 | +
 256 | +Since we make use of 0-RTT HPKE, the first message containing the sender's Original PSBT has minimal forward secrecy. If the receiver's key is compromised, this message containing the Original PSBT could be read by the compromiser.
 257 | +
 258 | +Receivers may break spec by ignoring the <code>exp=</code> without financial consequence since the sender payload contains a valid transaction that may be broadcast at any time. There is no mechanism to enforce penalties if a receiver fails to construct a Payjoin PSBT and wait for a signature once a Payjoin PSBT is returned to a sender. However, such basic transactions that comply with the common-input assumption are the norm, so falling back to them is no worse than typical bitcoin transaction behavior.

---

 148 | +
 149 | +Payjoin Sessions begin by having a receiver send the static public key to the directory via OHTTP, receiving their subdirectory in a base64url encoded directory URL as response. Initiation may be replayed in case the receiver goes offline and should result in the same response, i.e. it Is idempotent.
 150 | +
 151 | +Optionally, before returning the URI, the receiver may request an authentication token by presenting a message containing only the word <code>Authenticate: <description></code>, after which the receiver is required to submit an <code>Authenticate: <token></code> including the token from the directory out of band. If authentication fails, an error is returned.
 152 | +
 153 | +If a directory is operated by an exchange, it may give out authentication tokens for users of its app, or may require some proof of work out of band. Tokens should be anonymous credentials from the directory describing the parameters of their authorization. Specific credentialing is out of the scope of this proposal.

---

 231 | +
 232 | +===Secp256k1 Hybrid Public Key Encryption===
 233 | +
 234 | +Hybrid Public Key Encryption (HPKE) is a modern web standard for secure message exchange without TLS. Since client and server agree on a configuration out of band, we can pre-define the Payjoin version 2 application specific configuration to use DHKEM(Secp256k1, HKDF-SHA256) and ChaCha20Poly1305 AEAD.
 235 | +
 236 | +The cryptographic handshake is conducted in parallel to the payjoin messaging inspired by the [[http://www.noiseprotocol.org/noise.html#zero-rtt-and-noise-protocols| zero-RTT]] version of the [[http://www.noiseprotocol.org/noise.html| Noise Framework]] [[https://noiseexplorer.com/patterns/NKpsk0/| IK]] pattern. A receiver shares its public key out of band in the BIP 21 URI. Static keys shared in URIs must only be used for a single Payjoin Session. The key is encoded in [[https://datatracker.ietf.org/doc/html/rfc4648#section-5| base64url]] encoding as a Payjoin Directory subdirectory in the <code>pj=</code> parameter.

---

 149 | +
 150 | +The Original PSBT is serialized in base64, followed by the query parameter string on a new line. This plaintext string is encrypted according to HPKE using a shared secret derived from the sender's Payjoin Session public key combined with the receiver's subdirectory Payjoin Session public key. The resulting HPKE payload body is then encapsulated according to Oblivious HTTP as a POST request to the directory's OHTTP Gateway to the receiver's payjoin session subdirectory.
 151 | +
 152 | +Upon receipt, the directory's OHTTP Gateway decapsulates the OHTTP request and handles the inner POST request at the receiver's Payjoin Session subdirectory endpoint, which stores the HPKE encrypted payload to be forwarded to the receiver.
 153 | +
 154 | +The sender then polls GET requests to the receiver's Payjoin Session subdirectory endpoint in order to await a response from the directory containing a <code>Payjoin PSBT</code>. It stops polling after expiry.

---

 155 | +
 156 | +====Receive Messaging====
 157 | +
 158 | +After sharing the Payjoin URI with the sender, the receiver sends a GET request to the path of the receiver's Payjoin Session subdirectory. This request is encapsulated in OHTTP. It continues to poll by sending a new OHTTP request after receiving an encapsulated 202 ACCEPTED response notifying the receiver that the directory has not yet received a request from the sender.
 159 | +
 160 | +Upon receiving OHTTP response from the directory encapsulating a request from the sender with status code 200 OK, the receiver decrypts the payload and checks the <code>Payjoin PSBT</code> according to the [[#receivers-payjoin-psbt-checklist|checklist]].

---

 157 | +
 158 | +After sharing the Payjoin URI with the sender, the receiver sends a GET request to the path of the receiver's Payjoin Session subdirectory. This request is encapsulated in OHTTP. It continues to poll by sending a new OHTTP request after receiving an encapsulated 202 ACCEPTED response notifying the receiver that the directory has not yet received a request from the sender.
 159 | +
 160 | +Upon receiving OHTTP response from the directory encapsulating a request from the sender with status code 200 OK, the receiver decrypts the payload and checks the <code>Payjoin PSBT</code> according to the [[#receivers-payjoin-psbt-checklist|checklist]].
 161 | +
 162 | +The receiver then updates the <code>Original PSBT</code> to include new signed inputs and outputs, invalidating sender signatures, and may adjust the fee. The result is called the <code>Payjoin PSBT</code>.

---

 159 | +
 160 | +Upon receiving OHTTP response from the directory encapsulating a request from the sender with status code 200 OK, the receiver decrypts the payload and checks the <code>Payjoin PSBT</code> according to the [[#receivers-payjoin-psbt-checklist|checklist]].
 161 | +
 162 | +The receiver then updates the <code>Original PSBT</code> to include new signed inputs and outputs, invalidating sender signatures, and may adjust the fee. The result is called the <code>Payjoin PSBT</code>.
 163 | +
 164 | +The receiver encrypts the <code>Payjoin PSBT</code> according to the HPKE protocol, generating an ephemeral keypair from which it derives a shared secret with the sender's Payjoin Session public key from the payload. It generates a nonce from sufficient randomness, and constructs a ciphertext containing the Payjoin PSBT and serialized receiver ephemeral key <code>e</code>'s public key as associated data using ChaCha20Poly1305. A payload is constructed by concatenating the ephemeral public key, the nonce, and the ciphertext. This Payjoin PSBT payload is then sent as a POST message to the directory in an OHTTP request encapsulating the binary payload to the sender's Payjoin Session subdirectory.

---

  99 | +
 100 | +The Payjoin version 2 protocol takes the following steps:
 101 | +
 102 | +* The receiver generates a Payjoin Session public key.
 103 | +* Out of band, the receiver shares a bitcoin URI with the sender, including a <code>pj=</code> query parameter where the subdirectory is the compressed Payjoin Session public key. The key is encoded in [[https://datatracker.ietf.org/doc/html/rfc4648#section-5| base64url]] encoding. To support version 1 senders, the directory acts as an unsecured Payjoin server, so <code>pjos=0</code> must be specified in the URI. Version 2 senders may safely allow output substitution regardless. An <code>ohttp=</code> fragment parameter containing the directory's base64url encoded [[https://www.ietf.org/rfc/rfc9458.html#name-key-configuration| Oblivious HTTP Key Configuration]] must also be provided. It should also include an <code>exp=</code> parameter with a Unix timestamp after which the receiver will broadcast the Original PSBT and stop polling the session.
 104 | +* The sender creates a valid version 0 PSBT satisfying the [[https://github.com/bitcoin/bips/blob/master/bip-0078.mediawiki#receivers-original-psbt-checklist| the receiver checklist]]. We call this the <code>Original PSBT</code>. This <code>Original PSBT</code>, and optional sender parameters, are wrapped in HPKE authenticated encryption, including a sender session public key as associated data, and encapsulats it all as OHTTP. This [[#send-messaging|Original PSBT Request send message]] is made to the directory's OHTTP Gateway.

---

  98 | +===Payjoin version 2 messaging===
  99 | +
 100 | +The Payjoin version 2 protocol takes the following steps:
 101 | +
 102 | +* The receiver generates a Payjoin Session public key.
 103 | +* Out of band, the receiver shares a bitcoin URI with the sender, including a <code>pj=</code> query parameter where the subdirectory is the compressed Payjoin Session public key. The key is encoded in [[https://datatracker.ietf.org/doc/html/rfc4648#section-5| base64url]] encoding. To support version 1 senders, the directory acts as an unsecured Payjoin server, so <code>pjos=0</code> must be specified in the URI. Version 2 senders may safely allow output substitution regardless. An <code>ohttp=</code> fragment parameter containing the directory's base64url encoded [[https://www.ietf.org/rfc/rfc9458.html#name-key-configuration| Oblivious HTTP Key Configuration]] must also be provided. It should also include an <code>exp=</code> parameter with a Unix timestamp after which the receiver will broadcast the Original PSBT and stop polling the session.

---

 101 | +
 102 | +* The receiver generates a Payjoin Session public key.
 103 | +* Out of band, the receiver shares a bitcoin URI with the sender, including a <code>pj=</code> query parameter where the subdirectory is the compressed Payjoin Session public key. The key is encoded in [[https://datatracker.ietf.org/doc/html/rfc4648#section-5| base64url]] encoding. To support version 1 senders, the directory acts as an unsecured Payjoin server, so <code>pjos=0</code> must be specified in the URI. Version 2 senders may safely allow output substitution regardless. An <code>ohttp=</code> fragment parameter containing the directory's base64url encoded [[https://www.ietf.org/rfc/rfc9458.html#name-key-configuration| Oblivious HTTP Key Configuration]] must also be provided. It should also include an <code>exp=</code> parameter with a Unix timestamp after which the receiver will broadcast the Original PSBT and stop polling the session.
 104 | +* The sender creates a valid version 0 PSBT satisfying the [[https://github.com/bitcoin/bips/blob/master/bip-0078.mediawiki#receivers-original-psbt-checklist| the receiver checklist]]. We call this the <code>Original PSBT</code>. This <code>Original PSBT</code>, and optional sender parameters, are wrapped in HPKE authenticated encryption, including a sender session public key as associated data, and encapsulats it all as OHTTP. This [[#send-messaging|Original PSBT Request send message]] is made to the directory's OHTTP Gateway.
 105 | +* The sender polls GET requests to the subdirectory defined by the sender's Payjoin Session public key in order to await a response from the directory containing a <code>Payjoin PSBT</code>. It stops polling after expiry.
 106 | +* The request is stored in the subdirectory.

---

 102 | +* The receiver generates a Payjoin Session public key.
 103 | +* Out of band, the receiver shares a bitcoin URI with the sender, including a <code>pj=</code> query parameter where the subdirectory is the compressed Payjoin Session public key. The key is encoded in [[https://datatracker.ietf.org/doc/html/rfc4648#section-5| base64url]] encoding. To support version 1 senders, the directory acts as an unsecured Payjoin server, so <code>pjos=0</code> must be specified in the URI. Version 2 senders may safely allow output substitution regardless. An <code>ohttp=</code> fragment parameter containing the directory's base64url encoded [[https://www.ietf.org/rfc/rfc9458.html#name-key-configuration| Oblivious HTTP Key Configuration]] must also be provided. It should also include an <code>exp=</code> parameter with a Unix timestamp after which the receiver will broadcast the Original PSBT and stop polling the session.
 104 | +* The sender creates a valid version 0 PSBT satisfying the [[https://github.com/bitcoin/bips/blob/master/bip-0078.mediawiki#receivers-original-psbt-checklist| the receiver checklist]]. We call this the <code>Original PSBT</code>. This <code>Original PSBT</code>, and optional sender parameters, are wrapped in HPKE authenticated encryption, including a sender session public key as associated data, and encapsulats it all as OHTTP. This [[#send-messaging|Original PSBT Request send message]] is made to the directory's OHTTP Gateway.
 105 | +* The sender polls GET requests to the subdirectory defined by the sender's Payjoin Session public key in order to await a response from the directory containing a <code>Payjoin PSBT</code>. It stops polling after expiry.
 106 | +* The request is stored in the subdirectory.
 107 | +* Once the receiver is online, it sends [[#receive-messaging|<code>GET</code>]] requests to the subdirectory. The receiver decrypts and authenticates the response, which it checks according to [[https://github.com/bitcoin/bips/blob/master/bip-0078.mediawiki#receivers-original-psbt-checklist| the receiver checklist]]. The receiver updates the Original PSBT to include new signed inputs and outputs, invalidating sender signatures, and may adjust the fee. The result is called the <code>Payjoin PSBT</code>.

---

 104 | +* The sender creates a valid version 0 PSBT satisfying the [[https://github.com/bitcoin/bips/blob/master/bip-0078.mediawiki#receivers-original-psbt-checklist| the receiver checklist]]. We call this the <code>Original PSBT</code>. This <code>Original PSBT</code>, and optional sender parameters, are wrapped in HPKE authenticated encryption, including a sender session public key as associated data, and encapsulats it all as OHTTP. This [[#send-messaging|Original PSBT Request send message]] is made to the directory's OHTTP Gateway.
 105 | +* The sender polls GET requests to the subdirectory defined by the sender's Payjoin Session public key in order to await a response from the directory containing a <code>Payjoin PSBT</code>. It stops polling after expiry.
 106 | +* The request is stored in the subdirectory.
 107 | +* Once the receiver is online, it sends [[#receive-messaging|<code>GET</code>]] requests to the subdirectory. The receiver decrypts and authenticates the response, which it checks according to [[https://github.com/bitcoin/bips/blob/master/bip-0078.mediawiki#receivers-original-psbt-checklist| the receiver checklist]]. The receiver updates the Original PSBT to include new signed inputs and outputs, invalidating sender signatures, and may adjust the fee. The result is called the <code>Payjoin PSBT</code>.
 108 | +* The <code>Payjoin PSBT</code> and HPKE keys are encrypted, authenticated, encapsulated in OHTTP, and POSTed to the directory's OHTTP Gateway.
 109 | +* The directory awaits a request from the sender if it goes offline. Upon request, the directory relays the encrypted <code>Payjoin PSBT</code>.

---

 163 | +
 164 | +The receiver encrypts the <code>Proposal PSBT</code> according to the HPKE protocol, generating an ephemeral keypair from which it derives a shared secret with the sender's Payjoin Session public key from the payload. It generates a nonce from sufficient randomness, and constructs a ciphertext containing the Proposal PSBT and serialized receiver ephemeral key <code>e</code>'s public key as associated data using ChaCha20Poly1305. A payload is constructed by concatenating the ephemeral public key, the nonce, and the ciphertext. This Proposal PSBT payload is then sent as a POST message to the directory in an OHTTP request encapsulating the binary payload to the sender's Payjoin Session subdirectory.
 165 | +
 166 | +===Receiver's Proposal PSBT checklist===
 167 | +
 168 | +The receiver checklist is the same as the [[https://github.com/bitcoin/bips/blob/master/bip-0078.mediawiki#receivers-original-psbt-checklist| the BIP 78 receiver checklist]], except for the "Verify that the payjoin proposal did not introduce mixed input's type" step, which may be ignored.

---

  30 | +
  31 | +===Relation to BIP 78 (Payjoin version 1)===
  32 | +
  33 | +The message payloads in this version parallel those used in BIP 78, while being encapsulated in authenticated encryption. TLS and Tor security, which depend on third-party authorities, are replaced with Hybrid Public Key Encryption ([[https://www.rfc-editor.org/rfc/rfc9180| HPKE]]). The synchronous HTTP client-server model is replaced with an asynchronous store-and-forward mechanism.
  34 | +
  35 | +The BIP 78 standard allows for an [[https://github.com/bitcoin/bips/blob/master/bip-0078.mediawiki#unsecured-payjoin-server| unsecured Payjoin server|]] to operate separately from the so-called "payment server" responsible for generating [[https://github.com/bitcoin/bips/blob/master/bip-0021.mediawiki| BIP 21]] request URIs. Because BIP 78 messages relayed over an unsecured server are neither end-to-end authenticated nor encrypted between sender and receiver, a malicious unsecured Payjoin server is able to modify the Proposal PSBT in flight, thus requiring payment output substitution to be disabled. Output substitution is useful for a number of block space optimizations, including payment batching and transaction cut-through. This proposal introduces authentication and encryption to secure output substitution by using a directory server without compromising sender or receiver privacy.

---

   5 | +  Author: Dan Gould <d@ngould.dev>
   6 | +  Comments-URI: https://github.com/bitcoin/bips/wiki/Comments:BIP-0077
   7 | +  Status: Draft
   8 | +  Type: Standards Track
   9 | +  Created: 2023-08-08
  10 | +  License: BSD-2-Clause

---

 114 | +* Include complete UTXO data.
 115 | +* Be signed.
 116 | +* Exclude unnecessary fields such as global xpubs or keypath information.
 117 | +* Be broadcastable.
 118 | +
 119 | +The Original PSBT MAY:

---

 122 | +
 123 | +The Proposal PSBT MUST:
 124 | +
 125 | +* Include all inputs from the Original PSBT.
 126 | +* Include all outputs which do not belong to the receiver from the Original PSBT.
 127 | +* Include complete UTXO data.

---

 130 | +
 131 | +* Add, remove or modify Original PSBT outputs under the control of the receiver (i.e. not sender change).
 132 | +
 133 | +The Proposal PSBT MUST NOT:
 134 | +
 135 | +* Shuffle the order of inputs or outputs; the additional outputs or additional inputs must be inserted at a random index.

---

 167 | +
 168 | +The receiver checklist is the same as the [[https://github.com/bitcoin/bips/blob/master/bip-0078.mediawiki#receivers-original-psbt-checklist| the BIP 78 receiver checklist]], except for the "Verify that the payjoin proposal did not introduce mixed input's type" step, which may be ignored.
 169 | +
 170 | +===Sender's Proposal PSBT checklist===
 171 | +
 172 | +The version 2 sender's checklist is largely the same as the [[https://github.com/bitcoin/bips/blob/master/bip-0078.mediawiki#senders-payjoin-proposal-checklist| the BIP 78 checklist]], with the exception that mixed input script types are allowed, and it expects all UTXO data to be filled in. BIP 78 required sender inputs UTXO data to be excluded from the PSBT, which has caused many issues, as it required the sender to add them back to the Payjoin proposal PSBT. Version 2 has no such requirement.

---

  22 | +
  23 | +Payjoin is the simplest case of interactive bitcoin batching, allowing two participants to combine their transaction intents. It solves the sole privacy problem left open in the bitcoin paper, that transactions with multiple inputs "necessarily reveal that their inputs were owned by the same owner," by enabling two owners to provide input in a transaction.
  24 | +
  25 | +The Payjoin protocols automate cooperative transaction construction to break that common-input assumption. The increased opportunity to batch payments and execute transaction cut-through increases intent throughput, since multiple intents combined take up fewer bytes than independent transactions.
  26 | +
  27 | +Payjoin version 1's requirements have proven to be an obstacle to adoption. Version 1 coordinates payjoins over a public server endpoint secured by either TLS or Tor hidden service hosted by the receiver. Version 1 is also synchronous, requiring both sender and receiver to be online simultaneously to payjoin. Both requirements present significant barriers for all but sophisticated server operators or those wallets with complex Tor integration. Wallet developers [[https://lists.linuxfoundation.org/pipermail/bitcoin-dev/2021-January/018358.html| regard]] these as limits to Payjoin adoption.

---

 171 | +
 172 | +The version 2 sender's checklist is largely the same as the [[https://github.com/bitcoin/bips/blob/master/bip-0078.mediawiki#senders-payjoin-proposal-checklist| the BIP 78 checklist]], with the exception that mixed input script types are allowed, and it expects all UTXO data to be filled in. BIP 78 required sender inputs UTXO data to be excluded from the PSBT, which has caused many issues, as it required the sender to add them back to the Payjoin proposal PSBT. Version 2 has no such requirement.
 173 | +
 174 | +===Directory interactions===
 175 | +
 176 | +The Payjoin Directory provides a rendezvous point for sender and receiver to meet. The directory stores Payjoin payloads to support asynchronous communication. The directory must only accept OHTTP requests with an OHTTP Gateway for Payjoin version 2, accepting encrypted payloads. The directory may optionally accept HTTP/1.1 POST requests without OHTTP to Payjoin Session subdirectories to support backwards compatible Payjoin version 1 requests.

---

 179 | +
 180 | +Each Payjoin Session subdirectory allocated on the directory has one buffer for a PSBT payload. The buffer updates listeners through awaitable events so that updates are immediately apparent upon client request.
 181 | +
 182 | +===Receiver fragment parameters===
 183 | +
 184 | +A major benefit of BIP 78 Payjoin over other coordination mechanisms is its compatibility with the universal BIP 21 bitcoin URI standard.

---

 183 | +
 184 | +A major benefit of BIP 78 Payjoin over other coordination mechanisms is its compatibility with the universal BIP 21 bitcoin URI standard.
 185 | +
 186 | +Instead of defining new [[https://github.com/bitcoin/bips/blob/master/bip-0021.mediawiki| BIP 21 URI]] parameters, Payjoin version 2 encodes parameters in the [[https://datatracker.ietf.org/doc/html/rfc3986#section-3.5| fragment]] of the URL following the <code>pj=</code> parameter in the BIP 21 URI. They follow the <code>#</code> character and follow the semantics of the [[https://github.com/bitcoin/bips/blob/master/bip-0021.mediawiki#abnf-grammar| BIP 21 "otherparam" grammar]], being separated by an <code>&</code> character.
 187 | +
 188 | +* <code>ohttp</code>: represents the OHTTP Key Configuration of the directory. This is a base64url encoded compressed public key of the directory's OHTTP Gateway, prefixed by the one byte Key Identifier, from which the [[https://www.ietf.org/rfc/rfc9458.html#section-3.1| RFC 9458 Key Configuration can be constructed]]. This parameter is required for version 2 Payjoin URIs.

---

 214 | +
 215 | +HTTP is ubiquitous. Using simple HTTP polling allows even Bitcoin Core to consider an implementation. Unlike a WebSockets protocol, plain HTTP can benefit from metadata protection by using Oblivious HTTP.
 216 | +
 217 | +===Oblivious HTTP===
 218 | +
 219 | +OHTTP protects sender and receiver IP addresses both from one another and from the directory. This makes it more difficult for a directory to correlate many payjoin transactions with specific IP addresses by intersection.

---

 220 | +
 221 | +OHTTP relays can be run as basic HTTP proxies from wallet providers or third parties.
 222 | +
 223 | +====OHTTP Sequence Diagram====
 224 | +
 225 | +<img src=bip-0077/oblivious-http-sequence.png></img>

---

 267 | +
 268 | +The receivers advertise Payjoin capabilities through [[https://github.com/bitcoin/bips/blob/master/bip-0021.mediawiki| BIP 21's URI Scheme]].
 269 | +
 270 | +Senders not supporting Payjoin will just ignore the <code>pj=</code> parameter and proceed to typical address-based transaction flows. A <code>req-pj=</code> parameter, as specified in BIP 21, may be advertised to compel Payjoin. If a sender intending to pay such a URI containing <code>req-pj=</code> does not support Payjoin, it MUST consider the entire URI invalid per BIP 21.
 271 | +
 272 | +Receivers may choose to support version 1 payloads. Version 2 Payjoin URIs for backwards compatible receivers MUST enable <code>pjos=0</code> so that these version 1 senders disable output substitution. Since the version 1 messages are neither encrypted nor authenticated, they would otherwise be at risk for man-in-the-middle attacks. The directory protocol should carry on as normal, responding to payjoin requests instead with this version 1 request as BHTTP in an OHTTP response. The receiver should POST version 1 Proposal PSBTs to the same subdirectory as in version 2 to respond to these version 1 senders within 30 seconds. If no response is received within 30 seconds, the directory should respond with an <code>unavailable</code> error code as [[https://github.com/bitcoin/bips/blob/master/bip-0078.mediawiki#receivers-well-known-errors| defined in BIP 78]].

---

 271 | +
 272 | +Receivers may choose to support version 1 payloads. Version 2 Payjoin URIs for backwards compatible receivers MUST enable <code>pjos=0</code> so that these version 1 senders disable output substitution. Since the version 1 messages are neither encrypted nor authenticated, they would otherwise be at risk for man-in-the-middle attacks. The directory protocol should carry on as normal, responding to payjoin requests instead with this version 1 request as BHTTP in an OHTTP response. The receiver should POST version 1 Proposal PSBTs to the same subdirectory as in version 2 to respond to these version 1 senders within 30 seconds. If no response is received within 30 seconds, the directory should respond with an <code>unavailable</code> error code as [[https://github.com/bitcoin/bips/blob/master/bip-0078.mediawiki#receivers-well-known-errors| defined in BIP 78]].
 273 | +
 274 | +==Reference implementation==
 275 | +
 276 | +An production reference implementation client can be found at [[https://crates.io/crates/payjoin-cli]]. Source code for the clients, the Payjoin Directory, and development kit may be found here: [[https://github.com/payjoin/rust-payjoin]]. Source code for an Oblivous HTTP relay implementation may be found here [[https://github.com/payjoin/ohttp-relay]]. The reference implementation may be configured to the following independent production relays as of 24/09/26:

---

  10 | +  License: BSD-2-Clause
  11 | +</pre>
  12 | +
  13 | +==Abstract==
  14 | +
  15 | +This document proposes a backwards-compatible second version of the Payjoin protocol described in [[bip-0078.mediawiki|BIP 78]], allowing complete Payjoin receiver functionality, including payment output substitution, without requiring one to host a secure public endpoint. This requirement is replaced with an untrusted third-party directory accessed via HTTP clients that communicate using an asynchronous protocol and authenticated, encrypted payloads. Authenticated encryption depends only on cryptographic primitives available in Bitcoin Core. Requests use [[https://www.ietf.org/rfc/rfc9458.html| Oblivious HTTP]] to prevent the directory and Payjoin peers from linking requests to client IP addresses.

---

   0 | @@ -0,0 +1,280 @@
   1 | +<pre>
   2 | +  BIP: 77
   3 | +  Layer: Applications
   4 | +  Title: Payjoin Version 2 — Async Payjoin

---

  62 | +a number of block space optimizations, including payment batching and transaction cut-through. This proposal
  63 | +introduces authentication and encryption to secure output substitution by using a directory server without
  64 | +compromising sender or receiver privacy.
  65 | +
  66 | +Although unsecured Payjoin server separation is mentioned in BIP 78, no known specification or implementation
  67 | +exists. This document specifies a way to use the Payjoin directory as an unsecured backwards compatible server

---