@terkoizmy/intent-sdk 1.0.0

package/dist/solver/mempool/mempool-monitor.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Mempool Monitor — Phase G
+ *
+ * The main orchestrator of the mempool integration pipeline.
+ * Listens for intents, filters them, solves viable ones via LiquidityAgent,
+ * and submits results back to the mempool.
+ *
+ * Pipeline:
+ *   new_intent event → IntentFilter.shouldSolve() → LiquidityAgent.solve()
+ *   → SolutionSubmitter.submit()
+ *
+ * Stats tracking:
+ *   - received: total intents from mempool
+ *   - filtered: intents passing shouldSolve (attempted)
+ *   - solved:   successfully completed solves
+ *   - failed:   solve attempts that returned success=false
+ *
+ * Used by: LiquidityAgent.start() (Phase K wiring)
+ */
+import type { LiquidityAgent } from "../agent/liquidity-agent";
+import type { MempoolClient } from "./mempool-client";
+import type { IntentFilter } from "./intent-filter";
+import type { SolutionSubmitter } from "./solution-submitter";
+export interface MempoolStats {
+    /** Total intents received from mempool */
+    received: number;
+    /** Intents that passed shouldSolve (were attempted) */
+    filtered: number;
+    /** Intents successfully solved */
+    solved: number;
+    /** Solve attempts that failed */
+    failed: number;
+}
+export declare class MempoolMonitor {
+    private readonly client;
+    private readonly filter;
+    private readonly agent;
+    private readonly submitter;
+    private running;
+    private stats;
+    /** Bound handler saved for proper off() unregistration */
+    private boundIntentHandler;
+    constructor(client: MempoolClient, filter: IntentFilter, agent: LiquidityAgent, submitter: SolutionSubmitter);
+    /**
+     * Start listening to mempool intent events.
+     *
+     * Attaches "new_intent" listener on the client.
+     * Also listens for "intent_solved" to update dedup cache.
+     */
+    start(): void;
+    /**
+     * Stop listening and clean up event handlers.
+     */
+    stop(): void;
+    /**
+     * Get current processing stats.
+     *
+     * @returns Snapshot of received/filtered/solved/failed counters
+     */
+    getStats(): MempoolStats;
+    /** Whether the monitor is currently listening */
+    isRunning(): boolean;
+    /**
+     * Process a single incoming intent through the full pipeline.
+     *
+     * Errors within the solve pipeline are caught here so that
+     * one bad intent doesn't crash the monitor loop.
+     */
+    private handleIntent;
+}
+//# sourceMappingURL=mempool-monitor.d.ts.map

package/dist/solver/mempool/mempool-monitor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mempool-monitor.d.ts","sourceRoot":"","sources":["../../../src/solver/mempool/mempool-monitor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAGH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC/D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACtD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AACpD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAM9D,MAAM,WAAW,YAAY;IACzB,0CAA0C;IAC1C,QAAQ,EAAE,MAAM,CAAC;IACjB,uDAAuD;IACvD,QAAQ,EAAE,MAAM,CAAC;IACjB,kCAAkC;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,iCAAiC;IACjC,MAAM,EAAE,MAAM,CAAC;CAClB;AAMD,qBAAa,cAAc;IAanB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAf9B,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,KAAK,CAKX;IAEF,0DAA0D;IAC1D,OAAO,CAAC,kBAAkB,CAAiC;gBAGtC,MAAM,EAAE,aAAa,EACrB,MAAM,EAAE,YAAY,EACpB,KAAK,EAAE,cAAc,EACrB,SAAS,EAAE,iBAAiB;IAYjD;;;;;OAKG;IACH,KAAK,IAAI,IAAI;IAYb;;OAEG;IACH,IAAI,IAAI,IAAI;IAUZ;;;;OAIG;IACH,QAAQ,IAAI,YAAY;IAIxB,iDAAiD;IACjD,SAAS,IAAI,OAAO;IAQpB;;;;;OAKG;YACW,YAAY;CA+B7B"}

package/dist/solver/mempool/mempool-monitor.js

@@ -0,0 +1,127 @@
+/**
+ * Mempool Monitor — Phase G
+ *
+ * The main orchestrator of the mempool integration pipeline.
+ * Listens for intents, filters them, solves viable ones via LiquidityAgent,
+ * and submits results back to the mempool.
+ *
+ * Pipeline:
+ *   new_intent event → IntentFilter.shouldSolve() → LiquidityAgent.solve()
+ *   → SolutionSubmitter.submit()
+ *
+ * Stats tracking:
+ *   - received: total intents from mempool
+ *   - filtered: intents passing shouldSolve (attempted)
+ *   - solved:   successfully completed solves
+ *   - failed:   solve attempts that returned success=false
+ *
+ * Used by: LiquidityAgent.start() (Phase K wiring)
+ */
+// ─────────────────────────────────────────────
+// MempoolMonitor
+// ─────────────────────────────────────────────
+export class MempoolMonitor {
+    client;
+    filter;
+    agent;
+    submitter;
+    running = false;
+    stats = {
+        received: 0,
+        filtered: 0,
+        solved: 0,
+        failed: 0,
+    };
+    /** Bound handler saved for proper off() unregistration */
+    boundIntentHandler;
+    constructor(client, filter, agent, submitter) {
+        this.client = client;
+        this.filter = filter;
+        this.agent = agent;
+        this.submitter = submitter;
+        // Bind once so we can unregister the same reference in stop()
+        this.boundIntentHandler = (intent) => {
+            void this.handleIntent(intent);
+        };
+    }
+    // ─────────────────────────────────────────
+    // Public API
+    // ─────────────────────────────────────────
+    /**
+     * Start listening to mempool intent events.
+     *
+     * Attaches "new_intent" listener on the client.
+     * Also listens for "intent_solved" to update dedup cache.
+     */
+    start() {
+        if (this.running)
+            return;
+        this.running = true;
+        this.client.on("new_intent", this.boundIntentHandler);
+        // When another solver solves an intent, mark it in our filter cache
+        this.client.on("intent_solved", (payload) => {
+            this.filter.markSolved(payload.intentId);
+        });
+    }
+    /**
+     * Stop listening and clean up event handlers.
+     */
+    stop() {
+        if (!this.running)
+            return;
+        this.running = false;
+        this.client.off("new_intent", this.boundIntentHandler);
+        // Note: we leave "intent_solved" registered for the duration it was
+        // attached, it's harmless as it only updates a Set and will be GC'd
+        // when the client is destroyed.
+    }
+    /**
+     * Get current processing stats.
+     *
+     * @returns Snapshot of received/filtered/solved/failed counters
+     */
+    getStats() {
+        return { ...this.stats };
+    }
+    /** Whether the monitor is currently listening */
+    isRunning() {
+        return this.running;
+    }
+    // ─────────────────────────────────────────
+    // Private
+    // ─────────────────────────────────────────
+    /**
+     * Process a single incoming intent through the full pipeline.
+     *
+     * Errors within the solve pipeline are caught here so that
+     * one bad intent doesn't crash the monitor loop.
+     */
+    async handleIntent(intent) {
+        this.stats.received++;
+        // 1. Filter
+        if (!this.filter.shouldSolve(intent)) {
+            return;
+        }
+        this.stats.filtered++;
+        // 2. Solve
+        try {
+            const result = await this.agent.solve(intent);
+            if (result.success) {
+                this.stats.solved++;
+                // 3. Submit
+                this.submitter.submit(intent.intentId, result);
+            }
+            else {
+                this.stats.failed++;
+                // Log failure reason at debug level — not alertable
+                console.debug(`[MempoolMonitor] Intent ${intent.intentId} solve failed: ${result.error}`);
+            }
+        }
+        catch (err) {
+            this.stats.failed++;
+            const message = err instanceof Error ? err.message : String(err);
+            console.error(`[MempoolMonitor] Unexpected error solving ${intent.intentId}:`, message);
+        }
+    }
+}
+//# sourceMappingURL=mempool-monitor.js.map

package/dist/solver/mempool/mempool-monitor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mempool-monitor.js","sourceRoot":"","sources":["../../../src/solver/mempool/mempool-monitor.ts"],"names":[],"mappings":"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"}

package/dist/solver/mempool/solution-submitter.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Solution Submitter — Phase G
+ *
+ * Formats and submits a solved intent's result back to the mempool server.
+ * Handles race conditions where another solver already claimed the intent.
+ *
+ * Used by: MempoolMonitor
+ */
+import type { SolutionResult } from "../types/agent";
+import type { MempoolClient } from "./mempool-client";
+/** Result of a submission attempt */
+export interface SubmitOutcome {
+    /** Whether submission was sent successfully */
+    submitted: boolean;
+    /** Whether submission was skipped because the intent was already solved */
+    alreadySolved: boolean;
+    /** Error if submission failed for some other reason */
+    error?: string;
+}
+export declare class SolutionSubmitter {
+    private readonly client;
+    constructor(client: MempoolClient);
+    /**
+     * Submit a solution result to the mempool server.
+     *
+     * On success: sends the txHash + profit to the server.
+     * On "already solved" race condition: logs a warning and skips silently.
+     * On failure: logs the error and returns error outcome.
+     *
+     * @param intentId - The intent being submitted
+     * @param result   - SolutionResult from LiquidityAgent.solve()
+     * @returns SubmitOutcome describing what happened
+     */
+    submit(intentId: string, result: SolutionResult): SubmitOutcome;
+    /**
+     * Detect "already solved" error messages from the mempool server.
+     * Protocol-agnostic heuristic covering common error wordings.
+     */
+    private isAlreadySolvedError;
+}
+//# sourceMappingURL=solution-submitter.d.ts.map

package/dist/solver/mempool/solution-submitter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"solution-submitter.d.ts","sourceRoot":"","sources":["../../../src/solver/mempool/solution-submitter.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AACrD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAEtD,qCAAqC;AACrC,MAAM,WAAW,aAAa;IAC1B,+CAA+C;IAC/C,SAAS,EAAE,OAAO,CAAC;IACnB,2EAA2E;IAC3E,aAAa,EAAE,OAAO,CAAC;IACvB,uDAAuD;IACvD,KAAK,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,qBAAa,iBAAiB;IACd,OAAO,CAAC,QAAQ,CAAC,MAAM;gBAAN,MAAM,EAAE,aAAa;IAMlD;;;;;;;;;;OAUG;IACH,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,cAAc,GAAG,aAAa;IA0C/D;;;OAGG;IACH,OAAO,CAAC,oBAAoB;CAS/B"}

package/dist/solver/mempool/solution-submitter.js

@@ -0,0 +1,71 @@
+/**
+ * Solution Submitter — Phase G
+ *
+ * Formats and submits a solved intent's result back to the mempool server.
+ * Handles race conditions where another solver already claimed the intent.
+ *
+ * Used by: MempoolMonitor
+ */
+export class SolutionSubmitter {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    // ─────────────────────────────────────────
+    // Public API
+    // ─────────────────────────────────────────
+    /**
+     * Submit a solution result to the mempool server.
+     *
+     * On success: sends the txHash + profit to the server.
+     * On "already solved" race condition: logs a warning and skips silently.
+     * On failure: logs the error and returns error outcome.
+     *
+     * @param intentId - The intent being submitted
+     * @param result   - SolutionResult from LiquidityAgent.solve()
+     * @returns SubmitOutcome describing what happened
+     */
+    submit(intentId, result) {
+        if (!result.success) {
+            // Don't submit failed solutions — they don't need to go to mempool
+            return { submitted: false, alreadySolved: false };
+        }
+        if (!this.client.isConnected()) {
+            console.warn(`[SolutionSubmitter] Cannot submit ${intentId}: not connected to mempool`);
+            return {
+                submitted: false,
+                alreadySolved: false,
+                error: "Not connected to mempool",
+            };
+        }
+        try {
+            this.client.submitSolution(intentId, result.txHash, result.metadata?.sourceChainId?.toString(), result.profit);
+            return { submitted: true, alreadySolved: false };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            // Detect "already solved" — another solver was faster
+            if (this.isAlreadySolvedError(message)) {
+                console.warn(`[SolutionSubmitter] Intent ${intentId} already solved by another solver`);
+                return { submitted: false, alreadySolved: true };
+            }
+            console.error(`[SolutionSubmitter] Failed to submit ${intentId}:`, message);
+            return { submitted: false, alreadySolved: false, error: message };
+        }
+    }
+    // ─────────────────────────────────────────
+    // Private
+    // ─────────────────────────────────────────
+    /**
+     * Detect "already solved" error messages from the mempool server.
+     * Protocol-agnostic heuristic covering common error wordings.
+     */
+    isAlreadySolvedError(message) {
+        const lower = message.toLowerCase();
+        return (lower.includes("already solved") ||
+            lower.includes("already claimed") ||
+            lower.includes("intent_not_found") ||
+            lower.includes("duplicate"));
+    }
+}
+//# sourceMappingURL=solution-submitter.js.map

package/dist/solver/mempool/solution-submitter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"solution-submitter.js","sourceRoot":"","sources":["../../../src/solver/mempool/solution-submitter.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAeH,MAAM,OAAO,iBAAiB;IACG;IAA7B,YAA6B,MAAqB;QAArB,WAAM,GAAN,MAAM,CAAe;IAAI,CAAC;IAEvD,4CAA4C;IAC5C,aAAa;IACb,4CAA4C;IAE5C;;;;;;;;;;OAUG;IACH,MAAM,CAAC,QAAgB,EAAE,MAAsB;QAC3C,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;YAClB,mEAAmE;YACnE,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,aAAa,EAAE,KAAK,EAAE,CAAC;QACtD,CAAC;QAED,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,WAAW,EAAE,EAAE,CAAC;YAC7B,OAAO,CAAC,IAAI,CAAC,qCAAqC,QAAQ,4BAA4B,CAAC,CAAC;YACxF,OAAO;gBACH,SAAS,EAAE,KAAK;gBAChB,aAAa,EAAE,KAAK;gBACpB,KAAK,EAAE,0BAA0B;aACpC,CAAC;QACN,CAAC;QAED,IAAI,CAAC;YACD,IAAI,CAAC,MAAM,CAAC,cAAc,CACtB,QAAQ,EACR,MAAM,CAAC,MAAM,EACb,MAAM,CAAC,QAAQ,EAAE,aAAa,EAAE,QAAQ,EAAE,EAC1C,MAAM,CAAC,MAAM,CAChB,CAAC;YAEF,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,aAAa,EAAE,KAAK,EAAE,CAAC;QACrD,CAAC;QAAC,OAAO,GAAY,EAAE,CAAC;YACpB,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YAEjE,sDAAsD;YACtD,IAAI,IAAI,CAAC,oBAAoB,CAAC,OAAO,CAAC,EAAE,CAAC;gBACrC,OAAO,CAAC,IAAI,CAAC,8BAA8B,QAAQ,mCAAmC,CAAC,CAAC;gBACxF,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC;YACrD,CAAC;YAED,OAAO,CAAC,KAAK,CAAC,wCAAwC,QAAQ,GAAG,EAAE,OAAO,CAAC,CAAC;YAC5E,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,aAAa,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC;QACtE,CAAC;IACL,CAAC;IAED,4CAA4C;IAC5C,UAAU;IACV,4CAA4C;IAE5C;;;OAGG;IACK,oBAAoB,CAAC,OAAe;QACxC,MAAM,KAAK,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;QACpC,OAAO,CACH,KAAK,CAAC,QAAQ,CAAC,gBAAgB,CAAC;YAChC,KAAK,CAAC,QAAQ,CAAC,iBAAiB,CAAC;YACjC,KAAK,CAAC,QAAQ,CAAC,kBAAkB,CAAC;YAClC,KAAK,CAAC,QAAQ,CAAC,WAAW,CAAC,CAC9B,CAAC;IACN,CAAC;CACJ"}

package/dist/solver/monitoring/alert-manager.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Alert Manager — Phase H
+ *
+ * Provides a structured way to report and track system alerts
+ * like low inventory or failed claim transactions.
+ *
+ * Used by: SettlementManager, DynamicPricing, Rebalancer
+ */
+import type { ChainId } from "../../types/common";
+export type AlertLevel = "info" | "warning" | "critical";
+export interface Alert {
+    id: string;
+    level: AlertLevel;
+    message: string;
+    timestamp: number;
+    context?: Record<string, unknown>;
+}
+export declare class AlertManager {
+    private alerts;
+    private readonly MAX_ALERTS;
+    private nextId;
+    /**
+     * Create a generalized structured alert
+     */
+    alert(level: AlertLevel, message: string, context?: Record<string, unknown>): void;
+    /**
+     * Helper to create a standardized low inventory warning
+     */
+    alertLowInventory(chainId: ChainId, token: string, available: string, threshold: string): void;
+    /**
+     * Helper to create a critical alert when a settlement claim fails repeatedly
+     */
+    alertFailedClaim(intentId: string, reason: string, attempt: number): void;
+    /**
+     * Retrieve stored alerts, optionally filtered by severity
+     */
+    getAlerts(level?: AlertLevel): Alert[];
+    /**
+     * Clear all stored alerts
+     */
+    clearAlerts(): void;
+}
+//# sourceMappingURL=alert-manager.d.ts.map

package/dist/solver/monitoring/alert-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"alert-manager.d.ts","sourceRoot":"","sources":["../../../src/solver/monitoring/alert-manager.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAElD,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,SAAS,GAAG,UAAU,CAAC;AAEzD,MAAM,WAAW,KAAK;IAClB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,UAAU,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACrC;AAED,qBAAa,YAAY;IACrB,OAAO,CAAC,MAAM,CAAe;IAC7B,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAQ;IACnC,OAAO,CAAC,MAAM,CAAK;IAEnB;;OAEG;IACH,KAAK,CAAC,KAAK,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IA2BlF;;OAEG;IACH,iBAAiB,CAAC,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI;IAQ9F;;OAEG;IACH,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI;IAQzE;;OAEG;IACH,SAAS,CAAC,KAAK,CAAC,EAAE,UAAU,GAAG,KAAK,EAAE;IAOtC;;OAEG;IACH,WAAW,IAAI,IAAI;CAGtB"}

package/dist/solver/monitoring/alert-manager.js

@@ -0,0 +1,69 @@
+/**
+ * Alert Manager — Phase H
+ *
+ * Provides a structured way to report and track system alerts
+ * like low inventory or failed claim transactions.
+ *
+ * Used by: SettlementManager, DynamicPricing, Rebalancer
+ */
+export class AlertManager {
+    alerts = [];
+    MAX_ALERTS = 1000;
+    nextId = 1;
+    /**
+     * Create a generalized structured alert
+     */
+    alert(level, message, context) {
+        const item = {
+            id: `alert-${this.nextId++}`,
+            level,
+            message,
+            timestamp: Date.now(),
+            context,
+        };
+        this.alerts.push(item);
+        // Keep memory bounded
+        if (this.alerts.length > this.MAX_ALERTS) {
+            this.alerts.shift();
+        }
+        // Production-ready: emit to stdout/stderr in standardized format
+        // Could be piped to external monitoring tools (Datadog, Sentry, etc.)
+        if (level === "critical") {
+            console.error(`[ALERT:CRITICAL] ${message}`, context ? context : "");
+        }
+        else if (level === "warning") {
+            console.warn(`[ALERT:WARNING] ${message}`, context ? context : "");
+        }
+        else {
+            console.info(`[ALERT:INFO] ${message}`, context ? context : "");
+        }
+    }
+    /**
+     * Helper to create a standardized low inventory warning
+     */
+    alertLowInventory(chainId, token, available, threshold) {
+        this.alert("warning", `Low inventory on chain ${chainId} for ${token}: available ${available} < threshold ${threshold}`, { chainId, token, available, threshold });
+    }
+    /**
+     * Helper to create a critical alert when a settlement claim fails repeatedly
+     */
+    alertFailedClaim(intentId, reason, attempt) {
+        this.alert("critical", `Failed claim for intent ${intentId} on attempt ${attempt}. Reason: ${reason}`, { intentId, reason, attempt });
+    }
+    /**
+     * Retrieve stored alerts, optionally filtered by severity
+     */
+    getAlerts(level) {
+        if (level) {
+            return this.alerts.filter((a) => a.level === level);
+        }
+        return [...this.alerts];
+    }
+    /**
+     * Clear all stored alerts
+     */
+    clearAlerts() {
+        this.alerts = [];
+    }
+}
+//# sourceMappingURL=alert-manager.js.map

package/dist/solver/monitoring/alert-manager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"alert-manager.js","sourceRoot":"","sources":["../../../src/solver/monitoring/alert-manager.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAcH,MAAM,OAAO,YAAY;IACb,MAAM,GAAY,EAAE,CAAC;IACZ,UAAU,GAAG,IAAI,CAAC;IAC3B,MAAM,GAAG,CAAC,CAAC;IAEnB;;OAEG;IACH,KAAK,CAAC,KAAiB,EAAE,OAAe,EAAE,OAAiC;QACvE,MAAM,IAAI,GAAU;YAChB,EAAE,EAAE,SAAS,IAAI,CAAC,MAAM,EAAE,EAAE;YAC5B,KAAK;YACL,OAAO;YACP,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE;YACrB,OAAO;SACV,CAAC;QAEF,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAEvB,sBAAsB;QACtB,IAAI,IAAI,CAAC,MAAM,CAAC,MAAM,GAAG,IAAI,CAAC,UAAU,EAAE,CAAC;YACvC,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;QACxB,CAAC;QAED,iEAAiE;QACjE,sEAAsE;QACtE,IAAI,KAAK,KAAK,UAAU,EAAE,CAAC;YACvB,OAAO,CAAC,KAAK,CAAC,oBAAoB,OAAO,EAAE,EAAE,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;QACzE,CAAC;aAAM,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YAC7B,OAAO,CAAC,IAAI,CAAC,mBAAmB,OAAO,EAAE,EAAE,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;QACvE,CAAC;aAAM,CAAC;YACJ,OAAO,CAAC,IAAI,CAAC,gBAAgB,OAAO,EAAE,EAAE,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;QACpE,CAAC;IACL,CAAC;IAED;;OAEG;IACH,iBAAiB,CAAC,OAAgB,EAAE,KAAa,EAAE,SAAiB,EAAE,SAAiB;QACnF,IAAI,CAAC,KAAK,CACN,SAAS,EACT,0BAA0B,OAAO,QAAQ,KAAK,eAAe,SAAS,gBAAgB,SAAS,EAAE,EACjG,EAAE,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,CAC3C,CAAC;IACN,CAAC;IAED;;OAEG;IACH,gBAAgB,CAAC,QAAgB,EAAE,MAAc,EAAE,OAAe;QAC9D,IAAI,CAAC,KAAK,CACN,UAAU,EACV,2BAA2B,QAAQ,eAAe,OAAO,aAAa,MAAM,EAAE,EAC9E,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,CAChC,CAAC;IACN,CAAC;IAED;;OAEG;IACH,SAAS,CAAC,KAAkB;QACxB,IAAI,KAAK,EAAE,CAAC;YACR,OAAO,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,KAAK,KAAK,CAAC,CAAC;QACxD,CAAC;QACD,OAAO,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC;IAC5B,CAAC;IAED;;OAEG;IACH,WAAW;QACP,IAAI,CAAC,MAAM,GAAG,EAAE,CAAC;IACrB,CAAC;CACJ"}

package/dist/solver/monitoring/health-checker.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Health Checker — Phase H
+ *
+ * Aggregates health status of all critical solver subsystems
+ * (RPC, Inventory, Mempool).
+ *
+ * Used by: Monitoring dashboard / AlertManager
+ */
+import type { InventoryManager } from "../inventory/inventory-manager";
+import type { MempoolClient } from "../mempool/mempool-client";
+import type { RPCProviderManager } from "../../shared/rpc/provider-manager";
+export interface HealthCheckResult {
+    healthy: boolean;
+    checks: {
+        rpc: {
+            healthy: boolean;
+            details?: string;
+        };
+        inventory: {
+            healthy: boolean;
+            details?: string;
+        };
+        mempool: {
+            healthy: boolean;
+            details?: string;
+        };
+    };
+    timestamp: number;
+}
+export declare class HealthChecker {
+    private readonly deps;
+    /** Cached result from last check() call */
+    private lastResult;
+    /** TTL for isHealthy() cache in ms (default 10 seconds) */
+    private readonly cacheTtlMs;
+    constructor(deps: {
+        inventoryManager: InventoryManager;
+        mempoolClient: MempoolClient;
+        rpcProviderManager: RPCProviderManager;
+    }, cacheTtlMs?: number);
+    /**
+     * Perform a full health check across all subsystems
+     * @returns Detailed health check result
+     */
+    check(): Promise<HealthCheckResult>;
+    /**
+     * Quick boolean check of overall health.
+     * Result is cached for `cacheTtlMs` to avoid per-call network calls.
+     * Pass `force = true` to skip the cache.
+     */
+    isHealthy(force?: boolean): Promise<boolean>;
+}
+//# sourceMappingURL=health-checker.d.ts.map

package/dist/solver/monitoring/health-checker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"health-checker.d.ts","sourceRoot":"","sources":["../../../src/solver/monitoring/health-checker.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gCAAgC,CAAC;AACvE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAC/D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,mCAAmC,CAAC;AAE5E,MAAM,WAAW,iBAAiB;IAC9B,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE;QACJ,GAAG,EAAE;YAAE,OAAO,EAAE,OAAO,CAAC;YAAC,OAAO,CAAC,EAAE,MAAM,CAAA;SAAE,CAAC;QAC5C,SAAS,EAAE;YAAE,OAAO,EAAE,OAAO,CAAC;YAAC,OAAO,CAAC,EAAE,MAAM,CAAA;SAAE,CAAC;QAClD,OAAO,EAAE;YAAE,OAAO,EAAE,OAAO,CAAC;YAAC,OAAO,CAAC,EAAE,MAAM,CAAA;SAAE,CAAC;KACnD,CAAC;IACF,SAAS,EAAE,MAAM,CAAC;CACrB;AAED,qBAAa,aAAa;IAOlB,OAAO,CAAC,QAAQ,CAAC,IAAI;IANzB,2CAA2C;IAC3C,OAAO,CAAC,UAAU,CAAkC;IACpD,2DAA2D;IAC3D,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;gBAGf,IAAI,EAAE;QACnB,gBAAgB,EAAE,gBAAgB,CAAC;QACnC,aAAa,EAAE,aAAa,CAAC;QAC7B,kBAAkB,EAAE,kBAAkB,CAAC;KAC1C,EACD,UAAU,SAAS;IAKvB;;;OAGG;IACG,KAAK,IAAI,OAAO,CAAC,iBAAiB,CAAC;IA4DzC;;;;OAIG;IACG,SAAS,CAAC,KAAK,UAAQ,GAAG,OAAO,CAAC,OAAO,CAAC;CAQnD"}

package/dist/solver/monitoring/health-checker.js

@@ -0,0 +1,94 @@
+/**
+ * Health Checker — Phase H
+ *
+ * Aggregates health status of all critical solver subsystems
+ * (RPC, Inventory, Mempool).
+ *
+ * Used by: Monitoring dashboard / AlertManager
+ */
+export class HealthChecker {
+    deps;
+    /** Cached result from last check() call */
+    lastResult = null;
+    /** TTL for isHealthy() cache in ms (default 10 seconds) */
+    cacheTtlMs;
+    constructor(deps, cacheTtlMs = 10_000) {
+        this.deps = deps;
+        this.cacheTtlMs = cacheTtlMs;
+    }
+    /**
+     * Perform a full health check across all subsystems
+     * @returns Detailed health check result
+     */
+    async check() {
+        const { inventoryManager, mempoolClient, rpcProviderManager } = this.deps;
+        // 1. RPC Check
+        let rpcHealthy = true;
+        let rpcDetails = "All providers ok";
+        try {
+            const rpcHealth = await rpcProviderManager.checkHealth();
+            let failedCount = 0;
+            for (const [, isHealthy] of rpcHealth.entries()) {
+                if (!isHealthy)
+                    failedCount++;
+            }
+            if (failedCount > 0) {
+                rpcHealthy = false;
+                rpcDetails = `${failedCount} provider(s) down`;
+            }
+        }
+        catch (e) {
+            rpcHealthy = false;
+            rpcDetails = e instanceof Error ? e.message : "RPC check failed";
+            console.error(`[HealthChecker] RPC check threw:`, rpcDetails);
+        }
+        // 2. Inventory Check
+        let inventoryHealthy = false;
+        let inventoryDetails = "No available balances";
+        try {
+            const snapshot = inventoryManager.getSnapshot();
+            if (snapshot.balances && snapshot.balances.length > 0) {
+                // Determine healthy if there's > 0 balance globally or tracked chains have some value
+                for (const bal of snapshot.balances) {
+                    if (BigInt(bal.available) > 0n) {
+                        inventoryHealthy = true;
+                        inventoryDetails = "Balances available";
+                        break;
+                    }
+                }
+            }
+        }
+        catch (e) {
+            const msg = e instanceof Error ? e.message : "Inventory check failed";
+            inventoryDetails = msg;
+            console.error(`[HealthChecker] Inventory check threw:`, msg);
+        }
+        // 3. Mempool Check
+        const mempoolHealthy = mempoolClient.isConnected();
+        const mempoolDetails = mempoolHealthy ? "Connected" : "Disconnected";
+        const healthy = rpcHealthy && inventoryHealthy && mempoolHealthy;
+        return {
+            healthy,
+            checks: {
+                rpc: { healthy: rpcHealthy, details: rpcDetails },
+                inventory: { healthy: inventoryHealthy, details: inventoryDetails },
+                mempool: { healthy: mempoolHealthy, details: mempoolDetails },
+            },
+            timestamp: Date.now(),
+        };
+    }
+    /**
+     * Quick boolean check of overall health.
+     * Result is cached for `cacheTtlMs` to avoid per-call network calls.
+     * Pass `force = true` to skip the cache.
+     */
+    async isHealthy(force = false) {
+        const now = Date.now();
+        if (!force && this.lastResult && (now - this.lastResult.timestamp) < this.cacheTtlMs) {
+            return this.lastResult.healthy;
+        }
+        this.lastResult = await this.check();
+        return this.lastResult.healthy;
+    }
+}
+//# sourceMappingURL=health-checker.js.map

package/dist/solver/monitoring/health-checker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"health-checker.js","sourceRoot":"","sources":["../../../src/solver/monitoring/health-checker.ts"],"names":[],"mappings":"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"}

package/dist/solver/monitoring/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Monitoring Module — Barrel Export
+ */
+export * from "./profit-tracker";
+export * from "./health-checker";
+export * from "./alert-manager";
+//# sourceMappingURL=index.d.ts.map

package/dist/solver/monitoring/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/solver/monitoring/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,cAAc,kBAAkB,CAAC;AACjC,cAAc,kBAAkB,CAAC;AACjC,cAAc,iBAAiB,CAAC"}

package/dist/solver/monitoring/index.js

@@ -0,0 +1,7 @@
+/**
+ * Monitoring Module — Barrel Export
+ */
+export * from "./profit-tracker";
+export * from "./health-checker";
+export * from "./alert-manager";
+//# sourceMappingURL=index.js.map

package/dist/solver/monitoring/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/solver/monitoring/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,cAAc,kBAAkB,CAAC;AACjC,cAAc,kBAAkB,CAAC;AACjC,cAAc,iBAAiB,CAAC"}