From 5b29eda4c6f611466892ec60614a25731409c154 Mon Sep 17 00:00:00 2001 From: Nicolas Ayache Date: Thu, 30 Jun 2022 11:50:21 +0200 Subject: [PATCH 1/7] Proto: Alpha_context docstrings for Big_map. --- src/proto_alpha/lib_protocol/alpha_context.mli | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/src/proto_alpha/lib_protocol/alpha_context.mli b/src/proto_alpha/lib_protocol/alpha_context.mli index 64e2726632d2..b07393790682 100644 --- a/src/proto_alpha/lib_protocol/alpha_context.mli +++ b/src/proto_alpha/lib_protocol/alpha_context.mli @@ -1365,12 +1365,19 @@ module Seed : sig context -> seed_computation_status tzresult Lwt.t end +(** Big maps are a data structure storing key-value associations, just like + regular maps, but here the whole content of the structure is not loaded in + memory when interacting with it. + They are thus suitable for a Michelson contract, for instance, when there are a + lot of bindings, but only a few items are accessed at each contract call. *) module Big_map : sig + (** A big map is referenced in the storage by its identifier. *) module Id : sig type t = Lazy_storage_kind.Big_map.Id.t val encoding : t Data_encoding.t + (** Big map argument for a RPC call. *) val rpc_arg : t RPC_arg.arg (** In the protocol, to be used in parse_data only *) @@ -1380,17 +1387,23 @@ module Big_map : sig val unparse_to_z : t -> Z.t end + (** Create a fresh big map in the context. *) val fresh : temporary:bool -> context -> (context * Id.t) tzresult Lwt.t + (** Carbonated membership of a key (from its hash) in a big map. *) val mem : context -> Id.t -> Script_expr_hash.t -> (context * bool) tzresult Lwt.t + (** Carbonated retrieval of the value associated to a key (from its hash) in + a big map, if any. *) val get_opt : context -> Id.t -> Script_expr_hash.t -> (context * Script.expr option) tzresult Lwt.t + (** Carbonated retrieval of the key and value types of the bindings in a big + map referenced by its identifier, if this identifier is actually bound to a big map in the context. *) val exists : context -> Id.t -> @@ -1411,14 +1424,18 @@ module Big_map : sig Id.t -> (context * (Script_expr_hash.t * Script.expr) list) tzresult Lwt.t + (** The type of big map updates. When [value = None], the potential binding + associated to the [key] will be removed. *) type update = { key : Script_repr.expr; + (** The key is ignored by an update but is shown in the receipt. *) key_hash : Script_expr_hash.t; value : Script_repr.expr option; } type updates = update list + (** The types of keys and values in a big map. *) type alloc = {key_type : Script_repr.expr; value_type : Script_repr.expr} end -- GitLab From 77b1cee168e37f2aa3b9bd35c14826a60966f8fd Mon Sep 17 00:00:00 2001 From: Nicolas Ayache Date: Thu, 30 Jun 2022 13:26:36 +0200 Subject: [PATCH 2/7] Proto: Alpha_context docstrings for Sapling. --- src/proto_alpha/lib_protocol/alpha_context.mli | 2 ++ 1 file changed, 2 insertions(+) diff --git a/src/proto_alpha/lib_protocol/alpha_context.mli b/src/proto_alpha/lib_protocol/alpha_context.mli index b07393790682..0b9476cf87b3 100644 --- a/src/proto_alpha/lib_protocol/alpha_context.mli +++ b/src/proto_alpha/lib_protocol/alpha_context.mli @@ -1455,6 +1455,7 @@ module Sapling : sig val unparse_to_z : t -> Z.t (* To be used in unparse_data only *) end + (** Create a fresh sapling state in the context. *) val fresh : temporary:bool -> context -> (context * Id.t) tzresult Lwt.t type diff = private { @@ -1521,6 +1522,7 @@ module Sapling : sig string -> (context * (Int64.t * state) option) tzresult Lwt.t + (** See {!Lazy_storage_kind.Sapling_state.alloc}. *) type alloc = {memo_size : Memo_size.t} type updates = diff -- GitLab From d19a6032b584ff04e471768840decb593e03cc19 Mon Sep 17 00:00:00 2001 From: Nicolas Ayache Date: Thu, 30 Jun 2022 13:35:21 +0200 Subject: [PATCH 3/7] Proto: Alpha_context docstrings for remaining Consensus definitions. --- src/proto_alpha/lib_protocol/alpha_context.mli | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/src/proto_alpha/lib_protocol/alpha_context.mli b/src/proto_alpha/lib_protocol/alpha_context.mli index 0b9476cf87b3..ca3c15c30e51 100644 --- a/src/proto_alpha/lib_protocol/alpha_context.mli +++ b/src/proto_alpha/lib_protocol/alpha_context.mli @@ -4677,9 +4677,15 @@ module Consensus : sig and type slot_set := Slot.Set.t and type round := Round.t + (** [store_endorsement_branch context branch] sets the "endorsement branch" + (see {!Storage.Tenderbake.Endorsement_branch} to [branch] in both the disk + storage and RAM. *) val store_endorsement_branch : context -> Block_hash.t * Block_payload_hash.t -> context Lwt.t + (** [store_grand_parent_branch context branch] sets the "grand-parent branch" + (see {!Storage.Tenderbake.Grand_parent_branch} to [branch] in both the + disk storage and RAM. *) val store_grand_parent_branch : context -> Block_hash.t * Block_payload_hash.t -> context Lwt.t end -- GitLab From 114b1aadf7b350b9554d78942e136c1cb223066f Mon Sep 17 00:00:00 2001 From: Nicolas Ayache Date: Thu, 30 Jun 2022 14:05:35 +0200 Subject: [PATCH 4/7] Proto: Alpha_context docstrings for First_level_of_protocol.get. --- src/proto_alpha/lib_protocol/alpha_context.mli | 1 + 1 file changed, 1 insertion(+) diff --git a/src/proto_alpha/lib_protocol/alpha_context.mli b/src/proto_alpha/lib_protocol/alpha_context.mli index ca3c15c30e51..fa53c58bdf9b 100644 --- a/src/proto_alpha/lib_protocol/alpha_context.mli +++ b/src/proto_alpha/lib_protocol/alpha_context.mli @@ -4664,6 +4664,7 @@ module Ticket_balance : sig end module First_level_of_protocol : sig + (** Get the level of the first block of this protocol. *) val get : context -> Raw_level.t tzresult Lwt.t end -- GitLab From 503672e2bce54ad3b6d38d080c309ae7718f3895 Mon Sep 17 00:00:00 2001 From: Nicolas Ayache Date: Fri, 2 Sep 2022 10:02:23 +0200 Subject: [PATCH 5/7] Proto: Alpha_context docstrings for Zk_rollup. --- src/proto_alpha/lib_protocol/alpha_context.mli | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/src/proto_alpha/lib_protocol/alpha_context.mli b/src/proto_alpha/lib_protocol/alpha_context.mli index fa53c58bdf9b..2692ad862991 100644 --- a/src/proto_alpha/lib_protocol/alpha_context.mli +++ b/src/proto_alpha/lib_protocol/alpha_context.mli @@ -2398,6 +2398,8 @@ module Bond_id : sig end end +(** This module re-exports definitions from {!Zk_rollup_repr} and + {!Zk_rollup_storage}. *) module Zk_rollup : sig module Address : S.HASH @@ -2407,12 +2409,14 @@ module Zk_rollup : sig val to_scalar : t -> scalar + (** This module re-exports definitions from {!Zk_rollup_state_repr}. *) module State : sig type t = scalar array val encoding : t Data_encoding.t end + (** This module re-exports definitions from {!Zk_rollup_account_repr}. *) module Account : sig module SMap : Map.S with type key = string @@ -2430,6 +2434,7 @@ module Zk_rollup : sig val encoding : t Data_encoding.t end + (** This module re-exports definitions from {!Zk_rollup_operation_repr}. *) module Operation : sig type t = { op_code : int; -- GitLab From 5034832c428dfc4dda329700cdd055ef37ca4d8c Mon Sep 17 00:00:00 2001 From: Nicolas Ayache Date: Fri, 2 Sep 2022 10:11:13 +0200 Subject: [PATCH 6/7] Proto: Alpha_context docstrings for Dal_errors. --- src/proto_alpha/lib_protocol/alpha_context.mli | 1 + 1 file changed, 1 insertion(+) diff --git a/src/proto_alpha/lib_protocol/alpha_context.mli b/src/proto_alpha/lib_protocol/alpha_context.mli index 2692ad862991..63afa33f0359 100644 --- a/src/proto_alpha/lib_protocol/alpha_context.mli +++ b/src/proto_alpha/lib_protocol/alpha_context.mli @@ -2846,6 +2846,7 @@ module Dal : sig end end +(** This module re-exports definitions from {!Dal_errors_repr}. *) module Dal_errors : sig (* DAL/FIXME: https://gitlab.com/tezos/tezos/-/issues/3168 do not expose these errors and return them in functions -- GitLab From 3d1548bbe46e38b0878d4323ef432d11d557669f Mon Sep 17 00:00:00 2001 From: Nicolas Ayache Date: Fri, 2 Sep 2022 10:11:48 +0200 Subject: [PATCH 7/7] Proto: Alpha_context docstrings for Dal. --- src/proto_alpha/lib_protocol/alpha_context.mli | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/src/proto_alpha/lib_protocol/alpha_context.mli b/src/proto_alpha/lib_protocol/alpha_context.mli index 63afa33f0359..b65cba0af6b0 100644 --- a/src/proto_alpha/lib_protocol/alpha_context.mli +++ b/src/proto_alpha/lib_protocol/alpha_context.mli @@ -2793,7 +2793,9 @@ module Vote : sig val clear_current_proposal : context -> context Lwt.t end +(** This module exposes definitions for the data-availability layer. *) module Dal : sig + (** This module re-exports definitions from {!Dal_slot_repr.Index}. *) module Slot_index : sig type t @@ -2808,6 +2810,8 @@ module Dal : sig val compare : t -> t -> int end + (** This module re-exports definitions from {!Dal_endorsement_repr} and + {!Raw_context.Dal}. *) module Endorsement : sig type t @@ -2824,6 +2828,8 @@ module Dal : sig val record_available_shards : context -> t -> int list -> context end + (** This module re-exports definitions from {!Dal_slot_repr}, + {!Dal_slot_storage} and {!Raw_context.Dal}. *) module Slot : sig type header = Dal.commitment -- GitLab