Echidna

Run Echidna smart contract fuzzer against an immutable prebuilt project artifact. Supports both Foundry and Hardhat project layouts. The project must be prebuilt — Echidna runs directly against compiled artifacts without invoking forge build or hardhat compile on the worker.

Current public support: shared placement on CPU workers only. Submit via POST /api/v1/recipes/echidna/jobs or POST /api/v1/jobs with "recipe": "echidna".

Operations

Operation	Description
`foundry_prebuilt`	Run Echidna against a prebuilt Foundry project archive
`hardhat_prebuilt`	Run Echidna against a prebuilt Hardhat project archive

Payload Fields

Field	Type	Required	Default	Description
`operation`	string	yes	—	`foundry_prebuilt` or `hardhat_prebuilt`
`project_ref`	string	yes	—	Artifact ID of the prebuilt project archive
`contract`	string	yes	—	Target contract name
`test_mode`	string	no	`property`	`property`, `assertion`, `foundry`, `overflow`, `optimization`, `exploration`
`test_limit`	integer	no	—	Max number of tests
`seq_len`	integer	no	—	Max transaction sequence length
`shrink_limit`	integer	no	—	Max shrink attempts
`seed`	integer	no	—	Random seed
`stop_on_fail`	boolean	no	—	Stop on first failure
`workers`	integer	no	—	Number of parallel workers

Examples

Fuzz a Foundry project


POST /api/v1/recipes/echidna/jobs
{
  "payload": {
    "operation": "foundry_prebuilt",
    "project_ref": "art_project_123",
    "contract": "VaultEchidna",
    "test_mode": "assertion",
    "test_limit": 2000
  },
  "timeout_s": 1800
}

Fuzz with specific seed


POST /api/v1/recipes/echidna/jobs
{
  "payload": {
    "operation": "foundry_prebuilt",
    "project_ref": "art_project_123",
    "contract": "TokenEchidna",
    "test_mode": "property",
    "test_limit": 5000,
    "seed": 42,
    "workers": 4
  },
  "timeout_s": 3600
}

Preparing Your Project

Upload a prebuilt project archive as an artifact:


# Build locally first
cd my-foundry-project && forge build
 
# Create archive and upload
tar czf project.tar.gz .
curl -sS -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/octet-stream" \
  -H "X-Artifact-Filename: project.tar.gz" \
  --data-binary @project.tar.gz \
  "$BASE_URL/api/v1/artifacts"

Use the returned artifact ID as project_ref.

Result Fields

success, contract, test_mode, tests_failed, failing_tests, coverage_collected, returncode, output_tail

Artifact Outputs

Artifact	Description
`campaign`	Echidna campaign JSON
`stdout`	Full stdout log
`stderr`	Full stderr log
`coverage`	Coverage data archive
`corpus`	Fuzzing corpus archive