Phala Cloud Documentation — Private AI on TEE

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 a compose hash

GetComposeHash normalizes an AppCompose before hashing by default. Pass false as the second argument to hash the typed compose without normalization. This default differs from older SDK behavior. AppCompose models only a subset of fields. For a complete decoded document, use GetComposeHashFromMap; it normalizes a copy without changing the input. Decode JSON with json.Decoder.UseNumber to preserve numeric values. DumpAppComposeFromMap returns the normalized canonical JSON used for hashing. These two hash manifest_version and init_script as given. To get the hash Phala Cloud computes for a CVM, use GetComposeHashFromMapForOSImage (or DumpAppComposeFromMapForOSImage) with the CVM’s OS image version, for example "0.6.0": below 0.6.0 the compose carries manifest_version 2 and a single init_script string, from 0.6.0 manifest_version “3” and a list.

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.

​ListKMSContracts

​GetKMSContract

​ListKMSContractNodes

​Legacy node methods

​GetAppEnvEncryptPubKey

​NextAppIDs

​GetKMSOnChainDetail

​Compute a compose hash

​Compute and verify mr_config_id

​Related