ERC-1613 Gas Station Network (Gas Stations Network)
Draft · Other · created 2018-11-18
Defines a decentralized relay network where users without ETH only need to sign a request, a relay node pays the gas and submits the transaction on their behalf, and costs and fees are settled from ETH that the dapp has deposited into a hub.
Why it is needed
On Ethereum, calling a contract requires paying gas fees in ETH. This means someone without ETH cannot use a dapp even if they have a wallet address, and it is hard for the dapp to grow its user base. Even if a dapp wants to cover gas fees on the user's behalf, or let the user pay through some other means such as fiat currency, there was no common way to do this. There are also users in restricted environments who cannot easily connect to the blockchain directly. This standard solves the problem without any protocol changes. A relay (a relaying node) receives the user's signed request over a public channel such as the web, pays the gas and submits it on the user's behalf, and a single hub contract trusted by everyone pays the relay's cost and fee out of the dapp's deposit. This gives relays a profit incentive, means censorship does not occur as long as even one honest relay exists, and lets misbehavior be proven and penalized on chain.
What to implement
function preRelayedCall(bytes calldata context) external returns (bytes32);: A hook called by RelayHub right before the relayed call. There is no default behavior, and reverting here only reverts the relayed call while the relay still gets compensated.function postRelayedCall(bytes calldata context, bool success, uint256 actualCharge, bytes32 preRetVal) external;: A hook called right after the relayed call that receives the success status, the estimated charge, and the return value of preRelayedCall.function stake(address relayAddress, uint256 unstakeDelay) external payable;: The relay owner locks a stake and a withdrawal waiting period against the relay address.function registerRelay(uint256 transactionFee, string calldata url) external;: The relay registers its fee rate (a multiple of gas cost) and its receiving URL with the hub.function removeRelayByOwner(address relay) external;: The owner removes the relay and starts the stake withdrawal countdown.function unstake(address relay) external;: After the waiting period has passed, the owner withdraws the stake.function depositFor(address target) external payable;: Deposits the gas fee to be used by a specific contract into the hub.function balanceOf(address target) external view returns (uint256);: Queries the contract's deposit balance held at the hub.function withdraw(uint256 amount, address payable dest) external;: Withdraws the deposit to a specified address.function getNonce(address from) external view returns (uint256);: Queries the sender's current replay-protection nonce.function canRelay(address relay, address from, address to, bytes calldata encodedFunction, uint256 transactionFee, uint256 gasPrice, uint256 gasLimit, uint256 nonce, bytes calldata signature, bytes calldata approvalData) external view returns (uint256 status, bytes memory recipientContext);: A view function that lets a relay check, free of charge, whether it will be compensated before submitting, checking as far as the recipient's acceptRelayedCall.function relayCall(address from, address to, bytes calldata encodedFunction, uint256 transactionFee, uint256 gasPrice, uint256 gasLimit, uint256 nonce, bytes calldata signature, bytes calldata approvalData) external;: The entry point through which a registered relay actually executes a user's signed request.function penalizeRepeatedNonce(bytes calldata unsignedTx1, bytes calldata signature1, bytes calldata unsignedTx2, bytes calldata signature2) external;: Submits two transactions signed with the same nonce as evidence to forfeit a dishonest relay's stake.function penalizeIllegalTransaction(bytes calldata unsignedTx, bytes calldata signature) external;: Submits a relay's illegal transaction as evidence to enforce a penalty.event RelayAdded(address indexed relay, address indexed owner, uint256 transactionFee, uint256 stake, uint256 unstakeDelay, string url);: Emitted when a relay is registered or renewed, and serves as the basis senders use to build their relay list.event RelayRemoved(address indexed relay, uint256 unstakeTime);: Emitted when a relay is removed.event CanRelayFailed(address indexed relay, address indexed from, address indexed to, bytes4 selector, uint256 reason);: Reports the status code when the recipient rejected acceptance and the relayed call was not executed.event TransactionRelayed(address indexed relay, address indexed from, address indexed to, bytes4 selector, RelayCallStatus status, uint256 charge);: Reports the result status and charge amount of the relayed call.function getGasAndDataLimits() external view returns (GasAndDataLimits memory limits);: A version 2 paymaster discloses its acceptance budget, hook gas limits, and calldata size limit.function trustedForwarder() external view returns (address);: Tells which forwarder address the paymaster trusts.function preRelayedCall(RelayRequest calldata relayRequest, bytes calldata signature, bytes calldata approvalData, uint256 maxPossibleGas) external returns (bytes memory context, bool rejectOnRecipientRevert);: In version 2, the function that decides whether to pay; the relay calls it first in view mode and then it is called again on chain. A revert means rejection.function postRelayedCall(bytes calldata context, bool success, uint256 gasUseWithoutPost, RelayData calldata relayData) external;: In version 2, this handles settlement after the relayed call. Even if this function reverts, the paymaster is still charged.
In depth
RelayHub: the system's single coordinator
RelayHub is the single registry contract trusted by every participating contract. It maintains the list of active relays, holds the ETH stake deposited by relays and the gas fee deposits prepaid by contracts, and mediates all communication between relays and contracts. It provides the receiving contract with a trustworthy real msg.sender and msg.data, and manages a per-sender nonce so the same transaction cannot be executed twice. It transfers the stake of a relay whose misbehavior has been proven to the address that submitted the evidence, keeping relays honest. A minimum size is enforced on the stake, and it can only be withdrawn after a cooldown period following deregistration of the relay. It also provides a way to check, free of charge and in advance, whether a relay will be compensated for a transaction it is about to send.
Integrating the recipient contract and the acceptance hook
In version 1, a contract that wants to receive gasless calls must inherit from RelayRecipient and use getSender() and getMessageData() instead of msg.sender and msg.data. The view function acceptRelayedCall is the key piece. Only a returned status value of 0 means acceptance; a nonzero value is interpreted as a dapp-specific error code, and values below 10 are reserved by RelayHub.canRelay. The context returned alongside it is opaque data to RelayHub and is passed unchanged to preRelayedCall and postRelayedCall, letting the recipient maintain state (such as the charge to apply) across the three calls. Examples of acceptance policies given include a trusted member whitelist, a balance ledger topped up by credit card payment, verification of an off-chain signed approvalData, and a transaction whitelist for onboarding new users. The deposit can be paid by the contract itself or by the dapp owner on its behalf, and if a problem occurs, deposits can be halted to limit damage from a bug being exploited.
The relay's compensation rules and liability
Before submitting a transaction, a relay must use the view function canRelay to check whether the recipient will pay the cost. For a transaction where acceptRelayedCall returned 0, the relay is compensated for the gas it actually used even if the recipient call reverts. The only case where a relay takes a loss is when it submits a transaction without checking, and canRelay would have returned a nonzero value. If uncompensated transactions occur, it means the recipient's acceptRelayedCall behaved inconsistently between the time of the view call and the time of execution; if this happens repeatedly, the relay blacklists that recipient and refuses service. The fee is disclosed to the hub as a multiple of the actual transaction's gas cost.
Proof of misbehavior and penalties
A relay that signs two different transactions with the same nonce has its misbehavior proven on chain. The victim submits both transactions and signatures to penalizeRepeatedNonce, and the hub forfeits the relay's stake, giving half to the submitter and sending the other half to address(0) to be burned. The burn mechanism exists to prevent a dishonest relay from penalizing itself and getting away without a net loss. An attack where a relay signs with a nonce higher than the current one to delay execution is prevented by having the sender include a max_nonce value in the request (recommended to be 2 to 3 higher than the current nonce) and rejecting any transaction outside that range. In version 2, a Penalizer contract takes over this proof logic, and to prevent the reward from being intercepted, it requires a two-step process: first committing the hash of the penalty call, then making the actual call within an expiration deadline after a block delay.
Version 2's module structure
Version 2 splits the single RelayHub into role-specific modules. RelayHub coordinates relayed calls and manages deposits and the relay registry. Forwarder verifies the EIP-712 signature and the replay-protection nonce, then forwards the call with the sender's address appended to the end of the call data, and is standardized as ERC-2771. A recipient identifies its trusted forwarder with isTrustedForwarder and reads the real sender with _msgSender(), but must not trust a forwarder it does not directly control or audit. Paymaster separates out the role that acceptRelayedCall played in version 1; a single paymaster can sponsor multiple recipients, and a recipient can switch paymasters without redeploying. StakeManager holds stakes independently of the hub, so a single stake can, once approved, back multiple RelayHub deployments. Relay identity is also split into relayManager, which holds the stake, and relayWorker, the hot key that sends transactions, so that even if the worker key is stolen or drained, the stake is not exposed.
The Paymaster's risk limits
A paymaster discloses four limits via getGasAndDataLimits. acceptanceBudget is the relay's risk ceiling: if a request is rejected within this budget, the relay bears at most that much gas, but if processing exceeds the budget, the paymaster is charged regardless of the outcome. A relay only deals with paymasters whose acceptanceBudget is within its own maxAcceptanceBudget. If rejectOnRecipientRevert is true, a revert in the recipient call is treated as a rejection, which avoids a charge, but this is only safe when you can trust that the recipient reverts quickly, since the entire judgment must complete within the acceptanceBudget. If false, a reverted recipient call is still paid for on chain just like any other call. The calldataSizeLimit and the gas limits for preRelayedCall and postRelayedCall limit the cost a single request can impose, and the paymaster is still charged even if postRelayedCall reverts. The total fee is calculated by the calculateCharge function.
Official deployments and processing track record
The source text lists the official deployment addresses. The version 1 RelayHub is deployed at the address 0xD216153c06E857cD7f72665E0aF1d7D82172F494 on Ethereum mainnet, Gnosis Chain, and Polygon alike, and the keccak256 hash of the deployed runtime bytecode is 0x917d7430793b798cc16d2231f924146cb5bd0b3df0152d31e9dcf99c7492f52c. The version 2 RelayHub is deployed on Ethereum mainnet (0x9e59Ea5333cD4f402dAc320a04fafA023fe3810D), Optimism, BNB Smart Chain, Gnosis Chain, and Polygon. As of when the source text was written, these deployments had processed over 60 million transactions combined across all chains. The network requires at least one active relay server to function.
Note on standard status
This proposal's status is Draft. Since it has not yet been finalized and the specification may still change, implementers should check the latest source text.
Things to watch out for
- A censorship attack reusing the same nonce: A relay can attempt censorship by submitting a different transaction with the same nonce instead of the one it signed for the user. The sender can call penalizeRepeatedNonce with the two transactions signed with the same nonce as evidence, receiving half the stake while the other half is burned, so the attacking relay only causes a delay of a few blocks and loses its entire stake.
- A delay attack using a higher nonce: If a relay signs with a nonce higher than the current one, execution can be delayed indefinitely until the intervening nonces are filled. The sender includes a max_nonce in the request (recommended to be 2 to 3 higher than the current nonce), and if the nonce of a received transaction is invalid, ignores that relay and sends to another relay instead, so no real delay occurs.
- Draining a relay's resources with an inconsistent acceptRelayedCall: A receiving contract can implement acceptRelayedCall inconsistently and drain a relay's resources through uncompensated transactions. If an unpaid transaction occurs, the relay detects it and blacklists that contract, so the damage a single contract can cause is limited to the cost of roughly 2 to 3 transactions, and since the attack cost is comparable to the damage, it does not scale.
- Draining a dapp's deposit through malicious users (Sybil attack): A malicious sender can repeatedly send meaningless transactions to make the recipient waste money paying relayers. Since recipient-pays calls are not meant for anonymous users, it is the dApp's responsibility to impose limits on users and block malicious ones via credit based on credit card payment, CAPTCHA, Google/Facebook login, and similar mechanisms.
- Mass registration of rogue relays: To register many untrustworthy relays in bulk to degrade availability, each relay must post a stake, which can only be withdrawn after deregistering and waiting through a long cooldown period (e.g. one month). A rogue relay only gives the sender a few seconds of delay before it is quickly blacklisted, so an attack large enough to create a noticeable delay is prohibitively expensive.