@brightchain/brightchain-lib 0.1.5 → 0.1.6

package/src/lib/interfaces/availability/locationRecord.js

@@ -0,0 +1,199 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createDefaultLocationMetadata = createDefaultLocationMetadata;
+exports.locationRecordToJSON = locationRecordToJSON;
+exports.locationRecordFromJSON = locationRecordFromJSON;
+exports.blockMetadataWithLocationToJSON = blockMetadataWithLocationToJSON;
+exports.blockMetadataWithLocationFromJSON = blockMetadataWithLocationFromJSON;
+const availabilityState_1 = require("../../enumerations/availabilityState");
+/**
+ * Create default location metadata for a new local block.
+ * Used when storing a block locally as the authoritative copy.
+ *
+ * @param localNodeId - The ID of the local node storing the block
+ * @returns Default location metadata fields for a new local block
+ */
+function createDefaultLocationMetadata(localNodeId) {
+    return {
+        availabilityState: availabilityState_1.AvailabilityState.Local,
+        locationRecords: [
+            {
+                nodeId: localNodeId,
+                lastSeen: new Date(),
+                isAuthoritative: true,
+            },
+        ],
+        locationUpdatedAt: new Date(),
+    };
+}
+/**
+ * Convert ILocationRecord to JSON-serializable format
+ * @param record - The location record to serialize
+ * @returns Serialized location record with Date fields as ISO strings
+ */
+function locationRecordToJSON(record) {
+    return {
+        nodeId: record.nodeId,
+        lastSeen: record.lastSeen.toISOString(),
+        isAuthoritative: record.isAuthoritative,
+        ...(record.latencyMs !== undefined && { latencyMs: record.latencyMs }),
+    };
+}
+/**
+ * Convert serialized location record back to ILocationRecord
+ * @param serialized - The serialized location record
+ * @returns Location record with Date objects
+ * @throws Error if validation fails
+ */
+function locationRecordFromJSON(serialized) {
+    // Validate required fields
+    if (!serialized.nodeId || typeof serialized.nodeId !== 'string') {
+        throw new Error('Invalid location record: nodeId is required and must be a string');
+    }
+    if (!serialized.lastSeen || typeof serialized.lastSeen !== 'string') {
+        throw new Error('Invalid location record: lastSeen is required and must be a string');
+    }
+    if (typeof serialized.isAuthoritative !== 'boolean') {
+        throw new Error('Invalid location record: isAuthoritative is required and must be a boolean');
+    }
+    // Validate and parse date
+    const lastSeen = new Date(serialized.lastSeen);
+    if (isNaN(lastSeen.getTime())) {
+        throw new Error('Invalid location record: lastSeen is not a valid ISO date string');
+    }
+    // Validate optional latencyMs
+    if (serialized.latencyMs !== undefined) {
+        if (typeof serialized.latencyMs !== 'number' || serialized.latencyMs < 0) {
+            throw new Error('Invalid location record: latencyMs must be a non-negative number');
+        }
+    }
+    return {
+        nodeId: serialized.nodeId,
+        lastSeen,
+        isAuthoritative: serialized.isAuthoritative,
+        ...(serialized.latencyMs !== undefined && {
+            latencyMs: serialized.latencyMs,
+        }),
+    };
+}
+/**
+ * Convert IBlockMetadataWithLocation to JSON-serializable format
+ * @param metadata - The block metadata with location to serialize
+ * @returns Serialized metadata with Date fields as ISO strings
+ */
+function blockMetadataWithLocationToJSON(metadata) {
+    return {
+        blockId: metadata.blockId,
+        createdAt: metadata.createdAt.toISOString(),
+        expiresAt: metadata.expiresAt ? metadata.expiresAt.toISOString() : null,
+        durabilityLevel: metadata.durabilityLevel,
+        parityBlockIds: [...metadata.parityBlockIds],
+        accessCount: metadata.accessCount,
+        lastAccessedAt: metadata.lastAccessedAt.toISOString(),
+        replicationStatus: metadata.replicationStatus,
+        targetReplicationFactor: metadata.targetReplicationFactor,
+        replicaNodeIds: [...metadata.replicaNodeIds],
+        size: metadata.size,
+        checksum: metadata.checksum,
+        availabilityState: metadata.availabilityState,
+        locationRecords: metadata.locationRecords.map(locationRecordToJSON),
+        locationUpdatedAt: metadata.locationUpdatedAt.toISOString(),
+    };
+}
+/**
+ * Convert serialized block metadata back to IBlockMetadataWithLocation
+ * @param serialized - The serialized block metadata
+ * @returns Block metadata with Date objects
+ * @throws Error if validation fails
+ */
+function blockMetadataWithLocationFromJSON(serialized) {
+    // Validate required fields from base IBlockMetadata
+    if (!serialized.blockId || typeof serialized.blockId !== 'string') {
+        throw new Error('Invalid metadata: blockId is required and must be a string');
+    }
+    if (!serialized.createdAt || typeof serialized.createdAt !== 'string') {
+        throw new Error('Invalid metadata: createdAt is required and must be a string');
+    }
+    if (!serialized.lastAccessedAt ||
+        typeof serialized.lastAccessedAt !== 'string') {
+        throw new Error('Invalid metadata: lastAccessedAt is required and must be a string');
+    }
+    if (!serialized.locationUpdatedAt ||
+        typeof serialized.locationUpdatedAt !== 'string') {
+        throw new Error('Invalid metadata: locationUpdatedAt is required and must be a string');
+    }
+    // Validate and parse dates
+    const createdAt = new Date(serialized.createdAt);
+    if (isNaN(createdAt.getTime())) {
+        throw new Error('Invalid metadata: createdAt is not a valid ISO date string');
+    }
+    const lastAccessedAt = new Date(serialized.lastAccessedAt);
+    if (isNaN(lastAccessedAt.getTime())) {
+        throw new Error('Invalid metadata: lastAccessedAt is not a valid ISO date string');
+    }
+    const locationUpdatedAt = new Date(serialized.locationUpdatedAt);
+    if (isNaN(locationUpdatedAt.getTime())) {
+        throw new Error('Invalid metadata: locationUpdatedAt is not a valid ISO date string');
+    }
+    let expiresAt = null;
+    if (serialized.expiresAt !== null) {
+        expiresAt = new Date(serialized.expiresAt);
+        if (isNaN(expiresAt.getTime())) {
+            throw new Error('Invalid metadata: expiresAt is not a valid ISO date string');
+        }
+    }
+    // Validate availability state
+    const validStates = Object.values(availabilityState_1.AvailabilityState);
+    if (!validStates.includes(serialized.availabilityState)) {
+        throw new Error(`Invalid metadata: availabilityState must be one of ${validStates.join(', ')}`);
+    }
+    // Validate and deserialize location records
+    if (!Array.isArray(serialized.locationRecords)) {
+        throw new Error('Invalid metadata: locationRecords must be an array');
+    }
+    const locationRecords = serialized.locationRecords.map((record, index) => {
+        try {
+            return locationRecordFromJSON(record);
+        }
+        catch (error) {
+            throw new Error(`Invalid metadata: locationRecords[${index}] - ${error instanceof Error ? error.message : String(error)}`);
+        }
+    });
+    // Validate numeric fields
+    if (typeof serialized.accessCount !== 'number' ||
+        serialized.accessCount < 0) {
+        throw new Error('Invalid metadata: accessCount must be a non-negative number');
+    }
+    if (typeof serialized.targetReplicationFactor !== 'number' ||
+        serialized.targetReplicationFactor < 0) {
+        throw new Error('Invalid metadata: targetReplicationFactor must be a non-negative number');
+    }
+    if (typeof serialized.size !== 'number' || serialized.size < 0) {
+        throw new Error('Invalid metadata: size must be a non-negative number');
+    }
+    // Validate arrays
+    if (!Array.isArray(serialized.parityBlockIds)) {
+        throw new Error('Invalid metadata: parityBlockIds must be an array');
+    }
+    if (!Array.isArray(serialized.replicaNodeIds)) {
+        throw new Error('Invalid metadata: replicaNodeIds must be an array');
+    }
+    return {
+        blockId: serialized.blockId,
+        createdAt,
+        expiresAt,
+        durabilityLevel: serialized.durabilityLevel,
+        parityBlockIds: [...serialized.parityBlockIds],
+        accessCount: serialized.accessCount,
+        lastAccessedAt,
+        replicationStatus: serialized.replicationStatus,
+        targetReplicationFactor: serialized.targetReplicationFactor,
+        replicaNodeIds: [...serialized.replicaNodeIds],
+        size: serialized.size,
+        checksum: serialized.checksum,
+        availabilityState: serialized.availabilityState,
+        locationRecords,
+        locationUpdatedAt,
+    };
+}
+//# sourceMappingURL=locationRecord.js.map

package/src/lib/interfaces/availability/locationRecord.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"locationRecord.js","sourceRoot":"","sources":["../../../../../../brightchain-lib/src/lib/interfaces/availability/locationRecord.ts"],"names":[],"mappings":"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"}

package/src/lib/interfaces/availability/reconciliationService.d.ts

@@ -0,0 +1,310 @@
+/**
+ * @fileoverview Reconciliation Service Interface
+ *
+ * Defines the interface for state synchronization after network reconnection.
+ * Handles manifest exchange, pending sync queue processing, orphan resolution,
+ * and conflict resolution using last-write-wins with vector timestamps.
+ *
+ * @see Requirements 9.1, 9.2, 9.3, 9.4, 9.5, 9.6, 9.7, 9.8, 10.1, 10.2, 10.3, 10.4, 10.5
+ */
+/**
+ * Sync vector entry for tracking synchronization state with a peer.
+ * Used for delta synchronization to request only changes since last sync.
+ *
+ * @see Requirements 10.1, 10.2, 10.3
+ */
+export interface SyncVectorEntry {
+    /**
+     * The peer ID this entry tracks
+     */
+    peerId: string;
+    /**
+     * Timestamp of the last successful synchronization with this peer
+     */
+    lastSyncTimestamp: Date;
+    /**
+     * Checksum of the last manifest received from this peer
+     */
+    lastManifestChecksum: string;
+}
+/**
+ * Item in the pending sync queue.
+ * Tracks local changes made during partition mode for later synchronization.
+ *
+ * @see Requirements 8.3, 8.5
+ */
+export interface PendingSyncItem {
+    /**
+     * Type of operation:
+     * - 'store': A block was stored locally
+     * - 'delete': A block was deleted locally
+     * - 'replicate': A block needs to be replicated to peers
+     */
+    type: 'store' | 'delete' | 'replicate';
+    /**
+     * The block ID affected by this operation
+     */
+    blockId: string;
+    /**
+     * Timestamp when the operation occurred
+     */
+    timestamp: Date;
+    /**
+     * Optional block data for store operations
+     */
+    data?: Uint8Array;
+}
+/**
+ * Error that occurred during reconciliation.
+ *
+ * @see Requirements 9.8
+ */
+export interface ReconciliationError {
+    /**
+     * The peer ID where the error occurred (if applicable)
+     */
+    peerId?: string;
+    /**
+     * The block ID involved in the error (if applicable)
+     */
+    blockId?: string;
+    /**
+     * Description of the error
+     */
+    error: string;
+}
+/**
+ * Result of a reconciliation operation.
+ *
+ * @see Requirements 9.7
+ */
+export interface ReconciliationResult {
+    /**
+     * Whether reconciliation completed successfully
+     */
+    success: boolean;
+    /**
+     * Number of peers that were reconciled with
+     */
+    peersReconciled: number;
+    /**
+     * Number of new blocks discovered during reconciliation
+     */
+    blocksDiscovered: number;
+    /**
+     * Number of blocks whose location metadata was updated
+     */
+    blocksUpdated: number;
+    /**
+     * Number of orphaned blocks that were resolved (found sources)
+     */
+    orphansResolved: number;
+    /**
+     * Number of conflicts that were resolved
+     */
+    conflictsResolved: number;
+    /**
+     * Errors that occurred during reconciliation
+     */
+    errors: ReconciliationError[];
+    /**
+     * Total duration of reconciliation in milliseconds
+     */
+    duration: number;
+}
+/**
+ * Configuration for the reconciliation service.
+ *
+ * @see Requirements 9.1, 10.1
+ */
+export interface ReconciliationConfig {
+    /**
+     * Timeout for manifest exchange operations in milliseconds
+     */
+    manifestExchangeTimeoutMs: number;
+    /**
+     * Maximum number of concurrent peer reconciliations
+     */
+    maxConcurrentReconciliations: number;
+    /**
+     * Path for persisting sync vectors
+     */
+    syncVectorPath: string;
+    /**
+     * Path for persisting pending sync queue
+     */
+    pendingSyncQueuePath: string;
+    /**
+     * Maximum items in pending sync queue before forcing flush
+     */
+    maxPendingSyncQueueSize: number;
+}
+/**
+ * Default reconciliation configuration values.
+ */
+export declare const DEFAULT_RECONCILIATION_CONFIG: ReconciliationConfig;
+/**
+ * Handler function type for reconciliation events.
+ */
+export type ReconciliationEventHandler = (event: ReconciliationEvent) => void;
+/**
+ * Events emitted during reconciliation.
+ */
+export type ReconciliationEvent = {
+    type: 'reconciliation_started';
+    timestamp: Date;
+    peerIds: string[];
+} | {
+    type: 'peer_reconciliation_started';
+    timestamp: Date;
+    peerId: string;
+} | {
+    type: 'peer_reconciliation_completed';
+    timestamp: Date;
+    peerId: string;
+    blocksDiscovered: number;
+} | {
+    type: 'peer_reconciliation_failed';
+    timestamp: Date;
+    peerId: string;
+    error: string;
+} | {
+    type: 'orphan_resolved';
+    timestamp: Date;
+    blockId: string;
+    sourceNodeId: string;
+} | {
+    type: 'conflict_resolved';
+    timestamp: Date;
+    blockId: string;
+    winningNodeId: string;
+} | {
+    type: 'reconciliation_completed';
+    timestamp: Date;
+    result: ReconciliationResult;
+};
+/**
+ * Reconciliation Service Interface
+ *
+ * Handles state synchronization after network reconnection.
+ * Implements manifest exchange, pending sync queue processing,
+ * orphan resolution, and conflict resolution.
+ *
+ * @see Requirements 9.1, 9.2, 9.3, 9.4, 9.5, 9.6, 9.7, 9.8, 10.1, 10.2, 10.3, 10.4, 10.5
+ */
+export interface IReconciliationService {
+    /**
+     * Start reconciliation with reconnected peers.
+     * Exchanges manifests, updates location metadata, processes pending sync queue,
+     * and resolves orphaned blocks.
+     *
+     * @param peerIds - Array of peer IDs to reconcile with
+     * @returns Promise resolving to reconciliation result
+     * @see Requirements 9.1, 9.2, 9.3, 9.4, 9.5, 9.6, 9.7
+     */
+    reconcile(peerIds: string[]): Promise<ReconciliationResult>;
+    /**
+     * Get the sync vector entry for a specific peer.
+     *
+     * @param peerId - The peer ID to get sync vector for
+     * @returns The sync vector entry or null if not found
+     * @see Requirements 10.1
+     */
+    getSyncVector(peerId: string): SyncVectorEntry | null;
+    /**
+     * Get all sync vector entries.
+     *
+     * @returns Map of peer IDs to sync vector entries
+     * @see Requirements 10.1
+     */
+    getAllSyncVectors(): Map<string, SyncVectorEntry>;
+    /**
+     * Update the sync vector for a peer after successful synchronization.
+     *
+     * @param peerId - The peer ID to update
+     * @param timestamp - The timestamp of the sync
+     * @param manifestChecksum - The checksum of the peer's manifest
+     * @see Requirements 10.3
+     */
+    updateSyncVector(peerId: string, timestamp: Date, manifestChecksum: string): void;
+    /**
+     * Initialize sync vector for a new peer.
+     *
+     * @param peerId - The peer ID to initialize
+     * @see Requirements 10.4
+     */
+    initializeSyncVector(peerId: string): void;
+    /**
+     * Get the pending sync queue.
+     *
+     * @returns Array of pending sync items
+     * @see Requirements 8.5
+     */
+    getPendingSyncQueue(): PendingSyncItem[];
+    /**
+     * Add an item to the pending sync queue.
+     * Called when local changes are made during partition mode.
+     *
+     * @param item - The item to add to the queue
+     * @see Requirements 8.3, 8.5
+     */
+    addToPendingSyncQueue(item: PendingSyncItem): void;
+    /**
+     * Process the pending sync queue.
+     * Sends queued operations to connected peers.
+     *
+     * @returns Promise that resolves when queue is processed
+     * @see Requirements 9.4
+     */
+    processPendingSyncQueue(): Promise<void>;
+    /**
+     * Clear the pending sync queue.
+     * Called after successful processing.
+     */
+    clearPendingSyncQueue(): void;
+    /**
+     * Persist sync vectors to disk.
+     *
+     * @returns Promise that resolves when persistence is complete
+     * @see Requirements 10.5
+     */
+    persistSyncVectors(): Promise<void>;
+    /**
+     * Load sync vectors from disk.
+     *
+     * @returns Promise that resolves when loading is complete
+     * @see Requirements 10.5
+     */
+    loadSyncVectors(): Promise<void>;
+    /**
+     * Persist pending sync queue to disk.
+     *
+     * @returns Promise that resolves when persistence is complete
+     */
+    persistPendingSyncQueue(): Promise<void>;
+    /**
+     * Load pending sync queue from disk.
+     *
+     * @returns Promise that resolves when loading is complete
+     */
+    loadPendingSyncQueue(): Promise<void>;
+    /**
+     * Subscribe to reconciliation events.
+     *
+     * @param handler - Function to call when events occur
+     */
+    onEvent(handler: ReconciliationEventHandler): void;
+    /**
+     * Remove a reconciliation event handler.
+     *
+     * @param handler - The handler to remove
+     */
+    offEvent(handler: ReconciliationEventHandler): void;
+    /**
+     * Get the current configuration.
+     *
+     * @returns The reconciliation configuration
+     */
+    getConfig(): ReconciliationConfig;
+}
+//# sourceMappingURL=reconciliationService.d.ts.map

package/src/lib/interfaces/availability/reconciliationService.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reconciliationService.d.ts","sourceRoot":"","sources":["../../../../../../brightchain-lib/src/lib/interfaces/availability/reconciliationService.ts"],"names":[],"mappings":"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"}

package/src/lib/interfaces/availability/reconciliationService.js

@@ -0,0 +1,23 @@
+"use strict";
+/**
+ * @fileoverview Reconciliation Service Interface
+ *
+ * Defines the interface for state synchronization after network reconnection.
+ * Handles manifest exchange, pending sync queue processing, orphan resolution,
+ * and conflict resolution using last-write-wins with vector timestamps.
+ *
+ * @see Requirements 9.1, 9.2, 9.3, 9.4, 9.5, 9.6, 9.7, 9.8, 10.1, 10.2, 10.3, 10.4, 10.5
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_RECONCILIATION_CONFIG = void 0;
+/**
+ * Default reconciliation configuration values.
+ */
+exports.DEFAULT_RECONCILIATION_CONFIG = {
+    manifestExchangeTimeoutMs: 30000,
+    maxConcurrentReconciliations: 5,
+    syncVectorPath: 'sync-vectors.json',
+    pendingSyncQueuePath: 'pending-sync-queue.json',
+    maxPendingSyncQueueSize: 1000,
+};
+//# sourceMappingURL=reconciliationService.js.map

package/src/lib/interfaces/availability/reconciliationService.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reconciliationService.js","sourceRoot":"","sources":["../../../../../../brightchain-lib/src/lib/interfaces/availability/reconciliationService.ts"],"names":[],"mappings":";AAAA;;;;;;;;GAQG;;;AA6JH;;GAEG;AACU,QAAA,6BAA6B,GAAyB;IACjE,yBAAyB,EAAE,KAAK;IAChC,4BAA4B,EAAE,CAAC;IAC/B,cAAc,EAAE,mBAAmB;IACnC,oBAAoB,EAAE,yBAAyB;IAC/C,uBAAuB,EAAE,IAAI;CAC9B,CAAC"}

package/src/lib/interfaces/backupCodeConsts.d.ts

@@ -1,9 +1,35 @@
+/**
+ * Constants for backup code generation and validation
+ *
+ * @remarks
+ * Backup codes provide an alternative authentication method when primary
+ * methods are unavailable. These constants control code generation and
+ * validation patterns.
+ *
+ * @example
+ * ```typescript
+ * const backupCodeConsts: IBackupCodeConstants = {
+ *   Count: 10,
+ *   NormalizedHexRegex: /^[0-9a-f]{16}$/,
+ *   DisplayRegex: /^[0-9A-F]{4}-[0-9A-F]{4}-[0-9A-F]{4}-[0-9A-F]{4}$/
+ * };
+ * ```
+ */
 export interface IBackupCodeConstants {
     /**
      * How many backup codes to generate for users
+     * @remarks Typically 8-12 codes to provide sufficient backup options
      */
     Count: number;
+    /**
+     * Regular expression for validating normalized hex backup codes
+     * @remarks Normalized codes are lowercase hex without separators
+     */
     NormalizedHexRegex: RegExp;
+    /**
+     * Regular expression for validating display-formatted backup codes
+     * @remarks Display codes typically include hyphens for readability
+     */
     DisplayRegex: RegExp;
 }
 //# sourceMappingURL=backupCodeConsts.d.ts.map

package/src/lib/interfaces/backupCodeConsts.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"backupCodeConsts.d.ts","sourceRoot":"","sources":["../../../../../brightchain-lib/src/lib/interfaces/backupCodeConsts.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,oBAAoB;IACnC;;OAEG;IACH,KAAK,EAAE,MAAM,CAAC;IACd,kBAAkB,EAAE,MAAM,CAAC;IAC3B,YAAY,EAAE,MAAM,CAAC;CACtB"}
+{"version":3,"file":"backupCodeConsts.d.ts","sourceRoot":"","sources":["../../../../../brightchain-lib/src/lib/interfaces/backupCodeConsts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,oBAAoB;IACnC;;;OAGG;IACH,KAAK,EAAE,MAAM,CAAC;IAEd;;;OAGG;IACH,kBAAkB,EAAE,MAAM,CAAC;IAE3B;;;OAGG;IACH,YAAY,EAAE,MAAM,CAAC;CACtB"}

package/src/lib/interfaces/basicObjectDto.d.ts

@@ -1,4 +1,30 @@
 import { PlatformID } from '@digitaldefiance/ecies-lib';
+/**
+ * Basic data transfer object with ID and creation date
+ *
+ * @remarks
+ * This is the base interface for all DTOs in the system. It provides
+ * common fields that all data objects should have: a unique identifier
+ * and a creation timestamp.
+ *
+ * @typeParam TID - The type used for the ID field (defaults to Uint8Array)
+ * @typeParam D - The type used for dates (Date or string, defaults to Date)
+ *
+ * @example
+ * ```typescript
+ * // Using default types
+ * const dto: IBasicObjectDTO = {
+ *   id: new Uint8Array([1, 2, 3]),
+ *   dateCreated: new Date()
+ * };
+ *
+ * // Using string ID and ISO date string
+ * const stringDto: IBasicObjectDTO<string, string> = {
+ *   id: 'abc-123',
+ *   dateCreated: '2024-01-01T00:00:00Z'
+ * };
+ * ```
+ */
 export interface IBasicObjectDTO<TID extends PlatformID = Uint8Array, D extends Date | string = Date> {
     /**
      * ID of the data object. Must be unique, usually UUID v4.

package/src/lib/interfaces/basicObjectDto.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"basicObjectDto.d.ts","sourceRoot":"","sources":["../../../../../brightchain-lib/src/lib/interfaces/basicObjectDto.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AAExD,MAAM,WAAW,eAAe,CAC9B,GAAG,SAAS,UAAU,GAAG,UAAU,EACnC,CAAC,SAAS,IAAI,GAAG,MAAM,GAAG,IAAI;IAE9B;;OAEG;IACH,EAAE,EAAE,GAAG,CAAC;IACR;;OAEG;IACH,WAAW,EAAE,CAAC,CAAC;CAChB"}
+{"version":3,"file":"basicObjectDto.d.ts","sourceRoot":"","sources":["../../../../../brightchain-lib/src/lib/interfaces/basicObjectDto.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AAExD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,WAAW,eAAe,CAC9B,GAAG,SAAS,UAAU,GAAG,UAAU,EACnC,CAAC,SAAS,IAAI,GAAG,MAAM,GAAG,IAAI;IAE9B;;OAEG;IACH,EAAE,EAAE,GAAG,CAAC;IACR;;OAEG;IACH,WAAW,EAAE,CAAC,CAAC;CAChB"}