From eb44e66fdd170bb7e8baed7c835d263b1afd72d5 Mon Sep 17 00:00:00 2001 From: Nic Volanschi Date: Mon, 19 Sep 2022 17:55:55 +0200 Subject: [PATCH 1/4] doc: centralize protocol constants in protocol_overview.rst (see https://gitlab.com/tezos/tezos/-/merge_requests/4901#note_902474846) --- docs/alpha/proof_of_stake.rst | 16 +--------------- docs/alpha/protocol_overview.rst | 27 +++++++++++++++++++++++++++ 2 files changed, 28 insertions(+), 15 deletions(-) diff --git a/docs/alpha/proof_of_stake.rst b/docs/alpha/proof_of_stake.rst index 6f2a68e99ccf..688f6b4bfba1 100644 --- a/docs/alpha/proof_of_stake.rst +++ b/docs/alpha/proof_of_stake.rst @@ -136,24 +136,10 @@ simple procedure which has as its initial state: the level, the level belongs, and the slot. -.. _protocol_constants_alpha: - -Protocol constants ------------------- - -Protocols are parameterized by several parameters called *protocol constants*, which may vary from one protocol to another or from one network to another (for instance, test networks move faster). - -The list of protocol constants can be found in the API of the `Constants module `__. - -The values of protocol constants can be found using a :ref:`specific RPC call `, as shown in :ref:`this example `. - -In particular, the protocol constants related to the proof-of-stake mechanism are detailed :ref:`below `. -Other important subsystems of the protocol have their own list of protocol constants, such as the :ref:`consensus-related parameters ` and the :ref:`randomness generation parameters `. - .. _ps_constants_alpha: Proof-of-stake parameters -^^^^^^^^^^^^^^^^^^^^^^^^^ +------------------------- .. list-table:: :widths: 55 25 diff --git a/docs/alpha/protocol_overview.rst b/docs/alpha/protocol_overview.rst index 245a4ca7ea5d..131e154d253a 100644 --- a/docs/alpha/protocol_overview.rst +++ b/docs/alpha/protocol_overview.rst @@ -113,6 +113,33 @@ Manager operations can be grouped into batches forming a so-called group operati The list of operations can be obtained with :ref:`this rpc `. +.. _protocol_constants_alpha: + +Protocol constants +~~~~~~~~~~~~~~~~~~ + +Protocols are tuned by several *protocol constants*, such as the size of a nonce, or the number of blocks per cycle. +One can distinguish two kinds of protocol constants: + +- *fixed* prototocol constants, such as the size of a nonce, are values wired in the code of a protocol, and can only be changed by protocol amendment (that is, by adopting a new protocol) +- *parametric* protocol constants, such as the number of blocks per cycle, are values maintained in a read-only data structure that can be instantiated differently, for the same protocol, from one network to another (for instance, test networks move faster). + +A first list of protocol constants (both fixed and parametric) in protocol Alpha can be found in the API of module :package-api:`Alpha_context.Constants `. +This modules reexports selected definitions from the following modules: + +- module :package-api:`Constants_repr ` (fixed constants) +- module :package-api:`Constants_storage ` (parametric constants) +- module :package-api:`Constants.Parametric ` (data structure holding parametric constants). + +The values of protocol constants (both fixed and parametric) in any given protocol can be found using a :ref:`specific RPC call `, as shown in :ref:`this example `. + +Further documentation of most protocol constants can be found in the subsystems where they conceptually belong. +See, for example: + +- :ref:`proof-of-stake parameters `. +- :ref:`consensus-related parameters ` +- :ref:`randomness generation parameters `. + See also ~~~~~~~~ -- GitLab From bce9e524ec212710d341203aea26d73d387f0837 Mon Sep 17 00:00:00 2001 From: Eugen Zalinescu Date: Thu, 22 Sep 2022 19:15:50 +0000 Subject: [PATCH 2/4] doc: fixup list of modules listing the constants --- docs/alpha/protocol_overview.rst | 7 +------ 1 file changed, 1 insertion(+), 6 deletions(-) diff --git a/docs/alpha/protocol_overview.rst b/docs/alpha/protocol_overview.rst index 131e154d253a..37f249816fee 100644 --- a/docs/alpha/protocol_overview.rst +++ b/docs/alpha/protocol_overview.rst @@ -124,12 +124,7 @@ One can distinguish two kinds of protocol constants: - *fixed* prototocol constants, such as the size of a nonce, are values wired in the code of a protocol, and can only be changed by protocol amendment (that is, by adopting a new protocol) - *parametric* protocol constants, such as the number of blocks per cycle, are values maintained in a read-only data structure that can be instantiated differently, for the same protocol, from one network to another (for instance, test networks move faster). -A first list of protocol constants (both fixed and parametric) in protocol Alpha can be found in the API of module :package-api:`Alpha_context.Constants `. -This modules reexports selected definitions from the following modules: - -- module :package-api:`Constants_repr ` (fixed constants) -- module :package-api:`Constants_storage ` (parametric constants) -- module :package-api:`Constants.Parametric ` (data structure holding parametric constants). +Fixed protocol constants are defined in the module module :package-api:`Constants_repr ` while parametric constants are defined in the module :package-api:`Constants_parametric_repr ```` The values of protocol constants (both fixed and parametric) in any given protocol can be found using a :ref:`specific RPC call `, as shown in :ref:`this example `. -- GitLab From ed34e95e0f0fccebea9afb95c2620d7405f46e1d Mon Sep 17 00:00:00 2001 From: Nic Volanschi Date: Thu, 22 Sep 2022 21:43:29 +0200 Subject: [PATCH 3/4] doc: add RPC for parametric constants --- docs/alpha/protocol_overview.rst | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/docs/alpha/protocol_overview.rst b/docs/alpha/protocol_overview.rst index 37f249816fee..4760a194aca1 100644 --- a/docs/alpha/protocol_overview.rst +++ b/docs/alpha/protocol_overview.rst @@ -124,11 +124,17 @@ One can distinguish two kinds of protocol constants: - *fixed* prototocol constants, such as the size of a nonce, are values wired in the code of a protocol, and can only be changed by protocol amendment (that is, by adopting a new protocol) - *parametric* protocol constants, such as the number of blocks per cycle, are values maintained in a read-only data structure that can be instantiated differently, for the same protocol, from one network to another (for instance, test networks move faster). -Fixed protocol constants are defined in the module module :package-api:`Constants_repr ` while parametric constants are defined in the module :package-api:`Constants_parametric_repr ```` +The *list* of protocol constants can be found in the OCaml APIs: -The values of protocol constants (both fixed and parametric) in any given protocol can be found using a :ref:`specific RPC call `, as shown in :ref:`this example `. +- fixed protocol constants are defined in the module :package-api:`Constants_repr ` +- parametric constants are defined in the module :package-api:`Constants_parametric_repr ` -Further documentation of most protocol constants can be found in the subsystems where they conceptually belong. +The *values* of protocol constants in any given protocol can be found using specific RPC calls: + +- one RPC for :ref:`all constants `, as shown in :ref:`this example ` +- one RPC for :ref:`the parametric constants `. + +Further documentation of various protocol constants can be found in the subsystems where they conceptually belong. See, for example: - :ref:`proof-of-stake parameters `. -- GitLab From c2234227dc6ccd5ed9381c0c854fd2a4f6a0646f Mon Sep 17 00:00:00 2001 From: Nic Volanschi Date: Fri, 23 Sep 2022 15:30:15 +0200 Subject: [PATCH 4/4] doc: backport changes to K --- docs/jakarta/proof_of_stake.rst | 1 - docs/kathmandu/proof_of_stake.rst | 15 +------------- docs/kathmandu/protocol_overview.rst | 29 ++++++++++++++++++++++++++++ 3 files changed, 30 insertions(+), 15 deletions(-) diff --git a/docs/jakarta/proof_of_stake.rst b/docs/jakarta/proof_of_stake.rst index 69df8355d600..2882410107c8 100644 --- a/docs/jakarta/proof_of_stake.rst +++ b/docs/jakarta/proof_of_stake.rst @@ -184,7 +184,6 @@ simple procedure which has as its initial state: the level, the level belongs, and the slot. -.. _protocol_constants: .. _protocol_constants_jakarta: Protocol constants diff --git a/docs/kathmandu/proof_of_stake.rst b/docs/kathmandu/proof_of_stake.rst index d4b892b35e8a..ae1a8c80c05c 100644 --- a/docs/kathmandu/proof_of_stake.rst +++ b/docs/kathmandu/proof_of_stake.rst @@ -136,23 +136,10 @@ simple procedure which has as its initial state: the level, the level belongs, and the slot. -.. _protocol_constants_kathmandu: - -Protocol constants ------------------- - -Protocols are parameterized by several parameters called *protocol constants*, which may vary from one protocol to another or from one network to another (for instance, test networks move faster). - -The list of protocol constants can be found in the API of the `Constants module `__. - -The values of protocol constants can be found using a :ref:`specific RPC call `, as shown in :ref:`this example `. - -In particular, the protocol constants related to the proof-of-stake mechanism are detailed below. - .. _ps_constants_kathmandu: Proof-of-stake parameters -^^^^^^^^^^^^^^^^^^^^^^^^^ +------------------------- .. list-table:: :widths: 55 25 diff --git a/docs/kathmandu/protocol_overview.rst b/docs/kathmandu/protocol_overview.rst index 8ec44213a5c9..3ba88eff06b7 100644 --- a/docs/kathmandu/protocol_overview.rst +++ b/docs/kathmandu/protocol_overview.rst @@ -113,6 +113,35 @@ Manager operations can be grouped into batches forming a so-called group operati The list of operations can be obtained with :ref:`this rpc `. +.. _protocol_constants: +.. _protocol_constants_kathmandu: + +Protocol constants +~~~~~~~~~~~~~~~~~~ + +Protocols are tuned by several *protocol constants*, such as the size of a nonce, or the number of blocks per cycle. +One can distinguish two kinds of protocol constants: + +- *fixed* prototocol constants, such as the size of a nonce, are values wired in the code of a protocol, and can only be changed by protocol amendment (that is, by adopting a new protocol) +- *parametric* protocol constants, such as the number of blocks per cycle, are values maintained in a read-only data structure that can be instantiated differently, for the same protocol, from one network to another (for instance, test networks move faster). + +The *list* of protocol constants can be found in the OCaml APIs: + +- fixed protocol constants are defined in the module :package-api:`Constants_repr ` +- parametric constants are defined in the module :package-api:`Constants_parametric_repr ` + +The *values* of protocol constants in any given protocol can be found using specific RPC calls: + +- one RPC for :ref:`all constants `, as shown in :ref:`this example ` +- one RPC for :ref:`the parametric constants `. + +Further documentation of various protocol constants can be found in the subsystems where they conceptually belong. +See, for example: + +- :ref:`proof-of-stake parameters `. +- :ref:`consensus-related parameters ` +- :ref:`randomness generation parameters `. + See also ~~~~~~~~ -- GitLab