Agent skill
chain-forensics
On-chain analysis and transaction forensics for blockchain security investigations. Provides capabilities for tracing fund flows, identifying suspicious patterns, MEV analysis, and generating forensic reports for incident response.
Stars
163
Forks
31
Install this agent skill to your Project
npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/data/chain-forensics
SKILL.md
Chain Analysis/Forensics Skill
Expert on-chain analysis and transaction forensics for security investigations and incident response.
Capabilities
- Transaction Tracing: Follow fund flows across addresses and protocols
- Pattern Detection: Identify suspicious patterns (wash trading, rugpulls, sandwich attacks)
- MEV Analysis: Analyze MEV activity and flashbots bundles
- Address Clustering: Group related addresses and identify ownership
- Cross-Chain Tracking: Track bridged assets across chains
- Forensic Reports: Generate detailed investigation reports
MCP/Tool Integration
| Tool | Purpose | Reference |
|---|---|---|
| Phalcon MCP | Transaction analysis, exploit detection | phalcon-mcp |
| whale-tracker-mcp | Large transaction monitoring | whale-tracker |
| bicscan-mcp | Address risk scoring | bicscan |
| dune-analytics-mcp | Custom queries, analytics | dune |
| Etherscan MCP | Block explorer data | etherscan |
Transaction Tracing
Basic Flow Analysis
bash
# Get transaction details
cast tx 0xTxHash --rpc-url $RPC
# Decode transaction input
cast 4byte-decode $(cast tx 0xTxHash --rpc-url $RPC | grep input)
# Get internal transactions via Etherscan API
curl "https://api.etherscan.io/api?module=account&action=txlistinternal&txhash=0xTxHash&apikey=$KEY"
Tracing with Tenderly/Phalcon
javascript
// Phalcon trace analysis
const trace = await phalcon.analyzeTransaction(txHash);
// Identify key flows
const flows = {
valueTransfers: trace.transfers.filter(t => t.value > 0),
tokenTransfers: trace.erc20Transfers,
internalCalls: trace.calls.filter(c => c.type === 'CALL'),
delegateCalls: trace.calls.filter(c => c.type === 'DELEGATECALL')
};
Address Analysis
Profile Building
javascript
const addressProfile = {
address: '0x...',
// Basic metrics
metrics: {
firstTransaction: '2022-01-15',
transactionCount: 1234,
uniqueInteractions: 56,
totalValueTransferred: '1000 ETH'
},
// Activity patterns
patterns: {
activeHours: [14, 15, 16], // UTC hours
frequentProtocols: ['Uniswap', 'Aave'],
averageTxFrequency: '5/day'
},
// Risk indicators
riskFlags: {
tornadoCashInteraction: false,
sanctionedAddressInteraction: false,
knownExploitPattern: false,
highFrequencyTrading: true
},
// Related addresses
clusters: [
{ address: '0x...', confidence: 0.95, reason: 'Funding source' },
{ address: '0x...', confidence: 0.8, reason: 'Common recipient' }
]
};
Clustering Heuristics
- Deposit Address Reuse: Same deposit addresses across exchanges
- Multi-Input Transactions: Addresses used together in single tx
- Timing Analysis: Coordinated transaction timing
- Amount Patterns: Matching amounts minus fees
- Contract Interactions: Shared smart contract usage patterns
MEV Analysis
Sandwich Attack Detection
sql
-- Dune Analytics query for sandwich detection
WITH potential_sandwiches AS (
SELECT
block_number,
transaction_index,
"from",
"to",
value,
LAG("from") OVER (PARTITION BY block_number ORDER BY transaction_index) as prev_from,
LEAD("from") OVER (PARTITION BY block_number ORDER BY transaction_index) as next_from
FROM ethereum.transactions
WHERE block_number > {{start_block}}
)
SELECT *
FROM potential_sandwiches
WHERE prev_from = next_from
AND prev_from != "from"
-- Additional filters for DEX interactions
Flashbots Bundle Analysis
javascript
// Analyze flashbots bundles
const bundleAnalysis = {
bundleHash: '0x...',
transactions: [
{ index: 0, type: 'frontrun', profit: '0.5 ETH' },
{ index: 1, type: 'victim', loss: '0.3 ETH' },
{ index: 2, type: 'backrun', profit: '0.4 ETH' }
],
totalMEV: '0.9 ETH',
miner: '0x...',
minerPayment: '0.45 ETH'
};
Suspicious Pattern Detection
Rugpull Indicators
javascript
const rugpullIndicators = {
// Contract analysis
contract: {
hasHiddenMint: true, // Owner can mint unlimited
hasDisableTrading: true, // Can disable selling
hasBlacklist: true, // Can block addresses
highOwnershipConcentration: true, // >50% in few wallets
unverifiedContract: true,
recentDeployment: true // <7 days old
},
// Token metrics
tokenMetrics: {
liquidityLocked: false,
lockDuration: 0,
holderCount: 50,
top10HoldersPercent: 85
},
// Trading patterns
tradingPatterns: {
artificialVolume: true, // Wash trading detected
sellPressure: 'high',
buyWallsArtificial: true
},
riskScore: 95 // 0-100
};
Wash Trading Detection
sql
-- Identify circular trading
WITH transfers AS (
SELECT
"from",
"to",
contract_address,
value,
block_time
FROM erc20_ethereum.evt_Transfer
WHERE contract_address = {{token_address}}
AND block_time > NOW() - INTERVAL '7 days'
)
SELECT
a."from" as trader,
COUNT(DISTINCT b."to") as counterparties,
SUM(a.value) as total_volume,
COUNT(*) as trade_count
FROM transfers a
JOIN transfers b ON a."to" = b."from" AND a."from" = b."to"
WHERE a.block_time < b.block_time
AND b.block_time < a.block_time + INTERVAL '1 hour'
GROUP BY a."from"
HAVING COUNT(*) > 10
ORDER BY total_volume DESC
Cross-Chain Tracking
Bridge Transaction Mapping
javascript
const crossChainTrace = {
originChain: 'ethereum',
originTx: '0x...',
originAddress: '0x...',
bridge: 'Wormhole',
bridgeMessage: '0x...',
destinationChain: 'arbitrum',
destinationTx: '0x...',
destinationAddress: '0x...',
amount: '100 USDC',
timestamp: {
origin: '2024-01-15T10:00:00Z',
destination: '2024-01-15T10:15:00Z'
}
};
Multi-Chain Address Mapping
javascript
// Track address across chains
const multiChainProfile = {
primaryAddress: '0x...',
chainPresence: {
ethereum: { address: '0x...', balance: '10 ETH', txCount: 500 },
arbitrum: { address: '0x...', balance: '5 ETH', txCount: 200 },
optimism: { address: '0x...', balance: '3 ETH', txCount: 100 },
polygon: { address: '0x...', balance: '1000 MATIC', txCount: 50 }
},
bridgeHistory: [
{ from: 'ethereum', to: 'arbitrum', amount: '5 ETH', date: '2024-01-10' },
{ from: 'ethereum', to: 'optimism', amount: '3 ETH', date: '2024-01-12' }
]
};
Forensic Report Template
markdown
# Blockchain Forensic Investigation Report
## Executive Summary
- **Investigation ID**: INV-2024-XXX
- **Date Range**: 2024-01-01 to 2024-01-15
- **Subject**: [Address/Protocol/Incident]
- **Conclusion**: [Brief finding]
## Key Findings
### 1. Fund Flow Analysis
[Diagram and description of fund movements]
### 2. Address Attribution
| Address | Attribution | Confidence | Evidence |
|---------|-------------|------------|----------|
| 0x... | Attacker | High | Funding pattern |
| 0x... | Mixer | Medium | Tornado Cash |
| 0x... | Exchange | High | Known deposit |
### 3. Timeline
| Timestamp | Event | Addresses | Amount |
|-----------|-------|-----------|--------|
| T+0 | Initial exploit | 0x... | 1000 ETH |
| T+1h | Consolidation | 0x... | 1000 ETH |
| T+2h | Mixer deposit | Tornado | 100 ETH |
### 4. Attack Vector
[Technical description of how the incident occurred]
### 5. Total Impact
- Funds Lost: $X
- Users Affected: Y
- Contracts Exploited: Z
## Appendix
- Full transaction list
- Address clustering data
- Supporting evidence
Process Integration
This skill integrates with:
incident-response-exploits.js- Exploit investigationeconomic-simulation.js- Market impact analysissmart-contract-security-audit.js- Post-audit monitoring
Tools Reference
| Tool | Purpose | URL |
|---|---|---|
| Etherscan | Explorer, API | etherscan.io |
| Dune Analytics | Custom queries | dune.com |
| Nansen | Wallet labels, flows | nansen.ai |
| Arkham Intelligence | Entity attribution | arkhamintelligence.com |
| Chainalysis Reactor | Investigation platform | chainalysis.com |
| TRM Labs | Risk scoring | trmlabs.com |
| Phalcon | Tx analysis | phalcon.blocksec.com |
See Also
agents/incident-response/AGENT.md- Incident commander agentskills/bug-bounty/SKILL.md- Disclosure coordinationincident-response-exploits.js- Full incident process
Didn't find tool you were looking for?