Set up
Local networks are a useful way to get started with Filecoin development. Everything happens locally on your computer, and the system requirements are quite low. This guide covers how to start a local network using Lotus as the Filecoin node implementation.
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:
- At least 8 GiB of RAM
- A quad-core CPU.
- (Optional) Because parts of this tutorial require multiple terminal windows, install a terminal multiplexer like Tmux.
To build the nodes, you’ll need some specific software. Run the following command to install the software prerequisites:
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
.
Build
Create the
2k
binary for Lotus:make 2k
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.
Fetch the proving parameters for a 2048-byte sector size:
./lotus fetch-params 2048
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.
Pre-seal two sectors for the genesis block:
./lotus-seed pre-seal --sector-size 2KiB --num-sectors 2
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 ...
Create the genesis block:
./lotus-seed genesis new localnet.json
Create a pre-miner and an address with some funds:
./lotus-seed genesis add-miner localnet.json ~/.genesis-sectors/pre-seal-t01000.json
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
Open a new terminal window.
Move into the
~/lotus-devnet
directory:cd ~/lotus-devnet
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.
Start the client node using
lotus daemon
:./lotus daemon --lotus-make-genesis=devgen.car --genesis-template=localnet.json --bootstrap=false
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
Open a new terminal window.
Move into the
~/lotus-devnet
directory:cd ~/lotus-devnet
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__"
Import the genesis miner key:
./lotus wallet import --as-default ~/.genesis-sectors/pre-seal-t01000.key
imported key t3q4o7gkwe7p7xokhgws4rwntj7yqfhpj5pm6cqc7dycl7cwk4uvgh2odwdvge5re7ne5gcc6xluifss5uu5cq successfully!
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
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.
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:
Open a new terminal window.
Move into the
~/lotus-devnet
directory:cd ~/lotus-devnet
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__"
Create a new wallet with
lotus wallet new
:./lotus wallet new
t1snly7vh4mjtjznwze56ihrdhzfwvbajywwmrenq
View the wallets available on this node with
lotus wallet list
:./lotus wallet list
Address Balance Nonce Default t1snly7vh4mjtjznwze56ihrdhzfwvbajywwmrenq 0 FIL 0 t3q4o7gkwe7p7xokhgws4rwntj7yqfhpj5pm6cqc7dycl7cwk4uvgh2odwdvge5re7ne5gcc6xluifss5uu5cq 49999999.999763880085417692 FIL 2 X
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
:
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__"
View the wallets available on this node with
lotus wallet list
:./lotus wallet list
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 newt1snl...
address.Create the send request with
lotus send
, supplying the pre-minedt3q4o...
address as the--from
address, the newt1snl...
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
Check the balance of your new
t1snl...
address withlotus wallet balance
:./lotus wallet balance <ADDRESS>
For example:
./lotus wallet balance t1snly7vh4mjtjznwze56ihrdhzfwvbajywwmrenq
2000 FIL
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
Open the storage provider terminal window.
Press
CTRL
+c
to stop the node. The node will printGraceful shutdown successful
once it has fully stopped:# CTRL + c
... 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
You can now close the storage provider terminal window.
Open the client terminal window.
Press
CTRL
+c
to stop the node. The node will printGraceful shutdown successful
once it has fully stopped:# CTRL + c
... 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
You can now close the client terminal window.
Restart the devnet
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__"
Start the client node with
lotus daemon
:./lotus daemon --lotus-make-genesis=devgen.car --genesis-template=localnet.json --bootstrap=false
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.
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__"
Restart the storage provider node with
lotus-miner run
:./lotus-miner run --nosync
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
This command will continue to run. Leave this window open.
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).