@bsv/overlay-express/dist/types/src/ReorgStream.d.ts

BSV Blockchain Overlay Express

/**
 * Consumes the go-chaintracks (Arcade) reorg SSE stream (`GET /v2/reorg/stream`)
 * and normalizes each `ReorgEvent` into the overlay engine's `handleReorg` input.
 *
 * The stream emits `data: <JSON>\n\n` frames (no `event:`/`id:` lines) with
 * `: keepalive` comment frames in between. Because there are no event ids, a
 * reconnect cannot replay events missed while disconnected — so every (re)connect
 * triggers an `onConnect` catch-up (the engine's revalidation sweep).
 */
/** Input shape accepted by `Engine.handleReorg`. */
export interface ReorgHandlerInput {
    orphanedBlockHashes: string[];
    rebuildFromHeight: number;
    newTipHeight: number;
}
/**
 * Parses a single SSE data frame (a go-chaintracks `ReorgEvent` JSON document)
 * into `handleReorg` input. Returns `null` for malformed frames.
 *
 * `ReorgEvent` = { orphanedHashes: string[], commonAncestor: BlockHeader|null,
 * newTip: BlockHeader, depth: number }. Block hashes are go-sdk `chainhash.Hash`
 * values marshaled as reversed (display) hex; they are lower-cased here to match
 * the overlay's stored block hashes.
 */
export declare function parseReorgEvent(frame: string): ReorgHandlerInput | null;
/**
 * Splits an SSE byte buffer into complete event payloads. Frames are delimited by
 * a blank line (`\n\n`); within a frame, `data:` lines are concatenated and
 * comment lines (starting with `:`) are ignored. Any trailing partial frame is
 * returned in `rest` for the next read.
 */
export declare function extractSseFrames(buffer: string): {
    events: string[];
    rest: string;
};
export interface ReorgSseAdapterOptions {
    /** Reorg SSE URL, e.g. `https://arcade.example/v2/reorg/stream`. */
    url: string;
    /** Invoked for each parsed reorg event. */
    onReorg: (input: ReorgHandlerInput) => Promise<void>;
    /** Invoked on every (re)connect for catch-up, since the stream has no replay. */
    onConnect?: () => Promise<void>;
    logger?: Pick<typeof console, 'log' | 'warn' | 'error'>;
    /** Delay before reconnecting after the stream ends or errors. */
    reconnectDelayMs?: number;
    /** Injectable fetch (defaults to global fetch); aids testing. */
    fetchImpl?: typeof fetch;
}
/**
 * Long-lived SSE client that keeps the overlay's BASM anchors reconciled with
 * chain reorgs. Auto-reconnects with a fixed delay and runs a catch-up on connect.
 */
export declare class ReorgSseAdapter {
    private readonly url;
    private readonly onReorg;
    private readonly onConnect?;
    private readonly logger;
    private readonly reconnectDelayMs;
    private readonly fetchImpl;
    private controller?;
    private stopped;
    constructor(options: ReorgSseAdapterOptions);
    /** Begins consuming the stream in the background. */
    start(): void;
    /** Stops consuming and aborts any in-flight connection. */
    stop(): void;
    private runLoop;
    private connectOnce;
    private runCatchUp;
    private pumpEvents;
    private processReorgFrame;
    private delay;
}
//# sourceMappingURL=ReorgStream.d.ts.map