Running Relays and Fun and (Maybe Someday) Profit

Ori Pomerantz —


Users that rely on GSNv2 to access distributed applications (dapps) need to access relays through the Internet to get their messages to the blockchain. While any user can access any relay to communicate with any dapp, it is expected that dapp developers will contribute back to GSNv2 by running a relay or two. Also, if you buy and hold ether as an investment you might as well run a relay and earn a bit extra (see explanation)

In this article you learn how to run a relay on a cloud VM using these tools:

Behind the scenes the relay server also uses Let’s Encrypt Certificate Authority to get a certificate, but you do not need to worry about that process.

Relays as an investment

If you are going to buy and hold ether as an investment, you might as well run a GSN relay with it. Relays get reimbursed by paymasters for the gas they spend sending transactions for users, plus a little bit more. It isn’t an impressive interest rate, but it’s better than nothing and it is a risk free investment. GCP does not charge you for running a single micro instance.

When you want to get your investment back you use the same account you used to register the relay to unstake (deregister) it. You get the ether in the relay’s own account immediately, and after the unstake period, which is about a week, you also get the one ether you staked on being honest.

How much do you get paid?

When you configure the gsn-relay-config.json file later, you will see two variables, baseRelayFee and pctRelayFee. For every transaction you get paid, in addition to expenses, baseRelayFee plus the cost of the gas for the transaction times pctRelayFee.

The client code selects relays based on price. If your fees are too high, you will not get anything. Click here to see what other relays are charging.


The Relay VM

Initial Setup

First you need to set up the virtual machine (VM) that will run the relay server.

  1. Go to the GCP console.


  3. Set these parameters (accept the default for all the others):

    Heading Parameter Value

    Machine configuration

    Machine type

    e2-small (you can change to e2-micro after you finish the setup)

    Boot disk


    Debian GNU/Linux 10 (buster)


    Allow HTTP traffic



    Allow HTTPS traffic


  4. Click Create.

  5. After the VM starts, click SSH to connect to it.

  6. Download the software you need:

    sudo apt update
    sudo apt install -y wget

DNS Entry

Every relay needs a certificate for TLS. Certificates require a hostname for the server, especially considering that the IP address we are assigned by GCP changes when we shut down and restart. In this step we create the public DNS entry for the relay server.

  1. Copy the public IP address of your virtual machine.

  2. Go to Duck DNS and sign in with one of the options.

    This is just one of the options. You can use any other dynamic DNS service if you prefer.
  3. Type a host name and click add domain.

  4. Click install at the top bar and select your operating system and how you’d like to update your DNS entry. The easiest way is probably linux cron.

  5. Select your domain.

  6. Follow the directions. Both cron and curl are already installed on your VM.

  7. Ping your hostname and see that it resolves to your relay server.

The Docker Container

Now that the VM is running and has a hostname, the next step is to actually run the relay software. It runs inside a docker container.

  1. Download and open the relay configuration files.

    mkdir ~/relaydc
    cd ~/relaydc
    mkdir config
    cd config
    cd ..
  2. Edit .env:

    nano .env
  3. In .env, specify:

    Parameter Value


    Your host name from DuckDNS

  4. Press Ctrl-O and then Enter to save the modified file.

  5. Press Ctrl-X to exit.

  6. Edit config/gsn-relay-config.json:

    nano config/gsn-relay-config.json
  7. In gsn-relay-config.json, specify:

    Parameter Value


    The base fee that your relay will charge


    The percent fee that your relay will charge


    The address for the version registry on the network you are using. See this list.


    The URL to a node on the network you wish to use. If you do not know what to put here, get a free Infura account, create a project, and look at KEYS > ENDPOINTS.

  8. Press Ctrl-O and then Enter to save the modified file.

  9. Press Ctrl-X to exit.

  10. Download the docker relay, run it, and reboot the virtual machine.

    sudo docker run --rm  -e ROOT=$PWD -v /var/run/docker.sock:/var/run/docker.sock \
         -v $PWD/.env:/.env opengsn/relaydc up -d
  11. Browse to https://<your-DNS-name>/gsn1/getaddr. You should receive a JSON file with addresses and status. The ready setting should be false, because it isn’t registered with the relay hub yet.

    It can take a few minutes before everything is set up and you can get this value.

Relay Registration

Finally, we need to register the relay with the Relay Hub. This has several purposes:

  • Stake one ether on the relay’s honesty, so relays won’t try to abuse the system (for example by delaying messages)

  • Put up the initial relay budget for sending messages. The default is 2 Ether, but you can change that with --funds <amount in wei>.

  • Add the relay to the relay list so clients will know they can use it for free messages

You can use any computer for this process. For the sake of simplicify I’m going to assume you are doing it from the same VM you will use as a relay.

Here is how we do it:

  1. To actually fund the account you need the mnemonic, the twelve word passphrase, for an account that has sufficient ether. Use nano to create a file with that passphrase.

    To avoid risking your main account, you can create a dedicated address and transfer 3.001 ether to it. One ether is the stake that you lose if your relay doesn’t relay messages in a timely manner, two ethers are the initial funds for the relay, and the 0.001 is for the gas needed for the registration itself. Make sure to keep the mnemonic, you need will it at some point to unstake the relay and get back your ether (and some extra).
  2. Install node as explained here, and the yarn package.

    curl -sL | sudo bash -
    sudo apt install -y nodejs
    sudo npm install -g yarn
    1. Install the GSN package.

      yarn init -y
      yarn add @opengsn/gsn
  3. Create a file ~/menm with the twelve word mnemonic for the account you’ll use to fund the relay.

  4. Get the parameters.

    ADDR=<address of the account you'll use to fund the relay>
    cd ~
    NODE_URL=`cat relaydc/config/gsn* | awk '/ethereum/ {print $2}' | sed 's/"//g'`
    . relaydc/.env
  5. Register the relay.

    npx gsn relayer-register --network $NODE_URL \
        --relayUrl https://$HOST/gsn1 -m mnem --from $ADDR
  6. Browse to https://<your-DNS-name>/gsn1/getaddr. See that the relay is now ready. Congratulations.


Eventually you will want the ether back. To do so:

  1. Go here with your wallet (for example, MetaMask) set to the account that created the relay in the first place.

  2. Enter your RelayManagerAddress (from https://<your-dns-name>/getaddr) and click Unlock your stake.

  3. To see the block in which you’ll be able to get back your stake either open the browser’s console or run this command on the relay. Either way, look for withdrawBlock.

    sudo docker logs jsrelay_gsn_1 2>1
  4. Use https://<network name> to see the latest block, wait until it is past the withdrawal block.

  5. Go back to the unstake page and enter the RelayManagerAddress again.

  6. Click Withdraw previously unlocked stake.


In this article you learned how to create a GSNv2 relay and connect it to the network. The more relays are available, the better the performance for users who rely on GSNv2 to access dapps without spending ether.