crypttrace 0.8.0__tar.gz → 0.9.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: crypttrace
-Version: 0.8.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
@@ -226,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)
@@ -277,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.8.0 → crypttrace-0.9.0}/README.md

@@ -192,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)
@@ -243,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.8.0 → crypttrace-0.9.0}/src/crypttrace/__init__.py

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

{crypttrace-0.8.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.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.8.0 → crypttrace-0.9.0/src/crypttrace.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: crypttrace
-Version: 0.8.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
@@ -226,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)
@@ -277,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.8.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