Guides

Register a TEE Provider

Stake provider capacity on-chain, register your hardware attestation key, rotate keys, and gate any HTTP endpoint with gate402().

Prerequisites

  • A provider Solana wallet (providerPubkey) holding enough SOL for your chosen Capacity Stake (stakeLamports) and account rent.
  • An Ed25519 hardware attestation keypair (attestationKeypair) running inside Intel TDX (IntelTDX), AMD SEV-SNP (AmdSevSnp), or a localnet enclave (LocalAttested).

Step 1: Register on ProviderRegistry

Web console

  1. Open Providers and connect the provider wallet.
  2. Enter your provider name, HTTPS endpoint URL, attestation public key, hardware type (IntelTDX, AmdSevSnp, or LocalAttested), attestation expiry slot, capacity stake in lamports, and default price per call.
  3. Click Register provider and sign the transaction. register_provider transfers stakeLamports into the provider_stake PDA and activates your ProviderRegistry PDA.

TypeScript SDK

ts
import { TovaClient } from '@tova/sdk'

const tova = new TovaClient({ apiUrl: 'http://127.0.0.1:37402' })

const built = await tova.api.buildRegisterProvider({
  providerPubkey: process.env.PROVIDER_PUBKEY!,
  name: 'Atlas TDX Inference',
  endpointUrl: 'https://infer.example.com/v1/complete',
  attestationPubkey: process.env.ATTESTATION_PUBKEY!,
  hardwareType: 'IntelTDX',
  attestationExpirySlot: 350_000_000,
  stakeLamports: '2000000000',       // 2 SOL concurrent capacity ceiling
  pricePerCallLamports: '50000000',  // 0.05 SOL per call
})

console.log('ProviderRegistry PDA:', built.targetAddress)

Sign built.transactionBase64 with providerPubkey and submit via tova.api.submitTransaction.

Step 2: Gate your HTTP handler with gate402()

Wrap your workload handler with gate402(handler, pricing) from @tova/sdk. When a request arrives without X-Tova-Settlement, gate402() returns HTTP 402 with X-Tova-Quote. When X-Tova-Settlement is present, it executes the handler, computes responseHash, signs the 99-byte TOVA_TEE_RECEIPT_V1 message with attestationKeypair, and returns HTTP 200 with X-Tova-Receipt.

ts
import { Keypair } from '@solana/web3.js'
import { gate402 } from '@tova/sdk'

const attestationKeypair = Keypair.fromSecretKey(
  Uint8Array.from(JSON.parse(process.env.ATTESTATION_KEYPAIR_JSON!)),
)

const gatedInfer = gate402(
  async (req) => {
    const parsed = JSON.parse(req.body) as { prompt: string }
    const output = await runInferenceInTee(parsed.prompt)
    return {
      output,
      payload: { model: 'tova-tee-llama-3-8b' },
    }
  },
  {
    provider: process.env.PROVIDER_PDA!,
    providerName: 'Atlas TDX Inference',
    mint: 'So11111111111111111111111111111111111111112',
    mintSymbol: 'SOL',
    priceLamports: '50000000',
    hardwareType: 'IntelTDX',
    attestationKeypair,
    endpoint: '/v1/complete',
    getCurrentSlot: async () => connection.getSlot('confirmed'),
  },
)

Call gatedInfer({ method, path, body, settlementId: req.headers['x-tova-settlement'] }) from your HTTP framework (Hono, Express, Fastify, or Node http) and forward the returned status, headers, and body.

Step 3: Claim the settlement on-chain

After signing the receipt, submit claim_settlement before deadlineSlot:

ts
const claimBuilt = await tova.api.buildClaimSettlement(settlementPda, {
  providerPubkey: process.env.PROVIDER_PUBKEY!,
  responseHash: res.body.responseHash,
  attestationSignature: res.body.attestationSignature,
  slot: res.body.slot,
  amountLamports: '50000000',
})

The API automatically prepends Solana's Ed25519SigVerify precompile instruction before claim_settlement in the returned v0 transaction. Sign with providerPubkey and submit. On confirmation:

  • amount - floor(amount * fee_bps / 10_000) transfers to providerPubkey.
  • floor(amount * fee_bps / 10_000) routes to ProtocolConfig.fee_recipient.
  • provider.active_unsettled_lamports decreases by amount, freeing capacity for new calls.

Step 4: Rotate an attestation key

Before attestationExpirySlot is reached, rotate your TEE key or extend its expiry without unstaking:

ts
const rotateBuilt = await tova.api.buildUpdateAttestation(providerPda, {
  providerPubkey: process.env.PROVIDER_PUBKEY!,
  attestationPubkey: nextAttestationPubkey,
  hardwareType: 'IntelTDX',
  attestationExpirySlot: 400_000_000,
})

Common failures

ErrorCauseFix
InvalidHardwareTypehardware_type outside 0..=2Use IntelTDX, AmdSevSnp, or LocalAttested
AttestationExpiredclock.slot > attestation_expiry_slotCall update_provider_attestation with a future slot
InvalidAttestationMissing or mismatched Ed25519SigVerify precompile instructionBuild via /v1/settlements/:settlement/claim/build or prepend Ed25519Program.createInstructionWithPublicKey with the exact TOVA_TEE_RECEIPT_V1 message
SettlementExpiredclock.slot > escrow.deadline_slotClaim before the quote's deadlineSlot (slot + 150 by default in gate402)