Saturn L1 Node 🪐

Saturn L1 nodes are CDN edge caches in the outermost layer of the Filecoin Saturn network. L1 nodes serve CAR files to retrieval clients as requested by their CIDs. Cache misses are served by the IPFS Network and Filecoin Storage Providers.

Saturn is live. Do you have a server that meets the minimum hardware requirements? If so, follow the setup instructions below to get started. You can run an L1 node, contribute bandwidth to the network, and earn Filecoin (FIL) today.

Beyond running a node, Saturn is a community run project and we'd love for you to get involved. Come say hi in #filecoin-saturn on Filecoin Slack! 👋

Table of Contents

• Requirements
  • General requirements
  • Node hardware requirements
• Set up a node
• Set up a node with Ansible
• Stopping a node
• Switch networks between test net and main net
• Node operator guide
  • Obtaining a Filecoin wallet address
  • Claiming your node's earnings
  • Node monitoring
  • Community Tools
• License

Requirements

General requirements

• Filecoin wallet address
• Email address

Node hardware requirements

• Linux server with a static public IPv4 address in a unique /24 CIDR block
• Root access / passwordless sudo user (How to)
• Ports 80 and 443 free and public to the internet
• Docker installed (Instructions here) with Docker Compose v2
• CPU with 6 cores (12+ cores recommended). CPU Mark of 8,000+ (20,000+ recommended)
• 10Gbps upload link minimum¹ (Why 10Gbps?)
• 32GB RAM minimum (128GB+ recommended)
• 4TB SSD storage minimum (16TB+ NVMe recommended)²

Only one node per physical host is allowed. If you want to run multiple nodes, you need to run them on dedicated hardware.
Multi-noding (Sharing CPU, RAM, Uplink or storage among nodes) is not allowed.

_{¹ The more you can serve → greater FIL earnings
² Bigger disk → bigger cache → greater FIL earnings}

Set up a node

_{If you want to switch your node from test net to main net, or vice versa, see Switch networks below.}

1. Install

   • Docker: instructions here
   • Docker compose v2: instructions here

2. Change directory to $SATURN_HOME (default: $HOME) to download the required files

   cd ${SATURN_HOME:-$HOME}

3. Download the .env file

   Note: the .env file does not take precedence over env variables set locally.

   • Set the mandatory FIL_WALLET_ADDRESS and NODE_OPERATOR_EMAIL environment variables in the .env file.
   • Set the SATURN_NETWORK environment variable in the .env file.
     • To join Saturn's Main network and earn FIL rewards, make sure to set SATURN_NETWORK to main.
     • To join Saturn's Test network, which doesn't earn FIL rewards, set SATURN_NETWORK to test. Note that this is the default value!
   • By default, the Saturn volume is mounted from $HOME. It can be changed by setting the $SATURN_HOME environment variable.

   curl -s https://raw.githubusercontent.com/filecoin-saturn/L1-node/main/.env -o .env

   You can use the text editor of your choice (e.g. nano or vim on Linux)

4. Download the docker-compose.yml file:

   curl -s https://raw.githubusercontent.com/filecoin-saturn/L1-node/main/docker-compose.yml -o docker-compose.yml

5. Download the docker_compose_update.sh script and make it executable:

   curl -s https://raw.githubusercontent.com/filecoin-saturn/L1-node/main/docker_compose_update.sh -o docker_compose_update.sh
   chmod +x docker_compose_update.sh

6. Set up the cron job to auto-update the docker-compose.yml file:

   (crontab -l 2>/dev/null; echo "*/5 * * * * cd $SATURN_HOME && sh docker_compose_update.sh >> docker_compose_update.log 2>&1") | crontab -

7. Launch it:

   sudo docker compose up -d

8. Check logs with docker logs -f -n 100 saturn-node

9. Check for any errors. Registration will happen automatically and the node will restart once it receives its TLS certificate

In most instances speedtest does a good job of picking "close" servers but for small networks it may be incorrect. If the speedtest value reported by speedtest seems low, you may want to configure SPEEDTEST_SERVER_CONFIG to point to a different public speedtest server. You will need to install speedtest CLI in the host and fetch close servers' IDs by doing speedtest --servers, then setting SPEEDTEST_SERVER_CONFIG="--server-id=XXXXX"

Update a node

We are using a Watchtower container to update the saturn-node container. Your node will be updated automatically. You can see the update logs with docker logs -f saturn-watchtower. Make sure to setup the cron job to auto-update docker-compose.yml as well (see above).

Set up a node with Ansible

From here:

"Ansible is an IT automation tool. It can configure systems, deploy software, and orchestrate more advanced IT tasks such as continuous deployments or zero downtime rolling updates."

This playbook is meant as a bare-bones approach to set up an L1. It simply automates running the steps described above. A consequence of this is that when run it will restart a crashed L1 node docker container. It also presents a basic approach to server hardening which is by no means thorough.

Note: The security of your servers is your responsibility. You should do your own research to ensure your server follows security best practices.

If you're looking for a playbook which covers server hardening, monitoring and logging please check out https://github.com/hyphacoop/ansible-saturn-l1.

Currently, this playbook runs on the following Linux distros:

• Ubuntu
• Debian
• CentOS

These instructions are to be run in a machine with Ansible >= 2.14 installed. This machine is known as your control node and it should not be the one to run your L1 node.

Most commands are run as root and your ssh user should have root access on the target machine.

1. Install the required Ansible modules

ansible-galaxy collection install community.docker

2. Clone this repository and cd into it.

3. For target host connectivity, ssh keys are recommended and this playbook can help you with that.

   Note: Using the playbook for this is completely optional.

   1. Make sure you have configured ansible_user and ansible_ssh_pass for your target host in your inventory file. See more here.
   2. Setup an authorized_keys file with your public ssh keys in the cloned repository root.
   3. Run ansible-playbook -i <path_to_your_inventory> -l <host_label> --skip-tags=config,harden,run playbooks/l1.yaml

4. Ensure your control node has ssh access to your target machine(s).

• Make sure to specify which hosts you want to provision in your inventory file.

ansible -vvv -i <path_to_your_inventory> <host_label> -m ping

5. Replace the environment variable values where appropriate and export them.

• If Main network: Set SATURN_NETWORK to main
• If you are switching networks check Switching networks and rerun step 4 and 5.
• You can define a host-specific SATURN_HOME by setting a saturn_root variable for that host on your inventory file. See more here.

export FIL_WALLET_ADDRESS=<your_fil_wallet_address>; export NODE_OPERATOR_EMAIL=<your_email>; export SATURN_NETWORK=test

6. Run the playbook

• Feel free to use host labels to filter them or to deploy incrementally.
• We're skipping the bootstrap play by default, as it deals with setting authorized ssh keys on the target machine. See 2 for more info.

ansible-playbook -i <path_to_your_inventory> -l <host_label> --skip-tags=bootstrap playbooks/l1.yaml

• To skip the hardening step run this instead:

ansible-playbook -i <path_to_your_inventory> -l <host_label> --skip-tags=bootstrap,harden playbooks/l1.yaml

Stopping a node

To gracefully stop a node and not receive a penalty, run:

  sudo docker stop --time 1800 saturn-node

or if you are in your $SATURN_HOME folder with the Saturn docker-compose.yml file:

  sudo docker compose down

We are setting the stop_signal and the stop_grace_period in our Docker compose file to avoid issues. If you have a custom setup, make sure to send a SIGTERM to your node and wait at least 30 minutes for it to drain.

Switch networks between test net and main net

If you want to switch your node from Saturn's test network (aka test) to Saturn's main network (aka main), or vice versa, follow these steps:

1. Gracefully halt your node as explained in Stopping a node.
2. Set the network environment variable SATURN_NETWORK to main, or test, in your $SATURN_HOME/.env file (default: $HOME/.env).
3. Delete contents in $SATURN_HOME/shared/ssl (default: $HOME/shared/ssl).
4. Start the node again with docker compose -f $SATURN_HOME/docker-compose.yml up -d.
5. Check logs with docker logs -f saturn-node

Node operator guide

For answers to common questions about operating a node, see the L1 node FAQ page.

Network Uptime Requirement

To be eligible for the end of month earnings on the Saturn Network, nodes must satisfy a minimum uptime requirement each month. Having an uptime requirement has the following benefits:

• Addresses node churn on the network. Node churn reduced performance and the stability of the network. Having a minimum uptime requirement incentivizes nodes to remain online for longer periods.
• Certain malicious nodes on the network run on compromised cloud accounts. Those usually have a lifetime of ~3 days. The uptime requirement ensures that those nodes do not receive earnings.

The current uptime requirement is as follows:

• For a node operator to qualify for earnings at the end of the month, their node must be online for at least 14 days during the month. It is important to note that earnings for nodes STILL get calculated before the node satisfies the uptime requirement.
• When a node first registers during a given month, its uptime requirement check will be postponed to the following month to give a fair opportunity for each node to meet the uptime requirement. Its earnings will remain pending until it has satisfied the uptime requirement. If the node satisfied the uptime requirement during the same month it registers, it will be eligible to receive earnings that month.
• Nodes that do not satisfy the uptime requirement in the months after their registration month will forfeit their earnings for the given month. Their forfeited earnings will be added to the network reward pool for the following month.
• The uptime requirement must be satisfied on a monthly basis after the registration month is over.

Note: Beginning July 1st, 2023, Saturn’s monthly node uptime requirement increased from 7 days to 14 days. This means that for a node to qualify for earnings on August 1st, 2023, that node must have been online and operational for at least 14 contiguous days in July.

Read more about Saturn's node uptime requirement in the docs, here.

Obtaining a Filecoin wallet address

You need to own a Filecoin wallet to receive FIL payouts.

• Official Filecoin wallet documentation

• If you have an account on a Centralized Exchange (Coinbase, Binance, etc.) that supports Filecoin, go through the steps to deposit Filecoin and you'll be given a wallet address. This is recommended if you don't want to manage your wallet's seed phrase.

• Web wallets

  • Filfox wallet
  • Glif - Supports Ledger

• Desktop wallets

  • Exodus

• Mobile wallets

  • FoxWallet

⚠️ Please follow crypto wallet best practices. Never share your seed phrase with anyone or enter it into websites. The Saturn team will never DM you or ask you to verify/validate/upgrade your wallet. If you need assistance, please ask in public channels such as the #filecoin-saturn Slack.

Claiming your earnings

Each month, your node's earnings, in FIL, are calculated by the network based on various factors such as the amount of bandwidth it served, the number of requests it handled, its performance metrics like TTFB and upload speed, and its availaility and uptime. These earnings are then sent to a payout FVM smart contract by the 7th day of the following month. For example, earnings for December 2022 would be transferred to a payout smart contract by January 7th, 2023.

After your node's earnings are in the payout FVM smart contract, you can claim them on payouts.saturn.tech. Claiming your earnings moves the Filecoin your node(s) earned from the smart contract to your personal Filecoin wallet.

Node monitoring

• https://dashboard.saturn.tech - View detailed, real-time stats on every Saturn node.
• https://dashboard.saturn.tech/address - View historical data on your bandwidth contributions, FIL earnings, and more.
• https://explorer.saturn.tech - View a 3D geospatial visualization of the Saturn network, along with nodes and network statistics.

Community Tools

These Saturn tools are maintained by community members outside the Saturn core team.

• https://github.com/31z4/saturn-moonlet - Self-hosted Saturn monitoring using Prometheus and Grafana. View detailed, real-time and historical data on your nodes and earnings, setup alerts, and more.

License

Dual-licensed under MIT + Apache 2.0