> ## Documentation Index
> Fetch the complete documentation index at: https://docs.phala.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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`

```typescript theme={"system"}
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`.

```typescript theme={"system"}
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}`

```typescript theme={"system"}
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.

```typescript theme={"system"}
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`

```typescript theme={"system"}
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.

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

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

## Legacy node methods

```typescript theme={"system"}
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}`

```typescript theme={"system"}
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.

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

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

## nextAppIds

`GET /kms/phala/next_app_id`

```typescript theme={"system"}
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.

```typescript theme={"system"}
const reserved = await client.nextAppIds({ counts: 3 });
console.log(reserved.app_ids);
```

## getKmsOnChainDetail

`GET /kms/on-chain/{chain}`

```typescript theme={"system"}
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.

```typescript theme={"system"}
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`:

```typescript theme={"system"}
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`.

```typescript theme={"system"}
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](/phala-cloud/references/cloud-js-sdk/api-versioning)
* [CVM Configuration](/phala-cloud/references/cloud-js-sdk/cvm-configuration)
* [Error Handling](/phala-cloud/references/cloud-js-sdk/error-handling)