Client API Reference

Complete reference for the ZKVAULT TypeScript SDK client API.

ZKVault Class

The main entry point for interacting with ZKVAULT:

import { ZKVault } from '@zkvault/sdk'

const zkvault = new ZKVault({
  connection: Connection,      // Solana web3 connection
  wallet: Wallet,              // Wallet adapter or Keypair
  cluster?: 'devnet' | 'mainnet-beta',  // Default: 'devnet'
  programId?: PublicKey,       // Override program ID
})

Properties

• zkvault.prover - Proof generation interface
• zkvault.solana - On-chain interaction interface
• zkvault.vault - Vault management interface
• zkvault.circuit - Circuit builder utilities

createProof()

Generate a zero-knowledge proof for a circuit:

async function createProof(
  circuit: Circuit,
  inputs: CircuitInputs,
  options?: ProofOptions
): Promise<Proof>

// Example
const circuit = new Circuit()
  .addPublicInput('balance')
  .addPrivateInput('secret')
  .assertGreaterThan('balance', 1000)

const proof = await zkvault.prover.createProof(
  circuit,
  {
    public: { balance: 5000 },
    private: { secret: 'my_secret_key' }
  },
  {
    compress: true,        // Enable compression (default: true)
    cache: true,           // Cache proving key (default: true)
    timeout: 30000         // Timeout in ms (default: 30000)
  }
)

// Returns
interface Proof {
  bytes: Uint8Array      // Compressed proof bytes
  publicInputs: bigint[] // Public inputs
  circuitId: string      // Circuit identifier
  metadata: {
    generatedAt: number
    compressionRatio: number
  }
}

verifyOnchain()

Submit and verify a proof on Solana:

async function verifyOnchain(
  proof: Proof,
  vault?: PublicKey
): Promise<TransactionSignature>

// Example
const signature = await zkvault.solana.verifyOnchain(proof)

// Wait for confirmation
await zkvault.connection.confirmTransaction(signature)

// Check verification result
const verified = await zkvault.vault.isProofVerified(signature)
console.log('Proof verified:', verified)

encryptVaultData()

Encrypt data for storage in a vault:

async function encryptVaultData(
  data: Uint8Array | string,
  recipientPublicKey: PublicKey,
  options?: EncryptOptions
): Promise<EncryptedPayload>

// Example
const encrypted = await zkvault.vault.encryptVaultData(
  JSON.stringify({ secret: 'sensitive_data' }),
  recipientPubkey,
  {
    algorithm: 'chacha20-poly1305',  // Default
    forwardSecrecy: true              // Enable ephemeral keys
  }
)

// Returns
interface EncryptedPayload {
  ciphertext: Uint8Array
  nonce: Uint8Array
  ephemeralPublicKey?: Uint8Array
  mac: Uint8Array
}

decryptVaultData()

Decrypt data from a vault:

async function decryptVaultData(
  encrypted: EncryptedPayload,
  privateKey: Uint8Array
): Promise<Uint8Array>

// Example
const decrypted = await zkvault.vault.decryptVaultData(
  encrypted,
  wallet.secretKey
)

const data = JSON.parse(Buffer.from(decrypted).toString())
console.log('Decrypted:', data)

buildCircuit()

High-level circuit builder API:

function buildCircuit(builder: (circuit: CircuitBuilder) => void): Circuit

// Example
const circuit = zkvault.circuit.buildCircuit((c) => {
  // Public inputs (visible on-chain)
  const commitment = c.publicInput('commitment')
  const threshold = c.publicInput('threshold')
  
  // Private inputs (hidden)
  const value = c.privateInput('value')
  const salt = c.privateInput('salt')
  
  // Constraints
  c.assertEqual(
    commitment,
    c.hash([value, salt])
  )
  
  c.assertGreaterThan(value, threshold)
})

// Compiled circuit ready for proving

Advanced Options

Batching Multiple Proofs

// Generate multiple proofs
const proofs = await Promise.all([
  zkvault.prover.createProof(circuit1, inputs1),
  zkvault.prover.createProof(circuit2, inputs2),
  zkvault.prover.createProof(circuit3, inputs3),
])

// Batch verify on-chain (saves gas)
const tx = await zkvault.solana.batchVerify(proofs)

// One transaction verifies all proofs with aggregation

Custom Verification Keys

// Load custom VK from file
const vk = await zkvault.circuit.loadVerificationKey('./my_circuit.vk.json')

// Create vault with custom VK
const vault = await zkvault.vault.create({
  owner: wallet.publicKey,
  verificationKey: vk
})

// Proofs for this circuit can only be verified at this vault

Event Listeners

// Listen for proof verification events
zkvault.on('proofVerified', (event) => {
  console.log('Proof verified:', event.signature)
  console.log('Vault:', event.vault.toString())
  console.log('Submitter:', event.submitter.toString())
})

// Listen for errors
zkvault.on('error', (error) => {
  console.error('ZKVAULT error:', error)
})

Error Handling

try {
  const proof = await zkvault.prover.createProof(circuit, inputs)
  await zkvault.solana.verifyOnchain(proof)
} catch (error) {
  if (error instanceof ZKVaultError) {
    switch (error.code) {
      case 'INVALID_WITNESS':
        console.error('Inputs do not satisfy circuit constraints')
        break
      case 'PROOF_GENERATION_FAILED':
        console.error('Failed to generate proof:', error.message)
        break
      case 'VERIFICATION_FAILED':
        console.error('Proof verification failed on-chain')
        break
      case 'INSUFFICIENT_FUNDS':
        console.error('Not enough SOL for transaction')
        break
      default:
        console.error('Unknown error:', error)
    }
  }
}

Type Definitions

// Core types exported by SDK
export interface CircuitInputs {
  public: Record<string, number | bigint | string>
  private: Record<string, number | bigint | string>
}

export interface ProofOptions {
  compress?: boolean
  cache?: boolean
  timeout?: number
}

export interface EncryptOptions {
  algorithm?: 'chacha20-poly1305' | 'aes-256-gcm'
  forwardSecrecy?: boolean
}

export class ZKVaultError extends Error {
  code: string
  details?: any
}

For circuit building details, see Proof Builder Guide.