Lotus components
Lotus is the reference implementation for the Filecoin network written in Go and maintained by Protocol Labs. Understanding the components of Lotus is necessary in understanding subsequent sections on sealing, and what it means to build well-balanced storage provider architecture.
The diagram below shows the major components of Lotus:
The following components are the most important to understand:
Lotus daemon
The daemon is a key Lotus component that does the following:
- Syncs the chain
- Holds the wallets of the storage provider
The machine running the Lotus daemon must be connected to the public internet for the storage provider to function. See the Lotus documentation for more in-depth information on connectivity requirements.
Syncing the chain
Syncing the chain is a key role of the daemon. It communicates with the other nodes on the network by sending messages, which are, in turn, collected into blocks. These blocks are then collected into tipsets. Your Lotus daemon receives the messages on-chain, enabling you to maintain consensus about the state of the Filecoin network with all the other participants.
Due to the growth in the size of the chain since its genesis, it is not advised for storage providers to sync the entire history of the network. Instead, providers should use the available lightweight snapshots to import the most recent messages. One exception in which a provider would need to sync the entire chain would be to run a blockchain explorer.
Synced chain data should be stored on an SSD; however, faster NVMe drives are strongly recommended. A slow chain sync can lead to delays in critical messages being sent on-chain from your Lotus miner, resulting in the faulting of sectors and the slashing of collateral.
Another important consideration is the size of the file system and available free space. Because the Filecoin chain grows as much as 50GB a day, any available space will eventually fill up. It is up to storage providers to manage the size of the chain on disk and prune it as needed. Solutions like SplitStore and compacting reduce the storage space used by the chain. Compacting involves replacing the built-up chain data with a recent lightweight snapshot.
Holding wallets
Another key role of the Lotus daemon is to host the Filecoin wallets that are required to run a storage provider (SP). As an SP, you will need a minimum of 2 wallets: an owner wallet and a worker wallet. A third wallet called the control wallet is required to scale your operations in a production environment.
To keep wallets safe, providers should consider physical access, network access, software security, and secure backups. As with any cryptocurrency wallet, access to the private key means access to your funds. Lotus supports Ledger hardware wallets, the use of which is recommended. The worker and control wallets can not be kept on a hardware device because Lotus requires frequent access to those types of wallets. For instance, Lotus may require access to a worker or control wallet to send WindowPoSt proofs on-chain.
Control wallets
Control wallets are required to scale your operations in a production environment. In production, only using the general worker wallet increases the risk of message congestion, which can result in delayed message delivery on-chain and potential sector faulting, slashing, or lost block rewards. It is recommended that providers create wallets for each subprocess. There are five different types of control wallets a storage provider can create:
- PoSt wallet
- PreCommit wallet
- Commit wallet
- Publish storage deals wallet
- Terminate wallet
Lotus miner
The Lotus miner, often referred to using the daemon naming syntax lotus-miner, is the process that coordinates most of the storage provider activities. It has 3 main responsibilities:
- Storing sectors and data
- Scheduling jobs
- Proving the stored data
Storing sectors and data
Storage Providers on the Filecoin network store sectors. There are two types of sectors that a provider may store:
- Sealed sectors: these sectors may or may not actually contain data, but they provide capacity to the network, for which the provider is rewarded.
- Unsealed sectors: used when storing data deals, as retrievals happen from unsealed sectors.
Originally, lotus-miner was the component with storage access. This resulted in lotus-miner hardware using internal disks, directly attached storage shelves like JBODs, Network-Attached-Storage (NAS), or a storage cluster. However, this design introduced a bottleneck on the Lotus miner.
More recently, Lotus has added a more scalable storage access solution in which workers can also be assigned storage access. This removes the bottleneck from the Lotus miner. Low-latency storage access is critical because of the impact on storage-proving processes.
Keeping a backup of your sealed sectors, the cache directory, and any unsealed sectors is crucial. Additionally, you should keep a backup of the sectorstore.json file that lives under your storage path. The sectorestore.json file is required to restore your system in the event of a failure. You can read more about the sectorstore.json file in the lotus docs.
It is also imperative to have at least a daily backup of your lotus-miner state. Backups can be made with:
lotus-miner backup
The sectorstore.json file, which lives under your storage path, is also required for restoration in the event of a failure. You can read more about the file in the Lotus docs.
Scheduling jobs
Another key responsibility of the Lotus Miner is the scheduling of jobs for the sealing pipeline and storage proving.
Storage proving
One of the most important roles of lotus-miner is the Storage proving. Both WindowPoSt and WinningPoSt processes are usually handled by the lotus-miner process. For scalability and reliability purposes it is now also possible to run these proving processes on dedicated servers (proving workers) instead of using the Lotus miner.
The proving processes require low-latency access to sealed sectors. The proving challenge requires a GPU to run on. The resulting zkProof will be sent to the chain in a message. Messages must arrive within 30 minutes for WindowPoSt, and 30 seconds for WinningPoSt. It is extremely important that providers properly size and configure the proving workers, whether they are using just the Lotus miner or separate workers. Additionally, dedicated wallets, described in Control wallets, should be set up for these processes.
Always check if there are upcoming proving deadlines before halting any services for maintenance. For detailed instructions, refer to the Lotus maintenance guide.
Lotus worker
The Lotus worker is another important component of the Lotus architecture. There can be - and most likely will be - multiple workers in a single storage provider setup. Assigning specific roles to each worker enables higher throughput, sealing rate, and improved redundancy.
As mentioned above, proving tasks can be assigned to dedicated workers, and workers can also get storage access. The remaining worker tasks encompass running a sealing pipeline, which is discussed in the next section.
Helpful commands
The following commands can help storage providers with their setup.
Backup Lotus miner state
It is imperative to have at least one daily backup of your Lotus miner state. Backups can be made using the following command:
lotus-miner backup
View wallets and funds
You can use the following command to view wallets and their funds:
lotus wallet list
Check storage configuration
Run the following command to check the storage configuration for your Lotus miner instance:
lotus-miner storage list
This command return information on your sealed space and your scratch space, otherwise known as a cache. These spaces are only available if you have properly configured your Lotus miner by following the steps described in the Lotus documentation.
View scheduled jobs
To view the scheduled sealing jobs, run the following:
lotus-miner sealing jobs
View available workers
To see the workers on which the miner can schedule jobs, run:
lotus-miner sealing workers
View proving deadlines
To check if there are upcoming proving deadlines, run the following:
lotus-miner proving deadlines