164 lines
6.8 KiB
OCaml
164 lines
6.8 KiB
OCaml
(**************************************************************************)
|
|
(* *)
|
|
(* 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.t
|
|
|
|
(** 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
|