Foundry 快照语义修正:Anvil 回退到早期快照时废弃更新的状态快照
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 容器中,并且仍然可以被继续回退。这会造成时间线混乱:链状态已经回到早期,却还允许跳回一个基于旧时间线创建的"更新快照",其记录的区块哈希、时间偏移与费用状态都已经与当前链失去对应关系。
补丁之后的行为是:
evm_revert(id)只保留 id 更小(更早) 的快照;- 所有 id 更大(更新)的快照被立即废弃,后续对其发起
evm_revert将返回false; - 被回退快照本身(
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);
}
测试流程清晰还原了变更语义:
- 在初始高度
initial_block上取第一个快照(id 较小); - 挖一个新块后取第二个快照(id 较大);
- 回退到第一个快照——断言返回
true; - 再尝试回退第二个快照——断言返回
false,因为它已被废弃; - 最后断言最新区块等于
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 模式下都保持了一致的语义——这正是链上状态测试工具对"快照"这一核心抽象应有的严谨态度。