@layerzerolabs/lz-evm-oapp-v2 2.0.2

package/contracts/oft/OFTAdapter.sol

@@ -0,0 +1,131 @@
+// SPDX-License-Identifier: MIT
+
+pragma solidity ^0.8.22;
+
+import { IERC20Metadata, IERC20 } from "@openzeppelin/contracts/token/ERC20/extensions/IERC20Metadata.sol";
+import { SafeERC20 } from "@openzeppelin/contracts/token/ERC20/utils/SafeERC20.sol";
+import { OFTCore } from "./OFTCore.sol";
+
+/**
+ * @title OFTAdapter Contract
+ * @dev OFTAdapter is a contract that adapts an ERC-20 token to the OFT functionality.
+ *
+ * @dev For existing ERC20 tokens, this can be used to convert the token to crosschain compatibility.
+ * @dev WARNING: ONLY 1 of these should exist for a given global mesh,
+ * unless you make a NON-default implementation of OFT and needs to be done very carefully
+ */
+contract OFTAdapter is OFTCore {
+    using SafeERC20 for IERC20;
+
+    IERC20 internal immutable innerToken;
+
+    // @dev The amount of tokens locked inside this contract.
+    // @dev This SHOULD equal the total amount of OFTs in circulation on all the NON OFTAdapter chains
+    uint256 public outboundAmount;
+
+    /**
+     * @dev Constructor for the OFTAdapter contract.
+     * @param _token The address of the ERC-20 token to be adapted.
+     * @param _lzEndpoint The LayerZero endpoint address.
+     * @param _owner The owner of the contract.
+     */
+    constructor(
+        address _token,
+        address _lzEndpoint,
+        address _owner
+    ) OFTCore(IERC20Metadata(_token).decimals(), _lzEndpoint, _owner) {
+        innerToken = IERC20(_token);
+    }
+
+    /**
+     * @dev Retrieves the OFTAdapter contract version.
+     * @return major The major version.
+     * @return minor The minor version.
+     *
+     * @dev major version: Indicates a cross-chain compatible msg encoding with other OFTs.
+     * @dev minor version: Indicates a version within the local chains context. eg. OFTAdapter vs. OFT
+     * @dev For example, if a new feature is added to the OFT contract, the minor version will be incremented.
+     * @dev If a new feature is added to the OFT cross-chain msg encoding, the major version will be incremented.
+     * ie. localOFT version(1,1) CAN send messages to remoteOFT version(1,2)
+     */
+    function oftVersion() external pure returns (uint64 major, uint64 minor) {
+        return (1, 2);
+    }
+
+    /**
+     * @dev Retrieves the address of the underlying ERC20 implementation.
+     * @return The address of the adapted ERC-20 token.
+     *
+     * @dev In the case of OFTAdapter, address(this) and erc20 are NOT the same contract.
+     */
+    function token() public view virtual returns (address) {
+        return address(innerToken);
+    }
+
+    /**
+     * @dev Burns tokens from the sender's specified balance, ie. pull method.
+     * @param _amountToSendLD The amount of tokens to send in local decimals.
+     * @param _minAmountToCreditLD The minimum amount to credit in local decimals.
+     * @param _dstEid The destination chain ID.
+     * @return amountDebitedLD The amount of tokens ACTUALLY debited in local decimals.
+     * @return amountToCreditLD The amount of tokens to credit in local decimals.
+     */
+    function _debitSender(
+        uint256 _amountToSendLD,
+        uint256 _minAmountToCreditLD,
+        uint32 _dstEid
+    ) internal virtual override returns (uint256 amountDebitedLD, uint256 amountToCreditLD) {
+        (amountDebitedLD, amountToCreditLD) = _debitView(_amountToSendLD, _minAmountToCreditLD, _dstEid);
+        // @dev msg.sender will need to approve this amountLD of tokens to be locked inside of the contract.
+        // @dev Move all of the debited tokens into this contract.
+        innerToken.safeTransferFrom(msg.sender, address(this), amountDebitedLD);
+
+        // @dev In NON-default OFTAdapter, amountDebited could be 100, with a 10% fee, the credited amount is 90,
+        // so technically the amountToCredit would be locked as outboundAmount. Therefore amountDebited CAN differ from amountToCredit.
+        // @dev Due to OFTs containing both push/pull methods, the reserved amount needs to be tracked so _debitThis() cant spend it.
+        outboundAmount += amountToCreditLD;
+    }
+
+    /**
+     * @dev Allows a sender to send tokens that are inside the contract but are NOT accounted for in outboundAmount, ie. push method.
+     * @param _minAmountToCreditLD The minimum amount to credit in local decimals.
+     * @param _dstEid The destination chain ID.
+     * @return amountDebitedLD The amount of tokens ACTUALLY debited in local decimals.
+     * @return amountToCreditLD The amount of tokens to credit in local decimals.
+     */
+    function _debitThis(
+        uint256 _minAmountToCreditLD,
+        uint32 _dstEid
+    ) internal virtual override returns (uint256 amountDebitedLD, uint256 amountToCreditLD) {
+        // @dev This is the push method, where at any point in the transaction, the OFT receives tokens and they can be sent by the caller.
+        // @dev This SHOULD be done atomically, otherwise any caller can spend tokens that are owned by the contract.
+        uint256 availableToSend = innerToken.balanceOf(address(this)) - outboundAmount;
+        (amountDebitedLD, amountToCreditLD) = _debitView(availableToSend, _minAmountToCreditLD, _dstEid);
+
+        // @dev Due to OFTs containing both push/pull methods, the reserved amount needs to be tracked so _debitThis() cant spend it.
+        outboundAmount += amountToCreditLD;
+
+        // @dev When sending tokens direct to the OFTAdapter contract,
+        // there is NOT a default mechanism to capture the dust that MIGHT get left in the contract.
+        // If you want to refund this dust, will need to add another function to return it.
+    }
+
+    /**
+     * @dev Credits tokens to the specified address.
+     * @param _to The address to credit the tokens to.
+     * @param _amountToCreditLD The amount of tokens to credit in local decimals.
+     * @dev _srcEid The source chain ID.
+     * @return amountReceivedLD The amount of tokens ACTUALLY received in local decimals.
+     */
+    function _credit(
+        address _to,
+        uint256 _amountToCreditLD,
+        uint32 /*_srcEid*/
+    ) internal virtual override returns (uint256 amountReceivedLD) {
+        outboundAmount -= _amountToCreditLD;
+        // @dev Unlock the tokens and transfer to the recipient.
+        innerToken.safeTransfer(_to, _amountToCreditLD);
+        // @dev In the case of NON-default OFTAdapter, the amountToCreditLD MIGHT not == amountReceivedLD.
+        return _amountToCreditLD;
+    }
+}

package/contracts/oft/OFTCore.sol

@@ -0,0 +1,456 @@
+// SPDX-License-Identifier: MIT
+
+pragma solidity ^0.8.22;
+
+import { OApp, Origin } from "../oapp/OApp.sol";
+import { OAppOptionsType3 } from "../oapp/libs/OAppOptionsType3.sol";
+import { IOAppMsgInspector } from "../oapp/interfaces/IOAppMsgInspector.sol";
+
+import { OAppPreCrimeSimulator } from "../precrime/OAppPreCrimeSimulator.sol";
+
+import { IOFT, SendParam, OFTLimit, OFTReceipt, OFTFeeDetail, MessagingReceipt, MessagingFee } from "./interfaces/IOFT.sol";
+import { OFTMsgCodec } from "./libs/OFTMsgCodec.sol";
+import { OFTComposeMsgCodec } from "./libs/OFTComposeMsgCodec.sol";
+
+/**
+ * @title OFTCore
+ * @dev Abstract contract for the OftChain (OFT) token.
+ */
+abstract contract OFTCore is IOFT, OApp, OAppPreCrimeSimulator, OAppOptionsType3 {
+    using OFTMsgCodec for bytes;
+    using OFTMsgCodec for bytes32;
+
+    // @notice Provides a conversion rate when swapping between denominations of SD and LD
+    //      - shareDecimals == SD == shared Decimals
+    //      - localDecimals == LD == local decimals
+    // @dev Considers that tokens have different decimal amounts on various chains.
+    // @dev eg.
+    //  For a token
+    //      - locally with 4 decimals --> 1.2345 => uint(12345)
+    //      - remotely with 2 decimals --> 1.23 => uint(123)
+    //      - The conversion rate would be 10 ** (4 - 2) = 100
+    //  @dev If you want to send 1.2345 -> (uint 12345), you CANNOT represent that value on the remote,
+    //  you can only display 1.23 -> uint(123).
+    //  @dev To preserve the dust that would otherwise be lost on that conversion,
+    //  we need to unify a denomination that can be represented on ALL chains inside of the OFT mesh
+    uint256 public immutable decimalConversionRate;
+
+    // @notice Msg types that are used to identify the various OFT operations.
+    // @dev This can be extended in child contracts for non-default oft operations
+    // @dev These values are used in things like combineOptions() in OAppOptionsType3.sol.
+    uint16 public constant SEND = 1;
+    uint16 public constant SEND_AND_CALL = 2;
+
+    // Address of an optional contract to inspect both 'message' and 'options'
+    address public msgInspector;
+
+    /**
+     * @dev Constructor.
+     * @param _localDecimals The decimals of the token on the local chain (this chain).
+     * @param _endpoint The address of the LayerZero endpoint.
+     * @param _owner The address of the OFT owner.
+     */
+    constructor(uint8 _localDecimals, address _endpoint, address _owner) OApp(_endpoint, _owner) {
+        if (_localDecimals < sharedDecimals()) revert InvalidLocalDecimals();
+        decimalConversionRate = 10 ** (_localDecimals - sharedDecimals());
+    }
+
+    /**
+     * @dev Retrieves the shared decimals of the OFT.
+     * @return The shared decimals of the OFT.
+     *
+     * @dev Sets an implicit cap on the amount of tokens, over uint64.max() will need some sort of outbound cap / totalSupply cap
+     * Lowest common decimal denominator between chains.
+     * Defaults to 6 decimal places to provide up to 18,446,744,073,709.551615 units (max uint64).
+     * For tokens exceeding this totalSupply(), they will need to override the sharedDecimals function with something smaller.
+     * ie. 4 sharedDecimals would be 1,844,674,407,370,955.1615
+     */
+    function sharedDecimals() public pure virtual returns (uint8) {
+        return 6;
+    }
+
+    /**
+     * @dev Sets the message inspector address for the OFT.
+     * @param _msgInspector The address of the message inspector.
+     *
+     * @dev This is an optional contract that can be used to inspect both 'message' and 'options'.
+     * @dev Set it to address(0) to disable it, or set it to a contract address to enable it.
+     */
+    function setMsgInspector(address _msgInspector) public virtual onlyOwner {
+        msgInspector = _msgInspector;
+        emit MsgInspectorSet(_msgInspector);
+    }
+
+    /**
+     * @notice Provides a quote for OFT-related operations.
+     * @param _sendParam The parameters for the send operation.
+     * @dev _oftCmd The OFT command to be executed.
+     * @return oftLimit The OFT limit information.
+     * @return oftFeeDetails The details of OFT fees.
+     * @return oftReceipt The OFT receipt information.
+     */
+    function quoteOFT(
+        SendParam calldata _sendParam,
+        bytes calldata /*_oftCmd*/ // @dev unused in the default implementation.
+    )
+        external
+        view
+        virtual
+        returns (OFTLimit memory oftLimit, OFTFeeDetail[] memory oftFeeDetails, OFTReceipt memory oftReceipt)
+    {
+        uint256 minAmountLD = 0; // Unused in the default implementation.
+        uint256 maxAmountLD = type(uint64).max; // Unused in the default implementation.
+        oftLimit = OFTLimit(minAmountLD, maxAmountLD);
+
+        // Unused in the default implementation; reserved for future complex fee details.
+        oftFeeDetails = new OFTFeeDetail[](0);
+
+        // @dev This is the same as the send() operation, but without the actual send.
+        // - amountToDebitLD is the amount in local decimals that was be debited from the sender.
+        // - amountToCreditLD is the amount in local decimals that will be credited to the recipient on the remote OFT instance.
+        // @dev The amount credited does NOT always equal the amount the user actually receives.
+        // HOWEVER, In the default implementation it is.
+        (uint256 amountToDebitLD, uint256 amountToCreditLD) = _debitView(
+            _sendParam.amountToSendLD,
+            _sendParam.minAmountToCreditLD,
+            _sendParam.dstEid
+        );
+        oftReceipt = OFTReceipt(amountToDebitLD, amountToCreditLD);
+    }
+
+    /**
+     * @notice Provides a quote for the send() operation.
+     * @param _sendParam The parameters for the send() operation.
+     * @param _extraOptions Additional options supplied by the caller to be used in the LayerZero message.
+     * @param _payInLzToken Flag indicating whether the caller is paying in the LZ token.
+     * @param _composeMsg The composed message for the send() operation.
+     * @dev _oftCmd The OFT command to be executed.
+     * @return msgFee The calculated LayerZero messaging fee from the send() operation.
+     *
+     * @dev MessagingFee: LayerZero msg fee
+     *  - nativeFee: The native fee.
+     *  - lzTokenFee: The lzToken fee.
+     */
+    function quoteSend(
+        SendParam calldata _sendParam,
+        bytes calldata _extraOptions,
+        bool _payInLzToken,
+        bytes calldata _composeMsg,
+        bytes calldata /*_oftCmd*/ // @dev unused in the default implementation.
+    ) external view virtual returns (MessagingFee memory msgFee) {
+        // @dev mock the amount to credit, this is the same operation used in the send().
+        // The quote is as similar as possible to the actual send() operation.
+        (, uint256 amountToCreditLD) = _debitView(
+            _sendParam.amountToSendLD,
+            _sendParam.minAmountToCreditLD,
+            _sendParam.dstEid
+        );
+
+        // @dev Builds the options and OFT message to quote in the endpoint.
+        (bytes memory message, bytes memory options) = _buildMsgAndOptions(
+            _sendParam,
+            _extraOptions,
+            _composeMsg,
+            amountToCreditLD
+        );
+
+        // @dev Calculates the LayerZero fee for the send() operation.
+        return _quote(_sendParam.dstEid, message, options, _payInLzToken);
+    }
+
+    /**
+     * @dev Executes the send operation.
+     * @param _sendParam The parameters for the send operation.
+     * @param _extraOptions Additional options for the send() operation.
+     * @param _fee The calculated fee for the send() operation.
+     *      - nativeFee: The native fee.
+     *      - lzTokenFee: The lzToken fee.
+     * @param _refundAddress The address to receive any excess funds.
+     * @param _composeMsg The composed message for the send() operation.
+     * @dev _oftCmd The OFT command to be executed.
+     * @return msgReceipt The receipt for the send operation.
+     * @return oftReceipt The OFT receipt information.
+     *
+     * @dev MessagingReceipt: LayerZero msg receipt
+     *  - guid: The unique identifier for the sent message.
+     *  - nonce: The nonce of the sent message.
+     *  - fee: The LayerZero fee incurred for the message.
+     */
+    function send(
+        SendParam calldata _sendParam,
+        bytes calldata _extraOptions,
+        MessagingFee calldata _fee,
+        address _refundAddress,
+        bytes calldata _composeMsg,
+        bytes calldata /*_oftCmd*/ // @dev unused in the default implementation.
+    ) external payable virtual returns (MessagingReceipt memory msgReceipt, OFTReceipt memory oftReceipt) {
+        // @dev Applies the token transfers regarding this send() operation.
+        // - amountDebitedLD is the amount in local decimals that was ACTUALLY debited from the sender.
+        // - amountToCreditLD is the amount in local decimals that will be credited to the recipient on the remote OFT instance.
+        (uint256 amountDebitedLD, uint256 amountToCreditLD) = _debit(
+            _sendParam.amountToSendLD,
+            _sendParam.minAmountToCreditLD,
+            _sendParam.dstEid
+        );
+
+        // @dev Builds the options and OFT message to quote in the endpoint.
+        (bytes memory message, bytes memory options) = _buildMsgAndOptions(
+            _sendParam,
+            _extraOptions,
+            _composeMsg,
+            amountToCreditLD
+        );
+
+        // @dev Sends the message to the LayerZero endpoint and returns the LayerZero msg receipt.
+        msgReceipt = _lzSend(_sendParam.dstEid, message, options, _fee, _refundAddress);
+        // @dev Formulate the OFT receipt.
+        oftReceipt = OFTReceipt(amountDebitedLD, amountToCreditLD);
+
+        emit OFTSent(msgReceipt.guid, msg.sender, amountDebitedLD, amountToCreditLD, _composeMsg);
+    }
+
+    /**
+     * @dev Internal function to build the message and options.
+     * @param _sendParam The parameters for the send() operation.
+     * @param _extraOptions Additional options for the send() operation.
+     * @param _composeMsg The composed message for the send() operation.
+     * @param _amountToCreditLD The amount to credit in local decimals.
+     * @return message The encoded message.
+     * @return options The encoded options.
+     */
+    function _buildMsgAndOptions(
+        SendParam calldata _sendParam,
+        bytes calldata _extraOptions,
+        bytes calldata _composeMsg,
+        uint256 _amountToCreditLD
+    ) internal view virtual returns (bytes memory message, bytes memory options) {
+        bool hasCompose;
+        // @dev This generated message has the msg.sender encoded into the payload so the remote knows who the caller is.
+        (message, hasCompose) = OFTMsgCodec.encode(
+            _sendParam.to,
+            _toSD(_amountToCreditLD),
+            // @dev Must be include a non empty bytes if you want to compose, EVEN if you dont need it on the remote.
+            // EVEN if you dont require an arbitrary payload to be sent... eg. '0x01'
+            _composeMsg
+        );
+        // @dev Change the msg type depending if its composed or not.
+        uint16 msgType = hasCompose ? SEND_AND_CALL : SEND;
+        // @dev Combine the callers _extraOptions with the enforced options via the OAppOptionsType3.
+        options = combineOptions(_sendParam.dstEid, msgType, _extraOptions);
+
+        // @dev Optionally inspect the message and options depending if the OApp owner has set a msg inspector.
+        // @dev If it fails inspection, needs to revert in the implementation. ie. does not rely on return boolean
+        if (msgInspector != address(0)) IOAppMsgInspector(msgInspector).inspect(message, options);
+    }
+
+    /**
+     * @dev Internal function to handle the receive on the LayerZero endpoint.
+     * @param _origin The origin information.
+     *  - srcEid: The source chain endpoint ID.
+     *  - sender: The sender address from the src chain.
+     *  - nonce: The nonce of the LayerZero message.
+     * @param _guid The unique identifier for the received LayerZero message.
+     * @param _message The encoded message.
+     * @dev _executor The address of the executor.
+     * @dev _extraData Additional data.
+     */
+    function _lzReceive(
+        Origin calldata _origin,
+        bytes32 _guid,
+        bytes calldata _message,
+        address /*_executor*/, // @dev unused in the default implementation.
+        bytes calldata /*_extraData*/ // @dev unused in the default implementation.
+    ) internal virtual override {
+        // @dev The src sending chain doesnt know the address length on this chain (potentially non-evm)
+        // Thus everything is bytes32() encoded in flight.
+        address toAddress = _message.sendTo().bytes32ToAddress();
+        // @dev Convert the amount to credit into local decimals.
+        uint256 amountToCreditLD = _toLD(_message.amountSD());
+        // @dev Credit the amount to the recipient and return the ACTUAL amount the recipient received in local decimals
+        uint256 amountReceivedLD = _credit(toAddress, amountToCreditLD, _origin.srcEid);
+
+        if (_message.isComposed()) {
+            // @dev Proprietary composeMsg format for the OFT.
+            bytes memory composeMsg = OFTComposeMsgCodec.encode(
+                _origin.nonce,
+                _origin.srcEid,
+                amountReceivedLD,
+                _message.composeMsg()
+            );
+
+            // @dev Stores the lzCompose payload that will be executed in a separate tx.
+            // Standardizes functionality for executing arbitrary contract invocation on some non-evm chains.
+            // @dev The off-chain executor will listen and process the msg based on the src-chain-callers compose options passed.
+            // @dev The index is used when a OApp needs to compose multiple msgs on lzReceive.
+            // For default OFT implementation there is only 1 compose msg per lzReceive, thus its always 0.
+            endpoint.sendCompose(toAddress, _guid, 0 /* the index of the composed message*/, composeMsg);
+        }
+
+        emit OFTReceived(_guid, toAddress, amountToCreditLD, amountReceivedLD);
+    }
+
+    /**
+     * @dev Internal function to handle the OAppPreCrimeSimulator simulated receive.
+     * @param _origin The origin information.
+     *  - srcEid: The source chain endpoint ID.
+     *  - sender: The sender address from the src chain.
+     *  - nonce: The nonce of the LayerZero message.
+     * @param _guid The unique identifier for the received LayerZero message.
+     * @param _message The LayerZero message.
+     * @param _executor The address of the off-chain executor.
+     * @param _extraData Arbitrary data passed by the msg executor.
+     *
+     * @dev Enables the preCrime simulator to mock sending lzReceive() messages,
+     * routes the msg down from the OAppPreCrimeSimulator, and back up to the OAppReceiver.
+     */
+    function _lzReceiveSimulate(
+        Origin calldata _origin,
+        bytes32 _guid,
+        bytes calldata _message,
+        address _executor,
+        bytes calldata _extraData
+    ) internal virtual override {
+        _lzReceive(_origin, _guid, _message, _executor, _extraData);
+    }
+
+    /**
+     * @dev Internal function to check if peer is considered 'trusted' by the OApp.
+     * @param _eid The endpoint ID to check.
+     * @param _peer The peer to check.
+     * @return Whether the peer passed is considered 'trusted' by the OApp.
+     *
+     * @dev Enables OAppPreCrimeSimulator to check whether a potential Inbound Packet is from a trusted source.
+     */
+    function isPeer(uint32 _eid, bytes32 _peer) public view virtual override returns (bool) {
+        return peers[_eid] == _peer;
+    }
+
+    /**
+     * @dev Internal function to remove dust from the given local decimal amount.
+     * @param _amountLD The amount in local decimals.
+     * @return amountLD The amount after removing dust.
+     *
+     * @dev Prevents the loss of dust when moving amounts between chains with different decimals.
+     * @dev eg. uint(123) with a conversion rate of 100 becomes uint(100).
+     */
+    function _removeDust(uint256 _amountLD) internal view virtual returns (uint256 amountLD) {
+        return (_amountLD / decimalConversionRate) * decimalConversionRate;
+    }
+
+    /**
+     * @dev Internal function to convert an amount from shared decimals into local decimals.
+     * @param _amountSD The amount in shared decimals.
+     * @return amountLD The amount in local decimals.
+     */
+    function _toLD(uint64 _amountSD) internal view virtual returns (uint256 amountLD) {
+        return _amountSD * decimalConversionRate;
+    }
+
+    /**
+     * @dev Internal function to convert an amount from local decimals into shared decimals.
+     * @param _amountLD The amount in local decimals.
+     * @return amountSD The amount in shared decimals.
+     */
+    function _toSD(uint256 _amountLD) internal view virtual returns (uint64 amountSD) {
+        return uint64(_amountLD / decimalConversionRate);
+    }
+
+    /**
+     * @dev Internal function to mock the amount mutation from a OFT debit() operation.
+     * @param _amountToSendLD The amount to send in local decimals.
+     * @param _minAmountToCreditLD The minimum amount to credit in local decimals.
+     * @dev _dstEid The destination endpoint ID.
+     * @return amountToDebitLD The amount to ACTUALLY debit, in local decimals.
+     * @return amountToCreditLD The amount to credit on the remote chain, in local decimals.
+     *
+     * @dev This is where things like fees would be calculated and deducted from the amount to credit on the remote.
+     */
+    function _debitView(
+        uint256 _amountToSendLD,
+        uint256 _minAmountToCreditLD,
+        uint32 /*_dstEid*/
+    ) internal view virtual returns (uint256 amountToDebitLD, uint256 amountToCreditLD) {
+        // @dev Remove the dust so nothing is lost on the conversion between chains with different decimals for the token.
+        amountToDebitLD = _removeDust(_amountToSendLD);
+        // @dev The amount to credit is the same as the amount to debit in the default implementation.
+        amountToCreditLD = amountToDebitLD;
+
+        // @dev Check for slippage.
+        if (amountToCreditLD < _minAmountToCreditLD) {
+            revert SlippageExceeded(amountToCreditLD, _minAmountToCreditLD);
+        }
+    }
+
+    /**
+     * @dev Internal function to perform a debit operation.
+     * @param _amountToSendLD The amount to send in local decimals.
+     * @param _minAmountToCreditLD The minimum amount to credit in local decimals.
+     * @param _dstEid The destination endpoint ID.
+     * @return amountDebitedLD The amount ACTUALLY debited in local decimals.
+     * @return amountToCreditLD The amount to credit in local decimals on the remote.
+     */
+    function _debit(
+        uint256 _amountToSendLD,
+        uint256 _minAmountToCreditLD,
+        uint32 _dstEid
+    ) internal virtual returns (uint256 amountDebitedLD, uint256 amountToCreditLD) {
+        // @dev Caller can indicate it wants to use push vs. pull method by passing an _amountToSendLD of 0.
+        if (_amountToSendLD > 0) {
+            // @dev Pull the tokens from the caller.
+            (amountDebitedLD, amountToCreditLD) = _debitSender(_amountToSendLD, _minAmountToCreditLD, _dstEid);
+        } else {
+            // @dev Caller has pushed tokens.
+            (amountDebitedLD, amountToCreditLD) = _debitThis(_minAmountToCreditLD, _dstEid);
+        }
+    }
+
+    /**
+     * @dev Internal function to perform a debit operation for this chain.
+     * @param _amountToSendLD The amount to send in local decimals.
+     * @param _minAmountToCreditLD The minimum amount to credit in local decimals.
+     * @param _dstEid The destination endpoint ID.
+     * @return amountDebitedLD The amount ACTUALLY debited in local decimals.
+     * @return amountToCreditLD The amount to credit in local decimals.
+     *
+     * @dev Defined here but are intended to be override depending on the OFT implementation.
+     * @dev This is used when the OFT pulls the tokens from the caller.
+     * ie. A user sends has approved the OFT to spend on its behalf.
+     */
+    function _debitSender(
+        uint256 _amountToSendLD,
+        uint256 _minAmountToCreditLD,
+        uint32 _dstEid
+    ) internal virtual returns (uint256 amountDebitedLD, uint256 amountToCreditLD);
+
+    /**
+     * @dev Internal function to perform a debit operation for this chain.
+     * @param _minAmountToCreditLD The minimum amount to credit in local decimals.
+     * @param _dstEid The destination endpoint ID.
+     * @return amountDebitedLD The amount ACTUALLY debited in local decimals.
+     * @return amountToCreditLD The amount to credit in local decimals.
+     *
+     * @dev Defined here but are intended to be override depending on the OFT implementation.
+     * @dev This is used when the OFT is the recipient of a push operation.
+     * ie. A user sends tokens direct to the OFT contract address.
+     */
+    function _debitThis(
+        uint256 _minAmountToCreditLD,
+        uint32 _dstEid
+    ) internal virtual returns (uint256 amountDebitedLD, uint256 amountToCreditLD);
+
+    /**
+     * @dev Internal function to perform a credit operation.
+     * @param _to The address to credit.
+     * @param _amountToCreditLD The amount to credit in local decimals.
+     * @param _srcEid The source endpoint ID.
+     * @return amountReceivedLD The amount ACTUALLY received in local decimals.
+     *
+     * @dev Defined here but are intended to be override depending on the OFT implementation.
+     * @dev Depending on OFT implementation the _amountToCreditLD could differ from the amountReceivedLD.
+     */
+    function _credit(
+        address _to,
+        uint256 _amountToCreditLD,
+        uint32 _srcEid
+    ) internal virtual returns (uint256 amountReceivedLD);
+}