refactor: inject purpose keys structurally through SeismicNode

Instead of relying solely on a global OnceLock side-channel,
purpose keys are now stored in SeismicNode and threaded through
the node builder lifecycle to SeismicExecutorBuilder.

- SeismicNode::new(keys) leaks keys to 'static and stores them
- SeismicExecutorBuilder receives keys from SeismicNode::components()
- main.rs passes keys via SeismicNode::new() instead of ::default()
- Global OnceLock retained as fallback for stage CLI and tests
  that use SeismicNode::default()

Addresses review comment from samlaf on PR #352.

Author: ameya-deshmukh

bin/seismic-reth/src/main.rs

@@ -18,14 +18,17 @@ fn main() {
         // Boot enclave and fetch purpose keys BEFORE building node components
         let purpose_keys = boot_enclave_and_fetch_keys(&encl).await;
 
-        // Store purpose keys in global static storage before building the node
+        // Store purpose keys in global static storage as a fallback for code
+        // paths that cannot yet receive keys structurally (e.g. CLI stage command).
         reth_seismic_node::purpose_keys::init_purpose_keys(purpose_keys.clone());
 
         // building additional endpoints seismic api
         let seismic_api = SeismicApi::new(purpose_keys.clone());
 
+        // Inject purpose keys structurally into SeismicNode so they flow
+        // through the node builder lifecycle without relying on the global.
         let node = builder
-            .node(SeismicNode::default())
+            .node(SeismicNode::new(purpose_keys.clone()))
             .extend_rpc_modules(move |ctx| {
                 // replace eth_ namespace
                 ctx.modules.replace_configured(

crates/seismic/node/src/node.rs

@@ -57,12 +57,38 @@ use crate::seismic_evm_config;
 /// Storage implementation for Seismic.
 pub type SeismicStorage = EthStorage<SeismicTransactionSigned>;
 
-#[derive(Debug, Default, Clone)]
-#[non_exhaustive]
+#[derive(Debug, Clone)]
 /// Type configuration for a regular Seismic node.
-pub struct SeismicNode;
+///
+/// Purpose keys can be injected via [`SeismicNode::new`] so they flow through
+/// the node builder lifecycle instead of being read from a global side-channel.
+/// When constructed via [`Default`] (e.g. in tests), the executor builder will
+/// fall back to the global [`crate::purpose_keys::get_purpose_keys`].
+pub struct SeismicNode {
+    /// Structurally-injected purpose keys.  `None` means "use global fallback".
+    purpose_keys: Option<&'static seismic_enclave::GetPurposeKeysResponse>,
+}
+
+impl Default for SeismicNode {
+    fn default() -> Self {
+        Self { purpose_keys: None }
+    }
+}
 
 impl SeismicNode {
+    /// Create a new [`SeismicNode`] with structurally-injected purpose keys.
+    ///
+    /// The keys are leaked onto the heap so they live for `'static`, which is
+    /// required by the EVM configuration layer.
+    pub fn new(purpose_keys: seismic_enclave::GetPurposeKeysResponse) -> Self {
+        Self { purpose_keys: Some(crate::purpose_keys::leak_purpose_keys(purpose_keys)) }
+    }
+
+    /// Returns the injected purpose keys, if any.
+    pub fn purpose_keys(&self) -> Option<&'static seismic_enclave::GetPurposeKeysResponse> {
+        self.purpose_keys
+    }
+
     /// Returns the components for the given [`EnclaveArgs`].
     pub fn components<Node>(
         &self,
@@ -83,13 +109,14 @@ impl SeismicNode {
             >,
         >,
     {
+        let executor = SeismicExecutorBuilder { purpose_keys: self.purpose_keys };
         ComponentsBuilder::default()
             .node_types::<Node>()
             .pool(SeismicPoolBuilder::default())
-            .executor(SeismicExecutorBuilder::default())
+            .executor(executor.clone())
             .payload(BasicPayloadServiceBuilder::<SeismicPayloadBuilder>::default())
             .network(SeismicNetworkBuilder::default())
-            .executor(SeismicExecutorBuilder::default())
+            .executor(executor)
             .consensus(SeismicConsensusBuilder::default())
     }
 
@@ -404,9 +431,14 @@ where
 }
 
 /// A regular seismic evm and executor builder.
-#[derive(Debug, Default, Clone, Copy)]
-#[non_exhaustive]
-pub struct SeismicExecutorBuilder;
+///
+/// When `purpose_keys` is `Some`, uses the injected keys directly.
+/// When `None`, falls back to the global [`crate::purpose_keys::get_purpose_keys`].
+#[derive(Debug, Default, Clone)]
+pub struct SeismicExecutorBuilder {
+    /// Structurally-injected purpose keys, or `None` for global fallback.
+    purpose_keys: Option<&'static seismic_enclave::GetPurposeKeysResponse>,
+}
 
 impl<Node> ExecutorBuilder<Node> for SeismicExecutorBuilder
 where
@@ -415,7 +447,8 @@ where
     type EVM = SeismicEvmConfig;
 
     async fn build_evm(self, ctx: &BuilderContext<Node>) -> eyre::Result<Self::EVM> {
-        let purpose_keys = crate::purpose_keys::get_purpose_keys();
+        let purpose_keys =
+            self.purpose_keys.unwrap_or_else(|| crate::purpose_keys::get_purpose_keys());
         let evm_config = seismic_evm_config(ctx.chain_spec(), purpose_keys);
 
         Ok(evm_config)

crates/seismic/node/src/purpose_keys.rs

@@ -2,6 +2,19 @@
 //!
 //! This module provides thread-safe access to purpose keys that are fetched once
 //! during node startup and then used throughout the application lifetime.
+//!
+//! ## Preferred path: structural injection
+//!
+//! Purpose keys should be injected into [`SeismicNode::new`](crate::node::SeismicNode::new),
+//! which stores them and threads them through the node builder lifecycle
+//! (executor builder, etc.). This avoids reliance on global state.
+//!
+//! ## Deprecated fallback: global `OnceLock`
+//!
+//! The global [`init_purpose_keys`] / [`get_purpose_keys`] functions are retained
+//! as a fallback for code paths that cannot yet receive keys structurally (e.g.
+//! the CLI `stage` command, or tests that construct `SeismicNode::default()`).
+//! New code should prefer the injection path.
 
 use seismic_enclave::GetPurposeKeysResponse;
 use std::sync::OnceLock;
@@ -28,3 +41,12 @@ pub fn init_purpose_keys(keys: GetPurposeKeysResponse) {
 pub fn get_purpose_keys() -> &'static GetPurposeKeysResponse {
     PURPOSE_KEYS.get().expect("Purpose keys not initialized")
 }
+
+/// Leak-box the given keys onto the heap and return a `&'static` reference.
+///
+/// This is used by [`SeismicNode::new`](crate::node::SeismicNode::new) so that
+/// the purpose keys have a `'static` lifetime without relying on the global
+/// `OnceLock`.
+pub fn leak_purpose_keys(keys: GetPurposeKeysResponse) -> &'static GetPurposeKeysResponse {
+    Box::leak(Box::new(keys))
+}