@hyperbridge/core 1.0.0

package/contracts/interfaces/IDispatcher.sol

@@ -0,0 +1,228 @@
+// 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, FrozenStatus} from "../libraries/Message.sol";
+
+/**
+ * @title DispatchPost
+ * @notice Parameters for dispatching a POST request through Hyperbridge
+ * @dev Used to send arbitrary data to applications on other chains
+ */
+struct DispatchPost {
+    /// @notice Destination chain identifier (e.g., "POLKADOT-1000", "EVM-1")
+    /// @dev Must be a valid state machine identifier recognized by the protocol
+    bytes dest;
+    /// @notice Destination application address or identifier
+    /// @dev The receiving application on the destination chain
+    bytes to;
+    /// @notice The request payload
+    /// @dev Arbitrary bytes that will be delivered to the destination application
+    bytes body;
+    /// @notice Timeout duration in seconds from the current timestamp
+    /// @dev Request will be considered timed out after this duration
+    uint64 timeout;
+    /// @notice Fee paid to relayers for delivery & execution
+    /// @dev Paid in the fee token specified by IHost.feeToken()
+    uint256 fee;
+    /// @notice Account responsible for paying the fees
+    /// @dev If different from msg.sender, must have approved the Host contract
+    address payer;
+}
+
+/**
+ * @title DispatchGet
+ * @notice Parameters for dispatching a GET request to query state on another chain
+ * @dev Used to read storage values from other chains at a specific height
+ */
+struct DispatchGet {
+    /// @notice Destination chain identifier
+    /// @dev Must be a valid state machine identifier
+    bytes dest;
+    /// @notice Block height at which to read the state
+    /// @dev Use 0 for latest available state
+    uint64 height;
+    /// @notice Storage keys to query
+    /// @dev Array of storage keys whose values will be retrieved
+    bytes[] keys;
+    /// @notice Timeout duration in seconds
+    /// @dev Query will be considered timed out after this duration
+    uint64 timeout;
+    /// @notice Fee amount for the query operation
+    /// @dev Covers both protocol fees and relayer incentives
+    uint256 fee;
+    /// @notice Application-specific metadata
+    /// @dev Can be used to track the query purpose or pass additional context
+    bytes context;
+}
+
+/**
+ * @title DispatchPostResponse
+ * @notice Parameters for dispatching a response to a previously received POST request
+ * @dev Used by applications to respond to cross-chain requests
+ */
+struct DispatchPostResponse {
+    /// @notice The original request being responded to
+    /// @dev Must be a valid request that was previously received
+    PostRequest request;
+    /// @notice Response payload
+    /// @dev Data to send back to the requesting application
+    bytes response;
+    /// @notice Timeout duration in seconds for the response
+    /// @dev Response will be considered timed out after this duration
+    uint64 timeout;
+    /// @notice Fee paid to relayers for delivery & execution
+    /// @dev Paid in the fee token specified by IHost.feeToken()
+    uint256 fee;
+    /// @notice Account responsible for paying the fees
+    /// @dev If different from msg.sender, must have approved the Host contract
+    address payer;
+}
+
+/**
+ * @title IDispatcher
+ * @author Polytope Labs (hello@polytope.technology)
+ * @notice Interface for dispatching cross-chain messages through Hyperbridge
+ * @dev This interface provides methods for sending POST requests, GET queries, and responses.
+ * All dispatch methods support both native token and fee token payments for relayer fees.
+ * The dispatcher handles message routing, fee collection, and timeout management.
+ */
+interface IDispatcher {
+    /**
+     * @return the host state machine id
+     */
+    function host() external view returns (bytes memory);
+
+    /**
+     * @return the state machine identifier for the connected hyperbridge instance
+     */
+    function hyperbridge() external view returns (bytes memory);
+
+    /**
+     * @return the `frozen` status
+     */
+    function frozen() external view returns (FrozenStatus);
+
+    /**
+     * @dev Returns the address for the Uniswap V2 Router implementation used for swaps
+     * @return routerAddress - The address to the in-use RouterV02 implementation
+     */
+    function uniswapV2Router() external view returns (address);
+
+    /**
+     * @dev Returns the nonce immediately available for requests
+     * @return the `nonce`
+     */
+    function nonce() external view returns (uint256);
+
+    /**
+     * @dev Returns the address of the ERC-20 fee token contract configured for this state machine.
+     *
+     * @notice Hyperbridge collects it's dispatch fees in the provided token denomination. This will typically be in stablecoins.
+     *
+     * @return feeToken - The ERC20 contract address for fees.
+     */
+    function feeToken() external view returns (address);
+
+    /**
+     * @dev Returns the address of the per byte fee configured for the destination state machine.
+     *
+     * @notice Hyperbridge collects it's dispatch fees per every byte of the outgoing message.
+     *
+     * @param dest - The destination chain for the per byte fee.
+     * @return perByteFee - The per byte fee for outgoing messages.
+     */
+    function perByteFee(bytes memory dest) external view returns (uint256);
+
+    /**
+     * @dev Dispatch a POST request to Hyperbridge
+     *
+     * @notice Payment for the request can be made with either the native token or the IHost.feeToken.
+     * If native tokens are supplied, it will perform a swap under the hood using the local uniswap router.
+     * Will revert if enough native tokens are not provided.
+     *
+     * If no native tokens are provided then it will try to collect payment from the calling contract in
+     * the IHost.feeToken.
+     *
+     * @param request - post request
+     * @return commitment - the request commitment
+     */
+    function dispatch(DispatchPost memory request) external payable returns (bytes32 commitment);
+
+    /**
+     * @dev Dispatch a GET request to Hyperbridge
+     *
+     * @notice Payment for the request can be made with either the native token or the IHost.feeToken.
+     * If native tokens are supplied, it will perform a swap under the hood using the local uniswap router.
+     * Will revert if enough native tokens are not provided.
+     *
+     * If no native tokens are provided then it will try to collect payment from the calling contract in
+     * the IHost.feeToken.
+     *
+     * @param request - get request
+     * @return commitment - the request commitment
+     */
+    function dispatch(DispatchGet memory request) external payable returns (bytes32 commitment);
+
+    /**
+     * @dev Dispatch a POST response to Hyperbridge
+     *
+     * @notice Payment for the request can be made with either the native token or the IHost.feeToken.
+     * If native tokens are supplied, it will perform a swap under the hood using the local uniswap router.
+     * Will revert if enough native tokens are not provided.
+     *
+     * If no native tokens are provided then it will try to collect payment from the calling contract in
+     * the IHost.feeToken.
+     *
+     * @param response - post response
+     * @return commitment - the request commitment
+     */
+    function dispatch(DispatchPostResponse memory response) external payable returns (bytes32 commitment);
+
+    /**
+     * @dev Increase the relayer fee for a previously dispatched request.
+     * This is provided for use only on pending requests, such that when they timeout,
+     * the user can recover the entire relayer fee.
+     *
+     * @notice Payment can be made with either the native token or the IHost.feeToken.
+     * If native tokens are supplied, it will perform a swap under the hood using the local uniswap router.
+     * Will revert if enough native tokens are not provided.
+     *
+     * If no native tokens are provided then it will try to collect payment from the calling contract in
+     * the IHost.feeToken.
+     *
+     * If called on an already delivered request, these funds will be seen as a donation to the hyperbridge protocol.
+     * @param commitment - The request commitment
+     * @param amount - The amount provided in `IHost.feeToken()`
+     */
+    function fundRequest(bytes32 commitment, uint256 amount) external payable;
+
+    /**
+     * @dev Increase the relayer fee for a previously dispatched response.
+     * This is provided for use only on pending responses, such that when they timeout,
+     * the user can recover the entire relayer fee.
+     *
+     * @notice Payment can be made with either the native token or the IHost.feeToken.
+     * If native tokens are supplied, it will perform a swap under the hood using the local uniswap router.
+     * Will revert if enough native tokens are not provided.
+     *
+     * If no native tokens are provided then it will try to collect payment from the calling contract in
+     * the IHost.feeToken.
+     *
+     * If called on an already delivered response, these funds will be seen as a donation to the hyperbridge protocol.
+     * @param commitment - The response commitment
+     * @param amount - The amount to be provided in `IHost.feeToken()`
+     */
+    function fundResponse(bytes32 commitment, uint256 amount) external payable;
+}

package/contracts/interfaces/IHandler.sol

@@ -0,0 +1,97 @@
+// 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 {IHost} from "./IHost.sol";
+import {
+    PostRequestMessage,
+    PostResponseMessage,
+    GetResponseMessage,
+    PostRequestTimeoutMessage,
+    PostResponseTimeoutMessage,
+    GetTimeoutMessage
+} from "../libraries/Message.sol";
+
+/**
+ * @title IHandler
+ * @author Polytope Labs (hello@polytope.technology)
+ * @notice Interface for handling incoming cross-chain messages and consensus updates
+ * @dev The Handler is responsible for verifying and processing all incoming ISMP protocol messages.
+ * It validates consensus proofs, message proofs, and ensures messages are delivered to the correct applications.
+ * This interface serves as the entry point for all cross-chain communication through Hyperbridge.
+ */
+interface IHandler {
+    /**
+     * @notice Process an incoming consensus update
+     * @dev Verifies the consensus proof using the registered IConsensus implementation and updates the trusted state.
+     * This enables the protocol to track state changes on remote chains.
+     * @param host The Host contract that stores protocol state
+     * @param proof Consensus proof data (format depends on the consensus mechanism)
+     */
+    function handleConsensus(IHost host, bytes memory proof) external;
+
+    /**
+     * @notice Process a batch of incoming POST requests
+     * @dev Verifies request proofs, checks for timeouts, validates message delays, and dispatches valid requests to destination apps.
+     * Ensures requests haven't expired and come from verified state commitments.
+     * @param host The Host contract that stores protocol state
+     * @param request Batch of POST requests with their merkle proofs
+     */
+    function handlePostRequests(IHost host, PostRequestMessage memory request) external;
+
+    /**
+     * @notice Process a batch of incoming POST responses
+     * @dev Verifies response proofs, checks for timeouts, validates message delays, and dispatches valid responses to requesting apps.
+     * Matches responses to their original requests and ensures they haven't expired.
+     * @param host The Host contract that stores protocol state
+     * @param response Batch of POST responses with their merkle proofs
+     */
+    function handlePostResponses(IHost host, PostResponseMessage memory response) external;
+
+    /**
+     * @notice Process a batch of GET responses (state queries)
+     * @dev Verifies state proofs, checks for timeouts, and delivers the queried state data to requesting apps.
+     * Ensures the state data comes from the requested height and hasn't expired.
+     * @param host The Host contract that stores protocol state
+     * @param message Batch of GET responses with their state proofs
+     */
+    function handleGetResponses(IHost host, GetResponseMessage memory message) external;
+
+    /**
+     * @notice Process POST request timeouts
+     * @dev Verifies non-membership proofs to confirm requests were not processed before timeout.
+     * Notifies source apps about timed-out requests and allows them to handle refunds or retries.
+     * @param host The Host contract that stores protocol state
+     * @param message Batch of timed-out POST requests with non-membership proofs
+     */
+    function handlePostRequestTimeouts(IHost host, PostRequestTimeoutMessage memory message) external;
+
+    /**
+     * @notice Process POST response timeouts
+     * @dev Verifies non-membership proofs to confirm responses were not processed before timeout.
+     * Notifies responding apps about timed-out responses.
+     * @param host The Host contract that stores protocol state
+     * @param message Batch of timed-out POST responses with non-membership proofs
+     */
+    function handlePostResponseTimeouts(IHost host, PostResponseTimeoutMessage memory message) external;
+
+    /**
+     * @notice Process GET request timeouts
+     * @dev Verifies non-membership proofs to confirm queries were not answered before timeout.
+     * Notifies requesting apps about timed-out state queries so they can implement fallback logic.
+     * @param host The Host contract that stores protocol state
+     * @param message Batch of timed-out GET requests with non-membership proofs
+     */
+    function handleGetRequestTimeouts(IHost host, GetTimeoutMessage memory message) external;
+}

package/contracts/interfaces/IHost.sol

@@ -0,0 +1,209 @@
+// 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 {StateCommitment, StateMachineHeight} from "./IConsensus.sol";
+import {IDispatcher} from "./IDispatcher.sol";
+import {PostRequest, PostResponse, GetResponse, GetRequest, FrozenStatus} from "../libraries/Message.sol";
+
+// Some metadata about the request fee
+struct FeeMetadata {
+    // the relayer fee
+    uint256 fee;
+    // user who initiated the request
+    address sender;
+}
+
+struct ResponseReceipt {
+    // commitment of the response object
+    bytes32 responseCommitment;
+    // address of the relayer responsible for this response delivery
+    address relayer;
+}
+
+/**
+ * @title The Host Interface
+ * @author Polytope Labs (hello@polytope.technology)
+ *
+ * @notice The Host interface sits at the core of the interoperable state machine protocol,
+ * It which encapsulates the interfaces required for ISMP datagram handlers and modules.
+ *
+ * @dev The Host provides the necessary storage interface for the ISMP handlers to process
+ * ISMP messages, the Dispatcher provides the interfaces applications use for dispatching requests
+ * and responses. This host implementation delegates all verification logic to the IHandler contract.
+ * It is only responsible for dispatching incoming & outgoing messages as well as managing
+ * the state of the ISMP protocol.
+ */
+interface IHost is IDispatcher {
+    /**
+     * @return the host admin
+     */
+    function admin() external returns (address);
+
+    /**
+     * @return the host timestamp
+     */
+    function timestamp() external view returns (uint256);
+
+    /**
+     * @dev Returns the fisherman responsible for vetoing the given state machine height.
+     * @return the `fisherman` address
+     */
+    function vetoes(uint256 paraId, uint256 height) external view returns (address);
+
+    /**
+     * @dev Returns the fee required for 3rd party applications to access hyperbridge state commitments.
+     * @return the `stateCommitmentFee`
+     */
+    function stateCommitmentFee() external view returns (uint256);
+
+    /**
+     * @notice Charges the stateCommitmentFee to 3rd party applications.
+     * If native tokens are provided, will attempt to swap them for the stateCommitmentFee.
+     * If not enough native tokens are supplied, will revert.
+     *
+     * If no native tokens are provided then it will try to collect payment from the calling contract in
+     * the IHost.feeToken.
+     *
+     * @param height - state machine height
+     * @return the state commitment at `height`
+     */
+    function stateMachineCommitment(StateMachineHeight memory height) external payable returns (StateCommitment memory);
+
+    /**
+     * @param height - state machine height
+     * @return the state machine commitment update time at `height`
+     */
+    function stateMachineCommitmentUpdateTime(StateMachineHeight memory height) external returns (uint256);
+
+    /**
+     * @return the consensus client contract
+     */
+    function consensusClient() external view returns (address);
+
+    /**
+     * @return the last updated time of the consensus client
+     */
+    function consensusUpdateTime() external view returns (uint256);
+
+    /**
+     * @return the latest state machine height for the given stateMachineId. If it returns 0, the state machine is unsupported.
+     */
+    function latestStateMachineHeight(uint256 stateMachineId) external view returns (uint256);
+
+    /**
+     * @return the state of the consensus client
+     */
+    function consensusState() external view returns (bytes memory);
+
+    /**
+     * @dev Check the response status for a given request.
+     * @return `response` status
+     */
+    function responded(bytes32 commitment) external view returns (bool);
+
+    /**
+     * @param commitment - commitment to the request
+     * @return relayer address
+     */
+    function requestReceipts(bytes32 commitment) external view returns (address);
+
+    /**
+     * @param commitment - commitment to the request of the response
+     * @return response receipt
+     */
+    function responseReceipts(bytes32 commitment) external view returns (ResponseReceipt memory);
+
+    /**
+     * @param commitment - commitment to the request
+     * @return existence status of an outgoing request commitment
+     */
+    function requestCommitments(bytes32 commitment) external view returns (FeeMetadata memory);
+
+    /**
+     * @param commitment - commitment to the response
+     * @return existence status of an outgoing response commitment
+     */
+    function responseCommitments(bytes32 commitment) external view returns (FeeMetadata memory);
+
+    /**
+     * @return the challenge period
+     */
+    function challengePeriod() external view returns (uint256);
+
+    /**
+     * @return the unstaking period
+     */
+    function unStakingPeriod() external view returns (uint256);
+
+    /**
+     * @dev set the new frozen state of the host, only the admin or handler can call this.
+     * @param newState - the new frozen state
+     */
+    function setFrozenState(FrozenStatus newState) external;
+
+    /**
+     * @dev Store an encoded consensus state
+     * @param state new consensus state
+     */
+    function storeConsensusState(bytes memory state) external;
+
+    /**
+     * @dev Store the commitment at `state height`
+     * @param height state machine height
+     * @param commitment state commitment
+     */
+    function storeStateMachineCommitment(StateMachineHeight memory height, StateCommitment memory commitment) external;
+
+    /**
+     * @dev Delete the state commitment at given state height.
+     */
+    function deleteStateMachineCommitment(StateMachineHeight memory height, address fisherman) external;
+
+    /**
+     * @dev Dispatch an incoming request to destination app
+     * @param request - post request
+     */
+    function dispatchIncoming(PostRequest memory request, address relayer) external;
+
+    /**
+     * @dev Dispatch an incoming post response to source app
+     * @param response - post response
+     */
+    function dispatchIncoming(PostResponse memory response, address relayer) external;
+
+    /**
+     * @dev Dispatch an incoming get response to source app
+     * @param response - get response
+     */
+    function dispatchIncoming(GetResponse memory response, address relayer) external;
+
+    /**
+     * @dev Dispatch an incoming get timeout to source app
+     * @param timeout - timed-out get request
+     */
+    function dispatchTimeOut(GetRequest memory timeout, FeeMetadata memory meta, bytes32 commitment) external;
+
+    /**
+     * @dev Dispatch an incoming post timeout to source app
+     * @param timeout - timed-out post request
+     */
+    function dispatchTimeOut(PostRequest memory timeout, FeeMetadata memory meta, bytes32 commitment) external;
+
+    /**
+     * @dev Dispatch an incoming post response timeout to source app
+     * @param timeout - timed-out post response
+     */
+    function dispatchTimeOut(PostResponse memory timeout, FeeMetadata memory meta, bytes32 commitment) external;
+}