refactor: rename EthereumISM to EvmISM and introduce IEvmLightClient interface

keyleu · keyleu · commit 69984fc96a18 · 2026-02-12T17:53:02.000Z
diff --git a/contracts/script/Deploy.s.sol b/contracts/script/Deploy.s.sol
@@ -4,11 +4,11 @@ pragma solidity 0.8.30;
 import {Script, console} from "forge-std/src/Script.sol";
 import {ERC1967Proxy} from "@openzeppelin/contracts/proxy/ERC1967/ERC1967Proxy.sol";
 import {EthereumLightClient} from "../src/light-client/EthereumLightClient.sol";
-import {EthereumISM} from "../src/ism/EthereumISM.sol";
+import {EvmISM} from "../src/ism/EvmISM.sol";
 
 /**
  * @title Deploy
- * @notice Deploys the EthereumLightClient and EthereumISM behind UUPS proxies.
+ * @notice Deploys the EthereumLightClient and EvmISM behind UUPS proxies.
  *
  * @dev Required environment variables:
  *   ETHEREUM_LIGHT_CLIENT_VK   - SP1 verification key for the Helios circuit
@@ -77,13 +77,13 @@ contract Deploy is Script {
 
         // ============ ISM ============
 
-        console.log("=== Deploying EthereumISM ===");
+        console.log("=== Deploying EvmISM ===");
 
-        EthereumISM ismImpl = new EthereumISM();
+        EvmISM ismImpl = new EvmISM();
         console.log("  Implementation:", address(ismImpl));
 
         ERC1967Proxy ismProxy = new ERC1967Proxy(
-            address(ismImpl), abi.encodeCall(EthereumISM.initialize, (merkleVk, sp1Verifier, address(lcProxy)))
+            address(ismImpl), abi.encodeCall(EvmISM.initialize, (merkleVk, sp1Verifier, address(lcProxy)))
         );
         console.log("  Proxy:", address(ismProxy));
 
@@ -98,9 +98,9 @@ contract Deploy is Script {
         require(lc.headers(initialSlot) == initialHeader, "header mismatch");
         require(lc.stateRoots(initialBlockNumber) == initialStateRoot, "stateRoot mismatch");
 
-        EthereumISM ism = EthereumISM(address(ismProxy));
+        EvmISM ism = EvmISM(address(ismProxy));
         require(ism.programVk() == merkleVk, "ism programVk mismatch");
-        require(address(ism.ethereumLightClient()) == address(lcProxy), "light client address mismatch");
+        require(address(ism.lightClient()) == address(lcProxy), "light client address mismatch");
         require(address(ism.verifier()) == sp1Verifier, "ism verifier mismatch");
 
         console.log("=== Deployment verified successfully ===");
diff --git a/contracts/src/interfaces/IEthereumLightClient.sol b/contracts/src/interfaces/IEthereumLightClient.sol
@@ -3,6 +3,7 @@ pragma solidity >=0.8.20;
 
 import {IVersioned} from "./IVersioned.sol";
 import {IVkUpdatable} from "./IVkUpdatable.sol";
+import {IEvmLightClient} from "./IEvmLightClient.sol";
 
 /**
  * @title IEthereumLightClient
@@ -11,7 +12,7 @@ import {IVkUpdatable} from "./IVkUpdatable.sol";
  *      proofs. It maintains a chain of finalized headers verified through sync committee signatures and enables
  *      trustless cross-chain verification of Ethereum state.
  */
-interface IEthereumLightClient is IVersioned, IVkUpdatable {
+interface IEthereumLightClient is IEvmLightClient, IVersioned, IVkUpdatable {
     /// @notice Thrown when an invalid address (e.g., zero address) is provided.
     error InvalidAddress();
 
@@ -101,13 +102,6 @@ interface IEthereumLightClient is IVersioned, IVkUpdatable {
      */
     function headers(uint256 slot) external view returns (bytes32);
 
-    /**
-     * @notice Returns the execution state root for a given block number.
-     * @param blockNumber The execution layer block number.
-     * @return The state root hash, or zero if not set.
-     */
-    function stateRoots(uint256 blockNumber) external view returns (bytes32);
-
     /**
      * @notice Returns the sync committee hash for a given period.
      * @param period The sync committee period index.
@@ -121,18 +115,6 @@ interface IEthereumLightClient is IVersioned, IVkUpdatable {
      */
     function latestSlot() external view returns (uint256);
 
-    /**
-     * @notice Returns the execution state root for the latest finalized block.
-     * @return The state root hash that can be used for verifying storage proofs.
-     */
-    function latestStateRoot() external view returns (bytes32);
-
-    /**
-     * @notice Returns the latest finalized execution block number.
-     * @return The most recent execution block number with a verified state root.
-     */
-    function latestBlockNumber() external view returns (uint256);
-
     /**
      * @notice Calculates the sync committee period for a given slot.
      * @dev Each period spans 8192 slots (~27 hours). The sync committee rotates at period boundaries.
diff --git a/contracts/src/interfaces/IEvmISM.sol b/contracts/src/interfaces/IEvmISM.sol
@@ -7,14 +7,14 @@ import {IVersioned} from "./IVersioned.sol";
 import {IVkUpdatable} from "./IVkUpdatable.sol";
 
 /**
- * @title IEthereumISM
+ * @title IEvmISM
  * @notice Interface for a Hyperlane Interchain Security Module that verifies messages using SP1 ZK proofs
- *         of Ethereum's Merkle tree hook roots.
+ *         of Merkle tree hook roots from EVM chains.
  * @dev This ISM verifies messages in two steps:
- *      1. Accept SP1 proofs of Ethereum's Merkle tree hook roots via update()
+ *      1. Accept SP1 proofs of the source chain's Merkle tree hook roots via update()
  *      2. Validate Hyperlane messages against these roots via verify()
  */
-interface IEthereumISM is IInterchainSecurityModule, IVersioned, IVkUpdatable {
+interface IEvmISM is IInterchainSecurityModule, IVersioned, IVkUpdatable {
     /// @notice Thrown when an invalid address (e.g., zero address) is provided.
     error InvalidAddress();
 
@@ -24,17 +24,17 @@ interface IEthereumISM is IInterchainSecurityModule, IVersioned, IVkUpdatable {
     /**
      * @notice Emitted when a new Merkle tree root is verified and added to the valid roots set.
      * @param root The Merkle tree hook root that was verified.
-     * @param blockNumber The Ethereum block number at which the root was proven.
-     * @param stateRoot The Ethereum execution layer state root at the given block.
+     * @param blockNumber The source chain block number at which the root was proven.
+     * @param stateRoot The source chain execution state root at the given block.
      */
     event Updated(bytes32 root, uint64 blockNumber, bytes32 stateRoot);
 
     /**
      * @notice Output structure from the Merkle tree verification circuit.
-     * @dev This struct contains the data needed to validate a Merkle tree root against Ethereum state.
+     * @dev This struct contains the data needed to validate a Merkle tree root against the source chain's state.
      * @param root The Merkle tree hook root from the Hyperlane contract.
-     * @param stateRoot The Ethereum execution layer state root at the given block.
-     * @param blockNumber The Ethereum block number where the Merkle root was proven.
+     * @param stateRoot The source chain execution state root at the given block.
+     * @param blockNumber The source chain block number where the Merkle root was proven.
      */
     struct CircuitOutput {
         bytes32 root;
@@ -56,7 +56,7 @@ interface IEthereumISM is IInterchainSecurityModule, IVersioned, IVkUpdatable {
 
     /**
      * @notice Updates the set of valid Merkle roots by verifying an SP1 proof.
-     * @dev Verifies a ZK proof that attests to a valid Merkle tree hook root from Ethereum,
+     * @dev Verifies a ZK proof that attests to a valid Merkle tree hook root from the source EVM chain,
      *      validates the state root against the light client, and adds the root to the valid set.
      * @param proof The SP1 proof bytes generated by the Merkle tree circuit.
      * @param publicValues The ABI-encoded CircuitOutput containing the proof data.
diff --git a/contracts/src/interfaces/IEvmLightClient.sol b/contracts/src/interfaces/IEvmLightClient.sol
@@ -0,0 +1,28 @@
+// SPDX-License-Identifier: Apache-2.0
+pragma solidity >=0.8.20;
+
+/**
+ * @title IEvmLightClient
+ * @notice Minimal interface for light clients that provide verified EVM execution state roots.
+ * @dev Any chain-specific light client (Ethereum, Noble, etc.) should implement this.
+ */
+interface IEvmLightClient {
+    /**
+     * @notice Returns the execution state root for a given block number.
+     * @param blockNumber The execution layer block number.
+     * @return The state root hash, or zero if not set.
+     */
+    function stateRoots(uint256 blockNumber) external view returns (bytes32);
+
+    /**
+     * @notice Returns the execution state root for the latest finalized block.
+     * @return The state root hash that can be used for verifying storage proofs.
+     */
+    function latestStateRoot() external view returns (bytes32);
+
+    /**
+     * @notice Returns the latest finalized execution block number.
+     * @return The most recent execution block number with a verified state root.
+     */
+    function latestBlockNumber() external view returns (uint256);
+}
diff --git a/contracts/src/ism/EvmISM.sol b/contracts/src/ism/EvmISM.sol
@@ -5,30 +5,30 @@ import {OwnableUpgradeable} from "@openzeppelin-contracts-upgradeable/access/Own
 import {UUPSUpgradeable} from "@openzeppelin-contracts-upgradeable/proxy/utils/UUPSUpgradeable.sol";
 import {PausableUpgradeable} from "@openzeppelin-contracts-upgradeable/utils/PausableUpgradeable.sol";
 import {ISP1Verifier} from "succinctlabs-sp1-contracts/src/ISP1Verifier.sol";
-import {IEthereumISM} from "../interfaces/IEthereumISM.sol";
-import {IEthereumLightClient} from "../interfaces/IEthereumLightClient.sol";
+import {IEvmISM} from "../interfaces/IEvmISM.sol";
+import {IEvmLightClient} from "../interfaces/IEvmLightClient.sol";
 import {IInterchainSecurityModule} from "hyperlane/interfaces/IInterchainSecurityModule.sol";
 import {Message} from "hyperlane/libs/Message.sol";
 import {MerkleLib} from "hyperlane/libs/Merkle.sol";
 
 /**
- * @title EthereumISM
+ * @title EvmISM
  * @author NASD Inc.
  * @notice Hyperlane Interchain Security Module that uses SP1 zk proofs to verify Hyperlane
- *         Merkle tree hook roots from the Ethereum blockchain
- * @dev This EthereumISM verifies messages by:
- *      1. Accepting SP1 proofs of Ethereum's Merkle tree hook roots via update()
+ *         Merkle tree hook roots from an EVM source chain.
+ * @dev This ISM verifies messages by:
+ *      1. Accepting SP1 proofs of the source chain's Merkle tree hook roots via update()
  *      2. Validating Hyperlane messages against these roots via verify(). This will be called by the Hyperlane mailbox.
  */
-contract EthereumISM is OwnableUpgradeable, UUPSUpgradeable, PausableUpgradeable, IEthereumISM {
+contract EvmISM is OwnableUpgradeable, UUPSUpgradeable, PausableUpgradeable, IEvmISM {
     /// @notice The verification key for the EVM Hyperlane Merkle Tree SP1 program circuit
     bytes32 public programVk;
 
     /// @notice The SP1 verifier contract used to verify the proofs
     ISP1Verifier public verifier;
 
-    /// @notice The Ethereum light client contract for validating app hashes
-    IEthereumLightClient public ethereumLightClient;
+    /// @notice The light client contract for validating source chain state roots
+    IEvmLightClient public lightClient;
 
     /// @notice Mapping of verified Merkle tree roots that can be used for message verification
     /// @dev A root is added when an SP1 proof is successfully verified via update()
@@ -43,25 +43,22 @@ contract EthereumISM is OwnableUpgradeable, UUPSUpgradeable, PausableUpgradeable
     }
 
     /**
-     * @notice Initializes the EthereumISM contract with required addresses and verification key
+     * @notice Initializes the EvmISM contract with required addresses and verification key
      * @dev Can only be called once due to initializer modifier
      * @param _programVk The SP1 program verification key for the Merkle tree circuit
      * @param verifierAddress Address of the SP1 verifier contract
-     * @param ethereumLightClientAddress Address of the Ethereum light client contract
+     * @param lightClientAddress Address of the EVM light client contract
      */
-    function initialize(bytes32 _programVk, address verifierAddress, address ethereumLightClientAddress)
-        public
-        initializer
-    {
+    function initialize(bytes32 _programVk, address verifierAddress, address lightClientAddress) public initializer {
         __Ownable_init(msg.sender);
         __Pausable_init();
 
         programVk = _programVk;
         require(verifierAddress != address(0), InvalidAddress());
         verifier = ISP1Verifier(verifierAddress);
 
-        require(ethereumLightClientAddress != address(0), InvalidAddress());
-        ethereumLightClient = IEthereumLightClient(ethereumLightClientAddress);
+        require(lightClientAddress != address(0), InvalidAddress());
+        lightClient = IEvmLightClient(lightClientAddress);
     }
 
     /**
@@ -71,14 +68,14 @@ contract EthereumISM is OwnableUpgradeable, UUPSUpgradeable, PausableUpgradeable
      */
     function _authorizeUpgrade(address newImplementation) internal override onlyOwner {}
 
-    /// @inheritdoc IEthereumISM
+    /// @inheritdoc IEvmISM
     function update(bytes calldata proof, bytes calldata publicValues) external override whenNotPaused {
         verifier.verifyProof(programVk, publicValues, proof);
 
         CircuitOutput memory output = abi.decode(publicValues, (CircuitOutput));
 
-        // Validate that the state root matches the Ethereum light client's state at this block number
-        bytes32 expectedStateRoot = ethereumLightClient.stateRoots(output.blockNumber);
+        // Validate that the state root matches the light client's state at this block number
+        bytes32 expectedStateRoot = lightClient.stateRoots(output.blockNumber);
         require(expectedStateRoot != bytes32(0) && output.stateRoot == expectedStateRoot, InvalidStateRoot());
 
         // Mark this Merkle hook root as valid for message verification
@@ -87,7 +84,7 @@ contract EthereumISM is OwnableUpgradeable, UUPSUpgradeable, PausableUpgradeable
         emit Updated(output.root, output.blockNumber, output.stateRoot);
     }
 
-    /// @inheritdoc IEthereumISM
+    /// @inheritdoc IEvmISM
     function verify(bytes calldata _metadata, bytes calldata _message)
         external
         view
@@ -143,7 +140,7 @@ contract EthereumISM is OwnableUpgradeable, UUPSUpgradeable, PausableUpgradeable
     }
 
     /**
-     * @notice Returns the version of the EthereumISM contract
+     * @notice Returns the version of the EvmISM contract
      * @return A string representing the semantic version
      */
     function version() external pure override returns (string memory) {
diff --git a/contracts/src/light-client/EthereumLightClient.sol b/contracts/src/light-client/EthereumLightClient.sol
@@ -199,7 +199,10 @@ contract EthereumLightClient is OwnableUpgradeable, UUPSUpgradeable, PausableUpg
      */
     function _authorizeUpgrade(address newImplementation) internal override onlyOwner {}
 
-    /// @inheritdoc IEthereumLightClient
+    /**
+     * @notice Returns the execution state root for the latest finalized block.
+     * @return The state root hash that can be used for verifying storage proofs.
+     */
     function latestStateRoot() public view returns (bytes32) {
         return stateRoots[latestBlockNumber];
     }
diff --git a/contracts/test/EvmISM.t.sol b/contracts/test/EvmISM.t.sol
