MinervaMinerva
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-sdk
typescript
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-zkesg
python
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
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-sdk
typescript
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-zkesg
python
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