@evvm/testnet-contracts 2.2.3 → 2.3.0

package/contracts/evvm/lib/SignatureUtils.sol

@@ -2,44 +2,73 @@
 // Full license terms available at: https://www.evvm.info/docs/EVVMNoncommercialLicense
 pragma solidity ^0.8.0;
 
-import {SignatureUtil} from "@evvm/testnet-contracts/library/utils/SignatureUtil.sol";
-import {AdvancedStrings} from "@evvm/testnet-contracts/library/utils/AdvancedStrings.sol";
+import {
+    SignatureUtil
+} from "@evvm/testnet-contracts/library/utils/SignatureUtil.sol";
+import {
+    AdvancedStrings
+} from "@evvm/testnet-contracts/library/utils/AdvancedStrings.sol";
 
+/**
+ * @title SignatureUtils
+ * @author Mate labs
+ * @notice Library for EIP-191 signature verification exclusively for Evvm.sol payment functions
+ * @dev This library provides signature verification utilities for the Evvm.sol contract,
+ *      specifically for payment operations (pay and dispersePay). It constructs the message
+ *      format expected by users and validates their signatures.
+ *
+ * Signature Verification:
+ * - Uses EIP-191 standard for message signing and verification
+ * - Constructs deterministic message strings from payment parameters
+ * - Integrates with SignatureUtil for cryptographic verification
+ * - Prevents replay attacks through nonce inclusion
+ * - Supports cross-chain safety through EvvmID inclusion
+ *
+ * Message Format:
+ * - pay: "receiver,token,amount,priorityFee,nonce,priorityFlag,executor"
+ * - dispersePay: "hashOfRecipients,token,amount,priorityFee,nonce,priorityFlag,executor"
+ *
+ * @custom:scope Exclusive to Evvm.sol payment functions
+ * @custom:standard EIP-191 (https://eips.ethereum.org/EIPS/eip-191)
+ * @custom:security All signatures include EvvmID to prevent cross-chain replay attacks
+ */
 library SignatureUtils {
-    /**
-     *  @dev using EIP-191 (https://eips.ethereum.org/EIPS/eip-191) can be used to sign and
-     *       verify messages, the next functions are used to verify the messages signed
-     *       by the users
-     */
 
     /**
-     *  @notice This function is used to verify the message signed for the payment
-     *  @param signer user who signed the message
-     *  @param _receiverAddress address of the receiver
-     *  @param _receiverIdentity identity of the receiver
+     * @notice Verifies EIP-191 signature for single payment operations
+     * @dev Constructs the expected message from payment parameters and verifies
+     *      the signature matches the signer. Used in pay() and payMultiple() functions.
      *
-     *  @notice if the _receiverAddress is 0x0 the function will use the _receiverIdentity
+     * Message Construction:
+     * - If receiverAddress is address(0): uses receiverIdentity string
+     * - Otherwise: converts receiverAddress to string
+     * - Concatenates all parameters with comma separators
+     * - Includes EvvmID for cross-chain replay protection
      *
-     *  @param _token address of the token to send
-     *  @param _amount amount to send
-     *  @param _priorityFee priorityFee to send to the staking holder
-     *  @param _nonce nonce of the transaction
-     *  @param _priorityFlag if the transaction is priority or not
-     *  @param _executor the executor of the transaction
-     *  @param signature signature of the user who wants to send the message
-     *  @return true if the signature is valid
+     * @param evvmID Unique identifier of the EVVM instance for cross-chain safety
+     * @param signer Address that signed the message (payment sender)
+     * @param receiverAddress Direct recipient address (used if receiverIdentity is empty)
+     * @param receiverIdentity Username/identity to resolve (takes priority over address)
+     * @param token Address of the token to transfer
+     * @param amount Amount of tokens to transfer
+     * @param priorityFee Fee paid to the staker/fisher processing the transaction
+     * @param nonce Transaction nonce for replay protection
+     * @param priorityFlag False for sync nonce (sequential), true for async nonce (flexible)
+     * @param executor Address authorized to execute this transaction (address(0) = anyone)
+     * @param signature EIP-191 signature from the signer
+     * @return bool True if the signature is valid and matches the signer
      */
     function verifyMessageSignedForPay(
         uint256 evvmID,
         address signer,
-        address _receiverAddress,
-        string memory _receiverIdentity,
-        address _token,
-        uint256 _amount,
-        uint256 _priorityFee,
-        uint256 _nonce,
-        bool _priorityFlag,
-        address _executor,
+        address receiverAddress,
+        string memory receiverIdentity,
+        address token,
+        uint256 amount,
+        uint256 priorityFee,
+        uint256 nonce,
+        bool priorityFlag,
+        address executor,
         bytes memory signature
     ) internal pure returns (bool) {
         return
@@ -47,21 +76,21 @@ library SignatureUtils {
                 evvmID,
                 "pay",
                 string.concat(
-                    _receiverAddress == address(0)
-                        ? _receiverIdentity
-                        : AdvancedStrings.addressToString(_receiverAddress),
+                    receiverAddress == address(0)
+                        ? receiverIdentity
+                        : AdvancedStrings.addressToString(receiverAddress),
                     ",",
-                    AdvancedStrings.addressToString(_token),
+                    AdvancedStrings.addressToString(token),
                     ",",
-                    AdvancedStrings.uintToString(_amount),
+                    AdvancedStrings.uintToString(amount),
                     ",",
-                    AdvancedStrings.uintToString(_priorityFee),
+                    AdvancedStrings.uintToString(priorityFee),
                     ",",
-                    AdvancedStrings.uintToString(_nonce),
+                    AdvancedStrings.uintToString(nonce),
                     ",",
-                    _priorityFlag ? "true" : "false",
+                    AdvancedStrings.boolToString(priorityFlag),
                     ",",
-                    AdvancedStrings.addressToString(_executor)
+                    AdvancedStrings.addressToString(executor)
                 ),
                 signature,
                 signer
@@ -69,29 +98,42 @@ library SignatureUtils {
     }
 
     /**
-     *  @notice This function is used to verify the message signed for the dispersePay
-     *  @param signer user who signed the message
-     *  @param hashList hash of the list of the transactions, the hash is calculated
-     *                  using sha256(abi.encode(toData))
-     *  @param _token token address to send
-     *  @param _amount amount to send
-     *  @param _priorityFee priorityFee to send to the fisher who wants to send the message
-     *  @param _nonce nonce of the transaction
-     *  @param _priorityFlag if the transaction is priority or not
-     *  @param _executor the executor of the transaction
-     *  @param signature signature of the user who wants to send the message
-     *  @return true if the signature is valid
+     * @notice Verifies EIP-191 signature for multi-recipient disperse payment operations
+     * @dev Constructs the expected message from disperse parameters and verifies
+     *      the signature matches the signer. Used in dispersePay() function.
+     *
+     * Message Construction:
+     * - Uses sha256 hash of recipient array instead of full data (gas optimization)
+     * - Concatenates hash and all other parameters with comma separators
+     * - Includes EvvmID for cross-chain replay protection
+     *
+     * Hash Calculation:
+     * - Client must calculate: sha256(abi.encode(toData))
+     * - toData is DispersePayMetadata[] array with recipients and amounts
+     * - Ensures tamper-proof verification of all recipients
+     *
+     * @param evvmID Unique identifier of the EVVM instance for cross-chain safety
+     * @param signer Address that signed the message (payment sender)
+     * @param hashList SHA256 hash of the recipient data array: sha256(abi.encode(toData))
+     * @param token Address of the token to distribute
+     * @param amount Total amount being distributed (must equal sum of individual amounts)
+     * @param priorityFee Fee paid to the staker/fisher processing the distribution
+     * @param nonce Transaction nonce for replay protection
+     * @param priorityFlag False for sync nonce (sequential), true for async nonce (flexible)
+     * @param executor Address authorized to execute this distribution (address(0) = anyone)
+     * @param signature EIP-191 signature from the signer
+     * @return bool True if the signature is valid and matches the signer
      */
     function verifyMessageSignedForDispersePay(
         uint256 evvmID,
         address signer,
         bytes32 hashList,
-        address _token,
-        uint256 _amount,
-        uint256 _priorityFee,
-        uint256 _nonce,
-        bool _priorityFlag,
-        address _executor,
+        address token,
+        uint256 amount,
+        uint256 priorityFee,
+        uint256 nonce,
+        bool priorityFlag,
+        address executor,
         bytes memory signature
     ) internal pure returns (bool) {
         return
@@ -101,17 +143,17 @@ library SignatureUtils {
                 string.concat(
                     AdvancedStrings.bytes32ToString(hashList),
                     ",",
-                    AdvancedStrings.addressToString(_token),
+                    AdvancedStrings.addressToString(token),
                     ",",
-                    AdvancedStrings.uintToString(_amount),
+                    AdvancedStrings.uintToString(amount),
                     ",",
-                    AdvancedStrings.uintToString(_priorityFee),
+                    AdvancedStrings.uintToString(priorityFee),
                     ",",
-                    AdvancedStrings.uintToString(_nonce),
+                    AdvancedStrings.uintToString(nonce),
                     ",",
-                    _priorityFlag ? "true" : "false",
+                    AdvancedStrings.boolToString(priorityFlag),
                     ",",
-                    AdvancedStrings.addressToString(_executor)
+                    AdvancedStrings.addressToString(executor)
                 ),
                 signature,
                 signer