crypttrace 0.2.0__tar.gz → 0.4.0__tar.gz

{crypttrace-0.2.0/src/crypttrace.egg-info → crypttrace-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: crypttrace
-Version: 0.2.0
+Version: 0.4.0
 Summary: OSINT toolkit for crypto investigations: trace stolen funds across Ethereum, Bitcoin, Tron and Solana
 Author: bobslayerX
 License-Expression: MIT
@@ -216,6 +216,9 @@ crypttrace report 0xADDRESS --depth 3
 # Refresh label lists (OFAC sanctions, …)
 crypttrace update-labels
 
+# …and add OKX's ~300k signed deposit addresses (downloads ~80 MB once)
+crypttrace update-labels --okx
+
 # Launch the web UI / list chains
 crypttrace serve
 crypttrace chains
@@ -273,7 +276,9 @@ behaviour: an address forwarding most of its outgoing value to a labelled
 exchange is almost certainly a deposit address, i.e. the cash-out point where
 that exchange holds the depositor's KYC. `trace` applies the same heuristic
 automatically, turning an anonymous intermediary into "→ Binance deposit (KYC
-point)".
+point)". It works on every supported chain; on Tron and Solana, where deposits
+are usually swept as stablecoins, it checks USDT and USDC as well as the native
+coin.
 
 ### First-funder (deanonymization)
 
@@ -371,11 +376,22 @@ SDN sanctioned-address list — and merges them into the local DB in
 `~/.crypttrace/`. The curated seed wins on conflicts, so richer names survive.
 Add sources in `labels/labels.py` → `SOURCES`.
 
-Bitcoin, Tron and Solana coverage is currently Binance only: its reserve
-wallets, taken from the address list Binance publishes itself for
-proof-of-reserves. So `offramp` can flag Binance deposit addresses on those
-chains, but funds sent to other exchanges there will still show as `unknown`.
-Every label records where it came from — see `crypttrace labels audit`.
+On Bitcoin, Tron and Solana the labels cover the reserve wallets of Binance,
+OKX and HTX, plus Bybit's older 2022 list — each taken from the address list the
+exchange publishes itself for proof-of-reserves. That is what lets `offramp`
+flag deposit addresses on those chains. Funds sent to an exchange not on that
+list still show as `unknown`. Every label records where it came from — see
+`crypttrace labels audit`.
+
+**Deposit addresses, labelled outright.** OKX signs every address that holds
+customer funds — over 300,000, nearly all of them per-customer deposit addresses
+— and publishes the list with its proof of reserves. `crypttrace update-labels
+--okx` downloads the latest one into `~/.crypttrace/` (about 18 MB once
+imported). With it, funds landing on an OKX deposit address are identified the
+moment they arrive, before OKX sweeps them onward — which is when a freeze
+request still has something to freeze. Without it, `offramp` only recognises a
+deposit address after it has forwarded the money. Rows without OKX's signature
+are ignored, and every address is checked before it is stored.
 
 ### Reports
 
@@ -478,7 +494,14 @@ cases/             # worked investigations with their data
 
 ## Roadmap
 
-- Exchange/service labels for Bitcoin, Tron and Solana
+- More exchanges on Bitcoin, Tron and Solana (now: Binance, OKX, HTX, Bybit),
+  and refreshing these lists as the exchanges republish them
+- Address-poisoning detection: flag look-alike addresses (same first and last
+  characters) in a victim's history before they copy the wrong one
+- Stablecoin freeze check: whether USDT/USDC at an address is already frozen
+  by the issuer, and who to ask for a freeze
+- `report --html`: one self-contained file with the interactive graph, to
+  send to an exchange or attach to a police report
 - `report --pdf` for exchange and law-enforcement filings
 - Internal transactions (completes `funder` and contract-mediated transfers)
 - Per-mint filtering for Solana SPL tokens

{crypttrace-0.2.0 → crypttrace-0.4.0}/README.md

@@ -182,6 +182,9 @@ crypttrace report 0xADDRESS --depth 3
 # Refresh label lists (OFAC sanctions, …)
 crypttrace update-labels
 
+# …and add OKX's ~300k signed deposit addresses (downloads ~80 MB once)
+crypttrace update-labels --okx
+
 # Launch the web UI / list chains
 crypttrace serve
 crypttrace chains
@@ -239,7 +242,9 @@ behaviour: an address forwarding most of its outgoing value to a labelled
 exchange is almost certainly a deposit address, i.e. the cash-out point where
 that exchange holds the depositor's KYC. `trace` applies the same heuristic
 automatically, turning an anonymous intermediary into "→ Binance deposit (KYC
-point)".
+point)". It works on every supported chain; on Tron and Solana, where deposits
+are usually swept as stablecoins, it checks USDT and USDC as well as the native
+coin.
 
 ### First-funder (deanonymization)
 
@@ -337,11 +342,22 @@ SDN sanctioned-address list — and merges them into the local DB in
 `~/.crypttrace/`. The curated seed wins on conflicts, so richer names survive.
 Add sources in `labels/labels.py` → `SOURCES`.
 
-Bitcoin, Tron and Solana coverage is currently Binance only: its reserve
-wallets, taken from the address list Binance publishes itself for
-proof-of-reserves. So `offramp` can flag Binance deposit addresses on those
-chains, but funds sent to other exchanges there will still show as `unknown`.
-Every label records where it came from — see `crypttrace labels audit`.
+On Bitcoin, Tron and Solana the labels cover the reserve wallets of Binance,
+OKX and HTX, plus Bybit's older 2022 list — each taken from the address list the
+exchange publishes itself for proof-of-reserves. That is what lets `offramp`
+flag deposit addresses on those chains. Funds sent to an exchange not on that
+list still show as `unknown`. Every label records where it came from — see
+`crypttrace labels audit`.
+
+**Deposit addresses, labelled outright.** OKX signs every address that holds
+customer funds — over 300,000, nearly all of them per-customer deposit addresses
+— and publishes the list with its proof of reserves. `crypttrace update-labels
+--okx` downloads the latest one into `~/.crypttrace/` (about 18 MB once
+imported). With it, funds landing on an OKX deposit address are identified the
+moment they arrive, before OKX sweeps them onward — which is when a freeze
+request still has something to freeze. Without it, `offramp` only recognises a
+deposit address after it has forwarded the money. Rows without OKX's signature
+are ignored, and every address is checked before it is stored.
 
 ### Reports
 
@@ -444,7 +460,14 @@ cases/             # worked investigations with their data
 
 ## Roadmap
 
-- Exchange/service labels for Bitcoin, Tron and Solana
+- More exchanges on Bitcoin, Tron and Solana (now: Binance, OKX, HTX, Bybit),
+  and refreshing these lists as the exchanges republish them
+- Address-poisoning detection: flag look-alike addresses (same first and last
+  characters) in a victim's history before they copy the wrong one
+- Stablecoin freeze check: whether USDT/USDC at an address is already frozen
+  by the issuer, and who to ask for a freeze
+- `report --html`: one self-contained file with the interactive graph, to
+  send to an exchange or attach to a police report
 - `report --pdf` for exchange and law-enforcement filings
 - Internal transactions (completes `funder` and contract-mediated transfers)
 - Per-mint filtering for Solana SPL tokens

{crypttrace-0.2.0 → crypttrace-0.4.0}/src/crypttrace/__init__.py

@@ -1,2 +1,2 @@
 """crypttrace — OSINT crypto investigation CLI."""
-__version__ = "0.2.0"
+__version__ = "0.4.0"

{crypttrace-0.2.0 → crypttrace-0.4.0}/src/crypttrace/cli.py

@@ -5,10 +5,12 @@ known entities (exchanges, mixers, sanctioned wallets), and traces where the
 funds went.
 """
 import sys
+import zipfile
 from datetime import datetime
 from pathlib import Path
 from typing import Optional
 
+import requests
 import typer
 from rich.console import Console
 
@@ -262,21 +264,21 @@ def crosschain(
 
 @app.command()
 def offramp(
-    address: str = typer.Argument(..., help="Address to check (0x…)"),
+    address: str = typer.Argument(..., help="Address to check"),
     chain: str = CHAIN_OPT,
 ):
     """Check whether an address is an exchange deposit address (cash-out / off-ramp)."""
     try:
         hit = offramp_mod.detect(address, chain)
-    except etherscan.EtherscanError as e:
+    except (chains_mod.ChainError, etherscan.EtherscanError) as e:
         console.print(f"[red]Error:[/red] {e}")
         raise typer.Exit(1)
     if hit:
         pct = int(hit["fraction"] * 100)
         console.print(
             f"[green]➜ Likely off-ramp:[/green] this address forwarded ~{pct}% of outgoing "
-            f"funds ({hit['forwarded']:.4f}) to [bold]{hit['exchange']}[/bold].\n"
-            f"  It is probably a {hit['exchange']} deposit address — a KYC identification point."
+            f"funds ({hit['forwarded']:.4f} {hit['symbol']}) to [bold]{hit['exchange']}[/bold].\n"
+            f"  It is probably a deposit address at {hit['company']} — a KYC identification point."
         )
     else:
         console.print("[dim]No exchange-forwarding pattern detected. "
@@ -352,6 +354,17 @@ def labels_audit():
         for u in a["unsourced"][:8]:
             console.print(f"     [dim]{u['name']} ({u['type']})[/dim]")
 
+    from crypttrace.labels import bulk
+    downloaded = bulk.sets()
+    if downloaded:
+        console.print("\n  [bold]downloaded exchange address sets[/bold] (self-published, "
+                      "checked on import)")
+        for s in downloaded.values():
+            console.print(f"     {s['name']:<34} {s['count']:>8}   snapshot {s['snapshot']}")
+    else:
+        console.print("\n  [dim]No exchange address sets downloaded. "
+                      "`crypttrace update-labels --okx` adds OKX's ~300k deposit addresses.[/dim]")
+
 
 @labels_app.command("why")
 def labels_why(
@@ -393,15 +406,33 @@ def labels_check(
 
 
 @app.command(name="update-labels")
-def update_labels():
+def update_labels(
+    okx: bool = typer.Option(False, "--okx",
+                             help="Also download OKX's signed address list (~80 MB): "
+                                  "labels its ~300k deposit addresses directly"),
+    okx_file: Optional[Path] = typer.Option(None, "--okx-file",
+                                            help="Import an OKX proof-of-reserves zip you "
+                                                 "already downloaded, instead of fetching it"),
+):
     """Download the latest label lists (OFAC sanctions, etc.) into the local DB."""
+    from crypttrace.labels import bulk
     console.print("Updating label database…")
     for name, cnt, err in labels.update():
         if err:
             console.print(f"  [red]✗[/red] {name}: {err}")
         else:
             console.print(f"  [green]✓[/green] {name}: [bold]{cnt}[/bold] addresses")
-    console.print(f"[green]Done.[/green] {labels.count()} labelled addresses now loaded.")
+    if okx or okx_file:
+        try:
+            n, snap = bulk.import_okx(str(okx_file) if okx_file else None,
+                                      progress=lambda m: console.print(f"  [dim]OKX: {m}[/dim]"))
+            console.print(f"  [green]✓[/green] OKX signed addresses (snapshot {snap}): "
+                          f"[bold]{n}[/bold] addresses")
+        except (requests.RequestException, ValueError, OSError, zipfile.BadZipFile) as e:
+            console.print(f"  [red]✗[/red] OKX signed addresses: {e}")
+    console.print(f"[green]Done.[/green] {labels.count()} curated and imported labels loaded"
+                  + (f", plus {sum(s['count'] for s in bulk.sets().values())} exchange addresses"
+                     if bulk.sets() else "") + ".")
     console.print(f"[dim]Cache: {config.DATA_DIR / 'imported_labels.json'}[/dim]")
 
 

{crypttrace-0.2.0 → crypttrace-0.4.0}/src/crypttrace/investigate.py

@@ -74,7 +74,7 @@ def analyse(address: str, chain: str = "eth", asset: Optional[dict] = None,
         result["funding"] = []
 
     try:
-        result["offramp"] = offramp_mod.detect(address, chain) if chains.is_evm(chain) else None
+        result["offramp"] = offramp_mod.detect(address, chain)
     except Exception:
         result["offramp"] = None
 
@@ -82,20 +82,11 @@ def analyse(address: str, chain: str = "eth", asset: Optional[dict] = None,
     return result
 
 
-def _service_name(label: str) -> str:
-    """'Binance 14 (hot wallet)' -> 'Binance' — victims need the company, not our label."""
-    import re
-    name = re.sub(r"\(.*?\)", "", label)          # drop parentheticals
-    name = name.split(" deposit")[0].split(":")[0]
-    name = re.sub(r"\s+\d+\s*$", "", name.strip())  # drop trailing wallet numbers
-    return name.strip() or label
-
-
 def build_guidance(r: dict) -> dict:
     """Turn findings into plain-language next steps."""
     steps: List[dict] = []
     exchanges = r["exchanges"]
-    ex_names = sorted({_service_name(f["label"]) for f in exchanges}) if exchanges else []
+    ex_names = sorted({labels.company(f["label"]) for f in exchanges}) if exchanges else []
 
     if exchanges:
         headline = ("Good news, relatively speaking: the trail reaches a "

{crypttrace-0.2.0 → crypttrace-0.4.0}/src/crypttrace/labels/audit.py

@@ -90,6 +90,9 @@ def evidence(address: str) -> Dict:
     # Tron/Solana keys keep their case (it carries the checksum), but callers
     # often pass addresses already lower-cased by the label layer.
     meta = raw.get(address) or {k.lower(): v for k, v in raw.items()}.get(address.lower())
+    if not meta:
+        from crypttrace.labels import bulk     # large downloaded sets (OKX, …)
+        meta = bulk.lookup(address)
     if not meta:
         return {"address": address, "known": False}
     return {

crypttrace-0.4.0/src/crypttrace/labels/bulk.py

@@ -0,0 +1,187 @@
+"""Large address sets published by exchanges themselves, kept in SQLite.
+
+OKX signs every address that holds customer funds for its proof of reserves —
+over 300,000 of them, most of them per-customer *deposit* addresses. A deposit
+address is the cash-out point: funds that land there are with an exchange that
+knows the depositor. Labelling them outright catches a deposit the moment funds
+arrive, before the exchange sweeps them onward — the window in which a freeze
+request can still work. The behavioural off-ramp heuristic only sees the sweep.
+
+That is far too many to ship in known.json or to load on every run, so the set
+is downloaded on request (`crypttrace update-labels --okx`) into a SQLite file
+and looked up one address at a time. Curated labels in known.json always win.
+"""
+import csv
+import io
+import re
+import sqlite3
+import time
+import zipfile
+from pathlib import Path
+from typing import Callable, Dict, Optional, Tuple
+
+import requests
+
+from crypttrace import addresses, config
+
+DB_PATH: Path = config.DATA_DIR / "bulk_labels.sqlite"
+
+OKX_PAGE = "https://www.okx.com/proof-of-reserves/download"
+_OKX_FILE = re.compile(r"https://static\.okx\.com/cdn/okx/por/chain/por_csv_(\d{10})_V(\d+)\.zip")
+
+# OKX network name -> crypttrace chain (only the chains crypttrace can trace)
+OKX_NETWORKS = {"BTC": "btc", "TRON": "tron", "SOL": "sol", "ETH": "eth", "BSC": "bsc",
+                "POLYGON": "polygon", "ARBITRUM": "arbitrum", "OPTIMISM": "optimism",
+                "BASE": "base"}
+
+_conn: Optional[sqlite3.Connection] = None
+
+
+def _db() -> Optional[sqlite3.Connection]:
+    """Open the store lazily; None when no set has been downloaded."""
+    global _conn
+    if _conn is None:
+        if not DB_PATH.exists():
+            return None
+        _conn = sqlite3.connect(DB_PATH, check_same_thread=False)
+    return _conn
+
+
+def _create(c: sqlite3.Connection) -> None:
+    c.execute("CREATE TABLE IF NOT EXISTS labels (key TEXT PRIMARY KEY, chain TEXT, "
+              "set_name TEXT) WITHOUT ROWID")
+    c.execute("CREATE TABLE IF NOT EXISTS sets (set_name TEXT PRIMARY KEY, name TEXT, "
+              "type TEXT, role TEXT, source TEXT, source_kind TEXT, snapshot TEXT, "
+              "url TEXT, count INTEGER, imported_at INTEGER)")
+
+
+def lookup(address: str) -> Optional[dict]:
+    c = _db()
+    if c is None:
+        return None
+    row = c.execute("SELECT s.name, s.type, s.role, s.source, s.source_kind, s.snapshot, l.chain "
+                    "FROM labels l JOIN sets s USING (set_name) WHERE l.key = ?",
+                    (address.strip().lower(),)).fetchone()
+    if not row:
+        return None
+    name, typ, role, source, kind, snapshot, chain = row
+    return {"name": name, "type": typ, "role": role, "source": source,
+            "source_kind": kind, "added": snapshot, "chain": chain}
+
+
+def sets() -> Dict[str, dict]:
+    """What has been downloaded, for `labels audit`."""
+    c = _db()
+    if c is None:
+        return {}
+    cols = ["set_name", "name", "snapshot", "url", "count", "imported_at"]
+    return {r[0]: dict(zip(cols, r)) for r in
+            c.execute(f"SELECT {', '.join(cols)} FROM sets").fetchall()}
+
+
+def latest_okx_url(timeout: int = 30) -> str:
+    """The newest address file linked from OKX's proof-of-reserves download page."""
+    html = requests.get(OKX_PAGE, timeout=timeout, headers={"User-Agent": "Mozilla/5.0"}).text
+    found = {(m.group(1), int(m.group(2))): m.group(0) for m in _OKX_FILE.finditer(html)}
+    if not found:
+        raise ValueError("no address file found on OKX's proof-of-reserves page")
+    return found[max(found)]
+
+
+def _okx_csv_name(zip_path: Path) -> str:
+    with zipfile.ZipFile(zip_path) as z:
+        return next(n for n in z.namelist() if n.lower().endswith(".csv"))
+
+
+def _okx_rows(zip_path: Path):
+    """Yield (network, address) from OKX's file: a totals table, a blank line,
+    then one row per address with its network and ownership signature."""
+    with zipfile.ZipFile(zip_path) as z:
+        with z.open(_okx_csv_name(zip_path)) as raw:
+            f = io.TextIOWrapper(raw, encoding="utf-8-sig", newline="")
+            for line in f:
+                if line.lower().startswith("coin,type,network"):
+                    header = next(csv.reader([line]))
+                    break
+            else:
+                raise ValueError("unexpected OKX file layout: no address table")
+            idx = {h.strip().lower(): i for i, h in enumerate(header)}
+            n_i, a_i, s_i = idx["network"], idx["address"], idx["signature1"]
+            for row in csv.reader(f):
+                if len(row) > max(n_i, a_i, s_i) and row[s_i].strip():   # signed only
+                    yield row[n_i].strip().upper(), row[a_i].strip()
+
+
+def import_okx(source: Optional[str] = None,
+               progress: Optional[Callable[[str], None]] = None) -> Tuple[int, str]:
+    """Download (or read a local copy of) OKX's signed address file and store it.
+
+    Returns (addresses stored, snapshot). The previous OKX set is replaced in
+    one transaction, so a failed import leaves the old one in place.
+    """
+    say = progress or (lambda m: None)
+    url = source or latest_okx_url()
+    config.DATA_DIR.mkdir(parents=True, exist_ok=True)
+
+    if Path(url).exists():
+        zip_path, downloaded = Path(url), False
+        # the source text can end up in a report; a local path would leak the user's name
+        url = f"local copy {zip_path.name}"
+    else:
+        zip_path, downloaded = config.DATA_DIR / "okx_por.zip.part", True
+        say(f"downloading {url}")
+        with requests.get(url, stream=True, timeout=60,
+                          headers={"User-Agent": "Mozilla/5.0"}) as r:
+            r.raise_for_status()
+            with open(zip_path, "wb") as fh:
+                for chunk in r.iter_content(1 << 20):
+                    fh.write(chunk)
+
+    try:
+        # the snapshot time is in the file name: okx_por_2026090800_V1.csv
+        stamp = re.search(r"(\d{10})", _okx_csv_name(zip_path) + " " + url)
+        snapshot = (f"{stamp[1][:4]}-{stamp[1][4:6]}-{stamp[1][6:8]}" if stamp
+                    else "unknown date")
+        say("reading addresses")
+        rows, validators, bad = {}, 0, 0
+        for network, addr in _okx_rows(zip_path):
+            chain = OKX_NETWORKS.get(network)
+            if not chain:
+                continue
+            key = addr.lower()
+            if key in rows:
+                continue
+            if chain == "eth" and len(addr) == 98:
+                validators += 1       # a staking validator's public key, not an address
+                continue
+            if not addresses.validate(addr, chain)[0]:
+                bad += 1
+                continue
+            rows[key] = (key, chain, "okx")
+
+        c = sqlite3.connect(DB_PATH)
+        try:
+            _create(c)
+            with c:
+                c.execute("DELETE FROM labels WHERE set_name = 'okx'")
+                c.executemany("INSERT OR REPLACE INTO labels VALUES (?, ?, ?)", rows.values())
+                c.execute("INSERT OR REPLACE INTO sets VALUES (?,?,?,?,?,?,?,?,?,?)", (
+                    "okx", "OKX deposit address", "exchange", "deposit",
+                    f"one of the ~{len(rows) // 1000}k addresses OKX signed ('I am an OKX "
+                    f"address') in its proof-of-reserves snapshot {snapshot} ({url}); most are "
+                    "customer deposit addresses. Signature not verified by crypttrace.",
+                    "self-published", snapshot, url, len(rows), int(time.time())))
+        finally:
+            c.close()
+    finally:
+        if downloaded:
+            zip_path.unlink(missing_ok=True)
+
+    global _conn
+    if _conn is not None:
+        _conn.close()
+    _conn = None
+    say(f"stored {len(rows)} addresses"
+        + (f", skipped {validators} ETH staking validator keys" if validators else "")
+        + (f", skipped {bad} malformed" if bad else ""))
+    return len(rows), snapshot