@layerzerolabs/layerzero-v2-ton 3.0.19-ton.0 → 3.0.21-ton.0

package/src/protocol/channel/handler.fc

@@ -0,0 +1,1054 @@
+#include "callbackOpcodes.fc";
+
+#include "../core/abstract/protocolHandler.fc";
+
+#include "../../funC++/actions/dispatch.fc";
+#include "../../funC++/actions/event.fc";
+
+#include "../../classes/lz/EpConfig.fc";
+#include "../../classes/lz/Packet.fc";
+#include "../../classes/lz/Path.fc";
+#include "../../classes/lz/ReceiveEpConfig.fc";
+#include "../../classes/lz/SendEpConfig.fc";
+
+#include "../../classes/msgdata/ChannelNonceInfo.fc";
+#include "../../classes/msgdata/CoinsAmount.fc";
+#include "../../classes/msgdata/ExtendedMd.fc";
+#include "../../classes/msgdata/LzReceivePrepare.fc";
+#include "../../classes/msgdata/LzReceiveStatus.fc";
+#include "../../classes/msgdata/LzReceivePrepare.fc";
+#include "../../classes/msgdata/LzSend.fc";
+#include "../../classes/msgdata/MdAddress.fc";
+#include "../../classes/msgdata/MdObj.fc";
+#include "../../classes/msgdata/MessagingReceipt.fc";
+#include "../../classes/msgdata/MsglibSendCallback.fc";
+#include "../../classes/msgdata/Nonce.fc";
+#include "../../classes/msgdata/PacketId.fc";
+#include "../../classes/msgdata/PacketSent.fc";
+
+
+#include "../../funC++/dataStructures/DeterministicInsertionCircularQueue.fc";
+#include "../../funC++/dataStructures/PipelinedOutOfOrder.fc";
+
+#include "../interfaces.fc";
+#include "../msglibs/interface.fc";
+#include "interface.fc";
+#include "storage.fc";
+
+;;; ================INTERFACE FUNCTIONS=====================
+
+int _getEventSink() inline {
+    return getContractStorage()
+        .cl::get<objRef>(Channel::baseStorage)
+        .cl::get<address>(BaseStorage::owner);
+}
+
+;;; ==========================HELPER FUNCTIONS=====================================
+
+() _assertEqualPaths(cell $path1, cell $path2) impure inline {
+    throw_unless(Channel::ERROR::wrongPath, $path1.cl::hash() == $path2.cl::hash());
+}
+
+;; @info The send request queue (Channel::sendRequestQueue) is a DeterministicInsertionCircularQueue
+;; that stores a mapping from requestId => hash of LzSend object.
+;; {_build, _read}SendRequestQueueEntry functions are helper functions that
+;; serialize and deserialize the 256-bit hash that is stored in the DICQueue
+cell _buildSendRequestQueueEntry(cell $lzSend) inline method_id {
+    return begin_cell().store_uint256($lzSend.cl::hash()).end_cell();
+}
+
+int _readSendRequestQueueEntry(cell contents) inline method_id {
+    if (contents.is_null()) {
+        return 0;
+    } elseif (contents.cell_is_empty()) {
+        return 0;
+    }
+    return contents.begin_parse().preload_uint(256);
+}
+
+;; returns boolean committable, (packet or null)
+(int, cell) _nonceCommittable(int incomingNonce) impure inline method_id {
+    throw_if(Channel::ERROR::invalidNonce, incomingNonce <= 0);
+
+    cell $storage = getContractStorage();
+
+    cell $executePOOO = $storage.cl::get<objRef>(Channel::executePOOO);
+    int firstUnexecutedNonce = $executePOOO.cl::get<uint64>(POOO::nextEmpty);
+
+    (int actualKey, cell $packet, int status, int exists) = DeterministicInsertionCircularQueue::get(
+        $storage.cl::get<cellRef>(Channel::executionQueue),
+        incomingNonce
+    );
+
+    if (
+        (incomingNonce == firstUnexecutedNonce)
+        & (actualKey == incomingNonce)
+        & (status != ExecutionQueue::executing)
+    ) {
+        ;; short-circuit for efficiency in the common case
+        return (true, exists ? $packet : null());
+    }
+
+    ;; condition 1 & 2: must be within the window
+    ;; condition 3: must not be executing
+    if (
+        (incomingNonce >= firstUnexecutedNonce)
+        & (incomingNonce <= POOO::maxSettableBit($executePOOO))
+        & (status != ExecutionQueue::executing)
+    ) {
+        ;; this is nested because funC doesn't support short-circuiting boolean/bitwise ops
+        ;; condition 4: must not be executed
+        ifnot (POOO::isBitSet($executePOOO, incomingNonce)) {
+            return (true, exists ? $packet : null());
+        }
+    }
+
+    return (false, null());
+}
+
+cell _getExecutablePacket(int incomingNonce) impure inline method_id {
+    (int isCommittable, cell $packet) = _nonceCommittable(incomingNonce);
+    int firstUncommittedNonce = getContractStorage()
+        .cl::get<objRef>(Channel::commitPOOO)
+        .cl::get<uint64>(POOO::nextEmpty);
+
+    throw_if(
+        Channel::ERROR::notExecutable,
+        ((~ isCommittable) | (incomingNonce >= firstUncommittedNonce) | $packet.is_null())
+    );
+
+    return $packet;
+}
+
+() _assertNonceCommittable(int incomingNonce) impure inline {
+    ;; Split into multiple lines to fix false-positive linter warning
+    (
+        int isCommittable,
+        _
+    ) = _nonceCommittable(incomingNonce);
+
+    throw_unless(Channel::ERROR::notCommittable, isCommittable);
+}
+
+;;; ==========================VIEW FUNCTIONS=====================================
+
+int _viewInboundNonce() impure method_id {
+    return getContractStorage()
+        .cl::get<objRef>(Channel::commitPOOO)
+        .cl::get<uint64>(POOO::nextEmpty) - 1;
+}
+
+int _viewExecutionStatus(int incomingNonce) impure method_id {
+    cell $storage = getContractStorage();
+
+    cell $executePOOO = $storage.cl::get<objRef>(Channel::executePOOO);
+    int firstUnexecutedNonce = $executePOOO.cl::get<uint64>(POOO::nextEmpty);
+    cell $commitPOOO = $storage.cl::get<objRef>(Channel::commitPOOO);
+    int firstUncommittedNonce = $commitPOOO.cl::get<uint64>(POOO::nextEmpty);
+    int inboundNonce = _viewInboundNonce();
+
+    int executed = incomingNonce < firstUnexecutedNonce;
+    if ((~ executed) & (incomingNonce < (firstUnexecutedNonce + MAX_CELL_BITS))) {
+        executed = executed | $executePOOO.POOO::isBitSet(incomingNonce);
+    }
+
+    int committed = incomingNonce < firstUncommittedNonce;
+    if ((~ committed) & (incomingNonce < (firstUncommittedNonce + MAX_CELL_BITS))) {
+        committed = committed | $commitPOOO.POOO::isBitSet(incomingNonce);
+    }
+
+    ifnot (committed) {
+        return ExecutionStatus::uncommitted;
+    } elseif (executed) {
+        return ExecutionStatus::executed;
+    }
+
+    (_, _, int status, _) = DeterministicInsertionCircularQueue::get(
+        $storage.cl::get<cellRef>(Channel::executionQueue),
+        incomingNonce
+    );
+    if (status == ExecutionQueue::executing) {
+        return ExecutionStatus::executing;
+    } elseif (incomingNonce <= inboundNonce) {
+        return ExecutionStatus::executable;
+    }
+    return ExecutionStatus::committedNotExecutable;
+}
+
+;;; ================INTERFACE FUNCTIONS=====================
+
+(cell, tuple) _initialize(cell $md) impure inline {
+    (cell $storage, tuple actions) = preamble();
+    cell $path = $storage.cl::get<objRef>(Channel::path);
+
+    throw_if(
+        Channel::ERROR::wrongPath,
+        ($path.cl::get<uint32>(lz::Path::srcEid) == 0)
+        | ($path.cl::get<address>(lz::Path::srcOApp) == NULLADDRESS)
+        | ($path.cl::get<uint32>(lz::Path::dstEid) == 0)
+        | ($path.cl::get<address>(lz::Path::dstOApp) == NULLADDRESS)
+    );
+
+    return (
+        $storage
+            .cl::set(Channel::executionQueue, DeterministicInsertionCircularQueue::create())
+            .cl::set(Channel::sendRequestQueue, DeterministicInsertionCircularQueue::create()),
+        actions
+    );
+}
+
+;;; ================PERMISSION FUNCTIONS=====================
+
+() _assertEndpoint() impure inline {
+    throw_unless(
+        Channel::ERROR::onlyEndpoint,
+        getCaller() == getContractStorage().cl::get<address>(Channel::endpointAddress)
+    );
+}
+
+;; this function is purposely designed to be maximally efficient when using a
+;; custom configuration and less efficient when using a default configuration
+() _assertSendMsglib(cell $mdAddress) impure inline {
+    cell epConfigOApp = getContractStorage().cl::get<objRef>(Channel::epConfigOApp);
+
+    ;; Resolve the actual sendMsglib address at the time of request.
+    ;; This function assumes the messagelib is not malicious or man-in-the-middle attacking,
+    ;; as those cases are asserted in the handler itself.
+    int sendMsglibAddress = $mdAddress
+            .cl::get<objRef>(md::MdAddress::md)
+            .cl::get<objRef>(md::MsglibSendCallback::lzSend)
+            .cl::get<address>(md::LzSend::sendMsglib);
+
+    throw_unless(Channel::ERROR::onlyApprovedSendMsglib, getCaller() == sendMsglibAddress);
+}
+
+() _assertOApp() impure inline {
+    throw_unless(
+        Channel::ERROR::onlyOApp,
+        getCaller() == getContractStorage()
+            .cl::get<objRef>(Channel::path)
+            .cl::get<uint256>(lz::Path::srcOApp)
+    );
+}
+
+() _checkPermissions(int op, cell $md) impure inline {
+    if (op == Channel::OP::LZ_RECEIVE_PREPARE) {
+        ;; open and public calls
+        return ();
+    } elseif (
+        (op == Channel::OP::CHANNEL_SEND)
+        | (op == Channel::OP::CHANNEL_COMMIT_PACKET)
+    ) {
+        return _assertEndpoint();
+    } elseif (op == Channel::OP::MSGLIB_SEND_CALLBACK) {
+        return _assertSendMsglib($md);
+    } elseif (
+        (op == Channel::OP::LZ_RECEIVE_LOCK)
+        | (op == Channel::OP::LZ_RECEIVE_EXECUTE_CALLBACK)
+    ) {
+        return _assertOApp();
+    } elseif (op == Channel::OP::DEPOSIT_ZRO) {
+        return assertOwner();
+    } elseif (
+        (op == Channel::OP::NOTIFY_PACKET_EXECUTED)
+        | (op == Channel::OP::SYNC_MSGLIB_CONNECTION)
+    ) {
+        return ();
+    } elseif (op == Channel::OP::SET_EP_CONFIG_OAPP) {
+        return _assertEndpoint();
+    } elseif (
+        ;; Management functions are all gated by OApp
+        (op == Channel::OP::NILIFY)
+        | (op == Channel::OP::BURN)
+        | (op == Channel::OP::FORCE_ABORT)
+    ) {
+       return _assertOApp();
+    } elseif (op == Channel::OP::EMIT_LZ_RECEIVE_ALERT) {
+        return ();
+    } else {
+        ;; we must put a check for all opcodes to make sure we don't
+        ;; mistakenly miss an opp code's permissions
+        throw(BaseInterface::ERROR::invalidOpcode);
+    }
+}
+
+;;; ==========================HANDLERS=====================================
+
+;; @in endpoint/handler.fc/setEpConfig
+;; @out controller/handler.fc/emit_event
+;; @md EpConfig
+tuple setEpConfigOApp(cell $epConfigOApp) impure inline method_id {
+    (cell $storage, tuple actions) = preamble();
+
+    int configValidity = $epConfigOApp.lz::EpConfig::isValid();
+    throw_if(configValidity, configValidity != lz::EpConfig::VALID);
+
+    setContractStorage($storage.cl::set(Channel::epConfigOApp, $epConfigOApp));
+
+    actions~pushAction<event>(Channel::event::EP_CFG_OAPP_SET, $epConfigOApp);
+    return actions;
+}
+
+;;; ==========================================
+;; Send flow
+;; @in: endpoint/handler.fc/quote
+;; @in_md: MdObj(lzSend, defaultEpConfig)
+;; @out: msglib/handler.fc/quote
+;; @out_md: $lzSend
+tuple channelSend(cell $mdObj) impure inline method_id {
+    (cell $storage, tuple actions) = preamble();
+
+    cell $lzSend = $mdObj.cl::get<objRef>(md::MdObj::md);
+    ;; assert the size and structure of the incoming lzSend message
+    lz::Packet::assertValidSendMessage($lzSend.cl::get<objRef>(md::LzSend::packet));
+
+    ;; Resolve the desired send msglib and send msglib connection
+    cell $epConfigOApp = $storage.cl::get<objRef>(Channel::epConfigOApp);
+    int sendMsglib = $epConfigOApp.cl::get<address>(lz::EpConfig::sendMsglib);
+    int sendMsglibConnection = $epConfigOApp.cl::get<address>(lz::EpConfig::sendMsglibConnection);
+    cell $sendPath = $storage.cl::get<objRef>(Channel::path);
+
+    if ($epConfigOApp.cl::get<bool>(lz::EpConfig::isNull)) {
+        cell $defaultSendEpConfig = $mdObj.cl::get<objRef>(md::MdObj::obj);
+
+        sendMsglib = $defaultSendEpConfig.cl::get<address>(lz::SendEpConfig::sendMsglibAddress);
+
+        sendMsglibConnection = $defaultSendEpConfig
+            .cl::get<address>(lz::SendEpConfig::sendMsglibConnectionAddress);
+    }
+
+    if ((sendMsglib == NULLADDRESS) | (sendMsglibConnection == NULLADDRESS)) {
+        actions~pushAction<call>(
+            $sendPath.cl::get<address>(lz::Path::srcOApp),
+            Layerzero::OP::CHANNEL_SEND_CALLBACK,
+            md::MdObj::New(
+                md::MessagingReceipt::New(
+                    $lzSend,
+                    0,
+                    0,
+                    Channel::ERROR::MsglibBlocked
+                ),
+                getInitialStorage()
+            )
+        );
+        return actions;
+    }
+
+    ;; Each send request is assigned a unique request ID, which is also used as the key into
+    ;; the sendRequestQueue
+    int curRequestId = $storage.cl::get<uint64>(Channel::lastSendRequestId) + 1;
+
+    $lzSend = md::lzSend::fillRequestInfo($lzSend, curRequestId, sendMsglib, sendMsglibConnection);
+
+    cell sendRequestQueue = $storage.cl::get<cellRef>(Channel::sendRequestQueue);
+    (_, _, _, int exists) = DeterministicInsertionCircularQueue::get(sendRequestQueue, curRequestId);
+    ifnot (exists) {
+        ;; submit to the msglib
+        setContractStorage(
+            $storage
+                .cl::set(Channel::lastSendRequestId, curRequestId)
+                .cl::set(
+                    Channel::sendRequestQueue,
+                    DeterministicInsertionCircularQueue::set(
+                        sendRequestQueue,
+                        curRequestId,
+                        _buildSendRequestQueueEntry($lzSend),
+                        SendRequestQueue::sending
+                    )
+                )
+        );
+
+        actions~pushAction<call>(
+            sendMsglibConnection,
+            MsglibConnection::OP::MSGLIB_CONNECTION_SEND,
+            $lzSend
+        );
+    } else {
+        ;; callback to the oApp with a failure and emit an event
+        actions~pushAction<event>(Channel::ERROR::sendQueueCongested, $lzSend);
+        actions~pushAction<call>(
+            $storage.cl::get<objRef>(Channel::path).cl::get<address>(lz::Path::srcOApp),
+            Layerzero::OP::CHANNEL_SEND_CALLBACK,
+            md::MdObj::New(
+                md::MessagingReceipt::New($lzSend, 0, 0, Channel::ERROR::sendQueueCongested),
+                getInitialStorage()
+            )
+        );
+    }
+
+    return actions;
+}
+
+;; in: msglib/handler.fc/msglibSend
+;; in_md: MsglibSendCallback
+;; out: OApp/handler.fc/sendCallback
+tuple msglibSendCallback(cell $mdAddress) impure inline method_id {
+    (cell $storage, tuple actions) = preamble();
+
+    cell $mdMsglibSendCallback = $mdAddress.cl::get<objRef>(md::MdAddress::md);
+
+    int errorCode = $mdMsglibSendCallback.cl::get<uint8>(md::MsglibSendCallback::errorCode);
+
+    cell $lzSend = $mdMsglibSendCallback.cl::get<objRef>(md::MsglibSendCallback::lzSend);
+    cell sendRequestQueue = $storage.cl::get<cellRef>(Channel::sendRequestQueue);
+
+    int requestId = $lzSend.cl::get<uint64>(md::LzSend::sendRequestId);
+
+    ;; Read the requestId from the sendRequestQueue to ensure this send request is genuine
+    ;; and is not being double-executed
+    (_, cell contents, _, int exists) = DeterministicInsertionCircularQueue::get(
+        sendRequestQueue,
+        requestId
+    );
+
+    if (exists) {
+        if (_readSendRequestQueueEntry(contents) == $lzSend.cl::hash()) {
+            $storage = $storage.cl::set(
+                Channel::sendRequestQueue,
+                DeterministicInsertionCircularQueue::delete(sendRequestQueue, requestId)
+            );
+        } else {
+            ;; See below comment, this else case is logically the same as the below else block,
+            ;; but needs to be split due to lack of short-circuiting boolean expressions in funC
+            return actions;
+        }
+    } else {
+        ;; if the send request doesn't exist, there are two cases
+        ;; 1. a legitimate request was frontrun by a force-abort
+        ;;  in this case, we can safely refund all the funds to the origin
+        ;; 2. a malicious MITM attack by ULN
+        ;;  in this case, we can't refund the funds, but we can still emit an event
+
+        ;; This technically silently reverts, by not processing any output actions,
+        ;; thus providing a refund, instead of hard reverting
+        return actions;
+    }
+
+    ;; verify that cumulative fees quoted by the msglib <= the fee cap specified by the user/app
+    int zroQuote = $mdMsglibSendCallback.cl::get<coins>(md::MsglibSendCallback::zroFee);
+    int nativeQuote = $mdMsglibSendCallback.cl::get<coins>(md::MsglibSendCallback::nativeFee);
+
+    if ($lzSend.cl::get<coins>(md::LzSend::nativeFee) < nativeQuote) {
+        errorCode = Channel::ERROR::notEnoughNative;
+    }
+    if ($lzSend.cl::get<coins>(md::LzSend::zroFee) < zroQuote) {
+        errorCode = Channel::ERROR::notEnoughZroToken;
+    }
+
+    ;; Verify that the ZRO token credits in the Channel is sufficient to cover the
+    ;; quoted ZRO cost of the message.
+    int zroBalance = $storage.cl::get<coins>(Channel::zroBalance);
+    if (zroBalance < zroQuote) {
+        errorCode = Channel::ERROR::notEnoughZroTokenBalance;
+    }
+
+    cell $sendPath = $storage.cl::get<objRef>(Channel::path);
+
+    int packetNonce = 0;
+    int packetGuid = 0;
+    if (errorCode == Channel::NO_ERROR) {
+        ;; Assign a nonce to the packet and calculate the resulting GUID
+        packetNonce = $storage.cl::get<uint64>(Channel::outboundNonce) + 1;
+        packetGuid = lz::Packet::calculateGuid($sendPath, packetNonce);
+
+        ;; native payments
+        tuple payees = deserializePayees(
+            $mdMsglibSendCallback.cl::get<cellRef>(md::MsglibSendCallback::payees)
+        );
+
+        ;; If the TON message does not contain sufficient value to perform the payments,
+        ;; the transaction will revert and the send channel will eventually get blocked.
+        ;; It is the responsibility of the OApp to assert sufficient gas + value to cover the
+        ;; entire transaction and avoid this failure.
+        repeat (payees.tlen()) {
+            [int payeeAddress, int nativeAmount] = payees~tpopPayee();
+            actions~pushAction<payment>(payeeAddress, nativeAmount, 0);
+        }
+
+        ;; Due to asynchrony between the Msglib and the Channel, the nonce and guid
+        ;; cannot be
+        cell encodedPacket = $mdMsglibSendCallback
+            .cl::get<cellRef>(md::MsglibSendCallback::packetEncoded);
+
+        int nonceByteOffset = $mdMsglibSendCallback
+            .cl::get<uint16>(md::MsglibSendCallback::nonceByteOffset);
+
+        int nonceBytes = $mdMsglibSendCallback
+            .cl::get<uint8>(md::MsglibSendCallback::nonceBytes);
+
+        int guidByteOffset = $mdMsglibSendCallback
+            .cl::get<uint16>(md::MsglibSendCallback::guidByteOffset);
+
+        int guidBytes = $mdMsglibSendCallback.cl::get<uint8>(md::MsglibSendCallback::guidBytes);
+
+        cell completedEncodedPacket = null();
+
+        if (guidByteOffset > nonceByteOffset) {
+            completedEncodedPacket = encodedPacket
+                .lz::Packet::replaceTwoFieldsAtOffsets(
+                    packetNonce,
+                    nonceByteOffset,
+                    nonceBytes,
+                    packetGuid,
+                    guidByteOffset,
+                    guidBytes
+                );
+        } else {
+            completedEncodedPacket = encodedPacket
+                .lz::Packet::replaceTwoFieldsAtOffsets(
+                    packetGuid,
+                    guidByteOffset,
+                    guidBytes,
+                    packetNonce,
+                    nonceByteOffset,
+                    nonceBytes
+                );
+        }
+
+        actions~pushAction<event>(
+            Channel::event::PACKET_SENT,
+            md::PacketSent::New(
+                nativeQuote,
+                zroQuote,
+                $lzSend.cl::get<objRef>(md::LzSend::extraOptions),
+                $lzSend.cl::get<objRef>(md::LzSend::enforcedOptions),
+                completedEncodedPacket,
+                packetNonce,
+                $mdAddress.cl::get<address>(md::MdAddress::address), ;; msglib manager address
+                $mdMsglibSendCallback.cl::get<objRef>(md::MsglibSendCallback::msglibSendEvents)
+            )
+        );
+
+        $storage = $storage
+            .cl::set(Channel::zroBalance, zroBalance - zroQuote)
+            .cl::set(Channel::outboundNonce, packetNonce);
+    }
+
+    ;; If the quote was unsuccessful, delete the hash from storage to prevent hol blocking
+    ;; If the quote was successful, additionally update the ZRO balance and outbound nonce
+    setContractStorage($storage);
+
+    actions~pushAction<call>(
+        $sendPath.cl::get<address>(lz::Path::srcOApp),
+        Layerzero::OP::CHANNEL_SEND_CALLBACK,
+        md::MdObj::New(
+            md::MessagingReceipt::New(
+                $lzSend.cl::set(
+                    md::LzSend::packet,
+                    $lzSend
+                        .cl::get<objRef>(md::LzSend::packet)
+                        .cl::set(lz::Packet::nonce, packetNonce)
+                        .cl::set(lz::Packet::guid, packetGuid)
+                ),
+                nativeQuote,
+                zroQuote,
+                errorCode
+            ),
+            getInitialStorage()
+        )
+    );
+
+    return actions;
+}
+
+;;; ==========================================
+;; Receive flow
+;; @in     endpoint/handler.fc/verify
+;; @in_md  ExtendedMd(msglibConnectionAddress, defaultEpConfig, verify)
+;; @out    packet_receive/handler.fc/verify
+;; @out_md ExtendedMd(msglib_addr, _, verify)
+;; @out    controller/handler.fc/emit_event
+tuple channelCommitPacket(cell $mdExtended) impure inline method_id {
+    (cell $storage, tuple actions) = preamble();
+
+    cell $packet = $mdExtended.cl::get<objRef>(md::ExtendedMd::md);
+    ;; assert the size of the incoming packet
+    lz::Packet::assertValidReceiveMessage($packet);
+
+    cell $epConfigOApp = $storage.cl::get<objRef>(Channel::epConfigOApp);
+    int receiveMsglibConnection = $epConfigOApp.cl::get<address>(
+        lz::EpConfig::receiveMsglibConnection
+    );
+
+    int useDefaults = $epConfigOApp.cl::get<bool>(lz::EpConfig::isNull);
+
+    if (useDefaults) {
+        cell $defaultConfig = $mdExtended.cl::get<objRef>(md::MdObj::obj);
+        receiveMsglibConnection = $defaultConfig
+            .cl::get<address>(lz::ReceiveEpConfig::receiveMsglibConnectionAddress);
+    }
+
+    int callerMsglibConnectionAddress = $mdExtended
+        .cl::get<address>(md::ExtendedMd::forwardingAddress);
+
+    if (receiveMsglibConnection != callerMsglibConnectionAddress) {
+        ;; grossly inefficient, but this will (almost) never happen
+        ;; so we can optimize the happy path by isolating this logic into this block
+        cell $defaultConfig = $mdExtended.cl::get<objRef>(md::MdObj::obj);
+        int timeoutReceiveMsglibConnection = useDefaults
+            ? $defaultConfig
+                .cl::get<address>(lz::ReceiveEpConfig::timeoutReceiveMsglibConnectionAddress)
+            : $epConfigOApp.cl::get<address>(lz::EpConfig::timeoutReceiveMsglibConnection);
+
+        int expiry = useDefaults
+            ? $defaultConfig.cl::get<uint64>(lz::ReceiveEpConfig::expiry)
+            : $epConfigOApp.cl::get<uint64>(lz::EpConfig::timeoutReceiveMsglibExpiry);
+
+        if ((timeoutReceiveMsglibConnection != callerMsglibConnectionAddress) | (expiry < now())) {
+            throw(Channel::ERROR::onlyApprovedReceiveMsglib);
+        }
+    }
+
+    int incomingNonce = $packet.cl::get<uint64>(lz::Packet::nonce);
+    cell $commitPOOO = $storage.cl::get<objRef>(Channel::commitPOOO);
+
+    (
+        int isCommittable,
+        _
+    ) = _nonceCommittable(incomingNonce);
+
+    if (isCommittable) {
+        setContractStorage(
+            $storage
+                .cl::set(Channel::commitPOOO, POOO::set($commitPOOO, incomingNonce))
+                .cl::set(Channel::executionQueue,
+                    DeterministicInsertionCircularQueue::set(
+                        $storage.cl::get<cellRef>(Channel::executionQueue),
+                        incomingNonce,
+                        $packet,
+                        ExecutionQueue::committed
+                    )
+                )
+        );
+        actions~pushAction<event>(Channel::event::PACKET_COMMITTED, $packet);
+    }
+
+    if (incomingNonce <= POOO::maxSettableBit($storage.cl::get<objRef>(Channel::executePOOO))) {
+        ;; Cannot respond back to msglib if the packet is not currently committable but
+        ;; will be committable in the future
+        ;; Caveat: if the packet is currently executing, we treat it as uncommittable.
+        ;; There exists a race condition where a uncommitted re-committable packet
+        ;; can be marked as committed. If the packet needs to be re-committed for a good reason
+        ;; (e.g., malicious DVN), the OApp owner must first nilify the packet
+
+        actions~pushAction<call>(
+            callerMsglibConnectionAddress,
+            MsglibConnection::OP::MSGLIB_CONNECTION_COMMIT_PACKET_CALLBACK,
+            md::ChannelNonceInfo::New(
+                incomingNonce,
+                $storage.cl::get<objRef>(Channel::executePOOO).cl::get<uint64>(POOO::nextEmpty)
+            )
+        );
+    }
+
+
+    return actions;
+}
+
+;;; ==========================================
+;; Execution step 1
+;; @in_opcode Channel::OP::LZ_RECEIVE_PREPARE
+;; @in_from (external in) permissionless
+;; @in_md nonce
+;; @out_opcode Layerzero::OP::LZ_RECEIVE_PREPARE
+;; @out_to srcOApp
+;; @out_md ExtendedMd(md=packetId, obj=channel_init_state, forwarding_addr=NULLADDRESS)
+;; @permissions: permissonless
+tuple lzReceivePrepare(cell $lzReceivePrepareMd) impure inline method_id {
+    (cell $storage, tuple actions) = preamble();
+    int nonce = $lzReceivePrepareMd.cl::get<uint64>(md::LzReceivePrepare::nonce);
+    int nanotons = $lzReceivePrepareMd.cl::get<coins>(md::LzReceivePrepare::nanotons);
+
+    ;; extract oApp from path
+    actions~pushAction<dispatch>(
+        $storage.cl::get<objRef>(Channel::path).cl::get<uint256>(lz::Path::srcOApp),
+        Layerzero::OP::LZ_RECEIVE_PREPARE,
+        ;; Throws if the Packet is not executable
+        _getExecutablePacket(nonce),
+        nanotons
+    );
+
+    return actions;
+}
+
+;; @in_opcode Channel::OP::LZ_RECEIVE_LOCK
+;; @in_from oApp
+;; @in_md nonce
+;; @out_opcode Layerzero::OP::LZ_RECEIVE_EXECUTE
+;; @out_to oApp
+;; @out_md ExtendedMd(md=Packet, obj=channel_init_state, forwarding_addr=NULLADDRESS)
+;; @permissions: only oApp
+tuple lzReceiveLock(cell $nonceMd) impure inline method_id {
+    (cell $storage, tuple actions) = preamble();
+
+    int incomingNonce = $nonceMd.cl::get<uint64>(md::Nonce::nonce);
+
+    throw_if(Channel::ERROR::invalidNonce, incomingNonce <= 0);
+    cell executionQueue = $storage.cl::get<cellRef>(Channel::executionQueue);
+
+    (int actualKey, cell $packet, int status, _) = DeterministicInsertionCircularQueue::get(
+        executionQueue,
+        incomingNonce
+    );
+
+    int firstUncommittedNonce = getContractStorage()
+        .cl::get<objRef>(Channel::commitPOOO)
+        .cl::get<uint64>(POOO::nextEmpty);
+
+    ;; executable if present and all preceding nonces are committed, executing, or executed
+    if (
+        (actualKey == incomingNonce)
+        & (status == ExecutionQueue::committed)
+        & (incomingNonce < firstUncommittedNonce)
+    ) {
+        ;; set state to executing
+        setContractStorage(
+            $storage.cl::set(
+                Channel::executionQueue,
+                DeterministicInsertionCircularQueue::set(
+                    executionQueue,
+                    incomingNonce,
+                    $packet,
+                    ExecutionQueue::executing
+                )
+            )
+        );
+
+        actions~pushAction<call>(
+            $storage.cl::get<objRef>(Channel::path).cl::get<uint256>(lz::Path::srcOApp),
+            Layerzero::OP::LZ_RECEIVE_EXECUTE,
+            md::MdObj::New($packet, getInitialStorage())
+        );
+    } else {
+        actions~pushAction<event>(
+            Channel::event::NOT_EXECUTABLE,
+            md::PacketId::New($storage.cl::get<objRef>(Channel::path), incomingNonce)
+        );
+    }
+
+    return actions;
+}
+
+;; @in_opcode Channel::OP::LZ_RECEIVE_EXECUTE_CALLBACK
+;; @in_from oApp
+;; @in_md LzReceiveStatus
+;; @out_opcode OP::PACKET_RECEIVE_DESTROYED_CALLBACK
+;; @out_to oApp
+;; @out_md ExtendedMd(md=packetId, obj=pr_init_state, forwarding_addr=address_std_hashpart_null())
+;; @failure => unlock the Packet
+;; @success => destroy the Packet and refund rent
+;; @permissions: only oApp
+tuple lzReceiveExecuteCallback(cell $lzReceiveStatus) impure inline method_id {
+    (cell $storage, tuple actions) = preamble();
+
+    int packetNonce = $lzReceiveStatus.cl::get<uint64>(md::LzReceiveStatus::nonce);
+    cell executionQueue = $storage.cl::get<cellRef>(Channel::executionQueue);
+
+    (int actualKey, cell $packet, int status, _) = DeterministicInsertionCircularQueue::get(
+        executionQueue,
+        packetNonce
+    );
+
+    throw_unless(
+        Channel::ERROR::notExecuting,
+        (actualKey == packetNonce) & (status == ExecutionQueue::executing)
+    );
+
+    ;; check for success/failure
+    if ($lzReceiveStatus.cl::get<bool>(md::LzReceiveStatus::success)) {
+        executionQueue = DeterministicInsertionCircularQueue::delete(executionQueue, packetNonce);
+
+        $storage = $storage.cl::set(
+            Channel::executePOOO,
+            POOO::set($storage.cl::get<objRef>(Channel::executePOOO), packetNonce)
+        );
+
+        ;; emit Packet in the manager
+        actions~pushAction<event>(
+            Channel::event::DELIVERED,
+            md::PacketId::New($storage.cl::get<objRef>(Channel::path), packetNonce)
+        );
+    } else {
+        executionQueue = DeterministicInsertionCircularQueue::set(
+            executionQueue,
+            packetNonce,
+            $packet, ;; same packet object that we extracted from the queue
+            ExecutionQueue::committed
+        );
+
+        ;; emit Packet so we know its unlocked
+        actions~pushAction<event>(
+            Channel::event::LZ_RECEIVE_ALERT,
+            md::LzReceiveStatus::NewFull(
+                false,
+                packetNonce,
+                $lzReceiveStatus.cl::get<coins>(md::LzReceiveStatus::value),
+                $lzReceiveStatus.cl::get<cellRef>(md::LzReceiveStatus::extraData),
+                $lzReceiveStatus.cl::get<cellRef>(md::LzReceiveStatus::reason),
+                getOrigin(),
+                $packet,
+                ExecutionStatus::executable
+            )
+        );
+    }
+
+    setContractStorage($storage.cl::set(Channel::executionQueue, executionQueue));
+
+    return actions;
+}
+
+;;; ====================== Management Helper ===================================
+() _commitFakePacket(cell $storage, int nonce, cell $receivePath) impure inline method_id {
+    cell $mockPacket = lz::Packet::New($receivePath, empty_cell(), nonce);
+
+    ;; Because this is not originating from the endpoint, we dont have the defaults
+    ;; Actual defaults and the msglib address arent required because the call is direct from the OApp
+    cell $mockEpConfigDefaults = lz::ReceiveEpConfig::New(
+        0xdeadbeef, ;; any non-null dummy value for the receive msglib connection address
+        NULLADDRESS, ;; timeout never has to be used for burn
+        0 ;; as above, timeout never has to be used for burn
+    );
+    cell $epConfigOApp = $storage.cl::get<objRef>(Channel::epConfigOApp);
+
+    ;; Step 1: Commit the 'mockPacket'
+    ;; This is safe because we are going to do the following steps (2 and 3) atomically.
+    ;; channelCommitPacket will not revert if the packet is not committed, but lzReceiveLock will.
+    ;; Basically lying to channelCommitPacket to say the "correct" msglib is committing
+    channelCommitPacket(
+        md::ExtendedMd::New(
+            $mockPacket,
+            $mockEpConfigDefaults, ;; this is completely ignored if useDefaults is false
+            $epConfigOApp.cl::get<bool>(lz::EpConfig::isNull)
+                ? $mockEpConfigDefaults.cl::get<address>(lz::EpConfig::receiveMsglibConnection)
+                : $epConfigOApp.cl::get<address>(lz::EpConfig::receiveMsglibConnection)
+        )
+    );
+}
+
+;; @permissions only-oApp
+tuple nilify(cell $packetId) impure inline method_id {
+    (cell $storage, tuple actions) = preamble();
+
+    cell $receivePath = $storage.cl::get<objRef>(Channel::path).lz::Path::optimizedReverse();
+    _assertEqualPaths($receivePath, $packetId.cl::get<objRef>(md::PacketId::path));
+
+    int incomingNonce = $packetId.cl::get<uint64>(md::PacketId::nonce);
+    _assertNonceCommittable(incomingNonce);
+
+    (_, cell $previousPacket) = _nonceCommittable(incomingNonce);
+
+    _commitFakePacket($storage, incomingNonce, $receivePath);
+    
+    setContractStorage(
+        getContractStorage().cl::set(
+            Channel::executionQueue,
+            DeterministicInsertionCircularQueue::delete(
+                $storage.cl::get<cellRef>(Channel::executionQueue),
+                incomingNonce
+            )
+        )
+    );
+
+    if ($previousPacket.is_null()) {
+        $previousPacket = lz::Packet::New($receivePath, empty_cell(), incomingNonce);
+    }
+    actions~pushAction<event>(Channel::event::PACKET_NILIFIED, $previousPacket);
+
+    actions~pushAction<call>(
+        $receivePath.cl::get<uint256>(lz::Path::dstOApp),
+        Layerzero::OP::NILIFY_CALLBACK,
+        md::MdObj::New($packetId, getInitialStorage())
+    );
+
+    return actions;
+}
+
+tuple burn(cell $packetId) impure inline method_id {
+    (cell $storage, tuple actions) = preamble();
+
+    ;; reverse the path because this is from a receive perspective
+    cell $receivePath = lz::Path::reverse($storage.cl::get<objRef>(Channel::path));
+    _assertEqualPaths($receivePath, $packetId.cl::get<objRef>(md::PacketId::path));
+
+    int nonce = $packetId.cl::get<uint64>(md::PacketId::nonce);
+
+    cell $nonceMd = md::Nonce::New(nonce);
+
+    (_, cell $previousPacket) = _nonceCommittable(nonce);
+
+    ;; Step 1: Commit a 'mockPacket' to be used when we 'burn' this nonce
+    _commitFakePacket($storage, nonce, $receivePath);
+    
+    ;; Step 2: Put the packet into 'executing'
+    lzReceiveLock($nonceMd);
+    ;; Step 3: Mock the lzReceiveExecuteCallback, which marks/flags that given nonce as used and 'executed'
+    lzReceiveExecuteCallback(md::LzReceiveStatus::New(true, nonce));
+
+
+    if ($previousPacket.is_null()) {
+        $previousPacket = lz::Packet::New($receivePath, empty_cell(), nonce);
+    }
+
+    ;; Emit an event so we are able to observe offchain that this nonce has been 'burned'
+    actions~pushAction<event>(
+        Channel::event::PACKET_BURNED,
+        $previousPacket
+    );
+
+    cell $packetId = md::PacketId::New($receivePath, nonce);
+    actions~pushAction<call>(
+        $receivePath.cl::get<uint256>(lz::Path::dstOApp),
+        Layerzero::OP::BURN_CALLBACK,
+        md::MdObj::New($packetId, getInitialStorage())
+    );
+
+    return actions;
+}
+
+;;; ==========================================
+;; ZRO management
+;; only controller
+tuple depositZro(cell $coinsAmount) impure inline method_id {
+    (cell $storage, tuple actions) = preamble();
+
+    setContractStorage(
+        $storage.cl::set(
+            Channel::zroBalance,
+            $storage.cl::get<coins>(Channel::zroBalance)
+            + $coinsAmount.cl::get<coins>(md::CoinsAmount::amount)
+        )
+    );
+
+   actions~pushAction<event>(Channel::event::ZRO_DEPOSITED, $coinsAmount);
+    
+    return actions;
+}
+
+;; Attempt to abort a send request. Check if hash still present, if present delete and send
+;; @in: oApp
+;; @in_opcode Channel::OP::FORCE_ABORT
+;; @in_md lzSend
+;; @out_opcode
+;; @out_to oApp
+;; @out_md lzSend
+;; @permissions: only oApp
+tuple forceAbort(cell $lzSend) impure inline method_id {
+    (cell $storage, tuple actions) = preamble();
+
+    cell $path = $storage.cl::get<objRef>(Channel::path);
+    _assertEqualPaths(
+        $path,
+        $lzSend
+            .cl::get<objRef>(md::LzSend::packet)
+            .cl::get<objRef>(lz::Packet::path)
+    );
+
+    int requestId = $lzSend.cl::get<uint64>(md::LzSend::sendRequestId);
+
+    cell sendRequestQueue = $storage.cl::get<cellRef>(Channel::sendRequestQueue);
+
+    (_, cell request, int status, _) = DeterministicInsertionCircularQueue::get(sendRequestQueue, requestId);
+
+    throw_if(
+        Channel::ERROR::cannotAbortSend,
+        (status != SendRequestQueue::sending) | (_readSendRequestQueueEntry(request) != $lzSend.cl::hash())
+    );
+
+    ;; delete the reservation and update the storage
+    setContractStorage(
+        $storage.cl::set(
+            Channel::sendRequestQueue,
+            DeterministicInsertionCircularQueue::delete(sendRequestQueue, requestId)
+        )
+    );
+
+    actions~pushAction<call>(
+        $path.cl::get<uint256>(lz::Path::srcOApp),
+        Layerzero::OP::CHANNEL_SEND_CALLBACK,
+        md::MdObj::New(
+            md::MessagingReceipt::New($lzSend, 0, 0, Channel::ERROR::sendAborted),
+            getInitialStorage()
+        )
+    );
+
+    return actions;
+}
+
+;; Send the current state of the channel to the MsglibConnection
+;; @in: permissionless
+;; @in_opcode Channel::OP::MSGLIB_CONNECTION_SYNC_CHANNEL_STATE
+;; @in_md mdAddress ( MsglibConnectionAddress, Path )
+tuple syncMsglibConnection(cell $mdAddress) impure inline method_id {
+    (cell $storage, tuple actions) = preamble();
+
+    actions~pushAction<call>(
+        $mdAddress.cl::get<address>(md::MdAddress::address), ;; msglibConnectionAddress
+        MsglibConnection::OP::MSGLIB_CONNECTION_SYNC_CHANNEL_STATE,
+        md::MdObj::New(
+            md::ChannelNonceInfo::New(
+                $storage
+                    .cl::get<objRef>(Channel::commitPOOO)
+                    .cl::get<uint64>(POOO::nextEmpty),
+                $storage
+                    .cl::get<objRef>(Channel::executePOOO)
+                    .cl::get<uint64>(POOO::nextEmpty)
+            ),
+            getInitialStorage()
+        )
+    );
+
+    return actions;
+}
+
+tuple notifyPacketExecuted(cell $mdAddress) impure inline method_id {
+    (cell $storage, tuple actions) = preamble();
+
+    cell $nonceMd = $mdAddress.cl::get<objRef>(md::MdAddress::md);
+
+    int executionStatus = _viewExecutionStatus($nonceMd.cl::get<uint64>(md::Nonce::nonce));
+
+    if (executionStatus != ExecutionStatus::executed) {
+        return actions;
+    }
+
+    actions~pushAction<call>(
+        $mdAddress.cl::get<address>(md::MdAddress::address),
+        MsglibConnection::OP::MSGLIB_CONNECTION_COMMIT_PACKET_CALLBACK,
+        md::ChannelNonceInfo::New(
+            $nonceMd.cl::get<uint64>(md::Nonce::nonce),
+            $storage.cl::get<objRef>(Channel::executePOOO).cl::get<uint64>(POOO::nextEmpty)
+        )
+    );
+    return actions;
+}
+
+tuple emitLzReceiveAlert(cell $lzReceiveStatus) impure inline method_id {
+    (cell $storage, tuple actions) = preamble();
+    int nonce = $lzReceiveStatus.cl::get<uint64>(md::LzReceiveStatus::nonce);
+    throw_if(Channel::ERROR::invalidNonce, nonce == 0);
+    int executionStatus = _viewExecutionStatus(nonce);
+    (int actualNonce, cell $packet, _, int exists) = DeterministicInsertionCircularQueue::get(
+        $storage.cl::get<cellRef>(Channel::executionQueue),
+        nonce
+    );
+
+    throw_unless(
+        Channel::ERROR::invalidNonce,
+        (actualNonce == nonce) & (exists)
+    );
+
+    actions~pushAction<event>(
+        Channel::event::LZ_RECEIVE_ALERT,
+        md::LzReceiveStatus::NewFull(
+            $lzReceiveStatus.cl::get<bool>(md::LzReceiveStatus::success),
+            nonce,
+            $lzReceiveStatus.cl::get<coins>(md::LzReceiveStatus::value),
+            $lzReceiveStatus.cl::get<cellRef>(md::LzReceiveStatus::extraData),
+            $lzReceiveStatus.cl::get<cellRef>(md::LzReceiveStatus::reason),
+            getCaller(),
+            $packet,
+            executionStatus
+        )
+    );
+    return actions;
+}