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.
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:
| System | Default 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.
# lotus.conf
txindex=1
maxconnections=64
[test]
rpcport=21604Options 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 #
| Network | Option | Data in | P2P | RPC, REST, web UI |
|---|---|---|---|---|
| Mainnet | none | <datadir>/ | 10605 | 10604 |
| Testnet | -testnet | <datadir>/testnet3/ | 11605 | 11604 |
| Regtest | -regtest | <datadir>/regtest/ | 12605 | 12604 |
| Napoleon test network | -napoleontestnet | <datadir>/napoleontest/ | 20605 | 20604 |
Only lotus.conf is shared between networks.
Network options #
| Option | Default | Meaning |
|---|---|---|
port=<port> | 10605 | P2P listening port |
bind=<addr>[:<port>] | all addresses | Address the P2P listener binds to |
listen | 1 (0 with proxy or connect) | Accept connections from outside |
maxconnections=<n> | 4096 | Most peer connections kept |
addnode=<ip> | none | A node to connect to and keep connected. Repeatable |
connect=<ip> | none | Connect only to these nodes; connect=0 disables automatic connections |
dnsseed | 1 | Ask the DNS seeds for peers when low on addresses |
externalip=<ip> | none | Your own public address |
onlynet=<net> | all | Outgoing connections only through ipv4, ipv6 or onion |
maxuploadtarget=<n> | 0 (no limit) | Try to keep outbound traffic under <n> MiB per 24 hours |
blocksonly | 0 | Do not accept transactions from peers |
proxy=<ip:port> | none | Connect through a SOCKS5 proxy. See Security |
RPC options #
| Option | Default | Meaning |
|---|---|---|
server | 1 for lotusd | Accept JSON-RPC commands |
rpcport=<port> | 10604 | Port of JSON-RPC, the REST API and the web UI |
rpcbind=<addr>[:port] | 127.0.0.1 and ::1 | Address to listen on. Ignored unless rpcallowip is also set |
rpcallowip=<ip> | localhost only | Source address, network/netmask or CIDR allowed to reach the port. Repeatable |
rpcauth=<user>:<salt>$<hash> | none | A user with a hashed password, generated by share/rpcauth/rpcauth.py. Repeatable |
rpcuser=<user>, rpcpassword=<pw> | none | A user with a clear-text password |
rpccookiefile=<loc> | .cookie in the data directory | Where the authentication cookie is written |
rpcwhitelist=<user>:<rpc>,... | none | Commands a user may call |
rpcnoauth | 0 | Disable authentication of JSON-RPC entirely. Read Security first |
rpcallowforwarded | 0 | Answer JSON-RPC and operator routes that arrive through a reverse proxy |
rpcthreads=<n> | 16 | HTTP 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.
| Option | Default | Meaning |
|---|---|---|
apireaders=<n> | rpcthreads, at most 8 | Read-only database connections of the REST API, 4 MiB of cache each. 0 reads through the connection shared with block connection |
httpcompression | 1 | gzip the replies of the REST API, the dashboard and the sitemaps for clients that ask for it |
mempooloverlay | 1 | Include unconfirmed transactions in REST address, UTXO and transaction answers |
scripttrace | 0 | Enable POST /api/v1/script/trace |
scripttraceratelimit=<n> | 30 | Script trace requests per minute, node-wide |
rest | 0 | Also serve the legacy /rest/ endpoints |
wslisten=<bind>:<port> | none | WebSocket listener for push notifications. See Push interfaces |
Indexes and storage #
| Option | Default | Meaning |
|---|---|---|
explorerindex | 1 | Maintain 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> | all | Chain modules that run: empp, pool, rank, pokr, blob, slp, alp, or all or none. Routes of a module left out answer 503 module_disabled |
txindex | 0 | Full transaction index, used by getrawtransaction |
blockfilterindex=<type> | 0 | Index of compact block filters (basic) |
contractindex | 0 | Index Taproot contract outputs (/api/v1/contracts) |
prune=<n> | 0 | Delete old block files; <n> is a target size in MiB. Incompatible with txindex |
dbcache=<n> | 1024 | Database cache in MiB (4 to 16384) |
maxmempool=<n> | 600 | Keep the mempool below <n> megabytes |
par=<n> | 0 (automatic) | Script verification threads |
thin=<mode> | 0 | See 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 #
| Option | Default | Meaning |
|---|---|---|
stratum | 0 | Enable the built-in stratum server |
stratumport=<port> | 3334 | Stratum port. Ignored when stratumlisten is given |
stratumbind=<addr> | 0.0.0.0 | Address the stratum server binds to |
stratumlisten=<bind>:<port>:<algo>[:<difficulty>] | none | A listener with a default algorithm. Repeatable; replaces stratumbind and stratumport |
stratumcoinbase=<address> | none | Address paid by the blocks the stratum server finds. Without a valid one the reward is burnt |
stratumdifficulty=<n> | 0.5 | Initial share difficulty |
stratumvardiff | 1 | Variable difficulty |
stratummaxworkers=<n> | 1024 | Most concurrent workers |
stratummaxperip=<n> | 64 | Most sessions from one source address |
stratumwslisten=<bind>[:<port>] | none | WebSocket stratum listener for the dashboard's browser miner (port 3335 when omitted). Requires stratum |
coinbasetag=<tag> | logos | Tag written in the coinbase of the blocks this node builds |
See Stratum and Merged mining.
Pool #
| Option | Default | Meaning |
|---|---|---|
poolpayouts | 0 | Stratum blocks pay every miner of the PPLNS window directly in the coinbase |
poolid=<id> | FRENCHBTC | Pool id written in the on-chain record; fleet peers must use the same |
poolpplnswindow=<tenths> | 40 | PPLNS window in tenths of the network difficulty (40 = 4.0x) |
poolminpayout=<amount> | 1 XPI | Smallest balance paid in a coinbase |
poolmaxpayees=<n> | 92 | Most payee outputs per coinbase |
poolfeebps=<n> | 0 | Pool fee in basis points, paid to poolfeeaddress |
poolburnbps=<n> | 1 | XPI burnt by the record outputs, in basis points of the block subsidy |
See Pool.
Logging #
| Option | Default | Meaning |
|---|---|---|
debuglogfile=<file> | debug.log | Log file; 0 disables it |
printtoconsole | 1 when not a daemon | Also write the log to the console |
debug=<category> | 0 | Log a debug category; debug=1 logs all |
debugexclude=<category> | none | Leave a category out of debug=1 |
shrinkdebugfile | 1 when no debug | Shrink debug.log at startup |
logips | 0 | Include IP addresses in the log |
logtimestamps | 1 | Prefix each line with a timestamp |
daemon | 0 | Run in the background |
Data directory layout #
| Path | Content |
|---|---|
lotus.conf | Your configuration. Never written by the node |
settings.json | Settings 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.log | The log |
peers.dat, banlist.dat, anchors.dat | Known peers, bans, and the peers to reconnect to at startup |
mempool.dat | The mempool saved at shutdown |
.cookie | The RPC authentication cookie of this run |
lotusd.pid, .lock | Process id and data directory lock |
Back up lotus.conf and wallets/. Blocks and the chain state can be downloaded again.
