@hyperbridge/core 1.0.0 → 1.1.0

package/README.md

@@ -3,7 +3,7 @@
 ![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.
+Hyperbridge SDK for EVM environments. This contains libraries & interfaces for working with hyperbridge contracts. These contracts can be used for sending data (Post requests), pulling data (Get requests), and working with token transfers (TokenGateway & IntentGateway)
 
 ### Interfaces
 
@@ -22,6 +22,8 @@
 
  - [`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
+ - [`ITokenGateway`](contracts/apps/TokenGateway.sol) - Interface for the TokenGateway contract that enables transfers of hyper-fungible tokens using Hyperbridge. Supports both ERC20 token custody and ERC6160 token burn-and-mint mechanisms
+ - [`IIntentGateway`](contracts/apps/IntentGateway.sol) - Interface for the IntentGateway contract that facilitates cross-chain intent-based orders. Allows users to place orders that can be filled by market makers across different chains
 
 ## License
 

package/contracts/apps/HyperApp.sol

@@ -17,6 +17,8 @@ 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";
 
+import {IERC20} from "@openzeppelin/contracts/token/ERC20/IERC20.sol";
+
 /**
  * @dev Uniswap interface for estimating fees in the native token
  */
@@ -65,19 +67,6 @@ abstract contract HyperApp is IApp {
         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
      */
@@ -90,9 +79,17 @@ abstract contract HyperApp is IApp {
     }
 
     /**
-     * @dev returns the quoted fee in the native token for dispatching a GET request
+     * @dev returns the quoted fee in the feeToken for dispatching a POST response
      */
-    function quoteNative(DispatchGet memory request) public view returns (uint256) {
+    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 request
+     */
+    function quoteNative(DispatchPost memory request) public view returns (uint256) {
         uint256 fee = quote(request);
         address _host = host();
         address _uniswap = IDispatcher(_host).uniswapV2Router();
@@ -103,11 +100,16 @@ abstract contract HyperApp is IApp {
     }
 
     /**
-     * @dev returns the quoted fee in the feeToken for dispatching a POST response
+     * @dev returns the quoted fee in the native token for dispatching a GET request
      */
-    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));
+    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];
     }
 
     /**
@@ -123,6 +125,54 @@ abstract contract HyperApp is IApp {
         return IUniswapV2Router02(_uniswap).getAmountsIn(fee, path)[0];
     }
 
+    /**
+     * @notice Dispatches a POST request using the fee token for payment
+     * @dev Handles fee token approval and transfer before dispatching the request to the Host.
+     * If the payer is not this contract, transfers fee tokens from the payer to this contract first.
+     * @param request The POST request to dispatch containing destination, body, timeout, and fee parameters
+     * @param payer The address that will pay the fee token. If different from this contract, must have approved this contract to spend the fee amount
+     */
+    function dispatchWithFeeToken(DispatchPost memory request, address payer) internal {
+        address hostAddr = host();
+        address feeToken = IDispatcher(hostAddr).feeToken();
+        uint256 fee = quote(request);
+        if (payer != address(this)) IERC20(feeToken).transferFrom(payer, address(this), fee);
+        IERC20(feeToken).approve(hostAddr, fee);
+        IDispatcher(hostAddr).dispatch(request);
+    }
+
+    /**
+     * @notice Dispatches a POST response using the fee token for payment
+     * @dev Handles fee token approval and transfer before dispatching the response to the Host.
+     * If the payer is not this contract, transfers fee tokens from the payer to this contract first.
+     * @param response The POST response to dispatch containing the original request, response data, timeout, and fee parameters
+     * @param payer The address that will pay the fee token. If different from this contract, must have approved this contract to spend the fee amount
+     */
+    function dispatchWithFeeToken(DispatchPostResponse memory response, address payer) internal {
+        address hostAddr = host();
+        address feeToken = IDispatcher(hostAddr).feeToken();
+        uint256 fee = quote(response);
+        if (payer != address(this)) IERC20(feeToken).transferFrom(payer, address(this), fee);
+        IERC20(feeToken).approve(hostAddr, fee);
+        IDispatcher(hostAddr).dispatch(response);
+    }
+
+    /**
+     * @notice Dispatches a GET request using the fee token for payment
+     * @dev Handles fee token approval and transfer before dispatching the request to the Host.
+     * If the payer is not this contract, transfers fee tokens from the payer to this contract first.
+     * @param request The GET request to dispatch containing destination, keys, height, timeout, and fee parameters
+     * @param payer The address that will pay the fee token. If different from this contract, must have approved this contract to spend the fee amount
+     */
+    function dispatchWithFeeToken(DispatchGet memory request, address payer) internal {
+        address hostAddr = host();
+        address feeToken = IDispatcher(hostAddr).feeToken();
+        uint256 fee = quote(request);
+        if (payer != address(this)) IERC20(feeToken).transferFrom(payer, address(this), fee);
+        IERC20(feeToken).approve(hostAddr, fee);
+        IDispatcher(hostAddr).dispatch(request);
+    }
+
     /**
      * @notice Callback for receiving incoming POST requests
      * @dev Called by the Host when a new POST request is received for this app.

package/contracts/apps/IntentGateway.sol

@@ -0,0 +1,290 @@
+// 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;
+
+/**
+ * @notice Tokens that must be received for a valid order fulfillment
+ */
+struct PaymentInfo {
+    /// @dev The address of the ERC20 token on the destination chain
+    /// @dev address(0) used as a sentinel for the native token
+    bytes32 token;
+    /// @dev The amount of the token to be sent
+    uint256 amount;
+    /// @dev The address to receive the output tokens
+    bytes32 beneficiary;
+}
+
+/**
+ * @notice Tokens that must be escrowed for an order
+ */
+struct TokenInfo {
+    /// @dev The address of the ERC20 token on the destination chain
+    /// @dev address(0) used as a sentinel for the native token
+    bytes32 token;
+    /// @dev The amount of the token to be sent
+    uint256 amount;
+}
+
+/**
+ * @dev Struct for predispatch information
+ */
+struct PredispatchInfo {
+    /// @dev Assets to execute a predispatch call with
+    TokenInfo[] assets;
+    /// @dev The actual call data to be executed
+    bytes call;
+}
+
+/**
+ * @dev Represents an order in the IntentGateway module.
+ */
+struct Order {
+    /// @dev The address of the user who is initiating the transfer
+    bytes32 user;
+    /// @dev The state machine identifier of the origin chain
+    bytes sourceChain;
+    /// @dev The state machine identifier of the destination chain
+    bytes destChain;
+    /// @dev The block number by which the order must be filled on the destination chain
+    uint256 deadline;
+    /// @dev The nonce of the order
+    uint256 nonce;
+    /// @dev Represents the dispatch fees associated with the IntentGateway.
+    uint256 fees;
+    /// @dev The tokens that the filler will provide.
+    PaymentInfo[] outputs;
+    /// @dev The tokens that are escrowed for the filler.
+    TokenInfo[] inputs;
+    /// @dev The predispatch information for the order
+    PredispatchInfo predispatch;
+    /// @dev A bytes array to store the calls if any.
+    bytes callData;
+}
+
+/**
+ * @dev Struct to define the parameters for the IntentGateway module.
+ */
+struct Params {
+    /// @dev The address of the host contract
+    address host;
+    /// @dev Address of the dispatcher contract responsible for handling intents.
+    address dispatcher;
+    /// @dev Protocol fee in basis points (BPS) deducted from filler-provided tokens
+    uint256 protocolFeeBps;
+}
+
+/**
+ * @notice A struct representing the options for filling an intent.
+ */
+struct FillOptions {
+    /// @dev The fee paid to the relayer for processing transactions.
+    uint256 relayerFee;
+}
+
+/**
+ * @dev Struct representing the options for canceling an intent.
+ */
+struct CancelOptions {
+    /// @dev The fee paid to the relayer for processing transactions.
+    uint256 relayerFee;
+    /// @dev Stores the height value.
+    uint256 height;
+}
+
+/**
+ * @title IIntentGatewayV2
+ * @author Polytope Labs (hello@polytope.technology)
+ * @notice Interface for the IntentGatewayV2 contract
+ * @dev The IntentGateway allows for the creation and fulfillment of cross-chain orders.
+ */
+interface IIntentGateway {
+    /**
+     * @dev Enum representing the different kinds of incoming requests that can be executed.
+     */
+    enum RequestKind {
+        /// @dev Identifies a request for redeeming an escrow.
+        RedeemEscrow,
+        /// @dev Identifies a request for recording new contract deployments
+        NewDeployment,
+        /// @dev Identifies a request for updating parameters.
+        UpdateParams,
+        /// @dev Identifies a request for refunding an escrow.
+        RefundEscrow,
+        /// @dev Identifies a request for collecting fees.
+        CollectFees
+    }
+
+    /// @notice Thrown when an unauthorized action is attempted.
+    error Unauthorized();
+
+    /// @notice Thrown when an invalid input is provided.
+    error InvalidInput();
+
+    /// @notice Thrown when an action is attempted on an expired order.
+    error Expired();
+
+    /// @notice Thrown when there are insufficient native tokens to complete an action.
+    error InsufficientNativeToken();
+
+    /// @notice Thrown when an action is attempted on an order that has not yet expired.
+    error NotExpired();
+
+    /// @notice Thrown when an action is attempted on an order that has already been filled.
+    error Filled();
+
+    /// @notice Thrown when an action is attempted on an order that has been cancelled.
+    error Cancelled();
+
+    /// @notice Thrown when an action is attempted on the wrong chain.
+    error WrongChain();
+
+    /// @notice Thrown when an action is attempted on an unknown order.
+    error UnknownOrder();
+
+    /**
+     * @dev Emitted when an order is placed.
+     */
+    event OrderPlaced(
+        /// @dev The address of the user who is initiating the transfer
+        bytes32 user,
+        /// @dev The state machine identifier of the origin chain
+        bytes sourceChain,
+        /// @dev The state machine identifier of the destination chain
+        bytes destChain,
+        /// @dev The block number by which the order must be filled on the destination chain
+        uint256 deadline,
+        /// @dev The nonce of the order
+        uint256 nonce,
+        /// @dev Represents the dispatch fees associated with the IntentGateway.
+        uint256 fees,
+        /// @dev Assets that were used to execute a predispatch call
+        TokenInfo[] predispatch,
+        /// @dev The tokens that are escrowed for the filler.
+        TokenInfo[] inputs,
+        /// @dev The tokens that the filler will provide.
+        PaymentInfo[] outputs
+    );
+
+    /**
+     * @notice Event emitted when an order is filled.
+     * @param commitment The order commitment hash
+     * @param filler The address of the filler
+     */
+    event OrderFilled(bytes32 commitment, address filler);
+
+    /**
+     * @notice Event emitted when escrow is released.
+     * @param commitment The order commitment hash
+     */
+    event EscrowReleased(bytes32 commitment);
+
+    /**
+     * @notice Event emitted when escrow is refunded.
+     * @param commitment The order commitment hash
+     */
+    event EscrowRefunded(bytes32 commitment);
+
+    /**
+     * @notice Event emitted when parameters are updated.
+     * @param previous The previous parameters
+     * @param current The new parameters
+     */
+    event ParamsUpdated(Params previous, Params current);
+
+    /**
+     * @notice Event emitted when a new deployment is added.
+     * @param stateMachineId The state machine identifier
+     * @param gateway The gateway address
+     */
+    event NewDeploymentAdded(bytes stateMachineId, bytes32 gateway);
+
+    /**
+     * @dev Emitted when dust is collected from predispatch swaps.
+     * @param token The token contract address of the dust, address(0) for native currency.
+     * @param amount The amount of dust collected.
+     */
+    event DustCollected(address token, uint256 amount);
+
+    /**
+     * @dev Emitted when protocol fee is collected from a filler.
+     * @param token The token contract address of the fee, address(0) for native currency.
+     * @param amount The amount of protocol fee collected.
+     * @param chain The chain where the funds are stored.
+     */
+    event FeeCollected(address token, uint256 amount, bytes chain);
+
+    /**
+     * @dev Emitted when protocol revenue is withdrawn.
+     * @param token The token contract address of the fee, address(0) for native currency.
+     * @param amount The amount of protocol revenue collected.
+     * @param beneficiary The beneficiary of the funds
+     */
+    event RevenueWithdrawn(address token, uint256 amount, address beneficiary);
+
+    /**
+     * @notice Returns the host address.
+     * @return The host contract address
+     */
+    function host() external view returns (address);
+
+    /**
+     * @notice Returns the instance address for a given state machine.
+     * @param stateMachineId The state machine identifier
+     * @return The instance address
+     */
+    function instance(bytes calldata stateMachineId) external view returns (bytes32);
+
+    /**
+     * @notice Returns the current gateway parameters.
+     * @return The current parameters
+     */
+    function params() external view returns (Params memory);
+
+    /**
+     * @notice Calculates the commitment slot hash for an order.
+     * @param commitment The order commitment
+     * @return The slot hash
+     */
+    function calculateCommitmentSlotHash(bytes32 commitment) external pure returns (bytes32);
+
+    /**
+     * @notice Places a new order.
+     * @param order The order details
+     * @param graffiti Additional data
+     */
+    function placeOrder(Order memory order, bytes32 graffiti) external payable;
+
+    /**
+     * @notice Fills an existing order.
+     * @param order The order to fill
+     * @param options Fill options including relayer fee
+     */
+    function fillOrder(Order calldata order, FillOptions memory options) external payable;
+
+    /**
+     * @notice Cancels an order (for expired orders).
+     * @param order The order to cancel
+     * @param options Cancel options including height and relayer fee
+     */
+    function cancelOrder(Order calldata order, CancelOptions memory options) external payable;
+
+    /**
+     * @notice Cancels a limit order (for orders with deadline = 0).
+     * @param order The order to cancel
+     * @param options Cancel options including relayer fee
+     */
+    function cancelLimitOrder(Order calldata order, CancelOptions memory options) external payable;
+}

package/contracts/apps/TokenGateway.sol

@@ -0,0 +1,142 @@
+// 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;
+
+struct TeleportParams {
+	// amount to be sent
+	uint256 amount;
+	// Relayer fee
+	uint256 relayerFee;
+	// The token identifier to send
+	bytes32 assetId;
+	// Redeem ERC20 on the destination?
+	bool redeem;
+	// recipient address
+	bytes32 to;
+	// recipient state machine
+	bytes dest;
+	// request timeout in seconds
+	uint64 timeout;
+	// Amount of native token to pay for dispatching the request
+	// if 0 will use the `IIsmpHost.feeToken`
+	uint256 nativeCost;
+	// destination contract call data
+	bytes data;
+}
+
+// Params for the TokenGateway contract
+struct TokenGatewayParams {
+	// address of the IsmpHost contract on this chain
+	address host;
+	// dispatcher for delegating external calls
+	address dispatcher;
+}
+
+/**
+ * @title ITokenGateway
+ * @author Polytope Labs (hello@polytope.technology)
+ *
+ * @notice Interface for the TokenGateway contract that allows users to send either ERC20 or hyper-fungible tokens
+ * using Hyperbridge as a message-passing layer.
+ *
+ * @dev ERC20 tokens are custodied in exchange for hyper-fungible tokens to be minted on the destination chain,
+ * Otherwise if hyper-fungible tokens are sent, then it simply performs a burn-and-mint.
+ */
+interface ITokenGateway {
+	// User has received some assets
+	event AssetReceived(
+		// The amount that was provided to the user
+		uint256 amount,
+		// The associated request commitment
+		bytes32 commitment,
+		// The source of the funds
+		bytes32 indexed from,
+		// The beneficiary of the funds
+		address indexed beneficiary,
+		// The provided assetId
+		bytes32 indexed assetId
+	);
+
+	// User has sent some assets
+	event AssetTeleported(
+		// The beneficiary of the funds
+		bytes32 to,
+		// The destination chain
+		string dest,
+		// The amount that was requested to be sent
+		uint256 amount,
+		// The associated request commitment
+		bytes32 commitment,
+		// The source of the funds
+		address indexed from,
+		// The provided assetId
+		bytes32 indexed assetId,
+		// Flag to redeem funds from the TokenGateway
+		bool redeem
+	);
+
+	// User assets could not be delivered and have been refunded.
+	event AssetRefunded(
+		// The amount that was requested to be sent
+		uint256 amount,
+		// The associated request commitment
+		bytes32 commitment,
+		// The beneficiary of the funds
+		address indexed beneficiary,
+		// The provided assetId
+		bytes32 indexed assetId
+	);
+
+	// @dev Unexpected zero address
+	error ZeroAddress();
+
+	// @dev Provided amount was invalid
+	error InvalidAmount();
+
+	// @dev Provided token was unknown
+	error UnknownAsset();
+
+	// @dev Protocol invariant violated
+	error InconsistentState();
+
+	/**
+	 * @dev Read the protocol parameters
+	 */
+	function params() external view returns (TokenGatewayParams memory);
+
+	/**
+	 * @dev Fetch the address for an ERC20 asset
+	 */
+	function erc20(bytes32 assetId) external view returns (address);
+
+	/**
+	 * @dev Fetch the address for a hyper-fungible asset
+	 */
+	function erc6160(bytes32 assetId) external view returns (address);
+
+	/**
+	 * @dev Fetch the TokenGateway instance for a destination.
+	 */
+	function instance(bytes calldata destination) external view returns (address);
+
+	/**
+	 * @dev Teleports a local ERC20/hyper-fungible asset to the destination chain. Allows users to pay
+	 * the Hyperbridge fees in the native token or `IIsmpHost.feeToken`
+	 *
+	 * @notice If a request times out, users can request a refund permissionlessly through
+	 * `HandlerV1.handlePostRequestTimeouts`.
+	 */
+	function teleport(TeleportParams calldata teleportParams) external payable;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperbridge/core",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Hyperbridge Solidity SDK for dispatching & receiving cross-chain messages",
   "author": "Polytope Labs <hello@polytope.technology>",
   "license": "Apache-2.0",