@evvm/testnet-contracts 2.1.1 → 2.1.3

package/contracts/treasuryTwoChains/lib/ExternalChainStationStructs.sol

@@ -3,25 +3,54 @@
 
 pragma solidity ^0.8.0;
 
+/**
+ * @title ExternalChainStationStructs
+ * @author Mate labs
+ * @notice Shared data structures for External Chain Station cross-chain treasury operations
+ * @dev Defines all structural types used by TreasuryExternalChainStation contract
+ *      These structures ensure type safety and consistency for cross-chain operations
+ *      from external chains to the host chain in the EVVM ecosystem
+ */
 abstract contract ExternalChainStationStructs {
+    /// @notice Time-delayed address change proposal structure for governance
+    /// @dev Used for admin and Fisher executor address changes with 1-day delay
+    /// @param current Currently active address with full privileges
+    /// @param proposal Proposed new address waiting for acceptance
+    /// @param timeToAccept Timestamp when the proposal becomes acceptable
     struct AddressTypeProposal {
         address current;
         address proposal;
         uint256 timeToAccept;
     }
 
+    /// @notice Hyperlane protocol configuration for cross-chain messaging
+    /// @dev Configuration for reliable cross-chain communication via Hyperlane
+    /// @param hostChainStationDomainId Hyperlane domain identifier for the host chain
+    /// @param hostChainStationAddress Host chain station address in bytes32 format
+    /// @param mailboxAddress Hyperlane mailbox contract address on this chain
     struct HyperlaneConfig {
         uint32 hostChainStationDomainId;
         bytes32 hostChainStationAddress;
         address mailboxAddress;
     }
 
+    /// @notice LayerZero protocol configuration for omnichain messaging
+    /// @dev Configuration for omnichain interoperability via LayerZero V2
+    /// @param hostChainStationEid LayerZero endpoint identifier for the host chain
+    /// @param hostChainStationAddress Host chain station address in bytes32 format
+    /// @param endpointAddress LayerZero V2 endpoint contract address on this chain
     struct LayerZeroConfig {
         uint32 hostChainStationEid;
         bytes32 hostChainStationAddress;
         address endpointAddress;
     }
 
+    /// @notice Axelar protocol configuration for cross-chain communication
+    /// @dev Configuration for secure cross-chain transfers via Axelar Network
+    /// @param hostChainStationChainName Axelar chain identifier for the host chain
+    /// @param hostChainStationAddress Host chain station address in string format
+    /// @param gasServiceAddress Axelar gas service contract address for fee payments
+    /// @param gatewayAddress Axelar gateway contract address for message routing
     struct AxelarConfig {
         string hostChainStationChainName;
         string hostChainStationAddress;
@@ -29,6 +58,15 @@ abstract contract ExternalChainStationStructs {
         address gatewayAddress;
     }
 
+    /// @notice Unified cross-chain configuration for all supported protocols
+    /// @dev Single structure containing all protocol configurations for deployment
+    /// @param hostChainStationDomainId Hyperlane domain ID for host chain
+    /// @param mailboxAddress Hyperlane mailbox contract address
+    /// @param hostChainStationEid LayerZero endpoint ID for host chain
+    /// @param endpointAddress LayerZero V2 endpoint contract address
+    /// @param hostChainStationChainName Axelar chain name for host chain
+    /// @param gasServiceAddress Axelar gas service contract address
+    /// @param gatewayAddress Axelar gateway contract address
     struct CrosschainConfig {
         uint32 hostChainStationDomainId;
         address mailboxAddress;
@@ -38,4 +76,16 @@ abstract contract ExternalChainStationStructs {
         address gasServiceAddress;
         address gatewayAddress;
     }
+
+    /// @notice Parameters for coordinated host chain address changes across all protocols
+    /// @dev Used to propose and execute synchronized address updates with time delay
+    /// @param porposeAddress_AddressType Address format for Hyperlane and LayerZero protocols
+    /// @param porposeAddress_StringType String format for Axelar protocol compatibility
+    /// @param timeToAccept Timestamp when the address change proposal can be executed
+    struct ChangeHostChainAddressParams {
+        address porposeAddress_AddressType;
+        string porposeAddress_StringType;
+        uint256 timeToAccept;
+    }
 }
+

package/contracts/treasuryTwoChains/lib/HostChainStationStructs.sol

@@ -4,35 +4,54 @@
 pragma solidity ^0.8.0;
 
 /**
- * @title TreasuryStructs
- * @dev Library of common structures used across TreasuryTwoChains.
- *      This contract serves as a shared type system for the entire ecosystem,
- *      ensuring consistency in data structures between the core TreasuryTwoChains and
- *      external service contracts.
- *
- * @notice This contract should be inherited by both TreasuryTwoChains contracts
- *         that need to interact with these data structures.
+ * @title HostChainStationStructs
+ * @author Mate labs
+ * @notice Shared data structures for Host Chain Station cross-chain treasury operations
+ * @dev Defines all structural types used by TreasuryHostChainStation contract
+ *      These structures ensure type safety and consistency for cross-chain operations
+ *      from the host chain to external chains in the EVVM ecosystem
  */
 
 abstract contract HostChainStationStructs {
+    /// @notice Time-delayed address change proposal structure for governance
+    /// @dev Used for admin and Fisher executor address changes with 1-day delay
+    /// @param current Currently active address with full privileges
+    /// @param proposal Proposed new address waiting for acceptance
+    /// @param timeToAccept Timestamp when the proposal becomes acceptable
     struct AddressTypeProposal {
         address current;
         address proposal;
         uint256 timeToAccept;
     }
 
+    /// @notice Hyperlane protocol configuration for cross-chain messaging
+    /// @dev Configuration for reliable cross-chain communication via Hyperlane
+    /// @param externalChainStationDomainId Hyperlane domain identifier for the external chain
+    /// @param externalChainStationAddress External chain station address in bytes32 format
+    /// @param mailboxAddress Hyperlane mailbox contract address on this host chain
     struct HyperlaneConfig {
         uint32 externalChainStationDomainId;
         bytes32 externalChainStationAddress;
         address mailboxAddress;
     }
 
+    /// @notice LayerZero protocol configuration for omnichain messaging
+    /// @dev Configuration for omnichain interoperability via LayerZero V2
+    /// @param externalChainStationEid LayerZero endpoint identifier for the external chain
+    /// @param externalChainStationAddress External chain station address in bytes32 format
+    /// @param endpointAddress LayerZero V2 endpoint contract address on this host chain
     struct LayerZeroConfig {
         uint32 externalChainStationEid;
         bytes32 externalChainStationAddress;
         address endpointAddress;
     }
 
+    /// @notice Axelar protocol configuration for cross-chain communication
+    /// @dev Configuration for secure cross-chain transfers via Axelar Network
+    /// @param externalChainStationChainName Axelar chain identifier for the external chain
+    /// @param externalChainStationAddress External chain station address in string format
+    /// @param gasServiceAddress Axelar gas service contract address for fee payments
+    /// @param gatewayAddress Axelar gateway contract address for message routing
     struct AxelarConfig {
         string externalChainStationChainName;
         string externalChainStationAddress;
@@ -40,6 +59,15 @@ abstract contract HostChainStationStructs {
         address gatewayAddress;
     }
 
+    /// @notice Unified cross-chain configuration for all supported protocols
+    /// @dev Single structure containing all protocol configurations for deployment
+    /// @param externalChainStationDomainId Hyperlane domain ID for external chain
+    /// @param mailboxAddress Hyperlane mailbox contract address
+    /// @param externalChainStationEid LayerZero endpoint ID for external chain
+    /// @param endpointAddress LayerZero V2 endpoint contract address
+    /// @param externalChainStationChainName Axelar chain name for external chain
+    /// @param gasServiceAddress Axelar gas service contract address
+    /// @param gatewayAddress Axelar gateway contract address
     struct CrosschainConfig {
         uint32 externalChainStationDomainId;
         address mailboxAddress;
@@ -49,4 +77,15 @@ abstract contract HostChainStationStructs {
         address gasServiceAddress;
         address gatewayAddress;
     }
+
+    /// @notice Parameters for coordinated external chain address changes across all protocols
+    /// @dev Used to propose and execute synchronized address updates with time delay
+    /// @param porposeAddress_AddressType Address format for Hyperlane and LayerZero protocols
+    /// @param porposeAddress_StringType String format for Axelar protocol compatibility
+    /// @param timeToAccept Timestamp when the address change proposal can be executed
+    struct ChangeExternalChainAddressParams {
+        address porposeAddress_AddressType;
+        string porposeAddress_StringType;
+        uint256 timeToAccept;
+    }
 }

package/contracts/treasuryTwoChains/lib/PayloadUtils.sol

@@ -0,0 +1,42 @@
+// SPDX-License-Identifier: EVVM-NONCOMMERCIAL-1.0
+// Full license terms available at: https://www.evvm.info/docs/EVVMNoncommercialLicense
+pragma solidity ^0.8.0;
+
+/**
+ * @title PayloadUtils Library
+ * @author Mate labs
+ * @notice Utility library for encoding and decoding cross-chain transfer payloads
+ * @dev Provides standardized payload format for cross-chain treasury operations
+ *      Used by both TreasuryHostChainStation and TreasuryExternalChainStation
+ *      to ensure consistent data format across Hyperlane, LayerZero, and Axelar protocols
+ */
+library PayloadUtils {
+    /// @notice Encodes transfer data into a standardized cross-chain payload
+    /// @dev Uses ABI encoding for reliable cross-chain data transmission
+    /// @param token Token contract address (address(0) for native ETH)
+    /// @param toAddress Recipient address on the destination chain
+    /// @param amount Amount of tokens to transfer (in token's native decimals)
+    /// @return payload Encoded bytes containing the transfer parameters
+    function encodePayload(
+        address token,
+        address toAddress,
+        uint256 amount
+    ) internal pure returns (bytes memory payload) {
+        payload = abi.encode(token, toAddress, amount);
+    }
+
+    /// @notice Decodes a cross-chain payload back into transfer parameters
+    /// @dev Uses ABI decoding to extract the original transfer data safely
+    /// @param payload Encoded bytes received from cross-chain protocols
+    /// @return token Token contract address (address(0) indicates native ETH)
+    /// @return toAddress Recipient address extracted from the payload
+    /// @return amount Amount of tokens to transfer in token's native decimals
+    function decodePayload(
+        bytes memory payload
+    ) internal pure returns (address token, address toAddress, uint256 amount) {
+        (token, toAddress, amount) = abi.decode(
+            payload,
+            (address, address, uint256)
+        );
+    }
+}

package/contracts/treasuryTwoChains/lib/SignatureUtils.sol

@@ -7,14 +7,48 @@ import {Strings} from "@openzeppelin/contracts/utils/Strings.sol";
 
 pragma solidity ^0.8.0;
 
+/**
+ * @title SignatureUtils
+ * @author Mate labs
+ * @notice Signature verification utilities for Treasury Cross-Chain Fisher Bridge operations
+ * @dev Specialized signature verification for Fisher Bridge transactions in the EVVM cross-chain treasury system
+ *      Provides EIP-191 compliant signature verification with structured message format for enhanced security
+ * 
+ * Key Features:
+ * - EIP-191 standard message signing format for wallet compatibility
+ * - Fisher Bridge specific message structure for transaction authenticity
+ * - Nonce-based replay attack prevention
+ * - EVVM ID integration for cross-instance security
+ * - Support for both ETH and ERC20 token bridge operations
+ * 
+ * Security Model:
+ * - Structured message format: "{evvmID},fisherBridge,{parameters}"
+ * - Nonce validation prevents replay attacks across chains
+ * - EVVM ID ensures signatures are valid only for specific EVVM instances
+ * - Address and amount validation through signature verification
+ */
 library SignatureUtils {
-    /**
-     *  @dev using EIP-191 (https://eips.ethereum.org/EIPS/eip-191) can be used to sign and
-     *       verify messages, the next functions are used to verify the messages signed
-     *       by the users
-     */
-
-
+    /// @notice Verifies Fisher Bridge transaction signatures using EIP-191 standard
+    /// @dev Constructs and verifies structured message for Fisher Bridge cross-chain operations
+    ///      Message format: "{evvmID},fisherBridge,{addressToReceive},{nonce},{tokenAddress},{priorityFee},{amount}"
+    ///      This ensures each signature is unique and prevents cross-chain replay attacks
+    /// 
+    /// @param evvmID Unique identifier of the EVVM instance (prevents cross-instance replay)
+    /// @param signer Address that should have signed the message (transaction originator)
+    /// @param addressToReceive Destination address on the target chain for the bridged tokens
+    /// @param nonce Sequential nonce for the user to prevent replay attacks
+    /// @param tokenAddress Contract address of the token being bridged (address(0) for ETH)
+    /// @param priorityFee Fee amount paid to Fisher executor for priority processing
+    /// @param amount Total amount of tokens being bridged across chains
+    /// @param signature ECDSA signature (65 bytes) created by the signer using their private key
+    /// @return bool True if the signature is valid and matches the expected signer, false otherwise
+    /// 
+    /// @dev Security Features:
+    ///      - EIP-191 compliance ensures wallet compatibility (MetaMask, WalletConnect, etc.)
+    ///      - Structured message prevents parameter manipulation
+    ///      - EVVM ID binding prevents cross-instance attacks
+    ///      - Nonce inclusion prevents replay attacks
+    ///      - All parameters are included in signature for integrity verification
     function verifyMessageSignedForFisherBridge(
         uint256 evvmID,
         address signer,

package/interfaces/ITreasuryExternalChainStation.sol

@@ -1,7 +1,5 @@
-// SPDX-License-Identifier: EVVM-NONCOMMERCIAL-1.0
-// Full license terms available at: https://www.evvm.info/docs/EVVMNoncommercialLicense
-
-pragma solidity ^0.8.0;
+// SPDX-License-Identifier: UNLICENSED
+pragma solidity ^0.8.4;
 
 library ExternalChainStationStructs {
     struct AddressTypeProposal {
@@ -40,7 +38,7 @@ library ExternalChainStationStructs {
     }
 }
 
-interface ITreasuryExternalChainStation {
+interface TreasuryExternalChainStation {
     struct EnforcedOptionParam {
         uint32 eid;
         uint16 msgType;
@@ -86,53 +84,27 @@ interface ITreasuryExternalChainStation {
         uint256 amount,
         uint256 nonce
     );
-    event OwnershipTransferred(
-        address indexed previousOwner,
-        address indexed newOwner
-    );
+    event OwnershipTransferred(address indexed previousOwner, address indexed newOwner);
     event PeerSet(uint32 eid, bytes32 peer);
 
+    function _setHostChainAddress(address hostChainStationAddress, string memory hostChainStationAddressString)
+        external;
     function acceptAdmin() external;
-
     function acceptFisherExecutor() external;
-
-    function allowInitializePath(
-        Origin memory origin
-    ) external view returns (bool);
-
-    function combineOptions(
-        uint32 _eid,
-        uint16 _msgType,
-        bytes memory _extraOptions
-    ) external view returns (bytes memory);
-
-    function depositCoin(
-        address toAddress,
-        uint256 amount,
-        bytes1 protocolToExecute
-    ) external payable;
-
-    function depositERC20(
-        address toAddress,
-        address token,
-        uint256 amount,
-        bytes1 protocolToExecute
-    ) external payable;
-
+    function acceptHostChainAddress() external;
+    function allowInitializePath(Origin memory origin) external view returns (bool);
+    function combineOptions(uint32 _eid, uint16 _msgType, bytes memory _extraOptions)
+        external
+        view
+        returns (bytes memory);
+    function depositCoin(address toAddress, uint256 amount, bytes1 protocolToExecute) external payable;
+    function depositERC20(address toAddress, address token, uint256 amount, bytes1 protocolToExecute)
+        external
+        payable;
     function endpoint() external view returns (address);
-
-    function enforcedOptions(
-        uint32 eid,
-        uint16 msgType
-    ) external view returns (bytes memory enforcedOption);
-
-    function execute(
-        bytes32 commandId,
-        string memory sourceChain,
-        string memory sourceAddress,
-        bytes memory payload
-    ) external;
-
+    function enforcedOptions(uint32 eid, uint16 msgType) external view returns (bytes memory enforcedOption);
+    function execute(bytes32 commandId, string memory sourceChain, string memory sourceAddress, bytes memory payload)
+        external;
     function fisherBridgeReceive(
         address from,
         address addressToReceive,
@@ -141,7 +113,6 @@ interface ITreasuryExternalChainStation {
         uint256 amount,
         bytes memory signature
     ) external;
-
     function fisherBridgeSendCoin(
         address from,
         address addressToReceive,
@@ -149,7 +120,6 @@ interface ITreasuryExternalChainStation {
         uint256 amount,
         bytes memory signature
     ) external payable;
-
     function fisherBridgeSendERC20(
         address from,
         address addressToReceive,
@@ -158,58 +128,17 @@ interface ITreasuryExternalChainStation {
         uint256 amount,
         bytes memory signature
     ) external;
-
     function gateway() external view returns (address);
-
-    function getAdmin()
-        external
-        view
-        returns (ExternalChainStationStructs.AddressTypeProposal memory);
-
-    function getAxelarConfig()
-        external
-        view
-        returns (ExternalChainStationStructs.AxelarConfig memory);
-
-    function getFisherExecutor()
-        external
-        view
-        returns (ExternalChainStationStructs.AddressTypeProposal memory);
-
-    function getHyperlaneConfig()
-        external
-        view
-        returns (ExternalChainStationStructs.HyperlaneConfig memory);
-
-    function getLayerZeroConfig()
-        external
-        view
-        returns (ExternalChainStationStructs.LayerZeroConfig memory);
-
-    function getNextFisherExecutionNonce(
-        address user
-    ) external view returns (uint256);
-
+    function getAdmin() external view returns (ExternalChainStationStructs.AddressTypeProposal memory);
+    function getAxelarConfig() external view returns (ExternalChainStationStructs.AxelarConfig memory);
+    function getFisherExecutor() external view returns (ExternalChainStationStructs.AddressTypeProposal memory);
+    function getHyperlaneConfig() external view returns (ExternalChainStationStructs.HyperlaneConfig memory);
+    function getLayerZeroConfig() external view returns (ExternalChainStationStructs.LayerZeroConfig memory);
+    function getNextFisherExecutionNonce(address user) external view returns (uint256);
     function getOptions() external view returns (bytes memory);
-
-    function getQuoteHyperlane(
-        address toAddress,
-        address token,
-        uint256 amount
-    ) external view returns (uint256);
-
-    function handle(
-        uint32 _origin,
-        bytes32 _sender,
-        bytes memory _data
-    ) external payable;
-
-    function isComposeMsgSender(
-        Origin memory,
-        bytes memory,
-        address _sender
-    ) external view returns (bool);
-
+    function getQuoteHyperlane(address toAddress, address token, uint256 amount) external view returns (uint256);
+    function handle(uint32 _origin, bytes32 _sender, bytes memory _data) external payable;
+    function isComposeMsgSender(Origin memory, bytes memory, address _sender) external view returns (bool);
     function lzReceive(
         Origin memory _origin,
         bytes32 _guid,
@@ -217,46 +146,21 @@ interface ITreasuryExternalChainStation {
         address _executor,
         bytes memory _extraData
     ) external payable;
-
     function nextNonce(uint32, bytes32) external view returns (uint64 nonce);
-
-    function oAppVersion()
-        external
-        pure
-        returns (uint64 senderVersion, uint64 receiverVersion);
-
+    function oAppVersion() external pure returns (uint64 senderVersion, uint64 receiverVersion);
     function owner() external view returns (address);
-
     function peers(uint32 eid) external view returns (bytes32 peer);
-
     function proposeAdmin(address _newOwner) external;
-
     function proposeFisherExecutor(address _newFisherExecutor) external;
-
-    function quoteLayerZero(
-        address toAddress,
-        address token,
-        uint256 amount
-    ) external view returns (uint256);
-
+    function proposeHostChainAddress(address hostChainStationAddress, string memory hostChainStationAddressString)
+        external;
+    function quoteLayerZero(address toAddress, address token, uint256 amount) external view returns (uint256);
     function rejectProposalAdmin() external;
-
     function rejectProposalFisherExecutor() external;
-
+    function rejectProposalHostChainAddress() external;
     function renounceOwnership() external;
-
     function setDelegate(address _delegate) external;
-
-    function setEnforcedOptions(
-        EnforcedOptionParam[] memory _enforcedOptions
-    ) external;
-
-    function setHostChainAddress(
-        address hostChainStationAddress,
-        string memory hostChainStationAddressString
-    ) external;
-
+    function setEnforcedOptions(EnforcedOptionParam[] memory _enforcedOptions) external;
     function setPeer(uint32 _eid, bytes32 _peer) external;
-
     function transferOwnership(address newOwner) external;
 }