Basics Storage providers Nodes Networks Smart contracts Reference

Spin up a lite-node

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

In this guide, we’re going to use the Lotus Filecoin implementation. We’ll show how 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 WLS with Ubuntu on your system and follow the Ubuntu instructions below.

Prerequisites

Lite-nodes have relatively lightweight hardware requirements – it’s possible to run a lite-node on a Raspberry Pi 4. Your machine should meet the following hardware requirements:

  1. At least 2 GiB of RAM

  2. A dual-core CPU.

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

  1. Ensure you have XCode and Homebrew installed.

  2. Install the following dependencies:

    brew install go bzr jq pkg-config hwloc coreutils rust

Pre-build

Before we can build the Lotus binaries, there’s some setup we need to do. MacOS users should select their CPU architecture from the tabs:

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

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

  2. Switch to the branch representing the network you want to use. Mainnet always uses the releases branch:

    git checkout releases

    Or you can checkout to the Calibration testnet release using the ntwk/calibration branch:

    git checkout ntwk/calibration

  3. 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:

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

    mv ~/.lotus ~/.lotus-backup

  2. Make the Lotus binaries and install them:

    make clean all
sudo make install

  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.19.1-dev+mainnet+git.94b621dd5

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:

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

  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.mainnet.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:

    lotus auth create-token --perm "admin"

    This will output something like:

    eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJBbGxvdyI6WyJyZWFkIiwid3JpdGUiLCJzaWduIiwiYWRtaW4iXX0.um-LqY7g-SDOsMheDRbQ9JIaFzus_Pan0J88VQ6ZLVE

  2. Keep this key handy. We're going to use it in the next section.

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 '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 our auth key eyJhbGc...:

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

    This will output something like:

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

    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:

    curl -X POST '127.0.0.1:1234/rpc/v0' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJBbGxvdyI6WyJyZWFkIiwid3JpdGUiLCJzaWduIiwiYWRtaW4iXX0.um-LqY7g-SDOsMheDRbQ9JIaFzus_Pan0J88VQ6ZLVE' \
--data '{"jsonrpc":"2.0","id":1,"method":"Filecoin.WalletSetDefault","params":["t1vuc4eu2wgsdnce2ngygyzuxky3aqijqe7gj5qqa"]}' \
| jq

    This will output something like:

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

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!

PreviousLite-nodesNextFundamentals

Last updated

Logo

Basics

OverviewCrypto-economicsStorage modelReference

Developers

The FVMEVM-runtimeQuickstartTransfer FIL

Contact

GitHubSlackTwitter