@waiaas/daemon 2.5.0 → 2.6.0-rc.1

package/dist/services/incoming/incoming-tx-monitor-service.js

@@ -0,0 +1,357 @@
+/**
+ * IncomingTxMonitorService -- top-level orchestrator for incoming transaction monitoring.
+ *
+ * Wires together:
+ * - IncomingTxQueue (memory buffer + batch flush)
+ * - SubscriptionMultiplexer (shared chain connections per chain:network)
+ * - BackgroundWorkers (6 periodic tasks: flush, retention, 2x confirmation, 2x polling)
+ * - Safety rules (DustAttackRule, UnknownTokenRule, LargeAmountRule)
+ * - EventBus (transaction:incoming, transaction:incoming:suspicious events)
+ * - KillSwitchService (notification suppression when SUSPENDED/LOCKED)
+ * - NotificationService (per-wallet per-event-type cooldown)
+ *
+ * Lifecycle:
+ * - start(): create queue + multiplexer, load wallets, register workers
+ * - stop(): drain queue, stop all subscriptions, clear cooldowns
+ * - updateConfig(): merge partial config (used by HotReloadOrchestrator)
+ * - syncSubscriptions(): reconcile DB wallets with active multiplexer subscriptions
+ *
+ * @see docs/76-incoming-transaction-monitoring.md
+ */
+import { IncomingTxQueue } from './incoming-tx-queue.js';
+import { SubscriptionMultiplexer } from './subscription-multiplexer.js';
+import { createConfirmationWorkerHandler, createRetentionWorkerHandler, createGapRecoveryHandler, updateCursor, } from './incoming-tx-workers.js';
+import { DustAttackRule, UnknownTokenRule, LargeAmountRule, } from './safety-rules.js';
+// ── IncomingTxMonitorService ────────────────────────────────────
+export class IncomingTxMonitorService {
+    sqlite;
+    workers;
+    eventBus;
+    killSwitchService;
+    notificationService;
+    subscriberFactory;
+    queue;
+    multiplexer;
+    safetyRules;
+    notifyCooldown = new Map();
+    config;
+    constructor(deps) {
+        this.sqlite = deps.sqlite;
+        this.workers = deps.workers;
+        this.eventBus = deps.eventBus;
+        this.killSwitchService = deps.killSwitchService ?? null;
+        this.notificationService = deps.notificationService ?? null;
+        this.subscriberFactory = deps.subscriberFactory;
+        this.config = { ...deps.config };
+        // Initialize safety rules
+        this.safetyRules = [
+            new DustAttackRule(),
+            new UnknownTokenRule(),
+            new LargeAmountRule(),
+        ];
+        // Create queue
+        this.queue = new IncomingTxQueue();
+    }
+    /**
+     * Start the monitoring service.
+     *
+     * 1. Create multiplexer with gap recovery handler
+     * 2. Load wallets with monitor_incoming = 1 from DB
+     * 3. Subscribe each wallet via multiplexer
+     * 4. Register 6 background workers
+     */
+    async start() {
+        // Create gap recovery handler (needs reference to multiplexer connections)
+        // We'll create it after multiplexer since it needs the internal connections map
+        // For now, use a thin wrapper
+        // Create multiplexer
+        this.multiplexer = new SubscriptionMultiplexer({
+            subscriberFactory: this.subscriberFactory,
+            onTransaction: (tx) => {
+                this.queue.push(tx);
+            },
+            onGapRecovery: async (chain, network, walletIds) => {
+                // Wire to createGapRecoveryHandler using multiplexer's subscriber access.
+                // this.multiplexer is captured via closure on 'this' -- safe because
+                // onGapRecovery is never called during construction (only on reconnect).
+                const handler = createGapRecoveryHandler({
+                    subscribers: this.multiplexer.getSubscriberEntries(),
+                });
+                await handler(chain, network, walletIds);
+            },
+        });
+        // Load wallets with monitor_incoming = 1
+        const wallets = this.sqlite
+            .prepare(`SELECT id, chain, network, public_key FROM wallets WHERE monitor_incoming = 1`)
+            .all();
+        // Subscribe each wallet
+        for (const wallet of wallets) {
+            try {
+                await this.multiplexer.addWallet(wallet.chain, wallet.network, wallet.id, wallet.public_key);
+            }
+            catch (err) {
+                console.warn(`IncomingTxMonitor: failed to subscribe wallet ${wallet.id}:`, err);
+            }
+        }
+        // Register 6 background workers
+        this.registerWorkers();
+        console.debug(`IncomingTxMonitorService started: ${wallets.length} wallets subscribed`);
+    }
+    /**
+     * Stop the monitoring service.
+     *
+     * 1. Drain queue (final flush of remaining items)
+     * 2. Stop all subscriber connections
+     * 3. Clear cooldown map
+     */
+    async stop() {
+        // 1. Final queue drain
+        this.queue.drain(this.sqlite);
+        // 2. Destroy all multiplexer connections
+        if (this.multiplexer) {
+            await this.multiplexer.stopAll();
+        }
+        // 3. Clear cooldowns
+        this.notifyCooldown.clear();
+        console.debug('IncomingTxMonitorService stopped');
+    }
+    /**
+     * Update configuration (used by HotReloadOrchestrator).
+     */
+    updateConfig(partial) {
+        this.config = { ...this.config, ...partial };
+    }
+    /**
+     * Re-read wallets with monitor_incoming=1 from DB and reconcile
+     * with current multiplexer subscriptions.
+     */
+    async syncSubscriptions() {
+        const dbWallets = this.sqlite
+            .prepare(`SELECT id, chain, network, public_key FROM wallets WHERE monitor_incoming = 1`)
+            .all();
+        // Add any new wallets to multiplexer (addWallet handles dedup internally)
+        for (const wallet of dbWallets) {
+            try {
+                await this.multiplexer.addWallet(wallet.chain, wallet.network, wallet.id, wallet.public_key);
+            }
+            catch (err) {
+                console.warn(`syncSubscriptions: failed to add wallet ${wallet.id}:`, err);
+            }
+        }
+    }
+    // ── Internal: flush handler logic ──────────────────────────────
+    /**
+     * Core flush worker: flush queue, evaluate safety rules, emit events, send notifications.
+     */
+    createFlushHandler() {
+        return async () => {
+            const inserted = this.queue.flush(this.sqlite);
+            if (inserted.length === 0)
+                return;
+            for (const tx of inserted) {
+                // 1. Evaluate safety rules
+                const context = this.buildSafetyRuleContext(tx);
+                const suspiciousReasons = this.safetyRules
+                    .filter((rule) => rule.check(tx, context))
+                    .map((rule) => rule.name);
+                const isSuspicious = suspiciousReasons.length > 0;
+                if (isSuspicious) {
+                    this.sqlite
+                        .prepare('UPDATE incoming_transactions SET is_suspicious = 1 WHERE id = ?')
+                        .run(tx.id);
+                }
+                // 2. Emit events (always, regardless of KillSwitch)
+                this.eventBus.emit('transaction:incoming', {
+                    walletId: tx.walletId,
+                    txHash: tx.txHash,
+                    fromAddress: tx.fromAddress,
+                    amount: tx.amount,
+                    tokenAddress: tx.tokenAddress,
+                    chain: tx.chain,
+                    network: tx.network,
+                    status: tx.status,
+                    timestamp: tx.detectedAt,
+                });
+                if (isSuspicious) {
+                    this.eventBus.emit('transaction:incoming:suspicious', {
+                        walletId: tx.walletId,
+                        txHash: tx.txHash,
+                        fromAddress: tx.fromAddress,
+                        amount: tx.amount,
+                        tokenAddress: tx.tokenAddress,
+                        chain: tx.chain,
+                        network: tx.network,
+                        status: tx.status,
+                        timestamp: tx.detectedAt,
+                        suspiciousReasons,
+                    });
+                }
+                // 3. Send notifications (suppressed by KillSwitch, subject to cooldown)
+                const killState = this.killSwitchService?.getState();
+                if (!killState || killState.state === 'ACTIVE') {
+                    const eventType = isSuspicious
+                        ? 'TX_INCOMING_SUSPICIOUS'
+                        : 'TX_INCOMING';
+                    if (!this.isCooldownActive(tx.walletId, eventType)) {
+                        this.notificationService?.notify(eventType, tx.walletId, {
+                            walletId: tx.walletId,
+                            txHash: tx.txHash,
+                            amount: tx.amount,
+                            fromAddress: tx.fromAddress,
+                            chain: tx.chain,
+                            display_amount: '',
+                            ...(isSuspicious && suspiciousReasons ? { reasons: suspiciousReasons.join(', ') } : {}),
+                        });
+                        this.recordCooldown(tx.walletId, eventType);
+                    }
+                }
+                // 4. Update cursor
+                updateCursor(this.sqlite, tx.walletId, tx.chain, tx.network, tx.blockNumber != null ? String(tx.blockNumber) : tx.txHash);
+            }
+        };
+    }
+    /**
+     * Build safety rule context for a transaction.
+     * Uses best-effort data -- null for unavailable price/average data.
+     */
+    buildSafetyRuleContext(tx) {
+        // Token registry lookup: check if tokenAddress is registered
+        let isRegisteredToken = true;
+        if (tx.tokenAddress !== null) {
+            try {
+                const row = this.sqlite
+                    .prepare(`SELECT 1 FROM token_registry WHERE address = ? AND chain = ? LIMIT 1`)
+                    .get(tx.tokenAddress, tx.chain);
+                isRegisteredToken = !!row;
+            }
+            catch {
+                // Table may not exist or query may fail -- safe default
+                isRegisteredToken = true;
+            }
+        }
+        // Decimals: try to get from token registry, fallback to chain default
+        let decimals = tx.chain === 'solana' ? 9 : 18;
+        if (tx.tokenAddress !== null) {
+            try {
+                const tokenRow = this.sqlite
+                    .prepare(`SELECT decimals FROM token_registry WHERE address = ? AND chain = ? LIMIT 1`)
+                    .get(tx.tokenAddress, tx.chain);
+                if (tokenRow) {
+                    decimals = tokenRow.decimals;
+                }
+            }
+            catch {
+                // Use default
+            }
+        }
+        // USD price: not available in this phase (requires PriceOracle integration)
+        // Will be wired in Phase 227
+        const usdPrice = null;
+        // Average incoming USD: not computed yet (requires historical aggregation)
+        // Will be wired in Phase 227
+        const avgIncomingUsd = null;
+        return {
+            dustThresholdUsd: this.config.dustThresholdUsd,
+            amountMultiplier: this.config.amountMultiplier,
+            isRegisteredToken,
+            usdPrice,
+            avgIncomingUsd,
+            decimals,
+        };
+    }
+    // ── Internal: cooldown logic ───────────────────────────────────
+    isCooldownActive(walletId, eventType) {
+        const key = `${walletId}:${eventType}`;
+        const lastNotified = this.notifyCooldown.get(key);
+        if (lastNotified === undefined)
+            return false;
+        const now = Math.floor(Date.now() / 1000);
+        return now - lastNotified < this.config.cooldownMinutes * 60;
+    }
+    recordCooldown(walletId, eventType) {
+        const key = `${walletId}:${eventType}`;
+        this.notifyCooldown.set(key, Math.floor(Date.now() / 1000));
+    }
+    // ── Internal: worker registration ──────────────────────────────
+    registerWorkers() {
+        // 1. Flush worker (5s)
+        this.workers.register('incoming-tx-flush', {
+            interval: 5_000,
+            handler: this.createFlushHandler(),
+        });
+        // 2. Retention worker (1 hour)
+        this.workers.register('incoming-tx-retention', {
+            interval: 3_600_000,
+            handler: createRetentionWorkerHandler({
+                sqlite: this.sqlite,
+                getRetentionDays: () => this.config.retentionDays,
+            }),
+        });
+        // 3. Confirmation worker for Solana (30s)
+        // Build checkSolanaFinalized callback from multiplexer's Solana subscriber.
+        // Uses structural typing to access checkFinalized() without importing the concrete class.
+        const checkSolanaFinalized = async (txHash) => {
+            const entries = this.multiplexer.getSubscribersForChain('solana');
+            if (entries.length === 0)
+                return false;
+            const sub = entries[0].subscriber;
+            return sub.checkFinalized(txHash);
+        };
+        this.workers.register('incoming-tx-confirm-solana', {
+            interval: 30_000,
+            handler: createConfirmationWorkerHandler({
+                sqlite: this.sqlite,
+                checkSolanaFinalized,
+            }),
+        });
+        // 4. Confirmation worker for EVM (30s)
+        // Build getBlockNumber callback from multiplexer's EVM subscriber.
+        // Routes to the correct subscriber for the given chain:network pair.
+        const getBlockNumber = async (_chain, network) => {
+            const entries = this.multiplexer.getSubscribersForChain('ethereum');
+            const entry = entries.find((e) => e.key === `ethereum:${network}`);
+            if (!entry)
+                throw new Error(`No EVM subscriber for network ${network}`);
+            const sub = entry.subscriber;
+            return sub.getBlockNumber();
+        };
+        this.workers.register('incoming-tx-confirm-evm', {
+            interval: 30_000,
+            handler: createConfirmationWorkerHandler({
+                sqlite: this.sqlite,
+                getBlockNumber,
+            }),
+        });
+        // 5. Polling worker for Solana (configurable interval)
+        this.workers.register('incoming-tx-poll-solana', {
+            interval: this.config.pollIntervalSec * 1000,
+            handler: async () => {
+                const entries = this.multiplexer.getSubscribersForChain('solana');
+                for (const { subscriber } of entries) {
+                    try {
+                        await subscriber.pollAll();
+                    }
+                    catch (err) {
+                        console.warn('Solana polling worker error:', err);
+                    }
+                }
+            },
+        });
+        // 6. Polling worker for EVM (configurable interval)
+        this.workers.register('incoming-tx-poll-evm', {
+            interval: this.config.pollIntervalSec * 1000,
+            handler: async () => {
+                const entries = this.multiplexer.getSubscribersForChain('ethereum');
+                for (const { subscriber } of entries) {
+                    try {
+                        await subscriber.pollAll();
+                    }
+                    catch (err) {
+                        console.warn('EVM polling worker error:', err);
+                    }
+                }
+            },
+        });
+    }
+}
+//# sourceMappingURL=incoming-tx-monitor-service.js.map

package/dist/services/incoming/incoming-tx-monitor-service.js.map

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

package/dist/services/incoming/incoming-tx-queue.d.ts

@@ -0,0 +1,52 @@
+/**
+ * IncomingTxQueue: Memory buffer for incoming transactions.
+ *
+ * Collects incoming transactions from chain subscriber callbacks and
+ * batch-flushes them to SQLite in periodic intervals. Prevents SQLITE_BUSY
+ * contention from concurrent WebSocket callbacks.
+ *
+ * Features:
+ * - Map-based in-memory deduplication by txHash:walletId composite key
+ * - Bounded memory (MAX_QUEUE_SIZE = 10,000) with oldest-first eviction
+ * - Batch INSERT with ON CONFLICT DO NOTHING for DB-level safety
+ * - flush() returns only actually-inserted records
+ *
+ * @see docs/76-incoming-transaction-monitoring.md section 2.6
+ */
+import type { Database } from 'better-sqlite3';
+import type { IncomingTransaction } from '@waiaas/core';
+export declare class IncomingTxQueue {
+    private queue;
+    /** Current number of queued items. */
+    get size(): number;
+    /**
+     * Add a transaction to the queue. Synchronous, O(1).
+     *
+     * Deduplicates by txHash:walletId composite key -- if the same key
+     * already exists in the queue, the push is silently ignored.
+     *
+     * If queue is at MAX_QUEUE_SIZE, the oldest entry (first Map key)
+     * is evicted before the new entry is added.
+     */
+    push(tx: IncomingTransaction): void;
+    /**
+     * Batch-flush up to MAX_BATCH items from the queue to SQLite.
+     *
+     * Extracts items from the queue, generates UUID v7 IDs, and inserts
+     * them atomically using a SQLite transaction with ON CONFLICT DO NOTHING.
+     *
+     * @returns Only the actually-inserted IncomingTransaction items
+     *          (excludes ON CONFLICT skipped ones).
+     */
+    flush(sqlite: Database): IncomingTransaction[];
+    /**
+     * Flush the entire queue (for graceful shutdown).
+     *
+     * Calls flush() in a loop until the queue is empty,
+     * collecting all successfully inserted items.
+     *
+     * @returns All inserted IncomingTransaction items across all flush cycles.
+     */
+    drain(sqlite: Database): IncomingTransaction[];
+}
+//# sourceMappingURL=incoming-tx-queue.d.ts.map

package/dist/services/incoming/incoming-tx-queue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"incoming-tx-queue.d.ts","sourceRoot":"","sources":["../../../src/services/incoming/incoming-tx-queue.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC/C,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AAgBxD,qBAAa,eAAe;IAC1B,OAAO,CAAC,KAAK,CAA0C;IAEvD,sCAAsC;IACtC,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED;;;;;;;;OAQG;IACH,IAAI,CAAC,EAAE,EAAE,mBAAmB,GAAG,IAAI;IAgBnC;;;;;;;;OAQG;IACH,KAAK,CAAC,MAAM,EAAE,QAAQ,GAAG,mBAAmB,EAAE;IA4C9C;;;;;;;OAOG;IACH,KAAK,CAAC,MAAM,EAAE,QAAQ,GAAG,mBAAmB,EAAE;CAQ/C"}

package/dist/services/incoming/incoming-tx-queue.js

@@ -0,0 +1,109 @@
+/**
+ * IncomingTxQueue: Memory buffer for incoming transactions.
+ *
+ * Collects incoming transactions from chain subscriber callbacks and
+ * batch-flushes them to SQLite in periodic intervals. Prevents SQLITE_BUSY
+ * contention from concurrent WebSocket callbacks.
+ *
+ * Features:
+ * - Map-based in-memory deduplication by txHash:walletId composite key
+ * - Bounded memory (MAX_QUEUE_SIZE = 10,000) with oldest-first eviction
+ * - Batch INSERT with ON CONFLICT DO NOTHING for DB-level safety
+ * - flush() returns only actually-inserted records
+ *
+ * @see docs/76-incoming-transaction-monitoring.md section 2.6
+ */
+import { generateId } from '../../infrastructure/database/id.js';
+/** Maximum items extracted per flush() call. */
+const MAX_BATCH = 100;
+/** Maximum queue size before oldest entries are evicted. */
+const MAX_QUEUE_SIZE = 10_000;
+/**
+ * INSERT statement for incoming_transactions table.
+ * 13 columns matching DB v21 schema. ON CONFLICT(tx_hash, wallet_id) DO NOTHING
+ * provides DB-level dedup safety net.
+ */
+const INSERT_SQL = `INSERT INTO incoming_transactions (id, wallet_id, chain, network, tx_hash, from_address, amount, token_address, status, block_number, detected_at, confirmed_at, is_suspicious) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?) ON CONFLICT(tx_hash, wallet_id) DO NOTHING`;
+export class IncomingTxQueue {
+    queue = new Map();
+    /** Current number of queued items. */
+    get size() {
+        return this.queue.size;
+    }
+    /**
+     * Add a transaction to the queue. Synchronous, O(1).
+     *
+     * Deduplicates by txHash:walletId composite key -- if the same key
+     * already exists in the queue, the push is silently ignored.
+     *
+     * If queue is at MAX_QUEUE_SIZE, the oldest entry (first Map key)
+     * is evicted before the new entry is added.
+     */
+    push(tx) {
+        if (this.queue.size >= MAX_QUEUE_SIZE) {
+            // Drop oldest entry (first key in insertion order) to prevent memory leak
+            const firstKey = this.queue.keys().next().value;
+            if (firstKey !== undefined) {
+                this.queue.delete(firstKey);
+            }
+            console.warn('IncomingTxQueue overflow: dropping oldest entry');
+        }
+        const key = `${tx.txHash}:${tx.walletId}`;
+        if (!this.queue.has(key)) {
+            this.queue.set(key, tx);
+        }
+    }
+    /**
+     * Batch-flush up to MAX_BATCH items from the queue to SQLite.
+     *
+     * Extracts items from the queue, generates UUID v7 IDs, and inserts
+     * them atomically using a SQLite transaction with ON CONFLICT DO NOTHING.
+     *
+     * @returns Only the actually-inserted IncomingTransaction items
+     *          (excludes ON CONFLICT skipped ones).
+     */
+    flush(sqlite) {
+        if (this.queue.size === 0)
+            return [];
+        // Extract up to MAX_BATCH items from queue
+        const batch = [];
+        for (const [key, tx] of this.queue) {
+            batch.push(tx);
+            this.queue.delete(key);
+            if (batch.length >= MAX_BATCH)
+                break;
+        }
+        // Prepare INSERT statement
+        const stmt = sqlite.prepare(INSERT_SQL);
+        // Run all inserts atomically, tracking which rows were actually inserted
+        const insertMany = sqlite.transaction((txs) => {
+            const inserted = [];
+            for (const tx of txs) {
+                const id = generateId();
+                const result = stmt.run(id, tx.walletId, tx.chain, tx.network, tx.txHash, tx.fromAddress, tx.amount, tx.tokenAddress, tx.status, tx.blockNumber, tx.detectedAt, tx.confirmedAt, tx.isSuspicious ? 1 : 0);
+                if (result.changes > 0) {
+                    inserted.push({ ...tx, id });
+                }
+            }
+            return inserted;
+        });
+        return insertMany(batch);
+    }
+    /**
+     * Flush the entire queue (for graceful shutdown).
+     *
+     * Calls flush() in a loop until the queue is empty,
+     * collecting all successfully inserted items.
+     *
+     * @returns All inserted IncomingTransaction items across all flush cycles.
+     */
+    drain(sqlite) {
+        const allInserted = [];
+        while (this.queue.size > 0) {
+            const inserted = this.flush(sqlite);
+            allInserted.push(...inserted);
+        }
+        return allInserted;
+    }
+}
+//# sourceMappingURL=incoming-tx-queue.js.map

package/dist/services/incoming/incoming-tx-queue.js.map

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

package/dist/services/incoming/incoming-tx-workers.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Worker handler factories for incoming transaction lifecycle management.
+ *
+ * Provides:
+ * 1. Confirmation worker -- transitions DETECTED -> CONFIRMED based on chain-specific thresholds
+ * 2. Retention worker -- deletes records older than configurable retention_days
+ * 3. Gap recovery handler -- calls pollAll() on subscribers after reconnection
+ * 4. Cursor utilities -- read/write incoming_tx_cursors for tracking processing position
+ *
+ * All handler factories return `async () => void` functions compatible with
+ * BackgroundWorkers.register() interval pattern.
+ *
+ * @see docs/76-incoming-transaction-monitoring.md sections 2.5, 5.3
+ */
+import type { Database } from 'better-sqlite3';
+/**
+ * Chain-specific block confirmation thresholds for EVM networks.
+ * A DETECTED transaction is upgraded to CONFIRMED when
+ * `currentBlock - txBlockNumber >= threshold`.
+ */
+export declare const EVM_CONFIRMATION_THRESHOLDS: Record<string, number>;
+/** Default threshold when network is not in EVM_CONFIRMATION_THRESHOLDS. */
+export declare const DEFAULT_EVM_CONFIRMATIONS = 12;
+/** Solana commitment level used for confirmation check. */
+export declare const SOLANA_CONFIRMATION = "finalized";
+interface ConfirmationWorkerDeps {
+    /** Raw SQLite handle for queries and updates. */
+    sqlite: Database;
+    /** Returns the current block number for the given EVM chain:network. */
+    getBlockNumber?: (chain: string, network: string) => Promise<bigint>;
+    /** Checks if a Solana transaction has reached finalized commitment. */
+    checkSolanaFinalized?: (txHash: string) => Promise<boolean>;
+}
+interface RetentionWorkerDeps {
+    /** Raw SQLite handle for DELETE operations. */
+    sqlite: Database;
+    /** Returns current retention period in days (supports hot-reload). */
+    getRetentionDays: () => number;
+}
+interface GapRecoveryDeps {
+    /** Map of connection key ("chain:network") to subscriber with pollAll(). */
+    subscribers: Map<string, {
+        subscriber: {
+            pollAll: () => Promise<void>;
+        };
+    }>;
+}
+/**
+ * Creates a handler that upgrades DETECTED transactions to CONFIRMED.
+ *
+ * - Solana: calls checkSolanaFinalized(txHash). If true -> CONFIRMED.
+ * - EVM: computes `currentBlock - txBlock`. If >= threshold -> CONFIRMED.
+ * - Per-record error isolation: one failure does not block other records.
+ */
+export declare function createConfirmationWorkerHandler(deps: ConfirmationWorkerDeps): () => Promise<void>;
+/**
+ * Creates a handler that deletes incoming_transactions records
+ * older than the configured retention period.
+ *
+ * Uses raw SQLite DELETE for efficiency. getRetentionDays() is called
+ * each invocation to support hot-reload of the setting.
+ */
+export declare function createRetentionWorkerHandler(deps: RetentionWorkerDeps): () => Promise<void>;
+/**
+ * Creates a handler for recovering missed transactions after reconnection.
+ *
+ * When a WebSocket reconnects, the gap between last-known cursor and current
+ * chain state needs to be filled. This handler finds the relevant subscriber
+ * and calls pollAll() to recover missed transactions.
+ */
+export declare function createGapRecoveryHandler(deps: GapRecoveryDeps): (chain: string, network: string, walletIds: string[]) => Promise<void>;
+/**
+ * Save or update the processing cursor for a wallet.
+ *
+ * Uses INSERT OR REPLACE to handle both new and existing cursors.
+ * The cursor value is chain-specific:
+ * - Solana: last processed transaction signature
+ * - EVM: last processed block number (as string)
+ */
+export declare function updateCursor(sqlite: Database, walletId: string, chain: string, network: string, cursor: string): void;
+/**
+ * Load the processing cursor for a wallet.
+ *
+ * Returns the cursor value (signature or block number as string),
+ * or null if no cursor exists for the given wallet+chain+network.
+ */
+export declare function loadCursor(sqlite: Database, walletId: string, chain: string, network: string): string | null;
+export {};
+//# sourceMappingURL=incoming-tx-workers.d.ts.map

package/dist/services/incoming/incoming-tx-workers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"incoming-tx-workers.d.ts","sourceRoot":"","sources":["../../../src/services/incoming/incoming-tx-workers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAI/C;;;;GAIG;AACH,eAAO,MAAM,2BAA2B,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAS9D,CAAC;AAEF,4EAA4E;AAC5E,eAAO,MAAM,yBAAyB,KAAK,CAAC;AAE5C,2DAA2D;AAC3D,eAAO,MAAM,mBAAmB,cAAc,CAAC;AAI/C,UAAU,sBAAsB;IAC9B,iDAAiD;IACjD,MAAM,EAAE,QAAQ,CAAC;IACjB,wEAAwE;IACxE,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IACrE,uEAAuE;IACvE,oBAAoB,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;CAC7D;AAED,UAAU,mBAAmB;IAC3B,+CAA+C;IAC/C,MAAM,EAAE,QAAQ,CAAC;IACjB,sEAAsE;IACtE,gBAAgB,EAAE,MAAM,MAAM,CAAC;CAChC;AAED,UAAU,eAAe;IACvB,4EAA4E;IAC5E,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE;QAAE,UAAU,EAAE;YAAE,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;SAAE,CAAA;KAAE,CAAC,CAAC;CAC5E;AAID;;;;;;GAMG;AACH,wBAAgB,+BAA+B,CAC7C,IAAI,EAAE,sBAAsB,GAC3B,MAAM,OAAO,CAAC,IAAI,CAAC,CAmErB;AAID;;;;;;GAMG;AACH,wBAAgB,4BAA4B,CAC1C,IAAI,EAAE,mBAAmB,GACxB,MAAM,OAAO,CAAC,IAAI,CAAC,CAgBrB;AAID;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CACtC,IAAI,EAAE,eAAe,GACpB,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAqBxE;AAID;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAC1B,MAAM,EAAE,QAAQ,EAChB,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,GACb,IAAI,CAiBN;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CACxB,MAAM,EAAE,QAAQ,EAChB,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,MAAM,GACd,MAAM,GAAG,IAAI,CAgBf"}