This page details the procedure to join the Marlin network.

For clusters

Step 1: Preliminaries
  • Refer to the architecture diagram here and understand the interactions
  • Preferably, set up marlinctl2 (available here) to make the setup process smoother
  • If you prefer a manual setup or marlinctl2 doesn't cover your use case, clone and build OpenWeaver
Step 2: Set up beacon
  • Run a beacon node
  • Ensure the beacon is reachable from outside
  • Pass "" as the beacon address while starting the beacon to register it with the wider testnet
# Using marlinctl
$ sudo marlinctl beacon keystore create
$ sudo marlinctl beacon create --discovery-addr "" --heartbeat-addr "" --bootstrap-addr ""

# Manually
$ ./beacon/beacon --discovery-addr "" --heartbeat-addr "" --beacon-addr ""
Step 3: Set up relays
  • Run a relay node
  • Set the discovery-addrs parameter to point to the discovery-addr of your beacon set up above
  • Set the heartbeat-addrs parameter to point to the heartbeat-addr of your beacon set up above
# Using marlinctl
$ sudo marlinctl relay eth create --discovery-addrs "beaconip:8002" --heartbeat-addrs "beaconip:8003"

# Manually
$ ./relay/eth_relay "beaconip:8002" "beaconip:8003" "/path/to/datadir/"
Step 4: Set up firewalls
  • Expose for public access

    • Discovery port of beacon
    • Discovery port of relay
    • Pubsub port of relay
  • Expose only for relay access

    • Heartbeat port of beacon


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:

  • 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

    Revision #10
    Created Sat, Feb 20, 2021 4:42 PM by Utsav Rohilla
    Updated Sun, Sep 5, 2021 1:48 PM by Roshan