Cosmos Relay


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
Expose only to relays


The linux UDP stack needs to be tuned for optimal performance. Here's a good reference for the parameters -

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:

# 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

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.



The current architecture has 4 types of nodes

A cluster operator is responsible for running managing the beacon, monitoring and relay nodes. Users of the network need to simply run and manage a user node.



The beacon node is similar to seed nodes or bootstrap nodes in other networks. It is the initial touchpoint using which a user discovers the other nodes in the network.


The relay nodes form the core of the network and are responsible for propagating information from one user to the others. They are ideally distributed across different regions to have low latency with users.

Hardware Requirements

Node Type vCPU Memory Disk space
Beacon 0.5 1 GB < 1 GB
Relay 1 1 < 1 GB