tornado-demix 2.13.0__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- tornado_demix/__init__.py +25 -0
- tornado_demix/__main__.py +6 -0
- tornado_demix/attribution.py +113 -0
- tornado_demix/characterize.py +165 -0
- tornado_demix/cli.py +698 -0
- tornado_demix/cluster.py +243 -0
- tornado_demix/config.py +165 -0
- tornado_demix/constants.py +37 -0
- tornado_demix/data/networks.csv +56 -0
- tornado_demix/demix.py +770 -0
- tornado_demix/errors.py +39 -0
- tornado_demix/etherscan.py +525 -0
- tornado_demix/events.py +101 -0
- tornado_demix/graph.py +121 -0
- tornado_demix/groups.py +98 -0
- tornado_demix/heuristics.py +603 -0
- tornado_demix/multi.py +356 -0
- tornado_demix/networks.py +343 -0
- tornado_demix/placebo.py +163 -0
- tornado_demix/pools.py +94 -0
- tornado_demix/relayer.py +150 -0
- tornado_demix/report.py +38 -0
- tornado_demix/report_csv.py +488 -0
- tornado_demix/report_html.py +1447 -0
- tornado_demix/report_json.py +107 -0
- tornado_demix/rpc.py +182 -0
- tornado_demix/trace.py +191 -0
- tornado_demix-2.13.0.dist-info/METADATA +460 -0
- tornado_demix-2.13.0.dist-info/RECORD +33 -0
- tornado_demix-2.13.0.dist-info/WHEEL +5 -0
- tornado_demix-2.13.0.dist-info/entry_points.txt +2 -0
- tornado_demix-2.13.0.dist-info/licenses/LICENSE +21 -0
- tornado_demix-2.13.0.dist-info/top_level.txt +1 -0
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
"""tornado_demix - Tornado.Cash demixing toolkit.
|
|
2
|
+
|
|
3
|
+
Public API:
|
|
4
|
+
from tornado_demix import EtherscanClient, run_demix, correlate, trace_wallet
|
|
5
|
+
from tornado_demix import Pool, load_networks
|
|
6
|
+
"""
|
|
7
|
+
|
|
8
|
+
from .cluster import trace_wallet
|
|
9
|
+
from .demix import run_demix
|
|
10
|
+
from .etherscan import EtherscanClient
|
|
11
|
+
from .multi import correlate
|
|
12
|
+
from .networks import get_network, load_networks
|
|
13
|
+
from .pools import Pool
|
|
14
|
+
|
|
15
|
+
__version__ = "2.13.0"
|
|
16
|
+
__all__ = [
|
|
17
|
+
"EtherscanClient",
|
|
18
|
+
"run_demix",
|
|
19
|
+
"correlate",
|
|
20
|
+
"trace_wallet",
|
|
21
|
+
"Pool",
|
|
22
|
+
"load_networks",
|
|
23
|
+
"get_network",
|
|
24
|
+
"__version__",
|
|
25
|
+
]
|
|
@@ -0,0 +1,113 @@
|
|
|
1
|
+
"""Address attribution: label known addresses (exchanges, mixers, sanctioned...).
|
|
2
|
+
|
|
3
|
+
A candidate or a next hop is more actionable once named. This module loads a
|
|
4
|
+
per-network attribution table (the aggregated public dataset at
|
|
5
|
+
``prettydeath/wallet-attribution``, one CSV per chain) and looks addresses up in
|
|
6
|
+
it, turning "high-activity service, trace boundary" into "Tornado.Cash: Router
|
|
7
|
+
(mixer)".
|
|
8
|
+
|
|
9
|
+
The dataset is large (megabytes per chain) and lives outside this package, so it
|
|
10
|
+
is never bundled. Point the tool at a checkout of it with the
|
|
11
|
+
``TORNADO_DEMIX_ATTRIBUTION`` environment variable (or ``--attribution-dir``),
|
|
12
|
+
set to the directory holding ``<network>.csv`` files. Without it, lookups return
|
|
13
|
+
nothing and every caller degrades to unlabelled output; the feature is additive.
|
|
14
|
+
|
|
15
|
+
Columns read: ``address,entity,label,category,source,confidence``; others are ignored.
|
|
16
|
+
"""
|
|
17
|
+
|
|
18
|
+
from __future__ import annotations
|
|
19
|
+
|
|
20
|
+
import csv
|
|
21
|
+
import os
|
|
22
|
+
|
|
23
|
+
from . import config
|
|
24
|
+
|
|
25
|
+
ATTRIBUTION_ENV = "TORNADO_DEMIX_ATTRIBUTION"
|
|
26
|
+
|
|
27
|
+
# Keyed by (path, mtime): the web UI must not re-read a multi-megabyte file on
|
|
28
|
+
# every request, but should pick up an updated one.
|
|
29
|
+
_CACHE = {}
|
|
30
|
+
|
|
31
|
+
|
|
32
|
+
def attribution_file(network_name: str, directory: str | None = None) -> str | None:
|
|
33
|
+
"""Resolve the attribution CSV for ``network_name``, or None.
|
|
34
|
+
|
|
35
|
+
An explicit ``directory`` scopes the search: the file must live there or
|
|
36
|
+
nothing is loaded. It never falls through to another source, so a label the
|
|
37
|
+
report calls authoritative comes from the place the caller named, not from a
|
|
38
|
+
different table (mirrors the config-dir scoping rule).
|
|
39
|
+
|
|
40
|
+
Without an explicit directory, ``TORNADO_DEMIX_ATTRIBUTION`` is tried, then
|
|
41
|
+
an ``attribution/`` sub-directory of each config dir. The file is named
|
|
42
|
+
``<network>.csv`` (matching the wallet-attribution layout).
|
|
43
|
+
"""
|
|
44
|
+
# A network name is a bare slug; refuse anything that could leave the directory.
|
|
45
|
+
if os.sep in network_name or (os.altsep and os.altsep in network_name):
|
|
46
|
+
return None
|
|
47
|
+
name = "{}.csv".format(network_name)
|
|
48
|
+
if directory:
|
|
49
|
+
candidate = os.path.join(directory, name)
|
|
50
|
+
return candidate if os.path.exists(candidate) else None
|
|
51
|
+
roots = []
|
|
52
|
+
env_dir = os.environ.get(ATTRIBUTION_ENV, "").strip()
|
|
53
|
+
if env_dir:
|
|
54
|
+
roots.append(env_dir)
|
|
55
|
+
for cfg in config.config_dirs():
|
|
56
|
+
roots.append(os.path.join(cfg, "attribution"))
|
|
57
|
+
for root in roots:
|
|
58
|
+
candidate = os.path.join(root, name)
|
|
59
|
+
if os.path.exists(candidate):
|
|
60
|
+
return candidate
|
|
61
|
+
return None
|
|
62
|
+
|
|
63
|
+
|
|
64
|
+
def load_attribution(network_name: str, directory: str | None = None) -> dict[str, dict]:
|
|
65
|
+
"""Return ``{address_lower: label_dict}`` for ``network_name``.
|
|
66
|
+
|
|
67
|
+
``label_dict`` has entity, label, category, source and confidence. Returns an
|
|
68
|
+
empty dict when no dataset is configured or the file is absent, so callers
|
|
69
|
+
need no special-casing. Result is cached by path + mtime.
|
|
70
|
+
"""
|
|
71
|
+
path = attribution_file(network_name, directory)
|
|
72
|
+
if not path:
|
|
73
|
+
return {}
|
|
74
|
+
try:
|
|
75
|
+
mtime = os.path.getmtime(path)
|
|
76
|
+
except OSError:
|
|
77
|
+
return {}
|
|
78
|
+
key = (path, mtime)
|
|
79
|
+
cached = _CACHE.get(key)
|
|
80
|
+
if cached is not None:
|
|
81
|
+
return cached
|
|
82
|
+
|
|
83
|
+
labels = {}
|
|
84
|
+
with open(path, newline="", encoding="utf-8-sig") as fh:
|
|
85
|
+
for row in csv.DictReader(fh):
|
|
86
|
+
addr = (row.get("address") or "").strip().lower()
|
|
87
|
+
if not addr:
|
|
88
|
+
continue
|
|
89
|
+
labels[addr] = {
|
|
90
|
+
"entity": (row.get("entity") or "").strip(),
|
|
91
|
+
"label": (row.get("label") or "").strip(),
|
|
92
|
+
"category": (row.get("category") or "").strip(),
|
|
93
|
+
"source": (row.get("source") or "").strip(),
|
|
94
|
+
"confidence": (row.get("confidence") or "").strip(),
|
|
95
|
+
}
|
|
96
|
+
_CACHE[key] = labels
|
|
97
|
+
return labels
|
|
98
|
+
|
|
99
|
+
|
|
100
|
+
def label_of(labels: dict[str, dict] | None, address: str | None) -> dict | None:
|
|
101
|
+
"""Return the label dict for ``address`` (case-insensitive), or None."""
|
|
102
|
+
if not labels or not address:
|
|
103
|
+
return None
|
|
104
|
+
return labels.get(address.lower())
|
|
105
|
+
|
|
106
|
+
|
|
107
|
+
def format_label(entry: dict | None) -> str:
|
|
108
|
+
"""One-line human form: 'Tornado.Cash: Router (mixer)', or '' if none."""
|
|
109
|
+
if not entry:
|
|
110
|
+
return ""
|
|
111
|
+
name = entry.get("label") or entry.get("entity") or "labelled"
|
|
112
|
+
category = entry.get("category")
|
|
113
|
+
return "{} ({})".format(name, category) if category else name
|
|
@@ -0,0 +1,165 @@
|
|
|
1
|
+
"""Recipient-side analysis: characterise an exit-candidate address.
|
|
2
|
+
|
|
3
|
+
The demix and multi analyses are depositor-centric: they surface a recipient
|
|
4
|
+
that looks like an exit. This module answers the next question, what that address
|
|
5
|
+
actually is. It pulls the candidate's own on-chain history and reports:
|
|
6
|
+
|
|
7
|
+
* activity level (normal / internal tx counts): a busy address is a service or
|
|
8
|
+
aggregator, not a personal wallet;
|
|
9
|
+
* Tornado-pool inflows: every withdrawal it received from a pool this network
|
|
10
|
+
knows, with timing and pool, so a busy recipient that collects notes from
|
|
11
|
+
many pools (including pools the subject never used) shows up as a shared
|
|
12
|
+
aggregator rather than a private exit;
|
|
13
|
+
* dominant next hops: where its funds flow, extending the trace one layer.
|
|
14
|
+
|
|
15
|
+
A classification is derived from those, with the reasoning stated, so an
|
|
16
|
+
aggregator that co-mingles unrelated withdrawals is labelled as such rather than
|
|
17
|
+
presented as one depositor's private exit.
|
|
18
|
+
|
|
19
|
+
Native (ETH-like) pools only: a pool withdrawal reaches the recipient as an
|
|
20
|
+
internal transfer from the pool contract, which ``internal_txs`` returns. ERC-20
|
|
21
|
+
pool withdrawals are token transfers and are out of scope for the inflow list.
|
|
22
|
+
"""
|
|
23
|
+
|
|
24
|
+
# Classification thresholds (judgement calls).
|
|
25
|
+
SERVICE_MIN_TXS = 500 # above this an address is a service/exchange, not personal
|
|
26
|
+
AGGREGATOR_MIN_POOLS = 3 # draws from this many distinct pools -> aggregator
|
|
27
|
+
AGGREGATOR_MIN_INFLOWS = 10 # this many pool withdrawals -> aggregator
|
|
28
|
+
DISPOSABLE_HOURS = 24 # history before the first inflow of a disposable outlet
|
|
29
|
+
|
|
30
|
+
# The pool also pays the relayer's fee as a separate internal transfer. Only a
|
|
31
|
+
# transfer of at least this fraction of the denomination counts as a received
|
|
32
|
+
# note, so a relayer's collected fees do not look like withdrawals.
|
|
33
|
+
INFLOW_MIN_FRACTION = 0.5
|
|
34
|
+
|
|
35
|
+
|
|
36
|
+
def _to_int(value, default=0):
|
|
37
|
+
try:
|
|
38
|
+
return int(value)
|
|
39
|
+
except (TypeError, ValueError):
|
|
40
|
+
return default
|
|
41
|
+
|
|
42
|
+
|
|
43
|
+
def characterize_address(client, address, network, next_hop_limit=8, labels=None):
|
|
44
|
+
"""Return a structured characterisation of ``address`` on ``network``.
|
|
45
|
+
|
|
46
|
+
Keys: address, label, normal_txs, internal_txs, first_activity_ts,
|
|
47
|
+
last_activity_ts, pool_inflows (list of {pool_key, asset, ts, value, tx_hash,
|
|
48
|
+
pool_address}), inflow_totals ({asset: summed value}), distinct_pools (sorted
|
|
49
|
+
keys), top_next_hops (list of {address, count, total_value, label}),
|
|
50
|
+
classification and classification_reason.
|
|
51
|
+
|
|
52
|
+
``labels`` is an optional ``{address_lower: label_dict}`` map (see
|
|
53
|
+
:func:`tornado_demix.attribution.load_attribution`); when given, the subject
|
|
54
|
+
and every next hop are annotated with their known attribution.
|
|
55
|
+
"""
|
|
56
|
+
labels = labels or {}
|
|
57
|
+
address = address.lower()
|
|
58
|
+
native_pools = {p.address.lower(): p for p in network.pools if p.is_native}
|
|
59
|
+
|
|
60
|
+
normal = client.outgoing_txs(address) or []
|
|
61
|
+
internal = client.internal_txs(address) or []
|
|
62
|
+
|
|
63
|
+
all_ts = [_to_int(t.get("timeStamp")) for t in (normal + internal) if t.get("timeStamp")]
|
|
64
|
+
first_ts = min(all_ts) if all_ts else None
|
|
65
|
+
last_ts = max(all_ts) if all_ts else None
|
|
66
|
+
|
|
67
|
+
# Tornado-pool inflows: internal transfers from a known pool contract to us.
|
|
68
|
+
pool_inflows = []
|
|
69
|
+
inflow_totals = {}
|
|
70
|
+
distinct = set()
|
|
71
|
+
for t in internal:
|
|
72
|
+
src = (t.get("from") or "").lower()
|
|
73
|
+
dst = (t.get("to") or "").lower()
|
|
74
|
+
pool = native_pools.get(src)
|
|
75
|
+
if pool is None or dst != address:
|
|
76
|
+
continue
|
|
77
|
+
value = _to_int(t.get("value")) / (10**pool.decimals)
|
|
78
|
+
if value < pool.denom * INFLOW_MIN_FRACTION:
|
|
79
|
+
continue
|
|
80
|
+
pool_inflows.append(
|
|
81
|
+
{
|
|
82
|
+
"pool_key": pool.key,
|
|
83
|
+
"asset": pool.asset,
|
|
84
|
+
"ts": _to_int(t.get("timeStamp")),
|
|
85
|
+
"value": round(value, 6),
|
|
86
|
+
"tx_hash": t.get("hash"),
|
|
87
|
+
"pool_address": pool.address,
|
|
88
|
+
}
|
|
89
|
+
)
|
|
90
|
+
inflow_totals[pool.asset] = round(inflow_totals.get(pool.asset, 0.0) + value, 6)
|
|
91
|
+
distinct.add(pool.key)
|
|
92
|
+
pool_inflows.sort(key=lambda r: r["ts"])
|
|
93
|
+
|
|
94
|
+
# Next hops: normal transactions sent by this address.
|
|
95
|
+
hop_count, hop_value = {}, {}
|
|
96
|
+
for t in normal:
|
|
97
|
+
if (t.get("from") or "").lower() != address:
|
|
98
|
+
continue
|
|
99
|
+
dst = (t.get("to") or "").lower()
|
|
100
|
+
if not dst:
|
|
101
|
+
continue # contract creation, no destination
|
|
102
|
+
hop_count[dst] = hop_count.get(dst, 0) + 1
|
|
103
|
+
hop_value[dst] = hop_value.get(dst, 0) + _to_int(t.get("value"))
|
|
104
|
+
top_next_hops = [
|
|
105
|
+
{
|
|
106
|
+
"address": dst,
|
|
107
|
+
"count": n,
|
|
108
|
+
"total_value": round(hop_value[dst] / 1e18, 6),
|
|
109
|
+
"kind": "transfer" if hop_value[dst] else "call",
|
|
110
|
+
"label": labels.get(dst),
|
|
111
|
+
}
|
|
112
|
+
for dst, n in sorted(hop_count.items(), key=lambda kv: (-kv[1], kv[0]))
|
|
113
|
+
][:next_hop_limit]
|
|
114
|
+
|
|
115
|
+
classification, reason = _classify(len(normal), len(pool_inflows), len(distinct))
|
|
116
|
+
# A disposable outlet: no more than a day of history before the first inflow.
|
|
117
|
+
disposable = bool(
|
|
118
|
+
pool_inflows and first_ts and pool_inflows[0]["ts"] - first_ts <= DISPOSABLE_HOURS * 3600
|
|
119
|
+
)
|
|
120
|
+
|
|
121
|
+
return {
|
|
122
|
+
"address": address,
|
|
123
|
+
"label": labels.get(address),
|
|
124
|
+
"normal_txs": len(normal),
|
|
125
|
+
"internal_txs": len(internal),
|
|
126
|
+
"first_activity_ts": first_ts,
|
|
127
|
+
"last_activity_ts": last_ts,
|
|
128
|
+
"pool_inflows": pool_inflows,
|
|
129
|
+
"inflow_totals": inflow_totals,
|
|
130
|
+
"distinct_pools": sorted(distinct),
|
|
131
|
+
"top_next_hops": top_next_hops,
|
|
132
|
+
"classification": classification,
|
|
133
|
+
"classification_reason": reason,
|
|
134
|
+
"disposable": disposable,
|
|
135
|
+
}
|
|
136
|
+
|
|
137
|
+
|
|
138
|
+
def _classify(n_normal, n_inflows, n_pools):
|
|
139
|
+
"""Classify an address from its activity and pool-inflow diversity."""
|
|
140
|
+
if n_normal >= SERVICE_MIN_TXS:
|
|
141
|
+
return (
|
|
142
|
+
"high-activity service",
|
|
143
|
+
"{} normal transactions - a service or exchange address, not a personal exit".format(
|
|
144
|
+
n_normal
|
|
145
|
+
),
|
|
146
|
+
)
|
|
147
|
+
if n_pools >= AGGREGATOR_MIN_POOLS or n_inflows >= AGGREGATOR_MIN_INFLOWS:
|
|
148
|
+
return (
|
|
149
|
+
"aggregator",
|
|
150
|
+
"collects {} pool withdrawal(s) across {} distinct pool(s) - a "
|
|
151
|
+
"shared aggregation point, so co-mingling with unrelated "
|
|
152
|
+
"withdrawals is likely and it is not one depositor's private "
|
|
153
|
+
"exit".format(n_inflows, n_pools),
|
|
154
|
+
)
|
|
155
|
+
if n_inflows == 0:
|
|
156
|
+
return (
|
|
157
|
+
"no pool inflows",
|
|
158
|
+
"no withdrawals from a known pool of this network were found - not "
|
|
159
|
+
"a Tornado exit on the pools analysed (ERC-20 pools are out of scope)",
|
|
160
|
+
)
|
|
161
|
+
return (
|
|
162
|
+
"possible personal exit",
|
|
163
|
+
"{} pool withdrawal(s) across {} pool(s) with low overall activity - "
|
|
164
|
+
"consistent with a personal exit, worth corroborating".format(n_inflows, n_pools),
|
|
165
|
+
)
|