Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 10 additions & 0 deletions docs/public-docs/node-operators/kona-node/configuration.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -271,6 +271,16 @@ Before interop both heads are the same block.
Under interop, `kona-node` verifies no cross-chain dependencies itself, so its safe label is only
as safe as the source's cross-safe head: the source must verify them.

If the execution client rejects a forkchoice update that moved the head to the source's heads, for
example because the source's chain does not descend from the node's finalized block, `kona-node`
sends its own last forkchoice again to undo the rejected head and does not send those heads again
until its next reset. A source whose chain does not descend from the node's finalized block is held
back as a whole: its heads are sent again once the node's finality moves, which only a canonical
finalized block from the source can cause, and otherwise once every five minutes. It resets
instead when the execution client no longer holds the node's finalized block, or does not apply the
node's own forkchoice. A rejected update that moved only the safe label is retried on the next
poll.

## RPC Trust Flags

The `--l1-trust-rpc` and `--l2-trust-rpc` flags control whether Kona verifies the block hashes of RPC responses. For guidance on when to disable trust and worked examples for trusted, untrusted, and mixed provider setups, see [configure RPC trust](/node-operators/kona-node/run/rpc-trust).
Expand Down
17 changes: 15 additions & 2 deletions rust/kona/crates/node/engine/src/client.rs
Original file line number Diff line number Diff line change
Expand Up @@ -4,12 +4,14 @@ use crate::Metrics;
use alloy_eips::{BlockId, eip1898::BlockNumberOrTag};
use alloy_json_rpc::{RequestPacket, ResponsePacket};
use alloy_network::{Ethereum, Network};
use alloy_primitives::Bytes;
use alloy_primitives::{B256, Bytes};
use alloy_provider::{EthGetBlock, Provider, RootProvider};
use alloy_rpc_client::ClientBuilder;
use alloy_rpc_types_engine::JwtSecret;
use alloy_rpc_types_eth::Block;
use alloy_transport::{RpcError, TransportError, TransportErrorKind, TransportFut};
use alloy_transport::{
RpcError, TransportError, TransportErrorKind, TransportFut, TransportResult,
};
use alloy_transport_http::{
AuthLayer, Http, HyperClient,
hyper_util::{client::legacy::Client, rt::TokioExecutor},
Expand Down Expand Up @@ -198,6 +200,17 @@ impl EngineClient {
self.engine.get_block(block)
}

/// Whether the execution layer stores the L2 block with `hash`, canonical or not. Only the
/// block's presence is needed, so it is fetched without its transactions.
pub async fn l2_block_is_stored(&self, hash: B256) -> TransportResult<bool> {
debug!(target: "engine", %hash, "Looking up the execution layer's block by hash");
let is_stored = self.get_l2_block(hash.into()).await.inspect_err(|err| {
warn!(target: "engine", ?err, %hash, "Failed to look up the execution layer's block by hash");
})?.is_some();
debug!(target: "engine", %hash, is_stored, "Looked up the execution layer's block by hash");
Ok(is_stored)
}

/// Fetches an L2 block with full transactions.
pub async fn l2_block_by_label(
&self,
Expand Down
8 changes: 4 additions & 4 deletions rust/kona/crates/node/engine/src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -40,10 +40,10 @@ extern crate tracing;
mod task_queue;
pub use task_queue::{
BuildTask, BuildTaskError, CanonicalizeTask, CanonicalizeTaskError, ConsolidateInput,
ConsolidateTask, ConsolidateTaskError, DelegatedSafeHeads, Engine, EngineBuildError,
EngineResetError, EngineTask, EngineTaskError, EngineTaskErrorSeverity, EngineTaskErrors,
ExecutableEngineTask, FinalizeBlockId, FinalizeTask, FinalizeTaskError,
InconsistentSafeHeadsError, InsertTask, InsertTaskError, SealTask, SealTaskError,
ConsolidateTask, ConsolidateTaskError, DelegatedRejection, DelegatedSafeHeads, Engine,
EngineBuildError, EngineResetError, EngineTask, EngineTaskError, EngineTaskErrorSeverity,
EngineTaskErrors, ExecutableEngineTask, FinalizeBlockId, FinalizeTask, FinalizeTaskError,
InconsistentSafeHeadsError, InsertTask, InsertTaskError, SafeLabel, SealTask, SealTaskError,
SynchronizeTaskError,
};

Expand Down
9 changes: 8 additions & 1 deletion rust/kona/crates/node/engine/src/state/core.rs
Original file line number Diff line number Diff line change
Expand Up @@ -77,7 +77,8 @@ impl EngineSyncState {
}

/// Applies the update to the provided sync state, using the current state values if the update
/// is not specified. Returns the new sync state.
/// is not specified, and records the updated labels in the block label metrics. Returns the
/// new sync state.
pub fn apply_update(self, sync_state_update: EngineSyncStateUpdate) -> Self {
if let Some(unsafe_head) = sync_state_update.unsafe_head {
Self::update_block_label_metric(
Expand All @@ -101,6 +102,12 @@ impl EngineSyncState {
);
}

self.with_update(sync_state_update)
}

/// The sync state with the update applied, using the current state values if the update is
/// not specified, without recording anything in the block label metrics.
pub fn with_update(self, sync_state_update: EngineSyncStateUpdate) -> Self {
Self {
unsafe_head: sync_state_update.unsafe_head.unwrap_or(self.unsafe_head),
local_safe_head: sync_state_update.local_safe_head.unwrap_or(self.local_safe_head),
Expand Down
44 changes: 40 additions & 4 deletions rust/kona/crates/node/engine/src/sync/error.rs
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
//! Contains the error types used for finding the starting forkchoice state.

use alloy_eips::BlockId;
use alloy_eips::{BlockId, BlockNumHash};
use alloy_primitives::B256;
use alloy_transport::{RpcError, TransportErrorKind};
use kona_protocol::FromBlockError;
Expand All @@ -26,9 +26,45 @@ pub enum SyncStartError {
/// Invalid L2 genesis hash.
#[error("Invalid L2 genesis hash. Expected {0}, Got {1}")]
InvalidL2GenesisHash(B256, B256),
/// Finalized block mismatch
#[error("Finalized block mismatch. Expected {0}, Got {1}")]
MismatchedFinalizedBlock(B256, B256),
/// The L1 provider holds a different block at the height of the L1 origin of the execution
/// layer's finalized block, so it follows another L1 chain.
#[error("L1 provider has {l1_block:?} at the height of finalized L1 origin {l1_origin:?}")]
FinalizedL1OriginNotCanonical {
/// The L1 provider's block at that height.
l1_block: BlockNumHash,
/// The finalized block's L1 origin.
l1_origin: BlockNumHash,
},
/// The L1 provider serves the L1 origin of the execution layer's finalized block by number
/// but not by hash, as a broken or lagging block-hash index does.
#[error("L1 provider serves finalized L1 origin {l1_origin:?} by number but not by hash")]
FinalizedL1OriginNotServedByHash {
/// The L1 origin it serves only by number.
l1_origin: BlockNumHash,
},
/// The L1 provider does not have the L1 origin of the execution layer's finalized block.
#[error("L1 origin {l1_origin:?} of finalized L2 block {l2_block:?} is not available")]
FinalizedL1OriginUnavailable {
/// The missing L1 origin.
l1_origin: BlockNumHash,
/// The finalized L2 block.
l2_block: BlockNumHash,
},
/// The execution layer returned no block at its finalized height, although its canonical chain
/// extends above it, as a briefly inconsistent execution layer does.
#[error("Execution layer has no block at finalized height {0}")]
FinalizedHeightUnavailable(u64),
/// The chain walked from the execution layer's unsafe head does not contain its finalized
/// block.
#[error(
"Walked chain reached finalized height on {walked:?}, not finalized block {finalized:?}"
)]
MismatchedFinalizedBlock {
/// The execution layer's finalized block.
finalized: BlockNumHash,
/// The walked block at or below the finalized height.
walked: BlockNumHash,
},
/// L1 origin mismatch.
#[error("L1 origin mismatch")]
L1OriginMismatch,
Expand Down
Loading
Loading