Interacting with RelayHub

One of RelayHub 's jobs is to act as a, well, hub for all relayers: they will advertise their services on this contract, and your users will query it to find the relayer that best suits their purposes.

GSN Provider provides some tools to help in this regard: the minStake and minDelay options can be used to filter out relayers based on their staked amounts and unstake delay. For example, a high-stake relayer might be desirable for critical operations (even if its fee is higher!) to reduce the likelihood of foul play from the relayer.

Advanced options are also available for relayer selection fine tuning: preferredRelayer will let you select a default relayer, or you can use either relayFilter or calculateRelayScore to create your custom relayer selection algorithm.

The other key task RelayHub carries out is the actual relaying of transactions, the sole purpose behind this whole system.

Instead of calling a function in your contract directly, your users will request a relayer to do it for them, who will then execute RelayHub 's relayCall function. RelayHub will verify that the transaction is legitimate (protecting both users and recipients from dishonest relayers), and then call into your contract as originally requested by your user. This requires your recipient trusting RelayHub to do the right thing, but since it is a smart contract, this is as simple as reading its source code!

For the most basic validation checks (like signature verification), a failure will cause relayers to reject a relay request. Some of the checks are dynamic however, and despite the relayed call being reverted, the actual transaction will not. This is so that relayers can still be paid for the work they did.

For consistency, GSN Provider will raise exceptions when processing the receipt of such a transaction: these contain data from decoded events and will provide you with relevant information about what went wrong during the relayed call.

We’ve mentioned how the RelayHub, and not your user, is the one that actually ends up calling a function in your contract. We will refer to this as the relayed call. Your contract needs to be set up to accept relayed calls from the hub. In particular, it needs to be able to answer whether it will pay for a given relayed call, and run some bookeeping to make sure a malicious user cannot abuse it. It also needs to unwrap a relayed call in order to process it.

The OpenZeppelin Contracts library includes a number of utilities to make receiving relayed calls as easy as developing a regular Solidity contract, without needing to worry about the low level details. It also ships with two built-in strategies for managing relayed call subsidies.

One of these strategies relies on checking a trusted signature before accepting the relay request: such a signature can be easily generated using GSN Provider by passing the approveFunction paramater.

By now you may be wondering how exactly relayers charge their recipients for gas costs and service fees. The answer is simple: each recipient must have funds deposited on RelayHub in advance, and payment is automatically handled on each relayed call.

You can head to the GSN Recipient Tool to check and top-up your contracts' balance, view previous charges, or do all of this programatically using the OpenZeppelin GSN Helpers.

Recipients may withdraw their balance from the system at any point, but remember that they will not be able to receive any further relayed calls!

Take a look at the GSN Frequently Asked Questions to clarify any doubts about the system you may have.