@brightchain/brightchain-lib 0.1.5 → 0.1.7

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

@@ -0,0 +1,319 @@
+/**
+ * @fileoverview Availability Service Interface
+ *
+ * Defines the main service interface for coordinating block availability tracking,
+ * discovery, partition handling, and event emission. This service integrates
+ * BlockRegistry, DiscoveryProtocol, GossipService, ReconciliationService, and
+ * HeartbeatMonitor to provide a unified availability management layer.
+ *
+ * @see Requirements 1.7, 7.2, 7.3, 7.4, 7.5, 7.7, 11.1, 11.2, 11.3, 11.4, 11.5, 11.6, 14.1, 14.2, 14.3, 14.4, 14.5, 14.6
+ */
+import { AvailabilityState } from '../../enumerations/availabilityState';
+import { ILocationRecord } from './locationRecord';
+import { ReconciliationResult } from './reconciliationService';
+/**
+ * Statistics about block availability across the system.
+ *
+ * @see Requirements 11.4, 15.1
+ */
+export interface AvailabilityStatistics {
+    /**
+     * Number of blocks stored locally as authoritative copies
+     */
+    localCount: number;
+    /**
+     * Number of blocks known to exist only on remote nodes
+     */
+    remoteCount: number;
+    /**
+     * Number of blocks cached locally with remote authoritative copies
+     */
+    cachedCount: number;
+    /**
+     * Number of blocks whose source nodes are unreachable
+     */
+    orphanedCount: number;
+    /**
+     * Number of blocks with unknown location
+     */
+    unknownCount: number;
+    /**
+     * Total number of known location records across all blocks
+     */
+    totalKnownLocations: number;
+    /**
+     * Average number of locations per block
+     */
+    averageLocationsPerBlock: number;
+}
+/**
+ * Event types emitted by the availability service.
+ *
+ * @see Requirements 14.1, 14.2, 14.3, 14.4, 14.5
+ */
+export type AvailabilityEvent = {
+    type: 'state_changed';
+    blockId: string;
+    oldState: AvailabilityState;
+    newState: AvailabilityState;
+    timestamp: Date;
+} | {
+    type: 'location_added';
+    blockId: string;
+    location: ILocationRecord;
+    timestamp: Date;
+} | {
+    type: 'location_removed';
+    blockId: string;
+    nodeId: string;
+    timestamp: Date;
+} | {
+    type: 'partition_entered';
+    timestamp: Date;
+    disconnectedPeers: string[];
+} | {
+    type: 'partition_exited';
+    timestamp: Date;
+    reconnectedPeers: string[];
+} | {
+    type: 'reconciliation_started';
+    timestamp: Date;
+    peerIds: string[];
+} | {
+    type: 'reconciliation_completed';
+    timestamp: Date;
+    result: ReconciliationResult;
+};
+/**
+ * Handler function type for availability events.
+ */
+export type AvailabilityEventHandler = (event: AvailabilityEvent) => void;
+/**
+ * Filter options for event subscriptions.
+ *
+ * @see Requirements 14.6
+ */
+export interface EventFilter {
+    /**
+     * Event types to receive. If empty or undefined, receives all types.
+     */
+    eventTypes?: AvailabilityEvent['type'][];
+    /**
+     * Block ID patterns to match. Supports glob patterns.
+     * If empty or undefined, receives events for all blocks.
+     */
+    blockIdPatterns?: string[];
+}
+/**
+ * Result of a location query with staleness indication.
+ *
+ * @see Requirements 11.5, 11.6
+ */
+export interface LocationQueryResult {
+    /**
+     * The block ID queried
+     */
+    blockId: string;
+    /**
+     * Current availability state
+     */
+    state: AvailabilityState;
+    /**
+     * Known locations for the block
+     */
+    locations: ILocationRecord[];
+    /**
+     * Whether the location information is considered stale
+     *
+     * @see Requirements 11.6
+     */
+    isStale: boolean;
+    /**
+     * When the location information was last updated
+     */
+    lastUpdated: Date;
+}
+/**
+ * Configuration for the availability service.
+ */
+export interface AvailabilityServiceConfig {
+    /**
+     * The local node's unique identifier
+     */
+    localNodeId: string;
+    /**
+     * Threshold in milliseconds after which location data is considered stale
+     *
+     * @see Requirements 11.6
+     */
+    stalenessThresholdMs: number;
+    /**
+     * Timeout for availability queries in milliseconds
+     *
+     * @see Requirements 11.5
+     */
+    queryTimeoutMs: number;
+}
+/**
+ * Default availability service configuration values.
+ */
+export declare const DEFAULT_AVAILABILITY_SERVICE_CONFIG: AvailabilityServiceConfig;
+/**
+ * Availability Service Interface
+ *
+ * Main service for coordinating block availability tracking across the distributed
+ * storage system. Integrates with BlockRegistry, DiscoveryProtocol, GossipService,
+ * ReconciliationService, and HeartbeatMonitor to provide:
+ *
+ * - State queries and updates for block availability
+ * - Partition mode handling when network connectivity is lost
+ * - Event emission for availability changes
+ * - Statistics about block distribution
+ *
+ * @see Requirements 1.7, 7.2, 7.3, 7.4, 7.5, 7.7, 11.1, 11.2, 11.3, 11.4, 11.5, 11.6, 14.1, 14.2, 14.3, 14.4, 14.5, 14.6
+ */
+export interface IAvailabilityService {
+    /**
+     * Get the availability state for a block.
+     *
+     * @param blockId - The block ID to query
+     * @returns Promise resolving to the block's availability state
+     * @see Requirements 1.7, 11.1
+     */
+    getAvailabilityState(blockId: string): Promise<AvailabilityState>;
+    /**
+     * Get all known locations for a block.
+     *
+     * @param blockId - The block ID to query
+     * @returns Promise resolving to array of location records
+     * @see Requirements 11.2
+     */
+    getBlockLocations(blockId: string): Promise<ILocationRecord[]>;
+    /**
+     * Get detailed location query result with staleness indication.
+     *
+     * @param blockId - The block ID to query
+     * @returns Promise resolving to location query result
+     * @see Requirements 11.5, 11.6
+     */
+    queryBlockLocation(blockId: string): Promise<LocationQueryResult>;
+    /**
+     * List all blocks in a specific availability state.
+     *
+     * @param state - The availability state to filter by
+     * @returns Promise resolving to array of block IDs
+     * @see Requirements 11.3
+     */
+    listBlocksByState(state: AvailabilityState): Promise<string[]>;
+    /**
+     * Get statistics about block availability distribution.
+     *
+     * @returns Promise resolving to availability statistics
+     * @see Requirements 11.4
+     */
+    getStatistics(): Promise<AvailabilityStatistics>;
+    /**
+     * Update or add a location record for a block.
+     * Emits a location_added event if this is a new location.
+     *
+     * @param blockId - The block ID to update
+     * @param location - The location record to add or update
+     * @returns Promise that resolves when the update is complete
+     * @see Requirements 2.4, 14.2
+     */
+    updateLocation(blockId: string, location: ILocationRecord): Promise<void>;
+    /**
+     * Remove a location record for a block.
+     * Emits a location_removed event.
+     *
+     * @param blockId - The block ID to update
+     * @param nodeId - The node ID to remove from locations
+     * @returns Promise that resolves when the removal is complete
+     * @see Requirements 2.5, 14.3
+     */
+    removeLocation(blockId: string, nodeId: string): Promise<void>;
+    /**
+     * Set the availability state for a block.
+     * Emits a state_changed event if the state changes.
+     *
+     * @param blockId - The block ID to update
+     * @param state - The new availability state
+     * @returns Promise that resolves when the update is complete
+     * @see Requirements 14.1
+     */
+    setAvailabilityState(blockId: string, state: AvailabilityState): Promise<void>;
+    /**
+     * Check if the service is currently in partition mode.
+     * Partition mode is entered when all peers become unreachable.
+     *
+     * @returns True if in partition mode
+     * @see Requirements 7.2
+     */
+    isInPartitionMode(): boolean;
+    /**
+     * Enter partition mode.
+     * Called when all peers become unreachable.
+     * Marks all Remote blocks as Orphaned and emits partition_entered event.
+     *
+     * @see Requirements 7.2, 7.3, 7.7, 14.4
+     */
+    enterPartitionMode(): void;
+    /**
+     * Exit partition mode and initiate reconciliation.
+     * Called when at least one peer becomes reachable.
+     * Emits partition_exited event and starts reconciliation.
+     *
+     * @returns Promise resolving to reconciliation result
+     * @see Requirements 7.5, 9.1, 14.4, 14.5
+     */
+    exitPartitionMode(): Promise<ReconciliationResult>;
+    /**
+     * Get the list of peers that were disconnected when entering partition mode.
+     *
+     * @returns Array of disconnected peer IDs, or empty if not in partition mode
+     */
+    getDisconnectedPeers(): string[];
+    /**
+     * Subscribe to availability events.
+     *
+     * @param handler - Function to call when events occur
+     * @param filter - Optional filter to receive only specific events
+     * @see Requirements 14.1, 14.2, 14.3, 14.4, 14.5, 14.6
+     */
+    onEvent(handler: AvailabilityEventHandler, filter?: EventFilter): void;
+    /**
+     * Remove an event handler.
+     *
+     * @param handler - The handler to remove
+     */
+    offEvent(handler: AvailabilityEventHandler): void;
+    /**
+     * Start the availability service.
+     * Initializes all integrated services and begins monitoring.
+     */
+    start(): Promise<void>;
+    /**
+     * Stop the availability service.
+     * Stops all integrated services and cleans up resources.
+     */
+    stop(): Promise<void>;
+    /**
+     * Check if the service is running.
+     *
+     * @returns True if the service is active
+     */
+    isRunning(): boolean;
+    /**
+     * Get the current configuration.
+     *
+     * @returns The availability service configuration
+     */
+    getConfig(): AvailabilityServiceConfig;
+    /**
+     * Get the local node ID.
+     *
+     * @returns The local node's unique identifier
+     */
+    getLocalNodeId(): string;
+}
+//# sourceMappingURL=availabilityService.d.ts.map

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

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

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

@@ -0,0 +1,22 @@
+"use strict";
+/**
+ * @fileoverview Availability Service Interface
+ *
+ * Defines the main service interface for coordinating block availability tracking,
+ * discovery, partition handling, and event emission. This service integrates
+ * BlockRegistry, DiscoveryProtocol, GossipService, ReconciliationService, and
+ * HeartbeatMonitor to provide a unified availability management layer.
+ *
+ * @see Requirements 1.7, 7.2, 7.3, 7.4, 7.5, 7.7, 11.1, 11.2, 11.3, 11.4, 11.5, 11.6, 14.1, 14.2, 14.3, 14.4, 14.5, 14.6
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_AVAILABILITY_SERVICE_CONFIG = void 0;
+/**
+ * Default availability service configuration values.
+ */
+exports.DEFAULT_AVAILABILITY_SERVICE_CONFIG = {
+    localNodeId: '',
+    stalenessThresholdMs: 300000, // 5 minutes
+    queryTimeoutMs: 10000, // 10 seconds
+};
+//# sourceMappingURL=availabilityService.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"availabilityService.js","sourceRoot":"","sources":["../../../../../../brightchain-lib/src/lib/interfaces/availability/availabilityService.ts"],"names":[],"mappings":";AAAA;;;;;;;;;GASG;;;AA+KH;;GAEG;AACU,QAAA,mCAAmC,GAA8B;IAC5E,WAAW,EAAE,EAAE;IACf,oBAAoB,EAAE,MAAM,EAAE,YAAY;IAC1C,cAAc,EAAE,KAAK,EAAE,aAAa;CACrC,CAAC"}

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

@@ -0,0 +1,135 @@
+/**
+ * @fileoverview Block Registry Interface
+ *
+ * Defines the interface for maintaining a fast local index of blocks,
+ * supporting O(1) lookups, Bloom filter export, and manifest generation.
+ *
+ * @see Requirements 3.1, 3.6, 3.7
+ */
+/**
+ * Bloom filter for efficient block existence queries.
+ * A space-efficient probabilistic data structure used to test
+ * whether a block might exist on a node.
+ *
+ * @see Requirements 4.1, 4.6
+ */
+export interface BloomFilter {
+    /**
+     * Serialized filter data as a base64 string
+     */
+    data: string;
+    /**
+     * Number of hash functions used
+     */
+    hashCount: number;
+    /**
+     * Size of the filter in bits
+     */
+    bitCount: number;
+    /**
+     * Number of items in the filter
+     */
+    itemCount: number;
+    /**
+     * Check if an item might exist in the filter.
+     * Returns true if the item might exist (possible false positive),
+     * returns false if the item definitely does not exist (no false negatives).
+     *
+     * @param blockId - The block ID to check
+     * @returns true if the block might exist, false if it definitely does not
+     */
+    mightContain(blockId: string): boolean;
+}
+/**
+ * Complete block manifest for synchronization.
+ * Contains a full list of block IDs stored on a node.
+ *
+ * @see Requirements 3.7
+ */
+export interface BlockManifest {
+    /**
+     * Unique identifier of the node that generated this manifest
+     */
+    nodeId: string;
+    /**
+     * Array of all block IDs stored on the node
+     */
+    blockIds: string[];
+    /**
+     * Timestamp when the manifest was generated
+     */
+    generatedAt: Date;
+    /**
+     * Checksum of the manifest for integrity verification.
+     * Changes if and only if the block set changes.
+     */
+    checksum: string;
+}
+/**
+ * Block Registry Interface
+ *
+ * Maintains a fast local index of blocks stored on the node.
+ * Provides O(1) lookups, Bloom filter export for efficient network queries,
+ * and manifest export for full synchronization.
+ *
+ * @see Requirements 3.1, 3.6, 3.7
+ */
+export interface IBlockRegistry {
+    /**
+     * Check if a block exists locally (O(1) lookup)
+     *
+     * @param blockId - The block ID to check
+     * @returns true if the block exists locally
+     */
+    hasLocal(blockId: string): boolean;
+    /**
+     * Add a block to the local registry
+     *
+     * @param blockId - The block ID to add
+     */
+    addLocal(blockId: string): void;
+    /**
+     * Remove a block from the local registry
+     *
+     * @param blockId - The block ID to remove
+     */
+    removeLocal(blockId: string): void;
+    /**
+     * Get count of local blocks
+     *
+     * @returns The number of blocks in the local registry
+     */
+    getLocalCount(): number;
+    /**
+     * Get all local block IDs (for full sync)
+     *
+     * @returns Array of all block IDs in the local registry
+     */
+    getLocalBlockIds(): string[];
+    /**
+     * Export a Bloom filter representation of the registry.
+     * The Bloom filter allows efficient probabilistic queries
+     * with no false negatives and a configurable false positive rate.
+     *
+     * @returns A Bloom filter representing all local block IDs
+     * @see Requirements 3.6, 4.1
+     */
+    exportBloomFilter(): BloomFilter;
+    /**
+     * Export a complete manifest of all local blocks.
+     * Used for full synchronization with peers.
+     *
+     * @returns A manifest containing all local block IDs
+     * @see Requirements 3.7
+     */
+    exportManifest(): BlockManifest;
+    /**
+     * Rebuild the registry from disk storage.
+     * Called on node startup to restore the index.
+     *
+     * @returns Promise that resolves when rebuild is complete
+     * @see Requirements 3.5
+     */
+    rebuild(): Promise<void>;
+}
+//# sourceMappingURL=blockRegistry.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"blockRegistry.d.ts","sourceRoot":"","sources":["../../../../../../brightchain-lib/src/lib/interfaces/availability/blockRegistry.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;;;;;GAMG;AACH,MAAM,WAAW,WAAW;IAC1B;;OAEG;IACH,IAAI,EAAE,MAAM,CAAC;IAEb;;OAEG;IACH,SAAS,EAAE,MAAM,CAAC;IAElB;;OAEG;IACH,QAAQ,EAAE,MAAM,CAAC;IAEjB;;OAEG;IACH,SAAS,EAAE,MAAM,CAAC;IAElB;;;;;;;OAOG;IACH,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC;CACxC;AAED;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC5B;;OAEG;IACH,MAAM,EAAE,MAAM,CAAC;IAEf;;OAEG;IACH,QAAQ,EAAE,MAAM,EAAE,CAAC;IAEnB;;OAEG;IACH,WAAW,EAAE,IAAI,CAAC;IAElB;;;OAGG;IACH,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,cAAc;IAC7B;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC;IAEnC;;;;OAIG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAEhC;;;;OAIG;IACH,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAEnC;;;;OAIG;IACH,aAAa,IAAI,MAAM,CAAC;IAExB;;;;OAIG;IACH,gBAAgB,IAAI,MAAM,EAAE,CAAC;IAE7B;;;;;;;OAOG;IACH,iBAAiB,IAAI,WAAW,CAAC;IAEjC;;;;;;OAMG;IACH,cAAc,IAAI,aAAa,CAAC;IAEhC;;;;;;OAMG;IACH,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1B"}

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

@@ -0,0 +1,11 @@
+"use strict";
+/**
+ * @fileoverview Block Registry Interface
+ *
+ * Defines the interface for maintaining a fast local index of blocks,
+ * supporting O(1) lookups, Bloom filter export, and manifest generation.
+ *
+ * @see Requirements 3.1, 3.6, 3.7
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=blockRegistry.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"blockRegistry.js","sourceRoot":"","sources":["../../../../../../brightchain-lib/src/lib/interfaces/availability/blockRegistry.ts"],"names":[],"mappings":";AAAA;;;;;;;GAOG"}

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

@@ -0,0 +1,179 @@
+/**
+ * @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
+ */
+import { BloomFilter } from './blockRegistry';
+import { ILocationRecord } from './locationRecord';
+/**
+ * Result of a block discovery operation.
+ * Contains information about where a block was found and query statistics.
+ *
+ * @see Requirements 5.1, 5.4, 5.6
+ */
+export interface DiscoveryResult {
+    /**
+     * The block ID that was searched for
+     */
+    blockId: string;
+    /**
+     * Whether the block was found on any peer
+     */
+    found: boolean;
+    /**
+     * Nodes where the block was found, sorted by latency (lowest first)
+     *
+     * @see Requirements 5.5
+     */
+    locations: ILocationRecord[];
+    /**
+     * Number of peers that were queried during discovery
+     */
+    queriedPeers: number;
+    /**
+     * Total duration of the discovery operation in milliseconds
+     */
+    duration: number;
+}
+/**
+ * Result of querying a single peer for a block.
+ *
+ * @see Requirements 5.3
+ */
+export interface PeerQueryResult {
+    /**
+     * The peer that was queried
+     */
+    peerId: string;
+    /**
+     * Whether the peer has the block
+     */
+    hasBlock: boolean;
+    /**
+     * Round-trip latency to the peer in milliseconds
+     */
+    latencyMs: number;
+    /**
+     * Error message if the query failed
+     */
+    error?: string;
+}
+/**
+ * Configuration for the discovery protocol.
+ *
+ * @see Requirements 5.7, 13.1, 13.2, 13.3
+ */
+export interface DiscoveryConfig {
+    /**
+     * Timeout for discovery queries in milliseconds.
+     * Queries that exceed this timeout will be cancelled.
+     *
+     * @see Requirements 5.7, 13.1
+     */
+    queryTimeoutMs: number;
+    /**
+     * Maximum number of concurrent queries to peers.
+     * Limits resource usage during discovery.
+     *
+     * @see Requirements 13.2
+     */
+    maxConcurrentQueries: number;
+    /**
+     * Time-to-live for cached discovery results in milliseconds.
+     * Cached results older than this will be refreshed.
+     *
+     * @see Requirements 5.8
+     */
+    cacheTtlMs: number;
+    /**
+     * Target false positive rate for Bloom filters.
+     * Lower values reduce unnecessary queries but increase filter size.
+     *
+     * @see Requirements 4.6, 13.3
+     */
+    bloomFilterFalsePositiveRate: number;
+    /**
+     * Number of hash functions for Bloom filters.
+     *
+     * @see Requirements 13.3
+     */
+    bloomFilterHashCount: number;
+}
+/**
+ * Default discovery configuration values.
+ */
+export declare const DEFAULT_DISCOVERY_CONFIG: DiscoveryConfig;
+/**
+ * Discovery Protocol Interface
+ *
+ * Handles finding blocks across the network using 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
+ */
+export interface IDiscoveryProtocol {
+    /**
+     * Discover locations for a block across the network.
+     *
+     * The discovery process:
+     * 1. Check local cache for recent results
+     * 2. Query peers using Bloom filter pre-checks
+     * 3. Make direct queries to peers whose Bloom filters indicate possible match
+     * 4. Cache and return results sorted by latency
+     *
+     * @param blockId - The block ID to discover
+     * @returns Promise resolving to discovery result with locations
+     * @see Requirements 5.1, 5.2, 5.3, 5.4, 5.5
+     */
+    discoverBlock(blockId: string): Promise<DiscoveryResult>;
+    /**
+     * Query a specific peer for a block.
+     * Makes a direct query without Bloom filter pre-check.
+     *
+     * @param peerId - The peer to query
+     * @param blockId - The block ID to query for
+     * @returns Promise resolving to the query result
+     * @see Requirements 5.3
+     */
+    queryPeer(peerId: string, blockId: string): Promise<PeerQueryResult>;
+    /**
+     * Get cached discovery results for a block.
+     * Returns null if no cached results exist or if cache has expired.
+     *
+     * @param blockId - The block ID to get cached locations for
+     * @returns Cached location records or null if not cached
+     * @see Requirements 5.8
+     */
+    getCachedLocations(blockId: string): ILocationRecord[] | null;
+    /**
+     * Clear the discovery cache for a specific block.
+     * Forces the next discovery to query the network.
+     *
+     * @param blockId - The block ID to clear from cache
+     */
+    clearCache(blockId: string): void;
+    /**
+     * Clear the entire discovery cache.
+     */
+    clearAllCache(): void;
+    /**
+     * Get the Bloom filter from a peer.
+     * Used to pre-check if a peer might have a block before making a direct query.
+     *
+     * @param peerId - The peer to get the Bloom filter from
+     * @returns Promise resolving to the peer's Bloom filter
+     * @see Requirements 4.2, 5.2
+     */
+    getPeerBloomFilter(peerId: string): Promise<BloomFilter>;
+    /**
+     * Get the current configuration.
+     *
+     * @returns The discovery configuration
+     */
+    getConfig(): DiscoveryConfig;
+}
+//# sourceMappingURL=discoveryProtocol.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"discoveryProtocol.d.ts","sourceRoot":"","sources":["../../../../../../brightchain-lib/src/lib/interfaces/availability/discoveryProtocol.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAC9C,OAAO,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAEnD;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B;;OAEG;IACH,OAAO,EAAE,MAAM,CAAC;IAEhB;;OAEG;IACH,KAAK,EAAE,OAAO,CAAC;IAEf;;;;OAIG;IACH,SAAS,EAAE,eAAe,EAAE,CAAC;IAE7B;;OAEG;IACH,YAAY,EAAE,MAAM,CAAC;IAErB;;OAEG;IACH,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B;;OAEG;IACH,MAAM,EAAE,MAAM,CAAC;IAEf;;OAEG;IACH,QAAQ,EAAE,OAAO,CAAC;IAElB;;OAEG;IACH,SAAS,EAAE,MAAM,CAAC;IAElB;;OAEG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B;;;;;OAKG;IACH,cAAc,EAAE,MAAM,CAAC;IAEvB;;;;;OAKG;IACH,oBAAoB,EAAE,MAAM,CAAC;IAE7B;;;;;OAKG;IACH,UAAU,EAAE,MAAM,CAAC;IAEnB;;;;;OAKG;IACH,4BAA4B,EAAE,MAAM,CAAC;IAErC;;;;OAIG;IACH,oBAAoB,EAAE,MAAM,CAAC;CAC9B;AAED;;GAEG;AACH,eAAO,MAAM,wBAAwB,EAAE,eAMtC,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,WAAW,kBAAkB;IACjC;;;;;;;;;;;;OAYG;IACH,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;IAEzD;;;;;;;;OAQG;IACH,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;IAErE;;;;;;;OAOG;IACH,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,eAAe,EAAE,GAAG,IAAI,CAAC;IAE9D;;;;;OAKG;IACH,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAElC;;OAEG;IACH,aAAa,IAAI,IAAI,CAAC;IAEtB;;;;;;;OAOG;IACH,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;IAEzD;;;;OAIG;IACH,SAAS,IAAI,eAAe,CAAC;CAC9B"}