diff --git a/src/interfaces/IWormholeReceiver.sol b/src/interfaces/IWormholeReceiver.sol index 6ef7d89..d865afc 100644 --- a/src/interfaces/IWormholeReceiver.sol +++ b/src/interfaces/IWormholeReceiver.sol @@ -12,11 +12,7 @@ interface IWormholeReceiver { * * NOTE: This function should be restricted such that only the Wormhole Relayer contract can call it. * - * We also recommend that this function: - * - Stores all received `deliveryHash`s in a mapping `(bytes32 => bool)`, and - * on every call, checks that deliveryHash has not already been stored in the - * map (This is to prevent other users maliciously trying to relay the same message) - * - Checks that `sourceChain` and `sourceAddress` are indeed who + * We also recommend that this function checks that `sourceChain` and `sourceAddress` are indeed who * you expect to have requested the calling of `send` on the source chain * * The invocation of this function corresponding to the `send` request will have msg.value equal @@ -26,22 +22,24 @@ interface IWormholeReceiver { * specified by the send requester, this delivery will result in a `ReceiverFailure`. * * @param payload - an arbitrary message which was included in the delivery by the - * requester. - * @param additionalVaas - Additional VAAs which were requested to be included in this delivery. - * They are guaranteed to all be included and in the same order as was specified in the - * delivery request. + * requester. This message's signature will already have been verified (as long as msg.sender is the Wormhole Relayer contract) + * @param additionalMessages - Additional messages which were requested to be included in this delivery. + * Note: There are no contract-level guarantees that the messages in this array are what was requested + * - so any sensitive information here should be verified! + * This field can be used to perform and relay TokenBridge or CCTP transfers, and there are example + * usages of this at + * https://github.com/wormhole-foundation/hello-token + * https://github.com/wormhole-foundation/hello-cctp + * * @param sourceAddress - the (wormhole format) address on the sending chain which requested * this delivery. * @param sourceChain - the wormhole chain ID where this delivery was requested. * @param deliveryHash - the VAA hash of the deliveryVAA. * - * NOTE: These signedVaas are NOT verified by the Wormhole core contract prior to being provided - * to this call. Always make sure `parseAndVerify()` is called on the Wormhole core contract - * before trusting the content of a raw VAA, otherwise the VAA may be invalid or malicious. */ function receiveWormholeMessages( bytes memory payload, - bytes[] memory additionalVaas, + bytes[] memory additionalMessages, bytes32 sourceAddress, uint16 sourceChain, bytes32 deliveryHash diff --git a/src/interfaces/IWormholeRelayer.sol b/src/interfaces/IWormholeRelayer.sol index b0c28be..520a1cc 100644 --- a/src/interfaces/IWormholeRelayer.sol +++ b/src/interfaces/IWormholeRelayer.sol @@ -4,11 +4,11 @@ pragma solidity ^0.8.0; /** * @title WormholeRelayer - * @author - * @notice This project allows developers to build cross-chain applications powered by Wormhole without needing to + * @author + * @notice This project allows developers to build cross-chain applications powered by Wormhole without needing to * write and run their own relaying infrastructure - * - * We implement the IWormholeRelayer interface that allows users to request a delivery provider to relay a payload (and/or additional VAAs) + * + * We implement the IWormholeRelayer interface that allows users to request a delivery provider to relay a payload (and/or additional messages) * to a chain and address of their choice. */ @@ -33,29 +33,38 @@ struct MessageKey { bytes encodedKey; } - interface IWormholeRelayerBase { event SendEvent( - uint64 indexed sequence, uint256 deliveryQuote, uint256 paymentForExtraReceiverValue + uint64 indexed sequence, + uint256 deliveryQuote, + uint256 paymentForExtraReceiverValue ); - function getRegisteredWormholeRelayerContract(uint16 chainId) external view returns (bytes32); + function getRegisteredWormholeRelayerContract( + uint16 chainId + ) external view returns (bytes32); /** * @notice Returns true if a delivery has been attempted for the given deliveryHash * Note: invalid deliveries where the tx reverts are not considered attempted */ - function deliveryAttempted(bytes32 deliveryHash) external view returns (bool attempted); + function deliveryAttempted( + bytes32 deliveryHash + ) external view returns (bool attempted); /** * @notice block number at which a delivery was successfully executed */ - function deliverySuccessBlock(bytes32 deliveryHash) external view returns (uint256 blockNumber); + function deliverySuccessBlock( + bytes32 deliveryHash + ) external view returns (uint256 blockNumber); /** * @notice block number of the latest attempt to execute a delivery that failed */ - function deliveryFailureBlock(bytes32 deliveryHash) external view returns (uint256 blockNumber); + function deliveryFailureBlock( + bytes32 deliveryHash + ) external view returns (uint256 blockNumber); } /** @@ -63,21 +72,20 @@ interface IWormholeRelayerBase { * @notice The interface to request deliveries */ interface IWormholeRelayerSend is IWormholeRelayerBase { - /** * @notice Publishes an instruction for the default delivery provider - * to relay a payload to the address `targetAddress` on chain `targetChain` + * to relay a payload to the address `targetAddress` on chain `targetChain` * with gas limit `gasLimit` and `msg.value` equal to `receiverValue` - * + * * `targetAddress` must implement the IWormholeReceiver interface - * + * * This function must be called with `msg.value` equal to `quoteEVMDeliveryPrice(targetChain, receiverValue, gasLimit)` - * - * Any refunds (from leftover gas) will be paid to the delivery provider. In order to receive the refunds, use the `sendPayloadToEvm` function + * + * Any refunds (from leftover gas) will be paid to the delivery provider. In order to receive the refunds, use the `sendPayloadToEvm` function * with `refundChain` and `refundAddress` as parameters - * + * * @param targetChain in Wormhole Chain ID format - * @param targetAddress address to call on targetChain (that implements IWormholeReceiver) + * @param targetAddress address to call on targetChain (that implements IWormholeReceiver) * @param payload arbitrary bytes to pass in as parameter in call to `targetAddress` * @param receiverValue msg.value that delivery provider should pass in for call to `targetAddress` (in targetChain currency units) * @param gasLimit gas limit with which to call `targetAddress`. @@ -93,16 +101,16 @@ interface IWormholeRelayerSend is IWormholeRelayerBase { /** * @notice Publishes an instruction for the default delivery provider - * to relay a payload to the address `targetAddress` on chain `targetChain` + * to relay a payload to the address `targetAddress` on chain `targetChain` * with gas limit `gasLimit` and `msg.value` equal to `receiverValue` - * + * * Any refunds (from leftover gas) will be sent to `refundAddress` on chain `refundChain` * `targetAddress` must implement the IWormholeReceiver interface - * + * * This function must be called with `msg.value` equal to `quoteEVMDeliveryPrice(targetChain, receiverValue, gasLimit)` - * + * * @param targetChain in Wormhole Chain ID format - * @param targetAddress address to call on targetChain (that implements IWormholeReceiver) + * @param targetAddress address to call on targetChain (that implements IWormholeReceiver) * @param payload arbitrary bytes to pass in as parameter in call to `targetAddress` * @param receiverValue msg.value that delivery provider should pass in for call to `targetAddress` (in targetChain currency units) * @param gasLimit gas limit with which to call `targetAddress`. Any units of gas unused will be refunded according to the @@ -123,21 +131,21 @@ interface IWormholeRelayerSend is IWormholeRelayerBase { /** * @notice Publishes an instruction for the default delivery provider - * to relay a payload and VAAs specified by `vaaKeys` to the address `targetAddress` on chain `targetChain` + * to relay a payload and VAAs specified by `vaaKeys` to the address `targetAddress` on chain `targetChain` * with gas limit `gasLimit` and `msg.value` equal to `receiverValue` - * + * * `targetAddress` must implement the IWormholeReceiver interface - * + * * This function must be called with `msg.value` equal to `quoteEVMDeliveryPrice(targetChain, receiverValue, gasLimit)` - * - * Any refunds (from leftover gas) will be paid to the delivery provider. In order to receive the refunds, use the `sendVaasToEvm` function + * + * Any refunds (from leftover gas) will be paid to the delivery provider. In order to receive the refunds, use the `sendVaasToEvm` function * with `refundChain` and `refundAddress` as parameters - * + * * @param targetChain in Wormhole Chain ID format - * @param targetAddress address to call on targetChain (that implements IWormholeReceiver) + * @param targetAddress address to call on targetChain (that implements IWormholeReceiver) * @param payload arbitrary bytes to pass in as parameter in call to `targetAddress` * @param receiverValue msg.value that delivery provider should pass in for call to `targetAddress` (in targetChain currency units) - * @param gasLimit gas limit with which to call `targetAddress`. + * @param gasLimit gas limit with which to call `targetAddress`. * @param vaaKeys Additional VAAs to pass in as parameter in call to `targetAddress` * @return sequence sequence number of published VAA containing delivery instructions */ @@ -152,19 +160,19 @@ interface IWormholeRelayerSend is IWormholeRelayerBase { /** * @notice Publishes an instruction for the default delivery provider - * to relay a payload and VAAs specified by `vaaKeys` to the address `targetAddress` on chain `targetChain` + * to relay a payload and VAAs specified by `vaaKeys` to the address `targetAddress` on chain `targetChain` * with gas limit `gasLimit` and `msg.value` equal to `receiverValue` - * + * * Any refunds (from leftover gas) will be sent to `refundAddress` on chain `refundChain` * `targetAddress` must implement the IWormholeReceiver interface - * + * * This function must be called with `msg.value` equal to `quoteEVMDeliveryPrice(targetChain, receiverValue, gasLimit)` - * + * * @param targetChain in Wormhole Chain ID format - * @param targetAddress address to call on targetChain (that implements IWormholeReceiver) + * @param targetAddress address to call on targetChain (that implements IWormholeReceiver) * @param payload arbitrary bytes to pass in as parameter in call to `targetAddress` * @param receiverValue msg.value that delivery provider should pass in for call to `targetAddress` (in targetChain currency units) - * @param gasLimit gas limit with which to call `targetAddress`. Any units of gas unused will be refunded according to the + * @param gasLimit gas limit with which to call `targetAddress`. Any units of gas unused will be refunded according to the * `targetChainRefundPerGasUnused` rate quoted by the delivery provider * @param vaaKeys Additional VAAs to pass in as parameter in call to `targetAddress` * @param refundChain The chain to deliver any refund to, in Wormhole Chain ID format @@ -183,30 +191,30 @@ interface IWormholeRelayerSend is IWormholeRelayerBase { ) external payable returns (uint64 sequence); /** - * @notice Publishes an instruction for the delivery provider at `deliveryProviderAddress` - * to relay a payload and VAAs specified by `vaaKeys` to the address `targetAddress` on chain `targetChain` - * with gas limit `gasLimit` and `msg.value` equal to + * @notice Publishes an instruction for the delivery provider at `deliveryProviderAddress` + * to relay a payload and VAAs specified by `vaaKeys` to the address `targetAddress` on chain `targetChain` + * with gas limit `gasLimit` and `msg.value` equal to * receiverValue + (arbitrary amount that is paid for by paymentForExtraReceiverValue of this chain's wei) in targetChain wei. - * + * * Any refunds (from leftover gas) will be sent to `refundAddress` on chain `refundChain` * `targetAddress` must implement the IWormholeReceiver interface - * - * This function must be called with `msg.value` equal to + * + * This function must be called with `msg.value` equal to * quoteEVMDeliveryPrice(targetChain, receiverValue, gasLimit, deliveryProviderAddress) + paymentForExtraReceiverValue - * + * * @param targetChain in Wormhole Chain ID format - * @param targetAddress address to call on targetChain (that implements IWormholeReceiver) + * @param targetAddress address to call on targetChain (that implements IWormholeReceiver) * @param payload arbitrary bytes to pass in as parameter in call to `targetAddress` * @param receiverValue msg.value that delivery provider should pass in for call to `targetAddress` (in targetChain currency units) - * @param paymentForExtraReceiverValue amount (in current chain currency units) to spend on extra receiverValue + * @param paymentForExtraReceiverValue amount (in current chain currency units) to spend on extra receiverValue * (in addition to the `receiverValue` specified) - * @param gasLimit gas limit with which to call `targetAddress`. Any units of gas unused will be refunded according to the + * @param gasLimit gas limit with which to call `targetAddress`. Any units of gas unused will be refunded according to the * `targetChainRefundPerGasUnused` rate quoted by the delivery provider * @param refundChain The chain to deliver any refund to, in Wormhole Chain ID format * @param refundAddress The address on `refundChain` to deliver any refund to * @param deliveryProviderAddress The address of the desired delivery provider's implementation of IDeliveryProvider * @param vaaKeys Additional VAAs to pass in as parameter in call to `targetAddress` - * @param consistencyLevel Consistency level with which to publish the delivery instructions - see + * @param consistencyLevel Consistency level with which to publish the delivery instructions - see * https://book.wormhole.com/wormhole/3_coreLayerContracts.html?highlight=consistency#consistency-levels * @return sequence sequence number of published VAA containing delivery instructions */ @@ -225,33 +233,33 @@ interface IWormholeRelayerSend is IWormholeRelayerBase { ) external payable returns (uint64 sequence); /** - * @notice Publishes an instruction for the delivery provider at `deliveryProviderAddress` - * to relay a payload and external messages specified by `messageKeys` to the address `targetAddress` on chain `targetChain` - * with gas limit `gasLimit` and `msg.value` equal to + * @notice Publishes an instruction for the delivery provider at `deliveryProviderAddress` + * to relay a payload and external messages specified by `messageKeys` to the address `targetAddress` on chain `targetChain` + * with gas limit `gasLimit` and `msg.value` equal to * receiverValue + (arbitrary amount that is paid for by paymentForExtraReceiverValue of this chain's wei) in targetChain wei. - * + * * Any refunds (from leftover gas) will be sent to `refundAddress` on chain `refundChain` * `targetAddress` must implement the IWormholeReceiver interface - * - * This function must be called with `msg.value` equal to + * + * This function must be called with `msg.value` equal to * quoteEVMDeliveryPrice(targetChain, receiverValue, gasLimit, deliveryProviderAddress) + paymentForExtraReceiverValue * - * MessageKeys can specify wormhole messages (VaaKeys) or other types of messages (ex. USDC CCTP attestations). Ensure the selected - * Note: DeliveryProvider supports all the MessageKey.keyType values specified or it will not be delivered! - * + * Note: MessageKeys can specify wormhole messages (VaaKeys) or other types of messages (ex. USDC CCTP attestations). Ensure the selected + * DeliveryProvider supports all the MessageKey.keyType values specified or it will not be delivered! + * * @param targetChain in Wormhole Chain ID format - * @param targetAddress address to call on targetChain (that implements IWormholeReceiver) + * @param targetAddress address to call on targetChain (that implements IWormholeReceiver) * @param payload arbitrary bytes to pass in as parameter in call to `targetAddress` * @param receiverValue msg.value that delivery provider should pass in for call to `targetAddress` (in targetChain currency units) - * @param paymentForExtraReceiverValue amount (in current chain currency units) to spend on extra receiverValue + * @param paymentForExtraReceiverValue amount (in current chain currency units) to spend on extra receiverValue * (in addition to the `receiverValue` specified) - * @param gasLimit gas limit with which to call `targetAddress`. Any units of gas unused will be refunded according to the + * @param gasLimit gas limit with which to call `targetAddress`. Any units of gas unused will be refunded according to the * `targetChainRefundPerGasUnused` rate quoted by the delivery provider * @param refundChain The chain to deliver any refund to, in Wormhole Chain ID format * @param refundAddress The address on `refundChain` to deliver any refund to * @param deliveryProviderAddress The address of the desired delivery provider's implementation of IDeliveryProvider * @param messageKeys Additional messagess to pass in as parameter in call to `targetAddress` - * @param consistencyLevel Consistency level with which to publish the delivery instructions - see + * @param consistencyLevel Consistency level with which to publish the delivery instructions - see * https://book.wormhole.com/wormhole/3_coreLayerContracts.html?highlight=consistency#consistency-levels * @return sequence sequence number of published VAA containing delivery instructions */ @@ -268,24 +276,24 @@ interface IWormholeRelayerSend is IWormholeRelayerBase { MessageKey[] memory messageKeys, uint8 consistencyLevel ) external payable returns (uint64 sequence); - + /** - * @notice Publishes an instruction for the delivery provider at `deliveryProviderAddress` - * to relay a payload and VAAs specified by `vaaKeys` to the address `targetAddress` on chain `targetChain` - * with `msg.value` equal to + * @notice Publishes an instruction for the delivery provider at `deliveryProviderAddress` + * to relay a payload and VAAs specified by `vaaKeys` to the address `targetAddress` on chain `targetChain` + * with `msg.value` equal to * receiverValue + (arbitrary amount that is paid for by paymentForExtraReceiverValue of this chain's wei) in targetChain wei. - * + * * Any refunds (from leftover gas) will be sent to `refundAddress` on chain `refundChain` * `targetAddress` must implement the IWormholeReceiver interface - * - * This function must be called with `msg.value` equal to - * quoteDeliveryPrice(targetChain, receiverValue, encodedExecutionParameters, deliveryProviderAddress) + paymentForExtraReceiverValue - * + * + * This function must be called with `msg.value` equal to + * quoteDeliveryPrice(targetChain, receiverValue, encodedExecutionParameters, deliveryProviderAddress) + paymentForExtraReceiverValue + * * @param targetChain in Wormhole Chain ID format * @param targetAddress address to call on targetChain (that implements IWormholeReceiver), in Wormhole bytes32 format * @param payload arbitrary bytes to pass in as parameter in call to `targetAddress` * @param receiverValue msg.value that delivery provider should pass in for call to `targetAddress` (in targetChain currency units) - * @param paymentForExtraReceiverValue amount (in current chain currency units) to spend on extra receiverValue + * @param paymentForExtraReceiverValue amount (in current chain currency units) to spend on extra receiverValue * (in addition to the `receiverValue` specified) * @param encodedExecutionParameters encoded information on how to execute delivery that may impact pricing * e.g. for version EVM_V1, this is a struct that encodes the `gasLimit` with which to call `targetAddress` @@ -293,7 +301,7 @@ interface IWormholeRelayerSend is IWormholeRelayerBase { * @param refundAddress The address on `refundChain` to deliver any refund to, in Wormhole bytes32 format * @param deliveryProviderAddress The address of the desired delivery provider's implementation of IDeliveryProvider * @param vaaKeys Additional VAAs to pass in as parameter in call to `targetAddress` - * @param consistencyLevel Consistency level with which to publish the delivery instructions - see + * @param consistencyLevel Consistency level with which to publish the delivery instructions - see * https://book.wormhole.com/wormhole/3_coreLayerContracts.html?highlight=consistency#consistency-levels * @return sequence sequence number of published VAA containing delivery instructions */ @@ -312,25 +320,25 @@ interface IWormholeRelayerSend is IWormholeRelayerBase { ) external payable returns (uint64 sequence); /** - * @notice Publishes an instruction for the delivery provider at `deliveryProviderAddress` - * to relay a payload and VAAs specified by `vaaKeys` to the address `targetAddress` on chain `targetChain` - * with `msg.value` equal to + * @notice Publishes an instruction for the delivery provider at `deliveryProviderAddress` + * to relay a payload and VAAs specified by `vaaKeys` to the address `targetAddress` on chain `targetChain` + * with `msg.value` equal to * receiverValue + (arbitrary amount that is paid for by paymentForExtraReceiverValue of this chain's wei) in targetChain wei. - * + * * Any refunds (from leftover gas) will be sent to `refundAddress` on chain `refundChain` * `targetAddress` must implement the IWormholeReceiver interface - * - * This function must be called with `msg.value` equal to - * quoteDeliveryPrice(targetChain, receiverValue, encodedExecutionParameters, deliveryProviderAddress) + paymentForExtraReceiverValue * - * MessageKeys can specify wormhole messages (VaaKeys) or other types of messages (ex. USDC CCTP attestations). Ensure the selected - * Note: DeliveryProvider supports all the MessageKey.keyType values specified or it will not be delivered! - * + * This function must be called with `msg.value` equal to + * quoteDeliveryPrice(targetChain, receiverValue, encodedExecutionParameters, deliveryProviderAddress) + paymentForExtraReceiverValue + * + * Note: MessageKeys can specify wormhole messages (VaaKeys) or other types of messages (ex. USDC CCTP attestations). Ensure the selected + * DeliveryProvider supports all the MessageKey.keyType values specified or it will not be delivered! + * * @param targetChain in Wormhole Chain ID format * @param targetAddress address to call on targetChain (that implements IWormholeReceiver), in Wormhole bytes32 format * @param payload arbitrary bytes to pass in as parameter in call to `targetAddress` * @param receiverValue msg.value that delivery provider should pass in for call to `targetAddress` (in targetChain currency units) - * @param paymentForExtraReceiverValue amount (in current chain currency units) to spend on extra receiverValue + * @param paymentForExtraReceiverValue amount (in current chain currency units) to spend on extra receiverValue * (in addition to the `receiverValue` specified) * @param encodedExecutionParameters encoded information on how to execute delivery that may impact pricing * e.g. for version EVM_V1, this is a struct that encodes the `gasLimit` with which to call `targetAddress` @@ -338,7 +346,7 @@ interface IWormholeRelayerSend is IWormholeRelayerBase { * @param refundAddress The address on `refundChain` to deliver any refund to, in Wormhole bytes32 format * @param deliveryProviderAddress The address of the desired delivery provider's implementation of IDeliveryProvider * @param messageKeys Additional messagess to pass in as parameter in call to `targetAddress` - * @param consistencyLevel Consistency level with which to publish the delivery instructions - see + * @param consistencyLevel Consistency level with which to publish the delivery instructions - see * https://book.wormhole.com/wormhole/3_coreLayerContracts.html?highlight=consistency#consistency-levels * @return sequence sequence number of published VAA containing delivery instructions */ @@ -357,22 +365,22 @@ interface IWormholeRelayerSend is IWormholeRelayerBase { ) external payable returns (uint64 sequence); /** - * @notice Requests a previously published delivery instruction to be redelivered + * @notice Requests a previously published delivery instruction to be redelivered * (e.g. with a different delivery provider) * - * This function must be called with `msg.value` equal to + * This function must be called with `msg.value` equal to * quoteEVMDeliveryPrice(targetChain, newReceiverValue, newGasLimit, newDeliveryProviderAddress) - * + * * @notice *** This will only be able to succeed if the following is true ** * - newGasLimit >= gas limit of the old instruction * - newReceiverValue >= receiver value of the old instruction * - newDeliveryProvider's `targetChainRefundPerGasUnused` >= old relay provider's `targetChainRefundPerGasUnused` - * - * @param deliveryVaaKey VaaKey identifying the wormhole message containing the + * + * @param deliveryVaaKey VaaKey identifying the wormhole message containing the * previously published delivery instructions * @param targetChain The target chain that the original delivery targeted. Must match targetChain from original delivery instructions * @param newReceiverValue new msg.value that delivery provider should pass in for call to `targetAddress` (in targetChain currency units) - * @param newGasLimit gas limit with which to call `targetAddress`. Any units of gas unused will be refunded according to the + * @param newGasLimit gas limit with which to call `targetAddress`. Any units of gas unused will be refunded according to the * `targetChainRefundPerGasUnused` rate quoted by the delivery provider, to the refund chain and address specified in the original request * @param newDeliveryProviderAddress The address of the desired delivery provider's implementation of IDeliveryProvider * @return sequence sequence number of published VAA containing redelivery instructions @@ -380,7 +388,6 @@ interface IWormholeRelayerSend is IWormholeRelayerBase { * @notice *** This will only be able to succeed if the following is true ** * - newGasLimit >= gas limit of the old instruction * - newReceiverValue >= receiver value of the old instruction - * - newDeliveryProvider's `targetChainRefundPerGasUnused` >= old relay provider's `targetChainRefundPerGasUnused` */ function resendToEvm( VaaKey memory deliveryVaaKey, @@ -391,13 +398,13 @@ interface IWormholeRelayerSend is IWormholeRelayerBase { ) external payable returns (uint64 sequence); /** - * @notice Requests a previously published delivery instruction to be redelivered - * + * @notice Requests a previously published delivery instruction to be redelivered + * * - * This function must be called with `msg.value` equal to + * This function must be called with `msg.value` equal to * quoteDeliveryPrice(targetChain, newReceiverValue, newEncodedExecutionParameters, newDeliveryProviderAddress) - * - * @param deliveryVaaKey VaaKey identifying the wormhole message containing the + * + * @param deliveryVaaKey VaaKey identifying the wormhole message containing the * previously published delivery instructions * @param targetChain The target chain that the original delivery targeted. Must match targetChain from original delivery instructions * @param newReceiverValue new msg.value that delivery provider should pass in for call to `targetAddress` (in targetChain currency units) @@ -405,7 +412,7 @@ interface IWormholeRelayerSend is IWormholeRelayerBase { * e.g. for version EVM_V1, this is a struct that encodes the `gasLimit` with which to call `targetAddress` * @param newDeliveryProviderAddress The address of the desired delivery provider's implementation of IDeliveryProvider * @return sequence sequence number of published VAA containing redelivery instructions - * + * * @notice *** This will only be able to succeed if the following is true ** * - (For EVM_V1) newGasLimit >= gas limit of the old instruction * - newReceiverValue >= receiver value of the old instruction @@ -421,41 +428,59 @@ interface IWormholeRelayerSend is IWormholeRelayerBase { /** * @notice Returns the price to request a relay to chain `targetChain`, using the default delivery provider - * + * * @param targetChain in Wormhole Chain ID format * @param receiverValue msg.value that delivery provider should pass in for call to `targetAddress` (in targetChain currency units) - * @param gasLimit gas limit with which to call `targetAddress`. + * @param gasLimit gas limit with which to call `targetAddress`. * @return nativePriceQuote Price, in units of current chain currency, that the delivery provider charges to perform the relay - * @return targetChainRefundPerGasUnused amount of target chain currency that will be refunded per unit of gas unused, - * if a refundAddress is specified + * @return targetChainRefundPerGasUnused amount of target chain currency that will be refunded per unit of gas unused, + * if a refundAddress is specified. + * Note: This value can be overridden by the delivery provider on the target chain. The returned value here should be considered to be a + * promise by the delivery provider of the amount of refund per gas unused that will be returned to the refundAddress at the target chain. + * If a delivery provider decides to override, this will be visible as part of the emitted Delivery event on the target chain. */ function quoteEVMDeliveryPrice( uint16 targetChain, uint256 receiverValue, uint256 gasLimit - ) external view returns (uint256 nativePriceQuote, uint256 targetChainRefundPerGasUnused); + ) + external + view + returns ( + uint256 nativePriceQuote, + uint256 targetChainRefundPerGasUnused + ); /** * @notice Returns the price to request a relay to chain `targetChain`, using delivery provider `deliveryProviderAddress` - * + * * @param targetChain in Wormhole Chain ID format * @param receiverValue msg.value that delivery provider should pass in for call to `targetAddress` (in targetChain currency units) - * @param gasLimit gas limit with which to call `targetAddress`. + * @param gasLimit gas limit with which to call `targetAddress`. * @param deliveryProviderAddress The address of the desired delivery provider's implementation of IDeliveryProvider * @return nativePriceQuote Price, in units of current chain currency, that the delivery provider charges to perform the relay - * @return targetChainRefundPerGasUnused amount of target chain currency that will be refunded per unit of gas unused, + * @return targetChainRefundPerGasUnused amount of target chain currency that will be refunded per unit of gas unused, * if a refundAddress is specified + * Note: This value can be overridden by the delivery provider on the target chain. The returned value here should be considered to be a + * promise by the delivery provider of the amount of refund per gas unused that will be returned to the refundAddress at the target chain. + * If a delivery provider decides to override, this will be visible as part of the emitted Delivery event on the target chain. */ function quoteEVMDeliveryPrice( uint16 targetChain, uint256 receiverValue, uint256 gasLimit, address deliveryProviderAddress - ) external view returns (uint256 nativePriceQuote, uint256 targetChainRefundPerGasUnused); + ) + external + view + returns ( + uint256 nativePriceQuote, + uint256 targetChainRefundPerGasUnused + ); /** * @notice Returns the price to request a relay to chain `targetChain`, using delivery provider `deliveryProviderAddress` - * + * * @param targetChain in Wormhole Chain ID format * @param receiverValue msg.value that delivery provider should pass in for call to `targetAddress` (in targetChain currency units) * @param encodedExecutionParameters encoded information on how to execute delivery that may impact pricing @@ -464,7 +489,7 @@ interface IWormholeRelayerSend is IWormholeRelayerBase { * @return nativePriceQuote Price, in units of current chain currency, that the delivery provider charges to perform the relay * @return encodedExecutionInfo encoded information on how the delivery will be executed * e.g. for version EVM_V1, this is a struct that encodes the `gasLimit` and `targetChainRefundPerGasUnused` - * (which is the amount of target chain currency that will be refunded per unit of gas unused, + * (which is the amount of target chain currency that will be refunded per unit of gas unused, * if a refundAddress is specified) */ function quoteDeliveryPrice( @@ -472,12 +497,15 @@ interface IWormholeRelayerSend is IWormholeRelayerBase { uint256 receiverValue, bytes memory encodedExecutionParameters, address deliveryProviderAddress - ) external view returns (uint256 nativePriceQuote, bytes memory encodedExecutionInfo); + ) + external + view + returns (uint256 nativePriceQuote, bytes memory encodedExecutionInfo); /** * @notice Returns the (extra) amount of target chain currency that `targetAddress` * will be called with, if the `paymentForExtraReceiverValue` field is set to `currentChainAmount` - * + * * @param targetChain in Wormhole Chain ID format * @param currentChainAmount The value that `paymentForExtraReceiverValue` will be set to * @param deliveryProviderAddress The address of the desired delivery provider's implementation of IDeliveryProvider @@ -495,12 +523,15 @@ interface IWormholeRelayerSend is IWormholeRelayerBase { * @return deliveryProvider The address of (the default delivery provider)'s contract on this source * chain. This must be a contract that implements IDeliveryProvider. */ - function getDefaultDeliveryProvider() external view returns (address deliveryProvider); + function getDefaultDeliveryProvider() + external + view + returns (address deliveryProvider); } /** * @title IWormholeRelayerDelivery - * @notice The interface to execute deliveries. Only relevant for Delivery Providers + * @notice The interface to execute deliveries. Only relevant for Delivery Providers */ interface IWormholeRelayerDelivery is IWormholeRelayerBase { enum DeliveryStatus { @@ -513,7 +544,8 @@ interface IWormholeRelayerDelivery is IWormholeRelayerBase { REFUND_FAIL, CROSS_CHAIN_REFUND_SENT, CROSS_CHAIN_REFUND_FAIL_PROVIDER_NOT_SUPPORTED, - CROSS_CHAIN_REFUND_FAIL_NOT_ENOUGH + CROSS_CHAIN_REFUND_FAIL_NOT_ENOUGH, + NO_REFUND_REQUESTED } /** @@ -524,17 +556,17 @@ interface IWormholeRelayerDelivery is IWormholeRelayerBase { * corresponding to this delivery request * @custom:member deliveryVaaHash - The hash of the delivery VAA corresponding to this delivery * request - * @custom:member gasUsed - The amount of gas that was used to call your target contract + * @custom:member gasUsed - The amount of gas that was used to call your target contract * @custom:member status: * - RECEIVER_FAILURE, if the target contract reverts - * - SUCCESS, if the target contract doesn't revert + * - SUCCESS, if the target contract doesn't revert * @custom:member additionalStatusInfo: * - If status is SUCCESS, then this is empty. * - If status is RECEIVER_FAILURE, this is `RETURNDATA_TRUNCATION_THRESHOLD` bytes of the * return data (i.e. potentially truncated revert reason information). * @custom:member refundStatus - Result of the refund. REFUND_SUCCESS or REFUND_FAIL are for * refunds where targetChain=refundChain; the others are for targetChain!=refundChain, - * where a cross chain refund is necessary + * where a cross chain refund is necessary, or if the default code path is used where no refund is requested (NO_REFUND_REQUESTED) * @custom:member overridesInfo: * - If not an override: empty bytes array * - Otherwise: An encoded `DeliveryOverride` @@ -553,14 +585,14 @@ interface IWormholeRelayerDelivery is IWormholeRelayerBase { /** * @notice The delivery provider calls `deliver` to relay messages as described by one delivery instruction - * + * * The delivery provider must pass in the specified (by VaaKeys[]) signed wormhole messages (VAAs) from the source chain * as well as the signed wormhole message with the delivery instructions (the delivery VAA) * * The messages will be relayed to the target address (with the specified gas limit and receiver value) iff the following checks are met: * - the delivery VAA has a valid signature * - the delivery VAA's emitter is one of these WormholeRelayer contracts - * - the delivery provider passed in at least enough of this chain's currency as msg.value (enough meaning the maximum possible refund) + * - the delivery provider passed in at least enough of this chain's currency as msg.value (enough meaning the maximum possible refund) * - the instruction's target chain is this chain * - the relayed signed VAAs match the descriptions in container.messages (the VAA hashes match, or the emitter address, sequence number pair matches, depending on the description given) * @@ -597,7 +629,10 @@ error InvalidMsgValue(uint256 msgValue, uint256 totalFee); error RequestedGasLimitTooLow(); -error DeliveryProviderDoesNotSupportTargetChain(address relayer, uint16 chainId); +error DeliveryProviderDoesNotSupportTargetChain( + address relayer, + uint16 chainId +); error DeliveryProviderCannotReceivePayment(); error DeliveryProviderDoesNotSupportMessageKeyType(uint8 keyType); @@ -634,4 +669,4 @@ error InsufficientRelayerFunds(uint256 msgValue, uint256 minimum); //When a bytes32 field can't be converted into a 20 byte EVM address, because the 12 padding bytes // are non-zero (duplicated from Utils.sol) -error NotAnEvmAddress(bytes32); \ No newline at end of file +error NotAnEvmAddress(bytes32);