Skip to content
Draft
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
3 changes: 3 additions & 0 deletions _typos.toml
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
[default.extend-words]
# A given name, in a citation.
Damon = "Damon"
7 changes: 6 additions & 1 deletion cspell.json
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,8 @@
"python",
"networking-terms",
"bitcoin-privacy",
"repo-tooling"
"repo-tooling",
"background"
],
"dictionaryDefinitions": [
{
Expand All @@ -31,6 +32,10 @@
{
"name": "repo-tooling",
"path": "./cspell/tooling.txt"
},
{
"name": "background",
"path": "./cspell/background.txt"
}
]
}
88 changes: 88 additions & 0 deletions cspell/background.txt
Original file line number Diff line number Diff line change
@@ -0,0 +1,88 @@
# Authors, projects and terms cited in docs/background, and misspellings quoted from sources
Aloni
Androulaki
Arvind
beliece
Bernasconi
bitcoinj
Böhme
Boneh
Calvez
Capkun
CIOH
Claessens
clusterable
Coinswap
Damiano
Danezis
deanonymized
Deidentification
Dorit
Elli
emember
entropist
Fergal
fingerprintable
Friedhelm
Ghassan
Goldfeder
Gruber
Haaroon
Hamacher
Haslhofer
Ishaana
Kalodner
Kappos
Karame
Katzenbeisser
Katzenpost
keyspend
Kirill
Kogman
Kristov
Latanya
Levchenko
Loporchio
Maesa
Maffei
Marjori
Maurer
Meiklejohn
Misra
Mixmaster
mixnet
mixnets
Monero
Möser
multisigs
Nordholt
nothingmuch
Pomarole
Preneel
Rainer
Reisman
Ricci
Roeschlin
Rollet
Romiti
Samourai
Serjantov
Seys
Srdjan
Stefaan
strawmen
Stütz
Syverson
textrm
Tramer
unlinkable
unredacted
Voelker
walletexplorer
Weili
xpubs
Yakun
Yousaf
Yuval
Zcash
Zhenghao
107 changes: 107 additions & 0 deletions docs/background/faces-of-coinjoin.md

Large diffs are not rendered by default.

164 changes: 164 additions & 0 deletions docs/background/headaches-of-coinjoin.md

Large diffs are not rendered by default.

90 changes: 90 additions & 0 deletions docs/background/history-of-wallet-clustering.md

Large diffs are not rendered by default.

Binary file added docs/background/img/faces-of-coinjoin-1-dark.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/background/img/faces-of-coinjoin-1-light.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
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/background/img/intersection-attacks-1.jpg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
222 changes: 222 additions & 0 deletions docs/background/intersection-attacks.md

Large diffs are not rendered by default.

36 changes: 36 additions & 0 deletions docs/background/wallet-clustering-basics.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,36 @@
---
type: Essay
title: "Wallet clustering basics"
description: "How chain analysis links coins to a common owner, starting from address reuse and the common input ownership heuristic."
status: stable
---

# Wallet Clustering Basics

> Originally published as [The Scroll #2: Wallet Clustering Basics](https://spiralxyz.substack.com/p/the-scroll-2-wallet-clustering-basics) by Yuval Kogman
> ([@not_nothingmuch](https://x.com/not_nothingmuch)) on Spiral,
> 2025-03-12.

The Bitcoin transaction graph has various observable patterns. Some of these patterns have been studied and used to link coins from the same wallet, both in theory and practice.

Every transaction consists of a list of inputs (where the sats are taken from) and outputs (where the input sats are distributed). **Inputs** refer to the outputs of previous transactions, such as connecting transactions. **Outputs** lock some amount of Bitcoin with certain spending conditions (i.e., the "address," public key, or output script). Linking coins means identifying the entity that controls the keys to a collection of transaction outputs, spent or unspent.

Section 10 of the Bitcoin Whitepaper, "Privacy,” briefly discusses linking:

> A new key pair should be used for each transaction to keep them from being linked to a common owner.

When the same public key controls more than one coin, these coins are trivially linked since only one entity is supposed to know the private key.

However, address reuse is not the only concern. The paper continues:

> Some linking is still unavoidable with multi-input transactions, which necessarily reveal that their inputs were owned by the same owner.

This is often referred to as the "common input ownership heuristic," **CIOH**, or the "multi-input heuristic." It's only a heuristic because, unlike the implication in the quote above, counter-examples exist. Although it isn't always true, it often is.

Over the years, more sophisticated methods for clustering have been developed, for example, telling apart change outputs from payments or using larger structures in the transaction graph than just individual transactions. Some of these have been described in academic work, while others remain proprietary. Improved methods can link to more coins or avoid so-called "cluster collapse," where coins belonging to different users are incorrectly connected. Commercial offerings often benefit from additional sources of information, such as KYC data; they don’t necessarily depend on just the privacy leaks that occur in the Bitcoin protocol, but clustering is still the central theme.

This motivates an adversarial framing of privacy, where a deanonymization attack attempts to assign coins to clusters. From this perspective, defending privacy means making it more difficult for the adversary to succeed in correctly assigning coins to clusters. The most notable examples involve collaborative transaction construction, whether it is overtly difficult to guess, as in CoinJoin, or covertly as in PayJoin, or perhaps most prominently just a part of how the software works as with Lightning node transactions, in all cases the simplistic assumption breaks down necessitating a more nuanced analysis.

The adversarial framing also makes it explicit that different adversaries have different capabilities, with the appropriate adversarial model depending on the user’s threat model: Are you more worried about surveillance by an oppressive government or snooping by your transaction’s counterparties?

Future posts will go into more detail on these subjects.
8 changes: 8 additions & 0 deletions docs/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,14 @@
okf_version: "0.2"
---

# Background

* [Wallet clustering basics](background/wallet-clustering-basics.md) - How chain analysis links coins to a common owner, starting from address reuse and the common input ownership heuristic.
* [A brief history of wallet clustering](background/history-of-wallet-clustering.md) - A survey of the academic literature on wallet clustering, from early observational studies to wallet fingerprinting.
* [Intersection attacks on CoinJoin anonymity](background/intersection-attacks.md) - Measuring anonymity with entropy, and how intersections of clusters over time erode CoinJoin anonymity sets.
* [The many faces of CoinJoins](background/faces-of-coinjoin.md) - What "CoinJoin" refers to: equal amount CoinJoins, multiparty batching, PayJoin and Lightning.
* [The many headaches of CoinJoin](background/headaches-of-coinjoin.md) - Why designing a CoinJoin that overtly optimizes for privacy is harder than the folk anonymity set model suggests.

# BIP Drafts

* [PSBT Scrubber](bip-drafts/scrubber.md) - Which PSBT fields can be shared with trusted and untrusted parties such that privacy is preserved.
Expand Down
46 changes: 42 additions & 4 deletions theme/diagrams.css
Original file line number Diff line number Diff line change
Expand Up @@ -3,15 +3,17 @@
once per theme and swapped here; graphviz keeps whatever its .dot source
asks for, with only graphviz's own defaults lifted for the dark themes. */
.mdbook-graphviz-output,
.mermaid {
.mermaid,
.chart-src {
overflow-x: auto;
margin: 1rem 0;
}

/* Scale wide graphs down to the content column instead of clipping them;
the svg viewBox keeps them sharp at any size. */
.mdbook-graphviz-output svg,
.mermaid svg {
.mermaid svg,
.chart-src img {
display: block;
max-width: 100%;
height: auto;
Expand All @@ -23,14 +25,16 @@
only just overflow still fit without scrolling. */
@media (max-width: 700px) {
.mdbook-graphviz-output,
.mermaid {
.mermaid,
.chart-src {
margin-left: calc(-1 * var(--page-padding, 15px));
margin-right: calc(-1 * var(--page-padding, 15px));
padding: 0 var(--page-padding, 15px);
}

.mdbook-graphviz-output svg,
.mermaid svg {
.mermaid svg,
.chart-src img {
max-width: none;
}
}
Expand Down Expand Up @@ -67,3 +71,37 @@ html:is(.coal, .navy, .ayu) .mdbook-graphviz-output [fill="black"] {
html:is(.coal, .navy, .ayu) .mdbook-graphviz-output text:not([fill]) {
fill: #b7b7b7;
}

/* Each chart has a light and a dark file, marked for GitHub by its URL
fragment; book themes select one the same way. */
.chart-src img[src$="#gh-dark-mode-only"] {
display: none;
}

/* Print the light palette even when the reader selected a dark book theme. */
@media screen {
html:is(.coal, .navy, .ayu) .chart-src img[src$="#gh-dark-mode-only"] {
display: block;
}

html:is(.coal, .navy, .ayu) .chart-src img[src$="#gh-light-mode-only"] {
display: none;
}
}

/* Without JavaScript, mdBook darkens the page by prefers-color-scheme alone. */
@media screen and (prefers-color-scheme: dark) {
html:not(.js) .chart-src img[src$="#gh-dark-mode-only"] {
display: block;
}

html:not(.js) .chart-src img[src$="#gh-light-mode-only"] {
display: none;
}
}

@media print {
.chart-src {
break-inside: avoid;
}
}
Loading