diff --git a/docs/Makefile b/docs/Makefile index aed73db0e7546308eb8a0a94eb669dcad9ce8faf..84c8a9d3330a533adaa9d106dec96e0b29f3eb0e 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -112,7 +112,7 @@ redirectcheck: html # - on each other protocol including alpha, also checking label defs (option -l) xrefscheck: $(CHECKXREFS) mumbai - $(CHECKXREFS) nairobi + $(CHECKXREFS) -l nairobi $(CHECKXREFS) -l alpha scriptsindoccheck: diff --git a/docs/alpha/michelson.rst b/docs/alpha/michelson.rst index fcfb3bb3e050140dfeacf529cd0cd5a90734157e..51b9da1b4578462683a8ad415e45a41b8d65fa8c 100644 --- a/docs/alpha/michelson.rst +++ b/docs/alpha/michelson.rst @@ -1113,6 +1113,8 @@ reject any contract using it. used to authenticate layer-2 operations to transfer tickets from this account. +.. _MichelsonViews_alpha: + Operations on views ~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/alpha/smart_rollups.rst b/docs/alpha/smart_rollups.rst index 30b6e19fae2cfb8bdfa111e8a4ff2b4f6fdde3ca..08a2c43c3fe86e8fa00930972ba103c3339eabd3 100644 --- a/docs/alpha/smart_rollups.rst +++ b/docs/alpha/smart_rollups.rst @@ -107,10 +107,10 @@ sequence of bytes following no particular underlying format. The interpretation of this sequence of bytes is the responsibility of each kernel. -There are two ways for an end-user to push an external message to the -rollups inbox: first, she can inject the dedicated Layer 1 operation +There are two ways for end-users to push an external message to the +rollups inbox: first, they can inject the dedicated Layer 1 operation using the Octez client (see command ``send smart rollup message - from ``); second, she can use the batcher + from ``); second, they can use the batcher of a smart rollup node. More details can be found in :ref:`sending_external_inbox_message_alpha`. Internal messages @@ -205,10 +205,10 @@ Starting from the rollup origination level, levels are partitioned into **commitment periods** of 60 consecutive blocks. 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 +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 +**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 for the genesis commitment that is automatically published at @@ -223,8 +223,8 @@ must be wrong. Notice that, to publish a commitment, an operator must provide a deposit of 10,000 tez. For this reason, the operator is said to be a **staker**. Several users can stake on the same commitment. When a -staker publishes a new commitment based on a commitment she is staking -on, she does not have to provide a new deposit: the deposit also +staker *S* publishes a new commitment based on a commitment that *S* is staking +on, *S* does not have to provide a new deposit: the deposit also applies to this new commitment. There is no need to synchronize between operators: if two honest @@ -280,15 +280,15 @@ given step is PVM-dependent. During the final phase, the stakers must provide a proof that they correctly interpreted this conflicting tick. The Layer 1 PVM then determines whether these proofs are valid. There -are only two possible outcomes: either one of the staker has provided -a valid proof, she wins the game, and is rewarded with half of the -opponent's deposit (the other half being burnt) ; or, both stakers have +are only two possible outcomes: either one of the stakers, that we dub *S* in the sequel, has provided +a valid proof, then *S* wins the game, and is rewarded with half of the +opponent's deposit (the other half being burnt); or, both stakers have provided an invalid proof and they both lose their deposit. In the end, at most one stake will be kept in the commitment tree. When a commitment has no more stake on it (because all stakers have lost the related refutation games), it is removed from the tree. An honest -player must therefore play as many refutation games as there are -stakes on the commitments in conflict with her own commitment. +player *H* must therefore play as many refutation games as there are +stakes on the commitments in conflict with *H*'s own commitment. Finally, notice that each player is subject to a timer similar to a chess clock, allowing each player to play only up to one week: after @@ -298,8 +298,8 @@ 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 -an honest participant, she will start the refutation game with all -concurrent stakers to avoid the rollup being stuck. +an honest participant *H*, then *H* will start the refutation game with all +concurrent stakers to avoid the rollup getting stuck. Workflows --------- @@ -366,12 +366,12 @@ In case you do not already have an implicit account, you can generate one with: octez-client gen keys "${ACCOUNT_NAME}" octez-client show address "${ACCOUNT_NAME}" -Then, the ``${OPERATOR_ADDR}`` can be set to the hash value (``tz1...``) returned. +Then, the ``${OPERATOR_ADDR}`` can be set to the hash value (``tz1...``) returned. Finally, you need to check that your balance is greater than 10,000 tez to make sure that staking is possible. In case your balance is not -sufficient, you can get test tokens for the ``tz1`` address from :ref:`a faucet `, -after your node gets synchronized with Dailynet. +sufficient, you can get test tokens for the ``tz1`` address from :ref:`a faucet `, +after your node gets synchronized with Dailynet. .. code:: sh @@ -620,8 +620,8 @@ originated a Layer 1 smart contract as follows: running 'parameter string; storage string; code {CAR; NIL operation; PAIR};' \ --init '""' --burn-cap 0.4 -and that this contract is identified by an address ``${CONTRACT}`` -(a ``KT1...`` address), then one can encode an +and that this contract is identified by an address ``${CONTRACT}`` +(a ``KT1...`` address), then one can encode an outbox transaction using the Octez rollup client as follows: .. code:: sh @@ -819,8 +819,7 @@ 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 behavior operations. -#. The length of the call stack of the WASM kernel is bounded (see the WASM PVM - versioning section). +#. The length of the call stack of the WASM kernel is bounded. Modulo the limitations above, a valid kernel is a WASM module that satisfies the following constraints: @@ -923,7 +922,6 @@ The values and subtrees under the key ``/readonly`` are not writable by a kernel, but can be used by the PVM to give information to the kernel. - WASM PVM Versioning """"""""""""""""""" @@ -952,6 +950,8 @@ upgrades. The WASM PVM will upgrade itself when it reads the | Alpha | 2.0.0-r1 | +--------------+----------------+ +The changes in each WASM PVM version can be found by searching for string "PVM" in the corresponding protocol's changelog, section ``Smart Rollups`` (e.g. `this section <../protocols/alpha.html#smart-rollups>`__ for protocol Alpha). + Control Flow """""""""""" @@ -1382,7 +1382,7 @@ evaluate the WASM PVM without relying on any node and network: octez-smart-rollup-wasm-debugger "${WASM_FILE}" --inputs "${JSON_INPUTS}" --rollup "${SOR_ADDR}" -``octez-smart-rollup-wasm-debugger`` takes as its argument the WASM kernel to be debugged, either a a ``.wasm`` file (the binary +``octez-smart-rollup-wasm-debugger`` takes the target WASM kernel to be debugged as argument, either as a ``.wasm`` file (the binary 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. diff --git a/docs/developer/data_encoding.rst b/docs/developer/data_encoding.rst index b9ad3df7142ec59524b336b1bc4b996d9ad49b6e..1c6fec5a3f930dad82f79fb92bcf1460212ff876 100644 --- a/docs/developer/data_encoding.rst +++ b/docs/developer/data_encoding.rst @@ -11,6 +11,12 @@ combinators. Examples/Tutorial ----------------- +The following is a very brief introduction to the data-encoding library. + +.. note:: + + A more complete documentation, including a full tutorial with many examples and a reference of all available combinators, is available in `data-encoding's API documentation `__. + Encoding an integer ~~~~~~~~~~~~~~~~~~~ diff --git a/docs/introduction/tezos.rst b/docs/introduction/tezos.rst index 01f5d144021dad3cf569d48819ec3dd1faf77990..b148764c4719c85323fbc134745d9da6ddb73761 100644 --- a/docs/introduction/tezos.rst +++ b/docs/introduction/tezos.rst @@ -19,7 +19,7 @@ Octez is an implementation of Tezos software, including a node, a client, a bake The source code is placed under the MIT Open Source License, and is available at https://gitlab.com/tezos/tezos. -The current release of Octez is :doc:`../releases/version-15`. +The current release of Octez is :doc:`../releases/version-17`. For installing instructions, see :doc:`./howtoget`. @@ -65,14 +65,12 @@ risks. Test Networks ~~~~~~~~~~~~~ -There are several test networks for the Tezos blockchain with a +There are several :ref:`test networks ` for the Tezos blockchain with a faucet to obtain free tez (see :ref:`faucet`). These networks are intended for developers wanting to test their software before going to beta and for users who want to familiarize themselves with Tezos before using their real tez. -See the list of test networks in :ref:`test network `. - This website ~~~~~~~~~~~~ diff --git a/docs/mumbai/smart_rollups.rst b/docs/mumbai/smart_rollups.rst index 84f2828ffaca3a2b1746ef2955f4b7d5ff957ef0..cc8de2a43b45d9152334f0a7adaba7839580b02e 100644 --- a/docs/mumbai/smart_rollups.rst +++ b/docs/mumbai/smart_rollups.rst @@ -98,10 +98,10 @@ sequence of bytes following no particular underlying format. The interpretation of this sequence of bytes is the responsibility of each kernel. -There are two ways for an end-user to push an external message to the -rollups inbox: first, she can inject the dedicated Layer 1 operation +There are two ways for end-users to push an external message to the +rollups inbox: first, they can inject the dedicated Layer 1 operation using the Octez client (see command ``send smart rollup message - from ``); second, she can use the batcher + from ``); second, they can use the batcher of a smart rollup node. More details can be found in :ref:`sending_external_inbox_message_mumbai`. Internal messages @@ -207,8 +207,8 @@ must be wrong. Notice that, to publish a commitment, an operator must provide a deposit of 10,000 tez. For this reason, the operator is said to be a **staker**. Several users can stake on the same commitment. When a -staker publishes a new commitment based on a commitment she is staking -on, she does not have to provide a new deposit: the deposit also +staker *S publishes a new commitment based on a commitment *S* is staking +on, *S* does not have to provide a new deposit: the deposit also applies to this new commitment. There is no need to synchronize between operators: if two honest @@ -256,14 +256,14 @@ provide a proof that they correctly interpreted this conflicting tick. The Layer 1 PVM then determines whether these proofs are valid. There are only two possible outcomes: either one of the staker has provided -a valid proof, she wins the game, and is rewarded with half of the -opponent's deposit (the other half being burnt) ; or, both stakers have +a valid proof, then that staker wins the game, and is rewarded with half of the +opponent's deposit (the other half being burnt); or, both stakers have provided an invalid proof and they both lose their deposit. In the end, at most one stake will be kept in the commitment tree. When a commitment has no more stake on it (because all stakers have lost the related refutation games), it is removed from the tree. An honest -player must therefore play as many refutation games as there are -stakes on the commitments in conflict with her own commitment. +player *H* must therefore play as many refutation games as there are +stakes on the commitments in conflict with *H*'s own commitment. Finally, notice that each player is subject to a timer similar to a chess clock, allowing each player to play only up to one week: after @@ -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 -an honest participant, she will start the refutation game with all +an honest participant, that participant will start the refutation game with all concurrent stakers to avoid the rollup being stuck. Workflows @@ -1280,7 +1280,7 @@ evaluate the WASM PVM without relying on any node and network: octez-smart-rollup-wasm-debugger "${WASM_FILE}" --inputs "${JSON_INPUTS}" --rollup "${SOR_ADDR}" -``octez-smart-rollup-wasm-debugger`` takes as its argument the WASM kernel to be debugged, either a a ``.wasm`` file (the binary +``octez-smart-rollup-wasm-debugger`` takes as its argument the WASM kernel to be debugged, either a ``.wasm`` file (the binary 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. diff --git a/docs/nairobi/smart_rollups.rst b/docs/nairobi/smart_rollups.rst index 740e25ca5b1519790257c2536330d8396333e4e2..7fc86571ef3e6cae2791cdd181c2428150fe167d 100644 --- a/docs/nairobi/smart_rollups.rst +++ b/docs/nairobi/smart_rollups.rst @@ -107,10 +107,10 @@ sequence of bytes following no particular underlying format. The interpretation of this sequence of bytes is the responsibility of each kernel. -There are two ways for an end-user to push an external message to the -rollups inbox: first, she can inject the dedicated Layer 1 operation +There are two ways for end-users to push an external message to the +rollups inbox: first, they can inject the dedicated Layer 1 operation using the Octez client (see command ``send smart rollup message - from ``); second, she can use the batcher + from ``); second, they can use the batcher of a smart rollup node. More details can be found in :ref:`sending_external_inbox_message_nairobi`. Internal messages @@ -224,8 +224,8 @@ must be wrong. Notice that, to publish a commitment, an operator must provide a deposit of 10,000 tez. For this reason, the operator is said to be a **staker**. Several users can stake on the same commitment. When a -staker publishes a new commitment based on a commitment she is staking -on, she does not have to provide a new deposit: the deposit also +staker *S* publishes a new commitment based on a commitment that *S* is staking +on, *S* does not have to provide a new deposit: the deposit also applies to this new commitment. There is no need to synchronize between operators: if two honest @@ -282,14 +282,14 @@ provide a proof that they correctly interpreted this conflicting tick. The Layer 1 PVM then determines whether these proofs are valid. There are only two possible outcomes: either one of the staker has provided -a valid proof, she wins the game, and is rewarded with half of the -opponent's deposit (the other half being burnt) ; or, both stakers have +a valid proof, then that staker wins the game, and is rewarded with half of the +opponent's deposit (the other half being burnt); or, both stakers have provided an invalid proof and they both lose their deposit. In the end, at most one stake will be kept in the commitment tree. When a commitment has no more stake on it (because all stakers have lost the related refutation games), it is removed from the tree. An honest -player must therefore play as many refutation games as there are -stakes on the commitments in conflict with her own commitment. +player *H* must therefore play as many refutation games as there are +stakes on the commitments in conflict with *H*'s own commitment. Finally, notice that each player is subject to a timer similar to a chess clock, allowing each player to play only up to one week: after @@ -299,7 +299,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 -an honest participant, she will start the refutation game with all +an honest participant, that participant will start the refutation game with all concurrent stakers to avoid the rollup being stuck. Workflows @@ -793,11 +793,10 @@ 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 behavior operations. -#. The length of the call stack of the WASM kernel is bounded (see the WASM PVM - versioning section). +#. The length of the call stack of the WASM kernel is bounded. -Modulo the limitations above, a valid kernel is a WASM module that satisfies -the following constraints: +Modulo the limitations above, a valid kernel is a WASM module that +satisfies the following constraints: #. It exports a function ``kernel_run`` that takes no argument and returns nothing. @@ -919,9 +918,12 @@ upgrades. The WASM PVM will upgrade itself when it reads the | Protocol | Version | +==============+================+ | Mumbai | 2.0.0 | ++--------------+----------------+ | Nairobi | 2.0.0-r1 | +--------------+----------------+ +The changes in each WASM PVM version can be found by searching for string "PVM" in the corresponding protocol's changelog, section ``Smart Rollups`` (e.g. `this section <../protocols/alpha.html#smart-rollups>`__ for protocol Alpha). + Control Flow """""""""""" @@ -1361,7 +1363,7 @@ evaluate the WASM PVM without relying on any node and network: octez-smart-rollup-wasm-debugger "${WASM_FILE}" --inputs "${JSON_INPUTS}" --rollup "${SOR_ADDR}" -``octez-smart-rollup-wasm-debugger`` takes as its argument the WASM kernel to be debugged, either a a ``.wasm`` file (the binary +``octez-smart-rollup-wasm-debugger`` takes as its argument the WASM kernel to be debugged, either a ``.wasm`` file (the binary 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. diff --git a/docs/protocols/naming.rst b/docs/protocols/naming.rst index c7d8e4eae8821d32e3adb61c69c85645f3e60f2d..1ea8eca1aa493ca3e8e311ed1941a6de732011e8 100644 --- a/docs/protocols/naming.rst +++ b/docs/protocols/naming.rst @@ -57,15 +57,15 @@ in-use and upcoming protocols: - other terms: "active protocol", "mainnet protocol" -* The protocol currently under voting, that is in any of the possible voting +* Any protocol currently subject to the governance process, that is, being part of any of the possible voting phases: "candidate protocol". - - other possible terms: "current proposal" + - other possible terms: "(new) protocol proposal", "current proposal" External resources ------------------ -The current protocol status can be found at election pages such as: tzstats.com_, tzkt.io_, or tezosagora.org_. +The current status of a protocol in the governance process can be found at election pages such as: tzstats.com_, tzkt.io_, or tezosagora.org_. An interesting blog post on the history of the initial Tezos economic protocols is: `A quick history of past upgrades