@hyperlane-xyz/core 1.4.0 → 1.4.2

package/docs/src/contracts/igps/InterchainGasPaymaster.sol/contract.InterchainGasPaymaster.md

@@ -0,0 +1,231 @@
+# InterchainGasPaymaster
+[Git Source](https://github.com/hyperlane-xyz/hyperlane-monorepo/blob/a5209dbd9b0f5eb34e0bc9df2ba157dda2b454d3/contracts/igps/InterchainGasPaymaster.sol)
+
+**Inherits:**
+[IInterchainGasPaymaster](/contracts/interfaces/IInterchainGasPaymaster.sol/interface.IInterchainGasPaymaster.md), [IGasOracle](/contracts/interfaces/IGasOracle.sol/interface.IGasOracle.md), OwnableUpgradeable
+
+Manages payments on a source chain to cover gas costs of relaying
+messages to destination chains.
+
+
+## State Variables
+### TOKEN_EXCHANGE_RATE_SCALE
+The scale of gas oracle token exchange rates.
+
+
+```solidity
+uint256 internal constant TOKEN_EXCHANGE_RATE_SCALE = 1e10;
+```
+
+
+### gasOracles
+Keyed by remote domain, the gas oracle to use for the domain.
+
+
+```solidity
+mapping(uint32 => IGasOracle) public gasOracles;
+```
+
+
+### beneficiary
+The benficiary that can receive native tokens paid into this contract.
+
+
+```solidity
+address public beneficiary;
+```
+
+
+## Functions
+### initialize
+
+
+```solidity
+function initialize(address _owner, address _beneficiary) public initializer;
+```
+**Parameters**
+
+|Name|Type|Description|
+|----|----|-----------|
+|`_owner`|`address`|The owner of the contract.|
+|`_beneficiary`|`address`|The beneficiary.|
+
+
+### payForGas
+
+Deposits msg.value as a payment for the relaying of a message
+to its destination chain.
+
+*Overpayment will result in a refund of native tokens to the _refundAddress.
+Callers should be aware that this may present reentrancy issues.*
+
+
+```solidity
+function payForGas(bytes32 _messageId, uint32 _destinationDomain, uint256 _gasAmount, address _refundAddress)
+    external
+    payable
+    override;
+```
+**Parameters**
+
+|Name|Type|Description|
+|----|----|-----------|
+|`_messageId`|`bytes32`|The ID of the message to pay for.|
+|`_destinationDomain`|`uint32`|The domain of the message's destination chain.|
+|`_gasAmount`|`uint256`|The amount of destination gas to pay for.|
+|`_refundAddress`|`address`|The address to refund any overpayment to.|
+
+
+### claim
+
+Transfers the entire native token balance to the beneficiary.
+
+*The beneficiary must be able to receive native tokens.*
+
+
+```solidity
+function claim() external;
+```
+
+### setGasOracles
+
+Sets the gas oracles for remote domains specified in the config array.
+
+
+```solidity
+function setGasOracles(GasOracleConfig[] calldata _configs) external onlyOwner;
+```
+**Parameters**
+
+|Name|Type|Description|
+|----|----|-----------|
+|`_configs`|`GasOracleConfig[]`|An array of configs including the remote domain and gas oracles to set.|
+
+
+### setBeneficiary
+
+Sets the beneficiary.
+
+
+```solidity
+function setBeneficiary(address _beneficiary) external onlyOwner;
+```
+**Parameters**
+
+|Name|Type|Description|
+|----|----|-----------|
+|`_beneficiary`|`address`|The new beneficiary.|
+
+
+### quoteGasPayment
+
+Quotes the amount of native tokens to pay for interchain gas.
+
+
+```solidity
+function quoteGasPayment(uint32 _destinationDomain, uint256 _gasAmount)
+    public
+    view
+    virtual
+    override
+    returns (uint256);
+```
+**Parameters**
+
+|Name|Type|Description|
+|----|----|-----------|
+|`_destinationDomain`|`uint32`|The domain of the message's destination chain.|
+|`_gasAmount`|`uint256`|The amount of destination gas to pay for.|
+
+**Returns**
+
+|Name|Type|Description|
+|----|----|-----------|
+|`<none>`|`uint256`|The amount of native tokens required to pay for interchain gas.|
+
+
+### getExchangeRateAndGasPrice
+
+Gets the token exchange rate and gas price from the configured gas oracle
+for a given destination domain.
+
+
+```solidity
+function getExchangeRateAndGasPrice(uint32 _destinationDomain)
+    public
+    view
+    override
+    returns (uint128 tokenExchangeRate, uint128 gasPrice);
+```
+**Parameters**
+
+|Name|Type|Description|
+|----|----|-----------|
+|`_destinationDomain`|`uint32`|The destination domain.|
+
+**Returns**
+
+|Name|Type|Description|
+|----|----|-----------|
+|`tokenExchangeRate`|`uint128`|The exchange rate of the remote native token quoted in the local native token.|
+|`gasPrice`|`uint128`|The gas price on the remote chain.|
+
+
+### _setBeneficiary
+
+Sets the beneficiary.
+
+
+```solidity
+function _setBeneficiary(address _beneficiary) internal;
+```
+**Parameters**
+
+|Name|Type|Description|
+|----|----|-----------|
+|`_beneficiary`|`address`|The new beneficiary.|
+
+
+### _setGasOracle
+
+Sets the gas oracle for a remote domain.
+
+
+```solidity
+function _setGasOracle(uint32 _remoteDomain, address _gasOracle) internal;
+```
+**Parameters**
+
+|Name|Type|Description|
+|----|----|-----------|
+|`_remoteDomain`|`uint32`|The remote domain.|
+|`_gasOracle`|`address`|The gas oracle.|
+
+
+## Events
+### GasOracleSet
+Emitted when the gas oracle for a remote domain is set.
+
+
+```solidity
+event GasOracleSet(uint32 indexed remoteDomain, address gasOracle);
+```
+
+### BeneficiarySet
+Emitted when the beneficiary is set.
+
+
+```solidity
+event BeneficiarySet(address beneficiary);
+```
+
+## Structs
+### GasOracleConfig
+
+```solidity
+struct GasOracleConfig {
+    uint32 remoteDomain;
+    address gasOracle;
+}
+```
+

package/docs/src/contracts/igps/OverheadIgp.sol/contract.OverheadIgp.md

@@ -0,0 +1,161 @@
+# OverheadIgp
+[Git Source](https://github.com/hyperlane-xyz/hyperlane-monorepo/blob/a5209dbd9b0f5eb34e0bc9df2ba157dda2b454d3/contracts/igps/OverheadIgp.sol)
+
+**Inherits:**
+[IInterchainGasPaymaster](/contracts/interfaces/IInterchainGasPaymaster.sol/interface.IInterchainGasPaymaster.md), Ownable
+
+An IGP that adds configured gas overheads to gas amounts and forwards
+calls to an "inner" IGP.
+
+*The intended use of this contract is to store overhead gas amounts for destination
+domains, e.g. Mailbox and/or ISM gas usage, such that users of this IGP are only required
+to specify the gas amount used by their own applications.*
+
+
+## State Variables
+### innerIgp
+The IGP that is called when paying for or quoting gas
+after applying overhead gas amounts.
+
+
+```solidity
+IInterchainGasPaymaster public immutable innerIgp;
+```
+
+
+### destinationGasOverhead
+Destination domain => overhead gas amount on that domain.
+
+
+```solidity
+mapping(uint32 => uint256) public destinationGasOverhead;
+```
+
+
+## Functions
+### constructor
+
+
+```solidity
+constructor(address _innerIgp);
+```
+
+### payForGas
+
+Adds the stored destinationGasOverhead to the _gasAmount and forwards the
+call to the innerIgp's `payForGas` function.
+
+
+```solidity
+function payForGas(bytes32 _messageId, uint32 _destinationDomain, uint256 _gasAmount, address _refundAddress)
+    external
+    payable;
+```
+**Parameters**
+
+|Name|Type|Description|
+|----|----|-----------|
+|`_messageId`|`bytes32`|The ID of the message to pay for.|
+|`_destinationDomain`|`uint32`|The domain of the message's destination chain.|
+|`_gasAmount`|`uint256`|The amount of destination gas to pay for. This should not consider any gas that is accounted for in the stored destinationGasOverhead.|
+|`_refundAddress`|`address`|The address to refund any overpayment to.|
+
+
+### setDestinationGasOverheads
+
+Sets destination gas overheads for multiple domains.
+
+*Only callable by the owner.*
+
+
+```solidity
+function setDestinationGasOverheads(DomainConfig[] calldata configs) external onlyOwner;
+```
+**Parameters**
+
+|Name|Type|Description|
+|----|----|-----------|
+|`configs`|`DomainConfig[]`|A list of destination domains and gas overheads.|
+
+
+### quoteGasPayment
+
+Adds the stored destinationGasOverhead to the _gasAmount and forwards the
+call to the innerIgp's `quoteGasPayment` function.
+
+
+```solidity
+function quoteGasPayment(uint32 _destinationDomain, uint256 _gasAmount) public view returns (uint256);
+```
+**Parameters**
+
+|Name|Type|Description|
+|----|----|-----------|
+|`_destinationDomain`|`uint32`|The domain of the message's destination chain.|
+|`_gasAmount`|`uint256`|The amount of destination gas to pay for. This should not consider any gas that is accounted for in the stored destinationGasOverhead.|
+
+**Returns**
+
+|Name|Type|Description|
+|----|----|-----------|
+|`<none>`|`uint256`|The amount of native tokens required to pay for interchain gas.|
+
+
+### destinationGasAmount
+
+Returns the stored destinationGasOverhead added to the _gasAmount.
+
+*If there is no stored destinationGasOverhead, 0 is used.*
+
+
+```solidity
+function destinationGasAmount(uint32 _destinationDomain, uint256 _gasAmount) public view returns (uint256);
+```
+**Parameters**
+
+|Name|Type|Description|
+|----|----|-----------|
+|`_destinationDomain`|`uint32`|The domain of the message's destination chain.|
+|`_gasAmount`|`uint256`|The amount of destination gas to pay for. This should not consider any gas that is accounted for in the stored destinationGasOverhead.|
+
+**Returns**
+
+|Name|Type|Description|
+|----|----|-----------|
+|`<none>`|`uint256`|The stored destinationGasOverhead added to the _gasAmount.|
+
+
+### _setDestinationGasOverhead
+
+Sets the destination gas overhead for a single domain.
+
+
+```solidity
+function _setDestinationGasOverhead(DomainConfig calldata config) internal;
+```
+**Parameters**
+
+|Name|Type|Description|
+|----|----|-----------|
+|`config`|`DomainConfig`|The destination domain and gas overhead.|
+
+
+## Events
+### DestinationGasOverheadSet
+Emitted when an entry in the destinationGasOverhead mapping is set.
+
+
+```solidity
+event DestinationGasOverheadSet(uint32 indexed domain, uint256 gasOverhead);
+```
+
+## Structs
+### DomainConfig
+
+```solidity
+struct DomainConfig {
+    uint32 domain;
+    uint256 gasOverhead;
+}
+```
+

package/docs/src/contracts/igps/README.md

@@ -0,0 +1,6 @@
+
+
+# Contents
+- [gas-oracles](/contracts/igps/gas-oracles)
+- [InterchainGasPaymaster](InterchainGasPaymaster.sol/contract.InterchainGasPaymaster.md)
+- [OverheadIgp](OverheadIgp.sol/contract.OverheadIgp.md)

package/docs/src/contracts/igps/gas-oracles/README.md

@@ -0,0 +1,4 @@
+
+
+# Contents
+- [StorageGasOracle](StorageGasOracle.sol/contract.StorageGasOracle.md)

package/docs/src/contracts/igps/gas-oracles/StorageGasOracle.sol/contract.StorageGasOracle.md

@@ -0,0 +1,114 @@
+# StorageGasOracle
+[Git Source](https://github.com/hyperlane-xyz/hyperlane-monorepo/blob/a5209dbd9b0f5eb34e0bc9df2ba157dda2b454d3/contracts/igps/gas-oracles/StorageGasOracle.sol)
+
+**Inherits:**
+[IGasOracle](/contracts/interfaces/IGasOracle.sol/interface.IGasOracle.md), Ownable
+
+A gas oracle that uses data stored within the contract.
+
+*This contract is intended to be owned by an address that will
+update the stored remote gas data.*
+
+
+## State Variables
+### remoteGasData
+Keyed by remote domain, gas data on that remote domain.
+
+
+```solidity
+mapping(uint32 => IGasOracle.RemoteGasData) public remoteGasData;
+```
+
+
+## Functions
+### getExchangeRateAndGasPrice
+
+Returns the stored `remoteGasData` for the `_destinationDomain`.
+
+
+```solidity
+function getExchangeRateAndGasPrice(uint32 _destinationDomain)
+    external
+    view
+    override
+    returns (uint128 tokenExchangeRate, uint128 gasPrice);
+```
+**Parameters**
+
+|Name|Type|Description|
+|----|----|-----------|
+|`_destinationDomain`|`uint32`|The destination domain.|
+
+**Returns**
+
+|Name|Type|Description|
+|----|----|-----------|
+|`tokenExchangeRate`|`uint128`|The exchange rate of the remote native token quoted in the local native token.|
+|`gasPrice`|`uint128`|The gas price on the remote chain.|
+
+
+### setRemoteGasDataConfigs
+
+Sets the remote gas data for many remotes at a time.
+
+
+```solidity
+function setRemoteGasDataConfigs(RemoteGasDataConfig[] calldata _configs) external onlyOwner;
+```
+**Parameters**
+
+|Name|Type|Description|
+|----|----|-----------|
+|`_configs`|`RemoteGasDataConfig[]`|The configs to use when setting the remote gas data.|
+
+
+### setRemoteGasData
+
+Sets the remote gas data using the values in `_config`.
+
+
+```solidity
+function setRemoteGasData(RemoteGasDataConfig calldata _config) external onlyOwner;
+```
+**Parameters**
+
+|Name|Type|Description|
+|----|----|-----------|
+|`_config`|`RemoteGasDataConfig`|The config to use when setting the remote gas data.|
+
+
+### _setRemoteGasData
+
+Sets the remote gas data using the values in `_config`.
+
+
+```solidity
+function _setRemoteGasData(RemoteGasDataConfig calldata _config) internal;
+```
+**Parameters**
+
+|Name|Type|Description|
+|----|----|-----------|
+|`_config`|`RemoteGasDataConfig`|The config to use when setting the remote gas data.|
+
+
+## Events
+### RemoteGasDataSet
+Emitted when an entry in `remoteGasData` is set.
+
+
+```solidity
+event RemoteGasDataSet(uint32 indexed remoteDomain, uint128 tokenExchangeRate, uint128 gasPrice);
+```
+
+## Structs
+### RemoteGasDataConfig
+
+```solidity
+struct RemoteGasDataConfig {
+    uint32 remoteDomain;
+    uint128 tokenExchangeRate;
+    uint128 gasPrice;
+}
+```
+

package/docs/src/contracts/interfaces/IGasOracle.sol/interface.IGasOracle.md

@@ -0,0 +1,25 @@
+# IGasOracle
+[Git Source](https://github.com/hyperlane-xyz/hyperlane-monorepo/blob/a5209dbd9b0f5eb34e0bc9df2ba157dda2b454d3/contracts/interfaces/IGasOracle.sol)
+
+
+## Functions
+### getExchangeRateAndGasPrice
+
+
+```solidity
+function getExchangeRateAndGasPrice(uint32 _destinationDomain)
+    external
+    view
+    returns (uint128 tokenExchangeRate, uint128 gasPrice);
+```
+
+## Structs
+### RemoteGasData
+
+```solidity
+struct RemoteGasData {
+    uint128 tokenExchangeRate;
+    uint128 gasPrice;
+}
+```
+

package/docs/src/contracts/interfaces/IHyperlaneConnectionClient.sol/interface.IHyperlaneConnectionClient.md

@@ -0,0 +1,43 @@
+# IHyperlaneConnectionClient
+[Git Source](https://github.com/hyperlane-xyz/hyperlane-monorepo/blob/a5209dbd9b0f5eb34e0bc9df2ba157dda2b454d3/contracts/interfaces/IHyperlaneConnectionClient.sol)
+
+**Inherits:**
+[ISpecifiesInterchainSecurityModule](/contracts/interfaces/IInterchainSecurityModule.sol/interface.ISpecifiesInterchainSecurityModule.md)
+
+
+## Functions
+### mailbox
+
+
+```solidity
+function mailbox() external view returns (IMailbox);
+```
+
+### interchainGasPaymaster
+
+
+```solidity
+function interchainGasPaymaster() external view returns (IInterchainGasPaymaster);
+```
+
+### setMailbox
+
+
+```solidity
+function setMailbox(address) external;
+```
+
+### setInterchainGasPaymaster
+
+
+```solidity
+function setInterchainGasPaymaster(address) external;
+```
+
+### setInterchainSecurityModule
+
+
+```solidity
+function setInterchainSecurityModule(address) external;
+```
+

package/docs/src/contracts/interfaces/IInterchainGasPaymaster.sol/interface.IInterchainGasPaymaster.md

@@ -0,0 +1,33 @@
+# IInterchainGasPaymaster
+[Git Source](https://github.com/hyperlane-xyz/hyperlane-monorepo/blob/a5209dbd9b0f5eb34e0bc9df2ba157dda2b454d3/contracts/interfaces/IInterchainGasPaymaster.sol)
+
+Manages payments on a source chain to cover gas costs of relaying
+messages to destination chains.
+
+
+## Functions
+### payForGas
+
+
+```solidity
+function payForGas(bytes32 _messageId, uint32 _destinationDomain, uint256 _gasAmount, address _refundAddress)
+    external
+    payable;
+```
+
+### quoteGasPayment
+
+
+```solidity
+function quoteGasPayment(uint32 _destinationDomain, uint256 _gasAmount) external view returns (uint256);
+```
+
+## Events
+### GasPayment
+Emitted when a payment is made for a message's gas costs.
+
+
+```solidity
+event GasPayment(bytes32 indexed messageId, uint256 gasAmount, uint256 payment);
+```
+

package/docs/src/contracts/interfaces/IInterchainSecurityModule.sol/interface.IInterchainSecurityModule.md

@@ -0,0 +1,55 @@
+# IInterchainSecurityModule
+[Git Source](https://github.com/hyperlane-xyz/hyperlane-monorepo/blob/a5209dbd9b0f5eb34e0bc9df2ba157dda2b454d3/contracts/interfaces/IInterchainSecurityModule.sol)
+
+
+## Functions
+### moduleType
+
+Returns an enum that represents the type of security model
+encoded by this ISM.
+
+*Relayers infer how to fetch and format metadata.*
+
+
+```solidity
+function moduleType() external view returns (uint8);
+```
+
+### verify
+
+Defines a security model responsible for verifying interchain
+messages based on the provided metadata.
+
+
+```solidity
+function verify(bytes calldata _metadata, bytes calldata _message) external returns (bool);
+```
+**Parameters**
+
+|Name|Type|Description|
+|----|----|-----------|
+|`_metadata`|`bytes`|Off-chain metadata provided by a relayer, specific to the security model encoded by the module (e.g. validator signatures)|
+|`_message`|`bytes`|Hyperlane encoded interchain message|
+
+**Returns**
+
+|Name|Type|Description|
+|----|----|-----------|
+|`<none>`|`bool`|True if the message was verified|
+
+
+## Enums
+### Types
+
+```solidity
+enum Types {
+    UNUSED,
+    ROUTING,
+    AGGREGATION,
+    LEGACY_MULTISIG,
+    MERKLE_ROOT_MULTISIG,
+    MESSAGE_ID_MULTISIG,
+    NULL
+}
+```
+

package/docs/src/contracts/interfaces/IInterchainSecurityModule.sol/interface.ISpecifiesInterchainSecurityModule.md

@@ -0,0 +1,12 @@
+# ISpecifiesInterchainSecurityModule
+[Git Source](https://github.com/hyperlane-xyz/hyperlane-monorepo/blob/a5209dbd9b0f5eb34e0bc9df2ba157dda2b454d3/contracts/interfaces/IInterchainSecurityModule.sol)
+
+
+## Functions
+### interchainSecurityModule
+
+
+```solidity
+function interchainSecurityModule() external view returns (IInterchainSecurityModule);
+```
+

package/docs/src/contracts/interfaces/ILiquidityLayerMessageRecipient.sol/interface.ILiquidityLayerMessageRecipient.md

@@ -0,0 +1,13 @@
+# ILiquidityLayerMessageRecipient
+[Git Source](https://github.com/hyperlane-xyz/hyperlane-monorepo/blob/a5209dbd9b0f5eb34e0bc9df2ba157dda2b454d3/contracts/interfaces/ILiquidityLayerMessageRecipient.sol)
+
+
+## Functions
+### handleWithTokens
+
+
+```solidity
+function handleWithTokens(uint32 _origin, bytes32 _sender, bytes calldata _message, address _token, uint256 _amount)
+    external;
+```
+