Local testnet

Local networks are a useful way to get started with Filecoin development. This guide covers how to start a local network using Lotus as the Filecoin node implementation.

Setup

A Filecoin network has two node types: storage provider nodes and client nodes. In our local developer network (devnet), we’re going to create a single storage provider node to handle our requests, and we’ll also create a client node to pass information into our network. Both of these nodes run in the terminal. In total, we’ll have three terminal windows open at once.

Prerequisites

The nodes we’re going to run have relatively lightweight hardware requirements. However, since we’re running multiple instances at once it’s recommended that your computer meets the following requirements:

1. At least 8 GiB of RAM

2. A quad-core CPU.

3. (Optional) Because parts of this tutorial require multiple terminal windows, install a terminal multiplexer like Tmux.

Steps

To build the nodes, you’ll need some specific software. Run the following command to install the software prerequisites:

MacOS

1. Open a terminal window.

2. Check that you have Homebrew installed.\

   brew --version
   
   # Homebrew 3.6.18
   # ...

   If you do not see a version number. or receive an error message, install Homebrew.

3. Ensure you have XCode installed.\

   xcode-select -p
   
   # /Library/Developer/CommandLineTools

   If you do not see the output above. or receive an error message, install XCode.

4. Install the following dependencies:\

   brew install go bzr jq pkg-config hwloc coreutils

5. Install Rust:\

   curl https://sh.rustup.rs -sSf | sh -s -- -y
   
   
   # ...
   # Rust is installed now. Great!    
   # ...

6. Source the ~/.cargo/env config file:\

   source "$HOME/.cargo/env"

Ubuntu

1. Install the following dependencies:\

   sudo apt update -y
   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

2. Install Go and add /usr/local/go/bin to your $PATH variable:\

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

3. You may need to export /usr/local/go/bin to your $PATH. This process changes depending on which shell you’re using:

Shell	Export to $PATH example
Bash	echo 'export PATH=$PATH:/usr/local/go/bin' >> ~/.bashrc && source ~/.bashrc
ZSH	echo 'export PATH=$PATH:/usr/local/go/bin' >> ~/.zshrc && source ~/.zshrc

4. Install Rust and source the ~/.cargo/env config file:

curl https://sh.rustup.rs -sSf | sh -s -- -y
source "$HOME/.cargo/env"

5. Done! You can move on to the Pre-build section.

Pre-build

Before we can build the Lotus binaries, there’s some setup we need to do. We’ll create the executable binaries within a new ~/lotus-devnet.

MacOS Intel

1. Clone the repository:\

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

2. Checkout to the latest stable branch:\

   git checkout releases

3. Done! You can move on to the Build section.

MacOS ARM

1. Clone the repository into a new ~/lotus-devnet directory:\

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

2. Checkout to the latest stable branch:\

   git checkout releases

3. Create the necessary environment variables to allow Lotus to run on M1 architecture:\

   export LIBRARY_PATH=/opt/homebrew/lib
   export FFI_BUILD_FROM_SOURCE=1
   export PATH="$(brew --prefix coreutils)/libexec/gnubin:/usr/local/bin:$PATH"

4. Done! You can move on to the Build section.

Ubuntu

1. Clone the repository into a new ~/lotus-devnet directory:\

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

2. Checkout to the latest stable branch:\

   git checkout releases

3. If your processor was released later than an AMD Zen or Intel Ice Lake CPU, enable the use of SHA extensions by adding these two environment variables:\

   export RUSTFLAGS="-C target-cpu=native -g"
   export FFI_BUILD_FROM_SOURCE=1

   If in doubt, ignore this command and move on to the next section.

4. Done! You can move on to the Build section.

Build

1. Create 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'
   Submodule 'extern/serialization-vectors' (https://github.com/filecoin-project/serialization-vectors.git) registered for path 'extern/serialization-vectors'
   
   ...

   This process will take about 5 minutes to complete.

2. Fetch the proving parameters for a 2048-byte sector size:\

   ./lotus fetch-params 2048

   This will output something like:\

   2023-01-31T10:44:43.058-0400    INFO    paramfetch      go-paramfetch@v0.0.4/paramfetch.go:244  Fetching /var/tmp/filecoin-proof-parameters/v28-proof-of-spacetime-fallback-merkletree-poseidon_hasher-8-8-0-559e581f022bb4e4ec6e719e563bf0e026ad6de42e56c18714a2c692b1b88d7e.vk from https://proofs.filecoin.io/ipfs
   2023-01-31T10:44:43.058-0400    INFO    paramfetch      go-paramfetch@v0.0.4/paramfetch.go:262  GET https://proofs.filecoin.io/ipfs/QmZCvxKcKP97vDAk8Nxs9R1fWtqpjQrAhhfXPoCi1nkDoF 13.32 KiB / 13.32 KiB [===========================================================================================================================================] 100.00% 155.63 KiB/s 0
   
   ...

   This process downloads a few files totalling to around 2 GiB in size. Depending on your internet speed, this process can take a few minutes to complete.

3. Pre-seal two sectors for the genesis block:\

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

   This will output something like:\

   sector-id: {{1000 1} 5}, piece info: {2048 baga6ea4seaqf7ovs6euxa4ktencg2gza7lua32l2ugqu76uqgvnjocek6gtoufi}
   2023-01-31T10:49:46.562-0400    WARN    preseal seed/seed.go:175        PreCommitOutput: {{1000 1} 5} bagboea4b5abcamxkzmzcciabqqk3xuuvj3k23nfuojboopyw3kg2mblhj6mzipii baga6ea4seaqf7ovs6euxa4ktencg2gza7lua32l2ugqu76uqgvnjocek6gtoufi
   2023-01-31T10:49:46.562-0400    WARN    preseal seed/seed.go:100        PeerID not specified, generating dummy
   
   ...

4. Create the genesis block:\

   ./lotus-seed genesis new localnet.json

5. Create a pre-miner and an address with some funds:\

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

   This will output something like:\

   2023-01-31T10:52:03.855-0400    INFO    lotus-seed      lotus-seed/genesis.go:129       Adding miner t01000 to genesis template
   2023-01-31T10:52:03.855-0400    INFO    lotus-seed      lotus-seed/genesis.go:146       Giving t3q4o7gkwe7p7xokhgws4rwntj7yqfhpj5pm6cqc7dycl7cwk4uvgh2odwdvge5re7ne5gcc6xluifss5uu5cq some initial balance

Our Lotus installation is now ready to start running the nodes!

Start the nodes

As mentioned earlier, we will be running two types of a node: a storage provider node and a client node. In the Lotus project, a storage provider node is referred to as a miner. Since we’re going to run multiple nodes, you’ll need to have at least three terminal windows open. If your terminal emulator supports tabs, consider using them to help organize your setup.

Client

1. Open a new terminal window.

2. Move into the ~/lotus-devnet directory:\

   cd ~/lotus-devnet

3. Export the devnet-specific variables again to make sure we don’t interfere with any existing Lotus installations on your system:\

   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__"

   Because environmental variables are reset when you open a new terminal window, these variables must be exported every time we start a new terminal.

4. Start the client node using lotus daemon:\

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

   This will output something like:\

   2023-01-31T10:57:41.022-0400    INFO    main    lotus/daemon.go:218     lotus repo: /home/johnny/.lotus
   2023-01-31T10:57:41.022-0400    INFO    repo    repo/fsrepo.go:265      Initializing repo at '/home/johnny/.lotus'
   2023-01-31T10:57:41.022-0400    INFO    paramfetch      go-paramfetch@v0.0.4/paramfetch.go:209  Parameter file /var/tmp/filecoin-proof-parameters/v28-stacked-proof-of-replication-merkletree-poseidon_hasher-8-0-0-sha256_hasher-ecd683648512ab1765faa2a5f14bab48f676e633467f0aa8aad4b55dcb0652bb.vk is ok 

   This command will continue to run. Leave this window open.

Storage provider

1. Open a new terminal window.

2. Move into the ~/lotus-devnet directory:\

   cd ~/lotus-devnet

3. Export the devnet-specific variables again to make sure we don’t interfere with any existing Lotus installations on your system:\

   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__"

4. Import the genesis miner key:\

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

   This will output something like:\

   imported key t3q4o7gkwe7p7xokhgws4rwntj7yqfhpj5pm6cqc7dycl7cwk4uvgh2odwdvge5re7ne5gcc6xluifss5uu5cq successfully!

5. Initialize the genesis miner:\

   ./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 will output something like:\

   2023-01-31T11:04:46.148-0400    INFO    main    lotus-miner/init.go:130 Initializing lotus miner
   2023-01-31T11:04:46.148-0400    INFO    main    lotus-miner/init.go:157 Checking proof parameters
   
   ...
   
   2023-01-31T11:04:46.148-0400    INFO    main    lotus-miner/init.go:283 Miner successfully created, you can now start it with 'lotus-miner run'

   This process take a few minutes to complete.

6. Start the storage provider node with lotus-miner run:\

   ./lotus-miner run --nosync 

   This terminal window will continue to run. You must run all further commands from a new terminal window.

We now have a client node and a storage provider node successfully talking to each other! Next up, we can send requests to our client node to ensure everything is set up correctly.

Get some FIL

Now that we’ve got our local devnet running let’s create a new wallet and send some funds from our miner account to that new wallet.

Create a wallet

There are multiple ways to create a new wallet. The simplest way is to use the Lotus CLI directly:

1. Open a new terminal window.

2. Move into the ~/lotus-devnet directory:\

   cd ~/lotus-devnet

3. Export the devnet-specific variables again to make sure we don’t interfere with any existing Lotus installations on your system:\

   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__"

4. Create a new wallet with lotus wallet new:\

   ./lotus wallet new

   This will output something like:\

   t1snly7vh4mjtjznwze56ihrdhzfwvbajywwmrenq

5. View the wallets available on this node with lotus wallet list:\

   ./lotus wallet list

   This will output something like:\

   Address                                                                                 Balance                          Nonce  Default
   t1snly7vh4mjtjznwze56ihrdhzfwvbajywwmrenq                                               0 FIL                            0
   t3q4o7gkwe7p7xokhgws4rwntj7yqfhpj5pm6cqc7dycl7cwk4uvgh2odwdvge5re7ne5gcc6xluifss5uu5cq  49999999.999763880085417692 FIL  2      X

6. You can now close this terminal window, or you can keep it open for the next section.

Send funds

We can now send FIL from the pre-mined t3q4o7g... account to our new t1snly7... account with lotus send:

1. If you closed the terminal windows from the last section, open a new terminal window, move into the ~/lotus-devnet directory, and export the devnnet-specific variables again with:\

   cd ~/lotus-devnet
   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. View the wallets available on this node with lotus wallet list:\

   ./lotus wallet list

   This will output something like:\

   Address                                                                                 Balance                          Nonce  Default
   t1snly7vh4mjtjznwze56ihrdhzfwvbajywwmrenq                                               0 FIL                            0
   t3q4o7gkwe7p7xokhgws4rwntj7yqfhpj5pm6cqc7dycl7cwk4uvgh2odwdvge5re7ne5gcc6xluifss5uu5cq  49999999.999763880085417692 FIL  2      X

   In the above example, the t3q4o... address is the pre-mined address we created in an earlier step. This has a very large balance of FIL. We want to send FIL from this pre-mined address to our new t1snl... address.

3. Create the send request with lotus send, supplying the pre-mined t3q4o... address as the --from address, the new t1snl... address as the receiving address, and the amount of FIL we want to send:\

   ./lotus send --from <PRE-MINED ADDRESS> <TO ADDRESS> <VALUE>

   For example:\

   ./lotus send --from t3q4o7gkwe7p7xokhgws4rwntj7yqfhpj5pm6cqc7dycl7cwk4uvgh2odwdvge5re7ne5gcc6xluifss5uu5cq t1snly7vh4mjtjznwze56ihrdhzfwvbajywwmrenq 2000
   
   # bafy2bzaceaqzbgiazwvtpago6wpkxl42puxfkvwv5cwjpime2irqatamji2bq

4. Check the balance of your new t1snl... address with lotus wallet balance:\

   ./lotus wallet balance <ADDRESS>

   For example:\

   ./lotus wallet balance t1snly7vh4mjtjznwze56ihrdhzfwvbajywwmrenq
   
   # 2000 FIL

5. You can now close this terminal window, or you can keep it open for the next section.

Stop and restart

You’ll eventually want to stop your local devnet from running or may need to restart it. Follow these steps.

Stop the devnet

1. Open the storage provider terminal window.

2. Press CTRL + c to stop the node. The node will print Graceful shutdown successful once it has fully stopped:\

   # CTRL + c 

   This will output something like:\

   ...
   
   2023-02-14T10:54:42.030-0400    DEBUG   advmgr  sealer/sched_worker.go:603      worker 1fa5f6b1-eb4d-4d92-98b1-6114a0d7695d dropped
   2023-02-14T10:54:42.056-0400    INFO    builder node/shutdown.go:44     miner shut down successfully
   2023-02-14T10:54:42.056-0400    WARN    builder node/shutdown.go:47     Graceful shutdown successful

3. You can now close the storage provider terminal window.

4. Open the client terminal window.

5. Press CTRL + c to stop the node. The node will print Graceful shutdown successful once it has fully stopped:\

   ...
   
   2023-02-14T10:55:42.475-0400    INFO    badgerbs        v2@v2.2007.3/db.go:554  Force compaction on level 0 done
   2023-02-14T10:55:42.502-0400    INFO    builder node/shutdown.go:44     node shut down successfully
   2023-02-14T10:55:42.502-0400    WARN    builder node/shutdown.go:47     Graceful shutdown successful

6. You can now close the client terminal window.

Restart the devnet

1. Open a new terminal window, move into the ~/lotus-devnet directory, and export the devnnet-specific variables again with:\

   cd ~/lotus-devnet
   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. Start the client node with lotus daemon:\

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

   This will output something like:\

   2023-01-31T10:57:41.022-0400    INFO    main    lotus/daemon.go:218     lotus repo: /home/johnny/.lotus
   2023-01-31T10:57:41.022-0400    INFO    repo    repo/fsrepo.go:265      Initializing repo at '/home/johnny/.lotus'
   2023-01-31T10:57:41.022-0400    INFO    paramfetch      go-paramfetch@v0.0.4/paramfetch.go:209  Parameter file /var/tmp/filecoin-proof-parameters/v28-stacked-proof-of-replication-merkletree-poseidon_hasher-8-0-0-sha256_hasher-ecd683648512ab1765faa2a5f14bab48f676e633467f0aa8aad4b55dcb0652bb.vk is ok 

   This command will continue to run. Leave this window open.

3. For the storage provider node, open a new terminal window, move into the ~/lotus-devnet directory, and export the devnnet-specific variables again with:\

   cd ~/lotus-devnet
   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__"

4. Restart the storage provider node with lotus-miner run:\

   ./lotus-miner run --nosync

   This will output something like:\

   2023-01-31T12:54:12.009-0400    INFO    main    lotus-miner/run.go:98   Checking full node sync status
   2023-01-31T12:54:12.013-0400    INFO    modules modules/core.go:64      memory limits initialized    {"max_mem_heap": 0, "total_system_mem": 16444395520, "effective_mem_limit": 16444395520}
   2023-01-31T12:54:12.013-0400    WARN    modules modules/core.go:124     failed to initialize cgroup-driven watchdog; err: failed to load cgroup for process: cgroups: cgroup mountpoint does not exist

5. This command will continue to run. Leave this window open.

6. You must run all further commands from a new terminal window.

Next steps

To summarize, you’ve started a local devnet, funded a new address, and exported that address to a file! You’ve got all the pieces ready to start developing applications on Filecoin!

Troubleshooting

Running into issues? Check out these troubleshooting steps to figure out what’s going on.

Could not get API info for FullNode

You may encounter the following error message:

ERROR: could not get API info for FullNode: could not get api endpoint: API not running (no endpoint

If you receive this error when trying to call your Lotus daemon, either your lotus daemon isn’t running (see Restart the devnet) or you haven’t re-exported the necessary variables (see the Build section).