API Reference

Complete API documentation for all QuantZK VDI packages.

---

@quantzk/attest (Unified SDK)

The all-in-one package. Re-exports everything from all sub-packages plus a convenience attest() function.

attest(config)

High-level function to generate a Decision Attestation.

Parameters:

Parameter	Type	Required	Description
config.pipeline.name	string	Yes	Human-readable pipeline name
config.pipeline.steps	string[]	Yes	Ordered list of pipeline step names
config.pipeline.constraints	object[]	No	Array of constraint objects (or use manifest)
config.pipeline.manifest	string	No	Manifest key (e.g., 'fair-lending-v1'), loads constraints from registry
config.pipeline.version	string	No	Pipeline version (default: '1.0.0')
config.decision.path	string[]	Yes	Execution path through the pipeline
config.decision.inputs	object	Yes	Private inputs (never revealed)
config.decision.outcome	string	Yes	Step ID that produced the outcome
config.authority.type	string	No	'legal_review' | 'standards_body' | 'audit_firm' | 'self_attested'
config.authority.name	string	No	Authority name
config.authority.ref	string	No	Authority reference (e.g., opinion number)
config.options.signingKey	string	No	Hex-encoded Ed25519 signing key (generated if not provided)
config.options.circuitDir	string	No	Path to circuit artifacts (default: zk-cp/build)

Returns: Promise<DecisionAttestation>

Example:

import { attest } from '@quantzk/attest';

const attestation = await attest({
  pipeline: {
    name: 'Loan Approval',
    manifest: 'fair-lending-v1',
    steps: ['application', 'identity', 'credit', 'fairness', 'pricing', 'decision']
  },
  decision: {
    path: ['application', 'identity', 'credit', 'fairness', 'pricing', 'decision'],
    inputs: { credit_score: 720, income: 85000 },
    outcome: 'decision'
  },
  authority: { type: 'legal_review', name: 'Covington', ref: '#2026-014' }
});

---

@quantzk/vdi-prover

Server-side attestation generation with real Groth16 proofs.

new VDI(config)

Create a new VDI prover instance.

Parameters:

Parameter	Type	Required	Description
config.signingKey	string	Yes	Hex-encoded Ed25519 private key (32 bytes)
config.circuitDir	string	Yes	Path to directory containing circuit artifacts
config.kid	string	No	Key ID for rotation (auto-generated if not provided)

Example:

import { VDI } from '@quantzk/vdi-prover';
import { randomBytes } from 'crypto';

const vdi = new VDI({
  signingKey: randomBytes(32).toString('hex'),
  circuitDir: './zk-cp/build'
});

vdi.pipeline(config)

Create a Decision Pipeline definition.

Parameters:

Parameter	Type	Required	Description
config.name	string	Yes	Pipeline name
config.version	string	No	Version string (default: '1.0.0')
config.steps	string[]	Yes	Ordered step names
config.constraints	object[]	No	Array of { id, description, critical, vertex }
config.authority	object	No	{ type, name, reference, regulation }

Returns: Pipeline object with id, name, version, hash, steps, constraints, manifestHash, authority

vdi.attest(pipeline, decision)

Generate a Decision Attestation with a real Groth16 proof.

Parameters:

Parameter	Type	Required	Description
pipeline	Pipeline	Yes	Pipeline from vdi.pipeline()
decision.executionPath	string[]	Yes	Path taken through the pipeline
decision.privateInputs	object	Yes	Private inputs (never revealed in attestation)
decision.outcomeId	string	Yes	Step ID that produced the outcome

Returns: Promise<DecisionAttestation>

Example:

const pipeline = vdi.pipeline({
  name: 'Loan Approval',
  version: '2.0.0',
  steps: ['application', 'identity', 'credit', 'fairness', 'pricing', 'decision'],
  constraints: manifest.constraints,
  authority: { type: 'legal_review', name: 'Covington', reference: 'Opinion #2026' }
});

const attestation = await vdi.attest(pipeline, {
  executionPath: ['application', 'identity', 'credit', 'fairness', 'pricing', 'decision'],
  privateInputs: { credit_score: 720, income: 85000, debt_ratio: 0.32, approved: true },
  outcomeId: 'decision'
});

---

@quantzk/vdi-verifier

Independent offline verification. No server. No API.

verifyDecision(attestation) / verify(attestation)

Run the full 7-step verification on a Decision Attestation.

Parameters:

Parameter	Type	Required	Description
attestation	DecisionAttestation	Yes	The attestation to verify

Returns: Promise<VerificationResult>

interface VerificationResult {
  valid: boolean;
  steps: Array<{
    step: number;
    name: string;
    valid: boolean;
    detail?: string;
    reason?: string;
  }>;
  failedStep?: number;
  reason?: string;
  attestation_id?: string;
}

Example:

import { verify } from '@quantzk/attest';

const result = await verify(attestation);
console.log(result.valid); // true
console.log(result.steps.length); // 7 (or 8 with circuit governance)

verifyAndReceipt(attestation, verifierConfig)

Verify an attestation and emit a signed Verification Receipt.

Parameters:

Parameter	Type	Required	Description
attestation	DecisionAttestation	Yes	The attestation to verify
verifierConfig.signingKey	string	No	Hex-encoded Ed25519 key for signing the receipt
verifierConfig.verifierId	string	No	Verifier identifier (e.g., 'vdi:verifier:my-bot')
verifierConfig.profileId	string	No	Verification profile (default: 'VDI_VERIFY_STRICT_V1')
verifierConfig.parentReceiptHash	string	No	Hash of parent receipt (for chaining)
verifierConfig.chainDepth	number	No	Depth in receipt chain (default: 0)

Returns: Promise<{ verification: VerificationResult, receipt: VerificationReceipt }>

Example:

import { verifyAndReceipt } from '@quantzk/attest';

const { verification, receipt } = await verifyAndReceipt(attestation, {
  signingKey: myPrivateKey,
  verifierId: 'vdi:verifier:compliance-bot',
  profileId: 'VDI_VERIFY_STRICT_V1'
});

verifyReceipt(receipt, options)

Verify a Verification Receipt (meta-verification).

Parameters:

Parameter	Type	Required	Description
receipt	VerificationReceipt	Yes	The receipt to verify
options.attestation	DecisionAttestation	No	Original attestation (for hash binding check)
options.trustedVerifiers	string[]	No	List of trusted verifier IDs

Returns: Promise<ReceiptVerificationResult>

interface ReceiptVerificationResult {
  valid: boolean;
  receipt_id?: string;
  attestation_id?: string;
  verifier?: string;
  checks: Array<{ check: string; valid: boolean }>;
  all_original_checks_passed?: boolean;
  reason?: string;
}

evaluateAcceptancePolicy(receipts, policy, attestation?)

Evaluate whether a receipt set meets an acceptance policy.

Parameters:

Parameter	Type	Required	Description
receipts	VerificationReceipt[]	Yes	Array of receipts to evaluate
policy.level	string	No	'low' | 'medium' | 'high' | 'critical' (default: 'medium')
policy.tvs	object	No	Trusted Verifier Set definition
policy.spotCheckRate	number	No	Probability of spot-check (default: 0.05)
attestation	DecisionAttestation	No	Required for spot-check at 'critical' level

Returns: Promise<AcceptancePolicyResult>

interface AcceptancePolicyResult {
  accepted: boolean;
  reason: string;
  spotCheckTriggered: boolean;
  spotCheckValid: boolean | null;
  receiptsAccepted: number;
}

scoreReceiptSet(receipts)

Score a receipt set for trust assessment.

Parameters:

Parameter	Type	Required	Description
receipts	VerificationReceipt[]	Yes	Array of receipts to score

Returns: ReceiptSetScore

interface ReceiptSetScore {
  total_receipts: number;
  valid_receipts: number;
  unique_verifiers: number;
  unique_profiles: number;
  all_valid: boolean;
  includes_zk_verification: boolean;
  trust_score: number;        // 0-100
  recommendation: string;      // 'low_confidence' | 'medium_confidence' | 'high_confidence'
}

PROFILES

Object containing the three built-in verification profiles:

• PROFILES.VDI_VERIFY_STRICT_V1
• PROFILES.VDI_VERIFY_STANDARD_V1
• PROFILES.VDI_VERIFY_MINIMAL_V1

Individual Verification Steps

For advanced use, each verification step is exported individually:

• validateSchema(attestation), Step 1: Schema validation
• validateTimestamps(attestation), Step 2: Timestamp validation
• validatePipelineIntegrity(attestation), Step 3: Pipeline hash check
• validatePolicyIntegrity(attestation), Step 4: Policy manifest check
• verifyZKProof(attestation), Step 5: Groth16 proof verification
• verifySignature(attestation), Step 6: Ed25519 signature verification
• verifyKeyIntegrity(attestation), Step 7: Verification key hash check

Each returns { valid: boolean, detail?: string, reason?: string }.

---

@quantzk/vdi-registry

Published policy constraint libraries.

getManifest(manifestId)

Retrieve a constraint manifest by ID.

Parameters:

Parameter	Type	Required	Description
manifestId	string	Yes	Full manifest ID (e.g., 'vdi:manifest:fair-lending-v1')

Returns: Manifest | null

interface Manifest {
  manifest_version: string;
  manifest_id: string;
  name: string;
  regulation: string;
  authority: { type: string; name: string; reference: string | null };
  constraints: Constraint[];
  manifest_hash: string;
}

listManifests()

List all available manifests (summary view).

Returns: ManifestSummary[]

getConstraints(manifestId)

Get just the constraints array from a manifest.

Returns: Constraint[] | null

MANIFESTS

The raw manifests object for direct access.

---

@quantzk/vdi-transparency

Append-only receipt transparency log.

new TransparencyLog()

Create a new transparency log instance.

log.append(receipt)

Append a receipt to the log.

Parameters:

Parameter	Type	Required	Description
receipt	VerificationReceipt	Yes	Receipt to log

Returns: SignedLogEntry

interface SignedLogEntry {
  log_index: number;
  entry_hash: string;
  tree_root: string;
  tree_size: number;
  timestamp: number;
  attestation_id: string;
  verifier_id: string;
  result: boolean;
  equivocation_detected: boolean;
}

log.getInclusionProof(logIndex)

Get a Merkle inclusion proof for a log entry.

Returns: { log_index, entry_hash, tree_root, tree_size, proof: string[] }

log.verifyInclusionProof(proof)

Verify a Merkle inclusion proof.

Returns: boolean

log.checkEquivocation(attestationId)

Check for contradictory receipts for an attestation.

Returns: { clean: boolean, entries: object[], equivocations: object[] }

log.getSize()

Get the number of entries in the log.

Returns: number

log.getRoot()

Get the current Merkle root.

Returns: string

---

Verifiable API billing (HTTP)

Production host: https://api.quantzk.com. Paths are relative to that origin.

POST /api/vdi/billing/attest

Issue a signed billing attestation and verification receipt. Supports api-billing-v1 (usage_event) and api-billing-v2 (billing_version: "v2", meter_event, tariff_snapshot).

Requires VDI_ATTEST_ENABLED=true (or DEMO_MODE=true) and, in production, header X-VDI-Attest-Secret.

POST /api/vdi/billing/verify

Verify attestation, receipt, billing fingerprint (v2) or usage arithmetic (v1), commitment binding, and optional transparency inclusion proof.

Use profileId: "VDI_VERIFY_STRICT_V1" for production strict verify (revocation + manifest authority binding).

GET /.well-known/vdi-billing-revocation.json

Operator-published revocation snapshot:

{
  "revokedAttestations": [],
  "revokedKids": [],
  "snapshotTime": 1716300000
}

Sourced from VDI_BILLING_REVOCATION_JSON. Polled when VDI_BILLING_REVOCATION_URL points here.

GET /api/vdi/billing/transparency/head

Merkle tree root, tree size, latest signed log entry hash, operator kid.

GET /api/vdi/billing/transparency/checkpoint

Latest operator-signed tree head (STH).

GET /api/vdi/billing/transparency/consistency?from_size=N

Consistency proof from tree size N to the current head.

---

@quantzk/vdi-verifier-registry

Verifier identity registry with key lifecycle.

new VerifierRegistry()

Create a new verifier registry instance.

registry.register(config)

Register a new verifier.

Parameters:

Parameter	Type	Required	Description
config.verifierId	string	Yes	Unique verifier identifier
config.name	string	Yes	Human-readable name
config.publicKey	string	Yes	Hex-encoded Ed25519 public key
config.organization	string	No	Organization name
config.capabilities	string[]	No	List of capabilities (default: ['full_verification'])

Returns: Verifier record

registry.rotateKey(verifierId, newPublicKey, gracePeriodSeconds)

Rotate a verifier's key with an optional grace period.

Parameters:

Parameter	Type	Required	Description
verifierId	string	Yes	Verifier to rotate
newPublicKey	string	Yes	New hex-encoded public key
gracePeriodSeconds	number	No	Grace period where old key remains valid

Returns: { new_key_version, grace_period_seconds }

registry.revoke(verifierId, reason)

Revoke a verifier (e.g., after equivocation detection).

Returns: { verifier_id, reason, revoked_at }

registry.validateKey(verifierId, publicKey)

Check if a public key is currently valid for a verifier.

Returns: { valid: boolean, key_version?: number, status?: string, reason?: string }

registry.getVerifier(verifierId)

Get full verifier record.

registry.listActive()

List all non-revoked verifiers.

registry.isRevoked(verifierId)

Check if a verifier has been revoked.

Returns: boolean