(*****************************************************************************)
(*                                                                           *)
(* Open Source License                                                       *)
(* Copyright (c) 2018 Dynamic Ledger Solutions, Inc. <contact@tezos.com>     *)
(* Copyright (c) 2020 Metastate AG <hello@metastate.dev>                     *)
(*                                                                           *)
(* 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.                                                 *)
(*                                                                           *)
(*****************************************************************************)

(** Manages all the voting related storage in Storage.Vote.  *)

(** [get_delegate_proposal_count ctxt proposer] returns the number of
    proposals already made by [proposer] in the current voting cycle.

    This number of proposals, aka [count], has its own storage bucket.

    @return [0] if the [count] of the proposer was not initialized.

    @return [Error Storage_error] if the deserialization of [count]
    fails. *)
val get_delegate_proposal_count :
  Raw_context.t -> Signature.public_key_hash -> int tzresult Lwt.t

(** [set_delegate_proposal_count ctxt proposer count] sets
    [proposer]'s number of submitted proposals to [count].

    More precisely, the relevant storage bucket is allocated and
    initialized to [count] if it didn't exist; otherwise it is simply
    updated. *)
val set_delegate_proposal_count :
  Raw_context.t -> Signature.public_key_hash -> int -> Raw_context.t Lwt.t

(** [has_proposed ctxt proposer proposal] indicates whether the
    [proposer] has already proposed the [proposal]. *)
val has_proposed :
  Raw_context.t -> Signature.public_key_hash -> Protocol_hash.t -> bool Lwt.t

(** [add_proposal ctxt proposer proposal] records the submission of
    [proposal] by [proposer]. *)
val add_proposal :
  Raw_context.t ->
  Signature.public_key_hash ->
  Protocol_hash.t ->
  Raw_context.t Lwt.t

(** Computes for each proposal how many delegates proposed it. *)
val get_proposals : Raw_context.t -> int64 Protocol_hash.Map.t tzresult Lwt.t

val clear_proposals : Raw_context.t -> Raw_context.t Lwt.t

(** Counts of the votes *)
type ballots = {yay : int64; nay : int64; pass : int64}

(** All vote counts set to zero. *)
val ballots_zero : ballots

(** Encoding for {!ballots}. *)
val ballots_encoding : ballots Data_encoding.t

(** Equality check for {!ballots}. *)
val equal_ballots : ballots -> ballots -> bool

(** Pretty printer for {!ballots}. *)
val pp_ballots : Format.formatter -> ballots -> unit

val has_recorded_ballot :
  Raw_context.t -> Signature.Public_key_hash.t -> bool Lwt.t

(** Records a vote for a delegate, returns a {!Storage_error Existing_key} if
    the vote was already registered *)
val record_ballot :
  Raw_context.t ->
  Signature.Public_key_hash.t ->
  Vote_repr.ballot ->
  Raw_context.t tzresult Lwt.t

(** Computes the sum of the current ballots weighted by stake. *)
val get_ballots : Raw_context.t -> ballots tzresult Lwt.t

val get_ballot_list :
  Raw_context.t -> (Signature.Public_key_hash.t * Vote_repr.ballot) list Lwt.t

val clear_ballots : Raw_context.t -> Raw_context.t Lwt.t

val listings_encoding :
  (Signature.Public_key_hash.t * int64) list Data_encoding.t

(** Populates [!Storage.Vote.Listings] using the currently existing
   staking power and sets `Voting_power_in_listings`. Inactive
   delegates or delegates without the minimal required stake are not
   included in the listings. *)
val update_listings : Raw_context.t -> Raw_context.t tzresult Lwt.t

(** Verifies the presence of a delegate in the listing. *)
val in_listings : Raw_context.t -> Signature.Public_key_hash.t -> bool Lwt.t

val get_listings :
  Raw_context.t -> (Signature.Public_key_hash.t * int64) list Lwt.t

type delegate_info = {
  voting_power : Int64.t option;
  current_ballot : Vote_repr.ballot option;
  current_proposals : Protocol_hash.t list;
  remaining_proposals : int;
}

val pp_delegate_info : Format.formatter -> delegate_info -> unit

val delegate_info_encoding : delegate_info Data_encoding.t

val get_delegate_info :
  Raw_context.t -> Signature.public_key_hash -> delegate_info tzresult Lwt.t

val get_voting_power_free :
  Raw_context.t -> Signature.public_key_hash -> int64 tzresult Lwt.t

val get_voting_power :
  Raw_context.t ->
  Signature.public_key_hash ->
  (Raw_context.t * int64) tzresult Lwt.t

(** Returns the sum of all voting power in the listings,
    without accounting for gas cost. *)
val get_total_voting_power_free : Raw_context.t -> int64 tzresult Lwt.t

(** Returns the sum of all voting power in the listings. *)
val get_total_voting_power :
  Raw_context.t -> (Raw_context.t * int64) tzresult Lwt.t

val get_current_quorum : Raw_context.t -> int32 tzresult Lwt.t

val get_participation_ema : Raw_context.t -> int32 tzresult Lwt.t

val set_participation_ema :
  Raw_context.t -> int32 -> Raw_context.t tzresult Lwt.t

(** Indicates whether there is a current proposal in the storage. *)
val current_proposal_exists : Raw_context.t -> bool Lwt.t

(** Retrieves the current proposal.

    @return [Error Storage_error] if there is no current proposal, or
    if the deserialization fails. *)
val get_current_proposal : Raw_context.t -> Protocol_hash.t tzresult Lwt.t

(** Retrieves the current proposal.

    @return [None] if there is no current proposal.

    @return [Error Storage_error] if the deserialization fails. *)
val find_current_proposal :
  Raw_context.t -> Protocol_hash.t option tzresult Lwt.t

(** Registers a current proposal.

    @return [Error (Storage_error Existing_key)] if there was already
    a current proposal. *)
val init_current_proposal :
  Raw_context.t -> Protocol_hash.t -> Raw_context.t tzresult Lwt.t

(** Removes the current proposal. Does nothing if there was no current
    proposal. *)
val clear_current_proposal : Raw_context.t -> Raw_context.t Lwt.t

(** Sets the initial quorum to 80% and period kind to proposal. *)
val init :
  Raw_context.t -> start_position:Int32.t -> Raw_context.t tzresult Lwt.t