@brightchain/brightchain-lib 0.1.5 → 0.1.7

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

@@ -0,0 +1,23 @@
+"use strict";
+/**
+ * @fileoverview Discovery Protocol Interface
+ *
+ * Defines the interface for discovering blocks across the network.
+ * Supports Bloom filter pre-checks, concurrent query limiting,
+ * result caching, and latency-based node preference.
+ *
+ * @see Requirements 5.1, 5.2, 5.3, 5.4, 5.5, 5.6, 5.7, 5.8
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_DISCOVERY_CONFIG = void 0;
+/**
+ * Default discovery configuration values.
+ */
+exports.DEFAULT_DISCOVERY_CONFIG = {
+    queryTimeoutMs: 5000,
+    maxConcurrentQueries: 10,
+    cacheTtlMs: 60000,
+    bloomFilterFalsePositiveRate: 0.01,
+    bloomFilterHashCount: 7,
+};
+//# sourceMappingURL=discoveryProtocol.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"discoveryProtocol.js","sourceRoot":"","sources":["../../../../../../brightchain-lib/src/lib/interfaces/availability/discoveryProtocol.ts"],"names":[],"mappings":";AAAA;;;;;;;;GAQG;;;AAiHH;;GAEG;AACU,QAAA,wBAAwB,GAAoB;IACvD,cAAc,EAAE,IAAI;IACpB,oBAAoB,EAAE,EAAE;IACxB,UAAU,EAAE,KAAK;IACjB,4BAA4B,EAAE,IAAI;IAClC,oBAAoB,EAAE,CAAC;CACxB,CAAC"}

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

@@ -0,0 +1,166 @@
+/**
+ * @fileoverview Gossip Service Interface
+ *
+ * Defines the interface for gossip-based block announcements across the network.
+ * Enables nodes to announce new blocks and removals to peers, supporting
+ * efficient block discovery without polling.
+ *
+ * @see Requirements 6.1, 6.2, 6.3, 6.4, 6.5, 6.6
+ */
+/**
+ * Block announcement message sent via gossip protocol.
+ * Contains information about a block being added or removed from a node.
+ *
+ * @see Requirements 6.1, 6.5
+ */
+export interface BlockAnnouncement {
+    /**
+     * Type of announcement: 'add' for new blocks, 'remove' for deleted blocks
+     */
+    type: 'add' | 'remove';
+    /**
+     * The block ID being announced (hex string)
+     */
+    blockId: string;
+    /**
+     * The node ID that originated this announcement
+     */
+    nodeId: string;
+    /**
+     * Timestamp when the announcement was created
+     */
+    timestamp: Date;
+    /**
+     * Time-to-live: number of hops remaining before the announcement expires.
+     * Decremented on each forward. Announcements with TTL=0 are not forwarded.
+     *
+     * @see Requirements 6.4
+     */
+    ttl: number;
+}
+/**
+ * Configuration for the gossip protocol.
+ *
+ * @see Requirements 6.3, 6.4, 6.6
+ */
+export interface GossipConfig {
+    /**
+     * Number of peers to forward announcements to (fanout).
+     * Higher values increase propagation speed but also network traffic.
+     *
+     * @see Requirements 6.3
+     */
+    fanout: number;
+    /**
+     * Initial TTL for new announcements.
+     * Controls how far announcements propagate through the network.
+     *
+     * @see Requirements 6.4
+     */
+    defaultTtl: number;
+    /**
+     * Interval in milliseconds between batch flushes.
+     * Announcements are batched within this interval to reduce network overhead.
+     *
+     * @see Requirements 6.6
+     */
+    batchIntervalMs: number;
+    /**
+     * Maximum number of announcements per batch.
+     * Prevents batches from growing too large.
+     *
+     * @see Requirements 6.6
+     */
+    maxBatchSize: number;
+}
+/**
+ * Default gossip configuration values.
+ */
+export declare const DEFAULT_GOSSIP_CONFIG: GossipConfig;
+/**
+ * Handler function type for announcement events.
+ */
+export type AnnouncementHandler = (announcement: BlockAnnouncement) => void;
+/**
+ * Gossip Service Interface
+ *
+ * Handles gossip-based block announcements across the network.
+ * Supports announcing new blocks and removals, handling incoming announcements,
+ * and batching announcements for efficient network usage.
+ *
+ * @see Requirements 6.1, 6.2, 6.3, 6.4, 6.5, 6.6
+ */
+export interface IGossipService {
+    /**
+     * Announce a new block to the network.
+     * The announcement will be batched and sent to a random subset of peers.
+     *
+     * @param blockId - The block ID to announce
+     * @returns Promise that resolves when the announcement is queued
+     * @see Requirements 6.1
+     */
+    announceBlock(blockId: string): Promise<void>;
+    /**
+     * Announce block removal to the network.
+     * The announcement will be batched and sent to a random subset of peers.
+     *
+     * @param blockId - The block ID being removed
+     * @returns Promise that resolves when the announcement is queued
+     * @see Requirements 6.5
+     */
+    announceRemoval(blockId: string): Promise<void>;
+    /**
+     * Handle an incoming block announcement from a peer.
+     * Updates local location metadata and optionally forwards the announcement.
+     *
+     * @param announcement - The received announcement
+     * @returns Promise that resolves when the announcement is processed
+     * @see Requirements 6.2, 6.4
+     */
+    handleAnnouncement(announcement: BlockAnnouncement): Promise<void>;
+    /**
+     * Subscribe to announcement events.
+     * The handler will be called for each announcement received from peers.
+     *
+     * @param handler - Function to call when an announcement is received
+     * @see Requirements 6.2
+     */
+    onAnnouncement(handler: AnnouncementHandler): void;
+    /**
+     * Remove an announcement handler.
+     *
+     * @param handler - The handler to remove
+     */
+    offAnnouncement(handler: AnnouncementHandler): void;
+    /**
+     * Get pending announcements that have not yet been sent.
+     * Useful for inspection and testing.
+     *
+     * @returns Array of pending announcements
+     * @see Requirements 6.6
+     */
+    getPendingAnnouncements(): BlockAnnouncement[];
+    /**
+     * Immediately flush all pending announcements.
+     * Sends batched announcements to peers without waiting for the batch interval.
+     *
+     * @returns Promise that resolves when all announcements are sent
+     * @see Requirements 6.6
+     */
+    flushAnnouncements(): Promise<void>;
+    /**
+     * Start the gossip service (begins batch timer).
+     */
+    start(): void;
+    /**
+     * Stop the gossip service (stops batch timer and flushes pending).
+     */
+    stop(): Promise<void>;
+    /**
+     * Get the current configuration.
+     *
+     * @returns The gossip configuration
+     */
+    getConfig(): GossipConfig;
+}
+//# sourceMappingURL=gossipService.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"gossipService.d.ts","sourceRoot":"","sources":["../../../../../../brightchain-lib/src/lib/interfaces/availability/gossipService.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC;;OAEG;IACH,IAAI,EAAE,KAAK,GAAG,QAAQ,CAAC;IAEvB;;OAEG;IACH,OAAO,EAAE,MAAM,CAAC;IAEhB;;OAEG;IACH,MAAM,EAAE,MAAM,CAAC;IAEf;;OAEG;IACH,SAAS,EAAE,IAAI,CAAC;IAEhB;;;;;OAKG;IACH,GAAG,EAAE,MAAM,CAAC;CACb;AAED;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B;;;;;OAKG;IACH,MAAM,EAAE,MAAM,CAAC;IAEf;;;;;OAKG;IACH,UAAU,EAAE,MAAM,CAAC;IAEnB;;;;;OAKG;IACH,eAAe,EAAE,MAAM,CAAC;IAExB;;;;;OAKG;IACH,YAAY,EAAE,MAAM,CAAC;CACtB;AAED;;GAEG;AACH,eAAO,MAAM,qBAAqB,EAAE,YAKnC,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,mBAAmB,GAAG,CAAC,YAAY,EAAE,iBAAiB,KAAK,IAAI,CAAC;AAE5E;;;;;;;;GAQG;AACH,MAAM,WAAW,cAAc;IAC7B;;;;;;;OAOG;IACH,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE9C;;;;;;;OAOG;IACH,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEhD;;;;;;;OAOG;IACH,kBAAkB,CAAC,YAAY,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEnE;;;;;;OAMG;IACH,cAAc,CAAC,OAAO,EAAE,mBAAmB,GAAG,IAAI,CAAC;IAEnD;;;;OAIG;IACH,eAAe,CAAC,OAAO,EAAE,mBAAmB,GAAG,IAAI,CAAC;IAEpD;;;;;;OAMG;IACH,uBAAuB,IAAI,iBAAiB,EAAE,CAAC;IAE/C;;;;;;OAMG;IACH,kBAAkB,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAEpC;;OAEG;IACH,KAAK,IAAI,IAAI,CAAC;IAEd;;OAEG;IACH,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAEtB;;;;OAIG;IACH,SAAS,IAAI,YAAY,CAAC;CAC3B"}

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

@@ -0,0 +1,22 @@
+"use strict";
+/**
+ * @fileoverview Gossip Service Interface
+ *
+ * Defines the interface for gossip-based block announcements across the network.
+ * Enables nodes to announce new blocks and removals to peers, supporting
+ * efficient block discovery without polling.
+ *
+ * @see Requirements 6.1, 6.2, 6.3, 6.4, 6.5, 6.6
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_GOSSIP_CONFIG = void 0;
+/**
+ * Default gossip configuration values.
+ */
+exports.DEFAULT_GOSSIP_CONFIG = {
+    fanout: 3,
+    defaultTtl: 3,
+    batchIntervalMs: 1000,
+    maxBatchSize: 100,
+};
+//# sourceMappingURL=gossipService.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"gossipService.js","sourceRoot":"","sources":["../../../../../../brightchain-lib/src/lib/interfaces/availability/gossipService.ts"],"names":[],"mappings":";AAAA;;;;;;;;GAQG;;;AA6EH;;GAEG;AACU,QAAA,qBAAqB,GAAiB;IACjD,MAAM,EAAE,CAAC;IACT,UAAU,EAAE,CAAC;IACb,eAAe,EAAE,IAAI;IACrB,YAAY,EAAE,GAAG;CAClB,CAAC"}

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

@@ -0,0 +1,179 @@
+/**
+ * @fileoverview Heartbeat Monitor Interface
+ *
+ * Defines the interface for monitoring peer connectivity through heartbeat messages.
+ * Enables nodes to detect network partitions and track peer reachability.
+ *
+ * @see Requirements 7.1, 7.2, 7.5
+ */
+/**
+ * Connectivity event types emitted by the heartbeat monitor.
+ *
+ * @see Requirements 7.2, 7.5, 7.7
+ */
+export interface ConnectivityEvent {
+    /**
+     * Type of connectivity change:
+     * - 'peer_connected': A single peer became reachable
+     * - 'peer_disconnected': A single peer became unreachable
+     * - 'all_disconnected': All peers became unreachable (partition detected)
+     * - 'some_reconnected': At least one peer reconnected after partition
+     */
+    type: 'peer_connected' | 'peer_disconnected' | 'all_disconnected' | 'some_reconnected';
+    /**
+     * The peer ID involved in the event (for peer_connected/peer_disconnected)
+     */
+    peerId?: string;
+    /**
+     * Timestamp when the event occurred
+     */
+    timestamp: Date;
+}
+/**
+ * Configuration for the heartbeat monitor.
+ *
+ * @see Requirements 7.1, 7.2
+ */
+export interface HeartbeatConfig {
+    /**
+     * Interval between heartbeat pings in milliseconds.
+     * Lower values detect failures faster but increase network traffic.
+     *
+     * @see Requirements 7.1
+     */
+    intervalMs: number;
+    /**
+     * Timeout for heartbeat response in milliseconds.
+     * If a peer doesn't respond within this time, the heartbeat is considered missed.
+     *
+     * @see Requirements 7.1
+     */
+    timeoutMs: number;
+    /**
+     * Number of consecutive missed heartbeats before marking a peer as unreachable.
+     * Higher values reduce false positives but increase detection latency.
+     *
+     * @see Requirements 7.2
+     */
+    missedThreshold: number;
+}
+/**
+ * Default heartbeat configuration values.
+ */
+export declare const DEFAULT_HEARTBEAT_CONFIG: HeartbeatConfig;
+/**
+ * Handler function type for connectivity events.
+ */
+export type ConnectivityEventHandler = (event: ConnectivityEvent) => void;
+/**
+ * Heartbeat Monitor Interface
+ *
+ * Monitors peer connectivity using periodic heartbeat messages.
+ * Detects network partitions when all peers become unreachable and
+ * triggers reconnection events when peers become available again.
+ *
+ * @see Requirements 7.1, 7.2, 7.5
+ */
+export interface IHeartbeatMonitor {
+    /**
+     * Start the heartbeat monitor.
+     * Begins sending periodic heartbeat pings to all known peers.
+     *
+     * @see Requirements 7.1
+     */
+    start(): void;
+    /**
+     * Stop the heartbeat monitor.
+     * Stops sending heartbeats and clears all tracking state.
+     */
+    stop(): void;
+    /**
+     * Check if the monitor is currently running.
+     *
+     * @returns True if the monitor is active
+     */
+    isRunning(): boolean;
+    /**
+     * Check if a specific peer is currently reachable.
+     *
+     * @param peerId - The peer ID to check
+     * @returns True if the peer is reachable (responding to heartbeats)
+     * @see Requirements 7.5
+     */
+    isPeerReachable(peerId: string): boolean;
+    /**
+     * Get all peers that are currently reachable.
+     *
+     * @returns Array of peer IDs that are responding to heartbeats
+     * @see Requirements 7.5
+     */
+    getReachablePeers(): string[];
+    /**
+     * Get all peers that are currently unreachable.
+     *
+     * @returns Array of peer IDs that have exceeded the missed threshold
+     * @see Requirements 7.5
+     */
+    getUnreachablePeers(): string[];
+    /**
+     * Get the number of consecutive missed heartbeats for a peer.
+     *
+     * @param peerId - The peer ID to check
+     * @returns Number of missed heartbeats, or 0 if peer is unknown
+     */
+    getMissedCount(peerId: string): number;
+    /**
+     * Add a peer to be monitored.
+     *
+     * @param peerId - The peer ID to start monitoring
+     */
+    addPeer(peerId: string): void;
+    /**
+     * Remove a peer from monitoring.
+     *
+     * @param peerId - The peer ID to stop monitoring
+     */
+    removePeer(peerId: string): void;
+    /**
+     * Get all peers being monitored.
+     *
+     * @returns Array of all peer IDs being monitored
+     */
+    getMonitoredPeers(): string[];
+    /**
+     * Subscribe to connectivity change events.
+     * The handler will be called when peer connectivity changes.
+     *
+     * @param handler - Function to call when connectivity changes
+     * @see Requirements 7.2, 7.5, 7.7
+     */
+    onConnectivityChange(handler: ConnectivityEventHandler): void;
+    /**
+     * Remove a connectivity change handler.
+     *
+     * @param handler - The handler to remove
+     */
+    offConnectivityChange(handler: ConnectivityEventHandler): void;
+    /**
+     * Record a successful heartbeat response from a peer.
+     * Called when a pong is received in response to a ping.
+     *
+     * @param peerId - The peer that responded
+     * @param latencyMs - Round-trip latency in milliseconds
+     */
+    recordHeartbeatResponse(peerId: string, latencyMs: number): void;
+    /**
+     * Get the last recorded latency for a peer.
+     *
+     * @param peerId - The peer ID to check
+     * @returns Last recorded latency in milliseconds, or undefined if unknown
+     */
+    getLastLatency(peerId: string): number | undefined;
+    /**
+     * Get the current configuration.
+     *
+     * @returns The heartbeat configuration
+     */
+    getConfig(): HeartbeatConfig;
+}
+//# sourceMappingURL=heartbeatMonitor.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"heartbeatMonitor.d.ts","sourceRoot":"","sources":["../../../../../../brightchain-lib/src/lib/interfaces/availability/heartbeatMonitor.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;;;;OAMG;IACH,IAAI,EACA,gBAAgB,GAChB,mBAAmB,GACnB,kBAAkB,GAClB,kBAAkB,CAAC;IAEvB;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB;;OAEG;IACH,SAAS,EAAE,IAAI,CAAC;CACjB;AAED;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B;;;;;OAKG;IACH,UAAU,EAAE,MAAM,CAAC;IAEnB;;;;;OAKG;IACH,SAAS,EAAE,MAAM,CAAC;IAElB;;;;;OAKG;IACH,eAAe,EAAE,MAAM,CAAC;CACzB;AAED;;GAEG;AACH,eAAO,MAAM,wBAAwB,EAAE,eAItC,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,wBAAwB,GAAG,CAAC,KAAK,EAAE,iBAAiB,KAAK,IAAI,CAAC;AAE1E;;;;;;;;GAQG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;;;OAKG;IACH,KAAK,IAAI,IAAI,CAAC;IAEd;;;OAGG;IACH,IAAI,IAAI,IAAI,CAAC;IAEb;;;;OAIG;IACH,SAAS,IAAI,OAAO,CAAC;IAErB;;;;;;OAMG;IACH,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC;IAEzC;;;;;OAKG;IACH,iBAAiB,IAAI,MAAM,EAAE,CAAC;IAE9B;;;;;OAKG;IACH,mBAAmB,IAAI,MAAM,EAAE,CAAC;IAEhC;;;;;OAKG;IACH,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC;IAEvC;;;;OAIG;IACH,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAE9B;;;;OAIG;IACH,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAEjC;;;;OAIG;IACH,iBAAiB,IAAI,MAAM,EAAE,CAAC;IAE9B;;;;;;OAMG;IACH,oBAAoB,CAAC,OAAO,EAAE,wBAAwB,GAAG,IAAI,CAAC;IAE9D;;;;OAIG;IACH,qBAAqB,CAAC,OAAO,EAAE,wBAAwB,GAAG,IAAI,CAAC;IAE/D;;;;;;OAMG;IACH,uBAAuB,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IAEjE;;;;;OAKG;IACH,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;IAEnD;;;;OAIG;IACH,SAAS,IAAI,eAAe,CAAC;CAC9B"}

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

@@ -0,0 +1,20 @@
+"use strict";
+/**
+ * @fileoverview Heartbeat Monitor Interface
+ *
+ * Defines the interface for monitoring peer connectivity through heartbeat messages.
+ * Enables nodes to detect network partitions and track peer reachability.
+ *
+ * @see Requirements 7.1, 7.2, 7.5
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_HEARTBEAT_CONFIG = void 0;
+/**
+ * Default heartbeat configuration values.
+ */
+exports.DEFAULT_HEARTBEAT_CONFIG = {
+    intervalMs: 5000,
+    timeoutMs: 2000,
+    missedThreshold: 3,
+};
+//# sourceMappingURL=heartbeatMonitor.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"heartbeatMonitor.js","sourceRoot":"","sources":["../../../../../../brightchain-lib/src/lib/interfaces/availability/heartbeatMonitor.ts"],"names":[],"mappings":";AAAA;;;;;;;GAOG;;;AA+DH;;GAEG;AACU,QAAA,wBAAwB,GAAoB;IACvD,UAAU,EAAE,IAAI;IAChB,SAAS,EAAE,IAAI;IACf,eAAe,EAAE,CAAC;CACnB,CAAC"}

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

@@ -0,0 +1,8 @@
+export * from './availabilityService';
+export * from './blockRegistry';
+export * from './discoveryProtocol';
+export * from './gossipService';
+export * from './heartbeatMonitor';
+export * from './locationRecord';
+export * from './reconciliationService';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../../brightchain-lib/src/lib/interfaces/availability/index.ts"],"names":[],"mappings":"AAAA,cAAc,uBAAuB,CAAC;AACtC,cAAc,iBAAiB,CAAC;AAChC,cAAc,qBAAqB,CAAC;AACpC,cAAc,iBAAiB,CAAC;AAChC,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC;AACjC,cAAc,yBAAyB,CAAC"}

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

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const tslib_1 = require("tslib");
+tslib_1.__exportStar(require("./availabilityService"), exports);
+tslib_1.__exportStar(require("./blockRegistry"), exports);
+tslib_1.__exportStar(require("./discoveryProtocol"), exports);
+tslib_1.__exportStar(require("./gossipService"), exports);
+tslib_1.__exportStar(require("./heartbeatMonitor"), exports);
+tslib_1.__exportStar(require("./locationRecord"), exports);
+tslib_1.__exportStar(require("./reconciliationService"), exports);
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../../brightchain-lib/src/lib/interfaces/availability/index.ts"],"names":[],"mappings":";;;AAAA,gEAAsC;AACtC,0DAAgC;AAChC,8DAAoC;AACpC,0DAAgC;AAChC,6DAAmC;AACnC,2DAAiC;AACjC,kEAAwC"}

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

@@ -0,0 +1,110 @@
+import { AvailabilityState } from '../../enumerations/availabilityState';
+import { IBlockMetadata } from '../storage/blockMetadata';
+/**
+ * Location record for a block, tracking which node holds a copy
+ * and metadata about that copy.
+ *
+ * @see Requirements 2.1, 2.2, 2.3
+ */
+export interface ILocationRecord {
+    /**
+     * Unique identifier of the node holding this block
+     */
+    nodeId: string;
+    /**
+     * Timestamp when this node was last confirmed to have the block
+     */
+    lastSeen: Date;
+    /**
+     * Whether this node holds the authoritative (original) copy
+     */
+    isAuthoritative: boolean;
+    /**
+     * Optional latency measurement to this node in milliseconds
+     */
+    latencyMs?: number;
+}
+/**
+ * Extended block metadata with availability and location information.
+ * Extends the base IBlockMetadata to support distributed block discovery.
+ *
+ * @see Requirements 2.1, 2.2, 2.3
+ */
+export interface IBlockMetadataWithLocation extends IBlockMetadata {
+    /**
+     * Current availability state of the block
+     */
+    availabilityState: AvailabilityState;
+    /**
+     * Nodes known to hold this block
+     */
+    locationRecords: ILocationRecord[];
+    /**
+     * When the location information was last updated
+     */
+    locationUpdatedAt: Date;
+}
+/**
+ * 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
+ */
+export declare function createDefaultLocationMetadata(localNodeId: string): Pick<IBlockMetadataWithLocation, 'availabilityState' | 'locationRecords' | 'locationUpdatedAt'>;
+/**
+ * Serializable representation of ILocationRecord with Date fields as ISO strings
+ */
+export interface SerializedLocationRecord {
+    nodeId: string;
+    lastSeen: string;
+    isAuthoritative: boolean;
+    latencyMs?: number;
+}
+/**
+ * Serializable representation of IBlockMetadataWithLocation
+ */
+export interface SerializedBlockMetadataWithLocation {
+    blockId: string;
+    createdAt: string;
+    expiresAt: string | null;
+    durabilityLevel: string;
+    parityBlockIds: string[];
+    accessCount: number;
+    lastAccessedAt: string;
+    replicationStatus: string;
+    targetReplicationFactor: number;
+    replicaNodeIds: string[];
+    size: number;
+    checksum: string;
+    availabilityState: AvailabilityState;
+    locationRecords: SerializedLocationRecord[];
+    locationUpdatedAt: string;
+}
+/**
+ * Convert ILocationRecord to JSON-serializable format
+ * @param record - The location record to serialize
+ * @returns Serialized location record with Date fields as ISO strings
+ */
+export declare function locationRecordToJSON(record: ILocationRecord): SerializedLocationRecord;
+/**
+ * Convert serialized location record back to ILocationRecord
+ * @param serialized - The serialized location record
+ * @returns Location record with Date objects
+ * @throws Error if validation fails
+ */
+export declare function locationRecordFromJSON(serialized: SerializedLocationRecord): ILocationRecord;
+/**
+ * Convert IBlockMetadataWithLocation to JSON-serializable format
+ * @param metadata - The block metadata with location to serialize
+ * @returns Serialized metadata with Date fields as ISO strings
+ */
+export declare function blockMetadataWithLocationToJSON(metadata: IBlockMetadataWithLocation): SerializedBlockMetadataWithLocation;
+/**
+ * Convert serialized block metadata back to IBlockMetadataWithLocation
+ * @param serialized - The serialized block metadata
+ * @returns Block metadata with Date objects
+ * @throws Error if validation fails
+ */
+export declare function blockMetadataWithLocationFromJSON(serialized: SerializedBlockMetadataWithLocation): IBlockMetadataWithLocation;
+//# sourceMappingURL=locationRecord.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"locationRecord.d.ts","sourceRoot":"","sources":["../../../../../../brightchain-lib/src/lib/interfaces/availability/locationRecord.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,sCAAsC,CAAC;AAGzE,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAE1D;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B;;OAEG;IACH,MAAM,EAAE,MAAM,CAAC;IAEf;;OAEG;IACH,QAAQ,EAAE,IAAI,CAAC;IAEf;;OAEG;IACH,eAAe,EAAE,OAAO,CAAC;IAEzB;;OAEG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;GAKG;AACH,MAAM,WAAW,0BAA2B,SAAQ,cAAc;IAChE;;OAEG;IACH,iBAAiB,EAAE,iBAAiB,CAAC;IAErC;;OAEG;IACH,eAAe,EAAE,eAAe,EAAE,CAAC;IAEnC;;OAEG;IACH,iBAAiB,EAAE,IAAI,CAAC;CACzB;AAED;;;;;;GAMG;AACH,wBAAgB,6BAA6B,CAC3C,WAAW,EAAE,MAAM,GAClB,IAAI,CACL,0BAA0B,EAC1B,mBAAmB,GAAG,iBAAiB,GAAG,mBAAmB,CAC9D,CAYA;AAED;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACvC,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,eAAe,EAAE,OAAO,CAAC;IACzB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,mCAAmC;IAClD,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,eAAe,EAAE,MAAM,CAAC;IACxB,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,MAAM,CAAC;IACvB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,uBAAuB,EAAE,MAAM,CAAC;IAChC,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,iBAAiB,EAAE,iBAAiB,CAAC;IACrC,eAAe,EAAE,wBAAwB,EAAE,CAAC;IAC5C,iBAAiB,EAAE,MAAM,CAAC;CAC3B;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,eAAe,GACtB,wBAAwB,CAO1B;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,UAAU,EAAE,wBAAwB,GACnC,eAAe,CA2CjB;AAED;;;;GAIG;AACH,wBAAgB,+BAA+B,CAC7C,QAAQ,EAAE,0BAA0B,GACnC,mCAAmC,CAkBrC;AAED;;;;;GAKG;AACH,wBAAgB,iCAAiC,CAC/C,UAAU,EAAE,mCAAmC,GAC9C,0BAA0B,CAkI5B"}