@bsv/overlay
Version:
BSV Blockchain Overlay Services Engine
223 lines • 12.9 kB
TypeScript
import { TopicManager } from './TopicManager.js';
import { LookupService } from './LookupService.js';
import { Storage } from './storage/Storage.js';
import type { Output } from './Output.js';
import { ChainTracker, MerklePath, Broadcaster, TaggedBEEF, STEAK, LookupQuestion, LookupAnswer, OverlayBroadcastFacilitator } from '@bsv/sdk';
import { Advertiser } from './Advertiser.js';
import { GASPInitialRequest, GASPInitialResponse, GASPNode } from '@bsv/gasp';
import { SyncConfiguration } from './SyncConfiguration.js';
/**
* An engine for running BSV Overlay Services (topic managers and lookup services).
*/
export declare class Engine {
managers: {
[key: string]: TopicManager;
};
lookupServices: {
[key: string]: LookupService;
};
storage: Storage;
chainTracker: ChainTracker | 'scripts only';
hostingURL?: string | undefined;
shipTrackers?: string[] | undefined;
slapTrackers?: string[] | undefined;
broadcaster?: Broadcaster | undefined;
advertiser?: Advertiser | undefined;
syncConfiguration?: SyncConfiguration | undefined;
logTime: boolean;
logPrefix: string;
throwOnBroadcastFailure: boolean;
overlayBroadcastFacilitator: OverlayBroadcastFacilitator;
logger: typeof console;
suppressDefaultSyncAdvertisements: boolean;
/**
* Creates a new Overlay Services Engine
* @param {[key: string]: TopicManager} managers - manages topic admittance
* @param {[key: string]: LookupService} lookupServices - manages UTXO lookups
* @param {Storage} storage - for interacting with internally-managed persistent data
* @param {ChainTracker | 'scripts only'} chainTracker - Verifies SPV data associated with transactions
* @param {string} [hostingURL] - The URL this engine is hosted at. Required if going to support peer-discovery with an advertiser.
* @param {Broadcaster} [Broadcaster] - broadcaster used for broadcasting the incoming transaction
* @param {Advertiser} [Advertiser] - handles SHIP and SLAP advertisements for peer-discovery
* @param {string[]} shipTrackers - SHIP domains we know to bootstrap the system
* @param {string[]} slapTrackers - SLAP domains we know to bootstrap the system
* @param {SyncConfiguration} syncConfiguration — Configuration object describing historical synchronization of topics.
* @param {boolean} logTime - Enables / disables the timing logs for various operations in the Overlay submit route.
* @param {string} logPrefix - Supports overriding the log prefix with a custom string.
* @param {boolean} throwOnBroadcastFailure - Enables / disables throwing an error when a transaction broadcast failure is detected.
* @param {OverlayBroadcastFacilitator} overlayBroadcastFacilitator - Facilitator for propagation to other Overlay Services.
* @param {typeof console} logger - The place where log entries are written.
* @param {boolean} suppressDefaultSyncAdvertisements - Whether to suppress the default (SHIP/SLAP) sync advertisements.
*/
constructor(managers: {
[key: string]: TopicManager;
}, lookupServices: {
[key: string]: LookupService;
}, storage: Storage, chainTracker: ChainTracker | 'scripts only', hostingURL?: string | undefined, shipTrackers?: string[] | undefined, slapTrackers?: string[] | undefined, broadcaster?: Broadcaster | undefined, advertiser?: Advertiser | undefined, syncConfiguration?: SyncConfiguration | undefined, logTime?: boolean, logPrefix?: string, throwOnBroadcastFailure?: boolean, overlayBroadcastFacilitator?: OverlayBroadcastFacilitator, logger?: typeof console, suppressDefaultSyncAdvertisements?: boolean);
private startTime;
private endTime;
/**
* Submits a transaction for processing by Overlay Services.
* @param {TaggedBEEF} taggedBEEF - The transaction to process
* @param {function(STEAK): void} [onSTEAKReady] - Optional callback function invoked when the STEAK is ready.
* @param {string} mode — Indicates the submission behavior, whether historical or current. Historical transactions are not broadcast or propagated.
* @param {number[]} offChainValues — Values necessary to evaluate topical admittance that are not stored on-chain.
*
* The optional callback function should be used to get STEAK when ready, and avoid waiting for broadcast and transaction propagation to complete.
*
* @returns {Promise<STEAK>} The submitted transaction execution acknowledgement
*/
submit(taggedBEEF: TaggedBEEF, onSteakReady?: (steak: STEAK) => void, mode?: 'historical-tx' | 'current-tx', offChainValues?: number[]): Promise<STEAK>;
/**
* Submit a lookup question to the Overlay Services Engine, and receive back a Lookup Answer
* @param LookupQuestion — The question to ask the Overlay Services Engine
* @returns The answer to the question
*/
lookup(lookupQuestion: LookupQuestion): Promise<LookupAnswer>;
/**
* Ensures alignment between the current SHIP/SLAP advertisements and the
* configured Topic Managers and Lookup Services in the engine.
*
* This method performs the following actions:
* 1. Retrieves the current configuration of topics and services.
* 2. Fetches the existing SHIP advertisements for each configured topic.
* 3. Fetches the existing SLAP advertisements for each configured service.
* 4. Compares the current configuration with the fetched advertisements to determine which advertisements
* need to be created or revoked.
* 5. Creates new SHIP/SLAP advertisements if they do not exist for the configured topics/services.
* 6. Revokes existing SHIP/SLAP advertisements if they are no longer required based on the current configuration.
*
* The function uses the `Advertiser` methods to create or revoke advertisements and ensures the updates are
* submitted to the SHIP/SLAP overlay networks using the engine's `submit()` method.
*
* @throws Will throw an error if there are issues during the advertisement synchronization process.
* @returns {Promise<void>} A promise that resolves when the synchronization process is complete.
*/
syncAdvertisements(): Promise<void>;
/**
* This method goes through each topic that we support syncing and attempts to sync with each endpoint
* associated with that topic. If the sync configuration is 'SHIP', it will sync to all peers that support
* the topic.
*
* @throws Error if the overlay service engine is not configured for topical synchronization.
*/
startGASPSync(): Promise<void>;
/**
* Given a GASP request, create an initial response.
*
* This method processes an initial synchronization request by finding the relevant UTXOs for the given topic
* since the provided block height in the request. It constructs a response that includes a list of these UTXOs
* and the min block height from the initial request.
*
* @param initialRequest - The GASP initial request containing the version and the block height since the last sync.
* @param topic - The topic for which UTXOs are being requested.
* @returns A promise that resolves to a GASPInitialResponse containing the list of UTXOs and the provided min block height.
*/
provideForeignSyncResponse(initialRequest: GASPInitialRequest, topic: string): Promise<GASPInitialResponse>;
/**
* Provides a GASPNode for the given graphID, transaction ID, and output index.
*
* @param graphID - The identifier for the graph to which this node belongs (in the format txid.outputIndex).
* @param txid - The transaction ID for the requested output from somewhere within the graph's history.
* @param outputIndex - The index of the output in the transaction.
* @returns A promise that resolves to a GASPNode containing the raw transaction and other optional data.
* @throws An error if no output is found for the given transaction ID and output index.
*/
provideForeignGASPNode(graphID: string, txid: string, outputIndex: number): Promise<GASPNode>;
/**
* Traverse and return the history of a UTXO.
*
* This method traverses the history of a given Unspent Transaction Output (UTXO) and returns
* its historical data based on the provided history selector and current depth.
*
* @param output - The UTXO to traverse the history for.
* @param historySelector - Optionally directs the history traversal:
* - If a number, denotes how many previous spends (in terms of chain depth) to include.
* - If a function, accepts a BEEF-formatted transaction, an output index, and the current depth as parameters,
* returning a promise that resolves to a boolean indicating whether to include the output in the history.
* @param {number} [currentDepth=0] - The current depth of the traversal relative to the top-level UTXO.
*
* @returns {Promise<Output | undefined>} - A promise that resolves to the output history if found, or undefined if not.
*/
getUTXOHistory(output: Output, historySelector?: ((beef: number[], outputIndex: number, currentDepth: number) => Promise<boolean>) | number, currentDepth?: number): Promise<Output | undefined>;
/**
* Delete a UTXO and all stale consumed inputs.
* @param output - The UTXO to be deleted.
* @returns {Promise<void>} - A promise that resolves when the deletion process is complete.
*/
private deleteUTXODeep;
/**
* Given a new transaction proof (txid, proof),
* update tx.merklePath if appropriate,
* and if not, recurse through all input sourceTransactions.
*
* @param tx transaction which may benefit from new proof.
* @param txid BE hex string double hash of transaction proven by proof.
* @param proof for txid
*/
private updateInputProofs;
/**
* Recursively updates beefs (merkle proofs) of this output and its consumedBy lineage.
*
* @param output - An output derived from txid which may benefit from new proof.
* @param txid - The txid for which proof is a valid merkle path.
* @param proof - The merklePath proving txid is a mined transaction hash
*/
private updateMerkleProof;
/**
* Recursively prune UTXOs when an incoming Merkle Proof is received.
*
* @param txid - Transaction ID of the associated outputs to prune.
* @param proof - Merkle proof containing the Merkle path and other relevant data to verify the transaction.
* @param blockHeight - The block height associated with the incoming merkle proof.
*/
handleNewMerkleProof(txid: string, proof: MerklePath, blockHeight?: number): Promise<void>;
/**
* Find a list of supported topic managers
* @public
* @returns {Promise<Record<string, { name: string; shortDescription: string; iconURL?: string; version?: string; informationURL?: string; }>>} - Supported topic managers and their metadata
*/
listTopicManagers(): Promise<Record<string, {
name: string;
shortDescription: string;
iconURL?: string;
version?: string;
informationURL?: string;
}>>;
/**
* Find a list of supported lookup services
* @public
* @returns {Promise<Record<string, { name: string; shortDescription: string; iconURL?: string; version?: string; informationURL?: string; }>>} - Supported lookup services and their metadata
*/
listLookupServiceProviders(): Promise<Record<string, {
name: string;
shortDescription: string;
iconURL?: string;
version?: string;
informationURL?: string;
}>>;
/**
* Run a query to get the documentation for a particular topic manager
* @public
* @returns {Promise<string>} - the documentation for the topic manager
*/
getDocumentationForTopicManager(manager: any): Promise<string>;
/**
* Run a query to get the documentation for a particular lookup service
* @public
* @returns {Promise<string>} - the documentation for the lookup service
*/
getDocumentationForLookupServiceProvider(provider: any): Promise<string>;
/**
* Validates a URL to ensure it does not match disallowed patterns:
* - Contains "http:" protocol
* - Contains "localhost" (with or without a port)
* - Internal or non-routable IP addresses (e.g., 192.168.x.x, 10.x.x.x, 172.16.x.x to 172.31.x.x)
* - Non-routable IPs like 127.x.x.x, 0.0.0.0, or IPv6 loopback (::1)
*
* @param url - The URL string to validate
* @returns {boolean} - Returns `false` if the URL violates any of the conditions `true` otherwise
*/
private isValidUrl;
}
//# sourceMappingURL=Engine.d.ts.map