From f33fa9da3ed904972716580caa874f5ffeda02df Mon Sep 17 00:00:00 2001 From: Nic Volanschi Date: Mon, 31 Jul 2023 10:48:21 +0200 Subject: [PATCH 1/6] doc: make it clear that there is a single rollups inbox --- docs/alpha/smart_rollups.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/alpha/smart_rollups.rst b/docs/alpha/smart_rollups.rst index 5ed4f4a686a3..177636df6b3d 100644 --- a/docs/alpha/smart_rollups.rst +++ b/docs/alpha/smart_rollups.rst @@ -91,7 +91,7 @@ There are two channels of communication to interact with smart rollups: Rollups inbox """"""""""""" -The inbox is unique to all rollups and contains two kinds of messages: +A single global inbox serves all rollups and contains two kinds of messages: *external* messages are pushed through a Layer 1 manager operation while *internal* messages are pushed by Layer 1 smart contracts or by the protocol itself. All messages (external and internal) pushed to -- GitLab From 0db8706bdfa80a01be5d3d124279450d4cb9e5ae Mon Sep 17 00:00:00 2001 From: Eugen Zalinescu Date: Mon, 31 Jul 2023 11:07:07 +0200 Subject: [PATCH 2/6] Docs: add missing steps in env upgrade and fix some typos Co-Authored-By: Zettez <1766551-zettez@users.noreply.gitlab.com> --- .../protocol_environment_upgrade.rst | 38 ++++++++++--------- 1 file changed, 21 insertions(+), 17 deletions(-) diff --git a/docs/developer/protocol_environment_upgrade.rst b/docs/developer/protocol_environment_upgrade.rst index 31e7489889f2..88978da149e6 100644 --- a/docs/developer/protocol_environment_upgrade.rst +++ b/docs/developer/protocol_environment_upgrade.rst @@ -8,7 +8,7 @@ See the general overview in :doc:`Protocol environment <../shell/protocol_enviro The set of libraries a protocol is compiled against is called the *protocol environment*, or simply, the *environment*. -Each protocol is compiled against a given environment, as declared in the protocol's ``TEZOS_PROTOCOL`` manifest file. In order to ensure that old protocols can still be compiled in the future, all the environments are set in stone: their interface cannot ever be modified. Consequently, when new features are needed for new protocols, a whole new environment must be created. (Otherwise, if no new feature is needed, a protocol can use the same environment as its predecessor's.) +Each protocol is compiled against a given environment, as declared in the protocol's ``TEZOS_PROTOCOL`` manifest file. In order to ensure that old protocols can still be compiled in the future, all the environments are set in stone: their interface cannot ever be modified. Consequently, when new features are needed for new protocols, a whole new environment must be created (otherwise, if no new feature is needed, a protocol can use the same environment as its predecessor's). This page details the process of creating a new environment by copying the latest environment and building upon it. In the rest of this page, ```` is the version number for the new environment you are creating and ```` is the version number for the existing environment that you are copying from. @@ -20,15 +20,15 @@ The following steps are roughly the steps taken in the `V6 bootstrap MR `` into ``src/lib_protocol_environment/sigs/v`` + * Copy the directory ``src/lib_protocol_environment/sigs/v`` into ``src/lib_protocol_environment/sigs/v``. - * Copy the file ``src/lib_protocol_environment/sigs/v.in.ml`` into ``src/lib_protocol_environment/sigs/v.in.ml`` + * Copy the file ``src/lib_protocol_environment/sigs/v.in.ml`` into ``src/lib_protocol_environment/sigs/v.in.ml`` and change any reference from `v` to `v` in the copied file. 2. Make the new environment buildable by updating ``manifest/main.ml``: * Bump the ``latest_environment_number`` in ``manifest/main.ml``. - * Run ``make -C manifest`` + * Run ``make -C manifest``. 3. Copy the existing compatibility layer if any (see details in `Struct compatibility layer <#struct-compatibility-layer>`__). @@ -36,32 +36,32 @@ The following steps are roughly the steps taken in the `V6 bootstrap MR .ml[i]`` to ``src/lib_protocol_environment/environment_V.ml[i]`` + * Copy ``src/lib_protocol_environment/environment_V.ml[i]`` to ``src/lib_protocol_environment/environment_V.ml[i]``. - * Change any reference from ``V`` to ``V`` in all those copied files the + * Change any reference from ``V`` to ``V`` in all those copied files. - * Update ``src/lib_protocol_environment/environment_context_intf.ml`` + * Update ``src/lib_protocol_environment/environment_context_intf.ml``. 5. If the protocol signature is expected to change then copy and adapt it otherwise leave it as is: - ``Environment_protocol_T_V`` is the current protocol signature and ```` is equal to the environment version that introduce it. + ``Environment_protocol_T_V`` is the current protocol signature and ```` is equal to the environment version that introduces it. - * Copy ``src/lib_protocol_environment/environment_protocol_T_V.ml`` to ``src/lib_protocol_environment/environment_protocol_T_V.ml`` + * Copy ``src/lib_protocol_environment/environment_protocol_T_V.ml`` to ``src/lib_protocol_environment/environment_protocol_T_V.ml``. - * Change ``Environment_protocol_T_V`` to ``Environment_protocol_T_V`` in ``src/lib_protocol_environment/environment_V.ml`` + * Change ``Environment_protocol_T_V`` to ``Environment_protocol_T_V`` in ``src/lib_protocol_environment/environment_V.ml``. 6. Add references to the new environment version number in the rest of the code: - * Add references to ``src/lib_base/protocol.ml[i]`` + * ``src/lib_base/protocol.ml[i]`` * ``src/lib_validation/block_validation.ml`` 7. Adapt demo protocols to the new environment: - * Modify the required environment in ``src/proto_demo_noops/lib_protocol/TEZOS_PROTOCOL`` and ``src/proto_demo_counter/lib_protocol/TEZOS_PROTOCOL`` + * Modify the required environment in ``src/proto_demo_noops/lib_protocol/TEZOS_PROTOCOL`` and ``src/proto_demo_counter/lib_protocol/TEZOS_PROTOCOL``. - * Verify they both compile with ``dune build @src/proto_demo_noops/runtest_compile_protocol`` and ``dune build @src/proto_demo_counter/runtest_compile_protocol`` + * Verify they both compile with ``dune build @src/proto_demo_noops/runtest_compile_protocol`` and ``dune build @src/proto_demo_counter/runtest_compile_protocol``. 8. Commit all those changes and open an MR with your changes. @@ -73,7 +73,7 @@ Struct compatibility layer The struct compatibility layer is for providing compatibility between a signature of the protocol environment (which is set in stone) and the interface of an external library that provides it (which might change from version to version). E.g., at the time of the V0 environment the OCaml Stdlib did not include an ``Option`` module and so a custom one was provided in the whole of the Tezos project including the protocol environment; later, when the Tezos project switched to the now available and standard ``Stdlib.Option`` module, the struct compatibility module ``src/lib_protocol_environment/structs/v0_option.ml`` was added. -More recent protocol environments generally need less struct compatibility modules. Occasionally, the most recent environment needs no compatibility layer at all. You can know if this is the case by checking the file ``src/lib_protocol_environment/structs/tezos_protocol_environment_structs.ml``: if the submodule ``V`` exists and is not empty then there is a compatibility layer, otherwise there isn't. +More recent protocol environments generally need fewer struct compatibility modules. Occasionally, the most recent environment needs no compatibility layer at all. You can know if this is the case by checking the file ``src/lib_protocol_environment/structs/tezos_protocol_environment_structs.ml``: if the submodule ``V`` exists and is not empty then there is a compatibility layer, otherwise there isn't. Either way, the instructions in the list above are sufficient for creating the new environment. @@ -86,9 +86,9 @@ The new environment as it stands now is not activated. More precisely, it cannot When to activate ^^^^^^^^^^^^^^^^^ -This is on purpose: we do not want to release an unfinished environment because it interferes with the distributed nature of Tezos protocol development. Specifically, if an unfinished protocol was made available in a release of the Octez suite, then anyone could propose a protocol built upon this version. But then further work on the protocol (to finish it) would create multiple different environment that have the same name. To avoid this, we only activate the environment once it is safe. +This is on purpose: we do not want to release an unfinished environment because it interferes with the distributed nature of Tezos protocol development. Specifically, if an unfinished protocol was made available in a release of the Octez suite, then anyone could propose a protocol built upon this version. But then further work on the protocol (to finish it) would create multiple different environments that have the same name. To avoid this, we only activate the environment once it is safe. -The new environment should only be activated after the last release that precedes injection of the protocol that uses it. Don't worry too much about this, simply reach out to a release manager and work with them on the schedule. +The new environment should only be activated after the last release that precedes the injection of the protocol that uses it. Don't worry too much about this, simply reach out to a release manager and work with them on the schedule. How to activate ^^^^^^^^^^^^^^^^ @@ -99,7 +99,11 @@ To activate the environment you will need to change the following files, adding * ``src/lib_protocol_updater/registered_protocol.ml[i]`` * ``src/lib_protocol_compiler/registerer/tezos_protocol_registerer.ml[i]`` -Bump environment version in ``src/bin_client/test/proto_test_injection/TEZOS_PROTOCOL`` and in the embedded ``TEZOS_PROTOCOL`` found in ``tezt/tests/voting.ml``. +Bump environment version in: + +* ``src/bin_client/test/proto_test_injection/TEZOS_PROTOCOL`` +* ``tezt/tests/voting.ml`` (in the embedded ``TEZOS_PROTOCOL``) +* ``src/lib_store/unix/test/test_consistency.ml`` And finally, bump environment version in ``src/proto_alpha/lib_protocol/TEZOS_PROTOCOL``, and run ``make -C manifest``. -- GitLab From 8ef549584663960173b2b0c6f92b6447f3af364d Mon Sep 17 00:00:00 2001 From: Zettez <1766551-zettez@users.noreply.gitlab.com> Date: Thu, 3 Aug 2023 10:20:09 +0000 Subject: [PATCH 3/6] Docs: fix typos in alpha/smart_rollups.rst --- docs/alpha/smart_rollups.rst | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/docs/alpha/smart_rollups.rst b/docs/alpha/smart_rollups.rst index 177636df6b3d..d511504d5821 100644 --- a/docs/alpha/smart_rollups.rst +++ b/docs/alpha/smart_rollups.rst @@ -1,7 +1,7 @@ Smart Optimistic Rollups ======================== -A **rollup** is a processing unit that receives, retrieves, and +A **rollup** is a processing unit that receives, retrieves and interprets input messages to update its local state and to produce output messages targetting the Tezos blockchain. In this documentation, we will generally refer to the rollup under @@ -84,7 +84,7 @@ There are two channels of communication to interact with smart rollups: information to all the rollups. #. a **reveal data channel** allows each rollup to retrieve data - coming from data sources external to the Layer 1. Rollups requests + coming from data sources external to the Layer 1. Rollups request data through that channel to the runner of that rollup kernel (i.e. the smart rollup node). @@ -136,7 +136,7 @@ inbox. Finally, after the application of the operations of the Tezos block, the Layer 1 pushes one final internal message “End of -level”. Similarly to “Start of level“, this internal messages does not +level”. Similarly to “Start of level“, these internal messages does not come with any payload. .. _reveal_data_channel_smart_rollups_alpha: @@ -185,7 +185,7 @@ implements this reactive process: it downloads the Tezos block and interprets it according to the semantics of the PVM. This interpretation can require updating a state, downloading data from other sources, or performing some cryptographic verifications. The -state of the rollup contains an **outbox**, that is a sequence of +state of the rollup contains an **outbox**, which is a sequence of latent calls to Layer 1 contracts. The behavior of the rollup node is deterministic and fully specified @@ -483,7 +483,7 @@ The log should show that the rollup node follows the Layer 1 chain and processes the inbox of each level. -Notice that distinct Layer 1 adresses could be used for the Layer 1 +Notice that distinct Layer 1 addresses could be used for the Layer 1 operations issued by the rollup node simply by editing the configuration file to set different addresses for ``publish``, ``add_messages``, ``cement``, and ``refute``. @@ -606,7 +606,7 @@ representation of the message payload, one can do: from "${OPERATOR_ADDR}" to inject such an external message. -So let us focus now on producing a viable contents for ``${EMESSAGE}``. +So let us focus now on producing a viable content for ``${EMESSAGE}``. The kernel used previously in our running example is a simple "echo" kernel that copies its input as a new message to its outbox. @@ -703,7 +703,7 @@ Sending an internal inbox message ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ A smart contract can push an internal message in the rollup inbox -using the Michelson ``TRANSFER_TOKENS`` instruction targetting a +using the Michelson ``TRANSFER_TOKENS`` instruction targeting a specific rollup address. The parameter of this transfer must be a value of the Michelson type declared at the origination of this rollup. @@ -799,7 +799,7 @@ The available options are: - `When to use Cranelift `_ Note that while the rollup node is generally capable of using Wasmer's -LLVM-based compiler, Octez does not current ship with it. +LLVM-based compiler, Octez does not currently ship with it. When the environment variable is undefined, Cranelift is used by default. @@ -907,7 +907,7 @@ The smart rollup carries two states: contracts in the Layer 1, and a durable storage which is akin to a file system. -The durable storage is a persistent tree, whose contents is addressed +The durable storage is a persistent tree, whose contents are addressed by path-like keys. A path in the storage may contain: a value (also called file) consisting of a sequence of raw bytes, and/or any number of subtrees (also called directories), that is, the paths in the @@ -999,7 +999,7 @@ verify the ``kernel_run`` function does not take more ticks than authorized. The direct consequence of this setup is that it might be necessary for a WASM kernel to span a long computation across several calls to ``kernel_run``, and therefore to serialize any data it needs in the -durable storage to avoid loosing them. +durable storage to avoid losing them. Finally, the kernel can verify if the previous ``kernel_run`` invocation was trapped by verifying if some data are stored under the @@ -1046,7 +1046,7 @@ allow it to interact with the components of persistent state: ``store_delete_value`` Cuts the value under a given path out of the durable storage, but leaves the - rest of the substree untouched. Since version ``2.0.0-r1`` of the WASM PVM. + rest of the subtree untouched. Since version ``2.0.0-r1`` of the WASM PVM. ``store_copy`` Copies the subtree under a given path to another key. Since the @@ -1121,7 +1121,7 @@ programs, it is a low-level, stack-based, memory unsafe language. Fortunately, it was designed to be a compilation target, not a language in which developers would directly write their programs. -Rust has several advantages that makes it a good candidate for writing +Rust has several advantages that make it a good candidate for writing the kernel of a smart rollup. Not only does the Rust compiler treat WASM as a first class citizen when it comes to compilation targets, but its approach to memory safety eliminates large classes of bugs and @@ -1626,7 +1626,7 @@ Glossary This ability is used during the final step of refutation games. #. **Inbox**: A sequence of messages from the Layer 1 to smart rollups. - The contents of the inbox is determined by the consensus of the + The contents of the inbox are determined by the consensus of the Tezos protocol. #. **Outbox**: A sequence of messages from a smart rollup to the Layer 1. -- GitLab From 3c79ef5d2414c099f9e56ca405b01a4dde4b9cde Mon Sep 17 00:00:00 2001 From: julien Date: Mon, 14 Aug 2023 17:18:36 +0200 Subject: [PATCH 4/6] lib_node_config: fix typo in CLI help page --- src/lib_node_config/shared_arg.ml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/lib_node_config/shared_arg.ml b/src/lib_node_config/shared_arg.ml index 3ac0e1c85caf..9285e02a55ce 100644 --- a/src/lib_node_config/shared_arg.ml +++ b/src/lib_node_config/shared_arg.ml @@ -568,7 +568,7 @@ module Term = struct let bootstrap_threshold = let doc = - "[DEPRECATED: use synchronisation_threshold instead] The number of peers \ + "[DEPRECATED: use synchronisation-threshold instead] The number of peers \ to synchronize with before declaring the node bootstrapped." in Arg.( -- GitLab From c1dd874f8f35474416a09c4e8c8b082be4e9a959 Mon Sep 17 00:00:00 2001 From: Nic Volanschi Date: Tue, 22 Aug 2023 16:29:16 +0200 Subject: [PATCH 5/6] doc: fix broken OpenAPI links --- docs/api/openapi.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/api/openapi.rst b/docs/api/openapi.rst index 57490c812313..b6563c49d64f 100644 --- a/docs/api/openapi.rst +++ b/docs/api/openapi.rst @@ -50,7 +50,7 @@ Their OpenAPI specification can be found at: - `rpc-openapi.json (version 17.3) `_ -- `rpc-openapi-rc.json (version 18.0~rc1) `_ +- `rpc-openapi-rc.json (version 18.0~rc1) `_ .. TODO tezos/tezos#2170: add/remove section(s) @@ -60,12 +60,12 @@ Oxford RPCs The OpenAPI specification for RPCs which are specific to the Oxford (``Proxford``) protocol can be found at: -- `oxford-openapi.json (version 18.0~rc1) `_ +- `oxford-openapi-rc.json (version 18.0~rc1) `_ The OpenAPI specification for RPCs which are related to the mempool and specific to the Oxford protocol can be found at: -- `oxford-mempool-openapi.json (version 18.0~rc1) `_ +- `oxford-mempool-openapi-rc.json (version 18.0~rc1) `_ Nairobi RPCs ------------ -- GitLab From a651510efe6cc03255ba8735c8ef763ec0b45260 Mon Sep 17 00:00:00 2001 From: Nic Volanschi Date: Tue, 22 Aug 2023 16:30:36 +0200 Subject: [PATCH 6/6] doc: fix broken links in several pages --- docs/alpha/timelock.rst | 2 +- docs/developer/error_monad_p3_advanced.rst | 4 ++-- docs/developer/guidelines.rst | 2 +- docs/developer/long-tezts.rst | 2 +- docs/developer/protocol_environment_upgrade.rst | 2 +- docs/developer/snoop.rst | 2 +- docs/developer/testing.rst | 2 +- docs/nairobi/timelock.rst | 2 +- docs/oxford/timelock.rst | 2 +- 9 files changed, 10 insertions(+), 10 deletions(-) diff --git a/docs/alpha/timelock.rst b/docs/alpha/timelock.rst index fc0604fec5fb..8c01135ae6e1 100644 --- a/docs/alpha/timelock.rst +++ b/docs/alpha/timelock.rst @@ -70,7 +70,7 @@ their whole deposit by providing the decryption, but in a way that delays everyo Cryptographic design -------------------- -The time-lock features are supported by the Tezos_crypto.Timelock `library `__. +The time-lock features are supported by the Tezos_crypto.Timelock :package-api:`library `. Users first generate a RSA modulus and a symmetric encryption key. They use authenticated encryption to encrypt a packed Michelson value (an array of bytes computed with ``PACK``) diff --git a/docs/developer/error_monad_p3_advanced.rst b/docs/developer/error_monad_p3_advanced.rst index e9bb6c7e4b78..49152860490f 100644 --- a/docs/developer/error_monad_p3_advanced.rst +++ b/docs/developer/error_monad_p3_advanced.rst @@ -302,8 +302,8 @@ Note that if you are calling an Lwt function, you have to use ``Lwt.catch`` or (function | exc -> Lwt_result_syntax.fail (Cannot_destruct_json_value exc)) -The error monad provides `several helpers functions for catching exceptions -`__. +The error monad provides :package-api:`several helpers functions for catching exceptions +`. :: diff --git a/docs/developer/guidelines.rst b/docs/developer/guidelines.rst index 7ec7752e4bac..a64e211c740a 100644 --- a/docs/developer/guidelines.rst +++ b/docs/developer/guidelines.rst @@ -132,7 +132,7 @@ Here are a few tips and guidelines on using docstrings. - Docstrings in ``.mli`` and ``.ml`` files are handled the same, so do not omit documenting the interfaces in the latter files. -For more information on using docstrings, see the ``odoc`` `documentation for library authors `__. +For more information on using docstrings, see the ``odoc`` `documentation for library authors `__. Docstrings errors """"""""""""""""" diff --git a/docs/developer/long-tezts.rst b/docs/developer/long-tezts.rst index 3d8482002796..eeac39de09e0 100644 --- a/docs/developer/long-tezts.rst +++ b/docs/developer/long-tezts.rst @@ -219,7 +219,7 @@ Configuring and Running Tezt Long Tests ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ For more information about how to use the configuration file, please refer -to the `Long test module API `__. +to the :package-api:`Long test module API `. A predefined configuration has already been shipped in :src:`tezt/lib_performance_regression/local-sandbox/tezt_config.json`. It allows to use the InfluxDB and Grafana instances set up by the diff --git a/docs/developer/protocol_environment_upgrade.rst b/docs/developer/protocol_environment_upgrade.rst index 88978da149e6..5d75f014a3bd 100644 --- a/docs/developer/protocol_environment_upgrade.rst +++ b/docs/developer/protocol_environment_upgrade.rst @@ -22,7 +22,7 @@ The following steps are roughly the steps taken in the `V6 bootstrap MR `` into ``src/lib_protocol_environment/sigs/v``. - * Copy the file ``src/lib_protocol_environment/sigs/v.in.ml`` into ``src/lib_protocol_environment/sigs/v.in.ml`` and change any reference from `v` to `v` in the copied file. + * Copy the file ``src/lib_protocol_environment/sigs/v.in.ml`` into ``src/lib_protocol_environment/sigs/v.in.ml`` and change any reference from ``v`` to ``v`` in the copied file. 2. Make the new environment buildable by updating ``manifest/main.ml``: diff --git a/docs/developer/snoop.rst b/docs/developer/snoop.rst index 9c9b16370d75..a571643f58d6 100644 --- a/docs/developer/snoop.rst +++ b/docs/developer/snoop.rst @@ -7,7 +7,7 @@ help you do that. This tool allows to benchmark any given piece of OCaml code and use these measures to fit cost models predictive of execution time. It is in particular used to derive the functions in the -`Michelson gas cost API `_, +:package-api:`Michelson gas cost API `, computing the gas costs in the Tezos protocol. .. toctree:: diff --git a/docs/developer/testing.rst b/docs/developer/testing.rst index 0f4fbe35ef3d..8da2e51de31f 100644 --- a/docs/developer/testing.rst +++ b/docs/developer/testing.rst @@ -132,7 +132,7 @@ Typical use cases: randomized inputs. Example test: - - QCheck is used in :src:`src/lib_base/test/test_time.ml` to test the `Tezos_base.Time `_ module. For instance, subtracting and then adding a random amount of seconds to a random time should give back the original time: this tests that ``add`` and ``diff`` are consistent (and the inverse of each other). To run this test, you need to run ``dune exec src/lib_base/test/test_time.exe``. + - QCheck is used in :src:`src/lib_base/test/test_time.ml` to test the :package-api:`Tezos_base.Time ` module. For instance, subtracting and then adding a random amount of seconds to a random time should give back the original time: this tests that ``add`` and ``diff`` are consistent (and the inverse of each other). To run this test, you need to run ``dune exec src/lib_base/test/test_time.exe``. References: - `QCheck README `_ diff --git a/docs/nairobi/timelock.rst b/docs/nairobi/timelock.rst index 9fc225ee4c5d..7b88ba9f1a54 100644 --- a/docs/nairobi/timelock.rst +++ b/docs/nairobi/timelock.rst @@ -70,7 +70,7 @@ their whole deposit by providing the decryption, but in a way that delays everyo Cryptographic design -------------------- -The time-lock features are supported by the Tezos_crypto.Timelock `library `__. +The time-lock features are supported by the Tezos_crypto.Timelock :package-api:`library `. Users first generate a RSA modulus and a symmetric encryption key. They use authenticated encryption to encrypt a packed Michelson value (an array of bytes computed with ``PACK``) diff --git a/docs/oxford/timelock.rst b/docs/oxford/timelock.rst index 2b9a959a6f3f..01b1f874fb66 100644 --- a/docs/oxford/timelock.rst +++ b/docs/oxford/timelock.rst @@ -70,7 +70,7 @@ their whole deposit by providing the decryption, but in a way that delays everyo Cryptographic design -------------------- -The time-lock features are supported by the Tezos_crypto.Timelock `library `__. +The time-lock features are supported by the Tezos_crypto.Timelock :package-api:`library `. Users first generate a RSA modulus and a symmetric encryption key. They use authenticated encryption to encrypt a packed Michelson value (an array of bytes computed with ``PACK``) -- GitLab