@quantzk/sdk

Integrator-facing SDK for verifiable API billing. Record usage → portable .qzk receipt → offline or online verify against QZR-1 Minimal / Standard / Strict.

Package: protocol/packages/sdk (also in ayitsomar/quantzk-verify)
Spec: QZR-1

Install

git clone https://github.com/ayitsomar/quantzk-verify.git
cd quantzk-verify
npm install --legacy-peer-deps
# workspace package: @quantzk/sdk

Dream API

import { QuantZK } from '@quantzk/sdk';
import { readFileSync } from 'fs';

const trustRoots = JSON.parse(readFileSync('./trust-roots.json', 'utf8'));

const qzk = new QuantZK({
  baseUrl: 'https://api.quantzk.com',
  attestSecret: process.env.QUANTZK_ATTEST_SECRET,
  trustRoots,
});

const grant = await qzk.authorize({
  tenantId: 'cus_acme',
  tariffId: 'tariff_default',
  unitPriceMicros: 120,
  currency: 'USD',
});

const gate = await qzk.preflight({
  authority: grant,
  tenantId: 'cus_acme',
  eventTimestamp: new Date().toISOString(),
  units: 1842,
  unitPriceMicros: 120,
});
if (!gate.may_execute) throw new Error('not authorized to spend');

const receipt = await qzk.record({
  eventId: 'evt_123',
  tenantId: 'cus_acme',
  units: 1842,
  unitPriceMicros: 120,
  authority: grant,
});

const result = await qzk.verify(receipt, { level: 'standard' });
console.log(result.text);
console.log(result.levels);
// { minimal: 'PASS', standard: 'PASS', authority: 'PASS', revocation: 'NOT_CHECKED', ... }

authorize() issues a signed charge grant that must predate the meter event. preflight() is the execution-time MAY_EXECUTE decision (does not consume). record() attests after metering and atomically consumes a single-use grant. Canonical fields: tenantId, contractVersion, unitPriceMicros, currency (never IEEE-754 price). Set VDI_BILLING_REQUIRE_AUTHORITY=true on the API to reject attest without a grant.

v1 grants are usage_mode: single_use. Receipt-time authority: PASS is binding, not consumption uniqueness and not permission to spend now. See Charge authority.

Verification levels

Level	Meaning
minimal	Historical crypto + fingerprint
standard	Minimal + receipt + fingerprint hash + Phase-2 in-circuit binding + charge authority (PASS or NOT_CHECKED)
strict	Standard + fresh revocation CLEAR (+ meter/transparency per profile)

Missing Phase-2 under Standard is FAIL (not NOT_CHECKED).
Offline Standard PASS with revocation: NOT_CHECKED is not current governance clearance.

Exports: evaluateQzr1, reportOffline, buildQzkReceipt, parseQzk, buildVerifiedSummary.

Async (opt-in)

const pending = await qzk.record({
  eventId: 'evt_async',
  customerId: 'cus_acme',
  units: 100,
  unitPriceMicros: 120,
  async: true,
  wait: false,
});
// { async: true, job_id, status: 'accepted', ... }

const done = await qzk.record({
  eventId: 'evt_async_wait',
  customerId: 'cus_acme',
  units: 100,
  unitPriceMicros: 120,
  async: true,
  wait: true,
  timeoutMs: 180_000,
});

Trust roots

Pass a JSON allow-list (see protocol/conformance/qzr-1/trust-roots.json) so verification can distinguish math-valid proofs from authorized QuantZK billing evidence:

• authorized_billing_vkey_hashes
• authorized_circuit_ids / authorized_binding_versions
• authorized_attestation_issuer_public_keys
• max_snapshot_age_seconds, allow_missing_meter

Non-regression

• Existing api-billing-v2 /attest and /verify contracts are unchanged.
• QZR-1 is additive.
• Async remains opt-in.

See also

• Verify CLI — npx @quantzk/verify
• LiteLLM adapter
• QZR-1 specification
• API billing pilot
• Conformance: protocol/conformance/qzr-1/