KMS

List KMS contracts, inspect their nodes and verification anchors, and retrieve app encryption keys.

@phala/cloud v0.4.0 models KMS resources by contract. A KMS contract groups equivalent KMS node replicas that share one root key.

listKmsContracts

GET /kms

client.listKmsContracts(
  request?: ListKmsContractsRequest,
): Promise<ListKmsContractsResponse>

Parameters: page, page_size, and is_onchain are optional filters in request.

Returns: ListKmsContractsResponse, a paginated list of KmsContractInfo objects.

Returns the available KMS contracts. This method always requests API version 2026-06-23.

const contracts = await client.listKmsContracts({
  page: 1,
  page_size: 20,
  is_onchain: true,
});

for (const contract of contracts.items) {
  console.log(contract.slug, contract.chain_id, contract.node_count);
}

Each KmsContractInfo includes the contract id, slug, contract_address, chain_id, node_count, k256_pubkey, and ca_pubkey. For the off-chain Phala KMS, contract_address is "phala" and chain_id is 0.

getKmsContract

GET /kms/{slug}

client.getKmsContract(
  request: GetKmsContractRequest,
): Promise<KmsContractInfo>

Parameters: request.slug accepts a contract slug or kc_-prefixed contract ID.

Returns: KmsContractInfo for the resolved contract.

Returns one KMS contract by slug. A kc_-prefixed contract ID also resolves.

const contract = await client.getKmsContract({ slug: "base" });
console.log(contract.contract_address);
console.log(contract.k256_pubkey, contract.ca_pubkey);

Use the public keys as verification anchors when you validate KMS responses.

listKmsContractNodes

GET /kms/{slug}/nodes

client.listKmsContractNodes(
  request: ListKmsContractNodesRequest,
): Promise<ListKmsContractNodesResponse>

Parameters: request.slug accepts a contract slug or kc_-prefixed contract ID.

Returns: ListKmsContractNodesResponse with the contract’s node replicas.

Returns the KMS node replicas under a contract, including each node’s RPC URL and version.

const nodes = await client.listKmsContractNodes({ slug: "base" });

for (const node of nodes.items) {
  console.log(node.slug, node.url, node.version);
}

Legacy node methods

client.getKmsList(request?: GetKmsListRequest): Promise<GetKmsListResponse>
client.getKmsInfo(request: GetKmsInfoRequest): Promise<KmsInfo>

getKmsList() accepts optional pagination and is_onchain filters. getKmsInfo() requires request.kms_id. They return the earlier node-centric KMS shapes.

Both methods are deprecated and remain pinned to API version 2026-05-22.

Use listKmsContracts(), getKmsContract(), and listKmsContractNodes() for new code.

getAppEnvEncryptPubKey

GET /kms/{kms}/pubkey/{appId}

client.getAppEnvEncryptPubKey(
  request: GetAppEnvEncryptPubKeyRequest,
): Promise<GetAppEnvEncryptPubKey>

Parameters: request.kms is a KMS node ID or slug, and request.app_id is a 20-byte app ID with or without the 0x prefix.

Returns: GetAppEnvEncryptPubKey with public_key and signature.

Returns the public key used to encrypt environment variables for an app. Fetch and verify this key before encrypting secrets.

const key = await client.getAppEnvEncryptPubKey({
  kms: "phala",
  app_id: "ff22c67f5d3b4c8a9e1f0a2b3c4d5e6f7a8b9c0d",
});

console.log(key.public_key, key.signature);

nextAppIds

GET /kms/phala/next_app_id

client.nextAppIds(request?: NextAppIdsRequest): Promise<NextAppIds>

Parameters: request.counts requests 1 to 20 IDs and defaults to 1.

Returns: NextAppIds with the reserved app_id and nonce pairs.

Reserves app IDs from the Phala KMS for deterministic provisioning.

const reserved = await client.nextAppIds({ counts: 3 });
console.log(reserved.app_ids);

getKmsOnChainDetail

GET /kms/on-chain/{chain}

client.getKmsOnChainDetail(
  request: GetKmsOnChainDetailRequest,
): Promise<GetKmsOnChainDetailResponse>

Parameters: request.chain is the chain name, such as "base" or "ethereum".

Returns: GetKmsOnChainDetailResponse with the chain and its KMS contracts.

Returns the contracts, registered devices, OS images, and verification anchors for an on-chain KMS.

const detail = await client.getKmsOnChainDetail({ chain: "base" });

for (const contract of detail.contracts) {
  console.log(contract.contract_address);
  console.log(contract.k256_pubkey, contract.ca_pubkey);
}

Compute and verify mr_config_id

Import the measurement helpers from @phala/cloud:

getMrConfigId(input: MrConfigIdInput): Hex
getMrConfigIdV1(composeHash: Hex): Hex
verifyMrConfigId(mrConfigId: Hex, input: MrConfigIdInput): boolean

For key_provider_type: "kms", set key_provider_id to the contract’s k256_pubkey, not its ca_pubkey.

import { getMrConfigId, verifyMrConfigId } from "@phala/cloud";

const input = {
  compose_hash: "0x<64-hex-characters>",
  app_id: "0xff22c67f5d3b4c8a9e1f0a2b3c4d5e6f7a8b9c0d",
  key_provider_type: "kms" as const,
  key_provider_id: "0x<kms-key-provider-id>",
};

const mrConfigId = getMrConfigId(input);
const matches = verifyMrConfigId(mrConfigId, input);

getMrConfigIdV1(composeHash) remains available for the V1 compose-hash-only format.

Related

• API Versioning
• CVM Configuration
• Error Handling