refactor: Send funds directly to recipient for ERC20 intents (#6750)

larryob · web-flow · commit 5b17b0f37803 · 2025-09-24T15:57:44.000Z
diff --git a/.changeset/gold-islands-agree.md b/.changeset/gold-islands-agree.md
@@ -0,0 +1,5 @@
+---
+"@hyperlane-xyz/core": minor
+---
+
+Add Everclear bridges for ETH and ERC20 tokens.
diff --git a/solidity/contracts/mock/MockMailbox.sol b/solidity/contracts/mock/MockMailbox.sol
@@ -14,6 +14,7 @@ import {TestPostDispatchHook} from "../test/TestPostDispatchHook.sol";
 
 contract MockMailbox is Mailbox {
     using Message for bytes;
+    using TypeCasts for address;
 
     uint32 public inboundUnprocessedNonce = 0;
     uint32 public inboundProcessedNonce = 0;
@@ -92,4 +93,37 @@ contract MockMailbox is Mailbox {
     function addInboundMetadata(uint32 _nonce, bytes memory metadata) public {
         inboundMetadata[_nonce] = metadata;
     }
+
+    function buildMessage(
+        address sender,
+        uint32 destinationDomain,
+        bytes32 recipientAddress,
+        bytes calldata messageBody
+    ) external view returns (bytes memory) {
+        return
+            _buildMessage(
+                sender,
+                destinationDomain,
+                recipientAddress,
+                messageBody
+            );
+    }
+
+    function _buildMessage(
+        address sender,
+        uint32 destinationDomain,
+        bytes32 recipientAddress,
+        bytes calldata messageBody
+    ) internal view returns (bytes memory) {
+        return
+            Message.formatMessage(
+                VERSION,
+                nonce,
+                localDomain,
+                sender.addressToBytes32(),
+                destinationDomain,
+                recipientAddress,
+                messageBody
+            );
+    }
 }
diff --git a/solidity/contracts/token/bridge/EverclearEthBridge.sol b/solidity/contracts/token/bridge/EverclearEthBridge.sol
@@ -25,6 +25,9 @@ contract EverclearEthBridge is EverclearTokenBridge {
 
     /**
      * @notice Constructor to initialize the Everclear ETH bridge
+     * @param _weth The WETH contract address for wrapping/unwrapping ETH
+     * @param _scale The scaling factor for token amounts (typically 1 for 18-decimal tokens)
+     * @param _mailbox The address of the Hyperlane mailbox contract
      * @param _everclearAdapter The address of the Everclear adapter contract
      */
     constructor(
@@ -41,6 +44,27 @@ contract EverclearEthBridge is EverclearTokenBridge {
         )
     {}
 
+    /**
+     * @notice Gets the receiver address for an ETH transfer intent
+     * @dev Overrides parent to use the remote router instead of direct recipient
+     * @param _destination The destination domain ID
+     * @return receiver The remote router address that will handle the ETH transfer
+     */
+    function _getReceiver(
+        uint32 _destination,
+        bytes32 /* _recipient */
+    ) internal view override returns (bytes32 receiver) {
+        return _mustHaveRemoteRouter(_destination);
+    }
+
+    /**
+     * @notice Provides a quote for transferring ETH to a remote chain
+     * @dev Overrides parent to return a single quote for ETH (including transfer amount, fees, and gas)
+     * @param _destination The destination domain ID
+     * @param _recipient The recipient address on the destination chain
+     * @param _amount The amount of ETH to transfer
+     * @return quotes Array containing a single quote with total ETH amount needed
+     */
     function quoteTransferRemote(
         uint32 _destination,
         bytes32 _recipient,
@@ -57,6 +81,8 @@ contract EverclearEthBridge is EverclearTokenBridge {
 
     /**
      * @notice Transfers ETH from sender, wrapping to WETH
+     * @dev Requires msg.value to be at least the specified amount, then wraps ETH to WETH
+     * @param _amount The amount of ETH to wrap to WETH (includes transfer amount and fees)
      */
     function _transferFromSender(uint256 _amount) internal override {
         // The `_amount` here will be amount + fee where amount is what the user wants to send,
@@ -66,6 +92,12 @@ contract EverclearEthBridge is EverclearTokenBridge {
         IWETH(address(wrappedToken)).deposit{value: _amount}();
     }
 
+    /**
+     * @notice Transfers ETH to a recipient by unwrapping WETH and sending native ETH
+     * @dev Unwraps WETH to ETH and uses Address.sendValue for safe ETH transfer
+     * @param _recipient The address to receive the ETH
+     * @param _amount The amount of ETH to transfer
+     */
     function _transferTo(
         address _recipient,
         uint256 _amount
@@ -77,6 +109,14 @@ contract EverclearEthBridge is EverclearTokenBridge {
         payable(_recipient).sendValue(_amount);
     }
 
+    /**
+     * @notice Charges the sender for ETH transfer including all fees
+     * @dev Overrides parent to handle ETH-specific charging logic with fee calculation and distribution
+     * @param _destination The destination domain ID
+     * @param _recipient The recipient address on the destination chain
+     * @param _amount The amount of ETH to transfer (excluding fees)
+     * @return dispatchValue The remaining ETH value to include with the Hyperlane message dispatch
+     */
     function _chargeSender(
         uint32 _destination,
         bytes32 _recipient,
@@ -92,4 +132,15 @@ contract EverclearEthBridge is EverclearTokenBridge {
         }
         return dispatchValue;
     }
+
+    /**
+     * @notice Allows the contract to receive ETH
+     * @dev Required for WETH unwrapping functionality
+     */
+    receive() external payable {
+        require(
+            msg.sender == address(wrappedToken),
+            "EEB: Only WETH can send ETH"
+        );
+    }
 }
diff --git a/solidity/contracts/token/bridge/EverclearTokenBridge.sol b/solidity/contracts/token/bridge/EverclearTokenBridge.sol
@@ -11,6 +11,7 @@ import {PackageVersioned} from "../../PackageVersioned.sol";
 import {IWETH} from "../interfaces/IWETH.sol";
 import {TokenMessage} from "../libs/TokenMessage.sol";
 import {TypeCasts} from "../../libs/TypeCasts.sol";
+import {FungibleTokenRouter} from "../libs/FungibleTokenRouter.sol";
 
 /**
  * @notice Information about an output asset for a destination domain
@@ -68,6 +69,9 @@ contract EverclearTokenBridge is HypERC20Collateral {
 
     /**
      * @notice Constructor to initialize the Everclear token bridge
+     * @param _erc20 The address of the ERC20 token to be bridged
+     * @param _scale The scaling factor for token amounts (typically 1 for 18-decimal tokens)
+     * @param _mailbox The address of the Hyperlane mailbox contract
      * @param _everclearAdapter The address of the Everclear adapter contract
      */
     constructor(
@@ -81,8 +85,10 @@ contract EverclearTokenBridge is HypERC20Collateral {
     }
 
     /**
-     * @notice Initializes the proxy contract.
-     * @dev Approves the Everclear adapter to spend tokens
+     * @notice Initializes the proxy contract
+     * @dev Approves the Everclear adapter to spend tokens and calls parent initialization
+     * @param _hook The address of the post-dispatch hook (can be zero address)
+     * @param _owner The address that will own this contract
      */
     function initialize(address _hook, address _owner) public initializer {
         _HypERC20_initialize(_hook, address(0), _owner);
@@ -109,6 +115,11 @@ contract EverclearTokenBridge is HypERC20Collateral {
         emit FeeParamsUpdated(_fee, _deadline);
     }
 
+    /**
+     * @notice Internal function to set the output asset for a destination domain
+     * @dev Emits OutputAssetSet event when successful
+     * @param _outputAssetInfo The output asset information containing destination and asset address
+     */
     function _setOutputAsset(
         OutputAssetInfo calldata _outputAssetInfo
     ) internal {
@@ -172,27 +183,13 @@ contract EverclearTokenBridge is HypERC20Collateral {
         });
     }
 
-    /// @dev We can't use _feeAmount here because Everclear wants to pull tokens from this contract
-    /// and the amount from _feeAmount is sent to the fee recipient.
-    function _chargeSender(
-        uint32 _destination,
-        bytes32 _recipient,
-        uint256 _amount
-    ) internal virtual override returns (uint256 dispatchValue) {
-        return
-            super._chargeSender(
-                _destination,
-                _recipient,
-                _amount + feeParams.fee
-            );
-    }
-
     /**
      * @notice Creates an Everclear intent for cross-chain token transfer
      * @dev Internal function to handle intent creation with Everclear adapter
      * @param _destination The destination domain ID
      * @param _recipient The recipient address on the destination chain
      * @param _amount The amount of tokens to transfer
+     * @return The created Everclear intent struct containing all transfer details
      */
     function _createIntent(
         uint32 _destination,
@@ -209,40 +206,72 @@ contract EverclearTokenBridge is HypERC20Collateral {
         destinations[0] = _destination;
 
         // Create intent
-        // We always send the funds to the remote router, which will then send them to the recipient in _handle
         (, IEverclear.Intent memory intent) = everclearAdapter.newIntent({
             _destinations: destinations,
-            _receiver: _mustHaveRemoteRouter(_destination),
+            _receiver: _getReceiver(_destination, _recipient),
             _inputAsset: address(wrappedToken),
             _outputAsset: outputAssets[_destination], // We load this from storage again to avoid stack too deep
             _amount: _amount,
             _maxFee: 0,
             _ttl: 0,
-            _data: _getIntentCalldata(_recipient, _amount),
+            _data: "",
             _feeParams: feeParams
         });
 
         return intent;
     }
 
     /**
-     * @notice Gets the calldata for the intent that will unwrap WETH to ETH on destination
-     * @dev Overrides parent to return calldata for unwrapping WETH to ETH
-     * @return The encoded calldata for the unwrap and send operation
+     * @notice Gets the receiver address for an intent
+     * @dev Virtual function that can be overridden by derived contracts
+     * @param _destination The destination domain ID
+     * @param _recipient The intended recipient address
+     * @return receiver The receiver address to use in the intent (typically the recipient for token bridge)
      */
-    function _getIntentCalldata(
+    function _getReceiver(
+        uint32 _destination,
+        bytes32 _recipient
+    ) internal view virtual returns (bytes32) {
+        return _recipient;
+    }
+
+    /**
+     * @notice Charges the sender for the transfer including Everclear fees
+     * @dev We can't use _feeAmount here because Everclear wants to pull tokens from this contract
+     *      and the amount from _feeAmount is sent to the fee recipient.
+     * @param _destination The destination domain ID
+     * @param _recipient The recipient address on the destination chain
+     * @param _amount The amount of tokens to transfer (excluding fees)
+     * @return dispatchValue The ETH value to include with the Hyperlane message dispatch
+     */
+    function _chargeSender(
+        uint32 _destination,
         bytes32 _recipient,
         uint256 _amount
-    ) internal view returns (bytes memory) {
-        return abi.encode(_recipient, _amount);
+    ) internal virtual override returns (uint256 dispatchValue) {
+        return
+            super._chargeSender(
+                _destination,
+                _recipient,
+                _amount + feeParams.fee
+            );
     }
 
+    /**
+     * @notice Handles pre-dispatch logic including charging sender and creating Everclear intent
+     * @dev Overrides parent function to integrate with Everclear's intent system
+     * @param _destination The destination domain ID
+     * @param _recipient The recipient address on the destination chain
+     * @param _amount The amount of tokens to transfer
+     * @return dispatchValue The ETH value to include with the message dispatch
+     * @return message The encoded message containing transfer details and intent
+     */
     function _beforeDispatch(
         uint32 _destination,
         bytes32 _recipient,
         uint256 _amount
     ) internal virtual override returns (uint256, bytes memory) {
-        (uint256 _dispatchValue, bytes memory _msg) = super._beforeDispatch(
+        uint256 dispatchValue = _chargeSender(
             _destination,
             _recipient,
             _amount
@@ -254,45 +283,51 @@ contract EverclearTokenBridge is HypERC20Collateral {
             _amount
         );
 
-        // Add the intent to the `TokenMessage` as metadata
-        // The original `_msg` is abi.encodePacked(_recipient, _amount)
-        // We need can't use abi.encodePacked because the intent is a struct
-        _msg = bytes.concat(_msg, abi.encode(intent));
+        bytes memory message = TokenMessage.format(
+            _recipient,
+            _outboundAmount(_amount),
+            abi.encode(intent)
+        );
 
-        return (_dispatchValue, _msg);
+        return (dispatchValue, message);
     }
 
+    /**
+     * @dev No-op, the funds are transferred directly to `_recipient` via Everclear
+     * @param _recipient The address to receive the tokens
+     * @param _amount The amount of tokens to transfer
+     */
+    function _transferTo(
+        address _recipient,
+        uint256 _amount
+    ) internal virtual override {
+        // No-op, the funds are transferred directly to `_recipient` via Everclear
+    }
+
+    /**
+     * @notice Handles incoming messages from remote chains
+     * @dev For the base token bridge, this is a no-op since funds are transferred via Everclear
+     * @param _origin The origin domain ID where the message was sent from
+     * @param _message The message payload (unused in base implementation)
+     */
     function _handle(
         uint32 _origin,
-        bytes32 /* sender */,
+        bytes32 _sender,
         bytes calldata _message
     ) internal virtual override {
         // Get intent from hyperlane message
         bytes memory metadata = _message.metadata();
-        IEverclear.Intent memory intent = abi.decode(
-            metadata,
-            (IEverclear.Intent)
-        );
+        bytes32 intentId = keccak256(metadata);
 
-        /* CHECKS */
-        // Check that intent is settled
-        bytes32 intentId = keccak256(abi.encode(intent));
+        // Check Everclear intent status
         require(
             everclearSpoke.status(intentId) == IEverclear.IntentStatus.SETTLED,
             "ETB: Intent Status != SETTLED"
         );
         // Check that we have not processed this intent before
         require(!intentSettled[intentId], "ETB: Intent already processed");
-        (bytes32 _recipient, uint256 _amount) = abi.decode(
-            intent.data,
-            (bytes32, uint256)
-        );
 
-        /* EFFECTS */
         intentSettled[intentId] = true;
-        emit ReceivedTransferRemote(_origin, _recipient, _amount);
-
-        /* INTERACTIONS */
-        _transferTo(_recipient.bytes32ToAddress(), _amount);
+        super._handle(_origin, _sender, _message);
     }
 }
diff --git a/solidity/foundry.toml b/solidity/foundry.toml
@@ -8,7 +8,7 @@ cache_path = 'forge-cache'
 allow_paths = ["../node_modules"]
 solc_version = '0.8.22'
 evm_version= 'paris'
-optimizer = true
+# optimizer = true
 optimizer_runs = 999_999
 fs_permissions = [
     { access = "read", path = "./script/avs/"},
diff --git a/solidity/test/token/EverclearTokenBridge.t.sol b/solidity/test/token/EverclearTokenBridge.t.sol

-Original file line number
+Diff line change
@@ @@ -0,0 +1,5 @@ @@
 +---
 +"@hyperlane-xyz/core": minor
 +---
++
 +Add Everclear bridges for ETH and ERC20 tokens.