[key-server] handle committee config and rotation mode

Author: joyqvq

.gitignore

@@ -80,7 +80,7 @@ checkpoints_dir/*
 light_client.yaml
 docs/content/references/sui-api/sui-graphql/*
 docs/content/references/framework/**
-
+*.example
 lcov.info
 
 **/build/**

Cargo.lock

@@ -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

@@ -6,8 +6,7 @@
 # network: Devnet
 # 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. 
+#   use_default_mainnet_for_mvr: true # Optional, default to true if not present, 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,10 +18,12 @@ 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:
+#   1) Open: Supports all policy packages. 
+#   2) Permissioned: Supports only allowed policy packages. 
+#   3) Committee: Supports all packages. Requires DKG setup for master key share.
 #
+# #### OPEN MODE ####
 # For the Open mode, set the registered key server object ID to be used, e.g.,:
 # server_mode: !Open
 #   key_server_object_id: '0x0000000000000000000000000000000000000000000000000000000000000000'
@@ -31,7 +32,7 @@ network: Testnet
 server_mode: !Open
   key_server_object_id: '0x0000000000000000000000000000000000000000000000000000000000000000'
 
-#
+# #### PERMISSIONED MODE ####
 # For the Permissioned mode, set the allowed clients and their configurations.
 # A client config contains:
 # - Client name - for debugging purposes only, can always be modified.
@@ -75,6 +76,26 @@ server_mode: !Open
 #       package_ids:
 #         - "0x3333333333333333333333333333333333333333333333333333333333333333"
 
+# #### COMMITTEE MODE ####
+# See step 7 in the member runbook for fresh DKG and key rotation in details. 
+# - For active mode, only MASTER_SHARE is set, the key_serverion_version in config is expected to 
+#   be the same as the version onchain in Committee V2 key server.
+# - For key rotation, both MASTER_SHARE and NEXT_MASTER_SHARE are set, the key_server_version in 
+#   config is expected to be exactly 1 greater than the version onchain. The MASTER_SHARE is used to
+#   serve traffic, and when onchain version is updated to the same as the config version, the 
+#   NEXT_MASTER_SHARE will be used to serve traffic.
+#
+# Example for a fresh DKG (MASTER_SHARE is set as environment variable):
+# server_mode: !Committee
+#   member_address: '<MY_ADDRESS>'
+#   key_server_obj_id: '<KEY_SERVER_OBJ_ID>'
+#   key_server_version: 0
+# 
+# Example for key rotation (both MASTER_SHARE and NEXT_MASTER_SHARE are set in environment variables):
+# server_mode: !Committee
+#   member_address: '<MY_ADDRESS>'
+#   key_server_obj_id: '<KEY_SERVER_OBJ_ID>'
+#   key_server_version: <KEY_SERVER_VERSION>
 
 #### 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,6 +48,14 @@ pub enum ServerMode {
         // Master key is expected to by 32 byte HKDF seed
         client_configs: Vec<ClientConfig>,
     },
+    Committee {
+        member_address: Address,
+        key_server_obj_id: Address,
+        /// The target key server version set during rotation. During rotation, this can be exactly
+        /// 1 greater than the onchain version. Onchain rotation is completed, the onchain version
+        /// matches this version, NEXT_MASTER_SHARE will be used.
+        target_key_server_version: u32,
+    },
 }
 
 /// Configuration for the RPC client.
@@ -255,26 +264,6 @@ impl KeyServerOptions {
         }
         Ok(())
     }
-
-    pub(crate) fn get_supported_key_server_object_ids(&self) -> Vec<ObjectID> {
-        match &self.server_mode {
-            ServerMode::Open {
-                key_server_object_id,
-            } => {
-                vec![*key_server_object_id]
-            }
-            ServerMode::Permissioned { client_configs } => client_configs
-                .iter()
-                .filter(|c| {
-                    matches!(
-                        c.client_master_key,
-                        ClientKeyType::Derived { .. } | ClientKeyType::Imported { .. }
-                    )
-                })
-                .map(|c| c.key_server_object_id)
-                .collect(),
-        }
-    }
 }
 
 fn default_checkpoint_update_interval() -> Duration {
@@ -378,9 +367,17 @@ server_mode: !Open
     }
 }
 
-#[test]
-fn test_parse_permissioned_config() {
+#[tokio::test]
+async fn test_parse_permissioned_config() {
+    use crate::master_keys::MasterKeys;
+    use crate::types::IbeMasterKey;
+    use crate::DefaultEncoding;
+    use crate::Server;
+    use fastcrypto::encoding::Encoding;
+    use fastcrypto::groups::GroupElement;
+    use seal_committee::create_grpc_client;
     use std::str::FromStr;
+    use temp_env::async_with_vars;
 
     let valid_configuration = r#"
 network: Mainnet
@@ -416,19 +413,37 @@ session_key_ttl_max: '60s'
     let options: KeyServerOptions =
         serde_yaml::from_str(valid_configuration).expect("Failed to parse valid configuration");
 
-    assert_eq!(
-        options.get_supported_key_server_object_ids(),
-        vec![
-            ObjectID::from_str(
-                "0xaaaa000000000000000000000000000000000000000000000000000000000001"
-            )
-            .unwrap(),
-            ObjectID::from_str(
-                "0xbbbb000000000000000000000000000000000000000000000000000000000002"
-            )
-            .unwrap(),
-        ]
-    );
+    let seed_encoded = DefaultEncoding::encode([1u8; 32]);
+    let bob_key = IbeMasterKey::generator();
+    let bob_key_encoded = DefaultEncoding::encode(bcs::to_bytes(&bob_key).unwrap());
+
+    async_with_vars(
+        [
+            ("MASTER_KEY", Some(&seed_encoded)),
+            ("BOB_BLS_KEY", Some(&bob_key_encoded)),
+        ],
+        async {
+            let master_keys = MasterKeys::load(&options).expect("Failed to load master keys");
+            let grpc_client = create_grpc_client(&seal_committee::Network::Testnet).unwrap();
+            let map = Server::build_key_server_pop_map(&options, &master_keys, grpc_client)
+                .await
+                .unwrap();
+            assert_eq!(map.keys().len(), 2);
+            assert!(map.contains_key(
+                &ObjectID::from_str(
+                    "0xaaaa000000000000000000000000000000000000000000000000000000000001"
+                )
+                .unwrap()
+            ));
+            assert!(map.contains_key(
+                &ObjectID::from_str(
+                    "0xbbbb000000000000000000000000000000000000000000000000000000000002"
+                )
+                .unwrap()
+            ));
+        },
+    )
+    .await;
 }
 
 #[test]
@@ -569,3 +584,72 @@ server_mode: !Permissioned
         assert_eq!(result.unwrap_err().to_string(), expected_error);
     }
 }
+
+#[test]
+fn test_committee_mode_master_keys() {
+    use crate::master_keys::MasterKeys;
+    use crate::types::IbeMasterKey;
+    use crate::DefaultEncoding;
+    use fastcrypto::encoding::Encoding;
+    use fastcrypto::groups::GroupElement;
+    use temp_env::with_vars;
+
+    // master_share with version 0 (fresh DKG), no next_master_share expected.
+    let config_fresh_dkg = r#"
+network: Mainnet
+server_mode: !Committee
+  member_address: '0x0000000000000000000000000000000000000000000000000000000000000000'
+  key_server_obj_id: '0x0000000000000000000000000000000000000000000000000000000000000001'
+  target_key_server_version: 0
+"#;
+    let options: KeyServerOptions =
+        serde_yaml::from_str(config_fresh_dkg).expect("Failed to parse configuration");
+
+    let master_share = IbeMasterKey::generator();
+    let master_share_encoded = DefaultEncoding::encode(bcs::to_bytes(&master_share).unwrap());
+
+    with_vars([("MASTER_SHARE", Some(&master_share_encoded))], || {
+        assert!(MasterKeys::load(&options).is_ok());
+    });
+
+    // master_share and next_master_share with version > 0 (rotation), both shares expected.
+    let config_rotation = r#"
+network: Mainnet
+server_mode: !Committee
+  member_address: '0x0000000000000000000000000000000000000000000000000000000000000000'
+  key_server_obj_id: '0x0000000000000000000000000000000000000000000000000000000000000001'
+  target_key_server_version: 1
+"#;
+    let options_rotation: KeyServerOptions =
+        serde_yaml::from_str(config_rotation).expect("Failed to parse configuration");
+
+    let next_master_share = IbeMasterKey::generator();
+    let next_master_share_encoded =
+        DefaultEncoding::encode(bcs::to_bytes(&next_master_share).unwrap());
+
+    with_vars(
+        [
+            ("MASTER_SHARE", Some(&master_share_encoded)),
+            ("NEXT_MASTER_SHARE", Some(&next_master_share_encoded)),
+        ],
+        || {
+            assert!(MasterKeys::load(&options_rotation).is_ok());
+        },
+    );
+
+    // next_master_share present but version is 0 (fresh DKG), should fail.
+    with_vars(
+        [
+            ("MASTER_SHARE", Some(&master_share_encoded)),
+            ("NEXT_MASTER_SHARE", Some(&next_master_share_encoded)),
+        ],
+        || {
+            assert!(MasterKeys::load(&options).is_err());
+        },
+    );
+
+    // next_master_share absent but version > 0 (rotation complete), should succeed.
+    with_vars([("MASTER_SHARE", Some(&master_share_encoded))], || {
+        assert!(MasterKeys::load(&options_rotation).is_ok());
+    });
+}