KMS

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

phala-cloud v0.2.0 models KMS resources by contract. A KMS contract groups equivalent KMS node replicas that share one root key.

Every example works with both PhalaCloud and AsyncPhalaCloud. Add await when you use the async client.

list_kms_contracts

GET /kms

list_kms_contracts() -> ListKmsContractsResponse

Parameters: None.

Returns: ListKmsContractsResponse, a paginated list of KmsContract objects.

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

Sync

contracts = client.list_kms_contracts()
for contract in contracts.items:
    print(contract.slug, contract.chain_id, contract.node_count)

contracts = await client.list_kms_contracts()
for contract in contracts.items:
    print(contract.slug, contract.chain_id, contract.node_count)

Each KmsContract 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.

get_kms_contract

GET /kms/{slug}

get_kms_contract(slug: str) -> KmsContract

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

Returns: KmsContract for the resolved contract.

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

Sync

contract = client.get_kms_contract("base")
print(contract.contract_address)
print(contract.k256_pubkey, contract.ca_pubkey)

contract = await client.get_kms_contract("base")
print(contract.contract_address)
print(contract.k256_pubkey, contract.ca_pubkey)

list_kms_contract_nodes

GET /kms/{slug}/nodes

list_kms_contract_nodes(slug: str) -> ListKmsContractNodesResponse

Parameters: 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.

Sync

nodes = client.list_kms_contract_nodes("base")
for node in nodes.items:
    print(node.slug, node.url, node.version)

nodes = await client.list_kms_contract_nodes("base")
for node in nodes.items:
    print(node.slug, node.url, node.version)

Legacy node methods

get_kms_list(
    request: GetKmsListRequest | Mapping[str, Any] | None = None,
) -> GetKmsListResponse
get_kms_info(request: KmsInfoRequest | Mapping[str, Any]) -> KmsInfo

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

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

Use list_kms_contracts(), get_kms_contract(), and list_kms_contract_nodes() for new code.

get_app_env_encrypt_pub_key

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

get_app_env_encrypt_pub_key(
    request: KmsPubkeyRequest | Mapping[str, Any],
) -> AppEnvPubkeyResponse

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

Returns: AppEnvPubkeyResponse with public_key and signature.

Returns the public key used to encrypt environment variables for an app.

Sync

key = client.get_app_env_encrypt_pub_key({
    "kms": "phala",
    "app_id": "ff22c67f5d3b4c8a9e1f0a2b3c4d5e6f7a8b9c0d",
})
print(key.public_key, key.signature)

key = await client.get_app_env_encrypt_pub_key({
    "kms": "phala",
    "app_id": "ff22c67f5d3b4c8a9e1f0a2b3c4d5e6f7a8b9c0d",
})
print(key.public_key, key.signature)

next_app_ids

GET /kms/phala/next_app_id

next_app_ids(
    request: NextAppIdsRequest | Mapping[str, Any] | None = None,
) -> NextAppIdsResponse

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

Returns: NextAppIdsResponse with the reserved app_id and nonce pairs.

Reserves app IDs from the Phala KMS for deterministic provisioning.

reserved = client.next_app_ids({"counts": 3})
print(reserved.model_dump())

get_kms_on_chain_detail

GET /kms/on-chain/{chain}

get_kms_on_chain_detail(
    request: KmsOnChainDetailRequest | Mapping[str, Any],
) -> GetKmsOnChainDetailResponse

Parameters: 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.

detail = client.get_kms_on_chain_detail({"chain": "base"})
for contract in detail.contracts:
    print(contract.contract_address)
    print(contract.k256_pubkey, contract.ca_pubkey)

Compute and verify mr_config_id

The SDK exports byte-oriented and hex-oriented helpers:

get_mr_config_id(
    compose_hash: bytes,
    app_id: bytes,
    key_provider_type: KeyProviderKind,
    key_provider_id: bytes,
) -> bytes
get_mr_config_id_hex(
    compose_hash_hex: str,
    app_id_hex: str,
    key_provider_type: KeyProviderKind,
    key_provider_id_hex: str = "",
) -> str
get_mr_config_id_v1(compose_hash: bytes) -> bytes
verify_mr_config_id(
    mr_config_id_hex: str,
    compose_hash_hex: str,
    app_id_hex: str,
    key_provider_type: KeyProviderKind,
    key_provider_id_hex: str = "",
) -> bool

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

from phala_cloud import get_mr_config_id_hex, verify_mr_config_id

mr_config_id = get_mr_config_id_hex(
    compose_hash_hex="0x<64-hex-characters>",
    app_id_hex="0xff22c67f5d3b4c8a9e1f0a2b3c4d5e6f7a8b9c0d",
    key_provider_type="kms",
    key_provider_id_hex="0x<kms-key-provider-id>",
)

matches = verify_mr_config_id(
    mr_config_id,
    "0x<64-hex-characters>",
    "0xff22c67f5d3b4c8a9e1f0a2b3c4d5e6f7a8b9c0d",
    "kms",
    "0x<kms-key-provider-id>",
)

Use get_mr_config_id() for byte inputs and get_mr_config_id_v1() for the V1 compose-hash-only format.

Related

• CVM Configuration
• Error Handling