feat: add kms_contract_id to CVM SDK schemas, deprecate kms_id

cli/src/commands/deploy/handler.test.ts

@@ -117,7 +117,8 @@ describe("buildProvisionPayload", () => {
 			expect(payload.teepod_id).toBe(123);
 			expect(payload.region).toBe("us-west");
 			expect(payload.image).toBe("dstack-dev-0.5.0");
-			expect(payload.kms_id).toBe("phala");
+			// --kms-id is deprecated and now a no-op; it is no longer sent.
+			expect(payload.kms_id).toBeUndefined();
 			expect(payload.prefer_dev).toBe(true);
 		});
 
@@ -217,7 +218,7 @@ describe("buildProvisionPayload", () => {
 			expect(payload.kms).toBe("BASE");
 		});
 
-		test("should include deprecatedKmsId when provided via preResolvedKmsSelection", () => {
+		test("ignores deprecatedKmsId (kms_id is a no-op) but keeps kms type", () => {
 			const options = {};
 
 			const payload = buildProvisionPayload(
@@ -230,7 +231,8 @@ describe("buildProvisionPayload", () => {
 			);
 
 			expect(payload.kms).toBe("PHALA");
-			expect(payload.kms_id).toBe("custom-kms");
+			// --kms-id is deprecated and now a no-op; it is no longer sent.
+			expect(payload.kms_id).toBeUndefined();
 		});
 
 		test("should include CVM resource matching v2 fields when specified", () => {

cli/src/commands/deploy/handler.ts

@@ -690,10 +690,10 @@ export const buildProvisionPayload = (
 
 	// Always set kms type (defaults to PHALA)
 	payload.kms = kmsType;
-	// Keep kms_id for backward compatibility if provided
-	if (deprecatedKmsId) {
-		payload.kms_id = deprecatedKmsId;
-	}
+	// `--kms-id` is deprecated and now a no-op: the backend identifies the KMS
+	// by its on-chain contract (kms_contract_id), not a single node id. The flag
+	// is retained for one more release to avoid breaking existing invocations.
+	void deprecatedKmsId;
 	if (options.kmsContract) {
 		payload.kms_contract = options.kmsContract;
 	}

go/types_cvms.go

@@ -245,8 +245,11 @@ type ProvisionCVMResponse struct {
 	OSImageHash           string      `json:"os_image_hash,omitempty"`
 	InstanceType          string      `json:"instance_type,omitempty"`
 	NodeID                *int        `json:"node_id,omitempty"`
-	KMSID                 string      `json:"kms_id,omitempty"`
-	ComposeHashRegistered bool        `json:"compose_hash_registered,omitempty"`
+	// Deprecated: KMSID identifies a KMS node, not the on-chain KMS contract.
+	// Use KMSContractID instead.
+	KMSID                 string `json:"kms_id,omitempty"`
+	KMSContractID         string `json:"kms_contract_id,omitempty"`
+	ComposeHashRegistered bool   `json:"compose_hash_registered,omitempty"`
 }
 
 // CommitCVMProvisionRequest is the request for committing a CVM provision.

js/src/actions/cvms/commit_cvm_provision.ts

@@ -202,7 +202,9 @@ export const CommitCvmProvisionRequestSchema = z
     encrypted_env: z.string().optional().nullable(),
     app_id: z.string(),
     compose_hash: z.string(),
+    /** @deprecated Identifies a KMS node, not the on-chain KMS contract. Use kms_contract_id. */
     kms_id: z.string().optional(),
+    kms_contract_id: z.union([z.string(), z.number()]).optional(),
     contract_address: z.string().optional(),
     deployer_address: z.string().optional(),
     env_keys: z.array(z.string()).optional().nullable(),

js/src/actions/cvms/provision_cvm.ts

@@ -172,7 +172,9 @@ export const ProvisionCvmSchema = z
     instance_type: z.string().nullable().optional(),
     teepod_id: z.number().nullable().optional(), // Will be transformed to node_id
     node_id: z.number().nullable().optional(),
+    /** @deprecated Identifies a KMS node, not the on-chain KMS contract. Use kms_contract_id. */
     kms_id: z.string().nullable().optional(),
+    kms_contract_id: z.union([z.string(), z.number()]).nullable().optional(),
   })
   .passthrough()
   .transform((data) => {

js/src/types/app_info_v20251028.ts

@@ -17,7 +17,9 @@ export const CvmBasicInfoV20251028Schema = z.object({
   listed: z.boolean().nullable().optional(),
   base_image: z.string().nullable().optional(),
   kms_slug: z.string().nullable().optional(),
+  /** @deprecated Identifies a KMS node, not the on-chain KMS contract. Use kms_contract_id. */
   kms_id: z.string().nullable().optional(),
+  kms_contract_id: z.string().nullable().optional(),
   instance_id: z.string().nullable().optional(),
   machine_info: MachineInfoV20251028Schema.nullable().optional(),
   updated_at: z.string().nullable().optional(),

python/src/phala_cloud/action_responses.py

@@ -50,7 +50,10 @@ class ProvisionCvmResponse(CloudModel):
     os_image_hash: str | None = None
     instance_type: str | None = None
     node_id: int | None = None
+    # Deprecated: identifies a KMS node, not the on-chain KMS contract.
+    # Use kms_contract_id instead.
     kms_id: str | None = None
+    kms_contract_id: str | None = None
 
 
 class ProvisionCvmComposeFileUpdateResult(CloudModel):