Deep smart-contract fuzzing and exploit-sequence generation with ItyFuzz for EVM protocols (onchain forks from deployed addresses, offchain fuzzing from .abi/.bin or build commands, Foundry-style setup/invariant harnesses, detector/oracle tuning, replay/corpus triage, and Foundry PoC generation). Use when you need to hunt complex cross-contract chaining sequences, flashloan/price manipulation paths, reentrancy, fund-loss bugs, or deep protocol logic invariant violations in a protocol.
Use ItyFuzz to turn a protocol (onchain or local) into reviewable, reproducible artifacts:
work_dir/vulnerabilities/*.t.sol)vuln_info.jsonl, optional relations.log)Hard rule: do not guess CLI flags. Always consult references/cli-ityfuzz-evm-help.txt and/or run ityfuzz evm --help in the target environment.
$sourcify-contract-bundler for source/ABI/proxy mapping and onchain evidence$traverse-protocol-analysis for call graphs + storage access maps (choose entrypoints/invariants)$tenderly-protocol-lab for evidence-grade decoded traces/simulations (cheapest discriminators + E3 proof artifacts)When the user asks to “find deep/novel protocol bugs”, follow this loop and keep outputs explicit.
Produce (as text artifacts) the following:
If you already ran $traverse-protocol-analysis, mine:
Read references/sequence-driven-vuln-taxonomy-2026.md and generate a Hypothesis Matrix.
For each hypothesis, fill:
-t multi-target)Then pick the top 3-10 hypotheses by:
Pick the least constraining mode that still reproduces reality:
invariant_*()).Avoid prematurely writing bespoke configs unless forced.
Escalate in this order:
-f/--flashloan for DeFi sequences.--concolic --concolic-caller) when conditions/timing gates block progress.--detectors ...) when the bug is not “fund extraction” shaped.--run-forever, vary --seed) once you have the right target set and the fuzzer is exploring the right call surface.For each bug:
*_replayable) and confirm determinism..t.sol as a base and add:
# Minimal onchain campaign (address mode)
ityfuzz evm \
-t 0xTarget1,0xTarget2 \
-c bsc -b 23695904 \
-f \
-k "$BSC_ETHERSCAN_API_KEY" \
-w analysis/ityfuzz/onchain-run
# Requires *.abi + *.bin in ./build/
ityfuzz evm \
-t './build/*' \
--detectors high_confidence \
-w analysis/ityfuzz/offchain-run
# Build the project via Foundry and deploy an ItyFuzz harness contract.
# The harness contract must implement setUp() + targetContracts/targetSelectors/etc.
ityfuzz evm \
-m test/ItyFuzzHarness.sol:ItyFuzzHarness \
-f \
-w analysis/ityfuzz/foundry-harness \
-- forge test
See references/foundry-setup-harness.md and assets/ItyFuzzHarness.sol.
Collect:
-c/--chain-type and -b/--onchain-block-number.-t-t (e.g. ./build/*)-m file.sol:ContractNameETH_RPC_URL for performance/stability (archive RPC recommended for backtests)-k/--onchain-etherscan-api-key or ETHERSCAN_API_KEY env varIf the user provides only a single core address, proactively request the likely dependency set (tokens/pairs/routers/oracles/proxies).
Use references/target-types-and-modes.md to decide between:
glob (offchain artifacts)address (onchain fork)setup (Foundry harness; complex initialization + selector targeting)config (advanced fixed-address + ABI-encoded constructor args)anvil_fork (onchain + build artifacts mapping)Do:
ityfuzz --help and ityfuzz evm --helpreferences/cli-ityfuzz-evm-help.txt if needed-w analysis/ityfuzz/<campaign-name>ETH_RPC_URL, explorer keys, chain/block, and exact command (manifest)python skills/ityfuzz-protocol-hunter/scripts/ityfuzz_run_evm.py \
-w analysis/ityfuzz/campaign-1 -- \
<PASTE YOUR ityfuzz evm FLAGS HERE>
Onchain mode:
-t addr1,addr2,... (see official-tutorials-exp-known-working-hacks.md).--force-abi address:path/to/abi.json when decompilation is noisyOffchain mode:
--constructor-args "Contract:arg1,arg2;Other:arg1;..." (see official-docs-evm-contract-constructor-for-offchain-fuzzing.md)--fetch-tx-data proxy-forwarding method for “deploy then fuzz” workflows.Optional (recommended) mapping phase:
$sourcify-contract-bundler to fetch sources/ABIs + proxy mappings for the protocol.$traverse-protocol-analysis to generate call graphs + storage access maps.Detectors:
--detectors high_confidence (default) and -f for DeFi.references/detectors-and-oracles.md.Invariants (offchain + harness mode is best):
invariant_*() (ItyFuzz reports a bug when the call reverts)echidna_*() (ItyFuzz reports a bug when returns false / reverts)bug() / typed_bug(string) markers (see official-docs-evm-contract-writing-invariants.md).scribble ... --no-assert and fuzzing the compiled output (see the same doc).Pass A: baseline (fast)
-c/-b -k -f --detectors high_confidence-t './build/*' --detectors high_confidencePass B: unlock hard conditions (concolic)
--concolic --concolic-caller--concolic-timeout / --concolic-num-threadsPass C: widen detector surface
--detectors (see reference).Pass D: long-run bug harvest
--run-forever--seed across runs for diversity--write-relationship to keep relations.logAlways check:
work_dir/vuln_info.jsonl (machine-readable oracle outputs)work_dir/vulnerabilities/*.t.sol (Foundry PoCs)work_dir/vulnerabilities/*_replayable (replayable minimized traces)Summarize a run:
python skills/ityfuzz-protocol-hunter/scripts/ityfuzz_summarize_workdir.py analysis/ityfuzz/campaign-1
Replay a minimized trace:
--replay-file with the _replayable file glob (see references/replay-and-corpus.md).Deliver:
ETH_RPC_URL, explorer key).work_dir/ (or at minimum: vuln_info.jsonl, vulnerabilities/*.t.sol, _replayable traces, stdout.log, stderr.log).scripts/ityfuzz_run_evm.py: run ityfuzz evm with a manifest + stdout/stderr logs.scripts/ityfuzz_summarize_workdir.py: summarize vuln_info.jsonl + generated PoCs.references/ityfuzz-docs-index.md: map of all vendored official docs + source-derived notes.references/cli-ityfuzz-evm-help.txt: authoritative EVM CLI flags and defaults.references/sequence-driven-vuln-taxonomy-2026.md: hypothesis generator for deep, multi-step bugs.references/sequence-driven-prompt-pack.md: advanced prompting guide for sequence-driven bug hunting.references/target-types-and-modes.md: pick the correct target type.references/detectors-and-oracles.md: --detectors values and selection guidance.references/foundry-setup-harness.md: write a harness for --deployment-script.references/offchain-config-schema.md: JSON schema for --offchain-config-file/url.references/replay-and-corpus.md: work dir layout + replay/resume workflows.