@evvm/testnet-contracts 2.2.2 → 2.3.0

package/contracts/treasury/Treasury.sol

@@ -29,40 +29,48 @@ pragma solidity ^0.8.0;
 
 import {IERC20} from "@evvm/testnet-contracts/library/primitives/IERC20.sol";
 import {SafeTransferLib} from "@solady/utils/SafeTransferLib.sol";
-import {IEvvm} from "@evvm/testnet-contracts/interfaces/IEvvm.sol";
+import {Evvm} from "@evvm/testnet-contracts/contracts/evvm/Evvm.sol";
 import {
     ErrorsLib
 } from "@evvm/testnet-contracts/contracts/treasury/lib/ErrorsLib.sol";
 
 contract Treasury {
-
-    IEvvm evvm;
+    /// @dev Reference to the EVVM core contract for balance management
+    Evvm evvm;
 
     /**
      * @notice Initialize Treasury with EVVM contract address
      * @param _evvmAddress Address of the EVVM core contract
      */
     constructor(address _evvmAddress) {
-        evvm = IEvvm(_evvmAddress);
+        evvm = Evvm(_evvmAddress);
     }
 
     /**
-     * @notice Deposit ETH or ERC20 tokens
-     * @param token ERC20 token address (ignored for ETH deposits)
-     * @param amount Token amount (ignored for ETH deposits)
+     * @notice Deposit ETH or ERC20 tokens into the EVVM ecosystem
+     * @dev For ETH deposits: token must be address(0) and amount must equal msg.value
+     *      For ERC20 deposits: msg.value must be 0 and token must be a valid ERC20 contract
+     *      Deposited funds are credited to the user's EVVM balance and can be used for
+     *      gasless transactions within the ecosystem.
+     * @param token ERC20 token address (use address(0) for ETH deposits)
+     * @param amount Token amount to deposit (must match msg.value for ETH deposits)
+     * @custom:throws DepositAmountMustBeGreaterThanZero If amount/msg.value is zero
+     * @custom:throws InvalidDepositAmount If amount doesn't match msg.value (ETH) or msg.value != 0 (ERC20)
      */
     function deposit(address token, uint256 amount) external payable {
         if (address(0) == token) {
             /// user is sending host native coin
             if (msg.value == 0)
                 revert ErrorsLib.DepositAmountMustBeGreaterThanZero();
+
             if (amount != msg.value) revert ErrorsLib.InvalidDepositAmount();
 
             evvm.addAmountToUser(msg.sender, address(0), msg.value);
         } else {
             /// user is sending ERC20 tokens
 
-            if (msg.value != 0) revert ErrorsLib.InvalidDepositAmount();
+            if (msg.value != 0) revert ErrorsLib.DepositCoinWithToken();
+
             if (amount == 0)
                 revert ErrorsLib.DepositAmountMustBeGreaterThanZero();
 
@@ -72,12 +80,17 @@ contract Treasury {
     }
 
     /**
-     * @notice Withdraw ETH or ERC20 tokens
-     * @param token Token address (address(0) for ETH)
-     * @param amount Amount to withdraw
+     * @notice Withdraw ETH or ERC20 tokens from the EVVM ecosystem
+     * @dev Withdraws tokens from the user's EVVM balance back to their wallet.
+     *      Principal Tokens cannot be withdrawn through this function - they can
+     *      only be transferred via EVVM pay operations.
+     * @param token Token address to withdraw (use address(0) for ETH)
+     * @param amount Amount of tokens to withdraw
+     * @custom:throws PrincipalTokenIsNotWithdrawable If attempting to withdraw Principal Tokens
+     * @custom:throws InsufficientBalance If user's EVVM balance is less than withdrawal amount
      */
     function withdraw(address token, uint256 amount) external {
-        if (token == evvm.getEvvmMetadata().principalTokenAddress)
+        if (token == evvm.getPrincipalTokenAddress())
             revert ErrorsLib.PrincipalTokenIsNotWithdrawable();
 
         if (evvm.getBalance(msg.sender, token) < amount)
@@ -96,6 +109,11 @@ contract Treasury {
         }
     }
 
+    /**
+     * @notice Returns the address of the connected EVVM core contract
+     * @dev Used for verification and integration purposes
+     * @return Address of the EVVM contract managing balances
+     */
     function getEvvmAddress() external view returns (address) {
         return address(evvm);
     }

package/contracts/treasury/lib/ErrorsLib.sol

@@ -2,10 +2,40 @@
 // Full license terms available at: https://www.evvm.info/docs/EVVMNoncommercialLicense
 
 pragma solidity ^0.8.0;
+/**
+ * @title ErrorsLib
+ * @author Mate Labs
+ * @notice Library containing all custom error definitions for the Treasury contract
+ * @dev This library is exclusive to the Treasury.sol contract and provides descriptive
+ * error types for deposit and withdrawal operations.
+ *
+ * Error Categories:
+ * - Balance Errors: Insufficient funds for operations
+ * - Deposit Errors: Invalid deposit amounts or configurations
+ * - Withdrawal Restrictions: Token withdrawal limitations
+ */
 
 library ErrorsLib {
+    //█ Balance Errors ███████████████████████████████████████████████████████████████████████████████
+
+    /// @dev Thrown when a user attempts to withdraw more tokens than their available balance
     error InsufficientBalance();
+
+    //█ Withdrawal Restriction Errors ████████████████████████████████████████████████████████████████
+
+    /// @dev Thrown when attempting to withdraw Principal Tokens through the Treasury
+    /// @notice Principal Tokens can only be transferred through EVVM pay operations, not direct withdrawal
     error PrincipalTokenIsNotWithdrawable();
+
+    //█ Deposit Errors ███████████████████████████████████████████████████████████████████████████████
+
+    /// @dev Thrown when the deposit amount doesn't match msg.value for ETH deposits,
+    ///      or when msg.value is non-zero for ERC20 deposits
     error InvalidDepositAmount();
+
+    /// @dev Thrown when attempting to deposit zero amount of tokens or ETH
     error DepositAmountMustBeGreaterThanZero();
+
+    /// @dev Thrown when attempting to deposit blockchain native coin while also sending ERC20 tokens
+    error DepositCoinWithToken();
 }

package/contracts/treasuryTwoChains/TreasuryHostChainStation.sol

@@ -32,7 +32,7 @@ pragma solidity ^0.8.0;
  */
 
 import {IERC20} from "@evvm/testnet-contracts/library/primitives/IERC20.sol";
-import {IEvvm} from "@evvm/testnet-contracts/interfaces/IEvvm.sol";
+import {Evvm} from "@evvm/testnet-contracts/contracts/evvm/Evvm.sol";
 import {
     ErrorsLib
 } from "@evvm/testnet-contracts/contracts/treasuryTwoChains/lib/ErrorsLib.sol";
@@ -87,7 +87,7 @@ contract TreasuryHostChainStation is
 {
     /// @notice EVVM core contract for balance operations
     /// @dev Used to integrate with EVVM's balance management and token operations
-    IEvvm evvm;
+    Evvm evvm;
 
     /// @notice Admin address management with time-delayed proposals
     /// @dev Stores current admin, proposed admin, and acceptance timestamp
@@ -178,7 +178,7 @@ contract TreasuryHostChainStation is
         Ownable(_admin)
         AxelarExecutable(_crosschainConfig.axelar.gatewayAddress)
     {
-        evvm = IEvvm(_evvmAddress);
+        evvm = Evvm(_evvmAddress);
 
         admin = AddressTypeProposal({
             current: _admin,

package/interfaces/IEvvm.sol

@@ -40,16 +40,22 @@ library EvvmStructs {
 }
 
 interface IEvvm {
+    error AddressCantBeZero();
     error AsyncNonceAlreadyUsed();
+    error BreakerExploded();
+    error ImplementationIsNotActive();
+    error IncorrectAddressInput();
     error InsufficientBalance();
-    error InvalidAmount(uint256, uint256);
+    error InvalidAmount();
     error InvalidSignature();
     error NotAnCA();
+    error SenderIsNotAdmin();
     error SenderIsNotTheExecutor();
+    error SenderIsNotTheProposedAdmin();
     error SenderIsNotTreasury();
     error SyncNonceMismatch();
-    error UpdateBalanceFailed();
-    error WindowToChangeEvvmIDExpired();
+    error TimeLockNotExpired();
+    error WindowExpired();
 
     fallback() external;
 
@@ -116,6 +122,5 @@ interface IEvvm {
     function rejectUpgrade() external;
     function removeAmountFromUser(address user, address token, uint256 amount) external;
     function setEvvmID(uint256 newEvvmID) external;
-    function setNameServiceAddress(address _nameServiceAddress) external;
     function setPointStaker(address user, bytes1 answer) external;
 }

package/interfaces/INameService.sol

@@ -11,16 +11,24 @@ library NameServiceStructs {
 }
 
 interface INameService {
-    error AcceptOfferVerificationFailed();
+    error AmountMustBeGreaterThanZero();
     error AsyncNonceAlreadyUsed();
+    error CannotBeBeforeCurrentTime();
     error EmptyCustomMetadata();
-    error FlushUsernameVerificationFailed();
+    error IdentityIsNotAUsername();
+    error InvalidAdminProposal();
+    error InvalidEvvmAddress();
     error InvalidKey();
     error InvalidSignatureOnNameService();
     error InvalidUsername();
+    error InvalidWithdrawAmount();
+    error LockTimeNotExpired();
+    error OfferInactive();
+    error OwnershipExpired();
     error PreRegistrationNotValid();
-    error RenewUsernameVerificationFailed();
+    error RenewalTimeLimitExceeded();
     error SenderIsNotAdmin();
+    error SenderIsNotProposedAdmin();
     error UserIsNotOwnerOfIdentity();
     error UserIsNotOwnerOfOffer();
     error UsernameAlreadyRegistered();
@@ -85,6 +93,7 @@ interface INameService {
         external
         view
         returns (address currentEvvmAddress, address proposalEvvmAddress, uint256 timeToAcceptEvvmAddress);
+    function getEvvmID() external view returns (uint256);
     function getExpireDateOfIdentity(string memory _identity) external view returns (uint256);
     function getFullCustomMetadataOfIdentity(string memory _username) external view returns (string[] memory);
     function getIdentityBasicMetadata(string memory _username) external view returns (address, uint256);

package/interfaces/IStaking.sol

@@ -50,11 +50,12 @@ interface IStaking {
         external
         view
         returns (StakingStructs.HistoryMetadata memory);
-    function getAllDataOfAllowPublicStaking() external view returns (StakingStructs.BoolTypeProposal memory);
     function getAllowPresaleStaking() external view returns (StakingStructs.BoolTypeProposal memory);
+    function getAllowPublicStaking() external view returns (StakingStructs.BoolTypeProposal memory);
     function getEstimatorAddress() external view returns (address);
     function getEstimatorProposal() external view returns (address);
     function getEvvmAddress() external view returns (address);
+    function getEvvmID() external view returns (uint256);
     function getGoldenFisher() external view returns (address);
     function getGoldenFisherProposal() external view returns (address);
     function getIfUsedAsyncNonce(address user, uint256 nonce) external view returns (bool);

package/library/Erc191TestBuilder.sol

@@ -17,6 +17,21 @@ library Erc191TestBuilder {
     //-----------------------------------------------------------------------------------
     // EVVM
     //-----------------------------------------------------------------------------------
+    
+    /**
+     * @notice Builds the message hash for a pay operation signature
+     * @dev Creates an EIP-191 compatible hash for EVVM pay function
+     * @param evvmID Unique identifier of the EVVM instance
+     * @param _receiverAddress Address of the payment receiver (use address(0) if using identity)
+     * @param _receiverIdentity String identity of receiver (used if address is zero)
+     * @param _token Token address being transferred
+     * @param _amount Amount of tokens to transfer
+     * @param _priorityFee Priority fee for transaction processing
+     * @param _nonce Nonce for replay protection
+     * @param _priority_boolean True for async nonce, false for sync nonce
+     * @param _executor Address authorized to execute the transaction
+     * @return messageHash The EIP-191 formatted hash ready for signing
+     */
     function buildMessageSignedForPay(
         uint256 evvmID,
         address _receiverAddress,
@@ -52,6 +67,19 @@ library Erc191TestBuilder {
         messageHash = buildHashForSign(messageToSign);
     }
 
+    /**
+     * @notice Builds the message hash for a disperse pay operation signature
+     * @dev Creates an EIP-191 compatible hash for EVVM dispersePay function
+     * @param evvmID Unique identifier of the EVVM instance
+     * @param hashList Hash of the recipient list for batch payment
+     * @param _token Token address being transferred
+     * @param _amount Total amount of tokens to transfer
+     * @param _priorityFee Priority fee for transaction processing
+     * @param _nonce Nonce for replay protection
+     * @param _priority_boolean True for async nonce, false for sync nonce
+     * @param _executor Address authorized to execute the transaction
+     * @return messageHash The EIP-191 formatted hash ready for signing
+     */
     function buildMessageSignedForDispersePay(
         uint256 evvmID,
         bytes32 hashList,
@@ -90,6 +118,14 @@ library Erc191TestBuilder {
     // MATE NAME SERVICE
     //-----------------------------------------------------------------------------------
 
+    /**
+     * @notice Builds the message hash for username pre-registration
+     * @dev Creates an EIP-191 compatible hash for NameService preRegistrationUsername
+     * @param evvmID Unique identifier of the EVVM instance
+     * @param _hashUsername Hash of username + random number for commit-reveal
+     * @param _nameServiceNonce Nonce for NameService replay protection
+     * @return messageHash The EIP-191 formatted hash ready for signing
+     */
     function buildMessageSignedForPreRegistrationUsername(
         uint256 evvmID,
         bytes32 _hashUsername,
@@ -109,6 +145,15 @@ library Erc191TestBuilder {
             );
     }
 
+    /**
+     * @notice Builds the message hash for username registration
+     * @dev Creates an EIP-191 compatible hash for NameService registrationUsername
+     * @param evvmID Unique identifier of the EVVM instance
+     * @param _username The username being registered
+     * @param _clowNumber Random number from pre-registration
+     * @param _nameServiceNonce Nonce for NameService replay protection
+     * @return messageHash The EIP-191 formatted hash ready for signing
+     */
     function buildMessageSignedForRegistrationUsername(
         uint256 evvmID,
         string memory _username,
@@ -131,6 +176,16 @@ library Erc191TestBuilder {
             );
     }
 
+    /**
+     * @notice Builds the message hash for making a username offer
+     * @dev Creates an EIP-191 compatible hash for NameService makeOffer
+     * @param evvmID Unique identifier of the EVVM instance
+     * @param _username Target username for the offer
+     * @param _dateExpire Timestamp when the offer expires
+     * @param _amount Amount being offered in Principal Tokens
+     * @param _nameServiceNonce Nonce for NameService replay protection
+     * @return messageHash The EIP-191 formatted hash ready for signing
+     */
     function buildMessageSignedForMakeOffer(
         uint256 evvmID,
         string memory _username,
@@ -156,6 +211,15 @@ library Erc191TestBuilder {
             );
     }
 
+    /**
+     * @notice Builds the message hash for withdrawing a username offer
+     * @dev Creates an EIP-191 compatible hash for NameService withdrawOffer
+     * @param evvmID Unique identifier of the EVVM instance
+     * @param _username Username the offer was made for
+     * @param _offerId ID of the offer to withdraw
+     * @param _nameServiceNonce Nonce for NameService replay protection
+     * @return messageHash The EIP-191 formatted hash ready for signing
+     */
     function buildMessageSignedForWithdrawOffer(
         uint256 evvmID,
         string memory _username,
@@ -178,6 +242,15 @@ library Erc191TestBuilder {
             );
     }
 
+    /**
+     * @notice Builds the message hash for accepting a username offer
+     * @dev Creates an EIP-191 compatible hash for NameService acceptOffer
+     * @param evvmID Unique identifier of the EVVM instance
+     * @param _username Username being sold
+     * @param _offerId ID of the offer to accept
+     * @param _nameServiceNonce Nonce for NameService replay protection
+     * @return messageHash The EIP-191 formatted hash ready for signing
+     */
     function buildMessageSignedForAcceptOffer(
         uint256 evvmID,
         string memory _username,
@@ -200,6 +273,14 @@ library Erc191TestBuilder {
             );
     }
 
+    /**
+     * @notice Builds the message hash for renewing a username
+     * @dev Creates an EIP-191 compatible hash for NameService renewUsername
+     * @param evvmID Unique identifier of the EVVM instance
+     * @param _username Username to renew
+     * @param _nameServiceNonce Nonce for NameService replay protection
+     * @return messageHash The EIP-191 formatted hash ready for signing
+     */
     function buildMessageSignedForRenewUsername(
         uint256 evvmID,
         string memory _username,
@@ -219,6 +300,15 @@ library Erc191TestBuilder {
             );
     }
 
+    /**
+     * @notice Builds the message hash for adding custom metadata
+     * @dev Creates an EIP-191 compatible hash for NameService addCustomMetadata
+     * @param evvmID Unique identifier of the EVVM instance
+     * @param _username Username to add metadata to
+     * @param _value Metadata value following schema format
+     * @param _nameServiceNonce Nonce for NameService replay protection
+     * @return messageHash The EIP-191 formatted hash ready for signing
+     */
     function buildMessageSignedForAddCustomMetadata(
         uint256 evvmID,
         string memory _username,
@@ -241,6 +331,15 @@ library Erc191TestBuilder {
             );
     }
 
+    /**
+     * @notice Builds the message hash for removing custom metadata
+     * @dev Creates an EIP-191 compatible hash for NameService removeCustomMetadata
+     * @param evvmID Unique identifier of the EVVM instance
+     * @param _username Username to remove metadata from
+     * @param _key Index of the metadata entry to remove
+     * @param _nonce Nonce for NameService replay protection
+     * @return messageHash The EIP-191 formatted hash ready for signing
+     */
     function buildMessageSignedForRemoveCustomMetadata(
         uint256 evvmID,
         string memory _username,
@@ -263,6 +362,14 @@ library Erc191TestBuilder {
             );
     }
 
+    /**
+     * @notice Builds the message hash for flushing all custom metadata
+     * @dev Creates an EIP-191 compatible hash for NameService flushCustomMetadata
+     * @param evvmID Unique identifier of the EVVM instance
+     * @param _username Username to flush metadata from
+     * @param _nonce Nonce for NameService replay protection
+     * @return messageHash The EIP-191 formatted hash ready for signing
+     */
     function buildMessageSignedForFlushCustomMetadata(
         uint256 evvmID,
         string memory _username,
@@ -282,6 +389,14 @@ library Erc191TestBuilder {
             );
     }
 
+    /**
+     * @notice Builds the message hash for flushing a username
+     * @dev Creates an EIP-191 compatible hash for NameService flushUsername
+     * @param evvmID Unique identifier of the EVVM instance
+     * @param _username Username to completely remove
+     * @param _nonce Nonce for NameService replay protection
+     * @return messageHash The EIP-191 formatted hash ready for signing
+     */
     function buildMessageSignedForFlushUsername(
         uint256 evvmID,
         string memory _username,
@@ -305,6 +420,16 @@ library Erc191TestBuilder {
     // staking functions
     //-----------------------------------------------------------------------------------
 
+    /**
+     * @notice Builds the message hash for public service staking
+     * @dev Creates an EIP-191 compatible hash for Staking publicServiceStaking
+     * @param evvmID Unique identifier of the EVVM instance
+     * @param _serviceAddress Address of the service to stake for
+     * @param _isStaking True for staking, false for unstaking
+     * @param _amountOfStaking Amount of staking units
+     * @param _nonce Nonce for replay protection
+     * @return messageHash The EIP-191 formatted hash ready for signing
+     */
     function buildMessageSignedForPublicServiceStake(
         uint256 evvmID,
         address _serviceAddress,
@@ -330,6 +455,15 @@ library Erc191TestBuilder {
             );
     }
 
+    /**
+     * @notice Builds the message hash for public staking
+     * @dev Creates an EIP-191 compatible hash for Staking publicStaking
+     * @param evvmID Unique identifier of the EVVM instance
+     * @param _isStaking True for staking, false for unstaking
+     * @param _amountOfStaking Amount of staking units
+     * @param _nonce Nonce for replay protection
+     * @return messageHash The EIP-191 formatted hash ready for signing
+     */
     function buildMessageSignedForPublicStaking(
         uint256 evvmID,
         bool _isStaking,
@@ -352,6 +486,15 @@ library Erc191TestBuilder {
             );
     }
 
+    /**
+     * @notice Builds the message hash for presale staking
+     * @dev Creates an EIP-191 compatible hash for Staking presaleStaking
+     * @param evvmID Unique identifier of the EVVM instance
+     * @param _isStaking True for staking, false for unstaking
+     * @param _amountOfStaking Amount of staking units
+     * @param _nonce Nonce for replay protection
+     * @return messageHash The EIP-191 formatted hash ready for signing
+     */
     function buildMessageSignedForPresaleStaking(
         uint256 evvmID,
         bool _isStaking,
@@ -378,6 +521,17 @@ library Erc191TestBuilder {
     // P2PSwap functions
     //-----------------------------------------------------------------------------------
 
+    /**
+     * @notice Builds the message hash for making a P2P swap order
+     * @dev Creates an EIP-191 compatible hash for P2PSwap makeOrder
+     * @param evvmID Unique identifier of the EVVM instance
+     * @param _nonce Nonce for replay protection
+     * @param _tokenA Token address being offered
+     * @param _tokenB Token address being requested
+     * @param _amountA Amount of tokenA being offered
+     * @param _amountB Amount of tokenB being requested
+     * @return messageHash The EIP-191 formatted hash ready for signing
+     */
     function buildMessageSignedForMakeOrder(
         uint256 evvmID,
         uint256 _nonce,
@@ -406,6 +560,16 @@ library Erc191TestBuilder {
             );
     }
 
+    /**
+     * @notice Builds the message hash for canceling a P2P swap order
+     * @dev Creates an EIP-191 compatible hash for P2PSwap cancelOrder
+     * @param evvmID Unique identifier of the EVVM instance
+     * @param _nonce Nonce for replay protection
+     * @param _tokenA Token address that was offered
+     * @param _tokenB Token address that was requested
+     * @param _orderId ID of the order to cancel
+     * @return messageHash The EIP-191 formatted hash ready for signing
+     */
     function buildMessageSignedForCancelOrder(
         uint256 evvmID,
         uint256 _nonce,
@@ -431,6 +595,16 @@ library Erc191TestBuilder {
             );
     }
 
+    /**
+     * @notice Builds the message hash for dispatching (accepting) a P2P swap order
+     * @dev Creates an EIP-191 compatible hash for P2PSwap dispatchOrder
+     * @param evvmID Unique identifier of the EVVM instance
+     * @param _nonce Nonce for replay protection
+     * @param _tokenA Token address that was offered
+     * @param _tokenB Token address that was requested
+     * @param _orderId ID of the order to dispatch
+     * @return messageHash The EIP-191 formatted hash ready for signing
+     */
     function buildMessageSignedForDispatchOrder(
         uint256 evvmID,
         uint256 _nonce,
@@ -460,6 +634,12 @@ library Erc191TestBuilder {
     // General functions
     //-----------------------------------------------------------------------------------
 
+    /**
+     * @notice Creates an EIP-191 formatted hash from a message string
+     * @dev Prepends the Ethereum Signed Message prefix and message length
+     * @param messageToSign The message string to hash
+     * @return The EIP-191 formatted hash ready for signature verification
+     */
     function buildHashForSign(
         string memory messageToSign
     ) internal pure returns (bytes32) {
@@ -473,6 +653,14 @@ library Erc191TestBuilder {
             );
     }
 
+    /**
+     * @notice Combines signature components into a 65-byte signature
+     * @dev Packs r, s, and v into the standard EIP-191 signature format
+     * @param v Recovery identifier (27 or 28)
+     * @param r First 32 bytes of the signature
+     * @param s Second 32 bytes of the signature
+     * @return 65-byte encoded signature in (r, s, v) format
+     */
     function buildERC191Signature(
         uint8 v,
         bytes32 r,

package/library/EvvmService.sol

@@ -2,6 +2,36 @@
 // Full license terms available at: https://www.evvm.info/docs/EVVMNoncommercialLicense
 
 pragma solidity ^0.8.0;
+/**
+ * @title EvvmService
+ * @author Mate Labs
+ * @notice Abstract base contract for building services on the EVVM ecosystem
+ * @dev This contract provides a complete foundation for creating EVVM-compatible services.
+ * It combines multiple utility contracts to offer:
+ *
+ * Core Capabilities:
+ * - Async nonce management for replay protection (AsyncNonce)
+ * - Staking utilities for service-level staking (StakingServiceUtils)
+ * - Payment processing through the EVVM core (EvvmPayments)
+ * - EIP-191 signature verification for gasless transactions
+ *
+ * Usage:
+ * Inherit from this contract and implement your service logic. All signature
+ * verification, payment processing, and nonce management are handled automatically.
+ *
+ * Example:
+ * ```solidity
+ * contract MyService is EvvmService {
+ *     constructor(address evvm, address staking)
+ *         EvvmService(evvm, staking) {}
+ *
+ *     function myFunction(address user, ..., bytes memory sig) external {
+ *         validateServiceSignature("myFunction", "...", sig, user);
+ *         // Your logic here
+ *     }
+ * }
+ * ```
+ */
 
 import {EvvmStructs} from "@evvm/testnet-contracts/interfaces/IEvvm.sol";
 import {SignatureUtil} from "@evvm/testnet-contracts/library/utils/SignatureUtil.sol";
@@ -14,13 +44,29 @@ abstract contract EvvmService is
     StakingServiceUtils,
     EvvmPayments
 {
+    /// @dev Thrown when a signature verification fails for a service operation
     error InvalidServiceSignature();
 
+    /**
+     * @notice Initializes the EvvmService with EVVM and Staking contract addresses
+     * @param evvmAddress Address of the EVVM core contract for payment processing
+     * @param stakingAddress Address of the Staking contract for service staking operations
+     */
     constructor(
         address evvmAddress,
         address stakingAddress
     ) StakingServiceUtils(stakingAddress) EvvmPayments(evvmAddress) {}
 
+    /**
+     * @notice Validates an EIP-191 signature for a service operation
+     * @dev Verifies that the signature was created by the expected signer using the EVVM ID,
+     *      function name, and inputs as the signed message
+     * @param functionName Name of the function being called (used in signature message)
+     * @param inputs Comma-separated string of function inputs (used in signature message)
+     * @param signature The EIP-191 signature to verify
+     * @param expectedSigner Address that should have signed the message
+     * @custom:throws InvalidServiceSignature If signature verification fails
+     */
     function validateServiceSignature(
         string memory functionName,
         string memory inputs,
@@ -37,4 +83,13 @@ abstract contract EvvmService is
             )
         ) revert InvalidServiceSignature();
     }
+
+    /**
+     * @notice Retrieves the unique EVVM instance identifier
+     * @dev Used internally for signature verification to ensure signatures are chain-specific
+     * @return The unique identifier of the connected EVVM instance
+     */
+    function getEvvmID() internal view returns (uint256) {
+        return evvm.getEvvmID();
+    }
 }