Skip to main content

Relay Guide

Relays are communication intermediaries between block-builders and validators, ensuring secure and fair interactions. The relays will gather the bids received from multiple block-builders and aggregate them, while ensuring that the blocks submitted by builders include payment to the validators. Then the highest valid bid is selected to be forwarded to the validator to sign.


  • GoLang: Ensure that you have Golang Version 1.20 or higher. If not, you can download it here.
  • BLS Key: Generate a BLS key using tools such as Stakehouse, Wagyu Key Generator, or Ethereum CLI.
  • Access to a Beacon Node: You will need access to a beacon node and the use ETH2 API. Ensure this API is either behind publicly available URL or tunnel into the server running the beacon node. You can use multiple beacon clients as well. Run

ssh -L 3500:localhost:BEACON_CLIENT_PORT SERVER_IP

And replace BEACON_CLIENT_PORT with the port being used by the beacon client, and SERVER_IP with the public IP of the server.

  • PoN Pool Subgraph: Have the URL of the PoN Pool subgraph for the PoN pool the relay will be serving.

  • MQTT Broker: Ensure that the relay can connect to an MQTT Broker. It is possible to use a publicly available MQTT as well.

  • Database Systems: The relay needs to run Postgres (or any SQL Server) and a Redis Server. Options for running these include:

    • Docker Distribution: Use our build instructions to create a Docker Distribution.
    • Docker Compose File: Use the Docker Compose file provided with the relay.

See how to do this below.

Build Using Docker Distribution

Run the following commands

docker run -d -p 5432:5432 -e POSTGRES_USER=postgres -e POSTGRES_PASSWORD=postgres -e POSTGRES_DB=postgres postgres

and then

docker run -d -p 6379:6379 redis

In case you want to give your own Docker Username or Docker Password, give POSTGRES_USER and POSTGRES_PASSWORD your own.

Build Using Docker Compose

The relay repository comes with docker compose for Postgres and Redis. You can run the services using following command

sudo docker-compose -f docker-core.yml up

Set the following environment variables

  • POSTGRES_USER - Postgres User
  • POSTGRES_PASSWORD - Postgres Password
  • POSTGRES_DB - Postgres Database

For more description on how to run using docker compose visit

Run Relay

To run the relay, use the following command

go run . relay \
--relay-url <Relay_URL> \
--beacon-uris <Beacon_URIS> \
--redis-uri <Redis_URIS> \
--db <DB_URL> \
--secret-key <Relay_BLS> \
--network <Network> \
--max-db-connections <Max_DB_Connections> \
--max-idle-connections <Max_Idle_Connections> \
--max-idle-timeout <Max_Idle_Timeout> \
--db-driver <DB_Driver> \
--pon-pool <PON_POOL_URL> \
--pon-pool-API-Key <PON_POOL_API_KEY> \
--bulletinBoard-broker <Bulletin_Board_Broker> \
--bulletinBoard-port <Bulletin_Board_Port> \
--bulletinBoard-client <Bulletin_Board_Client> \
--bulletinBoard-password <Bulletin_Board_Password> \
--reporter-url <Reporter_URL> \
--bid-timeout <Bid_Timeout> \
--relay-read-timeout <Relay_Read_Timeout> \
--relay-read-header-timeout <Relay_Read_Header_Timeout> \
--relay-write-timeout <Relay_Write_Timeout> \
--relay-idle-timeout <Relay_Idle_Timeout> \
--new-relic-application <New_Relic_Application> \
--new-relic-license <New_Relic_License> \
--new-relic-forwarding <New_Relic_Forwarding>

These are the relay parameters you need to provide

--relay-urlListen Address For The PoN Relay Service LocallyLocalhost:9000No
--beacon-urisBeacon Node EndpointYes
--dbDatabase URLYes
--secret-keyBLS Secret Key Of RelayYes
--networkNetwork (Testnet/ Mainnet)TestnetNo
--max-db-connectionsMaximum Database Connections100No
--max-idle-connectionsMaximum Database Idle Connections100No
--max-idle-timeoutMaximum Database Timeout (In 1s/ 5h format)100sNo
--db-driverDatabase DriverPostgresNo
--pon-poolPoN Pool Subgraph URLYes
--bulletinBoard-brokerBulletin Board MQTT Broker URLYes
--bulletinBoard-portBulletin Board MQTT PortYes
--bulletinBoard-clientBulletin Board ClientYes
--bulletinBoard-passwordBulletin Board PasswordYes
--bid-timeoutMaximum Time Bid is Kept With Relay (In 1s/ 5h format)15sNo
--relay-read-timeoutRelay Server Read Timeout (In 1s/ 5h format)10sNo
--relay-read-header-timeoutRelay Server Read Header Timeout (In 1s/ 5h format)10sNo
--relay-write-timeoutRelay Server Write Timeout (In 1s/ 5h format)10sNo
--relay-idle-timeoutRelay Idle Timeout (In 1s/ 5h format)10sNo
--new-relic-applicationNew Relic Application (New Relic Not Used If Application Not Provided)No
--new-relic-licenseNew Relic LicenseNo
--new-relic-forwardingNew Relic ForwardingFalseNo