Flashpoint - EVM Call Simulator

A TypeScript-based CLI tool to simulate EVM contract calls using ethers.js and trace errors with detailed decoding.

Quick Start

# 1. Install dependencies
yarn install

# 2. Copy environment template
cp .env.example .env

# 3. Configure your transaction (edit .env)
CONTRACT_ADDRESS=0x... # Target contract
FUNCTION_CALLDATA=0x... # Encoded function call
FROM_ADDRESS=0x...      # Caller address
RPC_URL=https://...     # RPC endpoint

# 4. Run simulation
yarn simulate           # Standard simulation
yarn simulate:anvil     # Fork simulation with full tracing

Features

Core Functionality

🔄 Simulate contract calls on any EVM-compatible network
🌳 Full transaction tracing with hierarchical call trees (Contract A → B → C)
🐳 Anvil fork simulation at historical blocks using Docker
🔍 Auto-fetch ABIs from Explorer APIs (Etherscan v2, v1, and Blockscout)
📝 Contract name resolution - Display human-readable names in traces
🎨 Color-coded trace output with ANSI color syntax highlighting

Advanced Decoding

🔓 Decoded function signatures - Show readable function calls instead of selectors
⚠️ Custom error decoding - Parse custom errors with arguments
📤 Output value decoding - Decode function return values with type-aware formatting
🏷️ Type-specific colors - Different colors for addresses, booleans, numbers, etc.
📍 Address formatting - Underlined addresses with optional contract names

Error Analysis

🚨 Advanced error diagnostics - Pinpoint exact revert location in call stack
💡 Troubleshooting hints - Automatic suggestions for common error patterns
🔎 Nested error tracking - Identify which subcall caused the revert
📊 Gas analysis - Track gas usage and percentages across calls

Developer Experience

✅ Type-safe TypeScript implementation
🧹 ESLint and Prettier for code quality
🚀 Zero-config setup for most networks
📦 Automatic ABI caching for performance

Prerequisites

Node.js >= 18.x
Yarn package manager
Docker and Docker Compose (for Anvil fork simulation)

RPC Requirements

For Standard Simulation (yarn simulate):

Any RPC endpoint (free or paid)
Optional: debug_traceCall support for transaction tracing (Alchemy Archive, Hardhat, Anvil)

For Anvil Fork Simulation (yarn simulate:anvil):

Does NOT require archive node - works with standard free RPC endpoints
RPC must support eth_getBlockByNumber and eth_call (all standard RPCs)
Limitations:
- Some free RPCs may have rate limits
- Historical block data must be available (usually last 128 blocks minimum)
- Chain ID is auto-detected from RPC for Explorer API compatibility

Recommended RPC Providers:

Free: Public RPC endpoints (e.g., https://ethereum-sepolia-rpc.publicnode.com)
Paid: Alchemy, Infura, QuickNode (better rate limits and archive access)

Simulation Mode Comparison

Feature	Standard (`yarn simulate`)	Anvil Fork (`yarn simulate:anvil`)
Setup	Just RPC URL	RPC URL + Docker
Tracing	Optional (RPC-dependent)	Always enabled
Archive Node	Required for old blocks	Not required
Historical State	Current state only	Any historical block
Speed	Faster (direct RPC)	Slightly slower (fork + Docker)
Use Case	Quick checks, current state	Deep debugging, historical analysis
Cost	Free with public RPC	Free (uses Docker locally)
Best For	Production monitoring	Development & debugging

Recommendation: Use Anvil fork simulation for comprehensive debugging and historical analysis. Use standard simulation for quick checks on current state.

Installation

yarn install

Configuration

Copy the example environment file:
```
cp .env.example .env
```

Update .env with your configuration:

# Required: Transaction details
CONTRACT_ADDRESS=0x1234567890123456789012345678901234567890
FUNCTION_CALLDATA=0x12345678...
FROM_ADDRESS=0x0000000000000000000000000000000000000000
RPC_URL=https://eth-mainnet.g.alchemy.com/v2/your-api-key

# Optional: For Anvil fork simulation
BLOCK_NUMBER=19000000

# Optional: Auto-fetch ABIs from Explorer API
AUTO_FETCH_ABIS=true
EXPLORER_API_URL=https://api.etherscan.io/v2/api
ETHERSCAN_API_KEY=YourApiKeyToken

# Optional: Trace timeout (default: 30000ms)
TRACE_TIMEOUT=30000

Explorer API Configuration Examples

Flashpoint supports multiple Explorer APIs with automatic chain ID detection:

Etherscan API v2 (Unified - Recommended)

EXPLORER_API_URL=https://api.etherscan.io/v2/api
ETHERSCAN_API_KEY=YourApiKeyToken
# Supports 50+ chains via chainid parameter (auto-detected from RPC)

Etherscan API v1 (Chain-specific)

# Ethereum Mainnet
EXPLORER_API_URL=https://api.etherscan.io/api
ETHERSCAN_API_KEY=YourApiKeyToken

# Sepolia Testnet
EXPLORER_API_URL=https://api-sepolia.etherscan.io/api
ETHERSCAN_API_KEY=YourApiKeyToken

# Polygon
EXPLORER_API_URL=https://api.polygonscan.com/api
ETHERSCAN_API_KEY=YourApiKeyToken

# BSC
EXPLORER_API_URL=https://api.bscscan.com/api
ETHERSCAN_API_KEY=YourApiKeyToken

# Arbitrum
EXPLORER_API_URL=https://api.arbiscan.io/api
ETHERSCAN_API_KEY=YourApiKeyToken

# Optimism
EXPLORER_API_URL=https://api-optimistic.etherscan.io/api
ETHERSCAN_API_KEY=YourApiKeyToken

Blockscout (Open Source)

# Base
EXPLORER_API_URL=https://base.blockscout.com/api
# API key optional for most public instances

# Gnosis Chain
EXPLORER_API_URL=https://gnosis.blockscout.com/api

# Custom Blockscout instance
EXPLORER_API_URL=https://explorer.yourchain.com/api

How it works:

Chain ID is automatically detected from your RPC connection
For Etherscan v2: Chain ID is sent as chainid parameter
For Etherscan v1/Blockscout: Use chain-specific endpoint
ABIs are cached locally to minimize API calls
Rate limiting: 200ms between requests (5 req/sec)

Usage

Standard Simulation

Simulate a contract call on the current state:

yarn simulate

This will:

Validate your environment configuration
Connect to the specified RPC endpoint
Simulate the contract call with optional tracing
Display detailed results or error traces

Anvil Fork Simulation (Recommended)

For simulating at historical blocks with full transaction tracing:

# Run simulation (automatically starts/stops Anvil container)
yarn simulate:anvil

The simulate:anvil command will:

Automatically start the Anvil Docker container (if not running)
Fork the network at the block specified in .env
Auto-detect chain ID from the fork source network for Explorer API
Execute the simulation with full call tracing
Automatically stop the container after completion

Manual container management (optional):

yarn anvil:start  # Manually start container
yarn anvil:stop   # Manually stop container
yarn anvil:logs   # View Anvil logs

Important Notes:

⚠️ Non-Archive RPC: Works with standard RPC endpoints (no archive node required)
⚠️ Chain ID Detection: Automatically fetches chain ID from the original RPC for Explorer API
⚠️ Rate Limits: Subject to RPC provider rate limits for both fork source and Explorer API calls

See ANVIL_SIMULATION.md for detailed documentation.

Trace Output Examples

Successful Transaction Trace

======================================================================
                    TRANSACTION TRACE
======================================================================

 CALL 0xf3fb62e0cc08eb1fe9fa090aa4f18a09b49e4f96 (MorphoLiquidationGateway) → 0x8827171fcb8739a8e5efce10b42004cb96c269b5 (Vault)
├─ Function: liquidate(address,uint256,address)
├─ Gas: 500,000 (Used: 234,567, 46.9%)
├─ Decoded Output:
│  [0]: true
│  [1]: 0x1234567890123456789012345678901234567890 (TokenContract)
│  [2]: 1500000000000000000
├─ Raw Output: 0x0000000000000000000000000000000000000000000000000000000000000001
├─ Input Selector: 0x12345678
│
   ├─ DELEGATECALL 0x8827171fcb8739a8e5efce10b42004cb96c269b5 (Vault) → 0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48 (USDC)
   ├─ Function: transfer(address,uint256)
   ├─ Gas: 100,000 (Used: 45,123, 45.1%)
   ├─ Decoded Output:
   │  [0]: true
   ├─ Raw Output: 0x0000000000000000000000000000000000000000000000000000000000000001

======================================================================
                         SUMMARY
======================================================================
Total Gas Used:  234,567
Call Frames:     2
Max Depth:       2
Status:          SUCCESS
======================================================================

Failed Transaction with Error

======================================================================
                    TRANSACTION TRACE
======================================================================

 CALL 0xf3fb... (MorphoLiquidationGateway) → 0x8827... (Vault)
├─ Function: liquidate(address,uint256,address)
├─ Gas: 500,000 (Used: 123,456, 24.7%)
├─ ERROR: InsufficientCollateral(uint256,uint256)
│    arg0: 1000000000000000000
│    arg1: 500000000000000000
├─ Raw Error Data: 0x82b42900000000000000000000000000000000000000000000000de0b6b3a7640000...
│
   ├─ STATICCALL 0x8827... (Vault) → 0x5f4eC3Df9cbd43714FE2740f5E3616155c5b8419 (ChainlinkOracle)
   ├─ Function: latestRoundData()
   ├─ Gas: 50,000 (Used: 12,345, 24.7%)
   ├─ Decoded Output:
   │  [0]: 18446744073709551615
   │  [1]: 180000000000
   │  [2]: 1704067200
   │  [3]: 1704067200
   │  [4]: 18446744073709551615

======================================================================
                         SUMMARY
======================================================================
Total Gas Used:  123,456
Call Frames:     2
Max Depth:       2
Status:          FAILED
Error:           InsufficientCollateral
======================================================================

Color-Coded Elements

When running in a terminal with color support, the trace output includes:

Call Types: Different colors for CALL (cyan), DELEGATECALL (magenta), STATICCALL (yellow)
Addresses: Magenta + underlined with optional contract names in blue
Functions: Cyan for function signatures
Gas: Yellow for gas values
Output: Green for return data
Errors: Red for error messages
Booleans: Green for true, red for false
Selectors: Gray for function/error selectors

Other Commands

# Build the project
yarn build

# Run linting
yarn lint

# Fix linting issues
yarn lint:fix

# Format code
yarn format

# Check formatting
yarn format:check

# Type checking
yarn typecheck

Project Structure

flashpoint/
├── src/
│   ├── command/
│   │   ├── simulate.ts           # Standard simulation
│   │   └── simulate-anvil.ts     # Anvil fork simulation
│   ├── utils/
│   │   ├── logger.ts             # Color-coded logging utility
│   │   ├── validator.ts          # Environment and input validation
│   │   ├── abi-loader.ts         # Load contract ABIs from ./abis
│   │   ├── etherscan-client.ts   # Fetch ABIs from Explorer API (Etherscan/Blockscout)
│   │   ├── function-decoder.ts   # Function/error signature decoder
│   │   ├── trace-client.ts       # debug_traceCall RPC client
│   │   ├── trace-parser.ts       # Parse call frames from traces
│   │   └── trace-visualizer.ts   # Render tree visualization
├── abis/                         # Contract ABIs (auto-created)
│   └── README.md                 # Instructions for adding ABIs
├── docker-compose.yml            # Anvil Docker setup
├── ANVIL_SIMULATION.md           # Anvil fork documentation
├── .env.example                  # Environment variables template
├── tsconfig.json                 # TypeScript configuration
├── eslint.config.mjs             # ESLint configuration
├── .prettierrc                   # Prettier configuration
└── package.json                  # Project dependencies and scripts

Error Handling

The tool uses ethers-decode-error to provide detailed error information when simulations fail:

Error type and name
Revert reason
Function arguments
Error signature
Additional context (insufficient funds, gas issues, etc.)

Custom Error Decoding

To decode custom contract errors (like DepositAlreadySubmitted()), place your contract ABI files in the ./abis directory:

Create the abis directory (auto-created on first run)
Add your contract ABI JSON files (e.g., router.json, token.json)
The simulator will automatically load and use them for error decoding

Supported formats:

Raw ABI array: [{"type":"error","name":"CustomError"...}]
Hardhat compilation output: {"abi": [...], "bytecode": "..."}

Example:

# Add your contract ABI
echo '[{"type":"error","name":"DepositAlreadySubmitted","inputs":[]}]' > abis/router.json

# Run simulation - custom errors will now be decoded
yarn simulate

Troubleshooting

Common Issues

1. "Failed to connect to Anvil after 10 attempts"

Check if Docker is running: docker ps
View Anvil logs: yarn anvil:logs
Manually stop and restart: yarn anvil:stop && yarn anvil:start

2. "No ABI found for contract (NOTOK)" when using Anvil

This happens when Etherscan API v2 receives wrong chain ID
✅ Fixed in latest version: Chain ID is now auto-detected from original RPC
Verify logs show: [DEBUG] Using original network chain ID for Etherscan: <chainId>

3. "RPC does not support debug_traceCall"

Normal for free/public RPCs - tracing is optional
Simulation will fall back to standard call
For full tracing, use: Alchemy Archive nodes, Hardhat, or Anvil fork

4. "Historical state is not available" (Anvil error)

Free RPC doesn't have archive access for old blocks
✅ Fixed: Anvil now uses --no-storage-caching --accounts 0
Try a more recent block number

5. Rate limit errors from Explorer API

Built-in rate limiting: 200ms between requests (5 req/sec)
For Etherscan: Get a free API key to increase limits
For Blockscout: Most public instances don't require API keys

Development

Code Quality

All code is enforced with:

TypeScript strict mode
ESLint with TypeScript rules
Prettier for consistent formatting

Adding New Commands

Create a new file in src/command/
Implement your command logic
Add a script in package.json
Update this README

Advanced Features Roadmap

We're planning to add these advanced features in future releases. Vote for your favorites or contribute!

🥇 High Priority (Coming Soon)

🔄 State Diff Visualization

Why: Most requested feature by DeFi developers, critical for understanding protocol behavior

Features:

Show storage slot changes before/after each call
Display balance transfers as flow diagram
Decode storage values using contract ABIs
Export state changes to JSON/CSV
Highlight critical state modifications (e.g., ownership changes)
Implementation: Use debug_traceCall with prestateTracer

Use Cases:

Verify DEX pool state changes
Debug lending protocol liquidations
Audit governance proposal effects
Trace token balance flows

📊 Gas Profiling & Optimization Suggestions

Why: Save real money by identifying expensive operations

Features:

Highlight top 10 gas-consuming operations
Compare gas usage across different call paths
Detect common anti-patterns:
- Storage reads in loops (SLOAD spam)
- Redundant external calls
- Inefficient data structures
Generate gas optimization report with savings estimates
Visual gas flamegraph for complex traces

Use Cases:

Optimize contract deployments
Reduce transaction costs
Identify gas griefing vectors

🔍 Trace Comparison & Diff

Why: Debug why transactions behave differently

Features:

Side-by-side trace comparison view
Highlight divergence points in execution
Gas difference analysis with explanations
Compare successful vs failed transactions
Compare different block numbers (state evolution)
Compare different input parameters

Use Cases:

Debug failed vs successful transactions
Analyze impact of parameter changes
Verify upgrade behavior (proxy contracts)

🥈 Medium Priority

🎯 Interactive Trace Explorer (TUI)

Why: Static output is hard to navigate for complex traces

Features:

Terminal UI with keyboard navigation (built with blessed or ink)
Expand/collapse nested call frames
Filter by call type (CALL, DELEGATECALL, etc.)
Search for specific addresses/functions
Copy addresses/data to clipboard
Export filtered traces to JSON
Dark/light theme support

🔗 Multi-Transaction Simulation

Why: Test complex workflows and MEV strategies

Features:

Load transaction sequences from JSON/CSV
Simulate MEV bundles (flashbots-style)
Test different transaction orderings
Calculate total gas and profit/loss
Detect MEV opportunities (arbitrage, liquidation)
Flash loan attack simulation

Example Config:

{
  "transactions": [
    {"to": "0x...", "data": "0x...", "value": "0"},
    {"to": "0x...", "data": "0x...", "value": "1000000000000000000"}
  ]
}

📹 Trace Recording & Replay

Why: Build test cases from real transactions

Features:

Record traces to portable format
Replay on different networks/forks
Generate Foundry test from trace
Generate Hardhat test from trace
CI/CD integration for regression testing
Differential testing (trace vs actual execution)

🥉 Future Enhancements

🐛 EVM Debugger Integration

Why: Opcode-level debugging for complex issues

Features:

Step-by-step opcode execution viewer
Show stack/memory/storage at each step
Set breakpoints on specific opcodes
Export execution trace for Foundry/Hardhat
Implementation: Use debug_traceCall with opTracer

🎲 Smart Contract Fuzzing

Why: Discover edge cases and security issues

Features:

Auto-generate test inputs based on ABI
Detect invariant violations
Find revert conditions
Export failing cases for unit tests
Integration with Echidna/Medusa

🔒 Security Analysis

Why: Catch vulnerabilities during development

Automated Checks:

Reentrancy detection (CEI pattern violations)
Unchecked external calls
Insufficient access control
Integer overflow/underflow (pre-0.8.0)
Dangerous delegatecall patterns
Unprotected selfdestruct
Front-running vulnerabilities

Output: Security report with severity ratings (Critical, High, Medium, Low)

💰 Economic Simulation

Why: Test DeFi protocols under various market conditions

Features:

Mock Chainlink oracle responses
Simulate Uniswap V2/V3 price changes
Test liquidation thresholds
Calculate slippage and MEV opportunities
Stress test with extreme price movements

🌐 Multi-Network Simulation

Why: Test cross-chain protocols

Features:

Simulate on multiple chains simultaneously
Mock bridge messages (LayerZero, Wormhole)
Verify state consistency across chains
Test cross-chain MEV strategies

🤖 AI-Powered Error Analysis

Why: Help developers understand cryptic errors

Features:

Send trace + error to LLM (Claude/GPT)
Plain English error explanations
Suggested fixes with code examples
Link to similar issues on GitHub
Generate debugging checklist

🙌 Contributing

Want to help build these features? Here's how:

Vote: Star ⭐ the features you want most in GitHub Issues
Discuss: Join feature discussions and share your use cases
Build: Pick an unassigned feature and submit a PR
Sponsor: Help fund development of critical features

Feature Status Legend:

Planned - Not started yet
[🚧] In Progress - Actively being developed
[✅] Completed - Available in latest release

📬 Feature Requests

Have an idea not listed here? Open an issue with:

Use Case: What problem does it solve?
User Story: As a [role], I want [feature] so that [benefit]
Alternatives: What workarounds exist today?
Priority: How critical is this for your workflow?

See our GitHub Issues for full roadmap and active discussions.

FAQ

General Questions

Q: What's the difference between yarn simulate and yarn simulate:anvil?

A:

yarn simulate - Runs on current network state, requires RPC with debug_traceCall for full tracing
yarn simulate:anvil - Forks network at specific block using Docker, always has full tracing support

Q: Do I need an archive node?

A: No! Anvil simulation works with standard free RPC endpoints. It uses --no-storage-caching --accounts 0 flags to avoid requiring archive access.

Q: Which Explorer API should I use?

A:

Etherscan API v2 (recommended) - Single endpoint for 50+ chains with chainid parameter
Etherscan API v1 - Chain-specific endpoints (legacy)
Blockscout - Open source, often doesn't require API keys

Q: How does chain ID auto-detection work?

A: Flashpoint connects to your RPC endpoint and queries the network chain ID. This ensures the correct chain ID is used when fetching ABIs from Etherscan, even when simulating on Anvil (which uses chain ID 31337 locally).

Troubleshooting

Q: Why am I getting "No ABI found for contract (NOTOK)"?

A: Common causes:

Contract not verified on Explorer - Add ABI manually to ./abis directory
Wrong Explorer API URL - Check you're using correct endpoint for your network
Rate limiting - Wait a moment and retry
Chain ID mismatch (fixed in latest version via auto-detection)

Q: Trace shows all on one line without formatting?

A: This was a bug in earlier versions. Update to latest version where trace rendering uses proper newlines (join('\n')).

Q: Can I decode custom errors from my own contracts?

A: Yes! Place your contract ABI JSON files in the ./abis directory. Supported formats:

Raw ABI array: [{"type":"error","name":"MyError"...}]
Hardhat output: {"abi": [...], "bytecode": "..."}

Q: How do I simulate historical transactions?

A:

Set BLOCK_NUMBER in .env to the historical block
Use yarn simulate:anvil to fork at that block
Ensure your RPC has historical block data (last 128 blocks for free RPCs)

Q: What if my RPC doesn't support debug_traceCall?

A: The simulation will fall back to standard eth_call. You'll see results but without the detailed call tree. For full tracing, use:

Alchemy Archive nodes
Hardhat node
Anvil fork simulation (yarn simulate:anvil)

Performance & Limits

Q: How many contracts can Flashpoint fetch ABIs for?

A: No hard limit, but rate limiting applies:

Built-in: 200ms delay between requests (5 req/sec)
Etherscan: 5 req/sec with API key, 1 req/sec without
ABIs are cached locally after first fetch

Q: How long calldata can I use?

A: No limit on calldata length. Display is automatically truncated to 0x1234...5678 format for readability, but full data is used in simulation.

Q: Can I use this in CI/CD?

A: Yes! Flashpoint works great in CI/CD:

- name: Run EVM simulation
  run: |
    yarn simulate:anvil
  env:
    CONTRACT_ADDRESS: ${{ secrets.CONTRACT_ADDRESS }}
    RPC_URL: ${{ secrets.RPC_URL }}

Features & Capabilities

Q: What types of calls can I trace?

A: All EVM call types are supported and color-coded:

CALL (cyan)
DELEGATECALL (magenta)
STATICCALL (yellow)
CREATE / CREATE2 (green)
SELFDESTRUCT (red)

Q: Can I decode function return values?

A: Yes! If you have the contract ABI (auto-fetched or in ./abis), return values are automatically decoded with type-specific formatting:

Addresses: Underlined + magenta, with contract names if available
Booleans: Green for true, red for false
Numbers: Plain formatting
Arrays: JSON stringified

Q: How accurate is the gas estimation?

A: Gas estimates are exact for the simulated state. Real transaction gas may differ due to:

State changes between simulation and execution
Block gas limit and base fee changes
MEV searcher interference

Q: Can I use custom ABIs for error decoding?

A: Yes, place ABI files in ./abis directory. Flashpoint will:

Load local ABIs from ./abis
Auto-fetch ABIs from Explorer API (if enabled)
Combine all ABIs for comprehensive decoding

Contributing

Contributions are welcome! Please:

Fork the repository
Create a feature branch
Make your changes with tests
Submit a pull request

See CONTRIBUTING.md for detailed guidelines.

License

ISC

Name		Name	Last commit message	Last commit date
Latest commit History 7 Commits
src		src
.env.example		.env.example
.gitignore		.gitignore
.prettierrc		.prettierrc
Dockerfile		Dockerfile
README.md		README.md
docker-compose.yml		docker-compose.yml
eslint.config.mjs		eslint.config.mjs
hardhat.config.ts		hardhat.config.ts
package.json		package.json
tsconfig.json		tsconfig.json

Phathdt/flashpoint

Folders and files

Latest commit

History

Repository files navigation

Flashpoint - EVM Call Simulator

Table of Contents

Quick Start

Features

Core Functionality

Advanced Decoding

Error Analysis

Developer Experience

Prerequisites

RPC Requirements

Simulation Mode Comparison

Installation

Configuration

Explorer API Configuration Examples

Usage

Standard Simulation

Anvil Fork Simulation (Recommended)

Trace Output Examples

Successful Transaction Trace

Failed Transaction with Error

Color-Coded Elements

Other Commands

Project Structure

Error Handling

Custom Error Decoding

Troubleshooting

Common Issues

Development

Code Quality

Adding New Commands

Advanced Features Roadmap

🥇 High Priority (Coming Soon)

🔄 State Diff Visualization

📊 Gas Profiling & Optimization Suggestions

🔍 Trace Comparison & Diff

🥈 Medium Priority

🎯 Interactive Trace Explorer (TUI)

🔗 Multi-Transaction Simulation

📹 Trace Recording & Replay

🥉 Future Enhancements

🐛 EVM Debugger Integration

🎲 Smart Contract Fuzzing

🔒 Security Analysis

💰 Economic Simulation

🌐 Multi-Network Simulation

🤖 AI-Powered Error Analysis

🙌 Contributing

📬 Feature Requests

FAQ

General Questions

Troubleshooting

Performance & Limits

Features & Capabilities

Contributing

License

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Languages

Packages