Configuration
Running in production12.4.15+

Configuration

The lotus.conf file: where it lives, its syntax, and the options operators need most, each with its default.

lotusd and lotus-cli read the same configuration file, lotus.conf. Every option can also be given on the command line with a leading -; the command line wins over the file.

12.4.16+

New options: -asyncindex (default 1) moves the explorer and module indexing off block connection, bounded by -asyncindexmaxlag (64 blocks) and -asyncindexmaxmem (256 MiB), with REST reads waiting at most -asyncindexreadwait (250 ms). -restbatchbroadcastrate (30 batches per minute) and -restbatchbroadcasttxs (10,000 transactions per minute) limit POST /api/v1/txs/broadcast-batch. -gbtlightjobs (64) is the number of light block templates kept. -blockselector keeps its default, ancestor.

lotusd -help prints every option with its default. This page lists the ones operators set most often.

Where the file is #

The file is not created for you. Create it in the data directory:

SystemDefault path
Linux$HOME/.lotus/lotus.conf
macOS$HOME/Library/Application Support/Lotus/lotus.conf
Windows%APPDATA%\Lotus\lotus.conf

-datadir=<dir> moves the data directory and -conf=<file> names another file. Both are command line options. Inside the file, includeconf=<file> reads a further file.

Syntax #

One option=value per line, without the leading -. A value is mandatory: write testnet=1, not testnet. Lines starting with # are comments.

Config
# lotus.conf
txindex=1
maxconnections=64

[test]
rpcport=21604

Options that depend on the network go in a section, [main], [test] or [regtest], or take a prefix (test.rpcport=21604). A network-specific value wins over a general one.

Networks and ports #

NetworkOptionData inP2PRPC, REST, web UI
Mainnetnone<datadir>/1060510604
Testnet-testnet<datadir>/testnet3/1160511604
Regtest-regtest<datadir>/regtest/1260512604
Napoleon test network-napoleontestnet<datadir>/napoleontest/2060520604

Only lotus.conf is shared between networks.

Network options #

OptionDefaultMeaning
port=<port>10605P2P listening port
bind=<addr>[:<port>]all addressesAddress the P2P listener binds to
listen1 (0 with proxy or connect)Accept connections from outside
maxconnections=<n>4096Most peer connections kept
addnode=<ip>noneA node to connect to and keep connected. Repeatable
connect=<ip>noneConnect only to these nodes; connect=0 disables automatic connections
dnsseed1Ask the DNS seeds for peers when low on addresses
externalip=<ip>noneYour own public address
onlynet=<net>allOutgoing connections only through ipv4, ipv6 or onion
maxuploadtarget=<n>0 (no limit)Try to keep outbound traffic under <n> MiB per 24 hours
blocksonly0Do not accept transactions from peers
proxy=<ip:port>noneConnect through a SOCKS5 proxy. See Security

RPC options #

OptionDefaultMeaning
server1 for lotusdAccept JSON-RPC commands
rpcport=<port>10604Port of JSON-RPC, the REST API and the web UI
rpcbind=<addr>[:port]127.0.0.1 and ::1Address to listen on. Ignored unless rpcallowip is also set
rpcallowip=<ip>localhost onlySource address, network/netmask or CIDR allowed to reach the port. Repeatable
rpcauth=<user>:<salt>$<hash>noneA user with a hashed password, generated by share/rpcauth/rpcauth.py. Repeatable
rpcuser=<user>, rpcpassword=<pw>noneA user with a clear-text password
rpccookiefile=<loc>.cookie in the data directoryWhere the authentication cookie is written
rpcwhitelist=<user>:<rpc>,...noneCommands a user may call
rpcnoauth0Disable authentication of JSON-RPC entirely. Read Security first
rpcallowforwarded0Answer JSON-RPC and operator routes that arrive through a reverse proxy
rpcthreads=<n>16HTTP worker threads, shared by JSON-RPC, the REST API and the web UI

Without rpcauth or rpcuser, the node writes a random cookie at each start and lotus-cli reads it. See JSON-RPC.

REST API and web UI options #

The REST API /api/v1, the dashboard and the wallet are served on the RPC port whenever the RPC server runs; there is no separate option to enable them.

OptionDefaultMeaning
apireaders=<n>rpcthreads, at most 8Read-only database connections of the REST API, 4 MiB of cache each. 0 reads through the connection shared with block connection
httpcompression1gzip the replies of the REST API, the dashboard and the sitemaps for clients that ask for it
mempooloverlay1Include unconfirmed transactions in REST address, UTXO and transaction answers
scripttrace0Enable POST /api/v1/script/trace
scripttraceratelimit=<n>30Script trace requests per minute, node-wide
rest0Also serve the legacy /rest/ endpoints
wslisten=<bind>:<port>noneWebSocket listener for push notifications. See Push interfaces

Indexes and storage #

OptionDefaultMeaning
explorerindex1Maintain the explorer tables (transactions, inputs, outputs, address balances and history: about 90% of a synced data directory). With 0, explorer routes answer 503 explorer_disabled. Enabling it again needs -reindex
modules=<list>allChain modules that run: empp, pool, rank, pokr, blob, slp, alp, or all or none. Routes of a module left out answer 503 module_disabled
txindex0Full transaction index, used by getrawtransaction
blockfilterindex=<type>0Index of compact block filters (basic)
contractindex0Index Taproot contract outputs (/api/v1/contracts)
prune=<n>0Delete old block files; <n> is a target size in MiB. Incompatible with txindex
dbcache=<n>1024Database cache in MiB (4 to 16384)
maxmempool=<n>600Keep the mempool below <n> megabytes
par=<n>0 (automatic)Script verification threads
thin=<mode>0See Thin mode

To use less memory, lower dbcache and maxmempool first, then maxconnections. To use less bandwidth, set maxuploadtarget, lower maxconnections, or turn off listen.

Mining and stratum #

OptionDefaultMeaning
stratum0Enable the built-in stratum server
stratumport=<port>3334Stratum port. Ignored when stratumlisten is given
stratumbind=<addr>0.0.0.0Address the stratum server binds to
stratumlisten=<bind>:<port>:<algo>[:<difficulty>]noneA listener with a default algorithm. Repeatable; replaces stratumbind and stratumport
stratumcoinbase=<address>noneAddress paid by the blocks the stratum server finds. Without a valid one the reward is burnt
stratumdifficulty=<n>0.5Initial share difficulty
stratumvardiff1Variable difficulty
stratummaxworkers=<n>1024Most concurrent workers
stratummaxperip=<n>64Most sessions from one source address
stratumwslisten=<bind>[:<port>]noneWebSocket stratum listener for the dashboard's browser miner (port 3335 when omitted). Requires stratum
coinbasetag=<tag>logosTag written in the coinbase of the blocks this node builds

See Stratum and Merged mining.

Pool #

OptionDefaultMeaning
poolpayouts0Stratum blocks pay every miner of the PPLNS window directly in the coinbase
poolid=<id>FRENCHBTCPool id written in the on-chain record; fleet peers must use the same
poolpplnswindow=<tenths>40PPLNS window in tenths of the network difficulty (40 = 4.0x)
poolminpayout=<amount>1 XPISmallest balance paid in a coinbase
poolmaxpayees=<n>92Most payee outputs per coinbase
poolfeebps=<n>0Pool fee in basis points, paid to poolfeeaddress
poolburnbps=<n>1XPI burnt by the record outputs, in basis points of the block subsidy

See Pool.

Logging #

OptionDefaultMeaning
debuglogfile=<file>debug.logLog file; 0 disables it
printtoconsole1 when not a daemonAlso write the log to the console
debug=<category>0Log a debug category; debug=1 logs all
debugexclude=<category>noneLeave a category out of debug=1
shrinkdebugfile1 when no debugShrink debug.log at startup
logips0Include IP addresses in the log
logtimestamps1Prefix each line with a timestamp
daemon0Run in the background

Data directory layout #

PathContent
lotus.confYour configuration. Never written by the node
settings.jsonSettings changed at run time
blocks/Block files blkNNNNN.dat, undo files revNNNNN.dat, and index.sqlite (block index and explorer tables)
chainstate/chainstate.sqlite, the set of unspent outputs
modules/One database per chain module
indexes/Optional indexes (txindex, blockfilter)
wallets/The node's wallets
debug.logThe log
peers.dat, banlist.dat, anchors.datKnown peers, bans, and the peers to reconnect to at startup
mempool.datThe mempool saved at shutdown
.cookieThe RPC authentication cookie of this run
lotusd.pid, .lockProcess id and data directory lock

Back up lotus.conf and wallets/. Blocks and the chain state can be downloaded again.

Source share/www/docs/configuration.md in the lotusd repository
Checked against doc/lotus-conf.md doc/files.md doc/reduce-memory.md doc/reduce-traffic.md src/init.cpp src/chainparamsbase.cpp src/httpserver.h src/net.h src/txdb.h src/policy/policy.h src/stratum/stratumconfig.cpp src/pool/manager.cpp src/push/wsserver.cpp src/wallet/init.cpp