diff --git a/docs/009/cli-commands.rst b/docs/009/cli-commands.rst index 5defed5f9b9d40152922f275ffd172fa55fa17ec..3de61b832d5ffc75b0846cad8793950f7ddaded8 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/009/michelson.rst b/docs/009/michelson.rst index 6ba1b3cee72cdce173738215c8c0f64c2ff9bb97..504e41904bad70582231ddfa4e636517083d0de1 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 @@ -2006,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/cli-commands.rst b/docs/010/cli-commands.rst index e0c21f98f4ed62544d337acade9d7561555e85f9..132ee0ad7af01462746ff2b6568c1659a0d63ec2 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/010/michelson.rst b/docs/010/michelson.rst index 51bcb2a556b1edd152a69c9818eea9814803666b..390155a34dbe2a27be4bdf2af31d6c5377935b04 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 @@ -2006,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/cli-commands.rst b/docs/alpha/cli-commands.rst index ff5643a49b8ed94b7ea2f8ad10bca5236705389b..d9a9c92c344063fba278ad93bc6fc3d6ae534022 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/alpha/michelson.rst b/docs/alpha/michelson.rst index c9d7895170310fe50b4246530ec311ed6c4cf7fd..f34660e6fc8019d14c0810132d965caeb24c8393 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 @@ -2007,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. :: diff --git a/docs/developer/contributing.rst b/docs/developer/contributing.rst index 6ed155be01739fb66ad79fd086527a7257b779d2..74dd7c33f6bb15a582a56c2aa45ff0db5eae50e9 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/entering_alpha.rst b/docs/developer/entering_alpha.rst index cf206834fe9cde628244b1a6cfb698448308c8e8..f022428636358326574fa8b198be038fb2081b3e 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/developer/gadt.rst b/docs/developer/gadt.rst index bd02d1f0bc25d835884a343fe966cee3942b01ff..1de111caa0b0f5127d86d6cb078b226e194f6911 100644 --- a/docs/developer/gadt.rst +++ b/docs/developer/gadt.rst @@ -1,5 +1,3 @@ -.. _gadt: - Generalized Algebraic Data Types (GADTs) ======================================== @@ -29,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 diff --git a/docs/introduction/howtouse.rst b/docs/introduction/howtouse.rst index 30e89da6135f9106998738ba06a6e702576375c9..5ddc1f715d726434951a97ce8b2c2a8b51650c92 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 @@ -650,8 +652,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/docs/introduction/install-opam.sh b/docs/introduction/install-opam.sh index 02c1c5b1c001f5ab414d3ae979322fc008f6765b..af4638841268df1cfd51f1ba16e083579e90f288 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 diff --git a/docs/protocols/009_florence.rst b/docs/protocols/009_florence.rst index dc07eaabfb084ed92ca5eee8e45a7a00aef088cb..04dc874896d95fc7876a5fc9507445514dda9e53 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` diff --git a/docs/shell/cli-commands.rst b/docs/shell/cli-commands.rst index 76d459e2daf5593428bd11dfbde7d91b1afc54da..91f778cd53ee56e6bdc0f370c90fe6b4a4fdd773 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. diff --git a/src/lib_protocol_environment/proxy_context.mli b/src/lib_protocol_environment/proxy_context.mli index 8b1f0af34c06c4b2fa608d1d7827a6c8ce2b9be2..72eb40be41ed776de55f23015915d667b409d81b 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, after 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