Reference

@tova/sdk

Complete TypeScript reference for @tova/sdk: TovaClient, pay402(), gate402(), cryptographic commitment/proof helpers, and viewing-key encryption.

Installation

bash
npm install @tova/sdk

Package name: @tova/sdk (0.1.0, ESM). Re-exports createClient, CONTRACT_VERSION, and errors from @tova/contract.

TovaClient

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

const tova = new TovaClient({
  apiUrl: 'http://127.0.0.1:37402',
  headers: { Authorization: 'Bearer <optional-siws-token>' },
})

TovaClientConfig

FieldTypeRequiredDescription
apiUrlstringYesBase URL of the Tova REST API (trailing slashes stripped)
fetchtypeof fetchNoCustom fetch implementation (defaults to globalThis.fetch)
headersRecord<string, string>NoDefault headers attached to every API and pay402 request

Properties

  • tova.api (TovaApiClient): Typed REST client from @tova/contract exposing health(), protocolStats(), vaults(), vault(), buildCreateVault(), buildDepositShielded(), buildWithdrawShielded(), mandates(), mandate(), buildIssueMandate(), buildRevokeMandate(), providers(), provider(), buildRegisterProvider(), buildUpdateAttestation(), settlements(), settlement(), buildOpenSettlement(), buildClaimSettlement(), buildRefundSettlement(), submitTransaction(), transactionStatus(), demoInfer(), and eventsUrl().

tova.pay402<T>(url, options)

Executes a shielded HTTP 402 request end-to-end: fetches the 402 quote, opens the settlement escrow via tova.api.buildOpenSettlement(), retries with X-Tova-Settlement, and verifies the returned Ed25519 TEE receipt.

Pay402Options

FieldTypeRequiredDescription
agentstringYesDelegated agent public key
vaultstringYesParent RingVault PDA address
mandatestringYesActive Mandate PDA address
methodstringNoHTTP method (default "POST")
bodyunknownNoJSON-serializable request body
headersRecord<string, string>NoExtra per-request HTTP headers

Pay402Result<T>

FieldTypeDescription
statusnumberFinal HTTP status code
dataTParsed JSON response body
settlementIdstringSettled u64 escrow ID (empty string if endpoint did not return 402)
quoteobject{ provider, priceLamports, requestHash, deadlineSlot, attestationPubkey, hardwareType }
teeVerifiedbooleantrue when verifyTeeReceipt passes on the returned receipt fields

gate402(handler, pricing)

Wraps a provider workload handler to enforce Tova HTTP 402 payment quotes and sign Ed25519 TEE execution receipts.

ts
import { gate402, type Gate402Pricing } from '@tova/sdk'

Signature

ts
function gate402<
  Req extends { method: string; path: string; body: string; settlementId?: string },
  Res,
>(
  handler: (req: Req) => Promise<{ output: string; payload: Res }>,
  pricing: Gate402Pricing,
): (req: Req) => Promise<
  | { status: 402; headers: { 'X-Tova-Quote': string }; body: { error: { code: 'PAYMENT_REQUIRED'; message: string } } }
  | { status: 200; headers: { 'X-Tova-Receipt': string }; body: Res & { output: string; settlementId: string; requestHash: string; responseHash: string; slot: number; attestationSignature: string; attestationPubkey: string; hardwareType: string } }
>

Gate402Pricing

FieldTypeDescription
providerstringProvider's ProviderRegistry PDA address
providerNamestringDisplay name included in X-Tova-Quote
mintstringSettlement asset mint address
mintSymbolstringAsset symbol (e.g. "SOL", "USDC")
priceLamportsstringBase-unit price per call
hardwareType`"IntelTDX" \"AmdSevSnp" \"LocalAttested"`Hardware attestation type
attestationKeypairKeypairEd25519 keypair matching ProviderRegistry.attestation_pubkey
endpointstringEndpoint path included in the quote
getCurrentSlot() => Promise<number>Returns current Solana slot (deadlineSlot defaults to slot + 150)

Cryptographic and proof helpers

Exported directly from @tova/sdk:

ExportSignatureDescription
GROTH16_PROOF_BYTES192Byte length of the Groth16 proof envelope
computeAmountCommitment(amountLamports: bigint, salt32: Uint8Array) => Buffer`SHA256("TOVA_PRIVACY_RING_V1" \\amount_le \\salt32)`
computeNullifier(noteCommitment32: Uint8Array, agentKey32: Uint8Array, settlementId: bigint) => Buffer`SHA256("TOVA_NULLIFIER_V1" \\noteCommitment32 \\agentKey32 \\settlementId_le)`
computeRequestHash(method: string, path: string, body: string) => Buffer`SHA256("TOVA_402_REQ_V1" \\METHOD \\path \\body)`
computeResponseHash(requestHash32: Uint8Array, output: string) => Buffer`SHA256("TOVA_402_RES_V1" \\requestHash32 \\output)`
generateGroth16Proof(params: { merkleRoot, amountCommitment, nullifierHash, mandatePubkey, perCallCapCommitment, epochBudgetCommitment, amountLamports }) => BufferBuilds the 192-byte proof envelope verified by open_settlement
buildTeeReceiptMessage(params: { settlementId: bigint, requestHash: Uint8Array, responseHash: Uint8Array, slot: bigint }) => BufferBuilds the 99-byte TOVA_TEE_RECEIPT_V1 payload
signTeeReceipt(keypair: Keypair, message: Uint8Array) => BufferSigns the receipt message with an Ed25519 keypair (64 bytes)
verifyTeeReceipt(pubkey: PublicKey, message: Uint8Array, signature: Uint8Array) => booleanVerifies a 64-byte Ed25519 signature against pubkey
encryptViewingPayload(viewingKeyHex32: string, payload: Record<string, unknown>) => stringAES-256-GCM encrypts JSON payload under `SHA256("TOVA_VIEWING_KEY_AES_V1" \\key) and returns base64 iv \\tag \\ciphertext`
decryptViewingPayload<T>(viewingKeyHex32: string, ciphertextBase64: string) => TDecrypts AES-256-GCM viewing payloads (and base64 JSON fixture receipts)