poseidon-solidity-example/lib/forge-std/src/Vm.sol
lib/forge-std/src/Vm.solRaw
1// SPDX-License-Identifier: MIT
2pragma solidity >=0.6.2 <0.9.0;
3
4pragma experimental ABIEncoderV2;
5
6// Cheatcodes are marked as view/pure/none using the following rules:
7// 0. A call's observable behaviour includes its return value, logs, reverts and state writes,
8// 1. If you can influence a later call's observable behaviour, you're neither `view` nor `pure (you are modifying some state be it the EVM, interpreter, filesystem, etc),
9// 2. Otherwise if you can be influenced by an earlier call, or if reading some state, you're `view`,
10// 3. Otherwise you're `pure`.
11
12interface VmSafe {
13 struct Log {
14 bytes32[] topics;
15 bytes data;
16 address emitter;
17 }
18
19 struct Rpc {
20 string key;
21 string url;
22 }
23
24 struct FsMetadata {
25 bool isDir;
26 bool isSymlink;
27 uint256 length;
28 bool readOnly;
29 uint256 modified;
30 uint256 accessed;
31 uint256 created;
32 }
33
34 // Loads a storage slot from an address
35 function load(address target, bytes32 slot) external view returns (bytes32 data);
36 // Signs data
37 function sign(uint256 privateKey, bytes32 digest) external pure returns (uint8 v, bytes32 r, bytes32 s);
38 // Gets the address for a given private key
39 function addr(uint256 privateKey) external pure returns (address keyAddr);
40 // Gets the nonce of an account
41 function getNonce(address account) external view returns (uint64 nonce);
42 // Performs a foreign function call via the terminal
43 function ffi(string[] calldata commandInput) external returns (bytes memory result);
44 // Sets environment variables
45 function setEnv(string calldata name, string calldata value) external;
46 // Reads environment variables, (name) => (value)
47 function envBool(string calldata name) external view returns (bool value);
48 function envUint(string calldata name) external view returns (uint256 value);
49 function envInt(string calldata name) external view returns (int256 value);
50 function envAddress(string calldata name) external view returns (address value);
51 function envBytes32(string calldata name) external view returns (bytes32 value);
52 function envString(string calldata name) external view returns (string memory value);
53 function envBytes(string calldata name) external view returns (bytes memory value);
54 // Reads environment variables as arrays
55 function envBool(string calldata name, string calldata delim) external view returns (bool[] memory value);
56 function envUint(string calldata name, string calldata delim) external view returns (uint256[] memory value);
57 function envInt(string calldata name, string calldata delim) external view returns (int256[] memory value);
58 function envAddress(string calldata name, string calldata delim) external view returns (address[] memory value);
59 function envBytes32(string calldata name, string calldata delim) external view returns (bytes32[] memory value);
60 function envString(string calldata name, string calldata delim) external view returns (string[] memory value);
61 function envBytes(string calldata name, string calldata delim) external view returns (bytes[] memory value);
62 // Read environment variables with default value
63 function envOr(string calldata name, bool defaultValue) external returns (bool value);
64 function envOr(string calldata name, uint256 defaultValue) external returns (uint256 value);
65 function envOr(string calldata name, int256 defaultValue) external returns (int256 value);
66 function envOr(string calldata name, address defaultValue) external returns (address value);
67 function envOr(string calldata name, bytes32 defaultValue) external returns (bytes32 value);
68 function envOr(string calldata name, string calldata defaultValue) external returns (string memory value);
69 function envOr(string calldata name, bytes calldata defaultValue) external returns (bytes memory value);
70 // Read environment variables as arrays with default value
71 function envOr(string calldata name, string calldata delim, bool[] calldata defaultValue)
72 external
73 returns (bool[] memory value);
74 function envOr(string calldata name, string calldata delim, uint256[] calldata defaultValue)
75 external
76 returns (uint256[] memory value);
77 function envOr(string calldata name, string calldata delim, int256[] calldata defaultValue)
78 external
79 returns (int256[] memory value);
80 function envOr(string calldata name, string calldata delim, address[] calldata defaultValue)
81 external
82 returns (address[] memory value);
83 function envOr(string calldata name, string calldata delim, bytes32[] calldata defaultValue)
84 external
85 returns (bytes32[] memory value);
86 function envOr(string calldata name, string calldata delim, string[] calldata defaultValue)
87 external
88 returns (string[] memory value);
89 function envOr(string calldata name, string calldata delim, bytes[] calldata defaultValue)
90 external
91 returns (bytes[] memory value);
92 // Records all storage reads and writes
93 function record() external;
94 // Gets all accessed reads and write slot from a recording session, for a given address
95 function accesses(address target) external returns (bytes32[] memory readSlots, bytes32[] memory writeSlots);
96 // Gets the _creation_ bytecode from an artifact file. Takes in the relative path to the json file
97 function getCode(string calldata artifactPath) external view returns (bytes memory creationBytecode);
98 // Gets the _deployed_ bytecode from an artifact file. Takes in the relative path to the json file
99 function getDeployedCode(string calldata artifactPath) external view returns (bytes memory runtimeBytecode);
100 // Labels an address in call traces
101 function label(address account, string calldata newLabel) external;
102 // Using the address that calls the test contract, has the next call (at this call depth only) create a transaction that can later be signed and sent onchain
103 function broadcast() external;
104 // Has the next call (at this call depth only) create a transaction with the address provided as the sender that can later be signed and sent onchain
105 function broadcast(address signer) external;
106 // Has the next call (at this call depth only) create a transaction with the private key provided as the sender that can later be signed and sent onchain
107 function broadcast(uint256 privateKey) external;
108 // Using the address that calls the test contract, has all subsequent calls (at this call depth only) create transactions that can later be signed and sent onchain
109 function startBroadcast() external;
110 // Has all subsequent calls (at this call depth only) create transactions with the address provided that can later be signed and sent onchain
111 function startBroadcast(address signer) external;
112 // Has all subsequent calls (at this call depth only) create transactions with the private key provided that can later be signed and sent onchain
113 function startBroadcast(uint256 privateKey) external;
114 // Stops collecting onchain transactions
115 function stopBroadcast() external;
116 // Reads the entire content of file to string
117 function readFile(string calldata path) external view returns (string memory data);
118 // Reads the entire content of file as binary. Path is relative to the project root.
119 function readFileBinary(string calldata path) external view returns (bytes memory data);
120 // Get the path of the current project root
121 function projectRoot() external view returns (string memory path);
122 // Get the metadata for a file/directory
123 function fsMetadata(string calldata fileOrDir) external returns (FsMetadata memory metadata);
124 // Reads next line of file to string
125 function readLine(string calldata path) external view returns (string memory line);
126 // Writes data to file, creating a file if it does not exist, and entirely replacing its contents if it does.
127 function writeFile(string calldata path, string calldata data) external;
128 // Writes binary data to a file, creating a file if it does not exist, and entirely replacing its contents if it does.
129 // Path is relative to the project root.
130 function writeFileBinary(string calldata path, bytes calldata data) external;
131 // Writes line to file, creating a file if it does not exist.
132 function writeLine(string calldata path, string calldata data) external;
133 // Closes file for reading, resetting the offset and allowing to read it from beginning with readLine.
134 function closeFile(string calldata path) external;
135 // Removes file. This cheatcode will revert in the following situations, but is not limited to just these cases:
136 // - Path points to a directory.
137 // - The file doesn't exist.
138 // - The user lacks permissions to remove the file.
139 function removeFile(string calldata path) external;
140 // Convert values to a string
141 function toString(address value) external pure returns (string memory stringifiedValue);
142 function toString(bytes calldata value) external pure returns (string memory stringifiedValue);
143 function toString(bytes32 value) external pure returns (string memory stringifiedValue);
144 function toString(bool value) external pure returns (string memory stringifiedValue);
145 function toString(uint256 value) external pure returns (string memory stringifiedValue);
146 function toString(int256 value) external pure returns (string memory stringifiedValue);
147 // Convert values from a string
148 function parseBytes(string calldata stringifiedValue) external pure returns (bytes memory parsedValue);
149 function parseAddress(string calldata stringifiedValue) external pure returns (address parsedValue);
150 function parseUint(string calldata stringifiedValue) external pure returns (uint256 parsedValue);
151 function parseInt(string calldata stringifiedValue) external pure returns (int256 parsedValue);
152 function parseBytes32(string calldata stringifiedValue) external pure returns (bytes32 parsedValue);
153 function parseBool(string calldata stringifiedValue) external pure returns (bool parsedValue);
154 // Record all the transaction logs
155 function recordLogs() external;
156 // Gets all the recorded logs
157 function getRecordedLogs() external returns (Log[] memory logs);
158 // Derive a private key from a provided mnenomic string (or mnenomic file path) at the derivation path m/44'/60'/0'/0/{index}
159 function deriveKey(string calldata mnemonic, uint32 index) external pure returns (uint256 privateKey);
160 // Derive a private key from a provided mnenomic string (or mnenomic file path) at {derivationPath}{index}
161 function deriveKey(string calldata mnemonic, string calldata derivationPath, uint32 index)
162 external
163 pure
164 returns (uint256 privateKey);
165 // Adds a private key to the local forge wallet and returns the address
166 function rememberKey(uint256 privateKey) external returns (address keyAddr);
167 //
168 // parseJson
169 //
170 // ----
171 // In case the returned value is a JSON object, it's encoded as a ABI-encoded tuple. As JSON objects
172 // don't have the notion of ordered, but tuples do, they JSON object is encoded with it's fields ordered in
173 // ALPHABETICAL order. That means that in order to successfully decode the tuple, we need to define a tuple that
174 // encodes the fields in the same order, which is alphabetical. In the case of Solidity structs, they are encoded
175 // as tuples, with the attributes in the order in which they are defined.
176 // For example: json = { 'a': 1, 'b': 0xa4tb......3xs}
177 // a: uint256
178 // b: address
179 // To decode that json, we need to define a struct or a tuple as follows:
180 // struct json = { uint256 a; address b; }
181 // If we defined a json struct with the opposite order, meaning placing the address b first, it would try to
182 // decode the tuple in that order, and thus fail.
183 // ----
184 // Given a string of JSON, return it as ABI-encoded
185 function parseJson(string calldata json, string calldata key) external pure returns (bytes memory abiEncodedData);
186 function parseJson(string calldata json) external pure returns (bytes memory abiEncodedData);
187
188 // The following parseJson cheatcodes will do type coercion, for the type that they indicate.
189 // For example, parseJsonUint will coerce all values to a uint256. That includes stringified numbers '12'
190 // and hex numbers '0xEF'.
191 // Type coercion works ONLY for discrete values or arrays. That means that the key must return a value or array, not
192 // a JSON object.
193 function parseJsonUint(string calldata, string calldata) external returns (uint256);
194 function parseJsonUintArray(string calldata, string calldata) external returns (uint256[] memory);
195 function parseJsonInt(string calldata, string calldata) external returns (int256);
196 function parseJsonIntArray(string calldata, string calldata) external returns (int256[] memory);
197 function parseJsonBool(string calldata, string calldata) external returns (bool);
198 function parseJsonBoolArray(string calldata, string calldata) external returns (bool[] memory);
199 function parseJsonAddress(string calldata, string calldata) external returns (address);
200 function parseJsonAddressArray(string calldata, string calldata) external returns (address[] memory);
201 function parseJsonString(string calldata, string calldata) external returns (string memory);
202 function parseJsonStringArray(string calldata, string calldata) external returns (string[] memory);
203 function parseJsonBytes(string calldata, string calldata) external returns (bytes memory);
204 function parseJsonBytesArray(string calldata, string calldata) external returns (bytes[] memory);
205 function parseJsonBytes32(string calldata, string calldata) external returns (bytes32);
206 function parseJsonBytes32Array(string calldata, string calldata) external returns (bytes32[] memory);
207
208 // Serialize a key and value to a JSON object stored in-memory that can be later written to a file
209 // It returns the stringified version of the specific JSON file up to that moment.
210 function serializeBool(string calldata objectKey, string calldata valueKey, bool value)
211 external
212 returns (string memory json);
213 function serializeUint(string calldata objectKey, string calldata valueKey, uint256 value)
214 external
215 returns (string memory json);
216 function serializeInt(string calldata objectKey, string calldata valueKey, int256 value)
217 external
218 returns (string memory json);
219 function serializeAddress(string calldata objectKey, string calldata valueKey, address value)
220 external
221 returns (string memory json);
222 function serializeBytes32(string calldata objectKey, string calldata valueKey, bytes32 value)
223 external
224 returns (string memory json);
225 function serializeString(string calldata objectKey, string calldata valueKey, string calldata value)
226 external
227 returns (string memory json);
228 function serializeBytes(string calldata objectKey, string calldata valueKey, bytes calldata value)
229 external
230 returns (string memory json);
231
232 function serializeBool(string calldata objectKey, string calldata valueKey, bool[] calldata values)
233 external
234 returns (string memory json);
235 function serializeUint(string calldata objectKey, string calldata valueKey, uint256[] calldata values)
236 external
237 returns (string memory json);
238 function serializeInt(string calldata objectKey, string calldata valueKey, int256[] calldata values)
239 external
240 returns (string memory json);
241 function serializeAddress(string calldata objectKey, string calldata valueKey, address[] calldata values)
242 external
243 returns (string memory json);
244 function serializeBytes32(string calldata objectKey, string calldata valueKey, bytes32[] calldata values)
245 external
246 returns (string memory json);
247 function serializeString(string calldata objectKey, string calldata valueKey, string[] calldata values)
248 external
249 returns (string memory json);
250 function serializeBytes(string calldata objectKey, string calldata valueKey, bytes[] calldata values)
251 external
252 returns (string memory json);
253
254 //
255 // writeJson
256 //
257 // ----
258 // Write a serialized JSON object to a file. If the file exists, it will be overwritten.
259 // Let's assume we want to write the following JSON to a file:
260 //
261 // { "boolean": true, "number": 342, "object": { "title": "finally json serialization" } }
262 //
263 // ```
264 // string memory json1 = "some key";
265 // vm.serializeBool(json1, "boolean", true);
266 // vm.serializeBool(json1, "number", uint256(342));
267 // json2 = "some other key";
268 // string memory output = vm.serializeString(json2, "title", "finally json serialization");
269 // string memory finalJson = vm.serialize(json1, "object", output);
270 // vm.writeJson(finalJson, "./output/example.json");
271 // ```
272 // The critical insight is that every invocation of serialization will return the stringified version of the JSON
273 // up to that point. That means we can construct arbitrary JSON objects and then use the return stringified version
274 // to serialize them as values to another JSON object.
275 //
276 // json1 and json2 are simply keys used by the backend to keep track of the objects. So vm.serializeJson(json1,..)
277 // will find the object in-memory that is keyed by "some key".
278 function writeJson(string calldata json, string calldata path) external;
279 // Write a serialized JSON object to an **existing** JSON file, replacing a value with key = <value_key>
280 // This is useful to replace a specific value of a JSON file, without having to parse the entire thing
281 function writeJson(string calldata json, string calldata path, string calldata valueKey) external;
282 // Returns the RPC url for the given alias
283 function rpcUrl(string calldata rpcAlias) external view returns (string memory json);
284 // Returns all rpc urls and their aliases `[alias, url][]`
285 function rpcUrls() external view returns (string[2][] memory urls);
286 // Returns all rpc urls and their aliases as structs.
287 function rpcUrlStructs() external view returns (Rpc[] memory urls);
288 // If the condition is false, discard this run's fuzz inputs and generate new ones.
289 function assume(bool condition) external pure;
290 // Pauses gas metering (i.e. gas usage is not counted). Noop if already paused.
291 function pauseGasMetering() external;
292 // Resumes gas metering (i.e. gas usage is counted again). Noop if already on.
293 function resumeGasMetering() external;
294}
295
296interface Vm is VmSafe {
297 // Sets block.timestamp
298 function warp(uint256 newTimestamp) external;
299 // Sets block.height
300 function roll(uint256 newHeight) external;
301 // Sets block.basefee
302 function fee(uint256 newBasefee) external;
303 // Sets block.difficulty
304 function difficulty(uint256 newDifficulty) external;
305 // Sets block.chainid
306 function chainId(uint256 newChainId) external;
307 // Stores a value to an address' storage slot.
308 function store(address target, bytes32 slot, bytes32 value) external;
309 // Sets the nonce of an account; must be higher than the current nonce of the account
310 function setNonce(address account, uint64 newNonce) external;
311 // Sets the *next* call's msg.sender to be the input address
312 function prank(address msgSender) external;
313 // Sets all subsequent calls' msg.sender to be the input address until `stopPrank` is called
314 function startPrank(address msgSender) external;
315 // Sets the *next* call's msg.sender to be the input address, and the tx.origin to be the second input
316 function prank(address msgSender, address txOrigin) external;
317 // Sets all subsequent calls' msg.sender to be the input address until `stopPrank` is called, and the tx.origin to be the second input
318 function startPrank(address msgSender, address txOrigin) external;
319 // Resets subsequent calls' msg.sender to be `address(this)`
320 function stopPrank() external;
321 // Sets an address' balance
322 function deal(address account, uint256 newBalance) external;
323 // Sets an address' code
324 function etch(address target, bytes calldata newRuntimeBytecode) external;
325 // Expects an error on next call
326 function expectRevert(bytes calldata revertData) external;
327 function expectRevert(bytes4 revertData) external;
328 function expectRevert() external;
329 // Prepare an expected log with (bool checkTopic1, bool checkTopic2, bool checkTopic3, bool checkData).
330 // Call this function, then emit an event, then call a function. Internally after the call, we check if
331 // logs were emitted in the expected order with the expected topics and data (as specified by the booleans)
332 function expectEmit(bool checkTopic1, bool checkTopic2, bool checkTopic3, bool checkData) external;
333 function expectEmit(bool checkTopic1, bool checkTopic2, bool checkTopic3, bool checkData, address emitter)
334 external;
335 // Mocks a call to an address, returning specified data.
336 // Calldata can either be strict or a partial match, e.g. if you only
337 // pass a Solidity selector to the expected calldata, then the entire Solidity
338 // function will be mocked.
339 function mockCall(address callee, bytes calldata data, bytes calldata returnData) external;
340 // Mocks a call to an address with a specific msg.value, returning specified data.
341 // Calldata match takes precedence over msg.value in case of ambiguity.
342 function mockCall(address callee, uint256 msgValue, bytes calldata data, bytes calldata returnData) external;
343 // Clears all mocked calls
344 function clearMockedCalls() external;
345 // Expects a call to an address with the specified calldata.
346 // Calldata can either be a strict or a partial match
347 function expectCall(address callee, bytes calldata data) external;
348 // Expects a call to an address with the specified msg.value and calldata
349 function expectCall(address callee, uint256 msgValue, bytes calldata data) external;
350 // Sets block.coinbase
351 function coinbase(address newCoinbase) external;
352 // Snapshot the current state of the evm.
353 // Returns the id of the snapshot that was created.
354 // To revert a snapshot use `revertTo`
355 function snapshot() external returns (uint256 snapshotId);
356 // Revert the state of the EVM to a previous snapshot
357 // Takes the snapshot id to revert to.
358 // This deletes the snapshot and all snapshots taken after the given snapshot id.
359 function revertTo(uint256 snapshotId) external returns (bool success);
360 // Creates a new fork with the given endpoint and block and returns the identifier of the fork
361 function createFork(string calldata urlOrAlias, uint256 blockNumber) external returns (uint256 forkId);
362 // Creates a new fork with the given endpoint and the _latest_ block and returns the identifier of the fork
363 function createFork(string calldata urlOrAlias) external returns (uint256 forkId);
364 // Creates a new fork with the given endpoint and at the block the given transaction was mined in, replays all transaction mined in the block before the transaction,
365 // and returns the identifier of the fork
366 function createFork(string calldata urlOrAlias, bytes32 txHash) external returns (uint256 forkId);
367 // Creates _and_ also selects a new fork with the given endpoint and block and returns the identifier of the fork
368 function createSelectFork(string calldata urlOrAlias, uint256 blockNumber) external returns (uint256 forkId);
369 // Creates _and_ also selects new fork with the given endpoint and at the block the given transaction was mined in, replays all transaction mined in the block before
370 // the transaction, returns the identifier of the fork
371 function createSelectFork(string calldata urlOrAlias, bytes32 txHash) external returns (uint256 forkId);
372 // Creates _and_ also selects a new fork with the given endpoint and the latest block and returns the identifier of the fork
373 function createSelectFork(string calldata urlOrAlias) external returns (uint256 forkId);
374 // Takes a fork identifier created by `createFork` and sets the corresponding forked state as active.
375 function selectFork(uint256 forkId) external;
376 /// Returns the identifier of the currently active fork. Reverts if no fork is currently active.
377 function activeFork() external view returns (uint256 forkId);
378 // Updates the currently active fork to given block number
379 // This is similar to `roll` but for the currently active fork
380 function rollFork(uint256 blockNumber) external;
381 // Updates the currently active fork to given transaction
382 // this will `rollFork` with the number of the block the transaction was mined in and replays all transaction mined before it in the block
383 function rollFork(bytes32 txHash) external;
384 // Updates the given fork to given block number
385 function rollFork(uint256 forkId, uint256 blockNumber) external;
386 // Updates the given fork to block number of the given transaction and replays all transaction mined before it in the block
387 function rollFork(uint256 forkId, bytes32 txHash) external;
388 // Marks that the account(s) should use persistent storage across fork swaps in a multifork setup
389 // Meaning, changes made to the state of this account will be kept when switching forks
390 function makePersistent(address account) external;
391 function makePersistent(address account0, address account1) external;
392 function makePersistent(address account0, address account1, address account2) external;
393 function makePersistent(address[] calldata accounts) external;
394 // Revokes persistent status from the address, previously added via `makePersistent`
395 function revokePersistent(address account) external;
396 function revokePersistent(address[] calldata accounts) external;
397 // Returns true if the account is marked as persistent
398 function isPersistent(address account) external view returns (bool persistent);
399 // In forking mode, explicitly grant the given address cheatcode access
400 function allowCheatcodes(address account) external;
401 // Fetches the given transaction from the active fork and executes it on the current state
402 function transact(bytes32 txHash) external;
403 // Fetches the given transaction from the given fork and executes it on the current state
404 function transact(uint256 forkId, bytes32 txHash) external;
405}