project.yaml Reference

Multi-file projects are declared in YAML and loaded with --project.

name: my-dapp
target: evm          # required: evm | lean
output_dir: build/
sources:             # required
  - Token.cam
  - Vault.cam
  - Vault.test.cam
library_paths:
  - ${CAMBRIAN_STDLIB}     # optional; env-expanded
  - ../vendor/cam-libs
imports:
  - math.cam               # shared helpers, not entities
  - token/erc20-core.cam

Top-level keys

Key	Type	Notes
`name`	string	Optional; defaults to the directory name in the `--project` path (`project` when the path is a bare file name). Used for the EVM bundle file `src/_<name>_project.sol`
`target`	string	Required — `evm` or `lean`
`output_dir`	string	Default `build/`, relative to the YAML file
`sources`	list of paths	Required — entry-point `.cam` files (entities, tests)
`library_paths`	list of paths	Extra directories for shared `.cam` files. `${VAR}` is expanded; then absolute or relative to the YAML. No built-in default.
`imports`	list of paths	Shared helper files (not entities). Yaml directory first, then each `library_paths` entry. Same program-wide names as your own files.
`evm`	object	EVM codegen knobs
`foundry`	object	Foundry / solc settings
`fuzz`	object	Default fuzz runs / seed
`invariant`	object	Default invariant runs / depth
`lean`	object	Lean emission knobs

Unknown keys, at the top level or inside one of the blocks below, are ignored with an F7 warning (for example project.yaml: unknown key `foundry.solc_versoin` (ignored)), so a misspelt setting shows up in the build output.

Shared files (`library_paths` / `imports`)

Leave both keys out if you do not need them; existing projects stay unchanged.

imports: loads shared declaration files the same way import "…" does. They may contain pure fn, types, library, event / error, extern entity, and further imports — not entity, test, fuzz, or invariant. Put those under sources:.
Each path is tried next to the YAML, then in each library_paths directory, in order. The first file that exists wins.
If nothing matches, the error lists every directory that was tried. An unset ${VAR} stays as the text ${VAR} (it does not become the project directory).
A path listed in both sources: and imports: is treated as a project source.
import "./math.cam" / import "../lib/math.cam" stay relative to the importing file and do not search library_paths. A path without ./ or ../ (import "token/erc20-core.cam") tries the importer’s directory first, then library_paths.
Imported names are not namespaced. See Program Structure and the Contract Standard Library.

`evm`

Key	Default	Notes
`allow_constructor_payable`	`true`	When `false`, entity constructors are non-payable and the `CambrianFactory` deploys with `value: 0`

`foundry`

These keys are written into the generated foundry.toml.

Key	Default	Notes
`solc_version`	`0.8.24`	Compiler version
`evm_version`	`prague`	EVM revision
`optimizer`	`false`	Optimizer on/off
`optimizer_runs`	`200`	Optimizer runs
`via_ir`	`false`	IR pipeline
`fuzz_runs`	`fuzz.runs`	Default Foundry fuzz runs (overrides `fuzz.runs`)
`profiles`	—	Overrides for the generated `cambrian` / `cambrian_night` profiles: `fuzz_runs`, `invariant_runs`, `invariant_depth`, `fail_on_revert`
`remappings`	—	Solc remappings (`"prefix=path"` strings)

The generated foundry.toml always contains two extra profiles: cambrian (fuzz 100, invariant runs 50, depth 50) for quick runs and cambrian_night (fuzz 10000, invariant runs 5000, depth 250) for long runs, selected with FOUNDRY_PROFILE=cambrian forge test.

`fuzz` / `invariant`

Section	Key	Default	Notes
`fuzz`	`runs`	256	Fuzz cases per test
`fuzz`	`seed`	0	0 = random; non-zero pins the RNG
`fuzz`	`max_local_rejects`	1024	Written as Foundry `max_test_rejects`
`invariant`	`runs`	256	Invariant runs
`invariant`	`depth`	50	Calls per run
`invariant`	`fail_on_revert`	`false`	Fail the run on any reverting call
`invariant`	`seed`	0	0 = random; non-zero pins the RNG

fuzz.shrink is accepted for compatibility but has no effect; setting it produces an F7 warning.

In project mode these defaults are always written to foundry.toml. Single-file builds have no YAML and write only fuzz.runs = 256, leaving the rest to Foundry’s own defaults.

`lean`

Key	Default	Notes
`numerics`	`overflow-wrap`	`overflow-wrap` (legacy alias `bitvec`), `overflow-panic`, or `nat`. Any other value is an error (F2)
`proof_helpers`	`true`	`false` drops generated proof helpers (simp lemmas, proof scaffolding); theorems are then emitted as statements with `sorry`
`intrinsics`	`opaque`	`opaque` or `executable` (computable, non-cryptographic hash models). Any other value is an error (F2)
`lean_toolchain`	`leanprover/lean4:v4.29.1`	Written to the generated `lean-toolchain` file

Cambrian Language Documentation