Local network

Running a Filecoin network locally can be extremely useful for developers wanting to build and test their applications. This page provides guidance on different methods to run a Filecoin network locally.

You can spin up a local network (local-net) using the regular Lotus binaries. This method will launch Lotus using 2 KiB sectors, allowing systems with fewer resources to run a local-net. This solution runs comfortably on a computer with 2 CPU cores and 4 GB RAM.

This process requires you to use multiple terminal windows, so you might find a terminal multiplexer like Tmux helpful. However, you can easily complete this tutorial by just having several terminal windows open. The screenshots in this guide use Tmux.

Install Lotus

Since spinning up a local-net requires the lotus daemon, you need to have Lotus installed. If you have already installed a Lotus node on this computer you can move onto the next section ↓

Run through the installation steps for your operating system, then return here.

Environment setup

Local-nets use slightly different binaries to those used in the Filecoin mainnet. This section shows you how to setup the Lotus environment and build those binaries.

  1. Create the following environment variable in your terminal:

    export LOTUS_PATH=~/.lotus-local-net
export LOTUS_MINER_PATH=~/.lotus-miner-local-net
export LOTUS_SKIP_GENESIS_CHECK=_yes_
export CGO_CFLAGS_ALLOW="-D__BLST_PORTABLE__"
export CGO_CFLAGS="-D__BLST_PORTABLE__"

  2. Clone Lotus repo:

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

    The filecoin-project/lotus repository is the same one that you would use to join the Filecoin mainnet. The git clone command puts the Lotus repository into the lotus-local-net folder to keep this guide organized.

  3. Checkout to the latest branch:

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

  4. Remove any existing repositories.

    rm -rf ~/.genesis-sectors

  5. Build the 2k binary for Lotus:

    make 2k

    This will output something like:

    git submodule update --init --recursive
Submodule 'extern/filecoin-ffi' (https://github.com/filecoin-project/filecoin-ffi.git) registered for path 'extern/filecoin-ffi'
...
go build  -ldflags="-X=github.com/filecoin-project/lotus/build.CurrentCommit=+git.8d5be1c01" -tags=2k -o lotus-gateway ./cmd/lotus-gateway

  6. Grab the 2048 byte parameters:

    ./lotus fetch-params 2048

    This will output something like:

    2021-02-23T10:58:01.469-0500    INFO    build   go-paramfetch@v0.0.2-0.20200701152213-3e0f0afdc261/paramfetch.go:138  Parameter file /var/tmp/filecoin-proof-parameters/v28-proof-of-spacetime-fallback-merkletree-poseidon_hasher-8-0-0-0cfb4f178bbb71cf2ecfcd42accce558b27199ab4fb59cb78f2483fe21ef36d9.vk is ok
...
c261/paramfetch.go:162  parameter and key-fetching complete

  7. Pre-seal some sectors for the genesis block:

    ./lotus-seed pre-seal --sector-size 2KiB --num-sectors 2

    This will output something like:

    sector-id: {{1000 0} 0}, piece info: {2048 baga6ea4seaqoej3hzxzqr5y25ibovtjrhed7yba5vm6gwartr5hsgcbao7aluki}
...
2021-02-23T10:59:36.937-0500    INFO    preseal seed/seed.go:232        Writing preseal manifest to /home/user/.genesis-sectors/pre-seal-t01000.json

  8. Create the genesis block:

    ./lotus-seed genesis new localnet.json

    This command does not output anything on success.

  9. Create a default address and give it some funds:

    ./lotus-seed genesis add-miner localnet.json ~/.genesis-sectors/pre-seal-t01000.json

    This will output something like:

    2022-02-08T15:44:19.734-0500    INFO    lotus-seed      lotus-seed/genesis.go:129       Adding miner t01000 to genesis template
2022-02-08T15:44:19.734-0500    INFO    lotus-seed      lotus-seed/genesis.go:146       Giving t3xe5je75lkrvye32tfl37gug3az42iotuu3wxgkrhbpbvmum4lu26begiw74ju5a35nveqaw4ywdibj4y6kxq some initial balance

Start the nodes

Now that you’ve got everything setup, you can start the lotus and lotus-miner nodes.

  1. Start the first node:

    ./lotus daemon --lotus-make-genesis=devgen.car --genesis-template=localnet.json --bootstrap=false

    This command will output a lot of information and continue to run. All further steps should be completed in a new terminal window.

  2. Create a new terminal window or tab and re-export the LOTUS_PATH and LOTUS_MINER_PATH variables:

    export LOTUS_PATH=~/.lotus-local-net
export LOTUS_MINER_PATH=~/.lotus-miner-local-net
export LOTUS_SKIP_GENESIS_CHECK=_yes_
export CGO_CFLAGS_ALLOW="-D__BLST_PORTABLE__"
export CGO_CFLAGS="-D__BLST_PORTABLE__"

  3. Import the genesis miner key:

    ./lotus wallet import --as-default ~/.genesis-sectors/pre-seal-t01000.key

    This will output something like:

    imported key t3xe5je75lkrvye32tfl37gug3az42iotuu3wxgkrhbpbvmum4lu26begiw74ju5a35nveqaw4ywdibj4y6kxq successfully!

  4. Set up the genesis miner. This process can take a few minutes:

    ./lotus-miner init --genesis-miner --actor=t01000 --sector-size=2KiB --pre-sealed-sectors=~/.genesis-sectors --pre-sealed-metadata=~/.genesis-sectors/pre-seal-t01000.json --nosync

    This process may take a few minutes. When complete, the terminal window will display:

    Miner successfully created, you can now start it with 'lotus-miner run'

  5. Start the miner:

    ./lotus-miner run --nosync

    This command will output a lot of information and continue to run. You should now have two programs running at once - the lotus node and this lotus-miner. All further steps should be completed in a new terminal window.

Next steps

You now have a fully functioning Filecoin local network! You can start testing your setup and playing with the Filecoin network in a safe and fast environment.

Edit this page on GitHub

← Troubleshooting