From a802a697a016aa85b1ea5dc4243aacd7b2e59dd8 Mon Sep 17 00:00:00 2001 From: Gabriel Moise Date: Wed, 29 Jan 2025 19:09:22 +0000 Subject: [PATCH 1/3] Agnostic_baker: Improve existing documentation --- src/bin_agnostic_baker/daemon.ml | 24 +++++++++++++++++++----- src/bin_agnostic_baker/daemon.mli | 21 +++++++++++++++++---- src/bin_agnostic_baker/parameters.mli | 4 ++-- src/bin_agnostic_baker/rpc_services.ml | 3 +++ src/bin_agnostic_baker/rpc_services.mli | 12 ++++++------ src/bin_agnostic_baker/run_args.mli | 4 ++-- 6 files changed, 49 insertions(+), 19 deletions(-) diff --git a/src/bin_agnostic_baker/daemon.ml b/src/bin_agnostic_baker/daemon.ml index abfb1484ca47..e9f013d5bef7 100644 --- a/src/bin_agnostic_baker/daemon.ml +++ b/src/bin_agnostic_baker/daemon.ml @@ -54,6 +54,9 @@ module MakeBaker (Name : Lwt_process_watchdog.NAME) : BAKER = struct let* () = Agnostic_baker_events.(emit stopping_baker) baker.protocol_hash in Watchdog.stop baker.process + (** [spawn_baker protocol_hash ~binaries_directory ~baker_args] spawns a baker + for the given [protocol_hash] using the [~binaries_directory] as path for + the baker binary and with [~baker_args] as command line arguments. *) let spawn_baker protocol_hash ~binaries_directory ~baker_args = let open Lwt_result_syntax in let args_as_string = @@ -103,6 +106,9 @@ type 'a state = { type 'a t = 'a state +(** [monitor_heads ~node_addr] creates a stream which returns the data + of the heads of the current network; this information is received + from the RPC calls at the endpoint given by [~node_addr]. *) let monitor_heads ~node_addr = let open Lwt_result_syntax in let uri = Format.sprintf "%s/monitor/heads/main" node_addr in @@ -127,6 +133,10 @@ let monitor_heads ~node_addr = ignore (loop () : unit Lwt.t) ; return stream +(** [hot_swap_baker ~state ~next_protocol_hash] performs a swap in the current + [~state] of the agnostic baker, exchanging the current baker with the one + corresponding to [~next_protocol_hash]. This is done by shutting down the + current baking binary and generating the new binary instead. *) let hot_swap_baker ~state ~next_protocol_hash = let open Lwt_result_syntax in let* (module CurrentBaker : BAKER), current_baker = @@ -168,6 +178,10 @@ let hot_swap_baker ~state ~next_protocol_hash = state.current_baker <- Some new_baker ; return_unit +(** [monitor_voting_periods ~state head_stream] creates a process which listens + to the [head_stream] stream (which returns the data of the heads of the network + chain) in order to know when to "hot swap" (fork) the current protocol baking + binary with the one associated with the next protocol. *) let monitor_voting_periods ~state head_stream = let open Lwt_result_syntax in let node_addr = state.node_endpoint in @@ -200,11 +214,11 @@ let monitor_voting_periods ~state head_stream = let* () = loop () in return_unit -(* Aims to start the baker associated to the current protocol. If - the protocol is considered as frozen (not active anymore), and - there is thus no actual baker binary anymore, the initial phase - consist in waiting until an active protocol is observed on - monitored heads. *) +(** [may_start_initial_baker state] aims to start the baker associated + to the current protocol. If the protocol is considered as [frozen] (not + [active] anymore), and there is thus no actual baker binary anymore, the + initial phase consists in waiting until an [active] protocol is observed on + monitored heads function. *) let may_start_initial_baker state = let open Lwt_result_syntax in let*! () = Agnostic_baker_events.(emit experimental_binary) () in diff --git a/src/bin_agnostic_baker/daemon.mli b/src/bin_agnostic_baker/daemon.mli index 3cdc92dd9ab7..0577ab5eef4a 100644 --- a/src/bin_agnostic_baker/daemon.mli +++ b/src/bin_agnostic_baker/daemon.mli @@ -5,12 +5,25 @@ (* *) (*****************************************************************************) -(** Daemon handling the bakers life cycle. *) +(** Daemon handling the baker's life cycle. + + It is used to [create] and [run] a protocol-agnostic process which uses the existing + baking binaries in an adaptive way, depending on the current protocol obtained + from the chain. + + It relies on a [state] which contains the [endpoint] to contact the running node, + together with the current baker which is being run. + + To do so, it also spawns a "monitoring" process which follows the heads of the + chain, as reported by the node from the [state], more precisely which monitors + the voting period. By doing that, it decides when to swap to a different baking + binary. +*) type 'a t -(** [create binaries_directory node_endpoint baker_args] returns a non - initialized daemon.*) +(** [create ~binaries_directory ~node_endpoint ~baker_args] returns a non + initialized daemon. *) val create : binaries_directory:string option -> node_endpoint:string -> @@ -18,5 +31,5 @@ val create : 'a t (** [run t] Runs the daemon responsible for the spawn/stop of the - baker daemons. *) + baker daemons. *) val run : 'a t -> unit tzresult Lwt.t diff --git a/src/bin_agnostic_baker/parameters.mli b/src/bin_agnostic_baker/parameters.mli index 1b57b0d250ec..fe22e5bf98cd 100644 --- a/src/bin_agnostic_baker/parameters.mli +++ b/src/bin_agnostic_baker/parameters.mli @@ -12,9 +12,9 @@ val default_node_endpoint : string val log_config : base_dir:string option -> Tezos_base.Internal_event_config.t (** Status of a protocol, based on Manifest/Product_octez/Protocol. A - protocol is considered as Active while it is running on a network, + protocol is considered as [Active] while it is running on a network, and thus, have dedicated binaries. Otherwise, the protocol is - Frozen as not running anymore and no associated binaries. + [Frozen] as not running anymore and no associated binaries. Warning, it is needed to update status for each new protocol added. *) diff --git a/src/bin_agnostic_baker/rpc_services.ml b/src/bin_agnostic_baker/rpc_services.ml index 67866da85720..725f47615932 100644 --- a/src/bin_agnostic_baker/rpc_services.ml +++ b/src/bin_agnostic_baker/rpc_services.ml @@ -19,6 +19,9 @@ let request_uri ~node_addr ~uri = tzfail (Cannot_connect_to_node node_addr) | e -> raise e) +(** [call_and_wrap_rpc ~node_addr ~uri ~f] makes the RPC call given + by the [~uri] against [~node_addr], and in case of a well-formed + response, it applies [~f] to it. *) let call_and_wrap_rpc ~node_addr ~uri ~f = let open Lwt_result_syntax in let* resp, body = request_uri ~node_addr ~uri in diff --git a/src/bin_agnostic_baker/rpc_services.mli b/src/bin_agnostic_baker/rpc_services.mli index 5b962315d3c9..bdf44fb647fb 100644 --- a/src/bin_agnostic_baker/rpc_services.mli +++ b/src/bin_agnostic_baker/rpc_services.mli @@ -5,9 +5,9 @@ (* *) (*****************************************************************************) -(** request_uri ~node_addr ~uri] is a raw call that will return the - Cohttp response of a RPC call, given a [uri], against the - [node_addr]. *) +(** [request_uri ~node_addr ~uri] is a raw call that will return the + Cohttp response of an RPC call, given a [~uri], against the + [~node_addr]. *) val request_uri : node_addr:string -> uri:string -> @@ -18,12 +18,12 @@ val request_uri : block. *) val get_next_protocol_hash : node_addr:string -> Protocol_hash.t tzresult Lwt.t -(** [get_next_protocol_hash ~node_addr] returns the protocol hash of +(** [get_current_proposal ~node_addr] returns the protocol hash of the current voting period, if any. *) val get_current_proposal : node_addr:string -> Protocol_hash.t option tzresult Lwt.t -(** [get_next_protocol_hash ~node_addr] returns the current voting - period in addition to the number of remaining block until the end +(** [get_current_period ~node_addr] returns the current voting + period in addition to the number of remaining blocks until the end of the period. *) val get_current_period : node_addr:string -> (string * int) tzresult Lwt.t diff --git a/src/bin_agnostic_baker/run_args.mli b/src/bin_agnostic_baker/run_args.mli index ff420d04bb7d..cfe66e06de6d 100644 --- a/src/bin_agnostic_baker/run_args.mli +++ b/src/bin_agnostic_baker/run_args.mli @@ -13,7 +13,7 @@ type args = { baker_args : string list; } -(** [parse_args args] is a raw utility that aims to parse the give +(** [parse_args args] is a raw utility that aims to parse the given arguments from the command line and to return, respectively, the - endpoint, base_dir, binaries_directory and baker_args. *) + [endpoint], [base_dir], [binaries_directory] and [baker_args]. *) val parse_args : string array -> args -- GitLab From 3d1e907a36e5426b2443d8da67303138c2020989 Mon Sep 17 00:00:00 2001 From: Gabriel Moise Date: Thu, 30 Jan 2025 13:10:24 +0200 Subject: [PATCH 2/3] Agnostic_baker: Add README --- src/bin_agnostic_baker/README.md | 59 ++++++++++++++++++++++++++++++++ 1 file changed, 59 insertions(+) create mode 100644 src/bin_agnostic_baker/README.md diff --git a/src/bin_agnostic_baker/README.md b/src/bin_agnostic_baker/README.md new file mode 100644 index 000000000000..bec810985ea7 --- /dev/null +++ b/src/bin_agnostic_baker/README.md @@ -0,0 +1,59 @@ +# Agnostic Baker (experimental) + +## Overview + +Agnostic Baker is a protocol-independent binary that dynamically selects the +appropriate baking binary based on the active protocol. It monitors the state of +the blockchain and automatically switches to the correct binary when a new +protocol is encountered (for example, during migrations, or at startup). + +It is designed to simplify the baking process for users, such that they will no +longer need to run two baker binaries at migration time. + +## Experimental purpose + +For now, the binary is continuously being developed and tested. This is the reason +why users are warned that the binary is experimental and that it should not be +used for real-life scenarios, for instance, baking on `mainnet`. + +## Usage + +To run the agnostic baker, the command line syntax is quite similar to the one +for the protocol-dependent baking binaries: + +```bash +./octez-experimental-agnostic-baker [OCTEZ-EXPERIMENTAL-AGNOSTIC-BAKER-COMMANDS] \ +-- [OCTEZ-BAKER-COMMANDS] +``` + +The `[OCTEZ-EXPERIMENTAL-AGNOSTIC-BAKER-COMMANDS]` list consists of arguments specific +to the agnostic baker binary and they include: + +- `--binaries-directory` : where to find the baker binaries to use +- `--endpoint` : endpoint to communicate with the connected node +- `--base-dir` : directory dedicated to the agnostic baker (that can contain logs +and configuration files) +-- `--help` : displays help information + +The `[OCTEZ-BAKER-COMMANDS]` list consists of all the arguments that can be used +for the specific protocol baking binary. To be more clear, if a user wants to use +the agnostic baker to replace a baking command which would be + +```bash +./octez-baker- [OCTEZ-BAKER-COMMANDS] +``` + +they can do this by using the same `[OCTEZ-BAKER-COMMANDS]` and let the agnostic +baker run the binary for ``, information obtained from the node. + +Notice that the two types of arguments are separated by a clear `--`. + +## How it works + +1. **Initialization**: The daemon starts and connects to the specified Tezos node. +2. **Protocol Detection**: It fetches the currently active protocol. This is done via an RPC request on the `head` metadata against the Tezos node. +3. **Baker Selection**: Based on the active protocol, it selects the corresponding `octez-baker-` binary. +4. **Baker Execution**: The chosen binary is executed with the specified arguments +(`[OCTEZ-BAKER-COMMANDS]`). +5. **Chain Monitoring**: The daemon continuously monitors the chain for new blocks and protocol changes (based on the voting period). +6. **Protocol Updates**: If a new protocol is encountered, the daemon stops the current baker and starts a new one matching the new protocol. -- GitLab From 55419f83e1e246ed24c5a957ab9f53d01507d009 Mon Sep 17 00:00:00 2001 From: Gabriel Moise Date: Thu, 30 Jan 2025 13:26:42 +0200 Subject: [PATCH 3/3] Agnostic_baker: Add changelog entry --- CHANGES.rst | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/CHANGES.rst b/CHANGES.rst index 522047db6f21..46cb07bf0d0e 100644 --- a/CHANGES.rst +++ b/CHANGES.rst @@ -86,6 +86,28 @@ Baker - **Breaking change** The baker daemon ``--dal-node-timeout-percentage`` argument has been removed. (MR :gl:`!15554`) +Agnostic Baker +-------------- + +- Release agnostic baker binary as experimental. (MR :gl:`!16318`) + +- Use of a generic watchdog. (MR :gl:`!15508`) + +- Change the binary name to ``octez-experimental-agnostic-baker``. (MR :gl:`!16434`) + +- Added a mechanism for the agnostic baker to switch on new protocol. (MR :gl:`!15305`) + +- Introduced a dummy agnostic baker. (MR :gl:`!15029`) + +Overview: The Agnostic Baker is a protocol-independent binary that dynamically determines +and executes the appropriate baking binary based on the active protocol. It continuously +monitors the blockchain state and automatically transitions to the correct binary whenever +a new protocol is detected, such as during migrations or at startup. + +Please note that this feature is in an EXPERIMENTAL phase, as clearly suggested by its name. +Therefore, it should NOT be used on ``mainnet``. For further clarifications, you can consult +the README from ``src/bin_agnostic_baker``. + Accuser ------- -- GitLab