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.
Install this agent skill to your Project
npx add-skill https://github.com/a5c-ai/babysitter/tree/main/library/specializations/cryptography-blockchain/skills/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
# 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
- 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
-- 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 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
Recommended Agent Skills
Expand your agent's capabilities with these related and highly-rated skills.
gsd-tools
Central utility skill for GSD operations. Provides config parsing, slug generation, timestamps, path operations, and orchestrates calls to other specialized skills. Acts as the unified entry point that the original gsd-tools.cjs provided via its lib/ modules (commands, config, core, init).
model-profile-resolution
Resolve model profile (quality/balanced/budget) at orchestration start and map agents to specific models. Enables cost/quality tradeoffs by selecting appropriate AI models for each agent role.
verification-suite
Plan structure validation, phase completeness checks, reference integrity verification, and artifact existence confirmation. Provides the structured verification layer ensuring GSD artifacts are well-formed and complete.
state-management
STATE.md reading, writing, and field-level updates. Provides cross-session state persistence via .planning/STATE.md with structured fields for current task, completed phases, blockers, decisions, and quick tasks.
git-integration
Git commit patterns, formats, and conventions for GSD methodology. Provides atomic commits per task, structured commit messages, planning file commits, branch management, and milestone tag operations.
frontmatter-parsing
YAML frontmatter parsing and manipulation for .planning/ documents. Provides read, write, update, query, and validation operations on frontmatter blocks in GSD markdown artifacts.
Didn't find tool you were looking for?