package octez-proto-libs

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

Module Make.ContextSource

View over the context store, restricted to types, access and functional manipulation of an existing context.

Sourcetype depth = [
  1. | `Eq of int
  2. | `Le of int
  3. | `Lt of int
  4. | `Ge of int
  5. | `Gt of int
]

The tree depth of a fold. See the fold function for more information.

Sourcetype config = Tezos_context_sigs.Config.t

The type for context configuration.

Sourceval equal_config : config -> config -> bool

The equality function for context configurations. If two context have the same configuration, they will generate the same context hashes.

Sourcemodule type VIEW = sig ... end
Sourcemodule Kind : sig ... end
Sourcemodule type TREE = sig ... end

Tree provides immutable, in-memory partial mirror of the context, with lazy reads and delayed writes. The trees are Merkle trees that carry the same hash as the part of the context they mirror.

Sourcemodule Proof : sig ... end
include VIEW with type key = string list and type value = bytes with type t = Tezos_protocol_environment__.Environment_context.Context.t
Sourcetype t

The type for context views.

Sourcetype key = string list

The type for context keys.

Sourcetype value = bytes

The type for context values.

Sourcetype tree

The type for context trees.

Getters

Sourceval mem : t -> key -> bool Lwt.t

mem t k is an Lwt promise that resolves to true iff k is bound to a value in t.

Sourceval mem_tree : t -> key -> bool Lwt.t

mem_tree t k is like mem but for trees.

Sourceval find : t -> key -> value option Lwt.t

find t k is an Lwt promise that resolves to Some v if k is bound to the value v in t and None otherwise.

Sourceval find_tree : t -> key -> tree option Lwt.t

find_tree t k is like find but for trees.

Sourceval list : t -> ?offset:int -> ?length:int -> key -> (string * tree) list Lwt.t

list t key is the list of files and sub-nodes stored under k in t. The result order is not specified but is stable.

offset and length are used for pagination.

Sourceval length : t -> key -> int Lwt.t

length t key is an Lwt promise that resolves to the number of files and sub-nodes stored under k in t.

It is equivalent to list t k >|= List.length but has a constant-time complexity.

Setters

Sourceval add : t -> key -> value -> t Lwt.t

add t k v is an Lwt promise that resolves to c such that:

  • k is bound to v in c;
  • and c is similar to t otherwise.

If k was already bound in t to a value that is physically equal to v, the result of the function is a promise that resolves to t. Otherwise, the previous binding of k in t disappears.

Sourceval add_tree : t -> key -> tree -> t Lwt.t

add_tree is like add but for trees.

Sourceval remove : t -> key -> t Lwt.t

remove t k v is an Lwt promise that resolves to c such that:

  • k is unbound in c;
  • and c is similar to t otherwise.

Folding

Sourceval fold : ?depth:depth -> t -> key -> order:[ `Sorted | `Undefined ] -> init:'a -> f:(key -> tree -> 'a -> 'a Lwt.t) -> 'a Lwt.t

fold ?depth t root ~order ~init ~f recursively folds over the trees and values of t. The f callbacks are called with a key relative to root. f is never called with an empty key for values; i.e., folding over a value is a no-op.

The depth is 0-indexed. If depth is set (by default it is not), then f is only called when the conditions described by the parameter is true:

  • Eq d folds over nodes and values of depth exactly d.
  • Lt d folds over nodes and values of depth strictly less than d.
  • Le d folds over nodes and values of depth less than or equal to d.
  • Gt d folds over nodes and values of depth strictly more than d.
  • Ge d folds over nodes and values of depth more than or equal to d.

If order is `Sorted (the default), the elements are traversed in lexicographic order of their keys. For large nodes, it is memory-consuming, use `Undefined for a more memory efficient fold.

Configuration

Sourceval config : t -> config

config t is t's hash configuration.

Sourcemodule Tree : TREE with type t := t and type key := key and type value := value and type tree := tree

Tree provides immutable, in-memory partial mirror of the context, with lazy reads and delayed writes. The trees are Merkle trees that carry the same hash as the part of the context they mirror.

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 ]) Pervasives.result Lwt.t

verify p f runs f in checking mode. f is a function that takes a tree as input and returns a new version of the tree and a result. p is a proof, that is a minimal representation of the tree that contains what f should be expecting.

Therefore, contrary to trees found in a storage, the contents of the trees passed to f may not be available. For this reason, looking up a value at some path can now produce three distinct outcomes:

  • A value v is present in the proof p and returned : find tree path is a promise returning Some v;
  • path is known to have no value in tree : find tree path is a promise returning None; and
  • path is known to have a value in tree but p does not provide it because f should not need it: verify returns an error classifying path as an invalid path (see below).

The same semantics apply to all operations on the tree t passed to f and on all operations on the trees built from f.

The generated tree is the tree after f has completed. That tree is disconnected from any storage (i.e. index). It is possible to run operations on it as long as they don't require loading shallowed subtrees.

The result is Error (`Msg _) if the proof is rejected:

  • For tree proofs: when p.before is different from the hash of p.state;
  • For tree and stream proofs: when p.after is different from the hash of f p.state;
  • For tree proofs: when f p.state tries to access invalid paths in p.state;
  • For stream proofs: when the proof is not consumed in the exact same order it was produced;
  • For stream proofs: when the proof is too short or not empty once f is done.
  • raises Failure

    if the proof version is invalid or incompatible with the verifier.

type tree_proof := Proof.tree Proof.t

The type for tree proofs.

Guarantee that the given computation performs exactly the same state operations as the generating computation, *in some order*.

Sourceval verify_tree_proof : (tree_proof, 'a) verifier

verify_tree_proof is the verifier of tree proofs.

type stream_proof := Proof.stream Proof.t

The type for stream proofs.

Guarantee that the given computation performs exactly the same state operations as the generating computation, in the exact same order.

Sourceval verify_stream_proof : (stream_proof, 'a) verifier

verify_stream is the verifier of stream proofs.

Sourcemodule type PROOF_ENCODING = sig ... end
Sourcemodule Proof_encoding : sig ... end

Proof encoding for binary tree Merkle proofs

Sourceval complete : t -> string -> string list Lwt.t
Sourceval get_hash_version : t -> Context_hash.Version.t

Get the hash version used for the context

Sourceval set_hash_version : t -> Context_hash.Version.t -> t Error_monad.shell_tzresult Lwt.t

Set the hash version used for the context. It may recalculate the hashes of the whole context, which can be a long process. Returns an Error if the hash version is unsupported.

Sourcetype cache_key
Sourcetype cache_value = ..
Sourcemodule type CACHE = sig ... end
Sourcemodule Cache : CACHE with type t := t and type size := int and type index := int and type identifier := string and type key = cache_key and type value = cache_value
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