Skip to content

Instantly share code, notes, and snippets.

Last active November 1, 2023 20:07
Show Gist options
  • Save DanGould/243e418752fff760c9f6b23bba8a32f9 to your computer and use it in GitHub Desktop.
Save DanGould/243e418752fff760c9f6b23bba8a32f9 to your computer and use it in GitHub Desktop.
Serverless Payjoin - Receive surveillance-busting bitcoin transfers without hosting a secure endpoint

  BIP: ???
  Layer: Applications
  Title: Payjoin Version 2: Serverless Payjoin
  Author: Dan Gould <>
  Status: Draft
  Replaces: 78
  Type: Standards Track
  Created: 2023-08-08
  License: BSD-2-Clause

Table of Contents


This document proposes a backwards-compatible second version of the payjoin protocol described in BIP 78, allowing complete payjoin receiver functionality including payment output substitution without requiring them to host a secure public endpoint. This requirement is replaced with an untrusted third-party relay and streaming clients which communicate using an asynchronous protocol and authenticated, encrypted payloads.


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


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.

Version 1 coordinates payjoins over a public server endpoint secured by either TLS or Tor onion hidden service hosted by the receiver. Version 1 is synchronous, so both sender and reciever must be online simultaneously to payjoin. Both requirements present significant barriers for all but sophisticated server operators or those wallets with complex Tor integration. These barriers are regarded as limits to payjoin adoption.

The primary goal of this proposal is to provide a practical coordination mechanism to be adopted in a vast majority of wallet environments. This is realized as a simple protocol built on bitcoin URI requests, web standards, common crypto, and minimal dependencies.

Relation to BIP 78 (Payjoin version 1)

The message payloads in this version parrallel those used in BIP 78 while being encapsulated in authenticated encryption, forgoing HTTP messaging for WebTransport streaming of asynchronus interactions, and leveraging PSBT version 2.

The BIP 78 standard allows for an unsecured payjoin server to operate separately from the so-called "payment server" responsible for generating 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 relay without compromising sender or receiver privacy.

Although unsecured payjoin server separation is mentioned in BIP 78, no known specification or implementation of one exists. This document specifies one to be backwards compatible with 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 relay stealing funds.

The protocols in this document reuse BIP 78's BIP 21 URI parameters. A Fallback PSBT timeout parameter is introduced which may also help coordinate the synchronous version 1 protocol.

Relation to Stowaway

Stowaway is a payjoin coordination mechanism which depends on Tor, a third-party relay, and the PayNym 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 the wallet. Payjoin version 2 also supports asynchronous messaging, in contrast to online Stowaway's synchronous HTTP-based 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.



Payjoin requests are made using familiar BIP 21 URIs. Instead of a public HTTP endpoint, this scheme allows a WebTransport client to enroll with a relay server to receive payjoin. Relays may optionally require an authorization credential before allocating resources in order to prevent DoS attacks. Sender and receiver payloads are buffered at the relay to support asynchronous interaction. Authenticated encryption prevents the relay from snooping on message contents or forging messages. Aside from a application layer authenticate encryption and relayed asynchronus networking, the version 2 messaging takes much the same form as the existing BIP 78 specification.

Basic scheme

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 relay.

Rather than hosting a public server, they start a streaming 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 streamed from the relay 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 BIP 21 payjoin uri including the relay endpoint in the pj= query parameter.

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 streamed to the recipient by the relay-hosted subdirectory pj= endpoint.

Messages are secured by symmetric cipher rather than TLS or Onion routing session key. Sender and receiver may experience network interruption and proceed with the protocol since their request and response are buffered at the Payjoin relay subdirectory.

Payjoin version 2 messaging

Payjoin v2 messages use BIP 370 PSBT v2 format to fascilitate PSBT mutation.

The payjoin version 2 protocol takes the following steps:

- The recipient sends their payjoin pubkey and optional authentication credential according to receiver relay enrollment protocol. It may go offline and replay enrollment to come back online. - Out of band, the receiver of the payment, shares a bitcoin URI with the sender including a pj= query parameter describing the relay subdirectory endpoint parameter with UR encoded pubkey. To support version 1 senders the relay acts as an unsecured payjoin server so pjos=0 must be specified in the URI. Version 2 senders may safely allow output substitution regardless. - The sender creates a valid PSBT according to the receiver checklist formatted as PSBTv2. We call this the Fallback PSBT. This Fallback PSBT, optional sender parameters, and cryptographic keys are encrypted and authenticated according to the Secp256k1 IK handshake and streamed to the relay subdirectory endpoint. - The sender awaits a response from the relay stream containing an encrypted Payjoin PSBT as Message B. It can replay the Fallback PSBT Mesasge A to request a response if it goes offline. - The request is stored in the receiver's subdirectory buffer. - Once the receiver is online, it awaits a stream of request updates from the relay. The receiver decrypts aund authenticates the payload then checks it according to the receiver checklist. It updates it to include new signed inputs and outputs invalidating sender signatures, and may adjust the fee. We call this the Payjoin PSBT. - It responds with the Payjoin PSBT encrypted then authenticated as Message B according to the Secp256k1 IK handshake. - The relay awaits a connection from the sender if it goes offline. Upon connection, it relays the encrypted Payjoin PSBT to the sender. - The sender validates the Payjoin PSBT according to the sender checklist, signs its inputs and broadcasts the transaction to the Bitcoin network.

The encrypted Fallback PSBT and Payjoin PSBT payloads are sent as bytes.

The Fallback PSBT MUST:

- Include complete UTXO data. - Be signed. - Exclude unnecessary fields such as global xpubs or keypath information. - Set input and output Transaction Modifiable Flags to 1 - Be broadcastable.

The Fallback PSBT MAY:

- Include outputs unrelated to the sender-receiver transfer for batching purposes. - Set SIGHASH_SINGLE Transaction Modifiable Flags flags to 1

The Payjoin PSBT MUST:

- Include all inputs from the Fallback PSBT. - Include all outputs which do not belong to the receiver from the Fallback PSBT. - Include complete UTXO data.

The Payjoin PSBT sender MAY:

- Add, remove or modify Fallback PSBT outputs under the control of the receiver (i.e. not sender change).

The Payjoin PSBT MUST NOT:

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

Receiver's Payjoin PSBT checklist

Other than requiring PSBTv2 the receiver checklist is the same as the the BIP 78 receiver checklist

Sender's Payjoin PSBT checklist

The version 2 sender's checklist is largely the same as the 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.

Relay interactions

The Payjoin Relay provides a rendezvous point for sender and receiver to meet. It stores Payjoin payloads to support asynchronous communication. It is available on the open internet over HTTPS to accept both WebTransport for Payjoin version 2, accepting encrypted payloads, and optionally HTTP/1.1 to support backwards compatible Payjoin version 1 requests.

Receiver interactions

Relay enrollment

Receivers must enroll to have resources allocated on a relay. Sessions may begin by having a receiver send the static pubkey to the relay. The receiver returns the subdirectory endpoint url with the final subdirectory as UR encoded pubkey. Enrollment may be replayed in case the receiver goes offline.

Optionally, before returning the uri the receiver may request an authentication token by presenting a message containing only the word Authenticate: <description> after which the receiver is required to submit an Authenticate: <token> including the token from the Relay out of band. If authentication fails an error is returned.

In the case a relay 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 relay describing the parameters of their authorization. Specific credentialing is out of the scope of this proposal.

Receiver Payjoin PSBT response

The receiver streams the base64 Payjoin PSBT as encrypted bytes according to Secp256k1 IK.

Sender interactions

The sender starts a WebTransport session with the relay at the Payjoin endpoint URI provided by the receiver. It sends the following payload and awaits a relayed response payload from the receiver.

Version 2 Fallback PSBT request

The version 2 Fallback PSBT Payload is constructed in JSON before being encrypted as follows.

  "psbt": "<fallback_psbt_data_base64>",
  "params": {
      "param1": "<value1>",
      "param2": "<value1>",

The payload must be encrypted according to Secp256k1 IK.

Version 1 Fallback PSBT request

The message should be the same as version 2 but unencrypted, as version 1 is unaware of encryption when using an unsecured payjoin server. The Relay should convert the PSBT to PSBTv2 and construct the JSON payload from the HTTP request body and optional query parameters. Upon receiving an unencrypted PSBTv2 response from a receiver, it should convert it to PSBTv0 for compatibility with BIP 78.

Asynchronous relay buffers

Each receiver subdirectory on the relay server has a buffer for requests and one for responses. Each buffer updates listeners through awaitable events so that updates are immediately apparent to relevant client sessions.

BIP 21 receiver parameters

A major benefit of BIP 78 payjoin over other coordination mechanisms is its compatibility with the universal BIP 21 bitcoin URI standard.

This proposal defines the following new BIP 21 URI parameters:

- exp: represents a request expiration after which the receiver reserves the right to broadcast the Fallback and ignore requests. This is only necessary for receivers who only support synchonous execution of the protocol, like automated payment processors.

BIP 78's BIP 21 payjoin parameters are also valid for version 2.

Optional sender parameters

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

- v: represents the version number of the payjoin protocol that the sender is using. This version is 2.

BIP 78's optional query parameters are also valid as version 2 parameters.


Request expiration & fallback

The relay 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.

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 a fallback transaction 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 fallback with a new expiration parameter exp=.


Many transport protocols are good candidates for Serverless Payjoin functionality, but WebTransport stands out in its ability to stream and take advantage of QUIC's performance in mobile environments. In developing this BIP, serverless payjoin proofs of concept using TURN, HTTP/1.1 long polling, WebSockets, Magic Wormhole, and Nostr have been made. Streaming allows the relay to have more granular and asynchronous understanding of the state of the peers, and this protcol is designed specifically to address the shortcomings of an HTTP protocol's requirement to receive from a reliable, always-online connection.

While WebTransport and HTTP/3 it is built on are relatively new, widespread support across browsers assures me that it is being accepted as a standard and even has a fallback to HTTP/2 environments. Being built on top of QUIC allows it to multiplex connections from a relay to multiple peers which may prove advantageous for later payjoin protocols between more than two participants contributing inputs, such as those used to fund a lightning node with channels from multiple sources in one transaction, or those with threat models more similar to ZeroLink CoinJoin.

While Nostr is fascinating from the perspective of censorship resistance, the backwards compatibility with Payjoin v1 would mean only custom Nostr Payjoin relays exposing an https endpoint would be suitable. Nostr transport is also limited by the performance of WebSockets, being an abstraction on top of that protocol. There is nothing stopping a new version of this protocol or a NIP making Payjoin version 2 possible over Nostr should Payjoin censorship become a bottleneck in the way of adoption.

WebTransport is already shipped in both Firefox, Chrome, h3 in Rust, Go, and all popular languages. There is also a working draft for full P2P WebTransport without any relay, which a future payjoin protocol may make use of.

Secp256k1 IK inspired handshake

<-- The cryptographic handshake is conducted in parallel to the payjoin messaging inspired by the zero-RTT version of the Noise Framework IK pattern. A receiver shares its public key out of band in the BIP21 URI. Static noise keys are only to be used once per session

Noise IK pattern

  <- s
  -> e, es, s, ss
  <- e, ee, se

BIP 21 pre-shared public key

The recipient shares the first handshake message containing the receiver's static public key, i.e. s in Noise framework parlance.

Fallback PSBT Message A

Sender derives an ephemeral secp256k1 key pair for this session. Sender derives a shared secret using Elliptic Cureve Diffie-Hellman (ECDH) key agreement. The sender derives a symmetric key

Message A includes a sender ephemeral key, DH shared secret derived from the sender's ephemeral key and the receiver's static key, the sender's static key s, and a shared ss DH secret derived from both sender and receiver's static keys.

Message A, sent by the sender, benefits from receiver authentication and is resistant to Key Compromise Impersonation. Message contents benefit from message secrecy and some forward secrecy since ephemeral keys are used. The compromise of the receivers's (but not the sender's) static private keys,even at a later date, will lead to message contents being decrypted by an attacker.

Payjoin PSBT Message B

Message B is encreypted and authenticated using the shared secrets based off of per-session ephemeral keys.

The receiver's shared secrets

The sender can be confident that message B has sender authentication and is Key Compromise Impersonation resistant. If the sender receives a valid message from the receiver, then the receiver must have sent that message, unless the keys have been compromised before this session. If the responder's long-term static keys were previously compromised, the later compromise of the initiator's long-term static keys can lead to message contents being decrypted by an active attacker, should that attacker also have forged the initiator's ephemeral key during the session


Secp256k1 should be used in place of Noise's specified Curve25519 DH functions because of it's availability in bitcoin contexts.

ChaCha20Poly1305 AEAD

This authenticated encryption with additional data algorithm is standardized in RFC 8439 and has high performance. ChaCha20Poly1305 AEAD seems to be making its way into bitcoin by way of 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.

PSBT Version 2

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.

Attack vectors

Since relays store arbitrary encrypted payloads to the tragedy of the commons and denial of service attacks. Relay operators may impose an authentication requirement before they provide relay service to receivers to mitigate such attacks.

Since psk is a symmetric key, the first message containing the sender's original PSBT does not have forward secrecy. Since relay buffers are associated with a single ephemeral relay directory, to support request-response simplicity of version 1, this seems appropriate.

Since the Fallback PSBT is valid, even where exp= is specified, the receiver may broadcast it and lose out on ambiguous privacy protection from payjoin at any time. Though unfortunate, this is the typical bitcoin transaction flow today anyhow.

Network privacy

Unlike BIP 78 implementations, sender and receiver peers will only see the IP address of the relay, not their peer's. Relays may be made available via Tor hidden service or Oblivious HTTP in addition to IP / DNS to allow either of the peers to protect their IP from the relay with without requiring both peers to use additional network security dependencies.

Backwards compatibility

The receivers advertise payjoin capabilities through BIP21's URI Scheme.

Senders not supporting payjoin will just ignore the pj= parameter and proceed to typical address-based transaction flows. req-pj= may be used to compel payjoin.

Receivers may choose to support version 1 payloads. Version 2 payjoin URIs should enable pjos=0 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 relay protocol should carry on as normal, validating based on HTTP headers and constructing an unencrypted Version 2 payload from optional query parameters, and PSBT in the body.

The BIP 78 error messages are already JSON formatted, so it made sense to rely on the same dependency for these payloads and error messages.

Reference implementation

An early proof of concept draft reference implementation can be found at payjoin/rust-payjoin#78. It implements an asynchronous payment flow using WebSockets using PSBTv1 without encryption. Another reference can be found at payjoin/rust-payjoin#21 which uses HTTP long polling for transport and Noise NNpsk0 for crypto. Recently, I've come to realize the rationale for WebTransport, PSBTv2, and Noise IK substitutions and am working on an implementation including this exact specification, but wanted to get early feedback on this design in the spirit of BIP 2.


Thank you to OpenSats for funding this pursuit, to Human Rights Foundation for putting a bounty on it and funding invaluable BOB Space 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, and countless twitter 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.

Copy link

Thanks for doing this. I do also believe that P2P communication (P2EP) is the bottleneck for PayJoin adoption (and for many more things that does not only concerns privacy, but also UX: for example wallets can decide without bothering the user if they want to send LN or on chain payments.)

You also mentioned in the mailing list: "I think this work raises a greater problem which is that payjoin assumes synchronous communication while it’s an asynchronous world."

I think the solution here is patience. In time the world will be synchronous and everyone will be always online.

Also check out some recent work by @Kukks on this topic:

Copy link

DanGould commented Jan 27, 2023

@nopara73 love to see your comment here!

As far as UX goes, the bitcoin design community has picked up a Payjoin Design Challenge and has put together a comprehensive writeup for the sender UX as well as a design flow in figma. Receiver side coming 🔜

I realize now that payjoin only assumes synchronous communications some of the time, which is in what the spec calls "non-interactive" environments where a human isn't present to intervene. The problem isn't that everyone isn't always online, but that they're not necessarily synchronized. I suppose the original spec could be amended to make those situations explicit. One solution could be as easy as adding an rto=? timeout parameter after which the sender knows the receiver will broadcast the original psbt.

@Kukks, assuming the timeout issue is solved, because nostr doesn't do synchronous comms like http, I think the same crypto used here suggested could work for a nostr server too. The only other hurdle would be an http replacement to pass query parameters and errors because http is gone.

@NicolasDorier has offered very helpful push back to simplify this proposal. One way to remove the psk would be to only do ECDH and authenticate that the response indeed comes from the receiver (a prerequisite for output substitution) by signing the payload with the key associated with the bip21 address. The sender could verify the signature with the addresses public key included with the response payload. That would make for a smaller bip21 and no new query param, but would require an additional round of communication to do ECDH, like TLS does.

It also came to my attention that existing distributed hash tables like holepunch hyperswarm or libp2p could be used as a third alternative style of relay even to Nostr. I'm not sure if they establish synchronous communication channels or not yet.

Copy link

DanGould commented Feb 21, 2023

Just updated the doc to use HTTP relay proxy instead of TURN.

I thought for a long time about the practicalities of deploying TURN clients and Noise. After toying with WebRTC, a custom WebSockets protocol, and magic-wormhole, I remembered that @NicolasDorier had suggested long polling when he first imagined how complex TURN would be. HTTP is ubiquitous, so I think Nicolas is right. It's a clear winner in terms of distribution.

http relay proxy diagram from

This experience is making me reconsider using noise. Maybe AES + sha256 HMAC on the psk makes the most sense since the security would be the same as TLS session.

Copy link

I believe this protocol could forego sending any PSK entirely by using using BIP 322 and the bip21 address for authentication. The sender would authenticate the receiver's pubkey because it'd be signed MAC'd with the same key as the bip21 address. Such a protocol would require another round of communication to do ECDH before sending the fallback original psbt, but it would make the QR code a lot smaller.

This trade off is in internet connectivity + protocol complexity vs QR scan ability

Copy link

DanGould commented Mar 6, 2023

I'm thinking since only the receiver needs to allocate resources from a relay in this protocol, they should probably connect with WebSockets for rtc but allow the sender to stick to http, at least for the first version of this.

Copy link

What is HTTP SERVE method, where it's defined? Can't find such a thing in HTTP protocol specs.

Copy link

What is HTTP SERVE method, where it's defined? Can't find such a thing in HTTP protocol specs.

It's a custom method to tell the relay one is waiting for a response. While this sort of long-polling worked in demonstration, now I think WebSockets might make more sense for that side of communication.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment