Lite-nodes are a simplified node option that allows developers to perform lightweight tasks on a local node. This page covers how to spin up a lite node on your local machine.

Spin up a lite-node

In this guide, we will use the Lotus Filecoin implementation to install a lite-node on MacOS and Ubuntu. For other Linux distributions, check out the Lotus documentation. To run a lite-node on Windows, install WSL with Ubuntu on your system and follow the Ubuntu instructions below.

Prerequisites

Lite-nodes have relatively lightweight hardware requirements. Your machine should meet the following hardware requirements:

  1. At least 2 GiB of RAM
  2. A dual-core CPU.
  3. At least 4 GiB of storage space.

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

MacOS
Ubuntu
  1. Ensure you have XCode and Homebrew installed.

  2. Install the following dependencies:

    brew install go jq pkg-config hwloc coreutils rust

  1. Install the following dependencies:

    sudo apt update -y
sudo apt install mesa-opencl-icd ocl-icd-opencl-dev gcc git 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. Lotus v1.36.0 requires Go 1.25.7; check the current Lotus release go.mod before pinning a newer release:

    wget https://go.dev/dl/go1.25.7.linux-amd64.tar.gz
sudo rm -rf /usr/local/go && sudo tar -C /usr/local -xzf go1.25.7.linux-amd64.tar.gz
echo 'export PATH=$PATH:/usr/local/go/bin' >> ~/.bashrc && source ~/.bashrc

  3. Install Rust, choose the standard installation option, and source the ~/.cargo/env config file:

    curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source "$HOME/.cargo/env"

Pre-build

Before we can build the Lotus binaries, we need to follow a few pre-build steps. MacOS users should select their CPU architecture from the tabs:

MacOS Intel
MacOS ARM
Ubuntu

  1. Clone the repository and move into the lotus directory:

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

  2. Retrieve the latest Lotus release version and store it in your shell:

    LOTUS_RELEASE="$(git tag --list 'v*' --sort=-v:refname | grep -v '-' | head -n 1)"
echo "$LOTUS_RELEASE"

    This should output something like:

    v1.36.0

  3. Check out the release returned from the previous command:

    git checkout "$LOTUS_RELEASE"
  4. Done! You can move on to the Build section.

  1. Clone the repository and move into the lotus directory:

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

  2. Retrieve the latest Lotus release version and store it in your shell:

    LOTUS_RELEASE="$(git tag --list 'v*' --sort=-v:refname | grep -v '-' | head -n 1)"
echo "$LOTUS_RELEASE"

    This should output something like:

    v1.36.0

  3. Check out the release returned from the previous command:

    git checkout "$LOTUS_RELEASE"

  4. 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"
  5. Done! You can move on to the Build section.

  1. Clone the repository and move into the lotus directory:

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

  2. Retrieve the latest Lotus release version and store it in your shell:

    LOTUS_RELEASE="$(git tag --list 'v*' --sort=-v:refname | grep -v '-' | head -n 1)"
echo "$LOTUS_RELEASE"

    This should output something like:

    v1.36.0

  3. Check out the release returned from the previous command:

    git checkout "$LOTUS_RELEASE"

  4. If your processor was released later than an AMD Zen or Intel Ice Lake CPU, enable SHA extensions by adding these two environment variables. If in doubt, ignore this command and move on to the next section.

    export RUSTFLAGS="-C target-cpu=native -g"
export FFI_BUILD_FROM_SOURCE=1
  5. Done! You can move on to the Build section.

Build the binary

The last thing we need to do to get our node setup is to build the package. The command you need to run depends on which network you want to connect to:

Mainnet
Calibration

  1. Remove or delete any existing Lotus configuration files on your system:

    if [ -d ~/.lotus ]; then mv ~/.lotus ~/.lotus-backup-$(date +%Y%m%d%H%M%S); fi

  2. Make the Lotus binaries and install them:

    make clean lotus
sudo make install-daemon

  3. Once the installation finishes, query the Lotus version to ensure everything is installed successfully and for the correct network:

    lotus --version

    This will output something like:

    lotus version 1.36.0+mainnet+git.<commit>

  1. Remove or delete any existing Lotus configuration files on your system:

    if [ -d ~/.lotus ]; then mv ~/.lotus ~/.lotus-backup-$(date +%Y%m%d%H%M%S); fi

  2. Make the Lotus binaries and install them:

    make clean && make calibnet-lotus
sudo make install-daemon

  3. Once the installation finishes, query the Lotus version to ensure everything is installed successfully and for the correct network:

    lotus --version

    This will output something like:

    lotus version 1.36.0+calibnet+git.<commit>

Start the node

Let's start the lite-node by connecting to a remote full-node. We can use the public full-nodes from glif.io:

Mainnet
Calibration

  1. Create an environment variable called FULLNODE_API_INFO and set it to the WebSockets address of the node you want to connect to. At the same time, start the Lotus daemon with the --lite tag:

    FULLNODE_API_INFO=wss://wss.node.glif.io/apigw/lotus lotus daemon --lite

    This will output something like:

    2023-01-26T11:18:54.251-0400    INFO    main    lotus/daemon.go:219     lotus repo: /Users/johnny/.lotus
2023-01-26T11:18:54.254-0400    WARN    cliutil util/apiinfo.go:94      API Token not set and requested, capabilities might be limited.
...
  2. The Lotus daemon will continue to run in this terminal window. All subsequent commands we use should be done in a separate terminal window.

  1. Create an environment variable called FULLNODE_API_INFO and set it to the WebSockets address of the node you want to connect to. At the same time, start the Lotus daemon with the --lite tag:

    FULLNODE_API_INFO=wss://wss.calibration.node.glif.io/apigw/lotus lotus daemon --lite

    This will output something like:

    2023-01-26T11:18:54.251-0400    INFO    main    lotus/daemon.go:219     lotus repo: /Users/johnny/.lotus
2023-01-26T11:18:54.254-0400    WARN    cliutil util/apiinfo.go:94      API Token not set and requested, capabilities might be limited.
...
  2. The Lotus daemon will continue to run in this terminal window. All subsequent commands we use should be done in a separate terminal window.

Expose the API

To send JSON-RPC requests to our lite-node, we need to expose the API.

Mainnet
Calibration

  1. Open ~/.lotus/config.toml and uncomment ListenAddress on line 6:

    [API]
  # Binding address for the Lotus API
  #
  # type: string
  # env var: LOTUS_API_LISTENADDRESS
  ListenAddress = "/ip4/127.0.0.1/tcp/1234/http"

  # type: string
  # env var: LOTUS_API_REMOTELISTENADDRESS
  # RemoteListenAddress = ""
...
  2. Open the terminal window where your lite-node is running and press CTRL + c to close the daemon.

  3. In the same window, restart the lite-node:

    FULLNODE_API_INFO=wss://wss.node.glif.io/apigw/lotus lotus daemon --lite

    This will output something like:

    2023-01-26T11:18:54.251-0400    INFO    main    lotus/daemon.go:219     lotus repo: /Users/johnny/.lotus
2023-01-26T11:18:54.254-0400    WARN    cliutil util/apiinfo.go:94      API Token not set and requested, capabilities might be limited
...
  4. The Lotus daemon will continue to run in this terminal window. All subsequent commands we use should be done in a separate terminal window.

  1. Open ~/.lotus/config.toml and uncomment ListenAddress on line 6:

    [API]
  # Binding address for the Lotus API
  #
  # type: string
  # env var: LOTUS_API_LISTENADDRESS
  ListenAddress = "/ip4/127.0.0.1/tcp/1234/http"

  # type: string
  # env var: LOTUS_API_REMOTELISTENADDRESS
  # RemoteListenAddress = ""

...
  2. Open the terminal window where your lite-node is running and press CTRL + c to close the daemon.

  3. In the same window, restart the lite-node:

    FULLNODE_API_INFO=wss://wss.calibration.node.glif.io/apigw/lotus lotus daemon --lite

    This will output something like:

    2023-01-26T11:18:54.251-0400    INFO    main    lotus/daemon.go:219     lotus repo: /Users/johnny/.lotus
2023-01-26T11:18:54.254-0400    WARN    cliutil util/apiinfo.go:94      API Token not set and requested, capabilities might be limited.
...
  4. The Lotus daemon will continue to run in this terminal window. All subsequent commands we use should be done in a separate terminal window.

The lite-node is now set up to accept local JSON-RPC requests! However, we don't have an authorization key, so we won't have access to privileged JSON-RPC methods.

Create a key

To access privileged JSON-RPC methods, like creating a new wallet, we need to supply an authentication key with our Curl requests.

  1. Create a new admin token and set the result to a new LOTUS_ADMIN_KEY environment variable:

    export LOTUS_ADMIN_KEY="$(lotus auth create-token --perm admin)"

  2. Keep this key in your shell only. Do not commit it or paste it into shared logs.

Send requests

Let's run a couple of commands to see if the JSON-RPC API is set up correctly.

  1. First, let's grab the head of the Filecoin network chain:

    curl -X POST 'http://127.0.0.1:1234/rpc/v0' \
-H 'Content-Type: application/json' \
--data '{"jsonrpc":"2.0","id":1,"method":"Filecoin.ChainHead","params":[]}' \
| jq

    This will output something like:

    {
  "jsonrpc": "2.0",
  "result": {
    "Cids": [
      {
        "/": "bafy2bzacead2v2y6yob7rkm4y4snthibuamzy5a5iuzlwvy7rynemtkdywfuo"
      },
      {
        "/": "bafy2bzaced4zahevivrcdoefqlh2j45sevfh5g3zsw6whpqxqjig6dxxf3ip6"
      },
...

  2. Next, let's try to create a new wallet. Since this is a privileged method, we need to supply the auth key from LOTUS_ADMIN_KEY:

    curl -X POST 'http://127.0.0.1:1234/rpc/v0' \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer $LOTUS_ADMIN_KEY" \
--data '{"jsonrpc":"2.0","id":1,"method":"Filecoin.WalletNew","params":["secp256k1"]}' \
| jq

    This will output something like:

    {
  "id": 1,
  "jsonrpc": "2.0",
  "result": "f1vuc4eu2wgsdnce2ngygyzuxky3aqijqe7gj5qqa"
}

    The result field is the public key for our address. The private key is stored within our lite-node.

  3. Set the new address as the default wallet for our lite-node. Replace <WALLET_ADDRESS> with the wallet address returned from the previous command:

    curl -X POST 'http://127.0.0.1:1234/rpc/v0' \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer $LOTUS_ADMIN_KEY" \
--data '{"jsonrpc":"2.0","id":1,"method":"Filecoin.WalletSetDefault","params":["<WALLET_ADDRESS>"]}' \
| jq

    This will output something like:

    {
  "id": 1,
  "jsonrpc": "2.0",
  "result": null
}

Next steps

You should now have a local lite-node connected to a remote full-node with an admin API key! You can use this setup to continue playing around with the JSON-RPC, or start building your applications on Filecoin!

Was this page helpful?