Convert Figma logo to code with AI

filecoin-project logolotus

Reference implementation of the Filecoin protocol, written in Go

2,821
1,248
2,821
665

Top Related Projects

16,006

An IPFS implementation in Go

Go implementation of the Ethereum protocol

2,928

Ongoing Storj v3 development. Decentralized cloud object storage that is affordable, easy to use, private, and secure.

2,681

A BNB Smart Chain client based on the go-ethereum fork

Reference client for NEAR Protocol

Quick Overview

Lotus is an implementation of the Filecoin Distributed Storage Network. It provides a full Filecoin node and miner, as well as tools and APIs for interacting with the Filecoin network. Lotus is written in Go and is designed to be modular, extensible, and performant.

Pros

  • Comprehensive implementation of the Filecoin protocol
  • Active development and community support
  • Extensive documentation and guides
  • Modular architecture allowing for easy customization and extension

Cons

  • High system requirements for running a full node
  • Complex setup process for new users
  • Steep learning curve for understanding the Filecoin ecosystem
  • Performance can be challenging on lower-end hardware

Code Examples

  1. Retrieving chain head:
import "github.com/filecoin-project/lotus/api"

func getChainHead(ctx context.Context, api api.FullNode) (*types.TipSet, error) {
    return api.ChainHead(ctx)
}
  1. Creating a new wallet address:
import "github.com/filecoin-project/lotus/chain/wallet"

func createNewAddress(w *wallet.LocalWallet) (address.Address, error) {
    return w.WalletNew(context.Background(), types.KTBLS)
}
  1. Sending a message:
import "github.com/filecoin-project/lotus/chain/types"

func sendMessage(ctx context.Context, api api.FullNode, from, to address.Address, value types.BigInt) (cid.Cid, error) {
    msg := &types.Message{
        To:     to,
        From:   from,
        Value:  value,
        Method: 0,
    }
    return api.MpoolPushMessage(ctx, msg, nil)
}

Getting Started

To get started with Lotus, follow these steps:

  1. Install dependencies:

    sudo apt update
    sudo apt install mesa-opencl-icd ocl-icd-opencl-dev gcc git bzr jq pkg-config curl
    
  2. Clone the repository:

    git clone https://github.com/filecoin-project/lotus.git
    cd lotus
    
  3. Build and install Lotus:

    make clean all
    sudo make install
    
  4. Start the Lotus daemon:

    lotus daemon
    
  5. Wait for the chain to sync (this may take several hours or days depending on your hardware).

For more detailed instructions and advanced usage, refer to the official Lotus documentation.

Competitor Comparisons

16,006

An IPFS implementation in Go

Pros of Kubo

  • More mature and widely adopted project with a larger community
  • Simpler to set up and use for basic distributed file storage
  • Better documentation and educational resources available

Cons of Kubo

  • Lacks built-in incentive mechanisms for storage providers
  • Limited support for large-scale data storage compared to Lotus

Code Comparison

Kubo (IPFS) node initialization:

cfg, err := config.Init(os.Stdout, 2048)
if err != nil {
    return err
}
node, err := core.NewNode(context.Background(), &core.BuildCfg{
    Online: true,
    Repo:   repo,
})

Lotus node initialization:

fullNode, err := node.New(ctx,
    node.FullNode,
    node.Override(new(modules.Genesis), modules.LoadGenesis(genBytes)),
    node.Repo(r),
)
if err != nil {
    return xerrors.Errorf("failed to construct node: %w", err)
}

Both projects use Go and have similar node initialization patterns, but Lotus includes more complex configuration options related to the Filecoin network and blockchain functionality.

Go implementation of the Ethereum protocol

Pros of go-ethereum

  • More mature and widely adopted project with a larger community
  • Extensive documentation and resources for developers
  • Better performance and scalability for large-scale blockchain operations

Cons of go-ethereum

  • Higher complexity and steeper learning curve for new developers
  • Less focus on storage-specific features compared to Lotus

Code Comparison

go-ethereum

func (s *Ethereum) Start() error {
    if err := s.startEthService(); err != nil {
        return err
    }
    return nil
}

Lotus

func (n *Node) Start(ctx context.Context) error {
    if err := n.startNetworking(ctx); err != nil {
        return err
    }
    return nil
}

Both projects use Go and have similar structure for starting their respective services. However, go-ethereum's codebase is more extensive and complex, reflecting its broader scope and longer development history.

go-ethereum is the official Go implementation of the Ethereum protocol, focusing on supporting the Ethereum blockchain and its smart contract capabilities. Lotus, on the other hand, is the reference implementation for the Filecoin network, which emphasizes decentralized storage.

While go-ethereum has a larger ecosystem and more robust tooling, Lotus offers specialized features for storage providers and users of the Filecoin network. The choice between the two depends on the specific blockchain and use case requirements of the developer or organization.

2,928

Ongoing Storj v3 development. Decentralized cloud object storage that is affordable, easy to use, private, and secure.

Pros of Storj

  • Simpler architecture and easier to set up for developers
  • More focused on decentralized cloud storage, potentially better for specific use cases
  • Active community and regular updates

Cons of Storj

  • Less flexible than Lotus for general-purpose decentralized storage
  • Smaller ecosystem and fewer integrations compared to Filecoin
  • More centralized governance model

Code Comparison

Storj (Go):

func (db *DB) Get(ctx context.Context, bucket, key string) (_ []byte, err error) {
    defer mon.Task()(&ctx)(&err)
    return db.client.GetObject(ctx, bucket, key, minio.GetObjectOptions{})
}

Lotus (Go):

func (a *StorageAPI) Get(ctx context.Context, c cid.Cid) (blocks.Block, error) {
    return a.bs.Get(ctx, c)
}

Both projects use Go and implement similar storage-related functions. Storj's code appears more focused on traditional object storage paradigms, while Lotus is built around content-addressable storage using CIDs.

Storj is tailored for decentralized cloud storage, offering a simpler setup but with less flexibility. Lotus, as part of the Filecoin ecosystem, provides a more comprehensive decentralized storage solution with greater adaptability for various use cases. The choice between them depends on specific project requirements and the desired level of decentralization.

2,681

A BNB Smart Chain client based on the go-ethereum fork

Pros of BSC

  • Higher transaction throughput and lower fees compared to Lotus
  • More established ecosystem with a larger number of dApps and users
  • Easier integration with existing Ethereum-based projects due to EVM compatibility

Cons of BSC

  • More centralized network structure than Lotus, with fewer validators
  • Less focus on data storage and retrieval compared to Lotus' file storage capabilities
  • Potentially higher hardware requirements for running a full node

Code Comparison

BSC (Golang):

func (w *worker) commitTransaction(tx *types.Transaction, coinbase common.Address) ([]*types.Log, error) {
    snap := w.current.state.Snapshot()
    receipt, err := core.ApplyTransaction(w.config, w.chain, &coinbase, w.current.gasPool, w.current.state, w.current.header, tx, &w.current.header.GasUsed, *w.chain.GetVMConfig())
    if err != nil {
        w.current.state.RevertToSnapshot(snap)
        return nil, err
    }
    w.current.txs = append(w.current.txs, tx)
    w.current.receipts = append(w.current.receipts, receipt)
    return receipt.Logs, nil
}

Lotus (Golang):

func (sm *StateManager) ApplyMessage(ctx context.Context, cmsg types.ChainMsg) (*ApplyRet, error) {
    vmopt := &vm.VMOpts{
        StateBase:      sm.cs.GetState(ctx, cmsg.VMMessage().From),
        Epoch:          sm.cs.GetHeight(),
        Rand:           sm.cs.GetRandomness,
        Bstore:         sm.cs.BlockStore(),
        Syscalls:       sm.Syscalls,
        CircSupplyCalc: sm.GetCirculatingSupply,
        NtwkVersion:    sm.GetNtwkVersion,
        BaseFee:        sm.GetBaseFee,
    }
    vmi, err := sm.newVM(ctx, vmopt)
    if err != nil {
        return nil, xerrors.Errorf("failed to create VM: %w", err)
    }
    return sm.applyMessage(ctx, vmi, cmsg)
}

Reference client for NEAR Protocol

Pros of NEAR Core

  • Higher transaction throughput and lower latency
  • More developer-friendly with support for multiple programming languages
  • Simpler sharding mechanism for improved scalability

Cons of NEAR Core

  • Less established ecosystem compared to Filecoin
  • Fewer storage-specific features and optimizations
  • Smaller community and developer base

Code Comparison

NEAR Core (Rust):

pub fn process_block(
    &mut self,
    block: &Block,
    provenance: Provenance,
) -> Result<Option<BlockProcessingArtifact>, Error> {
    // Block processing logic
}

Lotus (Go):

func (syncer *Syncer) ValidateBlock(ctx context.Context, b *types.FullBlock) (err error) {
    // Block validation logic
}

Both projects implement blockchain consensus and block processing, but NEAR Core focuses on general-purpose smart contract execution, while Lotus specializes in decentralized storage. NEAR Core uses Rust for better performance and safety, whereas Lotus is written in Go for simplicity and ease of development.

NEAR Core's sharding approach allows for parallel processing of transactions, potentially offering higher scalability. Lotus, on the other hand, provides more robust storage-related features, making it better suited for decentralized file storage applications.

Convert Figma logo designs to code with AI

Visual Copilot

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot

README

Project Lotus Logo

Project Lotus - 莲


Lotus is an implementation of the Filecoin Distributed Storage Network. For more details about Filecoin, check out the Filecoin Spec.

Building & Documentation

Note: The default master branch is the dev branch, please use with caution. For the latest stable version, checkout the latest release.

For complete instructions on how to build, install and setup lotus, please visit https://lotus.filecoin.io. Basic build instructions can be found further down in this readme.

Reporting a Vulnerability

Please send an email to security@filecoin.org. See our security policy for more details.

Related packages

These repos are independent and reusable modules, but are tightly integrated into Lotus to make up a fully featured Filecoin implementation:

Contributing

We welcome contributions to Lotus! Please see our Contributing Guide for more details on how to get started.

Basic Build Instructions

System-specific Software Dependencies:

Building Lotus requires some system dependencies, usually provided by your distribution.

Ubuntu/Debian:

sudo apt install mesa-opencl-icd ocl-icd-opencl-dev gcc git bzr jq pkg-config curl clang build-essential hwloc libhwloc-dev wget -y && sudo apt upgrade -y

Fedora:

sudo dnf -y install gcc make git bzr jq pkgconfig mesa-libOpenCL mesa-libOpenCL-devel opencl-headers ocl-icd ocl-icd-devel clang llvm wget hwloc hwloc-devel

For other distributions you can find the required dependencies here. For instructions specific to macOS, you can find them here.

Go

To build Lotus, you need a working installation of Go 1.21.7 or higher:

wget -c https://golang.org/dl/go1.21.7.linux-amd64.tar.gz -O - | sudo tar -xz -C /usr/local

TIP: You'll need to add /usr/local/go/bin to your path. For most Linux distributions you can run something like:

echo "export PATH=$PATH:/usr/local/go/bin" >> ~/.bashrc && source ~/.bashrc

See the official Golang installation instructions if you get stuck.

Build and install Lotus

Once all the dependencies are installed, you can build and install the Lotus suite (lotus, lotus-miner, and lotus-worker).

  1. Clone the repository:

    git clone https://github.com/filecoin-project/lotus.git
    cd lotus/
    

Note: The default branch master is the dev branch where the latest new features, bug fixes and improvement are in. However, if you want to run lotus on Filecoin mainnet and want to run a production-ready lotus, get the latest release.

  1. To join mainnet, checkout the latest release.

    If you are changing networks from a previous Lotus installation or there has been a network reset, read the Switch networks guide before proceeding.

    For networks other than mainnet, look up the current branch or tag/commit for the network you want to join in the Filecoin networks dashboard, then build Lotus for your specific network below.

    git checkout <tag_or_branch>
    # For example:
    git checkout <vX.X.X> # tag for a release
    

    Currently, the latest code on the master branch corresponds to mainnet.

  2. If you are in China, see "Lotus: tips when running in China".

  3. This build instruction uses the prebuilt proofs binaries. If you want to build the proof binaries from source check the complete instructions. Note, if you are building the proof binaries from source, installing rustup is also needed.

  4. Build and install Lotus:

    make clean all #mainnet
    
    # Or to join a testnet or devnet:
    make clean calibnet # Calibration with min 32GiB sectors
    
    sudo make install
    

    This will put lotus, lotus-miner and lotus-worker in /usr/local/bin.

    lotus will use the $HOME/.lotus folder by default for storage (configuration, chain data, wallets, etc). See advanced options for information on how to customize the Lotus folder.

  5. You should now have Lotus installed. You can now start the Lotus daemon and sync the chain.

  6. (Optional) Follow the Setting Up Prometheus and Grafana guide for detailed instructions on setting up a working monitoring system running against a local running lotus node.

License

Dual-licensed under MIT + Apache 2.0