From 4ccc755b490d5bf5517b4fa17bbd6ccb56d446f7 Mon Sep 17 00:00:00 2001 From: Adam Allombert-Goget Date: Tue, 24 Sep 2024 10:30:57 +0200 Subject: [PATCH 1/2] docs/developer: add an architecture section & baker file --- docs/developer/baker.rst | 63 +++++++++++++++++++++++++++ docs/developer/octez_architecture.rst | 12 +++++ docs/index.rst | 4 +- 3 files changed, 78 insertions(+), 1 deletion(-) create mode 100644 docs/developer/baker.rst create mode 100644 docs/developer/octez_architecture.rst diff --git a/docs/developer/baker.rst b/docs/developer/baker.rst new file mode 100644 index 000000000000..70ae16040368 --- /dev/null +++ b/docs/developer/baker.rst @@ -0,0 +1,63 @@ +Baker +===== + +The Octez baker is an executable responsible for the creation of blocks and +consensus operations on the Tezos blockchain with respect to the Tenderbake +consensus algorithm. + +The baker is designed as finite-state machine, with states, transitions and +:package-api:`events`. + +The machine is orchestrated by a scheduler, which operates in a never-ending +loop to listen for ongoing events, trigger transitions accordingly, and perform +side-effects. + +It relies on two workers running alongside the main scheduling loop to manage +auxiliary tasks: + +- the operation worker monitors consensus operations from the node via the ``/mempool/monitor_operations`` RPC, reporting ``Prequorum_reached`` and ``Quorum_reached`` events to the main scheduler. + +- the forge worker is responsible for crafting blocks and operations. It receives crafting requests from the scheduler and notifies it back upon completion with ``New_forge_event (Block_ready block)``, ``New_forge_event (Preattestation_ready op)``, or ``New_forge_event (Attestation_ready op)`` events. + +.. _baker_scheduling: + +Scheduling +---------- + +:package-api:`Documentation` + +.. _baker_states: + +States +------ + +:package-api:`Documentation` + +.. _baker_transitions: + +Transitions +----------- + +:package-api:`Documentation` + +.. _baker_actions: + +Actions +------- + +:package-api:`Documentation` + +.. _baker_operation_worker: + +Operation worker +---------------- + +:package-api:`Documentation` + +.. _baker_forge_worker: + +Forge worker +------------ + +:package-api:`Documentation` + diff --git a/docs/developer/octez_architecture.rst b/docs/developer/octez_architecture.rst new file mode 100644 index 000000000000..1499b638816e --- /dev/null +++ b/docs/developer/octez_architecture.rst @@ -0,0 +1,12 @@ +Octez Architecture Details +========================== + +The following pages offer different modeling perspectives of some key components within +Octez. They form an onboarding guide for anyone looking to navigate and +contribute to the codebase. This section assumes the reader is familiar with +both Octez and the current protocol reference manuals. + +.. toctree:: + :maxdepth: 2 + + baker diff --git a/docs/index.rst b/docs/index.rst index 0ebcbb2456d9..01660fa0a538 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -127,7 +127,8 @@ Platform developers can find a rich set of explanations, tutorials, and howtos, - programming tutorials covering various libraries and frameworks specific to the Octez OCaml implementation, such as using :doc:`developer/gadt`, using :doc:`developer/error_monad`, using :doc:`developer/clic`, :doc:`developer/event_logging_framework`, etc. - howtos for specific maintenance tasks such as :doc:`developer/michelson_instructions`, :doc:`developer/protocol_environment_upgrade`, or :doc:`developer/howto-freeze-protocols` - a whole subsection on the :doc:`various testing frameworks ` for Octez, explaining how to use them and how to add different kinds of tests -- presentations of various tools for platform developers, such as support for :doc:`developer/profiling` and :doc:`developer/snoop`. +- presentations of various tools for platform developers, such as support for :doc:`developer/profiling` and :doc:`developer/snoop` +- a subsection on :doc:`architecture details` providing detailed explanations of the internal structure and design of key components in the Octez codebase. Platform developers are also provided reference materials for internal APIs of Octez, such as: @@ -225,6 +226,7 @@ Platform developers are also provided reference materials for internal APIs of O developer/contributing_index developer/programming + developer/octez_architecture developer/testing_index developer/maintaining README -- GitLab From c3c5e2883a5a8af6a32b1b26274320b2be09261c Mon Sep 17 00:00:00 2001 From: Adam Allombert-Goget Date: Wed, 25 Sep 2024 10:11:02 +0200 Subject: [PATCH 2/2] docs/baker: add scheduling section --- docs/developer/baker.rst | 27 +++++++++++++++++++++------ 1 file changed, 21 insertions(+), 6 deletions(-) diff --git a/docs/developer/baker.rst b/docs/developer/baker.rst index 70ae16040368..91791fefc2ed 100644 --- a/docs/developer/baker.rst +++ b/docs/developer/baker.rst @@ -1,12 +1,12 @@ -Baker -===== +Baker application's architecture +================================ The Octez baker is an executable responsible for the creation of blocks and -consensus operations on the Tezos blockchain with respect to the Tenderbake +consensus operations on the Tezos blockchain according to the Tenderbake consensus algorithm. The baker is designed as finite-state machine, with states, transitions and -:package-api:`events`. +:package-api:`specific consensus-related events `. The machine is orchestrated by a scheduler, which operates in a never-ending loop to listen for ongoing events, trigger transitions accordingly, and perform @@ -17,14 +17,29 @@ auxiliary tasks: - the operation worker monitors consensus operations from the node via the ``/mempool/monitor_operations`` RPC, reporting ``Prequorum_reached`` and ``Quorum_reached`` events to the main scheduler. -- the forge worker is responsible for crafting blocks and operations. It receives crafting requests from the scheduler and notifies it back upon completion with ``New_forge_event (Block_ready block)``, ``New_forge_event (Preattestation_ready op)``, or ``New_forge_event (Attestation_ready op)`` events. +- the forge worker is responsible for crafting blocks and operations. It receives crafting requests from the scheduler and notifies completion with ``New_forge_event (Block_ready block)``, ``New_forge_event (Preattestation_ready op)``, or ``New_forge_event (Attestation_ready op)`` events. .. _baker_scheduling: Scheduling ---------- -:package-api:`Documentation` +Alongside the operation and forge workers, the +:package-api:`scheduler` +tracks the following events itself: + +- new blocks via the ``/monitor/heads`` and ``/monitor/validated_blocks`` RPCs, where new inputs are converted into ``New_head_proposal p`` and ``New_valid_proposal p`` events, respectively. + +- end of rounds and baking times by spawning timers that trigger ``Timeout`` events. + +Upon receiving a new event, the scheduler applies the corresponding transition +based on the current state and the event. The transition function returns a new +state and an action. These actions are side-effect requests, such as injecting +operations, forging blocks, or monitoring prequorums. + +The scheduler then executes the current action and prepares for the next +loop iteration: it sets a timer to track the next timeout according to the +current state and then sleeps until the next event. .. _baker_states: -- GitLab