Introduction

Bisq seed nodes are used for the connection to the network at the startup of a new application. They have 2 main tasks:

  1. Deliver the peer addresses of network peers

  2. Deliver the initial P2P network data like the offers, mailbox messages or the arbitrators

The second task could (and should in future) be done also by any other nodes but because seed nodes are running on servers they deliver a higher level of reliability and better connectivity than an normal network node.

The user connects to one of the seed nodes randomly and if a node fails it tries the next in random node in the list. If the first seed node is not available it decreases usability for the user because startup takes longer. But more critical is that if a node has bad connectivity it might miss messages like mailbox messages. That would be very bad because if a trader connects to that node he will not see the message the peer or arbitrator has sent him when he was offline. Usually we never had issues with that but it could become a cause for disputes or bug reports if a node would be badly connected.

Seed node operators

The seed node addresses (onion address) are hard coded in the application but can be overruled if the user adds a seed node address as program argument. Any user can run therefor their own seed node and connect to it.

Some contributors of Bisq are running the default seed nodes which are hard coded in the application. It requires a to set up a bond in BSQ to get the privilege to run a default seed node and it requires that a certain quality of service is met. The node need to support at least 30 connections.

Contributors running a seed node will file a compensation request each month and get paid a fixed amount of BSQ for it if node availability was as expected.

A default seed node can be blocked by a network message in case the seed node does not fulfill the required quality.

Side note: The seed nodes on Linux get a out of memory error after running a few days. We still have not found the reason for it (see: link: Github issue) but as a quick fix we check the memory usage inside the application and if it is over a certain threshold the seed node restarts itself. This happens usually once a day and cause a connection loss for about 1 minute. If you have sufficient RAM you can increase that limit with --maxMemory=1024 to 1024 MB or more, default value for maxMemory is 500 MB.

Duties of the seed node operator

The operator of a seed node need to be responsive in case of seed node software updates as well to OS updates. If there are connectivity issues he need to investigate and if required upgrade his server (RAM, CPU). We recommend 2-4 GB of RAM for one seed node to allow 30 connections. He should check the error logs and the node log file (in the data directory) occasionally. He has to have a professional level of operational security to operate the node. Operators need to subscribe to the Bisq Slack channel 'seednode' and act if their node reports errors.

System requirements for hosting machine

  1. Min. 2 GB of RAM

  2. 10 GB disk space (SSD)

  3. 2 TB network traffic

  4. UPS (uninterruptible power supply)

  5. Uptime of > 99.9%

Setup instructions

Step 1. Install latest JDK

You need to have the latest JDK installed according to the build.md file.

Step 2. Start seed node the first time to find out the onion address

You need to know the onion address of your seed node (part of program argument). But at the first start you don’t know it. To solve that chicken and egg problem you start the below script start_btc_ONION_ADDRESS.sh and later replace the placeholder with the real address.

Step 2.1. Create 2 sh files:

start_btc_ONION_ADDRESS.sh:
nohup sh loop_btc_ONION_ADDRESS.sh &

loop_btc_ONION_ADDRESS.sh:
java -Xms1800m -Xmx1800m -jar SeedNode.jar --maxConnections=30 --baseCurrencyNetwork=BTC_MAINNET --nodePort=8000 --myAddress=ONION_ADDRESS.onion:8000 --appName=seed_BTC_MAINNET_ONION_ADDRESS >/dev/null 2>error_seed_BTC_MAINNET_ONION_ADDRESS.log

Step 2.2. Start the start_btc_ONION_ADDRESS.sh

~/sh start_btc_ONION_ADDRESS.sh

Step 2.3. Get onion address from log

After about 40 seconds you should see in the logs following entry: INFO c.m.t.t.OnionProxyManagerEventHandler: Hidden service joehwtpe7ijnz4df.onion:8000 published.

This is the onion address you need to use in the next step to replace the ONION_ADDRESS place holder.

Step 2.4. Stop the node

Step 3. Replace placeholder with real onion address

Replace the occurrence of ONION_ADDRESS in the above listed scripts and their file name.

Go to ~/.local/share and replace ONION_ADDRESS in the directory name with the real onion address.

Step 3. Backup private key for onion address

Go to ~/.local/share/seed_BTC_MAINNET_ONION_ADDRESS/btc_mainnet/tor/hiddenservice/ and backup the private key and the hostname file in a safe location. If your server would crash you can re-install the same seed node with the private key. All other data like the db or the keys directory are not relevant for the seed node.

Step 4. Start seed node again

Once all the renaming is done you can finally start the seed node and it will be available to the network. Check the logs and monitor the server to see if all is running as expected.

Monitoring

Seed nodes are monitored in the Bisq Slack channel 'monitoring' and errors are sent to the 'seednode' channel. Operators need to subscribe to the 'seednode' channel and act if their node reports errors.

Bond

We define a Bond of 2000 BSQ for the privilege to run a seed node. In case of severe failures of service (malicious or carelessness) the bond would be confiscated (burned).

Payment

For the service the contributor provides by running and maintaining a seed node as well as a compensation for the server costs we define a payment of 50 BSQ per month. For the setup we define a payment of 200 BSQ.