diff --git a/docs/README.rst b/docs/README.rst index 60257a19076d01bb704e525d6bbbf33cfba2bc79..da245f2e06e3d8ab47c35f92d4394f0107c50326 100644 --- a/docs/README.rst +++ b/docs/README.rst @@ -156,6 +156,15 @@ For such reasons: Thus, you may choose your own formatting style, while tolerating different styles from other contributors. +Images +------ + +When including images in the documentation: + +- commit under Git an image format which can be displayed by Gitlab's "View file" feature, such as ``png`` or ``jpeg``, to ease reviewing; +- preferably, also commit a source form of the image that can be maintained, explaining which tool to use if necessary (in a local Readme file, see :src:`docs/images/README.md` as an example); +- image files are usually placed next to the pages where they are used; as an exception, images to be used in several pages from different directories, or in toplevel page such as ``index.rst``, should be placed under :src:`docs/images/`. + Writing executable documentation -------------------------------- diff --git a/docs/alpha/adaptive_slashing.rst b/docs/alpha/adaptive_slashing.rst index bb801509e0ddc43ab67b3b4c1d509b94c971d41f..dc52debfc675f7176ac4fc285644cc932c04108f 100644 --- a/docs/alpha/adaptive_slashing.rst +++ b/docs/alpha/adaptive_slashing.rst @@ -16,14 +16,14 @@ Nonetheless, it overlooks the impact of double signing of attestations on the entire block committee, treating all cases uniformly and ignoring collusion among bakers. -To better reflect this distinction, the Paris protocol +To better reflect this distinction, protocols starting with Paris adjusts the amount of slashing based on the fraction of double-attestation in a single block. A low fraction of misconduct incurs moderate penalties, while a high fraction of misconduct is deemed to be critical and faces more serious repercussions. -This document presents the definition of an :ref:`adaptive slashing -function` implementing this idea, as well as a +This document presents the definition of the :ref:`adaptive slashing +function` implementing this idea, as well as the :ref:`new forbidden period`. .. _adaptive_slashing_fn_alpha: @@ -65,7 +65,7 @@ following: | 100.00% | | +------------------------------------------+----------------------------------------+ -Instead of using a constant function as in Oxford2, we propose to use +Instead of using a constant function as in Oxford2, we use a convex function that saturates at 100% when a critical fraction of doubled attestations are issued. Accidental double attestations are unlikely to cause a large amount of slashing to be applied, but @@ -126,8 +126,8 @@ where :math:`(b, B) \in C` means that: .. _new_forbidden_period_alpha: -A new definition for the forbidden period -========================================= +New definition for the forbidden period +======================================= Given that slashing occurs with a delay, immediate action at denunciation time is necessary upon clear evidence of a baker's diff --git a/docs/introduction/howtoget.rst b/docs/introduction/howtoget.rst index fa7cca23f5378b8ee669fe7bf19bc409ffd6f714..c6d3aec8ff776b2f6929a658aee6a0bcc5e7f700 100644 --- a/docs/introduction/howtoget.rst +++ b/docs/introduction/howtoget.rst @@ -97,6 +97,10 @@ If you're using Ubuntu or Debian, you can also install packages with Octez binar using ``apt`` directly from our APT repository, instead of going to the Octez release page as explained above. +.. warning:: + + This APT repository is currently empty. For installing the latest release (:doc:`../releases/version-20`), you must still use the installation method above. + We support the following distribution/releases: - ``debian/bookworm`` - ``ubuntu/focal`` diff --git a/docs/releases/version-20.rst b/docs/releases/version-20.rst index 1923056fc441a10957e29fbe4db2a05a808f65ba..c81a250a13d4206caf46f331712b04f5b32fc1da 100644 --- a/docs/releases/version-20.rst +++ b/docs/releases/version-20.rst @@ -16,12 +16,12 @@ its associated protocol-specific executable binaries (baker, accuser, etc). ParisB 2 was included in v20.0 as a *User-Activated Protocol Override* (UAPO). This meant that nodes running v20.0 activated ParisB 2, ``PtParisBxoLz5gzMmn3d9WBQNoPSZakgnkMC2VNuQ3KXfUtUQeZ`` instead of -the original ParisB proposal before block `#5,726,209 `__. +the original ParisB proposal before level `#5,726,209 `__. Additional issues were discovered after the activation of ParisB 2, including a critical liveness issue with Smart Rollups. These issues are solved in the bug-fix protocol upgrade ParisC included in Octez v20.1. ParisC is included in v20.1 as a *User-Activated Upgrade* (UAU). -This means that nodes running v20.1 will automatically activate ParisC at the end of cycle 749, just before `#5,898,24 `_. +This means that nodes running v20.1 will automatically activate ParisC at the end of cycle 749, just before `#5,898,241 `_. Octez v20.1 also includes minor fixes to Smart Rollup nodes addressing issues observed after the activation of Paris. More precisely, the Smart Rollup nodes released with Octez v20 and earlier keep using the constants of the previous protocol even after the activation of a new one. This means that at activation of ParisB Smart Rollup nodes did not use the correct commitment period to compute and publish commitments. To fix that, in Octez v20.1, the Smart Rollup node: @@ -40,9 +40,10 @@ Some deprecated RPCs have been removed. Please check `the changelog <../CHANGES. The RPC ``/health/ready`` has been introduced to get the status of the RPC server. -Starting from Octez v20, we strongly advise nodes and bakers operators to synchronise their clocks using NTP as issued in `the node section of getting started `__ +Starting from Octez v20, we strongly advise nodes and bakers operators to synchronise their clocks using NTP as issued in `the node section of getting started `__. Regarding the minimal hardware, we advise nodes and bakers operators to run on at least the following hardware requierements: + - 3 cores, 2 needed by the node and 1 needed by the baker (arm64 or amd64/x86-64) - 8GB of RAM + 8GB of swap or 16GB of RAM - 100GB SSD storage (or similar I/O performance) diff --git a/docs/shell/smart_rollup_node.rst b/docs/shell/smart_rollup_node.rst index 6dde2cb434aef34640be7ef0f4fad9aefce4ef70..d014745c7a4433ee1f2a6f8422652728ee220fa8 100644 --- a/docs/shell/smart_rollup_node.rst +++ b/docs/shell/smart_rollup_node.rst @@ -210,14 +210,14 @@ First, we need to decide on a mode the rollup node will run: #. ``accuser`` follows the layer1-chain and computes commitments but does not publish them. Only when a conflicting commitment (published by another - staker) is detected will the "accuser node" publish a commitment and + committer) is detected will the "accuser node" publish a commitment and participate in the subsequent refutation game. -#. ``bailout`` mode is designed to assist stakers in recovering their bonds. +#. ``bailout`` mode is designed to assist committers in recovering their bonds. It functions as a slightly modified version of "Accuser", differing in that it does not post any new commitments but instead focuses on defending the ones that have been previously submitted. When operating in bailout mode, the expectation is to initiate a recover bond - operation when the operator is no longer staked on any commitment. If the node detects that this + operation when the operator is no longer staking on any commitment. If the node detects that this operation has been successful, it can gratefully exit. #. ``custom`` mode refers to a mode where the users individually select which