[key-server] handle committee mode

Author: joyqvq

Cargo.lock

@@ -182,7 +182,12 @@ async fn main() -> Result<()> {
             };
 
             // Fetch current committee from onchain.
-            let mut grpc_client = create_grpc_client(&network)?;
+            let network_enum = match network.to_lowercase().as_str() {
+                "mainnet" => seal_committee::Network::Mainnet,
+                "testnet" => seal_committee::Network::Testnet,
+                _ => anyhow::bail!("Invalid network: {}. Use 'mainnet' or 'testnet'", network),
+            };
+            let mut grpc_client = create_grpc_client(network_enum)?;
             let committee = fetch_committee_data(&committee_id, &mut grpc_client).await?;
 
             // Validate committee state is in Init state and contains my address.

crates/dkg-cli/src/main.rs

@@ -50,6 +50,7 @@ hyper-util = "0.1.10"
 http-body-util = "0.1.2"
 futures = "0.3"
 seal-sdk = { path = "../seal-sdk" }
+seal-committee = { path = "../seal-committee" }
 
 # sui grpc dep
 sui-rpc = { workspace = true }

crates/key-server/Cargo.toml

@@ -7,7 +7,7 @@
 # network: !Custom
 #   node_url: 'url_to_node_endpoint'  # Optional - see below
 #   use_default_mainnet_for_mvr: true # Optional, default to true if not present, 
-set this to false for mvr to resolve on testnet. 
+# set this to false for mvr to resolve on testnet. 
 #
 # Use Custom for production deployments. You must provide the node URL
 # in exactly one of these ways:
@@ -19,20 +19,24 @@ set this to false for mvr to resolve on testnet.
 network: Testnet
 
 
-# Server mode. The server can either work in Open/permissionless mode that 
-# supports all packages, or in Permissioned mode that only supports
-# whitelisted packages .
+# Server mode: Open, Permissioned or Committee.  
+# Open: Supports all policy packages. 
+# Permissioned: Supports only allowed policy packages. 
+# Committee: Supports all packages. Contains committee ID and next 
+# committee ID. Note that the MASTER_KEY for Committee mode is the 
+# output of a DKG ceremony that you participated in. 
 #
-# For the Open mode, set the registered key server object ID to be used, e.g.,:
+#### OPEN MODE ####
+# Set the registered key server object ID to be used, e.g.,:
 # server_mode: !Open
 #   key_server_object_id: '0x0000000000000000000000000000000000000000000000000000000000000000'
 #
 # Example:
-server_mode: !Open
-  key_server_object_id: '0x0000000000000000000000000000000000000000000000000000000000000000'
+# server_mode: !Open
+#   key_server_object_id: '0x0000000000000000000000000000000000000000000000000000000000000000'
 
-#
-# For the Permissioned mode, set the allowed clients and their configurations.
+#### PERMISSIONED MODE ####
+# Set the allowed clients and their configurations.
 # A client config contains:
 # - Client name - for debugging purposes only, can always be modified.
 # - The associated key server object id. Should never change.
@@ -75,6 +79,24 @@ server_mode: !Open
 #       package_ids:
 #         - "0x3333333333333333333333333333333333333333333333333333333333333333"
 
+#### COMMITTEE MODE ####
+# The config contains the committee ID and member address, and the server expects a MASTER_KEY provided
+# as an environment variable. The server validates the committee is finalized and serve request with
+# MASTER_KEY. During key rotation, the config can also contain the next committee ID and the server 
+# expects NEXT_MASTER_KEY. The server fetches the onchain state periodically:
+# - If the committee still exists and the next committee is in Init or PostDKG state, still serve 
+# requests with MASTER_KEY.
+# - If the committee is deleted and the next committee is finalized, serve requests with 
+# NEXT_MASTER_KEY.
+# Example: 
+# server_mode: !Committee
+#   member_address: '0x0000000000000000000000000000000000000000000000000000000000000000'
+#   committee_id: '0x0000000000000000000000000000000000000000000000000000000000000001'
+#   next_committee_id: '0x0000000000000000000000000000000000000000000000000000000000000002'
+#
+server_mode: !Committee
+  member_address: '0x223762117ab21a439f0f3f3b0577e838b8b26a37d9a1723a4be311243f4461b9'
+  committee_id: '0xd80885d60e2d86be6ab936afd1c717dc0d459406d4fda0cee583dee429947784'
 
 #### Optional advanced configurations ####
 #

crates/key-server/key-server-config.yaml

@@ -9,6 +9,7 @@ use duration_str::deserialize_duration;
 use semver::VersionReq;
 use serde::{Deserialize, Serialize};
 use std::time::Duration;
+use sui_sdk_types::Address;
 use sui_types::base_types::ObjectID;
 use tracing::info;
 
@@ -47,8 +48,12 @@ pub enum ServerMode {
         // Master key is expected to by 32 byte HKDF seed
         client_configs: Vec<ClientConfig>,
     },
+    Committee {
+        member_address: Address,
+        committee_id: ObjectID,
+        next_committee_id: Option<ObjectID>,
+    },
 }
-
 /// Configuration for the RPC client.
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct RpcConfig {
@@ -197,6 +202,30 @@ impl KeyServerOptions {
             serde_yaml::to_string(self).expect("should serialize")
         );
 
+        // Validate Committee mode specific requirements
+        if let ServerMode::Committee {
+            next_committee_id, ..
+        } = &self.server_mode
+        {
+            // MASTER_KEY must always be present in Committee mode
+            if std::env::var("MASTER_KEY").is_err() {
+                return Err(anyhow!(
+                    "In Committee mode, MASTER_KEY environment variable must be set"
+                ));
+            }
+
+            let next_master_key_exists = std::env::var("NEXT_MASTER_KEY").is_ok();
+
+            // Both NEXT_MASTER_KEY and next_committee_id must be provided together or both absent
+            if next_master_key_exists != next_committee_id.is_some() {
+                return Err(anyhow!(
+                    "In Committee mode, NEXT_MASTER_KEY environment variable and next_committee_id must both be provided or both be absent. Found: NEXT_MASTER_KEY={}, next_committee_id={}",
+                    next_master_key_exists,
+                    next_committee_id.is_some()
+                ));
+            }
+        }
+
         if let ServerMode::Permissioned { client_configs } = &self.server_mode {
             let mut names = std::collections::HashSet::new();
             let mut derivation_indices = std::collections::HashSet::new();
@@ -256,13 +285,18 @@ impl KeyServerOptions {
         Ok(())
     }
 
-    pub(crate) fn get_supported_key_server_object_ids(&self) -> Vec<ObjectID> {
+    #[cfg(test)]
+    pub(crate) fn get_key_server_object_ids_for_testing(&self) -> Vec<ObjectID> {
         match &self.server_mode {
             ServerMode::Open {
                 key_server_object_id,
             } => {
                 vec![*key_server_object_id]
             }
+            ServerMode::Committee { .. } => {
+                // Committee mode fetches key_server_id from chain
+                vec![]
+            }
             ServerMode::Permissioned { client_configs } => client_configs
                 .iter()
                 .filter(|c| {
@@ -354,6 +388,43 @@ server_mode: !Open
 
     let unknown_option = "a_complete_unknown: 'a rolling stone'\n";
     assert!(serde_yaml::from_str::<KeyServerOptions>(unknown_option).is_err());
+
+    // test committee mode
+    let valid_configuration_committee = r#"
+network: Mainnet
+server_mode: !Committee
+  member_address: '0x0000000000000000000000000000000000000000000000000000000000000000'
+  committee_id: '0x1'
+  next_committee_id: '0x2'
+"#;
+    let options: KeyServerOptions = serde_yaml::from_str(valid_configuration_committee)
+        .expect("Failed to parse valid configuration");
+    assert_eq!(
+        options.server_mode,
+        ServerMode::Committee {
+            member_address: Address::ZERO,
+            committee_id: ObjectID::from_str("0x1").unwrap(),
+            next_committee_id: Some(ObjectID::from_str("0x2").unwrap()),
+        }
+    );
+
+    // test committee mode without next_committee_id
+    let valid_configuration_committee_no_next = r#"
+network: Mainnet
+server_mode: !Committee
+  member_address: '0x0000000000000000000000000000000000000000000000000000000000000000'
+  committee_id: '0x1'
+"#;
+    let options: KeyServerOptions = serde_yaml::from_str(valid_configuration_committee_no_next)
+        .expect("Failed to parse valid configuration");
+    assert_eq!(
+        options.server_mode,
+        ServerMode::Committee {
+            member_address: Address::ZERO,
+            committee_id: ObjectID::from_str("0x1").unwrap(),
+            next_committee_id: None,
+        }
+    );
 }
 
 #[test]
@@ -416,8 +487,9 @@ session_key_ttl_max: '60s'
     let options: KeyServerOptions =
         serde_yaml::from_str(valid_configuration).expect("Failed to parse valid configuration");
 
+    // Verify that the HashMap would contain keys for alice and bob (not carol since Exported)
     assert_eq!(
-        options.get_supported_key_server_object_ids(),
+        options.get_key_server_object_ids_for_testing(),
         vec![
             ObjectID::from_str(
                 "0xaaaa000000000000000000000000000000000000000000000000000000000001"

crates/key-server/src/key_server_options.rs

@@ -20,7 +20,7 @@ const MASTER_KEY_ENV_VAR: &str = "MASTER_KEY";
 /// Represents the set of master keys held by a key server.
 #[derive(Clone)]
 pub enum MasterKeys {
-    /// In open mode, the key server has a single master key used for all packages.
+    /// In open or committee mode, the key server has a single master key used for all packages.
     Open { master_key: IbeMasterKey },
     /// In permissioned mode, the key server has a mapping of package IDs to master keys.
     Permissioned {
@@ -33,7 +33,7 @@ impl MasterKeys {
     pub(crate) fn load(options: &KeyServerOptions) -> anyhow::Result<Self> {
         info!("Loading keys from env variables");
         match &options.server_mode {
-            ServerMode::Open { .. } => {
+            ServerMode::Open { .. } | ServerMode::Committee { .. } => {
                 let master_key = match decode_master_key::<DefaultEncoding>(MASTER_KEY_ENV_VAR) {
                     Ok(master_key) => master_key,
 

crates/key-server/src/master_keys.rs

@@ -4,7 +4,7 @@ use crate::errors::InternalError::{
     DeprecatedSDKVersion, InvalidSDKVersion, MissingRequiredHeader,
 };
 use crate::externals::get_reference_gas_price;
-use crate::key_server_options::ServerMode;
+use crate::key_server_options::{ClientKeyType, ServerMode};
 use crate::metrics::{call_with_duration, observation_callback, status_callback, Metrics};
 use crate::metrics_push::create_push_client;
 use crate::mvr::mvr_forward_resolution;
@@ -155,17 +155,7 @@ impl Server {
             panic!("Failed to load master keys: {}", e);
         });
 
-        let key_server_oid_to_pop = options
-            .get_supported_key_server_object_ids()
-            .into_iter()
-            .map(|ks_oid| {
-                let key = master_keys
-                    .get_key_for_key_server(&ks_oid)
-                    .expect("checked already");
-                let pop = create_proof_of_possession(key, &ks_oid.into_bytes());
-                (ks_oid, pop)
-            })
-            .collect();
+        let key_server_oid_to_pop = Self::build_key_server_pop_map(&options, &master_keys).await;
 
         Server {
             sui_rpc_client,
@@ -175,6 +165,114 @@ impl Server {
         }
     }
 
+    /// Build the key_server_oid -> PoP HashMap for all server modes.
+    /// Handles fetching from chain for Committee mode.
+    async fn build_key_server_pop_map(
+        options: &KeyServerOptions,
+        master_keys: &MasterKeys,
+    ) -> HashMap<ObjectID, MasterKeyPOP> {
+        match &options.server_mode {
+            ServerMode::Open {
+                key_server_object_id,
+            } => {
+                let key = master_keys
+                    .get_key_for_key_server(key_server_object_id)
+                    .expect("checked already");
+                let pop = create_proof_of_possession(key, &key_server_object_id.into_bytes());
+                let mut map = HashMap::new();
+                map.insert(*key_server_object_id, pop);
+                map
+            }
+            ServerMode::Committee {
+                member_address,
+                committee_id,
+                next_committee_id: _,
+            } => {
+                info!("Committee mode - validating committee at startup");
+
+                // Create gRPC client for seal-committee helpers
+                let network = match options.network {
+                    Network::Mainnet => seal_committee::Network::Mainnet,
+                    Network::Testnet => seal_committee::Network::Testnet,
+                    _ => panic!("Unsupported network for Committee mode"),
+                };
+                let mut grpc_client = seal_committee::create_grpc_client(network)
+                    .expect("Failed to create gRPC client");
+
+                // Fetch and verify committee is finalized
+                let committee_addr = sui_sdk_types::Address::from_bytes(committee_id.as_ref())
+                    .unwrap_or_else(|e| panic!("Invalid committee ID: {:?}", e));
+                if !seal_committee::check_committee_finalized(&mut grpc_client, &committee_addr)
+                    .await
+                    .unwrap_or_else(|e| panic!("Failed to check committee finalized: {:?}", e))
+                {
+                    panic!("Committee {} is not finalized", committee_id);
+                }
+
+                // Fetch KeyServer from committee's dynamic field
+                let key_server_id =
+                    seal_committee::fetch_key_server_id(&mut grpc_client, &committee_addr)
+                        .await
+                        .unwrap_or_else(|e| {
+                            panic!("Failed to fetch KeyServer from committee: {:?}", e)
+                        });
+
+                let key_server_oid = ObjectID::new(key_server_id.into_inner());
+
+                // Fetch PartialKeyServer info for this member
+                let partial_key_server_info = seal_committee::fetch_partial_key_server_info(
+                    &mut grpc_client,
+                    &key_server_id,
+                    *member_address,
+                )
+                .await
+                .unwrap_or_else(|e| panic!("Failed to fetch PartialKeyServer: {:?}", e))
+                .unwrap_or_else(|| {
+                    panic!("No PartialKeyServer found for member {}", member_address)
+                });
+
+                // Sign PoP over: key_server_oid || party_id || partial_pk
+                let mut pop_message = Vec::new();
+                pop_message.extend_from_slice(&key_server_oid.into_bytes());
+                pop_message.extend_from_slice(&partial_key_server_info.party_id.to_le_bytes());
+                pop_message.extend_from_slice(&partial_key_server_info.partial_pk);
+
+                // Extract master_key from already-loaded MasterKeys
+                let master_key = match master_keys {
+                    MasterKeys::Open { master_key } => master_key,
+                    _ => panic!("Committee mode requires Open master key configuration"),
+                };
+                let pop = create_proof_of_possession(master_key, &pop_message);
+
+                info!(
+                    "Committee mode: KeyServer {} with party_id={} for POP with MASTER_KEY",
+                    key_server_oid, partial_key_server_info.party_id
+                );
+
+                // Use KeyServer object ID as the key since PartialKeyServer is stored inline
+                let mut map = HashMap::new();
+                map.insert(key_server_oid, pop);
+                map
+            }
+            ServerMode::Permissioned { client_configs } => client_configs
+                .iter()
+                .filter(|c| {
+                    matches!(
+                        c.client_master_key,
+                        ClientKeyType::Derived { .. } | ClientKeyType::Imported { .. }
+                    )
+                })
+                .map(|c| {
+                    let key = master_keys
+                        .get_key_for_key_server(&c.key_server_object_id)
+                        .expect("checked already");
+                    let pop = create_proof_of_possession(key, &c.key_server_object_id.into_bytes());
+                    (c.key_server_object_id, pop)
+                })
+                .collect(),
+        }
+    }
+
     #[allow(clippy::too_many_arguments)]
     async fn check_signature(
         &self,