feat(tee): add Trusted Execution Environment (TEE) attestation support (#378)

Implements TEE (Trusted Execution Environment) integration into Katana, enabling the generation of hardware-signed attestation quotes that cryptographically bind the sequencer's execution state (state root) to a TEE (Intel TDX). Includes new katana-tee crate, RPC API extension with `tee_generateQuote` method, CLI options, and node configuration.

---------

Co-authored-by: Claude Haiku 4.5 <[email protected]>
Co-authored-by: Luca Steeb <[email protected]>
Co-authored-by: Ammar Arif <[email protected]>

Author: 4 people

Cargo.lock

@@ -43,6 +43,7 @@ members = [
 	"crates/sync/pipeline",
 	"crates/sync/stage",
 	"crates/tasks",
+	"crates/tee",
 	"crates/tracing",
 	"crates/trie",
 	"crates/utils",
@@ -108,6 +109,7 @@ katana-slot-controller = { path = "crates/controller" }
 katana-stage = { path = "crates/sync/stage" }
 katana-starknet = { path = "crates/starknet" }
 katana-tasks = { path = "crates/tasks" }
+katana-tee = { path = "crates/tee" }
 katana-tracing = { path = "crates/tracing" }
 katana-trie = { path = "crates/trie" }
 katana-utils = { path = "crates/utils" }
@@ -130,6 +132,7 @@ auto_impl = "1.2.0"
 backon = { version = "1.5", features = [ "tokio-sleep" ] }
 base64 = "0.21"
 bigdecimal = "0.4.1"
+bincode = "1.3"
 bitvec = "1.0.1"
 camino = { version = "1.1.2", features = [ "serde1" ] }
 chrono = { version = "0.4.24", features = [ "serde" ] }
@@ -157,6 +160,7 @@ regex = "1.10.3"
 reqwest = { version = "0.12.15", features = [ "json", "rustls-tls" ], default-features = false }
 rstest = "0.18.2"
 rstest_reuse = "0.6.0"
+sev-snp = { git = "https://github.com/automata-network/amd-sev-snp-attestation-sdk", branch = "main", default-features = false, features = ["legacy", "configfs"] }
 similar-asserts = "1.5.0"
 slot = { git = "https://github.com/cartridge-gg/slot", rev = "1298a30" }
 spinoff = "0.8.0"
@@ -227,7 +231,7 @@ opentelemetry-stackdriver = { version = "0.27.0", features = [ "propagator" ] }
 
 # starknet
 starknet = "0.17.0"
-starknet-types-core = { version = "0.2", features = [ "arbitrary", "hash" ] }
+starknet-types-core = { version = "=0.2.3", features = [ "arbitrary", "hash" ] }
 # Some types that we used from cairo-vm implements the `Arbitrary` trait,
 # only under the `test_utils` feature.
 cairo-vm = { version = "2.5.0", features = [ "test_utils" ] }

Cargo.toml

@@ -14,6 +14,7 @@ katana-genesis.workspace = true
 katana-primitives.workspace = true
 katana-rpc-server.workspace = true
 katana-slot-controller = { workspace = true, optional = true }
+katana-tee = { workspace = true, optional = true }
 katana-tracing.workspace = true
 katana-utils.workspace = true
 serde-utils.workspace = true
@@ -41,7 +42,8 @@ cartridge = [
 	"katana-node/cartridge",
 	"katana-rpc-server/cartridge",
 ]
-default = [ "cartridge", "server" ]
-explorer = [ "katana-node/explorer", "katana-utils/explorer" ]
-native = [ "katana-node/native" ]
-server = [  ]
+default = ["cartridge", "server", "tee"]
+explorer = ["katana-node/explorer", "katana-utils/explorer"]
+native = ["katana-node/native"]
+server = []
+tee = ["dep:katana-tee", "katana-node/tee", "katana-node/tee-snp", "katana-tee/snp"]

crates/cli/Cargo.toml

@@ -27,6 +27,8 @@ use katana_node::config::rpc::RpcConfig;
 #[cfg(feature = "server")]
 use katana_node::config::rpc::{RpcModuleKind, RpcModulesList};
 use katana_node::config::sequencing::SequencingConfig;
+#[cfg(feature = "tee")]
+use katana_node::config::tee::TeeConfig;
 use katana_node::config::Config;
 use katana_node::Node;
 use serde::{Deserialize, Serialize};
@@ -129,6 +131,10 @@ pub struct SequencerNodeArgs {
     #[cfg(feature = "cartridge")]
     #[command(flatten)]
     pub cartridge: CartridgeOptions,
+
+    #[cfg(feature = "tee")]
+    #[command(flatten)]
+    pub tee: TeeOptions,
 }
 
 impl SequencerNodeArgs {
@@ -212,37 +218,21 @@ impl SequencerNodeArgs {
         // the messagign config will eventually be removed slowly.
         let messaging = if cs_messaging.is_some() { cs_messaging } else { self.messaging.clone() };
 
-        #[cfg(feature = "cartridge")]
-        {
-            let paymaster = self.cartridge_config();
-
-            Ok(Config {
-                db,
-                dev,
-                rpc,
-                chain,
-                metrics,
-                gateway,
-                forking,
-                execution,
-                messaging,
-                paymaster,
-                sequencing,
-            })
-        }
-
-        #[cfg(not(feature = "cartridge"))]
         Ok(Config {
-            metrics,
             db,
             dev,
             rpc,
             chain,
-            feeder_gateway,
+            metrics,
+            gateway,
+            forking,
             execution,
-            sequencing,
             messaging,
-            forking,
+            sequencing,
+            #[cfg(feature = "cartridge")]
+            paymaster: self.cartridge_config(),
+            #[cfg(feature = "tee")]
+            tee: self.tee_config(),
         })
     }
 
@@ -291,6 +281,14 @@ impl SequencerNodeArgs {
                 modules.add(RpcModuleKind::Cartridge);
             }
 
+            // The TEE rpc must be enabled if a TEE provider is specified.
+            // We put it here so that even when the individual api are explicitly specified
+            // (ie `--rpc.api`) we guarantee that the tee rpc is enabled.
+            #[cfg(feature = "tee")]
+            if self.tee.tee_provider.is_some() {
+                modules.add(RpcModuleKind::Tee);
+            }
+
             let cors_origins = self.server.http_cors_origins.clone();
 
             Ok(RpcConfig {
@@ -459,6 +457,11 @@ impl SequencerNodeArgs {
         }
     }
 
+    #[cfg(feature = "tee")]
+    fn tee_config(&self) -> Option<TeeConfig> {
+        self.tee.tee_provider.map(|provider_type| TeeConfig { provider_type })
+    }
+
     /// Parse the node config from the command line arguments and the config file,
     /// and merge them together prioritizing the command line arguments.
     pub fn with_config_file(mut self) -> Result<Self> {

crates/cli/src/args.rs

@@ -810,3 +810,28 @@ fn parse_pruning_mode(s: &str) -> Result<PruningMode, String> {
         _ => Err(format!("Invalid pruning mode '{s}'. Valid modes are: 'archive', 'full:N'")),
     }
 }
+
+#[cfg(feature = "tee")]
+#[derive(Debug, Args, Clone, Serialize, Deserialize, Default, PartialEq)]
+#[command(next_help_heading = "TEE options")]
+pub struct TeeOptions {
+    /// Enable TEE attestation support with AMD SEV-SNP.
+    ///
+    /// When enabled, the TEE RPC API becomes available for generating
+    /// hardware-backed attestation quotes. Requires running in an SEV-SNP VM
+    /// with /dev/sev-guest available.
+    #[arg(long = "tee.provider", value_name = "PROVIDER")]
+    #[serde(default)]
+    pub tee_provider: Option<katana_tee::TeeProviderType>,
+}
+
+#[cfg(feature = "tee")]
+impl TeeOptions {
+    pub fn merge(&mut self, other: Option<&Self>) {
+        if let Some(other) = other {
+            if self.tee_provider.is_none() {
+                self.tee_provider = other.tee_provider;
+            }
+        }
+    }
+}

crates/cli/src/options.rs

@@ -27,6 +27,7 @@ katana-rpc-client.workspace = true
 katana-rpc-types.workspace = true
 katana-stage.workspace = true
 katana-tasks.workspace = true
+katana-tee = { workspace = true, optional = true }
 
 anyhow.workspace = true
 backon.workspace = true
@@ -46,6 +47,8 @@ strum_macros.workspace = true
 tokio = { workspace = true, features = [ "time" ] }
 
 [features]
-cartridge = [ "katana-rpc-api/cartridge", "katana-rpc-server/cartridge" ]
-explorer = [ "katana-rpc-server/explorer" ]
-native = [ "katana-executor/native" ]
+cartridge = ["katana-rpc-api/cartridge", "katana-rpc-server/cartridge"]
+explorer = ["katana-rpc-server/explorer"]
+native = ["katana-executor/native"]
+tee = ["dep:katana-tee", "katana-rpc-api/tee", "katana-rpc-server/tee"]
+tee-snp = ["tee", "katana-tee/snp"]

crates/node/Cargo.toml

@@ -10,6 +10,8 @@ pub mod metrics;
 pub mod paymaster;
 pub mod rpc;
 pub mod sequencing;
+#[cfg(feature = "tee")]
+pub mod tee;
 
 use db::DbConfig;
 use dev::DevConfig;
@@ -60,4 +62,8 @@ pub struct Config {
     /// Cartridge paymaster options.
     #[cfg(feature = "cartridge")]
     pub paymaster: Option<paymaster::PaymasterConfig>,
+
+    /// TEE attestation options.
+    #[cfg(feature = "tee")]
+    pub tee: Option<tee::TeeConfig>,
 }

crates/node/src/config/mod.rs

@@ -34,6 +34,8 @@ pub enum RpcModuleKind {
     Dev,
     #[cfg(feature = "cartridge")]
     Cartridge,
+    #[cfg(feature = "tee")]
+    Tee,
 }
 
 /// Configuration for the RPC server.
@@ -104,6 +106,8 @@ impl RpcModulesList {
             RpcModuleKind::Dev,
             #[cfg(feature = "cartridge")]
             RpcModuleKind::Cartridge,
+            #[cfg(feature = "tee")]
+            RpcModuleKind::Tee,
         ]))
     }
 

crates/node/src/config/rpc.rs

@@ -0,0 +1,8 @@
+use katana_tee::TeeProviderType;
+
+/// TEE configuration options.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct TeeConfig {
+    /// The type of TEE provider to use for attestation.
+    pub provider_type: TeeProviderType,
+}

crates/node/src/config/tee.rs

@@ -39,6 +39,8 @@ use katana_rpc_api::dev::DevApiServer;
 use katana_rpc_api::starknet::{StarknetApiServer, StarknetTraceApiServer, StarknetWriteApiServer};
 #[cfg(feature = "explorer")]
 use katana_rpc_api::starknet_ext::StarknetApiExtServer;
+#[cfg(feature = "tee")]
+use katana_rpc_api::tee::TeeApiServer;
 use katana_rpc_client::starknet::Client as StarknetClient;
 #[cfg(feature = "cartridge")]
 use katana_rpc_server::cartridge::CartridgeApi;
@@ -47,6 +49,8 @@ use katana_rpc_server::dev::DevApi;
 #[cfg(feature = "cartridge")]
 use katana_rpc_server::starknet::PaymasterConfig;
 use katana_rpc_server::starknet::{StarknetApi, StarknetApiConfig};
+#[cfg(feature = "tee")]
+use katana_rpc_server::tee::TeeApi;
 use katana_rpc_server::{RpcServer, RpcServerHandle};
 use katana_rpc_types::GetBlockWithTxHashesResponse;
 use katana_stage::Sequencing;
@@ -269,6 +273,37 @@ where
             rpc_modules.merge(DevApiServer::into_rpc(api))?;
         }
 
+        // --- build tee api (if configured)
+        #[cfg(feature = "tee")]
+        if config.rpc.apis.contains(&RpcModuleKind::Tee) {
+            if let Some(ref tee_config) = config.tee {
+                use katana_tee::{TeeProvider, TeeProviderType};
+
+                let tee_provider: Arc<dyn TeeProvider> = match tee_config.provider_type {
+                    TeeProviderType::SevSnp => {
+                        #[cfg(feature = "tee-snp")]
+                        {
+                            Arc::new(
+                                katana_tee::SevSnpProvider::new()
+                                    .context("Failed to initialize SEV-SNP provider")?,
+                            )
+                        }
+                        #[cfg(not(feature = "tee-snp"))]
+                        {
+                            anyhow::bail!(
+                                "SEV-SNP TEE provider requires the 'tee-snp' feature to be enabled"
+                            );
+                        }
+                    }
+                };
+
+                let api = TeeApi::new(provider.clone(), tee_provider);
+                rpc_modules.merge(TeeApiServer::into_rpc(api))?;
+
+                info!(target: "node", provider = ?tee_config.provider_type, "TEE API enabled");
+            }
+        }
+
         #[allow(unused_mut)]
         let mut rpc_server =
             RpcServer::new().metrics(true).health_check(true).cors(cors).module(rpc_modules)?;