Run the node
Getting started12.4.15+

Run the node

Start lotusd, find its ports, open its web pages, check that it syncs, and stop it cleanly.

A node validates the Lotus chain for you and serves what you need to use it: an explorer, a wallet and an API, from the node itself. This page starts one and checks it.

You need the binaries from Install a node.

Start #

Shell
lotusd -daemon

-daemon runs the node in the background (Linux and macOS). Without it the node stays in the terminal. It writes its log to debug.log in the data directory; -printtoconsole sends the log to the terminal instead.

No configuration is needed for a first start. Options go on the command line or in lotus.conf: see Configuration. lotusd -help lists every option.

Ports #

NetworkSelected withP2PRPC, REST and web
Mainnetnothing1060510604
Testnet-testnet1160511604
Regtest-regtest1260512604
Napoleon testnet-napoleontestnet2060520604

-port changes the P2P port and -rpcport the other one.

One port carries JSON-RPC, the REST API and the web pages. By default it listens on localhost only (127.0.0.1 and ::1). To reach it from another machine you need both -rpcbind and -rpcallowip; one without the other is ignored. Read Security before you do.

What the web port serves #

Open http://127.0.0.1:10604/dashboard in a browser on the machine that runs the node.

PathWhat
/dashboardThe explorer, tokens, social pages, the pool, the network view and the developer pages: see Web UI
/wallet/A wallet that creates and keeps its keys in your browser: see Wallets
/api/v1/The public REST API, described by /api/v1/openapi.json: see REST API
/ (POST)JSON-RPC, with credentials: see RPC

While the node is still loading the chain, a browser gets a "node is starting" page that lists the startup stages and opens the dashboard when the node is ready. API clients get a 503 answer during that time.

To see these pages before installing anything, open a public node: givelotus.org/dashboard.

Check the node #

Is it up, and at which height?

Shell
curl -s http://127.0.0.1:10604/api/v1/health

/api/v1/health answers:

JSON
{
  "status": "ok",
  "height": 1427139,
  "best_block_hash": "0000000000cc5180c5cf0168956fdc595fbf1ca3d8cb6bab47a3e36ca7fbd479",
  "median_time": 1794871298,
  "ibd": false,
  "uptime_seconds": 6250,
  "version": 12041500,
  "subversion": "/lotusd:12.4.15(EB32.0)/"
}

status is syncing while the node is in its initial block download, then ok.

Which version, how many peers?

Shell
curl -s http://127.0.0.1:10604/api/v1/node

getnetworkinfo gives the version in subversion and the number of peers in connections. lotus-cli finds the node's credentials by itself when it runs as the same user on the same data directory.

Does it know the next network upgrade?

Shell
curl -s http://127.0.0.1:10604/api/v1/upgrades

The answer lists every upgrade with its activation_time, whether it is active, and the name of the next one. For Napoleon you must see "name": "napoleon" with "activation_time": 1797886200.

Sync #

A new node downloads and validates the whole chain. Follow it:

Shell
curl -s http://127.0.0.1:10604/api/v1/chain/sync

/api/v1/chain/sync gives height, headers, initial_block_download, verification_progress, remaining_blocks and eta_seconds. In getblockchaininfo, compare blocks with headers; verificationprogress is above 0.999 on a synced node. The dashboard shows a sync banner on every page meanwhile.

During a first sync the node does not maintain some explorer indexes block by block (the rich list, the unspent outputs per address); it builds them once it is at the tip. The pages and routes that need them answer 503 explorer_indexing until then, and the rest of the explorer works.

To start without the whole history, see UTXO snapshots and Thin mode.

Stop #

Shell
lotus-cli stop

Wait until the process has exited before you restart or upgrade. With Docker, give it time: docker stop -t 120 lotusd.

Other networks #

The same binary runs every network. lotus-cli takes the same flag as lotusd:

Shell
lotusd -napoleontestnet -addnode=51.91.36.126:20605
lotus-cli -napoleontestnet getblockchaininfo

The Napoleon testnet has no DNS seed, so it needs -addnode. Its rules are described on the Napoleon page.

Help #

Ask in the Telegram group.

Source share/www/docs/run.md in the lotusd repository
Checked against src/chainparamsbase.cpp src/chainparams.cpp src/httpserver.cpp src/init.cpp src/api/api_server.cpp src/api/health_handler.cpp src/api/openapi_handler.cpp doc/production-deployment.md doc/testnet-napoleon.md