Budget Gas for Variable Omnichain Callbacks

Budget variable omnichain callbacks by separating each destination execution step and measuring the gas each supported workload can consume. In LayerZero V2, the sender supplies message options that tell the Executor how much gas and native value to use for destination calls. Those options are part of the send; the source chain cannot inspect the destination’s state to predict the callback’s work.

Why do omnichain callbacks need separate gas budgets?

A destination OApp’s lzReceive handler processes the verified message and may queue a follow-on composed call. The Endpoint later invokes lzCompose on the composer. These are distinct executions, so a budget for receipt does not also fund composition. For context on how a stalled transfer fits into the broader flow, see this guide to omnichain transfer failure and recovery choices. A composed flow needs options for both stages, and each compose message can have its own gas allocation by index.

How should teams estimate callback gas?

Measure the work the destination contract actually performs for each supported message path. A callback that only records a delivery may use less gas than one that validates a payload, updates several storage slots, or calls another contract. Branches, data size, and destination state can change execution cost, so a single average from a simple test may miss the expensive path.

Build a workload matrix before setting defaults:

• List each callback path and the payload or state conditions that select it.
• Profile representative executions on the destination chain, including the most expensive supported path.
• Set separate limits for lzReceive and each lzCompose index that the flow can trigger.
• Repeat profiling when callback logic, payload bounds, or destination-chain configuration changes.

Keep variable work bounded where possible. A maximum array length or a finite set of callback types gives the sender a clearer upper bound than a loop whose size follows unrestricted user input. Leave measured headroom for ordinary variation, but treat it as an engineering margin based on the tested paths, not as a universal percentage.

What do gas limits and fees actually cover?

The gas option sets execution capacity for a destination call. The option’s msg.value is a separate amount of native value forwarded with that call; increasing it does not increase the gas limit. The send fee is also distinct: it is the quoted cost of arranging the requested cross-chain delivery and execution, and can change with destination-chain pricing and the options supplied.

Quote using the same options that will be sent, then check the configured Executor’s destination gas cap. If users can choose optional callback work, enforce a valid baseline and constrain extra options to supported paths. The practical rule is simple: budget each execution independently, price the full path, and retest the highest-cost behavior whenever the callback changes.