feat: add canonical outcome type (#2765)

crates/interfaces/src/blockchain_tree/mod.rs

@@ -60,7 +60,8 @@ pub trait BlockchainTreeEngine: BlockchainTreeViewer + Send + Sync {
     /// [`BlockchainTreeEngine::finalize_block`]).
     fn restore_canonical_hashes(&self, last_finalized_block: BlockNumber) -> Result<(), Error>;
 
-    /// Make a block and its parent part of the canonical chain by committing it to the database.
+    /// Make a block and its parent chain part of the canonical chain by committing it to the
+    /// database.
     ///
     /// # Note
     ///
@@ -70,12 +71,45 @@ pub trait BlockchainTreeEngine: BlockchainTreeViewer + Send + Sync {
     /// # Returns
     ///
     /// Returns `Ok` if the blocks were canonicalized, or if the blocks were already canonical.
-    fn make_canonical(&self, block_hash: &BlockHash) -> Result<(), Error>;
+    fn make_canonical(&self, block_hash: &BlockHash) -> Result<CanonicalOutcome, Error>;
 
     /// Unwind tables and put it inside state
     fn unwind(&self, unwind_to: BlockNumber) -> Result<(), Error>;
 }
 
+/// All possible outcomes of a canonicalization attempt of [BlockchainTreeEngine::make_canonical].
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum CanonicalOutcome {
+    /// The block is already canonical.
+    AlreadyCanonical {
+        /// The corresponding [SealedHeader] that is already canonical.
+        header: SealedHeader,
+    },
+    /// Committed the block to the database.
+    Committed {
+        /// The new corresponding canonical head
+        head: SealedHeader,
+    },
+}
+
+impl CanonicalOutcome {
+    /// Returns the header of the block that was made canonical.
+    pub fn header(&self) -> &SealedHeader {
+        match self {
+            CanonicalOutcome::AlreadyCanonical { header } => header,
+            CanonicalOutcome::Committed { head } => head,
+        }
+    }
+
+    /// Consumes the outcome and returns the header of the block that was made canonical.
+    pub fn into_header(self) -> SealedHeader {
+        match self {
+            CanonicalOutcome::AlreadyCanonical { header } => header,
+            CanonicalOutcome::Committed { head } => head,
+        }
+    }
+}
+
 /// From Engine API spec, block inclusion can be valid, accepted or invalid.
 /// Invalid case is already covered by error, but we need to make distinction
 /// between if it is valid (extends canonical chain) or just accepted (is side chain).