add v1 and v2 explainer articles

docs/faq/_category_.json

@@ -1,6 +1,6 @@
 {
     "label": "Frequently Asked Questions",
-    "position": 2,
+    "position": 4,
     "link": {
       "type": "generated-index"
     }

docs/how-it-works/_category_.json

@@ -0,0 +1,8 @@
+{
+  "label": "How it Works",
+  "position": 2,
+  "link": {
+    "type": "generated-index",
+    "description": "Learn the technical details of the payjoin protocol"
+  }
+}

docs/how-it-works/v1.md

@@ -0,0 +1,59 @@
+---
+sidebar_position: 2
+title: Payjoin v1 (BIP 78)
+description: The initial payjoin flow
+---
+
+:::warning
+
+This version will be deprecated in favor of [Payjoin v2](./v2.md). However, everything defined here is backward-compatible and relevant to v2, so read on!
+
+:::
+
+### Motivation
+
+The initial payjoin specification as defined in [BIP 78](https://github.com/bitcoin/bips/blob/master/bip-0078.mediawiki) was designed to solve 2 problems for the sender (Alice) and receiver (Bob) of a given transaction:
+
+- The receiver misses an opportunity to **consolidate UTXOs** or **make a payment**.
+- The sender has privacy leaks due to heuristics about typical transactions.
+
+In most scenarios today, the sender signs a transaction containing _only_ her UTXOs and broadcasts it to the network. This pattern has led to several heuristics used to erode the privacy of those in the transaction and the network:
+
+- **Common input ownership heuristic**: The assumption that all inputs belong to the sender.
+- **Change identification from scriptPubKey**: The assumption that if all inputs spend from the same [scriptPubKey](todo) type (P2SH, P2PKH, P2TR, etc), then the change output is likely to have the same scriptPubKey too (since all the inputs belong to the sender, the output with the matching scriptPubKey is likely also the sender's).
+- **Change identification from round amount**: The assumption that the receiver gets the "round amount" (i.e. 0.3 instead of 0.354323...), since it's more natural for him to ask for payment in round amounts.
+
+The idea was to allow the receiver to consolidate UTXOs and/or batch payments during the sender's transaction to them (saving fees), and for the sender to invalidate the three heuristics above.
+
+Notably, payjoin transactions enhance the _efficiency_ of the network by reducing the number of transactions and the _privacy_ of the network by invalidating the reliability of the three heuristics used to track users.
+
+As Adam Gibson has noted, if some relatively small uptick in payjoin usage was observed, it would cast doubt on _all_ transactions, [even for those who don't payjoin](https://reyify.com/blog/payjoin#:~:text=Now%2C%20here%27s%20the,a%20privacy%20advantage!).
+
+### Protocol
+
+BIP 78 defines the following steps for payjoin:
+
+1. The receiver of the payment presents a [BIP 21 URI](https://github.com/bitcoin/bips/blob/master/bip-0021.mediawiki) to the sender with a parameter `pj=` describing a payjoin endpoint.
+   - Example: `bitcoin:<BITCOIN-ADDRESS>?pj=<RECEIVER-PAYJOIN-ENDPOINT>`
+2. The sender creates a signed, finalized PSBT with witness UTXO or previous transactions of the inputs. We call this PSBT the `original`.
+3. The receiver replies back with a signed PSBT containing his own signed inputs/outputs and those of the sender. We call this PSBT `Payjoin proposal`.
+4. The sender verifies the proposal, re-signs his inputs and broadcasts the transaction to the Bitcoin network. We call this transaction `Payjoin transaction`.
+
+![Payjoin v1 Flow](./img/v1.png)
+
+### BIP 21 Parameters
+
+The spec defines a few BIP 21 parameters for payjoin:
+
+- `pj=`: The receiver's http(s) endpoint which tells the sender where to POST the original PSBT to.
+- `pjos=0`: Signal to the sender that they MUST disallow [output substitution](https://github.com/bitcoin/bips/blob/master/bip-0078.mediawiki#payment-output-substitution) (the receiver's ability the modify the outputs. This should be set on unsecured servers to disallow the possibility of the receiver's funds being stolen.
+
+See the [full spec](https://github.com/bitcoin/bips/blob/master/bip-0078.mediawiki) for the full list of available parameters
+
+### Drawbacks
+
+One of the primary drawbacks of payjoin v1 is the requirement of a server for the receiver. This means that a) the funds received are kept in a hot wallet, and b) the server must be online at the time of payment receipt, which in practice means the server will likely need to be always-online. While this is probably fine for businesses, this is a significant barrier to individuals using payjoin. Thankfully, we can do better.
+
+### Next Steps
+
+Check out [BIP 78](https://github.com/bitcoin/bips/blob/master/bip-0078.mediawiki) to see the full payjoin v1 spec. In the next section, we'll learn how payjoin can be made _serverless_ and _asynchronous_ in version 2.

docs/how-it-works/v2.md

@@ -0,0 +1,66 @@
+---
+sidebar_position: 4
+title: Payjoin v2 (BIP 77)
+description: Serverless, asynchronous payjoin
+---
+
+:::note
+
+BIP 77 is still a draft BIP. Use at your own risk!
+
+:::
+
+### Motivation
+
+Payjoin version 2 ([BIP 77](https://github.com/bitcoin/bips/blob/bc3123e1dab1c5b08d6f934b11b4d741107ac386/bip-0077.mediawiki)) is a draft BIP designed to improve on the primary limitations of version 1. In version 1, a receiver was required to have a server from which to send the [BIP 21 URI](todo) as well as modify the **Original PSBT** from the sender into a **Payjoin PSBT**.
+
+Payjoin v2 eliminates this requirement by outsourcing the server called a _directory_ to an untrusted third party. This server is dead simple and has one task -- store pending payments from the sender, and forward them to the receiver when they come back online. These in-flight payment messages are small, ephemeral, and encrypted, so a malicious directory cannot snoop on or forge message contents.
+
+To make this work, in lieu of hosting a server themselves, the receiver starts a session with the directory to request a _subdirectory_ which will contain the encrypted payment PSBTs between the sender and receiver.
+
+That's all well and good, but what about the metadata being sent to the payjoin directory? After all, even if the untrusted directory couldn't see the actual transaction data, couldn't they see the sender and receiver's IP addresses and other metadata? Typically, yes, but payjoin v2 makes use of a novel protocol called [_Oblivious HTTP_](https://www.fastly.com/blog/enabling-privacy-on-the-internet-with-oblivious-http) to strip client identifying metadata from the request before it reaches the directory.
+
+Aside from these two changes in the means of communicating the transaction, the protocol remains largely the same as v1. V2 is also backward-compatible with v1.
+
+Payjoin v2 improves upon the ease-of-use by eliminating the need for the sender and receiver to be online at the same time, or for either to ever run any servers to do so. Unlike v1, it is both serverless and asynchronous, removing the primary barriers to adoption that v1 faced.
+
+### Protocol
+
+![Payjoin V2 Flow](./img/v2.png)
+
+:::info
+
+All requests made to the directory by the sender or receiver are done using OHTTP, so that the directory doesn't know any of their identifying metadata. OHTTP is explained below.
+
+:::
+
+At a high level (and omitting some important detail), a payjoin v2 transaction takes the following steps:
+
+- **Receiver**: Sends their payjoin pubkey to the directory to _enroll_ for a subdirectory on it.
+- **Receiver**: Out of band, the receiver of the payment shares a bitcoin URI with the sender including a `pj=` query parameter with the subdirectory. An `ohttp=` parameter containing the directory's public key should also be provided.
+- **Sender**: Creates an **Original PSBT** and sends it to the directory.
+- **Sender**: Continues to replay this request in order to await a response from the directory containing a `Payjoin PSBT`. It stops after a designated expiration time.
+- The request is stored in the **subdirectory**.
+- Once the receiver is online, it sends `/receive` requests to await updates from the subdirectory. The receiver decrypts and authenticates the response which it checks according to [the receiver checklist](https://github.com/bitcoin/bips/blob/master/bip-0078.mediawiki#receivers-original-psbt-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 `Payjoin PSBT`.
+- The `Payjoin PSBT` and HPKE keys are encrypted, authenticated, encapsulated in OHTTP, and sent to the directory's OHTTP Gateway.
+- The directory awaits a request from the sender if it goes offline. Upon request, it relays the encrypted `Payjoin PSBT`.
+- The sender validates the `Payjoin PSBT` according to [the sender checklist](https://github.com/bitcoin/bips/blob/bc3123e1dab1c5b08d6f934b11b4d741107ac386/bip-0077.mediawiki#senders-payjoin-psbt-checklist), signs its inputs and broadcasts the transaction to the Bitcoin network.
+
+### OHTTP
+
+[Oblivious HTTP](https://www.fastly.com/blog/enabling-privacy-on-the-internet-with-oblivious-http) works by separating who can see the client's metadata from who can see the actual request. There are four layers to the OHTTP architecture:
+
+- Client
+- Relay
+- Gateway
+- Target
+  The _client_ is trying to make a request to the _target_ in such a way that the target can only see the actual request, not the client's metadata.
+
+![OHTTP](./img/ohttp.png)
+
+1. The Client encapsulates and encrypts a request intended for the target and sends it to the relay.
+2. The Relay receives the encapsulated request and can see client metadata and HTTP headers, strips them, and sends the encapsulated request to the Gateway. This means that the relay knows identifying details about the Client. The encapsulated request is encrypted with a key the Relay doesn't have, so the Relay doesn't know what data has been sent to the Client, only the metadata.
+3. The Gateway receives the anonymized version of the Client's request from the Relay, decrypts and de-encapsulates it, and then forwards it to the Target. The Gateway doesn't know identifying information about the Client.
+4. The Target receives the request as a normal HTTP request without knowing any metadata about the Client, processes the request, and sends it back to the Gateway. The Gateway re-encapsulates/encrypts the response and sends it back through the Relay to the Client.
+
+To learn more about payjoin v2, dive into [BIP 77](https://github.com/bitcoin/bips/blob/bc3123e1dab1c5b08d6f934b11b4d741107ac386/bip-0077.mediawiki) or complete one of the tutorials!