From eb5401a6a826ed24b496ece2af796f8b737769f7 Mon Sep 17 00:00:00 2001 From: Nic Volanschi Date: Thu, 6 Jun 2024 14:22:31 +0200 Subject: [PATCH 1/5] doc: explain that v20 is not in APT yet --- docs/introduction/howtoget.rst | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/introduction/howtoget.rst b/docs/introduction/howtoget.rst index fa7cca23f537..c6d3aec8ff77 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`` -- GitLab From 3b5430ea1395023bd0001a1c5268065296eba9e9 Mon Sep 17 00:00:00 2001 From: Nic Volanschi Date: Tue, 11 Jun 2024 10:18:43 +0200 Subject: [PATCH 2/5] doc: rename trailing mentions of (rollup) staker to "committer" --- docs/shell/smart_rollup_node.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/shell/smart_rollup_node.rst b/docs/shell/smart_rollup_node.rst index 6dde2cb434ae..d014745c7a44 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 -- GitLab From 11a18234dfe6d1ca7989e28194bef7e6f6a8ef6f Mon Sep 17 00:00:00 2001 From: Nic Volanschi Date: Wed, 12 Jun 2024 15:50:24 +0200 Subject: [PATCH 3/5] doc: small fixes in new page alpha/adaptive_slashing --- docs/alpha/adaptive_slashing.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/alpha/adaptive_slashing.rst b/docs/alpha/adaptive_slashing.rst index bb801509e0dd..dc52debfc675 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 -- GitLab From b851a7ded80e20fbca8078d8dcd6b1e59c943d9b Mon Sep 17 00:00:00 2001 From: Nic Volanschi Date: Thu, 20 Jun 2024 10:30:09 +0200 Subject: [PATCH 4/5] doc: add guidelines for images in the doc --- docs/README.rst | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/docs/README.rst b/docs/README.rst index 60257a19076d..da245f2e06e3 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 -------------------------------- -- GitLab From 8f2260090da30181267ad4e0dd52c3247df2346a Mon Sep 17 00:00:00 2001 From: Eugen Zalinescu Date: Fri, 21 Jun 2024 09:27:58 +0200 Subject: [PATCH 5/5] Doc: typos in version-20 --- docs/releases/version-20.rst | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/releases/version-20.rst b/docs/releases/version-20.rst index 1923056fc441..c81a250a13d4 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) -- GitLab