package octez-proto-libs

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

Module Tezos_protocol_environment.ContextSource

Sourcetype ('ctxt, 'tree) ops = (module Tezos_protocol_environment__.Environment_context_intf.V5.S with type t = 'ctxt and type tree = 'tree)
Sourcetype _ kind = private ..
Sourcetype ('a, 'b) equality_witness
Sourcetype cache

Abstract type of a cache. A cache is made of subcaches. Each subcache has its own size limit. The limit of its subcache is called a layout and can be initialized via the set_cache_layout function.

Sourcetype t = private
  1. | Context : {
    1. kind : 'a kind;
    2. impl_name : string;
    3. ctxt : 'a;
    4. ops : ('a, 'b) ops;
    5. equality_witness : ('a, 'b) equality_witness;
    6. cache : cache;
    } -> t

A context is purely functional description of a state. This state is used to interpret operations, and more generally, to validate blocks.

This type is private because a context must be constructed using make, which is a smart constructor.

Sourceval equal_config : Tezos_context_sigs.Config.t -> Tezos_context_sigs.Config.t -> bool
Sourcetype key = string list
Sourcetype value = bytes
Sourcetype tree
Sourceval mem : t -> key -> bool Lwt.t
Sourceval mem_tree : t -> key -> bool Lwt.t
Sourceval find : t -> key -> value option Lwt.t
Sourceval find_tree : t -> key -> tree option Lwt.t
Sourceval list : t -> ?offset:int -> ?length:int -> key -> (string * tree) list Lwt.t
Sourceval length : t -> key -> int Lwt.t
Sourceval add : t -> key -> value -> t Lwt.t
Sourceval add_tree : t -> key -> tree -> t Lwt.t
Sourceval remove : t -> key -> t Lwt.t
Sourceval fold : ?depth:Tezos_context_sigs__Context.depth -> t -> key -> order:[ `Sorted | `Undefined ] -> init:'a -> f:(key -> tree -> 'a -> 'a Lwt.t) -> 'a Lwt.t
Sourceval config : t -> Tezos_context_sigs.Config.t
Sourcemodule Tree : sig ... end
Sourceval set_protocol : t -> Tezos_crypto.Hashed.Protocol_hash.t -> t Lwt.t
Sourceval get_protocol : t -> Tezos_crypto.Hashed.Protocol_hash.t Lwt.t
Sourceval fork_test_chain : t -> protocol:Tezos_crypto.Hashed.Protocol_hash.t -> expiration:Tezos_base.TzPervasives.Time.Protocol.t -> t Lwt.t
Sourceval set_hash_version : t -> Tezos_crypto.Hashed.Context_hash.Version.t -> t Tezos_base.TzPervasives.tzresult Lwt.t
Sourceval get_hash_version : t -> Tezos_crypto.Hashed.Context_hash.Version.t
Sourcemodule Proof : sig ... end
type tree_proof := Proof.tree Proof.t
type stream_proof := Proof.stream Proof.t
type ('proof, 'result) verifier := 'proof -> (tree -> (tree * 'result) Lwt.t) -> (tree * 'result, [ `Proof_mismatch of string | `Stream_too_long of string | `Stream_too_short of string ]) result Lwt.t
Sourceval verify_tree_proof : (tree_proof, 'a) verifier
Sourceval verify_stream_proof : (stream_proof, 'a) verifier
Sourceval make : kind:'a kind -> impl_name:string -> ctxt:'a -> ops:('a, 'b) ops -> equality_witness:('a, 'b) equality_witness -> t

make kind impl_name ctxt ops equality_witness builds a context value. In this context, the cache is uninitialized: one must call load_cache to obtain a context with a valid cache. Otherwise, the context is not usable for all protocol-level features based on the cache, e.g., smart contract execution.

Sourcetype cache_key

A key uniquely identifies a cached value in the some subcache.

Abstract type for cached values.

This type is an extensible type since values stored in the cache are heterogeneous. Notice that the cache must be cleared during during protocol stitching because the data constructors of this type are incompatible between two protocols: if there remains values built with a data constructor of an old protocol, the new protocol will be confused to find that some keys it is interesting in have unexploitable values.

Sourcetype cache_value = ..

Cached values inhabit an extensible type.

Sourcemodule Cache : sig ... end

See Context.CACHE in sigs/v3/context.mli for documentation.

Sourcetype block_cache = {
  1. context_hash : Tezos_crypto.Hashed.Context_hash.t;
  2. cache : cache;
}

A cache is a block-dependent value: to know whether a cache can be reused or recycled in a given block, we need the block that produces it.

During its loading, a cache can be populated in two different ways:

  • values are computed immediately via the builder and inserted into the cache ; or,
  • the computation of the values is delayed and will be computed only when such value is required.

The first mode is intended to be used after a rebooting of the node for example. The main benefit being that it does not impact the validation time of a block since the cache's values will be reconstructed beforehand. The second mode is intended to be used for RPCs where reactivity is important: we do not want to recompute the full cache to execute the RPC but only the values which are necessary.

Sourcetype source_of_cache = [
  1. | `Force_load
    (*

    Force the cache domain to be reloaded from the context.

    *)
  2. | `Load
    (*

    Load a cache by iterating over the keys of its domain and by building a cached value for each key.

    This operation can introduce a significant slowdown proportional to the number of entries in the cache, and depending on their nature. As a consequence, loading a cache from that source should be done when the system has no strict constraint on execution time, e.g., during startup.

    *)
  3. | `Lazy
    (*

    Same as Load except that cached values are built on demand.

    This strategy makes load_cache run a lot faster and the overall cost of loading the cache is only proportional to the number of entries *actually used* (and also depends on their nature).

    Notice that, contrary to the `Load source of cache, this loading mode may also introduce latencies when entries are actually used since they are reconstructed on-the-fly.

    RPCs are a typical place where this Lazy loading makes sense since the number of entries used is generally low, and the cache cannot be inherited (as in the next case).

    *)
  4. | `Inherited of block_cache * Tezos_crypto.Hashed.Context_hash.t
    (*

    When we already have some block_cache.cache in memory coming from the validation of some block block_cache.context_hash, we can reuse or recycle its entries to reconstruct a cache to check some other block identified by a given Context_hash.t, which typically comes after block_cache.context_hash in the chain.

    This source is usually the most efficient way to build a cache in memory since the cache entries only change marginally from one block to one of its close descendants.

    *)
]

To load_cache in memory, we need to iterate over its domain and for each key found in the domain, a builder produces the associated value.

Sourceval load_cache : Tezos_crypto.Hashed.Block_hash.t -> t -> source_of_cache -> builder -> t Tezos_base.TzPervasives.tzresult Lwt.t

load_cache predecessor ctxt source builder populates the in-memory cache values cached in the current context during the validation of predecessor block. To achieve that, the function uses the strategy described by source, exploiting the builder to create cached values that are not already available in memory.

The builder is assumed to never fail when evaluated on the keys of the cache domain. Indeed, if a key had an associated value in the cache at some point in the past, it should have been a valid key. In other words, the construction of cache should be reproducible. For this reason, an error in builder is fatal.

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