> **Can't find what you're looking for?** Use `search_docs` on the docs MCP server at `https://www.getfoundry.sh/api/mcp` to find what you need.
>
> **Have feedback?** Use `submit_feedback` on the same MCP server.

## Build, Runtime, and RPC

Configuration shared by build commands and EVM execution. All fields belong under
`[profile.<name>]` unless a table is shown explicitly.

### Build and project fields

| Field | Type | Default | Description |
| --- | --- | --- | --- |
| `dynamic_test_linking` | boolean | `true` | Dynamically links test contracts. Disable this when using external tools that do not support the generated `vm.deployCode` and `vm.getCode` calls. |
| `snapshots` | path | `snapshots` | Directory used for gas snapshot files. |
| `gas_snapshot_check` | boolean | `false` | Checks generated snapshots against stored snapshots. |
| `gas_snapshot_emit` | boolean | `true` | Writes gas snapshots to disk. |
| `skip` | array of globs | `[]` | Skips matching source paths during build and execution. |
| `test_failures_file` | path | `cache/test-failures` | Stores the last failed tests for reruns. |
| `no_match_coverage` | regular expression or none | none | Excludes matching source paths from coverage reports. |
| `gas_reports_ignore` | array of strings | `[]` | Excludes matching contracts from gas reports. |
| `gas_reports_include_tests` | boolean | `false` | Includes test contracts in gas reports. |
| `build_info` | boolean | `false` | Emits build-info files containing compiler input and output. |
| `build_info_path` | path or none | none | Overrides the build-info output directory. |
| `names` | boolean | `false` | Prints compiled contract names. |
| `sizes` | boolean | `false` | Prints compiled contract sizes. |

`dynamic_test_linking` is enabled by default since Foundry 1.8.0. It rewrites
contract deployments in tests and scripts to `vm.deployCode` and `vm.getCode`, so
changing a contract does not recompile the tests that deploy it. As a result, test
and script artifacts no longer contain the `linkReferences` of libraries used by the
contracts they deploy. Tools that link libraries from artifacts should read
`linkReferences` from the deployed contract's own artifact, or set
`dynamic_test_linking = false` to restore them in harness artifacts.

### Compiler and diagnostic fields

| Field | Type | Default | Description |
| --- | --- | --- | --- |
| `ast` | boolean | `false` | Includes the AST in compiler output. |
| `cbor_metadata` | boolean | `true` | Appends CBOR metadata to bytecode. |
| `via_ssa_cfg` | boolean | `false` | Enables Solidity's experimental SSA CFG pipeline and implies `via_ir`. |
| `experimental` | boolean | `false` | Passes Solidity's experimental-mode option to the compiler. |
| `extra_args` | array of strings | `[]` | Passes additional arguments to the `solc` binary. |
| `ignored_error_codes_from` | array | `[]` | Silences selected compiler diagnostics for specific path prefixes. |
| `deny` | `never`, `warnings`, or `notes` | `never` | Selects the minimum diagnostic level that makes a command fail. |

`ignored_error_codes_from` is an array of path-and-code pairs:

```toml
ignored_error_codes_from = [
  ["src/generated", [1878, 5574]],
]
```

### EVM execution fields

| Field | Type | Default | Description |
| --- | --- | --- | --- |
| `fork_block_number` | integer or none | none | Pins the block used for a fork. |
| `fork_state_by_number` | boolean | `false` | Reads fork state by block number for RPCs that cannot serve it by hash. |
| `code_size_limit` | integer or none | none | Overrides the EIP-170 deployed-code size limit. |
| `block_prevrandao` | bytes32 | zero | Sets `block.prevrandao` (`mix_hash` before the Merge). |
| `block_gas_limit` | integer or none | none | Sets `block.gaslimit`; distinct from the per-call `gas_limit`. |
| `isolate` | boolean | `true` | Executes each top-level call in a separate EVM transaction context. |
| `disable_block_gas_limit` | boolean | `false` | Disables block gas-limit checks. |
| `enable_tx_gas_limit` | boolean | `false` | Enables the Osaka transaction gas-limit check from EIP-7825. |
| `live_logs` | boolean | `false` | Displays `console.log` output while tests or scripts execute. |
| `allow_internal_expect_revert` | boolean | `false` | Allows `expectRevert` to match internal calls. |
| `always_use_create_2_factory` | boolean | `false` | Uses the CREATE2 factory in tests and non-broadcast scripts. |
| `eip1559_fee_estimate` | string | `market` | Selects `low`, `market`, or `aggressive` script fee estimation. |
| `assertions_revert` | boolean | `true` | Makes native cheatcode assertions revert. |
| `legacy_assertions` | boolean | `false` | Uses the legacy `failed()` assertion check. |
| `unchecked_cheatcode_artifacts` | boolean | `false` | Disables artifact freshness checks for `vm.getCode` and `vm.getDeployedCode`. |
| `decode_external_storage` | boolean | `false` | Decodes the storage of contracts outside the local project in state diffs using verified block explorer sources. |
| `create2_library_salt` | bytes32 | zero | Sets the CREATE2 salt used for library deployment. |
| `create2_deployer` | address | `0x4e59…956c` | Sets the CREATE2 deployer address. |
| `transaction_timeout` | integer | `120` | Sets the transaction timeout in seconds. |
| `script_execution_protection` | boolean | `true` | Prevents unsafe script execution. |

### Fork state by block number

`fork_state_by_number` makes Forge read account balances, nonces, code, and storage
using the resolved fork block's number instead of its hash. Use it when your RPC
serves state by number but rejects hash selectors or cannot serve older state by
hash. It does not restore historical state that the RPC no longer has.

* Section: a profile, such as `[profile.default]`
* Type: boolean
* Default: `false`
* Environment: `FOUNDRY_FORK_STATE_BY_NUMBER` or `DAPP_FORK_STATE_BY_NUMBER`

```toml
[profile.default]
fork_state_by_number = true
```

The setting covers `forge test`, forks created or rolled to a block number by
cheatcodes, and the initial and simulation state reads made by `forge script`. The `--fork-state-by-number` flag enables
it for an individual run and takes precedence over configuration and environment
values. Omitting the flag preserves the configured value.

You can scope it to a named profile alongside that profile's `eth_rpc_url` when
only one network requires it. It is a profile setting, not an `rpc_endpoints`
entry option.

Hash-based reads remain the default. Number-based reads use the resolved block
number, but cannot guarantee the same state if the remote chain reorganizes.
`fork_block_number` alone selects the fork block without enabling this mode.
Number-mode forks keep their state cache in memory and do not read or write the
disk cache.

Forks created or rolled to a transaction hash, and `cast run`, still require
hash-addressed state. `vm.transact` rejects number-mode forks; use a
transaction-targeted fork with an RPC that supports state by hash for replay.

### External storage decoding

`decode_external_storage` labels the storage slots of contracts that are not part
of the local project in `vm.getStateDiff()` and `vm.getStateDiffJson()` output.
For each such contract written to during recording, Forge fetches the verified
source from the block explorer configured for the chain, compiles it for its
storage layout, and decodes the slots with that layout. For a `delegatecall`,
the layout of the implementation that executed the write is used. Sourcify is not
consulted, since its responses do not carry the sources needed for compilation.

* Type: boolean
* Default: false
* Environment: `FOUNDRY_DECODE_EXTERNAL_STORAGE`

```toml
[profile.default]
decode_external_storage = true
```

`forge test --decode-external-storage` enables it for a single run. Lookups
require an `[etherscan]` entry or `etherscan_api_key` for the chain being
forked, and are bounded by `external_identification_timeout` in the `[tracing]`
section. Resolved layouts are cached under the block explorer cache directory,
so later runs skip the fetch and the compile; `forge cache clean` removes them.

### File-system permissions

`fs_permissions` controls which paths file cheatcodes may access. Each entry has
an `access` value (`read`, `write`, `read-write`, or `none`) and a path:

```toml
fs_permissions = [
  { access = "read", path = "out" },
  { access = "read-write", path = "./tmp" },
]
```

### RPC fields

| Field | Type | Default | Description |
| --- | --- | --- | --- |
| `eth_rpc_accept_invalid_certs` | boolean | `false` | Accepts invalid TLS certificates. |
| `eth_rpc_no_proxy` | boolean | `false` | Disables system and environment proxy detection. |
| `eth_rpc_jwt` | string or none | none | Supplies a JWT secret for RPC authentication. |
| `eth_rpc_timeout` | integer or none | none | Sets the RPC timeout in seconds. |
| `eth_rpc_headers` | array of strings or none | none | Adds `name:value` headers to RPC requests. |
| `eth_rpc_curl` | boolean | `false` | Prints an equivalent cURL command instead of sending the request. |
| `no_rpc_rate_limit` | boolean | `false` | Disables provider rate limiting. |

Named endpoints under `[rpc_endpoints]` accept either a URL string or an object.
Objects support `endpoint` (or an `endpoints` array), `auth`, `retries`,
`retry_backoff`, and `compute_units_per_second`:

```toml
[rpc_endpoints]
mainnet = { endpoints = ["${MAINNET_RPC_URL}", "${FALLBACK_RPC_URL}"], retries = 5, retry_backoff = 1000, compute_units_per_second = 330 }
```

`[rpc_storage_caching]` supports `chains` (`"all"`, `"none"`, or an array of
chains) and `endpoints` (`"all"`, `"remote"`, or a regular expression).