@evvm/testnet-contracts 2.3.0 → 3.0.1

package/library/EvvmService.sol

@@ -3,93 +3,49 @@
 
 pragma solidity ^0.8.0;
 /**
- * @title EvvmService
+ * @title EVVM Service Base Contract
  * @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
- *     }
- * }
- * ```
+ * @notice Abstract base contract for building EVVM services with payment, staking, and nonce management
+ * @dev Inherits StakingServiceUtils, CoreExecution, StateManagment. Signatures validated via Core.sol. Community can build custom services.
  */
 
-import {EvvmStructs} from "@evvm/testnet-contracts/interfaces/IEvvm.sol";
-import {SignatureUtil} from "@evvm/testnet-contracts/library/utils/SignatureUtil.sol";
-import {AsyncNonce} from "@evvm/testnet-contracts/library/utils/nonces/AsyncNonce.sol";
-import {StakingServiceUtils} from "@evvm/testnet-contracts/library/utils/service/StakingServiceUtils.sol";
-import {EvvmPayments} from "@evvm/testnet-contracts/library/utils/service/EvvmPayments.sol";
+import {
+    CoreExecution
+} from "@evvm/testnet-contracts/library/utils/service/CoreExecution.sol";
+import {
+    StakingServiceUtils
+} from "@evvm/testnet-contracts/library/utils/service/StakingServiceUtils.sol";
 
-abstract contract EvvmService is
-    AsyncNonce,
-    StakingServiceUtils,
-    EvvmPayments
-{
-    /// @dev Thrown when a signature verification fails for a service operation
+abstract contract EvvmService is CoreExecution, StakingServiceUtils {
+    /// @dev Thrown when signature validation fails
     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
+     * @notice Initializes EVVM service with core contract references
+     * @dev Initializes StakingServiceUtils, CoreExecution, StateManagment in order
+     * @param coreAddress Address of Core.sol contract
+     * @param stakingAddress Address of Staking.sol contract
      */
     constructor(
-        address evvmAddress,
+        address coreAddress,
         address stakingAddress
-    ) StakingServiceUtils(stakingAddress) EvvmPayments(evvmAddress) {}
+    ) StakingServiceUtils(stakingAddress) CoreExecution(coreAddress) {}
 
     /**
-     * @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
+     * @notice Gets unique EVVM instance identifier for signature validation
+     * @dev Returns core.getEvvmID(). Prevents cross-chain replays.
+     * @return Unique EVVM instance identifier
      */
-    function validateServiceSignature(
-        string memory functionName,
-        string memory inputs,
-        bytes memory signature,
-        address expectedSigner
-    ) internal view virtual {
-        if (
-            !SignatureUtil.verifySignature(
-                evvm.getEvvmID(),
-                functionName,
-                inputs,
-                signature,
-                expectedSigner
-            )
-        ) revert InvalidServiceSignature();
+    function getEvvmID() internal view returns (uint256) {
+        return core.getEvvmID();
     }
 
     /**
-     * @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
+     * @notice Gets Principal Token (MATE) address
+     * @dev Returns core.getPrincipalTokenAddress(). Used for payment operations.
+     * @return Address of Principal Token (MATE)
      */
-    function getEvvmID() internal view returns (uint256) {
-        return evvm.getEvvmID();
+    function getPrincipalTokenAddress() internal view returns (address) {
+        return core.getPrincipalTokenAddress();
     }
 }

package/library/errors/CoreError.sol

@@ -0,0 +1,116 @@
+// SPDX-License-Identifier: EVVM-NONCOMMERCIAL-1.0
+// Full license terms available at: https://www.evvm.info/docs/EVVMNoncommercialLicense
+
+pragma solidity ^0.8.0;
+
+/**
+ * @title CoreError - Error Definitions for EVVM Core
+ * @author Mate labs
+ * @notice Custom error definitions for Core.sol core contract
+ * @dev Custom errors are more gas-efficient than require
+ *      statements with strings and provide better error
+ *      handling in client applications.
+ *
+ * Error Categories:
+ * - Access Control: Unauthorized access attempts
+ * - Validation: Invalid inputs or state conditions
+ * - Balance Management: Insufficient funds or amounts
+ * - Time-Lock: Governance time delay mechanisms
+ * - Initialization: Setup and configuration errors
+ *
+ * Integration:
+ * - Used exclusively by Core.sol core contract
+ * - Includes payment and nonce validation errors
+ * - Provides clear failure reasons for users
+ *
+ * @custom:scope Exclusive to Core.sol contract
+ * @custom:security Clear failures without exposing state
+ */
+library CoreError {
+    //░▒▓█ Access Control Errors ████████████████████████████████████████████████▓▒░
+
+    /// @dev Thrown when non-admin calls admin-only function (onlyAdmin modifier)
+    error SenderIsNotAdmin();
+
+    /// @dev Thrown when proxy implementation == address(0)
+    error ImplementationIsNotActive();
+
+    /// @dev Thrown when EIP-191 signature invalid or signer mismatch
+    error InvalidSignature();
+
+    /// @dev Thrown when msg.sender != sender executor address
+    error SenderIsNotTheSenderExecutor();
+
+    /// @dev Thrown when non-treasury calls treasury-only function
+    error SenderIsNotTreasury();
+
+    /// @dev Thrown when non-proposed admin attempts acceptAdmin before timelock
+    error SenderIsNotTheProposedAdmin();
+
+    error OriginIsNotTheOriginExecutor();
+
+    /// @dev Thrown when EOA calls caPay/disperseCaPay (contract-only functions)
+    error NotAnCA();
+
+    //░▒▓█ Balance and Amount Errors ████████████████████████████████████████████▓▒░
+
+    /// @dev Thrown when balance < transfer amount
+    error InsufficientBalance();
+
+    /// @dev Thrown when amount validation fails (e.g., dispersePay total != sum)
+    error InvalidAmount();
+
+    //░▒▓█ Initialization and Setup Errors ██████████████████████████████████████▓▒░
+
+    /// @dev Thrown when one-time setup function called after breaker flag set
+    error BreakerExploded();
+
+    /// @dev Thrown when attempting EVVM ID change after 24h window
+    error WindowExpired();
+
+    /// @dev Thrown when address(0) provided (constructor, setup)
+    error AddressCantBeZero();
+
+    /// @dev Thrown when address validation fails in proposals
+    error IncorrectAddressInput();
+
+    //░▒▓█ Time-Lock Errors █████████████████████████████████████████████████████▓▒░
+
+    /// @dev Thrown when attempting time-locked action before delay (30d impl, 1d admin)
+    error TimeLockNotExpired();
+
+
+
+    /// @dev Thrown when async nonce already consumed
+    error AsyncNonceAlreadyUsed();
+
+    /// @dev Thrown when sync nonce != expected sequential nonce
+    error SyncNonceMismatch();
+
+    /// @dev Thrown when reserving already-reserved async nonce
+    error AsyncNonceAlreadyReserved();
+
+    /// @dev Thrown when revoking non-reserved async nonce
+    error AsyncNonceNotReserved();
+
+    /// @dev Thrown when using reserved async nonce (general check)
+    error AsyncNonceIsReserved();
+
+    /// @dev Thrown when UserValidator blocks user transaction
+    error UserCannotExecuteTransaction();
+
+    /// @dev Thrown when using async nonce reserved by different service
+    error AsyncNonceIsReservedByAnotherService();
+
+    /// @dev Thrown when accepting UserValidator proposal before timelock
+    error ProposalForUserValidatorNotReady();
+
+    /// @dev Thrown when validateAndConsumeNonce caller is EOA (contracts only)
+    error MsgSenderIsNotAContract();
+
+    /// @dev Thrown when accepting EVVM address proposal before timelock
+    error ProposalForEvvmAddressNotReady();
+
+    /// @dev Thrown when reserving nonce with service == address(0)
+    error InvalidServiceAddress();
+}

package/library/errors/CrossChainTreasuryError.sol

@@ -0,0 +1,36 @@
+// SPDX-License-Identifier: EVVM-NONCOMMERCIAL-1.0
+// Full license terms available at: https://www.evvm.info/docs/EVVMNoncommercialLicense
+
+pragma solidity ^0.8.0;
+
+/**
+ * @title Cross-Chain Treasury Error Library
+ * @author Mate labs
+ * @notice Custom errors for cross-chain treasury operations
+ * @dev Gas-efficient errors for TreasuryHostChainStation and TreasuryExternalChainStation. Independent from Core.sol (own nonces).
+ */
+library CrossChainTreasuryError {
+    /// @dev Thrown when Core.sol balance < withdrawal amount (host chain only)
+    error InsufficientBalance();
+
+    /// @dev Thrown when attempting to withdraw/bridge Principal Token (MATE). Cannot leave host chain.
+    error PrincipalTokenIsNotWithdrawable();
+
+    /// @dev Thrown when deposit amount validation fails (bounds check or msg.value mismatch)
+    error InvalidDepositAmount();
+
+    /// @dev Thrown when deposit/bridge amount == 0
+    error DepositAmountMustBeGreaterThanZero();
+
+    /// @dev Thrown when msg.sender != Hyperlane mailbox in message handler
+    error MailboxNotAuthorized();
+
+    /// @dev Thrown when message sender address != authorized station (Hyperlane/LayerZero/Axelar validation)
+    error SenderNotAuthorized();
+
+    /// @dev Thrown when origin chain ID != configured chain (Hyperlane domain/LayerZero eid/Axelar chainName)
+    error ChainIdNotAuthorized();
+
+    /// @dev Thrown when setEvvmID called after grace period (windowTimeToChangeEvvmID)
+     error WindowToChangeEvvmIDExpired();
+}

package/library/errors/NameServiceError.sol

@@ -0,0 +1,79 @@
+// SPDX-License-Identifier: EVVM-NONCOMMERCIAL-1.0
+// Full license terms available at: https://www.evvm.info/docs/EVVMNoncommercialLicense
+
+pragma solidity ^0.8.0;
+
+/**
+ * @title NameServiceError - Error Definitions for NameService
+ * @author Mate labs
+ * @notice Custom errors for NameService.sol
+ * @dev Gas-efficient errors used exclusively by NameService.sol. Works with Core.sol (nonce validation and payments).
+ */
+library NameServiceError {
+    //█ Access Control Errors ███████████████████████████████████████████████████
+
+    /// @dev Thrown when non-admin calls admin-only function (onlyAdmin modifier)
+    error SenderIsNotAdmin();
+
+    /// @dev Thrown when non-owner attempts to modify username or accept offers
+    error UserIsNotOwnerOfIdentity();
+
+    /// @dev Thrown when non-creator attempts withdrawOffer
+    error UserIsNotOwnerOfOffer();
+
+    /// @dev Thrown when non-proposed admin attempts acceptNewAdmin before timelock
+    error SenderIsNotProposedAdmin();
+
+    //█ Validation Errors ███████████████████████████████████████████████████████
+
+    /// @dev Thrown when username format invalid (4+ chars, start with letter, alphanumeric)
+    error InvalidUsername();
+
+    /// @dev Thrown when amount == 0 (e.g., makeOffer requires value)
+    error AmountMustBeGreaterThanZero();
+
+    /// @dev Thrown when removing non-existent custom metadata key
+    error InvalidKey();
+
+    /// @dev Thrown when custom metadata value == empty string
+    error EmptyCustomMetadata();
+
+    /// @dev Thrown when admin proposal address/config invalid
+    error InvalidAdminProposal();
+
+    /// @dev Thrown when proposed EVVM address invalid
+    error InvalidEvvmAddress();
+
+    /// @dev Thrown when withdrawal amount invalid or > balance
+    error InvalidWithdrawAmount();
+
+    //█ Registration and Time-Based Errors █████████████████████████████████████
+
+    /// @dev Thrown when attempting to register already-taken username
+    error UsernameAlreadyRegistered();
+
+    /// @dev Thrown when pre-registration doesn't exist or expired (30min window)
+    error PreRegistrationNotValid();
+
+    /// @dev Thrown when timestamp < current time (offer expiration, future ops)
+    error CannotBeBeforeCurrentTime();
+
+    /// @dev Thrown when operating on expired username (after expireDate)
+    error OwnershipExpired();
+
+    /// @dev Thrown when renewing > 100 years in advance
+    error RenewalTimeLimitExceeded();
+
+    /// @dev Thrown when time-locked governance action attempted prematurely
+    error LockTimeNotExpired();
+
+    //█ Marketplace and Offer Errors ███████████████████████████████████████████
+
+    /// @dev Thrown when accepting/interacting with expired/non-existent offer (offerer == 0)
+    error OfferInactive();
+
+    //█ Identity Type Errors ██████████████████████████████████████████████████
+
+    /// @dev Thrown when username operation attempted on pre-registration (flagNotAUsername: 0x01=pre-reg, 0x00=username)
+    error IdentityIsNotAUsername();
+}

package/library/errors/StakingError.sol

@@ -0,0 +1,79 @@
+// SPDX-License-Identifier: EVVM-NONCOMMERCIAL-1.0
+// Full license terms available at: https://www.evvm.info/docs/EVVMNoncommercialLicense
+
+pragma solidity ^0.8.0;
+/**
+ * @title Staking Error Library
+ * @author Mate Labs
+ * @notice Custom errors for Staking.sol
+ * @dev Gas-efficient errors for Staking.sol. Core.sol validates signatures and processes payments.
+ */
+
+library StakingError {
+    ///▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀
+    /// Access Control Errors
+    /// ▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀
+
+    /// @dev Thrown when non-admin calls admin-only function (onlyOwner)
+    error SenderIsNotAdmin();
+
+    /// @dev Thrown when non-goldenFisher attempts goldenStaking (sync nonces with Core.sol)
+    error SenderIsNotGoldenFisher();
+
+    /// @dev Thrown when non-proposed admin attempts acceptNewAdmin (1d delay)
+    error SenderIsNotProposedAdmin();
+
+    ///▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀
+    /// Presale Staking Errors
+    ///▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀
+
+    /// @dev Thrown when presale staking attempted while disabled (allowPresaleStaking.flag == false)
+    error PresaleStakingDisabled();
+
+    /// @dev Thrown when presale user tries to stake beyond 2-token cap
+    error UserPresaleStakerLimitExceeded();
+
+    /// @dev Thrown when non-whitelisted user attempts presaleStaking (max 800 presale stakers)
+    error UserIsNotPresaleStaker();
+
+    /// @dev Thrown when adding presale staker beyond 800 limit (LIMIT_PRESALE_STAKER)
+    error LimitPresaleStakersExceeded();
+
+    ///▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀
+    /// Public Staking Errors
+    ///▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀
+
+    /// @dev Thrown when public staking attempted while disabled (allowPublicStaking.flag == false). Uses Core.sol async nonces.
+    error PublicStakingDisabled();
+
+    ///Service Staking Errors
+
+    /// @dev Thrown when EOA calls service-only function (onlyCA checks code size)
+    error AddressIsNotAService();
+
+    /// @dev Thrown when service stakes for wrong user (user must equal service address)
+    error UserAndServiceMismatch();
+
+    /// @dev Thrown when confirmServiceStaking caller != prepareServiceStaking caller
+    error AddressMismatch();
+
+    /// @dev Thrown when Principal Token transfer != PRICE_OF_STAKING * amountOfStaking (via Evvm.caPay)
+    /// @param requiredAmount Exact Principal Tokens needed
+    error ServiceDoesNotFulfillCorrectStakingAmount(uint256 requiredAmount);
+
+    /// @dev Thrown when confirm timestamp != prepare timestamp (atomic 3-step process required)
+    error ServiceDoesNotStakeInSameTx();
+
+    ///▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀
+    /// Time Lock Errors
+    ///▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀
+
+    /// @dev Thrown when re-staking before cooldown expires (secondsToUnlockStaking.current)
+    error AddressMustWaitToStakeAgain();
+
+    /// @dev Thrown when full unstake attempted before lock period (secondsToUnllockFullUnstaking.current = 5 days)
+    error AddressMustWaitToFullUnstake();
+
+    /// @dev Thrown when accepting governance proposal before 1-day delay (TIME_TO_ACCEPT_PROPOSAL)
+    error TimeToAcceptProposalNotReached();
+}

package/{contracts/treasury/lib/ErrorsLib.sol → library/errors/TreasuryError.sol}

@@ -3,39 +3,31 @@
 
 pragma solidity ^0.8.0;
 /**
- * @title ErrorsLib
+ * @title TreasuryError
  * @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
+ * @notice Custom errors for Treasury.sol
+ * @dev Gas-efficient error definitions for deposit/withdrawal operations.
  */
 
-library ErrorsLib {
+library TreasuryError {
     //█ Balance Errors ███████████████████████████████████████████████████████████████████████████████
 
-    /// @dev Thrown when a user attempts to withdraw more tokens than their available balance
+    /// @dev Thrown when withdrawal amount > user 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
+    /// @dev Thrown when attempting to withdraw Principal Token (must use EVVM pay operations)
     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
+    /// @dev Thrown when deposit amount != msg.value (ETH) or msg.value != 0 (ERC20)
     error InvalidDepositAmount();
 
-    /// @dev Thrown when attempting to deposit zero amount of tokens or ETH
+    /// @dev Thrown when deposit amount == 0
     error DepositAmountMustBeGreaterThanZero();
 
-    /// @dev Thrown when attempting to deposit blockchain native coin while also sending ERC20 tokens
+    /// @dev Thrown when attempting to deposit both native coin and ERC20 simultaneously
     error DepositCoinWithToken();
 }

package/library/structs/CoreStructs.sol

@@ -0,0 +1,146 @@
+// SPDX-License-Identifier: EVVM-NONCOMMERCIAL-1.0
+// Full license terms available at: https://www.evvm.info/docs/EVVMNoncommercialLicense
+
+pragma solidity ^0.8.0;
+
+/**
+ * @title CoreStructs
+ * @author Mate labs
+ * @notice Data structures for Core.sol (payments, governance, metadata)
+ * @dev Payment structures with nonce validation. CA structures bypass nonces. Used by CoreStorage then Core.sol.
+ */
+
+library CoreStructs {
+    //░▒▓█ Payment Data Structures ██████████████████████████████████████████████████████▓▒░
+
+    /**
+     * @notice Data structure for single payment operations
+     * @dev Used in pay() and batchPay(). Validated via State.validateAndConsumeNonce.
+     * @param from Payment sender (signer)
+     * @param to_address Direct recipient
+     * @param to_identity Username via NameService (priority over to_address)
+     * @param token Token address (address(0) = ETH)
+     * @param amount Token amount
+     * @param priorityFee Fee for staker
+     * @param senderExecutor Authorized senderExecutor (address(0) = any)
+     * @param nonce Replay protection nonce
+     * @param isAsyncExec Nonce type (false=sync, true=async)
+     * @param signature EIP-191 signature
+     */
+    struct BatchData {
+        address from;
+        address to_address;
+        string to_identity;
+        address token;
+        uint256 amount;
+        uint256 priorityFee;
+        address senderExecutor;
+        uint256 nonce;
+        bool isAsyncExec;
+        bytes signature;
+    }
+
+    /**
+     * @notice Single-source multi-recipient payment data
+     * @dev Used in dispersePay(). Single nonce for entire batch.
+     * @param from Payment sender (signer)
+     * @param toData Recipients and amounts
+     * @param token Token address (address(0) = ETH)
+     * @param totalAmount Total distributed (must equal sum)
+     * @param priorityFee Fee for staker
+     * @param senderExecutor Authorized senderExecutor (address(0) = any)
+     * @param nonce Replay protection nonce
+     * @param isAsyncExec Nonce type (false=sync, true=async)
+     * @param signature EIP-191 signature
+     */
+    struct DisperseBatchData {
+        address from;
+        DispersePayMetadata[] toData;
+        address token;
+        uint256 totalAmount;
+        uint256 priorityFee;
+        address senderExecutor;
+        uint256 nonce;
+        bool isAsyncExec;
+        bytes signature;
+    }
+
+    /**
+     * @notice Contract-to-address payment data
+     * @dev Used in caPay(). No nonce validation (contract-authorized).
+     * @param from Sending contract (must be CA)
+     * @param to Recipient address
+     * @param token Token address (address(0) = ETH)
+     * @param amount Token amount
+     */
+    struct CaBatchData {
+        address from;
+        address to;
+        address token;
+        uint256 amount;
+    }
+
+    /**
+     * @notice Contract-based multi-recipient distribution
+     * @dev Used in disperseCaPay(). No nonce validation (contract-authorized).
+     * @param from Sending contract (must be CA)
+     * @param toData Recipients and amounts
+     * @param token Token address (address(0) = ETH)
+     * @param amount Total distributed (must equal sum)
+     */
+    struct DisperseCaBatchData {
+        address from;
+        DisperseCaPayMetadata[] toData;
+        address token;
+        uint256 amount;
+    }
+
+    //░▒▓█ Payment Metadata Structures ██████████████████████████████████████████████████▓▒░
+
+    /**
+     * @notice Recipient metadata for user-signed disperses
+     * @param amount Tokens to send
+     * @param to_address Direct recipient
+     * @param to_identity Username via NameService (priority)
+     */
+    struct DispersePayMetadata {
+        uint256 amount;
+        address to_address;
+        string to_identity;
+    }
+
+    /**
+     * @notice Recipient metadata for contract disperses
+     * @param amount Tokens to send
+     * @param toAddress Recipient address
+     */
+    struct DisperseCaPayMetadata {
+        uint256 amount;
+        address toAddress;
+    }
+
+    //░▒▓█ System Configuration Structures ██████████████████████████████████████████████▓▒░
+
+    /**
+     * @notice Core metadata configuration for EVVM instance
+     * @dev EvvmID used for cross-chain replay protection. Reward halvings occur at eraTokens supply thresholds.
+     * @param EvvmName Human-readable instance name
+     * @param EvvmID Unique ID for signature verification
+     * @param principalTokenName Principal token name
+     * @param principalTokenSymbol Principal token symbol
+     * @param principalTokenAddress Virtual token address
+     * @param totalSupply Current PT supply
+     * @param eraTokens Supply threshold for next era
+     * @param reward Current reward per transaction
+     */
+    struct EvvmMetadata {
+        string EvvmName;
+        uint256 EvvmID;
+        string principalTokenName;
+        string principalTokenSymbol;
+        address principalTokenAddress;
+        uint256 totalSupply;
+        uint256 eraTokens;
+        uint256 reward;
+    }
+}