@layerzerolabs/protocol-v2-oapp-evm-contracts 1.2.95

package/README.md

@@ -0,0 +1,15 @@
+# `@layerzerolabs/protocol-v2-oapp-evm-contracts`
+
+LayerZero V2 EVM OApp, OFT and PreCrime base contracts, and the `OmniCounter` example. Its sources import the old package names, which resolve to the workspace copies through package aliases.
+
+Copied byte for byte from `@layerzerolabs/lz-evm-oapp-v2` (`packages/layerzero-v2/evm/oapp`) in the old LayerZero-Labs/monorepo at `origin/cb/executor-upgrade` (`d976cafeaf`). Only `contracts/` and the Foundry tests are copied; the old deploy scripts, deployment records, typechain bindings and Hardhat tests are not.
+
+## Build
+
+`pnpm build` compiles with the old compiler settings (`hardhat.config.cjs`) into `artifacts/` (EVM), `artifacts-zk/` (zkSync) and `artifacts-tron/` (Tron), which the package publishes for consumers to read by path, e.g. `@layerzerolabs/protocol-v2-oapp-evm-contracts/artifacts/contracts/<Source>.sol/<Contract>.json`.
+
+`../scripts/compare-artifacts.mjs` compares the compiled bytecode with the artifacts the old monorepo published.
+
+## Test
+
+`pnpm test` runs the Foundry tests.

package/contracts/oapp/OApp.sol

@@ -0,0 +1,39 @@
+// SPDX-License-Identifier: MIT
+
+pragma solidity ^0.8.20;
+
+// @dev Import the 'MessagingFee' and 'MessagingReceipt' so it's exposed to OApp implementers
+// solhint-disable-next-line no-unused-import
+import { OAppSender, MessagingFee, MessagingReceipt } from "./OAppSender.sol";
+// @dev Import the 'Origin' so it's exposed to OApp implementers
+// solhint-disable-next-line no-unused-import
+import { OAppReceiver, Origin } from "./OAppReceiver.sol";
+import { OAppCore } from "./OAppCore.sol";
+
+/**
+ * @title OApp
+ * @dev Abstract contract serving as the base for OApp implementation, combining OAppSender and OAppReceiver functionality.
+ */
+abstract contract OApp is OAppSender, OAppReceiver {
+    /**
+     * @dev Constructor to initialize the OApp with the provided endpoint and owner.
+     * @param _endpoint The address of the LOCAL LayerZero endpoint.
+     * @param _delegate The delegate capable of making OApp configurations inside of the endpoint.
+     */
+    constructor(address _endpoint, address _delegate) OAppCore(_endpoint, _delegate) {}
+
+    /**
+     * @notice Retrieves the OApp version information.
+     * @return senderVersion The version of the OAppSender.sol implementation.
+     * @return receiverVersion The version of the OAppReceiver.sol implementation.
+     */
+    function oAppVersion()
+        public
+        pure
+        virtual
+        override(OAppSender, OAppReceiver)
+        returns (uint64 senderVersion, uint64 receiverVersion)
+    {
+        return (SENDER_VERSION, RECEIVER_VERSION);
+    }
+}

package/contracts/oapp/OAppCore.sol

@@ -0,0 +1,83 @@
+// SPDX-License-Identifier: MIT
+
+pragma solidity ^0.8.20;
+
+import { Ownable } from "@openzeppelin/contracts/access/Ownable.sol";
+import { IOAppCore, ILayerZeroEndpointV2 } from "./interfaces/IOAppCore.sol";
+
+/**
+ * @title OAppCore
+ * @dev Abstract contract implementing the IOAppCore interface with basic OApp configurations.
+ */
+abstract contract OAppCore is IOAppCore, Ownable {
+    // The LayerZero endpoint associated with the given OApp
+    ILayerZeroEndpointV2 public immutable endpoint;
+
+    // Mapping to store peers associated with corresponding endpoints
+    mapping(uint32 eid => bytes32 peer) public peers;
+
+    /**
+     * @dev Constructor to initialize the OAppCore with the provided endpoint and delegate.
+     * @param _endpoint The address of the LOCAL Layer Zero endpoint.
+     * @param _delegate The delegate capable of making OApp configurations inside of the endpoint.
+     *
+     * @dev The delegate typically should be set as the owner of the contract.
+     */
+    constructor(address _endpoint, address _delegate) {
+        endpoint = ILayerZeroEndpointV2(_endpoint);
+
+        if (_delegate == address(0)) revert InvalidDelegate();
+        endpoint.setDelegate(_delegate);
+    }
+
+    /**
+     * @notice Sets the peer address (OApp instance) for a corresponding endpoint.
+     * @param _eid The endpoint ID.
+     * @param _peer The address of the peer to be associated with the corresponding endpoint.
+     *
+     * @dev Only the owner/admin of the OApp can call this function.
+     * @dev Indicates that the peer is trusted to send LayerZero messages to this OApp.
+     * @dev Set this to bytes32(0) to remove the peer address.
+     * @dev Peer is a bytes32 to accommodate non-evm chains.
+     */
+    function setPeer(uint32 _eid, bytes32 _peer) public virtual onlyOwner {
+        _setPeer(_eid, _peer);
+    }
+
+    /**
+     * @notice Sets the peer address (OApp instance) for a corresponding endpoint.
+     * @param _eid The endpoint ID.
+     * @param _peer The address of the peer to be associated with the corresponding endpoint.
+     *
+     * @dev Indicates that the peer is trusted to send LayerZero messages to this OApp.
+     * @dev Set this to bytes32(0) to remove the peer address.
+     * @dev Peer is a bytes32 to accommodate non-evm chains.
+     */
+    function _setPeer(uint32 _eid, bytes32 _peer) internal virtual {
+        peers[_eid] = _peer;
+        emit PeerSet(_eid, _peer);
+    }
+
+    /**
+     * @notice Internal function to get the peer address associated with a specific endpoint; reverts if NOT set.
+     * ie. the peer is set to bytes32(0).
+     * @param _eid The endpoint ID.
+     * @return peer The address of the peer associated with the specified endpoint.
+     */
+    function _getPeerOrRevert(uint32 _eid) internal view virtual returns (bytes32) {
+        bytes32 peer = peers[_eid];
+        if (peer == bytes32(0)) revert NoPeer(_eid);
+        return peer;
+    }
+
+    /**
+     * @notice Sets the delegate address for the OApp.
+     * @param _delegate The address of the delegate to be set.
+     *
+     * @dev Only the owner/admin of the OApp can call this function.
+     * @dev Provides the ability for a delegate to set configs, on behalf of the OApp, directly on the Endpoint contract.
+     */
+    function setDelegate(address _delegate) public onlyOwner {
+        endpoint.setDelegate(_delegate);
+    }
+}

package/contracts/oapp/OAppRead.sol

@@ -0,0 +1,18 @@
+// SPDX-License-Identifier: MIT
+
+pragma solidity ^0.8.20;
+
+import { AddressCast } from "@layerzerolabs/lz-evm-protocol-v2/contracts/libs/AddressCast.sol";
+
+import { OApp } from "./OApp.sol";
+
+abstract contract OAppRead is OApp {
+
+    constructor(address _endpoint, address _delegate) OApp(_endpoint, _delegate) {}
+
+    // -------------------------------
+    // Only Owner
+    function setReadChannel(uint32 _channelId, bool _active) public virtual onlyOwner {
+        _setPeer(_channelId, _active ? AddressCast.toBytes32(address(this)) : bytes32(0));
+    }
+}

package/contracts/oapp/OAppReceiver.sol

@@ -0,0 +1,122 @@
+// SPDX-License-Identifier: MIT
+
+pragma solidity ^0.8.20;
+
+import { IOAppReceiver, Origin } from "./interfaces/IOAppReceiver.sol";
+import { OAppCore } from "./OAppCore.sol";
+
+/**
+ * @title OAppReceiver
+ * @dev Abstract contract implementing the ILayerZeroReceiver interface and extending OAppCore for OApp receivers.
+ */
+abstract contract OAppReceiver is IOAppReceiver, OAppCore {
+    // Custom error message for when the caller is not the registered endpoint/
+    error OnlyEndpoint(address addr);
+
+    // @dev The version of the OAppReceiver implementation.
+    // @dev Version is bumped when changes are made to this contract.
+    uint64 internal constant RECEIVER_VERSION = 2;
+
+    /**
+     * @notice Retrieves the OApp version information.
+     * @return senderVersion The version of the OAppSender.sol contract.
+     * @return receiverVersion The version of the OAppReceiver.sol contract.
+     *
+     * @dev Providing 0 as the default for OAppSender version. Indicates that the OAppSender is not implemented.
+     * ie. this is a RECEIVE only OApp.
+     * @dev If the OApp uses both OAppSender and OAppReceiver, then this needs to be override returning the correct versions.
+     */
+    function oAppVersion() public view virtual returns (uint64 senderVersion, uint64 receiverVersion) {
+        return (0, RECEIVER_VERSION);
+    }
+
+    /**
+     * @notice Indicates whether an address is an approved composeMsg sender to the Endpoint.
+     * @dev _origin The origin information containing the source endpoint and sender address.
+     *  - srcEid: The source chain endpoint ID.
+     *  - sender: The sender address on the src chain.
+     *  - nonce: The nonce of the message.
+     * @dev _message The lzReceive payload.
+     * @param _sender The sender address.
+     * @return isSender Is a valid sender.
+     *
+     * @dev Applications can optionally choose to implement separate composeMsg senders that are NOT the bridging layer.
+     * @dev The default sender IS the OAppReceiver implementer.
+     */
+    function isComposeMsgSender(
+        Origin calldata /*_origin*/,
+        bytes calldata /*_message*/,
+        address _sender
+    ) public view virtual returns (bool) {
+        return _sender == address(this);
+    }
+
+    /**
+     * @notice Checks if the path initialization is allowed based on the provided origin.
+     * @param origin The origin information containing the source endpoint and sender address.
+     * @return Whether the path has been initialized.
+     *
+     * @dev This indicates to the endpoint that the OApp has enabled msgs for this particular path to be received.
+     * @dev This defaults to assuming if a peer has been set, its initialized.
+     * Can be overridden by the OApp if there is other logic to determine this.
+     */
+    function allowInitializePath(Origin calldata origin) public view virtual returns (bool) {
+        return peers[origin.srcEid] == origin.sender;
+    }
+
+    /**
+     * @notice Retrieves the next nonce for a given source endpoint and sender address.
+     * @dev _srcEid The source endpoint ID.
+     * @dev _sender The sender address.
+     * @return nonce The next nonce.
+     *
+     * @dev The path nonce starts from 1. If 0 is returned it means that there is NO nonce ordered enforcement.
+     * @dev Is required by the off-chain executor to determine the OApp expects msg execution is ordered.
+     * @dev This is also enforced by the OApp.
+     * @dev By default this is NOT enabled. ie. nextNonce is hardcoded to return 0.
+     */
+    function nextNonce(uint32 /*_srcEid*/, bytes32 /*_sender*/) public view virtual returns (uint64 nonce) {
+        return 0;
+    }
+
+    /**
+     * @dev Entry point for receiving messages or packets from the endpoint.
+     * @param _origin The origin information containing the source endpoint and sender address.
+     *  - srcEid: The source chain endpoint ID.
+     *  - sender: The sender address on the src chain.
+     *  - nonce: The nonce of the message.
+     * @param _guid The unique identifier for the received LayerZero message.
+     * @param _message The payload of the received message.
+     * @param _executor The address of the executor for the received message.
+     * @param _extraData Additional arbitrary data provided by the corresponding executor.
+     *
+     * @dev Entry point for receiving msg/packet from the LayerZero endpoint.
+     */
+    function lzReceive(
+        Origin calldata _origin,
+        bytes32 _guid,
+        bytes calldata _message,
+        address _executor,
+        bytes calldata _extraData
+    ) public payable virtual {
+        // Ensures that only the endpoint can attempt to lzReceive() messages to this OApp.
+        if (address(endpoint) != msg.sender) revert OnlyEndpoint(msg.sender);
+
+        // Ensure that the sender matches the expected peer for the source endpoint.
+        if (_getPeerOrRevert(_origin.srcEid) != _origin.sender) revert OnlyPeer(_origin.srcEid, _origin.sender);
+
+        // Call the internal OApp implementation of lzReceive.
+        _lzReceive(_origin, _guid, _message, _executor, _extraData);
+    }
+
+    /**
+     * @dev Internal function to implement lzReceive logic without needing to copy the basic parameter validation.
+     */
+    function _lzReceive(
+        Origin calldata _origin,
+        bytes32 _guid,
+        bytes calldata _message,
+        address _executor,
+        bytes calldata _extraData
+    ) internal virtual;
+}

package/contracts/oapp/OAppSender.sol

@@ -0,0 +1,124 @@
+// SPDX-License-Identifier: MIT
+
+pragma solidity ^0.8.20;
+
+import { SafeERC20, IERC20 } from "@openzeppelin/contracts/token/ERC20/utils/SafeERC20.sol";
+import { MessagingParams, MessagingFee, MessagingReceipt } from "@layerzerolabs/lz-evm-protocol-v2/contracts/interfaces/ILayerZeroEndpointV2.sol";
+import { OAppCore } from "./OAppCore.sol";
+
+/**
+ * @title OAppSender
+ * @dev Abstract contract implementing the OAppSender functionality for sending messages to a LayerZero endpoint.
+ */
+abstract contract OAppSender is OAppCore {
+    using SafeERC20 for IERC20;
+
+    // Custom error messages
+    error NotEnoughNative(uint256 msgValue);
+    error LzTokenUnavailable();
+
+    // @dev The version of the OAppSender implementation.
+    // @dev Version is bumped when changes are made to this contract.
+    uint64 internal constant SENDER_VERSION = 1;
+
+    /**
+     * @notice Retrieves the OApp version information.
+     * @return senderVersion The version of the OAppSender.sol contract.
+     * @return receiverVersion The version of the OAppReceiver.sol contract.
+     *
+     * @dev Providing 0 as the default for OAppReceiver version. Indicates that the OAppReceiver is not implemented.
+     * ie. this is a SEND only OApp.
+     * @dev If the OApp uses both OAppSender and OAppReceiver, then this needs to be override returning the correct versions
+     */
+    function oAppVersion() public view virtual returns (uint64 senderVersion, uint64 receiverVersion) {
+        return (SENDER_VERSION, 0);
+    }
+
+    /**
+     * @dev Internal function to interact with the LayerZero EndpointV2.quote() for fee calculation.
+     * @param _dstEid The destination endpoint ID.
+     * @param _message The message payload.
+     * @param _options Additional options for the message.
+     * @param _payInLzToken Flag indicating whether to pay the fee in LZ tokens.
+     * @return fee The calculated MessagingFee for the message.
+     *      - nativeFee: The native fee for the message.
+     *      - lzTokenFee: The LZ token fee for the message.
+     */
+    function _quote(
+        uint32 _dstEid,
+        bytes memory _message,
+        bytes memory _options,
+        bool _payInLzToken
+    ) internal view virtual returns (MessagingFee memory fee) {
+        return
+            endpoint.quote(
+                MessagingParams(_dstEid, _getPeerOrRevert(_dstEid), _message, _options, _payInLzToken),
+                address(this)
+            );
+    }
+
+    /**
+     * @dev Internal function to interact with the LayerZero EndpointV2.send() for sending a message.
+     * @param _dstEid The destination endpoint ID.
+     * @param _message The message payload.
+     * @param _options Additional options for the message.
+     * @param _fee The calculated LayerZero fee for the message.
+     *      - nativeFee: The native fee.
+     *      - lzTokenFee: The lzToken fee.
+     * @param _refundAddress The address to receive any excess fee values sent to the endpoint.
+     * @return receipt The receipt for the sent message.
+     *      - guid: The unique identifier for the sent message.
+     *      - nonce: The nonce of the sent message.
+     *      - fee: The LayerZero fee incurred for the message.
+     */
+    function _lzSend(
+        uint32 _dstEid,
+        bytes memory _message,
+        bytes memory _options,
+        MessagingFee memory _fee,
+        address _refundAddress
+    ) internal virtual returns (MessagingReceipt memory receipt) {
+        // @dev Push corresponding fees to the endpoint, any excess is sent back to the _refundAddress from the endpoint.
+        uint256 messageValue = _payNative(_fee.nativeFee);
+        if (_fee.lzTokenFee > 0) _payLzToken(_fee.lzTokenFee);
+
+        return
+            // solhint-disable-next-line check-send-result
+            endpoint.send{ value: messageValue }(
+                MessagingParams(_dstEid, _getPeerOrRevert(_dstEid), _message, _options, _fee.lzTokenFee > 0),
+                _refundAddress
+            );
+    }
+
+    /**
+     * @dev Internal function to pay the native fee associated with the message.
+     * @param _nativeFee The native fee to be paid.
+     * @return nativeFee The amount of native currency paid.
+     *
+     * @dev If the OApp needs to initiate MULTIPLE LayerZero messages in a single transaction,
+     * this will need to be overridden because msg.value would contain multiple lzFees.
+     * @dev Should be overridden in the event the LayerZero endpoint requires a different native currency.
+     * @dev Some EVMs use an ERC20 as a method for paying transactions/gasFees.
+     * @dev The endpoint is EITHER/OR, ie. it will NOT support both types of native payment at a time.
+     */
+    function _payNative(uint256 _nativeFee) internal virtual returns (uint256 nativeFee) {
+        if (msg.value != _nativeFee) revert NotEnoughNative(msg.value);
+        return _nativeFee;
+    }
+
+    /**
+     * @dev Internal function to pay the LZ token fee associated with the message.
+     * @param _lzTokenFee The LZ token fee to be paid.
+     *
+     * @dev If the caller is trying to pay in the specified lzToken, then the lzTokenFee is passed to the endpoint.
+     * @dev Any excess sent, is passed back to the specified _refundAddress in the _lzSend().
+     */
+    function _payLzToken(uint256 _lzTokenFee) internal virtual {
+        // @dev Cannot cache the token because it is not immutable in the endpoint.
+        address lzToken = endpoint.lzToken();
+        if (lzToken == address(0)) revert LzTokenUnavailable();
+
+        // Pay LZ token fee by sending tokens to the endpoint.
+        IERC20(lzToken).safeTransferFrom(msg.sender, address(endpoint), _lzTokenFee);
+    }
+}

package/contracts/oapp/examples/CmdCodecV1Mock.sol

@@ -0,0 +1,31 @@
+// SPDX-License-Identifier: UNLICENSED
+pragma solidity ^0.8.0;
+
+import { EVMCallRequestV1, EVMCallComputeV1, ReadCmdCodecV1 } from "../libs/ReadCmdCodecV1.sol";
+
+contract CmdCodecV1Mock {
+    function decode(
+        bytes calldata _cmd
+    )
+        external
+        pure
+        returns (uint16 appCmdLabel, EVMCallRequestV1[] memory evmRequests, EVMCallComputeV1 memory compute)
+    {
+        return ReadCmdCodecV1.decode(_cmd);
+    }
+
+    function encode(
+        uint16 _appCmdLabel,
+        EVMCallRequestV1[] calldata _evmRequests
+    ) external pure returns (bytes memory) {
+        return ReadCmdCodecV1.encode(_appCmdLabel, _evmRequests);
+    }
+
+    function encode(
+        uint16 _appCmdLabel,
+        EVMCallRequestV1[] calldata _evmRequests,
+        EVMCallComputeV1 calldata _evmCompute
+    ) external pure returns (bytes memory) {
+        return ReadCmdCodecV1.encode(_appCmdLabel, _evmRequests, _evmCompute);
+    }
+}

package/contracts/oapp/examples/LzReadCounter.sol

@@ -0,0 +1,160 @@
+// SPDX-License-Identifier: MIT
+
+pragma solidity ^0.8.20;
+
+import { ILayerZeroEndpointV2, MessagingFee, MessagingReceipt, Origin } from "@layerzerolabs/lz-evm-protocol-v2/contracts/interfaces/ILayerZeroEndpointV2.sol";
+import { ReadCmdCodecV1, EVMCallComputeV1, EVMCallRequestV1 } from "../libs/ReadCmdCodecV1.sol";
+import { IOAppComputer } from "../interfaces/IOAppComputer.sol";
+
+import { OAppRead } from "../OAppRead.sol";
+
+contract LzReadCounter is OAppRead, IOAppComputer {
+    struct EvmReadRequest {
+        uint16 appRequestLabel;
+        uint32 targetEid;
+        bool isBlockNum;
+        uint64 blockNumOrTimestamp;
+        uint16 confirmations;
+        address to;
+        uint256 countAddition; // addition to add to the count when reading
+    }
+
+    struct ComputeSetting {
+        uint8 computeSetting;
+        uint16 computeConfirmations;
+        uint64 blockNumOrTimestamp;
+        bool isBlockNum;
+    }
+
+    uint8 internal constant COMPUTE_SETTING_MAP_ONLY = 0;
+    uint8 internal constant COMPUTE_SETTING_REDUCE_ONLY = 1;
+    uint8 internal constant COMPUTE_SETTING_MAP_REDUCE = 2;
+    uint8 internal constant COMPUTE_SETTING_NONE = 3;
+
+    uint32 public immutable eid;
+    uint256 public count;
+
+    constructor(address _endpoint) OAppRead(_endpoint, msg.sender) {
+        eid = ILayerZeroEndpointV2(_endpoint).eid();
+    }
+
+    // -------------------------------
+    // Trigger Read
+    function triggerRead(
+        uint32 _channelId, // The read channel id
+        uint16 _appLabel, // The cmd app label
+        EvmReadRequest[] memory _requests,
+        ComputeSetting memory _computeSetting,
+        bytes calldata _options
+    ) external payable returns (MessagingReceipt memory receipt) {
+        bytes memory cmd = buildCmd(_appLabel, _requests, _computeSetting);
+        count += 1; // increase the count, for pin block testing
+        return _lzSend(_channelId, cmd, _options, MessagingFee(msg.value, 0), payable(msg.sender));
+    }
+
+    function clearCount() external {
+        count = 0;
+    }
+
+    // -------------------------------
+    // View
+    function quote(
+        uint32 _channelId,
+        uint16 _appLabel,
+        EvmReadRequest[] memory _requests,
+        ComputeSetting memory _computeSetting,
+        bytes calldata _options
+    ) public view returns (uint256 nativeFee, uint256 lzTokenFee) {
+        bytes memory cmd = buildCmd(_appLabel, _requests, _computeSetting);
+        MessagingFee memory fee = _quote(_channelId, cmd, _options, false);
+        return (fee.nativeFee, fee.lzTokenFee);
+    }
+
+    function buildCmd(
+        uint16 appLabel,
+        EvmReadRequest[] memory _readRequests,
+        ComputeSetting memory _computeSetting
+    ) public view returns (bytes memory) {
+        require(_readRequests.length > 0, "LzReadCounter: empty requests");
+        // build read requests
+        EVMCallRequestV1[] memory readRequests = new EVMCallRequestV1[](_readRequests.length);
+        for (uint256 i = 0; i < _readRequests.length; i++) {
+            EvmReadRequest memory req = _readRequests[i];
+            readRequests[i] = EVMCallRequestV1({
+                appRequestLabel: req.appRequestLabel,
+                targetEid: req.targetEid,
+                isBlockNum: req.isBlockNum,
+                blockNumOrTimestamp: req.blockNumOrTimestamp,
+                confirmations: req.confirmations,
+                to: req.to,
+                callData: abi.encodeWithSelector(this.readCount.selector, req.countAddition)
+            });
+        }
+        // build compute, on current contract
+        require(_computeSetting.computeSetting <= COMPUTE_SETTING_NONE, "LzReadCounter: invalid compute type");
+        EVMCallComputeV1 memory evmCompute = EVMCallComputeV1({
+            computeSetting: _computeSetting.computeSetting,
+            targetEid: _computeSetting.computeSetting == COMPUTE_SETTING_NONE ? 0 : eid, // 0(means no compute) for none, else use local eid
+            isBlockNum: _computeSetting.isBlockNum,
+            blockNumOrTimestamp: _computeSetting.blockNumOrTimestamp,
+            confirmations: _computeSetting.computeConfirmations,
+            to: address(this)
+        });
+        bytes memory cmd = ReadCmdCodecV1.encode(appLabel, readRequests, evmCompute);
+
+        return cmd;
+    }
+
+    function readCount(uint256 countAddition) external view returns (uint256) {
+        require(countAddition != 9, "LzReadCounter: invalid count addition"); // This is only for testing
+        return count + countAddition;
+    }
+
+    function lzMap(bytes calldata _request, bytes calldata _response) external pure returns (bytes memory) {
+        require(_response.length == 32, "LzReadCounter: invalid response length");
+        uint16 requestId = ReadCmdCodecV1.decodeRequestV1AppRequestLabel(_request);
+        uint256 countNum = abi.decode(_response, (uint256));
+        return abi.encode(countNum + 100 + requestId * 1000); // map behavior
+    }
+
+    function lzReduce(bytes calldata _cmd, bytes[] calldata _responses) external pure returns (bytes memory) {
+        uint256 total = 0;
+        for (uint256 i = 0; i < _responses.length; i++) {
+            require(_responses[i].length == 32, "LzReadCounter: invalid response length");
+            uint256 countNum = abi.decode(_responses[i], (uint256));
+            total += countNum;
+        }
+        total += 10000; // reduce behavior
+
+        uint16 cmdAppLabel = ReadCmdCodecV1.decodeCmdAppLabel(_cmd);
+        total += uint256(cmdAppLabel) * 100000; // cmdAppLabel behavior
+
+        return abi.encode(total);
+    }
+
+    // -------------------------------
+    function _lzReceive(
+        Origin calldata /* _origin */,
+        bytes32 /* _guid */,
+        bytes calldata _message,
+        address /*_executor*/,
+        bytes calldata /*_extraData*/
+    ) internal override {
+        require(_message.length % 32 == 0, "LzReadCounter: invalid message length");
+        uint256 total = 0;
+        // loop read bytes32 of the message and decode it to uint256 then add it to the total
+        for (uint256 i = 0; i < _message.length; i += 32) {
+            total += abi.decode(_message[i:i + 32], (uint256));
+        }
+        // reset count if it's too large
+        if (count >= 2 ** 128) {
+            count = 0;
+        }
+        count += total;
+    }
+
+    // be able to receive ether
+    receive() external payable virtual {}
+
+    fallback() external payable {}
+}

package/contracts/oapp/examples/OmniCounter.sol

@@ -0,0 +1,15 @@
+// SPDX-License-Identifier: UNLICENSED
+pragma solidity ^0.8.20;
+
+// @dev Oz5 implementation
+// import { Ownable } from "@openzeppelin/contracts/access/Ownable.sol";
+
+import { OmniCounterAbstract, MsgCodec } from "./OmniCounterAbstract.sol";
+
+contract OmniCounter is OmniCounterAbstract {
+    // @dev Oz4 implementation
+    constructor(address _endpoint, address _delegate) OmniCounterAbstract(_endpoint, _delegate) {}
+
+    // @dev Oz5 implementation
+    //    constructor(address _endpoint, address _delegate) OmniCounterAbstract(_endpoint, _delegate) Ownable(_delegate) {}
+}