Advanced configuration

GSN aims to be a generic solution to all meta-transaction needs, and provides a lot of flexibility and composability in its configuration.

Using an Ephemeral Signing Key

Usually in web-dapps, holding user private keys is delegated to browser extensions like MetaMask. This extensions inject the page with web3 objects and web3 providres.

The snippet above uses the same technique, delegating to the underlying web3.currentProvider signing of the meta-transactions to send. This will only work if the provider has an account, which is not the case if you choose not to rely on any extension, and to use public nodes, such as infura, instead.

In order to support it, the GSN provider also provides the following accountManager API:

const { RelayProvider } = require('@opengsn/gsn');
const provider = new RelayProvider(web3.currentProvider, configuration)

const keypair = provider.newAccount()



From now on, you will be able to use this keypair to sign transactions:

await myRecipient.methods.myFunction().send({ from: keypair.address, paymaster, forwarder });
It is up to you to implement safe storage of this keypair if needed. RelayProvider will not store it and it will be lost on the next page refresh.

Injecting Approval Data

The GSN protocol allows you to supply an arbitrary approveData bytes array that can be checked on the recipient contract. This allows to implement off-chain approvals that are verified on-chain: for instance, you could have your users go through a captcha, and only then sign an approval for a transaction on your backend.

To support this, the GSN Dependencies accepts an asyncApprovalData callback that receives all transaction parameters, and should return the approval data.

const asyncApprovalData = async function (relayRequest: RelayRequest) {
  return Promise.resolve('0x1234567890')
const provider = new RelayProvider(web3.currentProvider, configuration, { asyncApprovalData })


pingFilter: PingFilter

Allows filtering the relay servers by their advertised ping info.

relayFilter: RelayFilter

Allows filtering the relay servers by their advertised event info.

asyncApprove: AsyncApprove

Allows injecting custom byte array for every relayed transaction.

scoreCalculator: AsyncScoreCalculator

Allows overriding the function by which the relay scores are calculated.


relayHubAddress (string)

Address of the RelayHub.

stakeManagerAddress (string)

Address of the StakeManager.

verbose (boolean)

Verbose log mode, on/off.

preferredRelays (string[])

An array of URLs of relay servers to be attempted first. GSN will exhaust this list before attempting any other registered relays.
The relay still has to be registered with the RelayHub in order to relay transactions.

relayLookupWindowBlocks (number)

Relay Server is considered active if it has had an interaction within the last relayLookupWindowBlocks blocks.

relayTimeoutGrace (number)

If the relay server failed to respond, it will be graylisted for the relayTimeoutGrace seconds.

sliceSize (number)

RelayProvider will ping this number of relay servers simultaneously to determine the fastest relay to respond.

gasPriceFactorPercent (number)

Percent of change to the average gas price as reported by the Ethereum node you are connected to. Negative value means lower-then-average gas price.

minGasPrice (number)

RelayProvider will not try to use gas price lower than minGasPrice even if the average gas price is lower.

chainId (number)
maxRelayNonceGap (number)