@digitalforgestudios/minerva-sdk

TypeScript/JavaScript SDK for the Minerva ZK-STARK Proof Engine

Interact with the Minerva platform from any JavaScript environment. The SDK provides typed access to circuit templates, proof generation, verification, and the Juno AI circuit design oracle.

Features

• 📐 MinervaFormat circuits — Load from templates or build programmatically
• ✅ Proof verification — Verify any Minerva proof structurally
• 🤖 Juno integration — Generate circuits from natural language via the Juno API
• 📤 Export & share — JSON and portable proof formats
• 🏢 Enterprise-ready — TypeScript-first, tree-shakeable, zero runtime dependencies

Installation

npm install @digitalforgestudios/minerva-sdk

Quick Start

import { Minerva, circuits } from '@digitalforgestudios/minerva-sdk';

// Connect to the Minerva platform
const minerva = new Minerva({ apiKey: 'mzk_your_key_here' });

// Load a built-in circuit template
const circuit = circuits.ageVerification({
  minimumAge: 18
});

// Generate a proof via the platform
const proof = await minerva.prove(circuit, {
  public: { minimum_age: 18 },
  private: { user_age: 25 }
});

console.log(proof.valid);      // true
console.log(proof.hash);       // "a1b2c3..."
console.log(proof.publicOnly); // { minimum_age: 18, result: true }

// Verify a proof
const verified = await minerva.verify(proof);
console.log(verified); // true

Circuit Templates

The SDK ships with 10 production-ready circuit templates:

Template	Category	Description
ageVerification	Identity	Prove age meets minimum threshold
incomeThreshold	Finance	Prove income exceeds requirement
creditRange	Finance	Prove credit score within range
documentAuthenticity	Legal	Prove document is authentic
balanceProof	Finance	Prove account balances sum correctly
kycAttestation	Identity	Prove KYC without re-sharing docs
supplyChain	Logistics	Prove supplier certification
voteEligibility	Governance	Prove voter eligibility
financialAudit	Finance	Prove financial compliance
carbonCompliance	ESG	Prove emissions below threshold

Custom Circuits

Build circuits programmatically using MinervaFormat:

import { Minerva, Circuit } from '@digitalforgestudios/minerva-sdk';

const circuit: Circuit = {
  version: '2.0',
  meta: {
    name: 'Salary Band Proof',
    description: 'Prove salary falls within a band',
    tags: ['hr', 'finance']
  },
  circuit: {
    gates: [
      { type: 'gt', left: 'salary', right: 'band_min' },
      { type: 'gt', left: 'band_max', right: 'salary' }
    ]
  },
  inputs: {
    public: { band_min: 80000, band_max: 120000 },
    private: { salary: 95000 }
  }
};

const minerva = new Minerva({ apiKey: 'mzk_your_key_here' });
const proof = await minerva.prove(circuit);

Juno AI Circuit Generation

Generate circuits from natural language:

import { Juno } from '@digitalforgestudios/minerva-sdk';

const juno = new Juno({ apiKey: 'mzk_your_key_here' });

const circuit = await juno.design(
  'Prove my company has fewer than 500 employees without revealing the exact count'
);

console.log(circuit.gates);
console.log(circuit.inputs);

MinervaFormat Specification

All circuits use the MinervaFormat JSON schema (v2.0):

{
  "version": "2.0",
  "meta": {
    "name": "string",
    "description": "string",
    "author": "string",
    "created_at": "ISO-8601",
    "tags": ["string"]
  },
  "circuit": {
    "gates": [
      {
        "type": "gt | lt | eq | add | mul | hash_eq",
        "left": "input_name",
        "right": "input_name"
      }
    ]
  },
  "inputs": {
    "public": { "key": "value" },
    "private": { "key": "value" }
  }
}

Gate Types

Gate	Operation	Description
gt	Greater than	left > right
lt	Less than	left < right
eq	Equals	left == right
add	Addition	left + right
mul	Multiplication	left * right
hash_eq	Hash equality	hash(left) == right

API Reference

new Minerva(options)

Connect to the Minerva platform.

const minerva = new Minerva({
  apiKey: string;      // Your Minerva API key (mzk_ prefix)
  baseUrl?: string;    // API endpoint (default: https://zkesg.com/api)
});

minerva.prove(circuit, inputs?)

Generate a zero-knowledge proof.

const proof = await minerva.prove(circuit, {
  public: { threshold: 100 },
  private: { value: 42 }
});
// Returns: { valid, hash, proof, publicOnly, meta }

minerva.verify(proof)

Verify a proof.

const isValid = await minerva.verify(proof);
// Returns: boolean

Juno(options)

Connect to the Juno AI circuit design oracle.

const juno = new Juno({
  apiKey: string;      // Your Minerva API key
  baseUrl?: string;    // API endpoint (default: https://zkesg.com/api)
});

juno.design(prompt)

Generate a circuit from natural language.

const circuit = await juno.design('Prove X without revealing Y');
// Returns: Circuit (MinervaFormat)

Standalone Verifier

The SDK includes a lightweight standalone verifier for structural proof validation. Anyone can check a Minerva proof — no authentication or account needed.

import { Verifier } from '@digitalforgestudios/minerva-sdk/verifier';

const verifier = new Verifier();

const result = await verifier.check(proofJsonString);

console.log(result.valid);        // true
console.log(result.status);       // "verified"
console.log(result.circuit);      // "Carbon Compliance"
console.log(result.publicInputs); // { threshold: 10000 }
console.log(result.security);     // 128
console.log(result.verifiedInMs); // 12

// Simple boolean check
const ok = await verifier.isValid(proofJson);

// Batch verification
const results = await verifier.checkBatch([proof1, proof2, proof3]);

For full cryptographic verification, use the Minerva platform API or the web verifier.

CLI Verifier

A standalone CLI verifier is available at digitalforgeca/minerva-verify:

# Verify a proof file
minerva-verify proof.json
# ✅ Verified: Carbon Compliance (128-bit security)

Security

• Private inputs are never transmitted to third parties during proof generation
• No trusted setup required (STARK-based)
• API keys use the mzk_ prefix with argon2id storage

Requirements

• Node.js: 18+
• Browser: Chrome 89+, Firefox 89+, Safari 15+, Edge 89+

Links

• 🌐 Minerva Platform
• 💬 Juno AI Oracle
• 📐 Circuit Templates
• 📖 Guides
• 🏢 Digital Forge Studios

License

Proprietary — see LICENSE