seed_repr.mli
(*****************************************************************************)
(* *)
(* Open Source License *)
(* Copyright (c) 2018 Dynamic Ledger Solutions, Inc. <contact@tezos.com> *)
(* *)
(* Permission is hereby granted, free of charge, to any person obtaining a *)
(* copy of this software and associated documentation files (the "Software"),*)
(* to deal in the Software without restriction, including without limitation *)
(* the rights to use, copy, modify, merge, publish, distribute, sublicense, *)
(* and/or sell copies of the Software, and to permit persons to whom the *)
(* Software is furnished to do so, subject to the following conditions: *)
(* *)
(* The above copyright notice and this permission notice shall be included *)
(* in all copies or substantial portions of the Software. *)
(* *)
(* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR*)
(* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, *)
(* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL *)
(* THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER*)
(* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING *)
(* FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER *)
(* DEALINGS IN THE SOFTWARE. *)
(* *)
(*****************************************************************************)
(** Tezos Protocol Implementation - Random number generation
This is not expected to be a good cryptographic random number
generator. In particular this is supposed to be used in situations
where the seed is a globally known information.
The only expected property is: It should be difficult to find a
seed such that the generated sequence is a given one. *)
(** {2 Random Generation} *)
(** The state of the random number generator *)
type t
(** A random seed, to derive random sequences from *)
type seed
(** A random sequence, to derive random values from *)
type sequence
(** A VDF discriminant and challenge *)
type vdf_setup = Vdf.discriminant * Vdf.challenge
(** A VDF result, to derive a seed from *)
type vdf_solution = Vdf.result * Vdf.proof
val pp_solution : Format.formatter -> vdf_solution -> unit
(** Compare only the first element of two vdf_solution, that are
of [Vdf.result]. *)
val compare_vdf_solution : vdf_solution -> vdf_solution -> int
val generate_vdf_setup :
seed_discriminant:seed -> seed_challenge:seed -> vdf_setup
val verify : vdf_setup -> Int64.t -> vdf_solution -> bool option
val vdf_to_seed : seed -> vdf_solution -> seed
(** [initialize_new state ident] returns a new generator *)
val initialize_new : seed -> bytes list -> t
(** [sequence state n] prepares the n-th sequence of a state *)
val sequence : t -> int32 -> sequence
(** Generates the next random value in the sequence *)
val take : sequence -> bytes * sequence
(** [take_int32 s bound] generates the next random value as a bounded [int32]
@param bound must be a positive integer
@raise Invalid_argument "Seed_repr.take_int32" if [bound] <= 0
*)
val take_int32 : sequence -> int32 -> int32 * sequence
(** [take_int64 s bound] generates the next random value as a bounded [int64]
@param bound must be a positive integer
@raise Invalid_argument "Seed_repr.take_int64" if [bound] <= 0
*)
val take_int64 : sequence -> int64 -> int64 * sequence
(** {2 Entropy} *)
(** A nonce for adding entropy to the generator *)
type nonce
(** Add entropy to the seed generator *)
val update_seed : seed -> nonce -> seed
(** Use a byte sequence as a nonce *)
val make_nonce : bytes -> nonce tzresult
(** Compute the hash of a nonce *)
val hash : nonce -> Nonce_hash.t
(** [check_hash nonce hash] is true if the nonce correspond to the hash *)
val check_hash : nonce -> Nonce_hash.t -> bool
(** For using nonce hashes as keys in the hierarchical database *)
val nonce_hash_key_part : Nonce_hash.t -> string list -> string list
(** Returns a new seed by hashing the one passed with a constant. *)
val deterministic_seed : seed -> seed
(** [initial_seeds n] generates the first [n] seeds for which there are no nonces.
The first seed is a constant value. The kth seed is the hash of seed (k-1)
concatenated with a constant. If an [initial_seed] is provided, the
{i first} seed is created using it as the first one. *)
val initial_seeds : ?initial_seed:State_hash.t -> int -> seed list
(** {2 Predefined nonce} *)
val initial_nonce_0 : nonce
val initial_nonce_hash_0 : Nonce_hash.t
(** {2 Serializers} *)
val nonce_encoding : nonce Data_encoding.t
val seed_encoding : seed Data_encoding.t
val vdf_setup_encoding : vdf_setup Data_encoding.t
val vdf_solution_encoding : vdf_solution Data_encoding.t
type seed_status = RANDAO_seed | VDF_seed
val seed_status_encoding : seed_status Data_encoding.t