BIP 77: Async Payjoin (#1483)

* 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 #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>

Author: 6 people

README.mediawiki

@@ -428,6 +428,13 @@ Those proposing changes should consider that ultimately consent may rest with th
 | Standard
 | Final
 |-
+| [[bip-0077.md|77]]
+| Applications
+| Async Payjoin
+| Dan Gould, Yuval Kogman
+| Standard
+| Draft
+|-
 | [[bip-0078.mediawiki|78]]
 | Applications
 | A Simple Payjoin Proposal