From a41993ab38366b9ecefefab1bdfa3cd7f8343208 Mon Sep 17 00:00:00 2001 From: Nic Volanschi Date: Fri, 24 Feb 2023 14:27:18 +0100 Subject: [PATCH 01/14] doc: fix address of ledger in key-management.rst --- docs/user/key-management.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/user/key-management.rst b/docs/user/key-management.rst index 51dc207f5f37..2538cf322a19 100644 --- a/docs/user/key-management.rst +++ b/docs/user/key-management.rst @@ -63,17 +63,17 @@ in the Tezos Wallet app):: ./octez-client list connected ledgers -You can follow the instructions to import the Ledger encrypted private key and +This will display some instructions to import the Ledger encrypted private key, and you can choose between the root or a derived address. -We can confirm the addition by listing known addresses:: +We can follow the instructions and then confirm the addition by listing known addresses:: - ./octez-client import secret key my_ledger ledger://tz1XXXXXXXXXX + ./octez-client import secret key my_ledger ledger://XXXXXXXXXX ./octez-client list known addresses Optional: we can check that our Ledger signs correctly using the following command and confirming on the device:: - octez-client show ledger path ledger://tz1XXXXXXXXXX + octez-client show ledger ledger://XXXXXXXXXX The address can now be used as any other with the exception that during an operation the device will prompt you to confirm when it's -- GitLab From a01a41fd3dca2016a916d7447e9ee5d84fb544dc Mon Sep 17 00:00:00 2001 From: Arvid Jakobsson Date: Mon, 27 Feb 2023 15:28:39 +0100 Subject: [PATCH 02/14] doc: fix error in smart_rollups.rst It should be an Octez node, not rollup node. --- docs/alpha/smart_rollups.rst | 2 +- docs/mumbai/smart_rollups.rst | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/alpha/smart_rollups.rst b/docs/alpha/smart_rollups.rst index 2fcee9dda642..25e817977405 100644 --- a/docs/alpha/smart_rollups.rst +++ b/docs/alpha/smart_rollups.rst @@ -309,7 +309,7 @@ docker images or can be compiled from sources. Please refer to the for installation details. An Octez rollup node needs an Octez node to run. We assume that -a rollup node has been launched locally, typically by issuing: +an Octez node has been launched locally, typically by issuing: .. code:: sh diff --git a/docs/mumbai/smart_rollups.rst b/docs/mumbai/smart_rollups.rst index 6cd5842ccf8b..034a2cb1e7dc 100644 --- a/docs/mumbai/smart_rollups.rst +++ b/docs/mumbai/smart_rollups.rst @@ -298,7 +298,7 @@ Prerequisites ^^^^^^^^^^^^^ An Octez rollup node needs an Octez node to run. We assume that -a rollup node has been launched locally, typically by issuing: +an Octez node has been launched locally, typically by issuing: .. code:: sh -- GitLab From f3260941214706f2292235f932ae2f0932af2011 Mon Sep 17 00:00:00 2001 From: Arvid Jakobsson Date: Mon, 27 Feb 2023 15:30:00 +0100 Subject: [PATCH 03/14] doc: fix spelling error DailyNet => Dailynet --- docs/alpha/smart_rollups.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/alpha/smart_rollups.rst b/docs/alpha/smart_rollups.rst index 25e817977405..a0e036c152d5 100644 --- a/docs/alpha/smart_rollups.rst +++ b/docs/alpha/smart_rollups.rst @@ -300,10 +300,10 @@ Prerequisites To experiment with the commands described in this section, we use the `Dailynet `_. In this section, we assume that ``${OPERATOR_ADDR}`` is a valid -implicit account on DailyNet owned by the reader. +implicit account on Dailynet owned by the reader. Notice that you need a specific development version of Octez to -participate to DailyNet. This version is either available from +participate to Dailynet. This version is either available from docker images or can be compiled from sources. Please refer to the `Dailynet `_ website for installation details. -- GitLab From 9052ee9f19c5d75aac0d73cdb70a1f3df8349952 Mon Sep 17 00:00:00 2001 From: Nic Volanschi Date: Tue, 28 Feb 2023 17:31:15 +0100 Subject: [PATCH 04/14] doc: gitignore generated manual for proxy-server --- docs/.gitignore | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/.gitignore b/docs/.gitignore index a2610d4c705c..8a4bf0506d40 100644 --- a/docs/.gitignore +++ b/docs/.gitignore @@ -7,6 +7,7 @@ octez-client.html /api/octez-admin-client.html /api/octez-signer.html /api/octez-node.txt +/api/octez-proxy-server.txt /alpha/rpc.rst /shell/rpc.rst -- GitLab From 58fdcd53dde86150eac1f59c96ac6f7f1eba369e Mon Sep 17 00:00:00 2001 From: Nic Volanschi Date: Fri, 3 Mar 2023 15:32:24 +0100 Subject: [PATCH 05/14] doc: fix typos in key_management --- docs/user/node-configuration.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/user/node-configuration.rst b/docs/user/node-configuration.rst index afe37bc84396..f7c7a82d9352 100644 --- a/docs/user/node-configuration.rst +++ b/docs/user/node-configuration.rst @@ -305,7 +305,7 @@ Note that the IP address is only used for selecting an active network interface (technically, it is only passed to the ``bind()`` function of the socket API). It is also possible to advertise to peers a different port than the binding port using ``--advertised-net-port`` configuration option or the P2P -`advertised-net-port`` configuration parameter. Currently it is only possible to +``advertised-net-port`` configuration parameter. Currently it is only possible to specify an advertised port, but not an IP address. .. note:: @@ -314,7 +314,7 @@ specify an advertised port, but not an IP address. subject to NAT, a port forwarding rule has to be added on the NAT server ``S`` on the listening port towards machine ``M``: ``S:p1 -> M:p2``, where ``p1`` is ``advertised-net-port`` and - ``p2`` is the port specified by ``listening-addr``. Alternatively, if the + ``p2`` is the port specified by ``listen-addr``. Alternatively, if the ``advertised-net-port`` is not configured, ``p1`` must be the same as ``p2``. As a consequence, if a second node has to be run behind the -- GitLab From fa9236841f9a58168e11757c62510fb34eb07926 Mon Sep 17 00:00:00 2001 From: Nic Volanschi Date: Fri, 3 Mar 2023 15:33:05 +0100 Subject: [PATCH 06/14] doc: add option to test signature onledger --- docs/user/key-management.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/user/key-management.rst b/docs/user/key-management.rst index 2538cf322a19..a9f91f4be96f 100644 --- a/docs/user/key-management.rst +++ b/docs/user/key-management.rst @@ -73,7 +73,7 @@ We can follow the instructions and then confirm the addition by listing known ad Optional: we can check that our Ledger signs correctly using the following command and confirming on the device:: - octez-client show ledger ledger://XXXXXXXXXX + octez-client show ledger ledger://XXXXXXXXXX --test-sign The address can now be used as any other with the exception that during an operation the device will prompt you to confirm when it's -- GitLab From eb3adb8e7478181b8096535dbde008b28bfcdbdd Mon Sep 17 00:00:00 2001 From: Nic Volanschi Date: Mon, 13 Mar 2023 18:04:01 +0200 Subject: [PATCH 07/14] doc: warn users that storage reconstruction may last weeks --- docs/user/history_modes.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/user/history_modes.rst b/docs/user/history_modes.rst index 32886dbe155a..3ca7c89f04d5 100644 --- a/docs/user/history_modes.rst +++ b/docs/user/history_modes.rst @@ -257,4 +257,4 @@ there are some restrictions when switching from one mode to another. (*) Switching from a ``full`` node to an ``archive`` one is possible using the ``reconstruct`` feature. To do so, run ``octez-node reconstruct`` on your node. Note that the storage reconstruction is a -long process that, on the main network, may requires days to complete. +long process that, on the main network, may require days (or weeks) to complete. -- GitLab From 0a5c2df80db2bdd2dd3aaf3ff3adbe620f94761f Mon Sep 17 00:00:00 2001 From: Nic Volanschi Date: Wed, 15 Mar 2023 11:23:21 +0200 Subject: [PATCH 08/14] doc: fix a few broken links --- docs/alpha/glossary.rst | 2 +- docs/developer/merkle-proof-encoding-formats.rst | 2 +- docs/developer/testing.rst | 4 ++-- docs/lima/glossary.rst | 2 +- docs/mumbai/glossary.rst | 2 +- 5 files changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/alpha/glossary.rst b/docs/alpha/glossary.rst index 76c2e36b6bfa..8c2519999f4e 100644 --- a/docs/alpha/glossary.rst +++ b/docs/alpha/glossary.rst @@ -163,7 +163,7 @@ _`Layer 2` the security of the L1 chain backs those operations. In Tezos there are a number of layer 2 solutions, including :doc:`Smart Optimistic Rollups `, validity or ZK-Rollups `Epoxy `_ , - zkChannels, and sidechains such as `Deku `_. + zkChannels, and sidechains such as `Deku `_. _`Michelson` The built-in language used by a `smart contract`_. diff --git a/docs/developer/merkle-proof-encoding-formats.rst b/docs/developer/merkle-proof-encoding-formats.rst index 128fa44bdd26..2e687f02e8e7 100644 --- a/docs/developer/merkle-proof-encoding-formats.rst +++ b/docs/developer/merkle-proof-encoding-formats.rst @@ -12,7 +12,7 @@ This document shows the encoding format of the Merkle proof implemented in :src: There are 2 versions of encodings (defined as V1 and V2), each generating 2 types of Merkle proofs (named tree_proof and stream_proof), for 2 types of Irmin Trees (32-tree and binary tree). The data structure is defined in -:src:`src/lib_context/sigs/context.ml` (`API `_) as below. +:src:`src/lib_context/sigs/context.ml` (:package-api:`API `) as below. The internal structure of Irmin, which is used to manage contexts in Octez, appears in it. Encoding formats give the conversion between a ``tree_proof`` and a byte sequence, and between a ``stream_proof`` and a byte sequence. diff --git a/docs/developer/testing.rst b/docs/developer/testing.rst index 39eabb89d9af..f15980473391 100644 --- a/docs/developer/testing.rst +++ b/docs/developer/testing.rst @@ -195,8 +195,8 @@ Example tests: References: - :doc:`Section in Tezos Developer Documentation on Tezt ` - - `General API documentation `_ - - `Octez-specific API documentation `_ + - `General API documentation `__ + - :package-api:`Octez-specific API documentation ` .. _long_tezt_section: diff --git a/docs/lima/glossary.rst b/docs/lima/glossary.rst index 4df1f6844fac..b04a3ec4fb65 100644 --- a/docs/lima/glossary.rst +++ b/docs/lima/glossary.rst @@ -159,7 +159,7 @@ _`Layer 2` including :doc:`TORUs (Transaction Optimistic Rollups) `, `Smart Optimistic Rollups`_, validity or ZK-Rollups `Epoxy `_ , - zkChannels, and sidechains such as `Deku `_. + zkChannels, and sidechains such as `Deku `_. _`Michelson` The built-in language used by a `smart contract`_. diff --git a/docs/mumbai/glossary.rst b/docs/mumbai/glossary.rst index aa87e81ad1dd..13e8ed3b1670 100644 --- a/docs/mumbai/glossary.rst +++ b/docs/mumbai/glossary.rst @@ -159,7 +159,7 @@ _`Layer 2` including :doc:`TORUs (Transaction Optimistic Rollups) `, `Smart Optimistic Rollups`_, validity or ZK-Rollups `Epoxy `_ , - zkChannels, and sidechains such as `Deku `_. + zkChannels, and sidechains such as `Deku `_. _`Michelson` The built-in language used by a `smart contract`_. -- GitLab From 84f92bb982871a1dca186b7885c00c1c23661884 Mon Sep 17 00:00:00 2001 From: Victor Dumitrescu Date: Thu, 16 Mar 2023 10:16:01 +0100 Subject: [PATCH 09/14] Doc: more details about node reconstruction --- docs/user/history_modes.rst | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/docs/user/history_modes.rst b/docs/user/history_modes.rst index 3ca7c89f04d5..fd8cb35141ff 100644 --- a/docs/user/history_modes.rst +++ b/docs/user/history_modes.rst @@ -257,4 +257,7 @@ there are some restrictions when switching from one mode to another. (*) Switching from a ``full`` node to an ``archive`` one is possible using the ``reconstruct`` feature. To do so, run ``octez-node reconstruct`` on your node. Note that the storage reconstruction is a -long process that, on the main network, may require days (or weeks) to complete. +long process that, on the main network, may require more than a week to +complete. Reconstruction also requires a machine with at least 16GB of +memory (for the flattening of the context storage operation) and takes up +about 1TB of storage once completed. -- GitLab From f6853f9c827cb2d2d6e77229f9331d8d8afdb69e Mon Sep 17 00:00:00 2001 From: Victor Dumitrescu Date: Mon, 20 Mar 2023 10:58:02 +0100 Subject: [PATCH 10/14] Doc: fix typos in Michelson docs --- docs/alpha/michelson.rst | 2 +- docs/lima/michelson.rst | 2 +- docs/mumbai/michelson.rst | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/alpha/michelson.rst b/docs/alpha/michelson.rst index 9aeb0c6b472e..8ec924f29d95 100644 --- a/docs/alpha/michelson.rst +++ b/docs/alpha/michelson.rst @@ -48,7 +48,7 @@ tokens (and be the destinations of transactions). From Michelson, they are indistinguishable. A safe way to think about this is to consider that implicit accounts are smart contracts that -always succeed to receive tokens, and does nothing else. +always succeed in receiving tokens, and do nothing else. Finally, addresses prefixed with ``sr1`` identify :doc:`smart rollups <./smart_rollups>`. diff --git a/docs/lima/michelson.rst b/docs/lima/michelson.rst index 5a8dd500ed84..d0f04819698e 100644 --- a/docs/lima/michelson.rst +++ b/docs/lima/michelson.rst @@ -49,7 +49,7 @@ tokens (and be the destinations of transactions). From Michelson, they are indistinguishable. A safe way to think about this is to consider that implicit accounts are smart contracts that -always succeed to receive tokens, and does nothing else. +always succeed in receiving tokens, and do nothing else. Another kind of addresses, prefixed by ``txr1`` and ``tz4``, are related to :doc:`transaction rollups <./transaction_rollups>`. diff --git a/docs/mumbai/michelson.rst b/docs/mumbai/michelson.rst index f211511ceff8..3c5c0300ee83 100644 --- a/docs/mumbai/michelson.rst +++ b/docs/mumbai/michelson.rst @@ -48,7 +48,7 @@ tokens (and be the destinations of transactions). From Michelson, they are indistinguishable. A safe way to think about this is to consider that implicit accounts are smart contracts that -always succeed to receive tokens, and does nothing else. +always succeed in receiving tokens, and do nothing else. Another kind of addresses, prefixed by ``txr1``, are related to :doc:`transaction rollups <./transaction_rollups>`. -- GitLab From b28550300f459faa109301b85c64adbe02e6df76 Mon Sep 17 00:00:00 2001 From: Victor Dumitrescu Date: Mon, 20 Mar 2023 14:40:34 +0100 Subject: [PATCH 11/14] Doc: fix typos in SCORU docs --- docs/alpha/smart_rollups.rst | 49 ++++++++++++++++------------------- docs/mumbai/smart_rollups.rst | 49 ++++++++++++++++------------------- 2 files changed, 46 insertions(+), 52 deletions(-) diff --git a/docs/alpha/smart_rollups.rst b/docs/alpha/smart_rollups.rst index a0e036c152d5..f36c1affc25b 100644 --- a/docs/alpha/smart_rollups.rst +++ b/docs/alpha/smart_rollups.rst @@ -273,7 +273,7 @@ two players can last at most 2 weeks. There is no timeout for starting a refutation game after having published a concurrent commitment. However, assuming the existence of -a honest participant, she will start the refutation game with all +an honest participant, she will start the refutation game with all concurrent stakers to avoid the rollup being stuck. Workflows @@ -471,8 +471,7 @@ In addition, a rollup node can run under different modes: inboxes, updating the states, publishing and cementing commitments regularly, and playing the refutation games. In this mode, the rollup node will accept transactions in its queue and batch them on - the Layer 1. It does not include the message batching service, - either. + the Layer 1. #. ``batcher`` means that the rollup node will accept transactions in its queue and batch them on the Layer 1. In this mode, the rollup @@ -480,12 +479,10 @@ In addition, a rollup node can run under different modes: and does not reconstruct inboxes. Consequently, it does not publish commitments nor play refutation games. - #. ``observer`` means that the rollup node follows the Layer 1 chain to reconstruct inboxes, to update its state. However, it will neither publish commitments, nor play a refutation game. - It does not include the message batching service, either. - + It does not include the message batching service either. #. ``maintenance`` is the same as the operator mode except that it does not include the message batching service. @@ -552,7 +549,7 @@ to inject such an external message. So let us focus now on producing a viable contents for ``${EMESSAGE}``. The kernel used previously in our running example is a simple "echo" -kernel that copies its input as a new message of its outbox. +kernel that copies its input as a new message to its outbox. Therefore, the input must be a valid binary encoding of an outbox message to make this work. Specifically, assuming that we have originated a Layer 1 smart contract as follows: @@ -586,7 +583,7 @@ Triggering the execution of an outbox message Once an outbox message has been pushed to the outbox by the kernel at some level ``${L}``, the user needs to wait for the commitment that includes this level to be cemented. On Dailynet, the cementation -process of a non disputed commitment is 40 blocks long while on +process of a non-disputed commitment is 40 blocks long while on Mainnet, it is 2 weeks long. When the commitment is cemented, one can observe that the outbox is @@ -610,7 +607,7 @@ Here is the output for this command: At this point, the actual execution of a given outbox message can be -triggered. This requires to precompute a proof that this outbox message +triggered. This requires precomputing a proof that this outbox message is indeed in the outbox. In the case of our running example, this proof is retrieved as follows: @@ -756,7 +753,7 @@ More precisely, determinism is ensured by the following restrictions: #. Instructions and types related to floating-point arithmetic are not supported. This is because IEEE floats are not deterministic, as - the standard includes undefined behaviors operations. + the standard includes undefined behavior operations. #. The length of the call stack of the WASM kernel is restricted to 300. Modulo the limitations above, a valid kernel is a WASM module that satisfies the following @@ -765,7 +762,7 @@ constraints: #. It exports a function ``kernel_run`` that takes no argument and returns nothing. #. It declares and exports exactly one memory. -#. It only imports the host functions, exported by the (virtual) +#. It only imports the host functions exported by the (virtual) module ``smart_rollup_core``. For instance, the mandatory example of a ``hello, world!`` kernel is @@ -820,9 +817,9 @@ The rest of the section proceeds as follows. Though Rust has become the primary language whose WASM backend has been tested in the context of smart rollups, the WASM VM has not been -modified in anyway to favor this language. We fully expect that other -mainstream languages like Go for instance are also good candidate to -implement WASM kernels. +modified in any way to favor this language. We fully expect that other +mainstream languages such as Go are also good candidates for +implementing WASM kernels. Execution Environment ^^^^^^^^^^^^^^^^^^^^^ @@ -876,7 +873,7 @@ state. More precisely, the WASM kernel is re-initialized, then ``kernel_run`` is called. By default, the WASM kernel yields when ``kernel_run`` returns. In -this case, the WASM kernel execution is put on hold while the input of +this case, the WASM kernel execution is put on hold while the inputs of the next inbox are being loaded. The inputs that were not consumed by ``kernel_run`` are dropped. ``kernel_run`` can prevent the WASM kernel from yielding by writing arbitrary data under the path @@ -1018,9 +1015,9 @@ Implementing a WASM Kernel in Rust Though WASM is a good fit for efficiently executing computation-intensive, arbitrary programs, it is a low-level, stack-based, memory unsafe language. Fortunately, it was designed to be a compilation target, not a -language whose program would be written directly by developers. +language in which developers would directly write their programs. -Rust has several advantages that makes it a good candidate to write +Rust has several advantages that makes 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 @@ -1297,7 +1294,7 @@ representation of WebAssembly modules) or as a ``.wast`` file (its textual representation), and actually parses and typechecks the kernel before giving it to the PVM. -Besides the kernel file, the debugger can optionally take an input file containing inboxes and a +Beside the kernel file, the debugger can optionally take an input file containing inboxes and a rollup address. The expected contents of the inboxes is a JSON value, with the following schema: @@ -1315,7 +1312,7 @@ with the following schema: ] ] -The contents of the input file is a JSON array of array of inputs, +The contents of the input file is a JSON array of arrays of inputs, which encodes a sequence of inboxes, where an inbox is a set of messages. These inboxes are read in the same order as they appear in the JSON file. For example, here is a valid input file that defines @@ -1362,12 +1359,12 @@ after its origination. Its current state can be inspected with the command Status: Waiting for inputs Internal state: Collect -At start, internally the kernel is in collection mode. It means it is -not executing any WASM code, and initially it is waiting for inputs to -proceed. It needs some inputs to continue its execution. The command +When started, the kernel is in collection mode internally. This means that it is +not executing any WASM code, and is waiting for inputs in order to +proceed. The command ``load inputs`` will load the first inbox from the file given with the -option ``--inputs``, putting ``Start_of_level`` and ``Info_per_level`` (and -``End_of_level``) before (resp. after) these inputs. +option ``--inputs``, putting ``Start_of_level`` and ``Info_per_level`` before +these inputs and ``End_of_level`` after the inputs. .. code:: @@ -1448,7 +1445,7 @@ snapshot internal state, with ``step result``, and inspect the memory at pointer Status: Evaluating Internal state: Snapshot -Once again, note that values from the memory are outputted as is, +Once again, note that values from the memory are output as is, since the representation is internal to WASM. Finally, it is possible to evaluate the whole inbox with ``step inbox``. It will @@ -1512,7 +1509,7 @@ hexadecimal value of the preimage: Metadata are automatically filled with level ``0`` as origination level and the configured smart rollup address (or the default one). -Note that when stepping tick per tick (using the ``step tick`` command), it is +Note that when stepping tick by tick (using the ``step tick`` command), it is possible to end up in a situation were the evaluation stops on ``Waiting for reveal``. If the expected value is a metadata, the command ``reveal metadata`` will give the default metadata to the kernel. If the value expected is the diff --git a/docs/mumbai/smart_rollups.rst b/docs/mumbai/smart_rollups.rst index 034a2cb1e7dc..965a03e74228 100644 --- a/docs/mumbai/smart_rollups.rst +++ b/docs/mumbai/smart_rollups.rst @@ -273,7 +273,7 @@ two players can last at most 2 weeks. There is no timeout for starting a refutation game after having published a concurrent commitment. However, assuming the existence of -a honest participant, she will start the refutation game with all +an honest participant, she will start the refutation game with all concurrent stakers to avoid the rollup being stuck. Workflows @@ -456,8 +456,7 @@ In addition, a rollup node can run under different modes: inboxes, updating the states, publishing and cementing commitments regularly, and playing the refutation games. In this mode, the rollup node will accept transactions in its queue and batch them on - the Layer 1. It does not include the message batching service, - either. + the Layer 1. #. ``batcher`` means that the rollup node will accept transactions in its queue and batch them on the Layer 1. In this mode, the rollup @@ -465,12 +464,10 @@ In addition, a rollup node can run under different modes: and does not reconstruct inboxes. Consequently, it does not publish commitments nor play refutation games. - #. ``observer`` means that the rollup node follows the Layer 1 chain to reconstruct inboxes, to update its state. However, it will neither publish commitments, nor play a refutation game. - It does not include the message batching service, either. - + It does not include the message batching service either. #. ``maintenance`` is the same as the operator mode except that it does not include the message batching service. @@ -537,7 +534,7 @@ to inject such an external message. So let us focus now on producing a viable contents for ``${EMESSAGE}``. The kernel used previously in our running example is a simple "echo" -kernel that copies its input as a new message of its outbox. +kernel that copies its input as a new message to its outbox. Therefore, the input must be a valid binary encoding of an outbox message to make this work. Specifically, assuming that we have originated a Layer 1 smart contract as follows: @@ -571,7 +568,7 @@ Triggering the execution of an outbox message Once an outbox message has been pushed to the outbox by the kernel at some level ``${L}``, the user needs to wait for the commitment that includes this level to be cemented. On Dailynet, the cementation -process of a non disputed commitment is 40 blocks long while on +process of a non-disputed commitment is 40 blocks long while on Mainnet, it is 2 weeks long. When the commitment is cemented, one can observe that the outbox is @@ -595,7 +592,7 @@ Here is the output for this command: At this point, the actual execution of a given outbox message can be -triggered. This requires to precompute a proof that this outbox message +triggered. This requires precomputing a proof that this outbox message is indeed in the outbox. In the case of our running example, this proof is retrieved as follows: @@ -741,7 +738,7 @@ More precisely, determinism is ensured by the following restrictions: #. Instructions and types related to floating-point arithmetic are not supported. This is because IEEE floats are not deterministic, as - the standard includes undefined behaviors operations. + the standard includes undefined behavior operations. #. The length of the call stack of the WASM kernel is restricted to 300. Modulo the limitations above, a valid kernel is a WASM module that satisfies the following @@ -750,7 +747,7 @@ constraints: #. It exports a function ``kernel_run`` that takes no argument and returns nothing. #. It declares and exports exactly one memory. -#. It only imports the host functions, exported by the (virtual) +#. It only imports the host functions exported by the (virtual) module ``smart_rollup_core``. For instance, the mandatory example of a ``hello, world!`` kernel is @@ -805,9 +802,9 @@ The rest of the section proceeds as follows. Though Rust has become the primary language whose WASM backend has been tested in the context of smart rollups, the WASM VM has not been -modified in anyway to favor this language. We fully expect that other -mainstream languages like Go for instance are also good candidate to -implement WASM kernels. +modified in any way to favor this language. We fully expect that other +mainstream languages such as Go are also good candidates for +implementing WASM kernels. Execution Environment ^^^^^^^^^^^^^^^^^^^^^ @@ -861,7 +858,7 @@ state. More precisely, the WASM kernel is re-initialized, then ``kernel_run`` is called. By default, the WASM kernel yields when ``kernel_run`` returns. In -this case, the WASM kernel execution is put on hold while the input of +this case, the WASM kernel execution is put on hold while the inputs of the next inbox are being loaded. The inputs that were not consumed by ``kernel_run`` are dropped. ``kernel_run`` can prevent the WASM kernel from yielding by writing arbitrary data under the path @@ -1003,9 +1000,9 @@ Implementing a WASM Kernel in Rust Though WASM is a good fit for efficiently executing computation-intensive, arbitrary programs, it is a low-level, stack-based, memory unsafe language. Fortunately, it was designed to be a compilation target, not a -language whose program would be written directly by developers. +language in which developers would directly write their programs. -Rust has several advantages that makes it a good candidate to write +Rust has several advantages that makes 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 @@ -1282,7 +1279,7 @@ representation of WebAssembly modules) or as a ``.wast`` file (its textual representation), and actually parses and typechecks the kernel before giving it to the PVM. -Besides the kernel file, the debugger can optionally take an input file containing inboxes and a +Beside the kernel file, the debugger can optionally take an input file containing inboxes and a rollup address. The expected contents of the inboxes is a JSON value, with the following schema: @@ -1300,7 +1297,7 @@ with the following schema: ] ] -The contents of the input file is a JSON array of array of inputs, +The contents of the input file is a JSON array of arrays of inputs, which encodes a sequence of inboxes, where an inbox is a set of messages. These inboxes are read in the same order as they appear in the JSON file. For example, here is a valid input file that defines @@ -1347,12 +1344,12 @@ after its origination. Its current state can be inspected with the command Status: Waiting for inputs Internal state: Collect -At start, internally the kernel is in collection mode. It means it is -not executing any WASM code, and initially it is waiting for inputs to -proceed. It needs some inputs to continue its execution. The command +When started, the kernel is in collection mode internally. This means that it is +not executing any WASM code, and is waiting for inputs in order to +proceed. The command ``load inputs`` will load the first inbox from the file given with the -option ``--inputs``, putting ``Start_of_level`` and ``Info_per_level`` (and -``End_of_level``) before (resp. after) these inputs. +option ``--inputs``, putting ``Start_of_level`` and ``Info_per_level`` before +these inputs and ``End_of_level`` after the inputs. .. code:: @@ -1433,7 +1430,7 @@ snapshot internal state, with ``step result``, and inspect the memory at pointer Status: Evaluating Internal state: Snapshot -Once again, note that values from the memory are outputted as is, +Once again, note that values from the memory are output as is, since the representation is internal to WASM. Finally, it is possible to evaluate the whole inbox with ``step inbox``. It will @@ -1479,7 +1476,7 @@ hexadecimal value of the preimage: Metadata are automatically filled with level ``0`` as origination level and the configured smart rollup address (or the default one). -Note that when stepping tick per tick (using the ``step tick`` command), it is +Note that when stepping tick by tick (using the ``step tick`` command), it is possible to end up in a situation were the evaluation stops on ``Waiting for reveal``. If the expected value is a metadata, the command ``reveal metadata`` will give the default metadata to the kernel. If the value expected is the -- GitLab From 62d916bae07a0c46033387ef0c2d59990646814c Mon Sep 17 00:00:00 2001 From: Nic Volanschi Date: Mon, 20 Mar 2023 17:07:42 +0100 Subject: [PATCH 12/14] doc: remove section on one-shot tests (abandoned) --- docs/developer/long-tezts.rst | 8 -------- 1 file changed, 8 deletions(-) diff --git a/docs/developer/long-tezts.rst b/docs/developer/long-tezts.rst index ffe33651e653..3d8482002796 100644 --- a/docs/developer/long-tezts.rst +++ b/docs/developer/long-tezts.rst @@ -115,14 +115,6 @@ significantly higher than usual. It also defines a graph of this time. This test and its graph are registered in :src:`tezt/long_tests/main.ml`. -One-Shot Tests --------------- - -You may be interested in running some long tests using this framework -on your own branch instead of ``master``. - -Check the documentation of the `PRT one-shot repository `_ - Providing Large Data -------------------- -- GitLab From af34fed7fa0239fd79d2f992c7edd581dc918954 Mon Sep 17 00:00:00 2001 From: Nic Volanschi Date: Mon, 20 Mar 2023 17:09:39 +0100 Subject: [PATCH 13/14] doc: typos in protocol_overview --- docs/alpha/protocol_overview.rst | 2 +- docs/lima/protocol_overview.rst | 2 +- docs/mumbai/protocol_overview.rst | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/alpha/protocol_overview.rst b/docs/alpha/protocol_overview.rst index 15c9bbf06da1..35ee57d36714 100644 --- a/docs/alpha/protocol_overview.rst +++ b/docs/alpha/protocol_overview.rst @@ -132,7 +132,7 @@ 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* -- +safely included in the Tezos blockchain -- and *application* -- that is, how the effects of operations and blocks are taken into account -- for this economic protocol. diff --git a/docs/lima/protocol_overview.rst b/docs/lima/protocol_overview.rst index aeadb802744e..5d2b70544430 100644 --- a/docs/lima/protocol_overview.rst +++ b/docs/lima/protocol_overview.rst @@ -134,7 +134,7 @@ 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* -- +safely included in the Tezos blockchain -- and *application* -- that is, how the effects of operations and blocks are taken into account -- for this economic protocol. diff --git a/docs/mumbai/protocol_overview.rst b/docs/mumbai/protocol_overview.rst index 5e3ee038dc62..4db0e5df7716 100644 --- a/docs/mumbai/protocol_overview.rst +++ b/docs/mumbai/protocol_overview.rst @@ -132,7 +132,7 @@ 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* -- +safely included in the Tezos blockchain -- and *application* -- that is, how the effects of operations and blocks are taken into account -- for this economic protocol. -- GitLab From c9059532ec017e7d652bbd50182dc46bd071bb3a Mon Sep 17 00:00:00 2001 From: Nic Volanschi Date: Tue, 21 Mar 2023 10:52:57 +0100 Subject: [PATCH 14/14] doc: better instructions for updating to v16 --- docs/introduction/howtoget.rst | 2 ++ docs/releases/version-16.rst | 3 +++ 2 files changed, 5 insertions(+) diff --git a/docs/introduction/howtoget.rst b/docs/introduction/howtoget.rst index d5509c00c4bd..5217c9681038 100644 --- a/docs/introduction/howtoget.rst +++ b/docs/introduction/howtoget.rst @@ -586,6 +586,8 @@ You may also activate Bash autocompletion by executing:: Note that if your shell is `zsh`, you may need extra configuration to customize shell completion (refer to the `zsh` documentation). +.. _update_from_sources: + Update ~~~~~~ diff --git a/docs/releases/version-16.rst b/docs/releases/version-16.rst index 593a60b266f4..fa6e7f34834e 100644 --- a/docs/releases/version-16.rst +++ b/docs/releases/version-16.rst @@ -53,6 +53,9 @@ To update from sources:: eval $(opam env) make +Note that, as the minimal required OCaml version is now 4.14.1, you may have to remove the ``_opam/`` directory when updating from Octez v15.1 or older released versions. +See more details :ref:`here `. + If you are using Docker instead, use the ``v16.0`` Docker images of Octez. If you are installing Octez using Opam, note that the minimal required -- GitLab