From a7342b3e7e784765cb7377dc19b13ca008df9a98 Mon Sep 17 00:00:00 2001 From: Nic Volanschi Date: Tue, 15 Jun 2021 16:16:36 +0200 Subject: [PATCH 1/8] doc: typos and rewordings --- docs/009/michelson.rst | 17 +++++++++-------- docs/010/michelson.rst | 17 +++++++++-------- docs/alpha/michelson.rst | 17 +++++++++-------- docs/developer/entering_alpha.rst | 2 +- docs/introduction/howtouse.rst | 3 +-- src/lib_protocol_environment/proxy_context.mli | 2 +- 6 files changed, 30 insertions(+), 28 deletions(-) diff --git a/docs/009/michelson.rst b/docs/009/michelson.rst index 6ba1b3cee72c..e42afa314f27 100644 --- a/docs/009/michelson.rst +++ b/docs/009/michelson.rst @@ -2,7 +2,7 @@ Michelson: the language of Smart Contracts in Tezos =================================================== This specification gives a detailed formal semantics of the Michelson -language, and a short explanation of how smart contracts are executed +language and a short explanation of how smart contracts are executed and interact in the blockchain. The language is stack-based, with high level data types and primitives, @@ -11,7 +11,7 @@ several language families. Vigilant readers will notice direct references to Forth, Scheme, ML and Cat. A Michelson program is a series of instructions that are run in -sequence: each instruction receives as input the stack resulting of the +sequence: each instruction receives as input the stack resulting from the previous instruction, and rewrites it for the next one. The stack contains both immediate values and heap allocated structures. All values are immutable and garbage collected. @@ -53,7 +53,7 @@ Intra-transaction semantics Alongside their tokens, smart contracts keep a piece of storage. Both are ruled by a specific logic specified by a Michelson program. A -transaction to smart contract will provide an input value and in +transaction to a smart contract will provide an input value and in option some tokens, and in return, the smart contract can modify its storage and transfer its tokens. @@ -69,7 +69,7 @@ not be caught by the type system (e.g. gas exhaustion). A bit of polymorphism can be used at contract level, with a lightweight system of named entrypoints: instead of an input value, the contract can be called with an entrypoint name and an argument, -and these two component are transformed automatically in a simple and +and these two components are transformed automatically in a simple and deterministic way to an input value. This feature is available both for users and from Michelson code. See the dedicated section. @@ -159,7 +159,8 @@ In any case, when a failure happens, either total success or total failure is guaranteed. If a transaction (internal or external) fails, then the whole sequence fails and all the effects up to the failure are reverted. These transactions can still be included in blocks, and -the transaction fees given to the implicit account who baked the block. +the transaction fees are given to the implicit account who baked the +block. Language semantics ------------------ @@ -191,8 +192,8 @@ The left hand side of the ``=>`` sign is used for selecting the rule. Given a program and an initial stack, one (and only one) rule can be selected using the following process. First, the toplevel structure of the program must match the syntax pattern. This is quite simple since -there is only a few non trivial patterns to deal with instruction -sequences, and the rest is made of trivial pattern that match one +there are only a few non-trivial patterns to deal with instruction +sequences, and the rest is made of trivial patterns that match one specific instruction. Then, the initial stack must match the initial stack pattern. Finally, some rules add extra conditions over the values in the stack that follow the ``iff`` keyword. Sometimes, several rules @@ -219,7 +220,7 @@ form. where (intermediate program) / (intermediate stack) => (partial result) -This means that this rules applies in case interpreting the intermediate +This means that this rule applies in case interpreting the intermediate state on the left gives the pattern on the right. The left hand sign of the ``=>`` sign is constructed from elements of diff --git a/docs/010/michelson.rst b/docs/010/michelson.rst index 51bcb2a556b1..13fc3f7409aa 100644 --- a/docs/010/michelson.rst +++ b/docs/010/michelson.rst @@ -4,7 +4,7 @@ Michelson: the language of Smart Contracts in Tezos =================================================== This specification gives a detailed formal semantics of the Michelson -language, and a short explanation of how smart contracts are executed +language and a short explanation of how smart contracts are executed and interact in the blockchain. The language is stack-based, with high level data types and primitives, @@ -13,7 +13,7 @@ several language families. Vigilant readers will notice direct references to Forth, Scheme, ML and Cat. A Michelson program is a series of instructions that are run in -sequence: each instruction receives as input the stack resulting of the +sequence: each instruction receives as input the stack resulting from the previous instruction, and rewrites it for the next one. The stack contains both immediate values and heap allocated structures. All values are immutable and garbage collected. @@ -55,7 +55,7 @@ Intra-transaction semantics Alongside their tokens, smart contracts keep a piece of storage. Both are ruled by a specific logic specified by a Michelson program. A -transaction to smart contract will provide an input value and in +transaction to a smart contract will provide an input value and in option some tokens, and in return, the smart contract can modify its storage and transfer its tokens. @@ -71,7 +71,7 @@ not be caught by the type system (e.g. gas exhaustion). A bit of polymorphism can be used at contract level, with a lightweight system of named entrypoints: instead of an input value, the contract can be called with an entrypoint name and an argument, -and these two component are transformed automatically in a simple and +and these two components are transformed automatically in a simple and deterministic way to an input value. This feature is available both for users and from Michelson code. See the dedicated section. @@ -161,7 +161,8 @@ In any case, when a failure happens, either total success or total failure is guaranteed. If a transaction (internal or external) fails, then the whole sequence fails and all the effects up to the failure are reverted. These transactions can still be included in blocks, and -the transaction fees given to the implicit account who baked the block. +the transaction fees are given to the implicit account who baked the +block. Language semantics ------------------ @@ -193,8 +194,8 @@ The left hand side of the ``=>`` sign is used for selecting the rule. Given a program and an initial stack, one (and only one) rule can be selected using the following process. First, the toplevel structure of the program must match the syntax pattern. This is quite simple since -there is only a few non trivial patterns to deal with instruction -sequences, and the rest is made of trivial pattern that match one +there are only a few non-trivial patterns to deal with instruction +sequences, and the rest is made of trivial patterns that match one specific instruction. Then, the initial stack must match the initial stack pattern. Finally, some rules add extra conditions over the values in the stack that follow the ``iff`` keyword. Sometimes, several rules @@ -221,7 +222,7 @@ form. where (intermediate program) / (intermediate stack) => (partial result) -This means that this rules applies in case interpreting the intermediate +This means that this rule applies in case interpreting the intermediate state on the left gives the pattern on the right. The left hand sign of the ``=>`` sign is constructed from elements of diff --git a/docs/alpha/michelson.rst b/docs/alpha/michelson.rst index c9d789517031..95bf4146e117 100644 --- a/docs/alpha/michelson.rst +++ b/docs/alpha/michelson.rst @@ -2,7 +2,7 @@ Michelson: the language of Smart Contracts in Tezos =================================================== This specification gives a detailed formal semantics of the Michelson -language, and a short explanation of how smart contracts are executed +language and a short explanation of how smart contracts are executed and interact in the blockchain. The language is stack-based, with high level data types and primitives, @@ -11,7 +11,7 @@ several language families. Vigilant readers will notice direct references to Forth, Scheme, ML and Cat. A Michelson program is a series of instructions that are run in -sequence: each instruction receives as input the stack resulting of the +sequence: each instruction receives as input the stack resulting from the previous instruction, and rewrites it for the next one. The stack contains both immediate values and heap allocated structures. All values are immutable and garbage collected. @@ -53,7 +53,7 @@ Intra-transaction semantics Alongside their tokens, smart contracts keep a piece of storage. Both are ruled by a specific logic specified by a Michelson program. A -transaction to smart contract will provide an input value and in +transaction to a smart contract will provide an input value and in option some tokens, and in return, the smart contract can modify its storage and transfer its tokens. @@ -69,7 +69,7 @@ not be caught by the type system (e.g. gas exhaustion). A bit of polymorphism can be used at contract level, with a lightweight system of named entrypoints: instead of an input value, the contract can be called with an entrypoint name and an argument, -and these two component are transformed automatically in a simple and +and these two components are transformed automatically in a simple and deterministic way to an input value. This feature is available both for users and from Michelson code. See the dedicated section. @@ -159,7 +159,8 @@ In any case, when a failure happens, either total success or total failure is guaranteed. If a transaction (internal or external) fails, then the whole sequence fails and all the effects up to the failure are reverted. These transactions can still be included in blocks, and -the transaction fees given to the implicit account who baked the block. +the transaction fees are given to the implicit account who baked the +block. Language semantics ------------------ @@ -191,8 +192,8 @@ The left hand side of the ``=>`` sign is used for selecting the rule. Given a program and an initial stack, one (and only one) rule can be selected using the following process. First, the toplevel structure of the program must match the syntax pattern. This is quite simple since -there is only a few non trivial patterns to deal with instruction -sequences, and the rest is made of trivial pattern that match one +there are only a few non-trivial patterns to deal with instruction +sequences, and the rest is made of trivial patterns that match one specific instruction. Then, the initial stack must match the initial stack pattern. Finally, some rules add extra conditions over the values in the stack that follow the ``iff`` keyword. Sometimes, several rules @@ -219,7 +220,7 @@ form. where (intermediate program) / (intermediate stack) => (partial result) -This means that this rules applies in case interpreting the intermediate +This means that this rule applies in case interpreting the intermediate state on the left gives the pattern on the right. The left hand sign of the ``=>`` sign is constructed from elements of diff --git a/docs/developer/entering_alpha.rst b/docs/developer/entering_alpha.rst index cf206834fe9c..f02242863635 100644 --- a/docs/developer/entering_alpha.rst +++ b/docs/developer/entering_alpha.rst @@ -78,7 +78,7 @@ enforced. Hashes and storage description layer ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -This layer is implemented by module ``storage_description.ml`` and modules named ``*_hash`. +This layer is implemented by module ``storage_description.ml`` and modules named ``*_hash``. It contains mainly Blake2b hash implementations specialized for various basic types of the protocol. diff --git a/docs/introduction/howtouse.rst b/docs/introduction/howtouse.rst index 30e89da6135f..7d115ac71587 100644 --- a/docs/introduction/howtouse.rst +++ b/docs/introduction/howtouse.rst @@ -650,8 +650,7 @@ The behavior of the client can be configured using the following environment var - `TEZOS_CLIENT_UNSAFE_DISABLE_DISCLAIMER`: Setting this variable to "YES" (or: "yes", "Y", "y") disables the warning displayed by the client at startup when it is not launched on Mainnet. - `TEZOS_CLIENT_DIR`: This variable may be used to supply the client data directory (by default, ``~/.tezos-client``). Its value is overridden by option ``-d``. -- `TEZOS_SIGNER_*`: These variables are used for connecting the client to a remote :ref:`signer `. - Its value is overwritten by option ``-d``. +- `TEZOS_SIGNER_*`: These variables are used for connecting the client to a remote :ref:`signer ` (see there for details). - `TEZOS_CLIENT_RPC_TIMEOUT_SECONDS`: This variable controls how long (in seconds, as an integer) the client will wait for a response from the node, for each of the two RPC calls made during startup. If this variable is not set, or otherwise cannot be parsed as a positive integer, a default value of ``10`` seconds is used for each call. diff --git a/src/lib_protocol_environment/proxy_context.mli b/src/lib_protocol_environment/proxy_context.mli index 8b1f0af34c06..ca3d56c52554 100644 --- a/src/lib_protocol_environment/proxy_context.mli +++ b/src/lib_protocol_environment/proxy_context.mli @@ -31,7 +31,7 @@ Whereas [Memory_context] is a regular recursive map, [Proxy_context] obtains values by delegating to endpoints when receiving requests. - Hence, after right after having created an [empty] value with an instance + Hence, right after having created an [empty] value with an instance of [M.ProxyDelegate], this value is as filled as the distant endpoint it delegates to. *) -- GitLab From c677d2ff7b413722360256bb98b4c526f57ae893 Mon Sep 17 00:00:00 2001 From: Marcin Pastudzki Date: Wed, 16 Jun 2021 10:07:37 +0200 Subject: [PATCH 2/8] Typo: reformat comment block. --- src/lib_protocol_environment/proxy_context.mli | 18 ++++++++---------- 1 file changed, 8 insertions(+), 10 deletions(-) diff --git a/src/lib_protocol_environment/proxy_context.mli b/src/lib_protocol_environment/proxy_context.mli index ca3d56c52554..72eb40be41ed 100644 --- a/src/lib_protocol_environment/proxy_context.mli +++ b/src/lib_protocol_environment/proxy_context.mli @@ -23,17 +23,15 @@ (* *) (*****************************************************************************) -(** This module is the location where the proxy tweaks the behavior of a - vanilla client. A regular mockup client uses a [Memory_context] in - place of this implementation. Compared to [Memory_context], this - instance features a [M.ProxyDelegate] - which under the hood relies on [Proxy_getter]. +(** This module is the location where the proxy tweaks the behavior of a vanilla + client. A regular mockup client uses a [Memory_context] in place of this + implementation. Compared to [Memory_context], this instance features a + [M.ProxyDelegate] which under the hood relies on [Proxy_getter]. - Whereas [Memory_context] is a regular recursive map, [Proxy_context] - obtains values by delegating to endpoints when receiving requests. - Hence, right after having created an [empty] value with an instance - of [M.ProxyDelegate], this value is as filled as the distant endpoint - it delegates to. *) + Whereas [Memory_context] is a regular recursive map, [Proxy_context] obtains + values by delegating to endpoints when receiving requests. Hence, right + after having created an [empty] value with an instance of [M.ProxyDelegate], + this value is as filled as the distant endpoint it delegates to. *) open Tezos_protocol_environment -- GitLab From f1b4fb7e76dd74bc69a4c0e3fbcf98394c4da1d4 Mon Sep 17 00:00:00 2001 From: Nic Volanschi Date: Wed, 16 Jun 2021 17:56:19 +0200 Subject: [PATCH 3/8] doc: remove useless -y in opam install tezos --- docs/introduction/install-opam.sh | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/introduction/install-opam.sh b/docs/introduction/install-opam.sh index 02c1c5b1c001..af4638841268 100644 --- a/docs/introduction/install-opam.sh +++ b/docs/introduction/install-opam.sh @@ -18,4 +18,4 @@ eval $(opam env) opam install depext opam depext tezos # [install tezos] -opam install -y tezos +opam install tezos -- GitLab From 128c714cf41c3519b67d78eb1b1068ce0455a7c6 Mon Sep 17 00:00:00 2001 From: Arvid Jakobsson Date: Mon, 21 Jun 2021 13:45:49 +0200 Subject: [PATCH 4/8] Docs/Michelson: Clarify LEVEL --- docs/009/michelson.rst | 2 +- docs/010/michelson.rst | 2 +- docs/alpha/michelson.rst | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/009/michelson.rst b/docs/009/michelson.rst index e42afa314f27..504e41904bad 100644 --- a/docs/009/michelson.rst +++ b/docs/009/michelson.rst @@ -2007,7 +2007,7 @@ Special operations > COMPARE / x : y : S => 1 : S iff x > y -- ``LEVEL``: Push the current block level. +- ``LEVEL``: Push the level of the current transaction's block. :: diff --git a/docs/010/michelson.rst b/docs/010/michelson.rst index 13fc3f7409aa..390155a34dbe 100644 --- a/docs/010/michelson.rst +++ b/docs/010/michelson.rst @@ -2007,7 +2007,7 @@ Special operations > COMPARE / x : y : S => 1 : S iff x > y -- ``LEVEL``: Push the current block level. +- ``LEVEL``: Push the level of the current transaction's block. :: diff --git a/docs/alpha/michelson.rst b/docs/alpha/michelson.rst index 95bf4146e117..f34660e6fc80 100644 --- a/docs/alpha/michelson.rst +++ b/docs/alpha/michelson.rst @@ -2008,7 +2008,7 @@ Special operations > COMPARE / x : y : S => 1 : S iff x > y -- ``LEVEL``: Push the current block level. +- ``LEVEL``: Push the level of the current transaction's block. :: -- GitLab From 3c195aad5e402727ebc3db8226df35513957adef Mon Sep 17 00:00:00 2001 From: Nic Volanschi Date: Thu, 24 Jun 2021 12:04:51 +0200 Subject: [PATCH 5/8] doc: remove top label in gadt.rst --- docs/developer/contributing.rst | 2 +- docs/developer/gadt.rst | 2 -- 2 files changed, 1 insertion(+), 3 deletions(-) diff --git a/docs/developer/contributing.rst b/docs/developer/contributing.rst index 6ed155be0173..74dd7c33f6bb 100644 --- a/docs/developer/contributing.rst +++ b/docs/developer/contributing.rst @@ -39,7 +39,7 @@ website https://ocaml.org gives a few useful pointers for that. In particular, we use a lot of functors, and a few GADTs in the codebase, so you may want to make sure that you master these advanced concepts. For a more specific explanation of GADT usage in Tezos you can check out -:ref:`gadt`. +:doc:`gadt`. Then, if you don’t know much about the Lwt library, that’s what you want to learn next. This library is used extensively throughout the code base: diff --git a/docs/developer/gadt.rst b/docs/developer/gadt.rst index bd02d1f0bc25..6c6c56625e9f 100644 --- a/docs/developer/gadt.rst +++ b/docs/developer/gadt.rst @@ -1,5 +1,3 @@ -.. _gadt: - Generalized Algebraic Data Types (GADTs) ======================================== -- GitLab From a49f397e9599d8b38598ce798560615d9b3dab20 Mon Sep 17 00:00:00 2001 From: Nic Volanschi Date: Fri, 25 Jun 2021 15:13:15 +0200 Subject: [PATCH 6/8] doc: fix issue number 52 --- docs/protocols/009_florence.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/protocols/009_florence.rst b/docs/protocols/009_florence.rst index dc07eaabfb08..04dc874896d9 100644 --- a/docs/protocols/009_florence.rst +++ b/docs/protocols/009_florence.rst @@ -86,7 +86,7 @@ sign arbitrary data securely, without fear of malicious injection into future protocols. - Solves issue: - :gl:`tezos#52` + :gl:`metastatedev/tezos#52` - MR: :gl:`tezos!2361` -- GitLab From de2619f2deb6b1e69ebcf02c65568a506c506001 Mon Sep 17 00:00:00 2001 From: Nic Volanschi Date: Wed, 30 Jun 2021 10:31:06 +0200 Subject: [PATCH 7/8] doc: fix inexistent :src: file --- docs/developer/gadt.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/developer/gadt.rst b/docs/developer/gadt.rst index 6c6c56625e9f..1de111caa0b0 100644 --- a/docs/developer/gadt.rst +++ b/docs/developer/gadt.rst @@ -27,7 +27,7 @@ directly implemented as OCaml type checking, so that the correctness of the latter entails the correctness of the former. The (simplified) definition of Michelson expressions type is presented below -(see the :src:`src/proto_alpha/lib_protocol/script_typed_ir.mli` module for the +(see the :src:`src/proto_alpha/lib_protocol/script_typed_ir.ml` module for the actual definition): .. code-block:: ocaml -- GitLab From 7a3ed085bd1627ab88f0562d50ea987eedd41ab9 Mon Sep 17 00:00:00 2001 From: Nic Volanschi Date: Thu, 1 Jul 2021 17:25:15 +0200 Subject: [PATCH 8/8] doc: specialize headers of */cli-commands.rst --- docs/009/cli-commands.rst | 5 ++--- docs/010/cli-commands.rst | 5 ++--- docs/alpha/cli-commands.rst | 5 ++--- docs/introduction/howtouse.rst | 2 ++ docs/shell/cli-commands.rst | 1 - 5 files changed, 8 insertions(+), 10 deletions(-) diff --git a/docs/009/cli-commands.rst b/docs/009/cli-commands.rst index 5defed5f9b9d..3de61b832d5f 100644 --- a/docs/009/cli-commands.rst +++ b/docs/009/cli-commands.rst @@ -4,12 +4,11 @@ Command Line Interface This document is a prettier output of the documentation produced by the command ``man`` of the different Tezos binaries. You can obtain similar pages -using the following shell commands. +using shell commands such as (:ref:`indicating the appropriate protocol `): :: - tezos-client -protocol ProtoALphaALph man -verbosity 3 - tezos-admin-client man -verbosity 3 + tezos-client -protocol man -verbosity 3 The rest of this page documents the protocol-dependent tools. The protocol-independent tools are documented :doc:`here <../shell/cli-commands>`. diff --git a/docs/010/cli-commands.rst b/docs/010/cli-commands.rst index e0c21f98f4ed..132ee0ad7af0 100644 --- a/docs/010/cli-commands.rst +++ b/docs/010/cli-commands.rst @@ -4,12 +4,11 @@ Command Line Interface This document is a prettier output of the documentation produced by the command ``man`` of the different Tezos binaries. You can obtain similar pages -using the following shell commands. +using shell commands such as (:ref:`indicating the appropriate protocol `): :: - tezos-client -protocol ProtoALphaALph man -verbosity 3 - tezos-admin-client man -verbosity 3 + tezos-client -protocol man -verbosity 3 The rest of this page documents the protocol-dependent tools. The protocol-independent tools are documented :doc:`here <../shell/cli-commands>`. diff --git a/docs/alpha/cli-commands.rst b/docs/alpha/cli-commands.rst index ff5643a49b8e..d9a9c92c3440 100644 --- a/docs/alpha/cli-commands.rst +++ b/docs/alpha/cli-commands.rst @@ -4,12 +4,11 @@ Command Line Interface This document is a prettier output of the documentation produced by the command ``man`` of the different Tezos binaries. You can obtain similar pages -using the following shell commands. +using shell commands such as (:ref:`indicating the appropriate protocol `): :: - tezos-client -protocol ProtoALphaALph man -verbosity 3 - tezos-admin-client man -verbosity 3 + tezos-client -protocol man -verbosity 3 The rest of this page documents the protocol-dependent tools. The protocol-independent tools are documented :doc:`here <../shell/cli-commands>`. diff --git a/docs/introduction/howtouse.rst b/docs/introduction/howtouse.rst index 7d115ac71587..5ddc1f715d72 100644 --- a/docs/introduction/howtouse.rst +++ b/docs/introduction/howtouse.rst @@ -61,6 +61,8 @@ node. In the last case, the above command generates a warning:: Warning: Failed to acquire the protocol version from the node +.. _tezos_client_protocol: + To get the manual of a client command for a protocol other than that used by the node (or even when not connected to a node), use the option ``--protocol``, e.g.:: tezos-client --protocol ProtoALphaALph man transfer diff --git a/docs/shell/cli-commands.rst b/docs/shell/cli-commands.rst index 76d459e2daf5..91f778cd53ee 100644 --- a/docs/shell/cli-commands.rst +++ b/docs/shell/cli-commands.rst @@ -8,7 +8,6 @@ obtain similar pages using shell commands such as: :: - tezos-client -protocol ProtoALphaALph man -verbosity 3 tezos-admin-client man -verbosity 3 The rest of this page documents the protocol-independent tools. -- GitLab