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/sdkPackage 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
| Field | Type | Required | Description |
|---|---|---|---|
apiUrl | string | Yes | Base URL of the Tova REST API (trailing slashes stripped) |
fetch | typeof fetch | No | Custom fetch implementation (defaults to globalThis.fetch) |
headers | Record<string, string> | No | Default headers attached to every API and pay402 request |
Properties
tova.api(TovaApiClient): Typed REST client from@tova/contractexposinghealth(),protocolStats(),vaults(),vault(),buildCreateVault(),buildDepositShielded(),buildWithdrawShielded(),mandates(),mandate(),buildIssueMandate(),buildRevokeMandate(),providers(),provider(),buildRegisterProvider(),buildUpdateAttestation(),settlements(),settlement(),buildOpenSettlement(),buildClaimSettlement(),buildRefundSettlement(),submitTransaction(),transactionStatus(),demoInfer(), andeventsUrl().
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
| Field | Type | Required | Description |
|---|---|---|---|
agent | string | Yes | Delegated agent public key |
vault | string | Yes | Parent RingVault PDA address |
mandate | string | Yes | Active Mandate PDA address |
method | string | No | HTTP method (default "POST") |
body | unknown | No | JSON-serializable request body |
headers | Record<string, string> | No | Extra per-request HTTP headers |
Pay402Result<T>
| Field | Type | Description |
|---|---|---|
status | number | Final HTTP status code |
data | T | Parsed JSON response body |
settlementId | string | Settled u64 escrow ID (empty string if endpoint did not return 402) |
quote | object | { provider, priceLamports, requestHash, deadlineSlot, attestationPubkey, hardwareType } |
teeVerified | boolean | true 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
| Field | Type | Description | ||
|---|---|---|---|---|
provider | string | Provider's ProviderRegistry PDA address | ||
providerName | string | Display name included in X-Tova-Quote | ||
mint | string | Settlement asset mint address | ||
mintSymbol | string | Asset symbol (e.g. "SOL", "USDC") | ||
priceLamports | string | Base-unit price per call | ||
hardwareType | `"IntelTDX" \ | "AmdSevSnp" \ | "LocalAttested"` | Hardware attestation type |
attestationKeypair | Keypair | Ed25519 keypair matching ProviderRegistry.attestation_pubkey | ||
endpoint | string | Endpoint 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:
| Export | Signature | Description | ||||||
|---|---|---|---|---|---|---|---|---|
GROTH16_PROOF_BYTES | 192 | Byte 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 }) => Buffer | Builds the 192-byte proof envelope verified by open_settlement | ||||||
buildTeeReceiptMessage | (params: { settlementId: bigint, requestHash: Uint8Array, responseHash: Uint8Array, slot: bigint }) => Buffer | Builds the 99-byte TOVA_TEE_RECEIPT_V1 payload | ||||||
signTeeReceipt | (keypair: Keypair, message: Uint8Array) => Buffer | Signs the receipt message with an Ed25519 keypair (64 bytes) | ||||||
verifyTeeReceipt | (pubkey: PublicKey, message: Uint8Array, signature: Uint8Array) => boolean | Verifies a 64-byte Ed25519 signature against pubkey | ||||||
encryptViewingPayload | (viewingKeyHex32: string, payload: Record<string, unknown>) => string | AES-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) => T | Decrypts AES-256-GCM viewing payloads (and base64 JSON fixture receipts) |