lovewebconnection 0.0.0-stage → 0.2.0

package/dist/watch.d.ts

@@ -0,0 +1,306 @@
+import { type Address, type PublicClient } from "viem";
+import { type BalancesReport, type ChunkProgress, type ChunkStatus } from "./balances.ts";
+import type { ChainConfig } from "./chain.ts";
+import { type SessionMetrics, type WatchMetrics } from "./metrics.ts";
+import { type PriceBook } from "./prices.ts";
+export interface WatchOptions {
+    /** Delay between polls. */
+    intervalMs: number;
+    /** How long the head may stay unchanged before a stall is reported. */
+    stallAfterSeconds: number;
+    /** Stop after this many successful samples; 0 runs until interrupted. */
+    maxSamples: number;
+    /** Percentage above the rolling gas baseline that counts as a surge. */
+    gasSurgePercent: number;
+    /** Rolling window size for latency and block-time statistics. */
+    windowSize: number;
+    /** Emit a rolling metrics line every n samples; 0 disables it. */
+    reportEvery: number;
+    /** Append every event to this file as one JSON object per line; null disables it. */
+    logPath: string | null;
+    /** Rotate the log to <path>.1 when it would grow past this many bytes; 0 disables it. */
+    logMaxBytes: number;
+    /** Re-launch in the background, logging to logPath, then exit. */
+    detach: boolean;
+    /** Alert when rolling p95 latency exceeds this many ms; null disables it. */
+    alertLatencyMs: number | null;
+    /** Alert when rolling median block time exceeds this many seconds; null disables it. */
+    alertBlockTimeSeconds: number | null;
+    /** Alert when a portfolio asset moves more than this percent between samples; null disables it. */
+    alertBalancePercent: number | null;
+    /** POST alert events here; null only prints and logs them. */
+    webhookUrl: string | null;
+    /** Authorization header sent with alert POSTs; null sends none. */
+    alertAuthHeader: string | null;
+    /** Durable alert queue file; null derives one from the log path. */
+    alertQueuePath: string | null;
+    /** Where alertAuthHeader came from; only used to word validation errors. */
+    /** Owner whose portfolio is read; null disables portfolio sampling. */
+    owner: Address | null;
+    /** Portfolio tokens, loaded from --tokens-file. */
+    tokens: Address[];
+    /** Lowercased token address → label from the token list file. */
+    labels: Map<string, string>;
+    /** Sample the portfolio every n polls. */
+    portfolioEvery: number;
+    /**
+     * Tokens per Multicall3 request when reading the portfolio; null uses
+     * readBalances' automatic 12 uncached / 24 fully cached chunking.
+     */
+    batchSize: number | null;
+    /** Fixed sub-call cap per portfolio request; null uses batchSize. */
+    maxSubCalls: number | null;
+    /** Print one line per portfolio Multicall3 chunk to stderr. */
+    verbose: boolean;
+    /** Value the portfolio in USD using DefiLlama prices. */
+    usd: boolean;
+}
+export declare const DEFAULT_WATCH_OPTIONS: WatchOptions;
+export declare class WatchArgError extends Error {
+    constructor(message: string);
+}
+/** `512kb`, `10mb`, `1gb`, or a bare number of megabytes. */
+export declare function parseLogSize(raw: string): number;
+export declare function parseWatchArgs(argv: string[], env?: Record<string, string | undefined>): WatchOptions;
+export interface PortfolioHolding {
+    address: Address;
+    symbol: string;
+    label: string | null;
+    decimals: number | null;
+    balance: bigint | null;
+    /** Change since the previous portfolio sample; null for the first one. */
+    delta: bigint | null;
+    /** USD value at this sample's prices; null when the asset could not be priced. */
+    usd: number | null;
+}
+export interface PortfolioNative {
+    symbol: string;
+    decimals: number;
+    balance: bigint;
+    delta: bigint | null;
+    usd: number | null;
+}
+export type WatchEvent = {
+    type: "advance";
+    at: number;
+    blockNumber: bigint;
+    delta: bigint;
+    gasPriceWei: bigint | null;
+    latencyMs: number;
+} | {
+    type: "hold";
+    at: number;
+    blockNumber: bigint;
+    staleSeconds: number;
+    gasPriceWei: bigint | null;
+    latencyMs: number;
+} | {
+    type: "stall";
+    at: number;
+    blockNumber: bigint;
+    staleSeconds: number;
+} | {
+    type: "recovered";
+    at: number;
+    from: bigint;
+    to: bigint;
+    stalledForSeconds: number;
+} | {
+    type: "chain-drift";
+    at: number;
+    expected: number;
+    previous: number | null;
+    actual: number;
+} | {
+    type: "gas-surge";
+    at: number;
+    gasPriceWei: bigint;
+    baselineWei: bigint;
+    increasePercent: number;
+} | {
+    type: "gas-normal";
+    at: number;
+    gasPriceWei: bigint;
+    baselineWei: bigint;
+} | {
+    type: "alert";
+    at: number;
+    metric: "latency" | "block-time";
+    direction: "breach" | "clear";
+    value: number;
+    threshold: number;
+    /** Rolling metrics snapshot that triggered this alert. */
+    metrics: WatchMetrics;
+    /** Whole-session totals at the moment of the alert. */
+    cumulative: SessionMetrics;
+} | {
+    type: "balance-alert";
+    at: number;
+    asset: "native" | "token";
+    /** Token address, or null for the native balance. */
+    address: Address | null;
+    symbol: string;
+    label: string | null;
+    decimals: number | null;
+    previous: bigint;
+    balance: bigint;
+    delta: bigint;
+    /** Percent moved, rounded; null when the previous balance was zero. */
+    changePercent: number | null;
+    thresholdPercent: number;
+} | {
+    type: "portfolio";
+    at: number;
+    blockNumber: bigint | null;
+    /** Tokens per Multicall3 request for this sample; null when it failed. */
+    batchSize: number | null;
+    /** Multicall3 chunks used by this sample; null when it failed. */
+    chunkCount: number | null;
+    native: PortfolioNative | null;
+    tokens: PortfolioHolding[];
+    /** Sum of the priced holdings, or null when nothing could be priced. */
+    usdTotal: number | null;
+    /** Why prices were unavailable; null when they were not needed or worked. */
+    priceError: string | null;
+    error: string | null;
+} | {
+    type: "chunk-recovery";
+    at: number;
+    /** Portfolio owner whose chunks were read. */
+    owner: Address;
+    /** 1-based position of the chunk that needed a retry, and the chunk count. */
+    chunk: number;
+    chunks: number;
+    /** Tokens assigned to the chunk. */
+    tokens: number;
+    status: ChunkStatus;
+    /** Why the chunk's first Multicall3 request failed; null when unknown. */
+    error: string | null;
+    /** Tokens from the chunk that had to be re-read individually. */
+    individual: Address[];
+} | {
+    type: "metrics";
+    at: number;
+    /** Rolling window snapshot. */
+    metrics: WatchMetrics;
+    /** Whole-session totals at the same moment. */
+    cumulative: SessionMetrics;
+} | {
+    type: "error";
+    at: number;
+    message: string;
+};
+export interface WatchTrackerState {
+    lastBlock: bigint | null;
+    lastChainId: number | null;
+    lastAdvanceAt: number;
+    stalledSince: number | null;
+    gasHistory: bigint[];
+    gasSurge: boolean;
+}
+export interface WatchSample {
+    at: number;
+    blockNumber: bigint;
+    chainId: number;
+    gasPriceWei: bigint | null;
+    latencyMs: number;
+}
+export declare function createTracker(): WatchTrackerState;
+/**
+ * Pure state machine: given the previous state and a fresh sample, decide which
+ * events happened. Chain drift is reported when the observed id differs from the
+ * configured one and from the previous observation. Gas surges compare the
+ * current price against the median of the last readings, with hysteresis so a
+ * price hovering at the threshold does not flap.
+ */
+export declare function evaluateSample(state: WatchTrackerState, sample: WatchSample, options: Pick<WatchOptions, "stallAfterSeconds" | "gasSurgePercent">, expectedChainId: number): {
+    state: WatchTrackerState;
+    events: WatchEvent[];
+};
+export interface AlertState {
+    latencyBreaching: boolean;
+    blockTimeBreaching: boolean;
+}
+export declare function createAlertState(): AlertState;
+export type AlertThresholds = Pick<WatchOptions, "alertLatencyMs" | "alertBlockTimeSeconds">;
+interface AlertSignal {
+    metric: "latency" | "block-time";
+    direction: "breach" | "clear";
+    value: number;
+    threshold: number;
+}
+/**
+ * Edge-triggered thresholds: one alert when a metric rises above its limit and
+ * one when it falls back under it, so a sustained breach does not repeat on
+ * every sample.
+ */
+export declare function evaluateAlerts(metrics: WatchMetrics, thresholds: AlertThresholds, state: AlertState): {
+    state: AlertState;
+    alerts: AlertSignal[];
+};
+export interface WatchSummary {
+    samples: number;
+    errors: number;
+    firstBlock: bigint | null;
+    lastBlock: bigint | null;
+    advancedBy: bigint;
+    chainDrift: boolean;
+    stalls: number;
+    gasSurges: number;
+    alerts: number;
+    lastGasWei: bigint | null;
+    peakGasWei: bigint | null;
+    metrics: WatchMetrics;
+    /** Whole-run totals, independent of the rolling window. */
+    session: SessionMetrics;
+    durationMs: number;
+    aborted: boolean;
+    portfolio: PortfolioSummary | null;
+}
+export interface PortfolioSummary {
+    samples: number;
+    native: {
+        symbol: string;
+        decimals: number;
+        first: bigint;
+        last: bigint;
+        delta: bigint;
+    } | null;
+    tokens: Array<{
+        address: Address;
+        symbol: string;
+        label: string | null;
+        decimals: number | null;
+        first: bigint | null;
+        last: bigint | null;
+        delta: bigint | null;
+    }>;
+}
+export interface WatchDeps {
+    now?: () => number;
+    sleep?: (ms: number) => Promise<void>;
+    /** Injected portfolio reader; defaults to readBalances with an in-memory cache. */
+    readPortfolio?: () => Promise<BalancesReport>;
+    /** Injected price reader; defaults to DefiLlama with a 60 s cache. */
+    readPrices?: (tokens: Address[]) => Promise<PriceBook>;
+    /** Receives each portfolio Multicall3 chunk as it settles. */
+    onChunkProgress?: (progress: ChunkProgress) => void;
+}
+export interface BalanceChange {
+    delta: bigint;
+    /** Percent of the previous balance, rounded; null when it was zero. */
+    changePercent: number | null;
+    direction: "up" | "down";
+}
+/**
+ * Compare two readings of the same balance. Returns null unless the move is
+ * strictly larger than `thresholdPercent`. A balance that was zero has no
+ * percentage baseline, so any move away from zero alerts.
+ */
+export declare function describeBalanceChange(previous: bigint, balance: bigint, thresholdPercent: number): BalanceChange | null;
+export declare function watchChain(client: PublicClient, config: ChainConfig, options: WatchOptions, onEvent: (event: WatchEvent) => unknown, signal?: AbortSignal, deps?: WatchDeps): Promise<WatchSummary>;
+export declare function formatWatchEvent(event: WatchEvent, config: ChainConfig): string;
+export declare function formatWatchSummary(summary: WatchSummary): string;
+export declare function toWatchEventJson(event: WatchEvent): Record<string, unknown>;
+export declare function toWatchSummaryJson(summary: WatchSummary): Record<string, unknown>;
+export {};