@evvm/testnet-contracts 2.2.2 → 2.3.0

package/library/primitives/SignatureRecover.sol

@@ -2,11 +2,33 @@
 // Full license terms available at: https://www.evvm.info/docs/EVVMNoncommercialLicense
 
 pragma solidity ^0.8.0;
+/**
+ * @title SignatureRecover
+ * @author Mate Labs
+ * @notice Library for recovering signer addresses from EIP-191 signed messages
+ * @dev Provides utilities for signature verification following the EIP-191 standard.
+ * This library is used throughout the EVVM ecosystem for gasless transaction validation.
+ *
+ * EIP-191 Format:
+ * The signed message follows the format:
+ * "\x19Ethereum Signed Message:\n" + message.length + message
+ *
+ * This library can be used by community-developed services to implement
+ * signature verification compatible with the EVVM ecosystem.
+ */
 
 import {AdvancedStrings} from "@evvm/testnet-contracts/library/utils/AdvancedStrings.sol";
 
 library SignatureRecover {
 
+    /**
+     * @notice Recovers the signer address from an EIP-191 signed message
+     * @dev Uses ecrecover to extract the signer address from the signature components.
+     *      The message is hashed with the EIP-191 prefix before recovery.
+     * @param message The original message that was signed (without prefix)
+     * @param signature 65-byte signature in the format (r, s, v)
+     * @return The address that signed the message, or address(0) if invalid
+     */
     function recoverSigner(
         string memory message,
         bytes memory signature
@@ -22,6 +44,17 @@ library SignatureRecover {
         return ecrecover(messageHash, v, r, s);
     }
 
+    /**
+     * @notice Splits a 65-byte signature into its r, s, and v components
+     * @dev Extracts signature components using assembly for gas efficiency.
+     *      Handles both pre-EIP-155 and post-EIP-155 signature formats.
+     * @param signature 65-byte signature to split
+     * @return r First 32 bytes of the signature
+     * @return s Second 32 bytes of the signature
+     * @return v Recovery identifier (27 or 28)
+     * @custom:throws "Invalid signature length" if signature is not 65 bytes
+     * @custom:throws "Invalid signature value" if v is not 27 or 28
+     */
     function splitSignature(
         bytes memory signature
     ) internal pure returns (bytes32 r, bytes32 s, uint8 v) {

package/library/utils/AdvancedStrings.sol

@@ -2,12 +2,37 @@
 // Full license terms available at: https://www.evvm.info/docs/EVVMNoncommercialLicense
 
 pragma solidity ^0.8.0;
+/**
+ * @title AdvancedStrings
+ * @author Mate Labs
+ * @notice Library for advanced string manipulation and type conversions
+ * @dev Provides utility functions for converting various Solidity types to their string
+ * representations. These functions are essential for building EIP-191 signature messages
+ * in the EVVM ecosystem.
+ *
+ * Key Features:
+ * - Unsigned integer to string conversion
+ * - Address to hexadecimal string conversion
+ * - Bytes and bytes32 to hexadecimal string conversion
+ * - Boolean to string conversion
+ * - String equality comparison
+ *
+ * All hexadecimal outputs use lowercase letters and include the "0x" prefix where applicable.
+ * This library can be used by community-developed services for message construction.
+ */
 
 import {Math} from "@evvm/testnet-contracts/library/primitives/Math.sol";
 
 library AdvancedStrings {
+    /// @dev Hexadecimal character lookup table for efficient conversion
     bytes16 private constant HEX_DIGITS = "0123456789abcdef";
 
+    /**
+     * @notice Converts an unsigned integer to its decimal string representation
+     * @dev Uses assembly for gas-efficient string construction. Works for any uint256 value.
+     * @param value The unsigned integer to convert
+     * @return The decimal string representation of the value
+     */
     function uintToString(uint256 value) internal pure returns (string memory) {
         unchecked {
             uint256 length = Math.log10(value) + 1;
@@ -30,6 +55,12 @@ library AdvancedStrings {
         }
     }
 
+    /**
+     * @notice Converts an address to its hexadecimal string representation
+     * @dev Returns a 42-character string including the "0x" prefix with lowercase hex digits
+     * @param _address The address to convert
+     * @return The hexadecimal string representation (e.g., "0x1234...abcd")
+     */
     function addressToString(
         address _address
     ) internal pure returns (string memory) {
@@ -44,6 +75,13 @@ library AdvancedStrings {
         return string(_string);
     }
 
+    /**
+     * @notice Compares two strings for equality
+     * @dev First compares lengths, then compares keccak256 hashes for efficiency
+     * @param a First string to compare
+     * @param b Second string to compare
+     * @return True if both strings are identical, false otherwise
+     */
     function equal(
         string memory a,
         string memory b
@@ -53,6 +91,13 @@ library AdvancedStrings {
             keccak256(bytes(a)) == keccak256(bytes(b));
     }
 
+    /**
+     * @notice Converts a dynamic bytes array to its hexadecimal string representation
+     * @dev Returns a string with "0x" prefix followed by lowercase hex digits.
+     *      Empty input returns "0x".
+     * @param data The bytes array to convert
+     * @return The hexadecimal string representation with "0x" prefix
+     */
     function bytesToString(
         bytes memory data
     ) internal pure returns (string memory) {
@@ -72,6 +117,12 @@ library AdvancedStrings {
         return string(result);
     }
 
+    /**
+     * @notice Converts a bytes32 value to its hexadecimal string representation
+     * @dev Returns a 66-character string ("0x" + 64 hex characters) with lowercase letters
+     * @param data The bytes32 value to convert
+     * @return The hexadecimal string representation with "0x" prefix
+     */
     function bytes32ToString(
         bytes32 data
     ) internal pure returns (string memory) {
@@ -86,4 +137,14 @@ library AdvancedStrings {
         
         return string(result);
     }
+
+    /**
+     * @notice Converts a boolean value to its string representation
+     * @dev Returns "true" or "false" as lowercase strings
+     * @param value The boolean value to convert
+     * @return "true" if value is true, "false" otherwise
+     */
+    function boolToString(bool value) internal pure returns (string memory) {
+        return value ? "true" : "false";
+    }
 }

package/library/utils/SignatureUtil.sol

@@ -2,11 +2,45 @@
 // Full license terms available at: https://www.evvm.info/docs/EVVMNoncommercialLicense
 
 pragma solidity ^0.8.0;
+/**
+ * @title SignatureUtil
+ * @author Mate Labs
+ * @notice Library for EIP-191 signature verification in EVVM services
+ * @dev Provides a standardized method for verifying signatures in EVVM-compatible services.
+ * The signature message format follows a consistent pattern:
+ * "[evvmID],[functionName],[inputs]"
+ *
+ * This library is designed for use by community-developed services to implement
+ * signature verification that is compatible with the EVVM ecosystem standard.
+ *
+ * Example Usage:
+ * ```solidity
+ * bool isValid = SignatureUtil.verifySignature(
+ *     evvmID,
+ *     "myFunction",
+ *     "param1,param2,param3",
+ *     signature,
+ *     expectedSigner
+ * );
+ * ```
+ */
 
 import {SignatureRecover} from "@evvm/testnet-contracts/library/primitives/SignatureRecover.sol";
 import {AdvancedStrings} from "@evvm/testnet-contracts/library/utils/AdvancedStrings.sol";
 
 library SignatureUtil {
+    /**
+     * @notice Verifies an EIP-191 signature for a service function call
+     * @dev Constructs the expected message from the provided parameters and verifies
+     *      the signature was created by the expected signer. The message format is:
+     *      "[evvmID],[functionName],[inputs]"
+     * @param evvmID Unique identifier of the EVVM instance (for chain-specific signatures)
+     * @param functionName Name of the function being called
+     * @param inputs Comma-separated string of function input values
+     * @param signature 65-byte EIP-191 signature to verify
+     * @param expectedSigner Address that should have signed the message
+     * @return True if the signature is valid and matches the expected signer
+     */
     function verifySignature(
         uint256 evvmID,
         string memory functionName,

package/library/utils/nonces/AsyncNonce.sol

@@ -2,13 +2,41 @@
 // Full license terms available at: https://www.evvm.info/docs/EVVMNoncommercialLicense
 
 pragma solidity ^0.8.0;
+/**
+ * @title AsyncNonce
+ * @author Mate Labs
+ * @notice Abstract contract for asynchronous nonce management in EVVM services
+ * @dev Provides replay protection using a bitmap-style nonce system where each nonce
+ * can be used only once, but nonces can be used in any order (non-sequential).
+ *
+ * Key Features:
+ * - Non-sequential nonce usage (any unused nonce is valid)
+ * - Gas-efficient O(1) lookup and marking
+ * - Suitable for parallel transaction submission
+ *
+ * Use Cases:
+ * - Services that allow users to submit multiple transactions simultaneously
+ * - Operations where transaction ordering is not critical
+ * - Batch operations where sequential nonces would be a bottleneck
+ *
+ * This contract is designed for use by community-developed services that need
+ * flexible replay protection without strict ordering requirements.
+ */
 
 abstract contract AsyncNonce {
+    /// @dev Thrown when attempting to use a nonce that has already been consumed
     error AsyncNonceAlreadyUsed();
 
+    /// @dev Mapping to track used nonces: user address => nonce value => used flag
     mapping(address user => mapping(uint256 nonce => bool availability))
         private asyncNonce;
 
+    /**
+     * @notice Marks a nonce as used for a specific user
+     * @dev Should be called after successful operation validation to prevent replay
+     * @param user Address of the user whose nonce is being marked
+     * @param nonce The nonce value to mark as used
+     */
     function markAsyncNonceAsUsed(
         address user,
         uint256 nonce
@@ -16,6 +44,13 @@ abstract contract AsyncNonce {
         asyncNonce[user][nonce] = true;
     }
 
+    /**
+     * @notice Verifies that a nonce has not been used yet
+     * @dev Reverts with AsyncNonceAlreadyUsed if the nonce was previously consumed
+     * @param user Address of the user to check the nonce for
+     * @param nonce The nonce value to verify
+     * @custom:throws AsyncNonceAlreadyUsed If the nonce has already been used
+     */
     function verifyAsyncNonce(
         address user,
         uint256 nonce
@@ -23,6 +58,13 @@ abstract contract AsyncNonce {
         if (asyncNonce[user][nonce]) revert AsyncNonceAlreadyUsed();
     }
 
+    /**
+     * @notice Checks if a specific nonce has been used by a user
+     * @dev Public view function for external queries and UI integration
+     * @param user Address of the user to check
+     * @param nonce The nonce value to query
+     * @return True if the nonce has been used, false if available
+     */
     function getIfUsedAsyncNonce(
         address user,
         uint256 nonce

package/library/utils/nonces/SyncNonce.sol

@@ -2,16 +2,54 @@
 // Full license terms available at: https://www.evvm.info/docs/EVVMNoncommercialLicense
 
 pragma solidity ^0.8.0;
+/**
+ * @title SyncNonce
+ * @author Mate Labs
+ * @notice Abstract contract for synchronous (sequential) nonce management in EVVM services
+ * @dev Provides replay protection using a sequential nonce system where nonces must be
+ * used in strict ascending order starting from 0.
+ *
+ * Key Features:
+ * - Sequential nonce enforcement (must use nonce N before N+1)
+ * - Gas-efficient single uint256 counter per user
+ * - Guarantees transaction ordering
+ *
+ * Use Cases:
+ * - Operations requiring strict ordering guarantees
+ * - Financial transactions where sequence matters
+ * - State-dependent operations that must execute in order
+ *
+ * Trade-offs:
+ * - Cannot submit parallel transactions (must wait for confirmation)
+ * - Transaction N+1 cannot be mined before transaction N
+ *
+ * This contract is designed for use by community-developed services that need
+ * strict sequential ordering for their operations.
+ */
 
 abstract contract SyncNonce {
+    /// @dev Thrown when the provided nonce does not match the expected next nonce
     error SyncNonceMismatch();
 
+    /// @dev Mapping to track the next expected nonce for each user
     mapping(address user => uint256 nonce) private syncNonce;
 
+    /**
+     * @notice Increments the nonce counter for a user after successful operation
+     * @dev Should be called after operation validation to advance the nonce
+     * @param user Address of the user whose nonce counter should be incremented
+     */
     function incrementSyncNonce(address user) internal virtual {
         syncNonce[user]++;
     }
 
+    /**
+     * @notice Verifies that the provided nonce matches the expected next nonce
+     * @dev Reverts with SyncNonceMismatch if the nonce is not the expected value
+     * @param user Address of the user to verify the nonce for
+     * @param nonce The nonce value to verify
+     * @custom:throws SyncNonceMismatch If nonce does not match the expected value
+     */
     function verifySyncNonce(
         address user,
         uint256 nonce
@@ -19,6 +57,12 @@ abstract contract SyncNonce {
         if (syncNonce[user] != nonce) revert SyncNonceMismatch();
     }
 
+    /**
+     * @notice Gets the current (next expected) nonce for a user
+     * @dev Public view function for external queries and transaction preparation
+     * @param user Address of the user to query
+     * @return The next nonce value that must be used by the user
+     */
     function getNextCurrentSyncNonce(
         address user
     ) public view virtual returns (uint256) {

package/library/utils/service/EvvmPayments.sol

@@ -2,14 +2,48 @@
 // Full license terms available at: https://www.evvm.info/docs/EVVMNoncommercialLicense
 
 pragma solidity ^0.8.0;
+/**
+ * @title EvvmPayments
+ * @author Mate Labs
+ * @notice Abstract contract providing EVVM payment integration for services
+ * @dev This contract provides a standardized interface for interacting with
+ * the EVVM core contract for payment operations. It supports:
+ *
+ * Payment Types:
+ * - Single payments (pay): Transfer tokens from a user to the service
+ * - Disperse payments (dispersePay): Batch payments from multiple sources
+ * - Contract-authorized payments (caPay): Service-initiated token distributions
+ * - Disperse CA payments: Batch service-initiated distributions
+ *
+ * This contract is designed for use by community-developed services that need
+ * to process payments through the EVVM ecosystem.
+ */
 
 import {IEvvm, EvvmStructs} from "@evvm/testnet-contracts/interfaces/IEvvm.sol";
 
 abstract contract EvvmPayments {
+    /// @dev Reference to the EVVM core contract for payment operations
     IEvvm internal evvm;
 
-    constructor(address evvmAddress) {}
+    /**
+     * @notice Initializes the EvvmPayments contract with the EVVM address
+     * @param evvmAddress Address of the EVVM core contract
+     */
+    constructor(address evvmAddress) {
+        evvm = IEvvm(evvmAddress);
+    }
 
+    /**
+     * @notice Requests a payment from a user to this contract
+     * @dev Calls the EVVM pay function to transfer tokens with signature verification
+     * @param from Address of the user making the payment
+     * @param token Address of the token being transferred
+     * @param amount Amount of tokens to transfer
+     * @param priorityFee Additional fee for priority processing
+     * @param nonce Nonce for replay protection in EVVM
+     * @param priorityFlag True for async nonce, false for sync nonce in EVVM
+     * @param signature EIP-191 signature authorizing the payment
+     */
     function requestPay(
         address from,
         address token,
@@ -33,6 +67,17 @@ abstract contract EvvmPayments {
         );
     }
 
+    /**
+     * @notice Requests a batch payment from the caller to multiple recipients
+     * @dev Calls the EVVM dispersePay function for efficient batch transfers
+     * @param toData Array of recipient addresses and amounts
+     * @param token Address of the token being transferred
+     * @param amount Total amount being transferred (for signature verification)
+     * @param priorityFee Additional fee for priority processing
+     * @param nonce Nonce for replay protection in EVVM
+     * @param priorityFlag True for async nonce, false for sync nonce in EVVM
+     * @param signature EIP-191 signature authorizing the batch payment
+     */
     function requestDispersePay(
         EvvmStructs.DispersePayMetadata[] memory toData,
         address token,
@@ -55,6 +100,14 @@ abstract contract EvvmPayments {
         );
     }
 
+    /**
+     * @notice Sends tokens from this contract to a recipient (contract-authorized)
+     * @dev Calls the EVVM caPay function for service-initiated token transfers.
+     *      This function does not require user signature as it's authorized by the contract.
+     * @param to Address of the recipient
+     * @param token Address of the token to transfer
+     * @param amount Amount of tokens to transfer
+     */
     function makeCaPay(
         address to,
         address token,
@@ -63,6 +116,14 @@ abstract contract EvvmPayments {
         evvm.caPay(to, token, amount);
     }
 
+    /**
+     * @notice Sends tokens from this contract to multiple recipients (batch CA pay)
+     * @dev Calls the EVVM disperseCaPay for efficient batch distributions.
+     *      This function does not require user signatures.
+     * @param toData Array of recipient addresses and amounts
+     * @param token Address of the token to transfer
+     * @param amount Total amount being distributed
+     */
     function makeDisperseCaPay(
         EvvmStructs.DisperseCaPayMetadata[] memory toData,
         address token,
@@ -71,6 +132,12 @@ abstract contract EvvmPayments {
         evvm.disperseCaPay(toData, token, amount);
     }
 
+    /**
+     * @notice Updates the EVVM contract address
+     * @dev Internal function for governance-controlled EVVM address changes.
+     *      Should be protected by time-delayed governance in implementing contracts.
+     * @param newEvvmAddress Address of the new EVVM contract
+     */
     function _changeEvvmAddress(address newEvvmAddress) internal virtual {
         evvm = IEvvm(newEvvmAddress);
     }

package/library/utils/service/StakingServiceUtils.sol

@@ -1,17 +1,50 @@
 // SPDX-License-Identifier: EVVM-NONCOMMERCIAL-1.0
 // Full license terms available at: https://www.evvm.info/docs/EVVMNoncommercialLicense
 pragma solidity ^0.8.0;
+/**
+ * @title StakingServiceUtils
+ * @author Mate Labs
+ * @notice Abstract contract providing staking utilities for EVVM services
+ * @dev This contract provides helper functions for services that need to
+ * interact with the EVVM Staking contract. Services can stake tokens to:
+ *
+ * Benefits of Service Staking:
+ * - Earn rewards from Fisher (executor) transaction fees
+ * - Participate in the EVVM staking ecosystem
+ * - Increase service credibility and commitment
+ *
+ * Staking Flow:
+ * 1. Call _makeStakeService with desired amount
+ * 2. Contract prepares staking, transfers tokens, and confirms
+ * 3. Call _makeUnstakeService when ready to withdraw
+ *
+ * This contract is designed for use by community-developed services that want
+ * to participate in the EVVM staking mechanism.
+ */
 
 import {IStaking} from "@evvm/testnet-contracts/interfaces/IStaking.sol";
 import {IEvvm} from "@evvm/testnet-contracts/interfaces/IEvvm.sol";
 
 abstract contract StakingServiceUtils {
+    /// @dev Reference to the Staking contract for staking operations
     IStaking internal staking;
 
+    /**
+     * @notice Initializes the StakingServiceUtils with the Staking contract address
+     * @param stakingAddress Address of the EVVM Staking contract
+     */
     constructor(address stakingAddress) {
         staking = IStaking(stakingAddress);
     }
 
+    /**
+     * @notice Stakes tokens on behalf of this service contract
+     * @dev Performs the full staking flow:
+     *      1. Prepares staking in the Staking contract
+     *      2. Transfers the required Principal Tokens via EVVM caPay
+     *      3. Confirms the staking operation
+     * @param amountToStake Number of staking units to purchase
+     */
     function _makeStakeService(uint256 amountToStake) internal {
         staking.prepareServiceStaking(amountToStake);
         IEvvm(staking.getEvvmAddress()).caPay(
@@ -22,10 +55,21 @@ abstract contract StakingServiceUtils {
         staking.confirmServiceStaking();
     }
 
+    /**
+     * @notice Unstakes tokens from this service contract
+     * @dev Calls the Staking contract to release staked tokens
+     * @param amountToUnstake Number of staking units to release
+     */
     function _makeUnstakeService(uint256 amountToUnstake) internal {
         staking.serviceUnstaking(amountToUnstake);
     }
 
+    /**
+     * @notice Updates the Staking contract address
+     * @dev Internal function for governance-controlled Staking address changes.
+     *      Should be protected by time-delayed governance in implementing contracts.
+     * @param newStakingAddress Address of the new Staking contract
+     */
     function _changeStakingAddress(address newStakingAddress) internal virtual {
         staking = IStaking(newStakingAddress);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@evvm/testnet-contracts",
-  "version": "2.2.2",
+  "version": "2.3.0",
   "type": "module",
   "description": "EVVM Testnet Contracts - Smart contracts and tools for scalable, modular, and cross-chain EVM virtualization",
   "files": [
@@ -54,6 +54,7 @@
   "dependencies": {
     "@hyperlane-xyz/core": "^3.6.1",
     "chalk": "^5.3.0",
+    "cli-loading-animation": "^1.0.6",
     "dotenv": "^16.4.5",
     "execa": "^8.0.1",
     "prompts": "^2.4.2",