Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Binary file added docs/img/coinjoin.png
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why do some of the images have double lines and other do not? Each of the 4 images has at least once instance of this discrepancy.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do you mean double lines like these? If so, this is just the semi-random "sketched" look that excalidraw.com, which was used to make these diagrams and is a very commonly used/popular open source tool for these sorts of things. I would be surprised if this caused confusion generally and think it's probably not a big deal, but perhaps there's configurations in excalidraw to mitigate this.
Screenshot 2024-06-12 at 7 25 43 AM

Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/img/multiple.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/img/payjoin.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/img/regular.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
52 changes: 52 additions & 0 deletions docs/intro.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,52 @@
---
sidebar_position: 1
---

# Introduction
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Titles should grab attention. Even "What is Payjoin?" Would be better for search here, and we might even be able to do better.

I think it's important to recognize that this is a piece of Content Marketing and should be written as such.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agreed 🤝 will change this


Payjoin is a protocol for creating collaborative transactions between a sender (Alice) and a receiver (Bob). It is simple, requires no changes to bitcoin, can operate without any manual interaction from the user, and has a variety of benefits and use cases, including:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The first sentence has to be a hook. Parentheticals are important caption information for the image, but don't add to a compelling reason to keep reading. The list of reasons why is good but perhaps should be summarized and then ordered as they will follow in the article to prepare a reader for what is to come.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I agree, I fronted "Alice" and "Bob" here so that the user would have context for the rest of the article, but they feel distracting here. Also totally agree with having brief summaries on the list of reasons


- **Privacy**
- **Cost & Time Savings**
- **Scaling**
- **Flexibility & Extensibility**

In a typical on-chain bitcoin transaction, all of the [UTXOs](https://unchained.com/blog/what-is-a-utxo-bitcoin/) would belong to Alice. After all, one might ask, what sense does it make for Bob to send bitcoin to himself? It is _assumed_ that the spender in a transaction is the one who owns every UTXO:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A link is good, but any abbreviation / acronym should be stated in full followed by the abbreviation in parens to use further down the article. e.g. "Unspent Transaction Outputs (UTXOs)." A brief explanation of how bitcoin uses UTXOs seems necessary to proceed with technical details.

What purpose does the double "After all, one might ask" serve? Would fewer words do?

Why is assumed italicized?

Copy link
Collaborator Author

@thebrandonlucas thebrandonlucas Jun 12, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

any abbreviation / acronym should be stated in full followed by the abbreviation in parens to use further down the article.

Yes! Good catch.

A brief explanation of how bitcoin uses UTXOs seems necessary to proceed with technical details.

Can do.

What purpose does the double "After all, one might ask" serve? Would fewer words do?

It was intended to emphasize that it's unnatural to think of UTXOs belonging to more than one owner and contrasts that with the previous sentence as being the natural thing to do. Just saying "What sense does it make..." feels to not get enough of the point across to me that the reader would also naturally think Bob wouldn't send the bitcoin to himself just like a chain analysis company. I agree that "one might ask" is over the top though, perhaps we can reduce to:
"After all, what sense does it make..."

Why is assumed italicized?

Because I have an overzealous love of em_PHA_sis. Will remove 😄


![Assumed Transaction](./img/regular.png)

This assumption is called the [common-input-ownership heuristic](https://en.bitcoin.it/wiki/Common-input-ownership_heuristic), and even Satoshi declared it the last unsolved privacy problem in the [whitepaper](https://bitcoin.org/bitcoin.pdf). But it wasn't unsolved, just undiscovered. Because the common-input-ownership heuristic is not required, a transaction can be constructed with any number of participants spending to anyone, including to themselves. One such combination is a [CoinJoin](https://en.bitcoin.it/wiki/CoinJoin), whose primary purpose is for the participants to collaboratively construct transactions to themselves to gain privacy. But it comes at the cost of paying high fees and requires high user interaction.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Satoshi's problem seems to be the hook of the whole piece and I think we're in agreement that solving it is stated purpose of this project. Putting the quote in the body makes a lot of sense to me.

[L]inking is still unavoidable with multi-input transactions, which necessarily reveal that their inputs were owned by the same owner. The risk is that if the owner of a key is revealed, linking could reveal other transactions that belonged to the same owner.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do you think we should put it here despite our reworking this to be more about cost savings/scaling than privacy? Should we save inputting this paragraph for the privacy section?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

CoinJoin is convenient when getting to the technical heart of Payjoin compared to existing tech. Depending on the target audience. I'd consider building up from a typical transaction instead, show how Common Input Heuristic is a threat, and show how payjoin breaks that.

Alternatively, since savings & scaling is the unique selling point of payjoin compared to other CIH busters, it might be interesting to explore building up the article from that perspective instead, starting with typical transactions and consolidation separately and showing a fee savings as a solid number for an example off the bat.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"Privacy without sacrificing savings" somewhere would be a good distinction. This gives me the idea that we should also have a "features" table where payjoin has most of the green check marks ("non-interactive" ✅ , no extra costs ✅ , etc.)

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"[Common-input-ownership heuristic] wasn't unsolved, just undiscovered" ? What does this mean? Doesn't Satoshi declare it to be a problem right off the bat?

I like "batched" or "batch" transaction more than "collaborative." It's a simpler word that gets the point across more concretely and has less magic aura over it.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

But it wasn't unsolved, just undiscovered.
I remember thinking this was cool when I wrote it, but have no idea what it means now. Whoops. Will remove.

I like "batched" or "batch" transaction more than "collaborative."
Agreed 🤝


![CoinJoin](./img/coinjoin.png)

Payjoin is a different combination, which uses both sender and receiver UTXOs:

![Payjoin](./img/Payjoin.png)

### Privacy

Payjoin also breaks the common-input-ownership heuristic, which is the primary metric used by creepy blockchain analysis companies trying to spy on your financial life. In this way, it restores and re-normalizes privacy as a fundamental human right back to the common individual, breaking the mold of difficult to use, expensive, centralized CoinJoin coordinators which can invite bad actors <!-- include this last part??? -->. With Payjoin, privacy best practices can be seamlessly integrated into the wallet experience, it is not a requirement that the user be aware they are conducting a Payjoin. Privacy is easy if it's obtained by _default_.

### Cost & Time Savings

Payjoin can save money and time by batching transactions when fees are low. Most wallets default to [address reuse](https://en.bitcoin.it/wiki/Address_reuse) (as they should!). This however results in more UTXOs when spending a transaction. Since the scarce resource in Bitcoin is block space, the [fee](https://unchained.com/blog/bitcoin-transaction-fees/) paid (in satoshis) in a transaction is measured relative to the number of bytes in the transaction, i.e. satoshis per byte or [satoshis per virtual byte](https://bitcoin.stackexchange.com/questions/89385/is-there-a-difference-between-bytes-and-virtual-bytes-vbytes). So if you have many small UTXOs, you're likely to have to combine some to make larger payments, which results in higher fees. Therefore, you should periodically [consolidate UTXOs](https://unchained.com/blog/too-many-bitcoin-utxos/) by sending them to a new address you own when fees are low.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

why should most wallets default to address reuse? And why does that result in more UTXOs (and more than what?)

passive voice "the fee ... is measured" could be active

Copy link
Collaborator Author

@thebrandonlucas thebrandonlucas Jun 12, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

why should most wallets default to address reuse? And why does that result in more UTXOs (and more than what?)

Jeez, I meant the exact opposite of what I actually wrote here. My mistake for not catching this obvious mistake on reread. What I meant was:

Most wallets default to generating new addresses for every payment to avoid address reuse (as they should!)

Will fix


Payjoin performs a consolidation on _every_ payment. While wallets today make this a manual, interactive experience, this can easily be the default for wallets that integrate Payjoin. Bitcoin users wouldn't have to worry about taking this extra step as it can be automated for them.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Does payjoin consolidate on every payment? Does that exclude cut-through?

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Oh, it definitely doesn't necessarily, this was just my mental model when writing this for some reason. Good catch.


Payjoin can also save time in Lightning Network channel opens by turning the two step process of creating and funding a lightning node [into one step](./why-payjoin/lightning.md).

### Scaling

As stated above, Payjoin's ability to negotiate the combination of UTXOs during transaction creation allows for opportunistic consolidation when fees are low. But it also allows for multiple transactions to be performed at once. In applicable scenarios (such as in simultaneously funding a lightning node and opening channels), any number of spends can be conducted with only a single on-chain transaction footprint. If you know you have to make a payment to multiple parties, why not just do it in one transaction and save on fees?

![Multiple](./img/multiple.png)

### Flexibility & Extensibility

Because Payjoin utilizes [BIP 21](https://bitcoinqr.dev/) payment URIs, parameters related and unrelated to Payjoin can be used and understood by wallets. The use of BIP 21 allows wallets that don't support Payjoin to fallback to regular transactions, allows for the configuration of the many [Payjoin-specific parameters](https://github.com/bitcoin/bips/blob/master/bip-0078.mediawiki#bip21-Payjoin-parameters), as well as parameters outside the Payjoin protocol or ones yet-to-be created.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

passive

"parameters related and unrelated to Payjoin can be used and understood by wallets"

active

"Wallets can use and understand parameters related and unrelated to payjoin"

concise

"Wallets can select a payment method they support from a list"

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Love it.


### Next Steps

Payjoin allows for automated enhancements to on-chain bitcoin that users currently have to expend a great deal of time and money to achieve. It upgrades bitcoin transactions from being laborious, costly, and traceable to being automated, efficient, and private. No soft forks required.

Keep going to learn more about how Payjoin works and its potential applications!