diff --git a/docs/alpha/smart_rollups.rst b/docs/alpha/smart_rollups.rst index 5ed4f4a686a3a1f4911a4bf09586e767ab74019e..d511504d58217dc7821131a489e2fe91971fc5ac 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,14 +84,14 @@ 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). 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 @@ -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. diff --git a/docs/alpha/timelock.rst b/docs/alpha/timelock.rst index fc0604fec5fb701d2582e910ffba2524eb203b66..8c01135ae6e121e8d24c0c31711d7b1e339d4524 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/api/openapi.rst b/docs/api/openapi.rst index 57490c8123135c8ce903bad9350c7029b0a6f6f0..b6563c49d64f5c220c2fc79af2fdb71bf180fd99 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 ------------ diff --git a/docs/developer/error_monad_p3_advanced.rst b/docs/developer/error_monad_p3_advanced.rst index e9bb6c7e4b78f439c9ad1eddd45cfdc1a2969224..49152860490fc82e9d483313901cea1f36fd8d89 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 7ec7752e4bac7db879907f8cf156b38e18e46d94..a64e211c740a4c10ea81faaaf6a50f12738faf85 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 3d848200279673c530baecdb23e8f35cc969bfe2..eeac39de09e0007a897ada03d388989f759dbd64 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 31e7489889f2ff91ebc904ee083b8bf1ce41b247..5d75f014a3bde222c352bfb996e76928e54f15c1 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``. diff --git a/docs/developer/snoop.rst b/docs/developer/snoop.rst index 9c9b16370d75bb75d24542cd7bf337371a73113d..a571643f58d677e845d9bc09ba7ad4b5b52db6b8 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 0f4fbe35ef3d8221715948a0eef2139dda0575bb..8da2e51de31f3de5c860948b942e6f46d1b026db 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 9fc225ee4c5d0e1f4439dcb1416621cae5817fa9..7b88ba9f1a54b111385f63d187c3bd8e1c4fc307 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 2b9a959a6f3fb0811e8312bcb19c8d92c7e43374..01b1f874fb66661f34b1519804ff1613ac104347 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``) diff --git a/src/lib_node_config/shared_arg.ml b/src/lib_node_config/shared_arg.ml index 3ac0e1c85caf01ad34a6004ffec241c04ebd5d55..9285e02a55ce2550f459dfc39462a2510aca7ceb 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.(