Add finalized to HTTP API responses (#3753)

## Issue Addressed

#3708 

## Proposed Changes
- Add `is_finalized_block` method to `BeaconChain` in `beacon_node/beacon_chain/src/beacon_chain.rs`.
- Add `is_finalized_state` method to `BeaconChain` in `beacon_node/beacon_chain/src/beacon_chain.rs`.
- Add `fork_and_execution_optimistic_and_finalized` in `beacon_node/http_api/src/state_id.rs`.
- Add `ExecutionOptimisticFinalizedForkVersionedResponse` type in `consensus/types/src/fork_versioned_response.rs`.
- Add `execution_optimistic_finalized_fork_versioned_response`function in  `beacon_node/http_api/src/version.rs`.
- Add `ExecutionOptimisticFinalizedResponse` type in `common/eth2/src/types.rs`.
- Add `add_execution_optimistic_finalized` method in  `common/eth2/src/types.rs`.
- Update API response methods to include finalized.
- Remove `execution_optimistic_fork_versioned_response`

Co-authored-by: Michael Sproul <michael@sigmaprime.io>

beacon_node/beacon_chain/src/beacon_chain.rs

@@ -432,6 +432,46 @@ pub struct BeaconChain<T: BeaconChainTypes> {
 type BeaconBlockAndState<T, Payload> = (BeaconBlock<T, Payload>, BeaconState<T>);
 
 impl<T: BeaconChainTypes> BeaconChain<T> {
+    /// Checks if a block is finalized.
+    /// The finalization check is done with the block slot. The block root is used to verify that
+    /// the finalized slot is in the canonical chain.
+    pub fn is_finalized_block(
+        &self,
+        block_root: &Hash256,
+        block_slot: Slot,
+    ) -> Result<bool, Error> {
+        let finalized_slot = self
+            .canonical_head
+            .cached_head()
+            .finalized_checkpoint()
+            .epoch
+            .start_slot(T::EthSpec::slots_per_epoch());
+        let is_canonical = self
+            .block_root_at_slot(block_slot, WhenSlotSkipped::None)?
+            .map_or(false, |canonical_root| block_root == &canonical_root);
+        Ok(block_slot <= finalized_slot && is_canonical)
+    }
+
+    /// Checks if a state is finalized.
+    /// The finalization check is done with the slot. The state root is used to verify that
+    /// the finalized state is in the canonical chain.
+    pub fn is_finalized_state(
+        &self,
+        state_root: &Hash256,
+        state_slot: Slot,
+    ) -> Result<bool, Error> {
+        let finalized_slot = self
+            .canonical_head
+            .cached_head()
+            .finalized_checkpoint()
+            .epoch
+            .start_slot(T::EthSpec::slots_per_epoch());
+        let is_canonical = self
+            .state_root_at_slot(state_slot)?
+            .map_or(false, |canonical_root| state_root == &canonical_root);
+        Ok(state_slot <= finalized_slot && is_canonical)
+    }
+
     /// Persists the head tracker and fork choice.
     ///
     /// We do it atomically even though no guarantees need to be made about blocks from

beacon_node/http_api/src/attester_duties.rs

@@ -114,8 +114,10 @@ fn compute_historic_attester_duties<T: BeaconChainTypes>(
             )?;
             (state, execution_optimistic)
         } else {
+            let (state, execution_optimistic, _finalized) =
                 StateId::from_slot(request_epoch.start_slot(T::EthSpec::slots_per_epoch()))
-                .state(chain)?
+                    .state(chain)?;
+            (state, execution_optimistic)
         };
 
     // Sanity-check the state lookup.

beacon_node/http_api/src/block_id.rs

@@ -4,13 +4,15 @@ use eth2::types::BlockId as CoreBlockId;
 use std::fmt;
 use std::str::FromStr;
 use std::sync::Arc;
-use types::{Hash256, SignedBeaconBlock, SignedBlindedBeaconBlock, Slot};
+use types::{EthSpec, Hash256, SignedBeaconBlock, SignedBlindedBeaconBlock, Slot};
 
 /// Wraps `eth2::types::BlockId` and provides a simple way to obtain a block or root for a given
 /// `BlockId`.
 #[derive(Debug)]
 pub struct BlockId(pub CoreBlockId);
 
+type Finalized = bool;
+
 impl BlockId {
     pub fn from_slot(slot: Slot) -> Self {
         Self(CoreBlockId::Slot(slot))
@@ -24,7 +26,7 @@ impl BlockId {
     pub fn root<T: BeaconChainTypes>(
         &self,
         chain: &BeaconChain<T>,
-    ) -> Result<(Hash256, ExecutionOptimistic), warp::Rejection> {
+    ) -> Result<(Hash256, ExecutionOptimistic, Finalized), warp::Rejection> {
         match &self.0 {
             CoreBlockId::Head => {
                 let (cached_head, execution_status) = chain
@@ -34,22 +36,23 @@ impl BlockId {
                 Ok((
                     cached_head.head_block_root(),
                     execution_status.is_optimistic_or_invalid(),
+                    false,
                 ))
             }
-            CoreBlockId::Genesis => Ok((chain.genesis_block_root, false)),
+            CoreBlockId::Genesis => Ok((chain.genesis_block_root, false, true)),
             CoreBlockId::Finalized => {
                 let finalized_checkpoint =
                     chain.canonical_head.cached_head().finalized_checkpoint();
                 let (_slot, execution_optimistic) =
                     checkpoint_slot_and_execution_optimistic(chain, finalized_checkpoint)?;
-                Ok((finalized_checkpoint.root, execution_optimistic))
+                Ok((finalized_checkpoint.root, execution_optimistic, true))
             }
             CoreBlockId::Justified => {
                 let justified_checkpoint =
                     chain.canonical_head.cached_head().justified_checkpoint();
                 let (_slot, execution_optimistic) =
                     checkpoint_slot_and_execution_optimistic(chain, justified_checkpoint)?;
-                Ok((justified_checkpoint.root, execution_optimistic))
+                Ok((justified_checkpoint.root, execution_optimistic, false))
             }
             CoreBlockId::Slot(slot) => {
                 let execution_optimistic = chain
@@ -66,7 +69,14 @@ impl BlockId {
                             ))
                         })
                     })?;
-                Ok((root, execution_optimistic))
+                let finalized = *slot
+                    <= chain
+                        .canonical_head
+                        .cached_head()
+                        .finalized_checkpoint()
+                        .epoch
+                        .start_slot(T::EthSpec::slots_per_epoch());
+                Ok((root, execution_optimistic, finalized))
             }
             CoreBlockId::Root(root) => {
                 // This matches the behaviour of other consensus clients (e.g. Teku).
@@ -88,7 +98,20 @@ impl BlockId {
                         .is_optimistic_or_invalid_block(root)
                         .map_err(BeaconChainError::ForkChoiceError)
                         .map_err(warp_utils::reject::beacon_chain_error)?;
-                    Ok((*root, execution_optimistic))
+                    let blinded_block = chain
+                        .get_blinded_block(root)
+                        .map_err(warp_utils::reject::beacon_chain_error)?
+                        .ok_or_else(|| {
+                            warp_utils::reject::custom_not_found(format!(
+                                "beacon block with root {}",
+                                root
+                            ))
+                        })?;
+                    let block_slot = blinded_block.slot();
+                    let finalized = chain
+                        .is_finalized_block(root, block_slot)
+                        .map_err(warp_utils::reject::beacon_chain_error)?;
+                    Ok((*root, execution_optimistic, finalized))
                 } else {
                     Err(warp_utils::reject::custom_not_found(format!(
                         "beacon block with root {}",
@@ -103,7 +126,14 @@ impl BlockId {
     pub fn blinded_block<T: BeaconChainTypes>(
         &self,
         chain: &BeaconChain<T>,
-    ) -> Result<(SignedBlindedBeaconBlock<T::EthSpec>, ExecutionOptimistic), warp::Rejection> {
+    ) -> Result<
+        (
+            SignedBlindedBeaconBlock<T::EthSpec>,
+            ExecutionOptimistic,
+            Finalized,
+        ),
+        warp::Rejection,
+    > {
         match &self.0 {
             CoreBlockId::Head => {
                 let (cached_head, execution_status) = chain
@@ -113,10 +143,11 @@ impl BlockId {
                 Ok((
                     cached_head.snapshot.beacon_block.clone_as_blinded(),
                     execution_status.is_optimistic_or_invalid(),
+                    false,
                 ))
             }
             CoreBlockId::Slot(slot) => {
-                let (root, execution_optimistic) = self.root(chain)?;
+                let (root, execution_optimistic, finalized) = self.root(chain)?;
                 chain
                     .get_blinded_block(&root)
                     .map_err(warp_utils::reject::beacon_chain_error)
@@ -128,7 +159,7 @@ impl BlockId {
                                     slot
                                 )));
                             }
-                            Ok((block, execution_optimistic))
+                            Ok((block, execution_optimistic, finalized))
                         }
                         None => Err(warp_utils::reject::custom_not_found(format!(
                             "beacon block with root {}",
@@ -137,7 +168,7 @@ impl BlockId {
                     })
             }
             _ => {
-                let (root, execution_optimistic) = self.root(chain)?;
+                let (root, execution_optimistic, finalized) = self.root(chain)?;
                 let block = chain
                     .get_blinded_block(&root)
                     .map_err(warp_utils::reject::beacon_chain_error)
@@ -149,7 +180,7 @@ impl BlockId {
                             ))
                         })
                     })?;
-                Ok((block, execution_optimistic))
+                Ok((block, execution_optimistic, finalized))
             }
         }
     }
@@ -158,7 +189,14 @@ impl BlockId {
     pub async fn full_block<T: BeaconChainTypes>(
         &self,
         chain: &BeaconChain<T>,
-    ) -> Result<(Arc<SignedBeaconBlock<T::EthSpec>>, ExecutionOptimistic), warp::Rejection> {
+    ) -> Result<
+        (
+            Arc<SignedBeaconBlock<T::EthSpec>>,
+            ExecutionOptimistic,
+            Finalized,
+        ),
+        warp::Rejection,
+    > {
         match &self.0 {
             CoreBlockId::Head => {
                 let (cached_head, execution_status) = chain
@@ -168,10 +206,11 @@ impl BlockId {
                 Ok((
                     cached_head.snapshot.beacon_block.clone(),
                     execution_status.is_optimistic_or_invalid(),
+                    false,
                 ))
             }
             CoreBlockId::Slot(slot) => {
-                let (root, execution_optimistic) = self.root(chain)?;
+                let (root, execution_optimistic, finalized) = self.root(chain)?;
                 chain
                     .get_block(&root)
                     .await
@@ -184,7 +223,7 @@ impl BlockId {
                                     slot
                                 )));
                             }
-                            Ok((Arc::new(block), execution_optimistic))
+                            Ok((Arc::new(block), execution_optimistic, finalized))
                         }
                         None => Err(warp_utils::reject::custom_not_found(format!(
                             "beacon block with root {}",
@@ -193,14 +232,14 @@ impl BlockId {
                     })
             }
             _ => {
-                let (root, execution_optimistic) = self.root(chain)?;
+                let (root, execution_optimistic, finalized) = self.root(chain)?;
                 chain
                     .get_block(&root)
                     .await
                     .map_err(warp_utils::reject::beacon_chain_error)
                     .and_then(|block_opt| {
                         block_opt
-                            .map(|block| (Arc::new(block), execution_optimistic))
+                            .map(|block| (Arc::new(block), execution_optimistic, finalized))
                             .ok_or_else(|| {
                                 warp_utils::reject::custom_not_found(format!(
                                     "beacon block with root {}",

beacon_node/http_api/src/lib.rs

@@ -63,7 +63,7 @@ use types::{
     SyncCommitteeMessage, SyncContributionData,
 };
 use version::{
-    add_consensus_version_header, execution_optimistic_fork_versioned_response,
+    add_consensus_version_header, execution_optimistic_finalized_fork_versioned_response,
     fork_versioned_response, inconsistent_fork_rejection, unsupported_version_rejection, V1, V2,
 };
 use warp::http::StatusCode;
@@ -522,12 +522,13 @@ pub fn serve<T: BeaconChainTypes>(
         .and(warp::path::end())
         .and_then(|state_id: StateId, chain: Arc<BeaconChain<T>>| {
             blocking_json_task(move || {
-                let (root, execution_optimistic) = state_id.root(&chain)?;
+                let (root, execution_optimistic, finalized) = state_id.root(&chain)?;
-
                 Ok(root)
                     .map(api_types::RootData::from)
                     .map(api_types::GenericResponse::from)
-                    .map(|resp| resp.add_execution_optimistic(execution_optimistic))
+                    .map(|resp| {
+                        resp.add_execution_optimistic_finalized(execution_optimistic, finalized)
+                    })
             })
         });
 
@@ -538,11 +539,12 @@ pub fn serve<T: BeaconChainTypes>(
         .and(warp::path::end())
         .and_then(|state_id: StateId, chain: Arc<BeaconChain<T>>| {
             blocking_json_task(move || {
-                let (fork, execution_optimistic) =
+                let (fork, execution_optimistic, finalized) =
-                    state_id.fork_and_execution_optimistic(&chain)?;
+                    state_id.fork_and_execution_optimistic_and_finalized(&chain)?;
-                Ok(api_types::ExecutionOptimisticResponse {
+                Ok(api_types::ExecutionOptimisticFinalizedResponse {
                     data: fork,
                     execution_optimistic: Some(execution_optimistic),
+                    finalized: Some(finalized),
                 })
             })
         });
@@ -554,9 +556,10 @@ pub fn serve<T: BeaconChainTypes>(
         .and(warp::path::end())
         .and_then(|state_id: StateId, chain: Arc<BeaconChain<T>>| {
             blocking_json_task(move || {
-                let (data, execution_optimistic) = state_id.map_state_and_execution_optimistic(
+                let (data, execution_optimistic, finalized) = state_id
+                    .map_state_and_execution_optimistic_and_finalized(
                         &chain,
-                    |state, execution_optimistic| {
+                        |state, execution_optimistic, finalized| {
                             Ok((
                                 api_types::FinalityCheckpointsData {
                                     previous_justified: state.previous_justified_checkpoint(),
@@ -564,13 +567,15 @@ pub fn serve<T: BeaconChainTypes>(
                                     finalized: state.finalized_checkpoint(),
                                 },
                                 execution_optimistic,
+                                finalized,
                             ))
                         },
                     )?;
 
-                Ok(api_types::ExecutionOptimisticResponse {
+                Ok(api_types::ExecutionOptimisticFinalizedResponse {
                     data,
                     execution_optimistic: Some(execution_optimistic),
+                    finalized: Some(finalized),
                 })
             })
         });
@@ -587,10 +592,10 @@ pub fn serve<T: BeaconChainTypes>(
              query_res: Result<api_types::ValidatorBalancesQuery, warp::Rejection>| {
                 blocking_json_task(move || {
                     let query = query_res?;
-                    let (data, execution_optimistic) = state_id
+                    let (data, execution_optimistic, finalized) = state_id
-                        .map_state_and_execution_optimistic(
+                        .map_state_and_execution_optimistic_and_finalized(
                             &chain,
-                            |state, execution_optimistic| {
+                            |state, execution_optimistic, finalized| {
                                 Ok((
                                     state
                                         .validators()
@@ -618,13 +623,15 @@ pub fn serve<T: BeaconChainTypes>(
                                         })
                                         .collect::<Vec<_>>(),
                                     execution_optimistic,
+                                    finalized,
                                 ))
                             },
                         )?;
 
-                    Ok(api_types::ExecutionOptimisticResponse {
+                    Ok(api_types::ExecutionOptimisticFinalizedResponse {
                         data,
                         execution_optimistic: Some(execution_optimistic),
+                        finalized: Some(finalized),
                     })
                 })
             },
@@ -642,10 +649,10 @@ pub fn serve<T: BeaconChainTypes>(
              query_res: Result<api_types::ValidatorsQuery, warp::Rejection>| {
                 blocking_json_task(move || {
                     let query = query_res?;
-                    let (data, execution_optimistic) = state_id
+                    let (data, execution_optimistic, finalized) = state_id
-                        .map_state_and_execution_optimistic(
+                        .map_state_and_execution_optimistic_and_finalized(
                             &chain,
-                            |state, execution_optimistic| {
+                            |state, execution_optimistic, finalized| {
                                 let epoch = state.current_epoch();
                                 let far_future_epoch = chain.spec.far_future_epoch;
 
@@ -695,13 +702,15 @@ pub fn serve<T: BeaconChainTypes>(
                                         })
                                         .collect::<Vec<_>>(),
                                     execution_optimistic,
+                                    finalized,
                                 ))
                             },
                         )?;
 
-                    Ok(api_types::ExecutionOptimisticResponse {
+                    Ok(api_types::ExecutionOptimisticFinalizedResponse {
                         data,
                         execution_optimistic: Some(execution_optimistic),
+                        finalized: Some(finalized),
                     })
                 })
             },
@@ -720,10 +729,10 @@ pub fn serve<T: BeaconChainTypes>(
         .and_then(
             |state_id: StateId, chain: Arc<BeaconChain<T>>, validator_id: ValidatorId| {
                 blocking_json_task(move || {
-                    let (data, execution_optimistic) = state_id
+                    let (data, execution_optimistic, finalized) = state_id
-                        .map_state_and_execution_optimistic(
+                        .map_state_and_execution_optimistic_and_finalized(
                             &chain,
-                            |state, execution_optimistic| {
+                            |state, execution_optimistic, finalized| {
                                 let index_opt = match &validator_id {
                                     ValidatorId::PublicKey(pubkey) => {
                                         state.validators().iter().position(|v| v.pubkey == *pubkey)
@@ -757,13 +766,15 @@ pub fn serve<T: BeaconChainTypes>(
                                             ))
                                         })?,
                                     execution_optimistic,
+                                    finalized,
                                 ))
                             },
                         )?;
 
-                    Ok(api_types::ExecutionOptimisticResponse {
+                    Ok(api_types::ExecutionOptimisticFinalizedResponse {
                         data,
                         execution_optimistic: Some(execution_optimistic),
+                        finalized: Some(finalized),
                     })
                 })
             },
@@ -778,10 +789,10 @@ pub fn serve<T: BeaconChainTypes>(
         .and_then(
             |state_id: StateId, chain: Arc<BeaconChain<T>>, query: api_types::CommitteesQuery| {
                 blocking_json_task(move || {
-                    let (data, execution_optimistic) = state_id
+                    let (data, execution_optimistic, finalized) = state_id
-                        .map_state_and_execution_optimistic(
+                        .map_state_and_execution_optimistic_and_finalized(
                             &chain,
-                            |state, execution_optimistic| {
+                            |state, execution_optimistic, finalized| {
                                 let current_epoch = state.current_epoch();
                                 let epoch = query.epoch.unwrap_or(current_epoch);
 
@@ -937,12 +948,13 @@ pub fn serve<T: BeaconChainTypes>(
                                     }
                                 }
 
-                                Ok((response, execution_optimistic))
+                                Ok((response, execution_optimistic, finalized))
                             },
                         )?;
-                    Ok(api_types::ExecutionOptimisticResponse {
+                    Ok(api_types::ExecutionOptimisticFinalizedResponse {
                         data,
                         execution_optimistic: Some(execution_optimistic),
+                        finalized: Some(finalized),
                     })
                 })
             },
@@ -959,10 +971,10 @@ pub fn serve<T: BeaconChainTypes>(
              chain: Arc<BeaconChain<T>>,
              query: api_types::SyncCommitteesQuery| {
                 blocking_json_task(move || {
-                    let (sync_committee, execution_optimistic) = state_id
+                    let (sync_committee, execution_optimistic, finalized) = state_id
-                        .map_state_and_execution_optimistic(
+                        .map_state_and_execution_optimistic_and_finalized(
                             &chain,
-                            |state, execution_optimistic| {
+                            |state, execution_optimistic, finalized| {
                                 let current_epoch = state.current_epoch();
                                 let epoch = query.epoch.unwrap_or(current_epoch);
                                 Ok((
@@ -972,7 +984,8 @@ pub fn serve<T: BeaconChainTypes>(
                                         .map_err(|e| match e {
                                             BeaconStateError::SyncCommitteeNotKnown { .. } => {
                                                 warp_utils::reject::custom_bad_request(format!(
-                                        "state at epoch {} has no sync committee for epoch {}",
+                                                    "state at epoch {} has no \
+                                                     sync committee for epoch {}",
                                                     current_epoch, epoch
                                                 ))
                                             }
@@ -985,6 +998,7 @@ pub fn serve<T: BeaconChainTypes>(
                                             e => warp_utils::reject::beacon_state_error(e),
                                         })?,
                                     execution_optimistic,
+                                    finalized,
                                 ))
                             },
                         )?;
@@ -1006,7 +1020,7 @@ pub fn serve<T: BeaconChainTypes>(
                     };
 
                     Ok(api_types::GenericResponse::from(response)
-                        .add_execution_optimistic(execution_optimistic))
+                        .add_execution_optimistic_finalized(execution_optimistic, finalized))
                 })
             },
         );
@@ -1020,23 +1034,23 @@ pub fn serve<T: BeaconChainTypes>(
         .and_then(
             |state_id: StateId, chain: Arc<BeaconChain<T>>, query: api_types::RandaoQuery| {
                 blocking_json_task(move || {
-                    let (randao, execution_optimistic) = state_id
+                    let (randao, execution_optimistic, finalized) = state_id
-                        .map_state_and_execution_optimistic(
+                        .map_state_and_execution_optimistic_and_finalized(
                             &chain,
-                            |state, execution_optimistic| {
+                            |state, execution_optimistic, finalized| {
                                 let epoch = query.epoch.unwrap_or_else(|| state.current_epoch());
                                 let randao = *state.get_randao_mix(epoch).map_err(|e| {
                                     warp_utils::reject::custom_bad_request(format!(
                                         "epoch out of range: {e:?}"
                                     ))
                                 })?;
-                                Ok((randao, execution_optimistic))
+                                Ok((randao, execution_optimistic, finalized))
                             },
                         )?;
 
                     Ok(
                         api_types::GenericResponse::from(api_types::RandaoMix { randao })
-                            .add_execution_optimistic(execution_optimistic),
+                            .add_execution_optimistic_finalized(execution_optimistic, finalized),
                     )
                 })
             },
@@ -1058,8 +1072,8 @@ pub fn serve<T: BeaconChainTypes>(
         .and_then(
             |query: api_types::HeadersQuery, chain: Arc<BeaconChain<T>>| {
                 blocking_json_task(move || {
-                    let (root, block, execution_optimistic) = match (query.slot, query.parent_root)
+                    let (root, block, execution_optimistic, finalized) =
-                    {
+                        match (query.slot, query.parent_root) {
                             // No query parameters, return the canonical head block.
                             (None, None) => {
                                 let (cached_head, execution_status) = chain
@@ -1070,11 +1084,12 @@ pub fn serve<T: BeaconChainTypes>(
                                     cached_head.head_block_root(),
                                     cached_head.snapshot.beacon_block.clone_as_blinded(),
                                     execution_status.is_optimistic_or_invalid(),
+                                    false,
                                 )
                             }
                             // Only the parent root parameter, do a forwards-iterator lookup.
                             (None, Some(parent_root)) => {
-                            let (parent, execution_optimistic) =
+                                let (parent, execution_optimistic, _parent_finalized) =
                                     BlockId::from_root(parent_root).blinded_block(&chain)?;
                                 let (root, _slot) = chain
                                     .forwards_iter_block_roots(parent.slot())
@@ -1096,18 +1111,18 @@ pub fn serve<T: BeaconChainTypes>(
                                     .blinded_block(&chain)
                                     // Ignore this `execution_optimistic` since the first value has
                                     // more information about the original request.
-                                .map(|(block, _execution_optimistic)| {
+                                    .map(|(block, _execution_optimistic, finalized)| {
-                                    (root, block, execution_optimistic)
+                                        (root, block, execution_optimistic, finalized)
                                     })?
                             }
                             // Slot is supplied, search by slot and optionally filter by
                             // parent root.
                             (Some(slot), parent_root_opt) => {
-                            let (root, execution_optimistic) =
+                                let (root, execution_optimistic, finalized) =
                                     BlockId::from_slot(slot).root(&chain)?;
                                 // Ignore the second `execution_optimistic`, the first one is the
                                 // most relevant since it knows that we queried by slot.
-                            let (block, _execution_optimistic) =
+                                let (block, _execution_optimistic, _finalized) =
                                     BlockId::from_root(root).blinded_block(&chain)?;
 
                                 // If the parent root was supplied, check that it matches the block
@@ -1121,7 +1136,7 @@ pub fn serve<T: BeaconChainTypes>(
                                     }
                                 }
 
-                            (root, block, execution_optimistic)
+                                (root, block, execution_optimistic, finalized)
                             }
                         };
 
@@ -1135,7 +1150,7 @@ pub fn serve<T: BeaconChainTypes>(
                     };
 
                     Ok(api_types::GenericResponse::from(vec![data])
-                        .add_execution_optimistic(execution_optimistic))
+                        .add_execution_optimistic_finalized(execution_optimistic, finalized))
                 })
             },
         );
@@ -1153,10 +1168,10 @@ pub fn serve<T: BeaconChainTypes>(
         .and(chain_filter.clone())
         .and_then(|block_id: BlockId, chain: Arc<BeaconChain<T>>| {
             blocking_json_task(move || {
-                let (root, execution_optimistic) = block_id.root(&chain)?;
+                let (root, execution_optimistic, finalized) = block_id.root(&chain)?;
                 // Ignore the second `execution_optimistic` since the first one has more
                 // information about the original request.
-                let (block, _execution_optimistic) =
+                let (block, _execution_optimistic, _finalized) =
                     BlockId::from_root(root).blinded_block(&chain)?;
 
                 let canonical = chain
@@ -1173,8 +1188,9 @@ pub fn serve<T: BeaconChainTypes>(
                     },
                 };
 
-                Ok(api_types::ExecutionOptimisticResponse {
+                Ok(api_types::ExecutionOptimisticFinalizedResponse {
                     execution_optimistic: Some(execution_optimistic),
+                    finalized: Some(finalized),
                     data,
                 })
             })
@@ -1263,7 +1279,8 @@ pub fn serve<T: BeaconChainTypes>(
              chain: Arc<BeaconChain<T>>,
              accept_header: Option<api_types::Accept>| {
                 async move {
-                    let (block, execution_optimistic) = block_id.full_block(&chain).await?;
+                    let (block, execution_optimistic, finalized) =
+                        block_id.full_block(&chain).await?;
                     let fork_name = block
                         .fork_name(&chain.spec)
                         .map_err(inconsistent_fork_rejection)?;
@@ -1279,10 +1296,11 @@ pub fn serve<T: BeaconChainTypes>(
                                     e
                                 ))
                             }),
-                        _ => execution_optimistic_fork_versioned_response(
+                        _ => execution_optimistic_finalized_fork_versioned_response(
                             endpoint_version,
                             fork_name,
                             execution_optimistic,
+                            finalized,
                             block,
                         )
                         .map(|res| warp::reply::json(&res).into_response()),
@@ -1299,12 +1317,11 @@ pub fn serve<T: BeaconChainTypes>(
         .and(warp::path::end())
         .and_then(|block_id: BlockId, chain: Arc<BeaconChain<T>>| {
             blocking_json_task(move || {
-                let (block, execution_optimistic) = block_id.blinded_block(&chain)?;
+                let (block, execution_optimistic, finalized) = block_id.blinded_block(&chain)?;
-
                 Ok(api_types::GenericResponse::from(api_types::RootData::from(
                     block.canonical_root(),
                 ))
-                .add_execution_optimistic(execution_optimistic))
+                .add_execution_optimistic_finalized(execution_optimistic, finalized))
             })
         });
 
@@ -1315,11 +1332,10 @@ pub fn serve<T: BeaconChainTypes>(
         .and(warp::path::end())
         .and_then(|block_id: BlockId, chain: Arc<BeaconChain<T>>| {
             blocking_json_task(move || {
-                let (block, execution_optimistic) = block_id.blinded_block(&chain)?;
+                let (block, execution_optimistic, finalized) = block_id.blinded_block(&chain)?;
-
                 Ok(
                     api_types::GenericResponse::from(block.message().body().attestations().clone())
-                        .add_execution_optimistic(execution_optimistic),
+                        .add_execution_optimistic_finalized(execution_optimistic, finalized),
                 )
             })
         });
@@ -1337,7 +1353,8 @@ pub fn serve<T: BeaconChainTypes>(
              chain: Arc<BeaconChain<T>>,
              accept_header: Option<api_types::Accept>| {
                 blocking_response_task(move || {
-                    let (block, execution_optimistic) = block_id.blinded_block(&chain)?;
+                    let (block, execution_optimistic, finalized) =
+                        block_id.blinded_block(&chain)?;
                     let fork_name = block
                         .fork_name(&chain.spec)
                         .map_err(inconsistent_fork_rejection)?;
@@ -1355,10 +1372,11 @@ pub fn serve<T: BeaconChainTypes>(
                             }),
                         _ => {
                             // Post as a V2 endpoint so we return the fork version.
-                            execution_optimistic_fork_versioned_response(
+                            execution_optimistic_finalized_fork_versioned_response(
                                 V2,
                                 fork_name,
                                 execution_optimistic,
+                                finalized,
                                 block,
                             )
                             .map(|res| warp::reply::json(&res).into_response())
@@ -1899,11 +1917,13 @@ pub fn serve<T: BeaconChainTypes>(
         .and(warp::path::end())
         .and_then(|chain: Arc<BeaconChain<T>>, block_id: BlockId| {
             blocking_json_task(move || {
-                let (rewards, execution_optimistic) =
+                let (rewards, execution_optimistic, finalized) =
                     standard_block_rewards::compute_beacon_block_rewards(chain, block_id)?;
                 Ok(rewards)
                     .map(api_types::GenericResponse::from)
-                    .map(|resp| resp.add_execution_optimistic(execution_optimistic))
+                    .map(|resp| {
+                        resp.add_execution_optimistic_finalized(execution_optimistic, finalized)
+                    })
             })
         });
 
@@ -1982,14 +2002,16 @@ pub fn serve<T: BeaconChainTypes>(
              validators: Vec<ValidatorId>,
              log: Logger| {
                 blocking_json_task(move || {
-                    let (rewards, execution_optimistic) =
+                    let (rewards, execution_optimistic, finalized) =
                         sync_committee_rewards::compute_sync_committee_rewards(
                             chain, block_id, validators, log,
                         )?;
 
                     Ok(rewards)
                         .map(api_types::GenericResponse::from)
-                        .map(|resp| resp.add_execution_optimistic(execution_optimistic))
+                        .map(|resp| {
+                            resp.add_execution_optimistic_finalized(execution_optimistic, finalized)
+                        })
                 })
             },
         );
@@ -2072,7 +2094,7 @@ pub fn serve<T: BeaconChainTypes>(
                         // We can ignore the optimistic status for the "fork" since it's a
                         // specification constant that doesn't change across competing heads of the
                         // beacon chain.
-                        let (state, _execution_optimistic) = state_id.state(&chain)?;
+                        let (state, _execution_optimistic, _finalized) = state_id.state(&chain)?;
                         let fork_name = state
                             .fork_name(&chain.spec)
                             .map_err(inconsistent_fork_rejection)?;
@@ -2090,16 +2112,17 @@ pub fn serve<T: BeaconChainTypes>(
                                 ))
                             })
                     }
-                    _ => state_id.map_state_and_execution_optimistic(
+                    _ => state_id.map_state_and_execution_optimistic_and_finalized(
                         &chain,
-                        |state, execution_optimistic| {
+                        |state, execution_optimistic, finalized| {
                             let fork_name = state
                                 .fork_name(&chain.spec)
                                 .map_err(inconsistent_fork_rejection)?;
-                            let res = execution_optimistic_fork_versioned_response(
+                            let res = execution_optimistic_finalized_fork_versioned_response(
                                 endpoint_version,
                                 fork_name,
                                 execution_optimistic,
+                                finalized,
                                 &state,
                             )?;
                             Ok(add_consensus_version_header(
@@ -3483,7 +3506,7 @@ pub fn serve<T: BeaconChainTypes>(
         .and_then(|state_id: StateId, chain: Arc<BeaconChain<T>>| {
             blocking_response_task(move || {
                 // This debug endpoint provides no indication of optimistic status.
-                let (state, _execution_optimistic) = state_id.state(&chain)?;
+                let (state, _execution_optimistic, _finalized) = state_id.state(&chain)?;
                 Response::builder()
                     .status(200)
                     .header("Content-Type", "application/ssz")

beacon_node/http_api/src/proposer_duties.rs

@@ -209,7 +209,9 @@ fn compute_historic_proposer_duties<T: BeaconChainTypes>(
                 .map_err(warp_utils::reject::beacon_chain_error)?;
             (state, execution_optimistic)
         } else {
-            StateId::from_slot(epoch.start_slot(T::EthSpec::slots_per_epoch())).state(chain)?
+            let (state, execution_optimistic, _finalized) =
+                StateId::from_slot(epoch.start_slot(T::EthSpec::slots_per_epoch())).state(chain)?;
+            (state, execution_optimistic)
         };
 
     // Ensure the state lookup was correct.

beacon_node/http_api/src/standard_block_rewards.rs

@@ -10,8 +10,8 @@ use warp_utils::reject::beacon_chain_error;
 pub fn compute_beacon_block_rewards<T: BeaconChainTypes>(
     chain: Arc<BeaconChain<T>>,
     block_id: BlockId,
-) -> Result<(StandardBlockReward, ExecutionOptimistic), warp::Rejection> {
+) -> Result<(StandardBlockReward, ExecutionOptimistic, bool), warp::Rejection> {
-    let (block, execution_optimistic) = block_id.blinded_block(&chain)?;
+    let (block, execution_optimistic, finalized) = block_id.blinded_block(&chain)?;
 
     let block_ref = block.message();
 
@@ -23,5 +23,5 @@ pub fn compute_beacon_block_rewards<T: BeaconChainTypes>(
         .compute_beacon_block_reward(block_ref, block_root, &mut state)
         .map_err(beacon_chain_error)?;
 
-    Ok((rewards, execution_optimistic))
+    Ok((rewards, execution_optimistic, finalized))
 }

beacon_node/http_api/src/state_id.rs

@@ -10,6 +10,9 @@ use types::{BeaconState, Checkpoint, EthSpec, Fork, Hash256, Slot};
 #[derive(Debug)]
 pub struct StateId(pub CoreStateId);
 
+// More clarity when returning if the state is finalized or not in the root function.
+type Finalized = bool;
+
 impl StateId {
     pub fn from_slot(slot: Slot) -> Self {
         Self(CoreStateId::Slot(slot))
@@ -19,8 +22,8 @@ impl StateId {
     pub fn root<T: BeaconChainTypes>(
         &self,
         chain: &BeaconChain<T>,
-    ) -> Result<(Hash256, ExecutionOptimistic), warp::Rejection> {
+    ) -> Result<(Hash256, ExecutionOptimistic, Finalized), warp::Rejection> {
-        let (slot, execution_optimistic) = match &self.0 {
+        let (slot, execution_optimistic, finalized) = match &self.0 {
             CoreStateId::Head => {
                 let (cached_head, execution_status) = chain
                     .canonical_head
@@ -29,24 +32,36 @@ impl StateId {
                 return Ok((
                     cached_head.head_state_root(),
                     execution_status.is_optimistic_or_invalid(),
+                    false,
                 ));
             }
-            CoreStateId::Genesis => return Ok((chain.genesis_state_root, false)),
+            CoreStateId::Genesis => return Ok((chain.genesis_state_root, false, true)),
             CoreStateId::Finalized => {
                 let finalized_checkpoint =
                     chain.canonical_head.cached_head().finalized_checkpoint();
-                checkpoint_slot_and_execution_optimistic(chain, finalized_checkpoint)?
+                let (slot, execution_optimistic) =
+                    checkpoint_slot_and_execution_optimistic(chain, finalized_checkpoint)?;
+                (slot, execution_optimistic, true)
             }
             CoreStateId::Justified => {
                 let justified_checkpoint =
                     chain.canonical_head.cached_head().justified_checkpoint();
-                checkpoint_slot_and_execution_optimistic(chain, justified_checkpoint)?
+                let (slot, execution_optimistic) =
+                    checkpoint_slot_and_execution_optimistic(chain, justified_checkpoint)?;
+                (slot, execution_optimistic, false)
             }
             CoreStateId::Slot(slot) => (
                 *slot,
                 chain
                     .is_optimistic_or_invalid_head()
                     .map_err(warp_utils::reject::beacon_chain_error)?,
+                *slot
+                    <= chain
+                        .canonical_head
+                        .cached_head()
+                        .finalized_checkpoint()
+                        .epoch
+                        .start_slot(T::EthSpec::slots_per_epoch()),
             ),
             CoreStateId::Root(root) => {
                 if let Some(hot_summary) = chain
@@ -61,7 +76,10 @@ impl StateId {
                         .is_optimistic_or_invalid_block_no_fallback(&hot_summary.latest_block_root)
                         .map_err(BeaconChainError::ForkChoiceError)
                         .map_err(warp_utils::reject::beacon_chain_error)?;
-                    return Ok((*root, execution_optimistic));
+                    let finalized = chain
+                        .is_finalized_state(root, hot_summary.slot)
+                        .map_err(warp_utils::reject::beacon_chain_error)?;
+                    return Ok((*root, execution_optimistic, finalized));
                 } else if let Some(_cold_state_slot) = chain
                     .store
                     .load_cold_state_slot(root)
@@ -77,7 +95,7 @@ impl StateId {
                         .is_optimistic_or_invalid_block_no_fallback(&finalized_root)
                         .map_err(BeaconChainError::ForkChoiceError)
                         .map_err(warp_utils::reject::beacon_chain_error)?;
-                    return Ok((*root, execution_optimistic));
+                    return Ok((*root, execution_optimistic, true));
                 } else {
                     return Err(warp_utils::reject::custom_not_found(format!(
                         "beacon state for state root {}",
@@ -94,7 +112,7 @@ impl StateId {
                 warp_utils::reject::custom_not_found(format!("beacon state at slot {}", slot))
             })?;
 
-        Ok((root, execution_optimistic))
+        Ok((root, execution_optimistic, finalized))
     }
 
     /// Return the `fork` field of the state identified by `self`.
@@ -103,9 +121,25 @@ impl StateId {
         &self,
         chain: &BeaconChain<T>,
     ) -> Result<(Fork, bool), warp::Rejection> {
-        self.map_state_and_execution_optimistic(chain, |state, execution_optimistic| {
+        self.map_state_and_execution_optimistic_and_finalized(
-            Ok((state.fork(), execution_optimistic))
+            chain,
-        })
+            |state, execution_optimistic, _finalized| Ok((state.fork(), execution_optimistic)),
+        )
+    }
+
+    /// Return the `fork` field of the state identified by `self`.
+    /// Also returns the `execution_optimistic` value of the state.
+    /// Also returns the `finalized` value of the state.
+    pub fn fork_and_execution_optimistic_and_finalized<T: BeaconChainTypes>(
+        &self,
+        chain: &BeaconChain<T>,
+    ) -> Result<(Fork, bool, bool), warp::Rejection> {
+        self.map_state_and_execution_optimistic_and_finalized(
+            chain,
+            |state, execution_optimistic, finalized| {
+                Ok((state.fork(), execution_optimistic, finalized))
+            },
+        )
     }
 
     /// Convenience function to compute `fork` when `execution_optimistic` isn't desired.
@@ -121,8 +155,8 @@ impl StateId {
     pub fn state<T: BeaconChainTypes>(
         &self,
         chain: &BeaconChain<T>,
-    ) -> Result<(BeaconState<T::EthSpec>, ExecutionOptimistic), warp::Rejection> {
+    ) -> Result<(BeaconState<T::EthSpec>, ExecutionOptimistic, Finalized), warp::Rejection> {
-        let ((state_root, execution_optimistic), slot_opt) = match &self.0 {
+        let ((state_root, execution_optimistic, finalized), slot_opt) = match &self.0 {
             CoreStateId::Head => {
                 let (cached_head, execution_status) = chain
                     .canonical_head
@@ -134,6 +168,7 @@ impl StateId {
                         .beacon_state
                         .clone_with_only_committee_caches(),
                     execution_status.is_optimistic_or_invalid(),
+                    false,
                 ));
             }
             CoreStateId::Slot(slot) => (self.root(chain)?, Some(*slot)),
@@ -152,24 +187,25 @@ impl StateId {
                 })
             })?;
 
-        Ok((state, execution_optimistic))
+        Ok((state, execution_optimistic, finalized))
     }
 
     /// Map a function across the `BeaconState` identified by `self`.
     ///
-    /// The optimistic status of the requested state is also provided to the `func` closure.
+    /// The optimistic and finalization status of the requested state is also provided to the `func`
+    /// closure.
     ///
     /// This function will avoid instantiating/copying a new state when `self` points to the head
     /// of the chain.
-    pub fn map_state_and_execution_optimistic<T: BeaconChainTypes, F, U>(
+    pub fn map_state_and_execution_optimistic_and_finalized<T: BeaconChainTypes, F, U>(
         &self,
         chain: &BeaconChain<T>,
         func: F,
     ) -> Result<U, warp::Rejection>
     where
-        F: Fn(&BeaconState<T::EthSpec>, bool) -> Result<U, warp::Rejection>,
+        F: Fn(&BeaconState<T::EthSpec>, bool, bool) -> Result<U, warp::Rejection>,
     {
-        let (state, execution_optimistic) = match &self.0 {
+        let (state, execution_optimistic, finalized) = match &self.0 {
             CoreStateId::Head => {
                 let (head, execution_status) = chain
                     .canonical_head
@@ -178,12 +214,13 @@ impl StateId {
                 return func(
                     &head.snapshot.beacon_state,
                     execution_status.is_optimistic_or_invalid(),
+                    false,
                 );
             }
             _ => self.state(chain)?,
         };
 
-        func(&state, execution_optimistic)
+        func(&state, execution_optimistic, finalized)
     }
 }
 

beacon_node/http_api/src/sync_committee_rewards.rs

@@ -13,8 +13,8 @@ pub fn compute_sync_committee_rewards<T: BeaconChainTypes>(
     block_id: BlockId,
     validators: Vec<ValidatorId>,
     log: Logger,
-) -> Result<(Option<Vec<SyncCommitteeReward>>, ExecutionOptimistic), warp::Rejection> {
+) -> Result<(Option<Vec<SyncCommitteeReward>>, ExecutionOptimistic, bool), warp::Rejection> {
-    let (block, execution_optimistic) = block_id.blinded_block(&chain)?;
+    let (block, execution_optimistic, finalized) = block_id.blinded_block(&chain)?;
 
     let mut state = get_state_before_applying_block(chain.clone(), &block)?;
 
@@ -44,7 +44,7 @@ pub fn compute_sync_committee_rewards<T: BeaconChainTypes>(
         )
     };
 
-    Ok((data, execution_optimistic))
+    Ok((data, execution_optimistic, finalized))
 }
 
 pub fn get_state_before_applying_block<T: BeaconChainTypes>(

beacon_node/http_api/src/validator_inclusion.rs

@@ -18,7 +18,7 @@ fn end_of_epoch_state<T: BeaconChainTypes>(
     let target_slot = epoch.end_slot(T::EthSpec::slots_per_epoch());
     // The execution status is not returned, any functions which rely upon this method might return
     // optimistic information without explicitly declaring so.
-    let (state, _execution_status) = StateId::from_slot(target_slot).state(chain)?;
+    let (state, _execution_status, _finalized) = StateId::from_slot(target_slot).state(chain)?;
     Ok(state)
 }
 

beacon_node/http_api/src/version.rs

@@ -1,9 +1,8 @@
+use crate::api_types::fork_versioned_response::ExecutionOptimisticFinalizedForkVersionedResponse;
 use crate::api_types::EndpointVersion;
 use eth2::CONSENSUS_VERSION_HEADER;
 use serde::Serialize;
-use types::{
+use types::{ForkName, ForkVersionedResponse, InconsistentFork};
-    ExecutionOptimisticForkVersionedResponse, ForkName, ForkVersionedResponse, InconsistentFork,
-};
 use warp::reply::{self, Reply, Response};
 
 pub const V1: EndpointVersion = EndpointVersion(1);
@@ -27,12 +26,13 @@ pub fn fork_versioned_response<T: Serialize>(
     })
 }
 
-pub fn execution_optimistic_fork_versioned_response<T: Serialize>(
+pub fn execution_optimistic_finalized_fork_versioned_response<T: Serialize>(
     endpoint_version: EndpointVersion,
     fork_name: ForkName,
     execution_optimistic: bool,
+    finalized: bool,
     data: T,
-) -> Result<ExecutionOptimisticForkVersionedResponse<T>, warp::reject::Rejection> {
+) -> Result<ExecutionOptimisticFinalizedForkVersionedResponse<T>, warp::reject::Rejection> {
     let fork_name = if endpoint_version == V1 {
         None
     } else if endpoint_version == V2 {
@@ -40,9 +40,10 @@ pub fn execution_optimistic_fork_versioned_response<T: Serialize>(
     } else {
         return Err(unsupported_version_rejection(endpoint_version));
     };
-    Ok(ExecutionOptimisticForkVersionedResponse {
+    Ok(ExecutionOptimisticFinalizedForkVersionedResponse {
         version: fork_name,
         execution_optimistic: Some(execution_optimistic),
+        finalized: Some(finalized),
         data,
     })
 }

beacon_node/http_api/tests/tests.rs

@@ -462,6 +462,264 @@ impl ApiTester {
         self
     }
 
+    // finalization tests
+    pub async fn test_beacon_states_root_finalized(self) -> Self {
+        for state_id in self.interesting_state_ids() {
+            let state_root = state_id.root(&self.chain);
+            let state = state_id.state(&self.chain);
+
+            // if .root or .state fail, skip the test. those would be errors outside the scope
+            // of this test, here we're testing the finalized field assuming the call to .is_finalized_state
+            // occurs after the state_root and state calls, and that the state_root and state calls
+            // were correct.
+            if state_root.is_err() || state.is_err() {
+                continue;
+            }
+
+            // now that we know the state is valid, we can unwrap() everything we need
+            let result = self
+                .client
+                .get_beacon_states_root(state_id.0)
+                .await
+                .unwrap()
+                .unwrap()
+                .finalized
+                .unwrap();
+
+            let (state_root, _, _) = state_root.unwrap();
+            let (state, _, _) = state.unwrap();
+            let state_slot = state.slot();
+            let expected = self
+                .chain
+                .is_finalized_state(&state_root, state_slot)
+                .unwrap();
+
+            assert_eq!(result, expected, "{:?}", state_id);
+        }
+
+        self
+    }
+
+    pub async fn test_beacon_states_fork_finalized(self) -> Self {
+        for state_id in self.interesting_state_ids() {
+            let state_root = state_id.root(&self.chain);
+            let state = state_id.state(&self.chain);
+
+            // if .root or .state fail, skip the test. those would be errors outside the scope
+            // of this test, here we're testing the finalized field assuming the call to .is_finalized_state
+            // occurs after the state_root and state calls, and that the state_root and state calls
+            // were correct.
+            if state_root.is_err() || state.is_err() {
+                continue;
+            }
+
+            // now that we know the state is valid, we can unwrap() everything we need
+            let result = self
+                .client
+                .get_beacon_states_fork(state_id.0)
+                .await
+                .unwrap()
+                .unwrap()
+                .finalized
+                .unwrap();
+
+            let (state_root, _, _) = state_root.unwrap();
+            let (state, _, _) = state.unwrap();
+            let state_slot = state.slot();
+            let expected = self
+                .chain
+                .is_finalized_state(&state_root, state_slot)
+                .unwrap();
+
+            assert_eq!(result, expected, "{:?}", state_id);
+        }
+
+        self
+    }
+
+    pub async fn test_beacon_states_finality_checkpoints_finalized(self) -> Self {
+        for state_id in self.interesting_state_ids() {
+            let state_root = state_id.root(&self.chain);
+            let state = state_id.state(&self.chain);
+
+            // if .root or .state fail, skip the test. those would be errors outside the scope
+            // of this test, here we're testing the finalized field assuming the call to .is_finalized_state
+            // occurs after the state_root and state calls, and that the state_root and state calls
+            // were correct.
+            if state_root.is_err() || state.is_err() {
+                continue;
+            }
+
+            // now that we know the state is valid, we can unwrap() everything we need
+            let result = self
+                .client
+                .get_beacon_states_finality_checkpoints(state_id.0)
+                .await
+                .unwrap()
+                .unwrap()
+                .finalized
+                .unwrap();
+
+            let (state_root, _, _) = state_root.unwrap();
+            let (state, _, _) = state.unwrap();
+            let state_slot = state.slot();
+            let expected = self
+                .chain
+                .is_finalized_state(&state_root, state_slot)
+                .unwrap();
+
+            assert_eq!(result, expected, "{:?}", state_id);
+        }
+
+        self
+    }
+
+    pub async fn test_beacon_headers_block_id_finalized(self) -> Self {
+        for block_id in self.interesting_block_ids() {
+            let block_root = block_id.root(&self.chain);
+            let block = block_id.full_block(&self.chain).await;
+
+            // if .root or .state fail, skip the test. those would be errors outside the scope
+            // of this test, here we're testing the finalized field assuming the call to .is_finalized_state
+            // occurs after the state_root and state calls, and that the state_root and state calls
+            // were correct.
+            if block_root.is_err() || block.is_err() {
+                continue;
+            }
+
+            // now that we know the block is valid, we can unwrap() everything we need
+            let result = self
+                .client
+                .get_beacon_headers_block_id(block_id.0)
+                .await
+                .unwrap()
+                .unwrap()
+                .finalized
+                .unwrap();
+
+            let (block_root, _, _) = block_root.unwrap();
+            let (block, _, _) = block.unwrap();
+            let block_slot = block.slot();
+            let expected = self
+                .chain
+                .is_finalized_block(&block_root, block_slot)
+                .unwrap();
+
+            assert_eq!(result, expected, "{:?}", block_id);
+        }
+
+        self
+    }
+
+    pub async fn test_beacon_blocks_finalized<T: EthSpec>(self) -> Self {
+        for block_id in self.interesting_block_ids() {
+            let block_root = block_id.root(&self.chain);
+            let block = block_id.full_block(&self.chain).await;
+
+            // if .root or .full_block fail, skip the test. those would be errors outside the scope
+            // of this test, here we're testing the finalized field assuming the call to .is_finalized_block
+            // occurs after those calls, and that they were correct.
+            if block_root.is_err() || block.is_err() {
+                continue;
+            }
+
+            // now that we know the block is valid, we can unwrap() everything we need
+            let result = self
+                .client
+                .get_beacon_blocks::<MainnetEthSpec>(block_id.0)
+                .await
+                .unwrap()
+                .unwrap()
+                .finalized
+                .unwrap();
+
+            let (block_root, _, _) = block_root.unwrap();
+            let (block, _, _) = block.unwrap();
+            let block_slot = block.slot();
+            let expected = self
+                .chain
+                .is_finalized_block(&block_root, block_slot)
+                .unwrap();
+
+            assert_eq!(result, expected, "{:?}", block_id);
+        }
+
+        self
+    }
+
+    pub async fn test_beacon_blinded_blocks_finalized<T: EthSpec>(self) -> Self {
+        for block_id in self.interesting_block_ids() {
+            let block_root = block_id.root(&self.chain);
+            let block = block_id.full_block(&self.chain).await;
+
+            // if .root or .full_block fail, skip the test. those would be errors outside the scope
+            // of this test, here we're testing the finalized field assuming the call to .is_finalized_block
+            // occurs after those calls, and that they were correct.
+            if block_root.is_err() || block.is_err() {
+                continue;
+            }
+
+            // now that we know the block is valid, we can unwrap() everything we need
+            let result = self
+                .client
+                .get_beacon_blinded_blocks::<MainnetEthSpec>(block_id.0)
+                .await
+                .unwrap()
+                .unwrap()
+                .finalized
+                .unwrap();
+
+            let (block_root, _, _) = block_root.unwrap();
+            let (block, _, _) = block.unwrap();
+            let block_slot = block.slot();
+            let expected = self
+                .chain
+                .is_finalized_block(&block_root, block_slot)
+                .unwrap();
+
+            assert_eq!(result, expected, "{:?}", block_id);
+        }
+
+        self
+    }
+
+    pub async fn test_debug_beacon_states_finalized(self) -> Self {
+        for state_id in self.interesting_state_ids() {
+            let state_root = state_id.root(&self.chain);
+            let state = state_id.state(&self.chain);
+
+            // if .root or .state fail, skip the test. those would be errors outside the scope
+            // of this test, here we're testing the finalized field assuming the call to .is_finalized_state
+            // occurs after the state_root and state calls, and that the state_root and state calls
+            // were correct.
+            if state_root.is_err() || state.is_err() {
+                continue;
+            }
+
+            // now that we know the state is valid, we can unwrap() everything we need
+            let result = self
+                .client
+                .get_debug_beacon_states::<MainnetEthSpec>(state_id.0)
+                .await
+                .unwrap()
+                .unwrap()
+                .finalized
+                .unwrap();
+
+            let (state_root, _, _) = state_root.unwrap();
+            let (state, _, _) = state.unwrap();
+            let state_slot = state.slot();
+            let expected = self
+                .chain
+                .is_finalized_state(&state_root, state_slot)
+                .unwrap();
+
+            assert_eq!(result, expected, "{:?}", state_id);
+        }
+
+        self
+    }
+
     pub async fn test_beacon_states_root(self) -> Self {
         for state_id in self.interesting_state_ids() {
             let result = self
@@ -474,7 +732,7 @@ impl ApiTester {
             let expected = state_id
                 .root(&self.chain)
                 .ok()
-                .map(|(root, _execution_optimistic)| root);
+                .map(|(root, _execution_optimistic, _finalized)| root);
 
             assert_eq!(result, expected, "{:?}", state_id);
         }
@@ -508,15 +766,13 @@ impl ApiTester {
                 .unwrap()
                 .map(|res| res.data);
 
-            let expected =
+            let expected = state_id.state(&self.chain).ok().map(
-                state_id
+                |(state, _execution_optimistic, _finalized)| FinalityCheckpointsData {
-                    .state(&self.chain)
-                    .ok()
-                    .map(|(state, _execution_optimistic)| FinalityCheckpointsData {
                     previous_justified: state.previous_justified_checkpoint(),
                     current_justified: state.current_justified_checkpoint(),
                     finalized: state.finalized_checkpoint(),
-                    });
+                },
+            );
 
             assert_eq!(result, expected, "{:?}", state_id);
         }
@@ -529,7 +785,9 @@ impl ApiTester {
             for validator_indices in self.interesting_validator_indices() {
                 let state_opt = state_id.state(&self.chain).ok();
                 let validators: Vec<Validator> = match state_opt.as_ref() {
-                    Some((state, _execution_optimistic)) => state.validators().clone().into(),
+                    Some((state, _execution_optimistic, _finalized)) => {
+                        state.validators().clone().into()
+                    }
                     None => vec![],
                 };
                 let validator_index_ids = validator_indices
@@ -568,7 +826,7 @@ impl ApiTester {
                     .unwrap()
                     .map(|res| res.data);
 
-                let expected = state_opt.map(|(state, _execution_optimistic)| {
+                let expected = state_opt.map(|(state, _execution_optimistic, _finalized)| {
                     let mut validators = Vec::with_capacity(validator_indices.len());
 
                     for i in validator_indices {
@@ -598,7 +856,7 @@ impl ApiTester {
                     let state_opt = state_id
                         .state(&self.chain)
                         .ok()
-                        .map(|(state, _execution_optimistic)| state);
+                        .map(|(state, _execution_optimistic, _finalized)| state);
                     let validators: Vec<Validator> = match state_opt.as_ref() {
                         Some(state) => state.validators().clone().into(),
                         None => vec![],
@@ -688,7 +946,7 @@ impl ApiTester {
             let state_opt = state_id
                 .state(&self.chain)
                 .ok()
-                .map(|(state, _execution_optimistic)| state);
+                .map(|(state, _execution_optimistic, _finalized)| state);
             let validators = match state_opt.as_ref() {
                 Some(state) => state.validators().clone().into(),
                 None => vec![],
@@ -743,7 +1001,7 @@ impl ApiTester {
             let mut state_opt = state_id
                 .state(&self.chain)
                 .ok()
-                .map(|(state, _execution_optimistic)| state);
+                .map(|(state, _execution_optimistic, _finalized)| state);
 
             let epoch_opt = state_opt.as_ref().map(|state| state.current_epoch());
             let results = self
@@ -790,7 +1048,7 @@ impl ApiTester {
             let mut state_opt = state_id
                 .state(&self.chain)
                 .ok()
-                .map(|(state, _execution_optimistic)| state);
+                .map(|(state, _execution_optimistic, _finalized)| state);
 
             let epoch_opt = state_opt.as_ref().map(|state| state.current_epoch());
             let result = self
@@ -900,7 +1158,7 @@ impl ApiTester {
             let block_root_opt = block_id
                 .root(&self.chain)
                 .ok()
-                .map(|(root, _execution_optimistic)| root);
+                .map(|(root, _execution_optimistic, _finalized)| root);
 
             if let CoreBlockId::Slot(slot) = block_id.0 {
                 if block_root_opt.is_none() {
@@ -914,7 +1172,7 @@ impl ApiTester {
                 .full_block(&self.chain)
                 .await
                 .ok()
-                .map(|(block, _execution_optimistic)| block);
+                .map(|(block, _execution_optimistic, _finalized)| block);
 
             if block_opt.is_none() && result.is_none() {
                 continue;
@@ -960,7 +1218,7 @@ impl ApiTester {
             let expected = block_id
                 .root(&self.chain)
                 .ok()
-                .map(|(root, _execution_optimistic)| root);
+                .map(|(root, _execution_optimistic, _finalized)| root);
             if let CoreBlockId::Slot(slot) = block_id.0 {
                 if expected.is_none() {
                     assert!(SKIPPED_SLOTS.contains(&slot.as_u64()));
@@ -1007,7 +1265,7 @@ impl ApiTester {
                 .full_block(&self.chain)
                 .await
                 .ok()
-                .map(|(block, _execution_optimistic)| block);
+                .map(|(block, _execution_optimistic, _finalized)| block);
 
             if let CoreBlockId::Slot(slot) = block_id.0 {
                 if expected.is_none() {
@@ -1091,7 +1349,7 @@ impl ApiTester {
             let expected = block_id
                 .blinded_block(&self.chain)
                 .ok()
-                .map(|(block, _execution_optimistic)| block);
+                .map(|(block, _execution_optimistic, _finalized)| block);
 
             if let CoreBlockId::Slot(slot) = block_id.0 {
                 if expected.is_none() {
@@ -1172,7 +1430,7 @@ impl ApiTester {
                 .map(|res| res.data);
 
             let expected = block_id.full_block(&self.chain).await.ok().map(
-                |(block, _execution_optimistic)| {
+                |(block, _execution_optimistic, _finalized)| {
                     block.message().body().attestations().clone().into()
                 },
             );
@@ -1593,7 +1851,7 @@ impl ApiTester {
             let mut expected = state_id
                 .state(&self.chain)
                 .ok()
-                .map(|(state, _execution_optimistic)| state);
+                .map(|(state, _execution_optimistic, _finalized)| state);
             expected.as_mut().map(|state| state.drop_all_caches());
 
             if let (Some(json), Some(expected)) = (&result_json, &expected) {
@@ -3657,7 +3915,7 @@ impl ApiTester {
             let mut expected = state_id
                 .state(&self.chain)
                 .ok()
-                .map(|(state, _execution_optimistic)| state);
+                .map(|(state, _execution_optimistic, _finalized)| state);
             expected.as_mut().map(|state| state.drop_all_caches());
 
             assert_eq!(result, expected, "{:?}", state_id);
@@ -4065,6 +4323,20 @@ async fn beacon_get() {
         .await
         .test_beacon_genesis()
         .await
+        .test_beacon_states_root_finalized()
+        .await
+        .test_beacon_states_fork_finalized()
+        .await
+        .test_beacon_states_finality_checkpoints_finalized()
+        .await
+        .test_beacon_headers_block_id_finalized()
+        .await
+        .test_beacon_blocks_finalized::<MainnetEthSpec>()
+        .await
+        .test_beacon_blinded_blocks_finalized::<MainnetEthSpec>()
+        .await
+        .test_debug_beacon_states_finalized()
+        .await
         .test_beacon_states_root()
         .await
         .test_beacon_states_fork()

beacon_node/store/src/hot_cold_store.rs

@@ -1741,7 +1741,7 @@ fn no_state_root_iter() -> Option<std::iter::Empty<Result<(Hash256, Slot), Error
 /// Allows full reconstruction by replaying blocks.
 #[derive(Debug, Clone, Copy, Default, Encode, Decode)]
 pub struct HotStateSummary {
-    slot: Slot,
+    pub slot: Slot,
     pub latest_block_root: Hash256,
     epoch_boundary_state_root: Hash256,
 }

common/eth2/src/lib.rs

@@ -29,6 +29,7 @@ use std::fmt;
 use std::iter::Iterator;
 use std::path::PathBuf;
 use std::time::Duration;
+use store::fork_versioned_response::ExecutionOptimisticFinalizedForkVersionedResponse;
 
 pub const V1: EndpointVersion = EndpointVersion(1);
 pub const V2: EndpointVersion = EndpointVersion(2);
@@ -338,7 +339,7 @@ impl BeaconNodeHttpClient {
     pub async fn get_beacon_states_root(
         &self,
         state_id: StateId,
-    ) -> Result<Option<ExecutionOptimisticResponse<RootData>>, Error> {
+    ) -> Result<Option<ExecutionOptimisticFinalizedResponse<RootData>>, Error> {
         let mut path = self.eth_path(V1)?;
 
         path.path_segments_mut()
@@ -357,7 +358,7 @@ impl BeaconNodeHttpClient {
     pub async fn get_beacon_states_fork(
         &self,
         state_id: StateId,
-    ) -> Result<Option<ExecutionOptimisticResponse<Fork>>, Error> {
+    ) -> Result<Option<ExecutionOptimisticFinalizedResponse<Fork>>, Error> {
         let mut path = self.eth_path(V1)?;
 
         path.path_segments_mut()
@@ -376,7 +377,7 @@ impl BeaconNodeHttpClient {
     pub async fn get_beacon_states_finality_checkpoints(
         &self,
         state_id: StateId,
-    ) -> Result<Option<ExecutionOptimisticResponse<FinalityCheckpointsData>>, Error> {
+    ) -> Result<Option<ExecutionOptimisticFinalizedResponse<FinalityCheckpointsData>>, Error> {
         let mut path = self.eth_path(V1)?;
 
         path.path_segments_mut()
@@ -396,7 +397,8 @@ impl BeaconNodeHttpClient {
         &self,
         state_id: StateId,
         ids: Option<&[ValidatorId]>,
-    ) -> Result<Option<ExecutionOptimisticResponse<Vec<ValidatorBalanceData>>>, Error> {
+    ) -> Result<Option<ExecutionOptimisticFinalizedResponse<Vec<ValidatorBalanceData>>>, Error>
+    {
         let mut path = self.eth_path(V1)?;
 
         path.path_segments_mut()
@@ -426,7 +428,7 @@ impl BeaconNodeHttpClient {
         state_id: StateId,
         ids: Option<&[ValidatorId]>,
         statuses: Option<&[ValidatorStatus]>,
-    ) -> Result<Option<ExecutionOptimisticResponse<Vec<ValidatorData>>>, Error> {
+    ) -> Result<Option<ExecutionOptimisticFinalizedResponse<Vec<ValidatorData>>>, Error> {
         let mut path = self.eth_path(V1)?;
 
         path.path_segments_mut()
@@ -466,7 +468,7 @@ impl BeaconNodeHttpClient {
         slot: Option<Slot>,
         index: Option<u64>,
         epoch: Option<Epoch>,
-    ) -> Result<Option<ExecutionOptimisticResponse<Vec<CommitteeData>>>, Error> {
+    ) -> Result<Option<ExecutionOptimisticFinalizedResponse<Vec<CommitteeData>>>, Error> {
         let mut path = self.eth_path(V1)?;
 
         path.path_segments_mut()
@@ -499,7 +501,7 @@ impl BeaconNodeHttpClient {
         &self,
         state_id: StateId,
         epoch: Option<Epoch>,
-    ) -> Result<ExecutionOptimisticResponse<SyncCommitteeByValidatorIndices>, Error> {
+    ) -> Result<ExecutionOptimisticFinalizedResponse<SyncCommitteeByValidatorIndices>, Error> {
         let mut path = self.eth_path(V1)?;
 
         path.path_segments_mut()
@@ -522,7 +524,7 @@ impl BeaconNodeHttpClient {
         &self,
         state_id: StateId,
         epoch: Option<Epoch>,
-    ) -> Result<Option<ExecutionOptimisticResponse<RandaoMix>>, Error> {
+    ) -> Result<Option<ExecutionOptimisticFinalizedResponse<RandaoMix>>, Error> {
         let mut path = self.eth_path(V1)?;
 
         path.path_segments_mut()
@@ -547,7 +549,7 @@ impl BeaconNodeHttpClient {
         &self,
         state_id: StateId,
         validator_id: &ValidatorId,
-    ) -> Result<Option<ExecutionOptimisticResponse<ValidatorData>>, Error> {
+    ) -> Result<Option<ExecutionOptimisticFinalizedResponse<ValidatorData>>, Error> {
         let mut path = self.eth_path(V1)?;
 
         path.path_segments_mut()
@@ -568,7 +570,7 @@ impl BeaconNodeHttpClient {
         &self,
         slot: Option<Slot>,
         parent_root: Option<Hash256>,
-    ) -> Result<Option<ExecutionOptimisticResponse<Vec<BlockHeaderData>>>, Error> {
+    ) -> Result<Option<ExecutionOptimisticFinalizedResponse<Vec<BlockHeaderData>>>, Error> {
         let mut path = self.eth_path(V1)?;
 
         path.path_segments_mut()
@@ -595,7 +597,7 @@ impl BeaconNodeHttpClient {
     pub async fn get_beacon_headers_block_id(
         &self,
         block_id: BlockId,
-    ) -> Result<Option<ExecutionOptimisticResponse<BlockHeaderData>>, Error> {
+    ) -> Result<Option<ExecutionOptimisticFinalizedResponse<BlockHeaderData>>, Error> {
         let mut path = self.eth_path(V1)?;
 
         path.path_segments_mut()
@@ -675,7 +677,10 @@ impl BeaconNodeHttpClient {
     pub async fn get_beacon_blocks<T: EthSpec>(
         &self,
         block_id: BlockId,
-    ) -> Result<Option<ExecutionOptimisticForkVersionedResponse<SignedBeaconBlock<T>>>, Error> {
+    ) -> Result<
+        Option<ExecutionOptimisticFinalizedForkVersionedResponse<SignedBeaconBlock<T>>>,
+        Error,
+    > {
         let path = self.get_beacon_blocks_path(block_id)?;
         let response = match self.get_response(path, |b| b).await.optional()? {
             Some(res) => res,
@@ -691,8 +696,10 @@ impl BeaconNodeHttpClient {
     pub async fn get_beacon_blinded_blocks<T: EthSpec>(
         &self,
         block_id: BlockId,
-    ) -> Result<Option<ExecutionOptimisticForkVersionedResponse<SignedBlindedBeaconBlock<T>>>, Error>
+    ) -> Result<
-    {
+        Option<ExecutionOptimisticFinalizedForkVersionedResponse<SignedBlindedBeaconBlock<T>>>,
+        Error,
+    > {
         let path = self.get_beacon_blinded_blocks_path(block_id)?;
         let response = match self.get_response(path, |b| b).await.optional()? {
             Some(res) => res,
@@ -760,7 +767,7 @@ impl BeaconNodeHttpClient {
     pub async fn get_beacon_blocks_root(
         &self,
         block_id: BlockId,
-    ) -> Result<Option<ExecutionOptimisticResponse<RootData>>, Error> {
+    ) -> Result<Option<ExecutionOptimisticFinalizedResponse<RootData>>, Error> {
         let mut path = self.eth_path(V1)?;
 
         path.path_segments_mut()
@@ -779,7 +786,7 @@ impl BeaconNodeHttpClient {
     pub async fn get_beacon_blocks_attestations<T: EthSpec>(
         &self,
         block_id: BlockId,
-    ) -> Result<Option<ExecutionOptimisticResponse<Vec<Attestation<T>>>>, Error> {
+    ) -> Result<Option<ExecutionOptimisticFinalizedResponse<Vec<Attestation<T>>>>, Error> {
         let mut path = self.eth_path(V1)?;
 
         path.path_segments_mut()
@@ -1267,7 +1274,8 @@ impl BeaconNodeHttpClient {
     pub async fn get_debug_beacon_states<T: EthSpec>(
         &self,
         state_id: StateId,
-    ) -> Result<Option<ExecutionOptimisticForkVersionedResponse<BeaconState<T>>>, Error> {
+    ) -> Result<Option<ExecutionOptimisticFinalizedForkVersionedResponse<BeaconState<T>>>, Error>
+    {
         let path = self.get_debug_beacon_states_path(state_id)?;
         self.get_opt(path).await
     }
@@ -1661,7 +1669,7 @@ impl BeaconNodeHttpClient {
         &self,
         epoch: Epoch,
         indices: &[u64],
-    ) -> Result<ExecutionOptimisticResponse<Vec<SyncDuty>>, Error> {
+    ) -> Result<ExecutionOptimisticFinalizedResponse<Vec<SyncDuty>>, Error> {
         let mut path = self.eth_path(V1)?;
 
         path.path_segments_mut()

common/eth2/src/types.rs

@@ -200,6 +200,14 @@ pub struct ExecutionOptimisticResponse<T: Serialize + serde::de::DeserializeOwne
     pub data: T,
 }
 
+#[derive(Debug, PartialEq, Clone, Serialize, Deserialize)]
+#[serde(bound = "T: Serialize + serde::de::DeserializeOwned")]
+pub struct ExecutionOptimisticFinalizedResponse<T: Serialize + serde::de::DeserializeOwned> {
+    pub execution_optimistic: Option<bool>,
+    pub finalized: Option<bool>,
+    pub data: T,
+}
+
 #[derive(Debug, PartialEq, Clone, Serialize, Deserialize)]
 #[serde(bound = "T: Serialize + serde::de::DeserializeOwned")]
 pub struct GenericResponse<T: Serialize + serde::de::DeserializeOwned> {
@@ -222,6 +230,18 @@ impl<T: Serialize + serde::de::DeserializeOwned> GenericResponse<T> {
             data: self.data,
         }
     }
+
+    pub fn add_execution_optimistic_finalized(
+        self,
+        execution_optimistic: bool,
+        finalized: bool,
+    ) -> ExecutionOptimisticFinalizedResponse<T> {
+        ExecutionOptimisticFinalizedResponse {
+            execution_optimistic: Some(execution_optimistic),
+            finalized: Some(finalized),
+            data: self.data,
+        }
+    }
 }
 
 #[derive(Debug, PartialEq, Clone, Serialize)]

consensus/types/src/fork_versioned_response.rs

@@ -5,6 +5,46 @@ use serde_json::value::Value;
 use std::sync::Arc;
 
 // Deserialize is only implemented for types that implement ForkVersionDeserialize
+#[derive(Debug, PartialEq, Clone, Serialize)]
+pub struct ExecutionOptimisticFinalizedForkVersionedResponse<T> {
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub version: Option<ForkName>,
+    pub execution_optimistic: Option<bool>,
+    pub finalized: Option<bool>,
+    pub data: T,
+}
+
+impl<'de, F> serde::Deserialize<'de> for ExecutionOptimisticFinalizedForkVersionedResponse<F>
+where
+    F: ForkVersionDeserialize,
+{
+    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
+    where
+        D: Deserializer<'de>,
+    {
+        #[derive(Deserialize)]
+        struct Helper {
+            version: Option<ForkName>,
+            execution_optimistic: Option<bool>,
+            finalized: Option<bool>,
+            data: serde_json::Value,
+        }
+
+        let helper = Helper::deserialize(deserializer)?;
+        let data = match helper.version {
+            Some(fork_name) => F::deserialize_by_fork::<'de, D>(helper.data, fork_name)?,
+            None => serde_json::from_value(helper.data).map_err(serde::de::Error::custom)?,
+        };
+
+        Ok(ExecutionOptimisticFinalizedForkVersionedResponse {
+            version: helper.version,
+            execution_optimistic: helper.execution_optimistic,
+            finalized: helper.finalized,
+            data,
+        })
+    }
+}
+
 #[derive(Debug, PartialEq, Clone, Serialize)]
 pub struct ExecutionOptimisticForkVersionedResponse<T> {
     #[serde(skip_serializing_if = "Option::is_none")]