diff --git a/docs/Makefile b/docs/Makefile index c4b3c88cad261d47ef1c44b64e1edeb1d1dc3991..02e49672be03ca7e2f82ec12b276a1aa871102cf 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -69,7 +69,9 @@ odoc: docexes odoc-lite: docexes rm -rf $(TMPDOCDIR)/ mkdir -p $(TMPDOCDIR)/ - rsync --recursive --links --perms --exclude="src/proto_0*" \ + rsync --recursive --links --perms \ + --include="src/proto_014*" --include="src/proto_015*" \ + --exclude="src/proto_0*" \ ../src ../tezt ../vendors ../dune ../dune-project $(TMPDOCDIR)/ # FIXME: https://gitlab.com/tezos/tezos/-/issues/2971 # The new version of odoc (2.1.0) is stricter than the old version (1.5.3), diff --git a/docs/alpha/blocks_ops.rst b/docs/alpha/blocks_ops.rst new file mode 100644 index 0000000000000000000000000000000000000000..f4c25e2416b7e98bbc746df0e607181833dd4a1b --- /dev/null +++ b/docs/alpha/blocks_ops.rst @@ -0,0 +1,229 @@ +===================== +Blocks and Operations +===================== + +The content of a Tezos block is made up of operations, which implement +and reify different functionalities provided by a Tezos economic +protocol: from reaching consensus on the state of the Tezos +blockchain, to performing smart contract calls and transactions. Each +Tezos economic protocol can specify different kinds of operations. + +This entry describes the operations supported by :doc:`the economic +protocol <./protocol>` that implement *enabled* features -- that is, +those available to end-users on Tezos Mainnet. The complete list of +operations, including those corresponding to features in development +or available only on test networks, is given in the +:package-api:`OCaml Documentation +`. + +.. _validation_passes_alpha: + +Validation Passes +~~~~~~~~~~~~~~~~~ + +The different kinds of operations are grouped into classes. Each class +has an associated index, a natural number, also known as a +:ref:`validation pass`. There are currently four classes +of operations: :ref:`consensus `, +:ref:`voting `, +:ref:`anonymous`, and :ref:`manager +operations`. This order also specifies the +:ref:`validation and application` priority +of each of these classes. Consensus operations are considered the +highest priority ones, and manager operations the lowest. + +The current protocol implementation enforces the following invariant: + +- each kind of operation belongs to *at most one* validation pass; +- operations whose kind does not belong to any validation pass cannot + be :ref:`applied`. + +.. FIXME tezos/tezos#3915: + + Failing noops don't fit within any of the validation passes + below. We need to change the structure a bit to be able to list + them here. + +In the sequel, we describe the different classes of operations, and +the different kinds of operations belonging to each class. + +.. _consensus_operations_alpha: + +Consensus Operations +~~~~~~~~~~~~~~~~~~~~ + +.. TODO tezos/tezos#4204: document PCQ/PQ + +Consensus operations are administrative operations that are necessary +to implement the :doc:`consensus algorithm`. There are two +kinds of consensus operations, each belonging to the different voting +phases required to agree on the next block. + +- A ``Preendorsement`` operation implements a first vote for a + :ref:`candidate block ` with the aim of + building a :ref:`preendorsement quorum `. + +- An ``Endorsement`` operation implements a vote for a candidate block + for which a preendorsement quorum certificate (PQC) has been + observed. + +.. _voting_operations_alpha: + +Voting Operations +~~~~~~~~~~~~~~~~~ + +Voting operations are operations related to the on-chain :doc:`Tezos +Amendment` process. In this economic protocol, there are two +voting operations: + +- The ``Proposal`` operation enables delegates to submit (also known as + to "inject") protocol amendment proposals, or to up-vote previously + submitted proposals, during the Proposal period. + +- The ``Ballot`` operation enables delegates to participate in the + Exploration and Promotion periods. Delegates use this operation to + vote for (``Yay``), against (``Nay``), or to side with the majority + (``Pass``), when examining a protocol amendment proposal. + +Further details on each operation's implementation and semantics are +provided in the dedicated entry for :ref:`on-chain +governance`. + +.. _anonymous_operations_alpha: + +Anonymous Operations +~~~~~~~~~~~~~~~~~~~~ + +This class groups all operations that do not require a signature from +a Tezos account (with an exception, detailed below). They implement +different functionalities of the protocol, and their common +characteristic is that they allow the account originating these +operations to remain anonymous in order to avoid censorship. + +Two operations in this class implement functionality pertaining to the +protocol's :doc:`random seeds generation +mechanism`: + +- The ``Seed_nonce_revelation`` operation allows a baker to + anonymously reveal the nonce seed for the commitment it had included + in a previously baked block (in the previous cycle). + +- The ``Vdf_revelation`` operation allows the submission of a solution + to, and a proof of correctness of, the :ref:`VDF + challenge` corresponding to the VDF revelation period of + the randomness generation protocol. + +Further details on the latter operation's implementation and semantics +are provided in the :ref:`random seed generation +protocol`. + +Three operations in this class are used to :ref:`punish participants +which engage in Byzantine behaviour` -- notably +delegates which :ref:`"double sign" ` blocks, or emit +conflicting :ref:`consensus operations`: + +- The ``Double_preendorsement_evidence`` operation allows for accusing + a delegate of having *double-preendorsed* -- i.e., of having + preendorsed two different block candidates, at the same level and at + the same round. The bulk of the evidence, the two arguments + provided, consists of the two offending preendorsements. + +- Similarly, the ``Double_endorsement_evidence`` operation allows for + accusing a delegate of having *double-endorsed* -- i.e., of having + endorsed two different block candidates at the same level and the + same round -- by providing the two offending endorsements. + +- The ``Double_baking_evidence`` allows for accusing a delegate of + having "double-baked" a block -- i.e., of having signed two + different blocks at the same level and at same round. The bulk of + the evidence consists of the :ref:`block + headers` of each of the two offending blocks. + +See :ref:`here` for further detail on the semantics of +evidence-providing operations. + +The ``Activation`` operation allows users which participated in the +Tezos fundraiser to make their :ref:`accounts ` operational. + +Finally, the ``Drain_delegate`` operation allows an active +consensus-key account, i.e., an account to which a baker delegated its +consensus-signing responsibility, to **empty** its delegate +account. This operation is used as a deterrent to ensure that a +delegate secures its consensus key as much as its manager (or main) +key. + +.. _manager_operations_alpha: + +Manager Operations +~~~~~~~~~~~~~~~~~~ + +.. FIXME tezos/tezos#3936: integrate consensus keys operations. + +.. FIXME tezos/tezos#3937: + + Document increased paid storage manager operation. + +Manager operations enable end-users to interact with the Tezos +blockchain -- e.g., transferring funds or calling :doc:`smart +contracts`. A manager operation is issued by a single +*manager* account which signs the operation and pays the +:ref:`fees` to the baker for its inclusion in a block. Indeed, +manager operations are the only fee-paying and +:ref:`gas-consuming` operations. + +- The ``Reveal`` operation reveals the public key of the sending + manager. Knowing this public key is indeed necessary to check the signature + of future operations signed by this manager. +- The ``Transaction`` operation allows users to either transfer tez + between accounts and/or to invoke a smart contract. +- The ``Delegation`` operation allows users to :ref:`delegate their + stake ` to a :ref:`delegate` (a + *baker*), or to register themselves as delegates. +- The ``Update_consensus_key`` operation allows users to delegate the + responsibility of signing blocks and consensus-related operations to + another account. +- The ``Origination`` operation is used to + :ref:`originate`, that is to deploy, smart contracts + in the Tezos blockchain. +- The ``Set_deposits_limit`` operation enables delegates to adjust the + amount of stake a delegate :ref:`has locked in + bonds`. +- Support for registering global constants is implemented with the + ``Register_global_constant`` operation. +- The ``Increase_paid_storage`` operation allows a sender to increase + the paid storage of some previously deployed contract. +- The ``Event`` operation enables sending event-like information to + external applications from Tezos smart contracts -- see + :doc:`Contract Events` for further detail. + +Moreover, all operations necessary to implement Tezos' *enshrined* +Layer 2 solutions into the economic protocol are also manager +operations: + +.. FIXME tezos/tezos#3916: expand documentation of TORU operations. + +- :doc:`Transaction Optimistic Rollups` are + implemented using the following manager operations: + ``Tx_rollup_origination``, ``Tx_rollup_submit_batch``, + ``Tx_rollup_commit``, ``Tx_rollup_return_bond``, + ``Tx_rollup_finalize_commitment``, ``Tx_rollup_remove_commitment``, + ``Tx_rollup_rejection``, ``Tx_rollup_rejection``, + ``Transfer_ticket``. + +.. _manager_operations_batches_alpha: + +Manager Operation Batches +""""""""""""""""""""""""" + +Manager operations can be grouped, forming a so-called +**batch**. Batches enable the inclusion of several manager operations +from the same manager in a single block. + +Batches satisfy the following properties: + +- All operations in a batch are issued by the same manager, which + provides a single signature for the entire batch. +- A batch is :ref:`applied` + atomically: all its operations are executed sequentially, without + interleaving other operations. Either all the operations in the + batch succeed, or none is applied. diff --git a/docs/alpha/consensus.rst b/docs/alpha/consensus.rst index 0ad1937e27da26f4959fdf3839718cd981f77fba..2816d8507a10144196ed090b71907cd39a868274 100644 --- a/docs/alpha/consensus.rst +++ b/docs/alpha/consensus.rst @@ -441,6 +441,11 @@ These are a subset of the :ref:`protocol constants `. Shell-protocol interaction revisited ------------------------------------ +.. FIXME tezos/tezos#3914: + + Integrate protocol-specific block parts in the blocks and ops + entry. + :ref:`Recall` that, for the shell to interact with the economic protocol, two notions are defined abstractly at the level of the shell and made concrete at the level of the consensus protocol. Namely, these two notions are the protocol-specific header and the fitness. As in Emmy*, the protocol-specific header contains the fields: diff --git a/docs/alpha/glossary.rst b/docs/alpha/glossary.rst index a0c9808a8833bff6a383d610e8aaa2295390c89f..7d50b69d4479db1bd7fef66d17b33859c925f029 100644 --- a/docs/alpha/glossary.rst +++ b/docs/alpha/glossary.rst @@ -74,9 +74,13 @@ _`Cycle` A cycle is a set of consecutive blocks. E.g., cycle 12 started at block_ level 49152 and ended at block_ level 53248. - Cycles are used as a unit of “time” in the block_ chain. For example, the - different phases in the amendment voting procedures are defined based on - cycles. + Cycles are used as a unit of “time” in the blockchain. For + example, the different phases in the amendment voting procedures + are defined based on cycles. + + The length of a cycle is a (parametric) protocol + :ref:`constant`, and thus might change across different + Tezos protocols. _`Delegate` An `implicit account`_ to which an account_ has delegated their @@ -92,20 +96,36 @@ _`Delegation` the account_. _`Double signing` - When a baker_ signs two different blocks at the same level and same round, - it is called double baking. Double baking is detrimental to the network and might be - indicative of an attempt to double spend. - The same goes for signing two different endorsements at the same level and the same round. - As such, double signing is punished by the - network: an accuser_ can provide proof of the double signing to be awarded - part of the double signer's deposit. + The action of a baker_ signing two different blocks at the same + level and same round is called *double baking*. Double baking + is detrimental to the network and might be indicative of an + attempt to double spend. The same goes for signing two different + *endorsements* at the same level and the same round. + + Double signing (i.e. double baking or double endorsing) is + punished by the network: an accuser_ can provide proof of the + double signing to be awarded part of the double signer's deposit + -- see :ref:`Slashing`. + +_`Failing Noop` + The ``Failing_noop`` operation implements a *No-op*, which always + fails at :ref:`application time`, and + should never appear in :ref:`applied + blocks`. This operation allows end-users to + :ref:`sign arbitrary messages` which have no + computational semantics. _`Fee` - To ensure responsible use of computation resources of other nodes, and also to encourage active participation in the consensus protocol, there are some - fees that users pay to bakers for including their operations in blocks. - For example, fees are paid to a baker for operations such as a transaction_ or a revelation of a public key. + To ensure responsible use of computation resources of other + nodes, and also to encourage active participation in the consensus + protocol, users pay fees to bakers for including (some of) their + operations in blocks. For example, fees are paid to a baker for + operations such as a transaction_ or a revelation of a public key. + + Currently, only :ref:`manager operations` + require collecting fees from its sender account_. - See also `burn`_. + See also `burn`_. _`Gas` A measure of the number of elementary operations_ performed during @@ -117,7 +137,7 @@ _`Implicit account` contract`_, an `Implicit account`_ cannot include a script and it cannot reject incoming transactions. - If registered, an `implicit account`_ can act as a delegate_. + If *registered*, an `implicit account`_ can act as a delegate_. The address of an `implicit account`_ always starts with the letters `tz` followed by `1`, `2` or `3` (depending on the @@ -161,7 +181,8 @@ _`Originated account` See `smart contract`_. _`Origination` - An operation_ to create a `smart contract`_. + A manager operation_ whose purpose is to create -- that + is, to deploy -- a `smart contract`_ on the Tezos blockchain. _`Round` An attempt to reach consensus on a block at a given level. @@ -175,10 +196,11 @@ _`Roll` deprecated; see `Minimal stake`_. _`Smart contract` - Account_ which is associated to a :ref:`Michelson ` script. They are - created with an explicit origination_ operation and are therefore - sometimes called originated accounts. The address of a smart - contract always starts with the letters ``KT1``. + Account_ which is associated to a :ref:`Michelson + ` script. They are created with an + explicit origination_ operation and are therefore sometimes called + originated accounts. The address of a smart contract always starts + with the letters ``KT1``. _`Smart Optimistic Rollups` Smart optimistic rollups constitute a `layer 2`_ solution that can be used to deploy either a general-purpose polyvalent layer 2 blockchain @@ -189,6 +211,13 @@ _`Transaction` An operation_ to transfer tez between two accounts, or to run the code of a `smart contract`_. +_`Validation pass` + An index (a natural number) associated with a particular kind of + operations, allowing to group them into classes. Validation passes + enable prioritizing the :ref:`validation and + application` of certain classes of + operations. + _`Voting period` Any of the ``proposal``, ``exploration``, ``cooldown``, ``promotion`` or ``adoption`` stages in the voting procedure when diff --git a/docs/alpha/plugins.rst b/docs/alpha/plugins.rst index c103825ea0a831b6107094e20f1949454b97610c..26647e5ccdd770259974b09b9a696a2259869747 100644 --- a/docs/alpha/plugins.rst +++ b/docs/alpha/plugins.rst @@ -97,11 +97,18 @@ block proposal as follows: This filtering strategy is implemented in the ``prefilter`` (see :doc:`../shell/prevalidation`). - +.. _precheck_filter_alpha: Prechecking of manager operations ................................. +.. FIXME tezos/tezos#3938: + + This section doesn't make much sense after the pipelining project + has plugged validate into the plugin for Lima. Parts of this + section be integrated into plugin.rst, and the relevant definitions + should point to the validation entry. + The aim of the ``precheck`` filter is to avoid fully executing manager operations before deciding whether to gossip them to the network. @@ -120,11 +127,6 @@ increased the chain's fitness), only one operation per manager is propagated. All other received operations originating from the same manager will be classified as ``Branch_delayed`` and will not be propagated. -This criterion is used only by the prevalidator to decide the propagation of -operations. A baker can still include several operations originating from the same -manager in a single block, provided that it gets them in time (note that they can be -propagated by nodes using different versions or implementations). - Alternatively, a user can inject an operation with the same manager and the same counter, but with a higher fee to replace an already existing operation in the prevalidator. Only one of the two operations will be eventually diff --git a/docs/alpha/precheck.rst b/docs/alpha/precheck.rst index 2a37ed54e6b7bcb3422249e4ecef146a21ccd591..9f978612729222e4fa81886d84a0d2fe34cee76d 100644 --- a/docs/alpha/precheck.rst +++ b/docs/alpha/precheck.rst @@ -1,6 +1,13 @@ Prechecking of manager operations ================================= +.. FIXME tezos/tezos#3938: + + This section doesn't make much sense after the pipelining project + has plugged validate into the plugin for Lima. Parts of this + section be integrated into plugin.rst, and the relevant definitions + should point to the validation entry. + The prevalidator of Octez prevents the propagation of non-valid operations by trying to apply (or execute) them. However, executing diff --git a/docs/alpha/protocol.rst b/docs/alpha/protocol.rst index ddd4a330ab8bc55785526785a879fa7fbb00c094..f3974f59c9c347ebded3ada6dd2d64b6689a463a 100644 --- a/docs/alpha/protocol.rst +++ b/docs/alpha/protocol.rst @@ -90,3 +90,13 @@ Sapling, etc), and some details about its implementation. :maxdepth: 2 event + +.. toctree:: + :maxdepth: 2 + + blocks_ops + +.. toctree:: + :maxdepth: 2 + + validation diff --git a/docs/alpha/protocol_overview.rst b/docs/alpha/protocol_overview.rst index 4760a194aca1f435b0dc119f4d2a06c50363942d..15c9bbf06da13981df45109c2343a72515572cb0 100644 --- a/docs/alpha/protocol_overview.rst +++ b/docs/alpha/protocol_overview.rst @@ -37,97 +37,131 @@ different implementations, and this is important, for instance because different to implement different transaction selection strategies. Tezos is a self-amending blockchain, in that a large part of Tezos can be -changed through a so-called amendement procedure. To this end, as mentioned in -:doc:`the big picture<../shell/the_big_picture>`, a Tezos node consists of two +changed through a so-called amendment procedure. To this end, as mentioned in +:ref:`the big picture`, a Tezos node consists of two components: - the shell, which comprises the network and storage layer, and embeds - the economic protocol component, which is the part that can be changed through amendment. -The role of the protocol -~~~~~~~~~~~~~~~~~~~~~~~~ +The role of the economic protocol +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. FIXME tezos/tezos#3921: + + Update for pipelined validation up to Lima. At a very high level, a protocol must: -- implement protocol-specific types, such as the type of operations or protocol-specific block header data (in addition to the shell generic header), -- define under which conditions a block is a valid extension of the current blockchain, and define an ordering on blocks to arbitrate between concurrent extensions. +- implement protocol-specific types, such as the type of operations or + protocol-specific block header data (in addition to the shell + generic header), + +- define under which conditions a block is a valid extension of the + current blockchain, and define an ordering on blocks to arbitrate + between concurrent extensions. -Validity conditions are implemented in the ``apply`` function which is called -whenever the node processes a block. The ``apply`` function takes as arguments a -*context* and a block. The context represents the *protocol state* and is -therefore protocol specific. The context may contain, for instance, a list of -accounts and their balances. More generally, the context must provide enough -information to determine the validity of a block. Given a context and a block, -the ``apply`` function returns the updated context if the block is valid and has -a higher :ref:`fitness`. The fitness determines a total ordering between blocks. +Validity conditions are implemented in the ``apply`` function which is +called whenever the node processes a block---see the dedicated +:doc:`protocol validation and operation` entry for further +detail into the validation and application process for +:ref:`blocks` and their +:ref:`operations`. .. _shell_proto_interact_alpha: Shell-protocol interaction ~~~~~~~~~~~~~~~~~~~~~~~~~~ -:doc:`Recall<../shell/the_big_picture>` that the economic protocol and the shell interact in order to ensure that the blocks being appended to the blockchain are valid. There are mainly two rules that the shell uses when receiving a new block: - -- 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 :package-api:`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 -~~~~~~ +In the Tezos :ref:`architecture`, the economic +protocol and the shell interact in order to ensure that the blocks +being appended to the blockchain are valid. There are mainly two rules +that the shell uses when receiving a new block: + +- 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 it has a higher + fitness than the current head; a block is + :ref:`valid` only if all the + operations included are also + :ref:`valid`. + +The support provided by the protocol for validating blocks can be +modulated by different :ref:`validation +modes`. They allow using this same +interface for quite different use cases, as follows: + +- being able to :ref:`apply` a block, + typically used by the shell's :doc:`validator <../shell/validation>` + component; +- being able to :ref:`construct` a block, + typically used by the baker daemon to *bake* -- that is, to produce + -- a new block; +- being able to :ref:`partially construct` + a block, typically used by the :doc:`prevalidator + <../shell/prevalidation>` to determine valid operations in the + mempool; and, +- being able to :ref:`pre-apply` a + block, typically used in the :doc:`validator <../shell/validation>` + to precheck a block, avoiding to further consider invalid blocks. + +.. _block_contents_alpha: + +Blocks, Operations and their Validation +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. FIXME tezos/tezos#3914: + + Integrate protocol-specific block parts in the blocks and ops + entry. A block consists of a header and operations. A block's header is composed of two parts: :ref:`the protocol-agnostic part` and :ref:`the protocol-specific part`. This separation enables the shell to interact with different -protocols. - -.. _validation_passes_alpha: - -Operations & Validation Passes -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The different kinds of operations are grouped in classes, such that operations belonging to different classes may be validated independently, and/or with different priorities. -Each class has an associated index, called a :ref:`validation pass`. -There are four classes of operations: :doc:`consensus ` operations, :doc:`voting ` operations, anonymous operations, manager operations. - -Consensus operations are endorsements, while `voting ` operations are ballot and proposal. - -Anonymous operations are operations which are not signed. There are three anonymous operations: seed nonce revelation, double baking evidence, and double endorsing evidence. The evidence for double baking and double endorsing is included in a block by the so-called accuser (see :ref:`slashing`). - -Manager operations are activation, origination (see :doc:`smart contracts`), transaction, reveal, and delegation (see :doc:`proof of stake `). Manager operations are the only fee-paying operations. - -Recall that users have associated :ref:`accounts ` which they activate before being able to participate. By means of the operation :ref:`origination`, accounts can be further associated with smart contracts in which they are called :ref:`originated accounts`. :ref:`Transactions` are used to either transfer tez between two accounts or run the code of a smart contract. Transactions are signed by an account's private key. Before making a transaction, a user must reveal her public key so that other users (not being aware of this public key) can effectively check the signature of the transaction. - -Manager operations can be grouped into batches forming a so-called group operation. A group operation satisfies: - -- atomicity: either all the operations in the batch succeed or none is applied -- efficiency: the whole batch is signed only once (by the same implicit account), thus it is much more efficient to check, and it requires much less gas -- usability: the batch only increments the counter of the signer account by one; for this reason it is easier for tools to provide sending several operations per block using operation batches than tracking counter changes. - -The list of operations can be obtained with :ref:`this rpc `. +protocols. Each Tezos economic protocol can specify different kinds of +operations, which are described further in detail in +:doc:`./blocks_ops`. + +The semantics of, respectively, operations and blocks is indeed also +dependent on each economic protocol. The :doc:`Validation and +Application` entry explains the internals of *validation* +-- that is, how to determine whether operations and blocks can be +safely be included in the Tezos blockchain -- and *application* -- +that is, how the effects of operations and blocks are taken into +account -- for this economic protocol. .. _protocol_constants_alpha: Protocol constants ~~~~~~~~~~~~~~~~~~ -Protocols are tuned by several *protocol constants*, such as the size of a nonce, or the number of blocks per cycle. -One can distinguish two kinds of protocol constants: +Protocols are tuned by several *protocol constants*, such as the size +of a nonce, or the number of blocks per cycle. One can distinguish two +kinds of protocol constants: + +- *fixed* protocol constants, such as the size of a nonce, are values + wired in the code of a protocol, and can only be changed by protocol + amendment (that is, by adopting a new protocol) -- *fixed* prototocol constants, such as the size of a nonce, are values wired in the code of a protocol, and can only be changed by protocol amendment (that is, by adopting a new protocol) -- *parametric* protocol constants, such as the number of blocks per cycle, are values maintained in a read-only data structure that can be instantiated differently, for the same protocol, from one network to another (for instance, test networks move faster). +- *parametric* protocol constants, such as the number of blocks per + cycle, are values maintained in a read-only data structure that can + be instantiated differently, for the same protocol, from one network + to another (for instance, test networks move faster). The *list* of protocol constants can be found in the OCaml APIs: -- fixed protocol constants are defined in the module :package-api:`Constants_repr ` -- parametric constants are defined in the module :package-api:`Constants_parametric_repr ` +- fixed protocol constants are defined in the module + :package-api:`Constants_repr + ` +- parametric constants are defined in the module + :package-api:`Constants_parametric_repr + ` The *values* of protocol constants in any given protocol can be found using specific RPC calls: @@ -144,6 +178,6 @@ See, for example: See also ~~~~~~~~ -An in-depth description of the inners of a protocol can be found in the blog -post `How to write a Tezos protocol +An in-depth description of the internals of developing a new Tezos +protocol can be found in the blog post: `How to write a Tezos protocol `_. diff --git a/docs/alpha/randomness_generation.rst b/docs/alpha/randomness_generation.rst index 80f9f9ab37513bf2ee84edf108ce71d73841598b..417c5acaa144f89f0cbf63e3bd119a1970bc479b 100644 --- a/docs/alpha/randomness_generation.rst +++ b/docs/alpha/randomness_generation.rst @@ -46,6 +46,8 @@ if a malicious participant can make sure she is the last revealer, then she can choose whether to reveal its committed value, effectively choosing between two different predetermined seeds. +.. _vdf_alpha: + Verifiable Delay Function ^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -75,6 +77,8 @@ cheaper and based on a weaker security assumption (low order assumption). Protocol -------- +.. _randomness_generation_alpha: + Randomness generation overview ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/docs/alpha/validation.rst b/docs/alpha/validation.rst new file mode 100644 index 0000000000000000000000000000000000000000..0814f9b2b992b86023dc369d6fd3effce8910937 --- /dev/null +++ b/docs/alpha/validation.rst @@ -0,0 +1,419 @@ +========================== +Validation and Application +========================== + +.. FIXME tezos/tezos#3921: + + Adapt to pipelined validation up to Lima and v7 environment + +The :doc:`economic protocol` is responsible for providing +the rules that govern the Tezos network, and for enforcing that these +rules implement a correct blockchain protocol. However, it does so +:ref:`in coordination with a Tezos shell`, who +ultimately implements these rules on its behalf. To this end, a Tezos +economic protocol must provide the shell with an interface enabling +roughly the following functionalities: + +- deciding whether an operation is *valid*, and thus can be safely + included into a new block in the blockchain; + +- deciding whether a new block is *valid*, and thus can be safely + appended to the blockchain; + +- including an operation in a block, and executing it on the + blockchain state, effectively modifying the ledger state; and, + +- appending a new block to a Tezos blockchain, and computing the + updated ledger state. + +From a higher-level, *abstract* perspective, the validation system in +the Tezos protocol implements this business logic in a functional, +state-passing machine where: + +- Its state is given by the :ref:`context`, the internal + representation of the state of the Tezos ledger at a given blockchain + level. For instance, the context contains the information of all + activated accounts and contracts, and their balances. More + generally, the context must provide enough information to determine + the validity of operations, and blocks. + +- The *apply_operation* method determines whether an operation is safe + to be executed in a given context. If so, it proceeds to execute it + and outputs the context resulting from the applied operation's + effects. + +- The *apply* method takes as input a block and a context, determines + whether the block can be safely and correctly appended to the + current head of the chain. If so, it appends the block to the chain + and outputs the resulting context, reflecting the state of the + ledger after the block has successfully been applied. *apply* relies + on (i.e., it should call) *apply_operation* to validate and apply + each operation in the block, and compute intermediate states. + +.. TODO #4155: + + When creating a new environment, update references to V in the + paragraph below. + +However, the *concrete* API exported from the Tezos economic protocol +does not implement this business logic *monolithically*, as described +above, but it rather presents a more fine-grained API. The rationale +is to provide specialized variations of the core *validation* and +*application* functionality, dubbed :ref:`Validation +modes`. For example, these modes enable the +protocol to distinguish operations "in the mempool", whose validation +is triggered by the :doc:`prevalidator<../shell/prevalidation>`, from +operations included in newly received blocks, whose validation is +triggered by the :ref:`block validator`, in order to +localize validation rules as needed. The resulting concrete API is +specified by the :package-api:`Protocol +` +module in the :doc:`protocol +environment<../shell/protocol_environment>` ``V8``, and it is +implemented by this protocol in the +:package-api:`Main` +module. + +The rest of this document is organized as follows: we first describe +the different validation modes implemented by this Tezos economic +protocol, and then we delve deeper into the particulars of validation +and application for blocks and the operations supported. + +.. _validation_modes_alpha: + +Validation modes +================ + +The Tezos protocol provides different validation modes, intended to be +used by Tezos *shell* and *baker* software implementations when +needing to apply (or to assert the validity) of blocks and operations +under different, or specialized, circumstances -- for example, in +order to *bake* a block. For each of these validation modes, the API +specified by the protocol environment offers an entry point so that +protocol-agnostic components, the Octez shell for instance, are able +to use these different modes. + +.. _full_application_alpha: + +Full Application +~~~~~~~~~~~~~~~~ + +The ``Full application`` mode is intended to be used to *fully* +validate and apply blocks. In particular, this mode is used to +validate and apply a **known** block, with a known operation trace. A +Tezos shell implementation should use the full application mode to +decide whether an incoming block can be safely included in the +blockchain. That is, all validity checks are enabled: the block's +signature is correct, and **all** operations included in the block are +valid; the correct amount of consensus operations have been included +in order to satisfy the consensus' threshold, etc. + +.. _full_construction_alpha: + +Full Construction +~~~~~~~~~~~~~~~~~ + +The ``Full construction`` mode is intended to be used when a +*delegate* is trying to bake a block and therefore needs to filter the +validity of the desired operation trace, to include only valid +operations. This mode is mostly similar to the ``Full application`` +mode except that *some* global block validity checks are disabled, and +consensus operations are validated with slightly different +preconditions. For instance, since a delegate cannot sign a block +while it is being built, the signature check is disabled, and it will +be left to the baker to correctly sign the resulting block after its +construction is finalized. + +In Octez, this mode is mainly used by the baker daemon. + +.. _partial_construction_alpha: + +Partial Construction +~~~~~~~~~~~~~~~~~~~~ + +The ``Partial construction`` mode, also known as ``Mempool mode`` is +used by the :doc:`prevalidator component<../shell/prevalidation>` of +an Octez node to validate incoming operations -- that is, those +not-yet included into blocks. This mode's business-logic is very close +to the ``Full construction`` mode, and the differences boil down to +the intended usage. The partial construction mode does not try to +fully bake a block, but rather to inform the Octez prevalidator on the +potential validity of operations (and whether they can safely included +into a block), so that the latter can **classify** incoming +operations, and further decide how to process them accordingly. + +.. _protocol_classification_alpha: + +The protocol provides the shell with the following classification of +an operation, consisting of one valid kind -- ``Applied`` --, and +:ref:`four error kinds ` defined by the +protocol environment: + +- ``Applied``: the operation is valid and can be included in a + potential block in the current context. + +- ``Temporary``: the operation is invalid in the current context, but + it could *later* become valid -- in the context associated to a + successor block of the current head. For instance, a manager + operation whose counter value is greater than the one expected (a + *"counter-in-the-future"* error), or the manager's balance is + insufficient to pay the operation's fees, etc. + +- ``Branch``: the operation is invalid in the current context and in + any possible context from its future successors, but it might still + be valid in an alternative branch. For example: a manager operation + with a smaller counter than the one expected (a + *"counter-in-the-past"* error), an unexpected endorsement for the + current level, etc. + +- ``Permanent``: the operation is invalid in the current context, and + there isn't any plausible context where it might be or become + valid. For example, an operation carrying an invalid signature. + +- ``Outdated``: the operation is *too old* to be included in a + block. Furthermore, there might be still some value in the + information provided by an ``Outdated`` operation. An example is the + case of an endorsement which was received *too late*, but that could + still be used to form a consensus quorum. + +.. _partial_application_alpha: + +Partial Application +~~~~~~~~~~~~~~~~~~~ + +The ``Partial application`` mode is used for :ref:`multi-pass +validation`. Its aim is to provide Tezos shell +implementations with a light-weight (read "fast") block application +mechanism, which can determine whether a block has a *chance* of being +valid or not, in a situation when the provided context is *not a +recent one*. That is, when the block candidate succeeds neither the +head of the chain, nor a close ancestor. + +This validation mode is typically used when the node receives a +significantly large branch -- for instance, while bootstrapping. To +check whether this branch is plausibly valid or potentially malicious +spam, the shell retrieves the context from the most recent common +ancestor between its current head and the announced branch, and +proceeds to "partially apply" each block of this branch using the +common ancestor's context. + +Indeed, by relying on the ancestor context, this mode can *only* +assert the validity of consensus-related preconditions (endorsing +power, block fitness, etc.), as future consensus slots are known in +advance -- how much in advance being specified by the +```` protocol constant. Thus, the `Partial +application` mode provides an over-approximation of the branch's +validity, and as a result intermediate results are not committed on +disk in order to prevent potential attacks. + +.. _block_validation_overview_alpha: + +Block Validation +================ + +.. FIXME tezos/tezos#3921: + + Adapt to pipelined block validation up to Lima and v7 environment. + +The validity of a blocks depends on a set of precondition checks +implemented in different steps, which happen at different stages of +the application (and the construction) of a block. + +The first step in the process is to decide whether a candidate block +is *well-formed*, that is, that it has the expected "shape" of a valid +block under the current Tezos economic protocol. Given a block +candidate, the block validation process will then verify that the +candidate block declares consistent :ref:`level`, +:ref:`round`, and timestamp values; that it carries a valid +signature, etc. At this step, the block validation process will also +initialize the data-structures required for subsequent steps. + +The second step iterates over the block's operations and proceeds to +apply them sequentially. When at least one operation is found to be +invalid, under the conditions described in +:ref:`operation_validity_alpha` further below, the whole block is +considered as invalid. + +The last step in the block validation process, known as "block +finalization", aims to verify that the collected consensus operations +constitute a sufficiently large :ref:`quorum`. That is, +it will verify that the total endorsing power present in the block is +greater than the ``CONSENSUS_THRESHOLD`` constant. + +This sequence of three steps also yields a new context -- the +resulting state of the Tezos ledger after the application of the +candidate block. The shell may decide to commit this context to disk. + +The Tezos economic protocol also offers a cheap (read "faster") +alternative to determine an over-approximation of the validity of a +block (see :ref:`partial_application_alpha` above). This feature +allows the shell to propagate blocks faster without needing to fully +validate them, speeding-up block propagation over the network. Of +course, as this is an over-approximation, this feature cannot be +considered to provide a safe guarantee that a block will be valid: in +particular, it does not validate all kinds of operations. + +.. _operation_validity_alpha: + +Operation Validation and Application +==================================== + +In the Tezos economic protocol, we dissociate the notion of *validity* +from the notion of *applicability* for operations. A valid operation +is an operation that can be included safely in a block without +affecting the block's validity. Applying an operation, on the other +hand, actually performs the operation's side-effects which can be: +registering a new delegate, executing a smart contract, voting for a +new protocol amendment proposal, etc. + +Note that an operation may fail during the application phase, even +though it has been checked as valid. For example, a smart contract +call that exceeds its gas limit can be included in a block even if an +error is raised at run-time. The application (that is, the operation's +side-effects) will not take effect, but fees will nonetheless be taken +from the account submitting the smart contract call. + +In the sequel we refine the validity conditions and describe the +application process for each of the different validation passes. + +.. FIXME tezos/tezos#3921: + + Adapt to pipelined validation up to Lima and v7 environment. + +.. _voting_operations_validity_alpha: + +Validity and Application of Voting Operations +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. FIXME tezos/tezos#3921: + + Adapt to pipelined validation up to Lima and v7 environment. + +.. _anonymous_operations_validity_alpha: + +Validity and Application of Anonymous Operations +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. FIXME tezos/tezos#3921: + + Adapt to pipelined validation up to Lima and v7 environment. + +.. _manager_operations_validity_alpha: + +Validity of Manager Operations +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +In this sub-section, we explain the conditions for manager operations +(and batches of managers operations) to be considered valid and hence +suitable for inclusion in a block. + +Validity of Individual Manager Operations +......................................... + +:ref:`Manager operation` are a class of +operations, issued by a single *manager* account which signs the +operation and pays their fees. The different manager operation kinds +share several common fields: + +- ``source``: the public key's hash of the *source* account of the + manager operation -- that is, the *manager*. +- ``fee``: the amount of tez paid to the baker which decides to + include this operation; +- ``counter``: the manager account's counter, incremented each time + this account executes a manager operation, to prevent + replay-attacks. +- ``gas_limit``: the maximum amount of gas that this operation may + consume before failing. +- ``storage_limit``: the maximum amount of storage that this operation + may require before failing. +- ``operation``: the actual operation(s) -- e.g., transfers, + smart-contract calls, originations, delegations, etc. +- ``signature``: the manager's signature used to prove its identity. + +A manager operation is **valid** if and only if all of the following +conditions hold: + +- The operation source's public key has been previously *revealed*, + unless the operation is itself a ``Reveal`` operation. +- The operation's signature is correct with regard to the manager + account's public key. +- The provided ``counter`` value is the expected one for the manager. +- Depending on the operation's kind, the ``gas_limit`` is high enough + to cover the minimal cost of parsing the operation and further + minimal treatment. +- The manager account is solvent to pay the announced fees. + +Validity of Manager Operation Batches +..................................... + +A :ref:`batch` of manager operations +includes one or more manager operations for sequential and atomic +execution. The atomicity property imposes that the validity of a batch +should entail the validity of each individual operation in the batch, +as defined above. However, it also entails some additional *global* +constraints on manager batches. + +For each of the operations present in a batch, the validation process +must check that the individual constraints above are satisfied, *with +the exception of* the signature constraint. Given that the signature +concerns the whole batch, as all operations in the batch are signed by +the same manager, it suffices to verify the signature only once. + +The **global batch validity** constraint for this economic protocol is +defined as the conjunction of the following conditions: + +- When a ``Reveal`` operation is present, **it must only occur once**, + and **it must be placed at the head** of the batch -- that is, the + ``Reveal`` operation must be the first operation in the batch. +- Every operation in the batch should declare the same `source`. +- Each of the individual operation counters must be incremented + correctly and sequentially. +- The sum of each individual operation's declared fees must be lower + than the account's balance. That is, the manager account must be + solvent to pay the announced fees for all the operations in the + batch. + +.. _manager_operations_application_alpha: + +Application of Manager Operations +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Once the validity of a manager operation (or, a batch of manager +operations) is established, the protocol proceeds to apply the +operation. This first step in this application phase is to transfer +the operation's fees to the baker that included this operation. Then, +the actual application depends on the operation kind. For instance, +this could be a smart contract execution, enacting a delegation, or +multiple actions executed as a batch. The application of a batch of +manager operations consists of the sequential application of each +operation in the batch, following their inclusion order -- the head of +the batch being the first manager operation being applied. + +The application of each individual manager operation may either +succeed -- and therefore be reported as ``Applied`` --, or indeed fail +with an error. In both cases, the fees are taken and the counter for +the operation's manager is incremented. + +When a manager operation fails, every side-effect which was previously +performed is backtracked. Moreover, the (rest of the) batch has to be +aborted. Thus, depending on the position of the manager operation in +a batch, its failure has to be propagated accordingly: + +- If there were other successfully applied operations in the batch + prior to the offending one, the effect of each of them has to be + reverted, and each of them will be reported as ``Backtracked``. + +- If there were other operations pending application after the + offending one, their application is aborted, and they are reported + as ``Skipped``. + +For example, let's consider a simple batch of three manager operations +``[op1, op2, op3]``, if ``op1`` is successful but ``op2`` fails, the +ticket result for the application of the manager operation batch will +report: + +* ``op1`` -- ``Backtracked``, ```op1`` was applied successfully, but + after ``op2`` failed, the operation was canceled; +* ``op2`` -- ``Failed``, the application of this particular operation failed; +* ``op3`` -- ``Skipped``, this operation was never executed because + ``op2`` had previously failed. diff --git a/docs/kathmandu/blocks_ops.rst b/docs/kathmandu/blocks_ops.rst new file mode 100644 index 0000000000000000000000000000000000000000..0fcfef7a8511e415077128c0762c519ff108506e --- /dev/null +++ b/docs/kathmandu/blocks_ops.rst @@ -0,0 +1,225 @@ +===================== +Blocks and Operations +===================== + +The content of a Tezos block is made up of operations, which implement +and reify different functionalities provided by a Tezos economic +protocol: from reaching consensus on the state of the Tezos +blockchain, to performing smart contract calls and transactions. Each +Tezos economic protocol can specify different kinds of operations. + +This entry describes the operations supported by :doc:`the economic +protocol <./protocol>` that implement *enabled* features -- that is, +those available to end-users on Tezos Mainnet. The complete list of +operations, including those corresponding to features in development +or available only on test networks, is given in the +:package-api:`OCaml Documentation +`. + +.. _validation_passes_kathmandu: + +Validation Passes +~~~~~~~~~~~~~~~~~ + +The different kinds of operations are grouped into classes. Each class +has an associated index, a natural number, also known as a +:ref:`validation pass`. There are currently four classes +of operations: :ref:`consensus `, +:ref:`voting `, +:ref:`anonymous`, and :ref:`manager +operations`. This order also specifies +the :ref:`validation and application` +priority of each of these classes. Consensus operations are +considered the highest priority ones, and manager operations the +lowest. + +The current protocol implementation enforces the following invariant: + +- each kind of operation belongs to *at most one* validation pass; +- operations whose kind does not belong to any validation pass cannot + be :ref:`applied`. + +.. FIXME tezos/tezos#3915: + + Failing noops don't fit within any of the validation passes + below. We need to change the structure a bit to be able to list + them here. + +In the sequel, we describe the different classes of operations, and +the different kinds of operations belonging to each class. + +.. _consensus_operations_kathmandu: + +Consensus Operations +~~~~~~~~~~~~~~~~~~~~ + +.. TODO tezos/tezos#4204: document PCQ/PQ + +Consensus operations are administrative operations that are necessary +to implement the :doc:`consensus algorithm`. There are two +kinds of consensus operations, each belonging to the different voting +phases required to agree on the next block. + +- A ``Preendorsement`` operation implements a first vote for a + :ref:`candidate block ` with the aim of + building a :ref:`preendorsement quorum `. + +- An ``Endorsement`` operation implements a vote for a candidate block + for which a preendorsement quorum certificate (PQC) has been + observed. + +.. _consensus_content_kathmandu: + +These operations carry a similar "consensus content" -- consisting of +the delegate's first :ref:`slot`, the target +:ref:`level` and :ref:`round`, and the hash of the +(pre)endorsed block' payload. + + +.. _voting_operations_kathmandu: + +Voting Operations +~~~~~~~~~~~~~~~~~ + +Voting operations are operations related to the on-chain :doc:`Tezos +Amendment` process. In this economic protocol, there are two +voting operations: + +- The ``Proposal`` operation enables delegates to submit (also known as + to "inject") protocol amendment proposals, or to up-vote previously + submitted proposals, during the Proposal period. + +- The ``Ballot`` operation enables delegates to participate in the + Exploration and Promotion periods. Delegates use this operation to + vote for (``Yay``), against (``Nay``), or to side with the majority + (``Pass``), when examining a protocol amendment proposal. + +Further details on each operation's implementation and semantics are +provided in the dedicated entry for :ref:`on-chain +governance`. + +.. _anonymous_operations_kathmandu: + +Anonymous Operations +~~~~~~~~~~~~~~~~~~~~ + +This class groups all operations that do not require a signature from +a Tezos account. They implement different functionalities of the +protocol, and their common characteristic is that they allow the +account originating these operations to remain anonymous in order to +avoid censorship. + +Two operations in this class implement functionality pertaining to the +protocol's :doc:`random seeds generation +mechanism`: + +- The ``Seed_nonce_revelation`` operation allows a baker to + anonymously reveal the nonce seed for the commitment it had included + in a previously baked block (in the previous cycle). + +- The ``Vdf_revelation`` operation allows the submission of a solution + to, and a proof of correctness of, the :ref:`VDF + challenge` corresponding to the VDF revelation period + of the randomness generation protocol. + +Further details on the latter operation's implementation and semantics +are provided in the :ref:`random seed generation +protocol`. + +Three operations in this class are used to :ref:`punish participants +which engage in Byzantine behaviour` -- notably +delegates which :ref:`"double sign" ` blocks, or emit +conflicting :ref:`consensus +operations`: + +- The ``Double_preendorsement_evidence`` operation allows for accusing + a delegate of having *double-preendorsed* -- i.e., of having + preendorsed two different block candidates, at the same level and at + the same round. The bulk of the evidence, the two arguments + provided, consists of the two offending preendorsements. + +- Similarly, the ``Double_endorsement_evidence`` operation allows for + accusing a delegate of having *double-endorsed* -- i.e., of having + endorsed two different block candidates at the same level and the + same round -- by providing the two offending endorsements. + +- The ``Double_baking_evidence`` allows for accusing a delegate of + having "double-baked" a block -- i.e., of having signed two + different blocks at the same level and at same round. The bulk of + the evidence consists of the :ref:`block + headers` of each of the two offending + blocks. + +See :ref:`here` for further detail on the +semantics of evidence-providing operations. + +Finally, the ``Activation`` operation allows users which participated +in the Tezos fundraiser to make their :ref:`accounts ` +operational. + +.. _manager_operations_kathmandu: + +Manager Operations +~~~~~~~~~~~~~~~~~~ + +Manager operations enable end-users to interact with the Tezos +blockchain -- e.g., transferring funds or calling :doc:`smart +contracts`. A manager operation is issued by a single +*manager* account which signs the operation and pays the +:ref:`fees` to the baker for its inclusion in a block. Indeed, +manager operations are the only fee-paying and +:ref:`gas-consuming` operations. + +- The ``Reveal`` operation reveals the public key of the sending + manager. Knowing this public key is indeed necessary to check the signature + of future operations signed by this manager. +- The ``Transaction`` operation allows users to either transfer tez + between accounts and/or to invoke a smart contract. +- The ``Delegation`` operation allows users to :ref:`delegate their + stake ` to a :ref:`delegate` (a + *baker*), or to register themselves as delegates. +- The ``Origination`` operation is used to + :ref:`originate`, that is to deploy, smart contracts + in the Tezos blockchain. +- The ``Set_deposits_limit`` operation enables delegates to adjust the + amount of stake a delegate :ref:`has locked in + bonds`. +- Support for registering global constants is implemented with the + ``Register_global_constant`` operation. +- The ``Increase_paid_storage`` operation allows a sender to increase + the paid storage of some previously deployed contract. +- The ``Event`` operation enable sending event-like information to + external applications from Tezos smart contracts -- see + :doc:`Contract Events` for further detail. + +Moreover, all operations necessary to implement Tezos' *enshrined* +Layer 2 solutions into the economic protocol are also manager +operations: + +.. FIXME tezos/tezos#3916: expand documentation of TORU operations. + +- :doc:`Transaction Optimistic Rollups` are + implemented using the following manager operations: + ``Tx_rollup_origination``, ``Tx_rollup_submit_batch``, + ``Tx_rollup_commit``, ``Tx_rollup_return_bond``, + ``Tx_rollup_finalize_commitment``, ``Tx_rollup_remove_commitment``, + ``Tx_rollup_rejection``, ``Tx_rollup_rejection``, + ``Transfer_ticket``. + +.. _manager_operations_batches_kathmandu: + +Manager Operation Batches +""""""""""""""""""""""""" + +Manager operations can be grouped, forming a so-called +**batch**. Batches enable the inclusion of several manager operations +from the same manager in a single block. + +Batches satisfy the following properties: + +- All operations in a batch are issued by the same manager, which + provides a single signature for the entire batch. +- A batch is :ref:`applied` + atomically: all its operations are executed sequentially, without + interleaving other operations. Either all the operations in the + batch succeed, or none is applied. diff --git a/docs/kathmandu/consensus.rst b/docs/kathmandu/consensus.rst index 29c7a90ed32f276644edc36ba3576e30dca281e6..ef9e48cbfbaf74289fe5eac7331e6f49e1eb7505 100644 --- a/docs/kathmandu/consensus.rst +++ b/docs/kathmandu/consensus.rst @@ -448,6 +448,11 @@ Consensus related protocol parameters Shell-protocol interaction revisited ------------------------------------ +.. FIXME tezos/tezos#3914: + + Integrate protocol-specific block parts in the blocks and ops + entry. + :ref:`Recall` that, for the shell to interact with the economic protocol, two notions are defined abstractly at the level of the shell and made concrete at the level of the consensus protocol. Namely, these two notions are the protocol-specific header and the fitness. As in Emmy*, the protocol-specific header contains the fields: diff --git a/docs/kathmandu/glossary.rst b/docs/kathmandu/glossary.rst index 4a779f64c7baeab38eda5f35fdafe826c037d664..6d7183b4026baad153ad250aa6c600d55b3a44c2 100644 --- a/docs/kathmandu/glossary.rst +++ b/docs/kathmandu/glossary.rst @@ -74,9 +74,13 @@ _`Cycle` A cycle is a set of consecutive blocks. E.g., cycle 12 started at block_ level 49152 and ended at block_ level 53248. - Cycles are used as a unit of “time” in the block_ chain. For example, the - different phases in the amendment voting procedures are defined based on - cycles. + Cycles are used as a unit of “time” in the blockchain. For + example, the different phases in the amendment voting procedures + are defined based on cycles. + + The length of a cycle is a (parametric) protocol + :ref:`constant`, and thus might change across different + Tezos protocols. _`Delegate` An `implicit account`_ to which an account_ has delegated their @@ -92,20 +96,36 @@ _`Delegation` the account_. _`Double signing` - When a baker_ signs two different blocks at the same level and same round, - it is called double baking. Double baking is detrimental to the network and might be - indicative of an attempt to double spend. - The same goes for signing two different endorsements at the same level and the same round. - As such, double signing is punished by the - network: an accuser_ can provide proof of the double signing to be awarded - part of the double signer's deposit. + The action of a baker_ signing two different blocks at the same + level and same round is called *double baking*. Double baking + is detrimental to the network and might be indicative of an + attempt to double spend. The same goes for signing two different + *endorsements* at the same level and the same round. + + Double signing (i.e. double baking or double endorsing) is + punished by the network: an accuser_ can provide proof of the + double signing to be awarded part of the double signer's deposit + -- see :ref:`Slashing`. + +_`Failing Noop` + The ``Failing_noop`` operation implements a *No-op*, which always + fails at :ref:`application time`, and + should never appear in :ref:`applied + blocks`. This operation allows end-users to + :ref:`sign arbitrary messages` which have no + computational semantics. _`Fee` - To ensure responsible use of computation resources of other nodes, and also to encourage active participation in the consensus protocol, there are some - fees that users pay to bakers for including their operations in blocks. - For example, fees are paid to a baker for operations such as a transaction_ or a revelation of a public key. + To ensure responsible use of computation resources of other + nodes, and also to encourage active participation in the consensus + protocol, users pay fees to bakers for including (some of) their + operations in blocks. For example, fees are paid to a baker for + operations such as a transaction_ or a revelation of a public key. + + Currently, only :ref:`manager operations` + require collecting fees from its sender account_. - See also `burn`_. + See also `burn`_. _`Gas` A measure of the number of elementary operations_ performed during @@ -117,7 +137,7 @@ _`Implicit account` contract`_, an `Implicit account`_ cannot include a script and it cannot reject incoming transactions. - If registered, an `implicit account`_ can act as a delegate_. + If *registered*, an `implicit account`_ can act as a delegate_. The address of an `implicit account`_ always starts with the letters `tz` followed by `1`, `2` or `3` (depending on the @@ -163,7 +183,8 @@ _`Originated account` See `smart contract`_. _`Origination` - An operation_ to create a `smart contract`_. + A manager operation_ whose purpose is to create -- that + is, to deploy -- a `smart contract`_ on the Tezos blockchain. _`Round` An attempt to reach consensus on a block at a given level. @@ -177,10 +198,11 @@ _`Roll` deprecated; see `Minimal stake`_. _`Smart contract` - Account_ which is associated to a :ref:`Michelson ` script. They are - created with an explicit origination_ operation and are therefore - sometimes called originated accounts. The address of a smart - contract always starts with the letters ``KT1``. + Account_ which is associated to a :ref:`Michelson + ` script. They are created with an + explicit origination_ operation and are therefore sometimes called + originated accounts. The address of a smart contract always starts + with the letters ``KT1``. _`Smart Optimistic Rollups` Smart optimistic rollups constitute a `layer 2`_ solution that can be used to deploy either a general-purpose polyvalent layer 2 blockchain @@ -191,6 +213,13 @@ _`Transaction` An operation_ to transfer tez between two accounts, or to run the code of a `smart contract`_. +_`Validation pass` + An index (a natural number) associated with a particular kind of + operations, allowing to group them into classes. Validation passes + enable prioritizing the :ref:`validation and + application` of certain classes of + operations. + _`Voting period` Any of the ``proposal``, ``exploration``, ``cooldown``, ``promotion`` or ``adoption`` stages in the voting procedure when diff --git a/docs/kathmandu/plugins.rst b/docs/kathmandu/plugins.rst index 057080a8beb522feb7680669daf5c18ac8b2cd65..4ef29a90b5a6f18a4a68ea2d9ab26689b89f5f6f 100644 --- a/docs/kathmandu/plugins.rst +++ b/docs/kathmandu/plugins.rst @@ -101,6 +101,7 @@ This filtering strategy is implemented in the ``prefilter`` (see :doc:`../shell/prevalidation`). +.. _precheck_filter_kathmandu: Prechecking of manager operations ................................. @@ -123,11 +124,6 @@ increased the chain's fitness), only one operation per manager is propagated. All other received operations originating from the same manager will be classified as ``Branch_delayed`` and will not be propagated. -This criterion is used only by the prevalidator to decide the propagation of -operations. A baker can still include several operations originating from the same -manager in a single block, provided that it gets them in time (note that they can be -propagated by nodes using different versions or implementations). - Alternatively, a user can inject an operation with the same manager and the same counter, but with a higher fee to replace an already existing operation in the prevalidator. Only one of the two operations will be eventually @@ -155,7 +151,7 @@ In addition to quick detection of operations that have no chance to be prechecked or applied in the current context, the mempool's ``prefilter`` provides a priority for each successfully filtered operation. Concretely, the priority is either ``High``, ``Medium`` or ``Low`` in the current implementation, depending -on the :ref:`validation pass`.Some extra information (like the fees, or the gas/fees +on their :ref:`validation pass`.Some extra information (like the fees, or the gas/fees ratio of manager operations) are also provided along the priorities to enable fine-grained operations ordering. This extra information is similar to the one used by the baker's diff --git a/docs/kathmandu/precheck.rst b/docs/kathmandu/precheck.rst index a4339589255d9e1d8a64a2a219c849491aecc14f..0a4b3a1c5eba8a99f40269a2dc182bd814183b86 100644 --- a/docs/kathmandu/precheck.rst +++ b/docs/kathmandu/precheck.rst @@ -2,22 +2,21 @@ Prechecking of manager operations ================================= The prevalidator of Octez prevents the propagation of non-valid -operations by trying to apply (or execute) them. -However, executing -manager operations (like complex smart contract calls) can be -time-consuming. -To ensure a high throughput of the Tezos protocol, the -propagation of operations should be as fast as possible. This calls -for a lighter approach. +operations by trying to :ref:`apply` +them. However, executing :ref:`manager +operations` can be time-consuming. To +ensure a high throughput of the Tezos protocol, the propagation of +operations should be as fast as possible. This calls for a lighter +approach. Prechecking manager operations implements such a lighter approach, by discarding most invalid operations, without executing any of them. -This is possible because the validity of an operation (in the sense, -being able to include it in a block) -depends on its solvability (see below :ref:`solvability_kathmandu`). +This is possible because the :ref:`validity of a manager +operation` depends on its +*solvability* -- :ref:`defined further below`. -Fortunately, it turns out that deciding whether an operation is solvable can be achieved without -applying it. +Fortunately, it turns out that deciding whether an operation is +solvable can be achieved without applying it. However, restricting the propagation to solvable operations is not enough to ensure resilience against DDoS attacks. @@ -33,23 +32,21 @@ block. Note however that one can still inject successive operations with the same counter using the ``replace-by-fee`` feature. - .. _solvability: .. _solvability_kathmandu: Solvable operations ------------------- -The solvability of an operation depends on the content of the Tezos -context in which it is applied. - +The solvability of a manager operation depends on the content of the +Tezos context in which it is applied. In the following, we consider the context kept by the prevalidator (see :doc:`../shell/prevalidation`). Checking operation solvability with this context is lighter than with the contexts for block validation or block construction: it can be decided without checking whether the gas announced by the operation -is below the remaining gas for the whole block. +is below the remaining gas for the whole block -- . Checking solvability consists in verifying that the operation is well-formed and that fees can be paid: no execution of operations (especially of smart-contract code) is done to determine @@ -68,7 +65,6 @@ Roughly, a manager operation is solvable when the following conditions hold: operation; and - the signature of the operation is valid. - Co-precheckable operations -------------------------- @@ -86,7 +82,7 @@ In this case, the operations could be included in the next block in any order, modulo block limits (eg. maximum gas, block size limit, etc). -The precheck of a manger operation, with respect to a context and a +The precheck of a manager operation, with respect to a context and a set of co-precheckable operations, consists in checking whether adding the operation to the set preserves the operations of the set being co-precheckable. diff --git a/docs/kathmandu/protocol.rst b/docs/kathmandu/protocol.rst index 1e263d2cb0458e77bdef2bfd3bc597c72d81f7a5..57a36ccc1b4ae5d27aa1c1976c1e3ae872799c94 100644 --- a/docs/kathmandu/protocol.rst +++ b/docs/kathmandu/protocol.rst @@ -83,5 +83,15 @@ Sapling, etc), and some details about its implementation. .. toctree:: :maxdepth: 2 - + event + +.. toctree:: + :maxdepth: 2 + + blocks_ops + +.. toctree:: + :maxdepth: 2 + + validation diff --git a/docs/kathmandu/protocol_overview.rst b/docs/kathmandu/protocol_overview.rst index ef457b858ce3ff55629064b35ee4582c67e944f3..5856df6a52d5fcb0aac22305cf3df90c25f279fb 100644 --- a/docs/kathmandu/protocol_overview.rst +++ b/docs/kathmandu/protocol_overview.rst @@ -37,29 +37,32 @@ different implementations, and this is important, for instance because different to implement different transaction selection strategies. Tezos is a self-amending blockchain, in that a large part of Tezos can be -changed through a so-called amendement procedure. To this end, as mentioned in -:doc:`the big picture<../shell/the_big_picture>`, a Tezos node consists of two +changed through a so-called amendment procedure. To this end, as mentioned in +:ref:`the big picture`, a Tezos node consists of two components: - the shell, which comprises the network and storage layer, and embeds - the economic protocol component, which is the part that can be changed through amendment. -The role of the protocol -~~~~~~~~~~~~~~~~~~~~~~~~ +The role of the economic protocol +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ At a very high level, a protocol must: -- implement protocol-specific types, such as the type of operations or protocol-specific block header data (in addition to the shell generic header), -- define under which conditions a block is a valid extension of the current blockchain, and define an ordering on blocks to arbitrate between concurrent extensions. +- implement protocol-specific types, such as the type of operations or + protocol-specific block header data (in addition to the shell + generic header), -Validity conditions are implemented in the ``apply`` function which is called -whenever the node processes a block. The ``apply`` function takes as arguments a -*context* and a block. The context represents the *protocol state* and is -therefore protocol specific. The context may contain, for instance, a list of -accounts and their balances. More generally, the context must provide enough -information to determine the validity of a block. Given a context and a block, -the ``apply`` function returns the updated context if the block is valid and has -a higher :ref:`fitness`. The fitness determines a total ordering between blocks. +- define under which conditions a block is a valid extension of the + current blockchain, and define an ordering on blocks to arbitrate + between concurrent extensions. + +Validity conditions are implemented in the ``apply`` function which is +called whenever the node processes a block---see the dedicated +:doc:`protocol validation and operation` entry for further +detail into the validation and application process for +:ref:`blocks` and their +:ref:`operations`. .. _shell_proto_interact: .. _shell_proto_interact_kathmandu: @@ -67,53 +70,69 @@ a higher :ref:`fitness`. The fitness determines a total order Shell-protocol interaction ~~~~~~~~~~~~~~~~~~~~~~~~~~ -:doc:`Recall<../shell/the_big_picture>` that the economic protocol and the shell interact in order to ensure that the blocks being appended to the blockchain are valid. There are mainly two rules that the shell uses when receiving a new block: - -- 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 :package-api:`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 -~~~~~~ +In the Tezos :ref:`architecture`, the economic +protocol and the shell interact in order to ensure that the blocks +being appended to the blockchain are valid. There are mainly two rules +that the shell uses when receiving a new block: + +- 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 it has a higher + fitness than the current head; a block is + :ref:`valid` only if all the + operations included are also + :ref:`valid`. + +The support provided by the protocol for validating blocks can be +modulated by different :ref:`validation +modes`. They allow using this same +interface for quite different use cases, as follows: + +- being able to :ref:`apply` a block, + typically used by the shell's :doc:`validator <../shell/validation>` + component; +- being able to :ref:`construct` a block, + typically used by the baker daemon to *bake* -- that is, to produce + -- a new block; +- being able to :ref:`partially construct` + a block, typically used by the :doc:`prevalidator + <../shell/prevalidation>` to determine valid operations in the + mempool; and, +- being able to :ref:`pre-apply` a + block, typically used in the :doc:`validator <../shell/validation>` + to precheck a block, avoiding to further consider invalid blocks. + +.. _block_contents: +.. _block_contents_kathmandu: + +Blocks, Operations and their Validation +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. FIXME tezos/tezos#3914: + + Integrate protocol-specific block parts in the blocks and ops + entry. A block consists of a header and operations. A block's header is composed of two parts: :ref:`the protocol-agnostic part` and :ref:`the protocol-specific part`. This separation enables the shell to interact with different -protocols. - -.. _validation_passes: -.. _validation_passes_kathmandu: - -Operations & Validation Passes -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The different kinds of operations are grouped in classes, such that operations belonging to different classes may be validated independently, and/or with different priorities. -Each class has an associated index, called a :ref:`validation pass`. -There are four classes of operations: :doc:`consensus ` operations, :doc:`voting ` operations, anonymous operations, manager operations. - -Consensus operations are endorsements, while `voting ` operations are ballot and proposal. - -Anonymous operations are operations which are not signed. There are three anonymous operations: seed nonce revelation, double baking evidence, and double endorsing evidence. The evidence for double baking and double endorsing is included in a block by the so-called accuser (see :ref:`slashing`). - -Manager operations are activation, origination (see :doc:`smart contracts`), transaction, reveal, and delegation (see :doc:`proof of stake `). Manager operations are the only fee-paying operations. - -Recall that users have associated :ref:`accounts ` which they activate before being able to participate. By means of the operation :ref:`origination`, accounts can be further associated with smart contracts in which they are called :ref:`originated accounts`. :ref:`Transactions` are used to either transfer tez between two accounts or run the code of a smart contract. Transactions are signed by an account's private key. Before making a transaction, a user must reveal her public key so that other users (not being aware of this public key) can effectively check the signature of the transaction. - -Manager operations can be grouped into batches forming a so-called group operation. A group operation satisfies: - -- atomicity: either all the operations in the batch succeed or none is applied -- efficiency: the whole batch is signed only once (by the same implicit account), thus it is much more efficient to check, and it requires much less gas -- usability: the batch only increments the counter of the signer account by one; for this reason it is easier for tools to provide sending several operations per block using operation batches than tracking counter changes. - -The list of operations can be obtained with :ref:`this rpc `. +protocols. Each Tezos economic protocol can specify different kinds of +operations, which are described further in detail in +:doc:`./blocks_ops`. + +The semantics of, respectively, operations and blocks is indeed also +dependent on each economic protocol. The :doc:`Validation and +Application` entry explains the internals of *validation* +-- that is, how to determine whether operations and blocks can be +safely be included in the Tezos blockchain -- and *application* -- +that is, how the effects of operations and blocks are taken into +account -- for this economic protocol. .. _protocol_constants: .. _protocol_constants_kathmandu: @@ -121,16 +140,27 @@ The list of operations can be obtained with :ref:`this rpc ` -- parametric constants are defined in the module :package-api:`Constants_parametric_repr ` +- fixed protocol constants are defined in the module + :package-api:`Constants_repr + ` +- parametric constants are defined in the module + :package-api:`Constants_parametric_repr + ` The *values* of protocol constants in any given protocol can be found using specific RPC calls: @@ -140,13 +170,13 @@ The *values* of protocol constants in any given protocol can be found using spec Further documentation of various protocol constants can be found in the subsystems where they conceptually belong. See, for example: -- :ref:`proof-of-stake parameters `. -- :ref:`consensus-related parameters ` -- :ref:`randomness generation parameters `. +- :ref:`proof-of-stake parameters `. +- :ref:`consensus-related parameters ` +- :ref:`randomness generation parameters `. See also ~~~~~~~~ -An in-depth description of the inners of a protocol can be found in the blog -post `How to write a Tezos protocol +An in-depth description of the internals of developing a new Tezos +protocol can be found in the blog post: `How to write a Tezos protocol `_. diff --git a/docs/kathmandu/randomness_generation.rst b/docs/kathmandu/randomness_generation.rst index c76a0d323256e80156193c78fdb25b6bd38c7071..eaf9483fa46450acb69242d4d2a2c2b19bbfaaec 100644 --- a/docs/kathmandu/randomness_generation.rst +++ b/docs/kathmandu/randomness_generation.rst @@ -46,6 +46,8 @@ if a malicious participant can make sure she is the last revealer, then she can choose whether to reveal its committed value, effectively choosing between two different predetermined seeds. +.. _vdf_kathmandu: + Verifiable Delay Function ^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -75,6 +77,8 @@ cheaper and based on a weaker security assumption (low order assumption). Protocol -------- +.. _randomness_generation_kathmandu: + Randomness generation overview ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/docs/kathmandu/validation.rst b/docs/kathmandu/validation.rst new file mode 100644 index 0000000000000000000000000000000000000000..d77fb96c5f7849d6690cd015079f4114d418f681 --- /dev/null +++ b/docs/kathmandu/validation.rst @@ -0,0 +1,506 @@ +========================== +Validation and Application +========================== + +The :doc:`economic protocol` is responsible for providing +the rules that govern the Tezos network, and for enforcing that these +rules implement a correct blockchain protocol. However, it does so +:ref:`in coordination with a Tezos shell`, who +ultimately implements these rules on its behalf. To this end, a Tezos +economic protocol must provide the shell with an interface enabling +roughly the following functionalities: + +- deciding whether an operation is *valid*, and thus can be safely + included into a new block in the blockchain; + +- deciding whether a new block is *valid*, and thus can be safely + appended to the blockchain; + +- including an operation in a block, and executing it on the + blockchain state, effectively modifying the ledger state; and, + +- appending a new block to a Tezos blockchain, and computing the + updated ledger state. + +From a higher-level, *abstract* perspective, the validation system in +the Tezos protocol implements this business logic in a functional, +state-passing machine where: + +- Its state is given by the :ref:`context`, the internal + representation of the state of the Tezos ledger at a given blockchain + level. For instance, the context contains the information of all + activated accounts and contracts, and their balances. More + generally, the context must provide enough information to determine + the validity of operations, and blocks. + +- The *apply_operation* method determines whether an operation is safe + to be executed in a given context. If so, it proceeds to execute it + and outputs the context resulting from the applied operation's + effects. + +- The *apply* method takes as input a block and a context, determines + whether the block can be safely and correctly appended to the + current head of the chain. If so, it appends the block to the chain + and outputs the resulting context, reflecting the state of the + ledger after the block has successfully been applied. *apply* relies + on (i.e., it should call) *apply_operation* to validate and apply + each operation in the block, and compute intermediate states. + +However, the *concrete* API exported from the Tezos economic protocol +does not implement this business logic *monolithically*, as described +above, but it rather presents a more fine-grained API. The rationale +is to provide specialized variations of the core *validation* and +*application* functionality, dubbed :ref:`Validation +modes`. For example, these modes enable the +protocol to distinguish operations "in the mempool", whose validation +is triggered by the :doc:`prevalidator<../shell/prevalidation>`, from +operations included in newly received blocks, whose validation is +triggered by the :ref:`block validator`, in order to +localize validation rules as needed. The resulting concrete API is +specified by the :package-api:`Protocol +` +module in the :doc:`protocol +environment<../shell/protocol_environment>` ``V6``, and it is +implemented by this protocol in the +:package-api:`Main` +module. + +The rest of this document is organized as follows: we first describe +the different validation modes implemented by this Tezos economic +protocol, and then we delve deeper into the particulars of validation +and application for blocks and the operations supported. + +.. _validation_modes_kathmandu: + +Validation modes +================ + +The Tezos protocol provides different validation modes, intended to be +used by Tezos *shell* and *baker* software implementations when +needing to apply (or to assert the validity) of blocks and operations +under different, or specialized, circumstances -- for example, in +order to *bake* a block. For each of these validation modes, the API +specified by the protocol environment offers an entry point so that +protocol-agnostic components, the Octez shell for instance, are able +to use these different modes. + +.. _full_application_kathmandu: + +Full Application +~~~~~~~~~~~~~~~~ + +The ``Full application`` mode is intended to be used to *fully* +validate and apply blocks. In particular, this mode is used to +validate and apply a **known** block, with a known operation trace. A +Tezos shell implementation should use the full application mode to +decide whether an incoming block can be safely included in the +blockchain. That is, all validity checks are enabled: the block's +signature is correct, and **all** operations included in the block are +valid; the correct amount of consensus operations have been included +in order to satisfy the consensus' threshold, etc. + +.. _full_construction_kathmandu: + +Full Construction +~~~~~~~~~~~~~~~~~ + +The ``Full construction`` mode is intended to be used when a +*delegate* is trying to bake a block and therefore needs to filter the +validity of the desired operation trace, to include only valid +operations. This mode is mostly similar to the ``Full application`` +mode except that *some* global block validity checks are disabled, and +consensus operations are validated with slightly different +preconditions. For instance, since a delegate cannot sign a block +while it is being built, the signature check is disabled, and it will +be left to the baker to correctly sign the resulting block after its +construction is finalized. + +In Octez, this mode is mainly used by the baker daemon. + +.. _partial_construction_kathmandu: + +Partial Construction +~~~~~~~~~~~~~~~~~~~~ + +The ``Partial construction`` mode, also known as ``Mempool mode`` is +used by the :doc:`prevalidator component<../shell/prevalidation>` of +an Octez node to validate incoming operations -- that is, those +not-yet included into blocks. This mode's business-logic is very close +to the ``Full construction`` mode, and the differences boil down to +the intended usage. The partial construction mode does not try to +fully bake a block, but rather to inform the Octez prevalidator on the +potential validity of operations (and whether they can safely included +into a block), so that the latter can **classify** incoming +operations, and further decide how to process them accordingly. + +.. _protocol_classification_kathmandu: + +The protocol provides the shell with the following classification of +an operation, consisting of one valid kind -- ``Applied`` --, and +:ref:`four error kinds ` defined by the +protocol environment: + +- ``Applied``: the operation is valid and can be included in a + potential block in the current context. + +- ``Temporary``: the operation is invalid in the current context, but + it could *later* become valid -- in the context associated to a + successor block of the current head. For instance, a manager + operation whose counter value is greater than the one expected (a + *"counter-in-the-future"* error), or the manager's balance is + insufficient to pay the operation's fees, etc. + +- ``Branch``: the operation is invalid in the current context and in + any possible context from its future successors, but it might still + be valid in an alternative branch. For example: a manager operation + with a smaller counter than the one expected (a + *"counter-in-the-past"* error), an unexpected endorsement for the + current level, etc. + +- ``Permanent``: the operation is invalid in the current context, and + there isn't any plausible context where it might be or become + valid. For example, an operation carrying an invalid signature. + +- ``Outdated``: the operation is *too old* to be included in a + block. Furthermore, there might be still some value in the + information provided by an ``Outdated`` operation. An example is the + case of an endorsement which was received *too late*, but that could + still be used to form a consensus quorum. + +.. _partial_application_kathmandu: + +Partial Application +~~~~~~~~~~~~~~~~~~~ + +The ``Partial application`` mode is used for :ref:`multi-pass +validation`. Its aim is to provide Tezos shell +implementations with a light-weight (read "fast") block application +mechanism, which can determine whether a block has a *chance* of being +valid or not, in a situation when the provided context is *not a +recent one*. That is, when the block candidate succeeds neither the +head of the chain, nor a close ancestor. + +This validation mode is typically used when the node receives a +significantly large branch -- for instance, while bootstrapping. To +check whether this branch is plausibly valid or potentially malicious +spam, the shell retrieves the context from the most recent common +ancestor between its current head and the announced branch, and +proceeds to "partially apply" each block of this branch using the +common ancestor's context. + +Indeed, by relying on the ancestor context, this mode can *only* +assert the validity of consensus-related preconditions (endorsing +power, block fitness, etc.), as future consensus slots are known in +advance -- how much in advance being specified by the +```` protocol constant. Thus, the `Partial +application` mode provides an over-approximation of the branch's +validity, and as a result intermediate results are not committed on +disk in order to prevent potential attacks. + +.. _block_validation_overview_kathmandu: + +Block Validation +================ + +The validity of a blocks depends on a set of precondition checks +implemented in different steps, which happen at different stages of +the application (and the construction) of a block. + +The first step in the process is to decide whether a candidate block +is *well-formed*, that is, that it has the expected "shape" of a valid +block under the current Tezos economic protocol. Given a block +candidate, the block validation process will then verify that the +candidate block declares consistent :ref:`level`, +:ref:`round`, and timestamp values; that it carries a valid +signature, etc. At this step, the block validation process will also +initialize the data-structures required for subsequent steps. + +The second step iterates over the block's operations and proceeds to +apply them sequentially. When at least one operation is found to be +invalid, under the conditions described in +:ref:`operation_validity_alpha` further below, the whole block is +considered as invalid. + +The last step in the block validation process, known as "block +finalization", aims to verify that the collected consensus operations +constitute a sufficiently large :ref:`quorum`. That is, +it will verify that the total endorsing power present in the block is +greater than the ``CONSENSUS_THRESHOLD`` constant. + +This sequence of three steps also yields a new context -- the +resulting state of the Tezos ledger after the application of the +candidate block. The shell may decide to commit this context to disk. + +The Tezos economic protocol also offers a cheap (read "faster") +alternative to determine an over-approximation of the validity of a +block (see :ref:`partial_application_kathmandu` above). This feature +allows the shell to propagate blocks faster without needing to fully +validate them, speeding-up block propagation over the network. Of +course, as this is an over-approximation, this feature cannot be +considered to provide a safe guarantee that a block will be valid: in +particular, it does not validate all kinds of operations. + +.. _operation_validity_kathmandu: + +Operation Validation and Application +==================================== + +In the Tezos economic protocol, we dissociate the notion of *validity* +from the notion of *applicability* for operations. A valid operation +is an operation that can be included safely in a block without +affecting the block's validity. Applying an operation, on the other +hand, actually performs the operation's side-effects which can be: +registering a new delegate, executing a smart contract, voting for a +new protocol amendment proposal, etc. + +Note that an operation may fail during the application phase, even +though it has been checked as valid. For example, a smart contract +call that exceeds its gas limit can be included in a block even if an +error is raised at run-time. The application (that is, the operation's +side-effects) will not take effect, but fees will nonetheless be taken +from the account submitting the smart contract call. + +Unfortunately, the implementation of these two morally distinct phases +in previous Tezos economic protocols has been entangled within the +``apply_operation`` method. As a result, using the latter method did +not allow in practice to distinguish between invalid and +valid-yet-inapplicable operations, and external *ad hoc* mechanisms +were developed to circumvent this limitation -- see the :ref:`precheck +prevalidator filter` entry. + +This economic protocol implements the first stage of a pipelined +validation discipline which targets to reflect, operationally, this +separation of concerns. However, in this economic protocol, only +manager operations are allowed to fail during the application phase +and yet still be included in a block. + +The explicit conditions for a manager operation to be considered as +valid, are given in the :ref:`manager_operations_validity_alpha` +sub-section below. For the remaining acceptable :ref:`validation +passes`, we provide a quick overview of +their global validity in the sequel. + +.. FIXME tezos/tezos#3921: + + Expand validity and application for other validation classes. + +.. _consensus_operations_validity_kathmandu: + +Validity and Application of Consensus Operations +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The validity and applicability of consensus operation is determined +monolithically on this protocol by ``apply_operation`` method. + +:ref:`Preendorsements and +endorsements` share a common +:ref:`consensus content` -- notably the +delegate's first :ref:`slots`, and the targeted +:ref:`level` and :ref:`round` values. Naturally they +share several preconditions, and the validation process exploits these +common patterns. + +Still, the whole process is nuanced by the validation mode in use, and +the + +The first step in the validation process consists on + +Exploits these common pattern by the differences in treatment of this +cont + +The first step in the validation process of consensus operations +depends on + +First, it attempts to validate the operation's "consensus content" by +checking that the delegate signing the operation has rights for the +proposed level and round values. + +slot, + +level and round values. + +A key difference in the process is that preendorsements arises from +the fact that preendorsements are not intended to be included in +blocks, but are rather an artefact of the implementation of the +Tenderbake consensus algorithm. As a result, pre-endorsements can only +be applied in the Partial Construction (or Mempool) mode. + +1. Validation:validate consensus content: + +(* Validate the 'operation.shell.branch' field of the operation. It + MUST point to the grandfather: the block hash used in the + payload_hash. Otherwise we could produce a preendorsement pointing + to the direct proposal. This preendorsement wouldn't be able to + propagate for a subsequent proposal using it as a locked_round + evidence. *) + +1.1 compute expected consensus content (* The [Alpha_context] is +modified only in [Full_construction] mode when we check a +preendorsement if the [preendorsement_quorum_round] was not set. *) + + Endorsements: need to have an endorsement branch. + + Preendorsements: pre-endorsements cannot appear in full application + mode (they are not included in blocks which are included in the + blockchain ledger). Partial Construction: mempool. they need to + check that there is an expected branch (i.e. they don't target a + future level), + + In Full construction mode: we check if there was a pqc round set, + otherwise we set it. + +1.2 check consensus content +: check level, + - Application/FullConsturction: match provided = expected +: check round, + - +op branch, payload hash. + +1.3 check funds, signature etc. + +Endorsements: depending on application mode (Partial construction) +needs to differentiate parents from grand parents: +- if is_parent_endorsement then validate_grand_parent_endorsement + +Refusals: + +Endorsements: doesn't target locked round; targets different level, +round, branch (grandparent) or payload; incorrect delegate for slot, +or doesn't have locked founds, signature doesn't match expected one, + + assert (not mem(op.slot, state.endorsements_seen)) (* Refused *) + +PreEndorsements: doesn't target locked round; targets different level, +round, branch (parent) or payload; incorrect delegate for slot, +or doesn't have locked founds, signature doesn't match expected one, + +.. _voting_operations_validity_kathmandu: + +Validity and Application of Voting Operations +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. _anonymous_operations_validity_kathmandu: + +Validity and Application of Anonymous Operations +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. _manager_operations_validity_kathmandu: + +Validity of Manager Operations +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +In this sub-section, we explain the conditions for manager operations +(and batches of managers operations) to be considered valid and hence +suitable for inclusion in a block. + + +Validity of Individual Manager Operations +......................................... + +:ref:`Manager operation` are a class of +operations, issued by a single *manager* account which signs the +operation and pays their fees. The different manager operation kinds +share several common fields: + +- ``source``: the public key's hash of the *source* account of the + manager operation -- that is, the *manager*. +- ``fee``: the amount of tez paid to the baker which decides to + include this operation; +- ``counter``: the manager account's counter, incremented each time + this account executes a manager operation, to prevent + replay-attacks. +- ``gas_limit``: the maximum amount of gas that this operation may + consume before failing. +- ``storage_limit``: the maximum amount of storage that this operation + may require before failing. +- ``operation``: the actual operation(s) -- e.g., transfers, + smart-contract calls, originations, delegations, etc. +- ``signature``: the manager's signature used to prove its identity. + +A manager operation is **valid** if and only if all of the following +conditions hold: + +- The operation source's public key has been previously *revealed*, + unless the operation is itself a ``Reveal`` operation. +- The operation's signature is correct with regard to the manager + account's public key. +- The provided ``counter`` value is the expected one for the manager. +- Depending on the operation's kind, the ``gas_limit`` is high enough + to cover the minimal cost of parsing the operation and further + minimal treatment. +- The manager account is solvent to pay the announced fees. + +Validity of Manager Operation Batches +..................................... + +A :ref:`batch` of manager +operations includes one or more manager operations for sequential and +atomic execution. The atomicity property imposes that the validity of +a batch should entail the validity of each individual operation in the +batch, as defined above. However, it also entails some additional +*global* constraints on manager batches. + +For each of the operations present in a batch, the validation process +must check that the individual constraints above are satisfied, *with +the exception of* the signature constraint. Given that the signature +concerns the whole batch, as all operations in the batch are signed by +the same manager, it suffices to verify the signature only once. + +The **global batch validity** constraint for this economic protocol is +defined as the conjunction of the following conditions: + +- When a ``Reveal`` operation is present, **it must only occur once**, + and **it must be placed at the head** of the batch -- that is, the + ``Reveal`` operation must be the first operation in the batch. +- Every operation in the batch should declare the same `source`. +- Each of the individual operation counters must be incremented + correctly and sequentially. +- The sum of each individual operation's declared fees must be lower + than the account's balance. That is, the manager account must be + solvent to pay the announced fees for all the operations in the + batch. + +.. _manager_operations_application_kathmandu: + +Application of Manager Operations +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Once the validity of a manager operation (or, a batch of manager +operations) is established, the protocol proceeds to apply the +operation. This first step in this application phase is to transfer +the operation's fees to the baker that included this operation. Then, +the actual application depends on the operation kind. For instance, +this could be a smart contract execution, enacting a delegation, or +multiple actions executed as a batch. The application of a batch of +manager operations consists of the sequential application of each +operation in the batch, following their inclusion order -- the head of +the batch being the first manager operation being applied. + +The application of each individual manager operation may either +succeed -- and therefore be reported as ``Applied`` --, or indeed fail +with an error. In both cases, the fees are taken and the counter for +the operation's manager is incremented. + +When a manager operation fails, every side-effect which was previously +performed is backtracked. Moreover, the (rest of the) batch has to be +aborted. Thus, depending on the position of the manager operation in +a batch, its failure has to be propagated accordingly: + +- If there were other successfully applied operations in the batch + prior to the offending one, the effect of each of them has to be + reverted, and each of them will be reported as ``Backtracked``. + +- If there were other operations pending application after the + offending one, their application is aborted, and they are reported + as ``Skipped``. + +For example, let's consider a simple batch of three manager operations +``[op1, op2, op3]``, if ``op1`` is successful but ``op2`` fails, the +ticket result for the application of the manager operation batch will +report: + +* ``op1`` -- ``Backtracked``, ```op1`` was applied successfully, but + after ``op2`` failed, the operation was canceled; +* ``op2`` -- ``Failed``, the application of this particular operation failed; +* ``op3`` -- ``Skipped``, this operation was never executed because + ``op2`` had previously failed. diff --git a/docs/lima/blocks_ops.rst b/docs/lima/blocks_ops.rst new file mode 100644 index 0000000000000000000000000000000000000000..71f8c1874bc591d5cd7674bce9af5cd8ee1834ea --- /dev/null +++ b/docs/lima/blocks_ops.rst @@ -0,0 +1,229 @@ +===================== +Blocks and Operations +===================== + +The content of a Tezos block is made up of operations, which implement +and reify different functionalities provided by a Tezos economic +protocol: from reaching consensus on the state of the Tezos +blockchain, to performing smart contract calls and transactions. Each +Tezos economic protocol can specify different kinds of operations. + +This entry describes the operations supported by :doc:`the economic +protocol <./protocol>` that implement *enabled* features -- that is, +those available to end-users on Tezos Mainnet. The complete list of +operations, including those corresponding to features in development +or available only on test networks, is given in the +:package-api:`OCaml Documentation +`. + +.. _validation_passes_lima: + +Validation Passes +~~~~~~~~~~~~~~~~~ + +The different kinds of operations are grouped into classes. Each class +has an associated index, a natural number, also known as a +:ref:`validation pass`. There are currently four classes +of operations: :ref:`consensus `, +:ref:`voting `, +:ref:`anonymous`, and :ref:`manager +operations`. This order also specifies the +:ref:`validation and application` priority of +each of these classes. Consensus operations are considered the highest +priority ones, and manager operations the lowest. + +The current protocol implementation enforces the following invariant: + +- each kind of operation belongs to *at most one* validation pass; +- operations whose kind does not belong to any validation pass cannot + be :ref:`applied`. + +.. FIXME tezos/tezos#3915: + + Failing noops don't fit within any of the validation passes + below. We need to change the structure a bit to be able to list + them here. + +In the sequel, we describe the different classes of operations, and +the different kinds of operations belonging to each class. + +.. _consensus_operations_lima: + +Consensus Operations +~~~~~~~~~~~~~~~~~~~~ + +.. TODO tezos/tezos#4204: document PCQ/PQ + +Consensus operations are administrative operations that are necessary +to implement the :doc:`consensus algorithm`. There are two +kinds of consensus operations, each belonging to the different voting +phases required to agree on the next block. + +- A ``Preendorsement`` operation implements a first vote for a + :ref:`candidate block ` with the aim of + building a :ref:`preendorsement quorum `. + +- An ``Endorsement`` operation implements a vote for a candidate block + for which a preendorsement quourm cerificate (PQC) has been + observed. + +.. _voting_operations_lima: + +Voting Operations +~~~~~~~~~~~~~~~~~ + +Voting operations are operations related to the on-chain :doc:`Tezos +Amendment` process. In this economic protocol, there are two +voting operations: + +- The ``Proposal`` operation enables delegates to submit (also known as + to "inject") protocol amendment proposals, or to up-vote previously + submitted proposals, during the Proposal period. + +- The ``Ballot`` operation enables delegates to participate in the + Exploration and Promotion periods. Delegates use this operation to + vote for (``Yay``), against (``Nay``), or to side with the majority + (``Pass``), when examining a protocol amendment proposal. + +Further details on each operation's implementation and semantics are +provided in the dedicated entry for :ref:`on-chain +governance`. + +.. _anonymous_operations_lima: + +Anonymous Operations +~~~~~~~~~~~~~~~~~~~~ + +This class groups all operations that do not require a signature from +a Tezos account (with an exception, detailed below). They implement +different functionalities of the protocol, and their common +characteristic is that they allow the account originating these +operations to remain anonymous in order to avoid censorship. + +Two operations in this class implement functionality pertaining to the +protocol's :doc:`random seeds generation +mechanism`: + +- The ``Seed_nonce_revelation`` operation allows a baker to + anonymously reveal the nonce seed for the commitment it had included + in a previously baked block (in the previous cycle). + +- The ``Vdf_revelation`` operation allows the submission of a solution + to, and a proof of correctness of, the :ref:`VDF + challenge` corresponding to the VDF revelation period + of the randomness generation protocol. + +Further details on the latter operation's implementation and semantics +are provided in the :ref:`random seed generation +protocol`. + +Three operations in this class are used to :ref:`punish participants +which engage in Byzantine behaviour` -- notably +delegates which :ref:`"double sign" ` blocks, or emit +conflicting :ref:`consensus operations`: + +- The ``Double_preendorsement_evidence`` operation allows for accusing + a delegate of having *double-preendorsed* -- i.e., of having + preendorsed two different block candidates, at the same level and at + the same round. The bulk of the evidence, the two arguments + provided, consists of the two offending preendorsements. + +- Similarly, the ``Double_endorsement_evidence`` operation allows for + accusing a delegate of having *double-endorsed* -- i.e., of having + endorsed two different block candidates at the same level and the + same round -- by providing the two offending endorsements. + +- The ``Double_baking_evidence`` allows for accusing a delegate of + having "double-baked" a block -- i.e., of having signed two + different blocks at the same level and at same round. The bulk of + the evidence consists of the :ref:`block + headers` of each of the two offending blocks. + +See :ref:`here` for further detail on the semantics of +evidence-providing operations. + +The ``Activation`` operation allows users which participated in the +Tezos fundraiser to make their :ref:`accounts ` operational. + +Finally, the ``Drain_delegate`` operation allows an active +consensus-key account, i.e., an account to which a baker delegated its +consensus-signing responsibility, to **empty** its delegate +account. This operation is used as a deterrent to ensure that a +delegate secures its consensus key as much as its manager (or main) +key. + +.. _manager_operations_lima: + +Manager Operations +~~~~~~~~~~~~~~~~~~ + +.. FIXME tezos/tezos#3936: integrate consensus keys operations. + +.. FIXME tezos/tezos#3937: + + Document increased paid storage manager operation. + +Manager operations enable end-users to interact with the Tezos +blockchain -- e.g., transferring funds or calling :doc:`smart +contracts`. A manager operation is issued by a single +*manager* account which signs the operation and pays the +:ref:`fees` to the baker for its inclusion in a block. Indeed, +manager operations are the only fee-paying and +:ref:`gas-consuming` operations. + +- The ``Reveal`` operation reveals the public key of the sending + manager. Knowing this public key is indeed necessary to check the signature + of future operations signed by this manager. +- The ``Transaction`` operation allows users to either transfer tez + between accounts and/or to invoke a smart contract. +- The ``Delegation`` operation allows users to :ref:`delegate their + stake ` to a :ref:`delegate` (a + *baker*), or to register themselves as delegates. +- The ``Update_consensus_key`` operation allows users to delegate the + responsibility of signing blocks and consensus-related operations to + another account. +- The ``Origination`` operation is used to + :ref:`originate`, that is to deploy, smart contracts + in the Tezos blockchain. +- The ``Set_deposits_limit`` operation enables delegates to adjust the + amount of stake a delegate :ref:`has locked in + bonds`. +- Support for registering global constants is implemented with the + ``Register_global_constant`` operation. +- The ``Increase_paid_storage`` operation allows a sender to increase + the paid storage of some previously deployed contract. +- The ``Event`` operation enables sending event-like information to + external applications from Tezos smart contracts -- see + :doc:`Contract Events` for further detail. + +Moreover, all operations necessary to implement Tezos' *enshrined* +Layer 2 solutions into the economic protocol are also manager +operations: + +.. FIXME tezos/tezos#3916: expand documentation of TORU operations. + +- :doc:`Transaction Optimistic Rollups` are + implemented using the following manager operations: + ``Tx_rollup_origination``, ``Tx_rollup_submit_batch``, + ``Tx_rollup_commit``, ``Tx_rollup_return_bond``, + ``Tx_rollup_finalize_commitment``, ``Tx_rollup_remove_commitment``, + ``Tx_rollup_rejection``, ``Tx_rollup_rejection``, + ``Transfer_ticket``. + +.. _manager_operations_batches_lima: + +Manager Operation Batches +""""""""""""""""""""""""" + +Manager operations can be grouped, forming a so-called +**batch**. Batches enable the inclusion of several manager operations +from the same manager in a single block. + +Batches satisfy the following properties: + +- All operations in a batch are issued by the same manager, which + provides a single signature for the entire batch. +- A batch is :ref:`applied` + atomically: all its operations are executed sequentially, without + interleaving other operations. Either all the operations in the + batch succeed, or none is applied. diff --git a/docs/lima/consensus.rst b/docs/lima/consensus.rst index 18d549e21b0c32c1607aac445f920c328745aae3..48ceaf456918758a390e8bb777f0113762591899 100644 --- a/docs/lima/consensus.rst +++ b/docs/lima/consensus.rst @@ -441,6 +441,11 @@ These are a subset of the :ref:`protocol constants `. Shell-protocol interaction revisited ------------------------------------ +.. FIXME tezos/tezos#3914: + + Integrate protocol-specific block parts in the blocks and ops + entry. + :ref:`Recall` that, for the shell to interact with the economic protocol, two notions are defined abstractly at the level of the shell and made concrete at the level of the consensus protocol. Namely, these two notions are the protocol-specific header and the fitness. As in Emmy*, the protocol-specific header contains the fields: diff --git a/docs/lima/glossary.rst b/docs/lima/glossary.rst index 0661d67e7b78de493b5d3e48fb826b982c281775..ddd11a51e20461cbd3d0aef7a551b7ef37f8cbd6 100644 --- a/docs/lima/glossary.rst +++ b/docs/lima/glossary.rst @@ -74,9 +74,13 @@ _`Cycle` A cycle is a set of consecutive blocks. E.g., cycle 12 started at block_ level 49152 and ended at block_ level 53248. - Cycles are used as a unit of “time” in the block_ chain. For example, the - different phases in the amendment voting procedures are defined based on - cycles. + Cycles are used as a unit of “time” in the blockchain. For + example, the different phases in the amendment voting procedures + are defined based on cycles. + + The length of a cycle is a (parametric) protocol + :ref:`constant`, and thus might change across different + Tezos protocols. _`Delegate` An `implicit account`_ to which an account_ has delegated their @@ -92,20 +96,36 @@ _`Delegation` the account_. _`Double signing` - When a baker_ signs two different blocks at the same level and same round, - it is called double baking. Double baking is detrimental to the network and might be - indicative of an attempt to double spend. - The same goes for signing two different endorsements at the same level and the same round. - As such, double signing is punished by the - network: an accuser_ can provide proof of the double signing to be awarded - part of the double signer's deposit. + The action of a baker_ signing two different blocks at the same + level and same round is called *double baking*. Double baking + is detrimental to the network and might be indicative of an + attempt to double spend. The same goes for signing two different + *endorsements* at the same level and the same round. + + Double signing (i.e. double baking or double endorsing) is + punished by the network: an accuser_ can provide proof of the + double signing to be awarded part of the double signer's deposit + -- see :ref:`Slashing`. + +_`Failing Noop` + The ``Failing_noop`` operation implements a *No-op*, which always + fails at :ref:`application time`, and + should never appear in :ref:`applied + blocks`. This operation allows end-users to + :ref:`sign arbitrary messages` which have no + computational semantics. _`Fee` - To ensure responsible use of computation resources of other nodes, and also to encourage active participation in the consensus protocol, there are some - fees that users pay to bakers for including their operations in blocks. - For example, fees are paid to a baker for operations such as a transaction_ or a revelation of a public key. + To ensure responsible use of computation resources of other + nodes, and also to encourage active participation in the consensus + protocol, users pay fees to bakers for including (some of) their + operations in blocks. For example, fees are paid to a baker for + operations such as a transaction_ or a revelation of a public key. + + Currently, only :ref:`manager operations` + require collecting fees from its sender account_. - See also `burn`_. + See also `burn`_. _`Gas` A measure of the number of elementary operations_ performed during @@ -117,7 +137,7 @@ _`Implicit account` contract`_, an `Implicit account`_ cannot include a script and it cannot reject incoming transactions. - If registered, an `implicit account`_ can act as a delegate_. + If *registered*, an `implicit account`_ can act as a delegate_. The address of an `implicit account`_ always starts with the letters `tz` followed by `1`, `2` or `3` (depending on the @@ -161,7 +181,8 @@ _`Originated account` See `smart contract`_. _`Origination` - An operation_ to create a `smart contract`_. + A manager operation_ whose purpose is to create -- that + is, to deploy -- a `smart contract`_ on the Tezos blockchain. _`Round` An attempt to reach consensus on a block at a given level. @@ -175,10 +196,11 @@ _`Roll` deprecated; see `Minimal stake`_. _`Smart contract` - Account_ which is associated to a :ref:`Michelson ` script. They are - created with an explicit origination_ operation and are therefore - sometimes called originated accounts. The address of a smart - contract always starts with the letters ``KT1``. + Account_ which is associated to a :ref:`Michelson + ` script. They are created with an + explicit origination_ operation and are therefore sometimes called + originated accounts. The address of a smart contract always starts + with the letters ``KT1``. _`Smart Optimistic Rollups` Smart optimistic rollups constitute a `layer 2`_ solution that can be used to deploy either a general-purpose polyvalent layer 2 blockchain @@ -189,6 +211,13 @@ _`Transaction` An operation_ to transfer tez between two accounts, or to run the code of a `smart contract`_. +_`Validation pass` + An index (a natural number) associated with a particular kind of + operations, allowing to group them into classes. Validation passes + enable prioritizing the :ref:`validation and + application` of certain classes of + operations. + _`Voting period` Any of the ``proposal``, ``exploration``, ``cooldown``, ``promotion`` or ``adoption`` stages in the voting procedure when diff --git a/docs/lima/plugins.rst b/docs/lima/plugins.rst index 3972ee212532b2f41103cd1189ffbda64fca30af..6027fc72b44c9052e9fcafa652c026c804b366d6 100644 --- a/docs/lima/plugins.rst +++ b/docs/lima/plugins.rst @@ -102,13 +102,21 @@ This filtering strategy is implemented in the ``prefilter`` (see Prechecking of manager operations ................................. +.. FIXME tezos/tezos#3938: + + This section doesn't make much sense after the pipelining project + has plugged validate into the plugin for Lima. Parts of this + section be integrated into plugin.rst, and the relevant definitions + should point to the validation entry. + The aim of the ``precheck`` filter is to avoid fully executing manager operations before deciding whether to gossip them to the network. The detailed description of this feature is given in :doc:`./precheck`. For operations other than manager operations, the -``precheck`` filter is a no-op, which entails that these operations need to be -fully executed to decide their propagation (see :doc:`../shell/prevalidation`). +``precheck`` filter is a no-op, which entails that these operations +need to be fully executed to decide their propagation (see +:doc:`../shell/prevalidation`). One manager operation per manager per block @@ -120,11 +128,6 @@ increased the chain's fitness), only one operation per manager is propagated. All other received operations originating from the same manager will be classified as ``Branch_delayed`` and will not be propagated. -This criterion is used only by the prevalidator to decide the propagation of -operations. A baker can still include several operations originating from the same -manager in a single block, provided that it gets them in time (note that they can be -propagated by nodes using different versions or implementations). - Alternatively, a user can inject an operation with the same manager and the same counter, but with a higher fee to replace an already existing operation in the prevalidator. Only one of the two operations will be eventually diff --git a/docs/lima/precheck.rst b/docs/lima/precheck.rst index c65cd5f03c3fabc1b962c57df5a5b61a730d3bc7..5ea3b537e792b18b46e9b682229166c9829c079a 100644 --- a/docs/lima/precheck.rst +++ b/docs/lima/precheck.rst @@ -1,6 +1,13 @@ Prechecking of manager operations ================================= +.. FIXME tezos/tezos#3938: + + This section doesn't make much sense after the pipelining project + has plugged validate into the plugin for Lima. Parts of this + section be integrated into plugin.rst, and the relevant definitions + should point to the validation entry. + The prevalidator of Octez prevents the propagation of non-valid operations by trying to apply (or execute) them. However, executing diff --git a/docs/lima/protocol.rst b/docs/lima/protocol.rst index 1e263d2cb0458e77bdef2bfd3bc597c72d81f7a5..57a36ccc1b4ae5d27aa1c1976c1e3ae872799c94 100644 --- a/docs/lima/protocol.rst +++ b/docs/lima/protocol.rst @@ -83,5 +83,15 @@ Sapling, etc), and some details about its implementation. .. toctree:: :maxdepth: 2 - + event + +.. toctree:: + :maxdepth: 2 + + blocks_ops + +.. toctree:: + :maxdepth: 2 + + validation diff --git a/docs/lima/protocol_overview.rst b/docs/lima/protocol_overview.rst index 03e679e73f8a3fbea5750829186d6e56ff60b534..9182a7496b464fbc957f91cdba8e025bfa84ca8d 100644 --- a/docs/lima/protocol_overview.rst +++ b/docs/lima/protocol_overview.rst @@ -37,97 +37,128 @@ different implementations, and this is important, for instance because different to implement different transaction selection strategies. Tezos is a self-amending blockchain, in that a large part of Tezos can be -changed through a so-called amendement procedure. To this end, as mentioned in -:doc:`the big picture<../shell/the_big_picture>`, a Tezos node consists of two +changed through a so-called amendment procedure. To this end, as mentioned in +:ref:`the big picture`, a Tezos node consists of two components: - the shell, which comprises the network and storage layer, and embeds - the economic protocol component, which is the part that can be changed through amendment. -The role of the protocol -~~~~~~~~~~~~~~~~~~~~~~~~ +The role of the economic protocol +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. FIXME tezos/tezos#3921: + + Update for pipelined validation up to Lima. At a very high level, a protocol must: -- implement protocol-specific types, such as the type of operations or protocol-specific block header data (in addition to the shell generic header), -- define under which conditions a block is a valid extension of the current blockchain, and define an ordering on blocks to arbitrate between concurrent extensions. +- implement protocol-specific types, such as the type of operations or + protocol-specific block header data (in addition to the shell + generic header), + +- define under which conditions a block is a valid extension of the + current blockchain, and define an ordering on blocks to arbitrate + between concurrent extensions. -Validity conditions are implemented in the ``apply`` function which is called -whenever the node processes a block. The ``apply`` function takes as arguments a -*context* and a block. The context represents the *protocol state* and is -therefore protocol specific. The context may contain, for instance, a list of -accounts and their balances. More generally, the context must provide enough -information to determine the validity of a block. Given a context and a block, -the ``apply`` function returns the updated context if the block is valid and has -a higher :ref:`fitness`. The fitness determines a total ordering between blocks. +Validity conditions are implemented in the ``apply`` function which is +called whenever the node processes a block---see the dedicated +:doc:`protocol validation and operation` entry for further +detail into the validation and application process for +:ref:`blocks` and their +:ref:`operations`. .. _shell_proto_interact_lima: Shell-protocol interaction ~~~~~~~~~~~~~~~~~~~~~~~~~~ -:doc:`Recall<../shell/the_big_picture>` that the economic protocol and the shell interact in order to ensure that the blocks being appended to the blockchain are valid. There are mainly two rules that the shell uses when receiving a new block: - -- 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 :package-api:`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 -~~~~~~ +In the Tezos :ref:`architecture`, the economic +protocol and the shell interact in order to ensure that the blocks +being appended to the blockchain are valid. There are mainly two rules +that the shell uses when receiving a new block: + +- 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 it has a higher + fitness than the current head; a block is + :ref:`valid` only if all the + operations included are also + :ref:`valid`. + +The support provided by the protocol for validating blocks can be +modulated by different :ref:`validation +modes`. They allow using this same +interface for quite different use cases, as follows: + +- being able to :ref:`apply` a block, + typically used by the shell's :doc:`validator <../shell/validation>` + component; +- being able to :ref:`construct` a block, + typically used by the baker daemon to *bake* -- that is, to produce + -- a new block; +- being able to :ref:`partially construct` + a block, typically used by the :doc:`prevalidator + <../shell/prevalidation>` to determine valid operations in the + mempool; and, +- being able to :ref:`pre-apply` a + block, typically used in the :doc:`validator <../shell/validation>` + to precheck a block, avoiding to further consider invalid blocks. + +.. _block_contents_lima: + +Blocks, Operations and their Validation +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. tezos/tezos#3914: + + Integrate protocol-specific block parts in the blocks and ops + entry. A block consists of a header and operations. A block's header is composed of two parts: :ref:`the protocol-agnostic part` -and :ref:`the protocol-specific part`. -This separation enables the shell to interact with different -protocols. - -.. _validation_passes_lima: - -Operations & Validation Passes -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The different kinds of operations are grouped in classes, such that operations belonging to different classes may be validated independently, and/or with different priorities. -Each class has an associated index, called a :ref:`validation pass`. -There are four classes of operations: :doc:`consensus ` operations, :doc:`voting ` operations, anonymous operations, manager operations. - -Consensus operations are endorsements, while `voting ` operations are ballot and proposal. - -Anonymous operations are operations which are not signed. There are three anonymous operations: seed nonce revelation, double baking evidence, and double endorsing evidence. The evidence for double baking and double endorsing is included in a block by the so-called accuser (see :ref:`slashing`). - -Manager operations are activation, origination (see :doc:`smart contracts`), transaction, reveal, and delegation (see :doc:`proof of stake `). Manager operations are the only fee-paying operations. - -Recall that users have associated :ref:`accounts ` which they activate before being able to participate. By means of the operation :ref:`origination`, accounts can be further associated with smart contracts in which they are called :ref:`originated accounts`. :ref:`Transactions` are used to either transfer tez between two accounts or run the code of a smart contract. Transactions are signed by an account's private key. Before making a transaction, a user must reveal her public key so that other users (not being aware of this public key) can effectively check the signature of the transaction. - -Manager operations can be grouped into batches forming a so-called group operation. A group operation satisfies: - -- atomicity: either all the operations in the batch succeed or none is applied -- efficiency: the whole batch is signed only once (by the same implicit account), thus it is much more efficient to check, and it requires much less gas -- usability: the batch only increments the counter of the signer account by one; for this reason it is easier for tools to provide sending several operations per block using operation batches than tracking counter changes. - -The list of operations can be obtained with :ref:`this rpc `. +and :ref:`the protocol-specific part`. This +separation enables the shell to interact with different +protocols. Each Tezos economic protocol can specify different kinds of +operations, which are described further in detail in +:doc:`./blocks_ops`. + +The semantics of, respectively, operations and blocks is indeed also +dependent on each economic protocol. The :doc:`Validation and +Application` entry explains the internals of *validation* +-- that is, how to determine whether operations and blocks can be +safely be included in the Tezos blockchain -- and *application* -- +that is, how the effects of operations and blocks are taken into +account -- for this economic protocol. .. _protocol_constants_lima: Protocol constants ~~~~~~~~~~~~~~~~~~ -Protocols are tuned by several *protocol constants*, such as the size of a nonce, or the number of blocks per cycle. -One can distinguish two kinds of protocol constants: +Protocols are tuned by several *protocol constants*, such as the size +of a nonce, or the number of blocks per cycle. One can distinguish two +kinds of protocol constants: -- *fixed* protocol constants, such as the size of a nonce, are values wired in the code of a protocol, and can only be changed by protocol amendment (that is, by adopting a new protocol) -- *parametric* protocol constants, such as the number of blocks per cycle, are values maintained in a read-only data structure that can be instantiated differently, for the same protocol, from one network to another (for instance, test networks move faster). +- *fixed* protocol constants, such as the size of a nonce, are values + wired in the code of a protocol, and can only be changed by protocol + amendment (that is, by adopting a new protocol) +- *parametric* protocol constants, such as the number of blocks per + cycle, are values maintained in a read-only data structure that can + be instantiated differently, for the same protocol, from one network + to another (for instance, test networks move faster). The *list* of protocol constants can be found in the OCaml APIs: -- fixed protocol constants are defined in the module :package-api:`Constants_repr ` -- parametric constants are defined in the module :package-api:`Constants_parametric_repr ` +- fixed protocol constants are defined in the module + :package-api:`Constants_repr + ` +- parametric constants are defined in the module :package-api:`Constants_parametric_repr ` The *values* of protocol constants in any given protocol can be found using specific RPC calls: @@ -144,6 +175,6 @@ See, for example: See also ~~~~~~~~ -An in-depth description of the inners of a protocol can be found in the blog -post `How to write a Tezos protocol +An in-depth description of the internals of developing a new Tezos +protocol can be found in the blog post: `How to write a Tezos protocol `_. diff --git a/docs/lima/randomness_generation.rst b/docs/lima/randomness_generation.rst index d340bd043edbff3bf4ebbf7036a491c5e83f5d0d..1b91f6b56fabaa331ebbd1d122457ff9cc5bdb3a 100644 --- a/docs/lima/randomness_generation.rst +++ b/docs/lima/randomness_generation.rst @@ -46,6 +46,8 @@ if a malicious participant can make sure she is the last revealer, then she can choose whether to reveal its committed value, effectively choosing between two different predetermined seeds. +.. _vdf_lima: + Verifiable Delay Function ^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -75,6 +77,8 @@ cheaper and based on a weaker security assumption (low order assumption). Protocol -------- +.. _randomness_generation_lima: + Randomness generation overview ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/docs/lima/validation.rst b/docs/lima/validation.rst new file mode 100644 index 0000000000000000000000000000000000000000..6d3c838a661977ef1c3f35d5f92b6e88592f0aac --- /dev/null +++ b/docs/lima/validation.rst @@ -0,0 +1,420 @@ +========================== +Validation and Application +========================== + +.. FIXME tezos/tezos#3921: + + Adapt to pipelined validation up to Lima and v7 environment + +The :doc:`economic protocol` is responsible for +providing the rules that govern the Tezos network, and for enforcing +that this rules implement a correct blockchain protocol. However, it +does so :ref:`in coordination with a Tezos shell`, +who ultimately implements these rules on its behalf. To this end, a +Tezos economic protocol must provide the shell with an interface +enabling roughly the following functionalities: + + - deciding whether an operations is *valid*, and thus can be safely + included in a new block in the blockchain; + + - deciding whether a new block is *valid*, and thus it can be safely + appended to the blockchain; + + - including an operation in a block, and executing it on the + blockchain state, effectively modifying the ledger state; and, + + - appending a new block to a Tezos blockchain, and computing the + updated ledger state. + +From a higher-level, *abstract* perspective, the validation system in +the Tezos protocol implements this business logic in a functional, +state-passing machine where: + +- Its state is given by the :ref:`context`, the internal + representation of the state of Tezos ledger at a given blockchain + level. For instance, the context contains the information of all + activated accounts and contracts, and their balances. More + generally, the context must provide enough information to determine + the validity of operations, and blocks. + +- The *apply_operation* method determines whether an operation is safe + to be executed in a given context. If so, it proceeds to execute it + and outputs the context resulting from the applied operation's + effects. + +- The *apply* method takes as input a block and a context, determines + whether the block can be safely and correctly appended to the + current head of the chain. If so, it appends the block to the chain + and outputs a the resulting context, reflecting the state of the + ledger after the block has successfully been applied. *apply* relies + on (i.e., it should call) *apply_operation* to validate and apply + each operation in the block, and compute intermediate states. + +However, the *concrete* API exported from the Tezos economic protocol +does not implement this business logic *monolithically*, as described +above, but it rather presents a more fine-grained API. The rationale +is to provide specialized variations of the core *validation* and +*application* functionality, dubbed :ref:`Validation +modes`. For example, these modes enable the +protocol to distinguish operations "in the mempool", whose validation +is triggered by the :doc:`prevalidator<../shell/prevalidation>`, from +operations included in newly received blocks, whose validation is +triggered by the :ref:`block validator`, in order to +localize validation rules as needed. The resulting concrete API is +specified by the :package-api:`Protocol +` +module in the :doc:`protocol +environment<../shell/protocol_environment>` ``V7``, and it is +implemented by this protocol in the +:package-api:`Main` +module. + +The rest of this document is organized as follows: we first describe +the different validation modes implemented by this Tezos economic +protocol, and then we delve deeper into the particulars of the validation and application of blocks and the operations supported. + +.. _validation_modes_lima: + +Validation modes +================ + +The Tezos protocol provides different validation modes, intended to be +used by Tezos *shell* and *baker* software implementations when +needing to apply (or to assert the validity) of blocks and operations +under different, or specialized, circumstances -- for example, in +order to *bake* a block. For each of these validation modes, the API +specified by the protocol environment offers an entry-point so that +protocol agnostic components, the Octez shell for instance, are able +to use these different modes. + +.. _full_application_lima: + +Full Application +~~~~~~~~~~~~~~~~ + +The ``Full application`` mode is intended to be used to *fully* +validate and apply blocks. In particular, this mode is used to +validate and apply a **known** block, with a known operation trace. A +Tezos shell implementation should use the full application mode to +decide whether an incoming block can be safely included in the +blockchain. Thus, all validity checks are enabled: the block's +signature is correct, and **all** operations included in the block are +valid; the correct amount of consensus operations have been included +in order to satisfy the consensus' threshold, etc. + +.. _full_construction_lima: + +Full Construction +~~~~~~~~~~~~~~~~~ + +The ``Full construction`` mode is intended to be used when a +*delegate* is trying to bake a block and therefore needs to filter the +validity of the desired operation trace, to include only valid +operations. This mode is mostly similar to the ``Full application`` +mode except that *some* global block validity checks are disabled, and +consensus operations are validated with slightly different +preconditions. For instance, since a delegate cannot sign a block +while it is being built, the signature check is disabled, and it will +be left to the baker to correctly sign the resulting block after its +construction is finalized. + +In Octez, this mode is mainly used by the baker daemon. + +.. _partial_construction_lima: + +Partial Construction +~~~~~~~~~~~~~~~~~~~~ + +The ``Partial construction`` mode, also known as ``Mempool mode`` is +used by the :doc:`prevalidator component<../shell/prevalidation>` of +an Octez node to validate incoming operations -- that is, those +not-yet included into blocks. This mode's business-logic is very close +to the ``Full construction`` mode, and the differences boil down to +the intended usage. The partial construction mode does not try to +fully bake a block, but rather to inform the Octez prevalidator on the +potential validity of operations (and whether they can safely included +into a block), so that the later can **classify** incoming operations, +and further decide how to process them accordingly. + +.. _protocol_classification_lima: + +The protocol provides the shell with the following classification of +an operation, consisting of one valid kind -- ``Applied`` --, and +:ref:`four error category kinds ` defined +by the protocol environment: + +- ``Applied``: the operation is valid and can be included in a + potential block in the current context. + +- ``Temporary``: the operation is invalid in the current context, but + it could *later* become valid -- in the context associated to a + successor of the current head. For instance, a manager operation + whose counter value is greater than the one expected (a + *"counter-in-the-future"* error), or the manager's balance is + insufficient to pay the operation's fees, etc. + +- ``Branch``: the operation is invalid in the current context and in + all possible context from its future successors, but it might still + be valid in an alternative branch. For example: a manager operation + with a smaller counter than the one expected (a + *"counter-in-the-past"* error), an unexpected endorsement for the + current level, etc. + +- ``Permanent``: the operation is invalid in the current context, + and there isn't any plausible context where it might become + valid. For example, an operation carrying an invalid signature. + +- ``Outdated``: the operation is *too old* to be included in a + block. Furthermore, there might be still some value in the + information provided by an ``Outdated`` operation. An example is the + case of an endorsement which was received *too late*, but that could + still be used to form a consensus quorum. + +.. _partial_application_lima: + +Partial Application +~~~~~~~~~~~~~~~~~~~ + +The ``Partial application`` mode is used for :ref:`multi-pass +validation`. Its aim is to provide Tezos shell +implementations with a light-weight (read, fast) block application +mechanism, which can determine whether a block has a *chance* of being +valid or not, in a situation when the provided context is *not a +recent one*. That is, when the block candidate succeeds neither the +head of the chain, nor a close ancestor. + +This is validation mode is typically used when the node receives a +significantly large branch -- for instance, while bootstrapping. To +check whether this branch is plausibly valid or potentially malicious +spam, the shell retrieves the context from the most recent common +ancestor between its current head and the announced branch, and +proceeds to "partially apply" each block of this branch using the +common ancestor's context. + +Indeed, by relying on the ancestor context, this mode can *only* +assert the validity of consensus-related preconditions (endorsing +power, block fitness, etc.), as future consensus slots are known in +advance -- how much in advance being specified by +the ```` protocol constant. Thus, the `Partial +application` modes provides an over-approximation of the branch's +validity, and as a result intermediate results are not committed on +disk in order to prevent potential attacks. + +.. _block_validation_overview_lima: + +Block Validation +================ + +.. FIXME tezos/tezos#3921: + + Adapt to pipelined block validation up to Lima and v7 environment. + +The validity of a blocks depends on a set of precondition checks +implemented in different steps, which happen at different stages of +the application (and the construction) of a block. + +The first step in the process is to decide whether a candidate block +is *well-formed*, that is, that it has the expected "shape" of a valid +block under the current Tezos economic protocol. Given a block +candidate, the block validation process will then verify that the +candidate block declares consistent :ref:`level`, +:ref:`round`, and timestamp values; that it carries a valid +signature, etc. At this step, the block validation process will also +initialize the data-structures required for subsequent steps. + +The second step iterates over the block's operations and proceeds to +apply them sequentially. When at least one operation is found to be +invalid, under the conditions described in +:ref:`operation_validity_lima` further below, the whole block is +considered as invalid. + +The last step in the block validation process, known as "block +finalization", aims to verify that the collected consensus operations +constitute a sufficiently large :ref:`quorum`. That is, +it will verify that the total endorsing power present in the block is +greater than the ``CONSENSUS_THRESHOLD`` constant. + +This last step also yields a new context -- the resulting state of the +Tezos ledger after the application of the candidate block. The shell +may decide to commit this context to disk. + +The Tezos economic protocol also offers a cheap (read "faster") +alternative to determine an over-approximation of the validity of a +block (see :ref:`partial_application_lima` above). This feature +allows the shell to propagate blocks faster without needing to fully +validate them, speeding-up block propagation over the network. As this +is an over-approximation, this feature cannot be considered to provide +a safe guarantee that a block will be valid: in particular, it does +not validate all kinds of operations. + +.. _operation_validity_lima: + +Operation Validation and Application +==================================== + +In the Tezos economic protocol, we dissociate the notion of *validity* +from the notion of *applicability* for operations. A valid operation +is an operation that can be included safely in a block without +affecting the block's validity. Applying an operation, on the other +hand, actually performs the operation's side-effects which can be: +registering to a new delegate, executing a smart contract, voting for +a new protocol amendment proposal, etc. + +While an operation may fail during the application phase, it could +still be considered as valid. For example, a smart contract call that +exceeds its gas limit can be included in a block even if an error is +raised at run-time. The application (that is, the operation's +side-effects) will not take effect, but fees will nonetheless be taken +from the account submitting the smart contract call. + +.. FIXME tezos/tezos#3921: + + Adapt to pipelined validation up to Lima and v7 environment: add + validity and application for other validation classes. + + .. _consensus_operations_validity_lima: + +Validity and Application of Consensus Operations +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. FIXME tezos/tezos#3921: + + Adapt to pipelined validation up to Lima and v7 environment. + +.. _voting_operations_validity_lima: + +Validity and Application of Voting Operations +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. FIXME tezos/tezos#3921: + + Adapt to pipelined validation up to Lima and v7 environment. + +.. _anonymous_operations_validity_lima: + +Validity and Application of Anonymous Operations +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. FIXME tezos/tezos#3921: + + Adapt to pipelined validation up to Lima and v7 environment. + +Validity of Manager Operations +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +In this sub-section, we explain the conditions for manager operations +(and batches of managers operations) to be considered valid and hence +includible in a block. + +Validity of Individual Manager Operations +......................................... + +:ref:`Manager operation` are a class of +operations, issued by a single *manager* account which signs the +operation and pays their fees. The different manager operation kinds +share several common fields: + +- ``source``: the public key's hash of the *source* account of the + manager operation -- that is, the *manager*. +- ``fee``: the amount of tez paid to the baker which decides to + include this operation; +- ``counter``: the manager account's counter, incremented each time + this account executes a manager operation, to prevent + replay-attacks. +- ``gas_limit``: the maximum amount of gas that this operation may + consume before failing. +- ``storage_limit``: the maximum amount of storage that this operation + may require before failing. +- ``operation``: the actual operation(s) -- e.g., transfers, + smart-contract calls, originations, delegations, etc. +- ``signature``: the manager's signature used to prove its identity. + +A manager operation is **valid** if and only if all of the following +conditions hold: + +- The operation source's public key has been previously *revealed*, + unless the operation is itself is a ``Reveal`` operation. +- The operation's signature is correct with regard to the manager + account's public key. +- The provided ``counter`` value is the expected one for the manager. +- Depending on the operation's kind, the ``gas_limit`` is high enough + to cover the minimal cost of the parsing the operation and further + minimal treatment. +- The manager account is solvent enough to be able to pay the + announced fees. + +Validity of Manager Operation Batches +..................................... + +A :ref:`batch` of manager +operations includes one or more manager operations for sequential and +atomic execution. The atomicity property imposes that the validity of +a batch should entail the validity of each individual operation in the +batch. As a result, the validity of a batch entails the lifting of the +individual validity defined above, and additional *global* constraints +on manager batches. + +For each of the operations present in a batch, the validation process +must check that the individual constraints above are satisfied, *with +the exception of* the signature constraint. Given that the signature +concerns the whole batch, as all operations in the batch are signed by +the same manager, it suffices to verify the signature only once. + +The **global batch validity** constraint for this economic protocol is +defined as the conjunction of the following conditions: + +- When a ``Reveal`` operation is present, **it must only occur once**, + and **it must be placed at the head** of the batch -- that is, the + ``Reveal`` operation must be the first operation in the batch. +- Every operation in the batch should declare the same `source`. +- Each of the individual operation counters must be incremented + correctly and sequentially. +- The sum of each individual operation's declared fees must be lower + than the account's balance. That is, the manager account must be + solvent enough to cover the announced fees for all the operations in + the batch. + +.. _manager_operations_application_lima: + +Application of Manager Operations +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Once the validity of a manager operation (or, a batch of manager +operations) is established, the protocol proceeds to apply the +operation. This first step in this application phase is to transfer +the operation's fees to the baker that included this operation. Then, +the actual application depends on the operation kind. For instance, +this could be a smart contract execution, enacting a delegation or +multiple actions executed as a batch. The application of a batch of +manager consists of the sequential application of each operation in +the batch, following their inclusion order -- the head of the batch +being the first manager operation being applied. + +The application of each individual manager operation may either +succeed -- and therefore reported as ``Applied`` --, or indeed fail +with an error. In both cases, the fees are taken and the counter for +the operation's manager is incremented. + +When a manager operation fails, every side-effect which was previously +performed is backtracked. Moreover, depending on the position of the +manager operation in a batch, this failure has to be propagated +accordingly: + +- If there were other successfully applied operations in the batch + prior to the offending one, the effect of each of them has to be + reverted, and each of them will be reported as ``Backtracked``. + +- If there were other operations pending application after the + offending one, their application is aborted, and they are reported + as ``Skipped``. + +For example, let's consider a simple batch of three manager operations +``[op1, op2, op3]``, if ``op1`` is successful but ``op2`` fails, the +ticket result for the application of the manager operation batch will +report: + +* ``op1`` -- ``Backtracked``, ```op1`` was applied successfully, but + after ``op2`` failed, the operation was cancelled; +* ``op2`` -- ``Failed``, the application of this particular operation failed; +* ``op3`` -- ``Skipped``, this operation was never executed because + ``op2`` had previously failed. diff --git a/docs/shell/glossary.rst.h b/docs/shell/glossary.rst.h index 3926a385b5136ede6a36a8dcde785811d9bf3f27..4b41bf55ee211d0f515e31b08d8b40cb33f92b58 100644 --- a/docs/shell/glossary.rst.h +++ b/docs/shell/glossary.rst.h @@ -7,9 +7,8 @@ _`Block` Blocks conceptually contain a header and a list of Operations_, which are specific to the `economic protocol`_. - The header itself decomposes into a shell header (common to all protocols) and a protocol-specific header. - The shell header contains `protocol`-agnostic data such as the - block predecessor's hash and the block's timestamp. + The header itself decomposes into a :ref:`shell header` (common to all Tezos economic protocols), and a protocol-specific header. + The shell header contains protocol-agnostic data such as the predecessor's block hash and the block's timestamp. _`Context` The state of the blockchain. The context is defined by the @@ -38,8 +37,8 @@ _`Fitness` (a.k.a. score, a.k.a. weight) _`Height` See level_. -_`Level` (a.k.a. height) - The position of a block in the chain, that is, the number of blocks +_`Level` (a.k.a. block height) + The position of a block in the blockchain, that is, the number of blocks since the genesis block, where the genesis block is at level 0. _`Mempool` diff --git a/docs/shell/validation.rst b/docs/shell/validation.rst index 0c058488bc3d6714e79a8743f545748e94604ccf..f103492a19f3e21400ab5378475a913c1bae1582 100644 --- a/docs/shell/validation.rst +++ b/docs/shell/validation.rst @@ -103,8 +103,10 @@ difference between the current head and the examined proposal is more than one block, mostly during the initial bootstrap phase, the peer worker launches a *bootstrap pipeline* task. +.. _multi_pass_validation: + A third scheme is planned (but not yet implemented) for validating -alternative chains: the *multipass validator*. This method is quite +alternative chains: the *multi-pass validator*. This method is quite more complex, its goal is to detect erroneous blocks as soon as possible, without having to download all the chain data. This process will work by first validating the block headers, then the operations @@ -123,7 +125,7 @@ signatures. For that to be sound, the fork limit is set to not allow rewinding before the baking and endorsing slots are set. Each of these three peer validator tasks (head increment, bootstrap -pipeline, or multipass) will interact with the distributed DB to get +pipeline, or multi-pass) will interact with the distributed DB to get the data they need (block headers and operations). When they have everything needed for a block, they will call the *block validator*. diff --git a/docs/user/various.rst b/docs/user/various.rst index 135d688a0fce1a2b570fd57a6a86ef5aa1493182..02c0497377127cbaae9bb82bea1e52bfe40fde9a 100644 --- a/docs/user/various.rst +++ b/docs/user/various.rst @@ -63,6 +63,8 @@ indicates a recommended course of action. | 255 | like 127 but an error and an error occurred during exit (e.g., ``kill -9``) | check output/logs, clean-up leftover files | +-------------+----------------------------------------------------------------------------------+------------------------------------------------------------------+ +.. _failing_noop: + Failing_noop operation ----------------------