diff --git a/docs/alpha/protocol_overview.rst b/docs/alpha/protocol_overview.rst index 75fba40ab573990e43ab4df1d99c9db35171e14a..b4100f828b4adf290f8d14af10bead1ca929ccc4 100644 --- a/docs/alpha/protocol_overview.rst +++ b/docs/alpha/protocol_overview.rst @@ -71,6 +71,13 @@ Shell-protocol interaction - The shell does not accept a branch whose fork point is in a cycle more than ``PRESERVED_CYCLES`` in the past. More precisely, if ``n`` is the current cycle, :ref:`the last allowed fork point` is the first level of cycle ``n-PRESERVED_CYCLES``. The parameter ``PRESERVED_CYCLES`` therefore plays a central role in Tezos: any block before the last allowed fork level is immutable. - The shell changes the head of the chain to this new block only if the block is :doc:`valid<../shell/validation>` and has a higher fitness than the current head; a block is valid if the operations it includes are valid. +The support provided by the protocol for validating blocks can be modulated by different `validation modes `__. +They allow using this same support for quite different use cases, as follows: + +- being able to validate a block, typically used in the :doc:`validator <../shell/validation>`; +- being able to pre-apply a block, typically used in the :doc:`validator <../shell/validation>` to precheck a block, avoiding to further consider invalid blocks; +- being able to construct a block, typically used by the baker to bake a block; +- being able to partially construct a block, typically used by the :doc:`prevalidator <../shell/prevalidation>` to determine valid operations in the mempool. Blocks ~~~~~~ diff --git a/docs/ithaca/protocol_overview.rst b/docs/ithaca/protocol_overview.rst index ee1e9d5806dd3f12a5ae3ff7213a3078b27d1f8b..5ebd8bf94b0deb535754ef8807e1927cfcd14681 100644 --- a/docs/ithaca/protocol_overview.rst +++ b/docs/ithaca/protocol_overview.rst @@ -72,6 +72,13 @@ Shell-protocol interaction - The shell does not accept a branch whose fork point is in a cycle more than ``PRESERVED_CYCLES`` in the past. More precisely, if ``n`` is the current cycle, :ref:`the last allowed fork point` is the first level of cycle ``n-PRESERVED_CYCLES``. The parameter ``PRESERVED_CYCLES`` therefore plays a central role in Tezos: any block before the last allowed fork level is immutable. - The shell changes the head of the chain to this new block only if the block is :doc:`valid<../shell/validation>` and has a higher fitness than the current head; a block is valid if the operations it includes are valid. +The support provided by the protocol for validating blocks can be modulated by different `validation modes `__. +They allow using this same support for quite different use cases, as follows: + +- being able to validate a block, typically used in the :doc:`validator <../shell/validation>`; +- being able to pre-apply a block, typically used in the :doc:`validator <../shell/validation>` to precheck a block, avoiding to further consider invalid blocks; +- being able to construct a block, typically used by the baker to bake a block; +- being able to partially construct a block, typically used by the :doc:`prevalidator <../shell/prevalidation>` to determine valid operations in the mempool. Blocks ~~~~~~ diff --git a/docs/jakarta/protocol_overview.rst b/docs/jakarta/protocol_overview.rst index 66c6ff4f1d325ff3a532224f603c161a993d35c6..13c233536b596796798d9e70f79d0009430ff501 100644 --- a/docs/jakarta/protocol_overview.rst +++ b/docs/jakarta/protocol_overview.rst @@ -71,6 +71,13 @@ Shell-protocol interaction - The shell does not accept a branch whose fork point is in a cycle more than ``PRESERVED_CYCLES`` in the past. More precisely, if ``n`` is the current cycle, :ref:`the last allowed fork point` is the first level of cycle ``n-PRESERVED_CYCLES``. The parameter ``PRESERVED_CYCLES`` therefore plays a central role in Tezos: any block before the last allowed fork level is immutable. - The shell changes the head of the chain to this new block only if the block is :doc:`valid<../shell/validation>` and has a higher fitness than the current head; a block is valid if the operations it includes are valid. +The support provided by the protocol for validating blocks can be modulated by different `validation modes `__. +They allow using this same support for quite different use cases, as follows: + +- being able to validate a block, typically used in the :doc:`validator <../shell/validation>`; +- being able to pre-apply a block, typically used in the :doc:`validator <../shell/validation>` to precheck a block, avoiding to further consider invalid blocks; +- being able to construct a block, typically used by the baker to bake a block; +- being able to partially construct a block, typically used by the :doc:`prevalidator <../shell/prevalidation>` to determine valid operations in the mempool. Blocks ~~~~~~ diff --git a/docs/shell/validation.rst b/docs/shell/validation.rst index 8d2b773cff3e50e0fd9a9cf35b6843a918870e84..afcbcfe654365c18a63161a4d43582fbd941e097 100644 --- a/docs/shell/validation.rst +++ b/docs/shell/validation.rst @@ -131,6 +131,8 @@ the chain validator will propagate this information to its associated *prevalidator*, and may decide to kill or spawn the test network according to the protocol's decision. +The validator :ref:`interacts with the protocol ` in order to determine valid blocks. + .. _prevalidator_component: Prevalidator @@ -141,7 +143,7 @@ responsible for determining which operations to propagate for this chain over th peer-to-peer network. The page :doc:`./prevalidation` gives a detailed description of the prevalidator component. - +The prevalidator also :ref:`interacts with the protocol ` in order to determine valid operations in the mempool to propagate in the gossip network. Distributed DB -------------- diff --git a/src/proto_alpha/lib_protocol/main.mli b/src/proto_alpha/lib_protocol/main.mli index fc6ced6e2e477fcf03634558920b3dbe95beeadb..a6e20a489ec40d0612844ce7698175cbad37b9d2 100644 --- a/src/proto_alpha/lib_protocol/main.mli +++ b/src/proto_alpha/lib_protocol/main.mli @@ -43,8 +43,14 @@ (** [validation_mode] permits to differenciate [!type:validation_state] values. - TODO: #2536 - Add some documentation for the different modes. + There are four validation modes: + - [Application] + - [Partial_application] + - [Partial_construction] + - [Full_construction] + + For the meaning and typical uses of each mode, refer to the + comments attached to the corresponding type constructors below. *) type validation_mode = | Application of { @@ -65,7 +71,7 @@ type validation_mode = predecessor_level : Alpha_context.Level.t; predecessor_round : Alpha_context.Round.t; } - (** [Partial_application] is used in chain bootstrapping - not all checks + (** [Partial_application] is used in pre-checking of blocks - not all checks are done. Special case of [Application] to allow quick rejection of bad blocks. See {!val:Tezos_protocol_environment_sigs.V5.T.Updater.PROTOCOL.begin_partial_application}