diff --git a/docs/010/consensus.rst b/docs/010/consensus.rst index 53fe408595df1f86ed95119b35f391ad81dd5ae7..75fd7acace8f098385abf2a2cd0766c1903464b0 100644 --- a/docs/010/consensus.rst +++ b/docs/010/consensus.rst @@ -273,7 +273,7 @@ that cycle. .. _cs_constants_010: Consensus protocol parameters -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +----------------------------- In this section we map the above notation to their corresponding parameter values. diff --git a/docs/011/consensus.rst b/docs/011/consensus.rst index 76d1c0299796997f5e993bf51db25c459d352c6b..a53bc9e06fc047643e0e9340e48ac2a70c3ddc73 100644 --- a/docs/011/consensus.rst +++ b/docs/011/consensus.rst @@ -269,7 +269,7 @@ that cycle. .. _cs_constants_011: Consensus protocol parameters -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +----------------------------- In this section we map the above notation to their corresponding parameter values. diff --git a/docs/alpha/consensus.rst b/docs/alpha/consensus.rst index 9764029c6cd699a4cea801d80dea842ca0365fca..0b4090c9562fc266e1999d5b6eda7abab2f754b9 100644 --- a/docs/alpha/consensus.rst +++ b/docs/alpha/consensus.rst @@ -332,6 +332,9 @@ The bonus per additional endorsement slot is in turn ``bonus / ``CONSENSUS_COMMITTEE_SIZE / 3`` validator slots corresponding to the additional endorsements included in a block). The rewards per endorsement slot are ``endorsing_rewards / CONSENSUS_COMMITTEE_SIZE``. +Assuming ``CONSENSUS_COMMITTEE_SIZE = 8000``, we obtain a bonus per slot of +``10 / (8000 / 3) = 0.00375`` tez and an endorsing +rewards per slot of ``20 / 8000 = 0.0025`` tez. Let's take an example. Say a block has round 1, is proposed by delegate B, and contains the payload from round 0 produced by delegate @@ -349,13 +352,12 @@ included during that cycle has been ``3,123,456`` slots. Given that this number bigger than the minimum required (``3,276,800 * 2 / 3``), it receives an endorsing reward of ``3,276,800 * 0.0025 = 8192`` tez for that cycle. - .. _slashing_alpha: Slashing ^^^^^^^^ -Like in Emmy*, not revealing nonces and double singing are punishable. If a +Like in Emmy*, not revealing nonces and double signing are punishable. If a validator does not reveal its nonce by the end of the cycle, it does not receive its endorsing rewards. If a validator double signs, that is, it double bakes or it double (pre)endorses (which means voting on two different proposals at the @@ -380,7 +382,7 @@ participation of a selfish baker does not have an impact. .. _cs_constants_alpha: Consensus protocol parameters -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +----------------------------- .. list-table:: :widths: 55 25 @@ -391,7 +393,7 @@ Consensus protocol parameters * - ``CONSENSUS_COMMITTEE_SIZE`` - 7000 * - ``CONSENSUS_THRESHOLD`` - - ``ceil(2*CONSENSUS_COMMITTEE_SIZE/3)`` + - ``ceil(2 * CONSENSUS_COMMITTEE_SIZE / 3)`` * - ``ROUND_DURATIONS`` - [30s, 45s] * - ``MINIMAL_PARTICIPATION_RATIO`` @@ -407,9 +409,9 @@ Consensus protocol parameters * - ``BAKING_REWARD_FIXED_PORTION`` - 10 tez * - ``BAKING_REWARD_BONUS_PER_SLOT`` - - ``bonus / (CONSENSUS_COMMITTEE_SIZE / 3)`` tez + - ``bonus / (CONSENSUS_COMMITTEE_SIZE / 3)`` = 0.004286 tez * - ``ENDORSING_REWARD_PER_SLOT`` - - ``endorsing_reward / CONSENSUS_COMMITTEE_SIZE`` tez + - ``endorsing_reward / CONSENSUS_COMMITTEE_SIZE`` = 0.002857 tez Further External Resources diff --git a/docs/alpha/glossary.rst b/docs/alpha/glossary.rst index 82924b7fa384a8134784c122947ad3521916fe55..8d156c35386c61670b9489c96754aa3b830d2d13 100644 --- a/docs/alpha/glossary.rst +++ b/docs/alpha/glossary.rst @@ -45,7 +45,7 @@ _`Baking`/_`Endorsing rights` A delegate_ is allowed to bake/endorse a block_ if he holds the baking/endorsing right for that block_. At the start of a Cycle_, baking and endorsing rights are computed for all the block_ heights in the - cycle_, based on the proportion of Rolls owned by each account. + cycle_, based on the proportion of the stake owned by each account. For each block_ height, there are several accounts that are allowed to bake. These different accounts are given different Priorities. diff --git a/docs/alpha/proof_of_stake.rst b/docs/alpha/proof_of_stake.rst index 116e636f55f14508d2e627b5192a7681a4d6e181..ec2169517417f5144723f0916ab40cf674b48925 100644 --- a/docs/alpha/proof_of_stake.rst +++ b/docs/alpha/proof_of_stake.rst @@ -39,7 +39,7 @@ A delegate participates in consensus and in governance with a weight proportional with their delegated stake, which includes the balances of all the accounts that delegate to it, and also the balance of the delegate itself. To participate in consensus or in governance, a -delegate needs to have at a minimal stake, which is given by the +delegate needs to have at least a minimal stake, which is given by the ``TOKENS_PER_ROLL`` :ref:`protocol constant `. diff --git a/docs/alpha/voting.rst b/docs/alpha/voting.rst index 869c77139ea99f4cc584fa86842761ac396aad3e..ee5b5044f58d77e9d23613e7f603736eb0f80730 100644 --- a/docs/alpha/voting.rst +++ b/docs/alpha/voting.rst @@ -11,8 +11,6 @@ protocol itself. Consequently the amendment rules themselves are subject to amendments. The rest of this page gives more details about the amendment and voting process. -Other than this page, there is an excellent overview from `Jacob -Arluck on medium `__. Periods ------- @@ -35,7 +33,7 @@ The five periods are as follows: At the end of a **proposal period**, the proposal with most support is selected and we move to an **exploration period**. Note that support is - measured in the cumulated number of rolls that delegates supporting the + measured in the cumulated number of :ref:`rolls ` that delegates supporting the proposal have. E.g., a proposal supported by a single delegate with 100 rolls has more support than a proposal supported by two delegates with 20 rolls each. @@ -315,8 +313,13 @@ ballots can be submitted once with:: tezos-client submit ballot for -Other resources -~~~~~~~~~~~~~~~ +Further External Resources +-------------------------- + +Further details and explanations on the voting procedure can be found at: + +- `the Open Tezos entry`_ +- `the Tezos Agora entry`_. For more details on the client commands refer to the manual at :ref:`client_manual_alpha`. diff --git a/docs/doc_gen/rpc_doc.ml b/docs/doc_gen/rpc_doc.ml index 7e61d560f1cc9004f5118dc4643b5db54be6f16c..6ccd9516631c6379500c28ee1f878f8ef1e536cd 100644 --- a/docs/doc_gen/rpc_doc.ml +++ b/docs/doc_gen/rpc_doc.ml @@ -346,7 +346,7 @@ let pp_document ppf descriptions version = Format.pp_set_max_indent ppf 9000 ; let version_suffix = if version = "" then "" else "_" ^ version in Format.fprintf ppf "%a" Rst.pp_ref ("rpc_index" ^ version_suffix) ; - Rst.pp_h2 ppf "RPCs - Index" ; + Rst.pp_h1 ppf "RPCs - Reference" ; List.iter (fun (name, intro, prefix, rpc_dir) -> (* If provided, insert the introductory include *) diff --git a/docs/include/rpc_introduction.rst.inc b/docs/include/rpc_introduction.rst.inc index f8195992215e183d384a08a1b3ea39f3060dcb0d..badc9de669553d57d96b54a0f74ecdb0ba6d1e4d 100644 --- a/docs/include/rpc_introduction.rst.inc +++ b/docs/include/rpc_introduction.rst.inc @@ -1,4 +1,7 @@ -Shell and Protocol -================== +RPCs - Index +************ -The protocol-independent RPCs are described :ref:`here `. +Shell +===== + +The protocol-independent RPCs are described :doc:`here <../shell/rpc>`. diff --git a/docs/introduction/howtouse.rst b/docs/introduction/howtouse.rst index 47e17f02b5d8f179beba2fdd3f71ffd1af4a2cdd..fd3a85006fca7c439de3ea8971baf48550a079ce 100644 --- a/docs/introduction/howtouse.rst +++ b/docs/introduction/howtouse.rst @@ -52,14 +52,23 @@ To see the usage of one specific command, you may also type the command without tezos-client transfer -However, beware that the commands available on the client depend on the specific -protocol run by the node. For instance, ``transfer`` is not available when -the node runs the genesis protocol, which may happen for a few minutes when -launching a node for the first time, or when the client is not connected to a -node. In the last case, the above command generates a warning:: - - Warning: - Failed to acquire the protocol version from the node +.. warning:: + + Beware that the commands available on the client depend on the specific + protocol run by the node. For instance, ``transfer`` is not available when + the node runs the genesis protocol, which may happen for a few minutes when + launching a node for the first time, **or when the client is not connected + to a node**. In the last case, the above command generates a warning + followed by an error:: + + Warning: + Failed to acquire the protocol version from the node + [...] + Error: + Unrecognized command. + Try using the man command to get more information. + Usage: + [...] .. _tezos_client_protocol: diff --git a/docs/protocols/tenderbake.rst b/docs/protocols/tenderbake.rst index cfaa150e271477837547a50fa675133f55834763..418f17ef0fa530a5925f54e0a56b3112b1739eb2 100644 --- a/docs/protocols/tenderbake.rst +++ b/docs/protocols/tenderbake.rst @@ -2,14 +2,14 @@ Tenderbake ========== This page contains a summary of the changes brought by the Tenderbake merge request (:gl:`!3738`). -Please refer to :doc:`the documentation<../alpha/consensus>` and to this `blog post`_ for an overview of the Tenderbake consensus algorithm and its motivation. +Please refer to :doc:`the documentation<../alpha/consensus>` and to this `blog post `_ for an overview of the Tenderbake consensus algorithm and its motivation. Protocol -------- The whole incentives scheme has been updated. In particular the security deposit mechanism has been overhauled. -See :doc:`../alpha/consensus`. +See :doc:`the documentation<../alpha/consensus>`. Rolls do not play an essential role anymore, in that the computation of delegates' rights is based directly on the delegates' stake. Snapshots are still used: it is the entire delegate's stake that is snapshot. @@ -25,7 +25,7 @@ Operations The layout of the endorsement operations has changed. It consists of a level, a round, a slot, and a payload hash. -There is a new consensus operation, `preendorsements`, with the same layout as an endorsement. +There is a new consensus operation, `preendorsement`, with the same layout as an endorsement. There is a new anonymous operation, `double preendorsement evidence`, with the same layout as a double endorsement evidence. diff --git a/docs/shell/p2p.rst b/docs/shell/p2p.rst index 83929902c63bb780ba980026abecf4ed135e890b..1eddd3f9527a73ba782200f346e1e83f59bb54a8 100644 --- a/docs/shell/p2p.rst +++ b/docs/shell/p2p.rst @@ -49,9 +49,9 @@ are used to store incoming (resp. outgoing) messages for each peer. This further restricts the speed at which communication is possible with a peer; when a queue is full, it is not possible to read (resp. write) an additional message. The high-level -`P2p_socket.connection -<../api/odoc/tezos-p2p/Tezos_p2p/P2p_socket/index.html#type-connection>`__ -type by the P2P layer is basically a UNIX socket upgraded with I/O +`P2p_socket.t +<../api/odoc/_html/tezos-p2p/Tezos_p2p/P2p_socket/index.html#type-t>`__ +type defined by the P2P layer is basically a UNIX socket upgraded with I/O scheduling, peer metadata, cryptographic keys, and two message queues operated by dedicated workers which operate on those queues. @@ -59,7 +59,7 @@ Pool of connections ~~~~~~~~~~~~~~~~~~~ All the above modules are used in `P2p_pool -<../api/odoc/tezos-p2p/Tezos_p2p/P2p_pool/index.html>`__, which +<../api/api-inline.html#tezos-p2p/Tezos_p2p/P2p_pool/index.html>`__, which constitutes the core of the P2P layer, together with the worker processes described below. It comprises various tables of connections as well as methods to query them, also connections are extended with @@ -67,19 +67,17 @@ another message queue where lower-level messages (like responses to ping) are filtered out and only application-level messages are kept. The main entry point of the P2P layer is in module `P2p -<../api/odoc/tezos-p2p/Tezos_p2p/P2p/index.html>`__. See below +<../api/api-inline.html#tezos-p2p/Tezos_p2p/P2p/index.html>`__. See below for a description of workers acting onto the P2P layer. -Welcome worker --------------- +Welcome worker & connect handler +-------------------------------- -The welcome worker is responsible for accepting incoming connections -and register them into the pool of connections managed by the P2P -layer. It basically runs the ``accept(2)`` syscall and call -`P2p_pool.accept -<../api/odoc/tezos-p2p/Tezos_p2p/P2p_pool/index.html#val-accept>`__ so -that it is made aware of an incoming connection. From there, the pool -will decide how this new connection must be handled. +The welcome worker & the connect handler are responsible for accepting incoming +connections and register them into the pool of connections managed by the P2P +layer. It basically runs the ``accept(2)`` syscall and build the stack of types +that composed a connection. They decide how this new connection must be +handled. {Black, White, Grey}lists ~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/shell/rpc_introduction.rst.inc b/docs/shell/rpc_introduction.rst.inc index 72950bff19c1ad9ddb29dff69a72dd4d48b257d4..32b382da830301a889f0612a058b66ff69dcc836 100644 --- a/docs/shell/rpc_introduction.rst.inc +++ b/docs/shell/rpc_introduction.rst.inc @@ -1,5 +1,8 @@ +RPCs - Index +************ + Protocol ======== Some RPCs are specific to a particular version of the Tezos protocol. -Those of the protocol currently active on Mainnet are described :ref:`here `. +Those of the protocol currently active on Mainnet are described :doc:`here <../active/rpc>`.