Security
What a Lotus node can safely expose and what it cannot: ports, RPC authentication, the public REST API, reverse proxy, limits and Tor.
A node has one port made for the internet, the P2P port, and one port that mixes public and private services, the RPC port. This page says what each interface exposes and how to publish the public part without the private one.
POST /api/v1/txs/broadcast-batch is rate limited node-wide (-restbatchbroadcastrate, -restbatchbroadcasttxs; a rate of 0 answers 403). Keep it closed on a public reverse proxy unless you open it on purpose.
Ports #
| Port (mainnet) | Service | Default | Expose to the internet? |
|---|---|---|---|
| 10605 | P2P | on | Yes |
| 10604 | JSON-RPC, REST API, dashboard, wallet | on, loopback only | Not directly. Through a reverse proxy if you want a public API or explorer |
| 3334 | Stratum (-stratum) | off | Only if you run a public pool |
| 3335 | WebSocket stratum and push (-stratumwslisten) | off | Through the reverse proxy only |
| 10610, 10611 | Public NNG listener (-nngpublic, -nngpublicpub) | off | Yes, it is built for that |
-nngrpc, -nngpub, -zmqpub* | Private NNG and ZeroMQ sockets | off | Never |
JSON-RPC #
JSON-RPC controls the node: it can spend the funds of the node's wallets, change what the node validates, and stop it. Treat its credentials like a root password.
- By default the port listens on localhost only (
127.0.0.1and::1). - Every call needs credentials. By default the node writes a random cookie to
.cookiein the data directory at each start;lotus-clion the same machine reads it. This is the safest mode for local use. - For a remote caller, create a user with a hashed password instead of writing a clear-text
rpcpassword:
python3 share/rpcauth/rpcauth.py myuserPut the rpcauth=... line it prints in lotus.conf, with the networks allowed to connect:
rpcauth=myuser:<salt>$<hash>
rpcbind=10.0.0.5
rpcallowip=10.0.0.0/8rpcwhitelist=<user>:<rpc 1>,<rpc 2>limits a user to the commands listed.- The interface is HTTP, not HTTPS: credentials travel in clear. Use it over a private network, a VPN or an SSH tunnel only.
Do not expose the RPC port to the public internet. -rpcallowip filters the whole port by source address (the REST API and the dashboard included), but it is not a substitute for a firewall.
No authentication (-rpcnoauth=1) #
-rpcnoauth=1 disables the credential check entirely: anyone who can reach the port can run any command. No .cookie is written. Use it only when the port is confined to a trusted boundary with -rpcbind, -rpcallowip and a firewall. The node logs a warning at startup.
REST API #
The REST API under /api/v1 is served on the same port, without credentials. What an anonymous caller can reach:
| Routes | Access |
|---|---|
| Chain, blocks, transactions, addresses, mempool, stats, network, modules | Public, read-only |
POST /api/v1/txs/send, txs/broadcast, txs/broadcast-checked | Public. They relay a signed transaction; the network's rules decide whether it is accepted |
/api/v1/rpc/<method> | Public for the methods of a fixed allowlist only (below) |
/api/v1/stratum*, /api/v1/sharechain*, /api/v1/scryptchains, /api/v1/pool/* | Operator routes: they need the JSON-RPC credentials (HTTP basic auth) and are never served through a reverse proxy |
POST /api/v1/script/trace | Off unless -scripttrace=1; then limited by -scripttraceratelimit (30 per minute, node-wide) |
Module rescans are not on the REST API: they are JSON-RPC commands (rescanmodule).
The /api/v1/rpc allowlist #
/api/v1/rpc/<method> runs a JSON-RPC command without credentials only if the method is on a list compiled into the node. The list holds:
- read-only queries (for example
getblockchaininfo,getblock,getrawtransaction,getmempoolinfo,getpeerinfo,validateaddress); - broadcasts that the network's rules validate:
sendrawtransaction,submitblock,submitheader,sendavalancheproof.
Everything else answers 403 method_not_allowed: wallet commands, stop, addnode, setban, generate*, invalidateblock and the mining operator commands. Any command of the wallet category is refused even if it were added to the list by mistake. GET /api/v1/rpc returns the list of your node.
The node's wallet and the browser wallet #
The node's own wallets are reachable through authenticated JSON-RPC only (/wallet/<name>), never through the REST API.
The web wallet served at /wallet/ is a different thing: it keeps its keys in the browser and uses the public REST API. It does not use the node's wallet.
Publish the web port behind a reverse proxy #
To offer a public API, explorer or wallet, keep the node on loopback and put nginx or another proxy in front for TLS, rate limiting and IP filtering.
limit_req_zone $binary_remote_addr zone=lotus_api:10m rate=10r/s;
server {
listen 443 ssl http2;
server_name your-node.example.com;
ssl_certificate /etc/letsencrypt/live/your-node.example.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/your-node.example.com/privkey.pem;
location /api/v1/ {
limit_req zone=lotus_api burst=50 nodelay;
proxy_pass http://127.0.0.1:10604;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
}
location / {
deny all;
}
}This publishes the REST API only. To publish the dashboard and the browser wallet too, proxy /dashboard, /wallet, /sitemap, /robots.txt and the favicon the same way.
The node protects itself behind a proxy: a JSON-RPC request or an operator route that carries a proxy header (X-Forwarded-For, X-Real-IP, Forwarded, CF-Connecting-IP, True-Client-IP, X-Forwarded-Host) is refused with 403, whatever path the proxy let through and whatever credentials it carries. So always set X-Real-IP in the proxy, as above. -rpcallowforwarded=1 turns this protection off; leave it at 0 unless you proxy JSON-RPC on purpose.
If a CDN sits in front, do not let it cache /api/v1/*.
WebSockets #
The browser miner (/api/v1/mining/ws) and push notifications (/api/v1/ws) are served by their own listener, not by the RPC port. Bind it to loopback or to the private interface the proxy reaches, never to a public address, and give the proxy one location per path with the Upgrade and Connection headers:
location = /api/v1/ws {
proxy_pass http://127.0.0.1:3335;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_read_timeout 120s;
}The node checks the Origin of browser clients (by default its host must equal the Host header's host) and believes the client address header only from -stratumwstrustedproxy (default: loopback). See Push interfaces.
Limits #
The node does not rate-limit the REST API per client. That is the proxy's job (limit_req above). What the node does itself:
| Limit | Value |
|---|---|
HTTP worker threads (-rpcthreads) | 16, shared by JSON-RPC, REST and the web UI |
Connections waiting for a worker (-rpcworkqueue) | 64; beyond it, 503 with Retry-After: 1 |
| Wrong JSON-RPC password | each attempt is delayed |
gettxoutsetinfo through /api/v1/rpc | one at a time; the others get 503 busy |
| Push WebSocket | connections, subscriptions and messages limited per client address |
| Public NNG listener | requests, templates, submissions and bytes limited per address, with bans |
Heavy calls keep a worker thread until they finish. Keep -rpcthreads at 16 or more on a node that serves explorers or indexers.
NNG and ZeroMQ #
- The private NNG sockets (
-nngrpc,-nngpub) are unauthenticated and expose everything they serve. Useipc://, ortcp://on a private address behind a firewall. - The public NNG listener (
-nngpublic,-nngpublicpub) is open to anyone by design. It serves mining templates and block submission only and refuses every other call. Usetls+tcp://with-nngpubliccertand-nngpublickey; plaintcp://works but logs a warning. - ZeroMQ does no authentication either. Expose its ports to trusted hosts only.
Tor #
To make every outgoing connection through Tor, point the node at Tor's SOCKS5 proxy:
proxy=127.0.0.1:9050With a proxy set, listening is off by default; set listen=1 if you also want to accept connections. onlynet=onion restricts outgoing connections to onion peers. onion=<ip:port> sets a separate proxy for onion services.
When the node listens and Tor's control port is reachable (ControlPort 9051 in torrc; -torcontrol, default 127.0.0.1:9051), it creates an onion service automatically. Authentication is Tor's cookie file, which the user running lotusd must be able to read, or -torpassword. Disable with -listenonion=0; debug with -debug=tor.
Do not add anything but the Lotus P2P port to that onion service. If you run a web service too, give it its own onion service, otherwise the two are trivial to link.
