@evvm/testnet-contracts 2.2.3 → 3.0.0

package/library/structs/ExternalChainStationStructs.sol

@@ -0,0 +1,92 @@
+// SPDX-License-Identifier: EVVM-NONCOMMERCIAL-1.0
+// Full license terms available at: https://www.evvm.info/docs/EVVMNoncommercialLicense
+
+pragma solidity ^0.8.0;
+
+/**
+ * @title External Chain Station Data Structures
+ * @author Mate labs
+ * @notice Data structures for external to host chain bridge
+ * @dev Structures for TreasuryExternalChainStation: multi-protocol messaging (Hyperlane, LayerZero, Axelar). Independent from Core.sol (Fisher bridge has own nonces).
+ */
+library ExternalChainStationStructs {
+    /**
+     * @notice Time-delayed address proposal for governance
+     * @dev 1-day delay for admin/fisherExecutor changes. Only proposal address can accept.
+     * @param current Currently active address
+     * @param proposal Proposed new address (1 day delay)
+     * @param timeToAccept Timestamp when acceptable
+     */
+    struct AddressTypeProposal {
+        address current;
+        address proposal;
+        uint256 timeToAccept;
+    }
+
+    /**
+     * @notice Hyperlane protocol configuration
+     * @dev Hyperlane cross-chain messaging: domain ID + mailbox. External → Host via mailbox.dispatch.
+     * @param hostChainStationDomainId Hyperlane domain for host
+     * @param hostChainStationAddress Host station (bytes32)
+     * @param mailboxAddress Hyperlane mailbox on this chain
+     */
+    struct HyperlaneConfig {
+        uint32 hostChainStationDomainId;
+        bytes32 hostChainStationAddress;
+        address mailboxAddress;
+    }
+
+    /**
+     * @notice LayerZero V2 protocol configuration
+     * @dev LayerZero V2 omnichain: eid + endpoint. External → Host via endpoint.send. Gas limit 200k.
+     * @param hostChainStationEid LayerZero eid for host chain
+     * @param hostChainStationAddress Host station (bytes32)
+     * @param endpointAddress LayerZero V2 endpoint address
+     */
+    struct LayerZeroConfig {
+        uint32 hostChainStationEid;
+        bytes32 hostChainStationAddress;
+        address endpointAddress;
+    }
+
+    /**
+     * @notice Axelar protocol configuration
+     * @dev Axelar cross-chain: chainName + gateway. External → Host via gateway.callContract.
+     * @param hostChainStationChainName Axelar chain name
+     * @param hostChainStationAddress Host station (string)
+     * @param gasServiceAddress Axelar gas service
+     * @param gatewayAddress Axelar gateway contract
+     */
+    struct AxelarConfig {
+        string hostChainStationChainName;
+        string hostChainStationAddress;
+        address gasServiceAddress;
+        address gatewayAddress;
+    }
+
+    /**
+     * @notice Unified deployment configuration
+     * @dev Groups all protocol configs: Hyperlane, LayerZero V2, Axelar.
+     */
+    struct CrosschainConfig {
+        HyperlaneConfig hyperlane;
+        LayerZeroConfig layerZero;
+        AxelarConfig axelar;
+    }
+
+    /**
+     * @notice Coordinated host chain address change proposal
+     * @dev 1-day delay to update host station across all protocols. AddressType for Hyperlane/LZ, StringType for Axelar.
+     * @param porposeAddress_AddressType Address for Hyperlane/LZ
+     * @param porposeAddress_StringType String for Axelar
+     * @param currentAddress Current host station address
+     * @param timeToAccept Timestamp when acceptable
+     */
+    struct ChangeHostChainAddressParams {
+        address porposeAddress_AddressType;
+        string porposeAddress_StringType;
+        address currentAddress;
+        uint256 timeToAccept;
+    }
+}
+

package/library/structs/HostChainStationStructs.sol

@@ -0,0 +1,77 @@
+// SPDX-License-Identifier: EVVM-NONCOMMERCIAL-1.0
+// Full license terms available at: https://www.evvm.info/docs/EVVMNoncommercialLicense
+
+pragma solidity ^0.8.0;
+
+/**
+ * @title Host Chain Station Data Structures
+ * @author Mate labs
+ * @notice Data structures for host to external chain bridge
+ * @dev Structures for TreasuryHostChainStation: multi-protocol messaging (Hyperlane, LayerZero, Axelar). Core.sol balance management on host only. Fisher bridge uses Core.sol nonces.
+ */
+
+library HostChainStationStructs {
+    /**
+     * @notice Hyperlane protocol configuration
+     * @dev Hyperlane cross-chain messaging: domain ID + mailbox. Host → External via mailbox.dispatch.
+     * @param externalChainStationDomainId Hyperlane domain for external
+     * @param externalChainStationAddress External station (bytes32)
+     * @param mailboxAddress Hyperlane mailbox on host chain
+     */
+    struct HyperlaneConfig {
+        uint32 externalChainStationDomainId;
+        bytes32 externalChainStationAddress;
+        address mailboxAddress;
+    }
+
+    /**
+     * @notice LayerZero V2 protocol configuration
+     * @dev LayerZero V2 omnichain: eid + endpoint. Host → External via endpoint.send. Gas limit 200k.
+     * @param externalChainStationEid LayerZero eid for external chain
+     * @param externalChainStationAddress External station (bytes32)
+     * @param endpointAddress LayerZero V2 endpoint address
+     */
+    struct LayerZeroConfig {
+        uint32 externalChainStationEid;
+        bytes32 externalChainStationAddress;
+        address endpointAddress;
+    }
+
+    /**
+     * @notice Axelar protocol configuration
+     * @dev Axelar cross-chain: chainName + gateway. Host → External via gateway.callContract.
+     * @param externalChainStationChainName Axelar chain name
+     * @param externalChainStationAddress External station (string)
+     * @param gasServiceAddress Axelar gas service
+     * @param gatewayAddress Axelar gateway contract
+     */
+    struct AxelarConfig {
+        string externalChainStationChainName;
+        string externalChainStationAddress;
+        address gasServiceAddress;
+        address gatewayAddress;
+    }
+
+    /**
+     * @notice Unified deployment configuration
+     * @dev Groups all protocol configs: Hyperlane, LayerZero V2, Axelar.
+     */
+    struct CrosschainConfig {
+        HyperlaneConfig hyperlane;
+        LayerZeroConfig layerZero;
+        AxelarConfig axelar;
+    }
+
+    /**
+     * @notice Coordinated external chain address change proposal
+     * @dev 1-day delay to update external station across all protocols. AddressType for Hyperlane/LZ, StringType for Axelar.
+     * @param porposeAddress_AddressType Address for Hyperlane/LZ
+     * @param porposeAddress_StringType String for Axelar
+     * @param timeToAccept Timestamp when acceptable
+     */
+    struct ChangeExternalChainAddressParams {
+        address porposeAddress_AddressType;
+        string porposeAddress_StringType;
+        uint256 timeToAccept;
+    }
+}

package/library/structs/NameServiceStructs.sol

@@ -0,0 +1,47 @@
+// SPDX-License-Identifier: EVVM-NONCOMMERCIAL-1.0
+// Full license terms available at: https://www.evvm.info/docs/EVVMNoncommercialLicense
+
+pragma solidity ^0.8.0;
+
+/**
+ * @title NameServiceStructs
+ * @author Mate labs
+ * @notice Data structures for NameService.sol (identity, marketplace, governance)
+ * @dev Identity and marketplace structures. Nonce validation and payment processing via Core.sol.
+ */
+library NameServiceStructs {
+
+    //░▒▓█ Identity Management Structures ███████████████████████████████████████████████▓▒░
+
+    /**
+     * @notice Core metadata for registered identity/username
+     * @dev Registration states: flagNotAUsername (0x01=pre-reg, 0x00=active). Renewable up to 100 years. Cost: 100x EVVM reward.
+     * @param owner Owner address
+     * @param expirationDate Registration expiry timestamp
+     * @param customMetadataMaxSlots Metadata entry count
+     * @param offerMaxSlots Highest offer ID
+     * @param flagNotAUsername Registration state flag
+     */
+    struct IdentityBaseMetadata {
+        address owner;
+        uint256 expirationDate;
+        uint256 customMetadataMaxSlots;
+        uint256 offerMaxSlots;
+        bytes1 flagNotAUsername;
+    }
+
+    //░▒▓█ Marketplace Structures ███████████████████████████████████████████████████████▓▒░
+
+    /**
+     * @notice Metadata for marketplace offers on usernames
+     * @dev Lifecycle: Created (locked PT with 0.5% fee) → Active (can be accepted/withdrawn) → Completed (offerer = address(0)).
+     * @param offerer Offer creator (can withdraw)
+     * @param expirationDate Offer expiry timestamp
+     * @param amount PT offered (after 0.5% fee)
+     */
+    struct OfferMetadata {
+        address offerer;
+        uint256 expirationDate;
+        uint256 amount;
+    }
+}

package/library/structs/P2PSwapStructs.sol

@@ -0,0 +1,127 @@
+// SPDX-License-Identifier: EVVM-NONCOMMERCIAL-1.0
+// Full license terms available at: https://www.evvm.info/docs/EVVMNoncommercialLicense
+
+pragma solidity ^0.8.0;
+
+/**
+ * @title P2P Swap Data Structures
+ * @author Mate labs
+ * @notice Core data structures for P2PSwap.sol order book (markets, orders, fees, operation metadata)
+ * @dev All operations validated via Core.sol async nonces. Payments via Core.sol.
+ */
+
+abstract contract P2PSwapStructs {
+    /**
+     * @notice Market metadata for token pair trading
+     * @dev Tracks order slot allocation and active order count.
+     * @param tokenA First token in pair
+     * @param tokenB Second token in pair
+     * @param maxSlot Highest slot number assigned
+     * @param ordersAvailable Active order count
+     */
+    struct MarketInformation {
+        address tokenA;
+        address tokenB;
+        uint256 maxSlot;
+        uint256 ordersAvailable;
+    }
+
+    /**
+     * @notice Core order data stored on-chain
+     * @dev Minimal storage for gas efficiency. Token addresses inferred from market ID. Deleted orders: seller = address(0).
+     * @param seller Order creator
+     * @param amountA Amount of tokenA offered
+     * @param amountB Amount of tokenB requested
+     */
+    struct Order {
+        address seller;
+        uint256 amountA;
+        uint256 amountB;
+    }
+
+    /**
+     * @notice Extended order data for view functions
+     * @dev Includes market and order IDs for UI display.
+     * @param marketId Market containing order
+     * @param orderId Order slot ID
+     * @param seller Order creator
+     * @param amountA Amount of tokenA offered
+     * @param amountB Amount of tokenB requested
+     */
+    struct OrderForGetter {
+        uint256 marketId;
+        uint256 orderId;
+        address seller;
+        uint256 amountA;
+        uint256 amountB;
+    }
+
+    /**
+     * @notice Fee distribution percentages for trades (basis points)
+     * @dev Total must equal 10,000 (100.00%). Adjustable via time-delayed governance.
+     * @param seller Basis points to order seller
+     * @param service Basis points to P2PSwap service
+     * @param mateStaker Basis points to staker
+     */
+    struct Percentage {
+        uint256 seller;
+        uint256 service;
+        uint256 mateStaker;
+    }
+
+    /**
+     * @notice Metadata for makeOrder operation signature
+     * @dev Hashed via P2PSwapHashUtils. Validated via Core.sol with async nonce.
+     * @param nonce Async nonce
+     * @param tokenA Token offered
+     * @param tokenB Token requested
+     * @param amountA Amount offered
+     * @param amountB Amount requested
+     */
+    struct MetadataMakeOrder {
+        uint256 nonce;
+        address originExecutor;
+        address tokenA;
+        address tokenB;
+        uint256 amountA;
+        uint256 amountB;
+    }
+
+    /**
+     * @notice Metadata for cancelOrder operation signature
+     * @dev Hashed via P2PSwapHashUtils. Only order owner can cancel. Async nonce.
+     * @param nonce Async nonce
+     * @param tokenA Token A in pair
+     * @param tokenB Token B in pair
+     * @param orderId Order ID to cancel
+     * @param signature EIP-191 signature from seller
+     */
+    struct MetadataCancelOrder {
+        uint256 nonce;
+        address originExecutor;
+        address tokenA;
+        address tokenB;
+        uint256 orderId;
+        bytes signature;
+    }
+
+    /**
+     * @notice Metadata for dispatchOrder operation signature
+     * @dev Hashed via P2PSwapHashUtils. Used by both proportional and fixed fee variants. Async nonce.
+     * @param nonce Async nonce
+     * @param tokenA Token A in pair
+     * @param tokenB Token B in pair
+     * @param orderId Order ID to fill
+     * @param amountOfTokenBToFill Total tokenB including fees
+     * @param signature EIP-191 signature from buyer
+     */
+    struct MetadataDispatchOrder {
+        uint256 nonce;
+        address originExecutor;
+        address tokenA;
+        address tokenB;
+        uint256 orderId;
+        uint256 amountOfTokenBToFill;
+        bytes signature;
+    }
+}

package/library/structs/StakingStructs.sol

@@ -0,0 +1,67 @@
+// 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 Data Structures
+ * @author Mate Labs
+ * @notice Core data structures for Staking.sol (presale, history, service staking)
+ * @dev Operations validated and payments processed via Core.sol. Cost: PRICE_OF_STAKING (5083 PT) per token.
+ */
+
+library StakingStructs {
+    /**
+     * @notice Metadata for presale staker whitelist
+     * @dev Max 800 presale stakers globally. Each limited to 2 staking tokens.
+     * @param isAllow Presale whitelist status
+     * @param stakingAmount Current staking tokens staked (max 2)
+     */
+    struct PresaleStakerMetadata {
+        bool isAllow;
+        uint256 stakingAmount;
+    }
+
+    /**
+     * @notice Historical record of staking transactions
+     * @dev Transaction types: 0x01=staking, 0x02=unstaking, others=yield/rewards.
+     * @param transactionType Operation type identifier
+     * @param amount Staking tokens affected
+     * @param timestamp Block timestamp
+     * @param totalStaked Total after operation
+     */
+    struct HistoryMetadata {
+        bytes32 transactionType;
+        uint256 amount;
+        uint256 timestamp;
+        uint256 totalStaked;
+    }
+
+    /**
+     * @notice Temporary metadata for service staking process
+     * @dev Atomic 3-step process: prepareServiceStaking → Evvm.caPay → confirmServiceStaking. All steps MUST occur in same tx.
+     * @param service Contract performing staking
+     * @param timestamp Block timestamp of prepare
+     * @param amountOfStaking Staking tokens to acquire
+     * @param amountServiceBeforeStaking Service PT balance before
+     * @param amountStakingBeforeStaking Staking PT balance before
+     */
+    struct ServiceStakingMetadata {
+        address service;
+        uint256 timestamp;
+        uint256 amountOfStaking;
+        uint256 amountServiceBeforeStaking;
+        uint256 amountStakingBeforeStaking;
+    }
+
+    /**
+     * @notice Account metadata with service/EOA indicator
+     * @dev IsAService: true if code size > 0 (contract), false if code size == 0 (EOA).
+     * @param Address Account address
+     * @param IsAService Contract flag
+     */
+    struct AccountMetadata {
+        address Address;
+        bool IsAService;
+    }
+
+}

package/library/utils/AdvancedStrings.sol

@@ -2,12 +2,25 @@
 // Full license terms available at: https://www.evvm.info/docs/EVVMNoncommercialLicense
 
 pragma solidity ^0.8.0;
+/**
+ * @title AdvancedStrings
+ * @author Mate Labs
+ * @notice Type conversion library for EIP-191 signature payload construction
+ * @dev Converts uint256, address, bytes, bytes32, bool to strings. Hexadecimal output uses lowercase with "0x" prefix.
+ */
 
 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 uint256 to decimal string
+     * @dev Uses assembly for gas-efficient construction
+     * @param value Unsigned integer to convert
+     * @return Decimal string representation
+     */
     function uintToString(uint256 value) internal pure returns (string memory) {
         unchecked {
             uint256 length = Math.log10(value) + 1;
@@ -30,6 +43,11 @@ library AdvancedStrings {
         }
     }
 
+    /**
+     * @notice Converts address to hex string with "0x" prefix
+     * @param _address Address to convert
+     * @return 42-character lowercase hex string
+     */
     function addressToString(
         address _address
     ) internal pure returns (string memory) {
@@ -44,6 +62,13 @@ library AdvancedStrings {
         return string(_string);
     }
 
+    /**
+     * @notice Compares two strings for equality
+     * @dev Compares lengths then keccak256 hashes
+     * @param a First string
+     * @param b Second string
+     * @return True if identical
+     */
     function equal(
         string memory a,
         string memory b
@@ -53,37 +78,91 @@ library AdvancedStrings {
             keccak256(bytes(a)) == keccak256(bytes(b));
     }
 
+    /**
+     * @notice Converts bytes array to hex string
+     * @dev Returns "0x" for empty input
+     * @param data Bytes array to convert
+     * @return Hex string with "0x" prefix
+     */
     function bytesToString(
         bytes memory data
     ) internal pure returns (string memory) {
         if (data.length == 0) {
             return "0x";
         }
-        
+
         bytes memory result = new bytes(2 + data.length * 2);
         result[0] = "0";
         result[1] = "x";
-        
+
         for (uint256 i = 0; i < data.length; i++) {
             result[2 + i * 2] = HEX_DIGITS[uint8(data[i] >> 4)];
             result[3 + i * 2] = HEX_DIGITS[uint8(data[i] & 0x0f)];
         }
-        
+
         return string(result);
     }
 
+    /**
+     * @notice Converts bytes32 to hex string
+     * @param data Bytes32 value to convert
+     * @return 66-character hex string with "0x" prefix
+     */
     function bytes32ToString(
         bytes32 data
     ) internal pure returns (string memory) {
         bytes memory result = new bytes(66);
         result[0] = "0";
         result[1] = "x";
-        
+
         for (uint256 i = 0; i < 32; i++) {
             result[2 + i * 2] = HEX_DIGITS[uint8(data[i] >> 4)];
             result[3 + i * 2] = HEX_DIGITS[uint8(data[i] & 0x0f)];
         }
-        
+
         return string(result);
     }
+
+    /**
+     * @notice Converts boolean to string ("true"/"false")
+     * @param value Boolean to convert
+     * @return Lowercase string representation
+     */
+    function boolToString(bool value) internal pure returns (string memory) {
+        return value ? "true" : "false";
+    }
+
+    /**
+     * @notice Builds EIP-191 signature payload for Core.sol validation
+     * @dev Format: "{evvmId},{serviceAddress},{hashPayload},{nonce},{isAsyncExec}"
+     * @param evvmId Chain-specific EVVM instance identifier
+     * @param serviceAddress Service contract requesting validation
+     * @param hashPayload Function-specific parameter hash
+     * @param nonce Sequential or async nonce
+     * @param isAsyncExec Nonce type (true=async, false=sync)
+     * @return Comma-separated payload string for signature
+     */
+    function buildSignaturePayload(
+        uint256 evvmId,
+        address serviceAddress,
+        bytes32 hashPayload,
+        address executor,
+        uint256 nonce,
+        bool isAsyncExec
+    ) internal pure returns (string memory) {
+        return
+            string.concat(
+                uintToString(evvmId),
+                ",",
+                addressToString(serviceAddress),
+                ",",
+                bytes32ToString(hashPayload),
+                ",",
+                addressToString(executor),
+                ",",
+                uintToString(nonce),
+                ",",
+                boolToString(isAsyncExec)
+            );
+    }
 }

package/library/utils/CAUtils.sol

@@ -0,0 +1,29 @@
+// SPDX-License-Identifier: EVVM-NONCOMMERCIAL-1.0
+// Full license terms available at: https://www.evvm.info/docs/EVVMNoncommercialLicense
+
+pragma solidity ^0.8.0;
+
+/**
+ * @title Contract Address Verification Utilities
+ * @author Mate labs
+ * @notice Utilities for detecting contract addresses vs EOAs
+ * @dev Uses extcodesize opcode. Returns false during contract construction and after self-destruct.
+ */
+library CAUtils {
+    /**
+     * @notice Checks if address is a contract using extcodesize
+     * @dev Returns false during construction and after self-destruct. Not reliable as sole security check.
+     * @param from Address to check
+     * @return true if contract (codesize > 0), false if EOA
+     */
+    function verifyIfCA(address from) internal view returns (bool) {
+        uint256 size;
+
+        assembly {
+            /// @dev check the size of the opcode of the address
+            size := extcodesize(from)
+        }
+
+        return (size != 0);
+    }
+}

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,