Solidity Cheatcodes

每个 Virtual Environment 都在 0xc100000000000000000000000000000000000000 上暴露一个预编译合约。从交易内部调用此预编译上的函数可让您的合约直接操纵链上状态、存储槽、ETH 余额、ERC-20 代币余额、nonce 和事件日志，而无需假冒账户或部署辅助代理。这些作弊码是对 Admin RPC 方法的补充。Admin RPC 方法从交易外部操纵状态（通过 JSON-RPC）。预编译从交易内部操纵状态（通过 Solidity 调用）。当您的设置需要保持原子性、可从 tx 哈希重放，或者要在多个槽上循环执行时，请使用预编译。

接口

将此文件作为 IVnetPrecompile.sol 添加到您的项目中：

IVnetPrecompile.sol

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.0;

interface IVnetPrecompile {
    function setStorageAt(address target, bytes32 slot, bytes32 value) external returns (bool);
    function setBalance(address[] calldata addresses, uint256 balance) external returns (bool);
    function getStorageAt(address target, bytes32 slot) external view returns (bytes32);
    function addBalance(address[] calldata addresses, uint256 amount) external returns (bool);
    function setNonce(address target, uint256 value) external returns (bool);
    function setErc20Balance(address target, address[] calldata addresses, uint256 amount) external returns (bool);
    function addErc20Balance(address target, address[] calldata addresses, uint256 amount) external returns (bool);
    function setMaxErc20Balance(address target, address account) external returns (bool);

    function emitEvent(address target, bytes calldata data) external returns (bool);
    function emitEvent(address target, bytes32 topic1) external returns (bool);
    function emitEvent(address target, bytes32 topic1, bytes calldata data) external returns (bool);
    function emitEvent(address target, bytes32 topic1, bytes32 topic2) external returns (bool);
    function emitEvent(address target, bytes32 topic1, bytes32 topic2, bytes calldata data) external returns (bool);
    function emitEvent(address target, bytes32 topic1, bytes32 topic2, bytes32 topic3) external returns (bool);
    function emitEvent(address target, bytes32 topic1, bytes32 topic2, bytes32 topic3, bytes calldata data) external returns (bool);
    function emitEvent(address target, bytes32 topic1, bytes32 topic2, bytes32 topic3, bytes32 topic4) external returns (bool);
    function emitEvent(address target, bytes32 topic1, bytes32 topic2, bytes32 topic3, bytes32 topic4, bytes calldata data) external returns (bool);

    event SetStorageAtEvent(address target, bytes32 slot, bytes32 value);
    event SetBalanceEvent(address[] addresses, uint256 balance);
    event AddBalanceEvent(address[] addresses, uint256 amount);
    event SetNonceEvent(address target, uint256 value);
    event SetErc20BalanceEvent(address target, address[] addresses, uint256 amount);
    event AddErc20BalanceEvent(address target, address[] addresses, uint256 amount);
    event SetMaxErc20BalanceEvent(address target, address account);
}

在您的合约中通过固定地址引用它：

IVnetPrecompile constant VNET = IVnetPrecompile(0xc100000000000000000000000000000000000000);

函数

Storage

函数	参数	返回值	描述
`setStorageAt`	`address target`, `bytes32 slot`, `bytes32 value`	`bool`	将 `value` 写入 `target` 上的 `slot`。
`getStorageAt`	`address target`, `bytes32 slot`	`bytes32`	读取 `target` 上 `slot` 的当前值。

VNET.setStorageAt(tokenContract, balanceSlot, bytes32(uint256(1000e18)));
bytes32 val = VNET.getStorageAt(tokenContract, balanceSlot);

Balance

函数	参数	返回值	描述
`setBalance`	`address[] addresses`, `uint256 balance`	`bool`	将 `addresses` 中每个地址的 ETH 余额设置为精确值。
`addBalance`	`address[] addresses`, `uint256 amount`	`bool`	向 `addresses` 中每个地址的当前 ETH 余额添加 `amount`。

address[] memory accounts = new address[](2);
accounts[0] = alice;
accounts[1] = bob;
VNET.setBalance(accounts, 10 ether);
VNET.addBalance(accounts, 2 ether);

ERC-20 balances

函数	参数	返回值	描述
`setErc20Balance`	`address target`, `address[] addresses`, `uint256 amount`	`bool`	在 `target` 处的 ERC-20 代币上，将 `addresses` 中每个地址的余额设置为 `amount`。
`addErc20Balance`	`address target`, `address[] addresses`, `uint256 amount`	`bool`	向 `addresses` 中每个地址的当前代币余额添加 `amount`。
`setMaxErc20Balance`	`address target`, `address account`	`bool`	将 `account` 的代币余额设置为最大值（`2^256 - 1`）。

预编译会自动定位代币的余额存储槽，因此无需提供槽输入。标准的 mapping 布局可直接解析，并在第一个持有者之后被缓存；非标准布局通过探测代币的 balanceOf 执行来发现。

address[] memory holders = new address[](2);
holders[0] = alice;
holders[1] = bob;
VNET.setErc20Balance(USDC, holders, 1_000_000e6);
VNET.addErc20Balance(USDC, holders, 500e6);
VNET.setMaxErc20Balance(USDC, alice);

在余额存储槽中打包额外标志位的代币会相应地报告 balanceOf。例如，USDC 保留了该槽的最高位，因此在 setMaxErc20Balance 之后，其 balanceOf 返回 2^255 - 1。

Nonce

函数	参数	返回值	描述
`setNonce`	`address target`, `uint256 value`	`bool`	设置 `target` 的交易计数。

VNET.setNonce(account, 42);

Events

emitEvent 触发一条 address 字段为 target（而不是调用合约）的日志。下游消费者（索引器、subgraph、webhook）会将该日志视为来自 target 的真实发出。九个重载覆盖了从零到四个索引 topic，以及可选的未索引 data 载荷：

重载	Topics	Data
`emitEvent(target, data)`	0	✓
`emitEvent(target, t1)`	1	,
`emitEvent(target, t1, data)`	1	✓
`emitEvent(target, t1, t2)`	2	,
`emitEvent(target, t1, t2, data)`	2	✓
`emitEvent(target, t1, t2, t3)`	3	,
`emitEvent(target, t1, t2, t3, data)`	3	✓
`emitEvent(target, t1, t2, t3, t4)`	4	,
`emitEvent(target, t1, t2, t3, t4, data)`	4	✓

topic1 通常是 keccak256("EventName(type,type,...)")。示例，伪造一次 USDC 的 Transfer：

VNET.emitEvent(
    USDC,
    keccak256("Transfer(address,address,uint256)"),
    bytes32(uint256(uint160(from))),
    bytes32(uint256(uint160(to))),
    abi.encode(amount)
);

Cheatcode events

每个改变状态的作弊码都会从预编译地址（0xc100000000000000000000000000000000000000）发出对应的事件：

作弊码	事件
`setStorageAt`	`SetStorageAtEvent(address target, bytes32 slot, bytes32 value)`
`setBalance`	`SetBalanceEvent(address[] addresses, uint256 balance)`
`addBalance`	`AddBalanceEvent(address[] addresses, uint256 amount)`
`setNonce`	`SetNonceEvent(address target, uint256 value)`
`setErc20Balance`	`SetErc20BalanceEvent(address target, address[] addresses, uint256 amount)`
`addErc20Balance`	`AddErc20BalanceEvent(address target, address[] addresses, uint256 amount)`
`setMaxErc20Balance`	`SetMaxErc20BalanceEvent(address target, address account)`

检查通过 emitEvent 伪造的日志的收据时，请按目标地址过滤 logs[] 以忽略预编译自身的条目。

已知限制

基于 Base 的 Virtual Environments。 Solidity 作弊码在 Base 上不可用。
基于 Arbitrum 的 Virtual Environments。 由于 Arbitrum 内部机制，通过 eth_call 进行的作弊码调用无法工作。交易、gas 估算和模拟按预期工作。

另请参阅

Admin RPC，用于从交易外部操纵状态的等价 JSON-RPC 方法。
Foundry 作弊码教程，部署可复用作弊码演练环境的端到端教程。

Getting Started

Simulator

Console

Monitor

Node RPC

Account & Settings

Solidity Cheatcodes

接口

函数

Storage

Balance

ERC-20 balances

Nonce

Events

Cheatcode events

已知限制

另请参阅

​接口

​函数

​Storage

​Balance

​ERC-20 balances

​Nonce

​Events

​Cheatcode events

​已知限制

​另请参阅

接口

函数

Storage

Balance

ERC-20 balances

Nonce

Events

Cheatcode events

已知限制

另请参阅