feat: persistence meter, consensus tuning, TLS fix, spammer/arch docs (#5)

## Summary
  
- Add `rustls-tls-native-roots` to snapshot download reqwest features
(fixes TLS on platforms without bundled certs)
- Document spammer backpressure and fire-and-forget operating modes in
spammer + quake READMEs
- Refresh `docs/ARCHITECTURE.md` with current crate paths, precompile
addresses, remove stale denylist references
  - Add ADR 0002-0004 entries to `docs/adr/README.md`
  - Add testnet/alpha software disclaimer to root `README.md`
  - Add persistence latency tracking module to eth-engine
  - Extend consensus ready handler with validator set management
  - Fix follow endpoint URL handling
  - Add new CLI config options for consensus tuning
  - Update quake localdev scenarios and compose templates
  - Update node docs and dependency versions

---------

Co-authored-by: atiwari-circle <ayush.tiwari@circle.com>

Author: msheth-circle

Cargo.lock

@@ -7,6 +7,10 @@ QUAKE_MANIFEST ?= crates/quake/scenarios/localdev.toml
 NUM_VALIDATORS := $(shell grep -c '^\[nodes\.validator' $(QUAKE_MANIFEST) 2>/dev/null || echo 5)
 QUAKE := cargo run --bin quake --
 LOAD_PREDEFINED_ARC_REMOTE_SIGNER_KEYS := true
+DEFAULT_BRANCH ?= $(shell git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's@^refs/remotes/origin/@@')
+ifeq ($(DEFAULT_BRANCH),)
+DEFAULT_BRANCH = master
+endif
 
 ##@ Help
 .PHONY: help
@@ -51,7 +55,7 @@ buf-format: ## Format protobuf files using buf
 
 .PHONY: buf-breaking
 buf-breaking: ## Check for breaking changes in protobuf files
-	buf breaking --against '.git#branch=master'
+	buf breaking --against '.git#branch=$(DEFAULT_BRANCH)'
 
 .PHONY: lint
 lint: fmt buf-format build-contract ## Run formatting and linting

Makefile

@@ -1,6 +1,9 @@
 # Arc Node
 
-> The Economic OS for the internet
+> [!IMPORTANT]
+> Arc is currently in testnet, and this is alpha software currently undergoing audits.
+
+The Economic OS for the internet
 
 [![Website](https://img.shields.io/badge/Website-arc.network-blue)](https://www.arc.network/)
 

README.md

@@ -14,6 +14,7 @@ mocks = ["dep:mockall"]
 
 # alloy crates
 alloy-consensus         = { workspace = true }
+alloy-eips              = { workspace = true }
 alloy-genesis           = { workspace = true }
 alloy-primitives        = { workspace = true }
 alloy-rpc-types         = { workspace = true }
@@ -29,7 +30,7 @@ backon = { workspace = true }
 ethereum_serde_utils = "0.8.0"
 eyre = { workspace = true }
 hex = { workspace = true }
-jsonrpsee = { workspace = true }
+jsonrpsee = { workspace = true, features = ["ws-client"] }
 jsonrpsee-types = { workspace = true }
 jsonwebtoken = { workspace = true }
 malachitebft-core-types = { workspace = true }

crates/eth-engine/Cargo.toml

@@ -39,6 +39,16 @@ use crate::ipc::{engine_ipc::EngineIPC, ethereum_ipc::EthereumIPC};
 use crate::json_structures::ExecutionBlock;
 use crate::rpc::{engine_rpc::EngineRpc, ethereum_rpc::EthereumRPC};
 
+/// A subscription-capable transport endpoint for the execution layer.
+///
+/// Exposed so that callers (e.g. startup replay, RPC sync) can establish
+/// auxiliary subscriptions without Engine needing to know about those concerns.
+#[derive(Clone, Debug)]
+pub enum SubscriptionEndpoint {
+    Ipc { socket_path: String },
+    Ws { url: Url },
+}
+
 #[cfg_attr(any(test, feature = "mocks"), mockall::automock)]
 #[async_trait]
 pub trait EngineAPI: Send + Sync {
@@ -105,7 +115,10 @@ impl Engine {
     pub async fn new_ipc(execution_socket: &str, eth_socket: &str) -> eyre::Result<Self> {
         let api = Box::new(EngineIPC::new(execution_socket).await?);
         let eth = Box::new(EthereumIPC::new(eth_socket).await?);
-        Ok(Self::new(api, eth))
+        let sub_endpoint = SubscriptionEndpoint::Ipc {
+            socket_path: eth_socket.to_owned(),
+        };
+        Ok(Self(Arc::new(Inner::new(api, eth, Some(sub_endpoint)))))
     }
 
     /// Create a new engine using RPC.
@@ -115,6 +128,7 @@ impl Engine {
     pub async fn new_rpc(
         execution_endpoint: Url,
         eth_endpoint: Url,
+        ws_endpoint: Option<Url>,
         execution_jwt: &str,
     ) -> eyre::Result<Self> {
         let api = Box::new(EngineRpc::new(
@@ -126,12 +140,13 @@ impl Engine {
         // Probe the RPC server to confirm it is reachable.
         eth.check_connectivity().await?;
 
-        Ok(Self::new(api, eth))
+        let sub_endpoint = ws_endpoint.map(|url| SubscriptionEndpoint::Ws { url });
+        Ok(Self(Arc::new(Inner::new(api, eth, sub_endpoint))))
     }
 
     /// Create a new engine with custom API implementations.
     pub fn new(api: Box<dyn EngineAPI>, eth: Box<dyn EthereumAPI>) -> Self {
-        Self(Arc::new(Inner::new(api, eth)))
+        Self(Arc::new(Inner::new(api, eth, None)))
     }
 
     /// Set the function that determines whether Osaka is active at a given timestamp.
@@ -209,6 +224,13 @@ impl Engine {
             .expect("Clock is before UNIX epoch!")
             .as_secs()
     }
+
+    /// Returns the subscription-capable endpoint for the execution layer,
+    /// if one was configured. `None` for test/mock engines or RPC without
+    /// `--execution-ws-endpoint`.
+    pub fn subscription_endpoint(&self) -> Option<&SubscriptionEndpoint> {
+        self.0.subscription_endpoint.as_ref()
+    }
 }
 
 impl Deref for Engine {
@@ -224,18 +246,24 @@ pub struct Inner {
     pub api: Box<dyn EngineAPI>,
     /// Client for Ethereum API.
     pub eth: Box<dyn EthereumAPI>,
+    /// Subscription-capable endpoint for the execution layer.
+    subscription_endpoint: Option<SubscriptionEndpoint>,
     /// Optional function to check if Osaka is active at a given timestamp.
     /// Set after construction via [`Engine::set_is_osaka_active`].
     /// When `None`, defaults to `false` (use V4).
     is_osaka_active: OnceLock<IsOsakaActiveFn>,
 }
 
 impl Inner {
-    /// Create a new engine with custom API implementations.
-    fn new(api: Box<dyn EngineAPI>, eth: Box<dyn EthereumAPI>) -> Self {
+    fn new(
+        api: Box<dyn EngineAPI>,
+        eth: Box<dyn EthereumAPI>,
+        subscription_endpoint: Option<SubscriptionEndpoint>,
+    ) -> Self {
         Self {
             api,
             eth,
+            subscription_endpoint,
             is_osaka_active: OnceLock::new(),
         }
     }

crates/eth-engine/src/engine.rs

@@ -18,6 +18,7 @@ pub mod capabilities;
 pub mod engine;
 pub mod ipc;
 pub mod json_structures;
+pub mod persistence_meter;
 pub mod retry;
 pub mod rpc;
 
@@ -29,4 +30,5 @@ pub use constants::INITIAL_RETRY_DELAY;
 #[cfg(any(test, feature = "mocks"))]
 pub mod mocks {
     pub use crate::engine::{MockEngineAPI, MockEthereumAPI};
+    pub use crate::persistence_meter::MockPersistenceMeter;
 }