SDK Guide

ObscuraProof SDKs provide native integration for major programming languages. Our client libraries handle the complexity of cryptographic operations, network communication, and error handling, allowing developers to focus on building applications.

Each SDK offers identical functionality with language-idiomatic interfaces. Whether you're building in JavaScript, Python, Java, or Go, the SDK abstracts away the complexities of zero-knowledge proofs while providing full access to platform capabilities. Installation takes minutes through standard package managers, and comprehensive examples help you generate your first proof within an hour of starting integration.

Installation and Setup

Getting started with ObscuraProof SDKs requires only your API key and the appropriate package manager for your language. All SDKs support both synchronous and asynchronous operations, with built-in retry logic and connection pooling for optimal performance.

npm install @obscuraproof/sdk
# or
yarn add @obscuraproof/sdk

import { ObscuraProof } from '@obscuraproof/sdk';

const client = new ObscuraProof({
  apiKey: process.env.OBSCURA_API_KEY,
  environment: 'production', // or 'sandbox'
  timeout: 30000, // 30 seconds
  maxRetries: 3
});

pip install obscuraproof

from obscuraproof import Client
import os

client = Client(
    api_key=os.environ['OBSCURA_API_KEY'],
    environment='production',
    timeout=30,
    max_retries=3
)

<dependency>
  <groupId>com.obscuraproof</groupId>
  <artifactId>obscuraproof-sdk</artifactId>
  <version>1.5.0</version>
</dependency>

import com.obscuraproof.Client;
import com.obscuraproof.Config;

Config config = new Config.Builder()
    .apiKey(System.getenv("OBSCURA_API_KEY"))
    .environment(Environment.PRODUCTION)
    .timeout(30000)
    .build();

Client client = new Client(config);

go get github.com/obscuraproof/go-sdk

package main

import (
    "github.com/obscuraproof/go-sdk"
    "os"
)

func main() {
    client := obscuraproof.NewClient(
        obscuraproof.WithAPIKey(os.Getenv("OBSCURA_API_KEY")),
        obscuraproof.WithEnvironment("production"),
        obscuraproof.WithTimeout(30),
    )
}

Core Operations

Data Commitment

The first step in zero-knowledge verification is converting raw data into cryptographic commitments. The SDK handles the mathematical operations required for commitment generation while ensuring data never leaves your control in plaintext.

// Create commitments from sensor data
const commitments = await client.commitments.create({
  dataSource: 'energy-sensors',
  values: [
    { timestamp: '2025-09-10T10:00:00Z', metric: 'kwh', value: 1250.5 },
    { timestamp: '2025-09-10T11:00:00Z', metric: 'kwh', value: 1180.3 }
  ],
  aggregation: 'hourly'
});

// Store commitment IDs for later proof generation
const commitmentIds = commitments.map(c => c.id);

Commitments are immutable once created, ensuring data integrity throughout the verification process. The SDK automatically handles batching for large datasets, optimizing network usage and reducing latency.

Proof Generation

Proof generation transforms commitments into zero-knowledge proofs that verify specific claims without revealing underlying data. The SDK provides both simple and advanced interfaces for proof generation.

// Simple proof generation
const proof = await client.proofs.create({
  circuit: 'carbon_reduction',
  commitments: commitmentIds,
  claims: {
    metric: 'emissions_reduction',
    threshold: 0.25,
    period: '2025-Q3'
  }
});

// Advanced proof with custom circuit
const customProof = await client.proofs.createCustom({
  circuitCode: customCircuitDefinition,
  inputs: {
    private: commitments,
    public: ['25', '2025-Q3']
  },
  provingKey: await client.circuits.getProvingKey('custom_circuit_v1')
});

The SDK caches proving keys locally after first use, significantly improving performance for repeated proof generation.

Verification

Verification confirms the validity of proofs without accessing underlying data. The SDK provides methods for both local and remote verification.

// Remote verification (recommended)
const result = await client.proofs.verify({
  proofId: proof.id,
  expectedClaims: {
    metric: 'emissions_reduction',
    minimum: 0.20
  }
});

// Local verification (requires verification key)
const localResult = await client.proofs.verifyLocal({
  proof: proof.data,
  verificationKey: proof.verificationKey,
  publicInputs: proof.publicInputs
});

console.log(`Proof is ${result.valid ? 'valid' : 'invalid'}`);

Advanced Features

Stream Processing

For real-time data sources, the SDK supports stream processing that generates commitments and proofs as data arrives.

// Create a stream processor
const stream = client.streams.create({
  source: 'iot-mqtt',
  broker: 'mqtt://sensors.local',
  topics: ['energy/+', 'emissions/+']
});

// Process incoming data
stream.on('data', async (reading) => {
  const commitment = await client.commitments.createSingle(reading);
  console.log(`Committed reading: ${commitment.id}`);
});

// Generate periodic proofs
stream.on('interval', async (period) => {
  const proof = await client.proofs.createFromStream({
    streamId: stream.id,
    period: period,
    claims: { reduction: 0.25 }
  });
});

Circuit Development

The SDK includes tools for developing and testing custom zero-knowledge circuits for specialized verification requirements.

// Define custom circuit
const circuit = client.circuits.define({
  name: 'custom_verification',
  inputs: {
    private: ['value1', 'value2', 'value3'],
    public: ['threshold']
  },
  constraints: `
    signal output result;
    result <== (value1 + value2 + value3) / 3;
    component gt = GreaterThan();
    gt.in[0] <== result;
    gt.in[1] <== threshold;
    gt.out === 1;
  `
});

// Compile and test circuit
const compiled = await circuit.compile();
const testResult = await circuit.test({
  private: [100, 120, 110],
  public: [100]
});

Error Handling

The SDK provides comprehensive error handling with typed exceptions and automatic retry logic for transient failures.

try {
  const proof = await client.proofs.create({
    circuit: 'carbon_reduction',
    commitments: commitmentIds
  });
} catch (error) {
  if (error instanceof InsufficientDataError) {
    console.log(`Need more data: ${error.details.required}`);
  } else if (error instanceof CircuitError) {
    console.log(`Circuit execution failed: ${error.message}`);
  } else if (error instanceof NetworkError) {
    console.log(`Network issue: ${error.message}`);
    // **SDK** automatically retries network errors
  }
}

Performance Optimization

The SDK includes several features to optimize performance in production environments. Connection pooling maintains persistent connections to ObscuraProof servers. Request batching combines multiple operations into single network calls. Caching stores frequently used data locally to reduce latency.

// Enable performance monitoring
client.monitoring.enable({
  metrics: ['latency', 'throughput', 'errors'],
  interval: 60000 // Report every minute
});

// Batch operations for efficiency
const batchResult = await client.batch([
  client.commitments.create({ /* ... */ }),
  client.proofs.create({ /* ... */ }),
  client.proofs.verify({ /* ... */ })
]);

Migration and Upgrades

The SDK maintains backward compatibility while adding new features. Migration guides accompany major version updates, and deprecation warnings provide advance notice of breaking changes.

// Check SDK version and available features
console.log(`SDK Version: ${client.version}`);
console.log(`API Version: ${client.apiVersion}`);

// Enable compatibility mode for legacy systems
client.compatibility.enable('v1');

The SDK ecosystem continues to evolve with community contributions welcome through our open-source repositories. Whether building simple proof-of-concept applications or production systems processing millions of proofs, ObscuraProof SDKs provide the foundation for privacy-preserving verification.

On this page