@bsv/sdk
Version:
BSV Blockchain Software Development Kit
115 lines • 4.65 kB
TypeScript
/**
* The question asked to the Overlay Services Engine when a consumer of state wishes to look up information.
*/
export interface LookupQuestion {
/**
* The identifier for a Lookup Service which the person asking the question wishes to use.
*/
service: string;
/**
* The query which will be forwarded to the Lookup Service.
* Its type depends on that prescribed by the Lookup Service employed.
*/
query: unknown;
}
/**
* How the Overlay Services Engine responds to a Lookup Question.
* It may comprise either an output list or a freeform response from the Lookup Service.
*/
export type LookupAnswer = {
type: 'output-list';
outputs: Array<{
beef: number[];
outputIndex: number;
context?: number[];
}>;
};
/** Default SLAP trackers */
export declare const DEFAULT_SLAP_TRACKERS: string[];
/** Default testnet SLAP trackers */
export declare const DEFAULT_TESTNET_SLAP_TRACKERS: string[];
/** Internal cache options. Kept optional to preserve drop-in compatibility. */
interface CacheOptions {
/** How long (ms) a hosts entry is considered fresh. Default 5 minutes. */
hostsTtlMs?: number;
/** How many distinct services’ hosts to cache before evicting. Default 128. */
hostsMaxEntries?: number;
/** How long (ms) to keep txId memoization. Default 10 minutes. */
txMemoTtlMs?: number;
}
/** Configuration options for the Lookup resolver. */
export interface LookupResolverConfig {
/**
* The network preset to use, unless other options override it.
* - mainnet: use mainnet SLAP trackers and HTTPS facilitator
* - testnet: use testnet SLAP trackers and HTTPS facilitator
* - local: directly query from localhost:8080 and a facilitator that permits plain HTTP
*/
networkPreset?: 'mainnet' | 'testnet' | 'local';
/** The facilitator used to make requests to Overlay Services hosts. */
facilitator?: OverlayLookupFacilitator;
/** The list of SLAP trackers queried to resolve Overlay Services hosts for a given lookup service. */
slapTrackers?: string[];
/** Map of lookup service names to arrays of hosts to use in place of resolving via SLAP. */
hostOverrides?: Record<string, string[]>;
/** Map of lookup service names to arrays of hosts to use in addition to resolving via SLAP. */
additionalHosts?: Record<string, string[]>;
/** Optional cache tuning. */
cache?: CacheOptions;
}
/** Facilitates lookups to URLs that return answers. */
export interface OverlayLookupFacilitator {
/**
* Returns a lookup answer for a lookup question
* @param url - Overlay Service URL to send the lookup question to.
* @param question - Lookup question to find an answer to.
* @param timeout - Specifics how long to wait for a lookup answer in milliseconds.
* @returns
*/
lookup: (url: string, question: LookupQuestion, timeout?: number) => Promise<LookupAnswer>;
}
export declare class HTTPSOverlayLookupFacilitator implements OverlayLookupFacilitator {
fetchClient: typeof fetch;
allowHTTP: boolean;
constructor(httpClient?: any, allowHTTP?: boolean);
lookup(url: string, question: LookupQuestion, timeout?: number): Promise<LookupAnswer>;
}
/**
* Represents a Lookup Resolver.
*/
export default class LookupResolver {
private readonly facilitator;
private readonly slapTrackers;
private readonly hostOverrides;
private readonly additionalHosts;
private readonly networkPreset;
private readonly hostsCache;
private readonly hostsInFlight;
private readonly hostsTtlMs;
private readonly hostsMaxEntries;
private readonly txMemo;
private readonly txMemoTtlMs;
constructor(config?: LookupResolverConfig);
/**
* Given a LookupQuestion, returns a LookupAnswer. Aggregates across multiple services and supports resiliency.
*/
query(question: LookupQuestion, timeout?: number): Promise<LookupAnswer>;
/**
* Cached wrapper for competent host discovery with stale-while-revalidate.
*/
private getCompetentHostsCached;
/**
* Actually resolves competent hosts from SLAP trackers and updates cache.
*/
private refreshHosts;
/**
* Returns a list of competent hosts for a given lookup service.
* @param service Service for which competent hosts are to be returned
* @returns Array of hosts competent for resolving queries
*/
private findCompetentHosts;
/** Evict an arbitrary “oldest” entry from a Map (iteration order). */
private evictOldest;
}
export {};
//# sourceMappingURL=LookupResolver.d.ts.map