harb/scripts/harb-evaluator/helpers/anvil.ts

/**
 * Anvil snapshot/revert helpers for the red-team agent feedback loop.
 *
 * snapshot() and revert() use Anvil's proprietary RPC methods to save and
 * restore chain state, allowing scenarios to run mutating actions and then
 * reset the fork cleanly.
 *
 * mineBlocks is re-exported from recenter.ts so callers can import both
 * snapshot helpers and block-mining from a single module.
 */
import { rpcCall } from './rpc.js';
export { mineBlocks } from './recenter.js';

/**
 * Take an Anvil chain snapshot.
 *
 * @returns The snapshot ID (hex string) to pass to revert().
 */
export async function snapshot(rpcUrl: string): Promise<string> {
  const id = (await rpcCall(rpcUrl, 'anvil_snapshot', [])) as string;
  console.log(`[anvil] Snapshot taken: ${id}`);
  return id;
}

/**
 * Revert the chain to a previously taken snapshot.
 *
 * ⚠️  anvil_revert is one-shot: the snapshot is consumed on success and the ID
 * becomes invalid afterward.  Callers that need to reuse a checkpoint must
 * call snapshot() again after each revert.
 *
 * Throws if Anvil reports the revert as unsuccessful (e.g. unknown or already-used
 * snapshot ID).
 *
 * @param snapshotId - The hex snapshot ID returned by snapshot().
 */
export async function revert(rpcUrl: string, snapshotId: string): Promise<void> {
  const success = (await rpcCall(rpcUrl, 'anvil_revert', [snapshotId])) as boolean;
  if (!success) throw new Error(`[anvil] revert failed for snapshot ${snapshotId}`);
  console.log(`[anvil] Reverted to snapshot: ${snapshotId}`);
}