crypttrace 0.16.0__tar.gz → 0.18.0__tar.gz

{crypttrace-0.16.0/src/crypttrace.egg-info → crypttrace-0.18.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: crypttrace
-Version: 0.16.0
+Version: 0.18.0
 Summary: OSINT toolkit for crypto investigations: trace stolen funds across Ethereum, Bitcoin, Tron, Solana and TON
 Author: bobslayerX
 License-Expression: MIT
@@ -104,6 +104,7 @@ export TRONGRID_API_KEY=xxxx            # optional: higher TronGrid quota
 export CRYPTTRACE_SOLANA_RPC=https://…  # optional: your own (faster) Solana RPC
 export TONCENTER_API_KEY=xxxx          # optional: toncenter allows ~1 request/s without it
 export TONAPI_KEY=xxxx                 # optional: faster tonapi name lookups on TON
+export TRONSCAN_API_KEY=xxxx           # optional: Tron exchange and scam tags from Tronscan
 ```
 
 (In PowerShell: `$env:TRONGRID_API_KEY = "xxxx"` and so on.)
@@ -153,6 +154,22 @@ history and answers in plain language:
 
 The web UI has the same check in its **Was I drained?** tab.
 
+### An evidence pack for the exchange and the police
+
+```bash
+crypttrace evidence YOUR_ADDRESS --chain ton --lang en   # for the exchange
+crypttrace evidence YOUR_ADDRESS --chain ton --lang ru   # for a police report (Russian)
+```
+
+Turns the check into a document to send: a summary of the theft, every
+transfer out of the wallet with its explorer link, the path to the exchange
+deposit and its memo with the hash of each hop, a precise request to the
+exchange (freeze the account behind the memo, preserve KYC, login and
+withdrawal records) and to the police (request them through the exchange's
+law-enforcement channel), and how it was established — so anyone can check it.
+Name, contact and signature are left blank to fill in. Saved as HTML (print to
+PDF), Markdown and JSON; the **Was I drained?** tab has download buttons too.
+
 ## Web UI
 
 ```bash
@@ -521,6 +538,13 @@ accounts. These become labels of kind `explorer-tag`, cached for a week. A
 "kucoin-1.ton" — is not taken as a label. A trace stops at a DEX: the funds
 come back to the sender in another token.
 
+**Tron: tags from Tronscan.** With a free Tronscan API key (`TRONSCAN_API_KEY`,
+created in a Tronscan account), Tron addresses the curated set does not know
+get Tronscan's tags: exchange wallets ("Binance-Cold 1", "Okex 1") become
+exchange labels and a red tag (scam, phishing) makes the address a scam — both
+as `explorer-tag` labels naming Tronscan as the source, cached for a week.
+Without a key nothing is fetched.
+
 **Exchange deposits with a memo.** A TON exchange takes all customers' deposits
 into one hot wallet and tells them apart by the transfer comment, the *memo*.
 The memo is the lead: it names one account at the exchange, which holds that

{crypttrace-0.16.0 → crypttrace-0.18.0}/README.md

@@ -70,6 +70,7 @@ export TRONGRID_API_KEY=xxxx            # optional: higher TronGrid quota
 export CRYPTTRACE_SOLANA_RPC=https://…  # optional: your own (faster) Solana RPC
 export TONCENTER_API_KEY=xxxx          # optional: toncenter allows ~1 request/s without it
 export TONAPI_KEY=xxxx                 # optional: faster tonapi name lookups on TON
+export TRONSCAN_API_KEY=xxxx           # optional: Tron exchange and scam tags from Tronscan
 ```
 
 (In PowerShell: `$env:TRONGRID_API_KEY = "xxxx"` and so on.)
@@ -119,6 +120,22 @@ history and answers in plain language:
 
 The web UI has the same check in its **Was I drained?** tab.
 
+### An evidence pack for the exchange and the police
+
+```bash
+crypttrace evidence YOUR_ADDRESS --chain ton --lang en   # for the exchange
+crypttrace evidence YOUR_ADDRESS --chain ton --lang ru   # for a police report (Russian)
+```
+
+Turns the check into a document to send: a summary of the theft, every
+transfer out of the wallet with its explorer link, the path to the exchange
+deposit and its memo with the hash of each hop, a precise request to the
+exchange (freeze the account behind the memo, preserve KYC, login and
+withdrawal records) and to the police (request them through the exchange's
+law-enforcement channel), and how it was established — so anyone can check it.
+Name, contact and signature are left blank to fill in. Saved as HTML (print to
+PDF), Markdown and JSON; the **Was I drained?** tab has download buttons too.
+
 ## Web UI
 
 ```bash
@@ -487,6 +504,13 @@ accounts. These become labels of kind `explorer-tag`, cached for a week. A
 "kucoin-1.ton" — is not taken as a label. A trace stops at a DEX: the funds
 come back to the sender in another token.
 
+**Tron: tags from Tronscan.** With a free Tronscan API key (`TRONSCAN_API_KEY`,
+created in a Tronscan account), Tron addresses the curated set does not know
+get Tronscan's tags: exchange wallets ("Binance-Cold 1", "Okex 1") become
+exchange labels and a red tag (scam, phishing) makes the address a scam — both
+as `explorer-tag` labels naming Tronscan as the source, cached for a week.
+Without a key nothing is fetched.
+
 **Exchange deposits with a memo.** A TON exchange takes all customers' deposits
 into one hot wallet and tells them apart by the transfer comment, the *memo*.
 The memo is the lead: it names one account at the exchange, which holds that

{crypttrace-0.16.0 → crypttrace-0.18.0}/src/crypttrace/__init__.py

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

{crypttrace-0.16.0 → crypttrace-0.18.0}/src/crypttrace/cli.py

@@ -182,6 +182,36 @@ def check(
     console.print(render.drain_report(res))
 
 
+@app.command()
+def evidence(
+    address: str = typer.Argument(..., help="The victim's own wallet address"),
+    chain: str = CHAIN_OPT,
+    lang: str = typer.Option("en", "--lang", "-l", help="en (for exchanges) or ru (for the police)"),
+    out: Path = typer.Option(Path.home() / "crypttrace-reports", "--out", "-o", help="Folder to save into"),
+):
+    """An evidence pack for the exchange and the police: what was taken, the path, the memo, the requests."""
+    from crypttrace import evidence as ev
+    if lang not in ev.T:
+        console.print(f"[red]Error:[/red] --lang must be one of {', '.join(ev.T)}")
+        raise typer.Exit(1)
+    try:
+        with console.status("Reading the wallet's history…"):
+            doc = ev.build(address, chain)
+    except (chains_mod.ChainError, etherscan.EtherscanError) as e:
+        console.print(f"[red]Error:[/red] {e}")
+        raise typer.Exit(1)
+    if doc["check"]["verdict"] == "no_drain":
+        console.print("[green]No drain found[/green] for this wallet — nothing to put in an evidence pack.")
+        raise typer.Exit(0)
+    paths = ev.write(doc, out, lang)
+    memos = ", ".join(f"{d['company']} memo {d['memo']}" for d in doc["deposits"]) or "none found yet"
+    console.print(f"[bold]Evidence pack saved[/bold] — exchange deposits: {memos}")
+    for p in paths:
+        console.print(f"  {p}")
+    console.print("[dim]Open the .html in a browser and print it to PDF. Fill in your name and contact, "
+                  "then send it with your report.[/dim]")
+
+
 @app.command()
 def trace(
     address: str = typer.Argument(..., help="Starting address (0x…)"),

{crypttrace-0.16.0 → crypttrace-0.18.0}/src/crypttrace/drain.py

@@ -100,7 +100,9 @@ def check(address: str, chain: str, limit: int = 1000) -> Dict:
     res.update({"to": dest, "to_label": labels.label_of(dest), "to_type": labels.type_of(dest),
                 "start": burst["start"], "end": burst["end"], "transfers": len({r.get("hash") for r in win}),
                 "assets": assets, "nfts": nfts, "emptied": emptied, "new_destination": not paid_before,
-                "tight_pairs": tight})
+                "tight_pairs": tight,
+                "drain_txs": [{"timestamp": r["timestamp"], "value": r.get("value", 0), "symbol": r.get("symbol", ""),
+                               "hash": r.get("hash", "")} for r in sorted(win, key=lambda r: r["timestamp"])]})
 
     # a mass drain: the same address swept many wallets around the same time
     try:

crypttrace-0.18.0/src/crypttrace/evidence.py

@@ -0,0 +1,233 @@
+"""An evidence pack a victim can hand to an exchange and to the police.
+
+Built from `drain.check` on the victim's own address: what was taken, when, by
+which transactions, where the money went, and — the part that gets results — the
+exchange deposit and its memo, with a precise request: freeze that account and
+preserve its records. Everything is a fact read from the chain with a link to
+check it; nothing about the victim is invented — name, contact and signature are
+left blank to fill in.
+
+English for exchanges' compliance teams, Russian for a police report.
+"""
+import datetime as dt
+import html
+import json
+from pathlib import Path
+from typing import Dict, List, Optional
+
+from crypttrace import __version__, chains, drain
+from crypttrace.labels import labels
+
+# law-enforcement request portals, only where checked against the exchange's own site
+LE_PORTALS = {"KuCoin": "https://www.kucoin.com/legal/requests"}
+SOURCES = {"ton": "toncenter.com (transactions), tonapi.io (account names)",
+           "tron": "TronGrid", "btc": "mempool.space", "sol": "Solana JSON-RPC"}
+
+
+def _utc(ts) -> str:
+    return dt.datetime.fromtimestamp(int(ts or 0), dt.timezone.utc).strftime("%Y-%m-%d %H:%M:%S UTC")
+
+
+def _link_hop(src: str, dst: str, chain: str) -> Optional[dict]:
+    """The largest transfer src → dst: the link between two hops of the path."""
+    rows = [r for r in chains.transfers(src, chain) if r.get("from") == src and r.get("to") == dst]
+    if not rows:
+        return None
+    r = max(rows, key=lambda r: r.get("value", 0) or 0)
+    return {"from": src, "to": dst, "value": r.get("value", 0), "symbol": r.get("symbol", ""),
+            "timestamp": r.get("timestamp", 0), "hash": r.get("hash", "")}
+
+
+def build(address: str, chain: str) -> Dict:
+    """Facts for the pack. `verdict` other than drained/suspicious means there is nothing to report."""
+    res = drain.check(address, chain)
+    doc = {"generated": dt.datetime.now(dt.timezone.utc).strftime("%Y-%m-%d %H:%M UTC"),
+           "tool": f"crypttrace {__version__}", "chain": chain, "check": res, "path": [], "deposits": []}
+    if res["verdict"] == "no_drain":
+        return doc
+    dest = res["to"]
+    for d in res.get("next", []):
+        if not d.get("memo"):
+            continue
+        hops = []
+        if d["from"] != dest:
+            link = _link_hop(dest, d["from"], chain)
+            if link:
+                hops.append(link)
+        company = labels.company(d["exchange"])
+        doc["deposits"].append({**d, "company": company, "portal": LE_PORTALS.get(company),
+                                "via": hops})
+    return doc
+
+
+# ------------------------------------------------------------------ text
+T = {
+    "en": {
+        "title": "Theft of cryptocurrency — evidence summary",
+        "victim": "Victim (to be completed)", "name": "Name", "contact": "Contact (e-mail / phone)",
+        "wallet": "Wallet", "discovered": "Date the theft was discovered",
+        "summary": "Summary",
+        "summary_text": ("On {start}, {n} transfer(s) moved {taken} out of the wallet {victim} to {to}{to_label}, "
+                         "within {mins} minute(s). The wallet was left empty."),
+        "mass": ("The same receiving address collected funds from {k} other wallets within one hour of this "
+                 "theft — a mass theft using leaked private keys, not an individual transaction made by the owner."),
+        "resweep": ("Money that arrived in the wallet after the theft was taken as well ({n} later transfer(s)): "
+                    "the attacker still holds the wallet's key."),
+        "chronology": "Transfers out of the victim's wallet",
+        "cols": ["Time (UTC)", "Amount", "Transaction"],
+        "path": "Where the funds went",
+        "deposit": ("The funds collected by the receiving address (from this and other victims) were moved on: "
+                    "{amount} was deposited on {time} to the hot wallet of {company} ({hot}) with the deposit "
+                    "memo {memo}. The memo identifies one customer account at {company}."),
+        "via": "Path: {chain_text}",
+        "requests": "Requests",
+        "req_exchange": ("To {company}: please freeze the account identified by deposit memo {memo} (deposits to {hot}), "
+                         "and preserve its KYC records, login IP addresses and withdrawal history. A police report "
+                         "is being filed; law enforcement will request the data through your official channel."),
+        "req_police": ("To the police: please request from {company} the identity, login records and withdrawal "
+                       "destinations of the account behind deposit memo {memo}{portal}."),
+        "portal": " — law-enforcement portal: {url}",
+        "none": "No deposit with a memo was found on the path yet; the receiving address above is the lead.",
+        "method": "How this was established",
+        "method_text": ("Read directly from the public {chain} blockchain ({sources}) with {tool} on {generated}. "
+                        "Every transaction above links to a public block explorer and can be checked by anyone. "
+                        "Exchange names are explorer tags; the account behind a memo can be confirmed only by the "
+                        "exchange. To reproduce: {cmd}"),
+        "sign": "Signature / date", "nothing": "No drain was found for this wallet in the history read.",
+    },
+    "ru": {
+        "title": "Хищение криптовалюты — сводка доказательств",
+        "victim": "Потерпевший (заполнить)", "name": "ФИО", "contact": "Контакты (e-mail / телефон)",
+        "wallet": "Кошелёк", "discovered": "Дата обнаружения хищения",
+        "summary": "Кратко",
+        "summary_text": ("{start} с кошелька {victim} на адрес {to}{to_label} было выполнено {n} перевод(а/ов) "
+                         "за {mins} мин.: {taken}. После этого кошелёк остался пустым."),
+        "mass": ("Тот же адрес-получатель в течение часа собрал средства ещё с {k} кошельков — это массовое хищение "
+                 "с использованием утёкших ключей, а не перевод, сделанный владельцем."),
+        "resweep": ("Средства, поступившие на кошелёк после хищения, также были выведены ({n} перевод(а/ов)): "
+                    "ключ от кошелька до сих пор у злоумышленника."),
+        "chronology": "Переводы с кошелька потерпевшего",
+        "cols": ["Время (UTC)", "Сумма", "Транзакция"],
+        "path": "Куда ушли средства",
+        "deposit": ("Средства, собранные адресом-получателем (в том числе с других потерпевших), выведены "
+                    "дальше: {amount} зачислено {time} на горячий кошелёк биржи {company} ({hot}) с депозитным "
+                    "memo {memo}. Memo однозначно указывает на один клиентский аккаунт на {company}."),
+        "via": "Путь: {chain_text}",
+        "requests": "Просьбы",
+        "req_exchange": ("Бирже {company}: заморозить аккаунт, определяемый депозитным memo {memo} (депозиты на {hot}), "
+                         "и сохранить его данные KYC, IP-адреса входов и историю выводов. Подаётся заявление в "
+                         "полицию; правоохранительные органы запросят данные через официальный канал биржи."),
+        "req_police": ("Полиции: запросить у {company} данные владельца, журнал входов и адреса выводов аккаунта "
+                       "с депозитным memo {memo}{portal}."),
+        "portal": " — портал для правоохранительных органов: {url}",
+        "none": "Депозит на биржу с memo пока не найден; зацепкой остаётся адрес-получатель, указанный выше.",
+        "method": "Как это установлено",
+        "method_text": ("Данные получены напрямую из публичного блокчейна {chain} ({sources}) инструментом {tool}, "
+                        "{generated}. Каждая транзакция выше снабжена ссылкой на публичный обозреватель и может быть "
+                        "проверена любым лицом. Названия бирж — метки обозревателей; владельца аккаунта по memo "
+                        "может подтвердить только биржа. Проверка: {cmd}"),
+        "sign": "Подпись / дата", "nothing": "Для этого кошелька хищение в прочитанной истории не обнаружено.",
+    },
+}
+
+
+def _facts(doc: Dict, lang: str) -> Dict:
+    t, res, chain = T[lang], doc["check"], doc["chain"]
+    taken = ", ".join(f"{v:,.4f} {k}" for k, v in res.get("assets", {}).items())
+    if res.get("nfts"):
+        taken += f"{', ' if taken else ''}{res['nfts']} NFT"
+    lab = res.get("to_label")
+    paras = [t["summary_text"].format(start=_utc(res["start"]), n=res["transfers"], taken=taken or "—",
+                                      victim=res["address"], to=res["to"], to_label=f" ({lab})" if lab else "",
+                                      mins=max(1, (res["end"] - res["start"]) // 60))]
+    if (res.get("other_wallets_same_hour") or 0) >= drain.MASS_SENDERS:
+        paras.append(t["mass"].format(k=res["other_wallets_same_hour"]))
+    if res.get("resweeps"):
+        paras.append(t["resweep"].format(n=res["resweeps"]))
+    rows = [(_utc(x["timestamp"]), f"{x['value']:,.4f} {x['symbol']}", x["hash"]) for x in res.get("drain_txs", [])]
+    deps = []
+    for d in doc["deposits"]:
+        hops = [res["address"], res["to"]] + [h["to"] for h in d["via"]] + [d["exchange_address"]]
+        deps.append({
+            "text": t["deposit"].format(amount=f"{d['value']:,.4f} {d['symbol']}", time=_utc(d["last_ts"]),
+                                        exchange=d["exchange"], hot=d["exchange_address"], memo=d["memo"],
+                                        company=d["company"]),
+            "via": t["via"].format(chain_text=" → ".join(hops)),
+            "links": [h["hash"] for h in d["via"]] + [d["hash"]],
+            "req_exchange": t["req_exchange"].format(company=d["company"], memo=d["memo"], hot=d["exchange_address"]),
+            "req_police": t["req_police"].format(company=d["company"], memo=d["memo"],
+                                                 portal=t["portal"].format(url=d["portal"]) if d.get("portal") else ""),
+        })
+    method = t["method_text"].format(chain=chain.upper(), sources=SOURCES.get(chain, "public node APIs"),
+                                     tool=doc["tool"], generated=doc["generated"],
+                                     cmd=f"crypttrace check {res['address']} --chain {chain}")
+    return {"paras": paras, "rows": rows, "deps": deps, "method": method}
+
+
+def render_markdown(doc: Dict, lang: str = "en") -> str:
+    t, res = T[lang], doc["check"]
+    if res["verdict"] == "no_drain":
+        return f"# {t['title']}\n\n{t['nothing']}\n"
+    f = _facts(doc, lang)
+    tx = lambda h: f"[{h[:16]}…]({chains.tx_url(h, doc['chain'])})"
+    L = [f"# {t['title']}\n", f"## {t['victim']}\n",
+         f"- {t['name']}: ____________________\n", f"- {t['contact']}: ____________________\n",
+         f"- {t['wallet']}: `{res['address']}` ({doc['chain'].upper()})\n", f"- {t['discovered']}: __________\n",
+         f"\n## {t['summary']}\n"] + [p + "\n\n" for p in f["paras"]]
+    L += [f"## {t['chronology']}\n", f"| {' | '.join(t['cols'])} |\n|---|---|---|\n"]
+    L += [f"| {a} | {b} | {tx(h)} |\n" for a, b, h in f["rows"]]
+    L += [f"\n## {t['path']}\n"]
+    if f["deps"]:
+        for d in f["deps"]:
+            L += [d["text"] + "\n\n", d["via"] + "\n\n", " · ".join(tx(h) for h in d["links"] if h) + "\n\n"]
+        L += [f"## {t['requests']}\n"] + [f"- {d['req_exchange']}\n- {d['req_police']}\n" for d in f["deps"]]
+    else:
+        L.append(t["none"] + "\n")
+    L += [f"\n## {t['method']}\n", f["method"] + "\n", f"\n{t['sign']}: ____________________\n"]
+    return "".join(L)
+
+
+def render_html(doc: Dict, lang: str = "en") -> str:
+    t, res, e = T[lang], doc["check"], html.escape
+    head = (f"<!doctype html><html lang='{lang}'><head><meta charset='utf-8'><title>{e(t['title'])}</title>"
+            "<style>body{font:15px/1.55 Georgia,'Times New Roman',serif;max-width:860px;margin:32px auto;padding:0 20px;"
+            "color:#111}h1{font-size:24px}h2{font-size:18px;margin-top:28px;border-bottom:1px solid #999}"
+            "table{border-collapse:collapse;width:100%}td,th{border:1px solid #bbb;padding:5px 8px;font-size:13px;"
+            "text-align:left;vertical-align:top}code,.mono{font-family:Consolas,monospace;font-size:12.5px;"
+            "word-break:break-all}.box{border:2px solid #111;padding:10px 14px;margin:10px 0}.blank{display:inline-block;"
+            "min-width:280px;border-bottom:1px solid #111}@media print{a{color:#111}}</style></head><body>")
+    if res["verdict"] == "no_drain":
+        return head + f"<h1>{e(t['title'])}</h1><p>{e(t['nothing'])}</p></body></html>"
+    f = _facts(doc, lang)
+    a = lambda h: f"<a class='mono' href='{e(chains.tx_url(h, doc['chain']))}'>{e(h)}</a>"
+    P = [head, f"<h1>{e(t['title'])}</h1>", f"<h2>{e(t['victim'])}</h2><table>"]
+    for k, v in ((t["name"], ""), (t["contact"], ""), (t["wallet"], f"<span class='mono'>{e(res['address'])}</span> "
+                                                                   f"({e(doc['chain'].upper())})"),
+                 (t["discovered"], "")):
+        P.append(f"<tr><th style='width:34%'>{e(k)}</th><td>{v or '<span class=blank>&nbsp;</span>'}</td></tr>")
+    P.append("</table>")
+    P.append(f"<h2>{e(t['summary'])}</h2>" + "".join(f"<p>{e(p)}</p>" for p in f["paras"]))
+    P.append(f"<h2>{e(t['chronology'])}</h2><table><tr>" + "".join(f"<th>{e(c)}</th>" for c in t["cols"]) + "</tr>")
+    P += [f"<tr><td>{e(x)}</td><td>{e(y)}</td><td>{a(h)}</td></tr>" for x, y, h in f["rows"]]
+    P.append(f"</table><h2>{e(t['path'])}</h2>")
+    if f["deps"]:
+        for d in f["deps"]:
+            P.append(f"<div class='box'><p><b>{e(d['text'])}</b></p><p class='mono'>{e(d['via'])}</p>"
+                     + "".join(f"<div>{a(h)}</div>" for h in d["links"] if h) + "</div>")
+        P.append(f"<h2>{e(t['requests'])}</h2><ol>"
+                 + "".join(f"<li>{e(d['req_exchange'])}</li><li>{e(d['req_police'])}</li>" for d in f["deps"]) + "</ol>")
+    else:
+        P.append(f"<p>{e(t['none'])}</p>")
+    P.append(f"<h2>{e(t['method'])}</h2><p>{e(f['method'])}</p>")
+    P.append(f"<p style='margin-top:40px'>{e(t['sign'])}: <span class='blank'>&nbsp;</span></p></body></html>")
+    return "".join(P)
+
+
+def write(doc: Dict, out_dir: Path, lang: str = "en") -> List[Path]:
+    out_dir.mkdir(parents=True, exist_ok=True)
+    stem = f"evidence_{doc['chain']}_{doc['check']['address'][:12]}_{lang}"
+    paths = [out_dir / f"{stem}.html", out_dir / f"{stem}.md", out_dir / f"{stem}.json"]
+    paths[0].write_text(render_html(doc, lang), encoding="utf-8")
+    paths[1].write_text(render_markdown(doc, lang), encoding="utf-8")
+    paths[2].write_text(json.dumps(doc, ensure_ascii=False, indent=1, default=str), encoding="utf-8")
+    return paths

{crypttrace-0.16.0 → crypttrace-0.18.0}/src/crypttrace/labels/labels.py

@@ -17,7 +17,7 @@ from typing import Optional, Dict, List
 import requests
 
 from crypttrace import addresses, config
-from crypttrace.labels import bulk, tonapi
+from crypttrace.labels import bulk, tonapi, tronscan
 
 _HERE = Path(__file__).parent
 _IMPORTED = config.DATA_DIR / "imported_labels.json"
@@ -189,15 +189,19 @@ def lookup(address: str) -> Optional[dict]:
     found = _match_partial(address) or bulk.lookup(address)
     if not found and (len(address) == 48 or ":" in address):
         found = tonapi.lookup(address)              # cached explorer tag, no network here
+    elif not found and len(address) == 34 and address.startswith("T"):
+        found = tronscan.lookup(address)
     return found
 
 
 def enrich(addrs, chain: str) -> None:
-    """Fetch explorer tags the curated set lacks (TON: tonapi names). Network, cached."""
+    """Fetch explorer tags the curated set lacks (TON: tonapi, Tron: Tronscan). Network, cached."""
+    _load()
     if chain == "ton":
-        _load()
         tonapi.enrich(a for a in addrs
                       if a and not _KNOWN.get((addresses.ton_friendly(a) or a).lower()))
+    elif chain == "tron":
+        tronscan.enrich(a for a in addrs if a and not _KNOWN.get(a.lower()))
 
 
 def is_deposit(address: str) -> bool:

crypttrace-0.18.0/src/crypttrace/labels/names.py

@@ -0,0 +1,8 @@
+"""Exchange names as explorers spell them — shared by the explorer-tag sources."""
+import re
+
+# custodial platforms that hold KYC and can freeze: a deposit there is a lead
+EXCHANGES = re.compile(
+    r"\b(binance|bybit|okx|okex|kucoin|htx|huobi|gate(\.io)?|mexc|bitget|kraken|coinbase|"
+    r"bitfinex|bingx|bitmart|lbank|whitebit|exmo|coinex|poloniex|crypto\.com|bitpanda|"
+    r"bithumb|upbit|cryptobot|crypto bot|xrocket|wallet in telegram|telegram wallet)\b", re.I)

{crypttrace-0.16.0 → crypttrace-0.18.0}/src/crypttrace/labels/tonapi.py

@@ -26,6 +26,7 @@ import requests
 
 from crypttrace import addresses, config
 from crypttrace.fetchers import http
+from crypttrace.labels.names import EXCHANGES
 
 API = "https://tonapi.io/v2/accounts/{}"
 CACHE = config.DATA_DIR / "tonapi_names.json"
@@ -33,12 +34,6 @@ MAX_AGE = 7 * 24 * 3600
 _KEY = os.environ.get("TONAPI_KEY")
 http.MIN_INTERVAL["tonapi.io"] = 0.12 if _KEY else 1.1
 
-# custodial platforms that hold KYC and can freeze: a deposit there is a lead
-_EXCHANGES = re.compile(
-    r"\b(binance|bybit|okx|okex|kucoin|htx|huobi|gate(\.io)?|mexc|bitget|kraken|coinbase|"
-    r"bitfinex|bingx|bitmart|lbank|whitebit|exmo|coinex|poloniex|crypto\.com|bitpanda|"
-    r"bithumb|upbit|cryptobot|crypto bot|xrocket|wallet in telegram|telegram wallet)\b", re.I)
-
 _cache: Optional[Dict[str, dict]] = None
 
 
@@ -73,7 +68,7 @@ def classify(account: dict) -> Optional[dict]:
         return {"name": name or "DEX contract", "type": "dex"}
     if not name or self_named:
         return None
-    if _EXCHANGES.search(name):
+    if EXCHANGES.search(name):
         memo = " (memo required)" if account.get("memo_required") else ""
         return {"name": f"{name}{memo}", "type": "exchange", "memo_required": bool(account.get("memo_required"))}
     return {"name": name, "type": "service"}

crypttrace-0.18.0/src/crypttrace/labels/tronscan.py

@@ -0,0 +1,105 @@
+"""Tron address tags from Tronscan — exchange wallets and risk warnings.
+
+Tronscan tags exchange hot and cold wallets ("Binance-Cold 1", "OKX-Hot") and
+puts red tags on addresses it flags as scams or phishing. Both become labels
+of kind "explorer-tag", with Tronscan named as the source; a red tag makes the
+address a scam. Grey tags and user feedback are not enough to call an address
+anything.
+
+Needs a free API key (TRONSCAN_API_KEY, created in a Tronscan account); without
+one nothing is fetched and Tron labels come from the curated set alone.
+Lookups are cached on disk for a week; only `enrich()` uses the network.
+"""
+import datetime as dt
+import json
+import os
+import sys
+import time
+from typing import Dict, Iterable, Optional
+
+import requests
+
+from crypttrace import config
+from crypttrace.fetchers import http
+from crypttrace.labels.names import EXCHANGES
+
+API = "https://apilist.tronscanapi.com/api/accountv2"
+CACHE = config.DATA_DIR / "tronscan_tags.json"
+MAX_AGE = 7 * 24 * 3600
+http.MIN_INTERVAL["apilist.tronscanapi.com"] = 0.25
+_cache: Optional[Dict[str, dict]] = None
+
+
+def _key() -> Optional[str]:
+    k = os.environ.get("TRONSCAN_API_KEY")
+    if not k and sys.platform == "win32":          # set with [Environment]::SetEnvironmentVariable(..., "User")
+        try:
+            import winreg
+            with winreg.OpenKey(winreg.HKEY_CURRENT_USER, "Environment") as reg:
+                k = winreg.QueryValueEx(reg, "TRONSCAN_API_KEY")[0]
+        except OSError:
+            k = None
+    return (k or "").strip() or None
+
+
+def _load() -> Dict[str, dict]:
+    global _cache
+    if _cache is None:
+        try:
+            _cache = json.loads(CACHE.read_text(encoding="utf-8"))
+        except (OSError, ValueError):
+            _cache = {}
+    return _cache
+
+
+def _save() -> None:
+    try:
+        CACHE.parent.mkdir(parents=True, exist_ok=True)
+        tmp = CACHE.with_suffix(".tmp")
+        tmp.write_text(json.dumps(_load(), ensure_ascii=False), encoding="utf-8")
+        tmp.replace(CACHE)
+    except OSError:
+        pass
+
+
+def classify(account: dict) -> Optional[dict]:
+    """A label from one Tronscan account record, or None if it names nothing."""
+    red = (account.get("redTag") or "").strip()
+    tag = (account.get("publicTag") or account.get("addressTag") or "").strip()
+    if red:
+        return {"name": f"{tag or red} (Tronscan: {red})", "type": "scam"}
+    if not tag:
+        return None
+    if EXCHANGES.search(tag.replace("-", " ")):
+        return {"name": tag, "type": "exchange"}
+    return {"name": tag, "type": "service"}
+
+
+def lookup(address: str) -> Optional[dict]:
+    """Cached Tronscan label, without touching the network."""
+    entry = _load().get(address)
+    if not entry or not entry.get("label"):
+        return None
+    return {**entry["label"], "chain": "tron", "source_kind": "explorer-tag",
+            "source": f"Tronscan address tag, fetched {entry.get('day', '')}"}
+
+
+def enrich(addrs: Iterable[str]) -> None:
+    """Fetch Tronscan tags for addresses not in the cache (or stale). No key, no fetch."""
+    key = _key()
+    if not key:
+        return
+    cache, now, changed = _load(), time.time(), False
+    for a in dict.fromkeys(addrs):
+        if not a or not a.startswith("T") or len(a) != 34 or now - cache.get(a, {}).get("at", 0) < MAX_AGE:
+            continue
+        try:
+            rec = http.request_json(API, {"address": a}, timeout=20, headers={"TRON-PRO-API-KEY": key})
+        except (http.RateLimited, requests.RequestException, ValueError):
+            continue
+        if not isinstance(rec, dict) or "__status__" in rec:
+            continue
+        cache[a] = {"at": now, "day": dt.date.today().isoformat(), "label": classify(rec)}
+        changed = True
+    if changed:
+        _save()

{crypttrace-0.16.0 → crypttrace-0.18.0}/src/crypttrace/web/index.html

@@ -644,6 +644,11 @@ async function loadCheck(a){
       }
       const left=(r.remaining_tokens||[]).map(x=>`${Number(x.amount).toLocaleString()} ${esc(x.symbol)}`)
         .concat(r.remaining_nfts?[`${r.remaining_nfts} NFT`]:[]);
+      const ev=l=>`/api/evidence-pack?address=${q(a)}&chain=${chain()}&lang=${l}`;
+      h+=`<div style="margin-top:14px">
+        <a class="btnlink" href="${ev('en')}">Evidence pack for the exchange (EN) ⬇</a>
+        <a class="btnlink" href="${ev('ru')}">Для полиции (RU) ⬇</a>
+        <div class="muted" style="margin-top:6px">Open it in a browser, print to PDF, fill in your name and contact.</div></div>`;
       h+=`<h3 style="margin-top:16px">What to do now</h3><ol>
         <li>This seed phrase is burned. Make a new wallet with a new seed phrase; never type it into a site, bot or "support" chat again.</li>
         ${left.length?`<li>Move what is still here to the new wallet right away: ${left.join(', ')}.</li>`:''}

{crypttrace-0.16.0 → crypttrace-0.18.0}/src/crypttrace/webapp.py

@@ -200,6 +200,23 @@ def create_app() -> Flask:
         res["to_explorer"] = chains.explorer_url(res["to"], chain) if res.get("to") else None
         return jsonify(res)
 
+    @app.route("/api/evidence-pack")
+    def api_evidence_pack():
+        from crypttrace import evidence as ev
+        addr = request.args.get("address", "")
+        chain = request.args.get("chain", "eth")
+        lang = request.args.get("lang", "en")
+        bad = validate(addr, chain)
+        if bad or lang not in ev.T:
+            return jsonify({"error": bad or "lang must be en or ru"}), 400
+        try:
+            doc = ev.build(addr, chain)
+        except _KNOWN_ERRORS as e:
+            return jsonify({"error": str(e)}), 400
+        resp = app.response_class(ev.render_html(doc, lang), mimetype="text/html")
+        resp.headers["Content-Disposition"] = f"attachment; filename=evidence_{chain}_{addr[:12]}_{lang}.html"
+        return resp
+
     @app.route("/api/victims")
     def api_victims():
         """Addresses that fed this wallet — in a mass theft, the victim list."""

{crypttrace-0.16.0 → crypttrace-0.18.0/src/crypttrace.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: crypttrace
-Version: 0.16.0
+Version: 0.18.0
 Summary: OSINT toolkit for crypto investigations: trace stolen funds across Ethereum, Bitcoin, Tron, Solana and TON
 Author: bobslayerX
 License-Expression: MIT
@@ -104,6 +104,7 @@ export TRONGRID_API_KEY=xxxx            # optional: higher TronGrid quota
 export CRYPTTRACE_SOLANA_RPC=https://…  # optional: your own (faster) Solana RPC
 export TONCENTER_API_KEY=xxxx          # optional: toncenter allows ~1 request/s without it
 export TONAPI_KEY=xxxx                 # optional: faster tonapi name lookups on TON
+export TRONSCAN_API_KEY=xxxx           # optional: Tron exchange and scam tags from Tronscan
 ```
 
 (In PowerShell: `$env:TRONGRID_API_KEY = "xxxx"` and so on.)
@@ -153,6 +154,22 @@ history and answers in plain language:
 
 The web UI has the same check in its **Was I drained?** tab.
 
+### An evidence pack for the exchange and the police
+
+```bash
+crypttrace evidence YOUR_ADDRESS --chain ton --lang en   # for the exchange
+crypttrace evidence YOUR_ADDRESS --chain ton --lang ru   # for a police report (Russian)
+```
+
+Turns the check into a document to send: a summary of the theft, every
+transfer out of the wallet with its explorer link, the path to the exchange
+deposit and its memo with the hash of each hop, a precise request to the
+exchange (freeze the account behind the memo, preserve KYC, login and
+withdrawal records) and to the police (request them through the exchange's
+law-enforcement channel), and how it was established — so anyone can check it.
+Name, contact and signature are left blank to fill in. Saved as HTML (print to
+PDF), Markdown and JSON; the **Was I drained?** tab has download buttons too.
+
 ## Web UI
 
 ```bash
@@ -521,6 +538,13 @@ accounts. These become labels of kind `explorer-tag`, cached for a week. A
 "kucoin-1.ton" — is not taken as a label. A trace stops at a DEX: the funds
 come back to the sender in another token.
 
+**Tron: tags from Tronscan.** With a free Tronscan API key (`TRONSCAN_API_KEY`,
+created in a Tronscan account), Tron addresses the curated set does not know
+get Tronscan's tags: exchange wallets ("Binance-Cold 1", "Okex 1") become
+exchange labels and a red tag (scam, phishing) makes the address a scam — both
+as `explorer-tag` labels naming Tronscan as the source, cached for a week.
+Without a key nothing is fetched.
+
 **Exchange deposits with a memo.** A TON exchange takes all customers' deposits
 into one hot wallet and tells them apart by the transfer comment, the *memo*.
 The memo is the lead: it names one account at the exchange, which holds that

{crypttrace-0.16.0 → crypttrace-0.18.0}/src/crypttrace.egg-info/SOURCES.txt

@@ -11,6 +11,7 @@ src/crypttrace/chains.py
 src/crypttrace/cli.py
 src/crypttrace/config.py
 src/crypttrace/drain.py
+src/crypttrace/evidence.py
 src/crypttrace/freeze.py
 src/crypttrace/funder.py
 src/crypttrace/investigate.py
@@ -43,6 +44,8 @@ src/crypttrace/labels/audit.py
 src/crypttrace/labels/bulk.py
 src/crypttrace/labels/known.json
 src/crypttrace/labels/labels.py
+src/crypttrace/labels/names.py
 src/crypttrace/labels/partial.json
 src/crypttrace/labels/tonapi.py
+src/crypttrace/labels/tronscan.py
 src/crypttrace/web/index.html