Atomic HTTP 402
How Tova binds shielded payment release to TEE-attested execution receipts over HTTP 402, with protocol fee routing and slot-based timeout refunds.
The non-atomic 402 problem
Standard HTTP 402 payment flows ask the caller to pay first and hope the server returns a valid response, or ask the server to run compute first and hope the caller pays. Tova makes HTTP 402 settlement atomic through an on-chain SettlementEscrow PDA that releases funds to the provider if and only if the provider submits a valid hardware-attested Execution Receipt before deadline_slot.
SettlementEscrow PDA: ["settlement", mandate_pubkey, settlement_id_u64_le]Five-step settlement loop
- Quote (`HTTP 402`): The agent sends a normal HTTP request to a Tova-gated endpoint without a payment header. The provider hashes the request (
TOVA_402_REQ_V1 || METHOD || PATH || BODY) and replies withHTTP 402 Payment Requiredand anX-Tova-QuoteJSON header containingprovider,priceLamports,requestHash,deadlineSlot,hardwareType, andattestationPubkey. - Escrow lock (`open_settlement`): The agent generates the 192-byte Groth16 budget-compliance proof and submits
open_settlement. The program verifies mandate status, expiry, per-call cap, epoch budget, provider capacity, vault balance, and proof validity, initializes a uniqueNullifierRecordPDA, createsSettlementEscrowin statusOpen, and incrementsprovider.active_unsettled_lamports. - Paid retry (`X-Tova-Settlement`): The agent retries the same HTTP request with
X-Tova-Settlement: <settlementId>(or the escrow PDA address). - TEE execution and claim (`claim_settlement`): The provider runs the workload inside its attested TEE, computes
response_hash = SHA256("TOVA_402_RES_V1" || request_hash || output), signs the receipt message with its registered Ed25519attestation_pubkey, and submits a Solana transaction containing Solana'sEd25519SigVerifyprecompile instruction followed byclaim_settlement. - Delivery (`HTTP 200`): Once
claim_settlementsucceeds, the program transfersamount - feeto the provider, routesfeetoProtocolConfig.fee_recipient, releasesprovider.active_unsettled_lamports, marks the escrowClaimed, and the provider returnsHTTP 200with the payload andX-Tova-Receipt.
HTTP headers
| Header | Direction | Format |
|---|---|---|
X-Tova-Quote | Provider to Agent (HTTP 402) | JSON object with provider, providerName, mint, mintSymbol, priceLamports, requestHash, deadlineSlot, hardwareType, attestationPubkey, endpoint |
X-Tova-Settlement | Agent to Provider (retry) | Settlement ID (u64 decimal string) or SettlementEscrow PDA address |
X-Tova-Receipt | Provider to Agent (HTTP 200) | 64-byte hex-encoded Ed25519 signature over the receipt message |
Escrow state machine
| Status | Enum byte | Transitions from | Condition |
|---|---|---|---|
Open | 0 | Initial state | Created by open_settlement with deadline_slot > clock.slot |
Claimed | 1 | Open | claim_settlement verifies Ed25519 TEE receipt while clock.slot <= deadline_slot |
Refunded | 2 | Open | refund_settlement runs after clock.slot > deadline_slot |
Claimed and Refunded are terminal states. Attempting to claim or refund a non-open escrow fails with SettlementNotOpen.
Protocol fee routing
On every claim_settlement, tova_core computes the protocol fee share from ProtocolConfig.fee_bps (default 25, maximum 1000):
fee = floor((amount * fee_bps) / 10_000)
provider_payout = amount - feeRounding favors the provider (fee rounds down). The program transfers provider_payout to provider_signer and fee to ProtocolConfig.fee_recipient (CMR92vY5iHC1o6pVCrpSpK1qrye4yQdWPkp4fukeUrbC) in the same instruction. For TOVA token supply and buyback-and-burn details, see Protocol.
Timeout refund path
If the provider goes offline, fails to execute, or misses deadline_slot, any signer (principal, agent, or keeper) can call refund_settlement once clock.slot > escrow.deadline_slot:
- Escrow status changes from
OpentoRefunded. provider.active_unsettled_lamportsdecreases byescrow.locked_amount.mandate.epoch_spentdecreases byescrow.locked_amountif the mandate is still inescrow.epoch_index.- Vault funds remain in
vault_escrow(they are only debited onclaim_settlement).
Calling refund_settlement before deadline_slot fails with SettlementNotExpired.