# IRelayHub
The RelayHub interface
The implementation of this interface provides all the information the GSN client needs to
create a valid RelayRequest and also serves as an entry point for such requests.
The RelayHub also handles all the related financial records and hold the balances of participants.
The Paymasters keep their Ether deposited in the RelayHub in order to pay for the RelayRequests that thay choose
to pay for, and Relay Servers keep their earned Ether in the RelayHub until they choose to withdraw()
The RelayHub on each supported network only needs a single instance and there is usually no need for dApp
developers or Relay Server operators to redeploy, reimplement, modify or override the RelayHub.
# Functions
# addRelayWorkers(address[] newRelayWorkers)
(external)
Add new worker addresses controlled by the sender who must be a staked Relay Manager address.
Emits a RelayWorkersAdded event.
This function can be called multiple times, emitting new events.
# onRelayServerRegistered(address relayManager)
(external)
The RelayRegistrar callback to notify the RelayHub that this relayManager has updated registration.
# depositFor(address target)
(external)
Deposits ether for a Paymaster, so that it can and pay for relayed transactions.
⚠️ Warning ⚠️ Unused balance can only be withdrawn by the holder itself, by calling withdraw.
Emits a Deposited event.
# withdraw(address payable dest, uint256 amount)
(external)
Withdraws from an account's balance, sending it back to the caller.
Relay Managers call this to retrieve their revenue, and Paymasters can also use it to reduce their funding.
Emits a Withdrawn event.
# withdrawMultiple(address payable[] dest, uint256[] amount)
(external)
Withdraws from an account's balance, sending funds to multiple provided addresses.
Relay Managers call this to retrieve their revenue, and Paymasters can also use it to reduce their funding.
Emits a Withdrawn event for each destination.
# relayCall(string domainSeparatorName, uint256 maxAcceptanceBudget, struct GsnTypes.RelayRequest relayRequest, bytes signature, bytes approvalData)
→ bool paymasterAccepted, uint256 charge, enum IRelayHub.RelayCallStatus status, bytes returnValue (external)
Relays a transaction. For this to succeed, multiple conditions must be met:
Paymaster'spreRelayCallmethod must succeed and not revert.- the
msg.sendermust be a registered Relay Worker that the user signed to use. - the transaction's gas fees must be equal or larger than the ones that were signed by the sender.
- the transaction must have enough gas to run all internal transactions if they use all gas available to them.
- the
Paymastermust have enough balance to pay the Relay Worker if all gas is spent.
If all conditions are met, the call will be relayed and the Paymaster charged.
domainSeparatorName: The name of the Domain Separator used to verify the EIP-712 signature
maxAcceptanceBudget: The maximum valid value for paymaster.getGasLimits().acceptanceBudget to return.
relayRequest: All details of the requested relayed call.
signature: The client's EIP-712 signature over the relayRequest struct.
approvalData: The dapp-specific data forwarded to the Paymaster's preRelayedCall method.
This value is not verified by the RelayHub in any way.
As an example, it can be used to pass some kind of a third-party signature to the Paymaster for verification.
Emits a TransactionRelayed event regardless of whether the transaction succeeded or failed.
# penalize(address relayWorker, address payable beneficiary)
(external)
In case the Relay Worker has been found to be in violation of some rules by the Penalizer contract,
the Penalizer will call this method to execute a penalization.
The RelayHub will look up the Relay Manager of the given Relay Worker and will forward the call to
the StakeManager contract. The RelayHub does not perform the actual penalization either.
relayWorker: The address of the Relay Worker that committed a penalizable offense.
beneficiary: The address that called the Penalizer and will receive a reward for it.
# setConfiguration(struct IRelayHub.RelayHubConfig _config)
(external)
Sets or changes the configuration of this RelayHub.
_config: The new configuration.
# setMinimumStakes(contract IERC20[] token, uint256[] minimumStake)
(external)
Sets or changes the minimum amount of a given token that needs to be staked so that the Relay Manager
is considered to be 'staked' by this RelayHub. Zero value means this token is not allowed for staking.
token: An array of addresses of ERC-20 compatible tokens.
minimumStake: An array of minimal amounts necessary for a corresponding token, in wei.
# deprecateHub(uint256 _deprecationTime)
(external)
Deprecate hub by reverting all incoming relayCall() calls starting from a given timestamp
_deprecationTime: The timestamp in seconds after which the RelayHub stops serving transactions.
# escheatAbandonedRelayBalance(address relayManager)
(external)
@notice
# calculateCharge(uint256 gasUsed, struct GsnTypes.RelayData relayData)
→ uint256 (external)
The fee is expressed as a base fee in wei plus percentage of the actual charge. For example, a value '40' stands for a 40% fee, so the recipient will be charged for 1.4 times the spent amount.
gasUsed: An amount of gas used by the transaction.
relayData: The details of a transaction signed by the sender.
# Return values
calculated charge, in wei.
# calculateDevCharge(uint256 charge)
→ uint256 (external)
The fee is expressed as a percentage of the actual charge.
For example, a value '40' stands for a 40% fee, so the Relay Manager will only get 60% of the charge.
charge: The amount of Ether in wei the Paymaster will be charged for this transaction.
# Return values
calculated devFee, in wei.
# getConfiguration()
→ struct IRelayHub.RelayHubConfig config (external)
# Return values
The configuration of the RelayHub.
# getMinimumStakePerToken(contract IERC20 token)
→ uint256 (external)
token: An address of an ERC-20 compatible tokens.
# Return values
minimum amount of a given token that needs to be staked so that the Relay Manager
is considered to be 'staked' by this RelayHub. Zero value means this token is not allowed for staking.
# getWorkerManager(address worker)
→ address (external)
worker: An address of the Relay Worker.
# Return values
address of its Relay Manager.
# getWorkerCount(address manager)
→ uint256 (external)
manager: An address of the Relay Manager.
# Return values
count of Relay Workers associated with this Relay Manager.
# balanceOf(address target)
→ uint256 (external)
# Return values
account's balance. It can be either a deposit of a Paymaster, or a revenue of a Relay Manager.
# getStakeManager()
→ contract IStakeManager (external)
# Return values
StakeManager address for this RelayHub.
# getPenalizer()
→ address (external)
# Return values
Penalizer address for this RelayHub.
# getRelayRegistrar()
→ address (external)
# Return values
RelayRegistrar address for this RelayHub.
# getBatchGateway()
→ address (external)
# Return values
BatchGateway address for this RelayHub.
# verifyRelayManagerStaked(address relayManager)
(external)
Uses StakeManager to decide if the Relay Manager can be considered staked or not.
Returns if the stake's token, amount and delay satisfy all requirements, reverts otherwise.
# isRelayEscheatable(address relayManager)
→ bool (external)
Uses StakeManager to check if the Relay Manager can be considered abandoned or not.
Returns true if the stake's abandonment time is in the past including the escheatment delay, false otherwise.
# isDeprecated()
→ bool (external)
# Return values
the RelayHub is deprecated, false it it is not deprecated and can serve transactions.
# getDeprecationTime()
→ uint256 (external)
# Return values
timestamp from which the hub no longer allows relaying calls.
# getCreationBlock()
→ uint256 (external)
# Return values
block number in which the contract has been deployed.
# versionHub()
→ string (external)
# Return values
SemVer-compliant version of the RelayHub contract.
# aggregateGasleft()
→ uint256 (external)
# Return values
total measurable amount of gas left to current execution. Same as 'gasleft()' for pure EVMs.
# Events
# RelayHubConfigured(struct IRelayHub.RelayHubConfig config)
Emitted when a configuration of the RelayHub is changed
# RelayWorkersAdded(address relayManager, address[] newRelayWorkers, uint256 workersCount)
Emitted when relays are added by a relayManager
# Withdrawn(address account, address dest, uint256 amount)
Emitted when an account withdraws funds from the RelayHub.
# Deposited(address paymaster, address from, uint256 amount)
Emitted when depositFor is called, including the amount and account that was funded.
# StakingTokenDataChanged(address token, uint256 minimumStake)
Emitted for each token configured for staking in setMinimumStakes
# TransactionRejectedByPaymaster(address relayManager, address paymaster, bytes32 relayRequestID, address from, address to, address relayWorker, bytes4 selector, uint256 innerGasUsed, bytes reason)
Emitted when an attempt to relay a call fails and the Paymaster does not accept the transaction.
The actual relayed call was not executed, and the recipient not charged.
# TransactionRelayed(address relayManager, address relayWorker, bytes32 relayRequestID, address from, address to, address paymaster, bytes4 selector, enum IRelayHub.RelayCallStatus status, uint256 charge)
Emitted when a transaction is relayed. Note that the actual internal function call might be reverted.
The reason for a revert will be indicated in the status field of a corresponding RelayCallStatus value.
charge is the Ether value deducted from the Paymaster balance.
The amount added to the relayManager balance will be lower if there is an activated devFee in the config.
# TransactionResult(enum IRelayHub.RelayCallStatus status, bytes returnValue)
This event is emitted in case the internal function returns a value or reverts with a revert string.
# HubDeprecated(uint256 deprecationTime)
This event is emitted in case this RelayHub is deprecated and will stop serving transactions soon.
# AbandonedRelayManagerBalanceEscheated(address relayManager, uint256 balance)
This event is emitted in case a relayManager has been deemed "abandoned" for being
unresponsive for a prolonged period of time.
This event means the entire balance of the relay has been transferred to the devAddress.
# Structs
# RelayHubConfig
uint256 maxWorkerCount
uint256 gasReserve
uint256 postOverhead
uint256 gasOverhead
uint256 minimumUnstakeDelay
address devAddress
uint8 devFee
uint80 baseRelayFee
uint16 pctRelayFee