API Reference

Command Line Interface

The following commands are available via the CLI:

  • deploy-relay-hub: deploys the singleton RelayHub instance.

  • run-relayer: downloads and runs a relayer binary, and registers it, deploying a RelayHub if needed.

  • register-relayer: stakes for a relayer and fund it.

  • fund-recipient: funds a recipient contract so that it can receive relayed calls.

  • balance: queries a recipient or relayer owner GSN balance.

  • withdraw: withdraws a relayer’s owner revenue.

To use a command, run:

$ npx oz-gsn <command> <options>

For example:

$ npx oz-gsn deploy-relay-hub --ethereumNodeURL http://localhost:8545
Deploying singleton RelayHub instance
RelayHub deployed at 0xd216153c06e857cd7f72665e0af1d7d82172f494

To learn about a command’s options and usage, run:

$ npx oz-gsn <command> --help

JavaScript Interface

The CLI commands are also exported as JavaScript functions.

Most functions receive an options object: these values are optional unless noted, and their defaults are listed here.


async function deployRelayHub(web3, {
  from: web3.eth.accounts[0],

Deploys a RelayHub instance.


async function runRelayer(web3, {
  relayUrl: 'http://localhost:8090',
  workdir: process.cwd(), // defaults to a tmp dir
  devMode: true,
  ethereumNodeURL: 'http://localhost:8545',
  gasPricePercent: 0,
  port: 8090,
  quiet: true,

Downloads the platform-specific binary and runs a relayer.


async function registerRelay({
  relayUrl: 'http://localhost:8090',
  stake: ether('1'),
  unstakeDelay: 604800, // 1 week
  funds: ether('5'),
  from: web3.eth.accounts[0],

Registers a relayer on RelayHub. Requires the relayer process to be running.


async function fundRecipient(web3, {
  recipient: RECIPIENT_ADDRESS, // required
  amount: ether('1'),
  from: web3.eth.accounts[0],

Funds a recipient contract.


async function balance(web3, {
  recipient: RECIPIENT_ADDRESS, // required

Queries a recipient’s or owner’s GSN balance.


async function withdraw(web3, {
  from: OWNER_ADDRESS, // required
  amount: await balance(web3, { recipient: from }),

Withdraws a relayer owner’s GSN balance.