Skip to main content

​
addComposeHash

Registers a new compose hash on the AppAuth smart contract. This is required when updating a CVM that uses on-chain KMS (ETHEREUM/BASE) — the updated compose hash must be registered on-chain before the Phala Cloud API will accept the update. This function interacts directly with the blockchain (not the Phala Cloud API). When to use: Call this function when updateDockerCompose, updateCvmEnvs, or updatePreLaunchScript returns { status: "precondition_required" }. Parameters:
FieldTypeRequiredDescription
chainChainConditionalViem chain config (required if no walletClient)
kmsContractAddressAddressYesKMS contract address (for lookup)
appIdAddressYesApp identifier (AppAuth contract address)
composeHashstringYesCompose hash to register
privateKeyHexConditionalCaller private key (provide this or walletClient)
walletClientWalletClientConditionalCustom wallet client (provide this or privateKey)
rpcUrlstringNoCustom RPC URL
publicClientPublicClientNoCustom public client
skipPrerequisiteChecksbooleanNoSkip balance checks (default: false)
minBalancestringNoMinimum ETH balance (default: "0.001")
timeoutnumberNoTransaction timeout in ms
retryOptionsobjectNoRetry configuration
Callbacks:
CallbackDescription
onTransactionStateChangeCalled when transaction state changes
onTransactionSubmittedCalled when transaction is submitted
onTransactionConfirmedCalled when transaction is confirmed
Returns: AddComposeHash
FieldTypeDescription
composeHashstringThe registered compose hash
appIdstringApp identifier
appAuthAddressstringAppAuth contract address
transactionHashstringOn-chain transaction hash
blockNumberbigint?Block number
gasUsedbigint?Gas consumed
Example: 
import { addComposeHash } from "@phala/cloud";

// After updateDockerCompose returns precondition_required:
const receipt = await addComposeHash({
  chain: cvmInfo.kms_info.chain,
  kmsContractAddress: cvmInfo.kms_info.kms_contract_address,
  appId: cvmInfo.app_id as `0x${string}`,
  composeHash: preconditionResult.compose_hash,
  privateKey: "0xabc123...",
});

// Now retry the update with the transaction hash
await client.updateDockerCompose({
  id: "my-app",
  docker_compose_file: newYaml,
  compose_hash: preconditionResult.compose_hash,
  transaction_hash: receipt.transactionHash,
});

​
safeAddComposeHash

Safe variant that returns a SafeResult<AddComposeHash> instead of throwing on errors.