@uvrn/sdk

TypeScript SDK for the UVRN Delta Engine — programmatic access to deterministic verification and consensus computation. Release: 1.6.0.

Disclaimer: UVRN is in Alpha testing. The engine measures whether your sources agree with each other — not whether they’re correct. Final trust of output rests with the user. Use at your own discretion. Have fun.

UVRN makes no claims to "truth", the "verification" is the output of math — it is up to any user to decide if claim is actually "true" — Research and testing are absolutely recommended per use case and individual system!!

Overview

The Delta Engine SDK provides a developer-friendly interface to interact with the Delta Engine in multiple execution modes:

• CLI Mode: Spawn the CLI executable as a child process
• HTTP Mode: Make REST API calls to a running Delta Engine server
• Local Mode: Direct import and execution of the core engine

Versioning

The package exports a VERSION constant that is read from package.json at runtime, so it always matches the published version. See default-safe behavior (ADR) for the monorepo policy on a single source of truth for version.

Installation

npm install @uvrn/sdk

Quick Start

TypeScript Example

import { DeltaEngineClient, BundleBuilder } from '@uvrn/sdk';

// Create a client (choose your mode)
const client = new DeltaEngineClient({
  mode: 'http',
  apiUrl: 'http://localhost:3000',
  timeout: 30000
});

// Build a bundle
const bundle = new BundleBuilder()
  .setClaim('Metrics from source-a and source-b agree within 5%')
  .addDataSpecQuick(
    'source-a',
    'Source A',
    'report',
    ['doc-001'],
    [{ key: 'total', value: 1000, unit: 'count' }]
  )
  .addDataSpecQuick(
    'source-b',
    'Source B',
    'report',
    ['doc-002'],
    [{ key: 'total', value: 1020, unit: 'count' }]
  )
  .setThreshold(0.05)
  .build();

// Execute the bundle
const receipt = await client.runEngine(bundle);

console.log('Outcome:', receipt.outcome);
console.log('Delta:', receipt.deltaFinal);
console.log('Hash:', receipt.hash);

JavaScript Example (ES Modules)

import { DeltaEngineClient, BundleBuilder } from '@uvrn/sdk';

const client = new DeltaEngineClient({
  mode: 'local'
});

const bundle = new BundleBuilder()
  .setClaim('Metrics from two sources agree within 10%')
  .addDataSpec({
    id: 'source-1',
    label: 'Source One',
    sourceKind: 'report',
    originDocIds: ['doc-001'],
    metrics: [{ key: 'total', value: 500 }]
  })
  .addDataSpec({
    id: 'source-2',
    label: 'Source Two',
    sourceKind: 'report',
    originDocIds: ['doc-002'],
    metrics: [{ key: 'total', value: 485 }]
  })
  .setThresholdPercent(10)
  .build();

const receipt = await client.runEngine(bundle);
console.log('Result:', receipt);

JavaScript Example (CommonJS)

const { DeltaEngineClient, BundleBuilder } = require('@uvrn/sdk');

// ... same as ES modules example

Client Modes

CLI Mode

Spawns the Delta Engine CLI as a child process:

const client = new DeltaEngineClient({
  mode: 'cli',
  cliPath: '/usr/local/bin/uvrn', // or './node_modules/.bin/uvrn'
  timeout: 30000
});

Requirements:

• Delta Engine CLI must be installed
• cliPath must point to the executable

HTTP Mode

Makes REST API calls to a running Delta Engine server:

const client = new DeltaEngineClient({
  mode: 'http',
  apiUrl: 'http://localhost:3000',
  timeout: 30000,
  retries: 3
});

Requirements:

• Delta Engine API server must be running
• Server must be accessible at apiUrl

Local Mode

Directly imports and executes the core engine:

const client = new DeltaEngineClient({
  mode: 'local'
});

Requirements:

• @uvrn/core must be installed

API Reference

DeltaEngineClient

Main client class for executing bundles and verifying receipts.

Constructor

new DeltaEngineClient(options: ClientOptions)

Options:

• mode: 'cli' | 'http' | 'local' - Execution mode
• cliPath?: string - Path to CLI executable (CLI mode only)
• apiUrl?: string - API base URL (HTTP mode only)
• timeout?: number - Request timeout in ms (default: 30000)
• retries?: number - Retry attempts (default: 3)

Methods

async runEngine(bundle: DeltaBundle): Promise<DeltaReceipt>

Executes a bundle and returns a receipt.

const receipt = await client.runEngine(bundle);

async validateBundle(bundle: DeltaBundle): Promise<ValidationResult>

Validates a bundle without executing it.

const result = await client.validateBundle(bundle);
if (!result.valid) {
  console.error('Errors:', result.errors);
}

async verifyReceipt(receipt: DeltaReceipt): Promise<VerificationResult>

Verifies a receipt's hash integrity.

const result = await client.verifyReceipt(receipt);
if (!result.verified) {
  console.error('Receipt verification failed!');
}

BundleBuilder

Fluent API for building Delta Bundles.

Methods

setClaim(claim: string): this

Sets the claim statement.

addDataSpec(spec: DataSpec): this

Adds a complete DataSpec.

addDataSpecQuick(id, label, sourceKind, originDocIds, metrics): this

Shorthand for adding a DataSpec.

setThreshold(threshold: number): this

Sets threshold as decimal (0.0 to 1.0).

setThresholdPercent(percent: number): this

Sets threshold as percentage (0 to 100).

setMaxRounds(rounds: number): this

Sets maximum rounds (default: 5).

validate(): ValidationResult

Validates current configuration.

build(): DeltaBundle

Builds and returns the bundle (throws if invalid).

Use cases

• Run the engine from code — Use local mode to run comparisons in-process, or HTTP/CLI mode to call a remote server or CLI.
• Build bundles programmatically — Use BundleBuilder to construct valid bundles without hand-writing JSON.
• Validate and verify in pipelines — Validate bundles before run; verify receipt hashes after run for integrity checks.
• Integrate into any service — Same API whether you use CLI, HTTP, or local; switch modes via config.

Validation and replay contract

Bundle validation is aligned with @uvrn/core: the SDK delegates to core so pass/fail is identical (e.g. single dataSpec, threshold=0, NaN or non-number metrics are invalid in both). See core README for the full validation contract.

Replay determinism uses the canonical receipt payload excluding the optional ts field. replayReceipt(receipt, bundle, executeFn) returns deterministic: true when the normalized payloads match, even if the original and replayed receipts differ only by ts; in that case timestampNormalized is set. This matters for audit/compliance: you can verify that a receipt was produced deterministically from a bundle without requiring that every executor use the same timestamp.

Validators

validateBundle(bundle: unknown): ValidationResult

Validates bundle structure (delegates to core; same pass/fail as API/MCP/CLI).

validateReceipt(receipt: unknown): ValidationResult

Validates receipt structure.

verifyReceiptHash(receipt: DeltaReceipt): boolean

Verifies receipt hash integrity.

Error Handling

The SDK provides typed error classes:

import {
  DeltaEngineError,
  ValidationError,
  ExecutionError,
  NetworkError,
  ConfigurationError
} from '@uvrn/sdk';

try {
  const receipt = await client.runEngine(bundle);
} catch (error) {
  if (error instanceof ValidationError) {
    console.error('Bundle is invalid:', error.errors);
  } else if (error instanceof ExecutionError) {
    console.error('Execution failed:', error.message, error.exitCode);
  } else if (error instanceof NetworkError) {
    console.error('Network error:', error.statusCode, error.response);
  } else if (error instanceof ConfigurationError) {
    console.error('Configuration error:', error.message);
  }
}

TypeScript Support

The SDK is written in TypeScript and includes full type definitions:

import type {
  DeltaBundle,
  DeltaReceipt,
  DataSpec,
  MetricPoint,
  ClientOptions,
  ValidationResult,
  VerificationResult
} from '@uvrn/sdk';

Examples

See the examples directory for complete working examples:

• examples/typescript-client/ - TypeScript usage
• examples/javascript-client/ - JavaScript (ESM and CommonJS)
• examples/error-handling/ - Error handling patterns
• examples/batch-processing/ - Processing multiple bundles

Links

Open source: Source code and issues: GitHub (uvrn-packages). Project landing: UVRN.

• Repository — monorepo (this package: uvrn-sdk)
• SDK Guide — comprehensive usage guide
• @uvrn/core — Delta Engine core (used in local mode)
• @uvrn/cli — run the engine from the command line
• @uvrn/api — HTTP server for the engine

Requirements

• Node.js >= 18.0.0
• TypeScript >= 5.0.0 (for TypeScript projects)

License

MIT