Concepts

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.

text
SettlementEscrow PDA: ["settlement", mandate_pubkey, settlement_id_u64_le]

Five-step settlement loop

  1. 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 with HTTP 402 Payment Required and an X-Tova-Quote JSON header containing provider, priceLamports, requestHash, deadlineSlot, hardwareType, and attestationPubkey.
  2. 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 unique NullifierRecord PDA, creates SettlementEscrow in status Open, and increments provider.active_unsettled_lamports.
  3. Paid retry (`X-Tova-Settlement`): The agent retries the same HTTP request with X-Tova-Settlement: <settlementId> (or the escrow PDA address).
  4. 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 Ed25519 attestation_pubkey, and submits a Solana transaction containing Solana's Ed25519SigVerify precompile instruction followed by claim_settlement.
  5. Delivery (`HTTP 200`): Once claim_settlement succeeds, the program transfers amount - fee to the provider, routes fee to ProtocolConfig.fee_recipient, releases provider.active_unsettled_lamports, marks the escrow Claimed, and the provider returns HTTP 200 with the payload and X-Tova-Receipt.

HTTP headers

HeaderDirectionFormat
X-Tova-QuoteProvider to Agent (HTTP 402)JSON object with provider, providerName, mint, mintSymbol, priceLamports, requestHash, deadlineSlot, hardwareType, attestationPubkey, endpoint
X-Tova-SettlementAgent to Provider (retry)Settlement ID (u64 decimal string) or SettlementEscrow PDA address
X-Tova-ReceiptProvider to Agent (HTTP 200)64-byte hex-encoded Ed25519 signature over the receipt message

Escrow state machine

StatusEnum byteTransitions fromCondition
Open0Initial stateCreated by open_settlement with deadline_slot > clock.slot
Claimed1Openclaim_settlement verifies Ed25519 TEE receipt while clock.slot <= deadline_slot
Refunded2Openrefund_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):

text
fee             = floor((amount * fee_bps) / 10_000)
provider_payout = amount - fee

Rounding 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 Open to Refunded.
  • provider.active_unsettled_lamports decreases by escrow.locked_amount.
  • mandate.epoch_spent decreases by escrow.locked_amount if the mandate is still in escrow.epoch_index.
  • Vault funds remain in vault_escrow (they are only debited on claim_settlement).

Calling refund_settlement before deadline_slot fails with SettlementNotExpired.