BIP 77: Specify v1-fallback response mechanism #2186

pull DanGould wants to merge 1 commits into bitcoin:master from DanGould:dangould/bip77-issue-1487-v1-fallback changing 1 files +17 −0

DanGould commented at 9:09 AM on June 1, 2026: contributor

The receiver-to-sender response section presented HPKE encryption and POST as the only path, when v2 receivers servicing v1 (BIP 78) senders in the wild send the cleartext base64 PSBT via PUT to their own mailbox. Add a forward-reference from the v2 path to Backwards compatibility, and specify the v1-fallback response (no HPKE; PUT method; UTF-8 body; receiver's own mailbox as target) normatively in that section.

This puts the spec in line with PDK integrations in the wild.

Addresses payjoin/rust-payjoin#1487. Partially addresses payjoin/rust-payjoin#844.

Seeking your review, @nothingmuch
jonatack added the label BIP Update by Owner on Jun 1, 2026
in bip-0077.md:757 in 400c6f6faa
```
 750 | @@ -744,6 +751,16 @@ seconds or else the directory should respond with an `unavailable` JSON
 751 |  error code as [defined in BIP
 752 |  78](https://github.com/bitcoin/bips/blob/master/bip-0078.mediawiki#receivers-well-known-errors).
 753 |  
 754 | +When responding to a BIP 78 sender, the receiver MUST NOT HPKE-encrypt
 755 | +the *Proposal PSBT*. The receiver MUST send the *Proposal PSBT* as the
 756 | +body of a PUT request, with the body being the base64-encoded PSBT
 757 | +serialized as UTF-8 bytes. The target mailbox endpoint MUST be the
```
nothingmuch commented at 8:48 PM on June 4, 2026:

nit: "serialized as UTF-8 bytes" is correct, since base64 is a character based encoding and specifies a subset of ASCII, and UTF-8 is a superset of ASCII. there's no technical difference but this could say "serialized as ASCII", so arguably the implicit complexity of utf-8 is not necessary.

for reference, BIP 174 does not specify this, it treats the character/string and octet representations of PSBTs as separate (which is correct). BIP 78 otoh just ignores this distinction and implicitly assumes base64 is an octet encoding by composition with ASCII/UTF-8 (but realistically nobody is really going to serialize base64 as UTF-16 or EBDIC or whatever and be surprised that it doesn't work, so it's fine)

nothingmuch commented at 8:53 PM on June 4, 2026:

and another nit: "encoded" more correct than "serialized" for character -> octet step, but again it's not like this could be misconstrued
nothingmuch commented at 8:51 PM on June 4, 2026: contributor

ACK
jonatack commented at 7:22 PM on June 5, 2026: member

@DanGould do you plan to update to take the review suggestions?
murchandamus added the label PR Author action required on Jun 8, 2026

BIP 77: Specify v1-fallback response mechanism

The receiver-to-sender response section presented HPKE encryption and
POST as the only path, when v2 receivers servicing v1 (BIP 78) senders
in the wild send the cleartext base64 PSBT via PUT to their own mailbox.
Add a forward-reference from the v2 path to Backwards compatibility,
and specify the v1-fallback response (no HPKE; PUT method; UTF-8 body;
receiver's own mailbox as target) normatively in that section.

Addresses payjoin/rust-payjoin#1487. Partially addresses
payjoin/rust-payjoin#844 (PUT/POST gap).

9997e00576

DanGould force-pushed on Jun 8, 2026
DanGould commented at 4:53 PM on June 8, 2026: contributor

Suggestions applied
jonatack removed the label PR Author action required on Jun 8, 2026
jonatack approved
jonatack commented at 5:46 PM on June 8, 2026: member

Update to take feedback by @nothingmuch LGTM.
jonatack merged this on Jun 8, 2026
jonatack closed this on Jun 8, 2026

Contributors

Labels