Version 2.2.5

# Tutorial: Running a Relay Server for Fun and Profit

# Introduction

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 Google Cloud Platform Compute (opens new window), though your can use any other hosting provider.

# Relays as an investment

Relays get reimbursed by paymasters for the gas they spend sending transactions for users, plus a transaction fee that you can configure.

Without significant transaction volume you won't necessarily get a super impressive interest rate, but you will get paid to support decentralization while taking little to no risk. Minimal resources are required to run a relay server so your costs will be low. For example, GCP does not charge you for running a single micro instance (opens new window).

When you want to get your ETH back you use the same account you used to register the relay to unstake (deregister) it. After the unstake period, which is about a week, you can request all your locked funds.

# Setting your relay server's transaction fee

When you configure the gsn-relay-config.json file later, you will see two variables, baseRelayFee and pctRelayFee. For every transaction you relay you can expect to earn baseRelayFee (wei) plus pctRelayFee% of the cost of the gas for the transaction (in addition to being reimbursed for gas used).

Note

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 relay servers are charging (opens new window).

# Directions

# 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 (opens new window).

  2. Click CREATE INSTANCE.

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

    Heading Parameter Value
    Name Select a meaningful name
    Machine configuration Machine type e2-micro
    Container Deploy a container image to this VM instance Selected
    Container image * (it does not matter, you just need to type something)
    Firewall Allow HTTPS traffic Selected
    Firewall Allow HTTP traffic Selected

  4. Click Create.

  5. Obtain a DNS entry for your service. Use your favorite DNS service, e.g. as Namecheap (opens new window), GoDaddy (opens new window), or even a free service, such as DuckDNS (opens new window)

  6. Configure the external IP of the relay in the DNS. Note: by default, public IP is "ephemeral" and might change after reboot.

# The Docker Container

Now that the VM is running and has a DNS entry, the next step is to actually run the relay software. It runs inside a docker container. You configure it using a script called rdc, which needs to run with more permissions than the GCP container-optimized OS (opens new window) allows. So you need to run it from a different computer that is authorized to SSH into the relay VM.

Note

If you don't have this permission restriction, you can also download the script directly on the vm, and run the following commands using the "local" option.

  1. On a computer that is authorized to ssh into the relay VM, download the relay configuration setup and put it on the relay VM:
    curl https://raw.githubusercontent.com/opengsn/gsn/master/dockers/relaydc/rdc > rdc
chmod +x rdc
./rdc <relay VM name> addalias
yes
  2. Open SSH to the relay VM.
  3. Download the relay configuration files.
    curl https://raw.githubusercontent.com/opengsn/gsn/master/dockers/relaydc/.env > .env
mkdir config
curl https://raw.githubusercontent.com/opengsn/gsn/master/dockers/relaydc/config-sample/gsn-relay-config.json > config/gsn-relay-config.json
  4. Edit .env:
    nano .env
  5. In .env, specify:
    Parameter Value
    HOST <Your host name>
    HTTP_STAGE production
  6. Press Ctrl-O and then Enter to save the modified file.
  7. Press Ctrl-X to exit.
  8. Edit config/gsn-relay-config.json to specify:
    Parameter Value
    HOST Your host name
    baseRelayFee The base fee that your relay will charge
    pctRelayFee The percent fee that your relay will charge
    versionRegistryAddress The address for the version registry on the network you are using. See this list.
    ownerAddress The owner account that will be used by relayer-register, below
    ethereumNodeUrl 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 (opens new window), create a project, and look at KEYS > ENDPOINTS for your network. Use the endpoint that starts with https://
  9. Download and run the docker images
    rdc config
rdc up -d
  10. Wait until the second rdc command finishes.
  11. To see the progress of the HTTPS server (the slowest component to set up), run
    rdc logs -f https-portal
  12. When you see this line it means the setup is done. You can close the SSH window.
    [services.d](https-portal_1  | ) done.
  13. 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.

You can also check the activity of the relay when you are on the vm. Get the id of the "jsrelay" container.

docker ps

Then get the logs of this container.

docker logs <container-id>

# Relay Staking and Registration

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 submitting invalid messages)
  • Put up the initial relay budget for sending messages. The default is 2 Ether.
  • Add the relay to the relay list so clients will know they can use it for free messages

You can use any UNIX computer for this process, but it requires the mnemonic, the twelve word pass phrase for your account. This is an extremely sensitive piece of information, which you never want away from your control.

  1. Install the GSN command line interface on Docker. It has to be the Docker version to be able to specify the gas price for the registration transaction.
    sudo docker image pull opengsn/cli
  2. Create a file pass12 with the twelve word mnemonic for the account you'll use to fund the relay.
  3. Get the current gas price for transactions from here (opens new window). The low cost should be sufficient
  4. Register the relay. You may get an error saying that after 60 seconds the relay is not yet ready. If so, ignore it, it is usually just because it takes a bit longer.
    docker run --rm -ti -v $PWD:$PWD \
    opengsn/cli relayer-register \
    --network <the ethereumNodeURL you used for the relay> \
    --gasPrice <get from the link above, specify in Gwei> \
    --relayUrl https://<your hostname for the relay>/gsn1 \
    -m `pwd`/pass12

    Note

    To avoid risking your main account, you can create a dedicated address (opens new window) and transfer 3.001 ether to it. One ether is the stake that you lose if your relay doesn't relay messages honestly, 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).

  5. Browse to https://<your DNS name>/gsn1/getaddr . See that the relay is now ready. Congratulations.

# Unstaking

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

  1. Go here (opens new window) 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.
docker logs default_gsn1_1 2>1 | grep withdrawBlock
  1. Use https://<network name>.etherscan.io to see the latest block, wait until it is past the withdrawal block.
  2. Go back to the unstake page (opens new window) and enter the RelayManagerAddress again.
  3. Click Withdraw previously unlocked stake.

# Conclusion

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.

Original version of this tutorial by Ori Pomerantz qbzzt1@gmail.com

← Mainnet →