@evvm/testnet-contracts 2.2.3 → 3.0.0

package/library/EvvmService.sol

@@ -2,39 +2,50 @@
 // Full license terms available at: https://www.evvm.info/docs/EVVMNoncommercialLicense
 
 pragma solidity ^0.8.0;
+/**
+ * @title EVVM Service Base Contract
+ * @author Mate Labs
+ * @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
-{
+abstract contract EvvmService is CoreExecution, StakingServiceUtils {
+    /// @dev Thrown when signature validation fails
     error InvalidServiceSignature();
 
+    /**
+     * @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) {}
 
-    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();
+    /**
+     * @notice Gets unique EVVM instance identifier for signature validation
+     * @dev Returns core.getEvvmID(). Prevents cross-chain replays.
+     * @return Unique EVVM instance identifier
+     */
+    function getEvvmID() internal view returns (uint256) {
+        return core.getEvvmID();
+    }
+
+    /**
+     * @notice Gets Principal Token (MATE) address
+     * @dev Returns core.getPrincipalTokenAddress(). Used for payment operations.
+     * @return Address of Principal Token (MATE)
+     */
+    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/library/errors/TreasuryError.sol

@@ -0,0 +1,33 @@
+// SPDX-License-Identifier: EVVM-NONCOMMERCIAL-1.0
+// Full license terms available at: https://www.evvm.info/docs/EVVMNoncommercialLicense
+
+pragma solidity ^0.8.0;
+/**
+ * @title TreasuryError
+ * @author Mate Labs
+ * @notice Custom errors for Treasury.sol
+ * @dev Gas-efficient error definitions for deposit/withdrawal operations.
+ */
+
+library TreasuryError {
+    //█ Balance Errors ███████████████████████████████████████████████████████████████████████████████
+
+    /// @dev Thrown when withdrawal amount > user balance
+    error InsufficientBalance();
+
+    //█ Withdrawal Restriction Errors ████████████████████████████████████████████████████████████████
+
+    /// @dev Thrown when attempting to withdraw Principal Token (must use EVVM pay operations)
+    error PrincipalTokenIsNotWithdrawable();
+
+    //█ Deposit Errors ███████████████████████████████████████████████████████████████████████████████
+
+    /// @dev Thrown when deposit amount != msg.value (ETH) or msg.value != 0 (ERC20)
+    error InvalidDepositAmount();
+
+    /// @dev Thrown when deposit amount == 0
+    error DepositAmountMustBeGreaterThanZero();
+
+    /// @dev Thrown when attempting to deposit both native coin and ERC20 simultaneously
+    error DepositCoinWithToken();
+}

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/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;
+    }
+}