tezos-store 12.3 · OCaml Package

Block representation effectively stored on disk and its accessors.

Type definitions and encodings

type contents = {

header : Tezos_base.Block_header.t;
operations : Tezos_base.Operation.t list list;
block_metadata_hash : Tezos_crypto.Block_metadata_hash.t option;
operations_metadata_hashes : Tezos_crypto.Operation_metadata_hash.t list list option;

}

The type for the effective contents of a block is its header and the operations it contains. Their metadata hashes are also present.

type metadata = {

message : string option;
max_operations_ttl : int;
last_allowed_fork_level : Int32.t;
block_metadata : Bytes.t;
operations_metadata : Tezos_validation.Block_validation.operation_metadata list list;

}

The type for a block's metadata stored on disk. This representation is tightly linked to Tezos_validation.Block_validation.result which also has a strong dependency to Tezos_protocol_environment.validation_result.

Some fields exposed by Tezos_validation.Block_validation.result are unnecessary hence the lack of direct link.

type block = {

hash : Tezos_crypto.Block_hash.t;
contents : contents;
mutable metadata : metadata option;

}

The type for a block stored on disk.

The hash of the block is also stored to improve efficiency by not forcing the user to hash the header. This also allows to store fake hashes (e.g. sandbox's genesis blocks) but should be prevented by the API.

The metadata might not be present. The mutability flag allows users to re-use the same structure to store freshly loaded metadata.

type t = block

Genesis

val create_genesis_block : 
  genesis:Tezos_base.Genesis.t ->
  Tezos_crypto.Context_hash.t ->
  t

create_genesis_block ~genesis context_hash creates a default genesis block for the given genesis and its context_hash that contains metadata.

val contents_encoding : contents Data_encoding.t

Encoding for contents.

val metadata_encoding : metadata Data_encoding.t

Encoding for metadata.

val encoding : t Data_encoding.t

Encoding for t (and block).

Important An encoded block is prefixed by 4 bytes which stands for the length of the data. This is the case with Data_encoding.dynamic_size ~kind:`Uint30 encodings. This will be expected to be present to improve the store efficiency.

val pp_json : Format.formatter -> t -> unit

pp_json pretty-print a block as JSON.

Accessors

val descriptor : t -> Store_types.block_descriptor

descriptor block returns the pair (hash x level) of block.

val hash : t -> Tezos_crypto.Block_hash.t

hash block returns the stored block's hash. It is not guaranteed to be the same as Block_header.hash (header block) (e.g. in sandbox, the genesis block might have a fake hash).

val operations : t -> Tezos_base.Operation.t list list

operations block returns the list of list of operations contained in the block.

Block header accessors

val header : t -> Tezos_base.Block_header.t

val shell_header : t -> Tezos_base.Block_header.shell_header

val level : t -> Int32.t

val proto_level : t -> int

val predecessor : t -> Tezos_crypto.Block_hash.t

val timestamp : t -> Tezos_base.Time.Protocol.t

val validation_passes : t -> int

val operations_hash : t -> Tezos_crypto.Operation_list_list_hash.t

val fitness : t -> Tezos_base.Fitness.t

val context : t -> Tezos_crypto.Context_hash.t

val protocol_data : t -> Bytes.t

val block_metadata_hash : t -> Tezos_crypto.Block_metadata_hash.t option

val operations_metadata_hashes : 
  t ->
  Tezos_crypto.Operation_metadata_hash.t list list option

Metadata accessors

val metadata : t -> metadata option

val message : metadata -> string option

val max_operations_ttl : metadata -> int

val last_allowed_fork_level : metadata -> Int32.t

val block_metadata : metadata -> bytes

val operations_metadata : 
  metadata ->
  Tezos_validation.Block_validation.operation_metadata list list

Utility functions

val check_block_consistency : 
  ?genesis_hash:Tezos_crypto.Block_hash.t ->
  ?pred_block:t ->
  t ->
  (unit, Tezos_error_monad.TzCore.error list) result Lwt.t

check_block_consistency ?genesis_hash ?pred_block block checks that the stored data is consistent:

Does the hash stored equals the result of Block_header.hash of its header and, if not, is this the stored genesis_hash?
Is the block a successor of pred_block with regards to its level and its predecessor's hash?
Are the stored operations hashes consistent regarding the stored operations hashes?

val read_next_block_exn : Lwt_unix.file_descr -> (t * int) Lwt.t

read_next_block_exn fd reads from fd and decode the next block found in the descriptor. The fd's offset is moved as a side effect. This returns the decoded block along with the block length (number of bytes) of the encoded block. This function updates the given fd state and may raise Unix.error errors, see Unix.read.

val read_next_block : Lwt_unix.file_descr -> (t * int) option Lwt.t

Same as read_next_block fd but returns None if there was an error.

val pread_block_exn : Lwt_unix.file_descr -> file_offset:int -> (t * int) Lwt.t

pread_block_exn fd ~file_offset reads from fd and decode the block at offset file_offset in the descriptor. This returns the decoded block along with the block length (number of bytes) of the encoded block. This function may raise Unix.error errors, see Unix.read.

val pread_block : 
  Lwt_unix.file_descr ->
  file_offset:int ->
  (t * int) option Lwt.t

Same as pread_block fd ~file_offset but returns None if there was an error.

val decode_metadata : string -> metadata option

decode_metadata data decodes metadata from data encoded either with the new encoding or the legacy one.