foundry_cheatcodes_spec/vm.rs
1// We don't document function parameters individually so we can't enable `missing_docs` for this
2// module. Instead, we emit custom diagnostics in `#[derive(Cheatcode)]`.
3#![allow(missing_docs)]
4
5use super::*;
6use crate::Vm::ForgeContext;
7use alloy_sol_types::sol;
8use foundry_macros::Cheatcode;
9
10sol! {
11// Cheatcodes are marked as view/pure/none using the following rules:
12// 0. A call's observable behaviour includes its return value, logs, reverts and state writes,
13// 1. If you can influence a later call's observable behaviour, you're neither `view` nor `pure`
14// (you are modifying some state be it the EVM, interpreter, filesystem, etc),
15// 2. Otherwise if you can be influenced by an earlier call, or if reading some state, you're `view`,
16// 3. Otherwise you're `pure`.
17
18/// Foundry cheatcodes interface.
19#[derive(Debug, Cheatcode)] // Keep this list small to avoid unnecessary bloat.
20#[sol(abi)]
21interface Vm {
22 // ======== Types ========
23
24 /// Error thrown by cheatcodes.
25 error CheatcodeError(string message);
26
27 /// A modification applied to either `msg.sender` or `tx.origin`. Returned by `readCallers`.
28 enum CallerMode {
29 /// No caller modification is currently active.
30 None,
31 /// A one time broadcast triggered by a `vm.broadcast()` call is currently active.
32 Broadcast,
33 /// A recurrent broadcast triggered by a `vm.startBroadcast()` call is currently active.
34 RecurrentBroadcast,
35 /// A one time prank triggered by a `vm.prank()` call is currently active.
36 Prank,
37 /// A recurrent prank triggered by a `vm.startPrank()` call is currently active.
38 RecurrentPrank,
39 }
40
41 /// The kind of account access that occurred.
42 enum AccountAccessKind {
43 /// The account was called.
44 Call,
45 /// The account was called via delegatecall.
46 DelegateCall,
47 /// The account was called via callcode.
48 CallCode,
49 /// The account was called via staticcall.
50 StaticCall,
51 /// The account was created.
52 Create,
53 /// The account was selfdestructed.
54 SelfDestruct,
55 /// Synthetic access indicating the current context has resumed after a previous sub-context (AccountAccess).
56 Resume,
57 /// The account's balance was read.
58 Balance,
59 /// The account's codesize was read.
60 Extcodesize,
61 /// The account's codehash was read.
62 Extcodehash,
63 /// The account's code was copied.
64 Extcodecopy,
65 }
66
67 /// Forge execution contexts.
68 enum ForgeContext {
69 /// Test group execution context (test, coverage or snapshot).
70 TestGroup,
71 /// `forge test` execution context.
72 Test,
73 /// `forge coverage` execution context.
74 Coverage,
75 /// `forge snapshot` execution context.
76 Snapshot,
77 /// Script group execution context (dry run, broadcast or resume).
78 ScriptGroup,
79 /// `forge script` execution context.
80 ScriptDryRun,
81 /// `forge script --broadcast` execution context.
82 ScriptBroadcast,
83 /// `forge script --resume` execution context.
84 ScriptResume,
85 /// Unknown `forge` execution context.
86 Unknown,
87 }
88
89 /// An Ethereum log. Returned by `getRecordedLogs`.
90 struct Log {
91 /// The topics of the log, including the signature, if any.
92 bytes32[] topics;
93 /// The raw data of the log.
94 bytes data;
95 /// The address of the log's emitter.
96 address emitter;
97 }
98
99 /// Gas used. Returned by `lastCallGas`.
100 struct Gas {
101 /// The gas limit of the call.
102 uint64 gasLimit;
103 /// The total gas used.
104 uint64 gasTotalUsed;
105 /// DEPRECATED: The amount of gas used for memory expansion. Ref: <https://github.com/foundry-rs/foundry/pull/7934#pullrequestreview-2069236939>
106 uint64 gasMemoryUsed;
107 /// The amount of gas refunded.
108 int64 gasRefunded;
109 /// The amount of gas remaining.
110 uint64 gasRemaining;
111 }
112
113 /// An RPC URL and its alias. Returned by `rpcUrlStructs`.
114 struct Rpc {
115 /// The alias of the RPC URL.
116 string key;
117 /// The RPC URL.
118 string url;
119 }
120
121 /// An RPC log object. Returned by `eth_getLogs`.
122 struct EthGetLogs {
123 /// The address of the log's emitter.
124 address emitter;
125 /// The topics of the log, including the signature, if any.
126 bytes32[] topics;
127 /// The raw data of the log.
128 bytes data;
129 /// The block hash.
130 bytes32 blockHash;
131 /// The block number.
132 uint64 blockNumber;
133 /// The transaction hash.
134 bytes32 transactionHash;
135 /// The transaction index in the block.
136 uint64 transactionIndex;
137 /// The log index.
138 uint256 logIndex;
139 /// Whether the log was removed.
140 bool removed;
141 }
142
143 /// A single entry in a directory listing. Returned by `readDir`.
144 struct DirEntry {
145 /// The error message, if any.
146 string errorMessage;
147 /// The path of the entry.
148 string path;
149 /// The depth of the entry.
150 uint64 depth;
151 /// Whether the entry is a directory.
152 bool isDir;
153 /// Whether the entry is a symlink.
154 bool isSymlink;
155 }
156
157 /// Metadata information about a file.
158 ///
159 /// This structure is returned from the `fsMetadata` function and represents known
160 /// metadata about a file such as its permissions, size, modification
161 /// times, etc.
162 struct FsMetadata {
163 /// True if this metadata is for a directory.
164 bool isDir;
165 /// True if this metadata is for a symlink.
166 bool isSymlink;
167 /// The size of the file, in bytes, this metadata is for.
168 uint256 length;
169 /// True if this metadata is for a readonly (unwritable) file.
170 bool readOnly;
171 /// The last modification time listed in this metadata.
172 uint256 modified;
173 /// The last access time of this metadata.
174 uint256 accessed;
175 /// The creation time listed in this metadata.
176 uint256 created;
177 }
178
179 /// A wallet with a public and private key.
180 struct Wallet {
181 /// The wallet's address.
182 address addr;
183 /// The wallet's public key `X`.
184 uint256 publicKeyX;
185 /// The wallet's public key `Y`.
186 uint256 publicKeyY;
187 /// The wallet's private key.
188 uint256 privateKey;
189 }
190
191 /// The result of a `tryFfi` call.
192 struct FfiResult {
193 /// The exit code of the call.
194 int32 exitCode;
195 /// The optionally hex-decoded `stdout` data.
196 bytes stdout;
197 /// The `stderr` data.
198 bytes stderr;
199 }
200
201 /// Information on the chain and fork.
202 struct ChainInfo {
203 /// The fork identifier. Set to zero if no fork is active.
204 uint256 forkId;
205 /// The chain ID of the current fork.
206 uint256 chainId;
207 }
208
209 /// Information about a blockchain.
210 struct Chain {
211 /// The chain name.
212 string name;
213 /// The chain's Chain ID.
214 uint256 chainId;
215 /// The chain's alias. (i.e. what gets specified in `foundry.toml`).
216 string chainAlias;
217 /// A default RPC endpoint for this chain.
218 string rpcUrl;
219 }
220
221 /// The storage accessed during an `AccountAccess`.
222 struct StorageAccess {
223 /// The account whose storage was accessed.
224 address account;
225 /// The slot that was accessed.
226 bytes32 slot;
227 /// If the access was a write.
228 bool isWrite;
229 /// The previous value of the slot.
230 bytes32 previousValue;
231 /// The new value of the slot.
232 bytes32 newValue;
233 /// If the access was reverted.
234 bool reverted;
235 }
236
237 /// An EIP-2930 access list item.
238 struct AccessListItem {
239 /// The address to be added in access list.
240 address target;
241 /// The storage keys to be added in access list.
242 bytes32[] storageKeys;
243 }
244
245 /// The result of a `stopAndReturnStateDiff` call.
246 struct AccountAccess {
247 /// The chain and fork the access occurred.
248 ChainInfo chainInfo;
249 /// The kind of account access that determines what the account is.
250 /// If kind is Call, DelegateCall, StaticCall or CallCode, then the account is the callee.
251 /// If kind is Create, then the account is the newly created account.
252 /// If kind is SelfDestruct, then the account is the selfdestruct recipient.
253 /// If kind is a Resume, then account represents a account context that has resumed.
254 AccountAccessKind kind;
255 /// The account that was accessed.
256 /// It's either the account created, callee or a selfdestruct recipient for CREATE, CALL or SELFDESTRUCT.
257 address account;
258 /// What accessed the account.
259 address accessor;
260 /// If the account was initialized or empty prior to the access.
261 /// An account is considered initialized if it has code, a
262 /// non-zero nonce, or a non-zero balance.
263 bool initialized;
264 /// The previous balance of the accessed account.
265 uint256 oldBalance;
266 /// The potential new balance of the accessed account.
267 /// That is, all balance changes are recorded here, even if reverts occurred.
268 uint256 newBalance;
269 /// Code of the account deployed by CREATE.
270 bytes deployedCode;
271 /// Value passed along with the account access
272 uint256 value;
273 /// Input data provided to the CREATE or CALL
274 bytes data;
275 /// If this access reverted in either the current or parent context.
276 bool reverted;
277 /// An ordered list of storage accesses made during an account access operation.
278 StorageAccess[] storageAccesses;
279 /// Call depth traversed during the recording of state differences
280 uint64 depth;
281 /// The previous nonce of the accessed account.
282 uint64 oldNonce;
283 /// The new nonce of the accessed account.
284 uint64 newNonce;
285 }
286
287 /// The result of the `stopDebugTraceRecording` call
288 struct DebugStep {
289 /// The stack before executing the step of the run.
290 /// stack\[0\] represents the top of the stack.
291 /// and only stack data relevant to the opcode execution is contained.
292 uint256[] stack;
293 /// The memory input data before executing the step of the run.
294 /// only input data relevant to the opcode execution is contained.
295 ///
296 /// e.g. for MLOAD, it will have memory\[offset:offset+32\] copied here.
297 /// the offset value can be get by the stack data.
298 bytes memoryInput;
299 /// The opcode that was accessed.
300 uint8 opcode;
301 /// The call depth of the step.
302 uint64 depth;
303 /// Whether the call end up with out of gas error.
304 bool isOutOfGas;
305 /// The contract address where the opcode is running
306 address contractAddr;
307 }
308
309 /// The transaction type (`txType`) of the broadcast.
310 enum BroadcastTxType {
311 /// Represents a CALL broadcast tx.
312 Call,
313 /// Represents a CREATE broadcast tx.
314 Create,
315 /// Represents a CREATE2 broadcast tx.
316 Create2
317 }
318
319 /// Represents a transaction's broadcast details.
320 struct BroadcastTxSummary {
321 /// The hash of the transaction that was broadcasted
322 bytes32 txHash;
323 /// Represent the type of transaction among CALL, CREATE, CREATE2
324 BroadcastTxType txType;
325 /// The address of the contract that was called or created.
326 /// This is address of the contract that is created if the txType is CREATE or CREATE2.
327 address contractAddress;
328 /// The block number the transaction landed in.
329 uint64 blockNumber;
330 /// Status of the transaction, retrieved from the transaction receipt.
331 bool success;
332 }
333
334 /// Holds a signed EIP-7702 authorization for an authority account to delegate to an implementation.
335 struct SignedDelegation {
336 /// The y-parity of the recovered secp256k1 signature (0 or 1).
337 uint8 v;
338 /// First 32 bytes of the signature.
339 bytes32 r;
340 /// Second 32 bytes of the signature.
341 bytes32 s;
342 /// The current nonce of the authority account at signing time.
343 /// Used to ensure signature can't be replayed after account nonce changes.
344 uint64 nonce;
345 /// Address of the contract implementation that will be delegated to.
346 /// Gets encoded into delegation code: 0xef0100 || implementation.
347 address implementation;
348 }
349
350 /// Represents a "potential" revert reason from a single subsequent call when using `vm.assumeNoReverts`.
351 /// Reverts that match will result in a FOUNDRY::ASSUME rejection, whereas unmatched reverts will be surfaced
352 /// as normal.
353 struct PotentialRevert {
354 /// The allowed origin of the revert opcode; address(0) allows reverts from any address
355 address reverter;
356 /// When true, only matches on the beginning of the revert data, otherwise, matches on entire revert data
357 bool partialMatch;
358 /// The data to use to match encountered reverts
359 bytes revertData;
360 }
361
362 // ======== EVM ========
363
364 /// Gets the address for a given private key.
365 #[cheatcode(group = Evm, safety = Safe)]
366 function addr(uint256 privateKey) external pure returns (address keyAddr);
367
368 /// Dump a genesis JSON file's `allocs` to disk.
369 #[cheatcode(group = Evm, safety = Unsafe)]
370 function dumpState(string calldata pathToStateJson) external;
371
372 /// Gets the nonce of an account.
373 #[cheatcode(group = Evm, safety = Safe)]
374 function getNonce(address account) external view returns (uint64 nonce);
375
376 /// Get the nonce of a `Wallet`.
377 #[cheatcode(group = Evm, safety = Safe)]
378 function getNonce(Wallet calldata wallet) external view returns (uint64 nonce);
379
380 /// Loads a storage slot from an address.
381 #[cheatcode(group = Evm, safety = Safe)]
382 function load(address target, bytes32 slot) external view returns (bytes32 data);
383
384 /// Load a genesis JSON file's `allocs` into the in-memory EVM state.
385 #[cheatcode(group = Evm, safety = Unsafe)]
386 function loadAllocs(string calldata pathToAllocsJson) external;
387
388 // -------- Record Debug Traces --------
389
390 /// Records the debug trace during the run.
391 #[cheatcode(group = Evm, safety = Safe)]
392 function startDebugTraceRecording() external;
393
394 /// Stop debug trace recording and returns the recorded debug trace.
395 #[cheatcode(group = Evm, safety = Safe)]
396 function stopAndReturnDebugTraceRecording() external returns (DebugStep[] memory step);
397
398
399 /// Clones a source account code, state, balance and nonce to a target account and updates in-memory EVM state.
400 #[cheatcode(group = Evm, safety = Unsafe)]
401 function cloneAccount(address source, address target) external;
402
403 // -------- Record Storage --------
404
405 /// Records all storage reads and writes. Use `accesses` to get the recorded data.
406 /// Subsequent calls to `record` will clear the previous data.
407 #[cheatcode(group = Evm, safety = Safe)]
408 function record() external;
409
410 /// Stops recording storage reads and writes.
411 #[cheatcode(group = Evm, safety = Safe)]
412 function stopRecord() external;
413
414 /// Gets all accessed reads and write slot from a `vm.record` session, for a given address.
415 #[cheatcode(group = Evm, safety = Safe)]
416 function accesses(address target) external view returns (bytes32[] memory readSlots, bytes32[] memory writeSlots);
417
418 /// Record all account accesses as part of CREATE, CALL or SELFDESTRUCT opcodes in order,
419 /// along with the context of the calls
420 #[cheatcode(group = Evm, safety = Safe)]
421 function startStateDiffRecording() external;
422
423 /// Returns an ordered array of all account accesses from a `vm.startStateDiffRecording` session.
424 #[cheatcode(group = Evm, safety = Safe)]
425 function stopAndReturnStateDiff() external returns (AccountAccess[] memory accountAccesses);
426
427 /// Returns state diffs from current `vm.startStateDiffRecording` session.
428 #[cheatcode(group = Evm, safety = Safe)]
429 function getStateDiff() external view returns (string memory diff);
430
431 /// Returns state diffs from current `vm.startStateDiffRecording` session, in json format.
432 #[cheatcode(group = Evm, safety = Safe)]
433 function getStateDiffJson() external view returns (string memory diff);
434
435 /// Returns an array of storage slots occupied by the specified variable.
436 #[cheatcode(group = Evm, safety = Safe)]
437 function getStorageSlots(address target, string calldata variableName) external view returns (uint256[] memory slots);
438
439 /// Returns an array of `StorageAccess` from current `vm.stateStateDiffRecording` session
440 #[cheatcode(group = Evm, safety = Safe)]
441 function getStorageAccesses() external view returns (StorageAccess[] memory storageAccesses);
442
443 // -------- Recording Map Writes --------
444
445 /// Starts recording all map SSTOREs for later retrieval.
446 #[cheatcode(group = Evm, safety = Safe)]
447 function startMappingRecording() external;
448
449 /// Stops recording all map SSTOREs for later retrieval and clears the recorded data.
450 #[cheatcode(group = Evm, safety = Safe)]
451 function stopMappingRecording() external;
452
453 /// Gets the number of elements in the mapping at the given slot, for a given address.
454 #[cheatcode(group = Evm, safety = Safe)]
455 function getMappingLength(address target, bytes32 mappingSlot) external view returns (uint256 length);
456
457 /// Gets the elements at index idx of the mapping at the given slot, for a given address. The
458 /// index must be less than the length of the mapping (i.e. the number of keys in the mapping).
459 #[cheatcode(group = Evm, safety = Safe)]
460 function getMappingSlotAt(address target, bytes32 mappingSlot, uint256 idx) external view returns (bytes32 value);
461
462 /// Gets the map key and parent of a mapping at a given slot, for a given address.
463 #[cheatcode(group = Evm, safety = Safe)]
464 function getMappingKeyAndParentOf(address target, bytes32 elementSlot)
465 external
466 view
467 returns (bool found, bytes32 key, bytes32 parent);
468
469 // -------- Block and Transaction Properties --------
470
471 /// Gets the current `block.chainid` of the currently selected environment.
472 /// You should use this instead of `block.chainid` if you use `vm.selectFork` or `vm.createSelectFork`, as `block.chainid` could be assumed
473 /// to be constant across a transaction, and as a result will get optimized out by the compiler.
474 /// See https://github.com/foundry-rs/foundry/issues/6180
475 #[cheatcode(group = Evm, safety = Safe)]
476 function getChainId() external view returns (uint256 blockChainId);
477
478 /// Sets `block.chainid`.
479 #[cheatcode(group = Evm, safety = Unsafe)]
480 function chainId(uint256 newChainId) external;
481
482 /// Sets `block.coinbase`.
483 #[cheatcode(group = Evm, safety = Unsafe)]
484 function coinbase(address newCoinbase) external;
485
486 /// Sets `block.difficulty`.
487 /// Not available on EVM versions from Paris onwards. Use `prevrandao` instead.
488 /// Reverts if used on unsupported EVM versions.
489 #[cheatcode(group = Evm, safety = Unsafe)]
490 function difficulty(uint256 newDifficulty) external;
491
492 /// Sets `block.basefee`.
493 #[cheatcode(group = Evm, safety = Unsafe)]
494 function fee(uint256 newBasefee) external;
495
496 /// Sets `block.prevrandao`.
497 /// Not available on EVM versions before Paris. Use `difficulty` instead.
498 /// If used on unsupported EVM versions it will revert.
499 #[cheatcode(group = Evm, safety = Unsafe)]
500 function prevrandao(bytes32 newPrevrandao) external;
501 /// Sets `block.prevrandao`.
502 /// Not available on EVM versions before Paris. Use `difficulty` instead.
503 /// If used on unsupported EVM versions it will revert.
504 #[cheatcode(group = Evm, safety = Unsafe)]
505 function prevrandao(uint256 newPrevrandao) external;
506
507 /// Sets the blobhashes in the transaction.
508 /// Not available on EVM versions before Cancun.
509 /// If used on unsupported EVM versions it will revert.
510 #[cheatcode(group = Evm, safety = Unsafe)]
511 function blobhashes(bytes32[] calldata hashes) external;
512
513 /// Gets the blockhashes from the current transaction.
514 /// Not available on EVM versions before Cancun.
515 /// If used on unsupported EVM versions it will revert.
516 #[cheatcode(group = Evm, safety = Unsafe)]
517 function getBlobhashes() external view returns (bytes32[] memory hashes);
518
519 /// Sets `block.height`.
520 #[cheatcode(group = Evm, safety = Unsafe)]
521 function roll(uint256 newHeight) external;
522
523 /// Gets the current `block.number`.
524 /// You should use this instead of `block.number` if you use `vm.roll`, as `block.number` is assumed to be constant across a transaction,
525 /// and as a result will get optimized out by the compiler.
526 /// See https://github.com/foundry-rs/foundry/issues/6180
527 #[cheatcode(group = Evm, safety = Safe)]
528 function getBlockNumber() external view returns (uint256 height);
529
530 /// Sets `tx.gasprice`.
531 #[cheatcode(group = Evm, safety = Unsafe)]
532 function txGasPrice(uint256 newGasPrice) external;
533
534 /// Sets `block.timestamp`.
535 #[cheatcode(group = Evm, safety = Unsafe)]
536 function warp(uint256 newTimestamp) external;
537
538 /// Gets the current `block.timestamp`.
539 /// You should use this instead of `block.timestamp` if you use `vm.warp`, as `block.timestamp` is assumed to be constant across a transaction,
540 /// and as a result will get optimized out by the compiler.
541 /// See https://github.com/foundry-rs/foundry/issues/6180
542 #[cheatcode(group = Evm, safety = Safe)]
543 function getBlockTimestamp() external view returns (uint256 timestamp);
544
545 /// Gets the RLP encoded block header for a given block number.
546 /// Returns the block header in the same format as `cast block <block_number> --raw`.
547 #[cheatcode(group = Evm, safety = Safe)]
548 function getRawBlockHeader(uint256 blockNumber) external view returns (bytes memory rlpHeader);
549
550 /// Sets `block.blobbasefee`
551 #[cheatcode(group = Evm, safety = Unsafe)]
552 function blobBaseFee(uint256 newBlobBaseFee) external;
553
554 /// Gets the current `block.blobbasefee`.
555 /// You should use this instead of `block.blobbasefee` if you use `vm.blobBaseFee`, as `block.blobbasefee` is assumed to be constant across a transaction,
556 /// and as a result will get optimized out by the compiler.
557 /// See https://github.com/foundry-rs/foundry/issues/6180
558 #[cheatcode(group = Evm, safety = Safe)]
559 function getBlobBaseFee() external view returns (uint256 blobBaseFee);
560
561 /// Set blockhash for the current block.
562 /// It only sets the blockhash for blocks where `block.number - 256 <= number < block.number`.
563 #[cheatcode(group = Evm, safety = Unsafe)]
564 function setBlockhash(uint256 blockNumber, bytes32 blockHash) external;
565
566 // -------- Account State --------
567
568 /// Sets an address' balance.
569 #[cheatcode(group = Evm, safety = Unsafe)]
570 function deal(address account, uint256 newBalance) external;
571
572 /// Sets an address' code.
573 #[cheatcode(group = Evm, safety = Unsafe)]
574 function etch(address target, bytes calldata newRuntimeBytecode) external;
575
576 /// Resets the nonce of an account to 0 for EOAs and 1 for contract accounts.
577 #[cheatcode(group = Evm, safety = Unsafe)]
578 function resetNonce(address account) external;
579
580 /// Sets the nonce of an account. Must be higher than the current nonce of the account.
581 #[cheatcode(group = Evm, safety = Unsafe)]
582 function setNonce(address account, uint64 newNonce) external;
583
584 /// Sets the nonce of an account to an arbitrary value.
585 #[cheatcode(group = Evm, safety = Unsafe)]
586 function setNonceUnsafe(address account, uint64 newNonce) external;
587
588 /// Stores a value to an address' storage slot.
589 #[cheatcode(group = Evm, safety = Unsafe)]
590 function store(address target, bytes32 slot, bytes32 value) external;
591
592 /// Marks the slots of an account and the account address as cold.
593 #[cheatcode(group = Evm, safety = Unsafe)]
594 function cool(address target) external;
595
596 /// Utility cheatcode to set an EIP-2930 access list for all subsequent transactions.
597 #[cheatcode(group = Evm, safety = Unsafe)]
598 function accessList(AccessListItem[] calldata access) external;
599
600 /// Utility cheatcode to remove any EIP-2930 access list set by `accessList` cheatcode.
601 #[cheatcode(group = Evm, safety = Unsafe)]
602 function noAccessList() external;
603
604 /// Utility cheatcode to mark specific storage slot as warm, simulating a prior read.
605 #[cheatcode(group = Evm, safety = Unsafe)]
606 function warmSlot(address target, bytes32 slot) external;
607
608 /// Utility cheatcode to mark specific storage slot as cold, simulating no prior read.
609 #[cheatcode(group = Evm, safety = Unsafe)]
610 function coolSlot(address target, bytes32 slot) external;
611
612 // -------- Call Manipulation --------
613 // --- Mocks ---
614
615 /// Clears all mocked calls.
616 #[cheatcode(group = Evm, safety = Unsafe)]
617 function clearMockedCalls() external;
618
619 /// Mocks a call to an address, returning specified data.
620 /// Calldata can either be strict or a partial match, e.g. if you only
621 /// pass a Solidity selector to the expected calldata, then the entire Solidity
622 /// function will be mocked.
623 #[cheatcode(group = Evm, safety = Unsafe)]
624 function mockCall(address callee, bytes calldata data, bytes calldata returnData) external;
625
626 /// Mocks a call to an address with a specific `msg.value`, returning specified data.
627 /// Calldata match takes precedence over `msg.value` in case of ambiguity.
628 #[cheatcode(group = Evm, safety = Unsafe)]
629 function mockCall(address callee, uint256 msgValue, bytes calldata data, bytes calldata returnData) external;
630
631 /// Mocks a call to an address, returning specified data.
632 /// Calldata can either be strict or a partial match, e.g. if you only
633 /// pass a Solidity selector to the expected calldata, then the entire Solidity
634 /// function will be mocked.
635 ///
636 /// Overload to pass the function selector directly `token.approve.selector` instead of `abi.encodeWithSelector(token.approve.selector)`.
637 #[cheatcode(group = Evm, safety = Unsafe)]
638 function mockCall(address callee, bytes4 data, bytes calldata returnData) external;
639
640 /// Mocks a call to an address with a specific `msg.value`, returning specified data.
641 /// Calldata match takes precedence over `msg.value` in case of ambiguity.
642 ///
643 /// Overload to pass the function selector directly `token.approve.selector` instead of `abi.encodeWithSelector(token.approve.selector)`.
644 #[cheatcode(group = Evm, safety = Unsafe)]
645 function mockCall(address callee, uint256 msgValue, bytes4 data, bytes calldata returnData) external;
646
647 /// Mocks multiple calls to an address, returning specified data for each call.
648 #[cheatcode(group = Evm, safety = Unsafe)]
649 function mockCalls(address callee, bytes calldata data, bytes[] calldata returnData) external;
650
651 /// Mocks multiple calls to an address with a specific `msg.value`, returning specified data for each call.
652 #[cheatcode(group = Evm, safety = Unsafe)]
653 function mockCalls(address callee, uint256 msgValue, bytes calldata data, bytes[] calldata returnData) external;
654
655 /// Reverts a call to an address with specified revert data.
656 #[cheatcode(group = Evm, safety = Unsafe)]
657 function mockCallRevert(address callee, bytes calldata data, bytes calldata revertData) external;
658
659 /// Reverts a call to an address with a specific `msg.value`, with specified revert data.
660 #[cheatcode(group = Evm, safety = Unsafe)]
661 function mockCallRevert(address callee, uint256 msgValue, bytes calldata data, bytes calldata revertData)
662 external;
663
664 /// Reverts a call to an address with specified revert data.
665 ///
666 /// Overload to pass the function selector directly `token.approve.selector` instead of `abi.encodeWithSelector(token.approve.selector)`.
667 #[cheatcode(group = Evm, safety = Unsafe)]
668 function mockCallRevert(address callee, bytes4 data, bytes calldata revertData) external;
669
670 /// Reverts a call to an address with a specific `msg.value`, with specified revert data.
671 ///
672 /// Overload to pass the function selector directly `token.approve.selector` instead of `abi.encodeWithSelector(token.approve.selector)`.
673 #[cheatcode(group = Evm, safety = Unsafe)]
674 function mockCallRevert(address callee, uint256 msgValue, bytes4 data, bytes calldata revertData)
675 external;
676
677 /// Whenever a call is made to `callee` with calldata `data`, this cheatcode instead calls
678 /// `target` with the same calldata. This functionality is similar to a delegate call made to
679 /// `target` contract from `callee`.
680 /// Can be used to substitute a call to a function with another implementation that captures
681 /// the primary logic of the original function but is easier to reason about.
682 /// If calldata is not a strict match then partial match by selector is attempted.
683 #[cheatcode(group = Evm, safety = Unsafe)]
684 function mockFunction(address callee, address target, bytes calldata data) external;
685
686 // --- Impersonation (pranks) ---
687
688 /// Sets the *next* call's `msg.sender` to be the input address.
689 #[cheatcode(group = Evm, safety = Unsafe)]
690 function prank(address msgSender) external;
691
692 /// Sets all subsequent calls' `msg.sender` to be the input address until `stopPrank` is called.
693 #[cheatcode(group = Evm, safety = Unsafe)]
694 function startPrank(address msgSender) external;
695
696 /// Sets the *next* call's `msg.sender` to be the input address, and the `tx.origin` to be the second input.
697 #[cheatcode(group = Evm, safety = Unsafe)]
698 function prank(address msgSender, address txOrigin) external;
699
700 /// Sets all subsequent calls' `msg.sender` to be the input address until `stopPrank` is called, and the `tx.origin` to be the second input.
701 #[cheatcode(group = Evm, safety = Unsafe)]
702 function startPrank(address msgSender, address txOrigin) external;
703
704 /// Sets the *next* delegate call's `msg.sender` to be the input address.
705 #[cheatcode(group = Evm, safety = Unsafe)]
706 function prank(address msgSender, bool delegateCall) external;
707
708 /// Sets all subsequent delegate calls' `msg.sender` to be the input address until `stopPrank` is called.
709 #[cheatcode(group = Evm, safety = Unsafe)]
710 function startPrank(address msgSender, bool delegateCall) external;
711
712 /// Sets the *next* delegate call's `msg.sender` to be the input address, and the `tx.origin` to be the second input.
713 #[cheatcode(group = Evm, safety = Unsafe)]
714 function prank(address msgSender, address txOrigin, bool delegateCall) external;
715
716 /// Sets all subsequent delegate calls' `msg.sender` to be the input address until `stopPrank` is called, and the `tx.origin` to be the second input.
717 #[cheatcode(group = Evm, safety = Unsafe)]
718 function startPrank(address msgSender, address txOrigin, bool delegateCall) external;
719
720 /// Resets subsequent calls' `msg.sender` to be `address(this)`.
721 #[cheatcode(group = Evm, safety = Unsafe)]
722 function stopPrank() external;
723
724 /// Reads the current `msg.sender` and `tx.origin` from state and reports if there is any active caller modification.
725 #[cheatcode(group = Evm, safety = Unsafe)]
726 function readCallers() external view returns (CallerMode callerMode, address msgSender, address txOrigin);
727
728 // ----- Arbitrary Snapshots -----
729
730 /// Snapshot capture an arbitrary numerical value by name.
731 /// The group name is derived from the contract name.
732 #[cheatcode(group = Evm, safety = Unsafe)]
733 function snapshotValue(string calldata name, uint256 value) external;
734
735 /// Snapshot capture an arbitrary numerical value by name in a group.
736 #[cheatcode(group = Evm, safety = Unsafe)]
737 function snapshotValue(string calldata group, string calldata name, uint256 value) external;
738
739 // -------- Gas Snapshots --------
740
741 /// Snapshot capture the gas usage of the last call by name from the callee perspective.
742 #[cheatcode(group = Evm, safety = Unsafe)]
743 function snapshotGasLastCall(string calldata name) external returns (uint256 gasUsed);
744
745 /// Snapshot capture the gas usage of the last call by name in a group from the callee perspective.
746 #[cheatcode(group = Evm, safety = Unsafe)]
747 function snapshotGasLastCall(string calldata group, string calldata name) external returns (uint256 gasUsed);
748
749 /// Start a snapshot capture of the current gas usage by name.
750 /// The group name is derived from the contract name.
751 #[cheatcode(group = Evm, safety = Unsafe)]
752 function startSnapshotGas(string calldata name) external;
753
754 /// Start a snapshot capture of the current gas usage by name in a group.
755 #[cheatcode(group = Evm, safety = Unsafe)]
756 function startSnapshotGas(string calldata group, string calldata name) external;
757
758 /// Stop the snapshot capture of the current gas by latest snapshot name, capturing the gas used since the start.
759 #[cheatcode(group = Evm, safety = Unsafe)]
760 function stopSnapshotGas() external returns (uint256 gasUsed);
761
762 /// Stop the snapshot capture of the current gas usage by name, capturing the gas used since the start.
763 /// The group name is derived from the contract name.
764 #[cheatcode(group = Evm, safety = Unsafe)]
765 function stopSnapshotGas(string calldata name) external returns (uint256 gasUsed);
766
767 /// Stop the snapshot capture of the current gas usage by name in a group, capturing the gas used since the start.
768 #[cheatcode(group = Evm, safety = Unsafe)]
769 function stopSnapshotGas(string calldata group, string calldata name) external returns (uint256 gasUsed);
770
771 // -------- State Snapshots --------
772
773 /// `snapshot` is being deprecated in favor of `snapshotState`. It will be removed in future versions.
774 #[cheatcode(group = Evm, safety = Unsafe, status = Deprecated(Some("replaced by `snapshotState`")))]
775 function snapshot() external returns (uint256 snapshotId);
776
777 /// Snapshot the current state of the evm.
778 /// Returns the ID of the snapshot that was created.
779 /// To revert a snapshot use `revertToState`.
780 #[cheatcode(group = Evm, safety = Unsafe)]
781 function snapshotState() external returns (uint256 snapshotId);
782
783 /// `revertTo` is being deprecated in favor of `revertToState`. It will be removed in future versions.
784 #[cheatcode(group = Evm, safety = Unsafe, status = Deprecated(Some("replaced by `revertToState`")))]
785 function revertTo(uint256 snapshotId) external returns (bool success);
786
787 /// Revert the state of the EVM to a previous snapshot
788 /// Takes the snapshot ID to revert to.
789 ///
790 /// Returns `true` if the snapshot was successfully reverted.
791 /// Returns `false` if the snapshot does not exist.
792 ///
793 /// **Note:** This does not automatically delete the snapshot. To delete the snapshot use `deleteStateSnapshot`.
794 #[cheatcode(group = Evm, safety = Unsafe)]
795 function revertToState(uint256 snapshotId) external returns (bool success);
796
797 /// `revertToAndDelete` is being deprecated in favor of `revertToStateAndDelete`. It will be removed in future versions.
798 #[cheatcode(group = Evm, safety = Unsafe, status = Deprecated(Some("replaced by `revertToStateAndDelete`")))]
799 function revertToAndDelete(uint256 snapshotId) external returns (bool success);
800
801 /// Revert the state of the EVM to a previous snapshot and automatically deletes the snapshots
802 /// Takes the snapshot ID to revert to.
803 ///
804 /// Returns `true` if the snapshot was successfully reverted and deleted.
805 /// Returns `false` if the snapshot does not exist.
806 #[cheatcode(group = Evm, safety = Unsafe)]
807 function revertToStateAndDelete(uint256 snapshotId) external returns (bool success);
808
809 /// `deleteSnapshot` is being deprecated in favor of `deleteStateSnapshot`. It will be removed in future versions.
810 #[cheatcode(group = Evm, safety = Unsafe, status = Deprecated(Some("replaced by `deleteStateSnapshot`")))]
811 function deleteSnapshot(uint256 snapshotId) external returns (bool success);
812
813 /// Removes the snapshot with the given ID created by `snapshot`.
814 /// Takes the snapshot ID to delete.
815 ///
816 /// Returns `true` if the snapshot was successfully deleted.
817 /// Returns `false` if the snapshot does not exist.
818 #[cheatcode(group = Evm, safety = Unsafe)]
819 function deleteStateSnapshot(uint256 snapshotId) external returns (bool success);
820
821 /// `deleteSnapshots` is being deprecated in favor of `deleteStateSnapshots`. It will be removed in future versions.
822 #[cheatcode(group = Evm, safety = Unsafe, status = Deprecated(Some("replaced by `deleteStateSnapshots`")))]
823 function deleteSnapshots() external;
824
825 /// Removes _all_ snapshots previously created by `snapshot`.
826 #[cheatcode(group = Evm, safety = Unsafe)]
827 function deleteStateSnapshots() external;
828
829 // -------- Forking --------
830 // --- Creation and Selection ---
831
832 /// Returns the identifier of the currently active fork. Reverts if no fork is currently active.
833 #[cheatcode(group = Evm, safety = Unsafe)]
834 function activeFork() external view returns (uint256 forkId);
835
836 /// Creates a new fork with the given endpoint and the _latest_ block and returns the identifier of the fork.
837 #[cheatcode(group = Evm, safety = Unsafe)]
838 function createFork(string calldata urlOrAlias) external returns (uint256 forkId);
839 /// Creates a new fork with the given endpoint and block and returns the identifier of the fork.
840 #[cheatcode(group = Evm, safety = Unsafe)]
841 function createFork(string calldata urlOrAlias, uint256 blockNumber) external returns (uint256 forkId);
842 /// Creates a new fork with the given endpoint and at the block the given transaction was mined in,
843 /// replays all transaction mined in the block before the transaction, and returns the identifier of the fork.
844 #[cheatcode(group = Evm, safety = Unsafe)]
845 function createFork(string calldata urlOrAlias, bytes32 txHash) external returns (uint256 forkId);
846
847 /// Creates and also selects a new fork with the given endpoint and the latest block and returns the identifier of the fork.
848 #[cheatcode(group = Evm, safety = Unsafe)]
849 function createSelectFork(string calldata urlOrAlias) external returns (uint256 forkId);
850 /// Creates and also selects a new fork with the given endpoint and block and returns the identifier of the fork.
851 #[cheatcode(group = Evm, safety = Unsafe)]
852 function createSelectFork(string calldata urlOrAlias, uint256 blockNumber) external returns (uint256 forkId);
853 /// Creates and also selects new fork with the given endpoint and at the block the given transaction was mined in,
854 /// replays all transaction mined in the block before the transaction, returns the identifier of the fork.
855 #[cheatcode(group = Evm, safety = Unsafe)]
856 function createSelectFork(string calldata urlOrAlias, bytes32 txHash) external returns (uint256 forkId);
857
858 /// Updates the currently active fork to given block number
859 /// This is similar to `roll` but for the currently active fork.
860 #[cheatcode(group = Evm, safety = Unsafe)]
861 function rollFork(uint256 blockNumber) external;
862 /// Updates the currently active fork to given transaction. This will `rollFork` with the number
863 /// of the block the transaction was mined in and replays all transaction mined before it in the block.
864 #[cheatcode(group = Evm, safety = Unsafe)]
865 function rollFork(bytes32 txHash) external;
866 /// Updates the given fork to given block number.
867 #[cheatcode(group = Evm, safety = Unsafe)]
868 function rollFork(uint256 forkId, uint256 blockNumber) external;
869 /// Updates the given fork to block number of the given transaction and replays all transaction mined before it in the block.
870 #[cheatcode(group = Evm, safety = Unsafe)]
871 function rollFork(uint256 forkId, bytes32 txHash) external;
872
873 /// Takes a fork identifier created by `createFork` and sets the corresponding forked state as active.
874 #[cheatcode(group = Evm, safety = Unsafe)]
875 function selectFork(uint256 forkId) external;
876
877 /// Fetches the given transaction from the active fork and executes it on the current state.
878 #[cheatcode(group = Evm, safety = Unsafe)]
879 function transact(bytes32 txHash) external;
880 /// Fetches the given transaction from the given fork and executes it on the current state.
881 #[cheatcode(group = Evm, safety = Unsafe)]
882 function transact(uint256 forkId, bytes32 txHash) external;
883
884 /// Performs an Ethereum JSON-RPC request to the current fork URL.
885 #[cheatcode(group = Evm, safety = Safe)]
886 function rpc(string calldata method, string calldata params) external returns (bytes memory data);
887
888 /// Performs an Ethereum JSON-RPC request to the given endpoint.
889 #[cheatcode(group = Evm, safety = Safe)]
890 function rpc(string calldata urlOrAlias, string calldata method, string calldata params)
891 external
892 returns (bytes memory data);
893
894 /// Gets all the logs according to specified filter.
895 #[cheatcode(group = Evm, safety = Safe)]
896 function eth_getLogs(uint256 fromBlock, uint256 toBlock, address target, bytes32[] calldata topics)
897 external
898 view
899 returns (EthGetLogs[] memory logs);
900
901 // --- Behavior ---
902
903 /// In forking mode, explicitly grant the given address cheatcode access.
904 #[cheatcode(group = Evm, safety = Unsafe)]
905 function allowCheatcodes(address account) external;
906
907 /// Marks that the account(s) should use persistent storage across fork swaps in a multifork setup
908 /// Meaning, changes made to the state of this account will be kept when switching forks.
909 #[cheatcode(group = Evm, safety = Unsafe)]
910 function makePersistent(address account) external;
911 /// See `makePersistent(address)`.
912 #[cheatcode(group = Evm, safety = Unsafe)]
913 function makePersistent(address account0, address account1) external;
914 /// See `makePersistent(address)`.
915 #[cheatcode(group = Evm, safety = Unsafe)]
916 function makePersistent(address account0, address account1, address account2) external;
917 /// See `makePersistent(address)`.
918 #[cheatcode(group = Evm, safety = Unsafe)]
919 function makePersistent(address[] calldata accounts) external;
920
921 /// Revokes persistent status from the address, previously added via `makePersistent`.
922 #[cheatcode(group = Evm, safety = Unsafe)]
923 function revokePersistent(address account) external;
924 /// See `revokePersistent(address)`.
925 #[cheatcode(group = Evm, safety = Unsafe)]
926 function revokePersistent(address[] calldata accounts) external;
927
928 /// Returns true if the account is marked as persistent.
929 #[cheatcode(group = Evm, safety = Unsafe)]
930 function isPersistent(address account) external view returns (bool persistent);
931
932 // -------- Record Logs --------
933
934 /// Record all the transaction logs.
935 #[cheatcode(group = Evm, safety = Safe)]
936 function recordLogs() external;
937
938 /// Gets all the recorded logs.
939 #[cheatcode(group = Evm, safety = Safe)]
940 function getRecordedLogs() external view returns (Log[] memory logs);
941
942 // -------- Gas Metering --------
943
944 // It's recommend to use the `noGasMetering` modifier included with forge-std, instead of
945 // using these functions directly.
946
947 /// Pauses gas metering (i.e. gas usage is not counted). Noop if already paused.
948 #[cheatcode(group = Evm, safety = Safe)]
949 function pauseGasMetering() external;
950
951 /// Resumes gas metering (i.e. gas usage is counted again). Noop if already on.
952 #[cheatcode(group = Evm, safety = Safe)]
953 function resumeGasMetering() external;
954
955 /// Reset gas metering (i.e. gas usage is set to gas limit).
956 #[cheatcode(group = Evm, safety = Safe)]
957 function resetGasMetering() external;
958
959 // -------- Gas Measurement --------
960
961 /// Gets the gas used in the last call from the callee perspective.
962 #[cheatcode(group = Evm, safety = Safe)]
963 function lastCallGas() external view returns (Gas memory gas);
964
965 // ======== Test Assertions and Utilities ========
966
967 /// If the condition is false, discard this run's fuzz inputs and generate new ones.
968 #[cheatcode(group = Testing, safety = Safe)]
969 function assume(bool condition) external pure;
970
971 /// Discard this run's fuzz inputs and generate new ones if next call reverted.
972 #[cheatcode(group = Testing, safety = Safe)]
973 function assumeNoRevert() external pure;
974
975 /// Discard this run's fuzz inputs and generate new ones if next call reverts with the potential revert parameters.
976 #[cheatcode(group = Testing, safety = Safe)]
977 function assumeNoRevert(PotentialRevert calldata potentialRevert) external pure;
978
979 /// Discard this run's fuzz inputs and generate new ones if next call reverts with the any of the potential revert parameters.
980 #[cheatcode(group = Testing, safety = Safe)]
981 function assumeNoRevert(PotentialRevert[] calldata potentialReverts) external pure;
982
983 /// Writes a breakpoint to jump to in the debugger.
984 #[cheatcode(group = Testing, safety = Safe)]
985 function breakpoint(string calldata char) external pure;
986
987 /// Writes a conditional breakpoint to jump to in the debugger.
988 #[cheatcode(group = Testing, safety = Safe)]
989 function breakpoint(string calldata char, bool value) external pure;
990
991 /// Returns the Foundry version.
992 /// Format: <cargo_version>-<tag>+<git_sha_short>.<unix_build_timestamp>.<profile>
993 /// Sample output: 0.3.0-nightly+3cb96bde9b.1737036656.debug
994 /// Note: Build timestamps may vary slightly across platforms due to separate CI jobs.
995 /// For reliable version comparisons, use UNIX format (e.g., >= 1700000000)
996 /// to compare timestamps while ignoring minor time differences.
997 #[cheatcode(group = Testing, safety = Safe)]
998 function getFoundryVersion() external view returns (string memory version);
999
1000 /// Returns the RPC url for the given alias.
1001 #[cheatcode(group = Testing, safety = Safe)]
1002 function rpcUrl(string calldata rpcAlias) external view returns (string memory json);
1003
1004 /// Returns all rpc urls and their aliases `[alias, url][]`.
1005 #[cheatcode(group = Testing, safety = Safe)]
1006 function rpcUrls() external view returns (string[2][] memory urls);
1007
1008 /// Returns all rpc urls and their aliases as structs.
1009 #[cheatcode(group = Testing, safety = Safe)]
1010 function rpcUrlStructs() external view returns (Rpc[] memory urls);
1011
1012 /// Returns a Chain struct for specific alias
1013 #[cheatcode(group = Testing, safety = Safe)]
1014 function getChain(string calldata chainAlias) external view returns (Chain memory chain);
1015
1016 /// Returns a Chain struct for specific chainId
1017 #[cheatcode(group = Testing, safety = Safe)]
1018 function getChain(uint256 chainId) external view returns (Chain memory chain);
1019
1020 /// Suspends execution of the main thread for `duration` milliseconds.
1021 #[cheatcode(group = Testing, safety = Safe)]
1022 function sleep(uint256 duration) external;
1023
1024 /// Expects a call to an address with the specified calldata.
1025 /// Calldata can either be a strict or a partial match.
1026 #[cheatcode(group = Testing, safety = Unsafe)]
1027 function expectCall(address callee, bytes calldata data) external;
1028
1029 /// Expects given number of calls to an address with the specified calldata.
1030 #[cheatcode(group = Testing, safety = Unsafe)]
1031 function expectCall(address callee, bytes calldata data, uint64 count) external;
1032
1033 /// Expects a call to an address with the specified `msg.value` and calldata.
1034 #[cheatcode(group = Testing, safety = Unsafe)]
1035 function expectCall(address callee, uint256 msgValue, bytes calldata data) external;
1036
1037 /// Expects given number of calls to an address with the specified `msg.value` and calldata.
1038 #[cheatcode(group = Testing, safety = Unsafe)]
1039 function expectCall(address callee, uint256 msgValue, bytes calldata data, uint64 count) external;
1040
1041 /// Expect a call to an address with the specified `msg.value`, gas, and calldata.
1042 #[cheatcode(group = Testing, safety = Unsafe)]
1043 function expectCall(address callee, uint256 msgValue, uint64 gas, bytes calldata data) external;
1044
1045 /// Expects given number of calls to an address with the specified `msg.value`, gas, and calldata.
1046 #[cheatcode(group = Testing, safety = Unsafe)]
1047 function expectCall(address callee, uint256 msgValue, uint64 gas, bytes calldata data, uint64 count) external;
1048
1049 /// Expect a call to an address with the specified `msg.value` and calldata, and a *minimum* amount of gas.
1050 #[cheatcode(group = Testing, safety = Unsafe)]
1051 function expectCallMinGas(address callee, uint256 msgValue, uint64 minGas, bytes calldata data) external;
1052
1053 /// Expect given number of calls to an address with the specified `msg.value` and calldata, and a *minimum* amount of gas.
1054 #[cheatcode(group = Testing, safety = Unsafe)]
1055 function expectCallMinGas(address callee, uint256 msgValue, uint64 minGas, bytes calldata data, uint64 count)
1056 external;
1057
1058 /// Prepare an expected log with (bool checkTopic1, bool checkTopic2, bool checkTopic3, bool checkData.).
1059 /// Call this function, then emit an event, then call a function. Internally after the call, we check if
1060 /// logs were emitted in the expected order with the expected topics and data (as specified by the booleans).
1061 #[cheatcode(group = Testing, safety = Unsafe)]
1062 function expectEmit(bool checkTopic1, bool checkTopic2, bool checkTopic3, bool checkData) external;
1063
1064 /// Same as the previous method, but also checks supplied address against emitting contract.
1065 #[cheatcode(group = Testing, safety = Unsafe)]
1066 function expectEmit(bool checkTopic1, bool checkTopic2, bool checkTopic3, bool checkData, address emitter)
1067 external;
1068
1069 /// Prepare an expected log with all topic and data checks enabled.
1070 /// Call this function, then emit an event, then call a function. Internally after the call, we check if
1071 /// logs were emitted in the expected order with the expected topics and data.
1072 #[cheatcode(group = Testing, safety = Unsafe)]
1073 function expectEmit() external;
1074
1075 /// Same as the previous method, but also checks supplied address against emitting contract.
1076 #[cheatcode(group = Testing, safety = Unsafe)]
1077 function expectEmit(address emitter) external;
1078
1079 /// Expect a given number of logs with the provided topics.
1080 #[cheatcode(group = Testing, safety = Unsafe)]
1081 function expectEmit(bool checkTopic1, bool checkTopic2, bool checkTopic3, bool checkData, uint64 count) external;
1082
1083 /// Expect a given number of logs from a specific emitter with the provided topics.
1084 #[cheatcode(group = Testing, safety = Unsafe)]
1085 function expectEmit(bool checkTopic1, bool checkTopic2, bool checkTopic3, bool checkData, address emitter, uint64 count)
1086 external;
1087
1088 /// Expect a given number of logs with all topic and data checks enabled.
1089 #[cheatcode(group = Testing, safety = Unsafe)]
1090 function expectEmit(uint64 count) external;
1091
1092 /// Expect a given number of logs from a specific emitter with all topic and data checks enabled.
1093 #[cheatcode(group = Testing, safety = Unsafe)]
1094 function expectEmit(address emitter, uint64 count) external;
1095
1096 /// Prepare an expected anonymous log with (bool checkTopic1, bool checkTopic2, bool checkTopic3, bool checkData.).
1097 /// Call this function, then emit an anonymous event, then call a function. Internally after the call, we check if
1098 /// logs were emitted in the expected order with the expected topics and data (as specified by the booleans).
1099 #[cheatcode(group = Testing, safety = Unsafe)]
1100 function expectEmitAnonymous(bool checkTopic0, bool checkTopic1, bool checkTopic2, bool checkTopic3, bool checkData) external;
1101
1102 /// Same as the previous method, but also checks supplied address against emitting contract.
1103 #[cheatcode(group = Testing, safety = Unsafe)]
1104 function expectEmitAnonymous(bool checkTopic0, bool checkTopic1, bool checkTopic2, bool checkTopic3, bool checkData, address emitter)
1105 external;
1106
1107 /// Prepare an expected anonymous log with all topic and data checks enabled.
1108 /// Call this function, then emit an anonymous event, then call a function. Internally after the call, we check if
1109 /// logs were emitted in the expected order with the expected topics and data.
1110 #[cheatcode(group = Testing, safety = Unsafe)]
1111 function expectEmitAnonymous() external;
1112
1113 /// Same as the previous method, but also checks supplied address against emitting contract.
1114 #[cheatcode(group = Testing, safety = Unsafe)]
1115 function expectEmitAnonymous(address emitter) external;
1116
1117 /// Expects the deployment of the specified bytecode by the specified address using the CREATE opcode
1118 #[cheatcode(group = Testing, safety = Unsafe)]
1119 function expectCreate(bytes calldata bytecode, address deployer) external;
1120
1121 /// Expects the deployment of the specified bytecode by the specified address using the CREATE2 opcode
1122 #[cheatcode(group = Testing, safety = Unsafe)]
1123 function expectCreate2(bytes calldata bytecode, address deployer) external;
1124
1125 /// Expects an error on next call with any revert data.
1126 #[cheatcode(group = Testing, safety = Unsafe)]
1127 function expectRevert() external;
1128
1129 /// Expects an error on next call that exactly matches the revert data.
1130 #[cheatcode(group = Testing, safety = Unsafe)]
1131 function expectRevert(bytes4 revertData) external;
1132
1133 /// Expects an error on next call that exactly matches the revert data.
1134 #[cheatcode(group = Testing, safety = Unsafe)]
1135 function expectRevert(bytes calldata revertData) external;
1136
1137 /// Expects an error with any revert data on next call to reverter address.
1138 #[cheatcode(group = Testing, safety = Unsafe)]
1139 function expectRevert(address reverter) external;
1140
1141 /// Expects an error from reverter address on next call, with any revert data.
1142 #[cheatcode(group = Testing, safety = Unsafe)]
1143 function expectRevert(bytes4 revertData, address reverter) external;
1144
1145 /// Expects an error from reverter address on next call, that exactly matches the revert data.
1146 #[cheatcode(group = Testing, safety = Unsafe)]
1147 function expectRevert(bytes calldata revertData, address reverter) external;
1148
1149 /// Expects a `count` number of reverts from the upcoming calls with any revert data or reverter.
1150 #[cheatcode(group = Testing, safety = Unsafe)]
1151 function expectRevert(uint64 count) external;
1152
1153 /// Expects a `count` number of reverts from the upcoming calls that match the revert data.
1154 #[cheatcode(group = Testing, safety = Unsafe)]
1155 function expectRevert(bytes4 revertData, uint64 count) external;
1156
1157 /// Expects a `count` number of reverts from the upcoming calls that exactly match the revert data.
1158 #[cheatcode(group = Testing, safety = Unsafe)]
1159 function expectRevert(bytes calldata revertData, uint64 count) external;
1160
1161 /// Expects a `count` number of reverts from the upcoming calls from the reverter address.
1162 #[cheatcode(group = Testing, safety = Unsafe)]
1163 function expectRevert(address reverter, uint64 count) external;
1164
1165 /// Expects a `count` number of reverts from the upcoming calls from the reverter address that match the revert data.
1166 #[cheatcode(group = Testing, safety = Unsafe)]
1167 function expectRevert(bytes4 revertData, address reverter, uint64 count) external;
1168
1169 /// Expects a `count` number of reverts from the upcoming calls from the reverter address that exactly match the revert data.
1170 #[cheatcode(group = Testing, safety = Unsafe)]
1171 function expectRevert(bytes calldata revertData, address reverter, uint64 count) external;
1172
1173 /// Expects an error on next call that starts with the revert data.
1174 #[cheatcode(group = Testing, safety = Unsafe)]
1175 function expectPartialRevert(bytes4 revertData) external;
1176
1177 /// Expects an error on next call to reverter address, that starts with the revert data.
1178 #[cheatcode(group = Testing, safety = Unsafe)]
1179 function expectPartialRevert(bytes4 revertData, address reverter) external;
1180
1181 /// Expects an error on next cheatcode call with any revert data.
1182 #[cheatcode(group = Testing, safety = Unsafe, status = Internal)]
1183 function _expectCheatcodeRevert() external;
1184
1185 /// Expects an error on next cheatcode call that starts with the revert data.
1186 #[cheatcode(group = Testing, safety = Unsafe, status = Internal)]
1187 function _expectCheatcodeRevert(bytes4 revertData) external;
1188
1189 /// Expects an error on next cheatcode call that exactly matches the revert data.
1190 #[cheatcode(group = Testing, safety = Unsafe, status = Internal)]
1191 function _expectCheatcodeRevert(bytes calldata revertData) external;
1192
1193 /// Only allows memory writes to offsets [0x00, 0x60) ∪ [min, max) in the current subcontext. If any other
1194 /// memory is written to, the test will fail. Can be called multiple times to add more ranges to the set.
1195 #[cheatcode(group = Testing, safety = Unsafe)]
1196 function expectSafeMemory(uint64 min, uint64 max) external;
1197
1198 /// Stops all safe memory expectation in the current subcontext.
1199 #[cheatcode(group = Testing, safety = Unsafe)]
1200 function stopExpectSafeMemory() external;
1201
1202 /// Only allows memory writes to offsets [0x00, 0x60) ∪ [min, max) in the next created subcontext.
1203 /// If any other memory is written to, the test will fail. Can be called multiple times to add more ranges
1204 /// to the set.
1205 #[cheatcode(group = Testing, safety = Unsafe)]
1206 function expectSafeMemoryCall(uint64 min, uint64 max) external;
1207
1208 /// Marks a test as skipped. Must be called at the top level of a test.
1209 #[cheatcode(group = Testing, safety = Unsafe)]
1210 function skip(bool skipTest) external;
1211
1212 /// Marks a test as skipped with a reason. Must be called at the top level of a test.
1213 #[cheatcode(group = Testing, safety = Unsafe)]
1214 function skip(bool skipTest, string calldata reason) external;
1215
1216 /// Asserts that the given condition is true.
1217 #[cheatcode(group = Testing, safety = Safe)]
1218 function assertTrue(bool condition) external pure;
1219
1220 /// Asserts that the given condition is true and includes error message into revert string on failure.
1221 #[cheatcode(group = Testing, safety = Safe)]
1222 function assertTrue(bool condition, string calldata error) external pure;
1223
1224 /// Asserts that the given condition is false.
1225 #[cheatcode(group = Testing, safety = Safe)]
1226 function assertFalse(bool condition) external pure;
1227
1228 /// Asserts that the given condition is false and includes error message into revert string on failure.
1229 #[cheatcode(group = Testing, safety = Safe)]
1230 function assertFalse(bool condition, string calldata error) external pure;
1231
1232 /// Asserts that two `bool` values are equal.
1233 #[cheatcode(group = Testing, safety = Safe)]
1234 function assertEq(bool left, bool right) external pure;
1235
1236 /// Asserts that two `bool` values are equal and includes error message into revert string on failure.
1237 #[cheatcode(group = Testing, safety = Safe)]
1238 function assertEq(bool left, bool right, string calldata error) external pure;
1239
1240 /// Asserts that two `uint256` values are equal.
1241 #[cheatcode(group = Testing, safety = Safe)]
1242 function assertEq(uint256 left, uint256 right) external pure;
1243
1244 /// Asserts that two `uint256` values are equal and includes error message into revert string on failure.
1245 #[cheatcode(group = Testing, safety = Safe)]
1246 function assertEq(uint256 left, uint256 right, string calldata error) external pure;
1247
1248 /// Asserts that two `int256` values are equal.
1249 #[cheatcode(group = Testing, safety = Safe)]
1250 function assertEq(int256 left, int256 right) external pure;
1251
1252 /// Asserts that two `int256` values are equal and includes error message into revert string on failure.
1253 #[cheatcode(group = Testing, safety = Safe)]
1254 function assertEq(int256 left, int256 right, string calldata error) external pure;
1255
1256 /// Asserts that two `address` values are equal.
1257 #[cheatcode(group = Testing, safety = Safe)]
1258 function assertEq(address left, address right) external pure;
1259
1260 /// Asserts that two `address` values are equal and includes error message into revert string on failure.
1261 #[cheatcode(group = Testing, safety = Safe)]
1262 function assertEq(address left, address right, string calldata error) external pure;
1263
1264 /// Asserts that two `bytes32` values are equal.
1265 #[cheatcode(group = Testing, safety = Safe)]
1266 function assertEq(bytes32 left, bytes32 right) external pure;
1267
1268 /// Asserts that two `bytes32` values are equal and includes error message into revert string on failure.
1269 #[cheatcode(group = Testing, safety = Safe)]
1270 function assertEq(bytes32 left, bytes32 right, string calldata error) external pure;
1271
1272 /// Asserts that two `string` values are equal.
1273 #[cheatcode(group = Testing, safety = Safe)]
1274 function assertEq(string calldata left, string calldata right) external pure;
1275
1276 /// Asserts that two `string` values are equal and includes error message into revert string on failure.
1277 #[cheatcode(group = Testing, safety = Safe)]
1278 function assertEq(string calldata left, string calldata right, string calldata error) external pure;
1279
1280 /// Asserts that two `bytes` values are equal.
1281 #[cheatcode(group = Testing, safety = Safe)]
1282 function assertEq(bytes calldata left, bytes calldata right) external pure;
1283
1284 /// Asserts that two `bytes` values are equal and includes error message into revert string on failure.
1285 #[cheatcode(group = Testing, safety = Safe)]
1286 function assertEq(bytes calldata left, bytes calldata right, string calldata error) external pure;
1287
1288 /// Asserts that two arrays of `bool` values are equal.
1289 #[cheatcode(group = Testing, safety = Safe)]
1290 function assertEq(bool[] calldata left, bool[] calldata right) external pure;
1291
1292 /// Asserts that two arrays of `bool` values are equal and includes error message into revert string on failure.
1293 #[cheatcode(group = Testing, safety = Safe)]
1294 function assertEq(bool[] calldata left, bool[] calldata right, string calldata error) external pure;
1295
1296 /// Asserts that two arrays of `uint256 values are equal.
1297 #[cheatcode(group = Testing, safety = Safe)]
1298 function assertEq(uint256[] calldata left, uint256[] calldata right) external pure;
1299
1300 /// Asserts that two arrays of `uint256` values are equal and includes error message into revert string on failure.
1301 #[cheatcode(group = Testing, safety = Safe)]
1302 function assertEq(uint256[] calldata left, uint256[] calldata right, string calldata error) external pure;
1303
1304 /// Asserts that two arrays of `int256` values are equal.
1305 #[cheatcode(group = Testing, safety = Safe)]
1306 function assertEq(int256[] calldata left, int256[] calldata right) external pure;
1307
1308 /// Asserts that two arrays of `int256` values are equal and includes error message into revert string on failure.
1309 #[cheatcode(group = Testing, safety = Safe)]
1310 function assertEq(int256[] calldata left, int256[] calldata right, string calldata error) external pure;
1311
1312 /// Asserts that two arrays of `address` values are equal.
1313 #[cheatcode(group = Testing, safety = Safe)]
1314 function assertEq(address[] calldata left, address[] calldata right) external pure;
1315
1316 /// Asserts that two arrays of `address` values are equal and includes error message into revert string on failure.
1317 #[cheatcode(group = Testing, safety = Safe)]
1318 function assertEq(address[] calldata left, address[] calldata right, string calldata error) external pure;
1319
1320 /// Asserts that two arrays of `bytes32` values are equal.
1321 #[cheatcode(group = Testing, safety = Safe)]
1322 function assertEq(bytes32[] calldata left, bytes32[] calldata right) external pure;
1323
1324 /// Asserts that two arrays of `bytes32` values are equal and includes error message into revert string on failure.
1325 #[cheatcode(group = Testing, safety = Safe)]
1326 function assertEq(bytes32[] calldata left, bytes32[] calldata right, string calldata error) external pure;
1327
1328 /// Asserts that two arrays of `string` values are equal.
1329 #[cheatcode(group = Testing, safety = Safe)]
1330 function assertEq(string[] calldata left, string[] calldata right) external pure;
1331
1332 /// Asserts that two arrays of `string` values are equal and includes error message into revert string on failure.
1333 #[cheatcode(group = Testing, safety = Safe)]
1334 function assertEq(string[] calldata left, string[] calldata right, string calldata error) external pure;
1335
1336 /// Asserts that two arrays of `bytes` values are equal.
1337 #[cheatcode(group = Testing, safety = Safe)]
1338 function assertEq(bytes[] calldata left, bytes[] calldata right) external pure;
1339
1340 /// Asserts that two arrays of `bytes` values are equal and includes error message into revert string on failure.
1341 #[cheatcode(group = Testing, safety = Safe)]
1342 function assertEq(bytes[] calldata left, bytes[] calldata right, string calldata error) external pure;
1343
1344 /// Asserts that two `uint256` values are equal, formatting them with decimals in failure message.
1345 #[cheatcode(group = Testing, safety = Safe)]
1346 function assertEqDecimal(uint256 left, uint256 right, uint256 decimals) external pure;
1347
1348 /// Asserts that two `uint256` values are equal, formatting them with decimals in failure message.
1349 /// Includes error message into revert string on failure.
1350 #[cheatcode(group = Testing, safety = Safe)]
1351 function assertEqDecimal(uint256 left, uint256 right, uint256 decimals, string calldata error) external pure;
1352
1353 /// Asserts that two `int256` values are equal, formatting them with decimals in failure message.
1354 #[cheatcode(group = Testing, safety = Safe)]
1355 function assertEqDecimal(int256 left, int256 right, uint256 decimals) external pure;
1356
1357 /// Asserts that two `int256` values are equal, formatting them with decimals in failure message.
1358 /// Includes error message into revert string on failure.
1359 #[cheatcode(group = Testing, safety = Safe)]
1360 function assertEqDecimal(int256 left, int256 right, uint256 decimals, string calldata error) external pure;
1361
1362 /// Asserts that two `bool` values are not equal.
1363 #[cheatcode(group = Testing, safety = Safe)]
1364 function assertNotEq(bool left, bool right) external pure;
1365
1366 /// Asserts that two `bool` values are not equal and includes error message into revert string on failure.
1367 #[cheatcode(group = Testing, safety = Safe)]
1368 function assertNotEq(bool left, bool right, string calldata error) external pure;
1369
1370 /// Asserts that two `uint256` values are not equal.
1371 #[cheatcode(group = Testing, safety = Safe)]
1372 function assertNotEq(uint256 left, uint256 right) external pure;
1373
1374 /// Asserts that two `uint256` values are not equal and includes error message into revert string on failure.
1375 #[cheatcode(group = Testing, safety = Safe)]
1376 function assertNotEq(uint256 left, uint256 right, string calldata error) external pure;
1377
1378 /// Asserts that two `int256` values are not equal.
1379 #[cheatcode(group = Testing, safety = Safe)]
1380 function assertNotEq(int256 left, int256 right) external pure;
1381
1382 /// Asserts that two `int256` values are not equal and includes error message into revert string on failure.
1383 #[cheatcode(group = Testing, safety = Safe)]
1384 function assertNotEq(int256 left, int256 right, string calldata error) external pure;
1385
1386 /// Asserts that two `address` values are not equal.
1387 #[cheatcode(group = Testing, safety = Safe)]
1388 function assertNotEq(address left, address right) external pure;
1389
1390 /// Asserts that two `address` values are not equal and includes error message into revert string on failure.
1391 #[cheatcode(group = Testing, safety = Safe)]
1392 function assertNotEq(address left, address right, string calldata error) external pure;
1393
1394 /// Asserts that two `bytes32` values are not equal.
1395 #[cheatcode(group = Testing, safety = Safe)]
1396 function assertNotEq(bytes32 left, bytes32 right) external pure;
1397
1398 /// Asserts that two `bytes32` values are not equal and includes error message into revert string on failure.
1399 #[cheatcode(group = Testing, safety = Safe)]
1400 function assertNotEq(bytes32 left, bytes32 right, string calldata error) external pure;
1401
1402 /// Asserts that two `string` values are not equal.
1403 #[cheatcode(group = Testing, safety = Safe)]
1404 function assertNotEq(string calldata left, string calldata right) external pure;
1405
1406 /// Asserts that two `string` values are not equal and includes error message into revert string on failure.
1407 #[cheatcode(group = Testing, safety = Safe)]
1408 function assertNotEq(string calldata left, string calldata right, string calldata error) external pure;
1409
1410 /// Asserts that two `bytes` values are not equal.
1411 #[cheatcode(group = Testing, safety = Safe)]
1412 function assertNotEq(bytes calldata left, bytes calldata right) external pure;
1413
1414 /// Asserts that two `bytes` values are not equal and includes error message into revert string on failure.
1415 #[cheatcode(group = Testing, safety = Safe)]
1416 function assertNotEq(bytes calldata left, bytes calldata right, string calldata error) external pure;
1417
1418 /// Asserts that two arrays of `bool` values are not equal.
1419 #[cheatcode(group = Testing, safety = Safe)]
1420 function assertNotEq(bool[] calldata left, bool[] calldata right) external pure;
1421
1422 /// Asserts that two arrays of `bool` values are not equal and includes error message into revert string on failure.
1423 #[cheatcode(group = Testing, safety = Safe)]
1424 function assertNotEq(bool[] calldata left, bool[] calldata right, string calldata error) external pure;
1425
1426 /// Asserts that two arrays of `uint256` values are not equal.
1427 #[cheatcode(group = Testing, safety = Safe)]
1428 function assertNotEq(uint256[] calldata left, uint256[] calldata right) external pure;
1429
1430 /// Asserts that two arrays of `uint256` values are not equal and includes error message into revert string on failure.
1431 #[cheatcode(group = Testing, safety = Safe)]
1432 function assertNotEq(uint256[] calldata left, uint256[] calldata right, string calldata error) external pure;
1433
1434 /// Asserts that two arrays of `int256` values are not equal.
1435 #[cheatcode(group = Testing, safety = Safe)]
1436 function assertNotEq(int256[] calldata left, int256[] calldata right) external pure;
1437
1438 /// Asserts that two arrays of `int256` values are not equal and includes error message into revert string on failure.
1439 #[cheatcode(group = Testing, safety = Safe)]
1440 function assertNotEq(int256[] calldata left, int256[] calldata right, string calldata error) external pure;
1441
1442 /// Asserts that two arrays of `address` values are not equal.
1443 #[cheatcode(group = Testing, safety = Safe)]
1444 function assertNotEq(address[] calldata left, address[] calldata right) external pure;
1445
1446 /// Asserts that two arrays of `address` values are not equal and includes error message into revert string on failure.
1447 #[cheatcode(group = Testing, safety = Safe)]
1448 function assertNotEq(address[] calldata left, address[] calldata right, string calldata error) external pure;
1449
1450 /// Asserts that two arrays of `bytes32` values are not equal.
1451 #[cheatcode(group = Testing, safety = Safe)]
1452 function assertNotEq(bytes32[] calldata left, bytes32[] calldata right) external pure;
1453
1454 /// Asserts that two arrays of `bytes32` values are not equal and includes error message into revert string on failure.
1455 #[cheatcode(group = Testing, safety = Safe)]
1456 function assertNotEq(bytes32[] calldata left, bytes32[] calldata right, string calldata error) external pure;
1457
1458 /// Asserts that two arrays of `string` values are not equal.
1459 #[cheatcode(group = Testing, safety = Safe)]
1460 function assertNotEq(string[] calldata left, string[] calldata right) external pure;
1461
1462 /// Asserts that two arrays of `string` values are not equal and includes error message into revert string on failure.
1463 #[cheatcode(group = Testing, safety = Safe)]
1464 function assertNotEq(string[] calldata left, string[] calldata right, string calldata error) external pure;
1465
1466 /// Asserts that two arrays of `bytes` values are not equal.
1467 #[cheatcode(group = Testing, safety = Safe)]
1468 function assertNotEq(bytes[] calldata left, bytes[] calldata right) external pure;
1469
1470 /// Asserts that two arrays of `bytes` values are not equal and includes error message into revert string on failure.
1471 #[cheatcode(group = Testing, safety = Safe)]
1472 function assertNotEq(bytes[] calldata left, bytes[] calldata right, string calldata error) external pure;
1473
1474 /// Asserts that two `uint256` values are not equal, formatting them with decimals in failure message.
1475 #[cheatcode(group = Testing, safety = Safe)]
1476 function assertNotEqDecimal(uint256 left, uint256 right, uint256 decimals) external pure;
1477
1478 /// Asserts that two `uint256` values are not equal, formatting them with decimals in failure message.
1479 /// Includes error message into revert string on failure.
1480 #[cheatcode(group = Testing, safety = Safe)]
1481 function assertNotEqDecimal(uint256 left, uint256 right, uint256 decimals, string calldata error) external pure;
1482
1483 /// Asserts that two `int256` values are not equal, formatting them with decimals in failure message.
1484 #[cheatcode(group = Testing, safety = Safe)]
1485 function assertNotEqDecimal(int256 left, int256 right, uint256 decimals) external pure;
1486
1487 /// Asserts that two `int256` values are not equal, formatting them with decimals in failure message.
1488 /// Includes error message into revert string on failure.
1489 #[cheatcode(group = Testing, safety = Safe)]
1490 function assertNotEqDecimal(int256 left, int256 right, uint256 decimals, string calldata error) external pure;
1491
1492 /// Compares two `uint256` values. Expects first value to be greater than second.
1493 #[cheatcode(group = Testing, safety = Safe)]
1494 function assertGt(uint256 left, uint256 right) external pure;
1495
1496 /// Compares two `uint256` values. Expects first value to be greater than second.
1497 /// Includes error message into revert string on failure.
1498 #[cheatcode(group = Testing, safety = Safe)]
1499 function assertGt(uint256 left, uint256 right, string calldata error) external pure;
1500
1501 /// Compares two `int256` values. Expects first value to be greater than second.
1502 #[cheatcode(group = Testing, safety = Safe)]
1503 function assertGt(int256 left, int256 right) external pure;
1504
1505 /// Compares two `int256` values. Expects first value to be greater than second.
1506 /// Includes error message into revert string on failure.
1507 #[cheatcode(group = Testing, safety = Safe)]
1508 function assertGt(int256 left, int256 right, string calldata error) external pure;
1509
1510 /// Compares two `uint256` values. Expects first value to be greater than second.
1511 /// Formats values with decimals in failure message.
1512 #[cheatcode(group = Testing, safety = Safe)]
1513 function assertGtDecimal(uint256 left, uint256 right, uint256 decimals) external pure;
1514
1515 /// Compares two `uint256` values. Expects first value to be greater than second.
1516 /// Formats values with decimals in failure message. Includes error message into revert string on failure.
1517 #[cheatcode(group = Testing, safety = Safe)]
1518 function assertGtDecimal(uint256 left, uint256 right, uint256 decimals, string calldata error) external pure;
1519
1520 /// Compares two `int256` values. Expects first value to be greater than second.
1521 /// Formats values with decimals in failure message.
1522 #[cheatcode(group = Testing, safety = Safe)]
1523 function assertGtDecimal(int256 left, int256 right, uint256 decimals) external pure;
1524
1525 /// Compares two `int256` values. Expects first value to be greater than second.
1526 /// Formats values with decimals in failure message. Includes error message into revert string on failure.
1527 #[cheatcode(group = Testing, safety = Safe)]
1528 function assertGtDecimal(int256 left, int256 right, uint256 decimals, string calldata error) external pure;
1529
1530 /// Compares two `uint256` values. Expects first value to be greater than or equal to second.
1531 #[cheatcode(group = Testing, safety = Safe)]
1532 function assertGe(uint256 left, uint256 right) external pure;
1533
1534 /// Compares two `uint256` values. Expects first value to be greater than or equal to second.
1535 /// Includes error message into revert string on failure.
1536 #[cheatcode(group = Testing, safety = Safe)]
1537 function assertGe(uint256 left, uint256 right, string calldata error) external pure;
1538
1539 /// Compares two `int256` values. Expects first value to be greater than or equal to second.
1540 #[cheatcode(group = Testing, safety = Safe)]
1541 function assertGe(int256 left, int256 right) external pure;
1542
1543 /// Compares two `int256` values. Expects first value to be greater than or equal to second.
1544 /// Includes error message into revert string on failure.
1545 #[cheatcode(group = Testing, safety = Safe)]
1546 function assertGe(int256 left, int256 right, string calldata error) external pure;
1547
1548 /// Compares two `uint256` values. Expects first value to be greater than or equal to second.
1549 /// Formats values with decimals in failure message.
1550 #[cheatcode(group = Testing, safety = Safe)]
1551 function assertGeDecimal(uint256 left, uint256 right, uint256 decimals) external pure;
1552
1553 /// Compares two `uint256` values. Expects first value to be greater than or equal to second.
1554 /// Formats values with decimals in failure message. Includes error message into revert string on failure.
1555 #[cheatcode(group = Testing, safety = Safe)]
1556 function assertGeDecimal(uint256 left, uint256 right, uint256 decimals, string calldata error) external pure;
1557
1558 /// Compares two `int256` values. Expects first value to be greater than or equal to second.
1559 /// Formats values with decimals in failure message.
1560 #[cheatcode(group = Testing, safety = Safe)]
1561 function assertGeDecimal(int256 left, int256 right, uint256 decimals) external pure;
1562
1563 /// Compares two `int256` values. Expects first value to be greater than or equal to second.
1564 /// Formats values with decimals in failure message. Includes error message into revert string on failure.
1565 #[cheatcode(group = Testing, safety = Safe)]
1566 function assertGeDecimal(int256 left, int256 right, uint256 decimals, string calldata error) external pure;
1567
1568 /// Compares two `uint256` values. Expects first value to be less than second.
1569 #[cheatcode(group = Testing, safety = Safe)]
1570 function assertLt(uint256 left, uint256 right) external pure;
1571
1572 /// Compares two `uint256` values. Expects first value to be less than second.
1573 /// Includes error message into revert string on failure.
1574 #[cheatcode(group = Testing, safety = Safe)]
1575 function assertLt(uint256 left, uint256 right, string calldata error) external pure;
1576
1577 /// Compares two `int256` values. Expects first value to be less than second.
1578 #[cheatcode(group = Testing, safety = Safe)]
1579 function assertLt(int256 left, int256 right) external pure;
1580
1581 /// Compares two `int256` values. Expects first value to be less than second.
1582 /// Includes error message into revert string on failure.
1583 #[cheatcode(group = Testing, safety = Safe)]
1584 function assertLt(int256 left, int256 right, string calldata error) external pure;
1585
1586 /// Compares two `uint256` values. Expects first value to be less than second.
1587 /// Formats values with decimals in failure message.
1588 #[cheatcode(group = Testing, safety = Safe)]
1589 function assertLtDecimal(uint256 left, uint256 right, uint256 decimals) external pure;
1590
1591 /// Compares two `uint256` values. Expects first value to be less than second.
1592 /// Formats values with decimals in failure message. Includes error message into revert string on failure.
1593 #[cheatcode(group = Testing, safety = Safe)]
1594 function assertLtDecimal(uint256 left, uint256 right, uint256 decimals, string calldata error) external pure;
1595
1596 /// Compares two `int256` values. Expects first value to be less than second.
1597 /// Formats values with decimals in failure message.
1598 #[cheatcode(group = Testing, safety = Safe)]
1599 function assertLtDecimal(int256 left, int256 right, uint256 decimals) external pure;
1600
1601 /// Compares two `int256` values. Expects first value to be less than second.
1602 /// Formats values with decimals in failure message. Includes error message into revert string on failure.
1603 #[cheatcode(group = Testing, safety = Safe)]
1604 function assertLtDecimal(int256 left, int256 right, uint256 decimals, string calldata error) external pure;
1605
1606 /// Compares two `uint256` values. Expects first value to be less than or equal to second.
1607 #[cheatcode(group = Testing, safety = Safe)]
1608 function assertLe(uint256 left, uint256 right) external pure;
1609
1610 /// Compares two `uint256` values. Expects first value to be less than or equal to second.
1611 /// Includes error message into revert string on failure.
1612 #[cheatcode(group = Testing, safety = Safe)]
1613 function assertLe(uint256 left, uint256 right, string calldata error) external pure;
1614
1615 /// Compares two `int256` values. Expects first value to be less than or equal to second.
1616 #[cheatcode(group = Testing, safety = Safe)]
1617 function assertLe(int256 left, int256 right) external pure;
1618
1619 /// Compares two `int256` values. Expects first value to be less than or equal to second.
1620 /// Includes error message into revert string on failure.
1621 #[cheatcode(group = Testing, safety = Safe)]
1622 function assertLe(int256 left, int256 right, string calldata error) external pure;
1623
1624 /// Compares two `uint256` values. Expects first value to be less than or equal to second.
1625 /// Formats values with decimals in failure message.
1626 #[cheatcode(group = Testing, safety = Safe)]
1627 function assertLeDecimal(uint256 left, uint256 right, uint256 decimals) external pure;
1628
1629 /// Compares two `uint256` values. Expects first value to be less than or equal to second.
1630 /// Formats values with decimals in failure message. Includes error message into revert string on failure.
1631 #[cheatcode(group = Testing, safety = Safe)]
1632 function assertLeDecimal(uint256 left, uint256 right, uint256 decimals, string calldata error) external pure;
1633
1634 /// Compares two `int256` values. Expects first value to be less than or equal to second.
1635 /// Formats values with decimals in failure message.
1636 #[cheatcode(group = Testing, safety = Safe)]
1637 function assertLeDecimal(int256 left, int256 right, uint256 decimals) external pure;
1638
1639 /// Compares two `int256` values. Expects first value to be less than or equal to second.
1640 /// Formats values with decimals in failure message. Includes error message into revert string on failure.
1641 #[cheatcode(group = Testing, safety = Safe)]
1642 function assertLeDecimal(int256 left, int256 right, uint256 decimals, string calldata error) external pure;
1643
1644 /// Compares two `uint256` values. Expects difference to be less than or equal to `maxDelta`.
1645 #[cheatcode(group = Testing, safety = Safe)]
1646 function assertApproxEqAbs(uint256 left, uint256 right, uint256 maxDelta) external pure;
1647
1648 /// Compares two `uint256` values. Expects difference to be less than or equal to `maxDelta`.
1649 /// Includes error message into revert string on failure.
1650 #[cheatcode(group = Testing, safety = Safe)]
1651 function assertApproxEqAbs(uint256 left, uint256 right, uint256 maxDelta, string calldata error) external pure;
1652
1653 /// Compares two `int256` values. Expects difference to be less than or equal to `maxDelta`.
1654 #[cheatcode(group = Testing, safety = Safe)]
1655 function assertApproxEqAbs(int256 left, int256 right, uint256 maxDelta) external pure;
1656
1657 /// Compares two `int256` values. Expects difference to be less than or equal to `maxDelta`.
1658 /// Includes error message into revert string on failure.
1659 #[cheatcode(group = Testing, safety = Safe)]
1660 function assertApproxEqAbs(int256 left, int256 right, uint256 maxDelta, string calldata error) external pure;
1661
1662 /// Compares two `uint256` values. Expects difference to be less than or equal to `maxDelta`.
1663 /// Formats values with decimals in failure message.
1664 #[cheatcode(group = Testing, safety = Safe)]
1665 function assertApproxEqAbsDecimal(uint256 left, uint256 right, uint256 maxDelta, uint256 decimals) external pure;
1666
1667 /// Compares two `uint256` values. Expects difference to be less than or equal to `maxDelta`.
1668 /// Formats values with decimals in failure message. Includes error message into revert string on failure.
1669 #[cheatcode(group = Testing, safety = Safe)]
1670 function assertApproxEqAbsDecimal(
1671 uint256 left,
1672 uint256 right,
1673 uint256 maxDelta,
1674 uint256 decimals,
1675 string calldata error
1676 ) external pure;
1677
1678 /// Compares two `int256` values. Expects difference to be less than or equal to `maxDelta`.
1679 /// Formats values with decimals in failure message.
1680 #[cheatcode(group = Testing, safety = Safe)]
1681 function assertApproxEqAbsDecimal(int256 left, int256 right, uint256 maxDelta, uint256 decimals) external pure;
1682
1683 /// Compares two `int256` values. Expects difference to be less than or equal to `maxDelta`.
1684 /// Formats values with decimals in failure message. Includes error message into revert string on failure.
1685 #[cheatcode(group = Testing, safety = Safe)]
1686 function assertApproxEqAbsDecimal(
1687 int256 left,
1688 int256 right,
1689 uint256 maxDelta,
1690 uint256 decimals,
1691 string calldata error
1692 ) external pure;
1693
1694 /// Compares two `uint256` values. Expects relative difference in percents to be less than or equal to `maxPercentDelta`.
1695 /// `maxPercentDelta` is an 18 decimal fixed point number, where 1e18 == 100%
1696 #[cheatcode(group = Testing, safety = Safe)]
1697 function assertApproxEqRel(uint256 left, uint256 right, uint256 maxPercentDelta) external pure;
1698
1699 /// Compares two `uint256` values. Expects relative difference in percents to be less than or equal to `maxPercentDelta`.
1700 /// `maxPercentDelta` is an 18 decimal fixed point number, where 1e18 == 100%
1701 /// Includes error message into revert string on failure.
1702 #[cheatcode(group = Testing, safety = Safe)]
1703 function assertApproxEqRel(uint256 left, uint256 right, uint256 maxPercentDelta, string calldata error) external pure;
1704
1705 /// Compares two `int256` values. Expects relative difference in percents to be less than or equal to `maxPercentDelta`.
1706 /// `maxPercentDelta` is an 18 decimal fixed point number, where 1e18 == 100%
1707 #[cheatcode(group = Testing, safety = Safe)]
1708 function assertApproxEqRel(int256 left, int256 right, uint256 maxPercentDelta) external pure;
1709
1710 /// Compares two `int256` values. Expects relative difference in percents to be less than or equal to `maxPercentDelta`.
1711 /// `maxPercentDelta` is an 18 decimal fixed point number, where 1e18 == 100%
1712 /// Includes error message into revert string on failure.
1713 #[cheatcode(group = Testing, safety = Safe)]
1714 function assertApproxEqRel(int256 left, int256 right, uint256 maxPercentDelta, string calldata error) external pure;
1715
1716 /// Compares two `uint256` values. Expects relative difference in percents to be less than or equal to `maxPercentDelta`.
1717 /// `maxPercentDelta` is an 18 decimal fixed point number, where 1e18 == 100%
1718 /// Formats values with decimals in failure message.
1719 #[cheatcode(group = Testing, safety = Safe)]
1720 function assertApproxEqRelDecimal(
1721 uint256 left,
1722 uint256 right,
1723 uint256 maxPercentDelta,
1724 uint256 decimals
1725 ) external pure;
1726
1727 /// Compares two `uint256` values. Expects relative difference in percents to be less than or equal to `maxPercentDelta`.
1728 /// `maxPercentDelta` is an 18 decimal fixed point number, where 1e18 == 100%
1729 /// Formats values with decimals in failure message. Includes error message into revert string on failure.
1730 #[cheatcode(group = Testing, safety = Safe)]
1731 function assertApproxEqRelDecimal(
1732 uint256 left,
1733 uint256 right,
1734 uint256 maxPercentDelta,
1735 uint256 decimals,
1736 string calldata error
1737 ) external pure;
1738
1739 /// Compares two `int256` values. Expects relative difference in percents to be less than or equal to `maxPercentDelta`.
1740 /// `maxPercentDelta` is an 18 decimal fixed point number, where 1e18 == 100%
1741 /// Formats values with decimals in failure message.
1742 #[cheatcode(group = Testing, safety = Safe)]
1743 function assertApproxEqRelDecimal(
1744 int256 left,
1745 int256 right,
1746 uint256 maxPercentDelta,
1747 uint256 decimals
1748 ) external pure;
1749
1750 /// Compares two `int256` values. Expects relative difference in percents to be less than or equal to `maxPercentDelta`.
1751 /// `maxPercentDelta` is an 18 decimal fixed point number, where 1e18 == 100%
1752 /// Formats values with decimals in failure message. Includes error message into revert string on failure.
1753 #[cheatcode(group = Testing, safety = Safe)]
1754 function assertApproxEqRelDecimal(
1755 int256 left,
1756 int256 right,
1757 uint256 maxPercentDelta,
1758 uint256 decimals,
1759 string calldata error
1760 ) external pure;
1761
1762 /// Returns true if the current Foundry version is greater than or equal to the given version.
1763 /// The given version string must be in the format `major.minor.patch`.
1764 ///
1765 /// This is equivalent to `foundryVersionCmp(version) >= 0`.
1766 #[cheatcode(group = Testing, safety = Safe)]
1767 function foundryVersionAtLeast(string calldata version) external view returns (bool);
1768
1769 /// Compares the current Foundry version with the given version string.
1770 /// The given version string must be in the format `major.minor.patch`.
1771 ///
1772 /// Returns:
1773 /// -1 if current Foundry version is less than the given version
1774 /// 0 if current Foundry version equals the given version
1775 /// 1 if current Foundry version is greater than the given version
1776 ///
1777 /// This result can then be used with a comparison operator against `0`.
1778 /// For example, to check if the current Foundry version is greater than or equal to `1.0.0`:
1779 /// `if (foundryVersionCmp("1.0.0") >= 0) { ... }`
1780 #[cheatcode(group = Testing, safety = Safe)]
1781 function foundryVersionCmp(string calldata version) external view returns (int256);
1782
1783 // ======== OS and Filesystem ========
1784
1785 // -------- Metadata --------
1786
1787 /// Returns true if the given path points to an existing entity, else returns false.
1788 #[cheatcode(group = Filesystem)]
1789 function exists(string calldata path) external view returns (bool result);
1790
1791 /// Given a path, query the file system to get information about a file, directory, etc.
1792 #[cheatcode(group = Filesystem)]
1793 function fsMetadata(string calldata path) external view returns (FsMetadata memory metadata);
1794
1795 /// Returns true if the path exists on disk and is pointing at a directory, else returns false.
1796 #[cheatcode(group = Filesystem)]
1797 function isDir(string calldata path) external view returns (bool result);
1798
1799 /// Returns true if the path exists on disk and is pointing at a regular file, else returns false.
1800 #[cheatcode(group = Filesystem)]
1801 function isFile(string calldata path) external view returns (bool result);
1802
1803 /// Get the path of the current project root.
1804 #[cheatcode(group = Filesystem)]
1805 function projectRoot() external view returns (string memory path);
1806
1807 /// Returns the time since unix epoch in milliseconds.
1808 #[cheatcode(group = Filesystem)]
1809 function unixTime() external view returns (uint256 milliseconds);
1810
1811 // -------- Reading and writing --------
1812
1813 /// Closes file for reading, resetting the offset and allowing to read it from beginning with readLine.
1814 /// `path` is relative to the project root.
1815 #[cheatcode(group = Filesystem)]
1816 function closeFile(string calldata path) external;
1817
1818 /// Copies the contents of one file to another. This function will **overwrite** the contents of `to`.
1819 /// On success, the total number of bytes copied is returned and it is equal to the length of the `to` file as reported by `metadata`.
1820 /// Both `from` and `to` are relative to the project root.
1821 #[cheatcode(group = Filesystem)]
1822 function copyFile(string calldata from, string calldata to) external returns (uint64 copied);
1823
1824 /// Creates a new, empty directory at the provided path.
1825 /// This cheatcode will revert in the following situations, but is not limited to just these cases:
1826 /// - User lacks permissions to modify `path`.
1827 /// - A parent of the given path doesn't exist and `recursive` is false.
1828 /// - `path` already exists and `recursive` is false.
1829 /// `path` is relative to the project root.
1830 #[cheatcode(group = Filesystem)]
1831 function createDir(string calldata path, bool recursive) external;
1832
1833 /// Reads the directory at the given path recursively, up to `maxDepth`.
1834 /// `maxDepth` defaults to 1, meaning only the direct children of the given directory will be returned.
1835 /// Follows symbolic links if `followLinks` is true.
1836 #[cheatcode(group = Filesystem)]
1837 function readDir(string calldata path) external view returns (DirEntry[] memory entries);
1838 /// See `readDir(string)`.
1839 #[cheatcode(group = Filesystem)]
1840 function readDir(string calldata path, uint64 maxDepth) external view returns (DirEntry[] memory entries);
1841 /// See `readDir(string)`.
1842 #[cheatcode(group = Filesystem)]
1843 function readDir(string calldata path, uint64 maxDepth, bool followLinks)
1844 external
1845 view
1846 returns (DirEntry[] memory entries);
1847
1848 /// Reads the entire content of file to string. `path` is relative to the project root.
1849 #[cheatcode(group = Filesystem)]
1850 function readFile(string calldata path) external view returns (string memory data);
1851
1852 /// Reads the entire content of file as binary. `path` is relative to the project root.
1853 #[cheatcode(group = Filesystem)]
1854 function readFileBinary(string calldata path) external view returns (bytes memory data);
1855
1856 /// Reads next line of file to string.
1857 #[cheatcode(group = Filesystem)]
1858 function readLine(string calldata path) external view returns (string memory line);
1859
1860 /// Reads a symbolic link, returning the path that the link points to.
1861 /// This cheatcode will revert in the following situations, but is not limited to just these cases:
1862 /// - `path` is not a symbolic link.
1863 /// - `path` does not exist.
1864 #[cheatcode(group = Filesystem)]
1865 function readLink(string calldata linkPath) external view returns (string memory targetPath);
1866
1867 /// Removes a directory at the provided path.
1868 /// This cheatcode will revert in the following situations, but is not limited to just these cases:
1869 /// - `path` doesn't exist.
1870 /// - `path` isn't a directory.
1871 /// - User lacks permissions to modify `path`.
1872 /// - The directory is not empty and `recursive` is false.
1873 /// `path` is relative to the project root.
1874 #[cheatcode(group = Filesystem)]
1875 function removeDir(string calldata path, bool recursive) external;
1876
1877 /// Removes a file from the filesystem.
1878 /// This cheatcode will revert in the following situations, but is not limited to just these cases:
1879 /// - `path` points to a directory.
1880 /// - The file doesn't exist.
1881 /// - The user lacks permissions to remove the file.
1882 /// `path` is relative to the project root.
1883 #[cheatcode(group = Filesystem)]
1884 function removeFile(string calldata path) external;
1885
1886 /// Writes data to file, creating a file if it does not exist, and entirely replacing its contents if it does.
1887 /// `path` is relative to the project root.
1888 #[cheatcode(group = Filesystem)]
1889 function writeFile(string calldata path, string calldata data) external;
1890
1891 /// Writes binary data to a file, creating a file if it does not exist, and entirely replacing its contents if it does.
1892 /// `path` is relative to the project root.
1893 #[cheatcode(group = Filesystem)]
1894 function writeFileBinary(string calldata path, bytes calldata data) external;
1895
1896 /// Writes line to file, creating a file if it does not exist.
1897 /// `path` is relative to the project root.
1898 #[cheatcode(group = Filesystem)]
1899 function writeLine(string calldata path, string calldata data) external;
1900
1901 /// Gets the artifact path from code (aka. creation code).
1902 #[cheatcode(group = Filesystem)]
1903 function getArtifactPathByCode(bytes calldata code) external view returns (string memory path);
1904
1905 /// Gets the artifact path from deployed code (aka. runtime code).
1906 #[cheatcode(group = Filesystem)]
1907 function getArtifactPathByDeployedCode(bytes calldata deployedCode) external view returns (string memory path);
1908
1909 /// Gets the creation bytecode from an artifact file. Takes in the relative path to the json file or the path to the
1910 /// artifact in the form of <path>:<contract>:<version> where <contract> and <version> parts are optional.
1911 #[cheatcode(group = Filesystem)]
1912 function getCode(string calldata artifactPath) external view returns (bytes memory creationBytecode);
1913
1914 /// Deploys a contract from an artifact file. Takes in the relative path to the json file or the path to the
1915 /// artifact in the form of <path>:<contract>:<version> where <contract> and <version> parts are optional.
1916 #[cheatcode(group = Filesystem)]
1917 function deployCode(string calldata artifactPath) external returns (address deployedAddress);
1918
1919 /// Deploys a contract from an artifact file. Takes in the relative path to the json file or the path to the
1920 /// artifact in the form of <path>:<contract>:<version> where <contract> and <version> parts are optional.
1921 ///
1922 /// Additionally accepts abi-encoded constructor arguments.
1923 #[cheatcode(group = Filesystem)]
1924 function deployCode(string calldata artifactPath, bytes calldata constructorArgs) external returns (address deployedAddress);
1925
1926 /// Deploys a contract from an artifact file. Takes in the relative path to the json file or the path to the
1927 /// artifact in the form of <path>:<contract>:<version> where <contract> and <version> parts are optional.
1928 ///
1929 /// Additionally accepts `msg.value`.
1930 #[cheatcode(group = Filesystem)]
1931 function deployCode(string calldata artifactPath, uint256 value) external returns (address deployedAddress);
1932
1933 /// Deploys a contract from an artifact file. Takes in the relative path to the json file or the path to the
1934 /// artifact in the form of <path>:<contract>:<version> where <contract> and <version> parts are optional.
1935 ///
1936 /// Additionally accepts abi-encoded constructor arguments and `msg.value`.
1937 #[cheatcode(group = Filesystem)]
1938 function deployCode(string calldata artifactPath, bytes calldata constructorArgs, uint256 value) external returns (address deployedAddress);
1939
1940 /// Deploys a contract from an artifact file, using the CREATE2 salt. Takes in the relative path to the json file or the path to the
1941 /// artifact in the form of <path>:<contract>:<version> where <contract> and <version> parts are optional.
1942 #[cheatcode(group = Filesystem)]
1943 function deployCode(string calldata artifactPath, bytes32 salt) external returns (address deployedAddress);
1944
1945 /// Deploys a contract from an artifact file, using the CREATE2 salt. Takes in the relative path to the json file or the path to the
1946 /// artifact in the form of <path>:<contract>:<version> where <contract> and <version> parts are optional.
1947 ///
1948 /// Additionally accepts abi-encoded constructor arguments.
1949 #[cheatcode(group = Filesystem)]
1950 function deployCode(string calldata artifactPath, bytes calldata constructorArgs, bytes32 salt) external returns (address deployedAddress);
1951
1952 /// Deploys a contract from an artifact file, using the CREATE2 salt. Takes in the relative path to the json file or the path to the
1953 /// artifact in the form of <path>:<contract>:<version> where <contract> and <version> parts are optional.
1954 ///
1955 /// Additionally accepts `msg.value`.
1956 #[cheatcode(group = Filesystem)]
1957 function deployCode(string calldata artifactPath, uint256 value, bytes32 salt) external returns (address deployedAddress);
1958
1959 /// Deploys a contract from an artifact file, using the CREATE2 salt. Takes in the relative path to the json file or the path to the
1960 /// artifact in the form of <path>:<contract>:<version> where <contract> and <version> parts are optional.
1961 ///
1962 /// Additionally accepts abi-encoded constructor arguments and `msg.value`.
1963 #[cheatcode(group = Filesystem)]
1964 function deployCode(string calldata artifactPath, bytes calldata constructorArgs, uint256 value, bytes32 salt) external returns (address deployedAddress);
1965
1966 /// Gets the deployed bytecode from an artifact file. Takes in the relative path to the json file or the path to the
1967 /// artifact in the form of <path>:<contract>:<version> where <contract> and <version> parts are optional.
1968 #[cheatcode(group = Filesystem)]
1969 function getDeployedCode(string calldata artifactPath) external view returns (bytes memory runtimeBytecode);
1970
1971 /// Returns the most recent broadcast for the given contract on `chainId` matching `txType`.
1972 ///
1973 /// For example:
1974 ///
1975 /// The most recent deployment can be fetched by passing `txType` as `CREATE` or `CREATE2`.
1976 ///
1977 /// The most recent call can be fetched by passing `txType` as `CALL`.
1978 #[cheatcode(group = Filesystem)]
1979 function getBroadcast(string calldata contractName, uint64 chainId, BroadcastTxType txType) external view returns (BroadcastTxSummary memory);
1980
1981 /// Returns all broadcasts for the given contract on `chainId` with the specified `txType`.
1982 ///
1983 /// Sorted such that the most recent broadcast is the first element, and the oldest is the last. i.e descending order of BroadcastTxSummary.blockNumber.
1984 #[cheatcode(group = Filesystem)]
1985 function getBroadcasts(string calldata contractName, uint64 chainId, BroadcastTxType txType) external view returns (BroadcastTxSummary[] memory);
1986
1987 /// Returns all broadcasts for the given contract on `chainId`.
1988 ///
1989 /// Sorted such that the most recent broadcast is the first element, and the oldest is the last. i.e descending order of BroadcastTxSummary.blockNumber.
1990 #[cheatcode(group = Filesystem)]
1991 function getBroadcasts(string calldata contractName, uint64 chainId) external view returns (BroadcastTxSummary[] memory);
1992
1993 /// Returns the most recent deployment for the current `chainId`.
1994 #[cheatcode(group = Filesystem)]
1995 function getDeployment(string calldata contractName) external view returns (address deployedAddress);
1996
1997 /// Returns the most recent deployment for the given contract on `chainId`
1998 #[cheatcode(group = Filesystem)]
1999 function getDeployment(string calldata contractName, uint64 chainId) external view returns (address deployedAddress);
2000
2001 /// Returns all deployments for the given contract on `chainId`
2002 ///
2003 /// Sorted in descending order of deployment time i.e descending order of BroadcastTxSummary.blockNumber.
2004 ///
2005 /// The most recent deployment is the first element, and the oldest is the last.
2006 #[cheatcode(group = Filesystem)]
2007 function getDeployments(string calldata contractName, uint64 chainId) external view returns (address[] memory deployedAddresses);
2008
2009 // -------- Foreign Function Interface --------
2010
2011 /// Performs a foreign function call via the terminal.
2012 #[cheatcode(group = Filesystem)]
2013 function ffi(string[] calldata commandInput) external returns (bytes memory result);
2014
2015 /// Performs a foreign function call via terminal and returns the exit code, stdout, and stderr.
2016 #[cheatcode(group = Filesystem)]
2017 function tryFfi(string[] calldata commandInput) external returns (FfiResult memory result);
2018
2019 // -------- User Interaction --------
2020
2021 /// Prompts the user for a string value in the terminal.
2022 #[cheatcode(group = Filesystem)]
2023 function prompt(string calldata promptText) external returns (string memory input);
2024
2025 /// Prompts the user for a hidden string value in the terminal.
2026 #[cheatcode(group = Filesystem)]
2027 function promptSecret(string calldata promptText) external returns (string memory input);
2028
2029 /// Prompts the user for hidden uint256 in the terminal (usually pk).
2030 #[cheatcode(group = Filesystem)]
2031 function promptSecretUint(string calldata promptText) external returns (uint256);
2032
2033 /// Prompts the user for an address in the terminal.
2034 #[cheatcode(group = Filesystem)]
2035 function promptAddress(string calldata promptText) external returns (address);
2036
2037 /// Prompts the user for uint256 in the terminal.
2038 #[cheatcode(group = Filesystem)]
2039 function promptUint(string calldata promptText) external returns (uint256);
2040
2041 // ======== Environment Variables ========
2042
2043 /// Resolves the env variable placeholders of a given input string.
2044 #[cheatcode(group = Environment)]
2045 function resolveEnv(string calldata input) external returns (string memory);
2046
2047 /// Sets environment variables.
2048 #[cheatcode(group = Environment)]
2049 function setEnv(string calldata name, string calldata value) external;
2050
2051 /// Gets the environment variable `name` and returns true if it exists, else returns false.
2052 #[cheatcode(group = Environment)]
2053 function envExists(string calldata name) external view returns (bool result);
2054
2055 /// Gets the environment variable `name` and parses it as `bool`.
2056 /// Reverts if the variable was not found or could not be parsed.
2057 #[cheatcode(group = Environment)]
2058 function envBool(string calldata name) external view returns (bool value);
2059 /// Gets the environment variable `name` and parses it as `uint256`.
2060 /// Reverts if the variable was not found or could not be parsed.
2061 #[cheatcode(group = Environment)]
2062 function envUint(string calldata name) external view returns (uint256 value);
2063 /// Gets the environment variable `name` and parses it as `int256`.
2064 /// Reverts if the variable was not found or could not be parsed.
2065 #[cheatcode(group = Environment)]
2066 function envInt(string calldata name) external view returns (int256 value);
2067 /// Gets the environment variable `name` and parses it as `address`.
2068 /// Reverts if the variable was not found or could not be parsed.
2069 #[cheatcode(group = Environment)]
2070 function envAddress(string calldata name) external view returns (address value);
2071 /// Gets the environment variable `name` and parses it as `bytes32`.
2072 /// Reverts if the variable was not found or could not be parsed.
2073 #[cheatcode(group = Environment)]
2074 function envBytes32(string calldata name) external view returns (bytes32 value);
2075 /// Gets the environment variable `name` and parses it as `string`.
2076 /// Reverts if the variable was not found or could not be parsed.
2077 #[cheatcode(group = Environment)]
2078 function envString(string calldata name) external view returns (string memory value);
2079 /// Gets the environment variable `name` and parses it as `bytes`.
2080 /// Reverts if the variable was not found or could not be parsed.
2081 #[cheatcode(group = Environment)]
2082 function envBytes(string calldata name) external view returns (bytes memory value);
2083
2084 /// Gets the environment variable `name` and parses it as an array of `bool`, delimited by `delim`.
2085 /// Reverts if the variable was not found or could not be parsed.
2086 #[cheatcode(group = Environment)]
2087 function envBool(string calldata name, string calldata delim) external view returns (bool[] memory value);
2088 /// Gets the environment variable `name` and parses it as an array of `uint256`, delimited by `delim`.
2089 /// Reverts if the variable was not found or could not be parsed.
2090 #[cheatcode(group = Environment)]
2091 function envUint(string calldata name, string calldata delim) external view returns (uint256[] memory value);
2092 /// Gets the environment variable `name` and parses it as an array of `int256`, delimited by `delim`.
2093 /// Reverts if the variable was not found or could not be parsed.
2094 #[cheatcode(group = Environment)]
2095 function envInt(string calldata name, string calldata delim) external view returns (int256[] memory value);
2096 /// Gets the environment variable `name` and parses it as an array of `address`, delimited by `delim`.
2097 /// Reverts if the variable was not found or could not be parsed.
2098 #[cheatcode(group = Environment)]
2099 function envAddress(string calldata name, string calldata delim) external view returns (address[] memory value);
2100 /// Gets the environment variable `name` and parses it as an array of `bytes32`, delimited by `delim`.
2101 /// Reverts if the variable was not found or could not be parsed.
2102 #[cheatcode(group = Environment)]
2103 function envBytes32(string calldata name, string calldata delim) external view returns (bytes32[] memory value);
2104 /// Gets the environment variable `name` and parses it as an array of `string`, delimited by `delim`.
2105 /// Reverts if the variable was not found or could not be parsed.
2106 #[cheatcode(group = Environment)]
2107 function envString(string calldata name, string calldata delim) external view returns (string[] memory value);
2108 /// Gets the environment variable `name` and parses it as an array of `bytes`, delimited by `delim`.
2109 /// Reverts if the variable was not found or could not be parsed.
2110 #[cheatcode(group = Environment)]
2111 function envBytes(string calldata name, string calldata delim) external view returns (bytes[] memory value);
2112
2113 /// Gets the environment variable `name` and parses it as `bool`.
2114 /// Reverts if the variable could not be parsed.
2115 /// Returns `defaultValue` if the variable was not found.
2116 #[cheatcode(group = Environment)]
2117 function envOr(string calldata name, bool defaultValue) external view returns (bool value);
2118 /// Gets the environment variable `name` and parses it as `uint256`.
2119 /// Reverts if the variable could not be parsed.
2120 /// Returns `defaultValue` if the variable was not found.
2121 #[cheatcode(group = Environment)]
2122 function envOr(string calldata name, uint256 defaultValue) external view returns (uint256 value);
2123 /// Gets the environment variable `name` and parses it as `int256`.
2124 /// Reverts if the variable could not be parsed.
2125 /// Returns `defaultValue` if the variable was not found.
2126 #[cheatcode(group = Environment)]
2127 function envOr(string calldata name, int256 defaultValue) external view returns (int256 value);
2128 /// Gets the environment variable `name` and parses it as `address`.
2129 /// Reverts if the variable could not be parsed.
2130 /// Returns `defaultValue` if the variable was not found.
2131 #[cheatcode(group = Environment)]
2132 function envOr(string calldata name, address defaultValue) external view returns (address value);
2133 /// Gets the environment variable `name` and parses it as `bytes32`.
2134 /// Reverts if the variable could not be parsed.
2135 /// Returns `defaultValue` if the variable was not found.
2136 #[cheatcode(group = Environment)]
2137 function envOr(string calldata name, bytes32 defaultValue) external view returns (bytes32 value);
2138 /// Gets the environment variable `name` and parses it as `string`.
2139 /// Reverts if the variable could not be parsed.
2140 /// Returns `defaultValue` if the variable was not found.
2141 #[cheatcode(group = Environment)]
2142 function envOr(string calldata name, string calldata defaultValue) external view returns (string memory value);
2143 /// Gets the environment variable `name` and parses it as `bytes`.
2144 /// Reverts if the variable could not be parsed.
2145 /// Returns `defaultValue` if the variable was not found.
2146 #[cheatcode(group = Environment)]
2147 function envOr(string calldata name, bytes calldata defaultValue) external view returns (bytes memory value);
2148
2149 /// Gets the environment variable `name` and parses it as an array of `bool`, delimited by `delim`.
2150 /// Reverts if the variable could not be parsed.
2151 /// Returns `defaultValue` if the variable was not found.
2152 #[cheatcode(group = Environment)]
2153 function envOr(string calldata name, string calldata delim, bool[] calldata defaultValue)
2154 external view
2155 returns (bool[] memory value);
2156 /// Gets the environment variable `name` and parses it as an array of `uint256`, delimited by `delim`.
2157 /// Reverts if the variable could not be parsed.
2158 /// Returns `defaultValue` if the variable was not found.
2159 #[cheatcode(group = Environment)]
2160 function envOr(string calldata name, string calldata delim, uint256[] calldata defaultValue)
2161 external view
2162 returns (uint256[] memory value);
2163 /// Gets the environment variable `name` and parses it as an array of `int256`, delimited by `delim`.
2164 /// Reverts if the variable could not be parsed.
2165 /// Returns `defaultValue` if the variable was not found.
2166 #[cheatcode(group = Environment)]
2167 function envOr(string calldata name, string calldata delim, int256[] calldata defaultValue)
2168 external view
2169 returns (int256[] memory value);
2170 /// Gets the environment variable `name` and parses it as an array of `address`, delimited by `delim`.
2171 /// Reverts if the variable could not be parsed.
2172 /// Returns `defaultValue` if the variable was not found.
2173 #[cheatcode(group = Environment)]
2174 function envOr(string calldata name, string calldata delim, address[] calldata defaultValue)
2175 external view
2176 returns (address[] memory value);
2177 /// Gets the environment variable `name` and parses it as an array of `bytes32`, delimited by `delim`.
2178 /// Reverts if the variable could not be parsed.
2179 /// Returns `defaultValue` if the variable was not found.
2180 #[cheatcode(group = Environment)]
2181 function envOr(string calldata name, string calldata delim, bytes32[] calldata defaultValue)
2182 external view
2183 returns (bytes32[] memory value);
2184 /// Gets the environment variable `name` and parses it as an array of `string`, delimited by `delim`.
2185 /// Reverts if the variable could not be parsed.
2186 /// Returns `defaultValue` if the variable was not found.
2187 #[cheatcode(group = Environment)]
2188 function envOr(string calldata name, string calldata delim, string[] calldata defaultValue)
2189 external view
2190 returns (string[] memory value);
2191 /// Gets the environment variable `name` and parses it as an array of `bytes`, delimited by `delim`.
2192 /// Reverts if the variable could not be parsed.
2193 /// Returns `defaultValue` if the variable was not found.
2194 #[cheatcode(group = Environment)]
2195 function envOr(string calldata name, string calldata delim, bytes[] calldata defaultValue)
2196 external view
2197 returns (bytes[] memory value);
2198
2199 /// Returns true if `forge` command was executed in given context.
2200 #[cheatcode(group = Environment)]
2201 function isContext(ForgeContext context) external view returns (bool result);
2202
2203 // ======== Scripts ========
2204 // -------- Broadcasting Transactions --------
2205
2206 /// Has the next call (at this call depth only) create transactions that can later be signed and sent onchain.
2207 ///
2208 /// Broadcasting address is determined by checking the following in order:
2209 /// 1. If `--sender` argument was provided, that address is used.
2210 /// 2. If exactly one signer (e.g. private key, hw wallet, keystore) is set when `forge broadcast` is invoked, that signer is used.
2211 /// 3. Otherwise, default foundry sender (1804c8AB1F12E6bbf3894d4083f33e07309d1f38) is used.
2212 #[cheatcode(group = Scripting)]
2213 function broadcast() external;
2214
2215 /// Has the next call (at this call depth only) create a transaction with the address provided
2216 /// as the sender that can later be signed and sent onchain.
2217 #[cheatcode(group = Scripting)]
2218 function broadcast(address signer) external;
2219
2220 /// Has the next call (at this call depth only) create a transaction with the private key
2221 /// provided as the sender that can later be signed and sent onchain.
2222 #[cheatcode(group = Scripting)]
2223 function broadcast(uint256 privateKey) external;
2224
2225 /// Has all subsequent calls (at this call depth only) create transactions that can later be signed and sent onchain.
2226 ///
2227 /// Broadcasting address is determined by checking the following in order:
2228 /// 1. If `--sender` argument was provided, that address is used.
2229 /// 2. If exactly one signer (e.g. private key, hw wallet, keystore) is set when `forge broadcast` is invoked, that signer is used.
2230 /// 3. Otherwise, default foundry sender (1804c8AB1F12E6bbf3894d4083f33e07309d1f38) is used.
2231 #[cheatcode(group = Scripting)]
2232 function startBroadcast() external;
2233
2234 /// Has all subsequent calls (at this call depth only) create transactions with the address
2235 /// provided that can later be signed and sent onchain.
2236 #[cheatcode(group = Scripting)]
2237 function startBroadcast(address signer) external;
2238
2239 /// Has all subsequent calls (at this call depth only) create transactions with the private key
2240 /// provided that can later be signed and sent onchain.
2241 #[cheatcode(group = Scripting)]
2242 function startBroadcast(uint256 privateKey) external;
2243
2244 /// Stops collecting onchain transactions.
2245 #[cheatcode(group = Scripting)]
2246 function stopBroadcast() external;
2247
2248 /// Takes a signed transaction and broadcasts it to the network.
2249 #[cheatcode(group = Scripting)]
2250 function broadcastRawTransaction(bytes calldata data) external;
2251
2252 /// Sign an EIP-7702 authorization for delegation
2253 #[cheatcode(group = Scripting)]
2254 function signDelegation(address implementation, uint256 privateKey) external returns (SignedDelegation memory signedDelegation);
2255
2256 /// Sign an EIP-7702 authorization for delegation for specific nonce
2257 #[cheatcode(group = Scripting)]
2258 function signDelegation(address implementation, uint256 privateKey, uint64 nonce) external returns (SignedDelegation memory signedDelegation);
2259
2260 /// Sign an EIP-7702 authorization for delegation, with optional cross-chain validity.
2261 #[cheatcode(group = Scripting)]
2262 function signDelegation(address implementation, uint256 privateKey, bool crossChain) external returns (SignedDelegation memory signedDelegation);
2263
2264 /// Designate the next call as an EIP-7702 transaction
2265 #[cheatcode(group = Scripting)]
2266 function attachDelegation(SignedDelegation calldata signedDelegation) external;
2267
2268 /// Designate the next call as an EIP-7702 transaction, with optional cross-chain validity.
2269 #[cheatcode(group = Scripting)]
2270 function attachDelegation(SignedDelegation calldata signedDelegation, bool crossChain) external;
2271
2272 /// Sign an EIP-7702 authorization and designate the next call as an EIP-7702 transaction
2273 #[cheatcode(group = Scripting)]
2274 function signAndAttachDelegation(address implementation, uint256 privateKey) external returns (SignedDelegation memory signedDelegation);
2275
2276 /// Sign an EIP-7702 authorization and designate the next call as an EIP-7702 transaction for specific nonce
2277 #[cheatcode(group = Scripting)]
2278 function signAndAttachDelegation(address implementation, uint256 privateKey, uint64 nonce) external returns (SignedDelegation memory signedDelegation);
2279
2280 /// Sign an EIP-7702 authorization and designate the next call as an EIP-7702 transaction, with optional cross-chain validity.
2281 #[cheatcode(group = Scripting)]
2282 function signAndAttachDelegation(address implementation, uint256 privateKey, bool crossChain) external returns (SignedDelegation memory signedDelegation);
2283
2284 /// Attach an EIP-4844 blob to the next call
2285 #[cheatcode(group = Scripting)]
2286 function attachBlob(bytes calldata blob) external;
2287
2288 /// Returns addresses of available unlocked wallets in the script environment.
2289 #[cheatcode(group = Scripting)]
2290 function getWallets() external view returns (address[] memory wallets);
2291
2292 // ======== Utilities ========
2293
2294 // -------- Strings --------
2295
2296 /// Converts the given value to a `string`.
2297 #[cheatcode(group = String)]
2298 function toString(address value) external pure returns (string memory stringifiedValue);
2299 /// Converts the given value to a `string`.
2300 #[cheatcode(group = String)]
2301 function toString(bytes calldata value) external pure returns (string memory stringifiedValue);
2302 /// Converts the given value to a `string`.
2303 #[cheatcode(group = String)]
2304 function toString(bytes32 value) external pure returns (string memory stringifiedValue);
2305 /// Converts the given value to a `string`.
2306 #[cheatcode(group = String)]
2307 function toString(bool value) external pure returns (string memory stringifiedValue);
2308 /// Converts the given value to a `string`.
2309 #[cheatcode(group = String)]
2310 function toString(uint256 value) external pure returns (string memory stringifiedValue);
2311 /// Converts the given value to a `string`.
2312 #[cheatcode(group = String)]
2313 function toString(int256 value) external pure returns (string memory stringifiedValue);
2314
2315 /// Parses the given `string` into `bytes`.
2316 #[cheatcode(group = String)]
2317 function parseBytes(string calldata stringifiedValue) external pure returns (bytes memory parsedValue);
2318 /// Parses the given `string` into an `address`.
2319 #[cheatcode(group = String)]
2320 function parseAddress(string calldata stringifiedValue) external pure returns (address parsedValue);
2321 /// Parses the given `string` into a `uint256`.
2322 #[cheatcode(group = String)]
2323 function parseUint(string calldata stringifiedValue) external pure returns (uint256 parsedValue);
2324 /// Parses the given `string` into a `int256`.
2325 #[cheatcode(group = String)]
2326 function parseInt(string calldata stringifiedValue) external pure returns (int256 parsedValue);
2327 /// Parses the given `string` into a `bytes32`.
2328 #[cheatcode(group = String)]
2329 function parseBytes32(string calldata stringifiedValue) external pure returns (bytes32 parsedValue);
2330 /// Parses the given `string` into a `bool`.
2331 #[cheatcode(group = String)]
2332 function parseBool(string calldata stringifiedValue) external pure returns (bool parsedValue);
2333
2334 /// Converts the given `string` value to Lowercase.
2335 #[cheatcode(group = String)]
2336 function toLowercase(string calldata input) external pure returns (string memory output);
2337 /// Converts the given `string` value to Uppercase.
2338 #[cheatcode(group = String)]
2339 function toUppercase(string calldata input) external pure returns (string memory output);
2340 /// Trims leading and trailing whitespace from the given `string` value.
2341 #[cheatcode(group = String)]
2342 function trim(string calldata input) external pure returns (string memory output);
2343 /// Replaces occurrences of `from` in the given `string` with `to`.
2344 #[cheatcode(group = String)]
2345 function replace(string calldata input, string calldata from, string calldata to) external pure returns (string memory output);
2346 /// Splits the given `string` into an array of strings divided by the `delimiter`.
2347 #[cheatcode(group = String)]
2348 function split(string calldata input, string calldata delimiter) external pure returns (string[] memory outputs);
2349 /// Returns the index of the first occurrence of a `key` in an `input` string.
2350 /// Returns `NOT_FOUND` (i.e. `type(uint256).max`) if the `key` is not found.
2351 /// Returns 0 in case of an empty `key`.
2352 #[cheatcode(group = String)]
2353 function indexOf(string calldata input, string calldata key) external pure returns (uint256);
2354 /// Returns true if `search` is found in `subject`, false otherwise.
2355 #[cheatcode(group = String)]
2356 function contains(string calldata subject, string calldata search) external pure returns (bool result);
2357
2358 // ======== JSON Parsing and Manipulation ========
2359
2360 // -------- Reading --------
2361
2362 // NOTE: Please read https://book.getfoundry.sh/cheatcodes/parse-json to understand the
2363 // limitations and caveats of the JSON parsing cheats.
2364
2365 /// Checks if `key` exists in a JSON object
2366 /// `keyExists` is being deprecated in favor of `keyExistsJson`. It will be removed in future versions.
2367 #[cheatcode(group = Json, status = Deprecated(Some("replaced by `keyExistsJson`")))]
2368 function keyExists(string calldata json, string calldata key) external view returns (bool);
2369 /// Checks if `key` exists in a JSON object.
2370 #[cheatcode(group = Json)]
2371 function keyExistsJson(string calldata json, string calldata key) external view returns (bool);
2372
2373 /// ABI-encodes a JSON object.
2374 #[cheatcode(group = Json)]
2375 function parseJson(string calldata json) external pure returns (bytes memory abiEncodedData);
2376 /// ABI-encodes a JSON object at `key`.
2377 #[cheatcode(group = Json)]
2378 function parseJson(string calldata json, string calldata key) external pure returns (bytes memory abiEncodedData);
2379
2380 // The following parseJson cheatcodes will do type coercion, for the type that they indicate.
2381 // For example, parseJsonUint will coerce all values to a uint256. That includes stringified numbers '12.'
2382 // and hex numbers '0xEF.'.
2383 // Type coercion works ONLY for discrete values or arrays. That means that the key must return a value or array, not
2384 // a JSON object.
2385
2386 /// Parses a string of JSON data at `key` and coerces it to `uint256`.
2387 #[cheatcode(group = Json)]
2388 function parseJsonUint(string calldata json, string calldata key) external pure returns (uint256);
2389 /// Parses a string of JSON data at `key` and coerces it to `uint256[]`.
2390 #[cheatcode(group = Json)]
2391 function parseJsonUintArray(string calldata json, string calldata key) external pure returns (uint256[] memory);
2392 /// Parses a string of JSON data at `key` and coerces it to `int256`.
2393 #[cheatcode(group = Json)]
2394 function parseJsonInt(string calldata json, string calldata key) external pure returns (int256);
2395 /// Parses a string of JSON data at `key` and coerces it to `int256[]`.
2396 #[cheatcode(group = Json)]
2397 function parseJsonIntArray(string calldata json, string calldata key) external pure returns (int256[] memory);
2398 /// Parses a string of JSON data at `key` and coerces it to `bool`.
2399 #[cheatcode(group = Json)]
2400 function parseJsonBool(string calldata json, string calldata key) external pure returns (bool);
2401 /// Parses a string of JSON data at `key` and coerces it to `bool[]`.
2402 #[cheatcode(group = Json)]
2403 function parseJsonBoolArray(string calldata json, string calldata key) external pure returns (bool[] memory);
2404 /// Parses a string of JSON data at `key` and coerces it to `address`.
2405 #[cheatcode(group = Json)]
2406 function parseJsonAddress(string calldata json, string calldata key) external pure returns (address);
2407 /// Parses a string of JSON data at `key` and coerces it to `address[]`.
2408 #[cheatcode(group = Json)]
2409 function parseJsonAddressArray(string calldata json, string calldata key)
2410 external
2411 pure
2412 returns (address[] memory);
2413 /// Parses a string of JSON data at `key` and coerces it to `string`.
2414 #[cheatcode(group = Json)]
2415 function parseJsonString(string calldata json, string calldata key) external pure returns (string memory);
2416 /// Parses a string of JSON data at `key` and coerces it to `string[]`.
2417 #[cheatcode(group = Json)]
2418 function parseJsonStringArray(string calldata json, string calldata key) external pure returns (string[] memory);
2419 /// Parses a string of JSON data at `key` and coerces it to `bytes`.
2420 #[cheatcode(group = Json)]
2421 function parseJsonBytes(string calldata json, string calldata key) external pure returns (bytes memory);
2422 /// Parses a string of JSON data at `key` and coerces it to `bytes[]`.
2423 #[cheatcode(group = Json)]
2424 function parseJsonBytesArray(string calldata json, string calldata key) external pure returns (bytes[] memory);
2425 /// Parses a string of JSON data at `key` and coerces it to `bytes32`.
2426 #[cheatcode(group = Json)]
2427 function parseJsonBytes32(string calldata json, string calldata key) external pure returns (bytes32);
2428 /// Parses a string of JSON data at `key` and coerces it to `bytes32[]`.
2429 #[cheatcode(group = Json)]
2430 function parseJsonBytes32Array(string calldata json, string calldata key)
2431 external
2432 pure
2433 returns (bytes32[] memory);
2434
2435 /// Parses a string of JSON data and coerces it to type corresponding to `typeDescription`.
2436 #[cheatcode(group = Json)]
2437 function parseJsonType(string calldata json, string calldata typeDescription) external pure returns (bytes memory);
2438 /// Parses a string of JSON data at `key` and coerces it to type corresponding to `typeDescription`.
2439 #[cheatcode(group = Json)]
2440 function parseJsonType(string calldata json, string calldata key, string calldata typeDescription) external pure returns (bytes memory);
2441 /// Parses a string of JSON data at `key` and coerces it to type array corresponding to `typeDescription`.
2442 #[cheatcode(group = Json)]
2443 function parseJsonTypeArray(string calldata json, string calldata key, string calldata typeDescription)
2444 external
2445 pure
2446 returns (bytes memory);
2447
2448 /// Returns an array of all the keys in a JSON object.
2449 #[cheatcode(group = Json)]
2450 function parseJsonKeys(string calldata json, string calldata key) external pure returns (string[] memory keys);
2451
2452 // -------- Writing --------
2453
2454 // NOTE: Please read https://book.getfoundry.sh/cheatcodes/serialize-json to understand how
2455 // to use the serialization cheats.
2456
2457 /// Serializes a key and value to a JSON object stored in-memory that can be later written to a file.
2458 /// Returns the stringified version of the specific JSON file up to that moment.
2459 #[cheatcode(group = Json)]
2460 function serializeJson(string calldata objectKey, string calldata value) external returns (string memory json);
2461
2462 /// See `serializeJson`.
2463 #[cheatcode(group = Json)]
2464 function serializeBool(string calldata objectKey, string calldata valueKey, bool value)
2465 external
2466 returns (string memory json);
2467 /// See `serializeJson`.
2468 #[cheatcode(group = Json)]
2469 function serializeUint(string calldata objectKey, string calldata valueKey, uint256 value)
2470 external
2471 returns (string memory json);
2472 /// See `serializeJson`.
2473 #[cheatcode(group = Json)]
2474 function serializeUintToHex(string calldata objectKey, string calldata valueKey, uint256 value)
2475 external
2476 returns (string memory json);
2477 /// See `serializeJson`.
2478 #[cheatcode(group = Json)]
2479 function serializeInt(string calldata objectKey, string calldata valueKey, int256 value)
2480 external
2481 returns (string memory json);
2482 /// See `serializeJson`.
2483 #[cheatcode(group = Json)]
2484 function serializeAddress(string calldata objectKey, string calldata valueKey, address value)
2485 external
2486 returns (string memory json);
2487 /// See `serializeJson`.
2488 #[cheatcode(group = Json)]
2489 function serializeBytes32(string calldata objectKey, string calldata valueKey, bytes32 value)
2490 external
2491 returns (string memory json);
2492 /// See `serializeJson`.
2493 #[cheatcode(group = Json)]
2494 function serializeString(string calldata objectKey, string calldata valueKey, string calldata value)
2495 external
2496 returns (string memory json);
2497 /// See `serializeJson`.
2498 #[cheatcode(group = Json)]
2499 function serializeBytes(string calldata objectKey, string calldata valueKey, bytes calldata value)
2500 external
2501 returns (string memory json);
2502
2503 /// See `serializeJson`.
2504 #[cheatcode(group = Json)]
2505 function serializeBool(string calldata objectKey, string calldata valueKey, bool[] calldata values)
2506 external
2507 returns (string memory json);
2508 /// See `serializeJson`.
2509 #[cheatcode(group = Json)]
2510 function serializeUint(string calldata objectKey, string calldata valueKey, uint256[] calldata values)
2511 external
2512 returns (string memory json);
2513 /// See `serializeJson`.
2514 #[cheatcode(group = Json)]
2515 function serializeInt(string calldata objectKey, string calldata valueKey, int256[] calldata values)
2516 external
2517 returns (string memory json);
2518 /// See `serializeJson`.
2519 #[cheatcode(group = Json)]
2520 function serializeAddress(string calldata objectKey, string calldata valueKey, address[] calldata values)
2521 external
2522 returns (string memory json);
2523 /// See `serializeJson`.
2524 #[cheatcode(group = Json)]
2525 function serializeBytes32(string calldata objectKey, string calldata valueKey, bytes32[] calldata values)
2526 external
2527 returns (string memory json);
2528 /// See `serializeJson`.
2529 #[cheatcode(group = Json)]
2530 function serializeString(string calldata objectKey, string calldata valueKey, string[] calldata values)
2531 external
2532 returns (string memory json);
2533 /// See `serializeJson`.
2534 #[cheatcode(group = Json)]
2535 function serializeBytes(string calldata objectKey, string calldata valueKey, bytes[] calldata values)
2536 external
2537 returns (string memory json);
2538 /// See `serializeJson`.
2539 #[cheatcode(group = Json)]
2540 function serializeJsonType(string calldata typeDescription, bytes calldata value)
2541 external
2542 pure
2543 returns (string memory json);
2544 /// See `serializeJson`.
2545 #[cheatcode(group = Json)]
2546 function serializeJsonType(string calldata objectKey, string calldata valueKey, string calldata typeDescription, bytes calldata value)
2547 external
2548 returns (string memory json);
2549
2550 // NOTE: Please read https://book.getfoundry.sh/cheatcodes/write-json to understand how
2551 // to use the JSON writing cheats.
2552
2553 /// Write a serialized JSON object to a file. If the file exists, it will be overwritten.
2554 #[cheatcode(group = Json)]
2555 function writeJson(string calldata json, string calldata path) external;
2556
2557 /// Write a serialized JSON object to an **existing** JSON file, replacing a value with key = <value_key.>
2558 /// This is useful to replace a specific value of a JSON file, without having to parse the entire thing.
2559 /// This cheatcode will create new keys if they didn't previously exist.
2560 #[cheatcode(group = Json)]
2561 function writeJson(string calldata json, string calldata path, string calldata valueKey) external;
2562
2563 // ======== TOML Parsing and Manipulation ========
2564
2565 // -------- Reading --------
2566
2567 // NOTE: Please read https://book.getfoundry.sh/cheatcodes/parse-toml to understand the
2568 // limitations and caveats of the TOML parsing cheat.
2569
2570 /// Checks if `key` exists in a TOML table.
2571 #[cheatcode(group = Toml)]
2572 function keyExistsToml(string calldata toml, string calldata key) external view returns (bool);
2573
2574 /// ABI-encodes a TOML table.
2575 #[cheatcode(group = Toml)]
2576 function parseToml(string calldata toml) external pure returns (bytes memory abiEncodedData);
2577
2578 /// ABI-encodes a TOML table at `key`.
2579 #[cheatcode(group = Toml)]
2580 function parseToml(string calldata toml, string calldata key) external pure returns (bytes memory abiEncodedData);
2581
2582 // The following parseToml cheatcodes will do type coercion, for the type that they indicate.
2583 // For example, parseTomlUint will coerce all values to a uint256. That includes stringified numbers '12.'
2584 // and hex numbers '0xEF.'.
2585 // Type coercion works ONLY for discrete values or arrays. That means that the key must return a value or array, not
2586 // a TOML table.
2587
2588 /// Parses a string of TOML data at `key` and coerces it to `uint256`.
2589 #[cheatcode(group = Toml)]
2590 function parseTomlUint(string calldata toml, string calldata key) external pure returns (uint256);
2591 /// Parses a string of TOML data at `key` and coerces it to `uint256[]`.
2592 #[cheatcode(group = Toml)]
2593 function parseTomlUintArray(string calldata toml, string calldata key) external pure returns (uint256[] memory);
2594 /// Parses a string of TOML data at `key` and coerces it to `int256`.
2595 #[cheatcode(group = Toml)]
2596 function parseTomlInt(string calldata toml, string calldata key) external pure returns (int256);
2597 /// Parses a string of TOML data at `key` and coerces it to `int256[]`.
2598 #[cheatcode(group = Toml)]
2599 function parseTomlIntArray(string calldata toml, string calldata key) external pure returns (int256[] memory);
2600 /// Parses a string of TOML data at `key` and coerces it to `bool`.
2601 #[cheatcode(group = Toml)]
2602 function parseTomlBool(string calldata toml, string calldata key) external pure returns (bool);
2603 /// Parses a string of TOML data at `key` and coerces it to `bool[]`.
2604 #[cheatcode(group = Toml)]
2605 function parseTomlBoolArray(string calldata toml, string calldata key) external pure returns (bool[] memory);
2606 /// Parses a string of TOML data at `key` and coerces it to `address`.
2607 #[cheatcode(group = Toml)]
2608 function parseTomlAddress(string calldata toml, string calldata key) external pure returns (address);
2609 /// Parses a string of TOML data at `key` and coerces it to `address[]`.
2610 #[cheatcode(group = Toml)]
2611 function parseTomlAddressArray(string calldata toml, string calldata key)
2612 external
2613 pure
2614 returns (address[] memory);
2615 /// Parses a string of TOML data at `key` and coerces it to `string`.
2616 #[cheatcode(group = Toml)]
2617 function parseTomlString(string calldata toml, string calldata key) external pure returns (string memory);
2618 /// Parses a string of TOML data at `key` and coerces it to `string[]`.
2619 #[cheatcode(group = Toml)]
2620 function parseTomlStringArray(string calldata toml, string calldata key) external pure returns (string[] memory);
2621 /// Parses a string of TOML data at `key` and coerces it to `bytes`.
2622 #[cheatcode(group = Toml)]
2623 function parseTomlBytes(string calldata toml, string calldata key) external pure returns (bytes memory);
2624 /// Parses a string of TOML data at `key` and coerces it to `bytes[]`.
2625 #[cheatcode(group = Toml)]
2626 function parseTomlBytesArray(string calldata toml, string calldata key) external pure returns (bytes[] memory);
2627 /// Parses a string of TOML data at `key` and coerces it to `bytes32`.
2628 #[cheatcode(group = Toml)]
2629 function parseTomlBytes32(string calldata toml, string calldata key) external pure returns (bytes32);
2630 /// Parses a string of TOML data at `key` and coerces it to `bytes32[]`.
2631 #[cheatcode(group = Toml)]
2632 function parseTomlBytes32Array(string calldata toml, string calldata key)
2633 external
2634 pure
2635 returns (bytes32[] memory);
2636
2637 /// Parses a string of TOML data and coerces it to type corresponding to `typeDescription`.
2638 #[cheatcode(group = Toml)]
2639 function parseTomlType(string calldata toml, string calldata typeDescription) external pure returns (bytes memory);
2640 /// Parses a string of TOML data at `key` and coerces it to type corresponding to `typeDescription`.
2641 #[cheatcode(group = Toml)]
2642 function parseTomlType(string calldata toml, string calldata key, string calldata typeDescription) external pure returns (bytes memory);
2643 /// Parses a string of TOML data at `key` and coerces it to type array corresponding to `typeDescription`.
2644 #[cheatcode(group = Toml)]
2645 function parseTomlTypeArray(string calldata toml, string calldata key, string calldata typeDescription)
2646 external
2647 pure
2648 returns (bytes memory);
2649
2650 /// Returns an array of all the keys in a TOML table.
2651 #[cheatcode(group = Toml)]
2652 function parseTomlKeys(string calldata toml, string calldata key) external pure returns (string[] memory keys);
2653
2654 // -------- Writing --------
2655
2656 // NOTE: Please read https://book.getfoundry.sh/cheatcodes/write-toml to understand how
2657 // to use the TOML writing cheat.
2658
2659 /// Takes serialized JSON, converts to TOML and write a serialized TOML to a file.
2660 #[cheatcode(group = Toml)]
2661 function writeToml(string calldata json, string calldata path) external;
2662
2663 /// Takes serialized JSON, converts to TOML and write a serialized TOML table to an **existing** TOML file, replacing a value with key = <value_key.>
2664 /// This is useful to replace a specific value of a TOML file, without having to parse the entire thing.
2665 /// This cheatcode will create new keys if they didn't previously exist.
2666 #[cheatcode(group = Toml)]
2667 function writeToml(string calldata json, string calldata path, string calldata valueKey) external;
2668
2669 // ======== Cryptography ========
2670
2671 // -------- Key Management --------
2672
2673 /// Derives a private key from the name, labels the account with that name, and returns the wallet.
2674 #[cheatcode(group = Crypto)]
2675 function createWallet(string calldata walletLabel) external returns (Wallet memory wallet);
2676
2677 /// Generates a wallet from the private key and returns the wallet.
2678 #[cheatcode(group = Crypto)]
2679 function createWallet(uint256 privateKey) external returns (Wallet memory wallet);
2680
2681 /// Generates a wallet from the private key, labels the account with that name, and returns the wallet.
2682 #[cheatcode(group = Crypto)]
2683 function createWallet(uint256 privateKey, string calldata walletLabel) external returns (Wallet memory wallet);
2684
2685 /// Signs data with a `Wallet`.
2686 #[cheatcode(group = Crypto)]
2687 function sign(Wallet calldata wallet, bytes32 digest) external returns (uint8 v, bytes32 r, bytes32 s);
2688
2689 /// Signs data with a `Wallet`.
2690 ///
2691 /// Returns a compact signature (`r`, `vs`) as per EIP-2098, where `vs` encodes both the
2692 /// signature's `s` value, and the recovery id `v` in a single bytes32.
2693 /// This format reduces the signature size from 65 to 64 bytes.
2694 #[cheatcode(group = Crypto)]
2695 function signCompact(Wallet calldata wallet, bytes32 digest) external returns (bytes32 r, bytes32 vs);
2696
2697 /// Signs `digest` with `privateKey` using the secp256k1 curve.
2698 #[cheatcode(group = Crypto)]
2699 function sign(uint256 privateKey, bytes32 digest) external pure returns (uint8 v, bytes32 r, bytes32 s);
2700
2701 /// Signs `digest` with `privateKey` on the secp256k1 curve, using the given `nonce`
2702 /// as the raw ephemeral k value in ECDSA (instead of deriving it deterministically).
2703 #[cheatcode(group = Crypto)]
2704 function signWithNonceUnsafe(uint256 privateKey, bytes32 digest, uint256 nonce) external pure returns (uint8 v, bytes32 r, bytes32 s);
2705
2706 /// Signs `digest` with `privateKey` using the secp256k1 curve.
2707 ///
2708 /// Returns a compact signature (`r`, `vs`) as per EIP-2098, where `vs` encodes both the
2709 /// signature's `s` value, and the recovery id `v` in a single bytes32.
2710 /// This format reduces the signature size from 65 to 64 bytes.
2711 #[cheatcode(group = Crypto)]
2712 function signCompact(uint256 privateKey, bytes32 digest) external pure returns (bytes32 r, bytes32 vs);
2713
2714 /// Signs `digest` with signer provided to script using the secp256k1 curve.
2715 ///
2716 /// If `--sender` is provided, the signer with provided address is used, otherwise,
2717 /// if exactly one signer is provided to the script, that signer is used.
2718 ///
2719 /// Raises error if signer passed through `--sender` does not match any unlocked signers or
2720 /// if `--sender` is not provided and not exactly one signer is passed to the script.
2721 #[cheatcode(group = Crypto)]
2722 function sign(bytes32 digest) external pure returns (uint8 v, bytes32 r, bytes32 s);
2723
2724 /// Signs `digest` with signer provided to script using the secp256k1 curve.
2725 ///
2726 /// Returns a compact signature (`r`, `vs`) as per EIP-2098, where `vs` encodes both the
2727 /// signature's `s` value, and the recovery id `v` in a single bytes32.
2728 /// This format reduces the signature size from 65 to 64 bytes.
2729 ///
2730 /// If `--sender` is provided, the signer with provided address is used, otherwise,
2731 /// if exactly one signer is provided to the script, that signer is used.
2732 ///
2733 /// Raises error if signer passed through `--sender` does not match any unlocked signers or
2734 /// if `--sender` is not provided and not exactly one signer is passed to the script.
2735 #[cheatcode(group = Crypto)]
2736 function signCompact(bytes32 digest) external pure returns (bytes32 r, bytes32 vs);
2737
2738 /// Signs `digest` with signer provided to script using the secp256k1 curve.
2739 ///
2740 /// Raises error if none of the signers passed into the script have provided address.
2741 #[cheatcode(group = Crypto)]
2742 function sign(address signer, bytes32 digest) external pure returns (uint8 v, bytes32 r, bytes32 s);
2743
2744 /// Signs `digest` with signer provided to script using the secp256k1 curve.
2745 ///
2746 /// Returns a compact signature (`r`, `vs`) as per EIP-2098, where `vs` encodes both the
2747 /// signature's `s` value, and the recovery id `v` in a single bytes32.
2748 /// This format reduces the signature size from 65 to 64 bytes.
2749 ///
2750 /// Raises error if none of the signers passed into the script have provided address.
2751 #[cheatcode(group = Crypto)]
2752 function signCompact(address signer, bytes32 digest) external pure returns (bytes32 r, bytes32 vs);
2753
2754 /// Signs `digest` with `privateKey` using the secp256r1 curve.
2755 #[cheatcode(group = Crypto)]
2756 function signP256(uint256 privateKey, bytes32 digest) external pure returns (bytes32 r, bytes32 s);
2757
2758 /// Derives secp256r1 public key from the provided `privateKey`.
2759 #[cheatcode(group = Crypto)]
2760 function publicKeyP256(uint256 privateKey) external pure returns (uint256 publicKeyX, uint256 publicKeyY);
2761
2762 /// Derive a private key from a provided mnemonic string (or mnemonic file path)
2763 /// at the derivation path `m/44'/60'/0'/0/{index}`.
2764 #[cheatcode(group = Crypto)]
2765 function deriveKey(string calldata mnemonic, uint32 index) external pure returns (uint256 privateKey);
2766 /// Derive a private key from a provided mnemonic string (or mnemonic file path)
2767 /// at `{derivationPath}{index}`.
2768 #[cheatcode(group = Crypto)]
2769 function deriveKey(string calldata mnemonic, string calldata derivationPath, uint32 index)
2770 external
2771 pure
2772 returns (uint256 privateKey);
2773 /// Derive a private key from a provided mnemonic string (or mnemonic file path) in the specified language
2774 /// at the derivation path `m/44'/60'/0'/0/{index}`.
2775 #[cheatcode(group = Crypto)]
2776 function deriveKey(string calldata mnemonic, uint32 index, string calldata language)
2777 external
2778 pure
2779 returns (uint256 privateKey);
2780 /// Derive a private key from a provided mnemonic string (or mnemonic file path) in the specified language
2781 /// at `{derivationPath}{index}`.
2782 #[cheatcode(group = Crypto)]
2783 function deriveKey(string calldata mnemonic, string calldata derivationPath, uint32 index, string calldata language)
2784 external
2785 pure
2786 returns (uint256 privateKey);
2787
2788 /// Adds a private key to the local forge wallet and returns the address.
2789 #[cheatcode(group = Crypto)]
2790 function rememberKey(uint256 privateKey) external returns (address keyAddr);
2791
2792 /// Derive a set number of wallets from a mnemonic at the derivation path `m/44'/60'/0'/0/{0..count}`.
2793 ///
2794 /// The respective private keys are saved to the local forge wallet for later use and their addresses are returned.
2795 #[cheatcode(group = Crypto)]
2796 function rememberKeys(string calldata mnemonic, string calldata derivationPath, uint32 count) external returns (address[] memory keyAddrs);
2797
2798 /// Derive a set number of wallets from a mnemonic in the specified language at the derivation path `m/44'/60'/0'/0/{0..count}`.
2799 ///
2800 /// The respective private keys are saved to the local forge wallet for later use and their addresses are returned.
2801 #[cheatcode(group = Crypto)]
2802 function rememberKeys(string calldata mnemonic, string calldata derivationPath, string calldata language, uint32 count)
2803 external
2804 returns (address[] memory keyAddrs);
2805
2806 // -------- Uncategorized Utilities --------
2807
2808 /// Labels an address in call traces.
2809 #[cheatcode(group = Utilities)]
2810 function label(address account, string calldata newLabel) external;
2811
2812 /// Gets the label for the specified address.
2813 #[cheatcode(group = Utilities)]
2814 function getLabel(address account) external view returns (string memory currentLabel);
2815
2816 /// Compute the address a contract will be deployed at for a given deployer address and nonce.
2817 #[cheatcode(group = Utilities)]
2818 function computeCreateAddress(address deployer, uint256 nonce) external pure returns (address);
2819
2820 /// Compute the address of a contract created with CREATE2 using the given CREATE2 deployer.
2821 #[cheatcode(group = Utilities)]
2822 function computeCreate2Address(bytes32 salt, bytes32 initCodeHash, address deployer) external pure returns (address);
2823
2824 /// Compute the address of a contract created with CREATE2 using the default CREATE2 deployer.
2825 #[cheatcode(group = Utilities)]
2826 function computeCreate2Address(bytes32 salt, bytes32 initCodeHash) external pure returns (address);
2827
2828 /// Encodes a `bytes` value to a base64 string.
2829 #[cheatcode(group = Utilities)]
2830 function toBase64(bytes calldata data) external pure returns (string memory);
2831
2832 /// Encodes a `string` value to a base64 string.
2833 #[cheatcode(group = Utilities)]
2834 function toBase64(string calldata data) external pure returns (string memory);
2835
2836 /// Encodes a `bytes` value to a base64url string.
2837 #[cheatcode(group = Utilities)]
2838 function toBase64URL(bytes calldata data) external pure returns (string memory);
2839
2840 /// Encodes a `string` value to a base64url string.
2841 #[cheatcode(group = Utilities)]
2842 function toBase64URL(string calldata data) external pure returns (string memory);
2843
2844 /// Returns ENS namehash for provided string.
2845 #[cheatcode(group = Utilities)]
2846 function ensNamehash(string calldata name) external pure returns (bytes32);
2847
2848 /// Returns an uint256 value bounded in given range and different from the current one.
2849 #[cheatcode(group = Utilities)]
2850 function bound(uint256 current, uint256 min, uint256 max) external view returns (uint256);
2851
2852 /// Returns a random uint256 value.
2853 #[cheatcode(group = Utilities)]
2854 function randomUint() external view returns (uint256);
2855
2856 /// Returns random uint256 value between the provided range (=min..=max).
2857 #[cheatcode(group = Utilities)]
2858 function randomUint(uint256 min, uint256 max) external view returns (uint256);
2859
2860 /// Returns a random `uint256` value of given bits.
2861 #[cheatcode(group = Utilities)]
2862 function randomUint(uint256 bits) external view returns (uint256);
2863
2864 /// Returns a random `address`.
2865 #[cheatcode(group = Utilities)]
2866 function randomAddress() external view returns (address);
2867
2868 /// Returns an int256 value bounded in given range and different from the current one.
2869 #[cheatcode(group = Utilities)]
2870 function bound(int256 current, int256 min, int256 max) external view returns (int256);
2871
2872 /// Returns a random `int256` value.
2873 #[cheatcode(group = Utilities)]
2874 function randomInt() external view returns (int256);
2875
2876 /// Returns a random `int256` value of given bits.
2877 #[cheatcode(group = Utilities)]
2878 function randomInt(uint256 bits) external view returns (int256);
2879
2880 /// Returns a random `bool`.
2881 #[cheatcode(group = Utilities)]
2882 function randomBool() external view returns (bool);
2883
2884 /// Returns a random byte array value of the given length.
2885 #[cheatcode(group = Utilities)]
2886 function randomBytes(uint256 len) external view returns (bytes memory);
2887
2888 /// Returns a random fixed-size byte array of length 4.
2889 #[cheatcode(group = Utilities)]
2890 function randomBytes4() external view returns (bytes4);
2891
2892 /// Returns a random fixed-size byte array of length 8.
2893 #[cheatcode(group = Utilities)]
2894 function randomBytes8() external view returns (bytes8);
2895
2896 /// Pauses collection of call traces. Useful in cases when you want to skip tracing of
2897 /// complex calls which are not useful for debugging.
2898 #[cheatcode(group = Utilities)]
2899 function pauseTracing() external view;
2900
2901 /// Unpauses collection of call traces.
2902 #[cheatcode(group = Utilities)]
2903 function resumeTracing() external view;
2904
2905 /// Utility cheatcode to copy storage of `from` contract to another `to` contract.
2906 #[cheatcode(group = Utilities)]
2907 function copyStorage(address from, address to) external;
2908
2909 /// Utility cheatcode to set arbitrary storage for given target address.
2910 #[cheatcode(group = Utilities)]
2911 function setArbitraryStorage(address target) external;
2912
2913 /// Utility cheatcode to set arbitrary storage for given target address and overwrite
2914 /// any storage slots that have been previously set.
2915 #[cheatcode(group = Utilities)]
2916 function setArbitraryStorage(address target, bool overwrite) external;
2917
2918 /// Sorts an array in ascending order.
2919 #[cheatcode(group = Utilities)]
2920 function sort(uint256[] calldata array) external returns (uint256[] memory);
2921
2922 /// Randomly shuffles an array.
2923 #[cheatcode(group = Utilities)]
2924 function shuffle(uint256[] calldata array) external returns (uint256[] memory);
2925
2926 /// Set RNG seed.
2927 #[cheatcode(group = Utilities)]
2928 function setSeed(uint256 seed) external;
2929
2930 /// Causes the next contract creation (via new) to fail and return its initcode in the returndata buffer.
2931 /// This allows type-safe access to the initcode payload that would be used for contract creation.
2932 /// Example usage:
2933 /// vm.interceptInitcode();
2934 /// bytes memory initcode;
2935 /// try new MyContract(param1, param2) { assert(false); }
2936 /// catch (bytes memory interceptedInitcode) { initcode = interceptedInitcode; }
2937 #[cheatcode(group = Utilities, safety = Unsafe)]
2938 function interceptInitcode() external;
2939
2940 /// Generates the hash of the canonical EIP-712 type representation.
2941 ///
2942 /// Supports 2 different inputs:
2943 /// 1. Name of the type (i.e. "Transaction"):
2944 /// * requires previous binding generation with `forge bind-json`.
2945 /// * bindings will be retrieved from the path configured in `foundry.toml`.
2946 ///
2947 /// 2. String representation of the type (i.e. "Foo(Bar bar) Bar(uint256 baz)").
2948 /// * Note: the cheatcode will output the canonical type even if the input is malformated
2949 /// with the wrong order of elements or with extra whitespaces.
2950 #[cheatcode(group = Utilities)]
2951 function eip712HashType(string calldata typeNameOrDefinition) external pure returns (bytes32 typeHash);
2952
2953 /// Generates the hash of the canonical EIP-712 type representation.
2954 /// Requires previous binding generation with `forge bind-json`.
2955 ///
2956 /// Params:
2957 /// * `bindingsPath`: path where the output of `forge bind-json` is stored.
2958 /// * `typeName`: Name of the type (i.e. "Transaction").
2959 #[cheatcode(group = Utilities)]
2960 function eip712HashType(string calldata bindingsPath, string calldata typeName) external pure returns (bytes32 typeHash);
2961
2962 /// Generates the struct hash of the canonical EIP-712 type representation and its abi-encoded data.
2963 ///
2964 /// Supports 2 different inputs:
2965 /// 1. Name of the type (i.e. "PermitSingle"):
2966 /// * requires previous binding generation with `forge bind-json`.
2967 /// * bindings will be retrieved from the path configured in `foundry.toml`.
2968 ///
2969 /// 2. String representation of the type (i.e. "Foo(Bar bar) Bar(uint256 baz)").
2970 /// * Note: the cheatcode will use the canonical type even if the input is malformated
2971 /// with the wrong order of elements or with extra whitespaces.
2972 #[cheatcode(group = Utilities)]
2973 function eip712HashStruct(string calldata typeNameOrDefinition, bytes calldata abiEncodedData) external pure returns (bytes32 typeHash);
2974
2975 /// Generates the struct hash of the canonical EIP-712 type representation and its abi-encoded data.
2976 /// Requires previous binding generation with `forge bind-json`.
2977 ///
2978 /// Params:
2979 /// * `bindingsPath`: path where the output of `forge bind-json` is stored.
2980 /// * `typeName`: Name of the type (i.e. "PermitSingle").
2981 /// * `abiEncodedData`: ABI-encoded data for the struct that is being hashed.
2982 #[cheatcode(group = Utilities)]
2983 function eip712HashStruct(string calldata bindingsPath, string calldata typeName, bytes calldata abiEncodedData) external pure returns (bytes32 typeHash);
2984
2985 /// Generates a ready-to-sign digest of human-readable typed data following the EIP-712 standard.
2986 #[cheatcode(group = Utilities)]
2987 function eip712HashTypedData(string calldata jsonData) external pure returns (bytes32 digest);
2988}
2989}
2990
2991impl PartialEq for ForgeContext {
2992 // Handles test group case (any of test, coverage or snapshot)
2993 // and script group case (any of dry run, broadcast or resume).
2994 fn eq(&self, other: &Self) -> bool {
2995 match (self, other) {
2996 (_, Self::TestGroup) => {
2997 matches!(self, Self::Test | Self::Snapshot | Self::Coverage)
2998 }
2999 (_, Self::ScriptGroup) => {
3000 matches!(self, Self::ScriptDryRun | Self::ScriptBroadcast | Self::ScriptResume)
3001 }
3002 (Self::Test, Self::Test)
3003 | (Self::Snapshot, Self::Snapshot)
3004 | (Self::Coverage, Self::Coverage)
3005 | (Self::ScriptDryRun, Self::ScriptDryRun)
3006 | (Self::ScriptBroadcast, Self::ScriptBroadcast)
3007 | (Self::ScriptResume, Self::ScriptResume)
3008 | (Self::Unknown, Self::Unknown) => true,
3009 _ => false,
3010 }
3011 }
3012}
3013
3014impl fmt::Display for Vm::CheatcodeError {
3015 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
3016 self.message.fmt(f)
3017 }
3018}
3019
3020impl fmt::Display for Vm::VmErrors {
3021 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
3022 match self {
3023 Self::CheatcodeError(err) => err.fmt(f),
3024 }
3025 }
3026}
3027
3028#[track_caller]
3029const fn panic_unknown_safety() -> ! {
3030 panic!("cannot determine safety from the group, add a `#[cheatcode(safety = ...)]` attribute")
3031}