@uvrn/delta-engine-sdk

UVRN SDK — receipt emitter + Delta Engine + parity verification for the UVRN registry.

Builds drvc3-receipt-1 receipts, runs multi-source comparisons via the Delta Engine, emits parity receipts, and computes verification scores (vScore).

Install

npm install @uvrn/delta-engine-sdk

Quick Start — Emit a Receipt

import { uvrn } from '@uvrn/delta-engine-sdk';

const stored = await uvrn.emit({
  source: 'lyrikai-node',
  action: 'TRACK_GENERATED',
  payload: { trackId: 'abc123', bpm: 128 },
  apiKey: process.env.UVRN_API_KEY,
  endpoint: 'https://uvrn-worker.uvrn-workers.workers.dev',
  receiptType: 'analytics',  // optional — included in hash if set
});

console.log('Receipt #', stored.registryId, stored.receiptHash);

Receipt Types

Receipts can optionally include a receiptType field that classifies the receipt. When set, this field becomes part of the canonical hash — changing the type invalidates the hash (tamper-evident).

import { buildReceipt } from '@uvrn/delta-engine-sdk';

const receipt = buildReceipt({
  source: 'my-app',
  action: 'DATA_CAPTURED',
  payload: { value: 42 },
  receiptType: 'analytics', // 'genesis' | 'parity' | 'analytics' | 'design' | 'audit' | custom
});

Common receipt types: genesis, parity, analytics, design, audit.

Delta Engine

Run deterministic multi-source comparisons using the Delta formula:

Δ = |a - b| / ((a + b) / 2)

import { runDeltaEngine } from '@uvrn/delta-engine-sdk';

const result = runDeltaEngine({
  bundleId: 'comparison-001',
  claim: 'Page views should match across providers',
  thresholdPct: 0.10,
  dataSpecs: [
    {
      id: 'ga4', label: 'Google Analytics 4', sourceKind: 'report',
      originDocIds: ['ga4-export-001'],
      metrics: [{ key: 'pageviews', value: 10000 }, { key: 'sessions', value: 5200 }],
    },
    {
      id: 'plausible', label: 'Plausible Analytics', sourceKind: 'report',
      originDocIds: ['plausible-export-001'],
      metrics: [{ key: 'pageviews', value: 10300 }, { key: 'sessions', value: 5100 }],
    },
  ],
});

console.log(result.outcome);    // 'consensus' or 'indeterminate'
console.log(result.deltaFinal); // Max delta across metrics
console.log(result.hash);       // SHA-256 of canonical receipt

Parity Receipts

Run the Delta Engine and emit the result as a parity receipt in one call:

import { emitParityReceipt } from '@uvrn/delta-engine-sdk';

const { delta, stored } = await emitParityReceipt(bundle, {
  apiKey: process.env.UVRN_API_KEY,
  endpoint: 'https://uvrn-worker.uvrn-workers.workers.dev',
  source: 'my-verifier',
});

console.log('Outcome:', delta.outcome);
console.log('Registry ID:', stored.registryId);

vScore — Verification Score

Compute a verification score (0–100) from completeness, parity, and freshness:

import { computeVScore, parityFromDelta, freshnessFromTimestamp } from '@uvrn/delta-engine-sdk';

const parity = parityFromDelta(0.03);                          // ~0.97
const freshness = freshnessFromTimestamp(new Date().toISOString()); // ~1.0

const score = computeVScore({
  completeness: 0.95,
  parity,
  freshness,
});
// Default weights: completeness 40%, parity 40%, freshness 20%
console.log('vScore:', score); // ~96

Receipt Format

Every receipt is a drvc3-receipt-1 envelope:

| Field | Description | |---|---| | schemaVersion | Always "drvc3-receipt-1" | | source | Caller identifier (e.g. "lyrikai-node") | | action | Event type (e.g. "TRACK_GENERATED") | | payload | Arbitrary JSON payload | | occurredAt | ISO 8601 UTC — defaults to new Date().toISOString() | | receiptType | Optional classification (included in hash when set) | | sdk.integrityHash | "stubbed" in Phase 0 — real hash in Phase 1 | | receiptHash | "sha256:<hex>" — JCS+SHA-256 of the above fields |

Error Handling

import { uvrn, DuplicateReceiptError, RegistryError, NetworkError } from '@uvrn/delta-engine-sdk';

try {
  const stored = await uvrn.emit({ ... });
} catch (err) {
  if (err instanceof DuplicateReceiptError) {
    // Receipt already in ledger — idempotent, safe to ignore
  } else if (err instanceof RegistryError) {
    console.error('Registry rejected:', err.statusCode, err.body);
  } else if (err instanceof NetworkError) {
    console.error('Network failure:', err.message);
  }
}

Phase Roadmap

| Phase | Feature | Status | |---|---|---| | 0 | Receipt emission, JCS+SHA-256 hash, registry POST | ✅ v0.1.0 | | 0.2 | Receipt types, Delta Engine, parity receipts, vScore | ✅ v0.2.0 | | 0.3 | Narrative field (tamper-evident), formatReceiptLog emoji utility | ✅ v0.3.0 | | 1 | uvrnSeal verification, Ed25519 certified ledger, real integrityHash | Planned | | 2 | Self-serve API key provisioning | Planned | | 3 | LK-Econ metering | Planned |

Suttle Media Systems · UVRN Protocol · github.com/UVRN-org