diff --git a/docs/user/snapshots.rst b/docs/user/snapshots.rst index 41c933aa7591424606338c8a411eb2c71dd631d5..c4a5fd9e9e5c8db54182009a5d7f2862c0c404a4 100644 --- a/docs/user/snapshots.rst +++ b/docs/user/snapshots.rst @@ -1,6 +1,7 @@ Snapshots ========= +When a node in the Tezos network is started, it has to catch up the current state of the blockchain (a process known as "bootstrapping"), making sure that this state is coherent with the whole history of the ledger. As the chain invariably grows every day, retrieving a full chain from the peer-to-peer network can be a very long process. Thanks to the implementation of :doc:`history modes `, it is now possible to propose an @@ -12,22 +13,20 @@ Importing a snapshot -------------------- When bootstrapping from a snapshot, the first thing that you want to -do is check the point in history from when you start. +be sure of is that the loaded state is not fake. The snapshot format does not (and cannot) provide any evidence that -the imported block is actually a part of the current main chain of the -Tezos network. To avoid to be fooled by a fake chain, it is +the imported block is actually a real point in the history of the +Tezos network blockchain. To avoid to be fooled by a fake chain, it is **necessary** to carefully check that the block hash of the imported -block is included in the main chain. This can be done by comparing the hash +block is included in the main chain. (Note that all the websites providing +snapshots mention the hash corresponding to the head block in each snapshot.) +This check can be done by comparing the hash to one provided by another node under the user’s control, or by relying on social cues to obtain a hash from a large number of trusted parties which are unlikely to be colluding. -As the Tezos position paper states: - - *“Occasional checkpoints can be an effective way to prevent very long blockchain reorganizations[…]. Forming a consensus over a single hash value over a period of months is something that human institutions are perfectly capable of safely accomplishing. This hash can be published in major newspapers around the world, carved on the tables of freshmen students, spray painted under bridges, included in songs, impressed on fresh concrete, tattooed on pet ferrets… there are countless ways to record occasional checkpoints in a way that makes forgery impossible.”* - -This same wisdom must be applied when using a snapshot. +For instance, one may use one or more Tezos block explorers in the :ref:`Tezos community ` to check whether this block hash matches an existing block. After that careful selection and verification of the imported block hash, you can trust the node with the rest of the procedure. In @@ -37,23 +36,22 @@ inconsistency, malicious or not. This safety comes from the fact that block headers are designed to make sure that applying a block has the same result for everyone in -the network. To achieve this, the block header include hashes of their operations +the network. To achieve this, a block header includes hashes of its operations and predecessor, as well as the resulting chain state. The import process does the same checks, recomputing and checking all the hashes it encounters in the snapshot. -To bootstrap a Tezos node from a file ``FILE`` to an empty Tezos +To bootstrap a Tezos node from a file to an empty Tezos node directory (running this command from an already synchronised node will not work), run: .. code-block:: console - tezos-node snapshot import FILE --block + tezos-node snapshot import --block [--data-dir ] The ``--block `` option argument aims to verify that the block contained in the snapshot is the one that you are expecting to -import. Otherwise, don’t forget to check the hash of the imported -block displayed by the node when importing. +import. .. warning:: @@ -79,11 +77,11 @@ command can be used to display snapshot's information such as: - targeted block hash, level and timestamp - ... -The command can be used as following: +This information is displayed by the following command: .. code-block:: console - tezos-node snapshot info snapshot.file + tezos-node snapshot info As can be seen in the snapshot information, a snapshot contains historical data corresponding to a given history mode, which can be: @@ -111,8 +109,8 @@ set their checkpoint to this block). Depending on the snapshot export option, additional history may also be put in the snapshot file. By default, the snapshot export command will create a ``full`` snapshot. Such a snapshot will contain all the -blocks from a given block hash back to the genesis. The whole chain -will be exported into a snapshot, from the beginning to the selected +blocks from a given block hash back to the genesis. Thus, the whole chain +will be exported into the snapshot, from the beginning to the selected point. This kind of snapshot can only be created from a ``full`` or an ``archive`` node. @@ -130,7 +128,7 @@ be chosen as the default block to export. By default, the snapshot will be exported into a file with a name following this pattern ``--.``. A specific -snapshot name can be given as an additional argument. For example: +snapshot file name can be given as an additional argument. For example: .. code-block:: console @@ -139,35 +137,35 @@ snapshot name can be given as an additional argument. For example: Rolling export ~~~~~~~~~~~~~~ -Rolling snapshots can be exported if you want to deploy a node quickly -or for test and experimentation purposes (such as in a classroom -setting) as they are much smaller. However, to bootstrap a long +Rolling snapshots are useful to quickly deploy a node +or for testing and experimentation purposes (such as in a classroom +setting), as they are much smaller. However, to bootstrap a long running node on the network, we recommend using ``full`` snapshots to -participate into the network wide preservation and sharing of chain +participate into the network-wide preservation and sharing of chain history. .. code-block:: console - tezos-node snapshot export --block FILE.rolling --rolling + tezos-node snapshot export .rolling --block --rolling Snapshot file format and IPFS ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -By default, the snapshot is exported as an archive file (through the -`.tar` format). Such a single file archive is well suitable for -compression mechanism. However, the compression of a snapshot file is -not handle by the node. +By default, the snapshot is exported as an archive file (in the +``.tar`` format). Such a single archive file is suitable for applying +compression mechanisms. However, the compression of a snapshot file is +not handled by the node. If one prefers not to export the snapshot as a single archive file, it -is possible to add the ``--export-format raw`` flag to the export +is possible to add the flag ``--export-format raw`` to the export command. The snapshot is then exported as a folder containing all the -necessary data. As the structure of the snapshot follows the storage +necessary files. As the structure of the snapshot follows the storage representation which is based on the network's cycles, the major part of the ``raw`` snapshot's data is canonical. The block history is thus represented as *cemented cycles* and will stay as it is for ever. Only the rest of the file contains data relative to the snapshot's target block, such as the current incomplete cycle and the block's associated -ledger state. This canonical representation is well suitable for +ledger state. This canonical representation is well suited for distributing snapshots through `IPFS `_. @@ -190,7 +188,7 @@ can be exported from a given history mode node. Snapshot providers ~~~~~~~~~~~~~~~~~~ -There is a number of services that provide node snapshots. They create snapshots +There are several services providing node snapshots. They create snapshots of their nodes on a regular basis (usually daily) and make them available for download. These include: