(**************************************************************************)
(*                                                                        *)
(*    Copyright (c) 2014 - 2017.                                          *)
(*    Dynamic Ledger Solutions, Inc. <contact@tezos.com>                  *)
(*                                                                        *)
(*    All rights reserved. No warranty, explicit or implicit, provided.   *)
(*                                                                        *)
(**************************************************************************)

(** Tezos Protocol Environment - Protocol updater. *)

(** Validation result: the record returned by the protocol
    on the successfull validation of a block. *)
type validation_result = {

  context: Context.t ;
  (** The resulting context, it will be used for the next block. *)

  fitness: Fitness.t ;
  (** The effective fitness of the block (to be compared with
      the 'announced' one in the block header. *)

  message: string option ;
  (** An optional informative message to be used as in the 'git
      commit' of the block's context. *)

  max_operation_data_length: int ;
  (** The maximum size of operations in bytes. *)

  max_number_of_operations: int list ;
  (** The maximum number of operations allowed in one block
      (per validation pass). *)

  max_operations_ttl: int ;
  (** The "time-to-live" of operation for the next block: any
      operations whose 'branch' is older than 'ttl' blocks in the
      past cannot be included in the next block. *)

}

type rpc_context = {
  block_hash: Block_hash.t ;
  block_header: Block_header.t ;
  operation_hashes: unit -> Operation_hash.t list list Lwt.t ;
  operations: unit -> Operation.t list list Lwt.t ;
  context: Context.t ;
}

(** This is the signature of a Tezos protocol implementation. It has
    access to the standard library and the Environment module. *)
module type PROTOCOL = sig

  (** The maximum size of block headers in bytes. *)
  val max_block_length: int

  (** The version specific type of operations. *)
  type operation

  (** The parsing / preliminary validation function for
      operations. Similar to {!parse_block}. *)
  val parse_operation:
    Operation_hash.t -> Operation.t -> operation tzresult

  (** Basic ordering of operations. [compare_operations op1 op2] means
      that [op1] should appear before [op2] in a block. *)
  val compare_operations: operation -> operation -> int

  (** A functional state that is transmitted through the steps of a
      block validation sequence. It must retain the current state of
      the store (that can be extracted from the outside using
      {!current_context}, and whose final value is produced by
      {!finalize_block}). It can also contain the information that
      must be remembered during the validation, which must be
      immutable (as validator or baker implementations are allowed to
      pause, replay or backtrack during the validation process). *)
  type validation_state

  (** Access the context at a given validation step. *)
  val current_context: validation_state -> Context.t tzresult Lwt.t

  (** Checks that a block is well formed in a given context. This
      function should run quickly, as its main use is to reject bad
      blocks from the network as early as possible. The input context
      is the one resulting of an ancestor block of same protocol
      version, not necessarily the one of its predecessor. *)
  val precheck_block:
    ancestor_context: Context.t ->
    ancestor_timestamp: Time.t ->
    Block_header.t ->
    unit tzresult Lwt.t

  (** The first step in a block validation sequence. Initializes a
      validation context for validating a block. Takes as argument the
      {!Block_header.t} to initialize the context for this block. The
      function {!precheck_block} may not have been called before
      [begin_application], so all the check performed by the former
      must be repeated in the latter. *)
  val begin_application:
    predecessor_context: Context.t ->
    predecessor_timestamp: Time.t ->
    predecessor_fitness: Fitness.t ->
    Block_header.t ->
    validation_state tzresult Lwt.t

  (** Initializes a validation context for constructing a new block
      (as opposed to validating an existing block). When the
      [proto_header] argument is not specified, the function should
      produce the exact same effect on the context than would produce
      the validation of a block containing an "equivalent" (but
      complete) header. For instance, if the block header usually
      includes a signature, the header provided to
      {!begin_construction} could includes a faked signature. *)
  val begin_construction:
    predecessor_context: Context.t ->
    predecessor_timestamp: Time.t ->
    predecessor_level: Int32.t ->
    predecessor_fitness: Fitness.t ->
    predecessor: Block_hash.t ->
    timestamp: Time.t ->
    ?proto_header: MBytes.t ->
    unit -> validation_state tzresult Lwt.t

  (** Called after {!begin_application} (or {!begin_construction}) and
      before {!finalize_block}, with each operation in the block. *)
  val apply_operation:
    validation_state -> operation -> validation_state tzresult Lwt.t

  (** The last step in a block validation sequence. It produces the
      context that will be used as input for the validation of its
      successor block candidates. *)
  val finalize_block:
    validation_state -> validation_result tzresult Lwt.t

  (** The list of remote procedures exported by this implementation *)
  val rpc_services: rpc_context RPC.directory

  (** An ad-hoc context patcher. It used only for debugging protocol
      while running in the "sandbox" mode. This function is never used
      in production. *)
  val configure_sandbox:
    Context.t -> Data_encoding.json option -> Context.t tzresult Lwt.t

end

(** Takes a version hash, a list of OCaml components in compilation
    order. The last element must be named [protocol] and respect the
    [protocol.ml] interface. Tries to compile it and returns true
    if the operation was successful. *)
val compile: Protocol_hash.t -> Protocol.t -> bool Lwt.t

(** Activates a given protocol version from a given context. This
    means that the context used for the next block will use this
    version (this is not an immediate change). The version must have
    been previously compiled successfully. *)
val activate: Context.t -> Protocol_hash.t -> Context.t Lwt.t

(** Fork a test network. The forkerd network will use the current block
    as genesis, and [protocol] as economic protocol. The network will
    be destroyed when a (successor) block will have a timestamp greater
    than [expiration]. The protocol must have been previously compiled
    successfully. *)
val fork_test_network:
  Context.t -> protocol:Protocol_hash.t -> expiration:Time.t -> Context.t Lwt.t