Foundry 快照语义修正:Anvil 回退到早期快照时废弃更新的状态快照

原创2026-09-15 21:36:331,877 阅读
文章标签:区块链开发工具

Foundry 快照语义修正:Anvil 回退到早期快照时废弃更新的状态快照

本文解读 Foundry 仓库中一份针对 Anvil 与 EVM 核心库的补丁变更:Anvil 现在会在回退(revert)到某个早期快照时,同步废弃所有更新的状态快照。文章将结合 crates/anvil 与 crates/evm/core 的源码实现和集成测试,说明这一行为变更的前因后果、底层机制,以及对测试脚本与工具集成方的实际影响。读完你可以准确理解 evm_snapshot / evm_revert 快照的生命周期语义,避免在依赖旧行为的代码上踩坑。

变更速览:一次针对快照生命周期的补丁修复

该变更记录于仓库的 .changelog/anvil-snapshot-invalidation.md,内容非常精炼:

anvil: patch
foundry-evm-core: patch
---

Anvil now invalidates newer state snapshots when reverting to an earlier snapshot.

从 changelog 头部可以读出两个关键信息:

  • 影响的 crate 有两个:anvil(节点本体)与 foundry-evm-core(EVM 后端核心库),均以 patch(补丁级)版本提升发布;
  • 变更的核心语义:当通过 evm_revert 回退到某个更早的快照时,比该快照更新的所有快照都会被一并废弃(invalidated),不再允许回退。

这份变更并非孤立的文档描述,它在 Anvil 的 RPC 层、EVM 后端的快照容器以及 fork 数据库三条链路上都有对应的代码与测试佐证,下面逐一展开。

背景:Anvil 的状态快照机制

Anvil 作为 Foundry 生态的本地开发节点,通过 RPC 提供两条标准的快照方法,其枚举定义位于 crates/anvil/core/src/eth/mod.rs:

  • evm_snapshot(服务端同时以 anvil_snapshot 作为别名):在当前区块高度为整个链上状态创建快照,返回单调递增的快照 id;
  • evm_revert(别名 anvil_revert):接收快照 id,将链状态回退到该快照记录的时刻。

对应的 RPC 处理器在 crates/anvil/src/eth/api.rs 与 crates/anvil/src/eth/api.rs 中实现,分别委托给 backend.create_state_snapshot() 与 backend.revert_state_snapshot(id)。

一个快照里记录了什么

在 crates/anvil/src/eth/backend/mem/mod.rs 的 create_state_snapshot 中可以看到,Anvil 为每个快照记录四类信息:

  • block_number / block_hash:快照时刻的最新区块定位信息;
  • fees:当前 basefee 等费用状态的快照;
  • time_offset:evm_setTime / evm_increaseTime 造成的时间偏移量;
  • 底层数据库(self.db)中的完整账户、存储、区块哈希状态。

也就是说,一个快照不是简单记录"改过的存储槽",而是足以把区块高度、区块哈希、费用、时间、世界状态整体复原的完整时间线坐标。

快照 id 的分配规则

快照 id 由 foundry-evm-core 中的 StateSnapshots<T> 容器统一管理,见 crates/evm/core/src/state_snapshot.rs:

fn next_id(&mut self) -> U256 {
    let id = self.id;
    self.id = id.saturating_add(U256::from(1));
    id
}

id 从 0 开始严格单调递增——id 越小代表快照创建得越早,id 越大代表快照越新。这一单调性正是本次补丁实现"废弃更新快照"逻辑的前提。

行为变更:回退时废弃更新的快照

在本次补丁之前,evm_revert(早期快照) 成功回退后,所有 id 更大的快照仍然保留在 Anvil 的 active_state_snapshots 容器中,并且仍然可以被继续回退。这会造成时间线混乱:链状态已经回到早期,却还允许跳回一个基于旧时间线创建的"更新快照",其记录的区块哈希、时间偏移与费用状态都已经与当前链失去对应关系。

补丁之后的行为是:

  1. evm_revert(id) 只保留 id 更小(更早) 的快照;
  2. 所有 id 更大(更新)的快照被立即废弃,后续对其发起 evm_revert 将返回 false;
  3. 被回退快照本身(id 对应的那一个)同样被移除。

源码实现剖析

Anvil 侧:active_state_snapshots 的一次性清理

补丁的核心逻辑位于 crates/anvil/src/eth/backend/mem/mod.rs 的 revert_state_snapshot:

let Some((num, hash, fees, time_offset)) =
    self.active_state_snapshots.lock().get(&id).map(|snapshot| {
        (snapshot.block_number, snapshot.block_hash, snapshot.fees, snapshot.time_offset)
    })
else {
    return Ok(false);
};
let block = self.block_by_hash(hash).await?.ok_or(BlockchainError::BlockNotFound)?;
if !self.db.write().await.revert_state(id, RevertStateSnapshotAction::RevertRemove) {
    return Ok(false);
}
{
    let mut snapshots = self.active_state_snapshots.lock();
    snapshots.remove(&id);
    snapshots.retain(|snapshot_id, _| *snapshot_id < id);
}
// Revert the storage that's newer than the snapshot.
self.blockchain.storage.write().unwind_to(num, hash);

关键就在这一行:

snapshots.retain(|snapshot_id, _| *snapshot_id < id);

retain 会遍历全部快照,只保留 id 严格小于目标 id 的条目,也就是保留更早的快照、剔除所有更新的快照。随后 unwind_to(num, hash) 会把链上存储区块同步回退到快照对应的高度,紧接着(见 同文件第 4803-4824 行)恢复时间偏移、清理 pending 的 prevrandao 覆盖、重建 evm_env.block_env(区块号、时间戳、difficulty、prevrandao、gas_limit 等),最后 fees.restore(fees) 还原费用状态。

注意这里使用的动作是 RevertStateSnapshotAction::RevertRemove:它既移除被回退的 id 快照本身,也(配合 retain)移除所有更新的快照,保证快照容器与回退后的链状态严格一致。

evm-core 侧:StateSnapshots::remove 的级联语义

foundry-evm-core 同样标记为 patch 变更,原因在于快照容器本身的语义。在 crates/evm/core/src/state_snapshot.rs 中,remove 方法的文档注释明确写明了这一级联规则:

/// Removes the state snapshot with the given `id`.
///
/// This will also remove any state snapshots taken after the state snapshot with the `id`.
/// e.g.: reverting to id 1 will delete snapshots with ids 1, 2, 3, etc.)
pub fn remove(&mut self, id: U256) -> Option<T> {
    let snapshot_state = self.state_snapshots.remove(&id);

    // Revert all state snapshots taken after the state snapshot with the `id`
    let mut to_revert = id + U256::from(1);
    while to_revert < self.id {
        self.state_snapshots.remove(&to_revert);
        to_revert += U256::from(1);
    }

    snapshot_state
}

与 remove_at(只移除单个 id、不动其他快照,见 同文件第 51-56 行)不同,remove 会在删除目标 id 后,从 id + 1 一直扫到当前已分配的最大 id,把区间内所有快照一并清掉。这套"id 单调递增 + 区间级联清理"的语义,是整个快照失效机制在核心库层面的统一表达。

Fork 数据库侧:ForkedDatabase 的行为对齐

对于 fork 模式(Anvil 通过 --fork-url 连接到远端链),快照回退走的是 crates/evm/core/src/fork/database.rs 的 insert_state_snapshot 与 同文件第 118-153 行 的 revert_state_snapshot:后者会把本地缓存账户、存储、区块哈希逐一替换为快照时的内容,并将 cache_db 恢复为快照时克隆的本地缓存。行为与内存模式保持一致——回退成功后,快照容器中不再存在该 id 及更新 id 的快照。

测试验证

Anvil 集成测试:精确复现"废弃更新快照"

Anvil 的集成测试 crates/anvil/tests/it/anvil_api.rs 中有一个专门针对本次语义的用例 test_revert_invalidates_newer_snapshots:

#[tokio::test(flavor = "multi_thread")]
async fn test_revert_invalidates_newer_snapshots() {
    let (api, _handle) = spawn(NodeConfig::test()).await;
    let initial_block = api.block_by_number(BlockNumberOrTag::Latest).await.unwrap().unwrap();

    let first_snapshot = api.evm_snapshot().await.unwrap();
    api.mine_one().await.unwrap();
    let second_snapshot = api.evm_snapshot().await.unwrap();

    assert!(api.evm_revert(first_snapshot).await.unwrap());
    assert!(!api.evm_revert(second_snapshot).await.unwrap());

    let latest_block = api.block_by_number(BlockNumberOrTag::Latest).await.unwrap().unwrap();
    assert_eq!(latest_block, initial_block);
}

测试流程清晰还原了变更语义:

  1. 在初始高度 initial_block 上取第一个快照(id 较小);
  2. 挖一个新块后取第二个快照(id 较大);
  3. 回退到第一个快照——断言返回 true;
  4. 再尝试回退第二个快照——断言返回 false,因为它已被废弃;
  5. 最后断言最新区块等于 initial_block,确认链状态确实回到了最初高度。

同文件中的 test_revert_restores_time_offset(第 767-779 行)则验证了回退时时间偏移被正确还原,佐证快照记录内容的完整性。

Fork 数据库单元测试:fork_db_revert_invalidates_newer_snapshots

Fork 数据库侧也有对称的单元测试 crates/evm/core/src/fork/database.rs:

#[tokio::test(flavor = "multi_thread")]
async fn fork_db_revert_invalidates_newer_snapshots() {
    let rpc = foundry_test_utils::rpc::next_http_rpc_endpoint();
    let provider = get_http_provider(rpc.clone());
    let meta = BlockchainDbMeta::new(BlockEnv::default(), rpc);
    let db = BlockchainDb::new(meta, None);
    let backend = SharedBackend::spawn_backend(Arc::new(provider), db.clone(), None).await;
    let mut db = ForkedDatabase::new(backend, db);

    let first = db.insert_state_snapshot();
    let second = db.insert_state_snapshot();

    assert!(db.revert_state_snapshot(first, RevertStateSnapshotAction::RevertRemove));
    assert!(!db.revert_state_snapshot(second, RevertStateSnapshotAction::RevertRemove));
}

与 Anvil 集成测试的断言完全一致:回退 first 成功后,对 second 的再次回退返回 false。这从侧面说明,本次补丁的语义在内存模式与 fork 模式、RPC 层与核心库层是统一对齐的。

与 forge 测试环境 cheatcode 快照的关系

值得区分的是,Anvil RPC 层的 evm_snapshot / evm_revert 与 forge 测试环境中的 cheatcode 快照共用 foundry-evm-core 的底层容器,但 API 不同。forge 侧的对应实现位于 crates/cheatcodes/src/evm.rs:

  • vm.snapshotState():创建快照,返回 id(inner_snapshot_state,第 1600 行);
  • vm.revertToState(id):回退但保留快照(内部使用 RevertStateSnapshotAction::RevertKeep,见 第 1681-1694 行);
  • vm.revertToStateAndDelete(id):回退并删除快照(内部使用 RevertStateSnapshotAction::RevertRemove,见 第 1725-1738 行)。

也就是说:RevertKeep(保留)与 RevertRemove(删除)是底层两种回退动作,Anvil 的 evm_revert 走的是 RevertRemove 语义,而"废弃更新快照"的级联清理由 StateSnapshots 容器负责,与回退动作的选择相互独立。需要提醒的是,revertTo / revertToAndDelete 在源码注释中已被标记为废弃(deprecated),建议新代码统一使用 revertToState / revertToStateAndDelete 命名。

对开发者的影响与使用建议

  • 回退方向是单向的:evm_revert 成功后,任何 id 大于目标 id 的快照都会失效,再次回退将返回 false。测试脚本中如果习惯"先回退到最旧快照、再依次回退较新快照"来清理现场,现在需要改为在回退前一次性规划好回退顺序,或直接重新创建快照。
  • 快照 id 不可复用:由于 id 单调递增且失效快照不会回填 id,程序中不应假设 id 连续或可预测,始终以 evm_snapshot 的返回值作为句柄。
  • 工具集成方需检查返回值:任何调用 evm_revert 的自动化工具都应把 false 视为"快照已失效/不存在"而非简单失败,避免对已废弃快照的二次回退产生误报。
  • 升级注意:该变更以 patch 级别同时发布在 anvil 与 foundry-evm-core 两个 crate,意味着升级 Anvil 后快照生命周期行为会随之变化;对快照时序敏感的 CI 脚本建议在升级后回归验证。

小结

本次补丁的实质,是把 Anvil 快照的"有效期"从无限期收紧为"仅在比它更新的快照尚未被回退前有效":一旦回退到早期快照,链时间线已经重构,所有基于旧时间线的更新快照便失去意义,必须一并废弃。从 active_state_snapshots 的 retain 清理,到 StateSnapshots::remove 的区间级联删除,再到两处命名一致的测试用例,整个机制在内存模式与 fork 模式下都保持了一致的语义——这正是链上状态测试工具对"快照"这一核心抽象应有的严谨态度。

登录后查看全文
foundry