-
Notifications
You must be signed in to change notification settings - Fork 312
/
Vm.sol
1763 lines (1345 loc) · 89.3 KB
/
Vm.sol
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
// Automatically @generated by scripts/vm.py. Do not modify manually.
// SPDX-License-Identifier: MIT OR Apache-2.0
pragma solidity >=0.6.2 <0.9.0;
pragma experimental ABIEncoderV2;
/// The `VmSafe` interface does not allow manipulation of the EVM state or other actions that may
/// result in Script simulations differing from on-chain execution. It is recommended to only use
/// these cheats in scripts.
interface VmSafe {
/// A modification applied to either `msg.sender` or `tx.origin`. Returned by `readCallers`.
enum CallerMode {
// No caller modification is currently active.
None,
// A one time broadcast triggered by a `vm.broadcast()` call is currently active.
Broadcast,
// A recurrent broadcast triggered by a `vm.startBroadcast()` call is currently active.
RecurrentBroadcast,
// A one time prank triggered by a `vm.prank()` call is currently active.
Prank,
// A recurrent prank triggered by a `vm.startPrank()` call is currently active.
RecurrentPrank
}
/// The kind of account access that occurred.
enum AccountAccessKind {
// The account was called.
Call,
// The account was called via delegatecall.
DelegateCall,
// The account was called via callcode.
CallCode,
// The account was called via staticcall.
StaticCall,
// The account was created.
Create,
// The account was selfdestructed.
SelfDestruct,
// Synthetic access indicating the current context has resumed after a previous sub-context (AccountAccess).
Resume,
// The account's balance was read.
Balance,
// The account's codesize was read.
Extcodesize,
// The account's codehash was read.
Extcodehash,
// The account's code was copied.
Extcodecopy
}
/// Forge execution contexts.
enum ForgeContext {
// Test group execution context (test, coverage or snapshot).
TestGroup,
// `forge test` execution context.
Test,
// `forge coverage` execution context.
Coverage,
// `forge snapshot` execution context.
Snapshot,
// Script group execution context (dry run, broadcast or resume).
ScriptGroup,
// `forge script` execution context.
ScriptDryRun,
// `forge script --broadcast` execution context.
ScriptBroadcast,
// `forge script --resume` execution context.
ScriptResume,
// Unknown `forge` execution context.
Unknown
}
/// An Ethereum log. Returned by `getRecordedLogs`.
struct Log {
// The topics of the log, including the signature, if any.
bytes32[] topics;
// The raw data of the log.
bytes data;
// The address of the log's emitter.
address emitter;
}
/// An RPC URL and its alias. Returned by `rpcUrlStructs`.
struct Rpc {
// The alias of the RPC URL.
string key;
// The RPC URL.
string url;
}
/// An RPC log object. Returned by `eth_getLogs`.
struct EthGetLogs {
// The address of the log's emitter.
address emitter;
// The topics of the log, including the signature, if any.
bytes32[] topics;
// The raw data of the log.
bytes data;
// The block hash.
bytes32 blockHash;
// The block number.
uint64 blockNumber;
// The transaction hash.
bytes32 transactionHash;
// The transaction index in the block.
uint64 transactionIndex;
// The log index.
uint256 logIndex;
// Whether the log was removed.
bool removed;
}
/// A single entry in a directory listing. Returned by `readDir`.
struct DirEntry {
// The error message, if any.
string errorMessage;
// The path of the entry.
string path;
// The depth of the entry.
uint64 depth;
// Whether the entry is a directory.
bool isDir;
// Whether the entry is a symlink.
bool isSymlink;
}
/// Metadata information about a file.
/// This structure is returned from the `fsMetadata` function and represents known
/// metadata about a file such as its permissions, size, modification
/// times, etc.
struct FsMetadata {
// True if this metadata is for a directory.
bool isDir;
// True if this metadata is for a symlink.
bool isSymlink;
// The size of the file, in bytes, this metadata is for.
uint256 length;
// True if this metadata is for a readonly (unwritable) file.
bool readOnly;
// The last modification time listed in this metadata.
uint256 modified;
// The last access time of this metadata.
uint256 accessed;
// The creation time listed in this metadata.
uint256 created;
}
/// A wallet with a public and private key.
struct Wallet {
// The wallet's address.
address addr;
// The wallet's public key `X`.
uint256 publicKeyX;
// The wallet's public key `Y`.
uint256 publicKeyY;
// The wallet's private key.
uint256 privateKey;
}
/// The result of a `tryFfi` call.
struct FfiResult {
// The exit code of the call.
int32 exitCode;
// The optionally hex-decoded `stdout` data.
bytes stdout;
// The `stderr` data.
bytes stderr;
}
/// Information on the chain and fork.
struct ChainInfo {
// The fork identifier. Set to zero if no fork is active.
uint256 forkId;
// The chain ID of the current fork.
uint256 chainId;
}
/// The result of a `stopAndReturnStateDiff` call.
struct AccountAccess {
// The chain and fork the access occurred.
ChainInfo chainInfo;
// The kind of account access that determines what the account is.
// If kind is Call, DelegateCall, StaticCall or CallCode, then the account is the callee.
// If kind is Create, then the account is the newly created account.
// If kind is SelfDestruct, then the account is the selfdestruct recipient.
// If kind is a Resume, then account represents a account context that has resumed.
AccountAccessKind kind;
// The account that was accessed.
// It's either the account created, callee or a selfdestruct recipient for CREATE, CALL or SELFDESTRUCT.
address account;
// What accessed the account.
address accessor;
// If the account was initialized or empty prior to the access.
// An account is considered initialized if it has code, a
// non-zero nonce, or a non-zero balance.
bool initialized;
// The previous balance of the accessed account.
uint256 oldBalance;
// The potential new balance of the accessed account.
// That is, all balance changes are recorded here, even if reverts occurred.
uint256 newBalance;
// Code of the account deployed by CREATE.
bytes deployedCode;
// Value passed along with the account access
uint256 value;
// Input data provided to the CREATE or CALL
bytes data;
// If this access reverted in either the current or parent context.
bool reverted;
// An ordered list of storage accesses made during an account access operation.
StorageAccess[] storageAccesses;
// Call depth traversed during the recording of state differences
uint64 depth;
}
/// The storage accessed during an `AccountAccess`.
struct StorageAccess {
// The account whose storage was accessed.
address account;
// The slot that was accessed.
bytes32 slot;
// If the access was a write.
bool isWrite;
// The previous value of the slot.
bytes32 previousValue;
// The new value of the slot.
bytes32 newValue;
// If the access was reverted.
bool reverted;
}
/// Gas used. Returned by `lastCallGas`.
struct Gas {
// The gas limit of the call.
uint64 gasLimit;
// The total gas used.
uint64 gasTotalUsed;
// DEPRECATED: The amount of gas used for memory expansion. Ref: <https://github.com/foundry-rs/foundry/pull/7934#pullrequestreview-2069236939>
uint64 gasMemoryUsed;
// The amount of gas refunded.
int64 gasRefunded;
// The amount of gas remaining.
uint64 gasRemaining;
}
// ======== Environment ========
/// Gets the environment variable `name` and parses it as `address`.
/// Reverts if the variable was not found or could not be parsed.
function envAddress(string calldata name) external view returns (address value);
/// Gets the environment variable `name` and parses it as an array of `address`, delimited by `delim`.
/// Reverts if the variable was not found or could not be parsed.
function envAddress(string calldata name, string calldata delim) external view returns (address[] memory value);
/// Gets the environment variable `name` and parses it as `bool`.
/// Reverts if the variable was not found or could not be parsed.
function envBool(string calldata name) external view returns (bool value);
/// Gets the environment variable `name` and parses it as an array of `bool`, delimited by `delim`.
/// Reverts if the variable was not found or could not be parsed.
function envBool(string calldata name, string calldata delim) external view returns (bool[] memory value);
/// Gets the environment variable `name` and parses it as `bytes32`.
/// Reverts if the variable was not found or could not be parsed.
function envBytes32(string calldata name) external view returns (bytes32 value);
/// Gets the environment variable `name` and parses it as an array of `bytes32`, delimited by `delim`.
/// Reverts if the variable was not found or could not be parsed.
function envBytes32(string calldata name, string calldata delim) external view returns (bytes32[] memory value);
/// Gets the environment variable `name` and parses it as `bytes`.
/// Reverts if the variable was not found or could not be parsed.
function envBytes(string calldata name) external view returns (bytes memory value);
/// Gets the environment variable `name` and parses it as an array of `bytes`, delimited by `delim`.
/// Reverts if the variable was not found or could not be parsed.
function envBytes(string calldata name, string calldata delim) external view returns (bytes[] memory value);
/// Gets the environment variable `name` and returns true if it exists, else returns false.
function envExists(string calldata name) external view returns (bool result);
/// Gets the environment variable `name` and parses it as `int256`.
/// Reverts if the variable was not found or could not be parsed.
function envInt(string calldata name) external view returns (int256 value);
/// Gets the environment variable `name` and parses it as an array of `int256`, delimited by `delim`.
/// Reverts if the variable was not found or could not be parsed.
function envInt(string calldata name, string calldata delim) external view returns (int256[] memory value);
/// Gets the environment variable `name` and parses it as `bool`.
/// Reverts if the variable could not be parsed.
/// Returns `defaultValue` if the variable was not found.
function envOr(string calldata name, bool defaultValue) external view returns (bool value);
/// Gets the environment variable `name` and parses it as `uint256`.
/// Reverts if the variable could not be parsed.
/// Returns `defaultValue` if the variable was not found.
function envOr(string calldata name, uint256 defaultValue) external view returns (uint256 value);
/// Gets the environment variable `name` and parses it as an array of `address`, delimited by `delim`.
/// Reverts if the variable could not be parsed.
/// Returns `defaultValue` if the variable was not found.
function envOr(string calldata name, string calldata delim, address[] calldata defaultValue)
external
view
returns (address[] memory value);
/// Gets the environment variable `name` and parses it as an array of `bytes32`, delimited by `delim`.
/// Reverts if the variable could not be parsed.
/// Returns `defaultValue` if the variable was not found.
function envOr(string calldata name, string calldata delim, bytes32[] calldata defaultValue)
external
view
returns (bytes32[] memory value);
/// Gets the environment variable `name` and parses it as an array of `string`, delimited by `delim`.
/// Reverts if the variable could not be parsed.
/// Returns `defaultValue` if the variable was not found.
function envOr(string calldata name, string calldata delim, string[] calldata defaultValue)
external
view
returns (string[] memory value);
/// Gets the environment variable `name` and parses it as an array of `bytes`, delimited by `delim`.
/// Reverts if the variable could not be parsed.
/// Returns `defaultValue` if the variable was not found.
function envOr(string calldata name, string calldata delim, bytes[] calldata defaultValue)
external
view
returns (bytes[] memory value);
/// Gets the environment variable `name` and parses it as `int256`.
/// Reverts if the variable could not be parsed.
/// Returns `defaultValue` if the variable was not found.
function envOr(string calldata name, int256 defaultValue) external view returns (int256 value);
/// Gets the environment variable `name` and parses it as `address`.
/// Reverts if the variable could not be parsed.
/// Returns `defaultValue` if the variable was not found.
function envOr(string calldata name, address defaultValue) external view returns (address value);
/// Gets the environment variable `name` and parses it as `bytes32`.
/// Reverts if the variable could not be parsed.
/// Returns `defaultValue` if the variable was not found.
function envOr(string calldata name, bytes32 defaultValue) external view returns (bytes32 value);
/// Gets the environment variable `name` and parses it as `string`.
/// Reverts if the variable could not be parsed.
/// Returns `defaultValue` if the variable was not found.
function envOr(string calldata name, string calldata defaultValue) external view returns (string memory value);
/// Gets the environment variable `name` and parses it as `bytes`.
/// Reverts if the variable could not be parsed.
/// Returns `defaultValue` if the variable was not found.
function envOr(string calldata name, bytes calldata defaultValue) external view returns (bytes memory value);
/// Gets the environment variable `name` and parses it as an array of `bool`, delimited by `delim`.
/// Reverts if the variable could not be parsed.
/// Returns `defaultValue` if the variable was not found.
function envOr(string calldata name, string calldata delim, bool[] calldata defaultValue)
external
view
returns (bool[] memory value);
/// Gets the environment variable `name` and parses it as an array of `uint256`, delimited by `delim`.
/// Reverts if the variable could not be parsed.
/// Returns `defaultValue` if the variable was not found.
function envOr(string calldata name, string calldata delim, uint256[] calldata defaultValue)
external
view
returns (uint256[] memory value);
/// Gets the environment variable `name` and parses it as an array of `int256`, delimited by `delim`.
/// Reverts if the variable could not be parsed.
/// Returns `defaultValue` if the variable was not found.
function envOr(string calldata name, string calldata delim, int256[] calldata defaultValue)
external
view
returns (int256[] memory value);
/// Gets the environment variable `name` and parses it as `string`.
/// Reverts if the variable was not found or could not be parsed.
function envString(string calldata name) external view returns (string memory value);
/// Gets the environment variable `name` and parses it as an array of `string`, delimited by `delim`.
/// Reverts if the variable was not found or could not be parsed.
function envString(string calldata name, string calldata delim) external view returns (string[] memory value);
/// Gets the environment variable `name` and parses it as `uint256`.
/// Reverts if the variable was not found or could not be parsed.
function envUint(string calldata name) external view returns (uint256 value);
/// Gets the environment variable `name` and parses it as an array of `uint256`, delimited by `delim`.
/// Reverts if the variable was not found or could not be parsed.
function envUint(string calldata name, string calldata delim) external view returns (uint256[] memory value);
/// Returns true if `forge` command was executed in given context.
function isContext(ForgeContext context) external view returns (bool result);
/// Sets environment variables.
function setEnv(string calldata name, string calldata value) external;
// ======== EVM ========
/// Gets all accessed reads and write slot from a `vm.record` session, for a given address.
function accesses(address target) external returns (bytes32[] memory readSlots, bytes32[] memory writeSlots);
/// Gets the address for a given private key.
function addr(uint256 privateKey) external pure returns (address keyAddr);
/// Gets all the logs according to specified filter.
function eth_getLogs(uint256 fromBlock, uint256 toBlock, address target, bytes32[] calldata topics)
external
returns (EthGetLogs[] memory logs);
/// Gets the current `block.blobbasefee`.
/// You should use this instead of `block.blobbasefee` if you use `vm.blobBaseFee`, as `block.blobbasefee` is assumed to be constant across a transaction,
/// and as a result will get optimized out by the compiler.
/// See https://github.com/foundry-rs/foundry/issues/6180
function getBlobBaseFee() external view returns (uint256 blobBaseFee);
/// Gets the current `block.number`.
/// You should use this instead of `block.number` if you use `vm.roll`, as `block.number` is assumed to be constant across a transaction,
/// and as a result will get optimized out by the compiler.
/// See https://github.com/foundry-rs/foundry/issues/6180
function getBlockNumber() external view returns (uint256 height);
/// Gets the current `block.timestamp`.
/// You should use this instead of `block.timestamp` if you use `vm.warp`, as `block.timestamp` is assumed to be constant across a transaction,
/// and as a result will get optimized out by the compiler.
/// See https://github.com/foundry-rs/foundry/issues/6180
function getBlockTimestamp() external view returns (uint256 timestamp);
/// Gets the map key and parent of a mapping at a given slot, for a given address.
function getMappingKeyAndParentOf(address target, bytes32 elementSlot)
external
returns (bool found, bytes32 key, bytes32 parent);
/// Gets the number of elements in the mapping at the given slot, for a given address.
function getMappingLength(address target, bytes32 mappingSlot) external returns (uint256 length);
/// Gets the elements at index idx of the mapping at the given slot, for a given address. The
/// index must be less than the length of the mapping (i.e. the number of keys in the mapping).
function getMappingSlotAt(address target, bytes32 mappingSlot, uint256 idx) external returns (bytes32 value);
/// Gets the nonce of an account.
function getNonce(address account) external view returns (uint64 nonce);
/// Gets all the recorded logs.
function getRecordedLogs() external returns (Log[] memory logs);
/// Gets the gas used in the last call.
function lastCallGas() external view returns (Gas memory gas);
/// Loads a storage slot from an address.
function load(address target, bytes32 slot) external view returns (bytes32 data);
/// Pauses gas metering (i.e. gas usage is not counted). Noop if already paused.
function pauseGasMetering() external;
/// Records all storage reads and writes.
function record() external;
/// Record all the transaction logs.
function recordLogs() external;
/// Resumes gas metering (i.e. gas usage is counted again). Noop if already on.
function resumeGasMetering() external;
/// Performs an Ethereum JSON-RPC request to the current fork URL.
function rpc(string calldata method, string calldata params) external returns (bytes memory data);
/// Signs `digest` with `privateKey` using the secp256r1 curve.
function signP256(uint256 privateKey, bytes32 digest) external pure returns (bytes32 r, bytes32 s);
/// Signs `digest` with `privateKey` using the secp256k1 curve.
function sign(uint256 privateKey, bytes32 digest) external pure returns (uint8 v, bytes32 r, bytes32 s);
/// Signs `digest` with signer provided to script using the secp256k1 curve.
/// If `--sender` is provided, the signer with provided address is used, otherwise,
/// if exactly one signer is provided to the script, that signer is used.
/// Raises error if signer passed through `--sender` does not match any unlocked signers or
/// if `--sender` is not provided and not exactly one signer is passed to the script.
function sign(bytes32 digest) external pure returns (uint8 v, bytes32 r, bytes32 s);
/// Signs `digest` with signer provided to script using the secp256k1 curve.
/// Raises error if none of the signers passed into the script have provided address.
function sign(address signer, bytes32 digest) external pure returns (uint8 v, bytes32 r, bytes32 s);
/// Starts recording all map SSTOREs for later retrieval.
function startMappingRecording() external;
/// Record all account accesses as part of CREATE, CALL or SELFDESTRUCT opcodes in order,
/// along with the context of the calls
function startStateDiffRecording() external;
/// Returns an ordered array of all account accesses from a `vm.startStateDiffRecording` session.
function stopAndReturnStateDiff() external returns (AccountAccess[] memory accountAccesses);
/// Stops recording all map SSTOREs for later retrieval and clears the recorded data.
function stopMappingRecording() external;
// ======== Filesystem ========
/// Closes file for reading, resetting the offset and allowing to read it from beginning with readLine.
/// `path` is relative to the project root.
function closeFile(string calldata path) external;
/// Copies the contents of one file to another. This function will **overwrite** the contents of `to`.
/// 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`.
/// Both `from` and `to` are relative to the project root.
function copyFile(string calldata from, string calldata to) external returns (uint64 copied);
/// Creates a new, empty directory at the provided path.
/// This cheatcode will revert in the following situations, but is not limited to just these cases:
/// - User lacks permissions to modify `path`.
/// - A parent of the given path doesn't exist and `recursive` is false.
/// - `path` already exists and `recursive` is false.
/// `path` is relative to the project root.
function createDir(string calldata path, bool recursive) external;
/// Returns true if the given path points to an existing entity, else returns false.
function exists(string calldata path) external returns (bool result);
/// Performs a foreign function call via the terminal.
function ffi(string[] calldata commandInput) external returns (bytes memory result);
/// Given a path, query the file system to get information about a file, directory, etc.
function fsMetadata(string calldata path) external view returns (FsMetadata memory metadata);
/// Gets the creation bytecode from an artifact file. Takes in the relative path to the json file or the path to the
/// artifact in the form of <path>:<contract>:<version> where <contract> and <version> parts are optional.
function getCode(string calldata artifactPath) external view returns (bytes memory creationBytecode);
/// Gets the deployed bytecode from an artifact file. Takes in the relative path to the json file or the path to the
/// artifact in the form of <path>:<contract>:<version> where <contract> and <version> parts are optional.
function getDeployedCode(string calldata artifactPath) external view returns (bytes memory runtimeBytecode);
/// Returns true if the path exists on disk and is pointing at a directory, else returns false.
function isDir(string calldata path) external returns (bool result);
/// Returns true if the path exists on disk and is pointing at a regular file, else returns false.
function isFile(string calldata path) external returns (bool result);
/// Get the path of the current project root.
function projectRoot() external view returns (string memory path);
/// Prompts the user for a string value in the terminal.
function prompt(string calldata promptText) external returns (string memory input);
/// Prompts the user for an address in the terminal.
function promptAddress(string calldata promptText) external returns (address);
/// Prompts the user for a hidden string value in the terminal.
function promptSecret(string calldata promptText) external returns (string memory input);
/// Prompts the user for hidden uint256 in the terminal (usually pk).
function promptSecretUint(string calldata promptText) external returns (uint256);
/// Prompts the user for uint256 in the terminal.
function promptUint(string calldata promptText) external returns (uint256);
/// Reads the directory at the given path recursively, up to `maxDepth`.
/// `maxDepth` defaults to 1, meaning only the direct children of the given directory will be returned.
/// Follows symbolic links if `followLinks` is true.
function readDir(string calldata path) external view returns (DirEntry[] memory entries);
/// See `readDir(string)`.
function readDir(string calldata path, uint64 maxDepth) external view returns (DirEntry[] memory entries);
/// See `readDir(string)`.
function readDir(string calldata path, uint64 maxDepth, bool followLinks)
external
view
returns (DirEntry[] memory entries);
/// Reads the entire content of file to string. `path` is relative to the project root.
function readFile(string calldata path) external view returns (string memory data);
/// Reads the entire content of file as binary. `path` is relative to the project root.
function readFileBinary(string calldata path) external view returns (bytes memory data);
/// Reads next line of file to string.
function readLine(string calldata path) external view returns (string memory line);
/// Reads a symbolic link, returning the path that the link points to.
/// This cheatcode will revert in the following situations, but is not limited to just these cases:
/// - `path` is not a symbolic link.
/// - `path` does not exist.
function readLink(string calldata linkPath) external view returns (string memory targetPath);
/// Removes a directory at the provided path.
/// This cheatcode will revert in the following situations, but is not limited to just these cases:
/// - `path` doesn't exist.
/// - `path` isn't a directory.
/// - User lacks permissions to modify `path`.
/// - The directory is not empty and `recursive` is false.
/// `path` is relative to the project root.
function removeDir(string calldata path, bool recursive) external;
/// Removes a file from the filesystem.
/// This cheatcode will revert in the following situations, but is not limited to just these cases:
/// - `path` points to a directory.
/// - The file doesn't exist.
/// - The user lacks permissions to remove the file.
/// `path` is relative to the project root.
function removeFile(string calldata path) external;
/// Performs a foreign function call via terminal and returns the exit code, stdout, and stderr.
function tryFfi(string[] calldata commandInput) external returns (FfiResult memory result);
/// Returns the time since unix epoch in milliseconds.
function unixTime() external returns (uint256 milliseconds);
/// Writes data to file, creating a file if it does not exist, and entirely replacing its contents if it does.
/// `path` is relative to the project root.
function writeFile(string calldata path, string calldata data) external;
/// Writes binary data to a file, creating a file if it does not exist, and entirely replacing its contents if it does.
/// `path` is relative to the project root.
function writeFileBinary(string calldata path, bytes calldata data) external;
/// Writes line to file, creating a file if it does not exist.
/// `path` is relative to the project root.
function writeLine(string calldata path, string calldata data) external;
// ======== JSON ========
/// Checks if `key` exists in a JSON object
/// `keyExists` is being deprecated in favor of `keyExistsJson`. It will be removed in future versions.
function keyExists(string calldata json, string calldata key) external view returns (bool);
/// Checks if `key` exists in a JSON object.
function keyExistsJson(string calldata json, string calldata key) external view returns (bool);
/// Parses a string of JSON data at `key` and coerces it to `address`.
function parseJsonAddress(string calldata json, string calldata key) external pure returns (address);
/// Parses a string of JSON data at `key` and coerces it to `address[]`.
function parseJsonAddressArray(string calldata json, string calldata key)
external
pure
returns (address[] memory);
/// Parses a string of JSON data at `key` and coerces it to `bool`.
function parseJsonBool(string calldata json, string calldata key) external pure returns (bool);
/// Parses a string of JSON data at `key` and coerces it to `bool[]`.
function parseJsonBoolArray(string calldata json, string calldata key) external pure returns (bool[] memory);
/// Parses a string of JSON data at `key` and coerces it to `bytes`.
function parseJsonBytes(string calldata json, string calldata key) external pure returns (bytes memory);
/// Parses a string of JSON data at `key` and coerces it to `bytes32`.
function parseJsonBytes32(string calldata json, string calldata key) external pure returns (bytes32);
/// Parses a string of JSON data at `key` and coerces it to `bytes32[]`.
function parseJsonBytes32Array(string calldata json, string calldata key)
external
pure
returns (bytes32[] memory);
/// Parses a string of JSON data at `key` and coerces it to `bytes[]`.
function parseJsonBytesArray(string calldata json, string calldata key) external pure returns (bytes[] memory);
/// Parses a string of JSON data at `key` and coerces it to `int256`.
function parseJsonInt(string calldata json, string calldata key) external pure returns (int256);
/// Parses a string of JSON data at `key` and coerces it to `int256[]`.
function parseJsonIntArray(string calldata json, string calldata key) external pure returns (int256[] memory);
/// Returns an array of all the keys in a JSON object.
function parseJsonKeys(string calldata json, string calldata key) external pure returns (string[] memory keys);
/// Parses a string of JSON data at `key` and coerces it to `string`.
function parseJsonString(string calldata json, string calldata key) external pure returns (string memory);
/// Parses a string of JSON data at `key` and coerces it to `string[]`.
function parseJsonStringArray(string calldata json, string calldata key) external pure returns (string[] memory);
/// Parses a string of JSON data at `key` and coerces it to `uint256`.
function parseJsonUint(string calldata json, string calldata key) external pure returns (uint256);
/// Parses a string of JSON data at `key` and coerces it to `uint256[]`.
function parseJsonUintArray(string calldata json, string calldata key) external pure returns (uint256[] memory);
/// ABI-encodes a JSON object.
function parseJson(string calldata json) external pure returns (bytes memory abiEncodedData);
/// ABI-encodes a JSON object at `key`.
function parseJson(string calldata json, string calldata key) external pure returns (bytes memory abiEncodedData);
/// See `serializeJson`.
function serializeAddress(string calldata objectKey, string calldata valueKey, address value)
external
returns (string memory json);
/// See `serializeJson`.
function serializeAddress(string calldata objectKey, string calldata valueKey, address[] calldata values)
external
returns (string memory json);
/// See `serializeJson`.
function serializeBool(string calldata objectKey, string calldata valueKey, bool value)
external
returns (string memory json);
/// See `serializeJson`.
function serializeBool(string calldata objectKey, string calldata valueKey, bool[] calldata values)
external
returns (string memory json);
/// See `serializeJson`.
function serializeBytes32(string calldata objectKey, string calldata valueKey, bytes32 value)
external
returns (string memory json);
/// See `serializeJson`.
function serializeBytes32(string calldata objectKey, string calldata valueKey, bytes32[] calldata values)
external
returns (string memory json);
/// See `serializeJson`.
function serializeBytes(string calldata objectKey, string calldata valueKey, bytes calldata value)
external
returns (string memory json);
/// See `serializeJson`.
function serializeBytes(string calldata objectKey, string calldata valueKey, bytes[] calldata values)
external
returns (string memory json);
/// See `serializeJson`.
function serializeInt(string calldata objectKey, string calldata valueKey, int256 value)
external
returns (string memory json);
/// See `serializeJson`.
function serializeInt(string calldata objectKey, string calldata valueKey, int256[] calldata values)
external
returns (string memory json);
/// Serializes a key and value to a JSON object stored in-memory that can be later written to a file.
/// Returns the stringified version of the specific JSON file up to that moment.
function serializeJson(string calldata objectKey, string calldata value) external returns (string memory json);
/// See `serializeJson`.
function serializeString(string calldata objectKey, string calldata valueKey, string calldata value)
external
returns (string memory json);
/// See `serializeJson`.
function serializeString(string calldata objectKey, string calldata valueKey, string[] calldata values)
external
returns (string memory json);
/// See `serializeJson`.
function serializeUintToHex(string calldata objectKey, string calldata valueKey, uint256 value)
external
returns (string memory json);
/// See `serializeJson`.
function serializeUint(string calldata objectKey, string calldata valueKey, uint256 value)
external
returns (string memory json);
/// See `serializeJson`.
function serializeUint(string calldata objectKey, string calldata valueKey, uint256[] calldata values)
external
returns (string memory json);
/// Write a serialized JSON object to a file. If the file exists, it will be overwritten.
function writeJson(string calldata json, string calldata path) external;
/// Write a serialized JSON object to an **existing** JSON file, replacing a value with key = <value_key.>
/// This is useful to replace a specific value of a JSON file, without having to parse the entire thing.
function writeJson(string calldata json, string calldata path, string calldata valueKey) external;
// ======== Scripting ========
/// Has the next call (at this call depth only) create transactions that can later be signed and sent onchain.
/// Broadcasting address is determined by checking the following in order:
/// 1. If `--sender` argument was provided, that address is used.
/// 2. If exactly one signer (e.g. private key, hw wallet, keystore) is set when `forge broadcast` is invoked, that signer is used.
/// 3. Otherwise, default foundry sender (1804c8AB1F12E6bbf3894d4083f33e07309d1f38) is used.
function broadcast() external;
/// Has the next call (at this call depth only) create a transaction with the address provided
/// as the sender that can later be signed and sent onchain.
function broadcast(address signer) external;
/// Has the next call (at this call depth only) create a transaction with the private key
/// provided as the sender that can later be signed and sent onchain.
function broadcast(uint256 privateKey) external;
/// Has all subsequent calls (at this call depth only) create transactions that can later be signed and sent onchain.
/// Broadcasting address is determined by checking the following in order:
/// 1. If `--sender` argument was provided, that address is used.
/// 2. If exactly one signer (e.g. private key, hw wallet, keystore) is set when `forge broadcast` is invoked, that signer is used.
/// 3. Otherwise, default foundry sender (1804c8AB1F12E6bbf3894d4083f33e07309d1f38) is used.
function startBroadcast() external;
/// Has all subsequent calls (at this call depth only) create transactions with the address
/// provided that can later be signed and sent onchain.
function startBroadcast(address signer) external;
/// Has all subsequent calls (at this call depth only) create transactions with the private key
/// provided that can later be signed and sent onchain.
function startBroadcast(uint256 privateKey) external;
/// Stops collecting onchain transactions.
function stopBroadcast() external;
// ======== String ========
/// Returns the index of the first occurrence of a `key` in an `input` string.
/// Returns `NOT_FOUND` (i.e. `type(uint256).max`) if the `key` is not found.
/// Returns 0 in case of an empty `key`.
function indexOf(string calldata input, string calldata key) external pure returns (uint256);
/// Parses the given `string` into an `address`.
function parseAddress(string calldata stringifiedValue) external pure returns (address parsedValue);
/// Parses the given `string` into a `bool`.
function parseBool(string calldata stringifiedValue) external pure returns (bool parsedValue);
/// Parses the given `string` into `bytes`.
function parseBytes(string calldata stringifiedValue) external pure returns (bytes memory parsedValue);
/// Parses the given `string` into a `bytes32`.
function parseBytes32(string calldata stringifiedValue) external pure returns (bytes32 parsedValue);
/// Parses the given `string` into a `int256`.
function parseInt(string calldata stringifiedValue) external pure returns (int256 parsedValue);
/// Parses the given `string` into a `uint256`.
function parseUint(string calldata stringifiedValue) external pure returns (uint256 parsedValue);
/// Replaces occurrences of `from` in the given `string` with `to`.
function replace(string calldata input, string calldata from, string calldata to)
external
pure
returns (string memory output);
/// Splits the given `string` into an array of strings divided by the `delimiter`.
function split(string calldata input, string calldata delimiter) external pure returns (string[] memory outputs);
/// Converts the given `string` value to Lowercase.
function toLowercase(string calldata input) external pure returns (string memory output);
/// Converts the given value to a `string`.
function toString(address value) external pure returns (string memory stringifiedValue);
/// Converts the given value to a `string`.
function toString(bytes calldata value) external pure returns (string memory stringifiedValue);
/// Converts the given value to a `string`.
function toString(bytes32 value) external pure returns (string memory stringifiedValue);
/// Converts the given value to a `string`.
function toString(bool value) external pure returns (string memory stringifiedValue);
/// Converts the given value to a `string`.
function toString(uint256 value) external pure returns (string memory stringifiedValue);
/// Converts the given value to a `string`.
function toString(int256 value) external pure returns (string memory stringifiedValue);
/// Converts the given `string` value to Uppercase.
function toUppercase(string calldata input) external pure returns (string memory output);
/// Trims leading and trailing whitespace from the given `string` value.
function trim(string calldata input) external pure returns (string memory output);
// ======== Testing ========
/// Compares two `uint256` values. Expects difference to be less than or equal to `maxDelta`.
/// Formats values with decimals in failure message.
function assertApproxEqAbsDecimal(uint256 left, uint256 right, uint256 maxDelta, uint256 decimals) external pure;
/// Compares two `uint256` values. Expects difference to be less than or equal to `maxDelta`.
/// Formats values with decimals in failure message. Includes error message into revert string on failure.
function assertApproxEqAbsDecimal(
uint256 left,
uint256 right,
uint256 maxDelta,
uint256 decimals,
string calldata error
) external pure;
/// Compares two `int256` values. Expects difference to be less than or equal to `maxDelta`.
/// Formats values with decimals in failure message.
function assertApproxEqAbsDecimal(int256 left, int256 right, uint256 maxDelta, uint256 decimals) external pure;
/// Compares two `int256` values. Expects difference to be less than or equal to `maxDelta`.
/// Formats values with decimals in failure message. Includes error message into revert string on failure.
function assertApproxEqAbsDecimal(
int256 left,
int256 right,
uint256 maxDelta,
uint256 decimals,
string calldata error
) external pure;
/// Compares two `uint256` values. Expects difference to be less than or equal to `maxDelta`.
function assertApproxEqAbs(uint256 left, uint256 right, uint256 maxDelta) external pure;
/// Compares two `uint256` values. Expects difference to be less than or equal to `maxDelta`.
/// Includes error message into revert string on failure.
function assertApproxEqAbs(uint256 left, uint256 right, uint256 maxDelta, string calldata error) external pure;
/// Compares two `int256` values. Expects difference to be less than or equal to `maxDelta`.
function assertApproxEqAbs(int256 left, int256 right, uint256 maxDelta) external pure;
/// Compares two `int256` values. Expects difference to be less than or equal to `maxDelta`.
/// Includes error message into revert string on failure.
function assertApproxEqAbs(int256 left, int256 right, uint256 maxDelta, string calldata error) external pure;
/// Compares two `uint256` values. Expects relative difference in percents to be less than or equal to `maxPercentDelta`.
/// `maxPercentDelta` is an 18 decimal fixed point number, where 1e18 == 100%
/// Formats values with decimals in failure message.
function assertApproxEqRelDecimal(uint256 left, uint256 right, uint256 maxPercentDelta, uint256 decimals)
external
pure;
/// Compares two `uint256` values. Expects relative difference in percents to be less than or equal to `maxPercentDelta`.
/// `maxPercentDelta` is an 18 decimal fixed point number, where 1e18 == 100%
/// Formats values with decimals in failure message. Includes error message into revert string on failure.
function assertApproxEqRelDecimal(
uint256 left,
uint256 right,
uint256 maxPercentDelta,
uint256 decimals,
string calldata error
) external pure;
/// Compares two `int256` values. Expects relative difference in percents to be less than or equal to `maxPercentDelta`.
/// `maxPercentDelta` is an 18 decimal fixed point number, where 1e18 == 100%
/// Formats values with decimals in failure message.
function assertApproxEqRelDecimal(int256 left, int256 right, uint256 maxPercentDelta, uint256 decimals)
external
pure;
/// Compares two `int256` values. Expects relative difference in percents to be less than or equal to `maxPercentDelta`.
/// `maxPercentDelta` is an 18 decimal fixed point number, where 1e18 == 100%
/// Formats values with decimals in failure message. Includes error message into revert string on failure.
function assertApproxEqRelDecimal(
int256 left,
int256 right,
uint256 maxPercentDelta,
uint256 decimals,
string calldata error
) external pure;
/// Compares two `uint256` values. Expects relative difference in percents to be less than or equal to `maxPercentDelta`.
/// `maxPercentDelta` is an 18 decimal fixed point number, where 1e18 == 100%
function assertApproxEqRel(uint256 left, uint256 right, uint256 maxPercentDelta) external pure;
/// Compares two `uint256` values. Expects relative difference in percents to be less than or equal to `maxPercentDelta`.
/// `maxPercentDelta` is an 18 decimal fixed point number, where 1e18 == 100%
/// Includes error message into revert string on failure.
function assertApproxEqRel(uint256 left, uint256 right, uint256 maxPercentDelta, string calldata error)
external
pure;
/// Compares two `int256` values. Expects relative difference in percents to be less than or equal to `maxPercentDelta`.
/// `maxPercentDelta` is an 18 decimal fixed point number, where 1e18 == 100%
function assertApproxEqRel(int256 left, int256 right, uint256 maxPercentDelta) external pure;
/// Compares two `int256` values. Expects relative difference in percents to be less than or equal to `maxPercentDelta`.
/// `maxPercentDelta` is an 18 decimal fixed point number, where 1e18 == 100%
/// Includes error message into revert string on failure.
function assertApproxEqRel(int256 left, int256 right, uint256 maxPercentDelta, string calldata error)
external
pure;
/// Asserts that two `uint256` values are equal, formatting them with decimals in failure message.
function assertEqDecimal(uint256 left, uint256 right, uint256 decimals) external pure;
/// Asserts that two `uint256` values are equal, formatting them with decimals in failure message.
/// Includes error message into revert string on failure.
function assertEqDecimal(uint256 left, uint256 right, uint256 decimals, string calldata error) external pure;
/// Asserts that two `int256` values are equal, formatting them with decimals in failure message.
function assertEqDecimal(int256 left, int256 right, uint256 decimals) external pure;
/// Asserts that two `int256` values are equal, formatting them with decimals in failure message.
/// Includes error message into revert string on failure.
function assertEqDecimal(int256 left, int256 right, uint256 decimals, string calldata error) external pure;
/// Asserts that two `bool` values are equal.
function assertEq(bool left, bool right) external pure;
/// Asserts that two `bool` values are equal and includes error message into revert string on failure.
function assertEq(bool left, bool right, string calldata error) external pure;
/// Asserts that two `string` values are equal.
function assertEq(string calldata left, string calldata right) external pure;