@obelyzk/sdk

TypeScript SDK for ObelyZK -- verifiable ML inference on Starknet.

Prove any supported model and get an on-chain verification receipt in a single call. All proofs use full OODS + Merkle + FRI + PoW (trustless) verification.

Installation

npm install @obelyzk/sdk

Quick Start

import { createProverClient } from "@obelyzk/sdk";

const client = createProverClient();

// Prove a model and verify on-chain
const result = await client.prove({
  model: "smollm2-135m",
  input: [1.0, 2.0, 3.0],
  onChain: true,
});

console.log("Output:", result.output);
console.log("Proof hash:", result.proofHash);
console.log("TX hash:", result.txHash);
console.log("Verified:", result.verified);

API Reference

createProverClient(options?)

Create a prover client instance.

const client = createProverClient({
  url: "https://api.bitsage.network",  // default; or your own GPU prover
  apiKey: "your-api-key",           // optional, for rate limiting
  timeout: 300_000,                 // request timeout in ms (default: 5 min)
});

client.prove(request)

Prove an ML model execution and optionally verify on-chain.

const result = await client.prove({
  model: "smollm2-135m",        // model name or HuggingFace ID
  input: [1.0, 2.0, 3.0],      // input tensor (flat array)
  onChain: true,                 // submit to Starknet (default: false)
  recursive: true,               // use recursive STARK (default: true)
  network: "sepolia",            // Starknet network (default: "sepolia")
});

// result: {
//   output: number[],           // model output tensor
//   proofHash: string,          // Poseidon hash of the proof
//   txHash?: string,            // Starknet TX hash (if onChain: true)
//   verified?: boolean,         // on-chain verification status
//   proveTime: number,          // proving time in seconds (~102s for SmolLM2)
//   recursiveTime: number,      // recursive STARK time (~3.55s)
//   felts: number,              // calldata size in felts (~942)
//   modelId: string,            // hex model identifier
// }

client.attest(request)

Prove and submit a full attestation with streaming verification.

const attestation = await client.attest({
  model: "smollm2-135m",
  input: [1.0, 2.0, 3.0],
  submitOnChain: true,
});

client.getModels()

List all available models on the prover.

const models = await client.getModels();
// [{ name: "smollm2-135m", params: "135M", layers: 30, ... }, ...]

client.getJob(jobId)

Check the status of an async proving job.

const job = await client.getJob("job-abc123");
// { status: "completed", progress: 100, result: { ... } }

Async Jobs

For large models, proving runs asynchronously:

const { jobId } = await client.prove({
  model: "phi-3-mini",
  input: data,
  async: true,
});

// Poll for completion
let job;
do {
  await new Promise(r => setTimeout(r, 5000));
  job = await client.getJob(jobId);
  console.log(`Progress: ${job.progress}%`);
} while (job.status === "running");

console.log("Result:", job.result);

Supported Models

| Model | Params | Prove Time (GPU) | Recursive Felts | |-------|--------|-------------------|-----------------| | SmolLM2-135M | 135M | ~102s | 942 | | Qwen2-0.5B | 500M | ~45s | ~900 | | Phi-3-mini | 3.8B | ~180s | ~950 |

On-Chain Verification

When onChain: true, the SDK submits the proof to the ObelyZK Recursive Verifier contract on Starknet Sepolia. Verification uses full OODS + Merkle + FRI + PoW (trustless).

• Contract: 0x1c208a5fe731c0d03b098b524f274c537587ea1d43d903838cc4a2bf90c40c7
• Method: verify_recursive(model_id, io_commitment, stark_proof_data)
• Verification: Full OODS + Merkle + FRI + PoW (trustless)
• Felts: ~942 per proof (49x compression)
• Cost: ~$0.02 per verification on Sepolia

You can verify independently:

import { RpcProvider } from "starknet";

const provider = new RpcProvider({
  nodeUrl: "https://starknet-sepolia.g.alchemy.com/starknet/version/rpc/v0_8/demo",
});

const result = await provider.callContract({
  contractAddress: "0x1c208a5fe731c0d03b098b524f274c537587ea1d43d903838cc4a2bf90c40c7",
  entrypoint: "get_recursive_verification_count",
  calldata: [modelId],
});

console.log("Verification count:", result[0]);

Environment Variables

| Variable | Description | Required | |----------|-------------|----------| | OBELYSK_API_KEY | API key for hosted prover | For hosted | | OBELYSK_PROVER_URL | Custom prover URL | For self-hosted | | STARKNET_ACCOUNT | Starknet account address | For on-chain | | STARKNET_PRIVATE_KEY | Starknet private key | For on-chain |

Self-Hosted Prover

Point the SDK at your own GPU prover instead of the hosted service:

const client = createProverClient({
  url: "http://your-gpu-server:8080",
});

See the Self-Hosting Guide for setup instructions.

Links

• GitHub
• npm
• Getting Started
• On-Chain Docs