Skip to content
Test and development helper methods and scripts for GSN
JavaScript Shell
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.
scripts Fix release script Aug 1, 2019
src Handle alternative hubs for fund recipient Aug 12, 2019
.gitignore Initial commit Jul 26, 2019
LICENSE Initial commit Jul 26, 2019 Remove relayHubAddr option from readme Aug 16, 2019
index.js Add isRelayHubDeployed and getRecipientFunds Aug 12, 2019
oz-gsn-deploy-relay-hub.js Hide verbose logs for deploy hub Aug 12, 2019
oz-gsn-fund-recipient.js Hide verbose logs for deploy hub Aug 12, 2019
oz-gsn-register-relayer.js Removes OZ helpers Aug 1, 2019
oz-gsn-run-relayer.js Fix typo in import Aug 16, 2019
oz-gsn.js Revert "Fail on unknown command" Aug 12, 2019
package-lock.json 0.1.9 Aug 12, 2019

OpenZeppelin GSN Helpers

Test and development helper methods and scripts for using the Gas Station Network. Provides methods for quickly running a relayer, deploying a relay hub, funding a recipient, or registering a relayer (the last based on fundrelay.js from tabookey-gasless).


npm install @openzeppelin/gsn-helpers


This suite has helper methods and command line scripts to:

  • Run a relayer process
  • Deploy a new relay hub
  • Register a relayer in the hub
  • Fund a recipient contract in the hub

Running the relayer binary

You can use the npx oz-gsn run-relayer command to automatically download a relayer binary for your current platform and start it. Before starting the relayer process, this command also deploys a relay hub to the current network (if there isn't one already), and then registers the relayer on it.

$ npx oz-gsn run-relayer --quiet
Deploying singleton RelayHub instance
RelayHub deployed at 0xd216153c06e857cd7f72665e0af1d7d82172f494
Downloading relayer from
Relayer downloaded to ~/.gsn/gsn-relay-v0.1.4
Starting relayer
 -EthereumNodeUrl http://localhost:8545
 -RelayHubAddress 0xd216153c06e857cd7f72665e0af1d7d82172f494
 -Port 8090
 -Url http://localhost:8090
 -GasPricePercent 0
 -Workdir /tmp/tmp-95095UJ2M2Pfw0xi
Funding GSN relay at http://localhost:8090
Will wait up to 30s for the relay to be ready
Relay is funded and ready!

You can pass in the --detach option if you want to the process to exit after the relay is ready to use. This is useful to setup an ephemeral relayer for testing purposes. The command will output the PID of the relayer subprocess, so you can kill it afterwards (see Sample testing setup below).

Usage from code

Import the relevant scripts from the gsn-helpers package, and provide a valid web3.js instance to use them. All options are optional unless noted, and default to the values listed here.

const { registerRelay, deployRelayHub, fundRecipient } = require('@openzeppelin/gsn-helpers');
const web3 = new Web3(...);

// Deploy a relay hub instance
await deployRelayHub(web3, {
  from: accounts[0]

// Download the platform-specific binary and run a relayer
await runRelayer({
  relayUrl: 'http://localhost:8090',
  workdir: process.cwd(), // defaults to a tmp dir
  devMode: true,
  ethereumNodeURL: 'http://localhost:8545',
  gasPricePercent: 0,
  port: 8090,
  quiet: true

// Register a relayer in the hub, requires the relayer process to be running
await registerRelay(web3, {
  relayUrl: 'http://localhost:8090',
  stake: ether('1'), 
  unstakeDelay: 604800, // 1 week
  funds: ether('5'),
  from: accounts[0]

// Fund a recipient
await fundRecipient(web3, {
  recipient: RECIPIENT_ADDRESS, // required
  amount: ether('1'),
  from: accounts[0]

Usage from command line

You can also run the command above from the command line directly, which is useful for setting up your development or testing environment.

$ npx oz-gsn --help
Usage: oz-gsn [options] [command]

  -V, --version     output the version number
  -h, --help        output usage information

  run-relayer       downloads and runs a relayer binary, and registers it, deploying a hub if needed
  deploy-relay-hub  deploy the singleton RelayHub instance
  register-relayer  stake for a relayer and fund it
  fund-recipient    fund a recipient contract so that it can receive relayed calls
  help [cmd]        display help for [cmd]

Sample testing setup

You can use the oz-gsn command line helpers to download the relayer binary, deploy a relay hub, spin up a relayer, and register it on your testing setup:

trap cleanup EXIT

cleanup() {
  kill $gsn_relay_server_pid


setup_gsn_relay() {
  gsn_relay_server_pid=$(npx oz-gsn run-relayer --ethereumNodeURL $ganache_url --port $relayer_port --detach --quiet)

Then, on your tests, you only need to set up a GSN provider and register any recipients:

beforeEach('setup', async function () {
  // Create web3 instance and a contract
  this.web3 = new Web3(PROVIDER_URL);
  this.accounts = await this.web3.eth.getAccounts();

  // Create recipient contract
  const Recipient = new this.web3.eth.Contract(RecipientAbi, null, { data: RecipientBytecode });
  this.recipient = await Recipient.deploy().send({ from: this.accounts[0], gas: 1e6 });

  // Register the recipient in the hub
  await fundRecipient(this.web3, { recipient: this.recipient.options.address });
  // Create gsn provider and plug it into the recipient
  const gsnProvider = new GSNProvider(PROVIDER_URL);

All transactions sent to the recipient contract instance will be sent as a meta-transaction via the GSN running locally on your workstation.

Advanced setup

If you prefer more fine-grained control over the recipient setup, or running a custom relayer binary, you can use the following setup:


relayer_running() {
  nc -z localhost "$relayer_port"

setup_gsn_relay() {
  relay_hub_addr=$(npx oz-gsn deploy-relay-hub --ethereumNodeURL $ganache_url)
  echo "Launching GSN relay server to hub $relay_hub_addr"

  ./bin/gsn-relay -DevMode -RelayHubAddress $relay_hub_addr -EthereumNodeUrl $ganache_url -Url $relayer_url &> /dev/null &

  while ! relayer_running; do
    sleep 0.1
  echo "GSN relay server launched!"

  npx oz-gsn register-relayer --ethereumNodeURL $ganache_url --relayUrl $relayer_url


The MIT License.

You can’t perform that action at this time.