@brightchain/brightchain-lib 0.13.0 → 0.15.0

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

@@ -7,7 +7,9 @@
  *
  * @see Requirements 5.1, 5.2, 5.3, 5.4, 5.5, 5.6, 5.7, 5.8
  */
-import { BloomFilter } from './blockRegistry';
+import type { ICBLIndexEntry } from '../storage/cblIndex';
+import { PoolId } from '../storage/pooledBlockStore';
+import { BloomFilter, PoolScopedBloomFilter } from './blockRegistry';
 import { ILocationRecord } from './locationRecord';
 /**
  * Result of a block discovery operation.
@@ -38,6 +40,13 @@ export interface DiscoveryResult {
      * Total duration of the discovery operation in milliseconds
      */
     duration: number;
+    /**
+     * Pool context used for this discovery, if any.
+     * Set when discoverBlock was called with a poolId parameter.
+     *
+     * @see Requirements 4.1
+     */
+    poolId?: PoolId;
 }
 /**
  * Result of querying a single peer for a block.
@@ -107,6 +116,49 @@ export interface DiscoveryConfig {
  * Default discovery configuration values.
  */
 export declare const DEFAULT_DISCOVERY_CONFIG: DiscoveryConfig;
+/**
+ * Query for searching CBL metadata across pool peers.
+ * All fields are optional; only specified fields are used as filters.
+ *
+ * @see Requirements 8.5
+ */
+export interface CBLMetadataSearchQuery {
+    /** Filter by file name (substring match) */
+    fileName?: string;
+    /** Filter by MIME type (exact match) */
+    mimeType?: string;
+    /** Filter by tags (entries must have all specified tags) */
+    tags?: string[];
+    /** Scope the search to a specific pool */
+    poolId?: PoolId;
+}
+/**
+ * A single matching entry from a CBL metadata search,
+ * annotated with the source node that reported it.
+ *
+ * @see Requirements 8.5
+ */
+export interface CBLMetadataSearchHit {
+    /** The matching CBL index entry */
+    entry: ICBLIndexEntry;
+    /** Node ID of the peer that reported this entry */
+    sourceNodeId: string;
+}
+/**
+ * Result of a CBL metadata search across pool peers.
+ *
+ * @see Requirements 8.5
+ */
+export interface CBLMetadataSearchResult {
+    /** The query that was executed */
+    query: CBLMetadataSearchQuery;
+    /** Matching entries with source node information */
+    hits: CBLMetadataSearchHit[];
+    /** Number of peers that were queried */
+    queriedPeers: number;
+    /** Total duration of the search in milliseconds */
+    duration: number;
+}
 /**
  * Discovery Protocol Interface
  *
@@ -125,11 +177,15 @@ export interface IDiscoveryProtocol {
      * 3. Make direct queries to peers whose Bloom filters indicate possible match
      * 4. Cache and return results sorted by latency
      *
+     * When poolId is provided, uses pool-scoped Bloom filters and
+     * includes poolId in peer queries for pool-specific discovery.
+     *
      * @param blockId - The block ID to discover
+     * @param poolId - Optional pool to scope the discovery to
      * @returns Promise resolving to discovery result with locations
-     * @see Requirements 5.1, 5.2, 5.3, 5.4, 5.5
+     * @see Requirements 4.1, 4.2, 4.3, 5.1, 5.2, 5.3, 5.4, 5.5
      */
-    discoverBlock(blockId: string): Promise<DiscoveryResult>;
+    discoverBlock(blockId: string, poolId?: PoolId): Promise<DiscoveryResult>;
     /**
      * Query a specific peer for a block.
      * Makes a direct query without Bloom filter pre-check.
@@ -169,11 +225,33 @@ export interface IDiscoveryProtocol {
      * @see Requirements 4.2, 5.2
      */
     getPeerBloomFilter(peerId: string): Promise<BloomFilter>;
+    /**
+     * Get the pool-scoped Bloom filter from a peer.
+     * Used for pool-aware discovery to pre-check block existence
+     * within specific pools before making direct queries.
+     *
+     * @param peerId - The peer to get the pool-scoped Bloom filter from
+     * @returns Promise resolving to the peer's pool-scoped Bloom filter
+     * @see Requirements 4.2, 4.5
+     */
+    getPeerPoolScopedBloomFilter(peerId: string): Promise<PoolScopedBloomFilter>;
     /**
      * Get the current configuration.
      *
      * @returns The discovery configuration
      */
     getConfig(): DiscoveryConfig;
+    /**
+     * Search for CBL index entries by metadata across pool peers.
+     *
+     * Queries connected peers for CBL entries matching the given criteria
+     * (file name, MIME type, tags) within the specified pool. Results are
+     * deduplicated by magnet URL, keeping the first occurrence.
+     *
+     * @param query - Search criteria with optional fileName, mimeType, tags, poolId
+     * @returns Promise resolving to search results with matching entries and source nodes
+     * @see Requirements 8.5
+     */
+    searchCBLMetadata(query: CBLMetadataSearchQuery): Promise<CBLMetadataSearchResult>;
 }
 //# sourceMappingURL=discoveryProtocol.d.ts.map

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

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

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

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

@@ -6,18 +6,82 @@
  * efficient block discovery without polling.
  *
  * @see Requirements 6.1, 6.2, 6.3, 6.4, 6.5, 6.6
+ * @see Requirements 1.1, 1.2, 1.3, 1.5, 1.6, 10.1 (Unified Gossip Delivery)
  */
+import type { ICBLIndexEntry } from '../storage/cblIndex';
+import { PoolId } from '../storage/pooledBlockStore';
+/**
+ * Metadata for message delivery via gossip protocol.
+ * Attached to 'add' type BlockAnnouncements to indicate the announcement
+ * is part of a logical message delivery.
+ *
+ * @see Requirements 1.2
+ */
+export interface MessageDeliveryMetadata {
+    /** Unique identifier for the message being delivered */
+    messageId: string;
+    /** IDs of the intended recipients */
+    recipientIds: string[];
+    /** Delivery priority level affecting fanout and TTL */
+    priority: 'normal' | 'high';
+    /** Block IDs containing the message content */
+    blockIds: string[];
+    /** The CBL block ID that serves as the manifest for this delivery */
+    cblBlockId: string;
+    /** Whether the recipient should send a delivery acknowledgment */
+    ackRequired: boolean;
+}
+/**
+ * Metadata for delivery acknowledgment via gossip protocol.
+ * Attached to 'ack' type BlockAnnouncements to confirm message receipt.
+ *
+ * @see Requirements 1.3
+ */
+export interface DeliveryAckMetadata {
+    /** The message ID being acknowledged */
+    messageId: string;
+    /** The recipient ID sending the acknowledgment */
+    recipientId: string;
+    /** The delivery status being reported */
+    status: 'delivered' | 'read' | 'failed' | 'bounced';
+    /** The node ID of the original message sender */
+    originalSenderNode: string;
+}
+/**
+ * Metadata for HeadRegistry head pointer update announcements.
+ * Attached to 'head_update' type BlockAnnouncements to propagate
+ * head pointer changes across nodes.
+ *
+ * @see Requirements 2.1
+ */
+export interface HeadUpdateMetadata {
+    /** The database name containing the collection */
+    dbName: string;
+    /** The collection whose head pointer was updated */
+    collectionName: string;
+}
 /**
  * Block announcement message sent via gossip protocol.
- * Contains information about a block being added or removed from a node.
+ * Contains information about a block being added, removed, or acknowledged.
  *
  * @see Requirements 6.1, 6.5
+ * @see Requirements 1.1, 1.2, 1.3, 1.5, 1.6
  */
 export interface BlockAnnouncement {
     /**
-     * Type of announcement: 'add' for new blocks, 'remove' for deleted blocks
+     * Type of announcement:
+     * - 'add' for new blocks (may include messageDelivery metadata)
+     * - 'remove' for deleted blocks
+     * - 'ack' for delivery acknowledgments (must include deliveryAck metadata)
+     * - 'pool_deleted' for pool deletion propagation (requires poolId)
+     * - 'cbl_index_update' for new/updated CBL index entries (requires cblIndexEntry and poolId)
+     * - 'cbl_index_delete' for soft-deleted CBL index entries (requires cblIndexEntry and poolId)
+     * - 'head_update' for HeadRegistry head pointer updates (requires headUpdate metadata)
+     * - 'acl_update' for approved ACL updates (requires poolId and aclBlockId)
+     *
+     * @see Requirements 1.1, 2.1, 8.1, 8.6, 13.4
      */
-    type: 'add' | 'remove';
+    type: 'add' | 'remove' | 'ack' | 'pool_deleted' | 'cbl_index_update' | 'cbl_index_delete' | 'head_update' | 'acl_update';
     /**
      * The block ID being announced (hex string)
      */
@@ -37,16 +101,73 @@ export interface BlockAnnouncement {
      * @see Requirements 6.4
      */
     ttl: number;
+    /**
+     * Optional message delivery metadata. Only allowed on 'add' type announcements.
+     *
+     * @see Requirements 1.2, 1.5
+     */
+    messageDelivery?: MessageDeliveryMetadata;
+    /**
+     * Optional delivery acknowledgment metadata. Only allowed on 'ack' type announcements.
+     *
+     * @see Requirements 1.3, 1.6
+     */
+    deliveryAck?: DeliveryAckMetadata;
+    /**
+     * Optional pool ID for pool-scoped announcements.
+     * Required for 'pool_deleted', 'cbl_index_update', and 'cbl_index_delete' types.
+     * Optional for 'add' and 'remove' types.
+     *
+     * @see Requirements 1.5, 1.6, 2.1, 8.1, 8.6
+     */
+    poolId?: PoolId;
+    /**
+     * Optional CBL index entry data for CBL index synchronization.
+     * Required for 'cbl_index_update' and 'cbl_index_delete' types.
+     * Contains the entry being announced (update) or the entry being soft-deleted (delete).
+     *
+     * @see Requirements 8.1, 8.6
+     */
+    cblIndexEntry?: ICBLIndexEntry;
+    /**
+     * Optional HeadRegistry update metadata for head pointer synchronization.
+     * Required for 'head_update' type announcements.
+     * The blockId field carries the new head block ID.
+     *
+     * @see Requirements 2.1
+     */
+    headUpdate?: HeadUpdateMetadata;
+    /**
+     * Optional ACL block ID for ACL update propagation.
+     * Required for 'acl_update' type announcements.
+     * Contains the block ID of the approved ACL document in the block store.
+     *
+     * @see Requirements 13.4
+     */
+    aclBlockId?: string;
+}
+/**
+ * Configuration for priority-based gossip propagation.
+ * Defines fanout and TTL values for a specific priority level.
+ *
+ * @see Requirements 10.1
+ */
+export interface PriorityGossipConfig {
+    /** Number of peers to forward announcements to */
+    fanout: number;
+    /** Time-to-live: number of hops for announcements */
+    ttl: number;
 }
 /**
  * Configuration for the gossip protocol.
  *
- * @see Requirements 6.3, 6.4, 6.6
+ * @see Requirements 6.3, 6.4, 6.6, 10.1
  */
 export interface GossipConfig {
     /**
      * Number of peers to forward announcements to (fanout).
      * Higher values increase propagation speed but also network traffic.
+     * This is the default fanout for block-level announcements.
      *
      * @see Requirements 6.3
      */
@@ -54,6 +175,7 @@ export interface GossipConfig {
     /**
      * Initial TTL for new announcements.
      * Controls how far announcements propagate through the network.
+     * This is the default TTL for block-level announcements.
      *
      * @see Requirements 6.4
      */
@@ -72,9 +194,21 @@ export interface GossipConfig {
      * @see Requirements 6.6
      */
     maxBatchSize: number;
+    /**
+     * Priority-based overrides for message delivery.
+     * Defines fanout and TTL values for normal and high priority messages.
+     *
+     * @see Requirements 10.1
+     */
+    messagePriority: {
+        normal: PriorityGossipConfig;
+        high: PriorityGossipConfig;
+    };
 }
 /**
  * Default gossip configuration values.
+ *
+ * @see Requirements 10.1
  */
 export declare const DEFAULT_GOSSIP_CONFIG: GossipConfig;
 /**
@@ -96,19 +230,71 @@ export interface IGossipService {
      * The announcement will be batched and sent to a random subset of peers.
      *
      * @param blockId - The block ID to announce
+     * @param poolId - Optional pool the block belongs to
      * @returns Promise that resolves when the announcement is queued
-     * @see Requirements 6.1
+     * @see Requirements 6.1, 1.1, 6.3
      */
-    announceBlock(blockId: string): Promise<void>;
+    announceBlock(blockId: string, poolId?: PoolId): 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
+     * @param poolId - Optional pool the block belonged to
      * @returns Promise that resolves when the announcement is queued
-     * @see Requirements 6.5
+     * @see Requirements 6.5, 2.2
      */
-    announceRemoval(blockId: string): Promise<void>;
+    announceRemoval(blockId: string, poolId?: PoolId): Promise<void>;
+    /**
+     * Announce that a pool has been deleted.
+     * Creates a pool_deleted announcement propagated as a tombstone.
+     *
+     * @param poolId - The pool that was deleted
+     * @returns Promise that resolves when the announcement is queued
+     * @see Requirements 2.2, 6.3
+     */
+    announcePoolDeletion(poolId: PoolId): Promise<void>;
+    /**
+     * Announce a new or updated CBL index entry to peers in the same pool.
+     * Creates a cbl_index_update announcement scoped to the entry's pool.
+     *
+     * @param entry - The CBL index entry being announced
+     * @returns Promise that resolves when the announcement is queued
+     * @see Requirements 8.1
+     */
+    announceCBLIndexUpdate(entry: ICBLIndexEntry): Promise<void>;
+    /**
+     * Announce a soft-deleted CBL index entry to peers in the same pool.
+     * Creates a cbl_index_delete announcement so peers also mark the entry as deleted.
+     *
+     * @param entry - The CBL index entry that was soft-deleted (with deletedAt set)
+     * @returns Promise that resolves when the announcement is queued
+     * @see Requirements 8.6
+     */
+    announceCBLIndexDelete(entry: ICBLIndexEntry): Promise<void>;
+    /**
+     * Announce a HeadRegistry head pointer update to peer nodes.
+     * Creates a head_update announcement with the database name, collection name,
+     * and new head block ID.
+     *
+     * @param dbName - The database name containing the collection
+     * @param collectionName - The collection whose head pointer was updated
+     * @param blockId - The new head block ID
+     * @returns Promise that resolves when the announcement is queued
+     * @see Requirements 2.1
+     */
+    announceHeadUpdate(dbName: string, collectionName: string, blockId: string): Promise<void>;
+    /**
+     * Announce an approved ACL update to peers in the same pool.
+     * Creates an acl_update announcement with the pool ID and the block ID
+     * of the signed ACL document stored in the block store.
+     *
+     * @param poolId - The pool whose ACL was updated
+     * @param aclBlockId - The block ID of the approved ACL document
+     * @returns Promise that resolves when the announcement is queued
+     * @see Requirements 13.4
+     */
+    announceACLUpdate(poolId: string, aclBlockId: string): Promise<void>;
     /**
      * Handle an incoming block announcement from a peer.
      * Updates local location metadata and optionally forwards the announcement.
@@ -162,5 +348,90 @@ export interface IGossipService {
      * @returns The gossip configuration
      */
     getConfig(): GossipConfig;
+    /**
+     * Announce message blocks to the network with message delivery metadata.
+     * Creates BlockAnnouncements with messageDelivery metadata, applies
+     * priority-based fanout/TTL from config, and queues for batch sending.
+     *
+     * @param blockIds - The block IDs containing the message content
+     * @param metadata - Message delivery metadata including recipients, priority, and CBL block ID
+     * @returns Promise that resolves when the announcements are queued
+     * @see Requirements 3.1 (message-aware gossip delivery)
+     */
+    announceMessage(blockIds: string[], metadata: MessageDeliveryMetadata): Promise<void>;
+    /**
+     * Send a delivery acknowledgment back through the gossip network.
+     * Creates a BlockAnnouncement of type 'ack' with deliveryAck metadata
+     * and queues it for propagation.
+     *
+     * @param ack - Delivery acknowledgment metadata including messageId, recipientId, status, and originalSenderNode
+     * @returns Promise that resolves when the ack announcement is queued
+     * @see Requirements 4.1 (delivery acknowledgment via gossip)
+     */
+    sendDeliveryAck(ack: DeliveryAckMetadata): Promise<void>;
+    /**
+     * Register a handler for message delivery events.
+     * The handler is called when a BlockAnnouncement with messageDelivery
+     * metadata is received and the recipientIds match local users.
+     *
+     * @param handler - Function to call when a message delivery announcement is received
+     * @see Requirements 3.4, 3.5 (message receipt handling)
+     */
+    onMessageDelivery(handler: (announcement: BlockAnnouncement) => void): void;
+    /**
+     * Remove a message delivery event handler.
+     *
+     * @param handler - The handler to remove
+     * @see Requirements 3.4, 3.5 (message receipt handling)
+     */
+    offMessageDelivery(handler: (announcement: BlockAnnouncement) => void): void;
+    /**
+     * Register a handler for delivery acknowledgment events.
+     * The handler is called when a BlockAnnouncement of type 'ack' with
+     * deliveryAck metadata is received at the original sender node.
+     *
+     * @param handler - Function to call when a delivery ack announcement is received
+     * @see Requirements 4.1 (delivery acknowledgment via gossip)
+     */
+    onDeliveryAck(handler: (announcement: BlockAnnouncement) => void): void;
+    /**
+     * Remove a delivery acknowledgment event handler.
+     *
+     * @param handler - The handler to remove
+     * @see Requirements 4.1 (delivery acknowledgment via gossip)
+     */
+    offDeliveryAck(handler: (announcement: BlockAnnouncement) => void): void;
 }
+/**
+ * Validates a BlockAnnouncement, enforcing field-type constraints.
+ *
+ * Validation rules:
+ * - messageDelivery is only allowed on 'add' type announcements (Req 1.5)
+ * - deliveryAck is only allowed on 'ack' type announcements (Req 1.6)
+ * - When messageDelivery is present, all fields must be complete and valid
+ * - When deliveryAck is present, all fields must be complete and valid
+ *
+ * @param announcement - The BlockAnnouncement to validate
+ * @returns true if the announcement is valid, false otherwise
+ *
+ * @see Requirements 1.1, 1.2, 1.3, 1.5, 1.6
+ */
+export declare function validateBlockAnnouncement(announcement: BlockAnnouncement): boolean;
+/**
+ * Validates a GossipConfig, ensuring all fanout and TTL values are positive integers.
+ *
+ * Validation rules:
+ * - config.fanout must be a positive integer (Req 10.3)
+ * - config.defaultTtl must be a positive integer (Req 10.4)
+ * - config.messagePriority.normal.fanout must be a positive integer (Req 10.3)
+ * - config.messagePriority.normal.ttl must be a positive integer (Req 10.4)
+ * - config.messagePriority.high.fanout must be a positive integer (Req 10.3)
+ * - config.messagePriority.high.ttl must be a positive integer (Req 10.4)
+ *
+ * @param config - The GossipConfig to validate
+ * @returns true if all values are valid, false otherwise
+ *
+ * @see Requirements 10.3, 10.4
+ */
+export declare function validateGossipConfig(config: GossipConfig): boolean;
 //# sourceMappingURL=gossipService.d.ts.map

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

@@ -1 +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"}
+{"version":3,"file":"gossipService.d.ts","sourceRoot":"","sources":["../../../../../../brightchain-lib/src/lib/interfaces/availability/gossipService.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAC1D,OAAO,EAAE,MAAM,EAAiB,MAAM,6BAA6B,CAAC;AAEpE;;;;;;GAMG;AACH,MAAM,WAAW,uBAAuB;IACtC,wDAAwD;IACxD,SAAS,EAAE,MAAM,CAAC;IAElB,qCAAqC;IACrC,YAAY,EAAE,MAAM,EAAE,CAAC;IAEvB,uDAAuD;IACvD,QAAQ,EAAE,QAAQ,GAAG,MAAM,CAAC;IAE5B,+CAA+C;IAC/C,QAAQ,EAAE,MAAM,EAAE,CAAC;IAEnB,qEAAqE;IACrE,UAAU,EAAE,MAAM,CAAC;IAEnB,kEAAkE;IAClE,WAAW,EAAE,OAAO,CAAC;CACtB;AAED;;;;;GAKG;AACH,MAAM,WAAW,mBAAmB;IAClC,wCAAwC;IACxC,SAAS,EAAE,MAAM,CAAC;IAElB,kDAAkD;IAClD,WAAW,EAAE,MAAM,CAAC;IAEpB,yCAAyC;IACzC,MAAM,EAAE,WAAW,GAAG,MAAM,GAAG,QAAQ,GAAG,SAAS,CAAC;IAEpD,iDAAiD;IACjD,kBAAkB,EAAE,MAAM,CAAC;CAC5B;AAED;;;;;;GAMG;AACH,MAAM,WAAW,kBAAkB;IACjC,kDAAkD;IAClD,MAAM,EAAE,MAAM,CAAC;IAEf,oDAAoD;IACpD,cAAc,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;;;;;;;;;;OAYG;IACH,IAAI,EACA,KAAK,GACL,QAAQ,GACR,KAAK,GACL,cAAc,GACd,kBAAkB,GAClB,kBAAkB,GAClB,aAAa,GACb,YAAY,CAAC;IAEjB;;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;IAEZ;;;;OAIG;IACH,eAAe,CAAC,EAAE,uBAAuB,CAAC;IAE1C;;;;OAIG;IACH,WAAW,CAAC,EAAE,mBAAmB,CAAC;IAElC;;;;;;OAMG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB;;;;;;OAMG;IACH,aAAa,CAAC,EAAE,cAAc,CAAC;IAE/B;;;;;;OAMG;IACH,UAAU,CAAC,EAAE,kBAAkB,CAAC;IAEhC;;;;;;OAMG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;GAKG;AACH,MAAM,WAAW,oBAAoB;IACnC,kDAAkD;IAClD,MAAM,EAAE,MAAM,CAAC;IAEf,qDAAqD;IACrD,GAAG,EAAE,MAAM,CAAC;CACb;AAED;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B;;;;;;OAMG;IACH,MAAM,EAAE,MAAM,CAAC;IAEf;;;;;;OAMG;IACH,UAAU,EAAE,MAAM,CAAC;IAEnB;;;;;OAKG;IACH,eAAe,EAAE,MAAM,CAAC;IAExB;;;;;OAKG;IACH,YAAY,EAAE,MAAM,CAAC;IAErB;;;;;OAKG;IACH,eAAe,EAAE;QACf,MAAM,EAAE,oBAAoB,CAAC;QAC7B,IAAI,EAAE,oBAAoB,CAAC;KAC5B,CAAC;CACH;AAED;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,EAAE,YASnC,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,mBAAmB,GAAG,CAAC,YAAY,EAAE,iBAAiB,KAAK,IAAI,CAAC;AAE5E;;;;;;;;GAQG;AACH,MAAM,WAAW,cAAc;IAC7B;;;;;;;;OAQG;IACH,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE/D;;;;;;;;OAQG;IACH,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEjE;;;;;;;OAOG;IACH,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEpD;;;;;;;OAOG;IACH,sBAAsB,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE7D;;;;;;;OAOG;IACH,sBAAsB,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE7D;;;;;;;;;;OAUG;IACH,kBAAkB,CAChB,MAAM,EAAE,MAAM,EACd,cAAc,EAAE,MAAM,EACtB,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,IAAI,CAAC,CAAC;IAEjB;;;;;;;;;OASG;IACH,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAErE;;;;;;;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;IAE1B;;;;;;;;;OASG;IACH,eAAe,CACb,QAAQ,EAAE,MAAM,EAAE,EAClB,QAAQ,EAAE,uBAAuB,GAChC,OAAO,CAAC,IAAI,CAAC,CAAC;IAEjB;;;;;;;;OAQG;IACH,eAAe,CAAC,GAAG,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEzD;;;;;;;OAOG;IACH,iBAAiB,CAAC,OAAO,EAAE,CAAC,YAAY,EAAE,iBAAiB,KAAK,IAAI,GAAG,IAAI,CAAC;IAE5E;;;;;OAKG;IACH,kBAAkB,CAAC,OAAO,EAAE,CAAC,YAAY,EAAE,iBAAiB,KAAK,IAAI,GAAG,IAAI,CAAC;IAE7E;;;;;;;OAOG;IACH,aAAa,CAAC,OAAO,EAAE,CAAC,YAAY,EAAE,iBAAiB,KAAK,IAAI,GAAG,IAAI,CAAC;IAExE;;;;;OAKG;IACH,cAAc,CAAC,OAAO,EAAE,CAAC,YAAY,EAAE,iBAAiB,KAAK,IAAI,GAAG,IAAI,CAAC;CAC1E;AA0BD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,yBAAyB,CACvC,YAAY,EAAE,iBAAiB,GAC9B,OAAO,CAmMT;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CA4ClE"}