package tezos-base

  1. Overview
  2. Docs
package tezos-base
Legend:
Library
Module
Module type
Parameter
Class
Class type
include module type of struct include Tezos_stdlib end
module Bits = Tezos_stdlib.Bits
module Bloomer = Tezos_stdlib.Bloomer
module Bounded_heap = Tezos_stdlib.Bounded_heap
module Circular_buffer = Tezos_stdlib.Circular_buffer
module Compare = Tezos_stdlib.Compare
module FallbackArray = Tezos_stdlib.FallbackArray
module Lwt_dropbox = Tezos_stdlib.Lwt_dropbox
module Lwt_idle_waiter = Tezos_stdlib.Lwt_idle_waiter
module Lwt_pipe = Tezos_stdlib.Lwt_pipe
module Lwt_utils = Tezos_stdlib.Lwt_utils
module Memory = Tezos_stdlib.Memory
module Tag = Tezos_stdlib.Tag
module TzEndian = Tezos_stdlib.TzEndian
module TzFilename = Tezos_stdlib.TzFilename
module TzList = Tezos_stdlib.TzList
module TzString = Tezos_stdlib.TzString
module Utils = Tezos_stdlib.Utils
module Error_monad : module type of struct include Tezos_error_monad.Error_monad end

Tezos Protocol Implementation - Error Monad

include module type of Tezos_rpc
module RPC_answer : sig ... end
module RPC_arg : sig ... end
module RPC_context : sig ... end
module RPC_description : sig ... end
module RPC_directory : sig ... end
module RPC_encoding : sig ... end
module RPC_error : sig ... end
module RPC_path : sig ... end
module RPC_query : sig ... end
module RPC_service : sig ... end
include module type of Tezos_clic
module Clic : sig ... end

Command Line Interpretation Combinators.

include module type of Tezos_crypto
module BLS12_381 : sig ... end
module Base58 : sig ... end
module Blake2B : sig ... end

Tezos - Manipulation and creation of hashes

module Block_hash : sig ... end
module Block_metadata_hash : sig ... end
module Chain_id : sig ... end
module Context_hash : sig ... end
module Crypto_box : sig ... end

Tezos - X25519/XSalsa20-Poly1305 cryptography

module Ed25519 : sig ... end

Tezos - Ed25519 cryptography

module Hacl : sig ... end
module Helpers : sig ... end
module Operation_hash : sig ... end
module Operation_list_hash : sig ... end
module Operation_list_list_hash : sig ... end
module Operation_metadata_hash : sig ... end
module Operation_metadata_list_hash : sig ... end
module P256 : sig ... end

Tezos - P256 cryptography

module Protocol_hash : sig ... end
module Pvss : sig ... end

PVSS protocol, following

module Pvss_secp256k1 : sig ... end
module Rand : sig ... end
module S : sig ... end
module Secp256k1 : sig ... end

Tezos - Secp256k1 cryptography

module Secp256k1_group : sig ... end
module Signature : sig ... end
module Timelock : sig ... end

Timelock is a set of functions to handle time-locking a value and opening time-locked values.

module Znz : sig ... end
module Zplus : sig ... end
module Data_encoding = Data_encoding
include module type of Tezos_error_monad.TzLwtreslib
include sig ... end
module Monad : sig ... end
module Hashtbl : sig ... end
module Map : sig ... end
module Option : sig ... end
module Result : sig ... end
module Seq : sig ... end
module Seq_e : sig ... end
module Seq_s : sig ... end
module Seq_es : sig ... end
module Set : sig ... end
module WithExceptions : sig ... end
module List : sig ... end
module String : sig ... end
module Time = Time
module Fitness = Fitness
module User_activated = User_activated
module Block_header = Block_header
module Genesis = Genesis
module Operation = Operation
module Protocol = Protocol
module Test_chain_status = Test_chain_status
module Preapply_result = Preapply_result
module Block_locator = Block_locator
module Mempool = Mempool
module P2p_addr = P2p_addr
module P2p_identity = P2p_identity
module P2p_peer = P2p_peer
module P2p_point = P2p_point
module P2p_connection = P2p_connection
module P2p_stat = P2p_stat
module P2p_version = P2p_version
module P2p_rejection = P2p_rejection
module Distributed_db_version = Distributed_db_version
module Network_version = Network_version
include module type of Utils.Infix
val (--) : int -> int -> int list

Sequence: i--j is the sequence i;i+1;...;j-1;j

include module type of Tezos_error_monad.Error_monad
type error_category = [
  1. | `Branch
    (*

    Errors that may not happen in another context

    *)
  2. | `Temporary
    (*

    Errors that may not happen in a later context

    *)
  3. | `Permanent
    (*

    Errors that will happen no matter the context

    *)
]

Categories of error

include Tezos_error_monad.Sig.CORE with type error := error
val error_encoding : error Data_encoding.t
val pp : Stdlib.Format.formatter -> error -> unit
include Tezos_error_monad.Sig.EXT with type error := error
val register_error_kind : Tezos_error_monad.Sig.error_category -> id:string -> title:string -> description:string -> ?pp:(Stdlib.Format.formatter -> 'err -> unit) -> 'err Data_encoding.t -> (error -> 'err option) -> ('err -> error) -> unit

The error data type is extensible. Each module can register specialized error serializers id unique name of this error. Ex.: overflow_time_counter title more readable name. Ex.: Overflow of time counter description human readable description. Ex.: The time counter overflowed while computing delta increase pp formatter used to pretty print additional arguments. Ex.: The time counter overflowed while computing delta increase. Previous value %d. Delta: %d encoder decoder data encoding for this error. If the error has no value, specify Data_encoding.empty

val register_recursive_error_kind : Tezos_error_monad.Sig.error_category -> id:string -> title:string -> description:string -> pp:(Stdlib.Format.formatter -> 'err -> unit) -> (error Data_encoding.t -> 'err Data_encoding.t) -> (error -> 'err option) -> ('err -> error) -> unit

Same as register_error_kind but allow errors to wrap other errors.

The encoding argument is a function which will be given the encoding of errors as argument so that you can encode errors in errors using a fixpoint.

Another difference with register_error_kind is that pp is mandatory.

Classify an error using the registered kinds

type error += private
  1. | Unclassified of string
    (*

    Catch all error when 'deserializing' an error.

    *)

Catch all error when 'serializing' an error.

type error += private
  1. | Unregistered_error of Data_encoding.json
val json_of_error : error -> Data_encoding.json

An error serializer

val error_of_json : Data_encoding.json -> error

Error documentation

type error_info = {
  1. category : Tezos_error_monad.Sig.error_category;
  2. id : string;
  3. title : string;
  4. description : string;
  5. schema : Data_encoding.json_schema;
}

Error information

val pp_info : Stdlib.Format.formatter -> error_info -> unit
val find_info_of_error : error -> error_info

find_info_of_error e retrieves the `error_info` associated with the given error `e`.

  • raises [Invalid_argument]

    if the error is a wrapped error from another monad

  • raises [Not_found]

    if the error's constructor has not been registered

val get_registered_errors : unit -> error_info list

Retrieves information of registered errors

include Tezos_error_monad.Sig.WITH_WRAPPED with type error := error
module type Wrapped_error_monad = sig ... end

The purpose of this module is to wrap a specific error monad E into a more general error monad Eg.

val register_wrapped_error_kind : (module Wrapped_error_monad) -> id:string -> title:string -> description:string -> unit

Same as register_error_kind but for a wrapped error monad. The codec is defined in the module parameter. It makes the category of the error Wrapped instead of Main.

module TzTrace : Tezos_error_monad.Sig.TRACE with type 'error trace = 'error list
type 'error trace = 'error TzTrace.trace
include Tezos_error_monad.Sig.MONAD with type 'error trace := 'error TzTrace.trace
val ok : 'a -> ('a, 'trace) Stdlib.result

Successful result

val ok_unit : (unit, 'trace) Stdlib.result
val ok_none : ('a option, 'trace) Stdlib.result
val ok_some : 'a -> ('a option, 'trace) Stdlib.result
val ok_nil : ('a list, 'trace) Stdlib.result
val ok_true : (bool, 'trace) Stdlib.result
val ok_false : (bool, 'trace) Stdlib.result
val return : 'a -> ('a, 'trace) Stdlib.result Lwt.t

Successful return

val return_unit : (unit, 'trace) Stdlib.result Lwt.t

Successful return of ()

val return_none : ('a option, 'trace) Stdlib.result Lwt.t

Successful return of None

val return_some : 'a -> ('a option, 'trace) Stdlib.result Lwt.t

return_some x is a successful return of Some x

val return_nil : ('a list, 'trace) Stdlib.result Lwt.t

Successful return of []

val return_true : (bool, 'trace) Stdlib.result Lwt.t

Successful return of true

val return_false : (bool, 'trace) Stdlib.result Lwt.t

Successful return of false

val error : 'err -> ('a, 'err TzTrace.trace) Stdlib.result

Erroneous result

val fail : 'err -> ('a, 'err TzTrace.trace) Stdlib.result Lwt.t

Erroneous return

Infix operators for monadic binds/maps. All operators follow this naming convention:

  • the first character is >
  • the second character is > for bind and | for map
  • the next character is = for Lwt or ? for Error
  • the next character (if present) is = for Lwt or ? for Error, it is only used for operator that are within both monads.
val (>>=) : 'a Lwt.t -> ('a -> 'b Lwt.t) -> 'b Lwt.t

Lwt's bind reexported. Following Lwt's convention, in this operator and the ones below, = indicate we operate within Lwt.

val (>|=) : 'a Lwt.t -> ('a -> 'b) -> 'b Lwt.t

Lwt's map reexported. The | indicates a map rather than a bind.

val (>>?) : ('a, 'trace) Stdlib.result -> ('a -> ('b, 'trace) Stdlib.result) -> ('b, 'trace) Stdlib.result

Non-Lwt bind operator. In this operator and the ones below, ? indicates that we operate within the error monad.

val (>|?) : ('a, 'trace) Stdlib.result -> ('a -> 'b) -> ('b, 'trace) Stdlib.result

Non-Lwt map operator.

val (>>=?) : ('a, 'trace) Stdlib.result Lwt.t -> ('a -> ('b, 'trace) Stdlib.result Lwt.t) -> ('b, 'trace) Stdlib.result Lwt.t

Combined bind operator. The =? indicates that the operator acts within the combined error-lwt monad.

val (>|=?) : ('a, 'trace) Stdlib.result Lwt.t -> ('a -> 'b) -> ('b, 'trace) Stdlib.result Lwt.t

Combined map operator.

val (>>?=) : ('a, 'trace) Stdlib.result -> ('a -> ('b, 'trace) Stdlib.result Lwt.t) -> ('b, 'trace) Stdlib.result Lwt.t

Injecting bind operator. This is for transitioning from the simple Error monad to the combined Error-Lwt monad.

Note the order of the character: it starts with the error monad marker ? and has the Lwt monad marker later. This hints at the role of the operator to transition into Lwt.

val (>|?=) : ('a, 'trace) Stdlib.result -> ('a -> 'b Lwt.t) -> ('b, 'trace) Stdlib.result Lwt.t

Injecting map operator.

val record_trace : 'err -> ('a, 'err TzTrace.trace) Stdlib.result -> ('a, 'err TzTrace.trace) Stdlib.result

Enrich an error report (or do nothing on a successful result) manually

val trace : 'err -> ('b, 'err TzTrace.trace) Stdlib.result Lwt.t -> ('b, 'err TzTrace.trace) Stdlib.result Lwt.t

Automatically enrich error reporting on stack rewind

val record_trace_eval : (unit -> ('err, 'err TzTrace.trace) Stdlib.result) -> ('a, 'err TzTrace.trace) Stdlib.result -> ('a, 'err TzTrace.trace) Stdlib.result

Same as record_trace, for unevaluated error

val trace_eval : (unit -> ('err, 'err TzTrace.trace) Stdlib.result Lwt.t) -> ('b, 'err TzTrace.trace) Stdlib.result Lwt.t -> ('b, 'err TzTrace.trace) Stdlib.result Lwt.t

Same as trace, for unevaluated Lwt error

val error_unless : bool -> 'err -> (unit, 'err TzTrace.trace) Stdlib.result

Error on failed assertion

val error_when : bool -> 'err -> (unit, 'err TzTrace.trace) Stdlib.result
val fail_unless : bool -> 'err -> (unit, 'err TzTrace.trace) Stdlib.result Lwt.t

Erroneous return on failed assertion

val fail_when : bool -> 'err -> (unit, 'err TzTrace.trace) Stdlib.result Lwt.t
val unless : bool -> (unit -> (unit, 'trace) Stdlib.result Lwt.t) -> (unit, 'trace) Stdlib.result Lwt.t
val when_ : bool -> (unit -> (unit, 'trace) Stdlib.result Lwt.t) -> (unit, 'trace) Stdlib.result Lwt.t
val dont_wait : (exn -> unit) -> ('trace -> unit) -> (unit -> (unit, 'trace) Stdlib.result Lwt.t) -> unit

Wrapper around Lwt_utils.dont_wait

val join_p : unit Lwt.t list -> unit Lwt.t

A few aliases for Lwt functions

val all_p : 'a Lwt.t list -> 'a list Lwt.t
val both_p : 'a Lwt.t -> 'b Lwt.t -> ('a * 'b) Lwt.t
val join_e : (unit, 'err TzTrace.trace) Stdlib.result list -> (unit, 'err TzTrace.trace) Stdlib.result

Similar functions in the error monad

val all_e : ('a, 'err TzTrace.trace) Stdlib.result list -> ('a list, 'err TzTrace.trace) Stdlib.result
val both_e : ('a, 'err TzTrace.trace) Stdlib.result -> ('b, 'err TzTrace.trace) Stdlib.result -> ('a * 'b, 'err TzTrace.trace) Stdlib.result
val join_ep : (unit, 'err TzTrace.trace) Stdlib.result Lwt.t list -> (unit, 'err TzTrace.trace) Stdlib.result Lwt.t

Similar functions in the combined monad

val all_ep : ('a, 'err TzTrace.trace) Stdlib.result Lwt.t list -> ('a list, 'err TzTrace.trace) Stdlib.result Lwt.t
val both_ep : ('a, 'err TzTrace.trace) Stdlib.result Lwt.t -> ('b, 'err TzTrace.trace) Stdlib.result Lwt.t -> ('a * 'b, 'err TzTrace.trace) Stdlib.result Lwt.t
include Tezos_error_monad.Sig.MONAD_EXT with type error := error and type 'error trace := 'error TzTrace.trace
type tztrace = error TzTrace.trace
type 'a tzresult = ('a, tztrace) Stdlib.result
val pp_print_error : Stdlib.Format.formatter -> error TzTrace.trace -> unit
val pp_print_error_first : Stdlib.Format.formatter -> error TzTrace.trace -> unit

Pretty prints a trace as the message of its first error

val trace_encoding : error TzTrace.trace Data_encoding.t
val result_encoding : 'a Data_encoding.t -> 'a tzresult Data_encoding.t

A serializer for result of a given type

val generic_error : ('a, Stdlib.Format.formatter, unit, 'b tzresult) Stdlib.format4 -> 'a

Erroneous result (shortcut for generic errors)

val failwith : ('a, Stdlib.Format.formatter, unit, 'b tzresult Lwt.t) Stdlib.format4 -> 'a

Erroneous return (shortcut for generic errors)

val error_exn : exn -> 'a tzresult
val error_of_exn : exn -> error trace

error_of_exn e is a trace that carries the exception e. This function is intended to be used when interacting with a part of the code (most likely an external library) which uses exception. E.g.,

try
  Ok (make_some_call parameter)
with
  | (Not_found | Failure _) as e ->
    Error (error_of_exn e)
val record_trace_exn : exn -> 'a tzresult -> 'a tzresult
val trace_exn : exn -> 'b tzresult Lwt.t -> 'b tzresult Lwt.t
val generic_trace : ('a, Stdlib.Format.formatter, unit, ('b, error trace) Stdlib.result Lwt.t -> ('b, error trace) Stdlib.result Lwt.t) Stdlib.format4 -> 'a
val pp_exn : Stdlib.Format.formatter -> exn -> unit
val failure : ('a, Stdlib.Format.formatter, unit, error) Stdlib.format4 -> 'a
type error +=
  1. | Exn of exn

Wrapped OCaml/Lwt exception

type error +=
  1. | Canceled
val protect : ?on_error:(error trace -> 'a tzresult Lwt.t) -> ?canceler:Lwt_canceler.t -> (unit -> 'a tzresult Lwt.t) -> 'a tzresult Lwt.t

protect is a wrapper around Lwt.catch where the error handler operates over `trace` instead of `exn`. Besides, protect ~on_error ~canceler ~f may *cancel* f via a Lwt_canceler.t.

More precisely, protect ~on_error ~canceler f runs f (). An Lwt failure triggered by f () is wrapped into an Exn. If a canceler is given and Lwt_canceler.cancellation canceler is determined before f (), a Canceled error is returned.

Errors are caught by ~on_error (if given), otherwise the previous value is returned. An Lwt failure triggered by ~on_error is wrapped into an Exn

type error +=
  1. | Timeout
val with_timeout : ?canceler:Lwt_canceler.t -> unit Lwt.t -> (Lwt_canceler.t -> 'a tzresult Lwt.t) -> 'a tzresult Lwt.t
module Internal_event = Tezos_event_logging.Internal_event
module Filename : 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