GSN Provider is deprecated. We are no longer developing new features nor addressing issues. Read here for more info.

API Reference

Basic Options

Multiple settings of the GSNProvider can be set at creation:

const options = { useGSN: true, fixedGasLimit: 10000 }; // Among others
new GSNProvider("http://localhost:8545", options);

These are documented below.


useGSN (bool)

Whether to send meta txs by default, or a function that receives a payload and returns whether to use a meta tx (defaults to true).


signKey (hex string)

Optional private key to sign the meta txs, using the underlying provider sign if not set.


approveFunction (function)

Optional function for generating application approval data for a transaction, and returns a bytes approval data (such as a signature) that can be checked in the recipient; receives as a parameter a single object with the properties from, to, encodedFunctionCall, txFee, gasPrice, gas, nonce, relayerAddress, relayHubAddress.


fixedGasPrice (integer|string)

Fixed gas price to use in all gsn transactions.


fixedGasLimit (integer|string)

Fixed gas limit to use in all gsn transactions.


minStake (integer)

Filters out relays with stake below this value (optional)


minDelay (integer)

Filters out relays with unstake delay below this value (optional)


verbose (bool)

Advanced Options

These are related to the relayer selection algorithm: most likely you will not need to use them.


preferredRelayer (object)

Attempt to use this relayer, falling back to the regular lookup algorithm on failure. Mandatory options are RelayServerAddress, relayUrl and transactionFee.

Sample configuration:

preferredRelayer = {
  RelayServerAddress: '0x73a652f54d5fd8273f17a28e206d47f5bd1bc06a',
  relayUrl: 'http://localhost:8090',
  transactionFee: '70',


`gasPriceFactorPercent (integer)

Percentage increase over the network gas price for gsn transactions (defaults to 20, note that you need to clear web3 default fixed gasprice for this setting to go into effect).


httpTimeout (integer)

Timeout in ms for HTTP requests to relayers (defaults to 10000).


allowedRelayNonceGap (integer)

(defaults to 3)


relayTimeoutGrace (integer)

Whenever a relayer timeouts a request, it is downscored by the client, and this penalization is reset every relayTimeoutGrace seconds (defaults to 1800, 30 mins)


`calculateRelayScore (function)

Given a relayer, must return a numeric score (the higher the better) to rank it (defaults to using the transaction fee and penalizations due to timeouts, maxes at 1000)


relayFilter (function)

Given a relayer, must return a boolean indicating whether it is elligible (defaults to using minDelay and minStake)


txfee (integer)

Forcefully use this transaction fee instead of the one advertised by the relayer (may lead to overpayment or rejections, defaults to empty)


addScoreRandomness (function)

Used for injecting randomness tie-breaking between relayers with the same score (defaults to uniform 0..1 random)

Transaction Parameters

In addition to the regular transaction parameters (from, gas, etc), the GSN provider will also accept these parameters, which will override the ones set during provider creation.

When using Truffle contracts, you must also pass one of the regular parameters. Since GSN transactions by definition carry no Ether, value is a good choice for this:

await myTruffleContract.myFunction(paramA, { useGSN: false, value: 0 });


useGSN (bool)

Same as the useGSN construction option.


txFee (integer)

Same as the txFee construction option.


approveFunction (function)

Same as the approveFunction construction option.