package tezos-protocol-alpha

  1. Overview
  2. Docs
package tezos-protocol-alpha
Legend:
Library
Module
Module type
Parameter
Class
Class type

State of the validation.

Two parts:

1. Context.t: what is stored between blocks, this includes an Irmin tree typically stored on disk and the cache (stored in RAM).

2. Additional information needed during the validation of a block but not persisted across blocks, always stored in RAM. The gas counter is here.

Alpha_context.t is actually implemented as Raw_context.t. The difference is that Alpha_context.mli does not expose this so functions manipulating an Alpha_context.t are guaranteed to only access the context through the storage modules exposed in Alpha_context.mli. These modules are in charge of maintaining invariants over the structure of the context.

Errors

type Tezos_protocol_environment_alpha.Error_monad.error +=
  1. | Too_many_internal_operations
type missing_key_kind =
  1. | Get
  2. | Set
  3. | Del
  4. | Copy
type storage_error =
  1. | Incompatible_protocol_version of string
  2. | Missing_key of string list * missing_key_kind
  3. | Existing_key of string list
  4. | Corrupted_data of string list

An internal storage error that should not happen

type Tezos_protocol_environment_alpha.Error_monad.error +=
  1. | Failed_to_parse_parameter of bytes

Abstract Context

type t

Abstract view of the context. Includes a handle to the functional key-value database (Context.t) along with some in-memory values (gas, etc.).

type root = t
val protocol_migration_internal_message : Sc_rollup_inbox_message_repr.internal_inbox_message

The internal message to be injected into the smart rollups’ shared inbox when validating the very first block of this protocol.

val protocol_migration_serialized_message : Sc_rollup_inbox_message_repr.serialized

Serialized version of protocol_migration_internal_message.

Retrieves the state of the database and gives its abstract view. It also returns wether this is the first block validated with this version of the protocol.

type previous_protocol =
  1. | Genesis of Parameters_repr.t
  2. | Nairobi_017

Returns the state of the database resulting of operations on its abstract view

val current_level : t -> Level_repr.t
val predecessor_timestamp : t -> Tezos_protocol_environment_alpha.Time.t
val current_timestamp : t -> Tezos_protocol_environment_alpha.Time.t
val constants : t -> Constants_parametric_repr.t
val round_durations : t -> Round_repr.Durations.t
val cycle_eras : t -> Level_repr.cycle_eras

Retrieve the cycle eras.

val credit_collected_fees_only_call_from_token : t -> Tez_repr.t -> t Tezos_protocol_environment_alpha.Error_monad.tzresult

Increment the current block fee stash that will be credited to the payload producer's account at finalize_application

val spend_collected_fees_only_call_from_token : t -> Tez_repr.t -> t Tezos_protocol_environment_alpha.Error_monad.tzresult

Decrement the current block fee stash that will be credited to the payload producer's account at finalize_application

val get_collected_fees : t -> Tez_repr.t

Returns the current block fee stash that will be credited to the payload producer's account at finalize_application

consume_gas_limit_in_block ctxt gas_limit checks that gas_limit is well-formed (i.e. it does not exceed the hard gas limit per operation as defined in ctxt, and it is positive), then consumes gas_limit in the current block gas level of ctxt.

  • returns

    Error Gas_limit_repr.Gas_limit_too_high if gas_limit is greater than the allowed limit for operation gas level or negative.

  • returns

    Error Block_quota_exceeded if not enough gas remains in the block.

val set_gas_limit : t -> 'a Gas_limit_repr.Arith.t -> t
val set_gas_unlimited : t -> t
val gas_level : t -> Gas_limit_repr.t
val gas_consumed : since:t -> until:t -> Gas_limit_repr.Arith.fp
val remaining_operation_gas : t -> Gas_limit_repr.Arith.fp
val update_remaining_operation_gas : t -> Gas_limit_repr.Arith.fp -> t
val block_gas_level : t -> Gas_limit_repr.Arith.fp
val update_remaining_block_gas : t -> Gas_limit_repr.Arith.fp -> t
type Tezos_protocol_environment_alpha.Error_monad.error +=
  1. | Undefined_operation_nonce
val init_origination_nonce : t -> Tezos_protocol_environment_alpha.Operation_hash.t -> t

init_origination_nonce ctxt hash initialise the origination nonce in memory from hash. See Origination_nonce.t for more information.

val unset_origination_nonce : t -> t

unset_origination_nonce ctxt unset the origination nonce in memory. To be used only when no more origination can be done in that operation. See Origination_nonce.t for more information.

Generic accessors

type key = string list
type value = bytes
type tree
type local_context
module type T = Raw_context_intf.T with type root := root and type key := key and type value := value and type tree := tree
include T with type t := t and type local_context := local_context
include Raw_context_intf.VIEW with type key := key with type value := value with type tree := tree with type t := t

Getters

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

val mem_tree : t -> key -> bool Tezos_protocol_environment_alpha.Lwt.t

mem_tree t k is like mem but for trees.

get t k is an Lwt promise that resolves to Ok v if k is bound to the value v in t and Storage_ErrorMissing_key otherwise.

get_tree is like get but for trees.

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.

val find_tree : t -> key -> tree option Tezos_protocol_environment_alpha.Lwt.t

find_tree t k is like find but for trees.

val list : t -> ?offset:int -> ?length:int -> key -> (string * tree) list Tezos_protocol_environment_alpha.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.

Setters

init t k v is an Lwt promise that resolves to Ok c if:

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

It is Storage_errorExisting_key if k is already bound in t.

init_tree is like init but for trees.

update t k v is an Lwt promise that resolves to Ok c if:

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

It is Storage_errorMissing_key if k is not already bound in t.

update_tree is like update but for trees.

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.

add_tree is like add but for trees.

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.

remove_existing t k v is an Lwt promise that resolves to Ok c if:

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

remove_existing_tree t k v is an Lwt promise that reolves to Ok c if:

  • k is bound in t to a tree;
  • k is unbound in c;
  • and c is similar to t otherwise.
val add_or_remove : t -> key -> value option -> t Tezos_protocol_environment_alpha.Lwt.t

add_or_remove t k v is:

  • add t k x if v is Some x;
  • remove t k otherwise.
val add_or_remove_tree : t -> key -> tree option -> t Tezos_protocol_environment_alpha.Lwt.t

add_or_remove_tree t k v is:

  • add_tree t k x if v is Some x;
  • remove t k otherwise.

Folds

val fold : ?depth:Raw_context_intf.depth -> t -> key -> order:[ `Sorted | `Undefined ] -> init:'a -> f:(key -> tree -> 'a -> 'a Tezos_protocol_environment_alpha.Lwt.t) -> 'a Tezos_protocol_environment_alpha.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.

Hash configurations

val config : t -> Raw_context_intf.config

config t is t's hash configuration.

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.

Most of the time, this function does not perform any I/O as the length is cached in the tree. It may perform one read to load the root node of the tree in case it has not been loaded already. The initial constant is the same between list and length. They both perform the same kind of I/O reads. While list usually performs a linear number of reads, length does at most one.

module Tree : Raw_context_intf.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.

Proofs are compact representations of trees which can be shared between peers.

type ('proof, 'result) verifier := 'proof -> (tree -> (tree * 'result) Tezos_protocol_environment_alpha.Lwt.t) -> (tree * 'result, [ `Proof_mismatch of string | `Stream_too_long of string | `Stream_too_short of string ]) Tezos_protocol_environment_alpha.Pervasives.result Tezos_protocol_environment_alpha.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*.

val 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.

val verify_stream_proof : (stream_proof, 'a) verifier

verify_stream is the verifier of stream proofs.

val equal_config : Raw_context_intf.config -> Raw_context_intf.config -> bool

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

val project : t -> root

Internally used in Storage_functors to escape from a view.

val absolute_key : t -> key -> key

Internally used in Storage_functors to retrieve a full key from partial key relative a view.

Raised if block gas quota is exhausted during gas consumption.

type Tezos_protocol_environment_alpha.Error_monad.error +=
  1. | Operation_quota_exceeded

Raised if operation gas quota is exhausted during gas consumption.

Internally used in Storage_functors to consume gas from within a view. May raise Block_quota_exceeded or Operation_quota_exceeded.

Check if consume_gas will fail

val description : t Storage_description.t

with_local_context ctxt key f runs function f over the local context at path key of the global ctxt. Using the local context f can perform faster context accesses under key.

module Local_context : sig ... end

Local_context provides functions for local access from a specific directory.

val reset_internal_nonce : t -> t

Initialize the local nonce used for preventing a script to duplicate an internal operation to replay it.

val fresh_internal_nonce : t -> (t * int) Tezos_protocol_environment_alpha.Error_monad.tzresult

Increments the internal operation nonce.

val record_internal_nonce : t -> int -> t

Mark an internal operation nonce as taken.

val internal_nonce_already_recorded : t -> int -> bool

Check is the internal operation nonce has been taken.

val fold_map_temporary_lazy_storage_ids : t -> (Lazy_storage_kind.Temp_ids.t -> Lazy_storage_kind.Temp_ids.t * 'res) -> t * 'res
module Cache : sig ... end
val record_non_consensus_operation_hash : t -> Tezos_protocol_environment_alpha.Operation_hash.t -> t
val non_consensus_operations : t -> Tezos_protocol_environment_alpha.Operation_hash.t list
val record_dictator_proposal_seen : t -> t

Record that the dictator already voted in this block.

val dictator_proposal_seen : t -> bool

Checks whether the dictator voted in this block.

init_sampler_for_cycle ctxt cycle seed state caches the seeded stake sampler (a.k.a. seed, state) for cycle in memory for quick access.

  • returns

    Error Sampler_already_set if the sampler was already cached.

sampler_for_cycle ~read ctxt cycle returns the seeded stake sampler for cycle. The sampler is read in memory if init_sampler_for_cycle or sampler_for_cycle was previously called for the same cycle. Otherwise, it is read "on-disk" with the read function and then cached in ctxt like init_sampler_for_cycle.

val init_stake_distribution_for_current_cycle : t -> Tez_repr.t Tezos_protocol_environment_alpha.Signature.Public_key_hash.Map.t -> t
module Internal_for_tests : sig ... end
module type CONSENSUS = sig ... end
module Consensus : CONSENSUS with type t := t and type slot := Slot_repr.t and type 'a slot_map := 'a Slot_repr.Map.t and type slot_set := Slot_repr.Set.t and type round := Round_repr.t and type consensus_pk := consensus_pk
module Tx_rollup : sig ... end
module Sc_rollup_in_memory_inbox : sig ... end
module Dal : sig ... end
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