diff --git a/docs/alpha/timelock.rst b/docs/alpha/timelock.rst index 38c42b7b0992b0bbb83d37ad5a6cdd9bae1f9472..3826851e2237abc611433e40a8cd1577a3f7c441 100644 --- a/docs/alpha/timelock.rst +++ b/docs/alpha/timelock.rst @@ -7,7 +7,7 @@ Block Producer Extractable Value We aim at tackling the issue known through the unfortunate misnomer of "generalized front running", described -for instance in `here `_. +for instance in `here `__. Observing a transaction before it is actually included in the chain can give an advantage to a trader against another one. Ultimately, @@ -55,7 +55,7 @@ ensure a level playing field in terms of computational speed. An implementation of the timelock puzzle and proof scheme is available in :src:`src/lib_crypto/timelock.mli` inspired from a proof of concept available -`here `_ +`here `__. General principle ----------------- @@ -81,7 +81,7 @@ Cryptographic principles ------------------------ Users first generate a RSA modulus and a symmetric encryption key. -They use authenticated encryption to encrypt a `PACK`ed Michelson value (i.e., bytes) +They use authenticated encryption to encrypt a packed Michelson value (an array of bytes computed with ``PACK``) and encrypt that encryption key using a timelock puzzle. They then combine the RSA modulus, the timelocked symmetric key, the constant T and the encrypted value as a single value as well (called chest in our library in src/lib_crypto). diff --git a/docs/alpha/voting.rst b/docs/alpha/voting.rst index a04d698013b88e0ce7297d49993cfe73a5d246c7..850a782f0ea2bb3b12ebd16c624ea34e37ef5305 100644 --- a/docs/alpha/voting.rst +++ b/docs/alpha/voting.rst @@ -1,5 +1,3 @@ -.. _alpha_voting_procedure - The Voting Process ================== @@ -19,8 +17,7 @@ Voting periods align with cycles: a voting period starts at the first block of a cycle. Other than this page, there is an excellent overview from `Jacob -Arluck on medium. -`_ +Arluck on medium `__. Periods ------- @@ -216,4 +213,4 @@ For vote related RPCs check the :doc:`rpc` under the prefix ``votes/``. For Ledger support refer to Obsidian Systems' `documentation -`_. +`__. diff --git a/docs/developer/contributing-adding-a-new-opam-dependency.rst b/docs/developer/contributing-adding-a-new-opam-dependency.rst index bc92813073839dae47beced32de359e06bce2033..16032e0d1870c2f87bc685557bfc00b34c427a45 100644 --- a/docs/developer/contributing-adding-a-new-opam-dependency.rst +++ b/docs/developer/contributing-adding-a-new-opam-dependency.rst @@ -1,5 +1,3 @@ -.. _adding_new_opam_dependency: - How to add or update opam dependencies ====================================== diff --git a/docs/developer/contributing.rst b/docs/developer/contributing.rst index 61686f0fba92f8dda5278decfad1310507781cff..5791f413814486320624ddd09b61e0e75b60d1a4 100644 --- a/docs/developer/contributing.rst +++ b/docs/developer/contributing.rst @@ -30,6 +30,7 @@ Going further You may also want to fix some typos and minor errors or incoherencies in the *documentation*, which is situated in the ``docs/`` subfolder of the code repository. This kind of small contributions can be done without creating a merge request, by directly pushing commits to the ``typo-doc`` branch, which is regularly merged into the master branch, e.g., every one or two weeks. +This periodic merging is implemented by a series of MRs named "the typo train", created for you by a volunteer, and batching the currently pending fixes. Of course, all these commits will be reviewed before being integrated. To directly contribute to the *codebase*, expertise in a few areas is necessary. @@ -338,7 +339,12 @@ Special case: MRs that introduce a new dependency In the special case where your MR adds a new opam dependency or updates an existing opam dependency, you will need to follow -:ref:`this additional dedicated guide `. +this additional dedicated guide: + +.. toctree:: + :maxdepth: 2 + + contributing-adding-a-new-opam-dependency In the special case where your MR adds a new Python, Rust, Javascript, or other dependency, additional steps must also be followed. @@ -533,7 +539,7 @@ The code for the bot is at work-in-progress and new warnings and comments will appear little by little. We welcome specific issues or contributions there too. -.. dev_tools: +.. _dev_tools: Developer Tools ~~~~~~~~~~~~~~~ diff --git a/docs/developer/protocol_environment.rst b/docs/developer/protocol_environment.rst index 5597879b5d2fdd104b878bd00e7b4227a9794af9..920c22f4418ff0ba478885c1f37e243cbca839f0 100644 --- a/docs/developer/protocol_environment.rst +++ b/docs/developer/protocol_environment.rst @@ -32,7 +32,7 @@ Here is a quick description of each file in this environment, all located under These files are assembled into a single interface file ``VX.mli`` by a helper program located in ``s_packer/``. - Special cases: the files ``context.mli``, ``fitness.mli``, and - ``updater.mli`` are interfaces that the protocol exposes to the shell. + ``updater.mli`` are interfaces that the protocol exposes to the shell. - Files in the ``structs/vX/`` directory declare compatibility layers for old protocol environments. E.g., ``structs/V0/error_monad_traversors.ml`` contain the code of error-monad-compatible list traversers that used to be part of diff --git a/docs/developer/unit_testing_legacy_code.rst b/docs/developer/unit_testing_legacy_code.rst index d3c7a86c9fc1a1a82b674039f4b4b2032dc1265a..38b14b1f3ce733369b961b7563eca574dcc28228 100644 --- a/docs/developer/unit_testing_legacy_code.rst +++ b/docs/developer/unit_testing_legacy_code.rst @@ -47,7 +47,6 @@ Works best when: - Code and its dependencies are pure, or "pure enough" (e.g. code may contain logging and other unharmful/unimportant side effects) - Dependency tree is not too deep (e.g. if A depends on B which depends on C which depends on D, then it becomes hard to write/read/maintain unit tests) -Function records Using function records ---------------------- @@ -68,11 +67,11 @@ As an example, consider the following ``Counter`` module (signature and implemen type t = { counter : int; } - + let create_from_file () = let counter = int_of_string (Files.read "/tmp/counter.txt") in {counter} - + let increment_and_save_to_file t = let t = {counter = t.counter + 1} in Files.write "/tmp/counter.txt" (string_of_int t.counter); @@ -93,7 +92,7 @@ One way to achieve this - when your module has a state, usually a type ``t`` - i type t val create_from_file : unit -> t val increment_and_save_to_file : t -> t - + module Internal_for_tests : sig type dependencies = { files_read : string -> string; @@ -106,30 +105,30 @@ One way to achieve this - when your module has a state, usually a type ``t`` - i files_read : string -> string; files_write : string -> string -> unit; } - + type t = { counter : int; dependencies : dependencies; } - + let create_from_file_internal dependencies () = let counter = int_of_string (dependencies.files_read "/tmp/counter.txt") in {counter; dependencies} - + let create_from_file = create_from_file_internal {files_read = Files.read; files_write = Files.write} - + let increment_and_save_to_file t = let t = {t with counter = t.counter + 1} in t.dependencies.files_write "/tmp/counter.txt" (string_of_int t.counter); t - + module Internal_for_tests = struct type nonrec dependencies = dependencies = { files_read : string -> string; files_write : string -> string -> unit; } - - let create_from_file = create_from_file_internal + + let create_from_file = create_from_file_internal end end @@ -165,13 +164,13 @@ An alternative solution, more verbose but not requiring any "state" value availa type t val create_from_file : unit -> t val increment_and_save_to_file : t -> t - + module Internal_for_tests : sig type dependencies = { files_read : string -> string; files_write : string -> string -> unit; } - + val create_from_file : dependencies -> unit -> t val increment_and_save_to_file : dependencies -> t -> t end @@ -195,14 +194,14 @@ An alternative solution, more verbose but not requiring any "state" value availa {counter} let create_from_file = create_from_file_internal business_dependencies - + let increment_and_save_to_file_internal dependencies t = let t = {counter = t.counter + 1} in dependencies.files_write "/tmp/counter.txt" (string_of_int t.counter); t - + let increment_and_save_to_file t = increment_and_save_to_file_internal business_dependencies t - + module Internal_for_tests = struct type nonrec dependencies = dependencies = { files_read : string -> string; @@ -264,8 +263,8 @@ To choose between the field and the argument: - Else add a ``dependencies`` argument - but this requires duplicating each function, which ends up being very verbose if you have several functions - If your "state" value (usually a value of type ``t``) is passed to a polymorphic function like ``=`` or ``compare`` (which throw on function fields, and are famous for being an anti-pattern), and it is not possible for you to fix this anti-pattern, then either switch to function arguments, or wrap in an object. -Functors --------- +Using functors +-------------- This approach decouples the business code from its dependency modules. Note that unlike the Function records solution, this decouples both dependency functions **and abstract types**! @@ -291,9 +290,9 @@ Consider the following code: it is similar to the previous ``Counter`` example b type t = { counter : int; } - + let create counter = {counter} - + let increment_and_save_to_file t = let t = {counter = t.counter + 1} in let file = Files.openf "/tmp/counter.txt" in @@ -312,9 +311,9 @@ The technique is to transform ``Counter`` into a functor that takes a module loo val create : int -> t val increment_and_save_to_file : t -> t end - + include S - + module Internal_for_tests : sig module type FILES = sig type t @@ -330,21 +329,21 @@ The technique is to transform ``Counter`` into a functor that takes a module loo val create : int -> t val increment_and_save_to_file : t -> t end - + module type FILES = sig type t val openf : string -> t val write : t -> string -> unit val close : t -> unit end - + module Make (Files : FILES) = struct type t = { counter : int; } - + let create counter = {counter} - + let increment_and_save_to_file t = let t = {counter = t.counter + 1} in let file = Files.openf "/tmp/counter.txt" in @@ -352,13 +351,13 @@ The technique is to transform ``Counter`` into a functor that takes a module loo Files.close file; t end - + (* Do not be mistaken: here [Files] refers to the real, business [Files] module! *) include Make (Files) - + module Internal_for_tests = struct module type FILES = FILES - + module Make = Make end end @@ -403,4 +402,3 @@ Cons: - Additional complexity (functors, module types) - Does not scale well in more complex dependencies (``A`` depends on ``B`` and ``C`` types, and ``B`` also depends on ``C`` types) as it induces a lot of destructive substitutions and module noise to convince the typechecker that ``C.t`` in ``A`` is the same as ``C.t`` in ``B`` - Does not work for exposed and private (exposed in read-only) dependency types - diff --git a/docs/index.rst b/docs/index.rst index d4c99b25090188fafce03347ced6e7a9f9b752a9..bce3595e19216ea04fa555369c12a03494a82d37 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -180,6 +180,7 @@ in the :ref:`introduction `. alpha/cli-commands alpha/rpc alpha/liquidity_baking + alpha/timelock .. toctree:: :maxdepth: 2 diff --git a/docs/poetry.lock b/docs/poetry.lock index 10d0e2987241f1b14a0b8e58cface042a6e35800..9d066f1b89ed30716bcafc4dc2d69524e301af18 100644 --- a/docs/poetry.lock +++ b/docs/poetry.lock @@ -57,7 +57,7 @@ test = ["flake8 (==3.7.8)", "hypothesis (==3.55.3)"] [[package]] name = "docutils" -version = "0.17.1" +version = "0.16" description = "Docutils -- Python Documentation Utilities" category = "main" optional = false @@ -208,13 +208,14 @@ test = ["pytest", "pytest-cov", "html5lib", "cython", "typed-ast"] [[package]] name = "sphinx-rtd-theme" -version = "0.5.1" +version = "0.5.2" description = "Read the Docs theme for Sphinx" category = "main" optional = false python-versions = "*" [package.dependencies] +docutils = "<0.17" sphinx = "*" [package.extras] @@ -307,7 +308,7 @@ socks = ["PySocks (>=1.5.6,!=1.5.7,<2.0)"] [metadata] lock-version = "1.1" python-versions = "~3.9" -content-hash = "ba85037512be7d45c3304f810c9e5512731e6b6f22c2e10d19c56f3fe7bd2ab4" +content-hash = "ea1c5f85f2bd02167d7a6b649d7b315381ef32dd3658a33907aa37799e7427ea" [metadata.files] alabaster = [ @@ -335,8 +336,8 @@ commonmark = [ {file = "commonmark-0.9.1.tar.gz", hash = "sha256:452f9dc859be7f06631ddcb328b6919c67984aca654e5fefb3914d54691aed60"}, ] docutils = [ - {file = "docutils-0.17.1-py2.py3-none-any.whl", hash = "sha256:cf316c8370a737a022b72b56874f6602acf974a37a9fba42ec2876387549fc61"}, - {file = "docutils-0.17.1.tar.gz", hash = "sha256:686577d2e4c32380bb50cbb22f575ed742d58168cee37e99117a854bcd88f125"}, + {file = "docutils-0.16-py2.py3-none-any.whl", hash = "sha256:0c5b78adfbf7762415433f5515cd5c9e762339e23369dbe8000d84a4bf4ab3af"}, + {file = "docutils-0.16.tar.gz", hash = "sha256:c2de3a60e9e7d07be26b7f2b00ca0309c207e06c100f9cc2a94931fc75a478fc"}, ] idna = [ {file = "idna-3.2-py3-none-any.whl", hash = "sha256:14475042e284991034cb48e06f6851428fb14c4dc953acd9be9a5e95c7b6dd7a"}, @@ -419,8 +420,8 @@ sphinx = [ {file = "Sphinx-4.1.0.tar.gz", hash = "sha256:4219f14258ca5612a0c85ed9b7222d54da69724d7e9dd92d1819ad1bf65e1ad2"}, ] sphinx-rtd-theme = [ - {file = "sphinx_rtd_theme-0.5.1-py2.py3-none-any.whl", hash = "sha256:fa6bebd5ab9a73da8e102509a86f3fcc36dec04a0b52ea80e5a033b2aba00113"}, - {file = "sphinx_rtd_theme-0.5.1.tar.gz", hash = "sha256:eda689eda0c7301a80cf122dad28b1861e5605cbf455558f3775e1e8200e83a5"}, + {file = "sphinx_rtd_theme-0.5.2-py2.py3-none-any.whl", hash = "sha256:4a05bdbe8b1446d77a01e20a23ebc6777c74f43237035e76be89699308987d6f"}, + {file = "sphinx_rtd_theme-0.5.2.tar.gz", hash = "sha256:32bd3b5d13dc8186d7a42fc816a23d32e83a4827d7d9882948e7b837c232da5a"}, ] sphinxcontrib-applehelp = [ {file = "sphinxcontrib-applehelp-1.0.2.tar.gz", hash = "sha256:a072735ec80e7675e3f432fcae8610ecf509c5f1869d17e2eecff44389cdbc58"}, diff --git a/docs/pyproject.toml b/docs/pyproject.toml index 496f4370449435a142ca8c9fe5a7c63c28fae016..117aaf49058b23fc338879d9676ec65e9b5a8263 100644 --- a/docs/pyproject.toml +++ b/docs/pyproject.toml @@ -13,5 +13,5 @@ keywords = ["tezos"] [tool.poetry.dependencies] python = "~3.9" sphinx = "*" -sphinx-rtd-theme = "0.5.1" +sphinx-rtd-theme = "0.5.2" recommonmark = "*" diff --git a/docs/user/fa12.rst b/docs/user/fa12.rst index 754be1f710f226c0ade946cce98f8e057bc2e7c2..90f7b4449484c0fa012e87c15a3de89c2eeeefb2 100644 --- a/docs/user/fa12.rst +++ b/docs/user/fa12.rst @@ -86,7 +86,7 @@ optional argument ``--as ``, allowing an approved account `operator` t make transfers from `source` to any other accounts. The JSON format for the transfers is the following: -.. code-block:: json +.. code-block:: javascript [{ "token_contract": , // address or alias of the FA1.2 contract "destination": , // address or alias of the recipient of the transfer diff --git a/src/lib_shell/prevalidation.mli b/src/lib_shell/prevalidation.mli index 6a0abbadd6c3434c18c6db80546a5f697d35673f..d431a9092e14f9bafe961967c63f5ecdfee3cba9 100644 --- a/src/lib_shell/prevalidation.mli +++ b/src/lib_shell/prevalidation.mli @@ -53,7 +53,7 @@ module type T = sig [unsafe] because there are no length checks, unlike {!parse}. - @deprecated You should use {parse} instead. *) + @deprecated You should use [parse] instead. *) val parse_unsafe : bytes -> Proto.operation_data tzresult (** Creates a new prevalidation context w.r.t. the protocol associate to the diff --git a/src/lib_shell/prevalidator_classification.mli b/src/lib_shell/prevalidator_classification.mli index c059830d0384426b41a917495ead4cc58ac85629..d7d752cdf9ba83ee4f1da51271b6ff9a16e62f58 100644 --- a/src/lib_shell/prevalidator_classification.mli +++ b/src/lib_shell/prevalidator_classification.mli @@ -89,7 +89,7 @@ val remove_not_applied : Operation_hash.t -> t -> unit class field is full. In that case, the new operation is added to the class, and the one removed is discarded. An operation is also discarded when it is classified as [Refused]. The callback - [on_discarded_operation] which was given by the function {create} + [on_discarded_operation] which was given by the function [create] when the value [classes] was created is called on each discarded operation. *) val add : diff --git a/src/proto_alpha/lib_protocol/test/helpers/cpmm_logic.ml b/src/proto_alpha/lib_protocol/test/helpers/cpmm_logic.ml index 1915a60df644a7f9268eea7c60b9f3c69a137443..a1d4d8027c5808afbd02a62372fede6e8adc33f9 100644 --- a/src/proto_alpha/lib_protocol/test/helpers/cpmm_logic.ml +++ b/src/proto_alpha/lib_protocol/test/helpers/cpmm_logic.ml @@ -27,7 +27,7 @@ open Protocol open Alpha_context (** This is a simulation of the CPMM contract, as implemented in mligo - in {v src/proto_alpha/lib_protocol/contracts/cpmm.mligo v}. The + in [src/proto_alpha/lib_protocol/contracts/cpmm.mligo]. The interested reader should look for comments in this file to gain a better understanding of the contract logic. *) module Simulate_raw = struct diff --git a/src/proto_alpha/lib_protocol/test/helpers/liquidity_baking_machine.mli b/src/proto_alpha/lib_protocol/test/helpers/liquidity_baking_machine.mli index 24d1670afe51eb98024794495b6d2fd896921998..ed8fb9e64ba16a313667d089a7f79209799111d5 100644 --- a/src/proto_alpha/lib_protocol/test/helpers/liquidity_baking_machine.mli +++ b/src/proto_alpha/lib_protocol/test/helpers/liquidity_baking_machine.mli @@ -55,7 +55,7 @@ open Alpha_context That is, the {! ValidationMachine} reports desynchronization of the two machines, but cannot explain this desynchronization. *) -(** {1 Machine State Characterization} Module Type} *) +(** {1 Machine State Characterization} *) type xtz = int64