crypttrace 0.2.0__py3-none-any.whl

crypttrace/labels/labels.py

@@ -0,0 +1,199 @@
+"""Local label database + risk scoring.
+
+Labels are the single most valuable part of a forensics tool: they turn an
+anonymous hex string into "Binance hot wallet" or "Tornado Cash".
+
+Two layers are merged:
+  1. known.json  — the curated seed set shipped with the tool (rich names).
+  2. imported labels — downloaded by `crypttrace update-labels` from public
+     sources (OFAC sanctions, etc.), cached in the user's data dir.
+The seed set takes priority on conflicts, so its richer names win.
+"""
+import json
+from pathlib import Path
+from typing import Optional, Dict, List
+
+import requests
+
+from crypttrace import addresses, config
+
+_HERE = Path(__file__).parent
+_IMPORTED = config.DATA_DIR / "imported_labels.json"
+_KNOWN: Dict[str, dict] = {}
+_PARTIAL: List[dict] = []
+
+
+# Public label sources. Each is fetched and merged on `update-labels`.
+# "lines" format = one address per line (comments/blank lines skipped).
+SOURCES: List[dict] = [
+    {
+        "name": "OFAC SDN — sanctioned ETH addresses",
+        "url": ("https://raw.githubusercontent.com/0xB10C/"
+                "ofac-sanctioned-digital-currency-addresses/lists/"
+                "sanctioned_addresses_ETH.txt"),
+        "format": "lines",
+        "label": "OFAC SDN (sanctioned)",
+        "type": "sanctioned",
+    },
+]
+
+
+def _valid(addr: str) -> bool:
+    """Accept address shapes from every supported chain, not just EVM."""
+    a = addr.strip()
+    if a.startswith("0x"):
+        return len(a) == 42                       # EVM
+    if a.startswith(("bc1", "tb1")):
+        return 26 <= len(a) <= 62                 # Bitcoin bech32
+    if a.startswith(("1", "3")):
+        return 26 <= len(a) <= 35                 # Bitcoin legacy / p2sh
+    if a.startswith("t"):
+        return len(a) == 34                       # Tron (lower-cased 'T…')
+    return 32 <= len(a) <= 44                     # Solana / other base58
+
+
+def _load_partials() -> List[dict]:
+    """Addresses published only in truncated form (e.g. 'bc1qq85v2c9…cu9r').
+
+    Incident reports often abbreviate. Requiring BOTH prefix and suffix to match
+    is specific enough to be safe, and lets the tool flag a wallet before the
+    full string is public. Exact labels always take priority.
+    """
+    path = _HERE / "partial.json"
+    if not path.exists():
+        return []
+    try:
+        data = json.loads(path.read_text())
+    except (ValueError, OSError):
+        return []
+    out = []
+    for e in data.get("entries", []):
+        pre, suf = e.get("prefix", ""), e.get("suffix", "")
+        if len(pre) >= 8 and len(suf) >= 4:       # guard against loose patterns
+            out.append(e)
+    return out
+
+
+def _load() -> None:
+    global _KNOWN, _PARTIAL
+    if _KNOWN:
+        return
+    merged: Dict[str, dict] = {}
+    # imported first (lower priority)...
+    if _IMPORTED.exists():
+        try:
+            raw = json.loads(_IMPORTED.read_text())
+            merged.update({k.lower(): v for k, v in raw.items() if _valid(k.lower())})
+        except (ValueError, OSError):
+            pass
+    # ...then curated seed overrides. An entry that declares its chain is checked
+    # with that chain's validator on the original-case key: guessing from the
+    # lower-cased prefix drops Solana addresses that happen to start with 1, 3 or T.
+    seed = json.loads((_HERE / "known.json").read_text(encoding="utf-8"))
+    for k, v in seed.items():
+        chain = v.get("chain") if isinstance(v, dict) else None
+        ok = addresses.validate(k, chain)[0] if chain else _valid(k.lower())
+        if ok:
+            merged[k.lower()] = v
+    _KNOWN = merged
+    _PARTIAL = _load_partials()
+
+
+def _match_partial(address: str) -> Optional[dict]:
+    a = address.strip().lower()
+    for e in _PARTIAL:
+        if a.startswith(e["prefix"].lower()) and a.endswith(e["suffix"].lower()):
+            return {"name": e["name"], "type": e["type"], "partial": True,
+                    "source": e.get("source", "")}
+    return None
+
+
+def update(timeout: int = 30) -> List[tuple]:
+    """Fetch every source and merge results into the imported-labels cache.
+
+    Returns a list of (source_name, count, error) tuples for reporting.
+    """
+    imported: Dict[str, dict] = {}
+    if _IMPORTED.exists():
+        try:
+            imported = json.loads(_IMPORTED.read_text())
+        except (ValueError, OSError):
+            imported = {}
+
+    results = []
+    for src in SOURCES:
+        try:
+            resp = requests.get(src["url"], timeout=timeout)
+            resp.raise_for_status()
+        except requests.RequestException as e:
+            results.append((src["name"], 0, str(e)))
+            continue
+
+        count = 0
+        if src["format"] == "lines":
+            for line in resp.text.splitlines():
+                addr = line.strip().lower()
+                if _valid(addr):
+                    imported[addr] = {"name": src["label"], "type": src["type"]}
+                    count += 1
+        results.append((src["name"], count, None))
+
+    _IMPORTED.parent.mkdir(parents=True, exist_ok=True)
+    _IMPORTED.write_text(json.dumps(imported, indent=2))
+
+    # invalidate cache so freshly imported labels take effect immediately
+    global _KNOWN
+    _KNOWN = {}
+    return results
+
+
+def count() -> int:
+    """Total number of labelled addresses currently loaded."""
+    _load()
+    return len(_KNOWN)
+
+
+# Risk weight per label type (0-100)
+RISK = {
+    "sanctioned": 100,
+    "mixer": 90,
+    "scam": 85,
+    "bridge": 40,
+    "exchange": 20,
+    "unknown": 0,
+}
+
+TYPE_ICON = {
+    "sanctioned": "\U0001F534",  # red
+    "mixer": "\U0001F7E3",       # purple
+    "scam": "\U0001F534",
+    "bridge": "\U0001F309",      # bridge
+    "exchange": "\U0001F7E2",    # green
+    "unknown": "⚪",         # white
+}
+
+
+def lookup(address: str) -> Optional[dict]:
+    _load()
+    hit = _KNOWN.get(address.lower())
+    if hit:
+        return hit
+    return _match_partial(address)
+
+
+def label_of(address: str) -> str:
+    hit = lookup(address)
+    return hit["name"] if hit else ""
+
+
+def type_of(address: str) -> str:
+    hit = lookup(address)
+    return hit["type"] if hit else "unknown"
+
+
+def risk_score(address: str) -> int:
+    return RISK.get(type_of(address), 0)
+
+
+def icon(address: str) -> str:
+    return TYPE_ICON.get(type_of(address), TYPE_ICON["unknown"])

crypttrace/labels/partial.json

@@ -0,0 +1,15 @@
+{
+  "_comment": [
+    "Addresses known publicly only in truncated form, as incident reports and",
+    "researcher threads often abbreviate them (e.g. 'bc1qq85v2c9…cu9r').",
+    "Matching requires BOTH prefix and suffix, which is specific enough to be",
+    "safe; minimum lengths are enforced in labels.py. Exact entries in",
+    "known.json always take priority — promote an address here to known.json as",
+    "soon as the full string is confirmed.",
+    "",
+    "Example entry:",
+    "{ \"prefix\": \"bc1qq85v2c9\", \"suffix\": \"cu9r\", \"chain\": \"btc\",",
+    "  \"name\": \"Some Exploiter (2026)\", \"type\": \"scam\", \"source\": \"where it came from\" }"
+  ],
+  "entries": []
+}

crypttrace/offramp.py

@@ -0,0 +1,58 @@
+"""Off-ramp detection — spotting exchange deposit addresses.
+
+When laundered funds reach a centralised exchange, they almost never land on the
+exchange's labelled hot wallet directly. They land on a per-user *deposit
+address* the exchange generated, which then forwards the funds inward to the hot
+wallet. There are millions of these, so they're not in any label list — but they
+give themselves away by behaviour: a deposit address receives money and sends
+almost all of it onward to one known exchange wallet.
+
+Detecting them turns a plain "⚪ unknown wallet" into "→ Binance deposit address",
+i.e. the cash-out point — the exact place an investigation hands off to a legal
+request (the exchange holds the depositor's KYC).
+"""
+from typing import Optional
+
+from crypttrace.fetchers import etherscan
+from crypttrace.labels import labels
+from crypttrace import config
+
+
+def detect(address: str, chain: str = "eth", threshold: float = 0.6) -> Optional[dict]:
+    """Is `address` acting as a deposit/forwarding address for a known exchange?
+
+    Returns {exchange, exchange_address, forwarded, out_total, fraction} when at
+    least `threshold` of outgoing value goes to labelled exchange wallets,
+    otherwise None.
+    """
+    me = address.lower()
+    txs = etherscan.get_txs(address, chain, limit=1000)  # cached; shared with trace
+    out_total = 0.0
+    to_exchange = {}  # exchange_addr -> value
+    for tx in txs:
+        if tx.get("from", "").lower() != me:
+            continue
+        to = tx.get("to", "").lower()
+        if not to:
+            continue
+        val = int(tx.get("value", 0)) / config.WEI
+        out_total += val
+        if labels.type_of(to) == "exchange":
+            to_exchange[to] = to_exchange.get(to, 0.0) + val
+
+    if out_total <= 0 or not to_exchange:
+        return None
+
+    forwarded = sum(to_exchange.values())
+    fraction = forwarded / out_total
+    if fraction < threshold:
+        return None
+
+    best = max(to_exchange, key=to_exchange.get)
+    return {
+        "exchange": labels.label_of(best),
+        "exchange_address": best,
+        "forwarded": forwarded,
+        "out_total": out_total,
+        "fraction": fraction,
+    }

crypttrace/prices.py

@@ -0,0 +1,90 @@
+"""USD price lookups, with graceful offline degradation.
+
+Stablecoins are pinned to $1. Everything else is fetched from CoinGecko
+(free, no key) by contract address and cached for the session. If the network
+is unavailable, price() returns None and callers simply show '—' for USD.
+"""
+from typing import Optional, Dict
+
+import requests
+
+# symbols treated as ~$1
+_STABLE = {"usdt", "usdc", "dai", "busd", "tusd", "usdp", "gusd", "frax", "lusd"}
+
+# CoinGecko platform id per chain
+_PLATFORM = {"eth": "ethereum", "bsc": "binance-smart-chain", "polygon": "polygon-pos",
+             "arbitrum": "arbitrum-one", "optimism": "optimistic-ethereum", "base": "base",
+             "tron": "tron", "sol": "solana"}
+_COINGECKO_NATIVE = {"eth": "ethereum", "bsc": "binancecoin", "polygon": "matic-network",
+                     "arbitrum": "ethereum", "optimism": "ethereum", "base": "ethereum",
+                     "btc": "bitcoin", "tron": "tron", "sol": "solana"}
+
+_cache: Dict[str, Optional[float]] = {}
+
+
+def _get_json(url: str, params: dict, timeout: int = 15):
+    try:
+        r = requests.get(url, params=params, timeout=timeout)
+        r.raise_for_status()
+        return r.json()
+    except (requests.RequestException, ValueError):
+        return None
+
+
+def native_price(chain: str = "eth") -> Optional[float]:
+    """USD price of the chain's native coin (ETH, BTC, TRX, SOL, …).
+
+    Unknown chains return None rather than guessing — pricing a BTC balance with
+    ETH's price would silently corrupt an investigation.
+    """
+    key = f"native:{chain}"
+    if key in _cache:
+        return _cache[key]
+    cid = _COINGECKO_NATIVE.get(chain)
+    if cid is None:
+        _cache[key] = None
+        return None
+    data = _get_json("https://api.coingecko.com/api/v3/simple/price",
+                     {"ids": cid, "vs_currencies": "usd"})
+    price = None
+    if data and cid in data:
+        price = data[cid].get("usd")
+    _cache[key] = price
+    return price
+
+
+def token_price(contract: str, chain: str = "eth", symbol: str = "") -> Optional[float]:
+    """USD price of an ERC-20 token by contract. Stablecoins short-circuit to $1."""
+    if symbol.lower() in _STABLE:
+        return 1.0
+    key = f"{chain}:{contract.lower()}"
+    if key in _cache:
+        return _cache[key]
+    platform = _PLATFORM.get(chain, "ethereum")
+    data = _get_json(f"https://api.coingecko.com/api/v3/simple/token_price/{platform}",
+                     {"contract_addresses": contract, "vs_currencies": "usd"})
+    price = None
+    if data:
+        entry = data.get(contract.lower()) or next(iter(data.values()), None)
+        if isinstance(entry, dict):
+            price = entry.get("usd")
+    _cache[key] = price
+    return price
+
+
+def usd(amount: float, price: Optional[float]) -> Optional[float]:
+    if price is None:
+        return None
+    return amount * price
+
+
+def fmt_usd(value: Optional[float]) -> str:
+    """Human-friendly USD string: $1.2M, $340.5K, $12.34, or '—'."""
+    if value is None:
+        return "—"
+    a = abs(value)
+    if a >= 1_000_000:
+        return f"${value/1_000_000:.2f}M"
+    if a >= 1_000:
+        return f"${value/1_000:.1f}K"
+    return f"${value:.2f}"

crypttrace/render.py

@@ -0,0 +1,241 @@
+"""Terminal rendering helpers (rich)."""
+from datetime import datetime, timezone
+from rich.table import Table
+from rich.tree import Tree
+from rich.text import Text
+
+from crypttrace.labels import labels
+from crypttrace import config, prices
+
+
+def _ts(unix: str) -> str:
+    try:
+        return datetime.fromtimestamp(int(unix), tz=timezone.utc).strftime("%Y-%m-%d %H:%M")
+    except (ValueError, TypeError):
+        return "?"
+
+
+def addr_label(address: str) -> Text:
+    """Coloured address with icon + known label."""
+    t = labels.type_of(address)
+    color = {
+        "sanctioned": "bold red", "mixer": "magenta", "scam": "bold red",
+        "bridge": "cyan", "exchange": "green", "unknown": "white",
+    }.get(t, "white")
+    name = labels.label_of(address)
+    short = address[:10] + "…" + address[-6:]
+    txt = Text()
+    txt.append(labels.icon(address) + " ")
+    txt.append(short, style=color)
+    if name:
+        txt.append(f"  [{name}]", style=color + " dim")
+    return txt
+
+
+def profile_table(address: str, chain: str, balance: float, txs: list,
+                  native_price=None) -> Table:
+    t = Table(title=f"Profile — {address}  ({chain})", show_header=True, header_style="bold")
+    t.add_column("Field")
+    t.add_column("Value")
+    bal_usd = prices.usd(balance, native_price)
+    bal_str = f"{balance:.6f} (native)"
+    if bal_usd is not None:
+        bal_str += f"  ≈ {prices.fmt_usd(bal_usd)}"
+    t.add_row("Balance", bal_str)
+    t.add_row("Total txs (fetched)", str(len(txs)))
+    if txs:
+        t.add_row("First seen", _ts(txs[-1]["timeStamp"]))
+        t.add_row("Last seen", _ts(txs[0]["timeStamp"]))
+    hit = labels.lookup(address)
+    if hit:
+        t.add_row("Label", f"{hit['name']} ({hit['type']})")
+    t.add_row("Risk score", f"{labels.risk_score(address)}/100")
+    return t
+
+
+def counterparties_table(address: str, txs: list, top: int = 10) -> Table:
+    """Aggregate value moved per counterparty."""
+    me = address.lower()
+    agg = {}  # counterparty -> [in_value, out_value, count]
+    for tx in txs:
+        frm, to = tx.get("from", "").lower(), tx.get("to", "").lower()
+        val = int(tx.get("value", 0)) / config.WEI
+        other = to if frm == me else frm
+        if not other:
+            continue
+        rec = agg.setdefault(other, [0.0, 0.0, 0])
+        if frm == me:
+            rec[1] += val  # outgoing
+        else:
+            rec[0] += val  # incoming
+        rec[2] += 1
+    rows = sorted(agg.items(), key=lambda kv: kv[1][0] + kv[1][1], reverse=True)[:top]
+
+    t = Table(title="Top counterparties", header_style="bold")
+    t.add_column("Address")
+    t.add_column("In", justify="right")
+    t.add_column("Out", justify="right")
+    t.add_column("Txs", justify="right")
+    for other, (vin, vout, cnt) in rows:
+        t.add_row(addr_label(other), f"{vin:.4f}", f"{vout:.4f}", str(cnt))
+    return t
+
+
+def profile_rows_table(address: str, chain: str, balance: float, rows: list,
+                       native_price=None, symbol: str = "") -> Table:
+    """Profile built from normalized transfer rows (works on every chain)."""
+    t = Table(title=f"Profile — {address}  ({chain})", show_header=True, header_style="bold")
+    t.add_column("Field")
+    t.add_column("Value")
+    bal_usd = prices.usd(balance, native_price)
+    bal_str = f"{balance:.8f} {symbol}".rstrip()
+    if bal_usd is not None:
+        bal_str += f"  ≈ {prices.fmt_usd(bal_usd)}"
+    t.add_row("Balance", bal_str)
+    t.add_row("Transfers (fetched)", str(len(rows)))
+    if rows:
+        t.add_row("First seen", _ts(str(rows[-1].get("timestamp", 0))))
+        t.add_row("Last seen", _ts(str(rows[0].get("timestamp", 0))))
+    hit = labels.lookup(address)
+    if hit:
+        t.add_row("Label", f"{hit['name']} ({hit['type']})")
+    t.add_row("Risk score", f"{labels.risk_score(address)}/100")
+    return t
+
+
+def counterparties_rows_table(address: str, chain: str, rows: list, top: int = 10) -> Table:
+    """Counterparties from normalized rows (works on every chain)."""
+    me = address if chain in ("btc", "tron", "sol") else address.lower()
+    agg = {}
+    for r in rows:
+        frm, to = r.get("from", ""), r.get("to", "")
+        other = to if frm == me else frm
+        if not other:
+            continue
+        rec = agg.setdefault(other, [0.0, 0.0, 0])
+        if frm == me:
+            rec[1] += r.get("value", 0.0)
+        else:
+            rec[0] += r.get("value", 0.0)
+        rec[2] += 1
+    ranked = sorted(agg.items(), key=lambda kv: kv[1][0] + kv[1][1], reverse=True)[:top]
+
+    t = Table(title="Top counterparties", header_style="bold")
+    t.add_column("Address")
+    t.add_column("In", justify="right")
+    t.add_column("Out", justify="right")
+    t.add_column("Txs", justify="right")
+    for other, (vin, vout, cnt) in ranked:
+        t.add_row(addr_label(other), f"{vin:.4f}", f"{vout:.4f}", str(cnt))
+    return t
+
+
+def sources_table(rows: list, symbol: str, top: int = 25) -> Table:
+    """Addresses that fed a wallet — in a mass theft, the victim list."""
+    t = Table(title=f"Addresses that sent funds here (top {min(top, len(rows))} of {len(rows)})",
+              header_style="bold")
+    t.add_column("Address")
+    t.add_column("Hop", justify="right")
+    t.add_column(f"Sent ({symbol})", justify="right")
+    t.add_column("Txs", justify="right")
+    t.add_column("When (UTC)")
+    for r in rows[:top]:
+        t.add_row(addr_label(r["address"]), str(r.get("hop", 1)),
+                  f"{r['value']:.8f}".rstrip("0").rstrip("."), str(r["txs"]),
+                  _ts(str(r.get("first_ts") or 0)))
+    return t
+
+
+def timeline_chart(tl: dict, symbol: str, width: int = 42) -> Table:
+    """Text histogram of activity over time."""
+    t = Table(title="Activity over time", header_style="bold", box=None, pad_edge=False)
+    t.add_column("From (UTC)")
+    t.add_column("Transfers", justify="right")
+    t.add_column("")
+    t.add_column(f"In ({symbol})", justify="right")
+    t.add_column(f"Out ({symbol})", justify="right")
+    peak = max((b["count"] for b in tl["buckets"]), default=0) or 1
+    for b in tl["buckets"]:
+        if b["count"] == 0:
+            continue
+        bar = "█" * max(1, int(b["count"] / peak * width))
+        t.add_row(_ts(str(b["start"])), str(b["count"]),
+                  f"[cyan]{bar}[/cyan]",
+                  f"{b['in']:.4f}" if b["in"] else "",
+                  f"{b['out']:.4f}" if b["out"] else "")
+    return t
+
+
+def cluster_table(address: str, peers: list) -> Table:
+    """Bitcoin common-input-ownership clustering results."""
+    t = Table(title=f"Likely same-owner addresses — {address}", header_style="bold")
+    t.add_column("Address")
+    t.add_column("Co-signed inputs", justify="right")
+    for a, n in peers:
+        t.add_row(addr_label(a), str(n))
+    return t
+
+
+def crosschain_tree(address: str, chain: str, results: list) -> Tree:
+    """Render bridge-outs and their likely cross-chain continuations."""
+    root = Tree(Text.assemble(addr_label(address), Text(f"  (source chain: {chain})")))
+    for r in results:
+        out = r["bridge_out"]
+        when = _ts(str(out["timestamp"]))
+        bnode = root.add(Text(f"🌉 bridged {out['amount']:.4f} via {out['bridge']}  ({when})",
+                              style="cyan"))
+        if not r["arrivals"]:
+            bnode.add(Text("↳ no matching arrival found on other chains "
+                           "(try a wider --window / --tol, or funds bridged as a token)",
+                           style="dim"))
+            continue
+        for a in r["arrivals"]:
+            bnode.add(Text.assemble(
+                Text(f"↳ likely continued on {a['chain'].upper()}: received "
+                     f"{a['amount']:.4f} ", style="green"),
+                Text(f"(+{a['delay_min']:.0f} min, from "),
+                addr_label(a["from"]),
+                Text(")"),
+            ))
+    return root
+
+
+def funding_tree(address: str, hops: list) -> Tree:
+    """Render a backward funding chain: target ← funder ← funder …"""
+    root = Tree(addr_label(address))
+    if not hops:
+        root.add(Text("no inbound funding tx found (first-funded internally, or too old)",
+                      style="dim"))
+        return root
+    node = root
+    for h in hops:
+        when = _ts(h["timestamp"])
+        edge = Text(f"◀── funded by {h['value']:.4f} ETH  ({when})  ")
+        node = node.add(Text.assemble(edge, addr_label(h["funder"])))
+        if h["terminal"]:
+            kind = h["funder_type"]
+            note = {"exchange": "KYC identification point",
+                    "mixer": "mixer — trail obscured",
+                    "sanctioned": "sanctioned entity",
+                    "bridge": "cross-chain bridge"}.get(kind, kind)
+            node.add(Text(f"↳ chain ends at {kind} ({note})", style="dim"))
+    return root
+
+
+def holdings_table(address: str, chain: str, holdings: list) -> Table:
+    """Token holdings with per-token and total USD value."""
+    t = Table(title=f"Token holdings — {address}  ({chain})", header_style="bold")
+    t.add_column("Token")
+    t.add_column("Amount", justify="right")
+    t.add_column("USD", justify="right")
+    t.add_column("Txs", justify="right")
+    total = 0.0
+    for h in holdings:
+        price = prices.token_price(h["contract"], chain, h["symbol"])
+        usd = prices.usd(h["net"], price)
+        if usd is not None:
+            total += usd
+        t.add_row(h["symbol"], f"{h['net']:.4f}", prices.fmt_usd(usd), str(h["txs"]))
+    t.add_section()
+    t.add_row("[bold]Total[/bold]", "", f"[bold]{prices.fmt_usd(total)}[/bold]", "")
+    return t