crypttrace 0.2.0__py3-none-any.whl

crypttrace/verify.py

@@ -0,0 +1,153 @@
+"""Self-verification: check the tool's own arithmetic against the chain.
+
+A forensics tool that quietly miscounts is worse than no tool — its output
+looks authoritative and gets pasted into reports. This module re-derives the
+totals from what we parsed and compares them with the figures the chain index
+reports independently, then says plainly whether the numbers agree.
+
+It catches the two failure modes that matter:
+
+  * **wrong maths** — e.g. crediting one wallet with funds a hundred others
+    supplied, which is a real bug this tool once had;
+  * **incomplete history** — when an address has more transactions than were
+    fetched, so a conclusion is drawn from a slice rather than the whole
+    record. That one is dangerous precisely because nothing looks broken.
+"""
+from typing import Dict, List, Optional
+
+from crypttrace import chains
+from crypttrace.fetchers import bitcoin
+
+# how far computed and reported totals may drift before we complain
+REL_TOLERANCE = 0.005     # 0.5%
+ABS_TOLERANCE = 1e-6
+
+
+def _within(a: float, b: float) -> bool:
+    if a is None or b is None:
+        return True
+    diff = abs(a - b)
+    return diff <= ABS_TOLERANCE or diff <= max(abs(a), abs(b)) * REL_TOLERANCE
+
+
+def reconcile(address: str, chain: str = "btc", asset: Optional[dict] = None,
+              limit: int = 1000) -> Dict:
+    """Compare our parsed totals with the chain's own aggregates."""
+    me = chains.norm_addr(address, chain)
+    notes: List[str] = []
+
+    try:
+        rows = chains.transfers(address, chain, limit, asset=asset)
+    except chains.ChainError as e:
+        return {"status": "unavailable", "notes": [str(e)], "address": address,
+                "chain": chain, "analysed": 0}
+
+    got_in = sum(r["value"] for r in rows if r.get("to") == me)
+    got_out = sum(r["value"] for r in rows if r.get("from") == me)
+
+    # Miner fees are spent from the address but never arrive anywhere, so the
+    # chain's "sent" figure exceeds what recipients received by exactly the fees.
+    # Count each transaction's fee once, no matter how many outputs it had.
+    fees_by_tx = {}
+    for r in rows:
+        if r.get("from") == me and "fee_share" in r:
+            fees_by_tx[r.get("hash", "")] = r["fee_share"]
+    fees = sum(fees_by_tx.values())
+
+    ref_in = ref_out = ref_balance = None
+    ref_tx = None
+
+    if chain == "btc" and asset is None:
+        try:
+            s = bitcoin.stats(address)
+            ref_in, ref_out = s["received"], s["sent"]
+            ref_balance, ref_tx = s["balance"], s["tx_count"]
+        except bitcoin.BitcoinError as e:
+            notes.append(f"chain totals unavailable: {e}")
+    else:
+        try:
+            ref_balance = chains.balance(address, chain)
+        except chains.ChainError as e:
+            notes.append(f"balance unavailable: {e}")
+
+    # --- completeness -------------------------------------------------
+    complete = True
+    if ref_tx is not None:
+        # rows are per-transfer, a tx can produce several — compare loosely
+        if ref_tx > limit:
+            complete = False
+            notes.append(f"address has {ref_tx} transactions on chain but only "
+                         f"{limit} were fetched — this is a partial view")
+    elif len(rows) >= limit:
+        complete = False
+        notes.append(f"hit the {limit}-transfer fetch limit — history may be truncated")
+
+    # --- arithmetic ---------------------------------------------------
+    checks = []
+    if ref_in is not None:
+        ok = _within(got_in, ref_in) or not complete
+        checks.append(("received", got_in, ref_in, ok))
+    if ref_out is not None:
+        # compare like with like: what recipients got, plus the fees we paid
+        sent_incl_fees = got_out + fees
+        ok = _within(sent_incl_fees, ref_out) or not complete
+        checks.append(("sent (incl. fees)", sent_incl_fees, ref_out, ok))
+        if fees > 0:
+            notes.append(f"of which {fees:.8f} went to miner fees across "
+                         f"{len(fees_by_tx)} transaction(s) — recipients received "
+                         f"{got_out:.8f}")
+    if ref_in is None and ref_balance is not None and asset is None and complete:
+        # no aggregate feed: fall back to net vs balance (fees make it inexact)
+        net = got_in - got_out
+        ok = abs(net - ref_balance) <= max(0.01, abs(ref_balance) * 0.02)
+        checks.append(("net vs balance", net, ref_balance, ok))
+        if not ok:
+            notes.append("net flow differs from the current balance; on account-based "
+                         "chains gas costs explain small gaps, large ones do not")
+
+    failed = [c for c in checks if not c[3]]
+    strong = ref_in is not None or ref_out is not None   # gross totals from the chain
+    if failed:
+        status = "mismatch"
+        for name, got, ref, _ in failed:
+            notes.append(f"{name}: computed {got:.8f}, chain reports {ref:.8f} "
+                         f"(off by {abs(got-ref):.8f})")
+    elif not complete:
+        status = "partial"
+    elif checks and strong:
+        status = "verified"
+    elif checks:
+        # only the balance reconciled: weaker evidence, so don't claim more
+        status = "consistent"
+        notes.append("this chain publishes no independent gross totals, so only the "
+                     "net balance could be checked — per-counterparty attribution "
+                     "is not cross-verified")
+    else:
+        status = "unchecked"
+        notes.append("no independent totals available for this chain — "
+                     "figures could not be cross-checked")
+
+    return {
+        "address": address, "chain": chain, "status": status,
+        "analysed": len(rows), "chain_tx_count": ref_tx, "complete": complete,
+        "computed_received": got_in, "chain_received": ref_in,
+        "computed_sent": got_out, "chain_sent": ref_out, "fees": fees,
+        "chain_balance": ref_balance,
+        "checks": [{"name": n, "computed": g, "chain": r, "ok": o} for n, g, r, o in checks],
+        "notes": notes,
+    }
+
+
+def headline(v: Dict) -> str:
+    """One line a human can act on."""
+    return {
+        "verified": "Verified — gross totals match the chain independently.",
+        "consistent": "Consistent — the balance reconciles, but this chain offers no "
+                      "independent gross totals, so attribution is only partly checked.",
+        "partial": "Partial view — only some of this address's history was read, "
+                   "so totals are a floor, not the whole picture.",
+        "mismatch": "MISMATCH — the computed totals disagree with the chain. "
+                    "Do not rely on this output until it is explained.",
+        "unchecked": "Not cross-checked — no independent totals for this chain.",
+        "unavailable": "Could not reach the chain to verify.",
+    }.get(v.get("status"), "Unknown verification state.")

crypttrace/watch.py

@@ -0,0 +1,138 @@
+"""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 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:
+            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