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 (default mode with 5 additional cycles)

  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

  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 explorers.

  • 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*	Restricted*

(*) Suitable for delegation services if the number of additional preserved cycles is high enough to allow the computation of rewards. See Preserving additional cycles for details.

History modes use some markers which are used to describe the state of the storage:

• checkpoint: the last allowed fork level of the chain (as defined in the Tezos position paper),

• savepoint: the last known block which contains metadata,

• caboose: the last known block.

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" },
   "savepoint": 4096, "caboose": 0, "history_mode": "full" }

In full mode, the savepoint is the last block which contains its metadata. The caboose is the last known block which is pruned (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"
}}

In rolling mode, the caboose is the genesis at its early state, and then, it is updated to the last known block of the rolling window. The savepoint is moved in accordance to the number of configured additional cycles.

$ 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.

In archive mode, both the savepoint and caboose are located down to the genesis.

Preserving additional cycles

When running a node in full or rolling mode, you have a full access to the block information in a sliding window of history. Indeed, at each new cycle, a garbage collection phase removes the ledger state and the block metadata (operation receipts, rewards updates, etc.) of blocks outside the offset of this sliding window. Depending on the network, a minimum number of cycles are preserved (e.g., 7 on mainnet). However, the node keeps a number of additional cycles that is configurable.

By default, the number of preserved additional cycles, for both full and rolling nodes, is 5 cycles. On mainnet, this would total 12 cycles of complete history (approximately a month). It is possible to increase this parameter to keep more history or, on the contrary, decrease it to reduce the storage size. For example, it is possible to run a baker and a delegation service on rolling mode with 7 additional cycles providing two more weeks to dispatch rewards.

When running your node for the first time on an empty storage, you may specify the history mode and number of additional cycles using --history-mode <HISTORY_MODE>:<NB_CYCLES> when running it. For example, --history-mode rolling:7.

It is also possible to modify the number of additional preserved cycles of a previously configured node. See Switch mode restrictions

Switching between node’s modes

It is possible to switch between history modes and/or to modify the number of additional cycles. To do so, it is necessary to restart the node with the desired history mode and add the flag --force-history-mode-switch. This flag is required to prevent erroneous history switches. Indeed, changing from one history mode to an other can irremediably remove data from the storage. The history mode switches must be manipulated with care.

However, as the different modes rely on different storage schemes, there are some restrictions when switching from one mode to another.

From/to	Archive	Full	Rolling
Archive	X	Yes	Yes
Full	Yes*	Yes	Yes
Rolling	No	No	Yes

(*) Switching from a full node to an archive one is possible using the reconstruct feature. To do so, run tezos-node reconstruct on your node. Note that the storage reconstruction is a long process that, on the main network, may requires days to complete.