@hyperbridge/core 1.0.0

package/LICENSE

@@ -0,0 +1,51 @@
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+"License" shall mean the terms and conditions for use, reproduction, and distribution as defined by Sections 1 through 9 of this document.
+
+"Licensor" shall mean the copyright owner or entity authorized by the copyright owner that is granting the License.
+
+"Legal Entity" shall mean the union of the acting entity and all other entities that control, are controlled by, or are under common control with that entity. For the purposes of this definition, "control" means (i) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity.
+
+"You" (or "Your") shall mean an individual or Legal Entity exercising permissions granted by this License.
+
+"Source" form shall mean the preferred form for making modifications, including but not limited to software source code, documentation source, and configuration files.
+
+"Object" form shall mean any form resulting from mechanical transformation or translation of a Source form, including but not limited to compiled object code, generated documentation, and conversions to other media types.
+
+"Work" shall mean the work of authorship, whether in Source or Object form, made available under the License, as indicated by a copyright notice that is included in or attached to the work (an example is provided in the Appendix below).
+
+"Derivative Works" shall mean any work, whether in Source or Object form, that is based on (or derived from) the Work and for which the editorial revisions, annotations, elaborations, or other modifications represent, as a whole, an original work of authorship. For the purposes of this License, Derivative Works shall not include works that remain separable from, or merely link (or bind by name) to the interfaces of, the Work and Derivative Works thereof.
+
+"Contribution" shall mean any work of authorship, including the original version of the Work and any modifications or additions to that Work or Derivative Works thereof, that is intentionally submitted to Licensor for inclusion in the Work by the copyright owner or by an individual or Legal Entity authorized to submit on behalf of the copyright owner. For the purposes of this definition, "submitted" means any form of electronic, verbal, or written communication sent to the Licensor or its representatives, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, the Licensor for the purpose of discussing and improving the Work, but excluding communication that is conspicuously marked or otherwise designated in writing by the copyright owner as "Not a Contribution."
+
+"Contributor" shall mean Licensor and any individual or Legal Entity on behalf of whom a Contribution has been received by Licensor and subsequently incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform, sublicense, and distribute the Work and such Derivative Works in Source or Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work, where such license applies only to those patent claims licensable by such Contributor that are necessarily infringed by their Contribution(s) alone or by combination of their Contribution(s) with the Work to which such Contribution(s) was submitted. If You institute patent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Work or a Contribution incorporated within the Work constitutes direct or contributory patent infringement, then any patent licenses granted to You under this License for that Work shall terminate as of the date such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the Work or Derivative Works thereof in any medium, with or without modifications, and in Source or Object form, provided that You meet the following conditions:
+
+You must give any other recipients of the Work or Derivative Works a copy of this License; and
+You must cause any modified files to carry prominent notices stating that You changed the files; and
+You must retain, in the Source form of any Derivative Works that You distribute, all copyright, patent, trademark, and attribution notices from the Source form of the Work, excluding those notices that do not pertain to any part of the Derivative Works; and
+If the Work includes a "NOTICE" text file as part of its distribution, then any Derivative Works that You distribute must include a readable copy of the attribution notices contained within such NOTICE file, excluding those notices that do not pertain to any part of the Derivative Works, in at least one of the following places: within a NOTICE text file distributed as part of the Derivative Works; within the Source form or documentation, if provided along with the Derivative Works; or, within a display generated by the Derivative Works, if and wherever such third-party notices normally appear. The contents of the NOTICE file are for informational purposes only and do not modify the License. You may add Your own attribution notices within Derivative Works that You distribute, alongside or as an addendum to the NOTICE text from the Work, provided that such additional attribution notices cannot be construed as modifying the License.
+
+You may add Your own copyright statement to Your modifications and may provide additional or different license terms and conditions for use, reproduction, or distribution of Your modifications, or for any such Derivative Works as a whole, provided Your use, reproduction, and distribution of the Work otherwise complies with the conditions stated in this License.
+5. Submission of Contributions. Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work by You to the Licensor shall be under the terms and conditions of this License, without any additional terms or conditions. Notwithstanding the above, nothing herein shall supersede or modify the terms of any separate license agreement you may have executed with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade names, trademarks, service marks, or product names of the Licensor, except as required for reasonable and customary use in describing the origin of the Work and reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or agreed to in writing, Licensor provides the Work (and each Contributor provides its Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for determining the appropriateness of using or redistributing the Work and assume any risks associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall any Contributor be liable to You for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising as a result of this License or out of the use or inability to use the Work (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if such Contributor has been advised of the possibility of such damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing the Work or Derivative Works thereof, You may choose to offer, and charge a fee for, acceptance of support, warranty, indemnity, or other liability obligations and/or rights consistent with this License. However, in accepting such obligations, You may act only on Your own behalf and on Your sole responsibility, not on behalf of any other Contributor, and only if You agree to indemnify, defend, and hold each Contributor harmless for any liability incurred by, or claims asserted against, such Contributor by reason of your accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS

package/README.md

@@ -0,0 +1,28 @@
+# @hyperbridge/core
+
+![Unit Tests](https://github.com/polytope-labs/hyperbridge-sdk/actions/workflows/test-core.yml/badge.svg)
+[![NPM](https://img.shields.io/npm/v/@hyperbridge/core?label=%40hyperbridge%2Fcore)](https://www.npmjs.com/package/@hyperbridge/core)
+
+[ISMP](https://docs.hyperbridge.network/protocol/ismp) protocol specification for EVM environments.
+
+### Interfaces
+
+ - [`IHost`](contracts/interfaces/IHost.sol) - The protocol host interface
+ - [`IDispatcher`](contracts/interfaces/IDispatcher.sol) - The protocol dispatcher interface
+ - [`IHandler`](contracts/interfaces/IHandler.sol) - The protocol message handler interface
+ - [`IConsensus`](contracts/interfaces/IConsensus.sol) - The consensus interface
+ - [`IApp`](contracts/interfaces/IApp.sol) - The protocol application interface
+
+### Libraries
+
+ - [`Message`](contracts/libraries/Message.sol) - The protocol message types and data structures
+ - [`StateMachine`](contracts/libraries/StateMachine.sol) - State machine identifier utilities
+
+### Apps
+
+ - [`HyperApp`](contracts/apps/HyperApp.sol) - Abstract base contract that implements `IApp` for building cross-chain applications with built-in fee estimation and host authorization
+ - [`HyperFungibleToken`](contracts/apps/HyperFungibleToken.sol) - Abstract ERC20 token implementation with gateway-restricted minting and burning capabilities for cross-chain bridging
+
+## License
+
+This library is licensed under the Apache 2.0 License, Copyright (c) 2025 Polytope Labs.

package/contracts/apps/HyperApp.sol

@@ -0,0 +1,179 @@
+// Copyright (C) Polytope Labs Ltd.
+// SPDX-License-Identifier: Apache-2.0
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// 	http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+pragma solidity ^0.8.17;
+
+import {PostRequest, PostResponse, GetRequest} from "../libraries/Message.sol";
+import {DispatchPost, DispatchPostResponse, DispatchGet, IDispatcher} from "../interfaces/IDispatcher.sol";
+import {IApp, IncomingPostRequest, IncomingPostResponse, IncomingGetResponse} from "../interfaces/IApp.sol";
+
+/**
+ * @dev Uniswap interface for estimating fees in the native token
+ */
+interface IUniswapV2Router02 {
+    function WETH() external pure returns (address);
+
+    function getAmountsIn(uint256, address[] calldata) external pure returns (uint256[] memory);
+}
+
+/**
+ * @title HyperApp
+ * @notice Abstract base contract for building cross-chain applications on Hyperbridge
+ * @dev Provides a simplified interface for implementing `IApp` with built-in utilities for fee estimation,
+ * host authorization, and cross-chain message handling. Extend this contract to build your Hyperbridge application.
+ */
+abstract contract HyperApp is IApp {
+    /**
+     * @dev Call was not expected
+     */
+    error UnexpectedCall();
+
+    /**
+     * @dev Account is unauthorized
+     */
+    error UnauthorizedCall();
+
+    /**
+     * @dev restricts caller to the local `Host`
+     */
+    modifier onlyHost() {
+        if (msg.sender != host()) revert UnauthorizedCall();
+        _;
+    }
+
+    /**
+     * @dev Should return the `Host` address for the current chain.
+     * The `Host` is an immutable contract that will never change.
+     */
+    function host() public view virtual returns (address);
+
+    /**
+     * @dev returns the quoted fee in the feeToken for dispatching a POST request
+     */
+    function quote(DispatchPost memory request) public view returns (uint256) {
+        uint256 len = 32 > request.body.length ? 32 : request.body.length;
+        return request.fee + (len * IDispatcher(host()).perByteFee(request.dest));
+    }
+
+    /**
+     * @dev returns the quoted fee in the native token for dispatching a POST request
+     */
+    function quoteNative(DispatchPost memory request) public view returns (uint256) {
+        uint256 fee = quote(request);
+        address _host = host();
+        address _uniswap = IDispatcher(_host).uniswapV2Router();
+        address[] memory path = new address[](2);
+        path[0] = IUniswapV2Router02(_uniswap).WETH();
+        path[1] = IDispatcher(_host).feeToken();
+        return IUniswapV2Router02(_uniswap).getAmountsIn(fee, path)[0];
+    }
+
+    /**
+     * @dev returns the quoted fee in the feeToken for dispatching a GET request
+     */
+    function quote(DispatchGet memory request) public view returns (uint256) {
+        address _host = host();
+        uint256 pbf = IDispatcher(_host).perByteFee(IDispatcher(_host).host());
+        uint256 minimumFee = 32 * pbf;
+        uint256 totalFee = request.fee + (pbf * request.context.length);
+        return minimumFee > totalFee ? minimumFee : totalFee;
+    }
+
+    /**
+     * @dev returns the quoted fee in the native token for dispatching a GET request
+     */
+    function quoteNative(DispatchGet memory request) public view returns (uint256) {
+        uint256 fee = quote(request);
+        address _host = host();
+        address _uniswap = IDispatcher(_host).uniswapV2Router();
+        address[] memory path = new address[](2);
+        path[0] = IUniswapV2Router02(_uniswap).WETH();
+        path[1] = IDispatcher(_host).feeToken();
+        return IUniswapV2Router02(_uniswap).getAmountsIn(fee, path)[0];
+    }
+
+    /**
+     * @dev returns the quoted fee in the feeToken for dispatching a POST response
+     */
+    function quote(DispatchPostResponse memory response) public view returns (uint256) {
+        uint256 len = 32 > response.response.length ? 32 : response.response.length;
+        return response.fee + (len * IDispatcher(host()).perByteFee(response.request.source));
+    }
+
+    /**
+     * @dev returns the quoted fee in the native token for dispatching a POST response
+     */
+    function quoteNative(DispatchPostResponse memory request) public view returns (uint256) {
+        uint256 fee = quote(request);
+        address _host = host();
+        address _uniswap = IDispatcher(_host).uniswapV2Router();
+        address[] memory path = new address[](2);
+        path[0] = IUniswapV2Router02(_uniswap).WETH();
+        path[1] = IDispatcher(_host).feeToken();
+        return IUniswapV2Router02(_uniswap).getAmountsIn(fee, path)[0];
+    }
+
+    /**
+     * @notice Callback for receiving incoming POST requests
+     * @dev Called by the Host when a new POST request is received for this app.
+     * Override this method to implement request handling logic. The default implementation reverts.
+     */
+    function onAccept(IncomingPostRequest calldata) external virtual onlyHost {
+        revert UnexpectedCall();
+    }
+
+    /**
+     * @notice Callback for handling POST request timeouts
+     * @dev Called by the Host when a previously dispatched POST request has timed out.
+     * Override this method to implement cleanup or retry logic. The default implementation reverts.
+     */
+    function onPostRequestTimeout(PostRequest memory) external virtual onlyHost {
+        revert UnexpectedCall();
+    }
+
+    /**
+     * @notice Callback for receiving POST responses
+     * @dev Called by the Host when a response is received for a previously dispatched POST request.
+     * Override this method to process response data. The default implementation reverts.
+     */
+    function onPostResponse(IncomingPostResponse memory) external virtual onlyHost {
+        revert UnexpectedCall();
+    }
+
+    /**
+     * @notice Callback for handling POST response timeouts
+     * @dev Called by the Host when a POST response that was sent has timed out.
+     * Override this method to handle response timeout scenarios. The default implementation reverts.
+     */
+    function onPostResponseTimeout(PostResponse memory) external virtual onlyHost {
+        revert UnexpectedCall();
+    }
+
+    /**
+     * @notice Callback for receiving GET responses
+     * @dev Called by the Host when a response is received for a previously dispatched GET request.
+     * Override this method to process the retrieved state data. The default implementation reverts.
+     */
+    function onGetResponse(IncomingGetResponse memory) external virtual onlyHost {
+        revert UnexpectedCall();
+    }
+
+    /**
+     * @notice Callback for handling GET request timeouts
+     * @dev Called by the Host when a previously dispatched GET request has timed out.
+     * Override this method to handle GET timeout scenarios. The default implementation reverts.
+     */
+    function onGetTimeout(GetRequest memory) external virtual onlyHost {
+        revert UnexpectedCall();
+    }
+}

package/contracts/apps/HyperFungibleToken.sol

@@ -0,0 +1,72 @@
+// Copyright (C) Polytope Labs Ltd.
+// SPDX-License-Identifier: Apache-2.0
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// 	http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+pragma solidity ^0.8.17;
+
+import {ERC20} from "@openzeppelin/contracts/token/ERC20/ERC20.sol";
+
+/**
+ * @title HyperFungibleToken
+ * @notice An cross-chain fungible token implementation that can only be minted and burned by a designated gateway address.
+ * @dev This abstract contract extends OpenZeppelin's ERC20 implementation and adds gateway-restricted minting and burning capabilities.
+ * It is designed to be used in cross-chain bridge scenarios where a trusted gateway manages token supply.
+ * Derived contracts must implement the gateway() function to return their specific gateway address.
+ */
+abstract contract HyperFungibleToken is ERC20 {
+    /// @notice Custom error thrown when a non-gateway address attempts to mint or burn
+    error OnlyGateway();
+
+    /**
+     * @notice Restricts function access to only the gateway address
+     * @dev Reverts with OnlyGateway error if called by any address other than the gateway
+     */
+    modifier onlyGateway() {
+        if (msg.sender != gateway()) revert OnlyGateway();
+        _;
+    }
+
+    /**
+     * @notice Initializes the token with a name and symbol
+     * @param name The name of the token
+     * @param symbol The symbol of the token
+     */
+    constructor(string memory name, string memory symbol) ERC20(name, symbol) {}
+
+    /**
+     * @notice Returns the gateway address
+     * @dev Must be implemented by derived contracts to return their specific gateway address
+     * The `gateway` should be an immutable contract that will never change.
+     * @return The address of the gateway contract
+     */
+    function gateway() public view virtual returns (address);
+
+    /**
+     * @notice Mints tokens to the specified account
+     * @dev Can only be called by the gateway address
+     * @param to The address that will receive the minted tokens
+     * @param amount The amount of tokens to mint
+     */
+    function mint(address to, uint256 amount) external onlyGateway {
+        _mint(to, amount);
+    }
+
+    /**
+     * @notice Burns tokens from the specified account
+     * @dev Can only be called by the gateway address. The account must have sufficient balance.
+     * @param from The address from which tokens will be burned
+     * @param amount The amount of tokens to burn
+     */
+    function burn(address from, uint256 amount) external onlyGateway {
+        _burn(from, amount);
+    }
+}

package/contracts/interfaces/IApp.sol

@@ -0,0 +1,98 @@
+// Copyright (C) Polytope Labs Ltd.
+// SPDX-License-Identifier: Apache-2.0
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// 	http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+pragma solidity ^0.8.17;
+
+import {PostRequest, PostResponse, GetResponse, GetRequest} from "../libraries/Message.sol";
+
+/**
+ * @title IncomingPostRequest
+ * @notice Encapsulates an incoming POST request with relayer information
+ * @dev Used by the Host to deliver POST requests to applications
+ */
+struct IncomingPostRequest {
+    // The Post request containing source, dest, nonce, from, to, timeout, and body
+    PostRequest request;
+    // Relayer responsible for delivering the request
+    address relayer;
+}
+
+/**
+ * @title IncomingPostResponse
+ * @notice Encapsulates an incoming POST response with relayer information
+ * @dev Used by the Host to deliver POST responses to applications
+ */
+struct IncomingPostResponse {
+    // The Post response containing the original request, response data, and timeout
+    PostResponse response;
+    // Relayer responsible for delivering the response
+    address relayer;
+}
+
+/**
+ * @title IncomingGetResponse
+ * @notice Encapsulates an incoming GET response with relayer information
+ * @dev Used by the Host to deliver GET responses containing state data to applications
+ */
+struct IncomingGetResponse {
+    // The Get response containing the request and retrieved state values
+    GetResponse response;
+    // Relayer responsible for delivering the response
+    address relayer;
+}
+
+/**
+ * @title IApp
+ * @author Polytope Labs (hello@polytope.technology)
+ * @notice Interface for cross-chain applications built on Hyperbridge
+ * @dev Applications must implement this interface to receive and handle cross-chain messages.
+ * The Host calls these methods to deliver messages, responses, and timeout notifications.
+ * All methods are permissioned and should only be callable by the Host contract.
+ */
+interface IApp {
+    /**
+     * @dev Called by the `Host` to notify an app of a new request the app may choose to respond immediately, or in a later block
+     * @param incoming post request
+     */
+    function onAccept(IncomingPostRequest memory incoming) external;
+
+    /**
+     * @dev Called by the `Host` to notify an app of a post response to a previously sent out request
+     * @param incoming post response
+     */
+    function onPostResponse(IncomingPostResponse memory incoming) external;
+
+    /**
+     * @dev Called by the `Host` to notify an app of a get response to a previously sent out request
+     * @param incoming get response
+     */
+    function onGetResponse(IncomingGetResponse memory incoming) external;
+
+    /**
+     * @dev Called by the `Host` to notify an app of post requests that were previously sent but have now timed-out
+     * @param request post request
+     */
+    function onPostRequestTimeout(PostRequest memory request) external;
+
+    /**
+     * @dev Called by the `Host` to notify an app of post responses that were previously sent but have now timed-out
+     * @param response post response
+     */
+    function onPostResponseTimeout(PostResponse memory response) external;
+
+    /**
+     * @dev Called by the `Host` to notify an app of get requests that were previously sent but have now timed-out
+     * @param request get request
+     */
+    function onGetTimeout(GetRequest memory request) external;
+}

package/contracts/interfaces/IConsensus.sol

@@ -0,0 +1,86 @@
+// Copyright (C) Polytope Labs Ltd.
+// SPDX-License-Identifier: Apache-2.0
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// 	http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+pragma solidity ^0.8.17;
+
+/**
+ * @title StateCommitment
+ * @notice Represents a commitment to an intermediate state in the state machine
+ * @dev Contains metadata about the state machine including timestamp and merkle roots
+ */
+struct StateCommitment {
+    /// @notice Unix timestamp of the state machine at the time of this commitment
+    /// @dev Used for calculating request timeouts and enforcing time-based logic
+    uint256 timestamp;
+    /// @notice Merkle root of the overlay trie containing all ISMP requests and responses
+    /// @dev Used to verify inclusion proofs for cross-chain messages
+    bytes32 overlayRoot;
+    /// @notice Merkle root of the state trie at the given block height
+    /// @dev Represents the complete state of the state machine at this height
+    bytes32 stateRoot;
+}
+
+/**
+ * @title StateMachineHeight
+ * @notice Uniquely identifies a specific height in a state machine
+ * @dev Consensus clients may track multiple concurrent state machines, hence the need for an identifier
+ */
+struct StateMachineHeight {
+    /// @notice Unique identifier for the state machine (e.g., parachain ID, chain ID)
+    /// @dev Each blockchain or parachain in the network has a unique identifier
+    uint256 stateMachineId;
+    /// @notice Block height or number in the state machine
+    /// @dev Represents the sequential position in the blockchain
+    uint256 height;
+}
+
+/**
+ * @title IntermediateState
+ * @notice Represents an intermediate state in the state transition sequence of a state machine
+ * @dev Used to track finalized states that have been verified through consensus
+ */
+struct IntermediateState {
+    /// @notice Unique identifier for the state machine
+    /// @dev Same as StateMachineHeight.stateMachineId
+    uint256 stateMachineId;
+    /// @notice Block height of this intermediate state
+    /// @dev The specific height at which this state was committed
+    uint256 height;
+    /// @notice The state commitment at this height
+    /// @dev Contains the timestamp and merkle roots for this state
+    StateCommitment commitment;
+}
+
+/**
+ * @title IConsensus
+ * @author Polytope Labs (hello@polytope.technology)
+ * @notice Interface for consensus verification in the Hyperbridge protocol
+ * @dev Consensus clients implement this interface to verify state transitions from different chains.
+ * The internals are intentionally opaque to the ISMP framework, allowing consensus mechanisms
+ * to evolve independently (e.g., GRANDPA for Polkadot, Sync Committee for Ethereum).
+ * Different consensus mechanisms can be plugged in as long as they conform to this interface.
+ */
+interface IConsensus {
+    /**
+     * @notice Verifies a consensus proof and returns the updated consensus state
+     * @dev This function is called by the Handler to verify incoming consensus updates.
+     * The implementation details vary based on the consensus mechanism being verified.
+     * @param trustedState The current trusted consensus state (encoded based on consensus type)
+     * @param proof The consensus proof to be verified (e.g., validator signatures, merkle proofs)
+     * @return The new consensus state after verification (encoded)
+     * @return Array of newly finalized intermediate states that can be trusted
+     */
+    function verifyConsensus(bytes memory trustedState, bytes memory proof)
+        external
+        returns (bytes memory, IntermediateState[] memory);
+}