Documentation
Getting Started
SDK Quickstart
Get started with Minerva SDKs — JavaScript/TypeScript, Rust, and Python.
Minerva provides official SDKs for JavaScript/TypeScript (npm), Rust (crates.io), and Python (PyPI). All SDKs support both session-cookie and API key authentication.
JavaScript / TypeScript
bash
npm install @digitalforgestudios/minerva-sdktypescript
import { MinervaClient } from '@digitalforgestudios/minerva-sdk';
const client = new MinervaClient({
apiKey: process.env.MINERVA_API_KEY,
baseUrl: 'https://api.zkesg.com',
});
// Generate a proof
const proof = await client.proofs.create({
type: 'carbon_emissions',
inputs: {
scope1: 1240.5,
scope2: 870.2,
threshold: 2500,
},
});
console.log('Proof ID:', proof.id);
console.log('Status:', proof.status);
// Verify a proof
const result = await client.proofs.verify(proof.id);
console.log('Valid:', result.valid);Rust
toml
# Cargo.toml
[dependencies]
minerva-zkesg-sdk = "0.3"
tokio = { version = "1", features = ["full"] }rust
use minerva_zkesg_sdk::{MinervaClient, ProofRequest};
use std::env;
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
let client = MinervaClient::new(
env::var("MINERVA_API_KEY")?,
"https://api.zkesg.com".to_string(),
);
let proof = client
.proofs()
.create(ProofRequest {
proof_type: "carbon_emissions".to_string(),
inputs: serde_json::json!({
"scope1": 1240.5,
"scope2": 870.2,
"threshold": 2500,
}),
webhook_url: None,
})
.await?;
println!("Proof ID: {}", proof.id);
println!("Status: {}", proof.status);
// Verify
let verified = client.proofs().verify(&proof.id).await?;
println!("Valid: {}", verified.valid);
Ok(())
}Python
bash
pip install minerva-zkesgpython
import os
from minerva_zkesg import MinervaClient
client = MinervaClient(
api_key=os.environ["MINERVA_API_KEY"],
base_url="https://api.zkesg.com",
)
# Generate a proof
proof = client.proofs.create(
type="carbon_emissions",
inputs={
"scope1": 1240.5,
"scope2": 870.2,
"threshold": 2500,
},
)
print(f"Proof ID: {proof.id}")
print(f"Status: {proof.status}")
# Verify a proof
result = client.proofs.verify(proof.id)
print(f"Valid: {result.valid}")Managing API Keys via SDK
typescript
// Create a key
const newKey = await client.keys.create({
name: 'ci-pipeline-prod',
description: 'GitHub Actions workflow key',
});
console.log('Key (save this!):', newKey.key);
// List keys
const { keys } = await client.keys.list();
keys.forEach(k => console.log(k.name, k.last_used_at));
// Revoke a key
await client.keys.revoke(newKey.id);Error Handling
typescript
import { MinervaError } from '@digitalforgestudios/minerva-sdk';
try {
const proof = await client.proofs.create({ ... });
} catch (err) {
if (err instanceof MinervaError) {
console.error('API error:', err.code, err.message);
if (err.status === 429) {
// Respect retry_after
await new Promise(r => setTimeout(r, err.retryAfter * 1000));
}
}
}Async Proof Generation
Proofs may take 1–30 seconds depending on circuit complexity. For long-running proofs, use webhooks instead of polling:
typescript
// Register a webhook first, then:
const proof = await client.proofs.create({
type: 'supply_chain_composite',
inputs: { ... },
webhook_url: 'https://your-app.com/minerva/webhook',
});
// proof.status === 'pending' — your webhook receives proof.completed