@hyperlane-xyz/core 1.4.1 → 1.4.2

package/docs/src/contracts/middleware/liquidity-layer/LiquidityLayerRouter.sol/contract.LiquidityLayerRouter.md

@@ -0,0 +1,81 @@
+# LiquidityLayerRouter
+[Git Source](https://github.com/hyperlane-xyz/hyperlane-monorepo/blob/a5209dbd9b0f5eb34e0bc9df2ba157dda2b454d3/contracts/middleware/liquidity-layer/LiquidityLayerRouter.sol)
+
+**Inherits:**
+[Router](/contracts/Router.sol/abstract.Router.md), [ILiquidityLayerRouter](/contracts/interfaces/ILiquidityLayerRouter.sol/interface.ILiquidityLayerRouter.md)
+
+
+## State Variables
+### liquidityLayerAdapters
+
+```solidity
+mapping(string => address) public liquidityLayerAdapters;
+```
+
+
+## Functions
+### initialize
+
+Initializes the Router contract with Hyperlane core contracts and the address of the interchain security module.
+
+
+```solidity
+function initialize(
+    address _mailbox,
+    address _interchainGasPaymaster,
+    address _interchainSecurityModule,
+    address _owner
+) external initializer;
+```
+**Parameters**
+
+|Name|Type|Description|
+|----|----|-----------|
+|`_mailbox`|`address`|The address of the mailbox contract.|
+|`_interchainGasPaymaster`|`address`|The address of the interchain gas paymaster contract.|
+|`_interchainSecurityModule`|`address`|The address of the interchain security module contract.|
+|`_owner`|`address`|The address with owner privileges.|
+
+
+### dispatchWithTokens
+
+
+```solidity
+function dispatchWithTokens(
+    uint32 _destinationDomain,
+    bytes32 _recipientAddress,
+    address _token,
+    uint256 _amount,
+    string calldata _bridge,
+    bytes calldata _messageBody
+) external returns (bytes32);
+```
+
+### _handle
+
+
+```solidity
+function _handle(uint32 _origin, bytes32, bytes calldata _message) internal override;
+```
+
+### setLiquidityLayerAdapter
+
+
+```solidity
+function setLiquidityLayerAdapter(string calldata _bridge, address _adapter) external onlyOwner;
+```
+
+### _getAdapter
+
+
+```solidity
+function _getAdapter(string memory _bridge) internal view returns (ILiquidityLayerAdapter _adapter);
+```
+
+## Events
+### LiquidityLayerAdapterSet
+
+```solidity
+event LiquidityLayerAdapterSet(string indexed bridge, address adapter);
+```
+

package/docs/src/contracts/middleware/liquidity-layer/README.md

@@ -0,0 +1,6 @@
+
+
+# Contents
+- [adapters](/contracts/middleware/liquidity-layer/adapters)
+- [interfaces](/contracts/middleware/liquidity-layer/interfaces)
+- [LiquidityLayerRouter](LiquidityLayerRouter.sol/contract.LiquidityLayerRouter.md)

package/docs/src/contracts/middleware/liquidity-layer/adapters/CircleBridgeAdapter.sol/contract.CircleBridgeAdapter.md

@@ -0,0 +1,197 @@
+# CircleBridgeAdapter
+[Git Source](https://github.com/hyperlane-xyz/hyperlane-monorepo/blob/a5209dbd9b0f5eb34e0bc9df2ba157dda2b454d3/contracts/middleware/liquidity-layer/adapters/CircleBridgeAdapter.sol)
+
+**Inherits:**
+[ILiquidityLayerAdapter](/contracts/middleware/liquidity-layer/interfaces/ILiquidityLayerAdapter.sol/interface.ILiquidityLayerAdapter.md), [Router](/contracts/Router.sol/abstract.Router.md)
+
+
+## State Variables
+### tokenMessenger
+The TokenMessenger contract.
+
+
+```solidity
+ITokenMessenger public tokenMessenger;
+```
+
+
+### circleMessageTransmitter
+The Circle MessageTransmitter contract.
+
+
+```solidity
+ICircleMessageTransmitter public circleMessageTransmitter;
+```
+
+
+### liquidityLayerRouter
+The LiquidityLayerRouter contract.
+
+
+```solidity
+address public liquidityLayerRouter;
+```
+
+
+### hyperlaneDomainToCircleDomain
+Hyperlane domain => Circle domain.
+ATM, known Circle domains are Ethereum = 0 and Avalanche = 1.
+Note this could result in ambiguity between the Circle domain being
+Ethereum or unknown.
+
+
+```solidity
+mapping(uint32 => uint32) public hyperlaneDomainToCircleDomain;
+```
+
+
+### tokenSymbolToAddress
+Token symbol => address of token on local chain.
+
+
+```solidity
+mapping(string => IERC20) public tokenSymbolToAddress;
+```
+
+
+### tokenAddressToSymbol
+Local chain token address => token symbol.
+
+
+```solidity
+mapping(address => string) public tokenAddressToSymbol;
+```
+
+
+## Functions
+### onlyLiquidityLayerRouter
+
+
+```solidity
+modifier onlyLiquidityLayerRouter();
+```
+
+### initialize
+
+
+```solidity
+function initialize(
+    address _owner,
+    address _tokenMessenger,
+    address _circleMessageTransmitter,
+    address _liquidityLayerRouter
+) external initializer;
+```
+**Parameters**
+
+|Name|Type|Description|
+|----|----|-----------|
+|`_owner`|`address`|The new owner.|
+|`_tokenMessenger`|`address`|The TokenMessenger contract.|
+|`_circleMessageTransmitter`|`address`|The Circle MessageTransmitter contract.|
+|`_liquidityLayerRouter`|`address`|The LiquidityLayerRouter contract.|
+
+
+### sendTokens
+
+
+```solidity
+function sendTokens(uint32 _destinationDomain, bytes32, address _token, uint256 _amount)
+    external
+    onlyLiquidityLayerRouter
+    returns (bytes memory);
+```
+
+### receiveTokens
+
+
+```solidity
+function receiveTokens(uint32 _originDomain, address _recipient, uint256 _amount, bytes calldata _adapterData)
+    external
+    onlyLiquidityLayerRouter
+    returns (address, uint256);
+```
+
+### _handle
+
+
+```solidity
+function _handle(uint32, bytes32, bytes calldata) internal pure override;
+```
+
+### addDomain
+
+
+```solidity
+function addDomain(uint32 _hyperlaneDomain, uint32 _circleDomain) external onlyOwner;
+```
+
+### addToken
+
+
+```solidity
+function addToken(address _token, string calldata _tokenSymbol) external onlyOwner;
+```
+
+### removeToken
+
+
+```solidity
+function removeToken(address _token, string calldata _tokenSymbol) external onlyOwner;
+```
+
+### _circleNonceId
+
+Gets the Circle nonce ID by hashing _originCircleDomain and _nonce.
+
+
+```solidity
+function _circleNonceId(uint32 _originCircleDomain, uint64 _nonce) internal pure returns (bytes32);
+```
+**Parameters**
+
+|Name|Type|Description|
+|----|----|-----------|
+|`_originCircleDomain`|`uint32`|Domain of chain where the transfer originated|
+|`_nonce`|`uint64`|The unique identifier for the message from source to destination|
+
+**Returns**
+
+|Name|Type|Description|
+|----|----|-----------|
+|`<none>`|`bytes32`|hash of source and nonce|
+
+
+## Events
+### BridgedToken
+Emits the nonce of the Circle message when a token is bridged.
+
+
+```solidity
+event BridgedToken(uint64 nonce);
+```
+
+### DomainAdded
+Emitted when the Hyperlane domain to Circle domain mapping is updated.
+
+
+```solidity
+event DomainAdded(uint32 indexed hyperlaneDomain, uint32 circleDomain);
+```
+
+### TokenAdded
+Emitted when a local token and its token symbol have been added.
+
+
+```solidity
+event TokenAdded(address indexed token, string indexed symbol);
+```
+
+### TokenRemoved
+Emitted when a local token and its token symbol have been removed.
+
+
+```solidity
+event TokenRemoved(address indexed token, string indexed symbol);
+```
+

package/docs/src/contracts/middleware/liquidity-layer/adapters/PortalAdapter.sol/contract.PortalAdapter.md

@@ -0,0 +1,189 @@
+# PortalAdapter
+[Git Source](https://github.com/hyperlane-xyz/hyperlane-monorepo/blob/a5209dbd9b0f5eb34e0bc9df2ba157dda2b454d3/contracts/middleware/liquidity-layer/adapters/PortalAdapter.sol)
+
+**Inherits:**
+[ILiquidityLayerAdapter](/contracts/middleware/liquidity-layer/interfaces/ILiquidityLayerAdapter.sol/interface.ILiquidityLayerAdapter.md), [Router](/contracts/Router.sol/abstract.Router.md)
+
+
+## State Variables
+### portalTokenBridge
+The Portal TokenBridge contract.
+
+
+```solidity
+IPortalTokenBridge public portalTokenBridge;
+```
+
+
+### liquidityLayerRouter
+The LiquidityLayerRouter contract.
+
+
+```solidity
+address public liquidityLayerRouter;
+```
+
+
+### hyperlaneDomainToWormholeDomain
+Hyperlane domain => Wormhole domain.
+
+
+```solidity
+mapping(uint32 => uint16) public hyperlaneDomainToWormholeDomain;
+```
+
+
+### portalTransfersProcessed
+transferId => token address
+
+
+```solidity
+mapping(bytes32 => address) public portalTransfersProcessed;
+```
+
+
+### localDomain
+
+```solidity
+uint32 public localDomain;
+```
+
+
+### nonce
+
+```solidity
+uint224 public nonce = 0;
+```
+
+
+## Functions
+### onlyLiquidityLayerRouter
+
+
+```solidity
+modifier onlyLiquidityLayerRouter();
+```
+
+### initialize
+
+
+```solidity
+function initialize(uint32 _localDomain, address _owner, address _portalTokenBridge, address _liquidityLayerRouter)
+    public
+    initializer;
+```
+**Parameters**
+
+|Name|Type|Description|
+|----|----|-----------|
+|`_localDomain`|`uint32`|The local hyperlane domain|
+|`_owner`|`address`|The new owner.|
+|`_portalTokenBridge`|`address`|The Portal TokenBridge contract.|
+|`_liquidityLayerRouter`|`address`|The LiquidityLayerRouter contract.|
+
+
+### sendTokens
+
+Sends tokens as requested by the router
+
+
+```solidity
+function sendTokens(uint32 _destinationDomain, bytes32, address _token, uint256 _amount)
+    external
+    onlyLiquidityLayerRouter
+    returns (bytes memory);
+```
+**Parameters**
+
+|Name|Type|Description|
+|----|----|-----------|
+|`_destinationDomain`|`uint32`|The hyperlane domain of the destination|
+|`<none>`|`bytes32`||
+|`_token`|`address`|The token address|
+|`_amount`|`uint256`|The amount of tokens to send|
+
+
+### receiveTokens
+
+Sends the tokens to the recipient as requested by the router
+
+
+```solidity
+function receiveTokens(uint32 _originDomain, address _recipient, uint256 _amount, bytes calldata _adapterData)
+    external
+    onlyLiquidityLayerRouter
+    returns (address, uint256);
+```
+**Parameters**
+
+|Name|Type|Description|
+|----|----|-----------|
+|`_originDomain`|`uint32`|The hyperlane domain of the origin|
+|`_recipient`|`address`|The address of the recipient|
+|`_amount`|`uint256`|The amount of tokens to send|
+|`_adapterData`|`bytes`|The adapter data from the origin chain, containing the nonce|
+
+
+### completeTransfer
+
+Completes the Portal transfer which sends the funds to this adapter.
+The router can call receiveTokens to move those funds to the ultimate recipient.
+
+
+```solidity
+function completeTransfer(bytes memory encodedVm) public;
+```
+**Parameters**
+
+|Name|Type|Description|
+|----|----|-----------|
+|`encodedVm`|`bytes`|The VAA from the Wormhole Guardians|
+
+
+### _handle
+
+
+```solidity
+function _handle(uint32, bytes32, bytes calldata) internal pure override;
+```
+
+### addDomain
+
+
+```solidity
+function addDomain(uint32 _hyperlaneDomain, uint16 _wormholeDomain) external onlyOwner;
+```
+
+### transferId
+
+The key that is used to track fulfilled Portal transfers
+
+
+```solidity
+function transferId(uint32 _hyperlaneDomain, uint224 _nonce) public pure returns (bytes32);
+```
+**Parameters**
+
+|Name|Type|Description|
+|----|----|-----------|
+|`_hyperlaneDomain`|`uint32`|The hyperlane of the origin|
+|`_nonce`|`uint224`|The nonce of the adapter on the origin|
+
+
+## Events
+### BridgedToken
+Emits the nonce of the Portal message when a token is bridged.
+
+
+```solidity
+event BridgedToken(uint256 nonce, uint64 portalSequence, uint32 destination);
+```
+
+### DomainAdded
+Emitted when the Hyperlane domain to Wormhole domain mapping is updated.
+
+
+```solidity
+event DomainAdded(uint32 indexed hyperlaneDomain, uint32 wormholeDomain);
+```
+

package/docs/src/contracts/middleware/liquidity-layer/adapters/README.md

@@ -0,0 +1,5 @@
+
+
+# Contents
+- [CircleBridgeAdapter](CircleBridgeAdapter.sol/contract.CircleBridgeAdapter.md)
+- [PortalAdapter](PortalAdapter.sol/contract.PortalAdapter.md)

package/docs/src/contracts/middleware/liquidity-layer/interfaces/ILiquidityLayerAdapter.sol/interface.ILiquidityLayerAdapter.md

@@ -0,0 +1,23 @@
+# ILiquidityLayerAdapter
+[Git Source](https://github.com/hyperlane-xyz/hyperlane-monorepo/blob/a5209dbd9b0f5eb34e0bc9df2ba157dda2b454d3/contracts/middleware/liquidity-layer/interfaces/ILiquidityLayerAdapter.sol)
+
+
+## Functions
+### sendTokens
+
+
+```solidity
+function sendTokens(uint32 _destinationDomain, bytes32 _recipientAddress, address _token, uint256 _amount)
+    external
+    returns (bytes memory _adapterData);
+```
+
+### receiveTokens
+
+
+```solidity
+function receiveTokens(uint32 _originDomain, address _recipientAddress, uint256 _amount, bytes calldata _adapterData)
+    external
+    returns (address, uint256);
+```
+

package/docs/src/contracts/middleware/liquidity-layer/interfaces/README.md

@@ -0,0 +1,6 @@
+
+
+# Contents
+- [circle](/contracts/middleware/liquidity-layer/interfaces/circle)
+- [portal](/contracts/middleware/liquidity-layer/interfaces/portal)
+- [ILiquidityLayerAdapter](ILiquidityLayerAdapter.sol/interface.ILiquidityLayerAdapter.md)

package/docs/src/contracts/middleware/liquidity-layer/interfaces/circle/ICircleMessageTransmitter.sol/interface.ICircleMessageTransmitter.md

@@ -0,0 +1,54 @@
+# ICircleMessageTransmitter
+[Git Source](https://github.com/hyperlane-xyz/hyperlane-monorepo/blob/a5209dbd9b0f5eb34e0bc9df2ba157dda2b454d3/contracts/middleware/liquidity-layer/interfaces/circle/ICircleMessageTransmitter.sol)
+
+
+## Functions
+### receiveMessage
+
+Receive a message. Messages with a given nonce
+can only be broadcast once for a (sourceDomain, destinationDomain)
+pair. The message body of a valid message is passed to the
+specified recipient for further processing.
+
+*Attestation format:
+A valid attestation is the concatenated 65-byte signature(s) of exactly
+`thresholdSignature` signatures, in increasing order of attester address.
+If the attester addresses recovered from signatures are not in
+increasing order, signature verification will fail.***
+If incorrect number of signatures or duplicate signatures are supplied,
+signature verification will fail.
+Message format:
+Field Bytes Type Index
+version 4 uint32 0
+sourceDomain 4 uint32 4
+destinationDomain 4 uint32 8
+nonce 8 uint64 12
+sender 32 bytes32 20
+recipient 32 bytes32 52
+messageBody dynamic bytes 84*
+
+
+```solidity
+function receiveMessage(bytes memory _message, bytes calldata _attestation) external returns (bool success);
+```
+**Parameters**
+
+|Name|Type|Description|
+|----|----|-----------|
+|`_message`|`bytes`|Message bytes|
+|`_attestation`|`bytes`|Concatenated 65-byte signature(s) of `_message`, in increasing order of the attester address recovered from signatures.|
+
+**Returns**
+
+|Name|Type|Description|
+|----|----|-----------|
+|`success`|`bool`|bool, true if successful|
+
+
+### usedNonces
+
+
+```solidity
+function usedNonces(bytes32 _nonceId) external view returns (bool);
+```
+

package/docs/src/contracts/middleware/liquidity-layer/interfaces/circle/ITokenMessenger.sol/interface.ITokenMessenger.md

@@ -0,0 +1,92 @@
+# ITokenMessenger
+[Git Source](https://github.com/hyperlane-xyz/hyperlane-monorepo/blob/a5209dbd9b0f5eb34e0bc9df2ba157dda2b454d3/contracts/middleware/liquidity-layer/interfaces/circle/ITokenMessenger.sol)
+
+
+## Functions
+### depositForBurn
+
+Deposits and burns tokens from sender to be minted on destination domain.
+Emits a `DepositForBurn` event.
+
+*reverts if:
+- given burnToken is not supported
+- given destinationDomain has no TokenMessenger registered
+- transferFrom() reverts. For example, if sender's burnToken balance or approved allowance
+to this contract is less than `amount`.
+- burn() reverts. For example, if `amount` is 0.
+- MessageTransmitter returns false or reverts.*
+
+
+```solidity
+function depositForBurn(uint256 _amount, uint32 _destinationDomain, bytes32 _mintRecipient, address _burnToken)
+    external
+    returns (uint64 _nonce);
+```
+**Parameters**
+
+|Name|Type|Description|
+|----|----|-----------|
+|`_amount`|`uint256`|amount of tokens to burn|
+|`_destinationDomain`|`uint32`|destination domain (ETH = 0, AVAX = 1)|
+|`_mintRecipient`|`bytes32`|address of mint recipient on destination domain|
+|`_burnToken`|`address`|address of contract to burn deposited tokens, on local domain|
+
+**Returns**
+
+|Name|Type|Description|
+|----|----|-----------|
+|`_nonce`|`uint64`|unique nonce reserved by message|
+
+
+### depositForBurnWithCaller
+
+Deposits and burns tokens from sender to be minted on destination domain. The mint
+on the destination domain must be called by `_destinationCaller`.
+WARNING: if the `_destinationCaller` does not represent a valid address as bytes32, then it will not be possible
+to broadcast the message on the destination domain. This is an advanced feature, and the standard
+depositForBurn() should be preferred for use cases where a specific destination caller is not required.
+Emits a `DepositForBurn` event.
+
+*reverts if:
+- given destinationCaller is zero address
+- given burnToken is not supported
+- given destinationDomain has no TokenMessenger registered
+- transferFrom() reverts. For example, if sender's burnToken balance or approved allowance
+to this contract is less than `amount`.
+- burn() reverts. For example, if `amount` is 0.
+- MessageTransmitter returns false or reverts.*
+
+
+```solidity
+function depositForBurnWithCaller(
+    uint256 _amount,
+    uint32 _destinationDomain,
+    bytes32 _mintRecipient,
+    address _burnToken,
+    bytes32 _destinationCaller
+) external returns (uint64 _nonce);
+```
+**Parameters**
+
+|Name|Type|Description|
+|----|----|-----------|
+|`_amount`|`uint256`|amount of tokens to burn|
+|`_destinationDomain`|`uint32`|destination domain|
+|`_mintRecipient`|`bytes32`|address of mint recipient on destination domain|
+|`_burnToken`|`address`|address of contract to burn deposited tokens, on local domain|
+|`_destinationCaller`|`bytes32`|caller on the destination domain, as bytes32|
+
+**Returns**
+
+|Name|Type|Description|
+|----|----|-----------|
+|`_nonce`|`uint64`|unique nonce reserved by message|
+
+
+## Events
+### MessageSent
+
+```solidity
+event MessageSent(bytes message);
+```
+

package/docs/src/contracts/middleware/liquidity-layer/interfaces/circle/README.md

@@ -0,0 +1,5 @@
+
+
+# Contents
+- [ICircleMessageTransmitter](ICircleMessageTransmitter.sol/interface.ICircleMessageTransmitter.md)
+- [ITokenMessenger](ITokenMessenger.sol/interface.ITokenMessenger.md)