package octez-shell-libs

  1. Overview
  2. Docs
package octez-shell-libs
Legend:
Library
Module
Module type
Parameter
Class
Class type

Snapshots for the store

Snapshots are canonical representations of the store and its associated context. Its main purposes it to save and load a current state with the minimal necessary amount of information. This snapshot may also be shared by third parties to facilitate the bootstrap process.

A snapshot of a block B is composed of :

  • The snapshot format version (see version), as a file;
  • The metadata of the snapshot (see metadata), as a file;
  • Some data to ensure snapshot consistency at import (see block_data), as a file;
  • A single context containing every key that the block B-1 needs (see below), as a file;
  • The set of (cemented and floating) blocks and their operations from the genesis block up to B -- it might contain less blocks if the snapshot is created from a store using a Rolling history mode of if it is created as a Rolling snapshot. Block's metadata are not exported. The cemented blocks are exported as a directory containing cycles as files, as well as some indexing data. The floating blocks are stored as a single file ;
  • The set of necessary Tezos protocols, as a directory containing the protocols as single files.

There are two kinds of snapshot formats that can be exported:

  • Raw is a directory containing the aforementioned data as independent files;
  • Tar is a tar archive containing all the data as a single archive file. To achieve better performances while loading the snapshot's information (version and metadata), we store first the version and then the metadata, to avoid seeking through the whole file.

Importing a snapshot will initialize a fresh store with the data contained in the snapshot. As snapshots may be shared between users, checks are made to ensure that no malicious data is loaded. For instance, we export the context of block B-1 to make sure that the application of the block B, given its predecessor's context, is valid.

Depending on the history mode, a snapshot might contain less blocks. In full, all blocks are present and importing such a snapshot will populate the Cemented_store with every cycle up to the snapshot's target block. Meanwhile, in Rolling, only a few previous blocks will be exported (max_op_ttl from the target block), only populating a Floating_block_store. Thus, the snapshot size greatly differs depending on the history mode used.

Snapshots may be created concurrently with a running node. It might impact the node for a few seconds to retrieve the necessary consistent information to produce the snapshot.

type Tezos_base.TzPervasives.error +=
  1. | Incompatible_history_mode of {
    1. requested : Tezos_shell_services.History_mode.t;
    2. stored : Tezos_shell_services.History_mode.t;
    }
  2. | Invalid_export_block of {
    1. block : Tezos_base.TzPervasives.Block_hash.t option;
    2. reason : [ `Pruned | `Pruned_pred | `Unknown | `Unknown_ancestor | `Caboose | `Genesis | `Not_enough_pred ];
    }
  3. | Invalid_export_path of string
  4. | Snapshot_file_not_found of string
  5. | Inconsistent_protocol_hash of {
    1. expected : Tezos_base.TzPervasives.Protocol_hash.t;
    2. got : Tezos_base.TzPervasives.Protocol_hash.t;
    }
  6. | Inconsistent_context_hash of {
    1. expected : Tezos_base.TzPervasives.Context_hash.t;
    2. got : Tezos_base.TzPervasives.Context_hash.t;
    }
  7. | Inconsistent_context of Tezos_base.TzPervasives.Context_hash.t
  8. | Cannot_decode_protocol of Tezos_base.TzPervasives.Protocol_hash.t
  9. | Cannot_write_metadata of string
  10. | Cannot_read of {
    1. kind : [ `Version | `Metadata | `Block_data | `Context | `Protocol_table | `Protocol | `Cemented_cycle ];
    2. path : string;
    }
  11. | Inconsistent_floating_store of Tezos_store_shared.Store_types.block_descriptor * Tezos_store_shared.Store_types.block_descriptor
  12. | Missing_target_block of Tezos_store_shared.Store_types.block_descriptor
  13. | Cannot_read_floating_store of string
  14. | Cannot_retrieve_block_interval
  15. | Invalid_cemented_file of string
  16. | Missing_cemented_file of string
  17. | Corrupted_floating_store
  18. | Invalid_protocol_file of string
  19. | Target_block_validation_failed of Tezos_base.TzPervasives.Block_hash.t * string
  20. | Directory_already_exists of string
  21. | Empty_floating_store
  22. | Cannot_remove_tmp_export_directory of string
  23. | Inconsistent_chain_import of {
    1. expected : Tezos_base.TzPervasives.Distributed_db_version.Name.t;
    2. got : Tezos_base.TzPervasives.Distributed_db_version.Name.t;
    }
  24. | Inconsistent_imported_block of Tezos_base.TzPervasives.Block_hash.t * Tezos_base.TzPervasives.Block_hash.t
type snapshot_format =
  1. | Tar
  2. | Raw
val pp_snapshot_format : Stdlib.Format.formatter -> snapshot_format -> unit
val snapshot_format_encoding : snapshot_format Tezos_base.TzPervasives.Data_encoding.t
module Snapshot_header : sig ... end
val read_snapshot_header : snapshot_path:string -> Snapshot_header.t Tezos_base.TzPervasives.tzresult Lwt.t

read_snapshot_header ~snapshot_path reads snapshot_file's header.

val export : ?snapshot_path:string -> snapshot_format -> ?rolling:bool -> block:Tezos_shell_services.Block_services.block -> store_dir:string -> context_dir:string -> chain_name:Tezos_base.TzPervasives.Distributed_db_version.Name.t -> progress_display_mode:Tezos_stdlib_unix.Animation.progress_display_mode -> Tezos_base.TzPervasives.Genesis.t -> unit Tezos_base.TzPervasives.tzresult Lwt.t

export ?snapshot_path snapshot_format ?rolling ~block ~store_dir ~context_dir ~chain_name genesis ~progress_display_mode reads from the store_dir and context_dir the current state of the node and produces a snapshot, of the given snapshot_format, in snapshot_file if it is provided. Otherwise, a snapshot file name is automatically generated using the target block as hint. If rolling is set, only the necessary blocks will be exported.

val import : snapshot_path:string -> ?patch_context: (Tezos_protocol_environment.Context.t -> Tezos_protocol_environment.Context.t Tezos_base.TzPervasives.tzresult Lwt.t) -> ?block:Tezos_base.TzPervasives.Block_hash.t -> ?check_consistency:bool -> dst_store_dir:string -> dst_context_dir:string -> chain_name:Tezos_base.TzPervasives.Distributed_db_version.Name.t -> configured_history_mode:Tezos_shell_services.History_mode.t option -> user_activated_upgrades:Tezos_base.TzPervasives.User_activated.upgrades -> user_activated_protocol_overrides: Tezos_base.TzPervasives.User_activated.protocol_overrides -> operation_metadata_size_limit: Tezos_shell_services.Shell_limits.operation_metadata_size_limit -> progress_display_mode:Tezos_stdlib_unix.Animation.progress_display_mode -> Tezos_base.TzPervasives.Genesis.t -> unit Tezos_base.TzPervasives.tzresult Lwt.t

import ~snapshot_path ?patch_context ?block ?check_consistency ~dst_store_dir ~dst_context_dir chain_name ~user_activated_upgrades ~user_activated_protocol_overrides ~ops_metadata_size_limit genesis populates dst_store_dir and dst_context_dir with the data contained in the snapshot_file. If check_consistency is unset, less security checks will be made and the import process will be more efficient. If block is set, the import process will make sure that the block is the correct one we load. patch_context, user_activated_upgrades and user_activated_protocol_overrides are passed to the validator in order to validate the target block. ops_metadata_size_limit determines the maximal size of the metadata to store while importing a snapshot.

val snapshot_file_kind : snapshot_path:string -> snapshot_format Tezos_base.TzPervasives.tzresult Lwt.t

snapshot_file_kind ~snapshot_file reads the snapshot_file and returns its kind. Returns Invalid if it is a wrong snapshot file.

OCaml

Innovation. Community. Security.

GitHub Discord Twitter Peertube RSS
About
Changelog Releases Industrial Users Academic Users Why OCaml
Ecosystem
Packages Community Events OCaml Planet Jobs
Resources
Install OCaml Get Started Platform Tools Language Manual Standard Library API Books Exercises Papers OCaml Playground Logo
Policies
Carbon Footprint Governance Privacy Code of Conduct