docs: add some additional engine docs (paradigmxyz#9669)

Co-authored-by: Roman Krasiuk <[email protected]>

crates/engine/tree/src/chain.rs

@@ -165,6 +165,14 @@ pub enum ChainEvent<T> {
 /// A trait that advances the chain by handling actions.
 ///
 /// This is intended to be implement the chain consensus logic, for example `engine` API.
+///
+/// ## Control flow
+///
+/// The [`ChainOrchestrator`] is responsible for advancing this handler through
+/// [`ChainHandler::poll`] and handling the emitted events, for example
+/// [`HandlerEvent::BackfillSync`] to start a backfill sync. Events from the [`ChainOrchestrator`]
+/// are passed to the handler via [`ChainHandler::on_event`], e.g.
+/// [`FromOrchestrator::BackfillSyncStarted`] once the backfill sync started or finished.
 pub trait ChainHandler: Send + Sync {
     /// Event generated by this handler that orchestrator can bubble up;
     type Event: Send;

crates/engine/tree/src/engine.rs

@@ -27,6 +27,8 @@ use tokio::sync::mpsc::UnboundedReceiver;
 /// received from the CL to the handler.
 ///
 /// It is responsible for handling the following:
+/// - Delegating incoming requests to the [`EngineRequestHandler`].
+/// - Advancing the [`EngineRequestHandler`] by polling it and emitting events.
 /// - Downloading blocks on demand from the network if requested by the [`EngineApiRequestHandler`].
 ///
 /// The core logic is part of the [`EngineRequestHandler`], which is responsible for processing the
@@ -111,7 +113,14 @@ where
     }
 }
 
-/// A type that processes incoming requests (e.g. requests from the consensus layer, engine API)
+/// A type that processes incoming requests (e.g. requests from the consensus layer, engine API,
+/// such as newPayload).
+///
+/// ## Control flow
+///
+/// Requests and certain updates, such as a change in backfill sync status, are delegated to this
+/// type via [`EngineRequestHandler::on_event`]. This type is responsible for processing the
+/// incoming requests and advancing the chain and emit events when it is polled.
 pub trait EngineRequestHandler: Send + Sync {
     /// Even type this handler can emit
     type Event: Send;