Skip to main content
Version: Endpoint V2 Docs

Aptos Execution Options

When sending cross-chain messages, the source chain has no knowledge of the destination chain's state or the resources required to execute a transaction on it.

To bridge this gap, Message Execution Options provide a standardized way to specify the execution requirements for transactions on the destination chain.

You can think of options as serialized requests in bytes that inform the off-chain infrastructure (DVNs and Executors) how to handle the execution of your message on the destination chain.

Why Execution Options?​

Because the execution environment differs between chains (e.g., gas units consumed, native tokens sent, the receiver application called), you need a way to communicate the execution requirements of your messages per destination chain to the off-chain infrastructure that will process the request.

  • Specifying Gas Limit: You anticipate that your EndpointV2.lzReceive() function on the destination chain will require a certain amount of gas to execute. You specify this gas limit in your options so the Executor can allocate the appropriate resources.

  • Transferring Native Tokens: You want to send a certain amount of the destination chain's native token (e.g., APT on Aptos) along with your message. By specifying msg.value, you inform the Executor to include this amount in the transaction.

How Do Execution Options Work?​

When sending a LayerZero message, every send call requires options sent to the Endpoint, which are interpreted by the Send Library and forwarded to the configured Executor and DVN(s).

// oapp_core.move
options: vector<u8>

endpoint::send(
    &oapp_store::call_ref(),
    dst_eid,
    get_peer_bytes32(dst_eid),
    message,
    options,
    native_fee,
    zro_fee,
)

1. Building Options​

  • You use the correct library to serialize your request for gas units and native tokens.

  • The SDK serializes your requests (e.g., gas limit, msg.value) into a bytes array.

import {Options} from '@layerzerolabs/lz-v2-utilities';

let options = Options.newOptions()
  .addExecutorLzReceiveOption(gas_limit_wei, msg_value_wei)
  .toBytes();

2. Sending the Message​

You include the serialized options when sending your cross-chain message via the LayerZero Endpoint. The caller pays fees returned from the configured DVNs and Executor.

endpoint::send(
    &oapp_store::call_ref(),
    dst_eid,
    get_peer_bytes32(dst_eid),
    message,
    options,
    native_fee,
    zro_fee,
)

3. Executor Processing​

  • The Executor receives the message and deserializes the options to see the number of gas units and native tokens requested, and calculate the fees for sending the message.

  • Once the fees have been paid, the Executor uses these parameters to execute the transaction on the destination chain by calling EndpointV2.lzReceive() after the message has been successfully verified.

Each Executor may support different pathways, maximum gas amounts, etc.

Options Builders​

An off-chain SDK has been provided to build specific Message Execution Options for your application.

Since both the EVM and Aptos versions use the same Options SDK, review the EVM section for all of the Available Options Types.

At a high level, you can specify the gas settings for EndpointV2.lzReceive() and EndpointV2.lzCompose() if necessary, as well as options for sending native tokens to specific EOA.

Sending Outbound to EVM Chains​

When sending messages from Aptos to an EVM chain, you will supply:

  • Gas Limit and Message Value necessary to execute the destination transaction in wei.
Options.newOptions().addExecutorLzReceiveOption(gas_limit, msg_value);

These execution options will be charged to the payer when quoting a cross-chain send transfer on Aptos.

Sending Outbound to Aptos​

Similar to the EVM, Aptos users can set a gas limit for their transactions, specifying the maximum amount of gas they are willing to consume.

When sending messages from an EVM chain to Aptos, you will supply:

  • Gas Limit and Message Value necessary to execute the destination transaction on Aptos.
Options.newOptions().addExecutorLzReceiveOption(gas_limit, msg_value);

Gas Limit: Specifies the maximum amount of gas units that can be consumed during the execution of the EndpointV2.lzReceive() function on Aptos. Aptos gas units are similar to EVM gas units but may have different costs and limits.

Message Value: Represents the amount of the native Aptos token (APT) to be sent along with the message to the destination contract. This value functions similarly to msg.value on EVM chains.

info

The required Aptos gas limit amount will generally be lower than those on EVM chains. It's recommended to start with a gas limit of around 1,500 units for the lzReceive function on Aptos V2.

Further Reading​