> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dokrypt.com/llms.txt
> Use this file to discover all available pages before exploring further.

# State Snapshots

> Save, restore, diff, export, and import chain state for reproducible testing.

## Overview

Snapshots let you capture the entire state of your local blockchain at a point in time and restore it later. This is essential for:

* **Reproducible tests** — Reset to a known state between test runs
* **Fast iteration** — Deploy contracts once, snapshot, then restore after each experiment
* **Team sharing** — Export snapshots and share with teammates
* **Debugging** — Snapshot before a failure and restore to investigate

## How Snapshots Work

Dokrypt snapshots use the EVM's built-in `evm_snapshot` and `evm_revert` JSON-RPC methods. When you save a snapshot:

1. A `evm_snapshot` call returns a snapshot ID
2. Metadata (name, block number, chain ID, description, tags) is saved to `~/.dokrypt/snapshots/<project>/`

When you restore:

1. `evm_revert` is called with the snapshot ID
2. The chain state rolls back to the exact state at the time of the snapshot
3. A new snapshot is taken at the same point (EVM snapshots are consumed on revert)

## Quick Start

```bash theme={null}
# Start your environment
dokrypt up

# Deploy contracts, do some setup...

# Save the current state
dokrypt snapshot save after-deploy --description "Contracts deployed and configured"

# Run some experiments, make changes...

# Restore back to the clean state
dokrypt snapshot restore after-deploy

# Chain is now back to the exact state after deployment
```

## Snapshot Lifecycle

```mermaid theme={null}
graph LR
    A["save"] --> B["list"]
    B --> C["restore"]
    C --> D["delete"]
    A --> E["export"]
    C --> F["import"]
```

## Commands

### Save

```bash theme={null}
dokrypt snapshot save <name> [--description "..."] [--tags tag1 --tags tag2]
```

### Restore

```bash theme={null}
dokrypt snapshot restore <name>
```

### List

```bash theme={null}
dokrypt snapshot list
```

### Delete

```bash theme={null}
dokrypt snapshot delete <name>
```

### Export / Import

```bash theme={null}
# Export to share with teammates
dokrypt snapshot export my-snapshot ./backup.json

# Import on another machine
dokrypt snapshot import ./backup.json
```

Export uses `anvil_dumpState` to capture the full chain state (accounts, storage, nonces, code). The exported JSON file contains both the metadata and the complete state.

### Diff

```bash theme={null}
dokrypt snapshot diff snapshot-a snapshot-b
```

Shows block number delta and time difference between two snapshots.

## Use Cases

### Test Isolation

```bash theme={null}
# Save clean state before each test suite
dokrypt snapshot save clean

# Run tests...

# Restore for next suite
dokrypt snapshot restore clean
```

### Contract Development Workflow

```bash theme={null}
# 1. Start clean environment
dokrypt up --fresh

# 2. Deploy contracts
forge script scripts/Deploy.s.sol --rpc-url http://localhost:8545

# 3. Snapshot the deployed state
dokrypt snapshot save deployed

# 4. Iterate on contract interactions
# ...make changes, test, break things...

# 5. Restore to deployed state
dokrypt snapshot restore deployed

# 6. Try again with a different approach
```

### Sharing State with Team

```bash theme={null}
# Developer A: Export the state
dokrypt snapshot export fully-configured ./team-state.json

# Developer B: Import the state
dokrypt snapshot import ./team-state.json
dokrypt snapshot restore fully-configured
```

## Storage

Snapshots are stored at:

<Tree>
  <Tree.Folder name="snapshots" defaultOpen>
    <Tree.Folder name="my-project" defaultOpen>
      <Tree.File name="my-snapshot.json" />

      <Tree.File name="before-deploy.json" />
    </Tree.Folder>
  </Tree.Folder>
</Tree>

Each metadata file contains:

```json theme={null}
{
  "name": "my-snapshot",
  "description": "Fresh deployment",
  "tags": ["v1.0"],
  "created_at": "2025-01-15T10:30:00Z",
  "project": "my-dapp",
  "chains": {
    "ethereum": {
      "name": "ethereum",
      "engine": "anvil",
      "chain_id": 31337,
      "block_number": 42,
      "state_file": ""
    }
  }
}
```

<Note>
  Export/import (`anvil_dumpState`/`anvil_loadState`) is Anvil-specific. If using Hardhat or Geth, basic `evm_snapshot`/`evm_revert` still works, but full state export is not available.
</Note>