> **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.

## State management

Anvil can save and restore chain state, enabling reproducible test scenarios and faster development workflows.

### Dumping state

Save the current state when Anvil exits:

```bash [Dump state on exit]
$ anvil --dump-state state.json
```

```bash [Dump to a directory]
$ anvil --dump-state ./states/
```

### Loading state

Start from a previously saved state:

```bash [Load from state file]
$ anvil --load-state state.json
```

The `anvil_dumpState` and `anvil_loadState` RPC methods provide the same functionality on a running node, and `anvil_reset` restores a fresh chain; see the [RPC method reference](/anvil/rpc-methods) for parameters and examples.

### Combined state file

Use `--state` to both load and dump from the same file:

```bash [Persist state across restarts]
$ anvil --state state.json
```

This loads the state on startup (if the file exists) and saves it on exit.

### Periodic snapshots

Save state at regular intervals to prevent data loss:

```bash [Dump state every 60 seconds]
$ anvil --state state.json --state-interval 60
```

### Historical states

By default, Anvil only keeps the latest state. Enable historical state preservation for debugging:

```bash [Preserve historical states]
$ anvil --preserve-historical-states --dump-state state.json
```

```bash [Limit persisted states]
$ anvil --max-persisted-states 100
```

### Memory management

For long-running instances, prune historical state to reduce memory usage:

```bash [Prune history (keep 10 states)]
$ anvil --prune-history 10
```

```bash [Prune all history]
$ anvil --prune-history
```

By default, Anvil keeps every locally mined block's transactions, receipts, and logs in memory. To prune older transaction data as new blocks are mined, use `--transaction-block-keeper`:

```bash [Keep transaction data for the last 1000 blocks]
$ anvil --transaction-block-keeper 1000
```

As new blocks are mined locally, Anvil drops transaction data outside this window while retaining the block headers. The dropped transactions, receipts, and logs are no longer available from local storage. This does not change state retention.

The limit does not retroactively prune history loaded from a state file. When forking, historical data may still be available from the upstream RPC provider.

### Genesis configuration

Initialize Anvil with a custom genesis file:

```bash [Use custom genesis]
$ anvil --init genesis.json
```

The genesis file follows the standard Ethereum genesis format with `alloc`, `difficulty`, `gasLimit`, and other fields.