Guides

Verifying Confidential Compute Receipts

Verify Ed25519 hardware-attested execution receipts on the client and on-chain, inspect enclave measurements, and refund expired escrows.

Receipt digest format

Every Kalo execution receipt binds three 32-byte values into a single SHA-256 digest:

text
digest = SHA256(escrow_pda_bytes (32B) || request_hash_bytes (32B) || output_hash_bytes (32B))

Both the on-chain kalo_protocol program (settle_with_receipt) and @kalo/sdk (buildReceiptDigest) compute this exact digest. Changing a single byte of the escrow address, request payload, or response payload produces a different digest and invalidates the Ed25519 signature.

Client-side verification with @kalo/sdk

kalo.fetch() verifies the receipt automatically before returning. If you are verifying a receipt manually from a saved settlement record or webhook, use buildReceiptDigest() and verifyTeeReceipt():

ts
import { buildReceiptDigest, sha256Hex, verifyTeeReceipt } from '@kalo/sdk'

const outputHash = sha256Hex(rawResponseString)
const digest = buildReceiptDigest(escrowAddress, requestHash, outputHash)
const valid = verifyTeeReceipt(digest, teeSignatureHex, enclavePubkey)

if (!valid) {
  throw new Error('Confidential Compute Ed25519 receipt verification failed.')
}
FunctionInputsOutput
sha256Hex(input)`string \Buffer \Uint8Array`0x-prefixed 32-byte hex digest
buildReceiptDigest(escrow, reqHash, outHash)Base58 PDA, 0x 32-byte hex, 0x 32-byte hex32-byte Buffer
verifyTeeReceipt(digest, sigHex, enclavePubkey)32-byte Buffer, 0x 64-byte hex, Base58 pubkeyboolean

On-chain verification in settle_with_receipt

When a provider settles a SealedEscrow, the transaction includes a Solana Ed25519SigVerify precompile instruction (Ed25519SigVerify111111111111111111111111111) before settle_with_receipt.

verify_ed25519_precompile in kalo_protocol:

  1. Loads the current instruction index from the Solana Instructions sysvar (Sysvar1nstructions1111111111111111111111111).
  2. Scans all prior instructions (0..current_ix) for an Ed25519 precompile instruction. It does not assume a fixed instruction index, so wallet-inserted ComputeBudget or guard instructions do not break verification.
  3. Checks num_signatures == 1, inline instruction indices (u16::MAX), and msg_size == 32.
  4. Verifies that the inline public key bytes match enclave_registry.enclave_pubkey and the inline message bytes match SHA256(escrow.key() || escrow.request_hash || output_hash).
  5. Rejects the transaction with InvalidTeeReceipt (6016) if no matching instruction is found.

Checking enclave measurement and expiry

Before locking funds into an unfamiliar provider, inspect its EnclaveRegistry record via GET /v1/providers/:address:

  • Confirm active === true.
  • Confirm expiresSlot is well ahead of the current Solana slot.
  • Compare measurementHash against the expected Intel TDX (IntelTDX) or AMD SEV-SNP (AmdSevSnp) image measurement.
  • Optionally run POST /v1/providers/:address/verify-reputation with a minSettledCount threshold to verify its flow witness root.

Handling timeouts and refunds

Every SealedEscrow carries a timeout_slot set at lock time (clock.slot + timeout_slots, where timeout_slots is between 5 and 10,000; default 150 slots in the API).

If a provider fails to submit a valid receipt before timeout_slot passes:

  1. Any caller (the agent, the sponsor, or Kalo's keeper worker) calls refund_expired_escrow (or POST /v1/settlements/:address/refund/build).
  2. The program checks escrow.state == 0 (Locked) and clock.slot > escrow.timeout_slot.
  3. escrow.state transitions to 2 (Refunded), escrow.amount returns to privacy_ring.vault_balance, and reputation_accumulator.disputed_count increments by 1.
ts
const refundRes = await fetch(`http://127.0.0.1:41202/v1/settlements/${escrowAddress}/refund/build`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ caller: agentOrSponsorPubkey }),
})

Calling refund_expired_escrow before timeout_slot reverts with EscrowNotExpired (6015). Calling it on an already settled or refunded escrow reverts with EscrowNotLocked (6014).

Confidential commerce infrastructure for autonomous software.

Shielded treasuries, scoped mandates, and receipt-bound HTTP 402 settlement on Solana L1.

Open consoleRead the docs