@gelatonetwork/relay-sdk
v3 or contracts from the package @gelatonetwork/relay-context
v2, please follow this migration guide to migrate to the new versions.sponsoredCallERC2771
and callWithSyncFeeERC2771
sponsoredCallERC2771
and callWithSyncFeeERC2771
in combination with ERC2771Context to achieve a gasless UX for your app, with secure user signature verificationsponsoredCallERC2771
callWithSyncFeeERC2771
sponsoredCallERC2771
, you sponsor your user’s gas fees, leveraging 1Balance for payment. In contrast, with callWithSyncFeeERC2771
, the fees are paid from the target contract.
In both instances, users are prompted to sign their transaction’s relay request using their private keys (for instance, through MetaMask). This step is crucial for security purposes. Gelato verifies on-chain that the user’s signature corresponds with the required address before forwarding the call.
When relaying a message to a target smart contract function, it’s essential for the function to authenticate the message’s origin and confirm it was forwarded through the correct relayer. Without these verifications, your target function becomes susceptible to exploitation. ERC-2771 employs sophisticated data encoding to relay the original _msgSender
from off-chain, and it guarantees that only the trustedForwarder
is capable of encoding this value. These two parameters, in tandem, safeguard against any potential misconduct, ensuring a secure transmission of information from off-chain to on-chain!
msg.sender
loses its usual informational significance. Under normal circumstances, msg.sender
would denote the user initiating the transaction; however, with off-chain relaying, we lose this valuable piece of information.
Consider this scenario: how does a target smart contract determine who can call a particular function? In this case, msg.sender
will be the relayer, but merely whitelisting this address is insufficient and still permits others using the same relayer to call your function. This situation can raise significant concerns, particularly when low-level calls are involved.
The optimal solution would be to allow the initiator of the relay call to specify an address and relay this address on-chain. The target smart contract can then authenticate a function call using this address.
The challenge then becomes: how can we successfully transmit information (a specific address) via low-level calldata from off-chain to on-chain without disrupting the calldata’s integrity?
trustedForwarder
encodes the from
address (i.e., the off-chain address) into the calldata by appending it at the end:
from
address by decoding the data in the same manner, ensuring that this message has been passed through the trustedForwarder
.
The necessary target contract function can then confidently confirm that the correct entity signed and requested this payload to be relayed, and only via a trusted forwarder - in our case, the Gelato Relay.
sponsoredCallERC2771
. Method callWithSyncFeeERC2771
works similarly.
Gelato Relay’s sponsoredCallERC2771
function encodes the user’s address, which can then be utilized by the ERC-2771 compatible target smart contract. The most relevant part, where the user address is appended to the calldata, is shown below:
_encodeERC2771Context
refers to:
sponsoredCallERC2771
. For callWithSyncFeeERC2771
please refer to the steps described here.
_msgSender()
.
trustedForwarder
variable is set in the constructor which allows for setting a trusted party that will relay your message to your target smart contract. In our case, this is GelatoRelay1BalanceERC2771.sol
which you can find in the contract addresses section.
The _msgSender()
function encapsulates the main functionality of ERC-2771, by decoding the user address from the last 20 bytes of the calldata.
In Solidity, the logic is equivalent to:
_msgSender()
function.
The function _msgData()
removes the msg.sender from the entire calldata if the contract was called by the trustedForwarder, or otherwise falls back to return the original calldata.
msg.sender
with a call to the _msgSender()
function inherited from ERC2771Context. _msgSender()
is the off-chain signer of the relay request, allowing for secure whitelisting on your target function.
GelatoRelay1BalanceERC2771.sol
as your trustedForwarder:
GelatoRelay1BalanceERC2771.sol
is immutable for security reasons. This means that once you set GelatoRelay1BalanceERC2771.sol
as your trusted forwarder, there is no way for Gelato to change the ERC2771 signature verification scheme and so you can be sure that the intended _msgSender
is correct and accessible from within your target contract.
Please refer to the contract addresses section to find out which Gelato relay address to use as a trustedForwarder. Use GelatoRelay1BalanceERC2771.sol
address for sponsoredCallERC2771
.