@uvrn/adapter 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+/**
+ * @uvrn/adapter — UVRN DRVC3 envelope adapter placeholder
+ */
+export declare const version = "1.0.0";

package/dist/index.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.version = void 0;
+/**
+ * @uvrn/adapter — UVRN DRVC3 envelope adapter placeholder
+ */
+exports.version = '1.0.0';

package/dist/src/index.d.ts

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

package/dist/src/index.js

@@ -0,0 +1,36 @@
+"use strict";
+/**
+ * Loosechain UVRN Adapter
+ * Layer 2 - Wraps Delta Engine Core receipts in DRVC3 envelopes
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isDRVC3Receipt = exports.validateDRVC3 = exports.verifySignature = exports.recoverSigner = exports.signHash = exports.extractDeltaReceipt = exports.wrapInDRVC3 = void 0;
+// Types
+__exportStar(require("./types"), exports);
+// Core wrapper
+var wrapper_1 = require("./wrapper");
+Object.defineProperty(exports, "wrapInDRVC3", { enumerable: true, get: function () { return wrapper_1.wrapInDRVC3; } });
+Object.defineProperty(exports, "extractDeltaReceipt", { enumerable: true, get: function () { return wrapper_1.extractDeltaReceipt; } });
+// Signing utilities
+var signer_1 = require("./signer");
+Object.defineProperty(exports, "signHash", { enumerable: true, get: function () { return signer_1.signHash; } });
+Object.defineProperty(exports, "recoverSigner", { enumerable: true, get: function () { return signer_1.recoverSigner; } });
+Object.defineProperty(exports, "verifySignature", { enumerable: true, get: function () { return signer_1.verifySignature; } });
+// Validation
+var validator_1 = require("./validator");
+Object.defineProperty(exports, "validateDRVC3", { enumerable: true, get: function () { return validator_1.validateDRVC3; } });
+Object.defineProperty(exports, "isDRVC3Receipt", { enumerable: true, get: function () { return validator_1.isDRVC3Receipt; } });

package/dist/src/signer.d.ts

@@ -0,0 +1,27 @@
+/**
+ * EIP-191 Signing Utilities
+ * Provides Ethereum personal message signing for DRVC3 receipts
+ */
+import { Wallet, HDNodeWallet } 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 declare function signHash(hash: string, wallet: Wallet | HDNodeWallet): Promise<string>;
+/**
+ * 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 declare function recoverSigner(hash: string, signature: string): string;
+/**
+ * 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 declare function verifySignature(hash: string, signature: string, expectedAddress: string): boolean;

package/dist/src/signer.js

@@ -0,0 +1,45 @@
+"use strict";
+/**
+ * EIP-191 Signing Utilities
+ * Provides Ethereum personal message signing for DRVC3 receipts
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.signHash = signHash;
+exports.recoverSigner = recoverSigner;
+exports.verifySignature = verifySignature;
+const ethers_1 = require("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
+ */
+async function signHash(hash, wallet) {
+    // 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
+ */
+function recoverSigner(hash, signature) {
+    return (0, ethers_1.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
+ */
+function verifySignature(hash, signature, expectedAddress) {
+    try {
+        const recoveredAddress = recoverSigner(hash, signature);
+        return recoveredAddress.toLowerCase() === expectedAddress.toLowerCase();
+    }
+    catch {
+        return false;
+    }
+}

package/dist/src/types.d.ts

@@ -0,0 +1,94 @@
+/**
+ * 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/dist/src/types.js

@@ -0,0 +1,8 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/src/validator.d.ts

@@ -0,0 +1,17 @@
+/**
+ * DRVC3 Schema Validator
+ * Uses ajv to validate DRVC3 receipts against the official schema
+ */
+import { DRVC3ValidationResult } from './types';
+/**
+ * Validates a DRVC3 receipt against the official schema
+ * @param receipt - The receipt object to validate
+ * @returns Validation result with errors if invalid
+ */
+export declare function validateDRVC3(receipt: unknown): DRVC3ValidationResult;
+/**
+ * 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 declare function isDRVC3Receipt(obj: unknown): boolean;

package/dist/src/validator.js

@@ -0,0 +1,82 @@
+"use strict";
+/**
+ * DRVC3 Schema Validator
+ * Uses ajv to validate DRVC3 receipts against the official schema
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateDRVC3 = validateDRVC3;
+exports.isDRVC3Receipt = isDRVC3Receipt;
+const ajv_1 = __importDefault(require("ajv"));
+const path = __importStar(require("path"));
+const fs = __importStar(require("fs"));
+// 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_1.default({ 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
+ */
+function validateDRVC3(receipt) {
+    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
+ */
+function isDRVC3Receipt(obj) {
+    return validateDRVC3(obj).valid;
+}

package/dist/src/wrapper.d.ts

@@ -0,0 +1,41 @@
+/**
+ * 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 } from 'ethers';
+import { DRVC3Receipt, WrapOptions } from './types';
+/**
+ * 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 declare function wrapInDRVC3(deltaReceipt: DeltaReceipt, signer: Wallet | HDNodeWallet, options: WrapOptions): Promise<DRVC3Receipt>;
+/**
+ * Extracts the original DeltaReceipt from a DRVC3 envelope
+ *
+ * @param drvc3 - DRVC3 receipt envelope
+ * @returns The embedded DeltaReceipt
+ */
+export declare function extractDeltaReceipt(drvc3: DRVC3Receipt): DeltaReceipt;

package/dist/src/wrapper.js

@@ -0,0 +1,92 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.wrapInDRVC3 = wrapInDRVC3;
+exports.extractDeltaReceipt = extractDeltaReceipt;
+const signer_1 = require("./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'
+ * });
+ * ```
+ */
+async function wrapInDRVC3(deltaReceipt, signer, options) {
+    // 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 (0, signer_1.signHash)(hash, signer);
+    // 4. Construct DRVC3 envelope
+    const drvc3 = {
+        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
+ */
+function extractDeltaReceipt(drvc3) {
+    return drvc3.validation.checks.delta_receipt;
+}

package/dist/tests/integration.test.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Integration Tests
+ * Tests the full flow from DeltaBundle → DeltaReceipt → DRVC3Receipt
+ */
+export {};

package/dist/tests/integration.test.js

@@ -0,0 +1,105 @@
+"use strict";
+/**
+ * Integration Tests
+ * Tests the full flow from DeltaBundle → DeltaReceipt → DRVC3Receipt
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+const ethers_1 = require("ethers");
+const core_1 = require("@uvrn/core");
+const src_1 = require("../src");
+describe('Integration: Layer 1 → Layer 2', () => {
+    let testWallet;
+    beforeAll(() => {
+        testWallet = ethers_1.Wallet.createRandom();
+    });
+    it('should complete full flow: bundle → receipt → DRVC3', async () => {
+        // 1. Create a DeltaBundle (input to Layer 1)
+        const bundle = {
+            bundleId: 'integration-test-001',
+            claim: 'Integration Test',
+            thresholdPct: 0.1,
+            dataSpecs: [
+                {
+                    id: 'source-1',
+                    label: 'Source 1',
+                    sourceKind: 'metric',
+                    originDocIds: ['doc-1'],
+                    metrics: [
+                        { key: 'revenue', value: 1000 },
+                        { key: 'users', value: 500 }
+                    ]
+                },
+                {
+                    id: 'source-2',
+                    label: 'Source 2',
+                    sourceKind: 'metric',
+                    originDocIds: ['doc-2'],
+                    metrics: [
+                        { key: 'revenue', value: 1050 },
+                        { key: 'users', value: 510 }
+                    ]
+                }
+            ]
+        };
+        // 2. Run Layer 1 Engine
+        const deltaReceipt = (0, core_1.runDeltaEngine)(bundle);
+        // Verify Layer 1 receipt
+        const verifyResult = (0, core_1.verifyReceipt)(deltaReceipt);
+        expect(verifyResult.verified).toBe(true);
+        // 3. Wrap in DRVC3 (Layer 2)
+        const drvc3 = await (0, src_1.wrapInDRVC3)(deltaReceipt, testWallet, {
+            issuer: 'uvrn-integration',
+            event: 'delta-reconciliation',
+            tags: ['#uvrn', '#integration-test']
+        });
+        // 4. Validate DRVC3 schema
+        const schemaResult = (0, src_1.validateDRVC3)(drvc3);
+        expect(schemaResult.valid).toBe(true);
+        // 5. Verify hash chain integrity
+        expect(drvc3.integrity.hash).toBe(deltaReceipt.hash);
+        // 6. Extract and verify embedded receipt
+        const extracted = (0, src_1.extractDeltaReceipt)(drvc3);
+        expect(extracted.hash).toBe(deltaReceipt.hash);
+        expect((0, core_1.verifyReceipt)(extracted).verified).toBe(true);
+    });
+    it('should maintain hash integrity through Layer 2 wrapping', async () => {
+        const bundle = {
+            bundleId: 'hash-integrity-test',
+            claim: 'Hash Test',
+            thresholdPct: 0.05,
+            dataSpecs: [
+                {
+                    id: 'a',
+                    label: 'A',
+                    sourceKind: 'metric',
+                    originDocIds: [],
+                    metrics: [{ key: 'val', value: 100 }]
+                },
+                {
+                    id: 'b',
+                    label: 'B',
+                    sourceKind: 'metric',
+                    originDocIds: [],
+                    metrics: [{ key: 'val', value: 100 }]
+                }
+            ]
+        };
+        const receipt = (0, core_1.runDeltaEngine)(bundle);
+        const originalHash = receipt.hash;
+        // Wrap multiple times - hash should always match
+        const drvc3_1 = await (0, src_1.wrapInDRVC3)(receipt, testWallet, {
+            issuer: 'test',
+            event: 'test'
+        });
+        const drvc3_2 = await (0, src_1.wrapInDRVC3)(receipt, testWallet, {
+            issuer: 'test',
+            event: 'test'
+        });
+        // Envelope metadata differs (receipt_id, timestamp)
+        expect(drvc3_1.receipt_id).not.toBe(drvc3_2.receipt_id);
+        expect(drvc3_1.timestamp).not.toBe(drvc3_2.timestamp);
+        // But hash domain remains identical
+        expect(drvc3_1.integrity.hash).toBe(originalHash);
+        expect(drvc3_2.integrity.hash).toBe(originalHash);
+    });
+});

package/dist/tests/wrapper.test.d.ts

@@ -0,0 +1,5 @@
+/**
+ * DRVC3 Wrapper Tests
+ * Tests the wrapInDRVC3 function and schema validation
+ */
+export {};