[seal] handle key server v2 with server mode, committee mode goes to aggregator URL

joyqvq · joyqvq · commit f7c1d00e4844 · 2026-01-28T14:02:35.000-05:00
diff --git a/.changeset/dull-baboons-deny.md b/.changeset/dull-baboons-deny.md
@@ -0,0 +1,5 @@
+---
+'@mysten/seal': minor
+---
+
+Handle key server v2 and aggregator for a committee of key servers
diff --git a/packages/seal/src/bcs.ts b/packages/seal/src/bcs.ts
@@ -51,6 +51,45 @@ export const KeyServerMoveV1 = bcs.struct('KeyServerV1', {
 	pk: bcs.byteVector(),
 });
 
+/**
+ * The Move struct for PartialKeyServer.
+ */
+export const PartialKeyServer = bcs.struct('PartialKeyServer', {
+	name: bcs.string(),
+	url: bcs.string(),
+	partialPk: bcs.byteVector(),
+	partyId: bcs.u16(),
+});
+
+/**
+ * The Move enum for ServerType (V2).
+ */
+export const ServerType = bcs.enum('ServerType', {
+	Independent: bcs.struct('Independent', {
+		url: bcs.string(),
+	}),
+	Committee: bcs.struct('Committee', {
+		version: bcs.u32(),
+		threshold: bcs.u16(),
+		partialKeyServers: bcs.vector(
+			bcs.struct('VecMapEntry', {
+				key: bcs.Address,
+				value: PartialKeyServer,
+			}),
+		),
+	}),
+});
+
+/**
+ * The Move struct for the KeyServerV2 object.
+ */
+export const KeyServerMoveV2 = bcs.struct('KeyServerV2', {
+	name: bcs.string(),
+	keyType: bcs.u8(),
+	pk: bcs.byteVector(),
+	serverType: ServerType,
+});
+
 /**
  * The Move struct for the parent object.
  */
diff --git a/packages/seal/src/client.ts b/packages/seal/src/client.ts
@@ -262,6 +262,7 @@ export class SealClient {
 				await retrieveKeyServers({
 					objectIds: missingKeyServers,
 					client: this.#suiClient,
+					configs: this.#configs,
 				})
 			).forEach((keyServer) =>
 				this.#cachedPublicKeys.set(keyServer.objectId, G2Element.fromBytes(keyServer.pk)),
@@ -295,8 +296,9 @@ export class SealClient {
 
 	async #loadKeyServers(): Promise<Map<string, KeyServer>> {
 		const keyServers = await retrieveKeyServers({
-			objectIds: [...this.#configs].map(([objectId]) => objectId),
+			objectIds: [...this.#configs.keys()],
 			client: this.#suiClient,
+			configs: this.#configs,
 		});
 
 		if (keyServers.length === 0) {
@@ -306,6 +308,10 @@ export class SealClient {
 		if (this.#verifyKeyServers) {
 			await Promise.all(
 				keyServers.map(async (server) => {
+					// Skip /service verification for committee key server type since the request goes through an aggregator.
+					if (server.serverType === 'Committee') {
+						return;
+					}
 					const config = this.#configs.get(server.objectId);
 					if (!(await verifyKeyServer(server, this.#timeout, config?.apiKeyName, config?.apiKey))) {
 						throw new InvalidKeyServerError(`Key server ${server.objectId} is not valid`);
diff --git a/packages/seal/src/key-server.ts b/packages/seal/src/key-server.ts
@@ -3,27 +3,35 @@
 import { bcs, fromBase64, fromHex, toBase64, toHex } from '@mysten/bcs';
 import { bls12_381 } from '@noble/curves/bls12-381';
 
-import { KeyServerMove, KeyServerMoveV1 } from './bcs.js';
-import { InvalidKeyServerError, InvalidKeyServerVersionError, SealAPIError } from './error.js';
+import { KeyServerMove, KeyServerMoveV1, KeyServerMoveV2 } from './bcs.js';
+import {
+	InvalidClientOptionsError,
+	InvalidKeyServerError,
+	InvalidKeyServerVersionError,
+	SealAPIError,
+} from './error.js';
 import { DST_POP } from './ibe.js';
 import { PACKAGE_VERSION } from './version.js';
-import type { SealCompatibleClient } from './types.js';
+import type { KeyServerConfig, SealCompatibleClient } from './types.js';
 import type { G1Element } from './bls12381.js';
 import { flatten, Version } from './utils.js';
 import { elgamalDecrypt } from './elgamal.js';
 import type { Certificate } from './session-key.js';
 
-const EXPECTED_SERVER_VERSION = 1;
+const SUPPORTED_SERVER_VERSIONS = [2, 1]; // Must be configured in descending order.
+
+export type ServerType = 'Independent' | 'Committee';
 
 export type KeyServer = {
 	objectId: string;
 	name: string;
 	url: string;
-	keyType: KeyServerType;
+	keyType: KeyType;
 	pk: Uint8Array<ArrayBuffer>;
+	serverType: ServerType;
 };
 
-export enum KeyServerType {
+export enum KeyType {
 	BonehFranklinBLS12381 = 0,
 }
 
@@ -33,16 +41,22 @@ export const SERVER_VERSION_REQUIREMENT = new Version('0.4.1');
  * Given a list of key server object IDs, returns a list of SealKeyServer
  * from onchain state containing name, objectId, URL and pk.
  *
+ * Supports both V1 (independent servers) and V2 (independent + committee servers).
+ * For V2 committee servers, returns the aggregator URL from the config.
+ *
  * @param objectIds - The key server object IDs.
  * @param client - The SuiClient to use.
+ * @param configs - The key server configurations containing aggregator URLs.
  * @returns - An array of SealKeyServer.
  */
 export async function retrieveKeyServers({
 	objectIds,
 	client,
+	configs,
 }: {
 	objectIds: string[];
 	client: SealCompatibleClient;
+	configs: Map<string, KeyServerConfig>;
 }): Promise<KeyServer[]> {
 	return await Promise.all(
 		objectIds.map(async (objectId) => {
@@ -51,39 +65,102 @@ export async function retrieveKeyServers({
 				objectId,
 			});
 			const ks = KeyServerMove.parse(await res.object.content);
-			if (
-				EXPECTED_SERVER_VERSION < Number(ks.firstVersion) ||
-				EXPECTED_SERVER_VERSION > Number(ks.lastVersion)
-			) {
+
+			// Find the highest supported version.
+			const firstVersion = Number(ks.firstVersion);
+			const lastVersion = Number(ks.lastVersion);
+			const version = SUPPORTED_SERVER_VERSIONS.find((v) => v >= firstVersion && v <= lastVersion);
+
+			if (version === undefined) {
 				throw new InvalidKeyServerVersionError(
-					`Key server ${objectId} supports versions between ${ks.firstVersion} and ${ks.lastVersion} (inclusive), but SDK expects version ${EXPECTED_SERVER_VERSION}`,
+					`Key server ${objectId} supports versions between ${ks.firstVersion} and ${ks.lastVersion} (inclusive), but SDK expects one of ${SUPPORTED_SERVER_VERSIONS.join(', ')}`,
 				);
 			}
 
-			// Then fetch the expected versioned object and parse it.
-			const resVersionedKs = await client.core.getDynamicField({
+			// Fetch the versioned object.
+			const versionedKeyServer = await client.core.getDynamicField({
 				parentId: objectId,
 				name: {
 					type: 'u64',
-					bcs: bcs.u64().serialize(EXPECTED_SERVER_VERSION).toBytes(),
+					bcs: bcs.u64().serialize(version).toBytes(),
 				},
 			});
 
-			const ksVersioned = KeyServerMoveV1.parse(resVersionedKs.dynamicField.value.bcs);
+			// Parse based on version.
+			switch (version) {
+				case 2: {
+					const ksV2 = KeyServerMoveV2.parse(versionedKeyServer.dynamicField.value.bcs);
+					if (ksV2.keyType !== KeyType.BonehFranklinBLS12381) {
+						throw new InvalidKeyServerError(
+							`Server ${objectId} has invalid key type: ${ksV2.keyType}`,
+						);
+					}
 
-			if (ksVersioned.keyType !== KeyServerType.BonehFranklinBLS12381) {
-				throw new InvalidKeyServerError(
-					`Server ${objectId} has invalid key type: ${ksVersioned.keyType}`,
-				);
-			}
+					// Return based on server type.
+					switch (ksV2.serverType.$kind) {
+						case 'Independent': {
+							if (configs.get(objectId)?.aggregatorUrl) {
+								throw new InvalidClientOptionsError(
+									`Independent server ${objectId} should not have aggregatorUrl in config`,
+								);
+							}
+							return {
+								objectId,
+								name: ksV2.name,
+								url: ksV2.serverType.Independent.url,
+								keyType: ksV2.keyType,
+								pk: new Uint8Array(ksV2.pk),
+								serverType: 'Independent',
+							};
+						}
+						case 'Committee': {
+							// For committee mode, get aggregator URL from config
+							const config = configs.get(objectId);
+							if (!config?.aggregatorUrl) {
+								throw new InvalidClientOptionsError(
+									`Committee server ${objectId} requires aggregatorUrl in config`,
+								);
+							}
+							return {
+								objectId,
+								name: ksV2.name,
+								url: config.aggregatorUrl,
+								keyType: ksV2.keyType,
+								pk: new Uint8Array(ksV2.pk),
+								serverType: 'Committee',
+							};
+						}
+						default:
+							throw new InvalidKeyServerError(`Unknown server type for ${objectId}`);
+					}
+				}
+				case 1: {
+					const ksV1 = KeyServerMoveV1.parse(versionedKeyServer.dynamicField.value.bcs);
+					if (ksV1.keyType !== KeyType.BonehFranklinBLS12381) {
+						throw new InvalidKeyServerError(
+							`Server ${objectId} has invalid key type: ${ksV1.keyType}`,
+						);
+					}
 
-			return {
-				objectId,
-				name: ksVersioned.name,
-				url: ksVersioned.url,
-				keyType: ksVersioned.keyType,
-				pk: new Uint8Array(ksVersioned.pk),
-			};
+					// V1 servers are always Independent and should not have aggregatorUrl
+					if (configs.get(objectId)?.aggregatorUrl) {
+						throw new InvalidClientOptionsError(
+							`V1 server ${objectId} is always Independent and should not have aggregatorUrl in config`,
+						);
+					}
+
+					return {
+						objectId,
+						name: ksV1.name,
+						url: ksV1.url,
+						keyType: ksV1.keyType,
+						pk: new Uint8Array(ksV1.pk),
+						serverType: 'Independent',
+					};
+				}
+				default:
+					throw new InvalidKeyServerVersionError(`Unsupported key server version: ${version}`);
+			}
 		}),
 	);
 }
diff --git a/packages/seal/src/types.ts b/packages/seal/src/types.ts
@@ -36,6 +36,9 @@ export interface KeyServerConfig {
 	weight: number;
 	apiKeyName?: string;
 	apiKey?: string;
+	/** Must be provided if object ID is for a committee mode server since all fetch key calls go
+	 * through an aggregator. */
+	aggregatorUrl?: string;
 }
 
 export interface SealClientOptions extends SealClientExtensionOptions {
diff --git a/packages/seal/test/unit/aggregator.test.ts b/packages/seal/test/unit/aggregator.test.ts
@@ -0,0 +1,89 @@
+// Copyright (c) Mysten Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+import { fromHex } from '@mysten/bcs';
+import { Ed25519Keypair } from '@mysten/sui/keypairs/ed25519';
+import { Transaction } from '@mysten/sui/transactions';
+import { getFullnodeUrl, SuiClient } from '@mysten/sui/client';
+import { describe, it, expect } from 'vitest';
+
+import { SealClient } from '../../src/client.js';
+import { SessionKey } from '../../src/session-key.js';
+
+/**
+ * Committee Aggregator Integration Tests against ci aggregator.
+ */
+describe('Committee Aggregator Tests', () => {
+	it('encrypt and decrypt through aggregator', { timeout: 12000 }, async () => {
+		// Committee key server object for aggregator ci server, that points to a committee of ci key servers.
+		const COMMITTEE_KEY_SERVER_OBJ_ID =
+			'0xa5d2b47e7c649a3c6f9730967a5514abb8e21f19f908ad78a6ad943970c6ad02';
+		const AGGREGATOR_URL = 'https://seal-aggregator-ci.mystenlabs.com';
+
+		// A v1 independent server in ci.
+		const INDEPENDENT_SERVER_OBJ_ID =
+			'0x71a3962c5d06a94d1ef5a9c0e7d63ad72cefb48acc93001eaa7ba13fab52786e';
+
+		// Testnet package with account_based policy.
+		const PACKAGE_ID = '0x58dce5d91278bceb65d44666ffa225ab397fc3ae9d8398c8c779c5530bd978c2';
+
+		const testKeypair = Ed25519Keypair.generate();
+		const testAddress = testKeypair.getPublicKey().toSuiAddress();
+
+		const testData = crypto.getRandomValues(new Uint8Array(100));
+		const suiClient = new SuiClient({ url: getFullnodeUrl('testnet') });
+
+		// Create Seal client.
+		const client = new SealClient({
+			suiClient,
+			serverConfigs: [
+				{
+					objectId: COMMITTEE_KEY_SERVER_OBJ_ID,
+					weight: 1,
+					aggregatorUrl: AGGREGATOR_URL,
+				},
+				{
+					objectId: INDEPENDENT_SERVER_OBJ_ID,
+					weight: 1,
+				},
+			],
+			verifyKeyServers: false,
+		});
+
+		// Encrypt with policy and 2 servers (1 for committee, 1 for independent).
+		const { encryptedObject: encryptedBytes } = await client.encrypt({
+			threshold: 2,
+			packageId: PACKAGE_ID,
+			id: testAddress,
+			data: testData,
+		});
+
+		// Create session key.
+		const sessionKey = await SessionKey.create({
+			address: testAddress,
+			packageId: PACKAGE_ID,
+			ttlMin: 10,
+			signer: testKeypair,
+			suiClient,
+		});
+
+		// Build transaction.
+		const tx = new Transaction();
+		const keyIdArg = tx.pure.vector('u8', fromHex(testAddress));
+		tx.moveCall({
+			target: `${PACKAGE_ID}::account_based::seal_approve`,
+			arguments: [keyIdArg],
+		});
+		const txBytes = await tx.build({ client: suiClient, onlyTransactionKind: true });
+
+		// Decrypt data through aggregator.
+		const decryptedData = await client.decrypt({
+			data: encryptedBytes,
+			sessionKey,
+			txBytes,
+		});
+
+		// Verify decrypted data matches original.
+		expect(decryptedData).toEqual(testData);
+	});
+});
diff --git a/packages/seal/test/unit/encrypt.test.ts b/packages/seal/test/unit/encrypt.test.ts
diff --git a/packages/seal/test/unit/integration.test.ts b/packages/seal/test/unit/integration.test.ts
diff --git a/packages/seal/test/unit/key-server.test.ts b/packages/seal/test/unit/key-server.test.ts

-Original file line number
+Diff line change
@@ @@ -0,0 +1,5 @@ @@
 +---
 +'@mysten/seal': minor
 +---
++
 +Handle key server v2 and aggregator for a committee of key servers
Original file line number	Diff line number	Diff line change
`@@ -36,6 +36,9 @@ export interface KeyServerConfig {`
`36`	`36`	`weight: number;`
`37`	`37`	`apiKeyName?: string;`
`38`	`38`	`apiKey?: string;`
	`39`	`+ /** Must be provided if object ID is for a committee mode server since all fetch key calls go`
	`40`	`+ * through an aggregator. */`
	`41`	`+ aggregatorUrl?: string;`
`39`	`42`	`}`
`40`	`43`
`41`	`44`	`export interface SealClientOptions extends SealClientExtensionOptions {`