Testing GSN Applications

A GSN-capable smart contract or web application cannot be properly tested without interacting with relayers and the RelayHub contract. While these exist on all testnets, it is often desirable to be able to perform tests on a local blockchain.

This guide will teach you how to have a slimmed-down version of the GSN on your development machine.

Deploying the RelayHub Contract

The on-chain part of the GSN cannot be stubbed or faked: the contracts will only recognize the canonical addresses.

Doing this locally however is not a complex process: head to the GSN Helpers to learn how to deploy a RelayHub instance, the core contract of the GSN, both from the terminal and programmatically.

Using the Development Provider

In addition to the RelayProvider, this package includes GSNDevProvider: a provider that also acts as a GSN relayer.

Any transactions sent through it will be signed by the sender, and relayed by another address. By default, it will register itself in the relay hub as http://localhost:{available_port}/.

The GSNDevProvider still needs RelayHub to be deployed on the network.

It requires and addresses with funds to act as the relayer owner (who will register it on the RelayHub).

const { GSNDevProvider } = require("@opengsn/gsn");

// Assuming you are running a truffle test and did not modify the Web3 yet, you can do:
const regularProvider = web3.currentProvider

const devConfig = {
    relayOwner: accounts[0],
    relayHubAddress: relayHub.address
const gsnDevProvider = new GSNDevProvider(regularProvider, devConfig);

The GSNDevProvider is used in the same way as the regular RelayProvider: transactions sent using it will go over the GSN by default.

With this setup in place, you will be able to test interactions that rely on the acceptRelayedCall, preRelayedCall, and postRelayedCall methods of your contracts. However, unlike regular relayers GSNDevProvider will never fail: this part of the testing process needs to be carried out on a real network.


In addition to the GSNConfig, the GSNDevProvider can be configured with following parameters:

relayOwner (string)

Account to be used to register and maintain the balance. Must be unlocked and hold ether.

relayWorkdir (string)

Folder to store the database of the local test relay server.

relayListenPort (number)

Port to use for the local test relay server.

relayUrl (string)

The URL to use for the local test relay server.

baseRelayFee (number)
pctRelayFee (number)
gasPriceFactor (number)
devMode (bool)