diff --git a/src/proto_alpha/lib_protocol/constants_storage.mli b/src/proto_alpha/lib_protocol/constants_storage.mli index 1a125e4b86be931c26583f15b809e600b52026a0..242f918277cbc4c508899191a98cb3ce826bd565 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 diff --git a/src/proto_alpha/lib_protocol/contract_services.mli b/src/proto_alpha/lib_protocol/contract_services.mli index 4625b5ea3a50f2cc6fda14482c7b4f7cf3191d68..6230fb8c444b4304aececb0effeebe0d97ccb2c3 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 diff --git a/src/proto_alpha/lib_protocol/cycle_repr.mli b/src/proto_alpha/lib_protocol/cycle_repr.mli index bfd7a7b66db3ea96538fc5abc50d720eca7b5486..7ff7a730bb827cd7f42244b43082ffa708a9a07f 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 diff --git a/src/proto_alpha/lib_protocol/delegate_services.mli b/src/proto_alpha/lib_protocol/delegate_services.mli index 2f83ed1ba1c9473fcc2f96df37ecef8faee2cbad..e01ffa725aef88f34b48f4a770a54e15f6f54282 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 : diff --git a/src/proto_alpha/lib_protocol/michelson_v1_gas.mli b/src/proto_alpha/lib_protocol/michelson_v1_gas.mli index 0b78e30f162d641d18f51225026f42eea0f8fba2..1bbb9cc97691bb5a9f1bc9a1e3044edeb8947794 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 diff --git a/src/proto_alpha/lib_protocol/nonce_storage.mli b/src/proto_alpha/lib_protocol/nonce_storage.mli index 1e278a4a5c4be6deee77424b2f72f84896d36e28..e85ce95de2e0c82a89af190c02c9f389863b8a4e 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 diff --git a/src/proto_alpha/lib_protocol/script_map.mli b/src/proto_alpha/lib_protocol/script_map.mli index fcf6a0af245325980b50b8903d87c6aea8385ab2..23fab2b979b6cffc87137c7e82e658c862b795ca 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 diff --git a/src/proto_alpha/lib_protocol/script_set.mli b/src/proto_alpha/lib_protocol/script_set.mli index 3d4e4b12ab3857c017d5e36aaad6061533964590..bffb228a0752e38b1892f3be48716c0b0e3fb87e 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 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 b8f29ec306a2f412a095a5fd7df19fb2bdf2ff5d..dd2e61e500ceaefc817e1c6f8a61a6e6f94e0305 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 diff --git a/src/proto_alpha/lib_protocol/voting_services.mli b/src/proto_alpha/lib_protocol/voting_services.mli index 9478c1a1135d4a61e3e3637850554c00b5bffb2e..693ac397e91578c9ed0b056ff6ef91ac47004036 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