Spin up a lite-node
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.
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:
At least 2 GiB of RAM
A dual-core CPU.
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:
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:
Clone the repository and move into the
lotus
directory:git clone https://github.com/filecoin-project/lotus.git cd lotus/
Retrieve the latest Lotus release version:
git tag -l 'v*' | grep -v '-' | sort -V -r | head -n 1
This should output something like:
v1.32.3
Using the value returned from the previous command, checkout to the latest release branch:
git checkout v1.32.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:
Remove or delete any existing Lotus configuration files on your system:
mv ~/.lotus ~/.lotus-backup
Make the Lotus binaries and install them:
make clean all sudo make install
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.32.3+mainnet+git.1ff3b360b
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:
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. ...
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.
Open
~/.lotus/config.toml
and uncommentListenAddress
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 = "" ...
Open the terminal window where your lite-node is running and press
CTRL
+c
to close the daemon.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 ...
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.
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
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.
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" }, ...
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:
{ "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.
Set the new address as the default wallet for our lite-node. Remember to replace the Bearer token with our auth key
eyJhbGc...
and the"params"
value with the wallet address,f1vuc4...
, returned from the previous command: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":["f1vuc4eu2wgsdnce2ngygyzuxky3aqijqe7gj5qqa"]}' \ | 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!
Last updated
Was this helpful?