diff --git a/docs/010/voting.rst b/docs/010/voting.rst index 17e2859f8a142b6c86d0fc359bb26eb0ae782b70..a5e4fa4a66f3ae59fe9ec891100549be334f4233 100644 --- a/docs/010/voting.rst +++ b/docs/010/voting.rst @@ -66,8 +66,8 @@ protocol that the hash identifies is invalid, the activation step fails. A protocol is invalid if the code cannot be compiled (e.g., if the code is not valid source code), if the code uses functions not present in the -:ref:`protocol environment `, or if it downgrades the -:ref:`protocol environment ` version. +:doc:`protocol environment <../developer/protocol_environment>`, or if it +downgrades the protocol environment version. If the protocol is invalid and the activation fails, the chain becomes stuck. Thus, when voting, it is important to vote for hashes that designate a protocol diff --git a/docs/011/consensus.rst b/docs/011/consensus.rst index a53bc9e06fc047643e0e9340e48ac2a70c3ddc73..4774358acf8d2291cef304d3def0d0173aecff00 100644 --- a/docs/011/consensus.rst +++ b/docs/011/consensus.rst @@ -44,10 +44,11 @@ Terminology A *block* in the blockchain consists of a header and a list of operations. The header has a shell part (common to all protocols) and a protocol-specific part. In Emmy*, :ref:`the protocol-specific part of the -header` contains, most notably, a timestamp, a -priority (a natural number), and the endorsements for the block at the previous -level. *Endorsements* are operations that can be seen as votes for a given -block. Each block is signed. +header` contains, most notably, a +priority (a natural number). The consensus operations in a block are called *endorsements*. +These operations can be seen as votes for a given block. +The endorsements included a block at level ``l`` are votes for the block at the previous +level ``l-1``. Each block is signed. Before being endorsed, blocks are baked. *Baking* is the action of producing and signing a block. Corresponding to these two actions of baking and endorsing, at @@ -172,6 +173,7 @@ protocol-specific header: ``BLOCKS_PER_COMMITMENT`` (see :ref:`Constants`). - ``proof_of_work_nonce``: a nonce used to pass a low-difficulty proof-of-work for the block, as a spam prevention measure. + - ``liquidity_baking_escape_vote``: :ref:`a flag` that requests ending the subsidy. The consensus algorithm is implemented in Tezos in five components: the shell, diff --git a/docs/011/liquidity_baking.rst b/docs/011/liquidity_baking.rst index 2e07ad736031fd74fcd86039c0c4358d45a72e7c..9b6c2e74f49bc1f00f818aac1fa7cfe91f76f6c4 100644 --- a/docs/011/liquidity_baking.rst +++ b/docs/011/liquidity_baking.rst @@ -34,6 +34,8 @@ As a safety precaution, the subsidy expires automatically at a given level called the liquidity baking sunset level. The sunset level can be renewed periodically by protocol amendment. +.. _esc_hatch_011: + Escape hatch ~~~~~~~~~~~~ diff --git a/docs/011/voting.rst b/docs/011/voting.rst index f8049e126b6f31da67c1be9cdf28210e553a4b86..a303415078250a6461efc9abf01fd30bb6884b1b 100644 --- a/docs/011/voting.rst +++ b/docs/011/voting.rst @@ -179,8 +179,8 @@ fails. A protocol is *invalid* if its code cannot be compiled (e.g., if the code is not valid source code), if its code uses functions not present in the -:ref:`protocol environment `, or if it downgrades the -:ref:`protocol environment ` version. +:doc:`protocol environment <../developer/protocol_environment>`, or if it +downgrades the protocol environment version. If an invalid protocol is voted in, then the activation fails for all the nodes, and then the chain becomes stuck. This is why it is important to vote for hashes diff --git a/docs/alpha/consensus.rst b/docs/alpha/consensus.rst index 0b4090c9562fc266e1999d5b6eda7abab2f754b9..37052b5b4d7d98a9d818f77d9e8d1f5377740d6f 100644 --- a/docs/alpha/consensus.rst +++ b/docs/alpha/consensus.rst @@ -99,6 +99,9 @@ preendorsement quorum for a candidate block in a previous round, is required to the same *payload* as the initial block. We talk about a *re-proposal* in this case. + +.. _finality_alpha: + Transaction and block finality ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -150,7 +153,7 @@ balance). Let us first (re)define these and related concepts. of the maximum active stake during the last ``PRESERVED_CYCLES + MAX_SLASHING_PERIOD``. This amount represents the delegate's skin in the game: in the case that the delegate behaves badly, its frozen deposit is partly slashed (see - :ref:`slashing`). Taking the maximum over an + :ref:`slashing_alpha`). Taking the maximum over an interval of cycles (instead of just considering the active stake at the cycle where the bad action can occur) allows to avoid situations where a malicious delegate empties its accounts between the time when @@ -381,8 +384,8 @@ participation of a selfish baker does not have an impact. .. _cs_constants_alpha: -Consensus protocol parameters ------------------------------ +Consensus related protocol parameters +------------------------------------- .. list-table:: :widths: 55 25 @@ -414,6 +417,34 @@ Consensus protocol parameters - ``endorsing_reward / CONSENSUS_COMMITTEE_SIZE`` = 0.002857 tez +.. _shell_proto_revisit_alpha: + +Shell-protocol interaction revisited +------------------------------------ + +: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: + +- ``signature``: a digital signature of the shell and protocol headers (excluding the signature itself) +- ``seed_nonce_hash``: a commitment to :ref:`a random number`, used to generate entropy on the chain +- ``proof_of_work_nonce``: a nonce used to pass a low-difficulty proof-of-work for the block, as a spam prevention measure +- ``liquidity_baking_escape_vote``: :ref:`a flag` that requests ending the subsidy. + +There are two additional fields: ``payload_hash`` and ``payload_round`` which are needed for establishing if a block is :ref:`final`. + +.. _fitness_alpha: + +The fitness is given by the tuple ``(level, locked_round, predecessor_round, round)``. +The fitness encapsulates more information than in Emmy* because Tenderbake is more complex: recall that blocks at the last level only represent :ref:`candidate blocks`. +In Emmy*, only the level mattered. +But in Tenderbake, we need to, for instance, allow for new blocks at the same level to be accepted by nodes. +Therefore the fitness also includes the block's round. +Furthermore, we also allow to change the predecessor block when it has a :ref:`smaller round`. +Therefore the fitness also includes the predecessor block's round. + + + Further External Resources -------------------------- diff --git a/docs/alpha/liquidity_baking.rst b/docs/alpha/liquidity_baking.rst index b7c94b936d8d35a70a6c60cb5c79a8c84bf0f086..0e2416b8c92afa5c9217c09530670699a0a7dfb0 100644 --- a/docs/alpha/liquidity_baking.rst +++ b/docs/alpha/liquidity_baking.rst @@ -34,6 +34,8 @@ As a safety precaution, the subsidy expires automatically at a given level called the liquidity baking sunset level. The sunset level can be renewed periodically by protocol amendment. +.. _esc_hatch_alpha: + Escape hatch ~~~~~~~~~~~~ diff --git a/docs/alpha/protocol_overview.rst b/docs/alpha/protocol_overview.rst index e549ac260134efce50dff60cd0740215faef89bb..a9a12c8ac0c4204a08c3740a1e2ef7aaa36b62f2 100644 --- a/docs/alpha/protocol_overview.rst +++ b/docs/alpha/protocol_overview.rst @@ -59,7 +59,9 @@ 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 *fitness*. The fitness determines a total ordering between blocks. +a higher :ref:`fitness`. The fitness determines a total ordering between blocks. + +.. _shell_proto_interact_alpha: Shell-protocol interaction ~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -75,7 +77,7 @@ Blocks 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`. +and :ref:`the protocol-specific part`. This separation enables the shell to interact with different protocols. diff --git a/docs/alpha/voting.rst b/docs/alpha/voting.rst index ee5b5044f58d77e9d23613e7f603736eb0f80730..dd44c3a3e75a4d873290c06f47b1a5fac97fbc5f 100644 --- a/docs/alpha/voting.rst +++ b/docs/alpha/voting.rst @@ -177,8 +177,8 @@ fails. A protocol is *invalid* if its code cannot be compiled (e.g., if the code is not valid source code), if its code uses functions not present in the -:ref:`protocol environment `, or if it downgrades the -:ref:`protocol environment ` version. +:doc:`protocol environment <../developer/protocol_environment>`, or if it +downgrades the protocol environment version. If an invalid protocol is voted in, then the activation fails for all the nodes, and then the chain becomes stuck. This is why it is important to vote for hashes @@ -318,8 +318,8 @@ Further External Resources Further details and explanations on the voting procedure can be found at: -- `the Open Tezos entry`_ -- `the Tezos Agora entry`_. +- `Governance on-chain `_ on Open Tezos +- `Tezos Governance `_ on Tezos Agora. For more details on the client commands refer to the manual at :ref:`client_manual_alpha`. diff --git a/docs/developer/entering_alpha.rst b/docs/developer/entering_alpha.rst index 9e6177ef5b200a8ae91c17a84e7e093f26e36e0b..860125b785e4ae8914576901a5871667b729afa4 100644 --- a/docs/developer/entering_alpha.rst +++ b/docs/developer/entering_alpha.rst @@ -7,7 +7,7 @@ name and is not related to the old Alphanet :ref:`test network `. Before reading that document, you may want to: - read the whitepaper, -- read :ref:`how the economic protocol is +- read :doc:`how the economic protocol is sandboxed `. As all protocols, Alpha is made of a series of OCaml interface and diff --git a/docs/developer/javascript.rst b/docs/developer/javascript.rst index 72c3ae59695a14dd2762fbdf27d95c84b4d64211..b88f4c224b49227f14e6b654de9760fcb8a89a52 100644 --- a/docs/developer/javascript.rst +++ b/docs/developer/javascript.rst @@ -1,5 +1,5 @@ Compiling (part of) the Octez codebase to JavaScript -================================================== +==================================================== We want to expose a JavaScript API while staying in sync with the OCaml codebase. A way to achieve this is to compile OCaml code to @@ -21,14 +21,15 @@ In the first phase, the focus is restricted to testing libraries needed to expose an Octez client API. Installing node (nodejs) ---------------------------------- +------------------------ In order to run JavaScript tests, one needs ``node`` to be installed. One way to achieve this is to rely on ``nvm``. Use the following -commands to install `nvm` and `node`: +commands to install ``nvm`` and ``node``: :: + curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash scripts/install_builld_deps.js.sh @@ -36,16 +37,16 @@ commands to install `nvm` and `node`: Limitation with inline_tests ---------------------------- -`Inline_tests` (e.g. `ppx_inline_test`) are compatible with -`js_of_ocaml`, but we currently can't configure the alias under which +``Inline_tests`` (e.g. ``ppx_inline_test``) are compatible with +``js_of_ocaml``, but we currently can't configure the alias under which they run. -Because we don't want to force a `nodejs` dependency on everybody, we -can't have JavaScript test run under the `runtest` alias by default. +Because we don't want to force a ``nodejs`` dependency on everybody, we +can't have JavaScript test run under the ``runtest`` alias by default. To workaround this limitation, running -`dune exec ./src/tooling/run_js_inline_tests.exe` will temporarily -patch dune files and run `dune runtest` for you. +``dune exec ./src/tooling/run_js_inline_tests.exe`` will temporarily +patch dune files and run ``dune runtest`` for you. Running tests ------------- @@ -54,8 +55,8 @@ One can run JavaScript tests with ``make test-js`` in the project root or directly using dune with ``dune builld @SOME-PATH/runtest_js``. In addition, to run inline_tests, execute -`dune exec ./src/tooling/run_js_inline_tests.exe` or -`dune exec ./src/tooling/run_js_inline_tests.exe SOME_PATH`. +``dune exec ./src/tooling/run_js_inline_tests.exe`` or +``dune exec ./src/tooling/run_js_inline_tests.exe SOME_PATH``. Adding tests ------------ @@ -65,12 +66,13 @@ Alcotest Alcotest tests are compatible with Js_of_ocaml. In order to run alcotest tests in JavaScript: -- add `js` to modes in the tests stanza. -- and a new rule in the dune file to execute the test with node. -- dune build @runtest_js +- add ``js`` to modes in the tests stanza. +- and a new rule in the dune file to execute the test with node. +- ``dune build @runtest_js`` :: + (tests (names mytest) (libraries alcotest) @@ -83,19 +85,21 @@ alcotest tests in JavaScript: Inline tests ~~~~~~~~~~~~ -Inline_tests (e.g. ppx_inline_test) are compatible with jsoo but do +Inline tests (e.g. ``ppx_inline_test``) are compatible with jsoo but do not run by default (see limitation above). In order to run inline_tests in javascript: -- make sure to have both `(js_of_ocaml)` and `(inline_tests)` in your library stanza. -- run `dune exec ./src/tooling/run_js_inline_tests.exe` + +- make sure to have both ``(js_of_ocaml)`` and ``(inline_tests)`` in your library stanza. +- run ``dune exec ./src/tooling/run_js_inline_tests.exe`` :: - (library - (name mylib) - (js_of_ocaml) - (inline_tests) - ) + + (library + (name mylib) + (js_of_ocaml) + (inline_tests) + ) JavaScript test failures ------------------------ @@ -104,8 +108,9 @@ There are plenty of reasons that can explain why a test fails when running in JavaScript and succeed otherwise. Here is a non exhaustive list: + - Integer (``int``) are 32bit, not 63bit. - The stack is much smaller by default on JavaScript VMs, it's easier to stackoverflow. - There is no general tailcall optimization. In particular, cps will not be optimized. Only self tail recursive and mutually tail recursive functions are usually optimized. -- Some OCaml feature/lib are not (or only partially) supported: Unix, Marshal, .. +- Some OCaml feature/lib are not (or only partially) supported: Unix, Marshal, ... diff --git a/docs/developer/michelson_instructions.rst b/docs/developer/michelson_instructions.rst index 530ffa61cdfb9edffff7afa91cd54f78c973de22..47cb26f81ac106426b1f53e8e48d1d76371158d9 100644 --- a/docs/developer/michelson_instructions.rst +++ b/docs/developer/michelson_instructions.rst @@ -91,7 +91,7 @@ Michelson types Before we talk about internal representations, we need to have a brief look at how the interpreter handles types of Michelson expressions internally. Types ``ty`` and ``stack_ty`` are both defined in -:src:`/src/proto_alpha/lib_protocol/script_typed_ir.ml`. Type ``ty`` enumerates +:src:`src/proto_alpha/lib_protocol/script_typed_ir.ml`. Type ``ty`` enumerates all types known to the Michelson interpreter and is parametrised by the underlying OCaml type in which Michelson values are actually stored in memory. Thus, when values of the ty type are pattern-matched on, their type parameters @@ -148,7 +148,7 @@ For instance ``ICar`` instruction is defined as:: The reason why the third parameter of the resulting ``kinstr`` is ``'r`` and not simply ``'a`` (which is the type of the first element of the pair at the top of the -initial stack) is because this constructor also contains the next instruction, +initial stack) is because this constructor also contains the next instruction, which produces a value of some arbitrary type ``'r``. However, note that this next instruction should expect ``'a`` at the top of its initial stack. @@ -184,7 +184,7 @@ The translator Now that we have chosen a primitive to represent our instruction in the code and an internal representation (IR), we need to provide a rule that translates the former into the latter. ``parse_instr`` function in -:src:`/src/proto_alpha/lib_protocol/script_ir_translator.ml` is responsible for +:src:`src/proto_alpha/lib_protocol/script_ir_translator.ml` is responsible for this. Notice that the function ``parse_instr``, despite what its name suggests, matches on pre-parsed Micheline AST. Micheline parser is not a part of the protocol and therefore must be run by the client before the script is submitted @@ -215,7 +215,7 @@ correct), which makes for faster execution. For this reason it is essential that each IR contains a value of type ``kinfo`` (or an equivalent thereof), from which the translator can obtain the type the stack should have after this instruction is executed. Function ``kinfo_of_kinstr`` in -:src:`/src/proto_alpha/lib_protocol/script_typed_ir.ml` is responsible for this +:src:`src/proto_alpha/lib_protocol/script_typed_ir.ml` is responsible for this extraction. An interesting situation occurs with instructions regulating control flow. These @@ -242,7 +242,7 @@ The precise return type of ``parse_instr`` is ``judgement`` defined in apply : 'r 'f. ('a, 's) kinfo -> ('b, 'u, 'r, 'f) kinstr -> ('a, 's, 'r, 'f) kinstr; } - + type ('a, 's, 'b, 'u) descr = { loc : Script.location; bef : ('a, 's) stack_ty; diff --git a/docs/developer/protocol_environment.rst b/docs/developer/protocol_environment.rst index 920c22f4418ff0ba478885c1f37e243cbca839f0..30dc11c4b3519ea8a1b01f6cdffafe0c4e24231b 100644 --- a/docs/developer/protocol_environment.rst +++ b/docs/developer/protocol_environment.rst @@ -1,5 +1,3 @@ -.. _protocol_environment: - Economic protocol sandboxing ============================ diff --git a/docs/developer/time_measurement_ppx.rst b/docs/developer/time_measurement_ppx.rst index f8d409b47333a3f0a2d3477d3119b20f973e42de..c5086f87ea4e6c063c6337787d0c87475e340ec7 100644 --- a/docs/developer/time_measurement_ppx.rst +++ b/docs/developer/time_measurement_ppx.rst @@ -1,5 +1,3 @@ -.. _time_measurement_ppx: - Time measurement PPX ==================== @@ -12,7 +10,7 @@ expressions and to log these measurements when desired. Since it uses together with ``Tezt`` framework to perform the benchmarking of specific parts of Tezos node. -**This PPX is only intended to be used for tests. As the current runtime +**This PPX is only intended to be used for tests. As the current runtime implemetation performs memory allocation, an unwise usage could mess with the garbage collector or blow up your memory.** @@ -95,7 +93,7 @@ time measurement in order to discriminate it later. This key is computed from th that was given inside the attribute ``[@time.duration f_time]``. ``"f_time"`` is the label of the key, an identifier that represents the name of the measurement. -``[]`` is a list of string that contains some additional metadata. It can be useful +``[]`` is a list of strings that contains some additional metadata. It can be useful to distinguish several measurements registered with the same label, for example if the expression is evaluated in a loop. In our case, the list is empty because no metadata was provided in the attribute's payload. @@ -145,7 +143,7 @@ is displayed on standard output. For example: .. code-block:: - Aug 23 17:52:58.593 - benchmarking: time measurements: + Aug 23 17:52:58.593 - benchmarking: time measurements: Aug 23 17:52:58.593 - benchmarking: [(f_time, 0.000177); (g_time, 0.005658)] Compatible Ocaml Attributes @@ -157,13 +155,13 @@ The PPX provides the handling of three attributes: Ocaml expressions execution. The ``