@uvrn/adapter 1.0.0

package/dist/tests/wrapper.test.js

@@ -0,0 +1,96 @@
+"use strict";
+/**
+ * DRVC3 Wrapper Tests
+ * Tests the wrapInDRVC3 function and schema validation
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+const ethers_1 = require("ethers");
+const wrapper_1 = require("../src/wrapper");
+const validator_1 = require("../src/validator");
+const signer_1 = require("../src/signer");
+describe('DRVC3 Wrapper', () => {
+    // Mock DeltaReceipt (as would come from Layer 1)
+    const mockDeltaReceipt = {
+        bundleId: 'test-bundle-001',
+        deltaFinal: 0.05,
+        sources: ['Source A', 'Source B'],
+        rounds: [
+            {
+                round: 1,
+                deltasByMetric: { revenue: 0.05, users: 0.0 },
+                withinThreshold: true,
+                witnessRequired: false
+            }
+        ],
+        suggestedFixes: [],
+        outcome: 'consensus',
+        hash: 'a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2'
+    };
+    let testWallet;
+    beforeAll(() => {
+        // Create a deterministic wallet for testing
+        testWallet = ethers_1.Wallet.createRandom();
+    });
+    it('should wrap DeltaReceipt in valid DRVC3 envelope', async () => {
+        const drvc3 = await (0, wrapper_1.wrapInDRVC3)(mockDeltaReceipt, testWallet, {
+            issuer: 'uvrn-test',
+            event: 'delta-reconciliation'
+        });
+        // Check required fields
+        expect(drvc3.receipt_id).toMatch(/^drvc3-test-bundle-001-\d+$/);
+        expect(drvc3.issuer).toBe('uvrn-test');
+        expect(drvc3.event).toBe('delta-reconciliation');
+        expect(drvc3.timestamp).toBeDefined();
+        expect(drvc3.block_state).toBe('loose');
+        expect(drvc3.certificate).toBe('DRVC3 v1.0');
+        // Check integrity block
+        expect(drvc3.integrity.hash_algorithm).toBe('sha256');
+        expect(drvc3.integrity.hash).toBe(mockDeltaReceipt.hash);
+        expect(drvc3.integrity.signature_method).toBe('eip191');
+        expect(drvc3.integrity.signature).toBeDefined();
+        expect(drvc3.integrity.signer_address).toBe(testWallet.address);
+        // Check validation block
+        expect(drvc3.validation.v_score).toBe(mockDeltaReceipt.deltaFinal);
+        expect(drvc3.validation.checks.delta_receipt).toEqual(mockDeltaReceipt);
+    });
+    it('should produce schema-valid DRVC3 receipt', async () => {
+        const drvc3 = await (0, wrapper_1.wrapInDRVC3)(mockDeltaReceipt, testWallet, {
+            issuer: 'uvrn',
+            event: 'test'
+        });
+        const result = (0, validator_1.validateDRVC3)(drvc3);
+        expect(result.valid).toBe(true);
+        expect(result.errors).toBeUndefined();
+    });
+    it('should include optional fields when provided', async () => {
+        const drvc3 = await (0, wrapper_1.wrapInDRVC3)(mockDeltaReceipt, testWallet, {
+            issuer: 'uvrn',
+            event: 'delta-reconciliation',
+            blockState: 'blocked',
+            certificate: 'DRVC3 v1.1',
+            description: 'Test receipt',
+            tags: ['#uvrn', '#receipt', '#test']
+        });
+        expect(drvc3.block_state).toBe('blocked');
+        expect(drvc3.certificate).toBe('DRVC3 v1.1');
+        expect(drvc3.description).toBe('Test receipt');
+        expect(drvc3.tags).toEqual(['#uvrn', '#receipt', '#test']);
+    });
+    it('should create verifiable signature', async () => {
+        const drvc3 = await (0, wrapper_1.wrapInDRVC3)(mockDeltaReceipt, testWallet, {
+            issuer: 'uvrn',
+            event: 'test'
+        });
+        // Recover signer from signature
+        const recoveredAddress = (0, signer_1.recoverSigner)(drvc3.integrity.hash, drvc3.integrity.signature);
+        expect(recoveredAddress.toLowerCase()).toBe(testWallet.address.toLowerCase());
+    });
+    it('should extract original DeltaReceipt from envelope', async () => {
+        const drvc3 = await (0, wrapper_1.wrapInDRVC3)(mockDeltaReceipt, testWallet, {
+            issuer: 'uvrn',
+            event: 'test'
+        });
+        const extracted = (0, wrapper_1.extractDeltaReceipt)(drvc3);
+        expect(extracted).toEqual(mockDeltaReceipt);
+    });
+});

package/jest.config.js

@@ -0,0 +1,12 @@
+/** @type {import('ts-jest').JestConfigWithTsJest} */
+module.exports = {
+  preset: 'ts-jest',
+  testEnvironment: 'node',
+  testMatch: ['**/tests/**/*.test.ts'],
+  moduleFileExtensions: ['ts', 'js', 'json'],
+  collectCoverageFrom: ['src/**/*.ts'],
+  moduleNameMapper: {
+    '^@uvrn/core$': '<rootDir>/../uvrn-core/src'
+  }
+};
+

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@uvrn/adapter",
+  "version": "1.0.0",
+  "description": "UVRN DRVC3 envelope adapter — wraps core receipts with EIP-191 signatures",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "keywords": [
+    "uvrn",
+    "drvc3",
+    "eip191",
+    "receipts"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "ethers": "^6.0.0",
+    "ajv": "^8.12.0",
+    "ajv-formats": "^2.1.1",
+    "@uvrn/core": "1.0.0"
+  },
+  "devDependencies": {
+    "@types/jest": "^29.5.0",
+    "@types/node": "^20.0.0",
+    "jest": "^29.5.0",
+    "ts-jest": "^29.1.0",
+    "typescript": "^5.3.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "jest",
+    "lint": "eslint src/**/*.ts",
+    "clean": "rm -rf dist"
+  }
+}

package/schemas/drvc3.schema.json

@@ -0,0 +1,115 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://uvrn.org/schemas/drvc3.v1.01.json",
+  "title": "DRVC3 Receipt v1.01",
+  "description": "DRVC3 envelope with Layer 2 extensions support. Backward-compatible with v1.0.",
+  "type": "object",
+  "required": [
+    "receipt_id",
+    "issuer",
+    "event",
+    "timestamp",
+    "integrity",
+    "block_state",
+    "certificate"
+  ],
+  "properties": {
+    "receipt_id": {
+      "type": "string"
+    },
+    "issuer": {
+      "type": "string"
+    },
+    "event": {
+      "type": "string"
+    },
+    "timestamp": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "description": {
+      "type": "string"
+    },
+    "resource": {
+      "type": "object",
+      "properties": {
+        "type": {
+          "type": "string"
+        },
+        "url": {
+          "type": "string"
+        },
+        "branch": {
+          "type": "string"
+        },
+        "commit_hash": {
+          "type": "string"
+        }
+      }
+    },
+    "integrity": {
+      "type": "object",
+      "required": [
+        "hash_algorithm",
+        "hash",
+        "signature_method",
+        "signature",
+        "signer_address"
+      ],
+      "properties": {
+        "hash_algorithm": {
+          "enum": [
+            "sha256"
+          ]
+        },
+        "hash": {
+          "type": "string"
+        },
+        "signature_method": {
+          "enum": [
+            "eip191"
+          ]
+        },
+        "signature": {
+          "type": "string"
+        },
+        "signer_address": {
+          "type": "string"
+        }
+      }
+    },
+    "validation": {
+      "type": "object",
+      "properties": {
+        "v_score": {
+          "type": "number"
+        },
+        "checks": {
+          "type": "object"
+        }
+      }
+    },
+    "block_state": {
+      "enum": [
+        "loose",
+        "blocked"
+      ]
+    },
+    "certificate": {
+      "type": "string"
+    },
+    "replay_instructions": {
+      "type": "object"
+    },
+    "tags": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "extensions": {
+      "type": "object",
+      "description": "Layer 2 provenance data — source URLs, timestamps, evidence links, domain metadata. Not covered by L1 integrity hash."
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1,16 @@
+/**
+ * Loosechain UVRN Adapter
+ * Layer 2 - Wraps Delta Engine Core receipts in DRVC3 envelopes
+ */
+
+// Types
+export * from './types';
+
+// Core wrapper
+export { wrapInDRVC3, extractDeltaReceipt } from './wrapper';
+
+// Signing utilities
+export { signHash, recoverSigner, verifySignature } from './signer';
+
+// Validation
+export { validateDRVC3, isDRVC3Receipt } from './validator';

package/src/signer.ts

@@ -0,0 +1,47 @@
+/**
+ * EIP-191 Signing Utilities
+ * Provides Ethereum personal message signing for DRVC3 receipts
+ */
+
+import { Wallet, HDNodeWallet, verifyMessage } from 'ethers';
+
+/**
+ * Signs a hash using EIP-191 (Ethereum Signed Message)
+ * @param hash - The hex string hash to sign
+ * @param wallet - ethers Wallet instance with private key
+ * @returns Promise resolving to the signature hex string
+ */
+export async function signHash(hash: string, wallet: Wallet | HDNodeWallet): Promise<string> {
+  // signMessage automatically prefixes with "\x19Ethereum Signed Message:\n" + message length
+  return wallet.signMessage(hash);
+}
+
+/**
+ * Recovers the signer address from a hash and signature
+ * @param hash - The original hash that was signed
+ * @param signature - The EIP-191 signature
+ * @returns The signer's Ethereum address
+ */
+export function recoverSigner(hash: string, signature: string): string {
+  return verifyMessage(hash, signature);
+}
+
+/**
+ * Verifies that a signature was created by the expected signer
+ * @param hash - The original hash that was signed
+ * @param signature - The EIP-191 signature
+ * @param expectedAddress - The expected signer address
+ * @returns True if the signature is valid and matches the expected address
+ */
+export function verifySignature(
+  hash: string,
+  signature: string,
+  expectedAddress: string
+): boolean {
+  try {
+    const recoveredAddress = recoverSigner(hash, signature);
+    return recoveredAddress.toLowerCase() === expectedAddress.toLowerCase();
+  } catch {
+    return false;
+  }
+}

package/src/types.ts

@@ -0,0 +1,102 @@
+/**
+ * DRVC3 Types for UVRN Adapter (v1.01)
+ * Layer 2 envelope types that wrap Layer 1 DeltaReceipt
+ *
+ * v1.01 adds the `extensions` field for Layer 2 provenance data.
+ */
+
+import { DeltaReceipt } from '@uvrn/core';
+
+/**
+ * DRVC3 Integrity block - contains hash and signature data
+ */
+export interface DRVC3Integrity {
+  hash_algorithm: 'sha256';
+  hash: string;
+  signature_method: 'eip191';
+  signature: string;
+  signer_address: string;
+}
+
+/**
+ * DRVC3 Validation block - contains score and embedded checks
+ */
+export interface DRVC3Validation {
+  v_score: number;
+  checks: {
+    delta_receipt: DeltaReceipt;
+    [key: string]: unknown;
+  };
+}
+
+/**
+ * DRVC3 Resource block (optional) - describes the verified resource
+ */
+export interface DRVC3Resource {
+  type?: string;
+  url?: string;
+  branch?: string;
+  commit_hash?: string;
+}
+
+/**
+ * Block state - "loose" means mutable/portable, "blocked" means canonized/permanent
+ */
+export type BlockState = 'loose' | 'blocked';
+
+/**
+ * Full DRVC3 Receipt Envelope
+ * Wraps Layer 1 DeltaReceipt with protocol metadata and signatures
+ */
+export interface DRVC3Receipt {
+  receipt_id: string;
+  issuer: string;
+  event: string;
+  timestamp: string;
+  description?: string;
+  resource?: DRVC3Resource;
+  integrity: DRVC3Integrity;
+  validation: DRVC3Validation;
+  block_state: BlockState;
+  certificate: string;
+  replay_instructions?: Record<string, unknown>;
+  tags?: string[];
+  /**
+   * Layer 2 extension data — provenance, evidence, domain-specific metadata.
+   * This field is NOT covered by the L1 integrity hash. It is envelope metadata
+   * owned by the consumer chain (e.g., MarketChain source URLs, evidence links).
+   */
+  extensions?: Record<string, unknown>;
+}
+
+/**
+ * Options for wrapping a DeltaReceipt in DRVC3 envelope
+ */
+export interface WrapOptions {
+  /** Issuer identifier (e.g., "uvrn", "app.example.com") */
+  issuer: string;
+  /** Event type (e.g., "delta-reconciliation") */
+  event: string;
+  /** Block state - defaults to "loose" */
+  blockState?: BlockState;
+  /** DRVC3 certificate version - defaults to "DRVC3 v1.0" */
+  certificate?: string;
+  /** Optional description */
+  description?: string;
+  /** Optional resource metadata */
+  resource?: DRVC3Resource;
+  /** Optional replay instructions */
+  replayInstructions?: Record<string, unknown>;
+  /** Optional tags (e.g., ["#uvrn", "#receipt"]) */
+  tags?: string[];
+  /** Optional Layer 2 extension data (provenance, evidence, domain metadata) */
+  extensions?: Record<string, unknown>;
+}
+
+/**
+ * Validation result from schema validation
+ */
+export interface DRVC3ValidationResult {
+  valid: boolean;
+  errors?: string[];
+}

package/src/validator.ts

@@ -0,0 +1,53 @@
+/**
+ * DRVC3 Schema Validator
+ * Uses ajv to validate DRVC3 receipts against the official schema
+ */
+
+import Ajv from 'ajv';
+import * as path from 'path';
+import * as fs from 'fs';
+import { DRVC3ValidationResult } from './types';
+
+// Load schema from file
+const schemaPath = path.join(__dirname, '../schemas/drvc3.schema.json');
+const drvc3Schema = JSON.parse(fs.readFileSync(schemaPath, 'utf-8'));
+
+// Initialize Ajv with JSON Schema 2020-12 support
+const ajv = new Ajv({ strict: false });
+
+// Add formats support (date-time, etc.)
+// eslint-disable-next-line @typescript-eslint/no-var-requires
+const addFormats = require('ajv-formats');
+addFormats(ajv);
+
+// Compile the schema once
+const validateSchema = ajv.compile(drvc3Schema);
+
+/**
+ * Validates a DRVC3 receipt against the official schema
+ * @param receipt - The receipt object to validate
+ * @returns Validation result with errors if invalid
+ */
+export function validateDRVC3(receipt: unknown): DRVC3ValidationResult {
+  const valid = validateSchema(receipt);
+  
+  if (valid) {
+    return { valid: true };
+  }
+  
+  const errors = validateSchema.errors?.map(err => {
+    const path = err.instancePath || '/';
+    return `${path}: ${err.message}`;
+  }) || ['Unknown validation error'];
+  
+  return { valid: false, errors };
+}
+
+/**
+ * Type guard to check if an object is a valid DRVC3 receipt
+ * @param obj - Object to check
+ * @returns True if the object is a valid DRVC3 receipt
+ */
+export function isDRVC3Receipt(obj: unknown): boolean {
+  return validateDRVC3(obj).valid;
+}

package/src/wrapper.ts

@@ -0,0 +1,103 @@
+/**
+ * DRVC3 Wrapper
+ * Wraps Layer 1 DeltaReceipt in a DRVC3 envelope with EIP-191 signatures
+ * 
+ * Key Principle: The DeltaReceipt hash is READ-ONLY from Layer 1.
+ * DRVC3 envelope fields (receipt_id, timestamp, signature) are envelope metadata
+ * and do NOT affect determinism or replay.
+ */
+
+import { DeltaReceipt } from '@uvrn/core';
+import { Wallet, HDNodeWallet, Signer } from 'ethers';
+import { DRVC3Receipt, WrapOptions } from './types';
+import { signHash } from './signer';
+
+/**
+ * Wraps a DeltaReceipt in a DRVC3 envelope
+ * 
+ * @param deltaReceipt - Layer 1 DeltaReceipt (deterministic, hash-covered)
+ * @param signer - ethers Wallet for EIP-191 signing
+ * @param options - Envelope options (issuer, event, etc.)
+ * @returns Promise resolving to complete DRVC3 receipt
+ * 
+ * @example
+ * ```typescript
+ * import { runDeltaEngine } from '@uvrn/core';
+ * import { wrapInDRVC3 } from '@uvrn/adapter';
+ * import { Wallet } from 'ethers';
+ * 
+ * const deltaReceipt = runDeltaEngine(bundle);
+ * const wallet = new Wallet(privateKey);
+ * const drvc3 = await wrapInDRVC3(deltaReceipt, wallet, {
+ *   issuer: 'uvrn',
+ *   event: 'delta-reconciliation'
+ * });
+ * ```
+ */
+export async function wrapInDRVC3(
+  deltaReceipt: DeltaReceipt,
+  signer: Wallet | HDNodeWallet,
+  options: WrapOptions
+): Promise<DRVC3Receipt> {
+  // 1. Generate receipt_id (ENVELOPE METADATA - non-deterministic, intentional)
+  const timestamp = new Date().toISOString();
+  const receipt_id = `drvc3-${deltaReceipt.bundleId}-${Date.now()}`;
+
+  // 2. Read hash from DeltaReceipt (HASH DOMAIN - read-only from Layer 1)
+  const hash = deltaReceipt.hash;
+
+  // 3. Sign hash with EIP-191 (ENVELOPE METADATA - certifies "who" and "when")
+  const signature = await signHash(hash, signer);
+
+  // 4. Construct DRVC3 envelope
+  const drvc3: DRVC3Receipt = {
+    receipt_id,
+    issuer: options.issuer,
+    event: options.event,
+    timestamp,
+    integrity: {
+      hash_algorithm: 'sha256',
+      hash,
+      signature_method: 'eip191',
+      signature,
+      signer_address: signer.address
+    },
+    validation: {
+      v_score: deltaReceipt.deltaFinal,
+      checks: {
+        delta_receipt: deltaReceipt
+      }
+    },
+    block_state: options.blockState || 'loose',
+    certificate: options.certificate || 'DRVC3 v1.01'
+  };
+
+  // Add optional fields if provided
+  if (options.description) {
+    drvc3.description = options.description;
+  }
+  if (options.resource) {
+    drvc3.resource = options.resource;
+  }
+  if (options.replayInstructions) {
+    drvc3.replay_instructions = options.replayInstructions;
+  }
+  if (options.extensions) {
+    drvc3.extensions = options.extensions;
+  }
+  if (options.tags) {
+    drvc3.tags = options.tags;
+  }
+
+  return drvc3;
+}
+
+/**
+ * Extracts the original DeltaReceipt from a DRVC3 envelope
+ * 
+ * @param drvc3 - DRVC3 receipt envelope
+ * @returns The embedded DeltaReceipt
+ */
+export function extractDeltaReceipt(drvc3: DRVC3Receipt): DeltaReceipt {
+  return drvc3.validation.checks.delta_receipt;
+}