[N-05] Insufficient Documentation

Signed-off-by: Matt Rice <[email protected]>

Author: mrice32

contracts/SpokePoolPeriphery.sol

@@ -222,6 +222,7 @@ contract SpokePoolPeriphery is SpokePoolPeripheryInterface, Lockable, MultiCalle
 
     /**
      * @inheritdoc SpokePoolPeripheryInterface
+     * @dev Does not support native tokens as swap output. Only ERC20 tokens can be deposited via this function.
      */
     function swapAndBridge(SwapAndDepositData calldata swapAndDepositData) external payable override nonReentrant {
         // If a user performs a swapAndBridge with the swap token as the native token, wrap the value and treat the rest of transaction
@@ -245,6 +246,7 @@ contract SpokePoolPeriphery is SpokePoolPeripheryInterface, Lockable, MultiCalle
 
     /**
      * @inheritdoc SpokePoolPeripheryInterface
+     * @dev Does not support native tokens as swap output. Only ERC20 tokens can be deposited via this function.
      */
     function swapAndBridgeWithPermit(
         address signatureOwner,
@@ -278,6 +280,7 @@ contract SpokePoolPeriphery is SpokePoolPeripheryInterface, Lockable, MultiCalle
 
     /**
      * @inheritdoc SpokePoolPeripheryInterface
+     * @dev Does not support native tokens as swap output. Only ERC20 tokens can be deposited via this function.
      */
     function swapAndBridgeWithPermit2(
         address signatureOwner,
@@ -310,6 +313,7 @@ contract SpokePoolPeriphery is SpokePoolPeripheryInterface, Lockable, MultiCalle
 
     /**
      * @inheritdoc SpokePoolPeripheryInterface
+     * @dev Does not support native tokens as swap output. Only ERC20 tokens can be deposited via this function.
      */
     function swapAndBridgeWithAuthorization(
         address signatureOwner,

contracts/handlers/MulticallHandler.sol

@@ -48,7 +48,6 @@ contract MulticallHandler is AcrossMessageHandler, ReentrancyGuard {
     error ReplacementCallFailed(bytes calldData);
     error CalldataTooShort(uint256 callDataLength, uint256 offset);
 
-
     modifier onlySelf() {
         _requireSelf();
         _;
@@ -120,7 +119,22 @@ contract MulticallHandler is AcrossMessageHandler, ReentrancyGuard {
         }
     }
 
-    function makeCallWithBalance(address target, bytes memory callData, uint256 value, Replacement[] memory replacement) external onlySelf {
+    /**
+     * @notice Executes a call while replacing specified calldata offsets with current token/native balances.
+     * @dev Modifies calldata in-place using OR operations. Target calldata positions must be zeroed out.
+     * Cannot handle negative balances, making it incompatible with DEXs requiring negative input amounts.
+     * For native balance (token = address(0)), the entire balance is used as call value.
+     * @param target The contract address to call
+     * @param callData The calldata to execute, with zero values at replacement positions
+     * @param value The native token value to send (ignored if native balance replacement is used)
+     * @param replacement Array of Replacement structs specifying token addresses and byte offsets for balance injection
+     */
+    function makeCallWithBalance(
+        address target,
+        bytes memory callData,
+        uint256 value,
+        Replacement[] memory replacement
+    ) external onlySelf {
         for (uint256 i = 0; i < replacement.length; i++) {
             uint256 bal = 0;
             if (replacement[i].token != address(0)) {