2023-02-10 10:36:08 -08:00
// SPDX-License-Identifier: Apache 2
pragma solidity ^ 0 . 8 . 0 ;
interface IWormholeRelayer {
2023-02-21 06:59:02 -08:00
/**
2023-02-17 15:08:44 -08:00
* @ title IWormholeRelayer
2023-02-21 06:59:02 -08:00
* @ notice Users may use this interface to have wormhole messages in their transaction
* relayed to destination contract ( s ) of their choice
* /
2023-02-17 15:08:44 -08:00
2023-02-10 10:36:08 -08:00
/**
2023-02-17 15:08:44 -08:00
* @ notice This ' send ' function emits a wormhole message that alerts the default wormhole relay provider to
2023-02-21 06:59:02 -08:00
* call the receiveWormholeMessage ( bytes [ ] memory vaas , bytes [ ] memory additionalData ) endpoint of the contract on chain ' targetChain ' and address ' targetAddress '
* with the first argument being all of the wormhole message in the current transaction that have nonce ' nonce ' ( which have additionally been encoded and signed by the Guardian set to form ' VAAs ' ) ,
2023-02-17 15:08:44 -08:00
* ( including the one emitted from this function , which can be ignored )
2023-02-21 06:59:02 -08:00
* ( these messages will be ordered in the ' vaas ' array in the order they were emitted in the source transaction )
2023-02-17 15:08:44 -08:00
* and with the second argument empty
2023-02-21 06:59:02 -08:00
*
*
2023-02-17 15:08:44 -08:00
* @ param targetChain The chain that the vaas are delivered to , in Wormhole Chain ID format
* @ param targetAddress The address ( in Wormhole 32 - byte format ) on chain ' targetChain ' of the contract to which the vaas are delivered .
* This contract must implement the IWormholeReceiver interface , which simply requires a ' receiveWormholeMessage(bytes[] memory vaas, bytes[] memory additionalData) ' endpoint
2023-02-21 06:59:02 -08:00
* @ param refundAddress The address ( in Wormhole 32 - byte format ) on chain ' targetChain ' to which any leftover funds ( that weren ' t used for target chain gas or passed into targetAddress as value) should be sent
2023-02-17 15:08:44 -08:00
* @ param maxTransactionFee The maximum amount ( denominated in source chain ( this chain ) currency ) that you wish to spend on funding gas for the target chain .
2023-02-27 15:49:38 -08:00
* If more gas is needed on the target chain than is paid for , there will be a Receiver Failure .
2023-02-17 15:08:44 -08:00
* Any unused value out of this fee will be refunded to ' refundAddress '
* If maxTransactionFee >= quoteGas ( targetChain , gasLimit , getDefaultRelayProvider ( ) ) , then as long as ' targetAddress ' ' s receiveWormholeMessage function uses at most ' gasLimit ' units of gas (and doesn ' t revert ) , the delivery will succeed
* @ param receiverValue The amount ( denominated in source chain currency ) that will be converted to target chain currency and passed into the receiveWormholeMessage endpoint as value .
2023-02-21 06:59:02 -08:00
* If receiverValue >= quoteReceiverValue ( targetChain , targetAmount , getDefaultRelayProvider ( ) ) , then at least ' targetAmount ' of targetChain currency will be passed into the ' receiveWormholeFunction ' as value .
* @ param nonce The messages to be relayed are all of the emitted wormhole messages in the current transaction that have nonce ' nonce ' .
*
* This function must be called with a payment of at least maxTransactionFee + receiverValue + one wormhole message fee .
*
2023-02-17 15:08:44 -08:00
* @ return sequence The sequence number for the emitted wormhole message , which contains encoded delivery instructions meant for the default wormhole relay provider .
* The relay provider will listen for these messages , and then execute the delivery as described .
2023-02-10 10:36:08 -08:00
* /
function send (
uint16 targetChain ,
bytes32 targetAddress ,
bytes32 refundAddress ,
uint256 maxTransactionFee ,
uint256 receiverValue ,
uint32 nonce
2023-02-10 12:33:00 -08:00
) external payable returns ( uint64 sequence ) ;
2023-02-10 10:36:08 -08:00
2023-02-17 15:08:44 -08:00
/**
* @ notice This ' Send ' struct represents a request to relay to a contract at address ' targetAddress ' on chain ' targetChain '
2023-02-21 06:59:02 -08:00
*
2023-02-17 15:08:44 -08:00
* @ custom : member targetChain The chain that the encoded + signed Wormhole messages ( VAAs ) are delivered to , in Wormhole Chain ID format
* @ custom : member targetAddress The address ( in Wormhole 32 - byte format ) on chain ' targetChain ' of the contract to which the vaas are delivered .
* This contract must implement the IWormholeReceiver interface , which simply requires a ' receiveWormholeMessage(bytes[] memory vaas, bytes[] memory additionalData) ' endpoint
2023-02-21 06:59:02 -08:00
* @ custom : member refundAddress The address ( in Wormhole 32 - byte format ) on chain ' targetChain ' to which any leftover funds ( that weren ' t used for target chain gas or passed into targetAddress as value) should be sent
2023-02-17 15:08:44 -08:00
* @ custom : member maxTransactionFee The maximum amount ( denominated in source chain ( this chain ) currency ) that you wish to spend on funding gas for the target chain .
2023-02-27 15:49:38 -08:00
* If more gas is needed on the target chain than is paid for , there will be a Receiver Failure .
2023-02-17 15:08:44 -08:00
* Any unused value out of this fee will be refunded to ' refundAddress '
* @ custom : member receiverValue The amount ( denominated in source chain currency ) that will be converted to target chain currency and passed into the receiveWormholeMessage endpoint as value .
2023-02-21 06:59:02 -08:00
* @ custom : member relayParameters This should be ' getDefaultRelayParameters() '
2023-02-17 15:08:44 -08:00
* /
struct Send {
uint16 targetChain ;
bytes32 targetAddress ;
bytes32 refundAddress ;
uint256 maxTransactionFee ;
uint256 receiverValue ;
bytes relayParameters ;
}
/**
* @ notice This ' send ' function emits a wormhole message that alerts a relay provider to
2023-02-21 06:59:02 -08:00
* call the receiveWormholeMessage ( bytes [ ] memory vaas , bytes [ ] memory additionalData ) endpoint of the contract on chain ' targetChain ' and address ' targetAddress '
* with the first argument being all of the wormhole message in the current transaction that have nonce ' nonce ' ( which have additionally been encoded and signed by the Guardian set to form ' VAAs ' ) ,
2023-02-17 15:08:44 -08:00
* ( including the one emitted from this function , which can be ignored )
2023-02-21 06:59:02 -08:00
* ( these messages will be ordered in the ' vaas ' array in the order they were emitted in the source transaction )
2023-02-17 15:08:44 -08:00
* and with the second argument empty
2023-02-21 06:59:02 -08:00
*
*
2023-02-17 15:08:44 -08:00
* @ param request The Send request containing info about the targetChain , targetAddress , refundAddress , maxTransactionFee , receiverValue , and relayParameters
2023-02-21 06:59:02 -08:00
* @ param nonce The messages to be relayed are all of the emitted wormhole messages in the current transaction that have nonce ' nonce ' .
* @ param relayProvider The address of ( the relay provider you wish to deliver the messages ) ' s contract on this source chain. This must be a contract that implements IRelayProvider.
* If request . maxTransactionFee >= quoteGas ( request . targetChain , gasLimit , relayProvider ) ,
2023-02-17 15:08:44 -08:00
* then as long as ' request.targetAddress ' ' s receiveWormholeMessage function uses at most ' gasLimit ' units of gas (and doesn ' t revert ) , the delivery will succeed
2023-02-21 06:59:02 -08:00
* If request . receiverValue >= quoteReceiverValue ( request . targetChain , targetAmount , relayProvider ) , then at least ' targetAmount ' of targetChain currency will be passed into the ' receiveWormholeFunction ' as value .
* To use the default relay provider , set this field to be getDefaultRelayProvider ( )
*
* This function must be called with a payment of at least request . maxTransactionFee + request . receiverValue + one wormhole message fee .
*
2023-02-17 15:08:44 -08:00
* @ return sequence The sequence number for the emitted wormhole message , which contains encoded delivery instructions meant for your specified relay provider .
* The relay provider will listen for these messages , and then execute the delivery as described .
* /
function send ( Send memory request , uint32 nonce , address relayProvider )
external
payable
returns ( uint64 sequence ) ;
/**
* @ notice This ' forward ' function can only be called in a IWormholeReceiver within the ' receiveWormholeMessages ' function
* It ' s purpose is to use any leftover fee from the ' maxTransactionFee ' of the current delivery to fund another delivery
2023-02-21 06:59:02 -08:00
*
* Specifically , suppose an integrator requested a Send ( with parameters oldTargetChain , oldTargetAddress , etc )
* and sets quoteGas ( oldTargetChain , gasLimit , oldRelayProvider ) as ' maxTransactionFee ' in a Send ,
2023-02-17 15:08:44 -08:00
* but during the delivery on oldTargetChain , the call to oldTargetAddress ' s receiveWormholeMessages endpoint uses only x units of gas (where x < gasLimit).
2023-02-21 06:59:02 -08:00
*
2023-02-17 15:08:44 -08:00
* Normally , ( gasLimit - x ) / gasLimit * oldMaxTransactionFee , converted to target chain currency , would be refunded to ' oldRefundAddress ' .
* However , if during execution of receiveWormholeMessage the integrator made a call to forward ,
2023-02-21 06:59:02 -08:00
*
2023-02-17 15:08:44 -08:00
* We instead would use [ ( gasLimit - x ) / gasLimit * oldMaxTransactionFee , converted to target chain currency ] + ( any additional funds passed into forward )
* to fund a new delivery ( of wormhole messages emitted during execution of oldTargetAddress ' s receiveWormholeMessages) that is requested in the call to ' forward ' .
*
* Specifically , this ' forward ' function is only callable within a delivery ( during receiveWormholeMessages ) and indicates the in - progress delivery to use any leftover funds from the current delivery to fund a new delivery
2023-02-21 06:59:02 -08:00
* or equivalently , indicates the in - progress delivery to call the receiveWormholeMessage ( bytes [ ] memory vaas , bytes [ ] memory additionalData ) endpoint of the contract on chain ' targetChain ' and address ' targetAddress '
* with the first argument being all of the wormhole message in the current transaction that have nonce ' nonce ' ( which have additionally been encoded and signed by the Guardian set to form ' VAAs ' ) ,
2023-02-17 15:08:44 -08:00
* ( which will be all of the wormhole messages emitted during the execution of oldTargetAddress ' s receiveWormholeMessages in the order that they were emitted, as well as one wormhole message *that is always at the end* that can be ignored)
* and with the second argument empty
2023-02-21 06:59:02 -08:00
*
2023-02-17 15:08:44 -08:00
* @ param targetChain The chain that the vaas are delivered to , in Wormhole Chain ID format
* @ param targetAddress The address ( in Wormhole 32 - byte format ) on chain ' targetChain ' of the contract to which the vaas are delivered .
* This contract must implement the IWormholeReceiver interface , which simply requires a ' receiveWormholeMessage(bytes[] memory vaas, bytes[] memory additionalData) ' endpoint
2023-02-21 06:59:02 -08:00
* @ param refundAddress The address ( in Wormhole 32 - byte format ) on chain ' targetChain ' to which any leftover funds ( that weren ' t used for target chain gas or passed into targetAddress as value) should be sent
2023-02-17 15:08:44 -08:00
* @ param maxTransactionFee The maximum amount ( denominated in source chain ( this chain ) currency ) that you wish to spend on funding gas for the target chain .
2023-02-27 15:49:38 -08:00
* If more gas is needed on the target chain than is paid for , there will be a Receiver Failure .
2023-02-17 15:08:44 -08:00
* Any unused value out of this fee will be refunded to ' refundAddress '
* If maxTransactionFee >= quoteGas ( targetChain , gasLimit , getDefaultRelayProvider ( ) ) , then as long as ' targetAddress ' ' s receiveWormholeMessage function uses at most ' gasLimit ' units of gas (and doesn ' t revert ) , the delivery will succeed
* @ param receiverValue The amount ( denominated in source chain currency ) that will be converted to target chain currency and passed into the receiveWormholeMessage endpoint as value .
2023-02-21 06:59:02 -08:00
* If receiverValue >= quoteReceiverValue ( targetChain , targetAmount , getDefaultRelayProvider ( ) ) , then at least ' targetAmount ' of targetChain currency will be passed into the ' receiveWormholeFunction ' as value .
* @ param nonce The messages to be relayed are all of the emitted wormhole messages in the current transaction that have nonce ' nonce ' .
*
* This forward will succeed if ( leftover funds from the current delivery that would have been refunded ) + ( any extra msg . value passed into forward ) is at least maxTransactionFee + receiverValue + one wormhole message fee .
2023-02-17 15:08:44 -08:00
* /
2023-02-10 10:36:08 -08:00
function forward (
uint16 targetChain ,
bytes32 targetAddress ,
bytes32 refundAddress ,
uint256 maxTransactionFee ,
uint256 receiverValue ,
uint32 nonce
2023-02-10 12:33:00 -08:00
) external payable ;
2023-02-10 10:36:08 -08:00
2023-02-17 15:08:44 -08:00
/**
* @ notice This ' forward ' function can only be called in a IWormholeReceiver within the ' receiveWormholeMessages ' function
* It ' s purpose is to use any leftover fee from the ' maxTransactionFee ' of the current delivery to fund another delivery
2023-02-21 06:59:02 -08:00
*
* Specifically , suppose an integrator requested a Send ( with parameters oldTargetChain , oldTargetAddress , etc )
* and sets quoteGas ( oldTargetChain , gasLimit , oldRelayProvider ) as ' maxTransactionFee ' in a Send ,
2023-02-17 15:08:44 -08:00
* but during the delivery on oldTargetChain , the call to oldTargetAddress ' s receiveWormholeMessages endpoint uses only x units of gas (where x < gasLimit).
2023-02-21 06:59:02 -08:00
*
2023-02-17 15:08:44 -08:00
* Normally , ( gasLimit - x ) / gasLimit * oldMaxTransactionFee , converted to target chain currency , would be refunded to ' oldRefundAddress ' .
* However , if during execution of receiveWormholeMessage the integrator made a call to forward ,
2023-02-21 06:59:02 -08:00
*
2023-02-17 15:08:44 -08:00
* We instead would use [ ( gasLimit - x ) / gasLimit * oldMaxTransactionFee , converted to target chain currency ] + ( any additional funds passed into forward )
* to fund a new delivery ( of wormhole messages emitted during execution of oldTargetAddress ' s receiveWormholeMessages) that is requested in the call to ' forward ' .
*
* Specifically , this ' forward ' function is only callable within a delivery ( during receiveWormholeMessages ) and indicates the in - progress delivery to use any leftover funds from the current delivery to fund a new delivery
2023-02-21 06:59:02 -08:00
* or equivalently , indicates the in - progress delivery to call the receiveWormholeMessage ( bytes [ ] memory vaas , bytes [ ] memory additionalData ) endpoint of the contract on chain ' targetChain ' and address ' targetAddress '
* with the first argument being all of the wormhole message in the current transaction that have nonce ' nonce ' ( which have additionally been encoded and signed by the Guardian set to form ' VAAs ' ) ,
2023-02-17 15:08:44 -08:00
* ( which will be all of the wormhole messages emitted during the execution of oldTargetAddress ' s receiveWormholeMessages in the order that they were emitted, as well as one wormhole message *that is always at the end* that can be ignored)
* and with the second argument empty
2023-02-21 06:59:02 -08:00
*
* @ param request The Send request containing info about the targetChain , targetAddress , refundAddress , maxTransactionFee , receiverValue , and relayParameters
2023-02-17 15:08:44 -08:00
* ( specifically , the send info that will be used to deliver all of the wormhole messages emitted during the execution of oldTargetAddress ' s receiveWormholeMessages)
2023-02-21 06:59:02 -08:00
* This forward will succeed if ( leftover funds from the current delivery that would have been refunded ) + ( any extra msg . value passed into forward ) is at least maxTransactionFee + receiverValue + one wormhole message fee .
* @ param nonce The messages to be relayed are all of the emitted wormhole messages in the current transaction ( during execution of oldTargetAddress ' s receiveWormholeMessages) that have nonce ' nonce ' .
* @ param relayProvider The address of ( the relay provider you wish to deliver the messages ) ' s contract on this source chain. This must be a contract that implements IRelayProvider.
* If request . maxTransactionFee >= quoteGas ( request . targetChain , gasLimit , relayProvider ) ,
2023-02-17 15:08:44 -08:00
* then as long as ' request.targetAddress ' ' s receiveWormholeMessage function uses at most ' gasLimit ' units of gas (and doesn ' t revert ) , the delivery will succeed
2023-02-21 06:59:02 -08:00
* If request . receiverValue >= quoteReceiverValue ( request . targetChain , targetAmount , relayProvider ) , then at least ' targetAmount ' of targetChain currency will be passed into the ' receiveWormholeFunction ' as value .
* To use the default relay provider , set this field to be getDefaultRelayProvider ( )
*
* This function must be called with a payment of at least request . maxTransactionFee + request . receiverValue + one wormhole message fee .
2023-02-17 15:08:44 -08:00
* /
2023-02-10 10:36:08 -08:00
function forward ( Send memory request , uint32 nonce , address relayProvider ) external payable ;
2023-02-17 15:08:44 -08:00
/**
* @ notice This ' ResendByTx ' struct represents a request to resend an array of messages that have been previously requested to be sent
2023-02-21 06:59:02 -08:00
* Specifically , if a user in transaction ' txHash ' on chain ' sourceChain ' emits many wormhole messages of nonce ' sourceNonce ' and then
2023-02-17 15:08:44 -08:00
* makes a call to ' send ' requesting these messages to be sent to ' targetAddress ' on ' targetChain ' ,
2023-02-21 06:59:02 -08:00
* then the user can request a redelivery of these wormhole messages any time in the future through a call to ' resend ' using this struct
*
2023-02-17 15:08:44 -08:00
* @ custom : member sourceChain The chain ( that the original Send was initiated from ( or equivalent , the chain that the original wormhole messages were emitted from ) .
* Important note : This does not need to be the current chain . A resend can be requested from any chain .
* @ custom : member sourceTxHash The transaction hash of the original source chain transaction that contained the original wormhole messages and the original ' Send ' request
* @ custom : member sourceNonce The nonce of the original wormhole messages and original ' Send ' request
* @ custom : member targetChain The chain that the encoded + signed Wormhole messages ( VAAs ) were originally delivered to ( and will be redelivered to ) , in Wormhole Chain ID format
2023-02-21 06:59:02 -08:00
* @ custom : member deliveryIndex If all the originally emitted wormhole messages are ordered , * including * the wormhole message emitted from the original Send request ,
* this is the ( 0 - indexed ) index of the wormhole message emitted from the original Send request . So , if originally the ' send ' request was made after the publishing of x wormhole messages ,
* deliveryIndex here would be ' x ' .
* @ custom : member multisendIndex If the ' send ' ( or forward ) function was used in the original transaction , this should be 0 . Otherwise if the multichainSend ( or multichainForward ) function was used ,
2023-02-17 15:08:44 -08:00
* then this should be the index of the specific Send request in the requests array that you wish to be redelivered
* @ custom : member newMaxTransactionFee The new maximum amount ( denominated in source chain ( this chain ) currency ) that you wish to spend on funding gas for the target chain .
2023-02-27 15:49:38 -08:00
* If more gas is needed on the target chain than is paid for , there will be a Receiver Failure .
2023-02-17 15:08:44 -08:00
* Any unused value out of this fee will be refunded to ' refundAddress '
* This must be greater than or equal to the original maxTransactionFee paid in the original request
* @ custom : member receiverValue The amount ( denominated in source chain currency ) that will be converted to target chain currency and passed into the receiveWormholeMessage endpoint as value .
* This must be greater than or equal to the original receiverValue paid in the original request
2023-02-21 06:59:02 -08:00
* @ custom : member newRelayParameters This should be ' getDefaultRelayParameters() '
2023-02-17 15:08:44 -08:00
* /
struct ResendByTx {
uint16 sourceChain ;
bytes32 sourceTxHash ;
uint32 sourceNonce ;
uint16 targetChain ;
uint8 deliveryIndex ;
uint8 multisendIndex ;
uint256 newMaxTransactionFee ;
uint256 newReceiverValue ;
bytes newRelayParameters ;
}
/**
* @ notice This ' ResendByTx ' struct represents a request to resend an array of messages that have been previously requested to be sent
2023-02-21 06:59:02 -08:00
* Specifically , if a user in transaction ' txHash ' on chain ' sourceChain ' emits many wormhole messages of nonce ' sourceNonce ' and then
2023-02-17 15:08:44 -08:00
* makes a call to ' send ' requesting these messages to be sent to ' targetAddress ' on ' targetChain ' ,
2023-02-21 06:59:02 -08:00
* then the user can request a redelivery of these wormhole messages any time in the future through a call to ' resend ' using this struct
*
2023-02-17 15:08:44 -08:00
* @ param request Information about the resend request , including the source chain and source transaction hash ,
2023-02-21 06:59:02 -08:00
* @ param relayProvider The address of ( the relay provider you wish to deliver the messages ) ' s contract on this source chain. This must be a contract that implements IRelayProvider.
2023-02-17 15:08:44 -08:00
* If the targetAddress ' s receiveWormholeMessage function uses ' gasLimit ' units of gas, then we must have newMaxTransactionFee >= quoteGasResend(targetChain, gasLimit, relayProvider)
2023-02-21 06:59:02 -08:00
*
2023-02-17 15:08:44 -08:00
* @ return sequence The sequence number for the emitted wormhole message , which contains encoded delivery instructions meant for your specified relay provider .
* The relay provider will listen for these messages , and then execute the redelivery as described
* /
2023-02-27 15:49:38 -08:00
function resend ( ResendByTx memory request , address relayProvider ) external payable returns ( uint64 sequence ) ;
2023-02-10 10:36:08 -08:00
2023-02-17 15:08:44 -08:00
/**
* @ notice This ' MultichainSend ' struct represents a collection of send requests ' requests ' and a specified relay provider ' relayProviderAddress '
2023-02-21 06:59:02 -08:00
* This struct is used to request sending the same array of transactions to many different destination contracts ( on many different chains ) ,
2023-02-17 15:08:44 -08:00
* With each request in the ' requests ' array denoting parameters for one specific destination
2023-02-21 06:59:02 -08:00
*
* @ custom : member relayProviderAddress The address of the relay provider ' s contract on this source chain. This relay provider will perform delivery of all of these Send requests.
2023-02-17 15:08:44 -08:00
* Use getDefaultRelayProvider ( ) here to use the default relay provider .
* @ custom : member requests The array of send requests , each specifying a targetAddress on a targetChain , along with information about the desired maxTransactionFee , receiverValue , refundAddress , and relayParameters
* /
struct MultichainSend {
address relayProviderAddress ;
Send [ ] requests ;
}
/**
* @ notice The multichainSend function delivers all wormhole messages in the current transaction of nonce ' nonce ' to many destinations ,
* with each destination specified in a Send struct , describing the desired targetAddress , targetChain , maxTransactionFee , receiverValue , refundAddress , and relayParameters
2023-02-21 06:59:02 -08:00
*
2023-02-17 15:08:44 -08:00
* @ param requests The MultichainSend struct , containing the array of Send requests , as well as the desired relayProviderAddress
* @ param nonce The messages to be relayed are all of the emitted wormhole messages in the current transaction that have nonce ' nonce '
2023-02-21 06:59:02 -08:00
*
* This function must be called with a payment of at least ( one wormhole message fee ) + Sum_ ( i = 0 - > requests . requests . length - 1 ) [ requests . requests [ i ] . maxTransactionFee + requests . requests [ i ] . receiverValue ] .
*
2023-02-17 15:08:44 -08:00
* @ return sequence The sequence number for the emitted wormhole message , which contains encoded delivery instructions meant for the default wormhole relay provider .
* The relay provider will listen for these messages , and then execute the delivery as described
* /
2023-02-21 06:59:02 -08:00
function multichainSend ( MultichainSend memory requests , uint32 nonce ) external payable returns ( uint64 sequence ) ;
2023-02-10 10:36:08 -08:00
/**
2023-02-17 15:08:44 -08:00
* @ notice The multichainForward function can only be called in a IWormholeReceiver within the ' receiveWormholeMessages ' function
* It ' s purpose is to use any leftover fee from the ' maxTransactionFee ' of the current delivery to fund another delivery, specifically a multichain delivery to many destinations
* See the description of ' forward ' for further explanation of what a forward is .
* multichainForward provides the same functionality of forward , while additionally allowing the same array of wormhole messages to be sent to many destinations
2023-02-21 06:59:02 -08:00
*
* Let LEFTOVER_VALUE = ( leftover funds from the current delivery that would have been refunded ) + ( any extra msg . value passed into forward )
* and let NEEDED_VALUE = ( one wormhole message fee ) + Sum_ ( i = 0 - > requests . requests . length - 1 ) [ requests . requests [ i ] . maxTransactionFee + requests . requests [ i ] . receiverValue ] .
2023-02-17 15:08:44 -08:00
* The multichainForward will succeed if LEFTOVER_VALUE >= NEEDED_VALUE
2023-02-21 06:59:02 -08:00
*
2023-02-27 11:32:57 -08:00
* note : If LEFTOVER_VALUE > NEEDED_VALUE , then the maxTransactionFee of the first request in the array of sends will be incremented by ' LEFTOVER_VALUE - NEEDED_VALUE '
*
2023-02-17 15:08:44 -08:00
* @ param requests The MultichainSend struct , containing the array of Send requests , as well as the desired relayProviderAddress
* @ param nonce The messages to be relayed are all of the emitted wormhole messages in the current transaction that have nonce ' nonce '
2023-02-21 06:59:02 -08:00
*
2023-02-10 10:36:08 -08:00
* /
2023-02-27 11:32:57 -08:00
function multichainForward ( MultichainSend memory requests , uint32 nonce ) external payable ;
2023-02-10 10:36:08 -08:00
2023-02-17 15:08:44 -08:00
/**
* @ notice quoteGas tells you how much maxTransactionFee ( denominated in current ( source ) chain currency ) must be in order to fund a call to
* receiveWormholeMessages on a contract on chain ' targetChain ' that uses ' gasLimit ' units of gas
2023-02-21 06:59:02 -08:00
*
* Specifically , for a Send ' request ' ,
2023-02-17 15:08:44 -08:00
* If ' request.targetAddress ' ' s receiveWormholeMessage function uses ' gasLimit ' units of gas,
* then we must have request . maxTransactionFee >= quoteGas ( request . targetChain , gasLimit , relayProvider )
2023-02-21 06:59:02 -08:00
*
2023-02-17 15:08:44 -08:00
* @ param targetChain the target chain that you wish to use gas on
* @ param gasLimit the amount of gas you wish to use
2023-02-21 06:59:02 -08:00
* @ param relayProvider The address of ( the relay provider you wish to deliver the messages ) ' s contract on this source chain. This must be a contract that implements IRelayProvider.
*
2023-02-17 15:08:44 -08:00
* @ return maxTransactionFee The ' maxTransactionFee ' you pass into your request ( to relay messages to ' targetChain ' and use ' gasLimit ' units of gas ) must be at least this amount
2023-02-21 06:59:02 -08:00
* /
2023-02-10 10:36:08 -08:00
function quoteGas ( uint16 targetChain , uint32 gasLimit , address relayProvider )
external
pure
returns ( uint256 maxTransactionFee ) ;
2023-02-17 15:08:44 -08:00
/**
* @ notice quoteGasResend tells you how much maxTransactionFee ( denominated in current ( source ) chain currency ) must be in order to fund a * resend * call to
* receiveWormholeMessages on a contract on chain ' targetChain ' that uses ' gasLimit ' units of gas
2023-02-21 06:59:02 -08:00
*
* Specifically , for a ResendByTx ' request ' ,
2023-02-17 15:08:44 -08:00
* If ' request.targetAddress ' ' s receiveWormholeMessage function uses ' gasLimit ' units of gas,
* then we must have request . maxTransactionFee >= quoteGasResend ( request . targetChain , gasLimit , relayProvider )
2023-02-21 06:59:02 -08:00
*
2023-02-17 15:08:44 -08:00
* @ param targetChain the target chain that you wish to use gas on
* @ param gasLimit the amount of gas you wish to use
2023-02-21 06:59:02 -08:00
* @ param relayProvider The address of ( the relay provider you wish to deliver the messages ) ' s contract on this source chain. This must be a contract that implements IRelayProvider.
*
2023-02-17 15:08:44 -08:00
* @ return maxTransactionFee The ' maxTransactionFee ' you pass into your resend request ( to relay messages to ' targetChain ' and use ' gasLimit ' units of gas ) must be at least this amount
* /
2023-02-10 10:36:08 -08:00
function quoteGasResend ( uint16 targetChain , uint32 gasLimit , address relayProvider )
external
pure
returns ( uint256 maxTransactionFee ) ;
2023-02-17 15:08:44 -08:00
/**
2023-02-21 06:59:02 -08:00
* @ notice quoteReceiverValue tells you how much receiverValue ( denominated in current ( source ) chain currency ) must be
2023-02-17 15:08:44 -08:00
* in order for the relayer to pass in ' targetAmount ' as msg value when calling receiveWormholeMessages .
2023-02-21 06:59:02 -08:00
*
* Specifically , for a send ' request ' ,
2023-02-17 15:08:44 -08:00
* In order for ' request.targetAddress ' ' s receiveWormholeMessage function to be called with ' targetAmount ' of value,
* then we must have request . receiverValue >= quoteReceiverValue ( request . targetChain , targetAmount , relayProvider )
2023-02-21 06:59:02 -08:00
*
2023-02-17 15:08:44 -08:00
* @ param targetChain the target chain that you wish to receive value on
* @ param targetAmount the amount of value you wish to be passed into receiveWormholeMessages
2023-02-21 06:59:02 -08:00
* @ param relayProvider The address of ( the relay provider you wish to deliver the messages ) ' s contract on this source chain. This must be a contract that implements IRelayProvider.
*
2023-02-17 15:08:44 -08:00
* @ return receiverValue The ' receiverValue ' you pass into your send request ( to relay messages to ' targetChain ' with ' targetAmount ' of value ) must be at least this amount
* /
2023-02-10 10:36:08 -08:00
function quoteReceiverValue ( uint16 targetChain , uint256 targetAmount , address relayProvider )
external
pure
2023-02-17 15:08:44 -08:00
returns ( uint256 receiverValue ) ;
2023-02-10 10:36:08 -08:00
2023-02-17 15:08:44 -08:00
/**
* @ notice Helper function that converts an EVM address to wormhole format
* @ param addr ( EVM 20 - byte address )
* @ return whFormat ( 32 - byte address in Wormhole format )
* /
function toWormholeFormat ( address addr ) external pure returns ( bytes32 whFormat ) ;
2023-02-10 10:36:08 -08:00
/**
2023-02-17 15:08:44 -08:00
* @ notice Helper function that converts an Wormhole format ( 32 - byte ) address to the EVM ' address ' 20 - byte format
* @ param whFormatAddress ( 32 - byte address in Wormhole format )
* @ return addr ( EVM 20 - byte address )
2023-02-10 10:36:08 -08:00
* /
2023-02-17 15:08:44 -08:00
function fromWormholeFormat ( bytes32 whFormatAddress ) external pure returns ( address addr ) ;
2023-02-10 10:36:08 -08:00
2023-02-17 15:08:44 -08:00
/**
* @ notice Returns the address of the current default relay provider
2023-02-21 06:59:02 -08:00
* @ return relayProvider The address of ( the default relay provider ) ' s contract on this source chain. This must be a contract that implements IRelayProvider.
2023-02-17 15:08:44 -08:00
* /
function getDefaultRelayProvider ( ) external view returns ( address relayProvider ) ;
/**
* @ notice Returns default relay parameters
* @ return relayParams default relay parameters
* /
function getDefaultRelayParams ( ) external pure returns ( bytes memory relayParams ) ;
2023-02-10 10:36:08 -08:00
2023-02-27 11:32:57 -08:00
error FundsTooMuch ( uint8 multisendIndex ) ; // (maxTransactionFee, converted to target chain currency) + (receiverValue, converted to target chain currency) is greater than what your chosen relay provider allows
error MaxTransactionFeeNotEnough ( uint8 multisendIndex ) ; // maxTransactionFee is less than the minimum needed by your chosen relay provider
2023-02-21 06:59:02 -08:00
error MsgValueTooLow ( ) ; // msg.value is too low
2023-02-17 15:08:44 -08:00
// Specifically, (msg.value) + (any leftover funds if this is a forward) is less than (maxTransactionFee + receiverValue), summed over all of your requests if this is a multichainSend/multichainForward
error NonceIsZero ( ) ; // Nonce cannot be 0
2023-02-27 11:32:57 -08:00
error NoDeliveryInProgress ( ) ; // Forwards can only be requested within execution of 'receiveWormholeMessages', or when a delivery is in progress
2023-02-17 15:08:44 -08:00
error MultipleForwardsRequested ( ) ; // Only one forward can be requested in a transaction
2023-02-27 11:32:57 -08:00
error ForwardRequestFromWrongAddress ( ) ; // A forward was requested from an address that is not the 'targetAddress' of the original delivery
2023-02-17 15:08:44 -08:00
error RelayProviderDoesNotSupportTargetChain ( ) ; // Your relay provider does not support the target chain you specified
2023-02-10 10:36:08 -08:00
}