crypttrace 0.2.0__py3-none-any.whl

crypttrace/report.py

@@ -0,0 +1,175 @@
+"""Generate a full investigation report (Markdown + JSON) for an address.
+
+Runs the same analysis as `profile` + `trace`, then writes a self-contained
+report to a folder the user can easily find (default: ~/crypttrace-reports).
+"""
+import json
+from datetime import datetime, timezone
+from pathlib import Path
+
+from rich.console import Console
+
+from crypttrace import __version__, config, prices
+from crypttrace.fetchers import etherscan
+from crypttrace.labels import labels
+from crypttrace import trace as trace_mod
+
+
+def _now() -> str:
+    return datetime.now(timezone.utc).strftime("%Y-%m-%d %H:%M UTC")
+
+
+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 _counterparties(address: str, txs: list, top: int = 15):
+    me = address.lower()
+    agg = {}
+    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
+        else:
+            rec[0] += val
+        rec[2] += 1
+    rows = sorted(agg.items(), key=lambda kv: kv[1][0] + kv[1][1], reverse=True)[:top]
+    return [
+        {"address": a, "in": round(vin, 6), "out": round(vout, 6), "txs": cnt,
+         "label": labels.label_of(a), "type": labels.type_of(a)}
+        for a, (vin, vout, cnt) in rows
+    ]
+
+
+def _tree_text(tree) -> str:
+    """Render the rich trace tree to plain text (ANSI stripped)."""
+    con = Console(record=True, width=100, file=None)
+    with con.capture() as cap:
+        con.print(tree)
+    return cap.get()
+
+
+def _headline(findings: list) -> str:
+    types = {f["type"] for f in findings}
+    if "sanctioned" in types:
+        return ("Funds from this address reach a **sanctioned / known-criminal wallet** — "
+                "escalate to law enforcement.")
+    if "mixer" in types:
+        return ("Funds from this address flow into a **mixer** (privacy pool), where on-chain "
+                "tracing terminates. Recovery from here requires timing/amount heuristics or "
+                "off-chain data.")
+    if "exchange" in types:
+        return ("Funds from this address reach a **centralised exchange** — a KYC handoff point. "
+                "Identifying the owner requires a legal request to that exchange.")
+    return ("No labelled entities were reached within the traced depth. Increase --depth or "
+            "extend the label database, then re-run.")
+
+
+def generate(address: str, chain: str, depth: int, branching: int,
+             out_dir: Path, asset=None) -> Path:
+    balance = etherscan.get_balance(address, chain)
+    txs = etherscan.get_txs(address, chain, limit=1000)
+    tree, findings = trace_mod.build(address, chain, depth, branching, asset)
+
+    # de-duplicate findings by address, keep highest value_reached
+    uniq = {}
+    for f in findings:
+        cur = uniq.get(f["address"])
+        if cur is None or f["value_reached"] > cur["value_reached"]:
+            uniq[f["address"]] = f
+    findings = sorted(uniq.values(), key=lambda f: f["risk"], reverse=True)
+
+    counterparties = _counterparties(address, txs)
+    hit = labels.lookup(address)
+
+    data = {
+        "tool": f"crypttrace v{__version__}",
+        "generated": _now(),
+        "subject": address,
+        "chain": chain,
+        "trace_depth": depth,
+        "trace_branching": branching,
+        "summary": {
+            "balance_native": round(balance, 6),
+            "txs_analysed": len(txs),
+            "first_seen": _ts(txs[-1]["timeStamp"]) if txs else None,
+            "last_seen": _ts(txs[0]["timeStamp"]) if txs else None,
+            "label": hit["name"] if hit else None,
+            "type": labels.type_of(address),
+            "risk_score": labels.risk_score(address),
+        },
+        "traced_asset": asset["symbol"] if asset else "ETH (native)",
+        "key_findings": findings,
+        "top_counterparties": counterparties,
+    }
+
+    out_dir.mkdir(parents=True, exist_ok=True)
+    stamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+    base = f"{chain}_{address[:10]}_{stamp}"
+    json_path = out_dir / f"{base}.json"
+    md_path = out_dir / f"{base}.md"
+
+    json_path.write_text(json.dumps(data, indent=2), encoding="utf-8")
+    md_path.write_text(_render_md(data, _tree_text(tree), json_path.name), encoding="utf-8")
+    return md_path
+
+
+def _render_md(d: dict, tree_text: str, json_name: str) -> str:
+    s = d["summary"]
+    L = []
+    L.append(f"# crypttrace investigation report\n")
+    L.append(f"**Generated:** {d['generated']}  •  **Tool:** {d['tool']}  \n")
+    L.append(f"**Subject:** `{d['subject']}`  •  **Chain:** {d['chain']}  •  "
+             f"**Traced asset:** {d.get('traced_asset', 'ETH (native)')}\n")
+
+    L.append(f"\n## Assessment\n")
+    L.append(_headline(d["key_findings"]) + "\n")
+
+    L.append(f"\n## Summary\n")
+    L.append(f"| Field | Value |\n|---|---|\n")
+    L.append(f"| Balance | {s['balance_native']} (native) |\n")
+    L.append(f"| Transactions analysed | {s['txs_analysed']} |\n")
+    L.append(f"| First seen | {s['first_seen']} |\n")
+    L.append(f"| Last seen | {s['last_seen']} |\n")
+    L.append(f"| Label | {s['label'] or '—'} |\n")
+    L.append(f"| Risk score | {s['risk_score']}/100 |\n")
+
+    L.append(f"\n## Key findings\n")
+    if d["key_findings"]:
+        L.append("Labelled entities reached while tracing funds outward from the subject:\n\n")
+        L.append("| Entity | Type | Risk | Value reached | ≈ USD |\n|---|---|---|---|---|\n")
+        for f in d["key_findings"]:
+            sym = f.get("symbol", "")
+            usd = prices.fmt_usd(f.get("usd_reached"))
+            L.append(f"| {f['label']} | {f['type']} | {f['risk']}/100 | "
+                     f"{f['value_reached']} {sym} | {usd} |\n")
+    else:
+        L.append("_None within the traced depth._\n")
+
+    L.append(f"\n## Top counterparties\n")
+    L.append("| Address | Label | In | Out | Txs |\n|---|---|---|---|---|\n")
+    for c in d["top_counterparties"]:
+        L.append(f"| `{c['address']}` | {c['label'] or '—'} | {c['in']} | {c['out']} | {c['txs']} |\n")
+
+    L.append(f"\n## Fund-flow trace (depth {d['trace_depth']})\n")
+    L.append("```\n" + tree_text.rstrip() + "\n```\n")
+
+    L.append(f"\n## Methodology & limitations\n")
+    L.append(
+        "Data is sourced from the public blockchain via Etherscan. Tracing follows the largest "
+        "outgoing transfers from each address and stops at identifiable entities (exchanges, "
+        "mixers, sanctioned wallets). Note: the blockchain is pseudonymous — reaching an address "
+        "does not identify its owner. Mixers sever the on-chain trail; exchanges require a legal "
+        "request to attribute ownership. This report is an investigative aid, not proof of "
+        "wrongdoing.\n")
+
+    L.append(f"\n---\n_Raw structured data: `{json_name}` (same folder)._\n")
+    return "".join(L)

crypttrace/store.py

@@ -0,0 +1,215 @@
+"""Local store of normalized transfers.
+
+Until now every command re-fetched from the network, so looking at the same
+case from a second angle meant paying for the whole traversal again — and the
+depth of an investigation was capped by how much could be held in memory during
+one run.
+
+This keeps what was already fetched in SQLite, in the same normalized shape the
+rest of the tool uses. Three things follow from that:
+
+  * re-analysis is instant and works with the network unplugged;
+  * a trace can be resumed or extended instead of restarted;
+  * addresses can be queried *across* each other in SQL, which is what a
+    multi-address case needs — the merging we previously did by hand.
+
+Rows are deduplicated by content, so fetching the same transaction from both
+ends of it stores one copy.
+"""
+import hashlib
+import sqlite3
+import time
+from pathlib import Path
+from typing import Dict, List, Optional
+
+from crypttrace import config
+
+DB_PATH: Path = config.DATA_DIR / "transfers.sqlite"
+
+# how long stored data is considered current before we go back to the network
+DEFAULT_MAX_AGE = 24 * 3600
+
+
+def _conn() -> sqlite3.Connection:
+    c = sqlite3.connect(DB_PATH)
+    c.execute("PRAGMA journal_mode=WAL")
+    c.executescript("""
+        CREATE TABLE IF NOT EXISTS transfers (
+            id        TEXT PRIMARY KEY,
+            chain     TEXT NOT NULL,
+            tx_hash   TEXT,
+            from_addr TEXT,
+            to_addr   TEXT,
+            value     REAL,
+            symbol    TEXT,
+            contract  TEXT,
+            ts        INTEGER,
+            fee_share REAL
+        );
+        CREATE INDEX IF NOT EXISTS ix_to   ON transfers(chain, to_addr);
+        CREATE INDEX IF NOT EXISTS ix_from ON transfers(chain, from_addr);
+        CREATE INDEX IF NOT EXISTS ix_ts   ON transfers(ts);
+
+        CREATE TABLE IF NOT EXISTS fetched (
+            chain      TEXT NOT NULL,
+            address    TEXT NOT NULL,
+            asset      TEXT NOT NULL DEFAULT '',
+            fetched_at INTEGER,
+            rows       INTEGER,
+            complete   INTEGER,
+            PRIMARY KEY (chain, address, asset)
+        );
+    """)
+    return c
+
+
+def _row_id(chain: str, r: dict) -> str:
+    """Content hash — the same transfer seen from either side stores once."""
+    key = "|".join([
+        chain, str(r.get("hash", "")), str(r.get("from", "")), str(r.get("to", "")),
+        str(r.get("symbol", "")), f"{float(r.get('value', 0)):.12f}",
+    ])
+    return hashlib.sha1(key.encode()).hexdigest()
+
+
+def save(chain: str, address: str, rows: List[dict], asset_key: str = "",
+         complete: bool = True) -> int:
+    """Persist transfers and note that this address was fetched."""
+    c = _conn()
+    try:
+        c.executemany(
+            "INSERT OR REPLACE INTO transfers"
+            "(id,chain,tx_hash,from_addr,to_addr,value,symbol,contract,ts,fee_share)"
+            " VALUES (?,?,?,?,?,?,?,?,?,?)",
+            [(_row_id(chain, r), chain, r.get("hash", ""), r.get("from", ""),
+              r.get("to", ""), float(r.get("value", 0) or 0), r.get("symbol", ""),
+              r.get("contract", ""), int(r.get("timestamp", 0) or 0),
+              float(r.get("fee_share", 0) or 0)) for r in rows])
+        c.execute("INSERT OR REPLACE INTO fetched(chain,address,asset,fetched_at,rows,complete)"
+                  " VALUES (?,?,?,?,?,?)",
+                  (chain, address, asset_key, int(time.time()), len(rows), int(complete)))
+        c.commit()
+        return len(rows)
+    finally:
+        c.close()
+
+
+def age(chain: str, address: str, asset_key: str = "") -> Optional[int]:
+    """Seconds since this address was last fetched, or None if never."""
+    c = _conn()
+    try:
+        row = c.execute("SELECT fetched_at FROM fetched WHERE chain=? AND address=? AND asset=?",
+                        (chain, address, asset_key)).fetchone()
+    finally:
+        c.close()
+    return None if not row else int(time.time()) - row[0]
+
+
+def is_fresh(chain: str, address: str, asset_key: str = "",
+             max_age: int = DEFAULT_MAX_AGE) -> bool:
+    a = age(chain, address, asset_key)
+    return a is not None and a <= max_age
+
+
+def load(chain: str, address: str, contract: str = "", native_symbol: str = "") -> List[dict]:
+    """Every stored transfer touching this address, newest first."""
+    c = _conn()
+    try:
+        if contract:
+            q = ("SELECT from_addr,to_addr,value,symbol,contract,ts,tx_hash,fee_share"
+                 " FROM transfers WHERE chain=? AND (from_addr=? OR to_addr=?)"
+                 " AND lower(contract)=lower(?) ORDER BY ts DESC")
+            args = (chain, address, address, contract)
+        else:
+            # native asset: rows carry no contract
+            q = ("SELECT from_addr,to_addr,value,symbol,contract,ts,tx_hash,fee_share"
+                 " FROM transfers WHERE chain=? AND (from_addr=? OR to_addr=?)"
+                 " AND (contract IS NULL OR contract='') ORDER BY ts DESC")
+            args = (chain, address, address)
+        rows = c.execute(q, args).fetchall()
+    finally:
+        c.close()
+    out = []
+    for f, t, v, sym, con, ts, h, fee in rows:
+        r = {"from": f, "to": t, "value": v, "symbol": sym,
+             "timestamp": ts, "hash": h}
+        if con:
+            r["contract"] = con
+        if fee:
+            r["fee_share"] = fee
+        out.append(r)
+    return out
+
+
+# ---- queries that span addresses (what a multi-address case needs) ----
+
+def sources_of(chain: str, addresses: List[str], min_value: float = 0.0) -> List[dict]:
+    """Everyone who funded any of these addresses, aggregated — across a whole case."""
+    if not addresses:
+        return []
+    marks = ",".join("?" * len(addresses))
+    c = _conn()
+    try:
+        rows = c.execute(
+            f"SELECT from_addr, SUM(value), COUNT(*), MIN(ts), MAX(ts)"
+            f" FROM transfers WHERE chain=? AND to_addr IN ({marks})"
+            f" AND value >= ? AND from_addr NOT IN ({marks})"
+            f" GROUP BY from_addr ORDER BY SUM(value) DESC",
+            (chain, *addresses, min_value, *addresses)).fetchall()
+    finally:
+        c.close()
+    return [{"address": a, "value": v, "txs": n, "first_ts": lo, "last_ts": hi}
+            for a, v, n, lo, hi in rows]
+
+
+def path_exists(chain: str, src: str, dst: str, max_hops: int = 4) -> Optional[List[str]]:
+    """Shortest stored path of transfers from src to dst — 'are these connected?'"""
+    c = _conn()
+    try:
+        frontier = {src: [src]}
+        seen = {src}
+        for _ in range(max_hops):
+            if not frontier:
+                break
+            marks = ",".join("?" * len(frontier))
+            rows = c.execute(
+                f"SELECT from_addr, to_addr FROM transfers"
+                f" WHERE chain=? AND from_addr IN ({marks})",
+                (chain, *frontier.keys())).fetchall()
+            nxt = {}
+            for f, t in rows:
+                if not t or t in seen:
+                    continue
+                p = frontier[f] + [t]
+                if t == dst:
+                    return p
+                seen.add(t)
+                nxt[t] = p
+            frontier = nxt
+    finally:
+        c.close()
+    return None
+
+
+def stats() -> Dict:
+    c = _conn()
+    try:
+        transfers = c.execute("SELECT COUNT(*) FROM transfers").fetchone()[0]
+        addresses = c.execute("SELECT COUNT(*) FROM fetched").fetchone()[0]
+        chains = c.execute("SELECT chain, COUNT(*) FROM transfers GROUP BY chain").fetchall()
+        oldest = c.execute("SELECT MIN(fetched_at) FROM fetched").fetchone()[0]
+    finally:
+        c.close()
+    return {"transfers": transfers, "addresses": addresses,
+            "by_chain": dict(chains), "oldest_fetch": oldest,
+            "path": str(DB_PATH),
+            "size_bytes": DB_PATH.stat().st_size if DB_PATH.exists() else 0}
+
+
+def clear() -> None:
+    c = _conn()
+    try:
+        c.executescript("DELETE FROM transfers; DELETE FROM fetched;")
+        c.commit()
+    finally:
+        c.close()

crypttrace/trace.py

@@ -0,0 +1,165 @@
+"""Fund-flow tracing: follow outgoing value (native coin or a token) N hops deep."""
+from typing import Optional
+from rich.tree import Tree
+from rich.text import Text
+
+from crypttrace.fetchers import etherscan
+from crypttrace.labels import labels
+from crypttrace import config, render, assets, prices, offramp
+
+
+def _outflows(address, chain, top, asset, direction="out"):
+    """Flows for one asset on any supported chain (native coin or a token)."""
+    from crypttrace import chains
+    return chains.flows(address, chain, top, direction, asset=asset)
+
+
+class _Ctx:
+    """Holds constant tracing context so it isn't threaded through every arg."""
+    def __init__(self, chain, branching, asset, symbol, price, direction="out"):
+        self.chain = chain
+        self.branching = branching
+        self.asset = asset
+        self.symbol = symbol
+        self.price = price
+        self.direction = direction
+
+
+def _edge_text(ctx, to, val, cnt):
+    usd = prices.fmt_usd(prices.usd(val, ctx.price))
+    money = f"{val:.4f} {ctx.symbol}"
+    tail = f" ≈{usd}" if ctx.price is not None else ""
+    arrow = "──▶ " if ctx.direction == "out" else "◀── "
+    return Text.assemble(Text(f"──{money} ({cnt} tx){tail}{arrow}"), render.addr_label(to))
+
+
+def _record_finding(findings, ctx, to, val, cnt):
+    if findings is None:
+        return
+    hit = labels.lookup(to)
+    if not hit:
+        return
+    findings.append({"address": to, "type": hit["type"], "label": hit["name"],
+                     "risk": labels.risk_score(to), "value_reached": round(val, 6),
+                     "symbol": ctx.symbol, "usd_reached": prices.usd(val, ctx.price),
+                     "tx_count": cnt})
+
+
+def _expand(node, address, ctx, depth, seen, findings=None, is_root=False):
+    if depth <= 0:
+        return
+    if address.lower() in seen:
+        node.add(Text("↳ already visited (cycle)", style="dim")); return
+    seen.add(address.lower())
+    if not is_root and labels.type_of(address) in ("exchange", "mixer", "sanctioned"):
+        node.add(Text("↳ trail ends here (identifiable entity — subpoena / off-chain)", style="dim"))
+        return
+    if not is_root and labels.type_of(address) == "bridge":
+        node.add(Text("↳ bridge — funds leave this chain; run `crypttrace crosschain` "
+                      "on the sender to find the destination chain", style="cyan"))
+        return
+    # Off-ramp heuristic: an unknown wallet that forwards most funds to an
+    # exchange is a deposit address — the cash-out / KYC point. Native only.
+    if not is_root and ctx.asset is None and labels.type_of(address) == "unknown":
+        off = offramp.detect(address, ctx.chain)
+        if off:
+            pct = int(off["fraction"] * 100)
+            node.add(Text(f"↳ off-ramp: ~{pct}% forwarded to {off['exchange']} "
+                          f"— likely a deposit address (KYC point)", style="green"))
+            if findings is not None:
+                findings.append({"address": address, "type": "offramp",
+                                 "label": f"{off['exchange']} deposit (off-ramp)",
+                                 "risk": 30, "value_reached": round(off["forwarded"], 6),
+                                 "symbol": ctx.symbol,
+                                 "usd_reached": prices.usd(off["forwarded"], ctx.price),
+                                 "tx_count": 0})
+            return
+    for to, val, cnt in _outflows(address, ctx.chain, ctx.branching, ctx.asset, ctx.direction):
+        _record_finding(findings, ctx, to, val, cnt)
+        child = node.add(_edge_text(ctx, to, val, cnt))
+        _expand(child, to, ctx, depth - 1, seen, findings)
+
+
+def build(address, chain, depth, branching, asset=None, direction="out"):
+    """Return (tree, findings). direction 'out' follows funds forward, 'in' traces their source."""
+    if asset is None:
+        from crypttrace import chains as _chains
+        symbol = _chains.symbol(chain)
+        price = prices.native_price(chain)
+    else:
+        symbol = asset["symbol"]
+        price = prices.token_price(asset["contract"], chain, symbol)
+    ctx = _Ctx(chain, branching, asset, symbol, price, direction)
+
+    root = Tree(render.addr_label(address))
+    findings = []
+    _expand(root, address, ctx, depth, set(), findings, is_root=True)
+    return root, findings
+
+
+def build_tree(address, chain, depth, branching, asset=None, direction="out"):
+    tree, _ = build(address, chain, depth, branching, asset, direction)
+    return tree
+
+
+def build_graph(address, chain, depth, branching, asset=None, direction="out"):
+    """Return {nodes, edges, symbol} for graph visualization (web UI).
+
+    direction 'out' follows where funds went; 'in' traces where they came from.
+    """
+    if asset is None:
+        from crypttrace import chains as _chains
+        symbol = _chains.symbol(chain)
+        price = prices.native_price(chain)
+    else:
+        symbol = asset["symbol"]
+        price = prices.token_price(asset["contract"], chain, symbol)
+
+    # Bitcoin / Tron / Solana addresses are case-sensitive (base58); only EVM
+    # addresses may be normalized to lowercase.
+    from crypttrace import chains as _c
+    _norm = (lambda a: a.lower()) if _c.is_evm(chain) else (lambda a: a)
+
+    nodes = {}
+    edges = []
+
+    def _node(addr, hop, is_root=False):
+        key = _norm(addr)
+        if key not in nodes:
+            nodes[key] = {
+                "id": key,
+                "short": addr[:10] + "…" + addr[-6:],
+                "type": labels.type_of(addr),
+                "label": labels.label_of(addr),
+                "root": is_root,
+                "terminal": False,
+                # hop distance from the investigated address — the renderer uses
+                # this as the layout level, which keeps the graph compact and
+                # ordered instead of letting the library invent deep levels.
+                "level": hop,
+            }
+        else:
+            nodes[key]["level"] = min(nodes[key]["level"], hop)
+        return nodes[key]
+
+    def _walk(addr, d, seen, is_root, hop=0):
+        _node(addr, hop, is_root)
+        key = _norm(addr)
+        if d <= 0 or key in seen:
+            return
+        seen.add(key)
+        if not is_root and labels.type_of(addr) in ("exchange", "mixer", "sanctioned", "bridge"):
+            nodes[key]["terminal"] = True
+            return
+        for to, val, cnt in _outflows(addr, chain, branching, asset, direction):
+            _node(to, hop + 1)
+            # arrows always point the way the money actually travelled
+            src, dst = (key, _norm(to)) if direction == "out" else (_norm(to), key)
+            edges.append({"from": src, "to": dst,
+                          "value": round(val, 4), "tx": cnt,
+                          "usd": prices.usd(val, price)})
+            _walk(to, d - 1, seen, False, hop + 1)
+
+    _walk(address, depth, set(), True, 0)
+    return {"nodes": list(nodes.values()), "edges": edges,
+            "symbol": symbol, "direction": direction}