chain-forensics

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

Transaction Tracing

Basic Flow Analysis

# 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

// 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

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

1. Deposit Address Reuse: Same deposit addresses across exchanges
2. Multi-Input Transactions: Addresses used together in single tx
3. Timing Analysis: Coordinated transaction timing
4. Amount Patterns: Matching amounts minus fees
5. Contract Interactions: Shared smart contract usage patterns

MEV Analysis

Sandwich Attack Detection

-- 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

// 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

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

-- 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

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

// 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

# 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 investigation
• economic-simulation.js - Market impact analysis
• smart-contract-security-audit.js - Post-audit monitoring

Tools Reference

See Also

• agents/incident-response/AGENT.md - Incident commander agent
• skills/bug-bounty/SKILL.md - Disclosure coordination
• incident-response-exploits.js - Full incident process