BIP 77: Async Payjoin #1483
Merged
BIP 77: Async Payjoin #1483
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
17 tasks
|
Let's call this BIP 77 |
luke-jr
changed the title
This was referenced Jan 13, 2024
This was referenced Mar 19, 2024
|
Hi @DanGould, the first comment on this PR seems to indicate that this proposal is still WIP. Is that an accurate understanding? If this PR is not yet ready to be merged, perhaps it should be changed to "Draft". If I misunderstood the status of this PR, please respond below so someone may review to assess whether this is ready for merge. |
spacebear21
reviewed
May 2, 2024
spacebear21
reviewed
May 2, 2024
DanGould
force-pushed
the
pjv2
branch
2 times, most recently
from
51bb8c0 to
9f4624e
Compare
|
Converted to draft until we have some more experience with the implementations in the wild. Still seeking review especially on the soundness of the network privacy, choice of cryptosystem, and bip21 parameter encoding. |
DanGould
force-pushed
the
pjv2
branch
2 times, most recently
from
ee517dd to
5ff5b7a
Compare
spacebear21
reviewed
May 7, 2024
spacebear21
reviewed
May 7, 2024
thebrandonlucas
suggested changes
May 13, 2024
Co-authored-by: Brandon Lucas <thebrandonlucas@gmail.com>
Co-authored-by: Brandon Lucas <thebrandonlucas@gmail.com>
Co-authored-by: Brandon Lucas <thebrandonlucas@gmail.com>
Co-authored-by: Brandon Lucas <thebrandonlucas@gmail.com>
Co-authored-by: Brandon Lucas <thebrandonlucas@gmail.com>
jonatack
reviewed
May 27, 2025
| participant S as Sender | ||
| participant N as Network | ||
|
|
||
| R-)S: Payjoin URI (BIP 21) out of band |
There was a problem hiding this comment.
Suggested change
| R-)S: Payjoin URI (BIP 21) out of band | |
| R-)S: Payjoin URI (BIP 321) out of band |
There was a problem hiding this comment.
Your comment suggests no accommodations are necessary, as does Murch's suggestion above. Are you convinced this one change is all that is necessary (plus Depends on BIP 321 in the preamble)?
There was a problem hiding this comment.
Hey, I have read both yours and BIP 321, but I haven’t studied in detail whether accommodations would be necessary. I think it was @nothingmuch that thought it should just be compatible. My suggestion was merely that with BIP 321 coming out, it would be nice if yours took it into account, which it sounds like you did.
There was a problem hiding this comment.
Upon further consideration. I'm going to leave this as-is. BIP 321 URI is a BIP 21 URI. And this document already makes the case-insensitivity considerations w.r.t. parameter key case that BIP 321 expands on from BIP 21.
BIP 321 states "Any existing BIP 21 implementation should automatically be fully compliant with this BIP [BIP 321]" and therefore the lowest common dependency seems to be the most appropriate to mention.
Co-authored-by: Jon Atack <jon@atack.com>
Co-authored-by: Jon Atack <jon@atack.com>
Co-authored-by: Jon Atack <jon@atack.com>
Co-authored-by: Jon Atack <jon@atack.com>
Co-authored-by: Jon Atack <jon@atack.com>
Co-authored-by: Jon Atack <jon@atack.com>
Co-authored-by: Jon Atack <jon@atack.com>
Co-authored-by: Jon Atack <jon@atack.com>
Co-authored-by: Jon Atack <jon@atack.com>
Co-authored-by: Jon Atack <jon@atack.com>
Co-authored-by: Jon Atack <jon@atack.com>
Co-authored-by: Jon Atack <jon@atack.com>
Co-authored-by: Jon Atack <jon@atack.com>
|
@jonatack I believe I've addressed each of your comments in this last review. Thanks for the useful feedback. Your polish really elevates the reading experience. |
A specific order might create a fingerprint for a specific wallet, imposing a privacy risk. It seems impossible to impose an order on BIP21 parameters, but BIP 77 clients may error on out-of-order fragment parameters to at least avoid some fingerprint there. Reverse lecicographical ordering was chosen because that is how the existing implmentation serializes the parameters already, so that no breaking change needs to be made. Co-authored-by: nothingmuch <nothingmuch@woobling.org>
|
Addressed comments requiring @jonatack's feedback, decided to stick with BIP 21 since that's the lowest common dependency, and imposed a requirement on fragment parameter order since it might impose a fingerprint (thanks @murchandamus for bringing up the consideration of parameter order). |
jbride
pushed a commit
to jbride/bips
that referenced
this pull request
Jun 11, 2025
* Draft payjoin v2 BIP * Include mailing list feedback * Include TABConf feedback * Include padding * Include production reference implementation * Adopt BIP-77 for payjoin v2 * Distinguish payjoin directory from OHTTP Relay * Detail OHTTP Key Configuration mechanism * Fix punctuation * Make base64URL references consistent * Reference standardized Secp256k1 DHKEM for HPKE * Add Comments-URI * fixup: Format and spell check Co-authored-by: spacebear <144076611+grizznaut@users.noreply.github.com> * Add BIP 77 to README * Add Payjoin V2 overview diagram * Add Oblivious HTTP Sequence Diagram * Correct links and spelling Co-authored-by: thebrandonlucas <38222767+thebrandonlucas@users.noreply.github.com> * Wrap <code> blocks * Fix basic scheme actors * Fix dead samourai links * Orient motivation around a problem * fix links * Keyconfig s/should/must/ be provided * Fix typos Co-authored-by: thebrandonlucas <38222767+thebrandonlucas@users.noreply.github.com> * s/pubkey/public key * Incorporate jonatack's suggestions * Incorporate more jonatack suggestions * Incorporate satsie's suggesetions * Rename "Async Payjoin" * Replace BIP21 params with fragment params * Revise document to describe Payjoin Sessions Enrollment was a less clear than sessions * Revise Sequence Diagram * Spell initialize * Update the bip to represent the stable protocol * Spell according to Type Checks's job * Mention the format of the ohttp fragment * Reference BIP 78 attack vectors * Remove straggling text * Specify authorization mechanism The specifics of a credential issuance are left out, however * Use implicit session initialization * Specify cryptographic handshake based on Noise IK Co-authored-by: Yuval Kogman <nothingmuch@woobling.org> * Add Spacebear's clarifications Co-authored-by: spacebear <git@spacebear.dev> * Document subdirectory Short IDs * Require uppercase URL bech32 fragment prefixes are case sensitive, and alphanumeric mode only works on capital letters. * Specify bech32 fragment parameter definitions * Uppercase URL specifically only after subdirectory * Note payload uniformity via padding and ellswift * Include Message Byte Representations This is the most straightforward way to explain the various padding requirements. * Document HPKE `info` strings * Truncate lines to 120 characters * Receiver's Original PSBT, not proposal * Specify no mixed [output script] * Remove extraneous pipe character * Require BIPS 21, 78, 174 * Update checklist MUST/MUST NOT sections MUST NOT contained MUST details. Move them to MUST. * inputs ⇒ input * Clarify BIP 78 payjoin version 1 connection * Fix backwards compat language * Payjoin version 2 URIs * Reference Binary HTTP RFC * Payjoin version 1 Proposal PSBTs * Oblivous -> Oblivious * Rm reference to 'production relays' * Repeat the active agent by name * Add Post-History * Title 'Async Payjoin' * Check spelling * directory -> mailbox * Move ohttp= fragment param to link to frag spec * Mention URI keys as bootstrap mechanism * Mailbox Discovery * Remove superfluous word * Clarify motivation * Revise backwards compatiblity section for clarity * Remove related protocol details * Mv copyright out of flow * Fix grammar (should be plural) * Weaken language around addressing CIOH "solves" implies this is the end of the story. Clarify that the problem is the sole *explicit* problem mentioned in the paper. * Simplify overview - describe happy path protocol sequence - introduce non-obvious key terms inherited from BIP 78 - no need for technical details that are clarified in the specification * Describe optionality in overview * Nitpicky sequence diagram fixes * Clarify receiver's initial message in sequence diagram * Simplify Basic Scheme section * Mention OHTTP abbreviation on first mention * Move sequence diagram up * fragment parameter encoding corrections - base64url was replaced by bech32 - formatting fixes - some clarifications * Use SHA-256 at independent mentions for consistency * bootstrap grammar fix & correction bootstrap would use a tor exit node, not a hidden service * clarify proposal PSBT encryption layers clarify which key is used for which layer of encryption (payjoin v2 e2ee vs. OHTTP) the message is not "authenticated" by the sender, rather it is tagged, it can be authenticated during decryption. * format original/proposal PSBT terms using italic, not <code> * HRP of short ID is an implementation detail it doesn't matter what is used since it's stripped after encoding * Clarify checklist requirements * "by intersection" unclear and unnecessary * the fragment doesn't follow the pj param, it's part of it * fix message diagram line intersections * Correct encapsulated OHTTP diagram The binary HTTP request is encrypted, and the AEAD tag is at the end, not the beginning * Clarifications for HPKE keys Remove noise protocol framework mention. The IK pattern is not accurate, the closest patterns are N or possibl NN, but neither is a perfect fit (N defines the key as static, which it isn't, and NN is an interactive pattern) * Remove note about forward secrecy This is inaccurate, forward secrecy is defined with respect to long term sessions, so the definition doesn't really extend to the request and response messages, each of which is encrypted with ephemeral keys. * Clarify OHTTP-relay bypassing by use of tor hidden service * Update HPKE mode used for sender's message Previously the reply key was included before the HPKE ciphertext, and the Auth mode was used using this key. Since they are delivered together that only proves the key was usable by the sender, not that the ciphertext is authentic. With the key included as part of the encrypted plaintext, the HPKE mode was changed to the base encryption to a public key mode with no authentication key. * keep mailbox, but rename mailroom back to directory Partly reverts a4d4065, this change is hardly more than a find & replace of mailroom to directory, and does not revert grammar changes etc in addition to not reverting the subdirectory -> mailbox rename which was the main point of confusion. * Clarify allowed_purposes mechanism First explain RFC 9540, then explain the extension mechanism. Make roles in the interaction more explicit by changing the heading, "Directory Discovery" sort of implies that clients discover these, when it describes relay to directory interaction. Clarify centralization pressure, that is alleviated by making senders' and receivers' choices independent of each other. * Correct payload uniformity section We forgot about the OHTTP header which is 7 bytes of cleartext that also specifies the DHKEM algoritm. Additional clarifications and some restructuring to describe the details two classes of messages each in its own self contained paragraph. * rewrap paragraph to fix broken link * fix bullet list formatting - unindent to avoid <pre> - fix broken URLs - fix bullet items split into paragraphs * rewrap section to fix broken links * rewrap more paragraphs to fix broken links * make attack vectors level 2 heading as level 3 heading it was displayed under rationale in the table of contents * Grammar/style fixes * Order Requires * Describe 'what' in the first sentence of the abstract. * Be more specific about motivation. * Make goal more explicit and consise * Standardize "Common-input-ownership heuristic" bitcoin wiki uses this. * Replace Request expiration with Session Expiration * Specify BIP 78 `v` parameter as redundant. * Separate Short ID length rationale from spec * Clairfy key nomeclature - mailbox key - reply key - receiver key as well as ephemerality and session nomeclature. * Place byte diagrams with there respective message description. * Include bitcoin URI subsection * Top half reorg * Add Yuval Kogman as Co-author * NO mak typo * Fix heirarchy * Convert mediawiki to markdown nix shell nixpkgs#pandoc --command bash -lc ' pandoc -f mediawiki -t gfm bip-0077.mediawiki -o bip-0077.md' rm bip-0077.mediawiki reference bip-0077.md in README surround bip-0077.md preamble in ``` to satisfy CI * Strip link titles from mediawiki -> md conversion sed -i.bak -E 's/\]\(([^ )]+) "[^"]*"\)/](\1)/g' bip-0077.md * Strip leading/trailing spaces from inside links sed -i.bak -E 's/\[[[:space:]]+/[/g; s/[[:space:]]+\]/]/g' bip-0077.md * Fix spacing around inline code * Take bitcoin URI example out of md link syntax * Fence byte diagrams in backtics * Replace sequence diagrams with mermaid Better rendering and semantic source * Collapse overview, basic scheme, and protocol sequence These were all inconsitent levels of detail for the same thing. Leave the overview the highest level and link to the specifics. * Consistent short id singularity * Remove straggling whitespace * Link whitepaper * Fix motivation flow * Clarify abstract * Clarify motivation * Clarify overview * Clarify bootstrapping * Use singular to describe Payjoin URI * Clarify mailbox endpoint Specify that v2 mailboxes are OHTTP Targets. Mention backwards compatibility. * Clarify Receiver Fragment Parameters * Revise messaging for clarity * Add rationale for allowed_purposes * Define ElligatorSwift according to BIP 324 * Clarify attacks, backwards compatibility * Fix Receiver Proposal PSBT messaging header for link. * Add activation to sequence * Correct bitcoin#64-bit-short-id-length link Co-authored-by: Yuval Kogman <nothingmuch@woobling.org> * Clarify why not AES-GCM rationale * Specify serialization of reply key in plaintext * Specify the wire format for ChaCha20-Poly1305 ciphertext and tag * Specify details of HPKE message wire format Also clarifies that HPKE auth mode is used with the receiver's key, authenticating the receiver as the sender of the encrypted Proposal PSBT. * Correct diagram for OHTTP encapsulation The order according to RFC 9458 and the code is is header, followed by encapsulated key, followed by the ciphertext. * OHTTP message encoding according to RFC 9458 * Rephrase abstract in active voice * Deduplicate motivation word choice - 'suitable for widespread implementation' vs appropriate, it's stronger - 'mature solutions' to express that we chose those already based on iteration - 'proven bitcoin primitives' to reflect the use of those battle tested like ElligatorSwift * Simplify output batching motivation * Reduce verbosity of linking exemplar conclusion * Use PSBT 'update' verb in overview Say 'appropriate intputs and/or outputs' because outputs might be merely replaced, not necessarily added. * Mention mutual exclusivity of Original and Proposal PSBTs * Capitalize Uri -> URI * Clarify URI parameter key/value distinction * Backwards-compatible receivers *disable* pjos * Use bech32 character set, not bech32 * Clarify session-specific parameter encoding * Say 33-byte compressed public key * Clarify v2 optional sender parameters application * Clarify receiver session initiation overview Co-authored-by: nothingmuch <nothingmuch@woobling.org> * Mention sender's ephemeral mailbox in overview Co-authored-by: nothingmuch <nothingmuch@woobling.org> * Clarify cut-through optimization * Replace mention of v1/v2 payjoin Instead use 'This proposal', 'BIP 78', 'BIP 77', or omit the mention. * Mention BIP 174 for PSBTv0 * Mention sender's *corresponding* public key * Hyphenate '16-byte' * Clarify who can post messagese direct to mailbox * liu -> lieu * Simplify cut through overview sentence structure * Replace 'Payjoin exemplar' with 'A natural application..' * Make motivation CIOH mention easier to read Use language from sataoshi and don't mention input batching since the next sentence already does. * Specify Proposal PSBT MUST/MAY input/output inclusion rules * remove duplicate 'and' * Remove duplicate 'preserve' Co-authored-by: Brandon Lucas <thebrandonlucas@gmail.com> * The HRP is used as the parameter key Co-authored-by: Yuval Kogman <nothingmuch@woobling.org> * Add rationale for random padding in OHTTP * Use "zero" instead of "0" Co-authored-by: Mark "Murch" Erhardt <murch@murch.one> * epehmeral -> ephemeral Co-authored-by: Brandon Lucas <thebrandonlucas@gmail.com> * subject match tense Co-authored-by: Brandon Lucas <thebrandonlucas@gmail.com> * Capitalize Payjoin for protocol Co-authored-by: Brandon Lucas <thebrandonlucas@gmail.com> * Capitalize Payjoin for protocol Co-authored-by: Brandon Lucas <thebrandonlucas@gmail.com> * Capitalize Payjoin for protocol Co-authored-by: Brandon Lucas <thebrandonlucas@gmail.com> * Capitalize Payjoin for protocol Co-authored-by: Brandon Lucas <thebrandonlucas@gmail.com> * Capitalize Payjoin for protocol Co-authored-by: Brandon Lucas <thebrandonlucas@gmail.com> * ("Version 2") relative to and described in ("Version 1") Co-authored-by: Jon Atack <jon@atack.com> * BIP78's requirements for Payjoin Version 1 Co-authored-by: Jon Atack <jon@atack.com> * Include missing period Co-authored-by: Jon Atack <jon@atack.com> * which -> that Co-authored-by: Jon Atack <jon@atack.com> * Separate independent clauses with a semicolon Co-authored-by: Jon Atack <jon@atack.com> * Remove duplicate "at" Co-authored-by: Jon Atack <jon@atack.com> * Hyphenate "short-lived" Co-authored-by: Jon Atack <jon@atack.com> * Fix Attack Vectors URL Co-authored-by: Jon Atack <jon@atack.com> * which -> that Co-authored-by: Jon Atack <jon@atack.com> * Include colon to reference Oblivious HTTP Relay impl Co-authored-by: Jon Atack <jon@atack.com> * consist -> consists Co-authored-by: Jon Atack <jon@atack.com> * Remove double "the" Co-authored-by: Jon Atack <jon@atack.com> * Remove double "the" Co-authored-by: Jon Atack <jon@atack.com> * Correct Padded BHTTP Response length 144 bytes not 104 See: https://github.com/payjoin/rust-payjoin/blob/87042266d124873be360320834245f5a9a50d7f1/payjoin-directory/src/lib.rs#L30-L31 * which -> , which * Note TLS is not available in Bitcoin Core * Link to BIP21 forwards compatibility `reqparam` * Require rev. lexicographical frag. param. order A specific order might create a fingerprint for a specific wallet, imposing a privacy risk. It seems impossible to impose an order on BIP21 parameters, but BIP 77 clients may error on out-of-order fragment parameters to at least avoid some fingerprint there. Reverse lecicographical ordering was chosen because that is how the existing implmentation serializes the parameters already, so that no breaking change needs to be made. Co-authored-by: nothingmuch <nothingmuch@woobling.org> --------- Co-authored-by: spacebear <144076611+grizznaut@users.noreply.github.com> Co-authored-by: thebrandonlucas <38222767+thebrandonlucas@users.noreply.github.com> Co-authored-by: Yuval Kogman <nothingmuch@woobling.org> Co-authored-by: spacebear <git@spacebear.dev> Co-authored-by: spacebear <144076611+spacebear21@users.noreply.github.com> Co-authored-by: Brandon Lucas <thebrandonlucas@gmail.com> Co-authored-by: Mark "Murch" Erhardt <murch@murch.one> Co-authored-by: Jon Atack <jon@atack.com>
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
This document proposes an asynchronous, backwards-compatible second version of the payjoin protocol described in BIP 78, enabling complete payjoin receiver functionality including payment output substitution with only an HTTP client rather than server. The former requirement for receivers to run HTTP servers is replaced with an untrusted third-party "payjoin directory" store-and-forward server accessed by polling clients which communicate using an asynchronous protocol and authenticated, encrypted payloads. It was originally proposed to the mailing list here.
The protocol design has received rounds of review elsewhere on the bitcoin-dev mailing list as well.
Feedback from that list post has been incorporated into this draft.
Proposing this as an Standards Track BIP to ensure wallets across the ecosystem can come to rough consensus on a single asynchronous payjoin standard and correctly implement it widely.