package octez-libs

  1. Overview
  2. Docs
A package that contains multiple base libraries used by the Octez suite

Install 

dune-project
 Dependency

www.tezos.com Readme Edit opam file Versions (5)

Authors

  1. T
    Tezos devteam

Maintainers

  1. C
    contact@tezos.com

Sources

tezos-octez-v20.1.tag.bz2
sha256=ddfb5076eeb0b32ac21c1eed44e8fc86a6743ef18ab23fff02d36e365bb73d61
sha512=d22a827df5146e0aa274df48bc2150b098177ff7e5eab52c6109e867eb0a1f0ec63e6bfbb0e3645a6c2112de3877c91a17df32ccbff301891ce4ba630c997a65

doc/octez-libs.base/Tezos_base/Block_locator/index.html

Module Tezos_base.Block_locatorSource

A locator t is a data structure which roughly represents a list of block hashes in the chain. These hashes go from the top of the chain to the bottom. It is sparse in the sense that the distance between two hashes increases exponentially when we move away from the head.

The distance between two hashes of a locator is randomized to prevent attacks. The seed is determined uniquely from the peer_id of the sender and the receiver so that the distance between two hashes can be recomputed locally. This is the purpose of the function to_steps.

The step representation is mostly used by the peer_validator and the bootstrap_pipeline modules.

The last step of a locator may be truncated. It is the case when the last step hits the caboose. Thus, such a non-strict step can be terminated by:

  • The genesis: it is the case in both Archive and Full modes as the caboose is always located down to the genesis block, but it is also the case in a Rolling mode early state (when caboose = genesis).
  • Any block: it is the case in Rolling mode when the caboose is higher than the genesis. Indeed, the caboose can be located (almost) anywhere.

Type for sparse block locators (/à la/ Bitcoin).

Sourceval pp : Format.formatter -> t -> unit
Sourceval pp_short : Format.formatter -> t -> unit
Sourceval encoding : t Data_encoding.t
Sourceval bounded_encoding : max_header_size:int -> max_length:int -> unit -> t Data_encoding.t
Sourcetype seed = {
  1. sender_id : Tezos_base.P2p_peer.Id.t;
  2. receiver_id : Tezos_base.P2p_peer.Id.t;
}

Argument to the seed used to randomize the locator.

Sourceval estimated_length : seed -> t -> int

estimated_length seed locator estimates the length of the chain represented by locator using seed.

compute ~get_predecessor ~caboose ~size block_hash header seed returns a sparse block locator whose header is the given header and whose sparse block is computed using seed to compute random jumps from the block_hash, adding the caboose at the end of the sparse block. The sparse block locator contains at most size + 1 elements, including the caboose.

Sourcetype step = {
  1. block : Tezos_crypto.Hashed.Block_hash.t;
  2. predecessor : Tezos_crypto.Hashed.Block_hash.t;
  3. step : int;
  4. strict_step : bool;
}

A 'step' in a locator is a couple of consecutive hashes in the locator, and the expected difference of level between the two blocks (or an upper bounds when strict_step = false).

Sourceval pp_step : Format.formatter -> step -> unit
Sourceval to_steps : seed -> t -> step list

to_steps seed t builds all the 'steps' composing the locator using the given seed, starting with the oldest one (typically the predecessor of the first step will be the `caboose`). All steps contains strict_step = true, except the oldest one.

Sourceval to_steps_truncate : limit:int -> save_point:Tezos_crypto.Hashed.Block_hash.t -> seed -> t -> step list

to_steps_truncate ~limit ~save_point seed t behaves as to_steps except that when the sum of all the steps already done, and the steps to do in order to reach the next block is superior to limit, we return a truncated list of steps, setting the predecessor of the last step as save_point and its field strict to false.

Sourcetype validity =
  1. | Unknown
  2. | Known_valid
  3. | Known_invalid

A block can either be known valid, invalid or unknown.

Sourceval unknown_prefix : is_known:(Tezos_crypto.Hashed.Block_hash.t -> validity Lwt.t) -> t -> (validity * t) Lwt.t

unknown_prefix ~is_known t either returns :

  • (Known_valid, (h, hist)) when we find a known valid block in the locator history (w.r.t. is_known), where h is the given locator header and hist is the unknown prefix ending with the known valid block.
  • (Known_invalid, (h, hist)) when we find a known invalid block (w.r.t. is_known) in the locator history, where h is the given locator header and hist is the unknown prefix ending with the known invalid block.
  • (Unknown, (h, hist)) when no block is known valid nor invalid (w.r.t. is_known), where (h, hist) is the given locator.