Interacting with RelayHub

There are many meta-transaction implementations out there, but the GSN has a unique detail that makes it special. At its core, a smart contract is responsible for keeping track of relayers, handling relayed transactions, charging their recipients, and generally ensuring all parties stay honest. This contract is called RelayHub, and there is a single instance of it in the whole network (you don’t need to deploy your own!). Think of it as a piece of public infrastructure, for all Ethereum users to benefit from.

This document will explain some of RelayHub 's tasks, and how they relate to the using of the GSN. See this flow diagram first, and we will try to explain what is going on in this article:

gsn flow full layered

Relay Hub

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.

Relaying Transactions

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 through the Forwarder. RelayHub and Forwarder 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 does not require your recipient to trust the RelayHub to do the right thing, as the user signature check remains in Forwarder contract. But since it is a very minimal smart contract, auditing it 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.

Receiving a Relayed Call

We’ve mentioned how the Forwarder, 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 OpenGSN 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.


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

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

Learn More

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