Revision 50ad02fa2a56f1d3541a6d8b3c8a6a93160d4f54 authored by Albin Coquereau on 05 April 2024, 09:32:54 UTC, committed by Albin Coquereau on 05 April 2024, 09:32:54 UTC
1 parent 9a71363
prevalidation.mli
(*****************************************************************************)
(* *)
(* Open Source License *)
(* Copyright (c) 2018 Dynamic Ledger Solutions, Inc. <contact@tezos.com> *)
(* Copyright (c) 2018-2022 Nomadic Labs, <contact@nomadic-labs.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. *)
(* *)
(*****************************************************************************)
(** This module is used by the prevalidator worker to determine
whether an operation should be added to the mempool. To do so, it
calls on the protocol's [Mempool] to validate the operation, as
well as the {!Prevalidator_bounding} to ensure that the mempool
remains bounded. It also retrieves relevant information from the
protocol plugin. *)
module type T = sig
(** Similar to the same type in the protocol,
see {!Tezos_protocol_environment.PROTOCOL.operation} *)
type protocol_operation
(** Mempool configuration that groups both the plugin config
(e.g. minimal fee to pass the {!pre_filter}) and the bounding
config (e.g. max number of valid operations in the mempool). *)
type config
(** Default mempool configuration. *)
val default_config : config
(** Encoding for {!config}.
Internally an object without any variable fields. *)
val config_encoding : config Data_encoding.t
(** The type implemented by {!Tezos_store.Store.chain_store} in
production, and mocked in tests *)
type chain_store
(** The state used internally by this module. Created by {!val-create}
and then passed back and possibly updated by {!add_operation} and
{!remove_operation}.
This state notably contains a representation of the protocol
mempool, as well as the bounding state. *)
type t
(** Create an empty state based on the [head] block.
Called only once when a prevalidator starts. *)
val create :
chain_store ->
head:Store.Block.t ->
timestamp:Time.Protocol.t ->
t tzresult Lwt.t
(** Create a new empty state based on the [head] block.
The previous state must be provided (even when it was based on a
different block). Indeed, parts of it are recycled to make this
function more efficient than [create]. *)
val flush :
chain_store ->
head:Store.Block.t ->
timestamp:Time.Protocol.t ->
t ->
t tzresult Lwt.t
(** Light preliminary checks that should be performed on arrival of
an operation and after a flush of the prevalidator.
See [Protocol_plugin.T.Plugin.pre_filter]. *)
val pre_filter :
t ->
config ->
protocol_operation Shell_operation.operation ->
[ `Passed_prefilter of Prevalidator_pending_operations.priority
| Prevalidator_classification.error_classification ]
Lwt.t
(** Contain the hash and new classification of any operations that
had to be removed to make room for a newly added operation. *)
type replacements =
(Operation_hash.t * Prevalidator_classification.error_classification) list
(** Result of {!add_operation}.
Contain the updated (or unchanged) state {!t}, the operation (in
which the [signature_checked] field has been updated if
appropriate), its classification, and the potential {!replacements}.
Invariant: [replacements] can only be non-empty when the
classification is [`Prechecked]. *)
type add_result =
t
* protocol_operation Shell_operation.operation
* Prevalidator_classification.classification
* replacements
(** Try and add an operation to the protocol's mempool; also ensure
that this mempool remains bounded (in terms of both operation
count and total byte size; the bounds are specified in the [config]).
See {!add_result} for a description of the output. *)
val add_operation :
t ->
config ->
protocol_operation Shell_operation.operation ->
add_result Lwt.t
(** Remove an operation from the state.
The state remains unchanged when the operation was not
present (though not physically equal to the input state). *)
val remove_operation : t -> Operation_hash.t -> t
module Internal_for_tests : sig
(** Return the map of operations currently present in the protocol
representation of the mempool. *)
val get_mempool_operations : t -> protocol_operation Operation_hash.Map.t
(** Type {!Tezos_protocol_environment.PROTOCOL.Mempool.t}. *)
type mempool
(** Modify the [mempool] field of the internal state [t]. *)
val set_mempool : t -> mempool -> t
(** Type [Prevalidator_bounding.T.state]. *)
type bounding_state
(** Return the [bounding_state] component of the state. *)
val get_bounding_state : t -> bounding_state
(** Modify the [bounding_state] component of the state. *)
val set_bounding_state : t -> bounding_state -> t
end
end
(** How-to obtain an instance of this module's main module type: {!T} *)
module Make : functor (Proto : Protocol_plugin.T) ->
T
with type protocol_operation = Proto.operation
and type chain_store = Store.chain_store
(**/**)
module Internal_for_tests : sig
module type CHAIN_STORE = sig
(** The [chain_store] type. Implemented by
{!Tezos_store.Store.chain_store} in production and mocked in
tests *)
type chain_store
(** [context store block] checkouts and returns the context of [block] *)
val context :
chain_store ->
Store.Block.t ->
Tezos_protocol_environment.Context.t tzresult Lwt.t
(** [chain_id store] returns the {!Chain_id.t} to which [store]
corresponds *)
val chain_id : chain_store -> Chain_id.t
end
(** A variant of [Make] above that is parameterized by {!CHAIN_STORE},
for mocking purposes. *)
module Make : functor
(Chain_store : CHAIN_STORE)
(Proto : Protocol_plugin.T)
(Bounding : Prevalidator_bounding.T
with type protocol_operation = Proto.operation)
->
T
with type protocol_operation = Proto.operation
and type chain_store = Chain_store.chain_store
and type Internal_for_tests.mempool = Proto.Mempool.t
and type Internal_for_tests.bounding_state = Bounding.state
end
![swh spinner](/static/img/swh-spinner.gif)
Computing file changes ...