The cosmos relay acts as a fabric between the cosmos nodes connected to the Marlin relay network through the cosmos gateway, enabling them to multicast messages between each other. In addition, it handles most of the Marlin related interactions for you like optimizing peer sets, checking attestations, handling tickets, etc.


This section assumes that marlinctl is installed already. See here if you have not installed it.

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

sudo marlinctl beacon keystore create

Step 2: Create the beacon

sudo marlinctl beacon create --bootstrap-addr "" --discovery-addr "" --heartbeat-addr ""

Note: For participating in the Lagoon testnet, use as the bootstrap address instead.

Step 3: Create one or more relays

sudo marlinctl relay cosmos create --discovery-addrs "<beacon_public_ip>:8002" --heartbeat-addrs "<beacon_public_ip>:8003"

That's it!

Firewall rules

Expose for public access
  • Discovery port of beacon (default: 8002)
  • Discovery port of relay (default: 22002)
  • Pubsub port of relay (default: 22000)
Expose only to relays
  • Heartbeat port of beacon (default: 8003)


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 relays and check again after some time

Manual Setup

Step 1: Create an identity keystore file (can use geth or MyEtherWallet). Also create a text file with the passphrase used to create the keystore.

Step 2: Run the beacon

./beacon --discovery-addr "" --heartbeat-addr "" --beacon-addr "" --keystore-path /path/to/keystore --keystore-pass-path /path/to/passphrase

Step 3: Run one or more relays

./cosmos_relay --discovery-addrs "<beacon_public_ip>:8002" --heartbeat-addrs "<beacon_public_ip>:8003"

Complete the setup by following the firewall and tuning sections above.