From f382f577e811ebbcf575304c2554379f33dcb6a4 Mon Sep 17 00:00:00 2001 From: Nicolas Ayache Date: Wed, 23 Mar 2022 13:36:42 +0100 Subject: [PATCH 01/10] Proto: doc for Script_set. --- src/proto_alpha/lib_protocol/script_set.mli | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/src/proto_alpha/lib_protocol/script_set.mli b/src/proto_alpha/lib_protocol/script_set.mli index 3d4e4b12ab38..bffb228a0752 100644 --- a/src/proto_alpha/lib_protocol/script_set.mli +++ b/src/proto_alpha/lib_protocol/script_set.mli @@ -3,6 +3,7 @@ (* Open Source License *) (* Copyright (c) 2018 Dynamic Ledger Solutions, Inc. *) (* Copyright (c) 2020 Metastate AG *) +(* Copyright (c) 2022 Nomadic Labs *) (* *) (* Permission is hereby granted, free of charge, to any person obtaining a *) (* copy of this software and associated documentation files (the "Software"),*) @@ -24,18 +25,33 @@ (* *) (*****************************************************************************) +(** Functions to ease the manipulation of sets of values in Michelson. + + A set in Michelson is a collection of type-homegeneous values along with the + functions that operate on the structure (through a first-class module). In + particular, the {!size} function runs in constant time. +*) + open Script_typed_ir val make : (module Boxed_set with type elt = 'elt) -> 'elt set val get : 'elt set -> (module Boxed_set with type elt = 'elt) +(** [empty cmp_ty] creates a set module where elements have size + [Gas_comparable_input_size.size_of_comparable_value cmp_ty] and are compared + with [Script_comparable.compare_comparable cmp_ty] (used for sorting values, + which ensures a reasonable complexity of the set functions). + The function returns an empty set packaged as a first-class set module. *) val empty : 'a comparable_ty -> 'a set val fold : ('elt -> 'acc -> 'acc) -> 'elt set -> 'acc -> 'acc +(** [update v true set] adds [v] to [set], and [update v false set] removes [v] + from [set]. *) val update : 'a -> bool -> 'a set -> 'a set val mem : 'elt -> 'elt set -> bool +(** [size set] runs in constant time. *) val size : 'elt set -> Script_int.n Script_int.num -- GitLab From d0276017d1339c179cd33014f97255f45b4bcd6f Mon Sep 17 00:00:00 2001 From: Nicolas Ayache Date: Wed, 23 Mar 2022 14:06:06 +0100 Subject: [PATCH 02/10] Proto: doc for Script_map. --- src/proto_alpha/lib_protocol/script_map.mli | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/src/proto_alpha/lib_protocol/script_map.mli b/src/proto_alpha/lib_protocol/script_map.mli index fcf6a0af2453..23fab2b979b6 100644 --- a/src/proto_alpha/lib_protocol/script_map.mli +++ b/src/proto_alpha/lib_protocol/script_map.mli @@ -3,6 +3,7 @@ (* Open Source License *) (* Copyright (c) 2018 Dynamic Ledger Solutions, Inc. *) (* Copyright (c) 2020 Metastate AG *) +(* Copyright (c) 2022 Nomadic Labs *) (* *) (* Permission is hereby granted, free of charge, to any person obtaining a *) (* copy of this software and associated documentation files (the "Software"),*) @@ -24,6 +25,13 @@ (* *) (*****************************************************************************) +(** Functions to ease the manipulation of Michelson maps. + + A map in Michelson is a type-homegeneous, partial function of keys to + values, along with the functions that operate on the structure (through a + first-class module). +*) + open Script_typed_ir val make : @@ -34,8 +42,15 @@ val get_module : ('key, 'value) map -> (module Boxed_map with type key = 'key and type value = 'value) +(** [empty cmp_ty] creates a map module where keys have size + [Gas_comparable_input_size.size_of_comparable_value cmp_ty] and are compared + with [Script_comparable.compare_comparable cmp_ty] (used for sorting keys, + which ensures a reasonable complexity of the map functions). + The function returns an empty map packaged as a first-class map module. *) val empty : 'a comparable_ty -> ('a, 'b) map +(** [empty_from map] creates an empty map module where the size of keys and the + comparison function are those of [map]. *) val empty_from : ('a, 'b) map -> ('a, 'c) map val fold : @@ -47,6 +62,9 @@ val fold_es : 'acc -> 'acc tzresult Lwt.t +(** [update k (Some v) map] associates [v] to [k] in [map] (overwriting the + previous value, if any), and [update k None map] removes the potential + association to [k] in [map]. *) val update : 'a -> 'b option -> ('a, 'b) map -> ('a, 'b) map val mem : 'key -> ('key, 'value) map -> bool -- GitLab From d4b2caabb81a979175ae6fb81e0f690a9aba04bd Mon Sep 17 00:00:00 2001 From: Nicolas Ayache Date: Wed, 23 Mar 2022 14:36:41 +0100 Subject: [PATCH 03/10] Proto: doc for Script_tc_errors_registration. And remove from the interface an unused value outside the module. --- .../lib_protocol/script_tc_errors_registration.mli | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/src/proto_alpha/lib_protocol/script_tc_errors_registration.mli b/src/proto_alpha/lib_protocol/script_tc_errors_registration.mli index b8f29ec306a2..dd2e61e500ce 100644 --- a/src/proto_alpha/lib_protocol/script_tc_errors_registration.mli +++ b/src/proto_alpha/lib_protocol/script_tc_errors_registration.mli @@ -2,7 +2,7 @@ (* *) (* Open Source License *) (* Copyright (c) 2018 Dynamic Ledger Solutions, Inc. *) -(* Copyright (c) 2020-2021 Nomadic Labs *) +(* Copyright (c) 2020-2022 Nomadic Labs *) (* *) (* Permission is hereby granted, free of charge, to any person obtaining a *) (* copy of this software and associated documentation files (the "Software"),*) @@ -24,10 +24,11 @@ (* *) (*****************************************************************************) +(** This module registers all the errors from [Script_tc_errors] as a top-level + effect. *) + open Alpha_context open Script val type_map_enc : (location * (expr list * expr list)) list Data_encoding.encoding - -val stack_ty_enc : expr list Data_encoding.encoding -- GitLab From fc8e72feec2a5f9dd3afce187d47dc5b7e48a163 Mon Sep 17 00:00:00 2001 From: Nicolas Ayache Date: Wed, 23 Mar 2022 15:12:04 +0100 Subject: [PATCH 04/10] Proto: doc for Constants_storage. --- src/proto_alpha/lib_protocol/constants_storage.mli | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/src/proto_alpha/lib_protocol/constants_storage.mli b/src/proto_alpha/lib_protocol/constants_storage.mli index 1a125e4b86be..242f918277cb 100644 --- a/src/proto_alpha/lib_protocol/constants_storage.mli +++ b/src/proto_alpha/lib_protocol/constants_storage.mli @@ -2,7 +2,7 @@ (* *) (* Open Source License *) (* Copyright (c) 2018 Dynamic Ledger Solutions, Inc. *) -(* Copyright (c) 2020-2021 Nomadic Labs *) +(* Copyright (c) 2020-2022 Nomadic Labs *) (* Copyright (c) 2021-2022 Trili Tech, *) (* *) (* Permission is hereby granted, free of charge, to any person obtaining a *) @@ -25,6 +25,10 @@ (* *) (*****************************************************************************) +(** This module provides functions to extract the value of protocol parameters + from the context. + See {!Constant_repr.parametric} for more details about these values. *) + val preserved_cycles : Raw_context.t -> int val blocks_per_cycle : Raw_context.t -> int32 -- GitLab From aa437a42997f27e1c77c4385e4a91e3cbb5c907b Mon Sep 17 00:00:00 2001 From: Nicolas Ayache Date: Wed, 23 Mar 2022 16:31:58 +0100 Subject: [PATCH 05/10] Proto: doc for Cycle_repr. --- src/proto_alpha/lib_protocol/cycle_repr.mli | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/src/proto_alpha/lib_protocol/cycle_repr.mli b/src/proto_alpha/lib_protocol/cycle_repr.mli index bfd7a7b66db3..7ff7a730bb82 100644 --- a/src/proto_alpha/lib_protocol/cycle_repr.mli +++ b/src/proto_alpha/lib_protocol/cycle_repr.mli @@ -2,6 +2,7 @@ (* *) (* Open Source License *) (* Copyright (c) 2018 Dynamic Ledger Solutions, Inc. *) +(* Copyright (c) 2022 Nomadic Labs *) (* *) (* Permission is hereby granted, free of charge, to any person obtaining a *) (* copy of this software and associated documentation files (the "Software"),*) @@ -23,6 +24,10 @@ (* *) (*****************************************************************************) +(** This module provides a type and functions to manipulate cycle numbers. + + Invariant: cycle numbers are always positive. *) + type t type cycle = t -- GitLab From 84bcc95d9cfd48f8584ddeb9f129b46935001974 Mon Sep 17 00:00:00 2001 From: Nicolas Ayache Date: Wed, 23 Mar 2022 17:05:30 +0100 Subject: [PATCH 06/10] Proto: doc for Michelson_v1_gas. --- src/proto_alpha/lib_protocol/michelson_v1_gas.mli | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/src/proto_alpha/lib_protocol/michelson_v1_gas.mli b/src/proto_alpha/lib_protocol/michelson_v1_gas.mli index 0b78e30f162d..1bbb9cc97691 100644 --- a/src/proto_alpha/lib_protocol/michelson_v1_gas.mli +++ b/src/proto_alpha/lib_protocol/michelson_v1_gas.mli @@ -24,6 +24,11 @@ (* *) (*****************************************************************************) +(** This module provides the gas costs for typechecking Michelson scripts, + parsing and unparsing Michelson values, and interpreting Michelson + instructions. +*) + open Alpha_context module Cost_of : sig -- GitLab From 99c12469a218e1d7066a6880c042cf0df600662c Mon Sep 17 00:00:00 2001 From: Nicolas Ayache Date: Wed, 23 Mar 2022 17:14:01 +0100 Subject: [PATCH 07/10] Proto: doc for Nonce_storage. --- src/proto_alpha/lib_protocol/nonce_storage.mli | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/src/proto_alpha/lib_protocol/nonce_storage.mli b/src/proto_alpha/lib_protocol/nonce_storage.mli index 1e278a4a5c4b..e85ce95de2e0 100644 --- a/src/proto_alpha/lib_protocol/nonce_storage.mli +++ b/src/proto_alpha/lib_protocol/nonce_storage.mli @@ -2,6 +2,7 @@ (* *) (* Open Source License *) (* Copyright (c) 2018 Dynamic Ledger Solutions, Inc. *) +(* Copyright (c) 2022 Nomadic Labs *) (* *) (* Permission is hereby granted, free of charge, to any person obtaining a *) (* copy of this software and associated documentation files (the "Software"),*) @@ -23,6 +24,12 @@ (* *) (*****************************************************************************) +(** This module provides types and functions to manipulate nonces. + + A nonce is a byte sequence of fixed length, which is supposed to be random + and used only once, provided by a block producer and used to generate a + random seed (see {!module:Seed_repr}). *) + type t = Seed_repr.nonce type nonce = t -- GitLab From 0118b0c3d87213cb90fb2e658e1b2a32a8cff754 Mon Sep 17 00:00:00 2001 From: Nicolas Ayache Date: Wed, 23 Mar 2022 23:06:42 +0100 Subject: [PATCH 08/10] Proto: doc for Voting_services. --- src/proto_alpha/lib_protocol/voting_services.mli | 3 +++ 1 file changed, 3 insertions(+) diff --git a/src/proto_alpha/lib_protocol/voting_services.mli b/src/proto_alpha/lib_protocol/voting_services.mli index 9478c1a1135d..693ac397e915 100644 --- a/src/proto_alpha/lib_protocol/voting_services.mli +++ b/src/proto_alpha/lib_protocol/voting_services.mli @@ -2,6 +2,7 @@ (* *) (* Open Source License *) (* Copyright (c) 2018 Dynamic Ledger Solutions, Inc. *) +(* Copyright (c) 2022 Nomadic Labs *) (* *) (* Permission is hereby granted, free of charge, to any person obtaining a *) (* copy of this software and associated documentation files (the "Software"),*) @@ -23,6 +24,8 @@ (* *) (*****************************************************************************) +(** This module provides RPC services that return voting-related information. *) + open Alpha_context val ballots : 'a #RPC_context.simple -> 'a -> Vote.ballots shell_tzresult Lwt.t -- GitLab From 19ea2fb8f4f6f5fa7fdb65d8f72190034d10f565 Mon Sep 17 00:00:00 2001 From: Nicolas Ayache Date: Fri, 1 Apr 2022 16:29:38 +0200 Subject: [PATCH 09/10] Proto: doc for Contract_services. --- src/proto_alpha/lib_protocol/contract_services.mli | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/src/proto_alpha/lib_protocol/contract_services.mli b/src/proto_alpha/lib_protocol/contract_services.mli index 4625b5ea3a50..6230fb8c444b 100644 --- a/src/proto_alpha/lib_protocol/contract_services.mli +++ b/src/proto_alpha/lib_protocol/contract_services.mli @@ -2,7 +2,7 @@ (* *) (* Open Source License *) (* Copyright (c) 2018 Dynamic Ledger Solutions, Inc. *) -(* Copyright (c) 2019-2020 Nomadic Labs *) +(* Copyright (c) 2019-2022 Nomadic Labs *) (* *) (* Permission is hereby granted, free of charge, to any person obtaining a *) (* copy of this software and associated documentation files (the "Software"),*) @@ -24,6 +24,10 @@ (* *) (*****************************************************************************) +(** This module defines RPC services to access the information associated to + contracts (balance, delegate, script, etc.). +*) + open Alpha_context val list : 'a #RPC_context.simple -> 'a -> Contract.t list shell_tzresult Lwt.t -- GitLab From 11c8fbf813e26109da583c94fe8c98843cbfe4bd Mon Sep 17 00:00:00 2001 From: Nicolas Ayache Date: Fri, 1 Apr 2022 16:40:08 +0200 Subject: [PATCH 10/10] Proto: doc for Delegate_services. --- src/proto_alpha/lib_protocol/delegate_services.mli | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/src/proto_alpha/lib_protocol/delegate_services.mli b/src/proto_alpha/lib_protocol/delegate_services.mli index 2f83ed1ba1c9..e01ffa725aef 100644 --- a/src/proto_alpha/lib_protocol/delegate_services.mli +++ b/src/proto_alpha/lib_protocol/delegate_services.mli @@ -3,7 +3,7 @@ (* Open Source License *) (* Copyright (c) 2018 Dynamic Ledger Solutions, Inc. *) (* Copyright (c) 2020 Metastate AG *) -(* Copyright (c) 2021 Nomadic Labs, *) +(* Copyright (c) 2021-2022 Nomadic Labs *) (* *) (* Permission is hereby granted, free of charge, to any person obtaining a *) (* copy of this software and associated documentation files (the "Software"),*) @@ -25,6 +25,10 @@ (* *) (*****************************************************************************) +(** This module defines RPC services to access the information associated to + delegates (who they are, their delegators, their different kinds of balances, their activity, etc.). +*) + open Alpha_context val list : -- GitLab