VCL TypeScript SDK

A drop-in replacement for OpenAI and Anthropic clients that generates cryptographically signed receipts for every AI inference request.

Installation

npm install vcl-sdk
# or
yarn add vcl-sdk
# or
pnpm add vcl-sdk

Quick Start

import { VCLClient } from 'vcl-sdk';

const client = new VCLClient({
  apiKey: 'vcl_your_api_key',
  baseUrl: 'https://your-vcl-server.com'
});

// OpenAI-compatible usage
const response = await client.chat.completions.create({
  model: 'gpt-4',
  messages: [{ role: 'user', content: 'Hello!' }]
});

console.log(response.choices[0].message.content);

// Get the receipt for this request
const receipt = await client.getLastReceipt();
console.log('Receipt ID:', receipt?.receipt_id);
console.log('Input tokens:', receipt?.execution.input.token_count);
console.log('Output tokens:', receipt?.execution.output.token_count);
console.log('Compute units:', receipt?.execution.compute_units);

Anthropic-Compatible Usage

import { VCLClient } from 'vcl-sdk';

const client = new VCLClient({
  apiKey: 'vcl_your_api_key',
  baseUrl: 'https://your-vcl-server.com'
});

const response = await client.messages.create({
  model: 'claude-3-sonnet-20240229',
  messages: [{ role: 'user', content: 'Hello!' }],
  max_tokens: 1024
});

console.log(response.content[0].text);

Streaming

// OpenAI streaming
for await (const chunk of client.chat.completions.create({
  model: 'gpt-4',
  messages: [{ role: 'user', content: 'Tell me a story' }],
  stream: true
})) {
  const content = chunk.choices?.[0]?.delta?.content;
  if (content) process.stdout.write(content);
}

// Anthropic streaming
for await (const chunk of client.messages.create({
  model: 'claude-3-sonnet-20240229',
  messages: [{ role: 'user', content: 'Tell me a story' }],
  max_tokens: 1024,
  stream: true
})) {
  if (chunk.type === 'content_block_delta') {
    process.stdout.write(chunk.delta.text);
  }
}

Receipt Verification

import { VCLClient, ReceiptNotFoundError } from 'vcl-sdk';

const client = new VCLClient({
  apiKey: 'vcl_...',
  baseUrl: 'https://...'
});

// Make a request
await client.chat.completions.create({
  model: 'gpt-4',
  messages: [{ role: 'user', content: 'Hello!' }]
});

// Verify the receipt
const receiptId = client.getLastReceiptId();
if (receiptId) {
  try {
    const result = await client.verifyReceipt(receiptId);
    console.log('Valid:', result.valid);
    console.log('Model:', result.model);
    console.log('Timestamp:', result.timestamp);
  } catch (e) {
    if (e instanceof ReceiptNotFoundError) {
      console.log('Receipt not found');
    }
  }
}

Receipt Details

const receipt = await client.getLastReceipt();

if (receipt) {
  // Basic info
  console.log('Receipt ID:', receipt.receipt_id);
  console.log('Timestamp:', receipt.timestamp);
  console.log('Provider:', receipt.provider.name);

  // Execution details
  console.log('Model:', receipt.execution.model_name);
  console.log('Input tokens:', receipt.execution.input.token_count);
  console.log('Output tokens:', receipt.execution.output.token_count);
  console.log('Compute units:', receipt.execution.compute_units);

  // Verification
  console.log('Receipt hash:', receipt.verification.receipt_hash);
  console.log('Signature:', receipt.verification.signature);

  // On-chain anchor (if available)
  if (receipt.verification.anchor?.tx_hash) {
    const anchor = receipt.verification.anchor;
    console.log('Chain:', anchor.chain);
    console.log('TX Hash:', anchor.tx_hash);
    console.log('Block:', anchor.block_num);
    console.log('Merkle Root:', anchor.merkle_root);
  }

  // TEE attestation (if available)
  if (receipt.tee_attestation?.type) {
    const tee = receipt.tee_attestation;
    console.log('TEE Type:', tee.type);
    console.log('MR Enclave:', tee.mr_enclave);
  }
}

API Key Management

// List your API keys
const { keys } = await client.listApiKeys();
for (const key of keys) {
  console.log(`${key.name}: ${key.key_prefix}...`);
}

// Create a new key
const newKey = await client.createApiKey('Production');
console.log('New key:', newKey.key); // Save this!

// Delete a key
await client.deleteApiKey('key-id-here');

Usage Statistics

const stats = await client.getStats();
console.log('Total receipts:', stats.total_receipts);
console.log('Total compute units:', stats.total_compute_units);

Error Handling

import {
  VCLClient,
  VCLError,
  AuthenticationError,
  RateLimitError
} from 'vcl-sdk';

const client = new VCLClient({
  apiKey: 'vcl_...',
  baseUrl: 'https://...'
});

try {
  const response = await client.chat.completions.create({
    model: 'gpt-4',
    messages: [{ role: 'user', content: 'Hello!' }]
  });
} catch (e) {
  if (e instanceof AuthenticationError) {
    console.log('Invalid API key');
  } else if (e instanceof RateLimitError) {
    console.log('Rate limit exceeded, try again later');
  } else if (e instanceof VCLError) {
    console.log(`Error: ${e.message} (status: ${e.statusCode})`);
  }
}

TypeScript Types

The SDK exports all types for TypeScript users:

import type {
  VCLClientOptions,
  Message,
  ChatCompletionRequest,
  AnthropicMessageRequest,
  Receipt,
  Anchor,
  TEEAttestation,
  Verification,
  Execution,
  VerificationResult,
  Stats,
  APIKey,
  Health
} from 'vcl-sdk';

License

MIT