diff --git a/docs/CHANGES.rst b/docs/CHANGES.rst index 1b700c7444ffdf329d669dbe0cacbbfded024268..cdec17e4399fc8dcf795340c62d7ade1484cec31 100644 --- a/docs/CHANGES.rst +++ b/docs/CHANGES.rst @@ -3042,7 +3042,7 @@ Node - Changed signal handling and exit codes for most binaries. The codes’ significance are detailed in `the user - documentation `__. + documentation `__. - Command ``octez-node --version`` now exits with exit code 0 instead of 1. diff --git a/docs/alpha/smart_rollups.rst b/docs/alpha/smart_rollups.rst index a300c8d873f858006328d799c4ee62973a1fba2e..53f86ab0de745e1812ea9cd2e3f05099c0004aaf 100644 --- a/docs/alpha/smart_rollups.rst +++ b/docs/alpha/smart_rollups.rst @@ -134,7 +134,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“, these internal messages does not +level”. Similarly to “Start of level“, this internal message does not come with any payload. .. _reveal_data_channel_smart_rollups_alpha: @@ -155,7 +155,7 @@ A rollup can do the following requests through the reveal data channel: #. **metadata requests** The rollup can request information from the protocol, namely the address and the origination level of the - rollup node itself. The rollup node retrieves this information + rollup itself. The rollup node retrieves this information through RPCs to answer the rollup. Information passing through the reveal data channel does not have to @@ -211,11 +211,16 @@ A **commitment** claims that the interpretation of all inbox messages published during a given commitment period, and applied on the state of a parent commitment, led to a given new state by performing a given number of execution steps of the PVM. Execution steps are called -**ticks** in Smart Rollups terminology. A commitment must be -published on the Layer 1 after each commitment period to have the rollup -progress. A commitment is always based on a parent commitment (except +**ticks** in Smart Rollups terminology. + +A commitment must be +published on the Layer 1 any time after each commitment period, to have the rollup +progress. +A new commitment period starts right after the previous commitment period, no matter if commitments were published or not for the previous commitment period(s). +For example, if an operator rollup node stops running for one day long, when it comes back, it will be able to resume publishing commitments for the passed periods, in chronological order. +Indeed, a commitment is always based on a parent commitment (except for the genesis commitment that is automatically published at -origination time). +origination time), so publishing a commitment fails if the parent commitment has not yet been published. Since the PVM is deterministic and the inputs are completely determined by the Layer 1 rollups inbox and the reveal channel, there @@ -236,7 +241,7 @@ the commitment will be published with two stakes on it. A commitment is optimistically trusted but it can be refuted until it is said to be **cemented** (i.e., final, unchangeable). Indeed, right -after a commitment is published, a two-weeks refutation period +after a commitment is published, a two-week refutation period starts. During the refutation period, anyone noticing that a commitment for a given commitment period is invalid can post a concurrent commitment for the same commitment period to force the @@ -363,9 +368,8 @@ Glossary commitment. A commitment must be published for each commitment period. -#. **Refutation period**: At the end of each commitment period, a - period of two weeks starts to allow any commitment related to - this commitment period to be challenged. +#. **Refutation period**: When the first commitment for a commitment period is published, a refutation + period of two weeks starts to allow this commitment to be challenged. #. **Staker**: An implicit account that has made a deposit on a commitment. diff --git a/docs/introduction/howtoget.rst b/docs/introduction/howtoget.rst index b63a269adddd9da22aad00562007a52c2e656f7a..cb63eb06746ba8541cbdbb33032f5c421ce0b0ac 100644 --- a/docs/introduction/howtoget.rst +++ b/docs/introduction/howtoget.rst @@ -72,7 +72,7 @@ Ubuntu Launchpad PPA with Octez packages ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ If you're using Ubuntu, you can install packages with Octez binaries from a Launchpad PPA. -Currently it supports Focal and Bionic versions. +Currently it supports Jammy and Focal versions. In order to add the stable release PPA repository to your machine, do: @@ -106,7 +106,7 @@ Fedora Copr repository with Octez packages ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ If you're using Fedora, you can install packages with Octez binaries from a Copr repository. -Currently it supports Fedora 35. +Currently it supports Fedora 37 and 38. In order to add the stable Copr repository to your machine, do: @@ -249,9 +249,8 @@ Environment ~~~~~~~~~~~ Currently Octez is being developed for Linux x86_64, mostly for -Debian/Ubuntu and Arch Linux. The following OSes are also reported to -work: macOS (x86_64), Arch Linux ARM (aarch64), Debian Linux (bullseye), -Ubuntu Linux (focal). A Windows port is feasible and might be +Ubuntu and Fedora Linux. The following OSes are also reported to +work: macOS (x86_64), Arch Linux ARM (aarch64), Debian Linux (x86_64). A Windows port is feasible and might be developed in the future. .. note:: diff --git a/docs/introduction/howtouse.rst b/docs/introduction/howtouse.rst index 109a7695d556b6e24462eaf5274d64f497321f22..7d8c77dd2fd3961d82834cc999e2c8cebe4dfd25 100644 --- a/docs/introduction/howtouse.rst +++ b/docs/introduction/howtouse.rst @@ -21,8 +21,8 @@ After a successful compilation, you should have the following binaries: - ``octez-{baker,accuser}-*``: daemons to bake and accuse on the Tezos network (see :doc:`howtorun`); - ``octez-signer``: a client to remotely sign operations or blocks (see :ref:`signer`); -- ``octez-smart-rollup-{client,node}-*``: executables for using and running a smart rollup as Layer 2 (see :doc:`../active/smart_rollups`) -- ``octez-smart-rollup-wasm-debugger``: debugger for smart rollup kernels (see :doc:`../active/smart_rollups`) +- ``octez-smart-rollup-node``: executable for using and running a smart rollup node as Layer 2 (see :doc:`../shell/smart_rollup_node`); +- ``octez-smart-rollup-wasm-debugger``: debugger for smart rollup kernels (see :doc:`../shell/smart_rollup_node`) - ``octez-proxy-server``: a readonly frontend to ``octez-node`` designed to lower the load of full nodes (see :doc:`../user/proxy-server`) - ``octez-codec``: a utility for documenting the data encodings and for performing data encoding/decoding (see `Codec`_) - ``octez-protocol-compiler``: a domain-specific compiler for Tezos protocols (see `Protocol compiler`_) @@ -37,7 +37,7 @@ of the development protocol. The ``octez-node`` daemon is not suffixed by any protocol name, because it is independent of the economic protocol. See also the `Node's Protocol`_ section below. -Read The Manual +Read the Manual --------------- All the Octez binaries provide the ``--help`` option to display information about their usage, including the available options and the possible parameters. @@ -51,7 +51,7 @@ It is also possible to get information on a specific command in the manual with octez-client man set -To see the usage of one specific command, you may also type the command without arguments, which display its possible completions and options:: +To see the usage of one specific command, you may also type the command without arguments, which displays its possible completions and options:: octez-client transfer @@ -95,12 +95,12 @@ The gossip network is where all Tezos nodes exchange blocks and operations with each other (see :ref:`octez-admin-client` to monitor p2p connections). Using this peer-to-peer network, an operation originated by a user can -hop several times through other nodes until it finds its way in a +hop several times through other nodes until it finds its way into a block baked by a baker. Using the blocks it receives on the gossip network the node also keeps up to date the current *context*, that is the full state of the blockchain shared by all peers. -Approximately every 30 seconds a new block is created and, when the node +Approximately every 15 seconds a new block is created and, when the node receives it, it applies each operation in the block to its current context and computes a new context. The last block received on a chain is also called the *head* of that @@ -225,7 +225,7 @@ The list of configurable options can be obtained using the following command:: You can read more about the :doc:`node configuration <../user/node-configuration>` and its :ref:`private mode `. -Besides listening from requests from the client, +Besides listening to requests from the client, the node listens to connections from peers, by default on port ``9732`` (this can be changed using option ``--net-addr``), so it's advisable to open incoming connections to that port. @@ -271,7 +271,7 @@ protocol run by the node. For instance, ``get timestamp`` isn't available when the node runs the genesis protocol, which may happen for a few minutes when launching a node for the first time. -The behaviour of the client can be customized using various mechanims, including command-line options, a configuration file, and environment variables. For details, refer to :doc:`../user/setup-client`. +The behaviour of the client can be customized using various mechanisms, including command-line options, a configuration file, and environment variables. For details, refer to :doc:`../user/setup-client`. A Simple Wallet ~~~~~~~~~~~~~~~ @@ -414,7 +414,7 @@ Fees are variable over time and depend on many factors but the Octez client selects a default for us. The last important bit of our receipt is the balance updates that -resume which address is being debited or credited of a certain amount. +resume which address is being debited or credited a certain amount. We see in this case that baker ``tz1Ke...yU`` is being credited one fee for each operation, that Bob's address ``tz1Rk...Ph`` gets 1 tez and that Alice pays the transfer, the burn, and the two fees. @@ -450,7 +450,7 @@ In Tezos there are two kinds of accounts: *implicit accounts* and *smart contrac - The implicit accounts are the addresses starting with *tz1*, *tz2*, and *tz3* we have used up to now. They are created with a transfer - operation to the account public key hash. + operation to the account's public key hash. - Smart contracts have addresses starting with *KT1* and are created with an origination operation. They don't have a corresponding @@ -469,7 +469,7 @@ The initial balance is ꜩ1, generously provided by implicit account Michelson value ``"hello"`` as initial storage (the extra quotes are needed to avoid shell expansion). The parameter ``--burn-cap`` specifies the maximal fee the user is willing to pay for this -operation, the actual fee being determined by the system. +operation, while the actual fee is determined by the system. A Michelson contract is expressed as a pure function, mapping a pair ``(parameter, storage)`` to a pair ``(list_of_operations, storage)``. @@ -519,7 +519,7 @@ To store more we'll need to pay more, you can try by passing a longer string. The other cost associated with running contracts is the *gas*, which -measures *how long* does a program take to compute. +measures *how long* a program takes to compute. Contrary to storage there is no cost per gas unit, a transfer can require as much gas as it wants, however a baker that has to choose among several transactions is much more likely to include a low gas @@ -622,12 +622,12 @@ An interesting block receipt is the one produced at the end of a cycle as many delegates receive back part of their unfrozen accounts. -You can find more info in the :doc:`RPCs' page <../active/rpc>`. +You can find more info on RPCs in the :doc:`RPCs' page <../active/rpc>`. Other binaries -------------- -In this short tutorial we will not use some other binaries, but let as briefly review their roles. +In this short tutorial we will not use some other binaries, but let's briefly review their roles. .. _octez-admin-client: diff --git a/docs/nairobi/smart_rollups.rst b/docs/nairobi/smart_rollups.rst index 840f4a527d0e297a55ffd489d38393699c30b934..67007ad7c90eb728a011c6343e1ab75b7ce783a8 100644 --- a/docs/nairobi/smart_rollups.rst +++ b/docs/nairobi/smart_rollups.rst @@ -14,7 +14,7 @@ rollups, allowing to increase the throughput of the Tezos blockchain, (almost) arbitrarily. The purpose of this documentation is to provide an overview of the terminology and basic principles of smart rollups. -In the :doc:`../shell/smart_rollup_node`, we will provide a complete tour +In the :doc:`../shell/smart_rollup_node`, we will provide a complete tour of smart rollups related workflows and reference documentation for the development of a WASM kernel. The integration of these rollups in the Tezos protocol is @@ -208,11 +208,14 @@ A **commitment** claims that the interpretation of all inbox messages published during a given commitment period and applied on the state of a parent commitment led to a given new state by performing a given number of execution steps of the PVM. Execution steps are called -**ticks** in the smart rollups terminology. A commitment must be -published on the Layer 1 after each commitment period to have the rollup -progress. A commitment is always based on a parent commitment (except +**ticks** in the smart rollups terminology. + +A commitment must be published on the Layer 1 any time after each commitment period, to have the rollup progress. +A new commitment period starts right after the previous commitment period, no matter if commitments were published or not for the previous commitment period(s). +For example, if an operator rollup node stops running for one day long, when it comes back, it will be able to resume publishing commitments for the passed periods, in chronological order. +Indeed, a commitment is always based on a parent commitment (except for the genesis commitment that is automatically published at -origination time). +origination time), so publishing a commitment fails if the parent commitment has not yet been published. Since the PVM is deterministic and the inputs are completely determined by the Layer 1 rollups inbox and the reveal channel, there @@ -326,9 +329,8 @@ Glossary commitment. A commitment must be published for each commitment period. -#. **Refutation period**: At the end of each commitment period, a - period of two weeks starts to allow any commitment related to - this commitment period to be challenged. +#. **Refutation period**: When the first commitment for a commitment period is published, a refutation + period of two weeks starts to allow this commitment to be challenged. #. **Staker**: An implicit account that has made a deposit on a commitment. diff --git a/docs/oxford/smart_rollups.rst b/docs/oxford/smart_rollups.rst index e6451a1395e27e1324084bf0397ce0b7c638a5b2..5f7c63b5406f83e4c16396c79112c559c72b668f 100644 --- a/docs/oxford/smart_rollups.rst +++ b/docs/oxford/smart_rollups.rst @@ -211,11 +211,16 @@ A **commitment** claims that the interpretation of all inbox messages published during a given commitment period, and applied on the state of a parent commitment, led to a given new state by performing a given number of execution steps of the PVM. Execution steps are called -**ticks** in Smart Rollups terminology. A commitment must be -published on the Layer 1 after each commitment period to have the rollup -progress. A commitment is always based on a parent commitment (except +**ticks** in Smart Rollups terminology. + +A commitment must be +published on the Layer 1 any time after each commitment period, to have the rollup +progress. +A new commitment period starts right after the previous commitment period, no matter if commitments were published or not for the previous commitment period(s). +For example, if an operator rollup node stops running for one day long, when it comes back, it will be able to resume publishing commitments for the passed periods, in chronological order. +Indeed, a commitment is always based on a parent commitment (except for the genesis commitment that is automatically published at -origination time). +origination time), so publishing a commitment fails if the parent commitment has not yet been published. Since the PVM is deterministic and the inputs are completely determined by the Layer 1 rollups inbox and the reveal channel, there @@ -363,9 +368,8 @@ Glossary commitment. A commitment must be published for each commitment period. -#. **Refutation period**: At the end of each commitment period, a - period of two weeks starts to allow any commitment related to - this commitment period to be challenged. +#. **Refutation period**: When the first commitment for a commitment period is published, a refutation + period of two weeks starts to allow this commitment to be challenged. #. **Staker**: An implicit account that has made a deposit on a commitment. diff --git a/docs/shell/smart_rollup_node.rst b/docs/shell/smart_rollup_node.rst index 4db7b180844886a938abd03d3cf4b9aa08d2c5ce..90518539fe2e4f57ac7fa9c0186c53dad437aa6c 100644 --- a/docs/shell/smart_rollup_node.rst +++ b/docs/shell/smart_rollup_node.rst @@ -43,7 +43,7 @@ in a terminal where ``${NETWORK}`` is of the form ``https://teztnets.xyz/dailynet-YYYY-MM-DD`` and ``${ONODE_DIR}`` is a path for the Octez node store, by default ``~/.tezos-node``. -The commands will only work when the node is completely boostrapped, and therefore the current protocol on the target network is activated. +The commands will only work when the node is completely bootstrapped, and therefore the current protocol on the target network is activated. This can be checked by: .. code:: sh @@ -217,7 +217,7 @@ In addition, a rollup node can run under different modes: operation when the operator is no longer staked on any commitment. If the node detects that this operation has been successful, it can gratefully exit. -#. ``custom`` mode refers to a mode where the users individually selects which +#. ``custom`` mode refers to a mode where the users individually select which kinds of operations the rollup node injects. It provides tailored control and flexibility customized to specific requirements, and is mostly used for tests. @@ -334,7 +334,7 @@ Archive mode When configured in *archive* mode, a rollup node will keep all history since the origination of the rollup. This mode can be useful for applications that require to regularly access historical data before the LCC, -i.e. for application that need more than two weeks of history. +i.e. for applications that need more than two weeks of history. This mode can be chosen e.g. on the command line with ``--history-mode archive``. @@ -365,7 +365,7 @@ representation of the message payload, one can do: to inject such an external message, where ``${PROTO_HASH}`` is the hash of your protocol (e.g. ``ProtoALphaAL`` for Alpha; see :ref:`how to obtain it `). -So let us focus now on producing a viable content for ``${EMESSAGE}``. +So let us focus now on producing 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. @@ -521,7 +521,7 @@ Populating the reveal channel """"""""""""""""""""""""""""" It is the responsibility of rollup node operators to get the data -passed through the reveal data channel when the rollup requested it. +passed through the reveal data channel when the rollup requests it. To answer a request for a page of hash ``H``, the rollup node tries to read the content of a file ``H`` named @@ -646,7 +646,7 @@ The rest of the section proceeds as follows. #. First, we explain the execution environment of a WASM kernel: when it is parsed, executed, etc. -#. Then, we explain in more details the API at the disposal of WASM +#. Then, we explain in more detail the API at the disposal of WASM kernel developers. #. Finally, we demonstrate how Rust in particular can be used to implement a WASM kernel. @@ -730,7 +730,7 @@ When a new block is published on Tezos, the inbox exposed to the smart rollup is populated with all the inputs published on Tezos in this block. It is important to keep in mind that all the smart rollups which are originated on Tezos share the same inbox. As a consequence, -a WASM kernel has to filter the inputs that are relevant for its +a WASM kernel has to filter the inputs that are relevant to its purpose from the ones it does not need to process. Once the inbox has been populated with the inputs of the Tezos block, @@ -884,7 +884,7 @@ conveying errors, as shown in the next table. ======= ======================================================================================================= 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. @@ -897,8 +897,10 @@ WASM as a first class citizen when it comes to compilation targets, but its approach to memory safety eliminates large classes of bugs and vulnerabilities that arbitrary WASM programs may suffer from. +Additionally there is support for implementing kernels in Rust, in the form of the `Smart Rollup Kernel SDK `__. + Setting-up Rust -""""""""""""""" +~~~~~~~~~~~~~~~ `rustup `_ is the standard way to get Rust. Once ``rustup`` is installed, enabling WASM as a compilation target is as @@ -910,7 +912,7 @@ simple as running the following command. Rust also proposes the ``wasm64-unknown-unknown`` compilation target. This target is **not** compatible with Tezos smart rollups, -which only provides a 32bit address space. +which only provide a 32bit address space. .. note:: @@ -993,7 +995,7 @@ deploy in our rollup. For instance, our “noop” kernel weighs kernel (down to 115 bytes in our case). Host Functions in Rust -"""""""""""""""""""""" +~~~~~~~~~~~~~~~~~~~~~~ The host functions exported by the WASM runtime to Rust programs are exposed by the following API. The ``link`` pragma is used to specify the @@ -1334,7 +1336,7 @@ take care of the possible reboots asked by the kernel (through the usage of the Internal state: Collect To obtain more information on the execution, the command ``profile`` will also run -the kernel on a full inbox, consumed all inputs, run until more inputs are +the kernel on a full inbox, consume all inputs, run until more inputs are required, and output some information about the run. .. code:: @@ -1398,7 +1400,7 @@ 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 by tick (using the ``step tick`` command), it is -possible to end up in a situation were the evaluation stops on ``Waiting for +possible to end up in a situation where 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 preimage of a given hash, there are two possible solutions: