# BUILD NOTES — On-Chain Ransom Tracing Module

## Purpose
A runnable prototype of the **lawful** on-chain tracing technique used by
firms like Chainalysis / TRM Labs: read a public ledger, follow a ransom
payment downstream, quantify taint, flag cash-out points, and produce a
law-enforcement hand-off report. It is **trace-and-report only** — the exact
opposite of a hack-back.

## Legal framing (non-negotiable, reflected everywhere)
Per `../shared/BRIEF.md` guardrails #1 and #4:
- **No touching funds.** No token injection, no moving/seizing/freezing/clawback,
  no attaching to a criminal's money. Those are impossible on a blockchain and
  illegal (CFAA 18 U.S.C. § 1030).
- **Read-only.** The chain is public; we only read it. Here the "chain" is a
  fully **simulated** local SQLite ledger — no network, no real chain client,
  no real wallet, no real funds, no PII.
- **Report, don't act.** Identification (KYC) and seizure are performed by law
  enforcement via lawful process (subpoena to the exchange at the cash-out
  point). The module only writes a report to `outbox/`.
The trace-not-touch statement appears in: every module docstring, the README
(top banner + Legal Use Notice), the report JSON/TXT (`legal_notice` field), and
the dashboard banner.

## Architecture
```
chain_model.py   simulated ledger (SQLite: addresses + transactions, labels)
     │
tracer.py        trace(start, max_hops): BFS discovery + proportional taint pass
     │                                    -> flow graph {nodes, edges, path, summary}
     ├── report.py   generate(): trace -> JSON + human TXT into outbox/ (+ sha256)
     └── app.py      Flask dashboard -> templates/dashboard.html (SVG flow graph)
demo_seed.py     resets ledger + inserts the synthetic ransom scenario
```

## Design decisions
- **SQLite, stdlib-first.** Matches the honeypot sibling module. Only third-party
  dep is Flask (dashboard). Everything else is stdlib.
- **Two-pass taint (discovery BFS, then propagation).** A first BFS discovers all
  reachable addresses/edges within `max_hops` and each address's earliest hop.
  A second pass distributes taint in earliest-hop order so an address's inbound
  taint is accumulated before it forwards. This avoids the double-counting bug of
  a naive single-pass BFS where an address reached via multiple paths would push
  taint out repeatedly.
- **Proportional / haircut taint.** Standard, defensible method. Taint per
  outgoing edge = addr_taint × (edge_amount / total_out), capped at edge amount;
  per-node taint capped at value actually received. Taint only dilutes.
- **Representative path.** For the report/UI, a single "primary trail" is built by
  following the highest-taint outgoing edge from the ransom address to the largest
  cash-out point. The full graph remains available in `nodes`/`edges`.
- **Cash-out flagging.** Addresses labeled `EXCHANGE` or `MIXER` that received
  taint are flagged, each with a `lawful_next_step` naming the LE action (subpoena
  / obfuscation indicator) — never an action we take.
- **Dashboard visualization.** Layered SVG graph (x = hop, edge width ∝ taint) +
  hop list + cash-out cards + report button. Colors/fonts from the BRIEF design
  system (bg #0D1117, accent #20808D, Space Grotesk / Inter / JetBrains Mono).

## Verification (run and confirmed)
- `demo_seed.py` seeds 10 addresses / 12 transactions; ransom = 12.0 BTC.
- `tracer.py` follows the ransom through hops to flagged cash-out points:
  QuickSwap EXCHANGE 7.0 BTC, GlobalCoin EXCHANGE 3.0 BTC, MIXER 4.0 BTC.
- Taint values are conserved and correctly diluted; no node's taint exceeds the
  value it received.
- `report.py` writes `RANSOM-TRACE-*.json` + `.txt` to `outbox/` with an
  integrity SHA-256.
- `app.py` serves the dashboard at :5057; `/api/trace`, `/api/report`,
  `/api/reports` verified.

## Possible extensions (not built)
- Tier-aware handling (individual/business/gov) per the platform tiers.
- Multiple simultaneous ransom cases; time-window filtering.
- Sankey-style flow view; export of the graph as an image attachment.
- Signed report packages + authenticated transmission stub to IC3/CISA.

## Explicitly out of scope (and will never be built)
Anything that reads, writes, or interacts with a real blockchain, a real wallet,
or anyone's real funds; anything that moves/seizes value; anything resembling a
hack-back. This module is passive, simulated, read-only, and report-only.
