SponsoredCall ERC-2771
Sponsored transactions with ERC2771 authentication support
multicall
method or any other method using delegateCall()
, please read carefully the section Avoid ERC-2771-risks.@gelatonetwork/relay-sdk
v3 or contracts from the package @gelatonetwork/relay-context
v2, please follow this migration guide to migrate to the new versions.After reading this page:
- You’ll know how to use the
sponsoredCallERC2771
SDK method. This will give your user’s a gasless UX requiring a user signature. This uses the 1Balance payment method, allowing you to sponsor some/all of your user’s gas costs. - You’ll learn about how to incorporate
ERC2771Context
into your contract for_msgSender()
support. - You’ll see some code which will help you send a relay request within minutes.
Overview
The sponsoredCallERC2771
method uses both a sponsor API key and a user’s signature, like that from MetaMask, to securely sponsor gasless transactions. Payments are made via the Gelato 1Balance method.
Gelato Relay SDK has various methods for handling sponsored ERC2771 transactions. The most straightforward is sponsoredCallERC2771
, which handles both signing and sending in one step. If you need to separate these processes, other SDK methods are available.
SDK Methods
sponsoredCallERC2771
This method initiates the signing of ERC2771 requests with the provided BrowserProvider or Wallet. Once the signature is obtained, the request is forwarded to Gelato.
Arguments
request
: The body of the request intended for sending.signerOrProvider
: a valid provider connected to RPC or a signer.sponsorApiKey
: an API key used to authenticate your sponsorship.options
: an object for specifying optional parameters.
Response
taskId
: a unique task ID which can be used for tracking your request.
getSignatureDataERC2771
This method starts the signing process for ERC2771 requests using the given BrowserProvider or Signer. After capturing the signature, it returns both the signature and the message. This collected data can then be used with the sponsoredCallERC2771WithSignature method to send the request to Gelato.
Arguments
request
: this is the request body used to send a request.signerOrProvider
: a valid provider connected to RPC or a signer.type
: SponsoredCall for a sequential flow or ConcurrentSponsoredCall for a concurrent flow.
Response
struct
: EIP-712 message data.signature
: EIP-712 signature.
getDataToSignERC2771
This method provides the message data intended for external signing along with the EIP-712 typed data. After obtaining the signature, the request can be dispatched using the sponsoredCallERC2771WithSignature method.
Arguments
request
: The body of the request intended for sending.type
: SponsoredCall for a sequential flow or ConcurrentSponsoredCall for a concurrent flow.signerOrProvider
(optional): A provider needed in a sequential flow to obtain the nonce from the smart contract. If you’re providing the nonce within your request or if you’re using the concurrent flow, this parameter isn’t necessary.
Response
struct
: EIP-712 message data.typedData
: EIP-712 typed data.
sponsoredCallERC2771WithSignature
This method sends pre-signed requests to Gelato.
Arguments
struct
: EIP-712 message data returned from the signing methods.signature
: EIP-712 signature returned after signing the request.sponsorApiKey
: an API key used to authenticate your sponsorship.options
: an object for specifying optional parameters.
Response
taskId
: a unique task ID which can be used for tracking your request.
Optional Parameters
gasLimit
: the gas limit of the relay call. This effectively sets an upper price limit for the relay call.
Note: If you are using your own custom gas limit, please add a 150k gas buffer on top of the expected gas usage for the transaction. This is for the Gelato Relay execution overhead, and adding this buffer reduces your chance of the task cancelling before it is executed on-chain.
Note: If your contract has any hardcoded requirements about gas usage, please always explicitly pass the gasLimit to the SDK/API, as Gelato will not know what hardcoded gas expectations your contract has. Otherwise, your relay requests might not be executable.
retries
: the number of retries that Gelato should attempt before discarding this relay call. This can be useful if the state of the target contract is not fully known and such reverts can not be definitively avoided.
Sending a Request
As of today, we support two distinct ways of sending sponsoredCallERC2771 requests:
-
Sequentially: This approach ensures that each request is ordered and validated against the nonce stored on-chain. You have two options in this method:
- Fetch the current nonce value from the smart contract yourself and include it with your request.
- Allow the relay-sdk to fetch the nonce value for you when handling your relay request.
-
Concurrently: This method enables you to send multiple transactions simultaneously. Replay protection is achieved using a hash-based salt mechanism. Again, you have two options:
- Provide your own salt value.
- Allow the relay-sdk to generate a unique salt value for you when processing your relay request.
By default sponsoredCallERC2771 requests are using the sequential method.
Note: Concurrent ERC2771 support has been introduced in the relay-sdk version 5.1.0. Please make sure that your package is up-to-date to start using it.
Request Body
Common Parameters:
chainId
: the chain ID of the chain where the target smart contract is deployed.target
: the address of the target smart contract.data
: encoded payload data (usually a function selector plus the required arguments) used to call the required target address.user
: the address of the user’s EOA.userDeadline
: optional, the amount of time in seconds that a user is willing for the relay call to be active in the relay backend before it is dismissed.
Note: This way the user knows that if the transaction is not sent within a certain timeframe, it will expire. Without this, an adversary could pick up the transaction in the mempool and send it later. This could transfer money, or change state at a point in time which would be highly undesirable to the user.
Parameters For Sequential Requests:
isConcurrent
: false (default), optional, represents that the users’ requests are validated based on a nonce, which enforces them to be processed sequentially.userNonce
: optional, this nonce, akin to Ethereum nonces, is stored in a local mapping on the relay contracts. It serves to enforce the nonce ordering of relay calls if the user requires sequential processing. If this parameter is omitted, the relay-sdk will automatically query the current value on-chain.
Parameters For Concurrent Requests:
isConcurrent
: true, indicates that the users’ requests are validated based on a unique salt, allowing them to be processed concurrently. Replay protection is still ensured by permitting each salt value to be used only once.userSalt
: optional, this is a bytes32 hash that is used for replay protection. If the salt is not provided then relay-sdk would generate a unique value based on a random seed and a timestamp.
Example Code
For your testing, Gelato has deployed a simple contract which implements logic to increment a counter with ERC2771 support.
CounterERC2771.sol: deployed at the address 0x00172f67db60E5fA346e599cdE675f0ca213b47b
on these networks.
CounterERC2771.sol’s counter is special because it implements ERC-2771 _msgSender authentication to allow for secure whitelisting based on the identity of the original off-chain relay request originator, which has been verified using a user signature.
Furthermore, to set your trusted forwarder, you need the address for GelatoRelay1BalanceERC2771.sol that you can find here.
1. Deploy an ERC2771Context compatible contract
2. Import GelatoRelaySDK into your front-end .js project
Once we have imported the GelatoRelay class, when using ERC2771 methods, we must initialize it with the appropriate trustedForwarder. The possible configurations are:
We will need to go to the Supported Networks and check the network and the contract addresses to identify the trustedForwarder associated with our method.
In the example below, we are using the method sponsoredCallERC2771 on Sepolia, the trustedForwarder associated is 0xd8253782c45a12053594b9deB72d8e8aB2Fca54c
. We will initialize GelatoRelay with the following config:
3. Send the payload to Gelato
This is an example using Gelato’s CounterERC2771.sol which is deployed on these networks.