Spin up a lite-node

A full-node is a Filecoin node that has access to the full feature set of the Filecoin network. However, full-nodes can be difficult to spin up and expensive to maintain. 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:

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:

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:

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:

Expose the API #

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

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"
   

   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 
   

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

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

   {
     "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!