@hyperbridge/core 1.2.1 → 1.4.0

package/contracts/apps/IntentGatewayV2.sol

@@ -0,0 +1,388 @@
+// 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.24;
+
+/**
+ * @notice Tokens that must be received for a valid order fulfillment
+ */
+struct PaymentInfo {
+    /// @dev The address to receive the output tokens
+    bytes32 beneficiary;
+    /// @dev The assets to be provided by the filler
+    TokenInfo[] assets;
+    /// @dev Optional calldata to be executed on the destination chain
+    bytes call;
+}
+
+/**
+ * @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;
+}
+
+/**
+ * @notice Information for executing calls before an order is placed on the destination chain
+ * @dev Used to specify pre-dispatch operations with associated assets
+ */
+struct DispatchInfo {
+    /// @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.
+ * @param Order The structure defining an order.
+ */
+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 source;
+    /// @dev The state machine identifier of the destination chain
+    bytes destination;
+    /// @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 Optional session key used to select winning solver.
+    address session;
+    /// @dev The predispatch information for the order
+    /// This is used to encode any calls before the order is placed
+    DispatchInfo predispatch;
+    /// @dev The tokens that are escrowed for the filler.
+    TokenInfo[] inputs;
+    /// @dev The filler output, ie the tokens that the filler will provide
+    PaymentInfo output;
+}
+
+/**
+ * @dev Request from hyperbridge for sweeping accumulated dust
+ */
+struct SweepDust {
+    /// @dev The address of the beneficiary of the protocol fee
+    address beneficiary;
+    /// @dev The tokens to be withdrawn
+    TokenInfo[] outputs;
+}
+
+/**
+ * @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 Flag indicating whether solver selection is enabled.
+    bool solverSelection;
+    /// @dev The percentage of surplus (in basis points) that goes to the protocol. The rest goes to beneficiary.
+    /// 10000 = 100%, 5000 = 50%, etc.
+    uint256 surplusShareBps;
+    /// @dev The protocol fee in basis points charged on order inputs.
+    /// 10000 = 100%, 100 = 1%, etc.
+    uint256 protocolFeeBps;
+}
+
+/**
+ * @dev Struct to define the destination fee parameters.
+ */
+struct DestinationFee {
+    /// @dev The percentage of fee (in basis points) charged for the destination chain.
+    /// 10000 = 100%, 5000 = 50%, etc.
+    uint256 destinationFeeBps;
+    /// @dev The state machine ID associated with the destination fee.
+    bytes32 stateMachineId;
+}
+
+/**
+ * @dev Struct to define a parameter update request from Hyperbridge
+ * @notice Contains both general parameters and destination-specific fee configurations
+ */
+struct ParamsUpdate {
+    /// @dev The general parameters for the IntentGateway module
+    Params params;
+    /// @dev The destination fee parameters for specific chains
+    DestinationFee[] destinationFees;
+}
+
+/**
+ * @dev Struct representing the body of a request.
+ */
+struct RequestBody {
+    /// @dev Represents the commitment of an order. This is typically a hash that uniquely identifies the order.
+    bytes32 commitment;
+    /// @dev Stores the identifier for the beneficiary.
+    bytes32 beneficiary;
+    /// @dev An array of token identifiers. Each element in the array represents a unique token involved in the order.
+    TokenInfo[] tokens;
+}
+
+/**
+ * @notice A struct representing the options for filling an intent.
+ * @dev This struct is used to specify various parameters and options
+ *      when filling an intent in the IntentGateway contract.
+ */
+struct FillOptions {
+    /// @dev The fee paid in feeTokens to the relayer for processing transactions.
+    uint256 relayerFee;
+    /// @dev The fee paid in native tokens for cross-chain dispatch.
+    uint256 nativeDispatchFee;
+    /// @dev The output tokens with amounts the solver is willing to give
+    /// @dev Must be strictly >= the amounts requested in order.output.assets
+    TokenInfo[] outputs;
+}
+
+/**
+ * @notice A struct representing the options for selecting a solver
+ * @dev This struct is used to specify various parameters and options
+ *      when selecting a solver.
+ */
+struct SelectOptions {
+    /// @dev The commitment hash of the order.
+    bytes32 commitment;
+    /// @dev The solver address to select.
+    address solver;
+    /// @dev The EIP-712 signature from the session key that signed SelectSolver(commitment, solver)
+    bytes signature;
+}
+
+/**
+ * @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;
+}
+
+/**
+ * @dev Request from hyperbridge for adding a new deployment of IntentGateway
+ */
+struct NewDeployment {
+    /// @dev Identifier for the state machine.
+    bytes stateMachineId;
+    /// @dev An address variable to store the gateway identifier.
+    address gateway;
+}
+
+/**
+ * @title IIntentGatewayV2
+ * @author Polytope Labs (hello@polytope.technology)
+ * @notice Interface for the IntentGatewayV2 contract
+ * @dev Defines all external functions, events, and errors for cross-chain intent fulfillment
+ */
+interface IIntentGatewayV2 {
+    // ============================================
+    // Errors
+    // ============================================
+
+    /// @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();
+
+    // ============================================
+    // Events
+    // ============================================
+
+    /**
+     * @notice Emitted when an order is placed.
+     * @param user The address of the user who is initiating the transfer
+     * @param source The state machine identifier of the origin chain
+     * @param destination The state machine identifier of the destination chain
+     * @param deadline The block number by which the order must be filled
+     * @param nonce The nonce of the order
+     * @param fees The dispatch fees associated with the order
+     * @param session Optional session key used to select winning solver
+     * @param beneficiary The address to receive the output tokens
+     * @param predispatch The predispatch assets for the order
+     * @param inputs The tokens that are escrowed for the filler (amounts reflect values after protocol fee deduction)
+     * @param outputs The tokens that the filler will provide
+     */
+    event OrderPlaced(
+        bytes32 user,
+        bytes source,
+        bytes destination,
+        uint256 deadline,
+        uint256 nonce,
+        uint256 fees,
+        address session,
+        bytes32 beneficiary,
+        TokenInfo[] predispatch,
+        TokenInfo[] inputs,
+        TokenInfo[] outputs
+    );
+
+    /**
+     * @notice Emitted when an order is filled.
+     * @param commitment The unique identifier of the order
+     * @param filler The address of the entity that filled the order
+     */
+    event OrderFilled(bytes32 indexed commitment, address filler);
+
+    /**
+     * @notice Emitted when an escrow is released.
+     * @param commitment The unique identifier of the order
+     */
+    event EscrowReleased(bytes32 indexed commitment);
+
+    /**
+     * @notice Emitted when an escrow is refunded.
+     * @param commitment The unique identifier of the order
+     */
+    event EscrowRefunded(bytes32 indexed commitment);
+
+    /**
+     * @notice Emitted when parameters are updated.
+     * @param previous The previous parameters
+     * @param current The current parameters
+     */
+    event ParamsUpdated(Params previous, Params current);
+
+    /**
+     * @notice Emitted when a new deployment is added.
+     * @param stateMachineId The state machine identifier
+     * @param gateway The gateway identifier
+     */
+    event NewDeploymentAdded(bytes stateMachineId, address gateway);
+
+    /**
+     * @notice Emitted when dust is collected.
+     * @param token The token address
+     * @param amount The amount of dust collected
+     */
+    event DustCollected(address token, uint256 amount);
+
+    /**
+     * @notice Emitted when dust is swept to a beneficiary.
+     * @param token The token address
+     * @param amount The amount swept
+     * @param beneficiary The beneficiary of the funds
+     */
+    event DustSwept(address token, uint256 amount, address beneficiary);
+
+    // ============================================
+    // Constants
+    // ============================================
+
+    /**
+     * @notice EIP-712 type hash for SelectSolver message
+     */
+    function SELECT_SOLVER_TYPEHASH() external view returns (bytes32);
+
+    /**
+     * @notice EIP-712 domain separator
+     */
+    function DOMAIN_SEPARATOR() external view returns (bytes32);
+
+    // ============================================
+    // Functions
+    // ============================================
+
+    /**
+     * @notice Returns the host contract address.
+     * @return address The address of the IsmpHost contract
+     */
+    function host() external view returns (address);
+
+    /**
+     * @notice Fetch the IntentGateway contract instance for a chain.
+     * @param stateMachineId The state machine identifier
+     * @return address The gateway address for the given state machine
+     */
+    function instance(bytes calldata stateMachineId) external view returns (address);
+
+    /**
+     * @notice Sets the parameters for the IntentGateway module.
+     * @param p The parameters to be set, encapsulated in a Params struct
+     */
+    function setParams(Params memory p) external;
+
+    /**
+     * @notice Returns the current parameters of the module.
+     * @return Params A struct containing the module's current parameters
+     */
+    function params() external view returns (Params memory);
+
+    /**
+     * @notice Calculates the commitment slot hash for storage proof verification.
+     * @param commitment The commitment hash
+     * @return bytes The calculated commitment slot hash
+     */
+    function calculateCommitmentSlotHash(bytes32 commitment) external pure returns (bytes memory);
+
+    /**
+     * @notice Places an order for cross-chain intent fulfillment.
+     * @dev If protocolFeeBps is configured, a protocol fee is deducted from each input token amount.
+     *      The full input amounts are escrowed, but the OrderPlaced event emits reduced amounts (after fee).
+     *      Protocol fees are retained as dust and can be swept via SweepDust requests.
+     * @param order The order to be placed
+     * @param graffiti The arbitrary data used for identification purposes
+     */
+    function placeOrder(Order memory order, bytes32 graffiti) external payable;
+
+    /**
+     * @notice Selects a solver for an order (when solver selection is enabled).
+     * @param options The options for selecting a solver
+     * @return sessionKey The recovered session key address
+     */
+    function select(SelectOptions calldata options) external returns (address sessionKey);
+
+    /**
+     * @notice Fills an order with the specified options.
+     * @param order The order to be filled
+     * @param options The options to be used when filling the order
+     */
+    function fillOrder(Order calldata order, FillOptions calldata options) external payable;
+
+    /**
+     * @notice Cancels an order after it has expired.
+     * @param order The order to be cancelled
+     * @param options The cancellation options
+     */
+    function cancelOrder(Order calldata order, CancelOptions calldata options) external payable;
+}

package/contracts/apps/TokenGateway.sol

@@ -15,33 +15,33 @@
 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;
+    // 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;
+    // address of the IsmpHost contract on this chain
+    address host;
+    // dispatcher for delegating external calls
+    address dispatcher;
 }
 
 /**
@@ -55,88 +55,88 @@ struct TokenGatewayParams {
  * 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 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 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
-	);
+    // 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 Unexpected zero address
+    error ZeroAddress();
 
-	// @dev Provided amount was invalid
-	error InvalidAmount();
+    // @dev Provided amount was invalid
+    error InvalidAmount();
 
-	// @dev Provided token was unknown
-	error UnknownAsset();
+    // @dev Provided token was unknown
+    error UnknownAsset();
 
-	// @dev Protocol invariant violated
-	error InconsistentState();
+    // @dev Protocol invariant violated
+    error InconsistentState();
 
-	/**
-	 * @dev Read the protocol parameters
-	 */
-	function params() external view returns (TokenGatewayParams memory);
+    /**
+     * @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 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 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 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;
+    /**
+     * @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.2.1",
+  "version": "1.4.0",
   "description": "Hyperbridge Solidity SDK for dispatching & receiving cross-chain messages",
   "author": "Polytope Labs <hello@polytope.technology>",
   "license": "Apache-2.0",