Lotus
Lotus is the reference implementation for the Filecoin network.
Lotus is the reference implementation for the Filecoin network. It is written in Go, and is maintained by the Protocol Labs team.
Filecoin is a decentralized storage network designed to enable users to store, retrieve, and transfer data in a secure and decentralized manner. Lotus is one of the software implementations of the Filecoin network. Filecoin mining refers to the process of contributing computational resources and storage capacity to the network, while earning Filecoin (FIL) tokens as a reward. Miners can run the Lotus software on their hardware to connect to the network, store data, and engage in mining activities.
Lotus is an open-source project developed by Protocol Labs, the company behind Filecoin. It provides the core software infrastructure for participating in the Filecoin network, including the ability to run Filecoin nodes, interact with the network, and manage storage and retrieval of data.
Install Lotus
You can run the Lotus software client to join the Filecoin Testnet. Lotus can run on MacOS and Linux. Windows is not supported yet.
To run a Lotus node your computer must have:
- macOS or Linux installed. Windows is not yet supported.
- 8-core CPU and 32 GiB RAM. Models with support for Intel SHA Extensions (AMD since Zen microarchitecture or Intel since Ice Lake) will significantly speed things up.
- Enough space to store the current Lotus chain (preferably on an SSD storage medium). The chain grows at approximately 38 GiB per day. The chain can be synced from trusted state snapshots and compacted or pruned.
These are the minimal requirements to run a Lotus node. Hardware requirements for storage providers are different.
Lotus Components
Lotus is a command-line application that lets you interact with Filecoin. You can do this by uploading and downloading files, renting out your storage to other users, and checking that computers are storing data correctly. The Lotus project is split into three main applications: the lotus daemon, lotus miner, and lotus worker.
The lotus daemon is available as a client for users to store data, the miner daemon is for storage providers to rent their storage to users, and the worker daemon allows storage-providers to split tasks across multiple computers.
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.
For information on how to view wallets and their funds, see Helpful commands.
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.
For information on how to check the storage configuration for your Lotus miner instance, see Helpful commands.
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
For information on how to back up Lotus miner state, see Helpful commands.
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.
For information on how to view scheduled jobs, see View scheduled jobs. For information on how to see the workers on which the miner can schedule jobs, see View available workers.
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.
For information on how to check if there are upcoming proving deadlines, see Helpful commands.
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 deadlinesInteract With Lotus
There are many ways to interact with a Lotus node, depending on your specific needs and interests. By leveraging the powerful tools and APIs provided by Lotus, you can build custom applications, extend the functionality of the network, and contribute to the ongoing development of the Filecoin ecosystem.
Lotus API
Lotus provides a comprehensive API that allows developers to interact with the Filecoin network programmatically. The API includes methods for performing various operations such as storing and retrieving data, mining blocks, and transferring FIL tokens. You can use the API to build custom applications or integrate Filecoin functionality into your existing applications.
Lotus CLI
Lotus includes a powerful command-line interface that allows developers to interact with the Filecoin network from the terminal. You can use the CLI to perform various operations such as creating wallets, sending FIL transactions, and querying the network. The CLI is a quick and easy way to interact with the network and is particularly useful for testing and development purposes.
Custom Plugin
Lotus is designed to be modular and extensible, allowing developers to create custom plugins that add new functionality to the network. You can develop plugins that provide custom storage or retrieval mechanisms, implement new consensus algorithms, or add support for new network protocols.
Source Contributions
If you are interested in contributing to the development of Lotus itself, you can do so by contributing to the open-source codebase on GitHub. You can submit bug reports, suggest new features, or submit code changes to improve the functionality, security, or performance of the network.