Thin mode
Running in production12.4.15+

Thin mode

Run lotusd without the chain history: what thin mode keeps, how to enable it, what it serves, and the lighter full-node options.

Thin mode is the same lotusd binary started with -thin. A thin node keeps the block headers, its peers, its wallet, the pool ledger and a bounded cache. It does not download or store the chain history. What it needs from the history it fetches from full nodes and verifies against its own header chain.

12.4.16+

-thinrelay lets a thin node serve LotusHash stratum miners with jobs from an upstream full pool node and forward their shares; the full nodes keep every pool decision and verify every share. The upstream full nodes need 12.4.16.

Use it where disk is scarce and you still want a node that validates new blocks and transactions itself. Use a full node if you serve an explorer, an API for others, or proofs to thin nodes.

Ways to run a node #

Start withWhat it is
nothing (default)Full node with the explorer index and every chain module
-explorerindex=0, -modules=<list>Light full node: validates everything from genesis, but skips the explorer tables and the modules you leave out
-thin=1Thin node: no history; proves the older coins it needs from full nodes
-thin=utxoThin node with the whole set of unspent outputs loaded from a snapshot; checks spends locally

Light full node #

These two options are independent of -thin and can be enough:

  • -explorerindex=0 does not maintain the explorer tables (transactions, inputs, outputs, address balances and history), which are about 90% of a synced data directory. The node validates and serves the chain as before; explorer routes that need those tables answer 503 explorer_disabled. Enabling the index again on a data directory that ran without it needs -reindex.
  • -modules=<list> runs only the chain modules listed (empp, pool, rank, pokr, blob, slp, alp, or all, or none). A module left out keeps no database and its routes answer 503 module_disabled. A module enabled again later catches up from its last block.
Config
explorerindex=0
modules=none

Turning the explorer off on an existing data directory does not shrink it; -reindex reclaims the space.

Enable thin mode #

Start from a fresh data directory:

Shell
lotusd -thin=1

Once its headers are synced, the node adopts a block a few blocks below the best header as its base, without downloading the history before it (-thinactivate, on by default). From there it validates every new block and transaction with the normal code. When a block spends a coin older than the base, the node asks peers that serve proofs for it:

  • every answer is checked against the node's own header chain;
  • "unspent" needs -thinpeers agreeing peers (default 3), chosen in distinct network groups;
  • a single valid proof that the coin was spent wins;
  • a peer caught sending a provable lie is banned.

A block whose inputs cannot be proven yet waits and is retried. It is never marked invalid for that reason.

-thin forces -explorerindex=0, -modules=none, -proofserver=0, no bloom or block filters served to peers, and a pruned block store. A conflicting explicit value refuses to start.

To move an existing full node to thin mode, start a fresh data directory with -thin=1 (you can copy the wallet file). Dropping block files and indexes in place is not supported.

With a snapshot of the unspent outputs #

Shell
lotusd -thin=utxo -loadutxosnapshot=<file>

The node loads the whole set of unspent outputs from the snapshot file and never downloads the history. Missing inputs are then checked locally, as on a full node. The snapshot is trusted through the commitment that a later block's coinbase carries, once that block is buried under -thincommitdepth headers (default 100), or through the entry of this release; a snapshot vouched for by neither is refused. See Snapshots.

Starting the same data directory later with -thin=0 upgrades it to a full node: the history is downloaded and validated in the background.

Options #

OptionDefaultMeaning
-thin=<mode>00 full node, 1 thin node, utxo thin node with a snapshot
-thinkeep=<n>12Recent blocks kept for relay and reorgs
-thincache=<MiB>256Size of the bounded cache of fetched data
-thinpeers=<k>3Independent proof peers asked for a cross-check
-thinquorummax=<n>6Most peers asked when answers disagree
-thinquorumpolicy=<strict\|majority\|any>majorityAnswer only unanimous quorums, also majorities, or also disputed answers
-thinfilterpeers=<k>3Filter peers that must agree during a wallet rescan
-thinactivate1Adopt a base near the tip on a fresh data directory. 0 validates from genesis
-thincommitdepth=<n>100With -thin=utxo: headers needed above the block that commits to the snapshot

What a thin node does #

  • Validates new blocks and mempool transactions.
  • Never relays a block before validating it.
  • Runs a wallet. Rescans and imports use compact block filters fetched from peers, which must agree; a wallet created on the thin node needs no rescan.
  • Can be a pool member and serve stratum and getblocktemplate.
  • Reports itself in its user agent: /lotusd:12.4.15-thin(EB32.0)/.

What a thin node does not do #

  • It does not serve the history to other nodes, nor bloom filters, compact filters or proofs.
  • It has no explorer index and no chain modules of its own.

The REST API on a thin node #

The routes exist on every node, so a client sees the same API. A thin node answers them in one of three ways and says which in the X-Lotus-Thin response header (and in a thin key when the body is an object):

LabelMeaning
"verified":"local"Answered from the node's own state
quorum label (peers, agree, height, block_hash, ...)The node asked its proof peers and returns the answer they agree on
"verified":"unavailable"503 thin_unavailable: the answer needs the explorer, a module or a block the node never held, and there is no quorum route for it

When the peers disagree beyond what -thinquorumpolicy accepts, the answer is 503 thin_quorum_disputed; with no quorum at all, 503 thin_quorum_unavailable.

Routes that are unavailable on a thin node today include the token activity and burn lists, most social/* and poker/* lists, and pool-public/*. Full nodes never add the label.

Check a thin node #

Shell
lotus-cli getthininfo

It reports the mode, the answers received from each proof peer (unspent, spent, unknown, busy, timeouts) and the blocks waiting for the proofs of their inputs, with their retry back-off. A block still waiting after 6 tries is reported stalled. The debug category thin logs every answer.

Serve thin nodes from a full node #

Thin nodes depend on full nodes that serve proofs. It is off by default:

Config
proofserver=1
blockfilterindex=basic
peerblockfilters=1

The proof server needs the explorer index (on by default) and is ignored on a pruned node. Requests are rate limited per peer (-proofratelimit) and to -proofpeers peers per 10 minutes. Run 12.4.15 on proof servers: it handles the request bursts of thin nodes that 12.4.14 did not.

Disk and memory #

There is no measured disk or memory figure for a thin node on mainnet yet, so none is given here. What is fixed by configuration:

  • memory for fetched data is bounded by -thincache (256 MiB by default);
  • the block store is pruned and holds the -thinkeep most recent blocks (12 by default);
  • with -thin=utxo the node also stores the whole set of unspent outputs, the same size as a full node's.

On a full node, the explorer tables are about 90% of a synced data directory; -explorerindex=0 leaves them out.

Source share/www/docs/thin-mode.md in the lotusd repository
Checked against doc/thin-mode.md doc/release-notes/release-notes-12.4.13.md doc/release-notes/release-notes-12.4.14.md doc/release-notes/release-notes-12.4.15.md src/init.cpp src/thin/mode.h src/thin/utxo.h src/rpc/blockchain.cpp src/api/api_server.cpp