🗞️ Add _options gas profiler

[St0rmBr3w]

In this PR:

This PR introduces a Gas Profiler for estimating the gas usage of LayerZero's lzReceive and lzCompose functions. It simplifies running Foundry scripts by adding pnpm commands that allow dynamic argument passing, making gas profiling more accessible and efficient for developers.

Some limitations are that Foundry does not accurately return L1 data fees on most L2s as referenced in [foundry-rs/foundry#6253](foundry-rs/foundry#6253), so the gas units returned are only part of the profile necessary to determine enforcedOptions. However, this is acceptable for LayerZero options, as the L1 data fee is handled by the Executor and added to the fee charged on the source chain for the provision of gas resources.

Additionally, accurate testing requires supplying different types of payload conditions to the script.

Key Features

1. Commands for Gas Profiling:

   • gas:lzReceive: Profiles the lzReceive function.
   • gas:lzCompose: Profiles the lzCompose function.

2. Dynamic Arguments:

   • Pass required parameters directly to the commands for custom configurations.

3. Detailed Output:

   • Provides gas usage metrics including average, median, minimum, and maximum values across multiple runs.
   • Note: Only includes gas used for L2 EVM execution fees, excluding L1 data fees.

4. Payload Condition Testing:

   • Supports testing with various payload conditions.

5. Extended Script Functionality:

   • Extend existing scripts using Foundry methods to simulate payload generation and pass multiple scenarios to the profiler, determining the optimal gas for your specific OApp implementation.

Usage Examples

lzReceive Gas Profiling

pnpm gas:lzReceive \
  <rpcUrl> \
  <endpointAddress> \
  <srcEid> \
  <sender> \
  <dstEid> \
  <receiver> \
  <message> \
  <msgValue> \
  <numOfRuns>

lzCompose Gas Profiling

pnpm gas:lzCompose \
  <rpcUrl> \
  <endpointAddress> \
  <srcEid> \
  <sender> \
  <dstEid> \
  <receiver> \
  <composer> \
  <composeMsg> \
  <msgValue> \
  <numOfRuns>

Extending the Profiler with Foundry Methods

In addition to the provided pnpm commands, you can extend the existing script as demonstrated in the OFTProfilerExample. This allows you to simulate payload generation using Foundry methods and pass multiple scenarios to the profiler to determine the optimal gas for your _options parameter.

Important Notes:

• Optimal Gas Allocation:
  Use the highest returned gas usage for enforcedOptions to prevent edge cases where calls revert due to insufficient gas being supplied.

• Custom msgTypes:
  Add custom msgTypes to your _options to specify gas requirements for different types of send function calls, enhancing the precision of gas profiling.

Benefits

• Simplifies repetitive gas profiling tasks.
• Ensures consistent metrics across multiple test runs.
• Allows for customization based on specific configurations and use cases.
• Excludes L1 data fees, which are handled separately, ensuring clarity in gas usage analysis.
• Enhanced Testing Flexibility: Supports diverse payload conditions to accurately assess gas consumption under various scenarios.
• Optimized Gas Allocation: Helps determine the optimal gas settings for enforcedOptions and extraOptions, preventing edge cases where calls might revert due to insufficient gas.

Limitations

1. Custom Safety Checks:

   • The implementation assumes the generic safety checks are in place (e.g., ensuring the caller is the endpoint and the call originates from the correct OApp).
   • If the receiver contract includes additional custom checks, these must be manually overridden in the script for accurate results.

2. L1 Data Fees Exclusion:

   • The Gas Profiler only outputs gas used for L2 EVM execution fees.
   • L1 data fees are not included, as they are handled by the Executor and added to the fee charged on the source chain for gas resources.

3. zk Chains Consideration:

   • For zkSync elastic chains, zk-foundry is required and should be run independently from other profiling.

4. Payload Condition Testing:

   • To accurately test using this Gas Profiler, you need to supply different types of payload conditions to the script. For example, an OFT transfer can have very different types of gas usage depending on the:
     • Receiver Address
     • Token Amount Size
     • Whether the Payload Contains a Composed Message

Recommendations

• Use Private RPCs:

  • Avoid timeouts by using private RPCs when running multiple test cases.

• Adjust Test Parameters:

  • Modify parameters like numOfRuns and msgValue to match your specific use case for more reliable results.

• Validate Custom Logic:

  • Ensure that custom receiver contract logic is independently validated to maintain compatibility with this profiler.

Benefits of the Updates

• Clarity in Gas Analysis:
  By excluding L1 data fees, developers can focus solely on L2 execution costs, simplifying optimization efforts.

• Comprehensive Testing:
  Supporting diverse payload conditions ensures that gas profiling covers a wide range of real-world scenarios, leading to more robust and reliable results.

• Specialized zk Chain Support:
  Addressing zk chains separately with zk-foundry ensures accurate profiling without interference from other profiling processes.

• Enhanced Gas Optimization:
  Utilizing the highest gas usage metrics for enforcedOptions helps prevent transaction reverts due to insufficient gas, ensuring smoother operations.

Fixed

[St0rmBr3w]

Based on some feedback and back and forth with off-chain team, I think that the scope of this can be reduced slightly.

Fork testing might not even be needed if we strictly just need to predict the EVM L2 execution cost. Since L1 data fee is not something we're in a place to abstract right now, the _options param can essentially only predict the L2 execution cost (special exception for different compilers like zkSolc).

In the future, we may have teams try to estimate the L1 data fee, but for today L2 execution cost maximum's is likely the best possible state.

[ryandgoulding]

@St0rmBr3w is this ready for review or do you want to make some more updates based on your above comment? Thanks!

[St0rmBr3w]

@St0rmBr3w is this ready for review or do you want to make some more updates based on your above comment? Thanks!

I would say we're ready to review this.