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.
@@ -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,6 @@
1
+ """Enable ``python -m tornado_demix ...``."""
2
+
3
+ from .cli import main
4
+
5
+ if __name__ == "__main__":
6
+ main()
@@ -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
+ )