package tezos-store

  1. Overview
  2. Docs

The module for handling chain-related operations such as setting the head of the chain, updating the chain state, forking testchains, ...

type nonrec chain_store = chain_store

The abstract type alias of a chain store.

type t = chain_store

The type alias of chain_store.

type testchain

The abstract type for testchain.

A type alias of a block identifier.

val global_store : chain_store -> store

global_store chain_store returns the global store of chain_store allowing to retrieve global infos.

chain_id chain_store returns chain id of chain_store.

val chain_dir : chain_store -> [ `Chain_dir ] Naming.directory

chain_dir chain_store returns the path of directory of chain_store.

history_mode chain_store returns the history mode of the chain_store.

genesis chain_store returns the Genesis.t of the chain_store.

val genesis_block : chain_store -> Block.t Lwt.t

genesis chain_store returns the genesis block of the chain_store.

val current_head : chain_store -> Block.t Lwt.t

current_head chain_store returns the current head of the chain_store.

val expiration : chain_store -> Tezos_base.Time.Protocol.t option

expiration chain_store returns the expiration date of the testchain's chain_store.

checkpoint chain_store returns the checkpoint associated to the chain_store.

The checkpoint is a block descriptor (Store_types.block_descriptor) pointing to a block that must be part of the chain. The checkpoint maintains the set of following invariants:

  • The store will only accept blocks that are above its checkpoint's level.
  • The checkpoint is updated periodically such that the following invariant holds: checkpoint.level >= all_head.last_allowed_fork_level

The checkpoint will tend to designate the highest block among all chain head's last_allowed_fork_level in a normal mode. This is not always true. i.e. after a snapshot import where the checkpoint will be set as the imported block and when the target block is reached, the checkpoint will be set at this point.

target chain_store returns the target block associated to the chain_store if there is one or None if it has already been reached.

The target is a (Store_types.block_descriptor) pointing to a future block that must be reached by the chain. When a block is received, if its level is equal to the target's block level then its hash must be also be the same. Otherwise, the block is considered as invalid and will be discarded.

The target should only be set manually. Whenever the target block is reached, the checkpoint will be updated to this block and the target will be set to None.

savepoint chain_store returns the savepoint associated to the chain_store.

The savepoint is a block descriptor (Store_types.block_descriptor) pointing to the lowest level block that has its metadata and/or context pruned with the following invariant:

is_stored(block) \and has_metadata(block) => block.level >= savepoint.level

For Full and Rolling history modes, the savepoint will be periodically updated at each store merge which happens when:

pred(head).last_allowed_fork_level < head.last_allowed_fork_level

On Archive history mode: savepoint = genesis.

caboose chain_store returns the caboose associated to the chain_store.

The caboose is a block descriptor (Store_types.block_descriptor) pointing to the lowest level block that we know present in the chain store, if the history mode is not Archive, it might not contain its metadata depending on the current savepoint:

is_stored(block) => block.level >= caboose.level

On Archive and Full history mode: caboose = genesis

mempool chain_store returns the mempool associated to the chain_store.

val block_of_identifier : chain_store -> block_identifier -> (Block.t, Tezos_error_monad.TzCore.error list) Stdlib.result Lwt.t

block_of_identifier chain_store identifier tries to return the block of the given identifier inside the given chain_store.

val block_of_identifier_opt : chain_store -> block_identifier -> Block.t option Lwt.t

block_of_identifier_opt chain_store identifier optional version of block_of_identifier.

val set_mempool : chain_store -> head:Tezos_crypto.Block_hash.t -> Tezos_base.Mempool.t -> (unit, Tezos_error_monad.TzCore.error list) Stdlib.result Lwt.t

set_mempool chain_store ~head mempool sets the mempool of the chain_store. Does nothing if head is not current_head which might happen when a new head concurrently arrives just before this operation being called.

live_blocks chain_store returns the set of previously computed live blocks for the current_head's chain_store.

compute_live_blocks ~block chain_store computes the set of live blocks and live operations relative to block. Does nothing if block is the chain_store's current head as it was previously updated in set_head.

Note: this operation should not be costly in most cases as recent blocks and operations are expected to be in a cache.

val set_head : chain_store -> Block.t -> (Block.t option, Tezos_error_monad.TzCore.error list) Stdlib.result Lwt.t

set_head chain_store block promotes the block as head of the chain_store and triggers an asynchronous store merge if a cycle is ready to be cemented. Triggering a merge will update the savepoint, checkpoint and caboose consistently with the chain_store's history mode. This function returns the previous head or None if the given block is below one of the current known heads. If block belongs to a new branch, the previous head will also be stored as an alternate head. Setting a new head will fail when the block is not fit to be promoted as head: too old or no metadata.

After a merge:

  • The checkpoint is updated to lafl(new_head) if it was below this level or unchanged otherwise;
  • The savepoint will be updated to : min(max_op_ttl(lafl(new_head)), lafl(new_head) - <cycle_length> * <history_mode_offset>) or will remain 0 in Archive mode;
  • The caboose will be updated to the same value as the savepoint in Rolling mode.

Note: lafl(new_head) is the last allowed fork level of the new head.

Warnings:

  • We expect blocks to be sequentially promoted as head using this function;
  • If a merge is triggered while another is happening, this function will block until the first merge is resolved.

known_heads chain_store returns the list of alternate heads for chain_store.

val is_ancestor : chain_store -> head:Store_types.block_descriptor -> ancestor:Store_types.block_descriptor -> bool Lwt.t

is_ancestor chain_store ~head ~ancestor checks whether the ancestor is a predecessor or head in chain_store.

val is_in_chain : chain_store -> Store_types.block_descriptor -> bool Lwt.t

is_in_chain chain_store block_descr checks that block_descr is an ancestor of chain_store's current head.

val is_acceptable_block : chain_store -> Store_types.block_descriptor -> bool Lwt.t

is_acceptable_block chain_store block_descr checks if block_descr would be a valid block to be stored in chain_store. Its predecessor is supposed to be already stored.

val best_known_head_for_checkpoint : chain_store -> checkpoint:Store_types.block_descriptor -> (Block.t, Tezos_error_monad.TzCore.error list) Stdlib.result Lwt.t

best_known_head_for_checkpoint chain_store checkpoint returns the fittest block among known heads in chain_store to be promoted as checkpoint if there is one.

val compute_locator : chain_store -> ?max_size:int -> Block.t -> Tezos_base.Block_locator.seed -> Tezos_base.Block_locator.t Lwt.t

compute_locator chain ?max_size head seed computes a locator of the chain from head to the chain's caboose or until the locator contains max_size steps. max_size defaults to 200.

val compute_protocol_locator : chain_store -> ?max_size:int -> proto_level:int -> Tezos_base.Block_locator.seed -> Tezos_base.Block_locator.t option Lwt.t

compute_protocol_locator chain ?max_size ~proto_level seed computes a locator for a specific protocol of level proto_level in the chain from the latest block with this protocol to its activation block or until the locator contains max_size steps. max_size defaults to 200.

val set_target : chain_store -> Store_types.block_descriptor -> (unit, Tezos_error_monad.TzCore.error list) Stdlib.result Lwt.t

set_target chain_store target_descr sets the target for chain_store. If target_descr is already known, set_checkpoint will be internally called. Fails if the target is below the current checkpoint.

val testchain : chain_store -> testchain option Lwt.t

testchain chain_store returns the active testchain to the given chain_store if it has been instantiated.

val testchain_forked_block : testchain -> Tezos_crypto.Block_hash.t

testchain_forked_block testchain returns the hash of the forked block of its parent chain.

val testchain_store : testchain -> chain_store

testchain_store testchain returns the chain store associated to this testchain.

val fork_testchain : chain_store -> testchain_id:Tezos_crypto.Chain_id.t -> forked_block:Block.t -> genesis_hash:Tezos_crypto.Block_hash.t -> genesis_header:Tezos_base.Block_header.t -> test_protocol:Tezos_crypto.Protocol_hash.t -> expiration:Tezos_base.Time.Protocol.t -> (testchain, Tezos_error_monad.TzCore.error list) Stdlib.result Lwt.t

fork testchain chain_store ~testchain_id ~forked_block ~genesis_hash ~genesis_header ~test_protocol ~expiration forks a testchain and activates it for chain_store. If a testchain with testchain_id already existed, it is then loaded from the store. If it was already activated, does nothing. It also registers this chain in the set of activated testchains.

val shutdown_testchain : chain_store -> (unit, Tezos_error_monad.TzCore.error list) Stdlib.result Lwt.t

shutdown_testchain chain_store closes and deactivates the testchain running for chain_store. Does nothing if no testchain is found running for chain_store.

Chain's protocols

val find_activation_block : chain_store -> protocol_level:int -> Store_types.Protocol_levels.activation_block option Lwt.t

find_activation_block chain_store ~protocol_level returns the block that activated the protocol of level protocol_level.

val find_protocol : chain_store -> protocol_level:int -> Tezos_crypto.Protocol_hash.t option Lwt.t

find_protocol chain_store ~protocol_level returns the protocol with the level protocol_level.

all_protocol_levels chain_store returns all the protocols registered in chain_store.

val may_update_protocol_level : chain_store -> ?pred:Block.block -> ?protocol_level:int -> (Block.block * Tezos_crypto.Protocol_hash.t) -> (unit, Tezos_error_monad.TzCore.error list) Stdlib.result Lwt.t

may_update_protocol_level chain_store ?pred ?protocol_level (block, ph) updates the protocol level for the protocol ph in chain_store with the activation block. If pred is not provided, it reads the block's predecessor and check that the block's protocol level is increasing compared to its predecessor. If protocol_level is provided, we use this value instead of the protocol level found in block. If a previous entry is found, it overwrites it.

val may_update_ancestor_protocol_level : chain_store -> head:Block.block -> (unit, Tezos_error_monad.TzCore.error list) Stdlib.result Lwt.t

may_update_ancestor_protocol_level chain_store ~head tries to find the activation block of the head's protocol, checks that its an ancestor and tries to update it if that's not the case. If the registered activation block is not reachable (already pruned), this function does nothing.

watcher chain_store instantiates a new block watcher for chain_store.

val get_rpc_directory : chain_store -> Block.t -> (chain_store * Block.t) Tezos_rpc.RPC_directory.t option Lwt.t

get_rpc_directory chain_store block returns the RPC directory associated to the block.

val set_rpc_directory : chain_store -> protocol_hash:Tezos_crypto.Protocol_hash.t -> next_protocol_hash:Tezos_crypto.Protocol_hash.t -> (chain_store * Block.t) Tezos_rpc.RPC_directory.t -> unit Lwt.t

set_rpc_directory chain_store ph next_ph rpc_directory sets a rpc_directory for the protocol ph and next protocol next_ph in chain_store.

OCaml

Innovation. Community. Security.