KMS

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

The Go SDK v0.2.0 models KMS resources by contract. A KMS contract groups equivalent KMS node replicas that share one root key.

ListKMSContracts

GET /kms

func (c *Client) ListKMSContracts(ctx context.Context) (*ListKMSContractsResponse, error)

Parameters: ctx controls cancellation and request lifetime.

Returns: *ListKMSContractsResponse, a paginated list of KMSContract values, or an error.

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

contracts, err := client.ListKMSContracts(ctx)
if err != nil {
	log.Fatal(err)
}
for _, contract := range contracts.Items {
	fmt.Println(contract.ID, contract.ContractAddress, contract.NodeCount)
}

Each KMSContract includes the contract ID, slug, contract address, chain ID, node count, K256Pubkey, and CAPubkey. For the off-chain Phala KMS, the contract address is "phala" and the chain ID is 0.

GetKMSContract

GET /kms/{slug}

func (c *Client) GetKMSContract(ctx context.Context, slug string) (*KMSContract, error)

Parameters: ctx controls cancellation; slug accepts a contract slug or kc_-prefixed contract ID.

Returns: *KMSContract for the resolved contract, or an error.

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

contract, err := client.GetKMSContract(ctx, "base")
if err != nil {
	log.Fatal(err)
}
fmt.Println(contract.ContractAddress)
fmt.Println(contract.K256Pubkey, contract.CAPubkey)

ListKMSContractNodes

GET /kms/{slug}/nodes

func (c *Client) ListKMSContractNodes(
	ctx context.Context,
	slug string,
) (*ListKMSContractNodesResponse, error)

Parameters: ctx controls cancellation; slug accepts a contract slug or kc_-prefixed contract ID.

Returns: *ListKMSContractNodesResponse with the contract’s node replicas, or an error.

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

nodes, err := client.ListKMSContractNodes(ctx, "base")
if err != nil {
	log.Fatal(err)
}
for _, node := range nodes.Items {
	fmt.Println(node.ID, node.URL, node.Version)
}

Legacy node methods

func (c *Client) GetKMSList(ctx context.Context) (*GetKMSListResponse, error)
func (c *Client) GetKMSInfo(ctx context.Context, kmsID string) (*KMSInfo, error)

GetKMSList takes a request context. GetKMSInfo also requires a KMS node ID or slug. They return the earlier node-centric KMS shapes or an error.

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

Use ListKMSContracts, GetKMSContract, and ListKMSContractNodes for new code.

GetAppEnvEncryptPubKey

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

func (c *Client) GetAppEnvEncryptPubKey(
	ctx context.Context,
	kmsType string,
	appID string,
) (*AppEnvPubKeyResponse, error)

Parameters: ctx controls cancellation, kmsType is a KMS node ID or slug, and appID is the app ID.

Returns: *AppEnvPubKeyResponse containing the public key response, or an error.

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

key, err := client.GetAppEnvEncryptPubKey(
	ctx,
	"phala",
	"ff22c67f5d3b4c8a9e1f0a2b3c4d5e6f7a8b9c0d",
)
if err != nil {
	log.Fatal(err)
}
fmt.Println(key)

NextAppIDs

GET /kms/phala/next_app_id

func (c *Client) NextAppIDs(ctx context.Context) (*NextAppIDsResponse, error)

Parameters: ctx controls cancellation and request lifetime.

Returns: *NextAppIDsResponse with the reserved app IDs, or an error.

Reserves app IDs from the Phala KMS for deterministic provisioning.

reserved, err := client.NextAppIDs(ctx)
if err != nil {
	log.Fatal(err)
}
fmt.Println(reserved)

GetKMSOnChainDetail

GET /kms/on-chain/{chain}

func (c *Client) GetKMSOnChainDetail(
	ctx context.Context,
	chain string,
) (*KMSOnChainDetail, error)

Parameters: ctx controls cancellation; chain is the chain name, such as "base" or "ethereum".

Returns: *KMSOnChainDetail with the chain and its KMS contracts, or an error.

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

detail, err := client.GetKMSOnChainDetail(ctx, "base")
if err != nil {
	log.Fatal(err)
}
for _, contract := range detail.Contracts {
	fmt.Println(contract.ContractAddress)
	fmt.Println(contract.K256Pubkey, contract.CAPubkey)
}

Compute and verify mr_config_id

Use GetMrConfigIdHex when your inputs are hex strings:

func GetMrConfigId(input MrConfigIdInput) ([48]byte, error)
func GetMrConfigIdHex(
	composeHashHex string,
	appIDHex string,
	kp KeyProviderKind,
	kpIDHex string,
) (string, error)
func GetMrConfigIdV1(composeHash [32]byte) [48]byte
func VerifyMrConfigId(
	mrConfigIDHex string,
	composeHashHex string,
	appIDHex string,
	kp KeyProviderKind,
	kpIDHex string,
) (bool, error)

For KeyProviderKMS, set kpIDHex to the contract’s K256Pubkey, not its CAPubkey.

mrConfigID, err := phala.GetMrConfigIdHex(
	"0x<64-hex-characters>",
	"0xff22c67f5d3b4c8a9e1f0a2b3c4d5e6f7a8b9c0d",
	phala.KeyProviderKMS,
	"0x<kms-key-provider-id>",
)
if err != nil {
	log.Fatal(err)
}

matches, err := phala.VerifyMrConfigId(
	mrConfigID,
	"0x<64-hex-characters>",
	"0xff22c67f5d3b4c8a9e1f0a2b3c4d5e6f7a8b9c0d",
	phala.KeyProviderKMS,
	"0x<kms-key-provider-id>",
)
if err != nil {
	log.Fatal(err)
}
fmt.Println(matches)

Use GetMrConfigId for fixed-size byte inputs and GetMrConfigIdV1 for the V1 compose-hash-only format.

Related

• CVM Configuration
• Error Handling