crypttrace 0.7.0__tar.gz → 0.9.0__tar.gz

{crypttrace-0.7.0/src/crypttrace.egg-info → crypttrace-0.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: crypttrace
-Version: 0.7.0
+Version: 0.9.0
 Summary: OSINT toolkit for crypto investigations: trace stolen funds across Ethereum, Bitcoin, Tron and Solana
 Author: bobslayerX
 License-Expression: MIT
@@ -131,7 +131,11 @@ crypttrace serve            # then open http://127.0.0.1:8000
 Paste an address, pick a chain and direction, and get an interactive fund-flow
 graph: nodes coloured by what they are, arrows showing where value went, click a
 node for its full profile, click a transfer line to open it on the block
-explorer. A side panel shows the profile, first-funder chain and off-ramp check.
+explorer. A side panel shows the profile, first-funder chain, off-ramp check
+and whether USDT/USDC at the address is frozen. Tabs add the assessment, the
+timeline, the list of who sent funds here, and address poisoning (look-alikes
+planted in the wallet's history, and payments lured by this address). **Case
+file** downloads the same one-page HTML report `crypttrace report` writes.
 Everything runs on your machine — nothing is uploaded anywhere.
 
 This exists so non-technical victims can use the tool at all: a form and a
@@ -222,7 +226,7 @@ crypttrace timeline bc1qADDRESS --chain btc
 crypttrace crosschain 0xADDRESS --window 48
 
 # Watch addresses; alert loudly the moment funds head for an exchange
-crypttrace watch add 0xADDRESS --note "my stolen ETH"
+crypttrace watch add TADDRESS --chain tron --note "my stolen USDT"
 crypttrace watch run --interval 300     # or --once for cron / Task Scheduler
 
 # Full investigation as a case file to send: one HTML page (plus Markdown + JSON)
@@ -273,15 +277,22 @@ toward an exchange (directly, or to a detected deposit address); quieter notices
 for other movement. It only alerts on activity *after* an address is added, and
 never double-alerts.
 
+It works on every supported chain and watches the native coin **and the
+stablecoins** (USDT, USDC) — on Tron, stolen money is almost always USDT.
+Counterfeit "USDT" and zero/dust transfers from address poisoners do not
+alert; they are summed up in one line per address with a warning never to copy
+those senders. Each check reads fresh data.
+
 ```bash
-crypttrace watch add 0xADDRESS --note "victim funds"
+crypttrace watch add TADDRESS --chain tron --note "victim funds"
 crypttrace watch list
 crypttrace watch run --interval 300     # continuous
 crypttrace watch run --once             # single check, for scheduled tasks
 ```
 
 Optional Telegram alerts: set `CRYPTTRACE_TG_TOKEN` and `CRYPTTRACE_TG_CHAT`,
-then pass `--telegram`.
+then pass `--telegram`. Each alert carries the chain, amount, asset and a link
+to the transaction.
 
 ### Stablecoin freezes
 

{crypttrace-0.7.0 → crypttrace-0.9.0}/README.md

@@ -97,7 +97,11 @@ crypttrace serve            # then open http://127.0.0.1:8000
 Paste an address, pick a chain and direction, and get an interactive fund-flow
 graph: nodes coloured by what they are, arrows showing where value went, click a
 node for its full profile, click a transfer line to open it on the block
-explorer. A side panel shows the profile, first-funder chain and off-ramp check.
+explorer. A side panel shows the profile, first-funder chain, off-ramp check
+and whether USDT/USDC at the address is frozen. Tabs add the assessment, the
+timeline, the list of who sent funds here, and address poisoning (look-alikes
+planted in the wallet's history, and payments lured by this address). **Case
+file** downloads the same one-page HTML report `crypttrace report` writes.
 Everything runs on your machine — nothing is uploaded anywhere.
 
 This exists so non-technical victims can use the tool at all: a form and a
@@ -188,7 +192,7 @@ crypttrace timeline bc1qADDRESS --chain btc
 crypttrace crosschain 0xADDRESS --window 48
 
 # Watch addresses; alert loudly the moment funds head for an exchange
-crypttrace watch add 0xADDRESS --note "my stolen ETH"
+crypttrace watch add TADDRESS --chain tron --note "my stolen USDT"
 crypttrace watch run --interval 300     # or --once for cron / Task Scheduler
 
 # Full investigation as a case file to send: one HTML page (plus Markdown + JSON)
@@ -239,15 +243,22 @@ toward an exchange (directly, or to a detected deposit address); quieter notices
 for other movement. It only alerts on activity *after* an address is added, and
 never double-alerts.
 
+It works on every supported chain and watches the native coin **and the
+stablecoins** (USDT, USDC) — on Tron, stolen money is almost always USDT.
+Counterfeit "USDT" and zero/dust transfers from address poisoners do not
+alert; they are summed up in one line per address with a warning never to copy
+those senders. Each check reads fresh data.
+
 ```bash
-crypttrace watch add 0xADDRESS --note "victim funds"
+crypttrace watch add TADDRESS --chain tron --note "victim funds"
 crypttrace watch list
 crypttrace watch run --interval 300     # continuous
 crypttrace watch run --once             # single check, for scheduled tasks
 ```
 
 Optional Telegram alerts: set `CRYPTTRACE_TG_TOKEN` and `CRYPTTRACE_TG_CHAT`,
-then pass `--telegram`.
+then pass `--telegram`. Each alert carries the chain, amount, asset and a link
+to the transaction.
 
 ### Stablecoin freezes
 

{crypttrace-0.7.0 → crypttrace-0.9.0}/src/crypttrace/__init__.py

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

{crypttrace-0.7.0 → crypttrace-0.9.0}/src/crypttrace/cli.py

@@ -836,12 +836,16 @@ app.add_typer(watch_app, name="watch")
 
 @watch_app.command("add")
 def watch_add(
-    address: str = typer.Argument(..., help="Address to watch (0x…)"),
+    address: str = typer.Argument(..., help="Address to watch"),
     chain: str = CHAIN_OPT,
-    note: str = typer.Option("", "--note", "-n", help="A label for this case, e.g. 'my stolen ETH'"),
+    note: str = typer.Option("", "--note", "-n", help="A label for this case, e.g. 'my stolen USDT'"),
 ):
     """Add an address to the watchlist (alerts only on activity from now on)."""
-    watch_mod.add(address, chain, note)
+    try:
+        watch_mod.add(address, chain, note)
+    except (watch_mod.WatchError, chains_mod.ChainError) as e:
+        console.print(f"[red]Error:[/red] {e}")
+        raise typer.Exit(1)
     console.print(f"[green]✓ Watching[/green] {address} ({chain})"
                   + (f" — {note}" if note else ""))
 
@@ -851,7 +855,8 @@ def watch_list():
     """Show the watchlist."""
     d = watch_mod.all_watched()
     if not d:
-        console.print("[dim]Watchlist is empty. Add one with `crypttrace watch add 0x…`[/dim]")
+        console.print("[dim]Watchlist is empty. Add one with "
+                      "`crypttrace watch add ADDRESS --chain tron`[/dim]")
         return
     for addr, m in d.items():
         console.print(f"  {addr}  ({m.get('chain','eth')})"
@@ -873,7 +878,7 @@ def _render_alert(e: dict) -> None:
     when = render._ts(str(e["timestamp"]))
     line = (f"{icon} [{style}]{e['sev'].upper()}[/{style}]  {e['address'][:12]}…"
             + (f" ({e['note']})" if e.get("note") else "")
-            + f"  {e['value']:.4f}  {e['reason']}  [dim]{when}[/dim]")
+            + f"  {e['value']:,.4f} {e.get('symbol', '')}  {e['reason']}  [dim]{when}[/dim]")
     if e["sev"] == "high":
         console.bell()  # audible bell for cash-out events
     console.print(line)
@@ -888,7 +893,8 @@ def watch_run(
 ):
     """Poll the watchlist and alert on new activity. Loud alert on likely cash-out."""
     if not watch_mod.all_watched():
-        console.print("[dim]Watchlist is empty. Add one with `crypttrace watch add 0x…`[/dim]")
+        console.print("[dim]Watchlist is empty. Add one with "
+                      "`crypttrace watch add ADDRESS --chain tron`[/dim]")
         raise typer.Exit(1)
 
     def _pass():
@@ -896,11 +902,20 @@ def watch_run(
         if not alerts:
             console.print(f"[dim]{render._ts(str(int(time.time())))} — no new activity[/dim]")
             return
+        dust = {}
         for e in alerts:
+            if e["sev"] == "dust":           # one line per address, not one per speck
+                dust[e["address"]] = dust.get(e["address"], 0) + 1
+                continue
             _render_alert(e)
             if telegram and e["sev"] in ("high", "move"):
-                msg = f"crypttrace {e['sev'].upper()}: {e['address']} {e['value']:.4f} {e['reason']}"
+                msg = (f"crypttrace {e['sev'].upper()} ({e.get('chain', '')}): {e['address']} "
+                       f"{e['value']:,.4f} {e.get('symbol', '')} {e['reason']}"
+                       + (f"\n{e['explorer']}" if e.get("explorer") else ""))
                 watch_mod.telegram_notify(msg)
+        for addr, n in dust.items():
+            console.print(f"[dim]  {addr[:12]}… {n} zero/dust transfer(s) — likely address "
+                          "poisoning; never copy an address from this wallet's history[/dim]")
 
     if once:
         _pass()

{crypttrace-0.7.0 → crypttrace-0.9.0}/src/crypttrace/report.py

@@ -174,22 +174,32 @@ def collect(address: str, chain: str, depth: int, branching: int, asset=None) ->
 def generate(address: str, chain: str, depth: int, branching: int,
              out_dir: Path, asset=None, guidance: Optional[dict] = None) -> Dict[str, Path]:
     """Write <case>.html, <case>.md and <case>.json; returns their paths."""
-    data = collect(address, chain, depth, branching, asset)
-    if guidance:
-        data["guidance"] = guidance
+    data, raw, digest = build(address, chain, depth, branching, asset, guidance)
     out_dir.mkdir(parents=True, exist_ok=True)
-    base = f"{chain}_{address[:10]}_{datetime.now().strftime('%Y%m%d_%H%M%S')}"
+    base = case_name(address, chain)
     paths = {k: out_dir / f"{base}.{k}" for k in ("html", "md", "json")}
-    raw = json.dumps(data, indent=2, ensure_ascii=False, default=str)
     # bytes, not text mode: on Windows text mode turns LF into CRLF, and the hash
     # printed in the HTML would no longer match the file next to it
     paths["json"].write_bytes(raw.encode("utf-8"))
-    digest = hashlib.sha256(raw.encode("utf-8")).hexdigest()
     paths["md"].write_text(_render_md(data, paths["json"].name), encoding="utf-8")
     paths["html"].write_text(render_html(data, raw, digest, paths["json"].name), encoding="utf-8")
     return paths
 
 
+def case_name(address: str, chain: str) -> str:
+    return f"{chain}_{address[:10]}_{datetime.now().strftime('%Y%m%d_%H%M%S')}"
+
+
+def build(address: str, chain: str, depth: int, branching: int, asset=None,
+          guidance: Optional[dict] = None):
+    """(data, raw JSON, its SHA-256) — the web UI renders the page from this in memory."""
+    data = collect(address, chain, depth, branching, asset)
+    if guidance:
+        data["guidance"] = guidance
+    raw = json.dumps(data, indent=2, ensure_ascii=False, default=str)
+    return data, raw, hashlib.sha256(raw.encode("utf-8")).hexdigest()
+
+
 # ------------------------------------------------------------------ markdown
 
 def _render_md(d: dict, json_name: str) -> str:
@@ -460,8 +470,10 @@ def render_html(d: dict, raw_json: str, digest: str, json_name: str) -> str:
     P.append(f"<h2>Method and limits</h2><p>{_e(_METHOD)}</p>")
     if d.get("errors"):
         P.append("<p class='muted'>Parts that could not be read: " + _e("; ".join(d["errors"])) + "</p>")
-    P.append(f"<p class='muted'>The raw data is saved next to this file as <span class='mono'>{_e(json_name)}"
-             f"</span> (SHA-256 <span class='mono'>{digest}</span>) and embedded below for analysts.</p>")
+    where = (f"saved next to this file as <span class='mono'>{_e(json_name)}</span>"
+             if json_name else "embedded in this file")
+    P.append(f"<p class='muted'>The raw data is {where} (SHA-256 of the JSON: "
+             f"<span class='mono'>{digest}</span>) and embedded below for analysts.</p>")
     # JSON inside <script type=application/json> is data, never executed. Every "<" is
     # written as < (still valid JSON), so a crafted token or label name can neither
     # close the element nor push the parser into its "<!--<script" escaping states.

crypttrace-0.9.0/src/crypttrace/watch.py

@@ -0,0 +1,194 @@
+"""Address monitoring — the feature that actually helps recover funds.
+
+The one window to freeze stolen crypto is the moment it reaches an exchange
+deposit address. Victims can't watch a chain 24/7. `watch` keeps a list of
+addresses, detects new activity, and raises a loud HIGH alert the instant funds
+move toward an exchange (directly, or to a detected deposit address). Everything
+else is a quieter movement notice.
+
+It works on every supported chain and watches the native coin *and* the
+stablecoins (USDT, USDC) — most thefts move stablecoins, and on Tron almost
+nothing else. Each poll reads fresh data, never the local store's copy.
+
+Honest limit: the tool tells you *when* to act; freezing funds still depends on
+the exchange and law enforcement responding quickly.
+"""
+import json
+from typing import Dict, List, Optional, Tuple
+
+import requests
+
+from crypttrace.labels import labels
+from crypttrace import addresses, assets, chains, config, offramp, poisoning
+
+WATCHLIST = config.DATA_DIR / "watchlist.json"
+
+
+class WatchError(ValueError):
+    pass
+
+
+def _load() -> Dict[str, dict]:
+    if WATCHLIST.exists():
+        try:
+            return json.loads(WATCHLIST.read_text(encoding="utf-8"))
+        except (ValueError, OSError):
+            return {}
+    return {}
+
+
+def _save(d: Dict[str, dict]) -> None:
+    WATCHLIST.parent.mkdir(parents=True, exist_ok=True)
+    WATCHLIST.write_text(json.dumps(d, indent=2), encoding="utf-8")
+
+
+_ALL_TOKENS = {"contract": None, "symbol": "*"}
+_SPL = {"contract": "spl", "symbol": "SPL"}
+
+
+def _key(row: dict) -> str:
+    return "|".join(str(row.get(k, "")) for k in ("hash", "from", "to", "value", "symbol"))
+
+
+def _rows(address: str, chain: str, limit: int) -> List[dict]:
+    """Fresh native and stablecoin transfers, each tagged with the asset it belongs to.
+
+    Tokens are read in one request and kept only when their contract is the real
+    stablecoin's — counterfeit "USDT" sent by address poisoners must not alert."""
+    rows = [{**r, "_asset": None} for r in chains.transfers(address, chain, limit, fresh=True)]
+    if chain == "btc":
+        return rows
+    try:
+        tokens = chains.transfers(address, chain, limit, asset=_ALL_TOKENS, fresh=True)
+    except chains.ChainError:
+        return rows              # the native history alone still gets watched
+    if chain == "sol":           # Solana token rows carry no mint to tell tokens apart
+        return rows + [{**r, "_asset": _SPL} for r in tokens]
+    stables = {t["contract"].lower(): dict(t) for t in assets.tokens_for(chain).values()
+               if t.get("stable")}
+    return rows + [{**r, "_asset": stables[(r.get("contract") or "").lower()]}
+                   for r in tokens if (r.get("contract") or "").lower() in stables]
+
+
+def _latest(rows: List[dict]) -> Tuple[int, List[str]]:
+    """Newest timestamp and the keys of every transfer at that second."""
+    last = max((int(r.get("timestamp") or 0) for r in rows), default=0)
+    return last, [_key(r) for r in rows if int(r.get("timestamp") or 0) == last]
+
+
+def add(address: str, chain: str = "eth", note: str = "") -> int:
+    ok, why = addresses.validate(address, chain)
+    if not ok:
+        raise WatchError(f"not a valid {chain} address: {why}")
+    last, keys = _latest(_rows(address, chain, 50))   # only alert on activity after now
+    d = _load()
+    d[chains.norm_addr(address, chain)] = {"chain": chain, "note": note,
+                                          "last_ts": last, "last_keys": keys}
+    _save(d)
+    return last
+
+
+def remove(address: str) -> bool:
+    d = _load()
+    for k in (address, address.lower()):
+        if k in d:
+            del d[k]
+            _save(d)
+            return True
+    return False
+
+
+def all_watched() -> Dict[str, dict]:
+    return _load()
+
+
+def _classify(me: str, row: dict, chain: str) -> dict:
+    frm, to = row.get("from") or "", row.get("to") or ""
+    val = row.get("value", 0) or 0
+    asset = row.get("_asset")
+    symbol = asset["symbol"] if asset else chains.symbol(chain)
+    direction = "out" if frm == me else "in"
+    other = to if direction == "out" else frm
+    otype = labels.type_of(other)
+
+    sev, reason = "info", "incoming funds" if direction == "in" else "funds moved out"
+    if poisoning._is_bait(row, chain):
+        # zero, dust or counterfeit: how poisoners plant look-alikes in a history
+        sev, reason = "dust", "zero/dust transfer — likely address poisoning; never copy this sender"
+    elif direction == "out" and otype == "exchange":
+        sev, reason = "high", f"→ EXCHANGE {labels.label_of(other)} — possible cash-out (freeze window)"
+    elif direction == "out" and otype in ("mixer", "sanctioned"):
+        sev, reason = "high", f"→ {otype} {labels.label_of(other)}"
+    elif direction == "out" and otype == "bridge":
+        sev, reason = "move", f"→ bridge {labels.label_of(other)} (funds may leave this chain)"
+    elif direction == "out" and val > 0:
+        try:
+            off = offramp.detect(other, chain, asset=asset, stablecoins=False)
+        except chains.ChainError:
+            off = None
+        if off:
+            sev, reason = "high", f"→ likely {off['company']} DEPOSIT address — possible cash-out"
+        else:
+            sev, reason = "move", "funds moved out"
+
+    return {"direction": direction, "other": other, "otype": otype, "value": val,
+            "symbol": symbol, "sev": sev, "reason": reason,
+            "timestamp": int(row.get("timestamp") or 0), "hash": row.get("hash", ""),
+            "explorer": chains.tx_url(row["hash"], chain) if row.get("hash") else ""}
+
+
+def check(address: str, chain: str, since_ts: int, seen_keys: Optional[List[str]] = None,
+          limit: int = 100) -> List[dict]:
+    """New events since the baseline, newest first, each classified. A transfer in
+    the same second as the baseline counts as new unless it was already seen."""
+    me = chains.norm_addr(address, chain)
+    seen = set(seen_keys or [])
+    rows = [r for r in _rows(address, chain, limit)
+            if int(r.get("timestamp") or 0) > since_ts
+            or (int(r.get("timestamp") or 0) == since_ts and _key(r) not in seen)]
+    rows.sort(key=lambda r: int(r.get("timestamp") or 0), reverse=True)
+    return [dict(_classify(me, r, chain), _key=_key(r)) for r in rows]
+
+
+def poll_once() -> List[dict]:
+    """Check every watched address, update baselines, return all new alerts."""
+    d = _load()
+    alerts = []
+    for addr, meta in d.items():
+        chain = meta.get("chain", "eth")
+        try:
+            events = check(addr, chain, meta.get("last_ts", 0), meta.get("last_keys"))
+        except chains.ChainError:
+            continue
+        if events:
+            last = max(e["timestamp"] for e in events)
+            keys = [e["_key"] for e in events if e["timestamp"] == last]
+            if last == meta.get("last_ts"):
+                keys += meta.get("last_keys", [])
+            meta["last_ts"], meta["last_keys"] = last, keys
+            for e in events:
+                e.pop("_key", None)
+                e["address"] = addr
+                e["chain"] = chain
+                e["note"] = meta.get("note", "")
+                alerts.append(e)
+    if alerts:
+        _save(d)
+    # highest severity first
+    order = {"high": 0, "move": 1, "info": 2, "dust": 3}
+    return sorted(alerts, key=lambda e: order.get(e["sev"], 3))
+
+
+def telegram_notify(text: str) -> Optional[bool]:
+    """Send an alert to Telegram if CRYPTTRACE_TG_TOKEN + CRYPTTRACE_TG_CHAT are set."""
+    import os
+    token = os.environ.get("CRYPTTRACE_TG_TOKEN")
+    chat = os.environ.get("CRYPTTRACE_TG_CHAT")
+    if not token or not chat:
+        return None
+    try:
+        r = requests.get(f"https://api.telegram.org/bot{token}/sendMessage",
+                         params={"chat_id": chat, "text": text}, timeout=15)
+        return r.ok
+    except requests.RequestException:
+        return False

{crypttrace-0.7.0 → crypttrace-0.9.0}/src/crypttrace/web/index.html

@@ -228,6 +228,7 @@
   <select id="depth" title="Depth"><option>2</option><option selected>3</option><option>4</option><option>5</option></select>
   <button id="go">Investigate</button>
   <button id="fit" class="ghost" title="Fit graph to view">Fit</button>
+  <button id="casefile" class="ghost" title="Download a one-page case file for an exchange or the police">Case file</button>
 </div>
 
 <div class="legend">
@@ -246,6 +247,7 @@
     <button class="tab" data-view="assess">Assessment</button>
     <button class="tab" data-view="timeline">Timeline</button>
     <button class="tab" data-view="victims">Who sent funds here</button>
+    <button class="tab" data-view="poison">Poisoning</button>
   </div>
   <div class="stage">
     <div class="loader" id="loader"></div>
@@ -255,6 +257,7 @@
     <div class="view" id="v-assess"></div>
     <div class="view" id="v-timeline"></div>
     <div class="view" id="v-victims"></div>
+    <div class="view" id="v-poison"></div>
     <div class="scaleview" id="scaleview" style="display:none">100%</div>
     <div class="zoomctl" id="zoomctl">
       <button id="zin"  title="Zoom in">+</button>
@@ -474,7 +477,7 @@ async function run(){
   setStatus('tracing the chain…',false,true); loader(35);
   $('#hint').classList.add('hide');
   loaded={};                       // new address -> other views must reload
-  $('#v-timeline').innerHTML=''; $('#v-victims').innerHTML=''; $('#v-assess').innerHTML='';
+  $('#v-timeline').innerHTML=''; $('#v-victims').innerHTML=''; $('#v-assess').innerHTML=''; $('#v-poison').innerHTML='';
   try{
     const dir=$('#direction').value;
     const g=await api(`/api/trace?address=${q(a)}&chain=${chain()}&depth=${$('#depth').value}&asset=${q($('#asset').value)}&direction=${dir}`);
@@ -524,12 +527,14 @@ function showView(v){
   $('#v-assess').classList.toggle('on',v==='assess');
   $('#v-timeline').classList.toggle('on',v==='timeline');
   $('#v-victims').classList.toggle('on',v==='victims');
+  $('#v-poison').classList.toggle('on',v==='poison');
   const a=$('#addr').value.trim();
   if(a && !loaded[v+a]) {
     loaded[v+a]=true;
     if(v==='timeline') loadTimeline(a);
     if(v==='victims') loadVictims(a);
     if(v==='assess') loadAssessment(a);
+    if(v==='poison') loadPoisoning(a);
   }
 }
 document.querySelectorAll('.tab').forEach(t=>t.onclick=()=>showView(t.dataset.view));
@@ -647,6 +652,67 @@ async function verifyInto(container, addr){
   }catch(e){ slot.innerHTML=`<span class="vfy vfy-unavailable">verification unavailable</span>`; }
 }
 
+// Address poisoning: look-alikes planted in this wallet's history, and — seen from
+// the other side — payments this address received right after luring the payer.
+async function loadPoisoning(a){
+  const el=$('#v-poison');
+  el.innerHTML='<div class="muted"><span class="spin"></span>Comparing every address in this history…</div>';
+  try{
+    const r=await api(`/api/poisoning?address=${q(a)}&chain=${chain()}`);
+    const amt=v=>Number(v).toLocaleString(undefined,{maximumFractionDigits:2});
+    const addr=x=>`<a class="mono" href="${safeUrl(addrUrl(x))}" target="_blank" rel="noopener">${esc(x)}</a>`;
+    let h='';
+    for(const x of r.lured||[]){
+      h+=`<div class="verdict">Lured payment: ${addr(x.payer)} paid <b>${amt(x.paid)} ${esc(x.symbol)}</b>
+        on ${dstamp(x.paid_ts)} UTC, right after this address lured it (${esc(x.lure)}).
+        ${x.imitates?`It imitates ${addr(x.imitates)}, an address the payer had really used.`
+          :'<span class="muted">The imitated address was not found in the payer\'s recent history.</span>'}</div>`;
+    }
+    const paid=(r.lookalikes||[]).filter(p=>p.sent_to_lookalike>0);
+    for(const p of paid){
+      h+=`<div class="verdict">Money went to a look-alike: <b>${amt(p.sent_to_lookalike)} ${esc(p.symbols.join('/'))}</b>
+        <div class="kv"><span class="k">real address</span><span class="v">${addr(p.genuine)}</span></div>
+        <div class="kv"><span class="k">look-alike</span><span class="v">${addr(p.lookalike)}</span></div>
+        <div class="muted">Same first ${p.matching.prefix} and last ${p.matching.suffix} characters;
+        the look-alike first appeared ${dstamp(p.lookalike_first_seen)} UTC.</div></div>`;
+    }
+    if(r.campaign){
+      h+=`<div class="verdict">Poisoning campaign: this address sent ${r.campaign.bait_transfers} zero, dust or
+        counterfeit transfers to ${r.campaign.targets} different wallets.</div>`;
+    }
+    const planted=(r.lookalikes||[]).filter(p=>!(p.sent_to_lookalike>0));
+    if(planted.length){
+      h+=`<h3 style="font-size:11px;letter-spacing:.09em;color:var(--dim);margin:16px 0 8px">
+        ${planted.length} LOOK-ALIKE ADDRESS(ES) PLANTED IN THIS HISTORY — NEVER COPY AN ADDRESS FROM HERE</h3>
+        <table class="grid"><thead><tr><th>Look-alike</th><th>Imitates</th><th>Match</th>
+        <th style="text-align:right">Bait</th><th>First seen (UTC)</th></tr></thead><tbody>`+
+        planted.map(p=>`<tr><td>${addr(p.lookalike)}</td><td>${addr(p.genuine)}</td>
+          <td>${esc(p.resemblance)} (${p.matching.prefix}+${p.matching.suffix})</td>
+          <td class="num">${p.bait_transfers}</td><td>${dstamp(p.lookalike_first_seen)}</td></tr>`).join('')+
+        '</tbody></table>';
+    }
+    el.innerHTML=h||'<div class="muted">No look-alike addresses or poisoning pattern in this history.</div>';
+  }catch(e){ el.innerHTML=`<div class="err">${esc(e.message)}</div>`; }
+}
+
+// The case file: the same one-page HTML `crypttrace report` writes, built by the
+// backend and handed to the browser as a download.
+async function downloadCaseFile(){
+  const a=$('#addr').value.trim(), b=$('#casefile');
+  if(!a){ setStatus('enter an address',true); return; }
+  b.disabled=true; setStatus('building the case file…',false,true);
+  try{
+    const r=await fetch(`/api/report?address=${q(a)}&chain=${chain()}&asset=${q($('#asset').value)}&depth=${q($('#depth').value)}`);
+    if(!r.ok){ const j=await r.json().catch(()=>({})); throw new Error(j.error||`HTTP ${r.status}`); }
+    const name=((r.headers.get('Content-Disposition')||'').match(/filename="([^"]+)"/)||[])[1]||'case-file.html';
+    const u=URL.createObjectURL(await r.blob()), l=document.createElement('a');
+    l.href=u; l.download=name; l.click(); URL.revokeObjectURL(u);
+    setStatus(`case file saved: ${name}`);
+  }catch(e){ setStatus(e.message,true); }
+  finally{ b.disabled=false; }
+}
+$('#casefile').addEventListener('click',downloadCaseFile);
+
 function downloadCsv(){
   const head=['address','hop',`amount_sent_${victimSym}`,'transactions','first_seen_utc','last_seen_utc','label','explorer'];
   const body=victimRows.map(r=>[r.address,r.hop,r.value,r.txs,dstamp(r.first_seen),dstamp(r.last_seen),

{crypttrace-0.7.0 → crypttrace-0.9.0}/src/crypttrace/webapp.py

@@ -10,7 +10,7 @@ Launch with:  crypttrace serve   (then open http://127.0.0.1:8000)
 from datetime import datetime
 from pathlib import Path
 
-from flask import Flask, jsonify, request, send_from_directory
+from flask import Flask, Response, jsonify, request, send_from_directory
 
 from crypttrace.fetchers import etherscan
 from crypttrace.labels import labels
@@ -255,6 +255,40 @@ def create_app() -> Flask:
             return jsonify({"error": str(e)}), 400
         return jsonify({"hops": hops})
 
+    @app.route("/api/poisoning")
+    def api_poisoning():
+        addr = request.args.get("address", "")
+        chain = request.args.get("chain", "eth")
+        bad = validate(addr, chain)
+        if bad:
+            return jsonify({"error": bad}), 400
+        from crypttrace import poisoning
+        try:
+            return jsonify({"lookalikes": poisoning.lookalikes(addr, chain),
+                            "lured": poisoning.baited_payments(addr, chain),
+                            "campaign": poisoning.campaign(addr, chain)})
+        except _KNOWN_ERRORS as e:
+            return jsonify({"error": str(e)}), 400
+
+    @app.route("/api/report")
+    def api_report():
+        """The HTML case file, built in memory and handed over as a download."""
+        addr = request.args.get("address", "")
+        chain = request.args.get("chain", "eth")
+        bad = validate(addr, chain)
+        if bad:
+            return jsonify({"error": bad}), 400
+        from crypttrace import report as report_mod
+        try:
+            asset = assets.resolve_asset(request.args.get("asset") or None, chain)
+            depth = max(1, min(5, int(request.args.get("depth", 3))))
+            data, raw, digest = report_mod.build(addr, chain, depth, 3, asset)
+        except _KNOWN_ERRORS as e:
+            return jsonify({"error": str(e)}), 400
+        name = report_mod.case_name(addr, chain) + ".html"
+        return Response(report_mod.render_html(data, raw, digest, None), mimetype="text/html",
+                        headers={"Content-Disposition": f'attachment; filename="{name}"'})
+
     @app.route("/api/freeze")
     def api_freeze():
         addr = request.args.get("address", "")

{crypttrace-0.7.0 → crypttrace-0.9.0/src/crypttrace.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: crypttrace
-Version: 0.7.0
+Version: 0.9.0
 Summary: OSINT toolkit for crypto investigations: trace stolen funds across Ethereum, Bitcoin, Tron and Solana
 Author: bobslayerX
 License-Expression: MIT
@@ -131,7 +131,11 @@ crypttrace serve            # then open http://127.0.0.1:8000
 Paste an address, pick a chain and direction, and get an interactive fund-flow
 graph: nodes coloured by what they are, arrows showing where value went, click a
 node for its full profile, click a transfer line to open it on the block
-explorer. A side panel shows the profile, first-funder chain and off-ramp check.
+explorer. A side panel shows the profile, first-funder chain, off-ramp check
+and whether USDT/USDC at the address is frozen. Tabs add the assessment, the
+timeline, the list of who sent funds here, and address poisoning (look-alikes
+planted in the wallet's history, and payments lured by this address). **Case
+file** downloads the same one-page HTML report `crypttrace report` writes.
 Everything runs on your machine — nothing is uploaded anywhere.
 
 This exists so non-technical victims can use the tool at all: a form and a
@@ -222,7 +226,7 @@ crypttrace timeline bc1qADDRESS --chain btc
 crypttrace crosschain 0xADDRESS --window 48
 
 # Watch addresses; alert loudly the moment funds head for an exchange
-crypttrace watch add 0xADDRESS --note "my stolen ETH"
+crypttrace watch add TADDRESS --chain tron --note "my stolen USDT"
 crypttrace watch run --interval 300     # or --once for cron / Task Scheduler
 
 # Full investigation as a case file to send: one HTML page (plus Markdown + JSON)
@@ -273,15 +277,22 @@ toward an exchange (directly, or to a detected deposit address); quieter notices
 for other movement. It only alerts on activity *after* an address is added, and
 never double-alerts.
 
+It works on every supported chain and watches the native coin **and the
+stablecoins** (USDT, USDC) — on Tron, stolen money is almost always USDT.
+Counterfeit "USDT" and zero/dust transfers from address poisoners do not
+alert; they are summed up in one line per address with a warning never to copy
+those senders. Each check reads fresh data.
+
 ```bash
-crypttrace watch add 0xADDRESS --note "victim funds"
+crypttrace watch add TADDRESS --chain tron --note "victim funds"
 crypttrace watch list
 crypttrace watch run --interval 300     # continuous
 crypttrace watch run --once             # single check, for scheduled tasks
 ```
 
 Optional Telegram alerts: set `CRYPTTRACE_TG_TOKEN` and `CRYPTTRACE_TG_CHAT`,
-then pass `--telegram`.
+then pass `--telegram`. Each alert carries the chain, amount, asset and a link
+to the transaction.
 
 ### Stablecoin freezes
 

crypttrace-0.7.0/src/crypttrace/watch.py

@@ -1,138 +0,0 @@
-"""Address monitoring — the feature that actually helps recover funds.
-
-The one window to freeze stolen crypto is the moment it reaches an exchange
-deposit address. Victims can't watch a chain 24/7. `watch` keeps a list of
-addresses, detects new activity, and raises a loud HIGH alert the instant funds
-move toward an exchange (directly, or to a detected deposit address). Everything
-else is a quieter movement notice.
-
-Honest limit: the tool tells you *when* to act; freezing funds still depends on
-the exchange and law enforcement responding quickly.
-"""
-import json
-import time
-from typing import List, Dict, Optional
-
-import requests
-
-from crypttrace.fetchers import etherscan
-from crypttrace.labels import labels
-from crypttrace import chains, config, offramp
-
-WATCHLIST = config.DATA_DIR / "watchlist.json"
-
-
-def _load() -> Dict[str, dict]:
-    if WATCHLIST.exists():
-        try:
-            return json.loads(WATCHLIST.read_text())
-        except (ValueError, OSError):
-            return {}
-    return {}
-
-
-def _save(d: Dict[str, dict]) -> None:
-    WATCHLIST.parent.mkdir(parents=True, exist_ok=True)
-    WATCHLIST.write_text(json.dumps(d, indent=2))
-
-
-def _latest_ts(address: str, chain: str) -> int:
-    txs = etherscan.get_txs(address, chain, limit=1)
-    return int(txs[0]["timeStamp"]) if txs else 0
-
-
-def add(address: str, chain: str = "eth", note: str = "") -> int:
-    d = _load()
-    baseline = _latest_ts(address, chain)  # only alert on activity *after* now
-    d[address.lower()] = {"chain": chain, "note": note, "last_ts": baseline}
-    _save(d)
-    return baseline
-
-
-def remove(address: str) -> bool:
-    d = _load()
-    if address.lower() in d:
-        del d[address.lower()]
-        _save(d)
-        return True
-    return False
-
-
-def all_watched() -> Dict[str, dict]:
-    return _load()
-
-
-def _classify(me: str, tx: dict, chain: str) -> dict:
-    frm = tx.get("from", "").lower()
-    to = tx.get("to", "").lower()
-    val = int(tx.get("value", 0)) / config.WEI
-    direction = "out" if frm == me else "in"
-    other = to if direction == "out" else frm
-    otype = labels.type_of(other)
-
-    sev, reason = "info", "incoming funds" if direction == "in" else "funds moved out"
-    if direction == "out" and otype == "exchange":
-        sev, reason = "high", f"→ EXCHANGE {labels.label_of(other)} — possible cash-out (freeze window)"
-    elif direction == "out" and otype in ("mixer", "sanctioned"):
-        sev, reason = "high", f"→ {otype} {labels.label_of(other)}"
-    elif direction == "out" and otype == "bridge":
-        sev, reason = "move", f"→ bridge {labels.label_of(other)} (funds may leave this chain)"
-    elif direction == "out" and val > 0:
-        off = offramp.detect(other, chain)
-        if off:
-            sev, reason = "high", f"→ likely {off['exchange']} DEPOSIT address — possible cash-out"
-        else:
-            sev, reason = "move", "funds moved out"
-
-    return {"direction": direction, "other": other, "otype": otype, "value": val,
-            "sev": sev, "reason": reason, "timestamp": int(tx.get("timeStamp", "0")),
-            "hash": tx.get("hash", "")}
-
-
-def check(address: str, chain: str, since_ts: int, limit: int = 100) -> List[dict]:
-    """New events (newer than since_ts), newest first, each classified."""
-    me = address.lower()
-    events = []
-    for tx in etherscan.get_txs(address, chain, limit=limit):  # desc (newest first)
-        ts = int(tx.get("timeStamp", "0"))
-        if ts <= since_ts:
-            break
-        events.append(_classify(me, tx, chain))
-    return events
-
-
-def poll_once() -> List[dict]:
-    """Check every watched address, update baselines, return all new alerts."""
-    d = _load()
-    alerts = []
-    for addr, meta in d.items():
-        try:
-            events = check(addr, meta.get("chain", "eth"), meta.get("last_ts", 0))
-        except (etherscan.EtherscanError, chains.ChainError):
-            continue
-        if events:
-            meta["last_ts"] = max(e["timestamp"] for e in events)
-            for e in events:
-                e["address"] = addr
-                e["note"] = meta.get("note", "")
-                alerts.append(e)
-    if alerts:
-        _save(d)
-    # highest severity first
-    order = {"high": 0, "move": 1, "info": 2}
-    return sorted(alerts, key=lambda e: order.get(e["sev"], 3))
-
-
-def telegram_notify(text: str) -> Optional[bool]:
-    """Send an alert to Telegram if CRYPTTRACE_TG_TOKEN + CRYPTTRACE_TG_CHAT are set."""
-    import os
-    token = os.environ.get("CRYPTTRACE_TG_TOKEN")
-    chat = os.environ.get("CRYPTTRACE_TG_CHAT")
-    if not token or not chat:
-        return None
-    try:
-        r = requests.get(f"https://api.telegram.org/bot{token}/sendMessage",
-                         params={"chat_id": chat, "text": text}, timeout=15)
-        return r.ok
-    except requests.RequestException:
-        return False