diff --git a/src/SUMMARY.md b/src/SUMMARY.md index 90528b8f0..b4767834c 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -69,7 +69,8 @@ - [Deploying and Verifying](./forge/deploying.md) - [Gas Tracking](./forge/gas-tracking.md) - [Gas Reports](./forge/gas-reports.md) - - [Gas Snapshots](./forge/gas-snapshots.md) + - [Gas Function Snapshots](./forge/gas-function-snapshots.md) + - [Gas Section Snapshots](./forge/gas-section-snapshots.md) # Cast Overview @@ -451,6 +452,8 @@ - [`txGasPrice`](./cheatcodes/tx-gas-price.md) - [`startStateDiffRecording`](./cheatcodes/start-state-diff-recording.md) - [`stopAndReturnStateDiff`](./cheatcodes/stop-and-return-state-diff.md) + - [`snapshotState`](./cheatcodes/state-snapshots.md) + - [`snapshotGas`](./cheatcodes/gas-snapshots.md) - [Assertions](./cheatcodes/assertions.md) - [`expectRevert`](./cheatcodes/expect-revert.md) - [`expectEmit`](./cheatcodes/expect-emit.md) @@ -515,7 +518,6 @@ - [`createWallet`](./cheatcodes/create-wallet.md) - [`copyStorage`](./cheatcodes/copy-storage.md) - [`setArbitraryStorage`](./cheatcodes/set-arbitrary-storage.md) - - [Snapshots](./cheatcodes/snapshots.md) - [RPC](./cheatcodes/rpc.md) - [Files](./cheatcodes/fs.md) - [ZKsync](./zksync-specifics/cheatcodes/README.md) diff --git a/src/cheatcodes/gas-snapshots.md b/src/cheatcodes/gas-snapshots.md new file mode 100644 index 000000000..5f14dcf58 --- /dev/null +++ b/src/cheatcodes/gas-snapshots.md @@ -0,0 +1,175 @@ +## `snapshotGas` cheatcodes + +### Signature + +```solidity +/// Start a snapshot capture of the current gas usage by name. +/// The group name is derived from the contract name. +function startSnapshotGas(string calldata name) external; + +/// Start a snapshot capture of the current gas usage by name in a group. +function startSnapshotGas(string calldata group, string calldata name) external; + +/// Stop the snapshot capture of the current gas by latest snapshot name, capturing the gas used since the start. +function stopSnapshotGas() external returns (uint256 gasUsed); + +/// Stop the snapshot capture of the current gas usage by name, capturing the gas used since the start. +/// The group name is derived from the contract name. +function stopSnapshotGas(string calldata name) external returns (uint256 gasUsed); + +/// Stop the snapshot capture of the current gas usage by name in a group, capturing the gas used since the start. +function stopSnapshotGas(string calldata group, string calldata name) external returns (uint256 gasUsed); + +/// Snapshot capture an arbitrary numerical value by name. +/// The group name is derived from the contract name. +function snapshotValue(string calldata name, uint256 value) external; + +/// Snapshot capture an arbitrary numerical value by name in a group. +function snapshotValue(string calldata group, string calldata name, uint256 value) external; + +/// Snapshot capture the gas usage of the last call by name from the callee perspective. +function snapshotGasLastCall(string calldata name) external returns (uint256 gasUsed); + +/// Snapshot capture the gas usage of the last call by name in a group from the callee perspective. +function snapshotGasLastCall(string calldata group, string calldata name) external returns (uint256 gasUsed); +``` + +### Description + +`snapshotGas*` cheatcodes allow you to capture gas usage in your tests. This can be useful to track how much gas your logic is consuming. You can capture the gas usage of the last call by name, capture an arbitrary numerical value by name, or start and stop a snapshot capture of the current gas usage by name. + +In order to strictly compare gas usage across test runs, set the `FORGE_SNAPSHOT_CHECK` environment variable to `true` before running your tests. This will compare the gas usage of your tests against the last snapshot and fail if the gas usage has changed. By default the snapshots directory will be newly created and its contents removed before each test run to ensure no stale data is present. + +It is intended that the `snapshots` directory created when using the `snapshotGas*` cheatcodes is checked into version control. This allows you to track changes in gas usage over time and compare gas usage during code reviews. + +When running `forge clean` the `snapshots` directory will be deleted. + +### Examples + +Capturing the gas usage of a section of code that calls an external contract: + +```solidity +contract SnapshotGasTest is Test { + uint256 public slot0; + + Flare public flare; + + function setUp() public { + flare = new Flare(); + } + + function testSnapshotGas() public { + vm.startSnapshotGas("externalA"); + flare.run(256); + uint256 gasUsed = vm.stopSnapshotGas(); + } +} +``` + +Capturing the gas usage of multiple sections of code that modify the internal state: + + +```solidity +contract SnapshotGasTest is Test { + uint256 public slot0; + + + /// Writes to `snapshots/SnapshotGasTest.json` group with name `internalA`, `internalB`, and `internalC`. + function testSnapshotGas() public { + vm.startSnapshotGas("internalA"); + slot0 = 1; + vm.stopSnapshotGas(); + + vm.startSnapshotGas("internalB"); + slot0 = 2; + vm.stopSnapshotGas(); + + vm.startSnapshotGas("internalC"); + slot0 = 0; + vm.stopSnapshotGas(); + } +} +``` + +Capturing the gas usage of a section of code that modifies both the internal state and calls an external contract: + +```solidity +contract SnapshotGasTest is Test { + uint256 public slot0; + Flare public flare; + + function setUp() public { + flare = new Flare(); + } + + /// Writes to `snapshots/SnapshotGasTest.json` group with name `combinedA`. + function testSnapshotGas() public { + vm.startSnapshotGas("combinedA"); + flare.run(256); + slot0 = 1; + vm.stopSnapshotGas(); + } +} +``` + +```solidity + +Capturing an arbitrary numerical value (such as the bytecode size of a contract): + +```solidity +contract SnapshotGasTest is Test { + uint256 public slot0; + + /// Writes to `snapshots/SnapshotGasTest.json` group with name `valueA`, `valueB`, and `valueC`. + function testSnapshotValue() public { + uint256 a = 123; + uint256 b = 456; + uint256 c = 789; + + vm.snapshotValue("valueA", a); + vm.snapshotValue("valueB", b); + vm.snapshotValue("valueC", c); + } +} +``` + +Capturing the gas usage of the last call from the callee perspective: + +```solidity +contract SnapshotGasTest is Test { + Flare public flare; + + function setUp() public { + flare = new Flare(); + } + + /// Writes to `snapshots/SnapshotGasTest.json` group with name `lastCallA`. + function testSnapshotGasLastCall() public { + flare.run(1); + vm.snapshotGasLastCall("lastCallA"); + } +} +``` + +For each of the above examples you can also use the `group` variant of the cheatcodes to group the snapshots together in a custom group. + +```solidity +contract SnapshotGasTest is Test { + uint256 public slot0; + + /// Writes to `snapshots/CustomGroup.json` group with name `internalA`, `internalB`, and `internalC`. + function testSnapshotGas() public { + vm.startSnapshotGas("CustomGroup", "internalA"); + slot0 = 1; + vm.stopSnapshotGas(); + + vm.startSnapshotGas("CustomGroup", "internalB"); + slot0 = 2; + vm.stopSnapshotGas(); + + vm.startSnapshotGas("CustomGroup", "internalC"); + slot0 = 0; + vm.stopSnapshotGas(); + } +} +``` diff --git a/src/cheatcodes/snapshots.md b/src/cheatcodes/snapshots.md deleted file mode 100644 index 147121154..000000000 --- a/src/cheatcodes/snapshots.md +++ /dev/null @@ -1,63 +0,0 @@ -## snapshot cheatcodes - -### Signature - -```solidity -// Snapshot the current state of the evm. -// Returns the id of the snapshot that was created. -// To revert a snapshot use `revertTo` -function snapshot() external returns(uint256); -// Revert the state of the evm to a previous snapshot -// Takes the snapshot id to revert to. -// This deletes the snapshot and all snapshots taken after the given snapshot id. -function revertTo(uint256) external returns(bool); -``` - -### Description - -`snapshot` takes a snapshot of the state of the blockchain and returns the identifier of the created snapshot - -`revertTo` reverts the state of the blockchain to the given snapshot. This deletes the given snapshot, as well as any snapshots taken after (e.g.: reverting to id 2 will delete snapshots with ids 2, 3, 4, etc.) - -### Examples - -```solidity -struct Storage { - uint slot0; - uint slot1; -} - -contract SnapshotTest is Test { - Storage store; - uint256 timestamp; - - function setUp() public { - store.slot0 = 10; - store.slot1 = 20; - vm.deal(address(this), 5 ether); // balance = 5 ether - timestamp = block.timestamp; - } - - function testSnapshot() public { - uint256 snapshot = vm.snapshot(); // saves the state - - // let's change the state - store.slot0 = 300; - store.slot1 = 400; - vm.deal(address(this), 500 ether); - vm.warp(12345); // block.timestamp = 12345 - - assertEq(store.slot0, 300); - assertEq(store.slot1, 400); - assertEq(address(this).balance, 500 ether); - assertEq(block.timestamp, 12345); - - vm.revertTo(snapshot); // restores the state - - assertEq(store.slot0, 10, "snapshot revert for slot 0 unsuccessful"); - assertEq(store.slot1, 20, "snapshot revert for slot 1 unsuccessful"); - assertEq(address(this).balance, 5 ether, "snapshot revert for balance unsuccessful"); - assertEq(block.timestamp, timestamp, "snapshot revert for timestamp unsuccessful"); - } -} -``` diff --git a/src/cheatcodes/state-snapshots.md b/src/cheatcodes/state-snapshots.md new file mode 100644 index 000000000..abb615939 --- /dev/null +++ b/src/cheatcodes/state-snapshots.md @@ -0,0 +1,81 @@ +## `snapshotState` cheatcodes + +### Signature + +```solidity +/// Snapshot the current state of the evm. +/// Returns the ID of the snapshot that was created. +/// To revert a snapshot use `revertToState`. +function snapshotState() external returns (uint256 snapshotId); + +/// Revert the state of the EVM to a previous snapshot +/// Takes the snapshot ID to revert to. +/// Returns `true` if the snapshot was successfully reverted. +/// Returns `false` if the snapshot does not exist. +/// **Note:** This does not automatically delete the snapshot. To delete the snapshot use `deleteStateSnapshot`. +function revertToState(uint256 snapshotId) external returns (bool success); + +/// Revert the state of the EVM to a previous snapshot and automatically deletes the snapshots +/// Takes the snapshot ID to revert to. +/// Returns `true` if the snapshot was successfully reverted and deleted. +/// Returns `false` if the snapshot does not exist. +function revertToStateAndDelete(uint256 snapshotId) external returns (bool success); + +/// Removes the snapshot with the given ID created by `snapshot`. +/// Takes the snapshot ID to delete. +/// Returns `true` if the snapshot was successfully deleted. +/// Returns `false` if the snapshot does not exist. +function deleteStateSnapshot(uint256 snapshotId) external returns (bool success); + +/// Removes _all_ snapshots previously created by `snapshot`. +function deleteStateSnapshots() external; +``` + +### Description + +`snapshotState` takes a snapshot of the state of the blockchain and returns the identifier of the created snapshot. + +`revertToState` reverts the state of the blockchain to the given state snapshot. This deletes the given snapshot, as well as any snapshots taken after (e.g.: reverting to id 2 will delete snapshots with ids 2, 3, 4, etc.). + +### Examples + +```solidity +struct Storage { + uint slot0; + uint slot1; +} + +contract SnapshotStateTest is Test { + Storage store; + uint256 timestamp; + + function setUp() public { + store.slot0 = 10; + store.slot1 = 20; + vm.deal(address(this), 5 ether); // balance = 5 ether + timestamp = block.timestamp; + } + + function testSnapshotState() public { + uint256 snapshot = vm.snapshotState(); // saves the state + + // let's change the state + store.slot0 = 300; + store.slot1 = 400; + vm.deal(address(this), 500 ether); + vm.warp(12345); // block.timestamp = 12345 + + assertEq(store.slot0, 300); + assertEq(store.slot1, 400); + assertEq(address(this).balance, 500 ether); + assertEq(block.timestamp, 12345); + + vm.revertToState(snapshot); // restores the state + + assertEq(store.slot0, 10, "snapshot revert for slot 0 unsuccessful"); + assertEq(store.slot1, 20, "snapshot revert for slot 1 unsuccessful"); + assertEq(address(this).balance, 5 ether, "snapshot revert for balance unsuccessful"); + assertEq(block.timestamp, timestamp, "snapshot revert for timestamp unsuccessful"); + } +} +``` diff --git a/src/ci-cd/github-actions.md b/src/ci-cd/github-actions.md new file mode 100644 index 000000000..7aed5a6a2 --- /dev/null +++ b/src/ci-cd/github-actions.md @@ -0,0 +1,104 @@ +# Overview of `foundry-toolchain` + +`foundry-toolchain` can be used to install Foundry for GitHub Actions build processes. + +### Example workflow + +``` +on: [push] + +name: test + +jobs: + check: + name: Foundry project + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + with: + submodules: recursive + + - name: Install Foundry + uses: foundry-rs/foundry-toolchain@v1 + + - name: Run tests + run: forge test -vvv + + - name: Run snapshot + run: forge snapshot +``` + +### Inputs + +| Name | Required | Default | Description | Type | +|---|---|---|---|---| +| cache | No | true | Whether to cache RPC responses or not. | bool | +| version | No | nightly | Version to install, e.g. nightly or 1.8.8. Note: Foundry only has nightly builds for the time being. | string | +| cache-key | No | `${{ github.job }}` | The cache key to use for caching. | string | +| cache-restore-keys | No | `[${{ github.job }}]` | The cache keys to use for restoring the cache. | string[] | + +### RPC Caching + +By default, this action matches Forge's behavior and caches all RPC responses in the `~/.foundry/cache/rpc` directory. This is done to speed up the tests and avoid hitting the rate limit of your RPC provider. + +The logic of the caching is as follows: + +- Always load the latest valid cache, and always create a new one with the updated cache. +- When there are no changes to the fork tests, the cache does not change but the key does, since the key is based on the commit hash. +- When the fork tests are changed, both the cache and the key are updated. + +If you would like to disable the caching (e.g. because you want to implement your own caching mechanism), you can set the `cache` input to `false`, like this: + +``` +- name: Install Foundry + uses: foundry-rs/foundry-toolchain@v1 + with: + cache: false +``` + +### Custom Cache Keys + +You have the ability to define custom cache keys by utilizing the `cache-key` and `cache-restore-keys` inputs. This feature is particularly beneficial when you aim to tailor the cache-sharing strategy across multiple jobs. It is important to ensure that the cache-key is unique for each execution to prevent conflicts and guarantee successful cache saving. + +For instance, if you wish to utilize a shared cache between two distinct jobs, the following configuration can be applied: + +``` +- name: Install Foundry + uses: foundry-rs/foundry-toolchain@v1 + with: + cache-key: custom-seed-test-${{ github.sha }} + cache-restore-keys: |- + custom-seed-test- + custom-seed- +--- +- name: Install Foundry + uses: foundry-rs/foundry-toolchain@v1 + with: + cache-key: custom-seed-coverage-${{ github.sha }} + cache-restore-keys: |- + custom-seed-coverage- + custom-seed- +``` + +#### Deleting Caches + +You can delete caches via the GitHub Actions user interface. Just go to your repo's "Actions" page: + +`https://github.com///actions/caches` + +Then, locate the "Management" section, and click on "Caches". You will see a list of all of your current caches, which you can delete by clicking on the trash icon. + +#### Fuzzing + +Note that if you are fuzzing in your fork tests, the RPC cache strategy above will not work unless you set a [fuzz seed](https://book.getfoundry.sh/reference/config/testing#seed). You might also want to reduce your number of RPC calls by using [Multicall](https://github.com/mds1/multicall). + +### Summaries + +You can add the output of Forge and Cast commands to GitHub step summaries. The summaries support GitHub flavored Markdown. + +For example, to add the output of `forge snapshot` to a summary, you would change the snapshot step to: + +``` +- name: Run snapshot + run: NO_COLOR=1 forge snapshot >> $GITHUB_STEP_SUMMARY +``` \ No newline at end of file diff --git a/src/forge/gas-snapshots.md b/src/forge/gas-function-snapshots.md similarity index 99% rename from src/forge/gas-snapshots.md rename to src/forge/gas-function-snapshots.md index 720a2e69c..ac0ff1c62 100644 --- a/src/forge/gas-snapshots.md +++ b/src/forge/gas-function-snapshots.md @@ -1,4 +1,4 @@ -## Gas Snapshots +## Gas Function Snapshots > 🚨 **Important** > diff --git a/src/forge/gas-section-snapshots.md b/src/forge/gas-section-snapshots.md new file mode 100644 index 000000000..e00584a71 --- /dev/null +++ b/src/forge/gas-section-snapshots.md @@ -0,0 +1,11 @@ +# Gas Section Snapshots + +> 🚨 **Important** +> +> Gas snapshots may not be entirely accurate in the ZKsync context. This is mostly due to the > additional overhead to executing each `CREATE` or `CALL` in its own zkEVM which has additional bootloader gas costs. + +Forge can capture gas snapshots over arbitrary sections inside of your test functions. This can be useful to get a granular measurement of how much gas your logic is consuming as both external calls and internal gas usage are measured. + +Instead of running a command like `forge snapshot` or `forge test --gas-report`, you use the `snapshotGas` [cheatcodes](./cheatcodes.md) in your tests to capture gas usage as follows: + +{{#include ../cheatcodes/gas-snapshots.md}} diff --git a/src/forge/gas-tracking.md b/src/forge/gas-tracking.md index 32f933923..0701659f1 100644 --- a/src/forge/gas-tracking.md +++ b/src/forge/gas-tracking.md @@ -6,16 +6,20 @@ Forge can help you estimate how much gas your contract will consume. -Currently, Forge ships with two different tools for this job, but they may be merged in the future: +Currently, Forge ships with three different tools for this job: - [**Gas reports**](./gas-reports.md): Gas reports give you an overview of how much Forge thinks the individual functions in your contracts will consume in gas. -- [**Gas snapshots**](./gas-snapshots.md): Gas snapshots give you an overview of how much - each test consumes in gas. +- [**Gas function snapshots**](./gas-function-snapshots.md): Gas function snapshots give you an overview of how much + each test function consumes in gas. +- [**Gas section snapshots**](./gas-section-snapshots.md): Gas section snapshots give you the ability to capture gas usage over arbitrary sections inside of test functions. + This also tracks internal gas usage. You can access this by using the `snapshotGas*` cheatcodes inside your tests. -Gas reports and gas snapshots differ in some ways: +Gas reports, gas function snapshots and gas section snapshots differ in some ways: - Gas reports use tracing to figure out gas costs for individual contract calls. This gives more granular insight, at the cost of speed. -- Gas snapshots have more built-in tools, such as diffs and exporting the results to a file. +- Gas function snapshots have more built-in tools, such as diffs and exporting the results to a file. Snapshots are not as granular as gas reports, but they are faster to generate. +- Gas section snapshots provides the most granular way to capture gas usage. Every captured gas snapshot is written to a file in a `snapshots` directory. + By default these snapshots are grouped by the contract name of the test. \ No newline at end of file diff --git a/src/output/cheatcodes/forge-test-cheatcodes-expectrevert b/src/output/cheatcodes/forge-test-cheatcodes-expectrevert index 31f8bfaeb..5eccf4602 100644 --- a/src/output/cheatcodes/forge-test-cheatcodes-expectrevert +++ b/src/output/cheatcodes/forge-test-cheatcodes-expectrevert @@ -5,6 +5,7 @@ $ forge test --zksync --match-test test_IncrementAsOwner|test_IncrementAsNotOwne // ANCHOR: output No files changed, compilation skipped +<<<<<<< HEAD No files changed, compilation skipped Ran 1 test for test/OwnerUpOnly.t.sol:OwnerUpOnlyTest @@ -12,5 +13,12 @@ Ran 1 test for test/OwnerUpOnly.t.sol:OwnerUpOnlyTest Suite result: ok. 1 passed; 0 failed; 0 skipped; finished in 34.49ms (19.06ms CPU time) Ran 1 test suite in 35.33ms (34.49ms CPU time): 1 tests passed, 0 failed, 0 skipped (1 total tests) +======= +Ran 1 test for test/OwnerUpOnly.t.sol:OwnerUpOnlyTest +[PASS] test_IncrementAsOwner() (gas: 29161) +Suite result: ok. 1 passed; 0 failed; 0 skipped; finished in 397.98µs (79.50µs CPU time) + +Ran 1 test suite in 6.09ms (397.98µs CPU time): 1 tests passed, 0 failed, 0 skipped (1 total tests) +>>>>>>> c1fe66deb639f82010d0b91cd528eeea1314eb2d // ANCHOR_END: output // ANCHOR_END: all diff --git a/src/output/fuzz_testing/forge-test-success-fuzz b/src/output/fuzz_testing/forge-test-success-fuzz index 6d1c6609d..98d4fa7ef 100644 --- a/src/output/fuzz_testing/forge-test-success-fuzz +++ b/src/output/fuzz_testing/forge-test-success-fuzz @@ -4,6 +4,7 @@ $ forge test --zksync // ANCHOR_END: command // ANCHOR: output Compiling 1 files with Solc 0.8.10 +<<<<<<< HEAD Solc 0.8.10 finished in 847.95ms Compiler run successful with warnings: Warning (9302): Return value of low-level calls not used. @@ -299,5 +300,15 @@ Ran 1 test for test/Safe.t.sol:SafeTest Suite result: ok. 1 passed; 0 failed; 0 skipped; finished in 3.46s (3.45s CPU time) Ran 1 test suite in 3.46s (3.46s CPU time): 1 tests passed, 0 failed, 0 skipped (1 total tests) +======= +Solc 0.8.10 finished in 1.05s +Compiler run successful! + +Ran 1 test for test/Safe.t.sol:SafeTest +[PASS] testFuzz_Withdraw(uint96) (runs: 257, μ: 19213, ~: 19631) +Suite result: ok. 1 passed; 0 failed; 0 skipped; finished in 4.96ms (4.55ms CPU time) + +Ran 1 test suite in 6.12ms (4.96ms CPU time): 1 tests passed, 0 failed, 0 skipped (1 total tests) +>>>>>>> c1fe66deb639f82010d0b91cd528eeea1314eb2d // ANCHOR_END: output // ANCHOR_END: all diff --git a/src/output/hello_foundry/forge-test b/src/output/hello_foundry/forge-test index bc5957dd1..936cfd26f 100644 --- a/src/output/hello_foundry/forge-test +++ b/src/output/hello_foundry/forge-test @@ -10,10 +10,10 @@ Compiler run successful! No files changed, compilation skipped Ran 2 tests for test/Counter.t.sol:CounterTest -[PASS] testFuzz_SetNumber(uint256) (runs: 256, μ: 720004, ~: 679696) -[PASS] test_Increment() (gas: 526627) -Suite result: ok. 2 passed; 0 failed; 0 skipped; finished in 3.29s (3.28s CPU time) +[PASS] testFuzz_SetNumber(uint256) (runs: 256, μ: 31288, ~: 31288) +[PASS] test_Increment() (gas: 31303) +Suite result: ok. 2 passed; 0 failed; 0 skipped; finished in 8.75ms (8.36ms CPU time) -Ran 1 test suite in 3.29s (3.29s CPU time): 2 tests passed, 0 failed, 0 skipped (2 total tests) +Ran 1 test suite in 9.79ms (8.75ms CPU time): 2 tests passed, 0 failed, 0 skipped (2 total tests) // ANCHOR_END: output // ANCHOR_END: all diff --git a/src/reference/cast/cast-etherscan-source.md b/src/reference/cast/cast-etherscan-source.md index d59649172..39c5547f2 100644 --- a/src/reference/cast/cast-etherscan-source.md +++ b/src/reference/cast/cast-etherscan-source.md @@ -22,6 +22,10 @@ The destination (*to*) can be an ENS name or an address.     The output directory to expand the source tree into.     If not provided, the source will be outputted to stdout. +`-f` +`--flatten` +    Whether to flatten the source code. + {{#include ../common/etherscan-options.md}} {{#include common-options.md}} diff --git a/src/reference/cast/cast-logs.md b/src/reference/cast/cast-logs.md index b12a0073f..8dd71210d 100644 --- a/src/reference/cast/cast-logs.md +++ b/src/reference/cast/cast-logs.md @@ -44,11 +44,11 @@ If using a signature, remaining arguments must be in their ordinary form. If usi 1. Get logs using a signature: ```sh - cast logs --from-block 15537393 --to-block latest 'Transfer (address indexed from, address indexed to, uint256 value)' 0x2e8ABfE042886E4938201101A63730D04F160A82 + cast logs --from-block 15537393 --to-block latest 'Transfer (address indexed from, address indexed to, uint256 value)' --address 0x2e8ABfE042886E4938201101A63730D04F160A82 ``` 2. Get logs using a topic: ```sh - cast logs --from-block 15537393 --to-block latest 0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef 0x0000000000000000000000002e8abfe042886e4938201101a63730d04f160a82 + cast logs --from-block 15537393 --to-block latest 0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef --address 0x0000000000000000000000002e8abfe042886e4938201101a63730d04f160a82 ``` ### SEE ALSO diff --git a/src/reference/cli/SUMMARY.md b/src/reference/cli/SUMMARY.md index 1b95a4a5a..b072f0de3 100644 --- a/src/reference/cli/SUMMARY.md +++ b/src/reference/cli/SUMMARY.md @@ -145,4 +145,3 @@ - [`cast wallet list`](./cast/wallet/list.md) - [`cast wallet private-key`](./cast/wallet/private-key.md) - [`cast wallet decrypt-keystore`](./cast/wallet/decrypt-keystore.md) - diff --git a/src/reference/cli/anvil.md b/src/reference/cli/anvil.md index 86562bbc5..6a19d29bc 100644 --- a/src/reference/cli/anvil.md +++ b/src/reference/cli/anvil.md @@ -268,6 +268,11 @@ Environment config: --disable-code-size-limit Disable EIP-170: Contract code size limit + --disable-min-priority-fee + Disable the enforcement of a minimum suggested priority fee + + [aliases: no-priority-fee] + --gas-limit The block gas limit @@ -278,7 +283,7 @@ EVM options: --alphanet Enable Alphanet features - [aliases: alphanet] + [aliases: odyssey] --auto-impersonate Enable autoImpersonate on startup diff --git a/src/reference/cli/cast/storage.md b/src/reference/cli/cast/storage.md index d17ed277b..fc6bdf617 100644 --- a/src/reference/cli/cast/storage.md +++ b/src/reference/cli/cast/storage.md @@ -71,6 +71,13 @@ Build options: --no-cache Disable the cache + --eof + Use EOF-enabled solc binary. Enables via-ir and sets EVM version to + Prague. Requires Docker to be installed. + + Note that this is a temporary solution until the EOF support is merged + into the main solc release. + --skip ... Skip building files whose names contain the given filter. @@ -121,8 +128,10 @@ Compiler options: --evm-version The target EVM version - --optimize + --optimize [] Activate the Solidity optimizer + + [possible values: true, false] --optimizer-runs The number of optimizer runs diff --git a/src/reference/cli/chisel.md b/src/reference/cli/chisel.md index 204d837ed..e8b5c8b10 100644 --- a/src/reference/cli/chisel.md +++ b/src/reference/cli/chisel.md @@ -14,6 +14,7 @@ Commands: load Load a cached session view View the source of a cached session clear-cache Clear all cached chisel sessions from the cache directory + eval Simple evaluation of a command without entering the REPL help Print this message or the help of the given subcommand(s) Options: @@ -45,6 +46,13 @@ Build options: --no-cache Disable the cache + --eof + Use EOF-enabled solc binary. Enables via-ir and sets EVM version to + Prague. Requires Docker to be installed. + + Note that this is a temporary solution until the EOF support is merged + into the main solc release. + --skip ... Skip building files whose names contain the given filter. @@ -95,8 +103,10 @@ Compiler options: --evm-version The target EVM version - --optimize + --optimize [] Activate the Solidity optimizer + + [possible values: true, false] --optimizer-runs The number of runs specifies roughly how often each opcode of the diff --git a/src/reference/cli/chisel/eval.md b/src/reference/cli/chisel/eval.md new file mode 100644 index 000000000..e05ef23f6 --- /dev/null +++ b/src/reference/cli/chisel/eval.md @@ -0,0 +1,17 @@ +# chisel eval + +Simple evaluation of a command without entering the REPL + +```bash +$ chisel eval --help +``` + +```txt +Usage: chisel eval + +Arguments: + The command to be evaluated + +Options: + -h, --help Print help +``` \ No newline at end of file diff --git a/src/reference/cli/forge.md b/src/reference/cli/forge.md index 20cf657c3..f47e8f128 100644 --- a/src/reference/cli/forge.md +++ b/src/reference/cli/forge.md @@ -46,7 +46,7 @@ Commands: script Run a smart contract as a script, building transactions that can be sent onchain selectors Function selector utilities [aliases: se] - snapshot Create a snapshot of each test's gas usage [aliases: s] + snapshot Create a gas snapshot of each test's gas usage [aliases: s] soldeer Soldeer dependency manager test Run the project's tests [aliases: t] tree Display a tree visualization of the project's diff --git a/src/reference/cli/forge/bind-json.md b/src/reference/cli/forge/bind-json.md index 7bd670477..54b47169d 100644 --- a/src/reference/cli/forge/bind-json.md +++ b/src/reference/cli/forge/bind-json.md @@ -25,6 +25,13 @@ Build options: --no-cache Disable the cache + --eof + Use EOF-enabled solc binary. Enables via-ir and sets EVM version to + Prague. Requires Docker to be installed. + + Note that this is a temporary solution until the EOF support is merged + into the main solc release. + --skip ... Skip building files whose names contain the given filter. @@ -75,8 +82,10 @@ Compiler options: --evm-version The target EVM version - --optimize + --optimize [] Activate the Solidity optimizer + + [possible values: true, false] --optimizer-runs The number of optimizer runs diff --git a/src/reference/cli/forge/bind.md b/src/reference/cli/forge/bind.md index 9e269bc01..8a87b92f7 100644 --- a/src/reference/cli/forge/bind.md +++ b/src/reference/cli/forge/bind.md @@ -81,6 +81,13 @@ Build options: --no-cache Disable the cache + --eof + Use EOF-enabled solc binary. Enables via-ir and sets EVM version to + Prague. Requires Docker to be installed. + + Note that this is a temporary solution until the EOF support is merged + into the main solc release. + --skip ... Skip building files whose names contain the given filter. @@ -131,8 +138,10 @@ Compiler options: --evm-version The target EVM version - --optimize + --optimize [] Activate the Solidity optimizer + + [possible values: true, false] --optimizer-runs The number of optimizer runs diff --git a/src/reference/cli/forge/build.md b/src/reference/cli/forge/build.md index 053e93cd7..f9cc4f7fa 100644 --- a/src/reference/cli/forge/build.md +++ b/src/reference/cli/forge/build.md @@ -23,6 +23,13 @@ Build options: --no-cache Disable the cache + --eof + Use EOF-enabled solc binary. Enables via-ir and sets EVM version to + Prague. Requires Docker to be installed. + + Note that this is a temporary solution until the EOF support is merged + into the main solc release. + --skip ... Skip building files whose names contain the given filter. @@ -80,8 +87,10 @@ Compiler options: --evm-version The target EVM version - --optimize + --optimize [] Activate the Solidity optimizer + + [possible values: true, false] --optimizer-runs The number of optimizer runs diff --git a/src/reference/cli/forge/config.md b/src/reference/cli/forge/config.md index 45cd7dbad..9bfa81f91 100644 --- a/src/reference/cli/forge/config.md +++ b/src/reference/cli/forge/config.md @@ -32,6 +32,13 @@ Build options: --no-cache Disable the cache + --eof + Use EOF-enabled solc binary. Enables via-ir and sets EVM version to + Prague. Requires Docker to be installed. + + Note that this is a temporary solution until the EOF support is merged + into the main solc release. + --skip ... Skip building files whose names contain the given filter. @@ -89,8 +96,10 @@ Compiler options: --evm-version The target EVM version - --optimize + --optimize [] Activate the Solidity optimizer + + [possible values: true, false] --optimizer-runs The number of optimizer runs diff --git a/src/reference/cli/forge/coverage.md b/src/reference/cli/forge/coverage.md index 88081f190..50c39e8c3 100644 --- a/src/reference/cli/forge/coverage.md +++ b/src/reference/cli/forge/coverage.md @@ -37,15 +37,8 @@ Options: Print help (see a summary with '-h') Test options: - --debug - Run a test in the debugger. - - The argument passed to this flag is the name of the test function you - want to run, and it works the same as --match-test. - - If more than one test matches your specified criteria, you must add - additional filters until only one test is found (see --match-contract - and --match-path). + --debug [] + Run a single test in the debugger. The matching test will be opened in the debugger regardless of the outcome of the test. @@ -53,23 +46,29 @@ Test options: If the matching test is a fuzz test, then it will open the debugger on the first failure case. If the fuzz test does not fail, it will open the debugger on the last fuzz case. + + --flamegraph + Generate a flamegraph for a single test. Implies `--decode-internal`. - For more fine-grained control of which fuzz case is run, see forge - run. + A flame graph is used to visualize which functions or operations + within the smart contract are consuming the most gas overall in a + sorted manner. - --decode-internal [] - Whether to identify internal functions in traces. + --flamechart + Generate a flamechart for a single test. Implies `--decode-internal`. - If no argument is passed to this flag, it will trace internal - functions scope and decode stack parameters, but parameters stored in - memory (such as bytes or arrays) will not be decoded. + A flame chart shows the gas usage over time, illustrating when each + function is called (execution order) and how much gas it consumes at + each point in the timeline. + + --decode-internal [] + Identify internal functions in traces. - To decode memory parameters, you should pass an argument with a test - function name, similarly to --debug and --match-test. + This will trace internal functions and decode stack parameters. - If more than one test matches your specified criteria, you must add - additional filters until only one test is found (see --match-contract - and --match-path). + Parameters stored in memory (such as bytes or arrays) are currently + decoded only when a single function is matched, similarly to + `--debug`, for performance reasons. --gas-report Print a gas report @@ -307,6 +306,13 @@ Build options: --no-cache Disable the cache + --eof + Use EOF-enabled solc binary. Enables via-ir and sets EVM version to + Prague. Requires Docker to be installed. + + Note that this is a temporary solution until the EOF support is merged + into the main solc release. + --skip ... Skip building files whose names contain the given filter. @@ -357,8 +363,10 @@ Compiler options: --evm-version The target EVM version - --optimize + --optimize [] Activate the Solidity optimizer + + [possible values: true, false] --optimizer-runs The number of optimizer runs @@ -508,4 +516,4 @@ Watch options: When using --poll mode, you'll want a larger duration, or risk overloading disk I/O. -``` \ No newline at end of file +``` diff --git a/src/reference/cli/forge/create.md b/src/reference/cli/forge/create.md index 1decc134a..9dd1a1e71 100644 --- a/src/reference/cli/forge/create.md +++ b/src/reference/cli/forge/create.md @@ -48,6 +48,13 @@ Build options: --no-cache Disable the cache + --eof + Use EOF-enabled solc binary. Enables via-ir and sets EVM version to + Prague. Requires Docker to be installed. + + Note that this is a temporary solution until the EOF support is merged + into the main solc release. + --skip ... Skip building files whose names contain the given filter. @@ -98,8 +105,10 @@ Compiler options: --evm-version The target EVM version - --optimize + --optimize [] Activate the Solidity optimizer + + [possible values: true, false] --optimizer-runs The number of optimizer runs @@ -334,7 +343,7 @@ Wallet options - raw: [default: 5] --delay - Optional delay to apply inbetween verification attempts, in seconds + Optional delay to apply in between verification attempts, in seconds [default: 5] diff --git a/src/reference/cli/forge/debug.md b/src/reference/cli/forge/debug.md index 8cf82e846..64a9337ec 100644 --- a/src/reference/cli/forge/debug.md +++ b/src/reference/cli/forge/debug.md @@ -45,6 +45,13 @@ Build options: --no-cache Disable the cache + --eof + Use EOF-enabled solc binary. Enables via-ir and sets EVM version to + Prague. Requires Docker to be installed. + + Note that this is a temporary solution until the EOF support is merged + into the main solc release. + --skip ... Skip building files whose names contain the given filter. @@ -95,8 +102,10 @@ Compiler options: --evm-version The target EVM version - --optimize + --optimize [] Activate the Solidity optimizer + + [possible values: true, false] --optimizer-runs The number of optimizer runs diff --git a/src/reference/cli/forge/eip712.md b/src/reference/cli/forge/eip712.md index 010da93e9..e05812ac1 100644 --- a/src/reference/cli/forge/eip712.md +++ b/src/reference/cli/forge/eip712.md @@ -25,6 +25,13 @@ Build options: --no-cache Disable the cache + --eof + Use EOF-enabled solc binary. Enables via-ir and sets EVM version to + Prague. Requires Docker to be installed. + + Note that this is a temporary solution until the EOF support is merged + into the main solc release. + --skip ... Skip building files whose names contain the given filter. @@ -75,8 +82,10 @@ Compiler options: --evm-version The target EVM version - --optimize + --optimize [] Activate the Solidity optimizer + + [possible values: true, false] --optimizer-runs The number of optimizer runs diff --git a/src/reference/cli/forge/inspect.md b/src/reference/cli/forge/inspect.md index 6a8c2edfb..0cf196347 100644 --- a/src/reference/cli/forge/inspect.md +++ b/src/reference/cli/forge/inspect.md @@ -18,9 +18,9 @@ Arguments: The contract artifact field to inspect [possible values: abi, bytecode, deployedBytecode, assembly, - assemblyOptimized, methodIdentifiers, gasEstimates, storageLayout, - devdoc, ir, irOptimized, metadata, userdoc, ewasm, errors, events, - eof, eof-init] + legacyAssembly, assemblyOptimized, methodIdentifiers, gasEstimates, + storageLayout, devdoc, ir, irOptimized, metadata, userdoc, ewasm, + errors, events, eof, eof-init] Options: --pretty @@ -37,6 +37,13 @@ Build options: --no-cache Disable the cache + --eof + Use EOF-enabled solc binary. Enables via-ir and sets EVM version to + Prague. Requires Docker to be installed. + + Note that this is a temporary solution until the EOF support is merged + into the main solc release. + --skip ... Skip building files whose names contain the given filter. @@ -87,8 +94,10 @@ Compiler options: --evm-version The target EVM version - --optimize + --optimize [] Activate the Solidity optimizer + + [possible values: true, false] --optimizer-runs The number of optimizer runs diff --git a/src/reference/cli/forge/script.md b/src/reference/cli/forge/script.md index 9e40b922a..b7e430fdb 100644 --- a/src/reference/cli/forge/script.md +++ b/src/reference/cli/forge/script.md @@ -121,6 +121,13 @@ Build options: --no-cache Disable the cache + --eof + Use EOF-enabled solc binary. Enables via-ir and sets EVM version to + Prague. Requires Docker to be installed. + + Note that this is a temporary solution until the EOF support is merged + into the main solc release. + --skip ... Skip building files whose names contain the given filter. @@ -171,8 +178,10 @@ Compiler options: --evm-version The target EVM version - --optimize + --optimize [] Activate the Solidity optimizer + + [possible values: true, false] --optimizer-runs The number of optimizer runs @@ -332,7 +341,7 @@ Wallet options - raw: Wallet options - keystore: --keystore - Use the keystore in the given folder or file + Use the keystore by its filename in the given folder [env: ETH_KEYSTORE=] [aliases: keystores] @@ -505,7 +514,7 @@ Executor environment config: [default: 5] --delay - Optional delay to apply inbetween verification attempts, in seconds + Optional delay to apply in between verification attempts, in seconds [default: 5] diff --git a/src/reference/cli/forge/selectors/collision.md b/src/reference/cli/forge/selectors/collision.md index 107f245ec..56b1763b6 100644 --- a/src/reference/cli/forge/selectors/collision.md +++ b/src/reference/cli/forge/selectors/collision.md @@ -30,6 +30,13 @@ Build options: --no-cache Disable the cache + --eof + Use EOF-enabled solc binary. Enables via-ir and sets EVM version to + Prague. Requires Docker to be installed. + + Note that this is a temporary solution until the EOF support is merged + into the main solc release. + --skip ... Skip building files whose names contain the given filter. @@ -80,8 +87,10 @@ Compiler options: --evm-version The target EVM version - --optimize + --optimize [] Activate the Solidity optimizer + + [possible values: true, false] --optimizer-runs The number of optimizer runs diff --git a/src/reference/cli/forge/snapshot.md b/src/reference/cli/forge/snapshot.md index 0be24b87f..45e502ace 100644 --- a/src/reference/cli/forge/snapshot.md +++ b/src/reference/cli/forge/snapshot.md @@ -1,6 +1,6 @@ # forge snapshot -Create a snapshot of each test's gas usage +Create a gas snapshot of each test's gas usage ```bash $ forge snapshot --help @@ -11,20 +11,20 @@ Usage: forge snapshot [OPTIONS] Options: --diff [] - Output a diff against a pre-existing snapshot. + Output a diff against a pre-existing gas snapshot. By default, the comparison is done with .gas-snapshot. --check [] - Compare against a pre-existing snapshot, exiting with code 1 if they - do not match. + Compare against a pre-existing gas snapshot, exiting with code 1 if + they do not match. - Outputs a diff if the snapshots do not match. + Outputs a diff if the gas snapshots do not match. By default, the comparison is done with .gas-snapshot. --snap - Output file for the snapshot + Output file for the gas snapshot [default: .gas-snapshot] @@ -35,15 +35,8 @@ Options: Print help (see a summary with '-h') Test options: - --debug - Run a test in the debugger. - - The argument passed to this flag is the name of the test function you - want to run, and it works the same as --match-test. - - If more than one test matches your specified criteria, you must add - additional filters until only one test is found (see --match-contract - and --match-path). + --debug [] + Run a single test in the debugger. The matching test will be opened in the debugger regardless of the outcome of the test. @@ -51,23 +44,29 @@ Test options: If the matching test is a fuzz test, then it will open the debugger on the first failure case. If the fuzz test does not fail, it will open the debugger on the last fuzz case. + + --flamegraph + Generate a flamegraph for a single test. Implies `--decode-internal`. - For more fine-grained control of which fuzz case is run, see forge - run. + A flame graph is used to visualize which functions or operations + within the smart contract are consuming the most gas overall in a + sorted manner. - --decode-internal [] - Whether to identify internal functions in traces. + --flamechart + Generate a flamechart for a single test. Implies `--decode-internal`. - If no argument is passed to this flag, it will trace internal - functions scope and decode stack parameters, but parameters stored in - memory (such as bytes or arrays) will not be decoded. + A flame chart shows the gas usage over time, illustrating when each + function is called (execution order) and how much gas it consumes at + each point in the timeline. + + --decode-internal [] + Identify internal functions in traces. - To decode memory parameters, you should pass an argument with a test - function name, similarly to --debug and --match-test. + This will trace internal functions and decode stack parameters. - If more than one test matches your specified criteria, you must add - additional filters until only one test is found (see --match-contract - and --match-path). + Parameters stored in memory (such as bytes or arrays) are currently + decoded only when a single function is matched, similarly to + `--debug`, for performance reasons. --gas-report Print a gas report @@ -305,6 +304,13 @@ Build options: --no-cache Disable the cache + --eof + Use EOF-enabled solc binary. Enables via-ir and sets EVM version to + Prague. Requires Docker to be installed. + + Note that this is a temporary solution until the EOF support is merged + into the main solc release. + --skip ... Skip building files whose names contain the given filter. @@ -355,8 +361,10 @@ Compiler options: --evm-version The target EVM version - --optimize + --optimize [] Activate the Solidity optimizer + + [possible values: true, false] --optimizer-runs The number of optimizer runs @@ -518,4 +526,4 @@ Watch options: --max Only include tests that used less gas that the given amount -``` \ No newline at end of file +``` diff --git a/src/reference/cli/forge/soldeer.md b/src/reference/cli/forge/soldeer.md index 42a48bef7..d2b4aef8c 100644 --- a/src/reference/cli/forge/soldeer.md +++ b/src/reference/cli/forge/soldeer.md @@ -17,47 +17,15 @@ Usage: forge soldeer install [DEPENDENCY]~[VERSION] forge soldeer version Commands: - install Install a dependency from soldeer repository or from a - custom url that points to a zip file or from git using a - git link. - IMPORTANT!! The `~` when specifying the dependency is - very important to differentiate between the name and - the version that needs to be installed. - Example from remote repository: soldeer install - @openzeppelin-contracts~2.3.0 - Example custom url: soldeer install - @openzeppelin-contracts~2.3.0 - https://github.com/OpenZeppelin/openzeppelin-contracts/archive/refs/tags/v5.0.2.zip - Example git: soldeer install - @openzeppelin-contracts~2.3.0 - git@github.com:OpenZeppelin/openzeppelin-contracts.git - Example git with specified commit: soldeer install - @openzeppelin-contracts~2.3.0 - git@github.com:OpenZeppelin/openzeppelin-contracts.git - --rev 05f218fb6617932e56bf5388c3b389c3028a7b73 - update Update dependencies by reading the config file. - login Login into the central repository to push the - dependencies. - push Push a dependency to the repository. The - PATH_TO_DEPENDENCY is optional and if not provided, the - current directory will be used. - Example: If the directory is /home/soldeer/my_project and - you do not specify the PATH_TO_DEPENDENCY, - the files inside the /home/soldeer/my_project will be - pushed to the repository. - If you specify the PATH_TO_DEPENDENCY, the files inside - the specified directory will be pushed to the repository. - If you want to ignore certain files, you can create a - .soldeerignore file in the root of the project and add - the files you want to ignore. - The .soldeerignore works like .gitignore. - For dry-run please use the --dry-run argument set to - true, `soldeer push ... --dry-run true`. This will create - a zip file that you can inspect and see what it will be - pushed to the central repository. - version-dry-run - help Print this message or the help of the given subcommand(s) + init Convert a Foundry project to use Soldeer + install Install a dependency + update Update dependencies by reading the config file + login Log into the central repository to push packages + push Push a dependency to the repository + uninstall Uninstall a dependency + version Display the version of Soldeer + help Print this message or the help of the given subcommand(s) Options: -h, --help Print help -``` \ No newline at end of file +``` diff --git a/src/reference/cli/forge/soldeer/init.md b/src/reference/cli/forge/soldeer/init.md index c66fd3e95..418a9b201 100644 --- a/src/reference/cli/forge/soldeer/init.md +++ b/src/reference/cli/forge/soldeer/init.md @@ -1,6 +1,6 @@ # forge soldeer init -Initialize a new Soldeer project for use with Foundry +Convert a Foundry project to use Soldeer ```bash $ forge soldeer init --help diff --git a/src/reference/cli/forge/soldeer/install.md b/src/reference/cli/forge/soldeer/install.md index 4fdea997d..c287dbd3d 100644 --- a/src/reference/cli/forge/soldeer/install.md +++ b/src/reference/cli/forge/soldeer/install.md @@ -1,21 +1,53 @@ # forge soldeer install -Install a dependency from soldeer repository or from a custom url that points to +Install a dependency ```bash $ forge soldeer install --help ``` ```txt -Usage: soldeer install ~ [URL] +Usage: forge soldeer install [OPTIONS] [DEPENDENCY~VERSION] [URL] Arguments: - [DEPENDENCY] - [REMOTE_URL] + [DEPENDENCY~VERSION] + The dependency name and version, separated by a tilde. The version is + always required. + + If not present, this command will install all dependencies which are + missing. + + [URL] + The URL to the dependency zip file. + + If not present, the package will be installed from the Soldeer + repository. + + Example: https://my-domain/dep.zip Options: - --rev - -h, --help Print help + --rev + A Git commit hash + + --tag + A Git tag + + --branch + A Git branch + + -g, --regenerate-remappings + If set, this command will delete the existing remappings and re-create + them + + -d, --recursive-deps + If set, this command will install dependencies recursively (via git + submodules or via soldeer) + + --clean + Perform a clean install by re-installing all dependencies + + -h, --help + Print help (see a summary with '-h') For more information, read the README.md ``` \ No newline at end of file diff --git a/src/reference/cli/forge/soldeer/login.md b/src/reference/cli/forge/soldeer/login.md index 4d15d311f..88573b2a2 100644 --- a/src/reference/cli/forge/soldeer/login.md +++ b/src/reference/cli/forge/soldeer/login.md @@ -1,13 +1,13 @@ # forge soldeer login -Login into the central repository to push the dependencies. +Log into the central repository to push packages ```bash $ forge soldeer login --help ``` ```txt -Usage: soldeer login +Usage: forge soldeer login Options: -h, --help Print help diff --git a/src/reference/cli/forge/soldeer/push.md b/src/reference/cli/forge/soldeer/push.md index 00054b21e..a3f25e106 100644 --- a/src/reference/cli/forge/soldeer/push.md +++ b/src/reference/cli/forge/soldeer/push.md @@ -1,22 +1,38 @@ # forge soldeer push -Push a dependency to the repository. The PATH_TO_DEPENDENCY is optional and if +Push a Dependency to the Repository ```bash $ forge soldeer push --help ``` ```txt -Usage: soldeer push ~ [PATH_TO_DEPENDENCY] +Usage: forge soldeer push [OPTIONS] ~ [PATH] Arguments: - - [PATH] + ~ + The dependency name and version, separated by a tilde. + + This should always be used when you want to push a dependency to the + central repository: ``. + + [PATH] + Use this if the package you want to push is not in the current + directory. + + Example: `soldeer push mypkg~0.1.0 /path/to/dep`. Options: - -d, --dry-run [possible values: true, false] - --skip-warnings [possible values: true, false] - -h, --help Print help + -d, --dry-run + If set, does not publish the package but generates a zip file that can + be inspected + + --skip-warnings + Use this if you want to skip the warnings that can be triggered when + trying to push dotfiles like .env + + -h, --help + Print help (see a summary with '-h') For more information, read the README.md ``` \ No newline at end of file diff --git a/src/reference/cli/forge/soldeer/update.md b/src/reference/cli/forge/soldeer/update.md index 18c4ec74a..f07e1bb27 100644 --- a/src/reference/cli/forge/soldeer/update.md +++ b/src/reference/cli/forge/soldeer/update.md @@ -1,16 +1,21 @@ # forge soldeer update -Update dependencies by reading the config file. +Update dependencies by reading the config file ```bash $ forge soldeer update --help ``` ```txt -Usage: soldeer update +Usage: forge soldeer update [OPTIONS] Options: - -h, --help Print help + -g, --regenerate-remappings If set, this command will delete the existing + remappings and re-create them + -d, --recursive-deps If set, this command will install the + dependencies recursively (via submodules or via + soldeer) + -h, --help Print help For more information, read the README.md ``` \ No newline at end of file diff --git a/src/reference/cli/forge/test.md b/src/reference/cli/forge/test.md index 208716d05..26dc4f501 100644 --- a/src/reference/cli/forge/test.md +++ b/src/reference/cli/forge/test.md @@ -14,15 +14,8 @@ Options: Print help (see a summary with '-h') Test options: - --debug - Run a test in the debugger. - - The argument passed to this flag is the name of the test function you - want to run, and it works the same as --match-test. - - If more than one test matches your specified criteria, you must add - additional filters until only one test is found (see --match-contract - and --match-path). + --debug [] + Run a single test in the debugger. The matching test will be opened in the debugger regardless of the outcome of the test. @@ -30,23 +23,29 @@ Test options: If the matching test is a fuzz test, then it will open the debugger on the first failure case. If the fuzz test does not fail, it will open the debugger on the last fuzz case. + + --flamegraph + Generate a flamegraph for a single test. Implies `--decode-internal`. - For more fine-grained control of which fuzz case is run, see forge - run. + A flame graph is used to visualize which functions or operations + within the smart contract are consuming the most gas overall in a + sorted manner. - --decode-internal [] - Whether to identify internal functions in traces. + --flamechart + Generate a flamechart for a single test. Implies `--decode-internal`. - If no argument is passed to this flag, it will trace internal - functions scope and decode stack parameters, but parameters stored in - memory (such as bytes or arrays) will not be decoded. + A flame chart shows the gas usage over time, illustrating when each + function is called (execution order) and how much gas it consumes at + each point in the timeline. + + --decode-internal [] + Identify internal functions in traces. - To decode memory parameters, you should pass an argument with a test - function name, similarly to --debug and --match-test. + This will trace internal functions and decode stack parameters. - If more than one test matches your specified criteria, you must add - additional filters until only one test is found (see --match-contract - and --match-path). + Parameters stored in memory (such as bytes or arrays) are currently + decoded only when a single function is matched, similarly to + `--debug`, for performance reasons. --gas-report Print a gas report @@ -284,6 +283,13 @@ Build options: --no-cache Disable the cache + --eof + Use EOF-enabled solc binary. Enables via-ir and sets EVM version to + Prague. Requires Docker to be installed. + + Note that this is a temporary solution until the EOF support is merged + into the main solc release. + --skip ... Skip building files whose names contain the given filter. @@ -334,8 +340,10 @@ Compiler options: --evm-version The target EVM version - --optimize + --optimize [] Activate the Solidity optimizer + + [possible values: true, false] --optimizer-runs The number of optimizer runs @@ -485,4 +493,4 @@ Watch options: When using --poll mode, you'll want a larger duration, or risk overloading disk I/O. -``` \ No newline at end of file +``` diff --git a/src/reference/cli/forge/verify-check.md b/src/reference/cli/forge/verify-check.md index 79cf3c0d9..5cbd84433 100644 --- a/src/reference/cli/forge/verify-check.md +++ b/src/reference/cli/forge/verify-check.md @@ -24,7 +24,7 @@ Options: [default: 5] --delay - Optional delay to apply inbetween verification attempts, in seconds + Optional delay to apply in between verification attempts, in seconds [default: 5] diff --git a/src/reference/cli/forge/verify-contract.md b/src/reference/cli/forge/verify-contract.md index 62e24f779..14fa82a85 100644 --- a/src/reference/cli/forge/verify-contract.md +++ b/src/reference/cli/forge/verify-contract.md @@ -113,7 +113,7 @@ Options: [default: 5] --delay - Optional delay to apply inbetween verification attempts, in seconds + Optional delay to apply in between verification attempts, in seconds [default: 5] diff --git a/src/static/config.default.toml b/src/static/config.default.toml index 1bcf419fc..fd6021156 100644 --- a/src/static/config.default.toml +++ b/src/static/config.default.toml @@ -115,17 +115,19 @@ rpc_endpoints = { optimism = "https://optimism.alchemyapi.io/v2/...", mainnet = # Etherscan API key #etherscan_api_key = None # Only run test functions matching the specified regex pattern -#test_pattern = None +#match_test = None # Only run test functions that do not match the specified regex pattern -#test_pattern_inverse = None +#no_match_test = None # Only run tests in contracts matching the specified regex pattern -#contract_pattern = None +#match_contract = None # Only run tests in contracts that do not match the specified regex pattern -#contract_pattern_inverse = None +#no_match_contract = None # Only run tests in source files matching the specified glob pattern -#path_pattern = None +#match_path = None # Only run tests in source files that do not match the specified glob pattern -#path_pattern_inverse = None +#no_match_path = None +# Only show coverage for files that do not match the specified regex pattern. +#no_match_coverage = None # Number of threads to use. Not set or zero specifies the number of logical cores. #threads = 0 # Whether to show test execution progress diff --git a/src/tutorials/solidity-scripting.md b/src/tutorials/solidity-scripting.md index 51ca7005d..28632a786 100644 --- a/src/tutorials/solidity-scripting.md +++ b/src/tutorials/solidity-scripting.md @@ -37,7 +37,7 @@ forge install transmissions11/solmate Openzeppelin/openzeppelin-contracts@v5.0.1 Next, we have to delete the `Counter.sol` file in the `src` folder and create another file called `NFT.sol`. You can do this by running: ```sh -rm src/Counter.sol script/Counter.s.sol test/Counter.t.sol && touch src/NFT.sol && ls src +rm src/Counter.sol test/Counter.t.sol script/Counter.s.sol && touch src/NFT.sol && ls src ``` Once that’s done, you should open up your preferred code editor and copy the code below into the `NFT.sol` file. @@ -219,6 +219,12 @@ NFT nft = new NFT("NFT_tutorial", "TUT", "baseUri"); Here we have just created our NFT contract. Because we called `vm.startBroadcast()` before this line, the contract creation will be recorded by Forge, and as mentioned previously, we can broadcast the transaction to deploy the contract on-chain. The broadcast transaction logs will be stored in the `broadcast` directory by default. You can change the logs location by setting [`broadcast`](../reference/config/project.md#broadcast) in your `foundry.toml` file. +The broadcasting sender 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, hardware wallet, keystore) is set, that signer is used. +3. Otherwise, the default Foundry sender (`0x1804c8AB1F12E6bbf3894d4083f33e07309d1f38`) is attempted to be used. + Now that you’re up to speed about what the script smart contract does, let’s run it. You should have added the variables we mentioned earlier to the `.env` for this next part to work.