TornadoCash Demixer¶
Transaction-linking heuristics for Tornado Cash deposits, using only public on-chain data.
The toolkit ranks candidate withdrawal addresses for a depositor wallet and reports
each candidate with an evidence band and the evidence behind it. A band needs a
lead signal that stood above chance on real depositors: a linked address (a direct
counterparty whose first withdrawal came within 72 hours of the deposit) or an
early multi-pool profile match; two different lead-signal families (their independence is not
established) make a band strong. Amount+timing and gas-price matches turn up as
often by chance as for real exits, so they are shown as context and never raise
a band. It also groups exits paid out together, groups wallets of one operator
by shared candidates and follows withdrawn funds forward.
Output is a set of leads for further investigation, not proof. Tornado Cash breaks the deposit-withdrawal link cryptographically; the tool looks for behavioural traces users leave around it.
What it does¶
- Finds a wallet's deposits into the 56 registered pools on 8 EVM networks (native transfers, internal transfers from contract wallets, ERC-20 transfers, direct or through a router).
- Groups deposits into vouchers (one pool, one session,
--gap-hours, default 24) and gives each voucher its own withdrawal search window. - Reads the pools'
Withdrawalevents in those windows and counts how many withdrawals each recipient received. A recipient that received exactly N withdrawals matches a voucher of N notes. - Scores every recipient: a count match weighted by how much of the recipient
field it eliminates (
disc; counted only atdisc >= 0.5in a field of at least 5 recipients), self-relayed withdrawals, reuse of a deposit gas price (only on withdrawals the user sent, and only in blocks without an EIP-1559 base fee), direct transactions with the depositor (not counted when the counterparty is a contract; a lead only when the recipient's first withdrawal came within 72 hours of the last deposit, otherwise shown as a late direct link, context), and an early multi-pool profile: a recipient that received the wallet's full note profile over two or more pools (10+ notes) within 72 hours of the last deposit in each pool. - Labels each listed deposit address as an exchange deposit, a service deposit, an operator-run forwarder or an ERC-4337 smart account; only the exchange kind can link two addresses, and it is context only.
- Reports a band per candidate:
strong(lead signals from two different families, independence not established: early direct link and early multi-pool profile),moderate(a lead signal from one source),weak(amount+timing, gas price and/or context-only signals, which never raise the band — chance-level on real depositors, see the placebo test in EVALUATION.md for details), with the evidence behind it: every family, whether it holds, and the numbers (share of the recipient field with the same count,disc, gas price). Candidates are ordered by band, then by an uncalibrated noisy-OR score taken across evidence families (within a family only the strongest signal counts). Reports state the analysis parameters and the block ranges read. - Marks the top candidates that had at most a day of history before their first withdrawal (fresh, disposable exits; shown as context, never scored).
- Groups exits withdrawn together in repeated bursts, the payout rhythm of an
operator that pooled several deposits; a group is listed when a corroborated
candidate or an exit you already know (
--known-exit) anchors it. - Finds the depositor's exchange deposit addresses and flags a recipient that
sent funds to the same one (
shared_deposit). Since 2.21 this is context only: it is shown in the evidence but has no weight and never raises the band (a post-hoc change, decided after the second hold-out and not tested on new data). On 1,000 random depositors it gave 27 real-window against 4 decoy hits when the deposit address swept to labelled exchange wallets (rule 2.17 sample; 2.23 re-run: 55 against 16), but in the second hold-out it was not above chance at 30 days (Ethereum 18 target against 30 decoy leads, R 1.77, interval 0.16-3.91; Polygon 23 against 13, R 0.58, 0.00-3.16); at 72 hours it was 14 against 2 and 23 against 0 (2.23 re-run: 56 / 35 and 58 / 8 at 30 days, 46 / 3 and 45 / 1 at 72 hours). The decoy leads came from deposit addresses with many senders, which are shared, not per customer. - Marks a linked exit that withdrew within 72 hours of the deposit (early exit).
Since 2.17 a direct link is a lead only then: on 302 random Ethereum depositors
a direct link first withdrawn within 72 hours was a lead 26 times in real
windows against once in decoy windows, a later one 8 against 13, chance level (2.23 re-run: early 11 / 1, late 6 / 11 on the 302 depositors; see Re-run on 2.23.0).
A later direct link is listed as context and never raises the band or the
score. Since 2.19 a withdrawal sent by
the depositor's side (
linked_sender) is context too: it did not separate from chance in any placebo sample. Since 2.21 so is a shared exchange deposit address (see above). Since 2.23 a direct link counts only when its transaction moved real value (at least a per-network dust floor, or a listed real token) before the first withdrawal to that address and the address is known not to be a contract; zero-value, dust, unlisted-token and post-withdrawal links are context, and the evidence shows each link's value, direction, block, time and position against the withdrawal. - Optionally excludes withdrawals by their Merkle root (
--root-check, or the "Merkle-root check" box in the web UI; exploratory, off by default). A withdrawal proof names the root it was built against; if that root held none of the depositor's notes in the pool the withdrawal cannot be theirs. A candidate with every withdrawal excluded leaves the ranking and is listed as "excluded by Merkle root"; one with some withdrawals removed is recounted and carries the context signalroot_excluded(or is listed as dropped after recount if it loses its count match); one whose notes were only partly in the tree carriesroot_partialand nothing is removed. It is not a lead and is not scored. It needs one transaction lookup per candidate withdrawal (at most 200) and a per-pool root index (about 30 minutes to build for a large pool, then cached). See METHODOLOGY.md section 4c and the measurement in EVALUATION.md. - Optionally runs a placebo check (
--placebo, or the web UI option): the same analysis on a decoy window that ends before the wallet's first deposit, so the report shows how many leads the same rule finds in a window before the deposits (a decoy rate; that window may hold the depositor's own earlier activity, so it is not a false-discovery rate). - Opens the HTML report with a case overview and a flow diagram: depositor, pools, candidate exits coloured by band.
- For several wallets: shared candidates, denomination-profile matches, cross-wallet consolidators graded against the window-overlap artefact, deposit synchronicity, shared private funders, and operator clusters (union-find on discriminating edges only).
- Traces split exits one hop forward to a common collection address (
cluster). - Follows withdrawn funds forward over several hops with FIFO attribution and
DEX-swap resolution, up to a labelled service (
trace); each edge showsFIFO amount [lower - upper], the share the traced funds can have under any ordering; every address has one ledger, so a transfer reached by several branches is attributed once, and FIFO starts at the traced arrival. Bridge deposits are decoded and tied to the traced transfer; which bridges are followed to the other side and which are only named is listed under Limits and in the methodology's bridge table;--arrival-txfixes the transaction that brought the start amount, which narrows the bounds. - Characterises an exit candidate: activity, pool inflows, next hops, a disposable
flag, optional address labels and the deposit-address check of each listed address
(
characterize). - Checks whether one address behaves like a deposit address: exchange, service or
deposit-like (unlabelled sweep target), forwarder or smart account (
classify-address).
The method, thresholds and the reasoning behind them are in docs/METHODOLOGY.md.
Components¶
| Module | Role |
|---|---|
tornado_demix/demix.py |
deposit detection, vouchers, search windows, withdrawal counting |
tornado_demix/heuristics.py |
signals, count_discrimination, noisy-OR score, bands |
tornado_demix/multi.py, graph.py |
multi-wallet correlation, consolidator grading, clustering |
tornado_demix/cluster.py |
one-hop tracing of split exits, on-disk cache |
tornado_demix/groups.py |
exit groups from joint withdrawal bursts |
tornado_demix/trace.py |
multi-hop FIFO tracing of withdrawn funds with swap resolution |
tornado_demix/characterize.py, attribution.py |
recipient-side analysis, address labels |
tornado_demix/etherscan.py, rpc.py, events.py |
explorer client, JSON-RPC probes, event decoding |
tornado_demix/networks.py, pools.py, data/networks.csv |
verified pool registry |
tornado_demix/report.py (report_csv, report_html, report_json) |
CSV, self-contained HTML and JSON reports |
tornado_demix/cli.py, webui/app.py |
command line and local Flask UI over the same functions |
tools/verify_pools.py |
on-chain verification of registry entries |
tools/calibrate.py |
precision/recall against confirmed cases (needs private data) |
tools/sensitivity.py |
ranking stability of saved results under perturbed weights |
tools/simulate.py |
synthetic benchmark: ablation, negative controls, counter-measures — results |
tools/real_cases.py |
the method on two public laundering cases (KuCoin, Harmony) |
tools/ens_labels.py, tools/evaluate_labels.py |
an ENS-labelled set of depositor/exit pairs and the evaluation on it — results |
tools/wang_baseline.py |
the ENS set scored under the Wang et al. (2023) protocol, with their H2/H3/H5 re-implemented |
tools/placebo_eval.py, tools/placebo_windows.py |
placebo (target-decoy) test on random real depositors, per evidence family and exit window — results |
tools/placebo_dar.py, tools/placebo_dar_universe.py |
placebo test of the shared exchange-deposit-address signal on the cached runs and on 1,000 depositors read from the ENS universe |
tools/root_ceiling.py, tools/root_exclusion_eval.py |
upper bound and placebo measurement of the Merkle-root exclusion on the cached runs |
tools/review_sample.py |
a blinded manual-review sheet of leads and hidden controls, and its scoring |
Requirements¶
- Python 3.9 or newer. Runtime dependency:
requests. The web UI addsflask. - An Etherscan V2 API key. On the free plan it covers Ethereum, Polygon and
Arbitrum; Optimism is served by Blockscout and Avalanche by Routescan, neither
needing a key. Base goes through Etherscan when the key's plan serves it and
otherwise switches to keyless Blockscout, which sits behind Cloudflare and may
answer with a challenge page: the run then stops with a
provider_blockederror (the challenge is never bypassed). Base needs a paid Etherscan plan or an RPC with archive access; the Blockscout fallback may be blocked. BNB Smart Chain and Gnosis need a paid Etherscan plan: the free tier does not serve them. Where a provider has noproxymodule (Blockscout), the client reads the head block from Blockscout'sblockmodule and falls back to the network's JSON-RPC node. - The Tornado proxy
0x0D5550d5...9b17is registered for Polygon, Avalanche, Arbitrum, Optimism, Gnosis and Base, so deposits made through it are detected there (before, an Arbitrum wallet with 4 proxy deposits showed 0). BNB Smart Chain has none: no deposit could be sampled with free data sources.
Installation¶
From PyPI (the tornado-demix command and the pool registry):
python -m pip install tornado-demix
The web UI and the evaluation tools live in the repository. From a checkout:
python -m pip install . # core: the tornado-demix command and the pool registry
python -m pip install ".[web]" # plus Flask; run the UI from a checkout
python -m pip install -e ".[dev]" # for development: tests and ruff
python -m pip install -e ".[eval]" # plus numpy, scipy, statsmodels: the evaluation tools
Dependencies and their version bounds are declared in pyproject.toml.
Configuration¶
Copy config/api.csv.example to config/api.csv and put your key in it, or set
ETHERSCAN_API_KEY:
service,api_key
etherscan,YOUR_KEY
Config files are looked up in $TORNADO_DEMIX_CONFIG (only there, when set),
then ./config/, then the repository's config/. One directory per case keeps
case inputs apart. config/wallets.csv (column address) can replace addresses
on the command line. config/networks.csv, if present, overrides the bundled
registry.
Labels (attribution set)¶
The shared exchange deposit address signal is context only since 2.21, labels or not. Exchange labels still decide which deposit addresses are listed as swept to a labelled exchange: with them, the placebo test gave 27 real-window against 4 decoy hits on 1,000 depositors (before the second hold-out; 2.23 re-run: 55 against 16); without them, deposit addresses found by activity alone were at chance (16 against 12; in the 2.23 re-run 67 against 35, R 0.56, 0.32-0.93, a post-hoc result) and are shown as context only. To load the public label set (the fetch of 2026-11-14 returned 105,267 Ethereum addresses, 32,943 of them exchange labels, and 131,117 rows on the eight networks; the counts move as the upstream sources do):
tornado-demix labels fetch # all 8 networks
tornado-demix labels fetch --network bsc # one network
tornado-demix labels status # what is loaded
Files go to $TORNADO_DEMIX_ATTRIBUTION if set, else config/attribution/
(--dir overrides), one <network>.csv per chain; that is where lookups read
them. The web UI shows the same download as a button when a demix result has no
labels for its network. Nothing is downloaded unless you run the command, and the
data is not bundled: it is third-party, and each upstream source keeps its own
licence (see below).
Address labels (optional)¶
Opt-in extra source: tornado-demix labels blockscout --network polygon --addresses-file F caches Blockscout metadata tags (needs the labels extra), and --labels-blockscout or the web checkbox uses them; see METHODOLOGY 7a for lineage.
Labels are not bundled. The tool reads one <network>.csv per chain
(ethereum.csv, bsc.csv, ...) with an address column and optionally entity,
label, category, source, confidence, from the directory given by
--attribution-dir or TORNADO_DEMIX_ATTRIBUTION.
A ready dataset in this format is
prettydeath/wallet-attribution:
addresses of exchanges, OFAC-sanctioned entities, scams, mixers, bridges and DeFi,
covering all eight networks of this tool (labels fetch reports the row count per network).
git clone https://github.com/prettydeath/wallet-attribution
python -m tornado_demix characterize <address> --attribution-dir wallet-attribution/data
It is aggregated from public sources: the OFAC SDN address list (US government public record, via 0xB10C/ofac-sanctioned-digital-currency-addresses), dawsbot/eth-labels, tradezon/cex-list, MyEtherWallet/ethereum-lists and the proof-of-reserves wallets in DefiLlama-Adapters. The dataset's code is MIT; each label keeps the license of its upstream source, so check those before redistributing labels or using them commercially.
Labels are only displayed. They never change a score or a band, and a label is a claim by its source, not a finding of this tool.
Command line¶
# one wallet: CSV files, an HTML report and the full result as JSON
python -m tornado_demix demix 0x1234567890abcdef1234567890abcdef12345678 \
--network ethereum --out-dir out/demix --report out/demix.html --json out/demix.json
# narrow the search to 6 hours after each voucher's last deposit
python -m tornado_demix demix <wallet> --exit-window 6
# list the exit group of an exit already known from the investigation
python -m tornado_demix demix <wallet> --known-exit <exit address>
# also run the same analysis on a decoy window before the first deposit
python -m tornado_demix demix <wallet> --placebo
# a 7-day exit window, as seen in public laundering cases
python -m tornado_demix demix <wallet> --rapid
# several wallets
python -m tornado_demix multi <wallet1> <wallet2> --report out/multi.html
python -m tornado_demix multi --wallets-csv config/wallets.csv
# intermediate wallets of one actor, also treated as one depositor (conditional on that assertion)
python -m tornado_demix multi <wallet1> <wallet2> --group --json out/multi.json
# split exits, one hop forward (resumable cache in --cache-dir)
python -m tornado_demix cluster <wallet> --cache-dir .cache/case-42
# describe an exit candidate
python -m tornado_demix characterize <address> --attribution-dir path/to/labels
# is this address a deposit address (exchange / service / deposit-like), a forwarder or neither?
python -m tornado_demix classify-address <address> --network polygon --labels-blockscout --json out/c.json
# follow 10 ETH withdrawn to <address> in block 12000000 over up to 4 hops
python -m tornado_demix trace <address> --amount 10 --start-block 12000000 --report out/trace.html
Provider flags, shared by every command that reads the chain:
--max-wait SECONDS(default 120): the longest one call backs off on a transient error (rate limit, HTTP 429/5xx, timeout), with exponential waits and jitter. Permanent errors (rejected key, a chain the plan does not cover, a malformed address) fail on the first answer with a one-line message.--pause SECONDS: wait before every explorer call, for a free key shared with other programs.--http-cache DIR: keep explorer answers in DIR and reuse them. Only account and log queries that end at least 64 blocks below the chain head are stored (such rows no longer change); errors, partially indexed answers and the API key are never stored.--progress-every N(default 50): a[*]line on stderr every N explorer calls.- On a network with an
rpc_urlinnetworks.csv,getLogsfalls back to JSON-RPCeth_getLogswhen the explorer fails after its retries (for example Blockscout throttling). The node is asked in block spans that shrink when it reports a range limit; block timestamps come frometh_getBlockByNumber. A log row read from a node has no gas price, so the unique-gas-price signal has nothing to match on it; every such list is listed as a notice ("read from the RPC node") in the CLI, HTML, JSON and web output.--max-waitbounds the wall time of one call, request timeouts included.
python -m tornado_demix <command> --help lists every option. A configuration or
provider error exits with a non-zero status and a one-line message. Progress goes
to stderr; the summary to stdout.
Reading the report¶
The HTML report and the web UI share one layout. The verdict card on top answers in one sentence and counts leads, context-only and chance-level candidates and failed lookups (plus the placebo verdict and the exploratory and limitations badges). Sections follow in a fixed order: Leads (open), then Context, Chance-level candidates, Deposit addresses, Groups and clusters, Fee fingerprints, Method and limitations, Raw data (collapsed; counts in the sticky table of contents). strong: lead signals from two different families, their independence not established (an early direct link and an early multi-pool profile); moderate: one lead source. weak: no lead signal, either with a context-only signal (late direct link, withdrawal sender, shared deposit address) or on amount+timing and gas price alone, which are chance-level; the score only orders candidates within a band. Each candidate row opens an evidence timeline with full hashes; a trace ends with a totals line (end points + below threshold + failed lookups = start amount). Filters, search and copy buttons need JavaScript; without it every row is still in the page, and printing expands every section.
Web UI¶
python webui/app.py # http://127.0.0.1:5000
The form runs the same six analyses (the sixth, classify, is the deposit-address check of one address); each mode shows only its own fields, and an input error is shown next to its field. The results page is the HTML report itself (same layout, see below): for each demix candidate an Evidence timeline lists the deposits, the withdrawals and every evidence family that was checked, whether it holds, and the numbers behind it. Analysis parameters (under Method and limitations) lists the assumptions (voucher gap, window, thresholds) and the block ranges read. The HTML report, the JSON result and the CSV table can be downloaded. With JavaScript on, a run goes to a background thread and the page shows a live status (elapsed time, explorer calls, cache hits, time spent waiting on the provider); without it the request runs to completion as before. One background run goes at a time (they share the API key's rate limit). The form's Provider settings are the flags above.
For trace, enter one exit address, the amount to follow and optionally the
block the funds arrived in, an ERC-20 token and the number of hops (up to 8). The
page lists where the traced funds stop and why (labelled address, hop limit, a
contract that paid nothing back, not moved on, lookup_failed, below_threshold,
tornado_redeposit, order_unknown) and every edge with its attributed amount, swaps
included, plus the possible outflows of incomplete histories (not followed); the HTML
report, CSV and JSON can be downloaded. When a lookup failed, every analysis
shows "N lookups failed — results may be incomplete" with the list.
A demix run on the KuCoin depositor (case 4 below): one candidate row with its expanded evidence timeline (the 11 withdrawals and the counterparty link) and the list of every check that was made. The only check that holds is the withdrawal sent by the depositor's counterparty; it is context, so the candidate stays weak.
The UI binds to localhost and has no authentication (forms carry a CSRF token); see SECURITY.md.
Documented cases¶
Five public cases with an external source of truth. Each can be re-run from the addresses shown (an Etherscan API key is enough; the Ronin labels need an attribution set). The screenshots are from the HTML report; the CLI prints the same results. There is no script in the repository that regenerates the images; most show the first page of the report (verdict, four figures, the diagram of how the money moved, the address table and the checks). A new run can show slightly different counts as the chain grows and open search windows are clamped to the current block.
| # | Case | Analysis | What it shows | Source of truth |
|---|---|---|---|---|
| 1 | Ronin Bridge 2022 | characterize |
OFAC-labelled exploiter, bridge and USDC calls, 12,595 ETH to a second sanctioned address | OFAC, 14 Apr 2022 |
| 2 | Wintermute 2022 | characterize |
one 9.9435 ETH inflow from the 10 ETH pool; a disposable address | Merkle Science |
| 3 | Beanstalk 2022 | demix --exit-window 24 |
271 deposits in three hours; no candidate above weak |
Merkle Science |
| 4 | KuCoin 2020 | demix |
6 of the attacker's 35 exits in the window found through the linked withdrawal sender (context only since 2.19) | tayvano/lazarus-bluenoroff-research |
| 5 | Harmony 2022 | demix --known-exit, multi, trace |
an exit group from one known exit; 14 depositors in 5 funder clusters; a three-hop trace | tayvano/lazarus-bluenoroff-research |
Attributing the Ronin, KuCoin and Harmony thefts to Lazarus is the conclusion of government and industry investigators, not of on-chain analysis; the identity of the Wintermute and Beanstalk attackers is not established.
1. Ronin Bridge exploiter¶
python -m tornado_demix characterize 0x098B716B8Aaf21512996dC57EB0615e2383E2f96
The exploiter received nothing from a Tornado pool; characterize shows where
its funds went next. With the attribution set loaded, the address itself and the
12,595.3 ETH destination are labelled OFAC-sanctioned, and the contract calls go
to Circle: USDC and the Ronin Bridge. Without labels the same hops are shown
unlabelled.
First page of the characterize report for the Ronin exploiter: verdict "No pool inflows", the diagram of the eight next hops with USDC, the Ronin Bridge and a second exploiter address labelled, and the table ending in the 12,595.3 ETH transfer to a sanctioned address.
2. Wintermute attacker¶
python -m tornado_demix characterize 0xe74b28c2eAe8679e3cCc3a94d5d0dE83CCB84705
One inflow of 9.9435 ETH from the 10 ETH pool on the day of the attack (2022-09-20), the first activity of the address: it is flagged as disposable, the pattern of 98.6 % of laundering exits in the MixLaunder cases.
First page of the characterize report for the Wintermute attacker: one 9.9435 ETH inflow from the 10 ETH pool, verdict "Possible personal exit", the eight next hops and the checks (the address was fresh, so it is flagged disposable as context).
3. Beanstalk attacker¶
python -m tornado_demix demix 0x1c5dCdd006EA78a7E4783f9e6021C32935a10fb4 --exit-window 24
271 deposits (247 x 100, 14 x 10, 9 x 1 and 1 x 0.1 ETH) within about three
hours. With a 24-hour exit window the count match leaves one weak candidate and
nothing corroborated: a careful operator leaves no lead, and the tool says so
rather than naming an unrelated address.
First page of the demix report for the Beanstalk attacker: 271 notes, verdict "No lead", and the one candidate, a weak count match at chance level.
4. KuCoin hack (2020)¶
python -m tornado_demix demix 0x820a7a97dd146fd97f79881afdf4767624973368
The attacker called withdraw() itself from two addresses (Koh, 2020): 451
withdrawals to 36 exits. No exit received a voucher-sized count, so the count
match finds nothing. The depositor had transacted with one of the callers,
0x82e6..., so every withdrawal it sent marks its recipient (linked_sender): 6
true exits. Before 2.19 they were moderate leads; since 2.19 they are listed as
context and the band stays weak. The 30 exits of the other caller, which is not a
counterparty of the depositor, are not found; how many of them carry this
depositor's notes rather than the attacker's other deposits is unknown. The report opens with
a flow diagram from the depositor through the pool to the candidates.
First page of the demix report for a KuCoin depositor: verdict "No lead", the six addresses that received withdrawals sent by the depositor's counterparty (linked_sender), the diagram and the checks. All six are weak, context only; before 2.19 they were moderate.
"How the money moved" in the same report: the depositor, the 100 ETH pool, the counterparty (dashed) and the six addresses, each with the number of withdrawals it received.
With --placebo the same analysis also runs on a decoy window that ends a day
before the first deposit, where no withdrawal can spend this depositor's notes:
The Checks list of the same report. The Placebo line reads: six weak candidates in the real window, none in the decoy window (4.87 vs 0 per 1000 withdrawals searched); the six are context only (linked_sender), so they are not counted as leads.
5. Harmony Bridge hack (2022)¶
Investigators listed 14 depositors and 55 withdrawal addresses. The attacker pooled 857 notes of the 100 ETH pool and paid them out mostly six at a time, so the count match finds no exit and no false one. Three other analyses do.
Exit groups. Starting from one exit known from the investigation, demix
lists the recipients paid out in the same bursts:
python -m tornado_demix demix 0xe71d5fa89d1086d5c3b0ab03eeee2483d2d5ca97 \
--known-exit 0x0562ddf7ea5ab56728852eea2eacab61c4b78a1a
The verdict ("No lead" for this depositor) and the Exit groups section of the report: one group of 22 addresses, 127 notes, paid out in joint bursts and anchored by one known exit. Across all depositors, one known exit gives 23 addresses on average, 73 % of them on the investigators' list.
Shared funders. Correlating the 14 depositors links all of them through five
immediate funders, each of which was paid directly by the bridge exploiter
0x0d04...ded00; a sixth, busy funder is left out:
python -m tornado_demix multi --wallets-csv docs/cases/harmony_depositors.csv
First page of the multi report for the 14 Harmony depositors: verdict "Operator cluster" (5 clusters link 14 of 14 wallets through shared funders), the diagram of the first 8 wallets and the pool, and the checks.
Trace. From an exit, trace follows the 100 ETH it received forward:
python -m tornado_demix trace 0x04bca8fa79f36749fa605597e9c9f6788c126944 --amount 100 --max-hops 3
First page of the trace report from a Harmony exit: 100 ETH, 3 edges, one stop at the hop limit, with the flow diagram and the checks.
More public cases (2021-2025)¶
Six further incidents with named depositors and published exit lists, run with the
default settings (demix, 30-day window; multi without options). The exit lists
come from investigators who matched by timing, amount and denomination, so they are
not independent ground truth for this tool: "found" would mean agreement with their
matching, not validation. Only the Deribit depositors come from a sworn document, the
DOJ civil forfeiture complaint (D.D.C. 1:24-cv-02828). Result in short: the known
exits fall inside the searched window almost every time, but only one of them (Garden
Finance) was found, as a weak candidate at chance level. The table with the counts
is in docs/EVALUATION.md.
| Incident | Depositor(s) | Source |
|---|---|---|
| Steadefi, Aug 2023 | 0xe10d4a5bd440775226c7e1858f573e379d0aca36 |
steadefi.md; UN Panel of Experts report S/2024/215 |
| Coinshift, Aug 2023 | 0x68c4a151d436ec1c5448d225a97bd19cce4dfed0 |
coinshift.md; ZachXBT |
| Deribit, Nov 2022 | 0xb0606f433496bf66338b8ad6b6d51fc4d84a44cd, 0x3089df0e2349faea1c8ec4a08593c137da10fe2d |
DOJ complaint D.D.C. 1:24-cv-02828 (2024-10-04), quoted in deribit.md |
| CoinMetro / Coinberry / Unibright, Jan 2021 | 0x0864b5ef4d8086cd0062306f39adea5da5bd2603, 0x1031ffaf5d00c6bc1ee0978eb7ec196b1d164129 |
coinmetro.md; ZachXBT (link above) |
| bZx, Nov-Dec 2021 | 0x20d9e73aafe69a3cd66ad7477de7358d0ed44b10 |
bZx.md; ZachXBT (link above) |
| Garden Finance, Oct-Nov 2025 | 0x95f0564879d5e33000d53107adaea6809aaa3838, 0xa9a166febace09fd620a3b85cbc6d40e535fbdf1, 0x7c1cf2f256d2e83dee5ae15e7ac0f7f6197e780b |
garden-finance.md |
The method on both public cases, with the numbers behind each claim, is in
docs/EVALUATION.md; python tools/real_cases.py repeats it.
Limitations¶
- An exchange label on a sweep target names the exchange; it is not evidence of a sweep.
Since 2.23 a labelled target counts only when the address sweeps its balance there: one
transfer of at least 90 % (
LABELLED_SWEEP_SHARE) of what arrived in that asset since its previous outgoing transfer, within 30 days (LABELLED_SWEEP_SECONDS) of the latest arrival, or one that passes the 38,400 s / 0.01 ETH forwarding test, which unlabelled targets keep as their only test. An address that only paid a labelled exchange ispaid_exchange(context), not an exchange deposit address. The 90 % and 30-day values are exploratory, not measured; one such sweep is enough (no repetition is required), and the classifier's precision and recall on independently labelled addresses were not measured. - The early multi-pool profile applies only when the full 72 h after the last deposit was read (a shorter window, a cut or partly indexed pool list, or a deposit younger than 72 h leaves it off, with a note in the run summary).
- A depositor can send notes and a direct transfer to an address that never agreed to receive them (an unsolicited receipt). Since 2.23 a direct link needs real value above a per-network floor and must come strictly before the first withdrawal; that raises the cost of planting one but does not stop a depositor who sends real value before withdrawing. A band says that funds reached the address, not that its owner controls it or took part.
- A router deposit into twin pools (two pools of one denomination: Ethereum, Avalanche)
is placed by the Deposit event in its receipt. When the receipt cannot settle it, the
deposit is listed with a
pool_ambiguousrecord in the incomplete notice andlookup_errors.csv, and its withdrawals are not searched (no guess between the twins). While such a deposit exists the early multi-pool profile is not applied, and the Merkle-root check places it by its leaf in each twin or leaves those pools unchecked. - Base on the free tier has no explorer data: the keyless Blockscout fallback may be
blocked by Cloudflare (
provider_blocked). Free public JSON-RPC nodes keep recent blocks only on Arbitrum and Optimism ("Archive requests require a personal token"): the log fallback then fails loudly with "unavailable for historical blocks" instead of returning an empty history; use a paid Etherscan plan or an archive endpoint inrpc_url. - Leads, not proof. The weights and
MIN_COUNT_DISCRIMINATION = 0.5are expert judgements; the score has not been calibrated on cases with known outcomes. The band does not depend on the weights at all; they only order candidates within a band (check a saved result withtools/sensitivity.py). How each component behaves on generated data with a known answer is in docs/EVALUATION.md. - On real depositors the count match, self-relay and gas-price reuse do not beat
chance: a placebo test on 152 random Ethereum depositors found as many such
leads in decoy windows before the first deposit as in the real windows, at every
window from 6 hours to 30 days; gas-price matches were almost all on withdrawals
whose gas price a relayer chose. A linked address (a direct counterparty or a
deposit address swept to a labelled exchange; before 2.19 also a
withdrawal sent by the depositor's side) stood above chance (30 against 7 over 30 days, 19 against 1
within 72 hours, measured before 2.17; the shared deposit part did not hold up
in the second hold-out, see below). The pooled 30-day number hid that a
direct link withdrawn later than 72 hours is chance-level (8 against 13 on 302
depositors, against 26 to 1 within 72 hours; 2.23 re-run: early 11 / 1, late 6 / 11), so since 2.17 it is context; and so did a multi-pool profile of 10+ notes within 72 hours
(318 against 34 on 4,194 such depositors); only these two (an early direct link, an early multi-pool profile) make a
moderateorstrongband, andstrongneeds both. Details: EVALUATION.md - The 2.17 rule was then frozen, pre-registered and run on new depositors (591 on
Ethereum, 300 on Polygon): early direct links 84 against 2 and 59 against 1,
moderatewithin 72 hours 103 against 7 and 71 against 1, count match at chance level on both chains. A labelled shared deposit on Polygon (5 against 0) was too rare to beat chance there;strongstayed rare (3 against 0). Details: HOLDOUT_RESULTS.md - The second hold-out (2.19 rule, 599 Ethereum and 400 Polygon depositors) found a labelled shared deposit at 30 days not above chance: Ethereum 18 target against 30 decoy leads (R 1.77, 0.16-3.91), Polygon 23 against 13 (R 0.58, 0.00-3.16; rule 2.19 run, on 2.23.0 the same samples give 56 / 35 and 58 / 8, context); the early direct link held (85 against 5 and 92 against 5; 2.23 re-run: 21 / 3 and 38 / 4). Since 2.21 the shared deposit address is context only (post-hoc, untested). Details: HOLDOUT2_RESULTS.md
- On 31 depositor/exit pairs labelled through ENS (2019-2026), demix found 16 of the 21 pairs inside its window (measured before 2.17, when a direct link counted at any delay), all through a direct transaction between the two addresses, which the label sees as well; without that signal it found two (through a shared exchange deposit address, again an address link). Most labelled depositors made single-note deposits, which the count match cannot narrow. Details: EVALUATION.md
- The discrimination gate (
disc >= 0.5) cuts the count matches about twelvefold but does not remove chance ones: in the placebo test the chance share stays near 1 in every discrimination bin (717 against 591 gated in, 72 hours). A count match never raises a band. - Single-note vouchers cannot be narrowed by count: every recipient in the window has count 1.
- Busy pools and long windows produce many equal counts.
--exit-windowtrades recall for discrimination. - A careful user defeats the method: relayers, long delays, split withdrawals
to fresh addresses. The result is then "no lead", or weak leads on unrelated
addresses that happen to share the voucher count, never a
moderateorstrongone. On the public KuCoin and Harmony laundering cases the count match found no exit (every exit collected notes of several deposits); in KuCoin the linked withdrawal sender found 6 of the attacker's 35 exits in one depositor's window; since 2.19 these are context, not leads. Details: docs/EVALUATION.md - Only Tornado Cash pools in the registry are covered. Other mixers are not followed.
Bridges followed across chains: Across (V3 and current deposits; SpokePools on
Ethereum, Optimism, BNB Chain, Polygon, Arbitrum, Base and Avalanche; a deposit made
directly, through a periphery or router, after a swap, to the MulticallHandler or from
an ERC-4337 smart account), native-ETH deposits through the Arbitrum Inbox and ERC-20
deposits through the Arbitrum token gateways (followed on Arbitrum once the L2 credit
is found), and Circle CCTP burns (v1 and v2) to an EVM chain of the registry (followed
from the mint). A Mayan same-chain payout and a CoW Protocol order (tied to the
owner's trade and its payout in the settlement receipt) are followed as swaps. Named,
not followed: ZKsync deposits (Bridgehub native and ERC-20, legacy Era
requestL2Transaction) show the L2 recipient; Relay, Mayan, THORChain, Maya, Layerswap,
NEAR Intents, Unit and Hyperliquid deposits show what the chain gives (request id,
memo, destination, recipient); a CCTP burn to Solana or another non-EVM domain shows
its recipient; other listed bridges are named only. A listed swap-and-bridge router
(LI.FI, Socket, Rango, Squid) that only refunds native coin ends as bridge or swap
unknown, and bridges that are not listed end as contracts. A hop is followed only when
the decoded call is tied to the traced transfer; otherwise the branch ends with a
named state.
clusterfollows one hop only, andtracefollows funds by FIFO attribution, a convention that does not hold when an address mixes the traced funds with others. - BNB Smart Chain has no verified router in the registry, so routed deposits there are not detected.
characterizecounts inflows from native pools only.- Transactions are read as they were mined. Fee-bump and replacement transactions, private relays and MEV bundles are not covered: nothing in the data shows how a transaction was routed or ordered, so a path that went through one is not recognised as such.
- Results depend on the explorer API. Provider failures raise errors instead of returning empty results, and pools whose search window cannot be resolved are reported as not searched.
Development¶
python -m pytest -q # network access is blocked in tests
python -m pytest -m live # on-chain registry check, needs network
python -m ruff check . && python -m ruff format --check .
Weight sensitivity of saved results (no API calls):
python tools/sensitivity.py out/demix.json:<expected exit> --samples 1000 --spread 0.5
Synthetic benchmark (no API calls, about half a minute):
python tools/simulate.py --experiment all --trials 200 --seed 1
Public laundering cases (KuCoin 2020, Harmony 2022; needs an API key):
python tools/real_cases.py
requirements-lock.txt pins every dependency with hashes (generated by
uv pip compile pyproject.toml --extra web --extra dev --extra eval --python-version 3.9
--generate-hashes --universal; the layout extra needs Python 3.10 and is installed
separately); install it with
pip install --require-hashes -r requirements-lock.txt and then
pip install --no-deps -e . to reproduce a result with the same libraries.
CI runs the tests on Linux and Windows with Python 3.9 and 3.13 against the lock file, a test under a
legacy Windows codepage, the layout tests in a real browser, the linter, pip-audit on the lock file, and a wheel install check.
Legal and ethical use¶
For research, compliance and authorised investigations. Every address processed is public on-chain data, but a label or a band attached to an address is an allegation about a person. Corroborate any lead independently before it appears in a report, a referral or a freeze request, and follow the terms of service of the data providers you use.
Citation¶
Two DOIs belong to this repository and both are correct: 10.5281/zenodo.23085804 is the
concept DOI (all versions, the one in CITATION.cff and the badge), and
10.5281/zenodo.24336477 is the version DOI of release 2.23.1. Cite the version DOI with the
version number when a result depends on one release.
License¶
MIT, see LICENSE.