# Lotus Miner: setup a high performance miner

This guide describes the necessary steps to configure a Lotus miner for production.

WARNING

Mining will only work if you fully cover the minimal hardware requirements for the network in which you will mine. As the mining process is very demanding for the machines on several aspects and relies on precise configuration, we strongly recommend Linux systems administration experience before embarking.

# Pre-requisites

Before attempting to follow this guide:

Be warned: if you decide to skip any of the sections below, things will not work! Read and tread carefully.

# Before starting the miner

# Performance tweaks

It is recommended to set the following environment variables in your environment so that they are defined every time any of the Lotus applications is launched (meaning, when the daemons are started):

# See https://github.com/filecoin-project/bellman
export BELLMAN_CPU_UTILIZATION=0.875

# See https://github.com/filecoin-project/rust-fil-proofs/
export FIL_PROOFS_MAXIMIZE_CACHING=1 # More speed at RAM cost (1x sector-size of RAM - 32 GB).
export FIL_PROOFS_USE_GPU_COLUMN_BUILDER=1 # precommit2 GPU acceleration
export FIL_PROOFS_USE_GPU_TREE_BUILDER=1

# The following increases speed of PreCommit1 at the cost of using a full
# CPU Core-Complex rather than a single core. Should be used with CPU affinities set!
# See https://github.com/filecoin-project/rust-fil-proofs/ and the seal workers guide.
export FIL_PROOFS_USE_MULTICORE_SDR=1

# Running the miner on a different machine as the Lotus Node

If you opt to run a miner on a different machine as the Lotus Node, set:

export FULLNODE_API_INFO=<api_token>:/ip4/<lotus_daemon_ip>/tcp/<lotus_daemon_port>/http

and make sure the ListenAddress has remote access enabled. Instructions on how to obtain a token are available here.

Similarly, lotus-miner (as a client application to the Lotus Miner daemon), can talk to a remote miner by setting:

export MINER_API_INFO="TOKEN:/ip4/<IP>/tcp/<PORT>/http"

# Adding the necessary swap

If you have only 128GiB of RAM, you will need to make sure your system provides at least an extra 256GiB of very fast swap (preferably NVMe SSD) or you will be unable to seal sectors:

sudo fallocate -l 256G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile
# show current swap spaces and take note of the current highest priority
swapon --show
# append the following line to /etc/fstab (ensure highest priority) and then reboot
# /swapfile swap swap pri=50 0 0
sudo reboot
# check a 256GB swap file is automatically mounted and has the highest priority
swapon --show

# Creating wallets for the miner

You will need at least a BLS wallet (f3... for mainnet) for mining. We recommend using separate owner and worker wallets though. Thus, create at least two wallets (unless you have some already):

# A new BLS address to use as owner address:
lotus wallet new bls
t3...

# A new BLS address to use as worker address:
lotus wallet new bls
t3...

Next make sure to send some funds to the worker address so that the miner setup can be completed.

For additional information about the different wallets that a miner can use and how to configure them, read the miner wallets guide.

# Downloading parameters

For the miner to start, it will need to read and verify the Filecoin proof parameters. These can be downloaded in advance (recommended), or otherwise the init process will. Proof parameters consist of several files, which in the case of 32GiB sectors, total over 100GiB.

We recommend setting a custom location to store parameters and proofs parent cache -created during the first run- with:

export FIL_PROOFS_PARAMETER_CACHE=/path/to/folder/in/fast/disk
export FIL_PROOFS_PARENT_CACHE=/path/to/folder/in/fast/disk2

Parameters are read on every (re)start, so using disks with very fast access, like NVMe drives, will speed up miners and workers (re)boots. When the above variables are not set, things will end up in /var/tmp/ by default, which often lacks enough space.

To download the parameters do:

# Use sectors supported by the Filecoin network that the miner will join and use.
# lotus-miner fetch-params <sector-size>
lotus-miner fetch-params 32GiB
lotus-miner fetch-params 64GiB

You can verify sectors sizes for a network in the network dashboard (opens new window). The FIL_PROOFS_*_CACHE variables should stay defined not only for download, but also when starting the Lotus miner (or workers).

# Checklist before launch

To summarize all of the above, make sure that:

  • The worker address has some funds so that the miner can be initialized.

  • The following environment variables have been defined and will be available for any Lotus miner runs:

    export LOTUS_MINER_PATH=/path/to/miner/config/storage
    export LOTUS_PATH=/path/to/lotus/node/folder # when using a local node
    export BELLMAN_CPU_UTILIZATION=0.875
    export FIL_PROOFS_MAXIMIZE_CACHING=1
    export FIL_PROOFS_USE_GPU_COLUMN_BUILDER=1 # when having GPU
    export FIL_PROOFS_USE_GPU_TREE_BUILDER=1   # when having GPU
    export FIL_PROOFS_PARAMETER_CACHE=/fast/disk/folder # > 100GiB!
    export FIL_PROOFS_PARENT_CACHE=/fast/disk/folder2   # > 50GiB!
    export TMPDIR=/fast/disk/folder3                    # Used when sealing.
    
  • Parameters have been prefetched to the cache folders specified above.

  • The systems has enough swap and it is active.

# Miner initialization

Before starting your miner for the first time run:

lotus-miner init --owner=<bls address>  --worker=<other_address> --no-local-storage
  • The --no-local-storage flag is used so that we can later configure specific locations for storage. This is optional but recommended.
  • The Lotus Miner configuration folder is created at ~/.lotusminer/ or $LOTUS_MINER_PATH if set.
  • The difference between owner and worker addresses is explained in the miner wallets guide. As mentioned above, we recommend using two separate addresses. If the --worker flag is not provided, the owner address will be used. Control addresses can be added later when the miner is running.

# Connectivity to the miner

Before you start your miner, it is very important to configure it so that it is reachable from any peer in the Filecoin network. For this you will need a stable public IP and edit your ~/.lotusminer/config.toml as follows:

...
[Libp2p]
  ListenAddresses = ["/ip4/0.0.0.0/tcp/24001"] # choose a fixed port
  AnnounceAddresses = ["/ip4/<YOUR_PUBLIC_IP_ADDRESS>/tcp/24001"] # important!
...

Once you start your miner, make sure you can connect to its public IP/port.

# Starting the miner

You are now ready to start your Lotus miner:

lotus-miner run

or if you are using the systemd service file:

systemctl start lotus-miner

WARNING

Do not proceed from here until you have verified that your miner not only is running, but also reachable on its public IP address.

# Publishing the miner addresses

Once the miner is up and running, publish your miner address (which you configured above) on the chain so that other nodes can talk to it directly and make deals:

lotus-miner actor set-addrs /ip4/<YOUR_PUBLIC_IP_ADDRESS>/tcp/24001

# Next steps

Your miner should now be preliminarly setup and running, but there are still a few more recommended tasks to be ready for prime-time: