Skip to main content

TornadoCash Demixer

DOI PyPI

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' Withdrawal events 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 at disc >= 0.5 in 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 signal root_excluded (or is listed as dropped after recount if it loses its count match); one whose notes were only partly in the tree carries root_partial and 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 shows FIFO 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-tx fixes 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 adds flask.
  • 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_blocked error (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 no proxy module (Blockscout), the client reads the head block from Blockscout's block module and falls back to the network's JSON-RPC node.
  • The Tornado proxy 0x0D5550d5...9b17 is 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_url in networks.csv, getLogs falls back to JSON-RPC eth_getLogs when 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 from eth_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-wait bounds 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.

demix HTML report with an evidence timeline open 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.

Ronin exploiter in characterize 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.

Wintermute attacker in characterize 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.

Beanstalk attacker in demix 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.

KuCoin depositor in demix 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.

KuCoin case overview diagram in the HTML report "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:

Placebo check in the KuCoin verdict card 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

Harmony exit group from one known exit 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

Harmony depositors linked by shared funders 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

Three-hop trace from a Harmony exit 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 is paid_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_ambiguous record in the incomplete notice and lookup_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 in rpc_url.
  • Leads, not proof. The weights and MIN_COUNT_DISCRIMINATION = 0.5 are 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 with tools/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 moderate or strong band, and strong needs 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, moderate within 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; strong stayed 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-window trades 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 moderate or strong one. 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. cluster follows one hop only, and trace follows 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.
  • characterize counts 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.

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.24279580 is the version DOI of release 2.23.0. Cite the version DOI with the version number when a result depends on one release.

License

MIT, see LICENSE.

Metadata

Release files for tornado-demix 2.23.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for tornado-demix 2.23.1
File Size Uploaded Provenance Actions
tornado_demix-2.23.1.tar.gz 715.1 kB With provenance Details for tornado_demix-2.23.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for tornado-demix 2.23.1
File Interpreter ABI Platform Actions
tornado_demix-2.23.1-py3-none-any.whl Python 3 none any Details for tornado_demix-2.23.1-py3-none-any.whl

Total release size: 1.1 MB

Release files / tornado_demix-2.23.1.tar.gz

Download URL tornado_demix-2.23.1.tar.gz
Size 715.1 kB
Tags Source
SHA-256 checksum
How to use checksums
89bf0469a4256845158b1474ff24d9a060bdbd5e030364299890946b55bb1285
BLAKE2b-256 checksum
How to use checksums
32de9afe03f4ba5c1b044ec0a849067395ebfaeb53b84d4bc20343524c7081d1
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.

Transparency log

Release files / tornado_demix-2.23.1-py3-none-any.whl

Download URL tornado_demix-2.23.1-py3-none-any.whl
Size 373.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
c08e9222ccdf19bbbfcc2a52217344deb4fdd11eb52cd5c41f5712a2c2b8bc6f
BLAKE2b-256 checksum
How to use checksums
4f2a2513d0ab56ca29178a90175848bd98ab72ca804ed62834a1430c9fe8d5c2
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.

Transparency log

Security for tornado-demix 2.23.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for tornado_demix-2.23.1.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page