History modes

History modes allow a node to require less disk storage. Indeed, depending on the chosen history mode, some parts of the complete chain history can be deleted as they are not required anymore.

Three history modes are provided:

• Full mode (default mode)

  The node stores the minimal data since the genesis required to reconstruct (or ‘replay’) the complete chain’s ledger state.

  • Upsides:

    • Can synchronize using a snapshot.

    • Keep all necessary information in order to reconstruct all the chain’s ledger state (balances, contracts, etc..) since the genesis block.

    • Requires little disk storage.

    • Suitable for bakers as you can still query any block information or operation at any level.

    • Help other nodes to bootstrap and synchronize with the chain.

  • Downsides:

    • The node is not able to query the balances or staking rights before the current checkpoint.

    • Disk storage slowly increases as the node keeps the history.

  See how to set up a full node.

• Rolling mode

  This is the lightest mode as it only maintains a minimal rolling fragment of the chain data so the node can still validate new blocks and synchronize with the head.

  • Upsides

    • Only requires a minimal and bounded disk storage.

    • Can run on low resources architectures.

    • Can be bootstrapped within minutes.

  • Downsides

    • The node is not able to query block information of balances and staking rights before the current checkpoint.

    • The node does not help other nodes to bootstrap as it is not able to send the whole chain history.

  See how to set up a rolling node.

• Archive

  This is the heaviest mode as it keeps the whole chain data to be able to query any information stored on the chain since the genesis. It is particularly suitable for indexers or block explorer.

  • Upsides

    • The whole chain data is available.

  • Downsides

    • Consume an increasing and rather large amount and data storage.

  See how to set up an archive node.

History modes in a nutshell

	Storage amount	Suitable for bakers	Operations history
Archive	High	Yes	Complete
Full	Limited	Yes	Complete
Rolling	Low	Restricted*	Last cycle

(*) Not suitable for delegation services which needs more than one previous cycle to compute rewards.

Setting up a node in full mode

To run a full node you can either use the command line arguments:

tezos-node run --history-mode full

or use your configuration file as described in here:

{ "shell": {
    "history_mode": "full"
}}

Note that, since the full mode is the default one, this configuration is optional.

You can then verify that your history mode is set to full by using the checkpoint RPC.

tezos-client rpc get /chains/main/checkpoint

{ "block": { "some": "data" },
   "save_point": 4096, "caboose": 0, "history_mode": "full" }

In full mode, the save point corresponds to the checkpoint of the current chain. It is the oldest block that contains all the data. The caboose is the oldest pruned block (that contains partial data).

Setting up a node in rolling mode

To run a rolling node you can either use the command line arguments:

tezos-node run --history-mode experimental-rolling

or use your configuration file as described in here:

{ "shell": {
    "history_mode": "experimental-rolling"
}}

Please note that the rolling mode is still an experimental feature.

In this mode, the new checkpoint RPC will also give you the save point (the oldest block that contains all the data) and caboose (the oldest pruned block). $ tezos rpc get /chains/main/checkpoint

Setting up a node in archive mode

To run an archive node you can use the command line arguments: $ tezos-node run --history-mode archive

Or the configuration file: { "shell": {"history_mode": "archive"} }

If you want to start an archive node, it is now mandatory to pass this argument the first time you launch your node. Indeed, there are some restrictions when switching from one mode to another.

Switching between node’s modes

As the different modes relies on different storage schemes, there are some restrictions when switching from one mode to another.

Going from archive to full or rolling or from full to rolling is possible by successively exporting a snapshot of the targeted mode and then, importing it into a clean data directory.

It is possible to restore an archive storage from a full one using the reconstruction feature (you should note that the procedure may take a couple of days to complete). To do so, you have two choices:

• import a full snapshot using the --reconstruct option (see Snapshots),

• use the dedicated command tezos-node reconstruct if you already have full storage.

However, it is not possible to switch from rolling to full or archive using a successive export and import or by using the reconstruct feature since the rolling mode does not keep enough data to restore a complete storage.

From/To	Archive	Full	Rolling
Archive	X	Exp./Imp.	Exp./Imp.
Full	Reconstruct	X	Exp./Imp.
Rolling	No	No	X