Overview

The Bor gateway acts as a bridge between your Polygon node and the Marlin relay network, enabling them to understand and talk to each other. In addition, it handles most of the Marlin related interactions for you like optimizing peer sets, attesting messages, generating tickets, spam checks, etc.

Quickstart

This section assumes that marlinctl is installed already. See here if you have not installed it. It also assumes that you are using a Sentry node (recommended) in front of the Validator.

Step 1: Generate a client identity for the gateway by running the below command and entering a passphrase when prompted

sudo marlinctl gateway polygon bor keystore create

Step 2: Set up abci-bor in the Sentry node. It is a drop in replacement for bor which implements spam prevention RPC methods.

wget http://public.artifacts.marlin.pro/projects/abci-bor/1.0.1/bor-linux_amd64 -O /path/to/local/bor

Step 3: Expose the RPC methods from abci-bor by adding the below cli flags to the start.sh script.

--http  # enable http rpc
--http.addr "0.0.0.0"  # expose the RPC endpoint outside the instance so the gateway can access it
					   # IMPORTANT: Protect the RPC endpoint from external access using a firewall
--http.api "lin"  # the RPC APIs used by the gateway live in the `lin` namespace, expose them

Restart the bor service in the Sentry node so all the above changes take effect.

Step 4: Set up mev-bor in the Validator node. It is a drop in replacement for bor which implements MEV bundles related RPC methods as well as includes them in blocks.

wget http://public.artifacts.marlin.pro/projects/mev-bor/1.0.1/bor-linux_amd64 -O /path/to/local/bor

Step 5: Expose the RPC methods from mev-bor by adding the below cli flags to the start.sh script.

--http  # enable http rpc
--http.addr "0.0.0.0"  # expose the RPC endpoint outside the instance so the gateway can access it
					   # IMPORTANT: Protect the RPC endpoint from external access using a firewall
--http.api "eth"  # the  RPC APIs used by the gateway live in the `eth` namespace, expose them

Restart the bor service in the Validator node so all the above changes take effect.

Step 6: Create the gateway, providing the above Sentry and Validator RPC endpoints (default RPC port in bor is 8545).

sudo marlinctl gateway polygon bor create --bootstrap-addr "54.219.12.125:8002" --spamcheck-addr "sentry_rpc_ip:sentry_rpc_port" --bundle-addr "http://validator_rpc_ip:validator_rpc_port/"

Step 7: Retrieve the enode of the gateway by checking the logs.

sudo marlinctl gateway polygon bor logs

Look for text like enode://32511b4996e9d...@ip:port, this is the identity. The default port used by the gateway is 22900.

Step 8: Add the gateway as a persistent peer to your Validator node similar to how you added the Sentry.

Step 9: The gateway needs to accept connections on port 18545, ensure it is open to the internet.

Step 10: Register yourself on this form. We will reach out to you for onboarding.

That's it!

Architecture

Tuning

The linux UDP stack needs to be tuned for optimal performance. Here's a good reference for the parameters - https://gist.github.com/voluntas/bc54c60aaa7ad6856e6f6a928b79ab6c.

Note: Try to understand what you're changing and why before you change it, since it depends on your system characteristics if any of the commands there would improve or worsen performance (and stability, be wary of memory exhaustion).

The important bits seem to be:

  • Run watch netstat -us - Check if send or receive errors are increasing with time, indicates buffer overflows
  • If yes, increase buffer size (replace the numbers below as you please)
# Per-socket read buffers
net.core.rmem_default = 8192000
net.core.rmem_max = 8192000

# Per-socket write buffers
net.core.wmem_default = 8192000
net.core.wmem_max = 8192000

# Option memory
net.core.optmem_max = 8192000

# Global tuning (multiplied by 4KB)
net.ipv4.udp_mem = 64000    64000    64000
  • Restart the gateway and check again after some time