Omnichain Queries (LayerZero Read)

LZ_ENABLE_READ_EXAMPLE=1 npx create-lz-oapp@latest --example oapp-read

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;

// Import necessary interfaces and contracts
import { AddressCast } from "@layerzerolabs/lz-evm-protocol-v2/contracts/libs/AddressCast.sol";
import { MessagingFee, MessagingReceipt } from "@layerzerolabs/lz-evm-protocol-v2/contracts/interfaces/ILayerZeroEndpointV2.sol";
import { Origin } from "@layerzerolabs/oapp-evm/contracts/oapp/OApp.sol";
import { OAppOptionsType3 } from "@layerzerolabs/oapp-evm/contracts/oapp/libs/OAppOptionsType3.sol";
import { ReadCodecV1, EVMCallRequestV1 } from "@layerzerolabs/oapp-evm/contracts/oapp/libs/ReadCodecV1.sol";
import { OAppRead } from "@layerzerolabs/oapp-evm/contracts/oapp/OAppRead.sol";
import { Ownable } from "@openzeppelin/contracts/access/Ownable.sol";

/// @title IExampleContract
/// @notice Interface for the ExampleContract's `data()` function.
interface IExampleContract {
    function data() external view returns (uint256);
}

/// @title ReadPublic
/// @notice An OAppRead contract example to read a public state variable from another chain.
contract ReadPublic is OAppRead, OAppOptionsType3 {
    /// @notice Emitted when the data is received.
    /// @param data The value of the public state variable.
    event DataReceived(uint256 data);

    /// @notice LayerZero read channel ID.
    uint32 public READ_CHANNEL;

    /// @notice Message type for the read operation.
    uint16 public constant READ_TYPE = 1;

    /**
     * @notice Constructor to initialize the OAppRead contract.
     *
     * @param _endpoint The LayerZero endpoint contract address.
     * @param _delegate The address that will have ownership privileges.
     * @param _readChannel The LayerZero read channel ID.
     */
    constructor(
        address _endpoint,
        address _delegate,
        uint32 _readChannel
    ) OAppRead(_endpoint, _delegate) Ownable(_delegate) {
        READ_CHANNEL = _readChannel;
        _setPeer(_readChannel, AddressCast.toBytes32(address(this)));
    }

    // ──────────────────────────────────────────────────────────────────────────────
    // 0. (Optional) Quote business logic
    //
    // Example: Get a quote from the Endpoint for a cost estimate of reading data.
    // Replace this to mirror your own read business logic.
    // ──────────────────────────────────────────────────────────────────────────────

    /**
     * @notice Estimates the messaging fee required to perform the read operation.
     *
     * @param _targetContractAddress The address of the contract on the target chain containing the `data` variable.
     * @param _targetEid The target chain's Endpoint ID.
     * @param _extraOptions Additional messaging options.
     *
     * @return fee The estimated messaging fee.
     */
    function quoteReadFee(
        address _targetContractAddress,
        uint32 _targetEid,
        bytes calldata _extraOptions
    ) external view returns (MessagingFee memory fee) {
        return
            _quote(
                READ_CHANNEL,
                _getCmd(_targetContractAddress, _targetEid),
                combineOptions(READ_CHANNEL, READ_TYPE, _extraOptions),
                false
            );
    }

    // ──────────────────────────────────────────────────────────────────────────────
    // 1a. Send business logic
    //
    // Example: send a read request to fetch data from a remote contract.
    // Replace this with your own read request logic.
    // ──────────────────────────────────────────────────────────────────────────────

    /**
     * @notice Sends a read request to fetch the public state variable `data`.
     *
     * @dev The caller must send enough ETH to cover the messaging fee.
     *
     * @param _targetContractAddress The address of the contract on the target chain containing the `data` variable.
     * @param _targetEid The target chain's Endpoint ID.
     * @param _extraOptions Additional messaging options.
     *
 * @return receipt The LayerZero messaging receipt for the request.
 */
    function readData(
        address _targetContractAddress,
        uint32 _targetEid,
    bytes calldata _extraOptions
) external payable returns (MessagingReceipt memory receipt) {
        // 1. Build the read command for the target contract and function
        bytes memory cmd = _getCmd(_targetContractAddress, _targetEid);

        // 2. Send the read request via LayerZero
        //    - READ_CHANNEL: Special channel ID for read operations
        //    - cmd: Encoded read command with target details
        //    - combineOptions: Merge enforced options with caller-provided options
        //    - MessagingFee(msg.value, 0): Pay all fees in native gas; no ZRO
        //    - payable(msg.sender): Refund excess gas to caller
    return
        _lzSend(
            READ_CHANNEL,
            cmd,
                combineOptions(READ_CHANNEL, READ_TYPE, _extraOptions),
            MessagingFee(msg.value, 0),
            payable(msg.sender)
        );
}

    // ──────────────────────────────────────────────────────────────────────────────
    // 1b. Read command construction
    //
    // This function defines WHAT data to fetch from the target network and WHERE to fetch it from.
    // This is the core of LayerZero Read - specifying exactly which contract function to call
    // on which chain and how to handle the request.
    // ──────────────────────────────────────────────────────────────────────────────

    /**
     * @notice Constructs the read command to fetch the `data` variable from target chain.
     * @dev This function defines the core read operation - what data to fetch and from where.
     *      Replace this logic to read different functions or data from your target contracts.
     *
     * @param _targetContractAddress The address of the contract containing the `data` variable.
     * @param _targetEid The target chain's Endpoint ID.
     *
     * @return cmd The encoded command that specifies what data to read.
     */
    function _getCmd(address _targetContractAddress, uint32 _targetEid) internal view returns (bytes memory cmd) {
        // 1. Define WHAT function to call on the target contract
        //    Using the interface selector ensures type safety and correctness
        //    You can replace this with any public/external function or state variable
        bytes memory callData = abi.encodeWithSelector(IExampleContract.data.selector);

        // 2. Build the read request specifying WHERE and HOW to fetch the data
        EVMCallRequestV1[] memory readRequests = new EVMCallRequestV1[](1);
        readRequests[0] = EVMCallRequestV1({
            appRequestLabel: 1, // Label for tracking this specific request
            targetEid: _targetEid, // WHICH chain to read from
            isBlockNum: false, // Use timestamp (not block number)
            blockNumOrTimestamp: uint64(block.timestamp), // WHEN to read the state (current time)
            confirmations: 15, // HOW many confirmations to wait for
            to: _targetContractAddress, // WHERE - the contract address to call
            callData: callData // WHAT - the function call to execute
        });

        // 3. Encode the complete read command
        //    No compute logic needed for simple data reading
        //    The appLabel (0) can be used to identify different types of read operations
        cmd = ReadCodecV1.encode(0, readRequests);
    }

    // ──────────────────────────────────────────────────────────────────────────────
    // 2. Receive business logic
    //
    // Override _lzReceive to handle the returned data from the read request.
    // The base OAppReceiver.lzReceive ensures:
    //   • Only the LayerZero Endpoint can call this method
    //   • The sender is a registered peer (peers[srcEid] == origin.sender)
    // ──────────────────────────────────────────────────────────────────────────────

    /**
     * @notice Handles the received data from the target chain.
     *
     * @dev This function is called internally by the LayerZero protocol.
     * @dev   _origin    Metadata (source chain, sender address, nonce)
     * @dev   _guid      Global unique ID for tracking this response
     * @param _message   The data returned from the read request (uint256 in this case)
     * @dev   _executor  Executor address that delivered the response
     * @dev   _extraData Additional data from the Executor (unused here)
     */
    function _lzReceive(
        Origin calldata /*_origin*/,
        bytes32 /*_guid*/,
        bytes calldata _message,
        address /*_executor*/,
        bytes calldata /*_extraData*/
    ) internal override {
        // 1. Decode the returned data from bytes to uint256
        uint256 data = abi.decode(_message, (uint256));

        // 2. Emit an event with the received data
        emit DataReceived(data);

        // 3. (Optional) Apply your custom logic here.
        //    e.g., store the data, trigger additional actions, etc.
    }

    // ──────────────────────────────────────────────────────────────────────────────
    // 3. Admin functions
    //
    // Functions for managing the read channel configuration.
    // ──────────────────────────────────────────────────────────────────────────────

    /**
     * @notice Sets the LayerZero read channel.
     *
     * @dev Only callable by the owner.
     *
     * @param _channelId The channel ID to set.
     * @param _active Flag to activate or deactivate the channel.
     */
    function setReadChannel(uint32 _channelId, bool _active) public override onlyOwner {
        _setPeer(_channelId, _active ? AddressCast.toBytes32(address(this)) : bytes32(0));
        READ_CHANNEL = _channelId;
    }
}

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;

/**
 * @title ExampleContract
 * @notice A simple contract with a public state variable that can be read crosschain.
 * @dev This contract would be deployed on target chains (e.g., Ethereum, Polygon, Arbitrum)
 *      and the ReadPublic contract can fetch its `data` value from any other supported chain.
 */
contract ExampleContract {
    /// @notice Public state variable that can be read from other chains
    /// @dev The public keyword automatically generates a getter function data()
    uint256 public data;

    constructor(uint256 _data) {
        data = _data;
    }
}

// Get fee estimate first
MessagingFee memory fee = readPublic.quoteReadFee(
    targetContractAddress,
    targetEid,
    "0x"  // no additional options
);

// Then send with the estimated fee
readPublic.readData{value: fee.nativeFee}(
    targetContractAddress,
    targetEid,
    "0x"
);

// Standard messaging options
OptionsBuilder.newOptions().addExecutorLzReceiveOption(100000, 0);

// lzRead options (note the size parameter)
OptionsBuilder.newOptions().addExecutorLzReadOption(100000, 64, 0);
//                                                   gas    size value

LZ_ENABLE_READ_EXAMPLE=1 npx create-lz-oapp@latest --example view-pure-read

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;

// Import necessary interfaces and contracts
import { AddressCast } from "@layerzerolabs/lz-evm-protocol-v2/contracts/libs/AddressCast.sol";
import { MessagingFee, MessagingReceipt } from "@layerzerolabs/lz-evm-protocol-v2/contracts/interfaces/ILayerZeroEndpointV2.sol";
import { Origin } from "@layerzerolabs/oapp-evm/contracts/oapp/OApp.sol";
import { OAppOptionsType3 } from "@layerzerolabs/oapp-evm/contracts/oapp/libs/OAppOptionsType3.sol";
import { OAppRead } from "@layerzerolabs/oapp-evm/contracts/oapp/OAppRead.sol";
import { Ownable } from "@openzeppelin/contracts/access/Ownable.sol";
import { EVMCallRequestV1, ReadCodecV1 } from "@layerzerolabs/oapp-evm/contracts/oapp/libs/ReadCodecV1.sol";

/// @title IExampleContract
/// @notice Interface for the ExampleContract's `add` function.
interface IExampleContract {
    function add(uint256 a, uint256 b) external pure returns (uint256);
}

/// @title ReadViewOrPure Example
/// @notice An OAppRead contract that calls view/pure functions on target chains and receives results
contract ReadViewOrPure is OAppRead, OAppOptionsType3 {

    /// @notice Emitted when crosschain function data is successfully received
    event SumReceived(uint256 sum);

    /// @notice LayerZero read channel ID for crosschain data requests
    uint32 public READ_CHANNEL;

    /// @notice Message type identifier for read operations
    uint16 public constant READ_TYPE = 1;

    /// @notice Target chain's LayerZero Endpoint ID (immutable after deployment)
    uint32 public immutable targetEid;

    /// @notice Address of the contract to read from on the target chain
    address public immutable targetContractAddress;

    /**
     * @notice Initialize the crosschain read contract
     * @dev Sets up LayerZero connectivity and establishes read channel peer relationship
     * @param _endpoint LayerZero endpoint address on the source chain
     * @param _readChannel Read channel ID for this contract's operations
     * @param _targetEid Destination chain's endpoint ID where target contract lives
     * @param _targetContractAddress Contract address to read from on target chain
     */
    constructor(
        address _endpoint,
        uint32 _readChannel,
        uint32 _targetEid,
        address _targetContractAddress
    ) OAppRead(_endpoint, msg.sender) Ownable(msg.sender) {
        READ_CHANNEL = _readChannel;
        targetEid = _targetEid;
        targetContractAddress = _targetContractAddress;

        // Establish read channel peer - contract reads from itself via LayerZero
        _setPeer(READ_CHANNEL, AddressCast.toBytes32(address(this)));
    }

    /**
     * @notice Configure the LayerZero read channel for this contract
     * @dev Owner-only function to activate/deactivate read channels
     * @param _channelId Read channel ID to configure
     * @param _active Whether to activate (true) or deactivate (false) the channel
     */
    function setReadChannel(uint32 _channelId, bool _active) public override onlyOwner {
        // Set or clear the peer relationship for the read channel
        _setPeer(_channelId, _active ? AddressCast.toBytes32(address(this)) : bytes32(0));
        READ_CHANNEL = _channelId;
    }

    /**
     * @notice Execute a crosschain read request to call the target function
     * @dev Builds the read command and sends it via LayerZero messaging
     * @param _a First parameter for the target function
     * @param _b Second parameter for the target function
     * @param _extraOptions Additional execution options (gas, value, etc.)
     * @return receipt LayerZero messaging receipt containing transaction details
     */
    function readSum(
        uint256 _a,
        uint256 _b,
        bytes calldata _extraOptions
    ) external payable returns (MessagingReceipt memory) {
        // 1. Build the read command specifying target function and parameters
        bytes memory cmd = _getCmd(_a, _b);

        // 2. Send the read request via LayerZero
        return _lzSend(
            READ_CHANNEL,
            cmd,
            combineOptions(READ_CHANNEL, READ_TYPE, _extraOptions),
            MessagingFee(msg.value, 0),
            payable(msg.sender)
        );
    }

    /**
     * @notice Get estimated messaging fee for a crosschain read operation
     * @dev Calculates LayerZero fees before sending to avoid transaction failures
     * @param _a First parameter for the target function
     * @param _b Second parameter for the target function
     * @param _extraOptions Additional execution options
     * @return fee Estimated LayerZero messaging fee structure
     */
    function quoteReadFee(
        uint256 _a,
        uint256 _b,
        bytes calldata _extraOptions
    ) external view returns (MessagingFee memory fee) {
        // Build the same command as readSum and quote its cost
        return _quote(READ_CHANNEL, _getCmd(_a, _b), combineOptions(READ_CHANNEL, READ_TYPE, _extraOptions), false);
    }

    /**
     * @notice Build the LayerZero read command for target function execution
     * @dev Constructs EVMCallRequestV1 specifying what data to fetch and from where
     * @param _a First parameter to pass to target function
     * @param _b Second parameter to pass to target function
     * @return Encoded read command for LayerZero execution
     */
    function _getCmd(uint256 _a, uint256 _b) internal view returns (bytes memory) {
        // 1. Build the function call data
        // Encode the target function selector with parameters
        bytes memory callData = abi.encodeWithSelector(IExampleContract.add.selector, _a, _b);

        // 2. Create the read request structure
        EVMCallRequestV1[] memory readRequests = new EVMCallRequestV1[](1);
        readRequests[0] = EVMCallRequestV1({
            appRequestLabel: 1, // Request identifier for tracking
            targetEid: targetEid, // Which chain to read from
            isBlockNum: false, // Use timestamp instead of block number for data freshness
            blockNumOrTimestamp: uint64(block.timestamp), // Read current state
            confirmations: 15, // Wait for block finality before executing
            to: targetContractAddress, // Target contract address
            callData: callData // The function call to execute
        });

        // 3. Encode the command (no compute logic needed for simple reads)
        return ReadCodecV1.encode(0, readRequests);
    }

    /**
     * @notice Process the received data from the target chain
     * @dev Called by LayerZero when the read response is delivered
     * @param _message Encoded response data from the target function call
     */
    function _lzReceive(
        Origin calldata /*_origin*/,
        bytes32 /*_guid*/,
        bytes calldata _message,
        address /*_executor*/,
        bytes calldata /*_extraData*/
    ) internal override {
        // 1. Validate response format
        require(_message.length == 32, "Invalid message length");

        // 2. Decode the returned data (matches target function return type)
        uint256 sum = abi.decode(_message, (uint256));

        // 3. Process the result (emit event, update state, trigger logic, etc.)
        emit SumReceived(sum);
    }
 }

 // Example target contract for demonstration
 contract ExampleContract {
     /**
      * @notice Adds two numbers.
      * @param a First number.
      * @param b Second number.
      * @return sum The sum of a and b.
      */
     function add(uint256 a, uint256 b) external pure returns (uint256 sum) {
         return a + b;
     }
   }

// Get fee estimate first
MessagingFee memory fee = readContract.quoteReadFee(5, 10, "0x");

// Then send with estimated fee
readContract.readSum{value: fee.nativeFee}(5, 10, "0x");

// Query token balances on other chains
function getBalance(address user) external view returns (uint256);

// Access oracle prices from different chains
function getLatestPrice() external view returns (uint256 price, uint256 timestamp);

// Check protocol states across deployments
function getTotalSupply() external view returns (uint256);
function getReserves() external view returns (uint112 reserve0, uint112 reserve1);

// Validate conditions before crosschain actions
function isEligibleForRewards(address user) external view returns (bool eligible, uint256 amount);

// Query governance states
function getProposalState(uint256 proposalId) external view returns (uint8 state);

LZ_ENABLE_READ_EXAMPLE=1 npx create-lz-oapp@latest --example view-pure-read

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;

// Import necessary interfaces and contracts
import { Ownable } from "@openzeppelin/contracts/access/Ownable.sol";

import { Origin } from "@layerzerolabs/oapp-evm/contracts/oapp/OApp.sol";
import { OAppOptionsType3 } from "@layerzerolabs/oapp-evm/contracts/oapp/libs/OAppOptionsType3.sol";
import { OAppRead } from "@layerzerolabs/oapp-evm/contracts/oapp/OAppRead.sol";
// highlight-start
import { IOAppMapper } from "@layerzerolabs/oapp-evm/contracts/oapp/interfaces/IOAppMapper.sol";
import { IOAppReducer } from "@layerzerolabs/oapp-evm/contracts/oapp/interfaces/IOAppReducer.sol";
// highlight-end
import { EVMCallRequestV1, EVMCallComputeV1, ReadCodecV1 } from "@layerzerolabs/oapp-evm/contracts/oapp/libs/ReadCodecV1.sol";

import { AddressCast } from "@layerzerolabs/lz-evm-protocol-v2/contracts/libs/AddressCast.sol";
import { MessagingFee, MessagingReceipt, ILayerZeroEndpointV2 } from "@layerzerolabs/lz-evm-protocol-v2/contracts/interfaces/ILayerZeroEndpointV2.sol";

/// @title IExampleContract
/// @notice Interface for the ExampleContract's `add` function.
interface IExampleContract {
    function add(uint256 a, uint256 b) external pure returns (uint256);
}

/// @title ReadViewOrPureAndCompute
/// @notice Crosschain read contract with compute processing for data transformation and aggregation
contract ReadViewOrPureAndCompute is OAppRead, IOAppMapper, IOAppReducer, OAppOptionsType3 {

    /// @notice Emitted when final computed result is received from the compute pipeline
    event SumReceived(uint256 sum);

    /// @notice LayerZero read channel ID for crosschain data requests with compute
    uint32 public READ_CHANNEL;

    /// @notice Message type identifier for read operations with compute processing
    uint16 public constant READ_TYPE = 1;

    /// @notice Target chain's LayerZero Endpoint ID (immutable after deployment)
    uint32 public immutable targetEid;

    /// @notice Address of the contract to read from on the target chain
    address public immutable targetContractAddress;

    /**
     * @notice Initialize the crosschain read contract with compute capabilities
     * @dev Sets up LayerZero connectivity, establishes read channel, and enables compute processing
     * @param _endpoint LayerZero endpoint address on the source chain
     * @param _readChannel Read channel ID for this contract's operations
     * @param _targetEid Destination chain's endpoint ID where target contract lives
     * @param _targetContractAddress Contract address to read from on target chain
     */
    constructor(
        address _endpoint,
        uint32 _readChannel,
        uint32 _targetEid,
        address _targetContractAddress
    ) OAppRead(_endpoint, msg.sender) Ownable(msg.sender) {
        READ_CHANNEL = _readChannel;
        targetEid = _targetEid;
        targetContractAddress = _targetContractAddress;

        // Establish read channel peer - contract processes its own compute functions
        _setPeer(READ_CHANNEL, AddressCast.toBytes32(address(this)));
    }

    /**
     * @notice Configure the LayerZero read channel for compute-enabled operations
     * @dev Owner-only function to activate/deactivate read channels with compute processing
     * @param _channelId Read channel ID to configure
     * @param _active Whether to activate (true) or deactivate (false) the channel
     */
    function setReadChannel(uint32 _channelId, bool _active) public override onlyOwner {
        // Set or clear the peer relationship for compute-enabled read operations
        _setPeer(_channelId, _active ? AddressCast.toBytes32(address(this)) : bytes32(0));
        READ_CHANNEL = _channelId;
    }

    /**
     * @notice Execute a crosschain read request with compute processing pipeline (Step 1)
     * @dev Builds read command with compute configuration and sends via LayerZero
     * @param _a First parameter for the target function
     * @param _b Second parameter for the target function
     * @param _extraOptions Additional execution options (gas, value, etc.)
     * @return receipt LayerZero messaging receipt containing transaction details
     */
    function readSum(
        uint256 _a,
        uint256 _b,
        bytes calldata _extraOptions
    ) external payable returns (MessagingReceipt memory) {
        // 1. Build the read command with compute configuration
        bytes memory cmd = _getCmd(_a, _b);

        // 2. Send the read request with compute processing enabled
        return _lzSend(
            READ_CHANNEL,
            cmd,
            combineOptions(READ_CHANNEL, READ_TYPE, _extraOptions),
            MessagingFee(msg.value, 0),
            payable(msg.sender)
        );
    }

    /**
     * @notice Get estimated messaging fee for crosschain read with compute processing
     * @dev Calculates LayerZero fees including compute overhead before sending
     * @param _a First parameter for the target function
     * @param _b Second parameter for the target function
     * @param _extraOptions Additional execution options
     * @return fee Estimated LayerZero messaging fee structure
     */
    function quoteReadFee(
        uint256 _a,
        uint256 _b,
        bytes calldata _extraOptions
    ) external view returns (MessagingFee memory fee) {
        // Build the same command as readSum (including compute config) and quote its cost
        return _quote(READ_CHANNEL, _getCmd(_a, _b), combineOptions(READ_CHANNEL, READ_TYPE, _extraOptions), false);
    }

    /**
     * @notice Build the LayerZero read command with compute processing configuration
     * @dev Constructs both the target function call AND the compute pipeline setup
     * @param _a First parameter to pass to target function
     * @param _b Second parameter to pass to target function
     * @return Encoded read command with compute configuration for LayerZero execution
     */
    function _getCmd(uint256 _a, uint256 _b) internal view returns (bytes memory) {
        // 1. Build the target function call data (same as basic read)
        bytes memory callData = abi.encodeWithSelector(IExampleContract.add.selector, _a, _b);

        // 2. Create the read request structure
        EVMCallRequestV1[] memory readRequests = new EVMCallRequestV1[](1);
        readRequests[0] = EVMCallRequestV1({
            appRequestLabel: 1, // Request identifier for tracking through compute pipeline
            targetEid: targetEid, // Which chain to read from
            isBlockNum: false, // Use timestamp for data freshness
            blockNumOrTimestamp: uint64(block.timestamp), // Read current state
            confirmations: 15, // Wait for block finality before processing
            to: targetContractAddress, // Target contract address
            callData: callData // The function call to execute
        });
        // highlight-start
        // 3. Configure the compute processing pipeline - THIS IS THE KEY DIFFERENCE
        EVMCallComputeV1 memory computeRequest = EVMCallComputeV1({
            computeSetting: 2, // 0=lzMap only, 1=lzReduce only, 2=both lzMap and lzReduce
            targetEid: ILayerZeroEndpointV2(endpoint).eid(), // Execute compute on source chain (this chain)
            isBlockNum: false, // Use timestamp for compute execution timing
            blockNumOrTimestamp: uint64(block.timestamp), // When to execute compute functions
            confirmations: 15, // Confirmations needed before compute processing begins
            to: address(this) // Contract address containing lzMap/lzReduce implementations
        });

        // 4. Encode the complete command (read requests + compute configuration)
        return ReadCodecV1.encode(0, readRequests, computeRequest);
        // highlight-end
    }
    // highlight-start
    /**
     * @notice Transform individual read responses during compute processing (Step 2 of compute pipeline)
     * @dev Called by LayerZero's compute layer for each raw response from target chains
     * @param _request Original request data (unused in this example, but available for context)
     * @param _response Raw response data from the target chain function call
     * @return Processed response data to pass to lzReduce (or final result if no reduce step)
     */
    function lzMap(
        bytes calldata /*_request*/,
        bytes calldata _response
    ) external pure override returns (bytes memory) {
        // 1. Decode the raw response from target function (uint256 from add function)
        uint256 sum = abi.decode(_response, (uint256));

        // 2. Apply transformation logic (example: increment by 1)
        // This could be: unit conversion, validation, filtering, formatting, etc.
        sum += 1;

        // 3. Re-encode for lzReduce or final delivery
        return abi.encode(sum);
    }

    /**
     * @notice Aggregate all mapped responses into final result (Step 3 of compute pipeline)
     * @dev Called after all lzMap operations complete, receives array of mapped responses
     * @param _cmd Original command data (unused in this example, but available for context)
     * @param _responses Array of processed responses from lzMap function
     * @return Final aggregated data to deliver to _lzReceive
     */
    function lzReduce(
        bytes calldata /*_cmd*/,
        bytes[] calldata _responses
    ) external pure override returns (bytes memory) {
        uint256 totalSum = 0;

        // Process each mapped response and aggregate them
    for (uint256 i = 0; i < _responses.length; i++) {
            // 1. Validate each response format
            require(_responses[i].length == 32, "Invalid response length");

            // 2. Decode the mapped response
            uint256 sum = abi.decode(_responses[i], (uint256));

            // 3. Apply aggregation logic (example: sum all responses)
            totalSum += sum;
        }

        // 4. Return final aggregated result
        return abi.encode(totalSum);
    }
    // highlight-end

    /**
     * @notice Process the final computed result from the compute pipeline (Step 4)
     * @dev Called by LayerZero when compute processing is complete and result is delivered
     * @param _message Final processed data from the compute pipeline (lzReduce output)
     */
    function _lzReceive(
        Origin calldata /*_origin*/,
        bytes32 /*_guid*/,
        bytes calldata _message,
        address /*_executor*/,
        bytes calldata /*_extraData*/
    ) internal override {
        // 1. Validate final result format
        require(_message.length == 32, "Invalid message length");

        // 2. Decode the final computed result
        uint256 sum = abi.decode(_message, (uint256));

        // 3. Process the result (emit event, update state, trigger logic, etc.)
        emit SumReceived(sum);
    }
 }

// Get fee estimate for read with compute
MessagingFee memory fee = readContract.quoteReadFee(5, 10, "0x");

// Send with computed processing
readContract.readSum{value: fee.nativeFee}(5, 10, "0x");

LZ_ENABLE_READ_EXAMPLE=1 npx create-lz-oapp@latest --example uniswap-read

// contracts/UniswapV3QuoteDemo.sol
//
// ──────────────────────────────────────────────────────────────────────────────
// 1b. Read Command Construction
// ──────────────────────────────────────────────────────────────────────────────
/// @notice Constructs the read command to fetch Uniswap V3 quotes from each configured chain.
/// @return cmd Encoded command for crosschain price queries.
function getCmd() public view returns (bytes memory cmd) {
    uint256 count = targetEids.length;
    EVMCallRequestV1[] memory requests = new EVMCallRequestV1[](count);
    for (uint256 i = 0; i < count; ++i) {
        uint32 eid = targetEids[i];
        ChainConfig memory cfg = chainConfigs[eid];
        bytes memory data = abi.encodeWithSelector(
            IQuoterV2.quoteExactInputSingle.selector,
            IQuoterV2.QuoteExactInputSingleParams({
                tokenIn: cfg.tokenInAddress,
                tokenOut: cfg.tokenOutAddress,
                amountIn: 1 ether,
                fee: cfg.fee,
                sqrtPriceLimitX96: 0
            })
        );
        requests[i] = EVMCallRequestV1({
            appRequestLabel: uint16(i + 1),
            targetEid: eid,
            isBlockNum: false,
            blockNumOrTimestamp: uint64(block.timestamp),
            confirmations: cfg.confirmations,
            to: cfg.quoterAddress,
            callData: data
        });
    }
    EVMCallComputeV1 memory compute = EVMCallComputeV1({
        computeSetting: 2,
        targetEid: ILayerZeroEndpointV2(endpoint).eid(),
        isBlockNum: false,
        blockNumOrTimestamp: uint64(block.timestamp),
        confirmations: 15,
        to: address(this)
    });
    return ReadCodecV1.encode(0, requests, compute);
}

// ──────────────────────────────────────────────────────────────────────────────
// 2. Map & Reduce Logic
// ──────────────────────────────────────────────────────────────────────────────

/// @notice Maps individual Uniswap quote responses to encoded amounts.
/// @param _response Raw response bytes from the quoted call.
/// @return Encoded amountOut for a single chain.
function lzMap(bytes calldata, bytes calldata _response) external pure returns (bytes memory) {
    require(_response.length >= 32, "Invalid response length");
    (uint256 amountOut,,,) = abi.decode(_response, (uint256, uint160, uint32, uint256));
    return abi.encode(amountOut);
}

/// @notice Reduces multiple mapped responses to a single average value.
/// @param _responses Array of encoded amountOut responses from each chain.
/// @return Encoded average of all responses.
function lzReduce(bytes calldata, bytes[] calldata _responses) external pure returns (bytes memory) {
    require(_responses.length > 0, "No responses");
    uint256 sum;
    for (uint i = 0; i < _responses.length; i++) {
        sum += abi.decode(_responses[i], (uint256));
    }
    uint256 avg = sum / _responses.length;
    return abi.encode(avg);
}

// ──────────────────────────────────────────────────────────────────────────────
// 3. Receive Business Logic
// ──────────────────────────────────────────────────────────────────────────────

/// @notice Handles the final averaged quote from LayerZero and emits the result.
/// @dev _origin LayerZero origin metadata (unused).
/// @dev _guid Unique message identifier (unused).
/// @param _message Encoded average price bytes.
function _lzReceive(
    Origin calldata /*_origin*/, bytes32 /*_guid*/, bytes calldata _message,
    address /*_executor*/, bytes calldata /*_extraData*/
) internal override {
    uint256 averagePrice = abi.decode(_message, (uint256));
    emit AggregatedPrice(averagePrice);
}

// Uniswap returns: (amountOut, sqrtPriceX96After, initializedTicksCrossed, gasEstimate)
(uint256 amountOut,,,) = abi.decode(_response, (uint256, uint160, uint32, uint256));
return abi.encode(amountOut); // Extract only the price data we need

uint256 sum;
for (uint i = 0; i < _responses.length; i++) {
    sum += abi.decode(_responses[i], (uint256));
}
uint256 avg = sum / _responses.length; // Simple average across 3 chains

contract HybridApp is OAppRead {
    uint32 constant READ_CHANNEL_THRESHOLD = 4294965694;

    function _lzReceive(
        Origin calldata _origin,
        bytes32 _guid,
        bytes calldata _message,
        address _executor,
        bytes calldata _extraData
    ) internal override {
        if (_origin.srcEid > READ_CHANNEL_THRESHOLD) {
            // Handle read responses
            _handleReadResponse(_message);
        } else {
            // Handle regular messages
            _handleMessage(_origin, _message);
        }
    }

    function _handleReadResponse(bytes calldata _message) internal {
        // Process read response data
        uint256 price = abi.decode(_message, (uint256));
        // Update application state with fetched data
    }

    function _handleMessage(Origin calldata _origin, bytes calldata _message) internal {
        // Process regular crosschain messages
        string memory data = abi.decode(_message, (string));
        // Handle standard messaging logic
    }
}

// ❌ WRONG - Standard messaging options
OptionsBuilder.newOptions().addExecutorLzReceiveOption(100000, 0);

// ✅ CORRECT - lzRead options with size estimation
OptionsBuilder.newOptions().addExecutorLzReadOption(100000, 64, 0);
//                                                   gas   size value

import { OptionsBuilder } from "@layerzerolabs/oapp-evm/contracts/oapp/libs/OptionsBuilder.sol";

function getReadOptions(uint256 responseSize) internal pure returns (bytes memory) {
    return OptionsBuilder
        .newOptions()
        .addExecutorLzReadOption(
            200000,        // Gas limit for response processing
            responseSize,  // Expected response data size in bytes
            0             // Native value (usually 0 for reads)
        );
}

// ❌ PROBLEMATIC - Function may revert with certain parameters
function riskyRead() external payable {
    bytes memory callData = abi.encodeWithSelector(
        IToken.balanceOf.selector,
        address(0) // Zero address may cause revert in some implementations
    );
    // ... rest of read logic
}

// ✅ SAFE - Validate parameters and use defensive programming
function safeRead(address tokenHolder) external payable {
    require(tokenHolder != address(0), "Invalid holder address");
    require(tokenHolder.code.length > 0, "Not a contract"); // If targeting contracts

    bytes memory callData = abi.encodeWithSelector(
        IToken.balanceOf.selector,
        tokenHolder
    );
    // ... rest of read logic
}

// Test target function locally before using in lzRead
function testTargetFunction(address target, bytes memory callData) external view returns (bool success, bytes memory result) {
    (success, result) = target.staticcall(callData);
    if (!success) {
        // Log the revert reason for debugging
        if (result.length > 0) {
            assembly {
                let returndata_size := mload(result)
                revert(add(32, result), returndata_size)
            }
        }
    }
}

// ❌ PROBLEMATIC - Multiple rapid requests without nonce management
function multipleReads() external payable {
    // These requests will be processed sequentially by nonce
    readData(target1, eid1); // Nonce N
    readData(target2, eid2); // Nonce N+1 - blocked if N fails
    readData(target3, eid3); // Nonce N+2 - blocked if N or N+1 fails
}

// ❌ UNDERESTIMATED - Will fail if response is larger than 32 bytes
OptionsBuilder.newOptions().addExecutorLzReadOption(100000, 32, 0);

// But target function returns: (uint256, address, string) ≈ 100+ bytes
function complexTargetFunction() external view returns (uint256, address, string memory);

contract SizeEstimator {
    // Calculate response sizes for common types
    function estimateResponseSize(bytes memory sampleResponse) external pure returns (uint256) {
        return sampleResponse.length;
    }

    // Common type sizes (for reference):
    // uint256: 32 bytes
    // address: 32 bytes (padded)
    // bool: 32 bytes (padded)
    // bytes32: 32 bytes
    // string: 32 + length + padding
    // dynamic array: 32 + (element_size * length)
    // tuple: sum of all element sizes
}

// ✅ PROPER SIZE ESTIMATION
function getOptionsWithCorrectSize(uint256 expectedStringLength) internal pure returns (bytes memory) {
    uint256 estimatedSize =
        32 +                    // uint256
        32 +                    // address
        32 +                    // string length
        expectedStringLength +  // string content
        32;                     // padding buffer

    return OptionsBuilder
        .newOptions()
        .addExecutorLzReadOption(200000, estimatedSize, 0);
}

// ❌ PROBLEMATIC on L2s - May reference L1 blocks
EVMCallRequestV1({
    // ...
    isBlockNum: true,
    blockNumOrTimestamp: uint64(block.number), // This is L1 block number on Arbitrum!
    // ...
});

// ✅ RECOMMENDED - Use timestamps for universal compatibility
EVMCallRequestV1({
    // ...
    isBlockNum: false,
    blockNumOrTimestamp: uint64(block.timestamp), // Works consistently across all chains
    // ...
});