onchain-forensics
Viprasol-Tech/onchain-forensics
AI agent skill for on-chain fund tracing & address-clustering investigations — MIH, change-address, FIFO mixer & bridge heuristics, OFAC checks, Daubert-grade evidence. Works with Claude Code, Codex, Cursor. By Viprasol Tech.
Instalação
npx convez-ai Viprasol-Tech/onchain-forensics1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
README
A tradução para o português deste README ainda está na fila.
On-Chain Forensics — Agent Skill
Trace fund flows across chains and cluster addresses with the standard 6-stage forensic workflow — MIH, change-address, FIFO mixer heuristics, bridge/DEX hops, OFAC screens, and a reproducible case report.
Works with: Claude Code · OpenAI Codex · Cursor · GitHub Copilot · Gemini CLI · 26+ tools that support portable agent skills.
Quick Install
Clone the skill into your agent's skills directory:
# Claude Code
git clone https://github.com/Viprasol-Tech/onchain-forensics \
~/.claude/skills/onchain-forensics
# OpenAI Codex
git clone https://github.com/Viprasol-Tech/onchain-forensics \
~/.codex/skills/onchain-forensics
# Cursor / Copilot / Gemini CLI / other tools — clone anywhere your tool
# loads skills from, e.g.
git clone https://github.com/Viprasol-Tech/onchain-forensics \
~/.config/skills/onchain-forensics
The skill is a single self-contained skill.md (plus examples) — no
dependencies, no install step, nothing to build.
Try It
Paste a few tx hashes, an address list, or a flow export and ask:
Trace these funds and tell me where they went — cluster the addresses and
flag any sanctioned-cluster contact.
The skill will scope the case, pick the right heuristics for the chain (UTXO vs account), walk the hops, call out mixer / bridge / DEX legs, score attribution confidence, and produce a reproducible investigator's case report.
Why This Exists
Modern crypto laundering chains 3–5 obfuscation techniques in sequence — peel chain → bridge → DEX → mixer → bridge — and a single missed clustering heuristic loses the trail. Professional investigators run the same 6-stage workflow every time: collect, cluster, attribute, graph, cross-chain hop, document. They label every claim with the heuristic used and its known limits so the report holds up under Daubert review. This skill encodes that workflow so your agent runs it the same way each time, picks the right heuristics for UTXO vs account-based chains, names confidence on every attribution, and never silently invents on-chain state.
What It Does
- Intake & scope — case type, chains, seed addresses/tx hashes, value at risk, timeframe, and the data the user can actually provide.
- Chooses heuristics by chain model — Multi-Input-Ownership and change-address for UTXO chains; deposit-address clustering, common gas funder, ENS reuse, and bridge-receipt matching for EVM/Solana.
- Walks the hops — direct transfer, DEX swap, bridge, mixer, peel chain, CEX deposit. Normalizes amounts in native units and USD where priced.
- Handles obfuscation chains — Tornado Cash with its OFAC sanction context and the published FIFO-temporal-matching defeat (5.1–12.6% baseline + 15–22pp from FIFO, per arXiv 2510.09433); Railgun and eXch flagged; bridges correlated by lock-mint event pairs.
- Attributes carefully — OSINT, public labels (Arkham, Nansen, Etherscan, Lookonchain), OFAC SDN, with Low / Med / High confidence and cited evidence on every row.
- Severity-tags red flags — 🔴 sanctioned contact / 🟠 mixer-adjacent / 🟡 multi-hop proximity / 🟢 / ℹ️.
- Outputs an investigator's case report — TL;DR + verdict, cluster table, hop-by-hop flow, mixer/bridge/DEX call-outs, attribution table, IOCs, reproducibility log (every step labeled with heuristic + source), and a Daubert-grounded disclaimer.
Features
- 6-stage workflow — collect, cluster, attribute, graph, cross-chain, document. The Chainalysis-grade investigator's loop.
- UTXO vs account-based — never confuses the two; MIH only fires on UTXO chains, deposit-address clustering only on account-based.
- Mixer handling — Tornado Cash sanction context, founder-conviction note, and the published FIFO/address-reuse/gas-funder defeats with honest candidate-set caveats. Railgun and eXch flagged.
- Bridge correlation — canonical lock-mint event pairing, AMM-bridge event-log scan, intent-solver caveat.
- Severity ladder — 🔴 sanctioned / 🟠 mixer-adjacent or peel-chain / 🟡 multi-hop indirect / 🟢 / ℹ️.
- Reproducibility log — every step in the report is labeled with the heuristic name + the source/link a human can re-walk to verify.
- Daubert-aware disclaimer — testable / known error rates / peer-reviewed / generally accepted; the skill cites the standard but doesn't pretend to satisfy it alone.
Heuristic-confidence quick reference
| Heuristic | Chain model | Strength | Defeat |
|---|---|---|---|
| Multi-Input Ownership (MIH) | UTXO | Strong (gold standard) | CoinJoin / PayJoin / multi-sig |
| Change-address detection | UTXO | Medium | Randomized modern wallets |
| Deposit-address clustering | Account | Strong with hot-wallet labels | Self-custody / DEX-only flows |
| Common gas funder | Account | Medium | Exchange withdrawals fund many users |
| FIFO temporal matching | Mixer | +15–22pp over baseline (arXiv 2510.09433) | Disciplined timing offsets |
| Bridge-receipt matching | Cross-chain | Strong on canonical bridges | Intent-based solvers, hop-aggregation |
See full worked reports in examples/:
- Stolen ETH trace — phishing victim, drainer EOA, peel chain into Tornado Cash, FIFO candidate set, CEX deposit attribution, 🟠 / 🔴 verdict.
- BTC rug-pull cluster — MIH on the deposit side to cluster founder wallets, change-address chain into a peel, CEX deposit recognized via hot-wallet pattern, 🔴 verdict.
Not Legal Advice
This skill provides probabilistic investigative leads, not court-ready evidence. Clustering and mixer-deanonymization heuristics have known false-positive and false-negative rates; the skill cannot fetch on-chain state and reasons only over what you provide. For law-enforcement, civil litigation, or regulatory action, pair this with professional tooling (Chainalysis Reactor, TRM Labs, Elliptic) and subpoena-backed exchange KYC data, and have it reviewed by a qualified investigator and counsel. Not affiliated with or endorsed by Anthropic or any forensics vendor.
Contact — Viprasol Tech Private Limited
- 🌐 Website: viprasol.com
- ✉️ Email: support@viprasol.com
- 💬 Telegram: t.me/viprasol_help · 📱 WhatsApp: +91 96336 52112
- 🐙 GitHub: @Viprasol-Tech · 💼 LinkedIn · 𝕏 @viprasol
Viprasol Tech — fintech software, AI agents, algorithmic trading systems, and B2B SaaS.
License
MIT © 2025 Viprasol Tech Private Limited