@thru/replay 0.1.36

package/dist/index.d.cts

@@ -0,0 +1,490 @@
+import { Transport, Interceptor, CallOptions } from '@connectrpc/connect';
+import { ListBlocksRequest, ListBlocksResponse, StreamBlocksRequest, StreamBlocksResponse, ListTransactionsRequest, ListTransactionsResponse, StreamTransactionsRequest, StreamTransactionsResponse, ListEventsRequest, ListEventsResponse, StreamEventsRequest, StreamEventsResponse, StreamAccountUpdatesRequest, StreamAccountUpdatesResponse, GetHeightResponse, Filter, BlockView, ConsensusStatus, Block, Transaction, Event, AccountView, AccountMeta, AccountUpdate } from '@thru/proto';
+export { Account, AccountFlags, AccountMeta, AccountPage, AccountUpdate, AccountView, BlockFinished, Event, Filter, FilterParamValue, FilterParamValueSchema, FilterSchema, Pubkey as ProtoPubkey, Signature as ProtoSignature, StreamAccountUpdatesRequest, StreamAccountUpdatesResponse } from '@thru/proto';
+
+interface ChainClientOptions {
+    baseUrl?: string;
+    apiKey?: string;
+    userAgent?: string;
+    transport?: Transport;
+    interceptors?: Interceptor[];
+    callOptions?: CallOptions;
+    useBinaryFormat?: boolean;
+}
+interface BlockSource {
+    listBlocks(request: Partial<ListBlocksRequest>): Promise<ListBlocksResponse>;
+    streamBlocks(request: Partial<StreamBlocksRequest>): AsyncIterable<StreamBlocksResponse>;
+}
+interface TransactionSource {
+    listTransactions(request: Partial<ListTransactionsRequest>): Promise<ListTransactionsResponse>;
+    streamTransactions(request: Partial<StreamTransactionsRequest>): AsyncIterable<StreamTransactionsResponse>;
+}
+interface EventSource {
+    listEvents(request: Partial<ListEventsRequest>): Promise<ListEventsResponse>;
+    streamEvents(request: Partial<StreamEventsRequest>): AsyncIterable<StreamEventsResponse>;
+}
+interface AccountSource {
+    streamAccountUpdates(request: Partial<StreamAccountUpdatesRequest>): AsyncIterable<StreamAccountUpdatesResponse>;
+}
+type ReplayDataSource = BlockSource & TransactionSource & EventSource & AccountSource;
+declare class ChainClient implements ReplayDataSource {
+    private readonly options;
+    private readonly query;
+    private readonly streaming;
+    private readonly callOptions?;
+    constructor(options: ChainClientOptions);
+    listBlocks(request: Partial<ListBlocksRequest>): Promise<ListBlocksResponse>;
+    streamBlocks(request: Partial<StreamBlocksRequest>): AsyncIterable<StreamBlocksResponse>;
+    listTransactions(request: Partial<ListTransactionsRequest>): Promise<ListTransactionsResponse>;
+    streamTransactions(request: Partial<StreamTransactionsRequest>): AsyncIterable<StreamTransactionsResponse>;
+    listEvents(request: Partial<ListEventsRequest>): Promise<ListEventsResponse>;
+    streamEvents(request: Partial<StreamEventsRequest>): AsyncIterable<StreamEventsResponse>;
+    private createTransport;
+    private createHeaderInterceptor;
+    streamAccountUpdates(request: Partial<StreamAccountUpdatesRequest>): AsyncIterable<StreamAccountUpdatesResponse>;
+    getHeight(): Promise<GetHeightResponse>;
+}
+
+type Slot = bigint;
+interface BackfillPage<T, Cursor = unknown> {
+    items: T[];
+    cursor?: Cursor;
+    done?: boolean;
+}
+type BackfillFetcher<T, Cursor = unknown> = (params: {
+    startSlot: Slot;
+    cursor?: Cursor;
+}) => Promise<BackfillPage<T, Cursor>>;
+type LiveSubscriber<T> = (startSlot: Slot) => AsyncIterable<T>;
+interface ReplayLogger {
+    debug(message: string, meta?: Record<string, unknown>): void;
+    info(message: string, meta?: Record<string, unknown>): void;
+    warn(message: string, meta?: Record<string, unknown>): void;
+    error(message: string, meta?: Record<string, unknown>): void;
+}
+interface ReplayMetrics {
+    bufferedItems: number;
+    emittedBackfill: number;
+    emittedLive: number;
+    discardedDuplicates: number;
+}
+interface ReplayConfig<T, Cursor = unknown> {
+    startSlot: Slot;
+    safetyMargin: bigint;
+    fetchBackfill: BackfillFetcher<T, Cursor>;
+    subscribeLive: LiveSubscriber<T>;
+    extractSlot: (item: T) => Slot;
+    extractKey?: (item: T) => string;
+    logger?: ReplayLogger;
+    resubscribeOnEnd?: boolean;
+}
+
+declare class ReplayStream<T, Cursor = unknown> implements AsyncIterable<T> {
+    private readonly config;
+    private readonly logger;
+    private readonly metrics;
+    constructor(config: ReplayConfig<T, Cursor>);
+    getMetrics(): ReplayMetrics;
+    [Symbol.asyncIterator](): AsyncIterator<T>;
+    private run;
+}
+
+interface BlockReplayOptions {
+    client: BlockSource;
+    startSlot: Slot;
+    safetyMargin?: bigint;
+    pageSize?: number;
+    filter?: Filter;
+    view?: BlockView;
+    minConsensus?: ConsensusStatus;
+    logger?: ReplayLogger;
+    resubscribeOnEnd?: boolean;
+}
+declare function createBlockReplay(options: BlockReplayOptions): ReplayStream<Block, string>;
+
+interface TransactionReplayOptions {
+    client: TransactionSource;
+    startSlot: Slot;
+    safetyMargin?: bigint;
+    pageSize?: number;
+    filter?: Filter;
+    minConsensus?: ConsensusStatus;
+    returnEvents?: boolean;
+    logger?: ReplayLogger;
+    resubscribeOnEnd?: boolean;
+}
+declare function createTransactionReplay(options: TransactionReplayOptions): ReplayStream<Transaction, string>;
+
+interface EventReplayOptions {
+    client: EventSource;
+    startSlot: Slot;
+    safetyMargin?: bigint;
+    pageSize?: number;
+    filter?: Filter;
+    logger?: ReplayLogger;
+    resubscribeOnEnd?: boolean;
+}
+declare function createEventReplay(options: EventReplayOptions): ReplayStream<Event, string>;
+
+/**
+ * Account Replay - streaming account state with backfill reconciliation.
+ *
+ * This module provides account state streaming with:
+ * - Page assembly for large accounts (>4KB)
+ * - Sequence number tracking for ordering
+ * - Backfill reconciliation with live updates
+ * - Block boundary detection via BlockFinished messages
+ */
+
+/**
+ * Represents a complete account state ready for processing
+ */
+interface AccountState {
+    /** Account address as bytes */
+    address: Uint8Array;
+    /** Account address as hex string */
+    addressHex: string;
+    /** Slot at which this state was observed */
+    slot: bigint;
+    /** Sequence number for ordering updates */
+    seq: bigint;
+    /** Account metadata */
+    meta: AccountMeta;
+    /** Complete account data (assembled from pages) */
+    data: Uint8Array;
+    /** Whether this is a deletion */
+    isDelete: boolean;
+    /** Source: "snapshot" for initial state, "update" for live updates */
+    source: "snapshot" | "update";
+}
+/**
+ * Block finished event for detecting transaction boundaries
+ */
+interface BlockFinishedEvent {
+    slot: bigint;
+}
+/**
+ * Union type for account replay events
+ */
+type AccountReplayEvent = {
+    type: "account";
+    account: AccountState;
+} | {
+    type: "blockFinished";
+    block: BlockFinishedEvent;
+};
+/**
+ * Options for account replay (single address)
+ */
+interface AccountReplayOptions {
+    /** Account source (typically ChainClient) */
+    client: AccountSource;
+    /** Account address to stream updates for */
+    address: Uint8Array;
+    /** Account view (default: FULL for complete data) */
+    view?: AccountView;
+    /** Optional filter expression */
+    filter?: {
+        expression: string;
+        params?: {
+            [key: string]: {
+                kind: {
+                    case: string;
+                    value: unknown;
+                };
+            };
+        };
+    };
+    /** Page assembler options */
+    pageAssemblerOptions?: {
+        assemblyTimeout?: number;
+        maxPendingPerAddress?: number;
+    };
+    /** Cleanup interval for page assembler (default: 10000ms) */
+    cleanupInterval?: number;
+}
+/**
+ * Options for streaming all accounts owned by a specific program
+ */
+interface AccountsByOwnerReplayOptions {
+    /** Account source (typically ChainClient) */
+    client: AccountSource;
+    /** Program owner address - streams all accounts owned by this program */
+    owner: Uint8Array;
+    /** Account view (default: FULL for complete data) */
+    view?: AccountView;
+    /** Optional data sizes to filter (e.g., [73, 115] for TokenAccount and MintAccount) */
+    dataSizes?: number[];
+    /** Optional additional filter expression */
+    filter?: {
+        expression: string;
+        params?: {
+            [key: string]: {
+                kind: {
+                    case: string;
+                    value: unknown;
+                };
+            };
+        };
+    };
+    /** Page assembler options */
+    pageAssemblerOptions?: {
+        assemblyTimeout?: number;
+        maxPendingPerAddress?: number;
+    };
+    /** Cleanup interval for page assembler (default: 10000ms) */
+    cleanupInterval?: number;
+}
+/**
+ * Create an async iterable for account replay with page assembly.
+ *
+ * This function streams account updates with proper page assembly for
+ * large accounts. It handles:
+ * - Initial snapshots
+ * - Live updates with page assembly
+ * - Block finished signals
+ *
+ * @param options - Account replay options
+ * @returns Async iterable of account replay events
+ *
+ * @example
+ * ```typescript
+ * const client = new ChainClient({ baseUrl: "https://grpc.thru.org" });
+ *
+ * for await (const event of createAccountReplay({
+ *   client,
+ *   address: accountPubkey,
+ *   view: AccountView.FULL,
+ * })) {
+ *   if (event.type === "account") {
+ *     console.log("Account update:", event.account.seq);
+ *   } else if (event.type === "blockFinished") {
+ *     console.log("Block finished:", event.block.slot);
+ *   }
+ * }
+ * ```
+ */
+declare function createAccountReplay(options: AccountReplayOptions): AsyncGenerator<AccountReplayEvent, void, undefined>;
+/**
+ * Create an async iterable for streaming all accounts owned by a program.
+ *
+ * This function streams account updates for ALL accounts owned by a specific
+ * program (identified by owner). It handles:
+ * - Initial snapshots for each account
+ * - Live updates with page assembly
+ * - Block finished signals
+ * - Optional filtering by data size (useful for specific account types)
+ *
+ * @param options - Accounts by owner replay options
+ * @returns Async iterable of account replay events
+ *
+ * @example
+ * ```typescript
+ * const client = new ChainClient({ baseUrl: "https://grpc.thru.org" });
+ *
+ * // Stream all token accounts (73 bytes) and mint accounts (115 bytes)
+ * for await (const event of createAccountsByOwnerReplay({
+ *   client,
+ *   owner: TOKEN_PROGRAM_ID,
+ *   dataSizes: [73, 115],
+ *   view: AccountView.FULL,
+ * })) {
+ *   if (event.type === "account") {
+ *     console.log("Account:", event.account.addressHex, "seq:", event.account.seq);
+ *   } else if (event.type === "blockFinished") {
+ *     console.log("Block finished:", event.block.slot);
+ *   }
+ * }
+ * ```
+ */
+declare function createAccountsByOwnerReplay(options: AccountsByOwnerReplayOptions): AsyncGenerator<AccountReplayEvent, void, undefined>;
+/**
+ * State tracker for account sequence numbers.
+ *
+ * Used to track the highest sequence number seen per account address
+ * to ensure updates are applied in order.
+ */
+declare class AccountSeqTracker {
+    private seqs;
+    /**
+     * Get the current sequence number for an address
+     */
+    getSeq(addressHex: string): bigint | undefined;
+    /**
+     * Check if an update should be applied (seq > current)
+     */
+    shouldApply(addressHex: string, seq: bigint): boolean;
+    /**
+     * Update the sequence number for an address
+     * Only updates if new seq is greater than current
+     */
+    update(addressHex: string, seq: bigint): boolean;
+    /**
+     * Remove tracking for an address
+     */
+    remove(addressHex: string): void;
+    /**
+     * Clear all tracking
+     */
+    clear(): void;
+    /**
+     * Get count of tracked addresses
+     */
+    size(): number;
+}
+/**
+ * Multi-account replay manager for streaming updates from multiple accounts.
+ *
+ * This class manages multiple account streams and provides:
+ * - Unified event stream from multiple accounts
+ * - Sequence number tracking per account
+ * - Automatic reconnection on errors
+ */
+declare class MultiAccountReplay {
+    private client;
+    private view;
+    private seqTracker;
+    private activeStreams;
+    constructor(options: {
+        client: AccountSource;
+        view?: AccountView;
+    });
+    /**
+     * Add an account to stream updates for
+     */
+    addAccount(address: Uint8Array): AsyncGenerator<AccountReplayEvent>;
+    /**
+     * Remove an account from streaming
+     */
+    removeAccount(address: Uint8Array): void;
+    /**
+     * Get the current sequence number for an account
+     */
+    getSeq(addressHex: string): bigint | undefined;
+    /**
+     * Stop all streams
+     */
+    stop(): void;
+}
+
+/**
+ * Page Assembler for multi-page account updates.
+ *
+ * Large accounts are split into multiple AccountPage messages (4KB chunks).
+ * This module buffers pages and emits complete account data when all pages
+ * for a given sequence number are received.
+ */
+
+/** Standard page size for account data (4KB) */
+declare const PAGE_SIZE = 4096;
+/**
+ * Assembled account data ready for processing
+ */
+interface AssembledAccount {
+    address: Uint8Array;
+    slot: bigint;
+    seq: bigint;
+    meta: AccountMeta;
+    data: Uint8Array;
+    isDelete: boolean;
+}
+/**
+ * Options for the PageAssembler
+ */
+interface PageAssemblerOptions {
+    /**
+     * Timeout in milliseconds for incomplete page assemblies.
+     * After this duration, incomplete assemblies are discarded.
+     * Default: 30000 (30 seconds)
+     */
+    assemblyTimeout?: number;
+    /**
+     * Maximum number of pending assemblies per address.
+     * Older assemblies are evicted when limit is exceeded.
+     * Default: 10
+     */
+    maxPendingPerAddress?: number;
+}
+/**
+ * Assembles multi-page account updates into complete account data.
+ *
+ * Usage:
+ * ```typescript
+ * const assembler = new PageAssembler();
+ *
+ * for await (const response of client.streamAccountUpdates(request)) {
+ *   if (response.message.case === "update") {
+ *     const assembled = assembler.processUpdate(address, response.message.value);
+ *     if (assembled) {
+ *       // Complete account data is ready
+ *       console.log("Assembled account:", assembled);
+ *     }
+ *   }
+ * }
+ * ```
+ */
+declare class PageAssembler {
+    private readonly assemblyTimeout;
+    private readonly maxPendingPerAddress;
+    /**
+     * Pending updates keyed by address (hex) -> seq (string) -> PendingUpdate
+     */
+    private pending;
+    constructor(options?: PageAssemblerOptions);
+    /**
+     * Process an account update and return assembled account if complete.
+     *
+     * @param address - Account address bytes
+     * @param update - Account update from streaming response
+     * @returns Assembled account if all pages received, null otherwise
+     */
+    processUpdate(address: Uint8Array, update: AccountUpdate): AssembledAccount | null;
+    /**
+     * Assemble complete data from buffered pages
+     */
+    private assemblePages;
+    /**
+     * Evict old pending updates for an address if limit exceeded
+     */
+    private evictOldPending;
+    /**
+     * Clean up expired pending assemblies.
+     * Call this periodically to prevent memory leaks.
+     */
+    cleanup(): number;
+    /**
+     * Get current pending count for debugging
+     */
+    getPendingCount(): number;
+    /**
+     * Clear all pending assemblies
+     */
+    clear(): void;
+}
+
+declare const NOOP_LOGGER: ReplayLogger;
+declare function createConsoleLogger(prefix?: string): ReplayLogger;
+
+interface ReplaySinkContext {
+    slot: Slot;
+    phase: "backfill" | "live";
+}
+interface ReplaySinkMeta {
+    stream?: string;
+    label?: string;
+}
+interface ReplaySink<T> {
+    open?(meta?: ReplaySinkMeta): Promise<void> | void;
+    write(item: T, ctx: ReplaySinkContext): Promise<void> | void;
+    close?(err?: unknown): Promise<void> | void;
+}
+
+declare class ConsoleSink<T> implements ReplaySink<T> {
+    private readonly prefix;
+    constructor(prefix?: string);
+    open(meta?: ReplaySinkMeta): void;
+    write(item: T, ctx: ReplaySinkContext): void;
+    close(err?: unknown): void;
+}
+
+export { type AccountReplayEvent, type AccountReplayOptions, AccountSeqTracker, type AccountSource, type AccountState, type AccountsByOwnerReplayOptions, type AssembledAccount, type BlockFinishedEvent, type BlockReplayOptions, type BlockSource, ChainClient, type ChainClientOptions, ConsoleSink, type EventReplayOptions, type EventSource, MultiAccountReplay, NOOP_LOGGER, PAGE_SIZE, PageAssembler, type PageAssemblerOptions, type ReplayConfig, type ReplayDataSource, type ReplayLogger, type ReplayMetrics, type ReplaySink, type ReplaySinkContext, type ReplaySinkMeta, ReplayStream, type Slot, type TransactionReplayOptions, type TransactionSource, createAccountReplay, createAccountsByOwnerReplay, createBlockReplay, createConsoleLogger, createEventReplay, createTransactionReplay };