BasicsStorage providersNodesNetworksSmart contractsReference
Edit

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:

  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"

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.

  1. Clone the repository:\

  2. Checkout to the latest stable branch:\

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

Build

  1. Create the 2k binary for Lotus:\

    This will output something like:\

    This process will take about 5 minutes to complete.

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

    This will output something like:\

    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:\

    This will output something like:\

  4. Create the genesis block:\

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

    This will output something like:\

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:\

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

    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:\

    This will output something like:\

    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:\

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

  4. Import the genesis miner key:\

    This will output something like:\

  5. Initialize the genesis miner:\

    This will output something like:\

    This process take a few minutes to complete.

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

    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:\

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

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

    This will output something like:\

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

    This will output something like:\

  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:\

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

    This will output something like:\

    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:\

    For example:\

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

    For example:\

  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:\

    This will output something like:\

  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:\

  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:\

  2. Start the client node with lotus daemon:\

    This will output something like:\

    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:\

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

    This will output something like:\

  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:

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).

Was this page helpful?

PreviousRPCsNextGet test tokens

Last updated

Was this helpful?