crypttrace 0.2.0__py3-none-any.whl

crypttrace/__init__.py

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

crypttrace/addresses.py

@@ -0,0 +1,132 @@
+"""Address validation — checksums, not guesses.
+
+Every address format in use carries a checksum precisely so that a mistyped or
+corrupted address can be rejected rather than acted upon. A forensics tool has
+no excuse for skipping that check: a single wrong character turns a claim about
+one wallet into a claim about a different, usually non-existent one.
+
+This validates without any network access or third-party library, so it works
+on user input, on label files, and in tests.
+"""
+import hashlib
+from typing import Optional, Tuple
+
+BECH32_CHARSET = "qpzry9x8gf2tvdw0s3jn54khce6mua7l"
+B58_ALPHABET = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz"
+
+
+# ---------------------------------------------------------------- bech32
+
+def _bech32_polymod(values) -> int:
+    gen = [0x3b6a57b2, 0x26508e6d, 0x1ea119fa, 0x3d4233dd, 0x2a1462b3]
+    chk = 1
+    for v in values:
+        top = chk >> 25
+        chk = (chk & 0x1ffffff) << 5 ^ v
+        for i in range(5):
+            chk ^= gen[i] if ((top >> i) & 1) else 0
+    return chk
+
+
+def _hrp_expand(hrp: str):
+    return [ord(c) >> 5 for c in hrp] + [0] + [ord(c) & 31 for c in hrp]
+
+
+def check_bech32(addr: str, expected_hrp: str = "bc") -> Tuple[bool, str]:
+    """Validate a bech32 / bech32m address (BIP-173 / BIP-350)."""
+    if addr.lower() != addr and addr.upper() != addr:
+        return False, "mixed case is not allowed in bech32"
+    a = addr.lower()
+    pos = a.rfind("1")
+    if pos < 1 or pos + 7 > len(a) or len(a) > 90:
+        return False, "malformed: bad separator position or length"
+    hrp, data = a[:pos], a[pos + 1:]
+    if expected_hrp and hrp != expected_hrp:
+        return False, f"wrong network prefix '{hrp}' (expected '{expected_hrp}')"
+    if any(c not in BECH32_CHARSET for c in data):
+        return False, "contains characters not in the bech32 alphabet"
+    const = _bech32_polymod(_hrp_expand(hrp) + [BECH32_CHARSET.find(c) for c in data])
+    if const == 1:
+        return True, "bech32 checksum valid"
+    if const == 0x2bc830a3:
+        return True, "bech32m checksum valid"
+    return False, "checksum does not match — the address is mistyped or invented"
+
+
+# ---------------------------------------------------------------- base58check
+
+def _b58_decode(s: str) -> Optional[bytes]:
+    n = 0
+    for ch in s:
+        idx = B58_ALPHABET.find(ch)
+        if idx < 0:
+            return None
+        n = n * 58 + idx
+    raw = n.to_bytes((n.bit_length() + 7) // 8, "big") if n else b""
+    pad = len(s) - len(s.lstrip("1"))
+    return b"\x00" * pad + raw
+
+
+def check_base58check(addr: str, expect_prefix: Optional[bytes] = None) -> Tuple[bool, str]:
+    """Validate a base58check address (legacy Bitcoin, Tron)."""
+    raw = _b58_decode(addr)
+    if raw is None:
+        return False, "contains characters not in the base58 alphabet"
+    if len(raw) < 5:
+        return False, "too short to contain a checksum"
+    payload, checksum = raw[:-4], raw[-4:]
+    if hashlib.sha256(hashlib.sha256(payload).digest()).digest()[:4] != checksum:
+        return False, "checksum does not match — the address is mistyped or invented"
+    if expect_prefix and not payload.startswith(expect_prefix):
+        return False, f"unexpected version byte {payload[:1].hex()}"
+    return True, "base58check checksum valid"
+
+
+# ---------------------------------------------------------------- per chain
+
+def validate(address: str, chain: str) -> Tuple[bool, str]:
+    """Is this a well-formed address for this chain? Checks the checksum where one exists."""
+    a = (address or "").strip()
+    if not a:
+        return False, "empty address"
+
+    if chain in ("eth", "bsc", "polygon", "arbitrum", "optimism", "base"):
+        if not a.startswith("0x") or len(a) != 42:
+            return False, "EVM addresses are 0x followed by 40 hex characters"
+        if any(c not in "0123456789abcdefABCDEF" for c in a[2:]):
+            return False, "contains non-hexadecimal characters"
+        # EIP-55 mixed-case addresses carry a checksum; all-one-case ones don't
+        body = a[2:]
+        if body != body.lower() and body != body.upper():
+            return (True, "valid hex (EIP-55 capitalisation present but unverified)")
+        return True, "valid hex address (no checksum in this format)"
+
+    if chain == "btc":
+        if a.startswith(("bc1", "tb1")):
+            return check_bech32(a, "bc" if a.startswith("bc1") else "tb")
+        if a.startswith(("1", "3")):
+            return check_base58check(a)
+        return False, "not a recognised Bitcoin address format"
+
+    if chain == "tron":
+        if not a.startswith("T") or len(a) != 34:
+            return False, "Tron addresses start with T and are 34 characters"
+        return check_base58check(a, b"\x41")
+
+    if chain == "sol":
+        if not (32 <= len(a) <= 44):
+            return False, "Solana addresses are 32–44 base58 characters"
+        raw = _b58_decode(a)
+        if raw is None:
+            return False, "contains characters not in the base58 alphabet"
+        if len(raw) != 32:
+            return False, "does not decode to a 32-byte public key"
+        return True, "valid 32-byte key (Solana addresses carry no checksum)"
+
+    return False, f"unknown chain '{chain}'"
+
+
+def looks_like_txid(value: str) -> bool:
+    """64 hex characters — a transaction id, which people paste in by mistake."""
+    v = (value or "").strip()
+    return len(v) == 64 and all(c in "0123456789abcdefABCDEF" for c in v)

crypttrace/analysis.py

@@ -0,0 +1,222 @@
+"""Analytical views: *who* lost the money, and *when* it moved.
+
+Two things a fund-flow graph shows but can't hand you as evidence:
+
+  * the list of addresses that fed a consolidation wallet — in a mass theft
+    that list is the set of victims, and it belongs in a spreadsheet attached
+    to a police report, not only in a picture;
+  * the timing of the movement. A theft executed by an automated tool looks
+    completely different from an owner spending their own coins: hundreds of
+    transfers inside minutes, rather than spread over months.
+"""
+import csv
+from bisect import bisect_left, bisect_right
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Dict, List, Optional, Tuple
+
+from crypttrace import chains
+from crypttrace.labels import labels
+
+
+# Amounts below these are treated as dust: spam sent to well-known addresses to
+# pollute their history (and sometimes to deanonymise the owner). Left in, dust
+# drowns out the transfers an investigation is actually about.
+DUST = {"btc": 0.0005, "eth": 0.002, "bsc": 0.005, "polygon": 5.0,
+        "arbitrum": 0.002, "optimism": 0.002, "base": 0.002,
+        "tron": 5.0, "sol": 0.01}
+
+
+def dust_threshold(chain: str, asset: Optional[dict] = None) -> float:
+    if asset:                      # stablecoins: anything under a dollar is noise
+        return 1.0 if asset.get("stable") else 0.0
+    return DUST.get(chain, 0.0)
+
+
+def _ts(unix) -> str:
+    try:
+        return datetime.fromtimestamp(int(unix), tz=timezone.utc).strftime("%Y-%m-%d %H:%M")
+    except (ValueError, TypeError, OSError):
+        return "?"
+
+
+def _direct(address: str, chain: str, asset: Optional[dict], limit: int,
+            direction: str = "in", min_value: float = 0.0) -> Dict[str, dict]:
+    """Aggregate counterparties one hop away, keeping amounts and timestamps."""
+    me = chains.norm_addr(address, chain)
+    near, far = ("to", "from") if direction == "in" else ("from", "to")
+    agg: Dict[str, dict] = {}
+    for r in chains.transfers(address, chain, limit, asset=asset):
+        if r.get(near) != me:
+            continue
+        other = r.get(far)
+        val = r.get("value", 0) or 0
+        if not other or val <= 0 or val < min_value:
+            continue
+        rec = agg.setdefault(other, {"address": other, "value": 0.0, "txs": 0,
+                                     "first_ts": None, "last_ts": None})
+        rec["value"] += val
+        rec["txs"] += 1
+        ts = int(r.get("timestamp") or 0)
+        rec["first_ts"] = ts if rec["first_ts"] is None else min(rec["first_ts"], ts)
+        rec["last_ts"] = ts if rec["last_ts"] is None else max(rec["last_ts"], ts)
+    return agg
+
+
+def collect_sources(address: str, chain: str = "btc", depth: int = 1,
+                    asset: Optional[dict] = None, limit: int = 1000,
+                    max_addresses: int = 400,
+                    min_value: Optional[float] = None) -> List[dict]:
+    """Every address that fed `address`, walking back `depth` hops.
+
+    In a mass-drain incident this is the victim list. Results carry the hop
+    distance so direct senders can be told apart from earlier sources. Dust is
+    excluded by default — well-known addresses get spammed, and those senders
+    are not victims.
+    """
+    if min_value is None:
+        min_value = dust_threshold(chain, asset)
+
+    found: Dict[str, dict] = {}
+    frontier = [chains.norm_addr(address, chain)]
+    seen = {chains.norm_addr(address, chain)}
+
+    for hop in range(1, depth + 1):
+        next_frontier = []
+        for node in frontier:
+            if len(found) >= max_addresses:
+                break
+            try:
+                sources = _direct(node, chain, asset, limit, "in", min_value)
+            except chains.ChainError:
+                continue
+            for addr, rec in sources.items():
+                key = chains.norm_addr(addr, chain)
+                if key in found:
+                    found[key]["value"] += rec["value"]
+                    found[key]["txs"] += rec["txs"]
+                    continue
+                rec = dict(rec)
+                rec["hop"] = hop
+                rec["into"] = node
+                rec["label"] = labels.label_of(addr)
+                rec["type"] = labels.type_of(addr)
+                found[key] = rec
+                if key not in seen:
+                    seen.add(key)
+                    next_frontier.append(addr)
+        frontier = next_frontier
+        if not frontier or len(found) >= max_addresses:
+            break
+
+    return sorted(found.values(), key=lambda r: r["value"], reverse=True)
+
+
+def export_csv(rows: List[dict], path: Path, chain: str, symbol: str) -> Path:
+    """Write the source list to CSV — the form an exchange or police force wants."""
+    path.parent.mkdir(parents=True, exist_ok=True)
+    cols = ["address", "hop", f"amount_sent_{symbol}", "transactions",
+            "first_seen_utc", "last_seen_utc", "sent_into", "label", "explorer"]
+    with open(path, "w", newline="", encoding="utf-8") as fh:
+        w = csv.writer(fh)
+        w.writerow(cols)
+        for r in rows:
+            w.writerow([r["address"], r.get("hop", 1), round(r["value"], 8), r["txs"],
+                        _ts(r.get("first_ts")), _ts(r.get("last_ts")),
+                        r.get("into", ""), r.get("label", ""),
+                        chains.explorer_url(r["address"], chain)])
+    return path
+
+
+# ---------- timing ----------
+
+def tightest_window(timestamps: List[int], fraction: float = 0.8) -> Optional[Tuple[int, int, int, int]]:
+    """Shortest time span containing `fraction` of the events.
+
+    Returns (span_seconds, count, start_ts, end_ts). This is what separates an
+    automated sweep from normal wallet use: hundreds of transfers inside minutes.
+    `count` is every event inside the window, not just the `fraction` used to
+    find it: when many transfers share a timestamp, the window holds more.
+    """
+    ts = sorted(t for t in timestamps if t)
+    n = len(ts)
+    if n < 2:
+        return None
+    need = max(2, int(n * fraction))
+    best = None
+    for i in range(0, n - need + 1):
+        j = i + need - 1
+        span = ts[j] - ts[i]
+        if best is None or span < best[0]:
+            best = (span, ts[i], ts[j])
+    span, start, end = best
+    return span, bisect_right(ts, end) - bisect_left(ts, start), start, end
+
+
+def timeline(address: str, chain: str = "eth", asset: Optional[dict] = None,
+             limit: int = 1000, buckets: int = 24,
+             min_value: Optional[float] = None) -> dict:
+    """Bucketed in/out activity plus burst detection (dust excluded by default)."""
+    if min_value is None:
+        min_value = dust_threshold(chain, asset)
+    me = chains.norm_addr(address, chain)
+    rows = chains.transfers(address, chain, limit, asset=asset)
+    total_rows = len(rows)
+    events = [{"ts": int(r.get("timestamp") or 0),
+               "value": r.get("value", 0) or 0,
+               "dir": "out" if r.get("from") == me else "in"} for r in rows]
+    events = [e for e in events if e["ts"] > 0 and e["value"] >= min_value]
+    dust_skipped = total_rows - len(events)
+    if not events:
+        return {"events": 0, "buckets": [], "burst": None, "dust_skipped": dust_skipped,
+                "first_ts": None, "last_ts": None, "in_total": 0.0, "out_total": 0.0}
+
+    events.sort(key=lambda e: e["ts"])
+    first, last = events[0]["ts"], events[-1]["ts"]
+    span = max(1, last - first)
+    width = max(1, span // buckets)
+
+    # assign each event to exactly one bucket (clamping the final edge inwards),
+    # otherwise the last event lands in two buckets and gets counted twice
+    grid = [{"start": first + i * width, "end": first + (i + 1) * width,
+             "count": 0, "in": 0.0, "out": 0.0} for i in range(buckets)]
+    for e in events:
+        idx = min(buckets - 1, (e["ts"] - first) // width)
+        b = grid[idx]
+        b["count"] += 1
+        b["in" if e["dir"] == "in" else "out"] += e["value"]
+
+    return {
+        "events": len(events),
+        "buckets": grid,
+        "burst": tightest_window([e["ts"] for e in events]),
+        "dust_skipped": dust_skipped,
+        "first_ts": first, "last_ts": last,
+        "in_total": sum(e["value"] for e in events if e["dir"] == "in"),
+        "out_total": sum(e["value"] for e in events if e["dir"] == "out"),
+    }
+
+
+def describe_burst(burst, total_events: int) -> Optional[str]:
+    """Plain-language read on the timing, if it looks automated."""
+    if not burst:
+        return None
+    span, count, start, end = burst
+    if span <= 0:
+        if count >= total_events:
+            return f"All {count} transfers share one timestamp — a single batched operation."
+        return (f"{count} of {total_events} transfers share one timestamp "
+                f"({_ts(start)} UTC) — a single batched operation.")
+    minutes = span / 60
+    rate = count / max(minutes, 0.01)
+    when = f"{_ts(start)} → {_ts(end)} UTC"
+    if minutes <= 90 and count >= 20:
+        return (f"{count} of {total_events} transfers happened inside "
+                f"{minutes:.0f} minutes ({when}), about {rate:.0f} per minute. "
+                "That rate is characteristic of an automated tool spending keys it "
+                "already holds, not of an owner moving their own funds.")
+    if minutes <= 60 * 24:
+        return (f"{count} of {total_events} transfers fall inside {minutes/60:.1f} hours ({when})."
+                " Activity is concentrated rather than spread out.")
+    return (f"Activity is spread over {minutes/60/24:.0f} days — no burst pattern, "
+            "which is what ordinary wallet use looks like.")

crypttrace/assess.py

@@ -0,0 +1,273 @@
+"""Assessment — turning observations into a stated conclusion.
+
+Collecting public data and drawing a graph is collection. Intelligence is the
+step after: saying what the data supports, how strongly, and on what evidence.
+
+So every signal here carries four things — what was *observed*, what it
+*implies*, how *confident* we are, and the numbers a reader can check. The
+overall confidence is deliberately reduced when the underlying figures could
+not be reconciled with the chain, or when the labels involved carry no source.
+An assessment that cannot be checked should not sound certain.
+"""
+import math
+from collections import Counter
+from dataclasses import dataclass, field, asdict
+from typing import Dict, List, Optional
+
+from crypttrace import analysis, chains
+from crypttrace.labels import labels
+
+
+@dataclass
+class Signal:
+    name: str
+    observed: str
+    implication: str
+    confidence: str          # high / medium / low
+    weight: int              # contribution to the risk figure
+    evidence: dict = field(default_factory=dict)
+
+
+CONF_ORDER = {"high": 3, "medium": 2, "low": 1}
+
+
+# ---------------------------------------------------------------- detectors
+
+def constant_fee_signature(values: List[float], min_hits: int = 5) -> Optional[dict]:
+    """Do the amounts look like round sums minus one fixed fee?
+
+    A person sends round-ish numbers. An automated sweeper takes whatever is in
+    a wallet and subtracts a hardcoded fee, so the *gap to the next round
+    number* repeats exactly across unrelated victims. That repetition is the
+    fingerprint — it found the 3,300-sat fee in the Coldcard case by hand.
+    """
+    deltas = Counter()
+    for v in values:
+        if v <= 0:
+            continue
+        for step in (1.0, 0.5, 0.1, 0.05, 0.01):
+            up = math.ceil(round(v / step, 9)) * step
+            d = round(up - v, 8)
+            if 0 < d < step * 0.5:
+                deltas[d] += 1
+                break
+    if not deltas:
+        return None
+    delta, hits = deltas.most_common(1)[0]
+    total = len([v for v in values if v > 0])
+    if hits < min_hits or total == 0 or hits / total < 0.10:
+        return None
+    return {"fee": delta, "hits": hits, "of": total, "share": hits / total}
+
+
+def repeated_amounts(values: List[float], min_repeat: int = 3) -> List[tuple]:
+    """Identical amounts arriving from unrelated addresses — batch automation."""
+    c = Counter(round(v, 8) for v in values if v > 0)
+    return [(amt, n) for amt, n in c.most_common(5) if n >= min_repeat]
+
+
+def burst(timestamps: List[int], fraction: float = 0.8) -> Optional[tuple]:
+    """(span_seconds, count, start_ts, end_ts) of the tightest burst; None under 5 events."""
+    if sum(1 for t in timestamps if t) < 5:
+        return None
+    return analysis.tightest_window(timestamps, fraction)
+
+
+# ---------------------------------------------------------------- assessment
+
+def assess(address: str, chain: str = "eth", asset: Optional[dict] = None,
+           depth: int = 2, branching: int = 5) -> Dict:
+    """Produce a reasoned assessment of an address, with evidence."""
+    from crypttrace import verify as verify_mod
+
+    me = chains.norm_addr(address, chain)
+    signals: List[Signal] = []
+    caveats: List[str] = []
+
+    # --- what the address itself is -----------------------------------
+    hit = labels.lookup(address)
+    sourced = bool(hit and hit.get("source"))
+    if hit:
+        kind = hit.get("type", "unknown")
+        conf = "high" if sourced else "medium"
+        weight = {"sanctioned": 60, "mixer": 45, "scam": 55,
+                  "bridge": 10, "exchange": 5}.get(kind, 0)
+        signals.append(Signal(
+            name="known entity",
+            observed=f"address is labelled '{hit['name']}'",
+            implication={"sanctioned": "on an international sanctions list",
+                         "mixer": "a privacy service that breaks the on-chain trail",
+                         "scam": "tied to a recorded theft or fraud",
+                         "exchange": "a custodial service that holds customer identity",
+                         "bridge": "a cross-chain bridge"}.get(kind, "a known service"),
+            confidence=conf, weight=weight,
+            evidence={"label": hit["name"], "source": hit.get("source", ""),
+                      "source_kind": hit.get("source_kind", "")}))
+        if not sourced:
+            caveats.append("the label on this address carries no recorded source, "
+                           "so it is inherited rather than evidenced")
+
+    # --- flows --------------------------------------------------------
+    try:
+        rows = chains.transfers(address, chain, 1000, asset=asset)
+    except chains.ChainError as e:
+        return {"address": address, "chain": chain, "error": str(e),
+                "signals": [], "risk": 0, "confidence": "none"}
+
+    inbound = [r for r in rows if r.get("to") == me]
+    outbound = [r for r in rows if r.get("from") == me]
+    received = sum(r.get("value", 0) for r in inbound)
+    sent = sum(r.get("value", 0) for r in outbound)
+
+    # --- automation ----------------------------------------------------
+    fee_sig = constant_fee_signature([r.get("value", 0) for r in inbound])
+    if fee_sig:
+        signals.append(Signal(
+            name="automated collection",
+            observed=(f"{fee_sig['hits']} of {fee_sig['of']} incoming amounts are a round "
+                      f"figure minus exactly {fee_sig['fee']:.8f}"),
+            implication="funds were swept by a tool with a hardcoded fee, not moved by owners",
+            confidence="high" if fee_sig["share"] > 0.3 else "medium",
+            weight=35, evidence=fee_sig))
+
+    b = burst([int(r.get("timestamp") or 0) for r in inbound])
+    if b and b[0] > 0:
+        span_min = b[0] / 60
+        rate = b[1] / max(span_min, 0.01)
+        if span_min <= 90 and b[1] >= 20:
+            signals.append(Signal(
+                name="burst of activity",
+                observed=f"{b[1]} transfers arrived within {span_min:.0f} minutes (~{rate:.0f}/min)",
+                implication="a rate consistent with automation rather than human activity",
+                confidence="high", weight=25,
+                evidence={"count": b[1], "span_minutes": round(span_min, 1),
+                          "from_ts": b[2], "to_ts": b[3]}))
+
+    rep = repeated_amounts([r.get("value", 0) for r in inbound])
+    if rep:
+        top = rep[0]
+        signals.append(Signal(
+            name="repeated amounts",
+            observed=f"the exact amount {top[0]} arrived {top[1]} times from different addresses",
+            implication="batch processing rather than independent human transfers",
+            confidence="medium", weight=10,
+            evidence={"repeats": rep[:3]}))
+
+    # --- where the money goes -----------------------------------------
+    try:
+        onward = chains.flows(address, chain, branching, "out", asset=asset)
+    except chains.ChainError:
+        onward = []
+
+    exposure = {"mixer": 0.0, "sanctioned": 0.0, "exchange": 0.0, "bridge": 0.0}
+    named: Dict[str, str] = {}
+    for other, val, _cnt in onward:
+        t = labels.type_of(other)
+        if t in exposure:
+            exposure[t] += val
+            named.setdefault(t, labels.label_of(other) or other)
+
+    if exposure["sanctioned"] > 0:
+        signals.append(Signal(
+            name="sanctions exposure",
+            observed=f"{exposure['sanctioned']:.8f} sent to sanctioned wallets ({named['sanctioned']})",
+            implication="funds moved to entities on an official sanctions list",
+            confidence="high", weight=50,
+            evidence={"amount": exposure["sanctioned"], "entity": named["sanctioned"]}))
+    if exposure["mixer"] > 0:
+        signals.append(Signal(
+            name="mixer exposure",
+            observed=f"{exposure['mixer']:.8f} sent into {named['mixer']}",
+            implication="the on-chain trail is deliberately broken from that point",
+            confidence="high", weight=40,
+            evidence={"amount": exposure["mixer"], "service": named["mixer"]}))
+    if exposure["exchange"] > 0:
+        signals.append(Signal(
+            name="exchange contact",
+            observed=f"{exposure['exchange']:.8f} sent to {named['exchange']}",
+            implication="reaches a custodial service that holds the recipient's identity — "
+                        "the point where a legal request can work",
+            confidence="high", weight=5,
+            evidence={"amount": exposure["exchange"], "exchange": named["exchange"]}))
+    if exposure["bridge"] > 0:
+        signals.append(Signal(
+            name="cross-chain movement",
+            observed=f"{exposure['bridge']:.8f} sent into {named['bridge']}",
+            implication="funds left this chain; the trail continues elsewhere",
+            confidence="medium", weight=15,
+            evidence={"amount": exposure["bridge"], "bridge": named["bridge"]}))
+
+    # --- holding behaviour ---------------------------------------------
+    if received > 0 and sent == 0 and len(inbound) >= 3:
+        signals.append(Signal(
+            name="funds held",
+            observed=f"received {received:.8f} across {len(inbound)} transfers, spent nothing",
+            implication="proceeds are being held rather than cashed out — "
+                        "the window to act is still open",
+            confidence="high", weight=0,
+            evidence={"received": received, "transfers": len(inbound)}))
+
+    # --- can we trust our own numbers? ---------------------------------
+    v = verify_mod.reconcile(address, chain, asset)
+    if v["status"] == "mismatch":
+        caveats.append("the tool's own totals do not reconcile with the chain — "
+                       "treat every figure here as unreliable until explained")
+    elif v["status"] == "partial":
+        caveats.append("only part of this address's history was read, so amounts are "
+                       "a lower bound and absent signals may simply be unseen")
+    elif v["status"] == "consistent":
+        caveats.append("this chain publishes no independent gross totals, so attribution "
+                       "could only be partly cross-checked")
+
+    # --- overall --------------------------------------------------------
+    risk = min(100, sum(s.weight for s in signals))
+    if v["status"] == "mismatch":
+        confidence = "low"
+    elif not signals:
+        confidence = "low"
+    else:
+        best = max(CONF_ORDER[s.confidence] for s in signals)
+        confidence = {3: "high", 2: "medium", 1: "low"}[best]
+        if v["status"] in ("partial", "consistent") and confidence == "high":
+            confidence = "medium"
+
+    return {
+        "address": address, "chain": chain,
+        "risk": risk, "confidence": confidence,
+        "assessment": _statement(signals, risk, confidence, hit),
+        "signals": [asdict(s) for s in signals],
+        "caveats": caveats,
+        "verification": {"status": v["status"], "headline": verify_mod.headline(v)},
+        "totals": {"received": received, "sent": sent,
+                   "inbound": len(inbound), "outbound": len(outbound)},
+    }
+
+
+def _statement(signals: List[Signal], risk: int, confidence: str, hit) -> str:
+    """One paragraph a person can read, act on, and argue with."""
+    if not signals:
+        return ("Nothing in the data collected distinguishes this address. That is not a "
+                "clearance — an unlabelled address with unremarkable flows is simply "
+                "unknown.")
+    names = {s.name for s in signals}
+    parts = []
+    if hit:
+        parts.append(f"This address is a known entity: {hit['name']}.")
+    if "automated collection" in names or "burst of activity" in names:
+        parts.append("The pattern of incoming funds indicates an automated sweep rather "
+                     "than owners moving their own money.")
+    if "sanctions exposure" in names:
+        parts.append("Funds moved on to sanctioned wallets, which puts this in "
+                     "law-enforcement territory.")
+    if "mixer exposure" in names:
+        parts.append("Part of the value entered a mixer, where on-chain tracing ends.")
+    if "exchange contact" in names:
+        parts.append("Some value reached a custodial exchange — the one point in this "
+                     "chain where identity can realistically be obtained.")
+    if "cross-chain movement" in names:
+        parts.append("Some value left this chain through a bridge and would need to be "
+                     "picked up on the destination network.")
+    if "funds held" in names:
+        parts.append("The proceeds have not been spent, so intervention is still possible.")
+    parts.append(f"Overall risk {risk}/100, confidence {confidence}.")
+    return " ".join(parts)