dexbot 1.1.10

package/dist/modules/dexbot_class.d.ts

@@ -0,0 +1,1074 @@
+/**
+ * modules/dexbot_class.ts - DEXBot Core Engine
+ *
+ * Core trading bot implementation shared by bot.ts (single) and dexbot.ts (multi-bot).
+ * Implements complete grid trading bot lifecycle.
+ *
+ * Responsibilities:
+ * - Bot initialization and account setup
+ * - Order placement and batch operations
+ * - Fill processing and synchronization
+ * - Grid rebalancing and order rotation
+ * - Divergence detection and correction
+ * - State persistence and recovery
+ * - Market monitoring and health checks
+ *
+ * ===============================================================================
+ * CORE CLASS: DEXBot
+ * ===============================================================================
+ *
+ * LIFECYCLE METHODS:
+ *   - constructor(config) - Initialize bot with configuration
+ *   - run() - Start bot operation loop
+ *   - shutdown() - Graceful shutdown
+ *
+ * FILL PROCESSING:
+ *   - processFills() - Handle fill events
+ *
+ * SYNCHRONIZATION:
+ *   - reconcileGrid() - Reconcile grid state with blockchain
+ *
+ * MONITORING:
+ *   - monitorHealth() - Check bot health status
+ *
+ * ===============================================================================
+ *
+ * HELPER FUNCTIONS (module-level):
+ *   - normalizeBotEntry() - Normalize bot configuration object
+ *
+ * ===============================================================================
+ *
+ * STATE MANAGEMENT:
+ * - Internal OrderManager maintains all state
+ * - Persists grid snapshots to profiles/orders/{botKey}.json
+ * - Recovers from persisted state on startup
+ * - Real-time synchronization with blockchain
+ *
+ * ERROR HANDLING:
+ * - Graceful error recovery
+ * - Automatic reconnection on connection loss
+ * - Anomaly detection and correction
+ * - Detailed logging for debugging
+ *
+ * ===============================================================================
+ */
+declare class DEXBot {
+    config: any;
+    _baseWeightDistribution: {
+        sell: number;
+        buy: number;
+    };
+    account: any;
+    accountId: string | null;
+    privateKey: any;
+    manager: any;
+    accountOrders: any;
+    triggerFile: string;
+    _recentlyQueuedFills: Map<any, any>;
+    _fillCleanupCounter: number;
+    _fillDedupeWindowMs: number;
+    _fillRecordRetentionMs: number;
+    _processedFillPersistBatchMs: number;
+    _processedFillPersistBatchSize: number;
+    _processedFillStore: any;
+    _recentlyProcessedFills: any;
+    _pendingProcessedFillWrites: any;
+    _incomingFillQueue: any[];
+    logPrefix: string;
+    _credentialDaemonWatchdogInterval: any;
+    _credentialDaemonDown: boolean;
+    _credentialRecoveryNeeded: boolean;
+    _credentialRecoveryInFlight: boolean;
+    _credentialDaemonWatchdogInFlight: boolean;
+    _staleCleanedOrderIds: Map<string, number>;
+    _staleCleanupRetentionMs: number;
+    _metrics: any;
+    _shuttingDown: boolean;
+    _shutdownStarted: boolean;
+    _shutdownPromise: Promise<void> | null;
+    _blockchainFetchInterval: any;
+    _blockchainFetchInFlight: boolean;
+    _fillsUnsubscribe: any;
+    _triggerWatcher: any;
+    _triggerDebounceTimer: any;
+    _deferredGridResyncTimer: any;
+    _maintenanceIdleTimer: any;
+    _mainLoopActive: boolean;
+    _mainLoopPromise: any;
+    _creditRuntime: any;
+    _creditWatchdogInterval: any;
+    _batchInFlight: boolean;
+    _recoverySyncInFlight: boolean;
+    _lastTargetedDriftSyncAt: number;
+    _targetedDriftSyncCooldownMs: number;
+    _maintenanceCooldownCycles: number;
+    _lastGridActivityAt: number;
+    _currentCycleId: number;
+    _autoCancelOrphanCycleMarker: number | null;
+    _consecutiveConsumeFailures: number;
+    _consumeFailureFirstAt: number;
+    _reconnectUnregister: any;
+    _credentialRecoveryDeferredTimer: any;
+    _structuralGridResyncTimer: any;
+    _structuralGridResyncRunning: boolean;
+    _dustHealthCheckTimer: any;
+    _lastBroadcastHeartbeatAt: number;
+    _currentBatchId: any;
+    /**
+     * Create a new DEXBot instance
+     * @param {Object} config - Bot configuration from profiles/bots.json
+     * @param {Object} options - Optional settings
+     * @param {string} options.logPrefix - Prefix for console logs (e.g., "[bot.js]")
+     */
+    constructor(config: any, options?: {
+        logPrefix?: string;
+    });
+    /**
+     * Validate startup configuration to catch errors early.
+     * Ensures critical values are valid before bot starts.
+     * @param {Object} config - Configuration object to validate
+     * @throws {Error} If critical validation fails
+     * @private
+     */
+    _validateStartupConfig(config: any): void;
+    /**
+     * Log a message to the console with the bot's prefix.
+     * @param {string} msg - The message to log.
+     * @param {string} [level='info'] - The log level ('debug', 'info', 'warn', 'error').
+     * @private
+     */
+    _log(msg: any, level?: string): void;
+    /**
+     * Log a warning message to the console with the bot's prefix.
+     * @param {string} msg - The message to log.
+     * @private
+     */
+    _warn(msg: any): void;
+    /**
+     * Persist the grid and trigger immediate recovery if validation fails.
+     * Used during startup to ensure bot begins in a stable state.
+     * @private
+     */
+    _persistAndRecoverIfNeeded(): Promise<void>;
+    /**
+     * Get current pipeline signal state for congestion checks.
+     * @returns {{incomingFillQueueLength: number, shadowLocks: number, batchInFlight: boolean, recoveryInFlight: boolean, broadcasting: boolean}}
+     */
+    _getPipelineSignals(): {
+        incomingFillQueueLength: number;
+        shadowLocks: any;
+        batchInFlight: boolean;
+        recoveryInFlight: boolean;
+        broadcasting: any;
+    };
+    /**
+     * Mark that grid activity occurred (updates idle timer).
+     * @param {string} [reason='activity'] - Reason for activity
+     * @returns {void}
+     */
+    _markGridActivity(reason?: string): void;
+    /**
+     * Trigger a full state recovery sync (fetch chain + sync from open orders + persist).
+     * @param {string} [reason='state recovery sync'] - Reason for recovery
+     * @returns {Promise<void>}
+     */
+    _triggerStateRecoverySync(reason?: string): Promise<void>;
+    /**
+     * Abort the current flow if an illegal state signal was raised.
+     * @param {string} flowContext - Description of the flow being aborted
+     * @returns {Promise<boolean>} True if flow was aborted
+     */
+    _abortFlowIfIllegalState(flowContext: any): Promise<boolean>;
+    /**
+     * Handle a hard abort from batch processing due to illegal state or accounting failure.
+     * @param {Error} err - The error that triggered the abort
+     * @param {string} [phase='batch processing'] - Phase description
+     * @param {number} [opsCount=0] - Number of operations in the batch
+     * @returns {Promise<Object>} Abort result object
+     */
+    _handleBatchHardAbort(err: any, phase?: string, opsCount?: number): Promise<{
+        abortedForIllegalState: boolean;
+        executed: boolean;
+        hadRotation: boolean;
+    } | {
+        abortedForAccountingFailure: boolean;
+        executed: boolean;
+        hadRotation: boolean;
+    }>;
+    /**
+     * Apply recoverable grid updates (order virtualisation) after a batch failure.
+     * @param {Array<Object>} updates - Array of order update objects
+     * @param {string} [context='recoverable-grid-update'] - Context label for logging
+     * @returns {Promise<number>} Number of updates applied
+     */
+    _applyRecoverableGridUpdates(updates: any, context?: string): Promise<any>;
+    /**
+     * Recover from explicit stale order errors by virtualizing affected grid slots.
+     * @param {Set<string>|string[]} staleOrderIds - Set or array of stale chain order IDs
+     * @param {string} [reason='stale order cleanup'] - Reason for cleanup
+     * @returns {Promise<{executed: boolean, hadRotation: boolean, stale: boolean, recoveredByVirtualization?: boolean}>}
+     */
+    _recoverExplicitStaleOrders(staleOrderIds: any, reason?: string): Promise<{
+        executed: boolean;
+        hadRotation: boolean;
+        stale: boolean;
+        recoveredByVirtualization?: undefined;
+    } | {
+        executed: boolean;
+        hadRotation: boolean;
+        stale: boolean;
+        recoveredByVirtualization: boolean;
+    }>;
+    /**
+     * Recover from on-chain size drift detected during batch broadcast.
+     * @param {Error} err - The size drift error
+     * @returns {Promise<{executed: boolean, hadRotation: boolean, recoveredBySync: boolean, reason: string}>}
+     */
+    _recoverBatchSizeDrift(err: any, opContexts?: any[]): Promise<{
+        executed: boolean;
+        hadRotation: boolean;
+        recoveredBySync: boolean;
+        reason: string;
+    }>;
+    /**
+     * Extract chain order IDs from opContexts for operations that could
+     * trigger a size-drift error (size-update and rotation update).
+     * @param {Array<Object>} opContexts
+     * @returns {string[]} Unique chain order IDs
+     */
+    _extractSizeDriftOrderIds(opContexts: any): unknown[];
+    /**
+     * Attempt to repair size-drift for specific order IDs by reading their
+     * current on-chain state and correcting the local grid directly.
+     * Falls back gracefully (returns false) on any error.
+     * @param {string[]} orderIds
+     * @returns {Promise<boolean>} True if all affected orders were repaired
+     */
+    _targetedOrderRepair(orderIds: any): Promise<boolean>;
+    /**
+     * Initialize bot state from storage and blockchain.
+     * Consolidates common initialization logic for start() and startWithPrivateKey().
+     * @returns {{persistedGrid: Object, persistedBtsFeesOwed: number, persistedBoundaryIdx: number, persistedBtsBalance: number}}
+     * @private
+     */
+    _initializeStartupState(): Promise<{
+        persistedGrid: any;
+        persistedBtsFeesOwed: any;
+        persistedBoundaryIdx: any;
+        persistedBtsBalance: any;
+    }>;
+    /**
+     * Wire processed fill tracking into the manager.
+     * @returns {void}
+     */
+    _wireProcessedFillTracking(): any;
+    /**
+     * Flush pending processed fill persistence to disk.
+     * @param {string} [reason='manual'] - Reason for flushing
+     * @param {Object} [options={}] - Flush options
+     * @returns {Promise<void>}
+     */
+    _flushProcessedFillPersistence(reason?: string, options?: {}): Promise<any>;
+    /**
+     * Flush persistence for specific fill keys.
+     * @param {Set<string>|string[]} fillKeys - Fill keys to persist
+     * @param {string} [reason='manual-selected'] - Reason for flushing
+     * @param {Object} [options={}] - Flush options
+     * @returns {Promise<void>}
+     */
+    _flushProcessedFillPersistenceForKeys(fillKeys: any, reason?: string, options?: {}): Promise<any>;
+    /**
+     * Discard pending persistence for specific fill keys.
+     * @param {string[]|Set<string>} fillKeys - Fill keys to discard
+     * @returns {void}
+     */
+    _discardPendingProcessedFillPersistence(fillKeys: any): any;
+    /**
+     * Build a fallback deduplication key for an orphan fill (when standard keys are unavailable).
+     * @param {Object} fill - Fill event object
+     * @returns {string|null} Fallback key or null
+     */
+    _buildOrphanFillFallbackKey(fill: any): any;
+    _isNewFillKey(fillKey: any, processedFillKeys: any, label?: string): boolean;
+    /**
+     * Apply replay-safe fill accounting using a provided fill key.
+     * @param {Object} fill - Fill event object
+     * @param {import('./types').FillOperationData} fillOp - Fill operation data
+     * @param {Object} [options={}] - Options
+     * @param {string} [options.missingKeyMessage]
+     * @param {string} [options.fallbackKeyMessage]
+     * @param {string} [options.replayMessage]
+     * @param {string} [options.errorMessage]
+     * @param {Object} [options.logger]
+     * @param {string} [options.missingKeyLevel='warn']
+     * @param {string} [options.fallbackKeyLevel='warn']
+     * @param {string} [options.replayLevel='debug']
+     * @param {string} [options.persistenceMode='immediate']
+     * @param {boolean} [options.allowOrphanFallbackKey=false]
+     * @returns {Promise<import('./types').ReplaySafeFillResult>}
+     */
+    _applyReplaySafeFillAccounting(fill: any, fillOp: any, { missingKeyMessage, fallbackKeyMessage, replayMessage, errorMessage, logger, missingKeyLevel, fallbackKeyLevel, replayLevel, persistenceMode, allowOrphanFallbackKey }?: {
+        missingKeyMessage?: any;
+        fallbackKeyMessage?: any;
+        replayMessage?: any;
+        errorMessage?: any;
+        logger?: any;
+        missingKeyLevel?: string;
+        fallbackKeyLevel?: string;
+        replayLevel?: string;
+        persistenceMode?: any;
+        allowOrphanFallbackKey?: boolean;
+    }): Promise<any>;
+    /**
+     * Apply replay-safe fill accounting for tracked fills (those with a valid grid order).
+     * @param {Object} fill - Fill event object
+     * @param {import('./types').FillOperationData} fillOp - Fill operation data
+     * @param {Object} [options={}]
+     * @param {string} [options.context]
+     * @param {Object} [options.logger]
+     * @param {string} [options.replayMessage]
+     * @param {string} [options.persistenceMode='batched']
+     * @returns {Promise<import('./types').ReplaySafeFillResult>}
+     */
+    _applyReplaySafeTrackedFillAccounting(fill: any, fillOp: any, { context, logger, replayMessage, persistenceMode }?: {
+        context?: string;
+        logger?: any;
+        replayMessage?: any;
+        persistenceMode?: any;
+    }): Promise<any>;
+    /**
+     * Apply replay-safe fill accounting for orphan fills (grid order not found).
+     * @param {Object} fill - Fill event object
+     * @param {import('./types').FillOperationData} fillOp - Fill operation data
+     * @param {Object} [options={}]
+     * @param {string} [options.context]
+     * @param {Object} [options.logger]
+     * @param {string} [options.replayMessage]
+     * @param {string} [options.persistenceMode='immediate']
+     * @returns {Promise<import('./types').ReplaySafeFillResult>}
+     */
+    _applyReplaySafeOrphanFillAccounting(fill: any, fillOp: any, { context, logger, replayMessage, persistenceMode }?: {
+        context?: string;
+        logger?: any;
+        replayMessage?: any;
+        persistenceMode?: any;
+    }): Promise<any>;
+    /**
+     * Refresh dynamic weight distribution from market adapter.
+     * @param {string} [context='runtime'] - Context label for logging
+     * @returns {import('./types').DynamicWeightRefreshResult|null}
+     */
+    _refreshDynamicWeightDistribution(context?: string): any;
+    /**
+     * Finalize the bot startup after account and initial grid sync are complete.
+     * Consolidates common logic for start() and startWithPrivateKey().
+     * @param {Object} startupState - The startup state from _initializeStartupState.
+     * @private
+     */
+    _finishStartupSequence(startupState: any): Promise<void>;
+    /**
+     * Create the fill callback for listenForFills.
+     * Separated from start() to allow deferred activation after startup completes.
+     * @param {Object} chainOrders - Chain orders module for blockchain operations
+     * @returns {Function} Async callback for processing fills
+     * @private
+     */
+    _createFillCallback(chainOrders: any): any;
+    /**
+     * Read open orders from chain, sync with local state, and process any fills found.
+     * Shared helper used by post-reset spread check and targeted drift reconciliation.
+     * @param {string} tag - Context label for logging
+     * @returns {Promise<{syncResult: Object|null, aborted: boolean, hasUnmatched: number, openOrders: Array|null}>}
+     */
+    _syncOpenOrdersAndProcessFills(tag: any): Promise<{
+        syncResult: any;
+        aborted: boolean;
+        hasUnmatched: any;
+        openOrders: any;
+    }>;
+    _maxConsecutiveFillConsumerFailures(): any;
+    /**
+     * Compute the backoff delay for fill-consumer retries after the failure
+     * budget (MAX_CONSECUTIVE_CONSUMER_FAILURES) is exhausted. Each retry
+     * doubles the previous delay, capped at CONSUMER_BACKOFF_MAX_MS. The
+     * consumer NEVER permanently stops re-scheduling — it just slows down.
+     * @param {number} failures The current consecutive-failure count.
+     * @returns {number} Delay in milliseconds before the next retry.
+     * @private
+     */
+    _computeFillConsumerBackoffMs(failures: any): number;
+    _scheduleFillConsumerRestart(chainOrders: any): void;
+    /**
+     * Consume queued fills from incomingFillQueue and rebalance.
+     *
+     * 1. Deduplicates fills against already-processed set (replay-safe)
+     * 2. Syncs filled orders from history or open orders mode
+     * 3. Handles price mismatches via correctAllPriceMismatches
+     * 4. Processes fills sequentially with interruptible rebalancing (merges new work between fills)
+     * 5. Periodically cleans old fill records to prevent memory leaks
+     *
+     * Atomic lock behavior: If already processing or has waiters, returns immediately (no double-queuing)
+     * @param {Object} chainOrders - Chain orders module for blockchain operations
+     * @private
+     */
+    _consumeFillQueue(chainOrders: any): Promise<void>;
+    /**
+     * Process fills during bootstrap phase using the standard fill pipeline.
+     *
+     * BOOTSTRAP MODE STRATEGY:
+     * - Delegate to the same fill pipeline as the post-reset path
+     * - Same-side replacement at the filled slot (handled by processFillsOnly)
+     * - Symmetric grid regen via COW rebalance (calculateTargetGrid + reconcileGrid)
+     * - Dust orders are cancelled by the rebalance's isCreateHealthy / cancelSurpluses
+     *
+     * This ensures:
+     * - Identical behavior between bootstrap and post-reset
+     * - Grid symmetry maintained by the rebalance, not by manual rotation
+     * - Budget safety enforced by validateWorkingGridFunds in the COW engine
+     *
+     * @param {Object} chainOrders - Chain orders instance for broadcasting
+     * @returns {Promise<void>}
+     */
+    _processFillsWithBootstrapMode(chainOrders: any): Promise<void>;
+    /**
+     * Set up account identifier and configure global context.
+     * @param {string} accountName - The name of the account to set up
+     * @private
+     */
+    _setupAccountContext(accountName: any): Promise<void>;
+    /**
+     * Initialize the bot by connecting to BitShares and setting up the account.
+     * @param {string|Object|Buffer} [vaultSecret=null] - The unlock secret for authentication.
+     * @returns {Promise<void>}
+     * @throws {Error} If initialization fails or preferredAccount is missing.
+     */
+    initialize(vaultSecret?: any): Promise<void>;
+    /**
+     * Places initial orders on the blockchain.
+     * @returns {Promise<void>}
+     */
+    placeInitialOrders(): Promise<void>;
+    /**
+     * Build outside-in pair groups for initial order placement.
+     * @param {Array<Object>} orders - Array of order objects
+     * @returns {Array<Array<Object>>} Grouped order arrays
+     */
+    _buildOutsideInPairGroupsForOrders(orders: any): any;
+    /**
+     * Build outside-in pair groups for create entry contexts.
+     * @param {Array<Object>} createEntries - Array of create entry objects with context.order
+     * @returns {Array<Array<Object>>} Grouped entry arrays
+     */
+    _buildOutsideInPairGroupsForCreateEntries(createEntries: any): any;
+    /**
+     * Resolve the centralized fill batch cap.
+     * @returns {number} Positive maximum number of fill-driven rotations per broadcast cycle
+     */
+    _getMaxFillBatchSize(): number;
+    /**
+     * Extract operation results from a batch transaction result.
+     * @param {Object|Array|null} result - Transaction result from executeBatch
+     * @param {string} [warnContext=''] - Context for warning messages
+     * @returns {Array} Array of operation result entries
+     */
+    _extractOperationResults(result: any, warnContext?: string): any[];
+    /**
+     * Find CREATE operation contexts whose broadcast result did not include a chain order id.
+     *
+     * @param {Array} operationResults - operation_results aligned with opContexts.
+     * @param {Array<Object>} opContexts - Operation context metadata aligned with operations.
+     * @returns {Array<{index:number, ctx:Object}>} Missing create result contexts.
+     */
+    _findMissingCreateResultContexts(operationResults: any, opContexts: any): any[];
+    /**
+     * Run an immediate chain sync after a successful CREATE broadcast returned incomplete ids.
+     *
+     * Missing-create blockers are intentionally preserved if the recovery snapshot does not
+     * account for the affected local slot. The sync engine owns normal clearing of
+     * _lastUnmatchedChainOrders after a successful clean snapshot; this method prevents a
+     * lagging empty snapshot from clearing blockers that were just created by this flow.
+     *
+     * @param {string} [reason] - Human-readable recovery context for logs.
+     * @returns {Promise<void>}
+     */
+    _recoverAfterMissingCreateResults(reason?: string): Promise<void>;
+    /**
+     * Restore unresolved missing-create blockers after recovery if sync did not adopt them.
+     *
+     * @param {Array<Object>} blockers - Pre-recovery missing-create blockers.
+     * @param {Object} recoveryResult - Result returned by manager.syncFromOpenOrders.
+     * @returns {void}
+     */
+    _preserveMissingCreateBlockersAfterRecovery(blockers: any, recoveryResult: any): void;
+    /**
+     * Merge missing CREATE result contexts into manager._lastUnmatchedChainOrders.
+     *
+     * The sync engine sets and clears _lastUnmatchedChainOrders on full sync snapshots.
+     * COW uses the same manager field as a structural create blocker before broadcasting.
+     * Missing-create entries are keyed by reason:slotId:operationIndex to avoid replacing
+     * unrelated unmatched chain orders that may already be blocking new creates.
+     *
+     * @param {Array<{index:number, ctx:Object}>} missingCreateResults - Missing CREATE results.
+     * @returns {void}
+     */
+    _markMissingCreateResultsAsStructuralBlocker(missingCreateResults: any): void;
+    /**
+     * Format an unmatched chain order/blocker for COW logs.
+     *
+     * @param {Object} order - Unmatched chain order or structural blocker.
+     * @returns {string} Compact human-readable diagnostic.
+     */
+    _formatUnmatchedChainOrderForLog(order: any): any;
+    /**
+     * Record a pending CREATE broadcast on the manager.
+     *
+     * Called immediately after each CREATE op is built into the opContext list.
+     * The fingerprint and op indices are stashed so the recovery path in
+     * _reconcileAfterUncertainBroadcast can correlate the planned op with an
+     * on-chain order (or discard it as a chain-side orphan).
+     *
+     * Storage: manager._pendingBroadcasts is a Map<fingerprint, PendingEntry>.
+     * We store on the manager (not on the bot) so the sync engine, grid
+     * reconcile, and any other consumer can read it without crossing the
+     * bot/manager boundary.
+     *
+     * @param {Object} entry
+     * @param {number} entry.opIndex - Index into the operations array
+     * @param {number} entry.ctxIndex - Index into opContexts
+     * @param {Object} entry.order - The grid order being broadcast
+     * @param {Object} entry.finalInts - { amountToSell, minToReceive, ... } blockchain integers
+     * @returns {void}
+     */
+    _recordPendingBroadcast(entry: any): void;
+    /**
+     * Clear the pending-broadcast cache.
+     *
+     * Called after a successful commit, after a confirmed failure (so the
+     * stale entries don't block the next cycle), and after a successful
+     * recovery adoption (matched entries are explicitly removed by
+     * _reconcileAfterUncertainBroadcast before calling this).
+     */
+    _clearPendingBroadcasts(): void;
+    /**
+     * Build a fingerprint for an on-chain order so it can be matched against
+     * the pending-broadcast cache.
+     *
+     * @param {Object} chainOrder - Parsed chain order (id, sell, receive, sellAssetId, receiveAssetId, ...)
+     * @param {string} slotId - The grid slot id (order.id) we expect this chain order to belong to
+     * @returns {string|null} Fingerprint or null on bad input
+     */
+    _buildChainOrderFingerprint(chainOrder: any, slotId: any): any;
+    /**
+     * Normalize raw BitShares limit_order_object data into the integer tuple
+     * used by pending-broadcast recovery.
+     *
+     * readOpenOrders() returns raw orders with sell_price/for_sale, not the
+     * parsed DEXBot fields type/sellInt/receiveInt. Test fixtures may still
+     * pass the parsed shape, so this helper accepts both.
+     *
+     * @param {Object} chainOrder
+     * @returns {{side: string, assetA: string, assetB: string, sellInt: number, receiveInt: number}|null}
+     */
+    _normalizeChainOrderForPendingMatch(chainOrder: any): {
+        side: any;
+        assetA: any;
+        assetB: any;
+        sellInt: number;
+        receiveInt: number;
+    };
+    /**
+     * Find a chain order that matches a planned slot using price+size proximity.
+     *
+     * Fallback for the case where the chain order's integer pair doesn't
+     * bit-match the planned op (e.g. the daemon normalized the minToReceive
+     * by ±1 unit to force an op, or precision rounding changed a value by 1).
+     * For each open chain order we build a fingerprint candidate per known
+     * slot id and accept the first exact match; if none, we look for a near
+     * match by sell+receive integer proximity.
+     *
+     * @param {Array<Object>} chainOrders - Open chain orders for the account
+     * @param {string} slotId - Planned grid slot id
+     * @param {Object} planned - { sell, receive, orderType } integers from the planned op
+     * @returns {Object|null} Matching chain order, or null
+     */
+    _findChainOrderForSlot(chainOrders: any, slotId: any, planned: any): any;
+    /**
+     * Reconcile a broadcast whose chain state is unknown.
+     *
+     * Triggered when the credential daemon times out (or hits its inner
+     * deadline) before confirming the broadcast. The chain may or may not
+     * have accepted the operations; we MUST treat the state as uncertain
+     * and recover deterministically.
+     *
+     * Algorithm:
+     *   1. Read the account's current open orders from the chain.
+     *   2. For each pending-broadcast entry (fingerprinted CREATE op), look
+     *      for a matching chain order. If found: adopt it (set the opContext's
+     *      chainOrderId and continue with the existing planned slot).
+     *   3. For pending entries with no chain match: virtualize (mark the
+     *      opContext as discarded; the planned slot stays empty until the
+     *      next planning cycle).
+     *   4. Persist + log a structured [COW][UNCERTAIN] summary.
+     *
+     * After this method returns, the bot has either adopted the on-chain
+     * result (good case — chain accepted but we didn't see the reply) or
+     * accepted the discard (chain rejected or never received the op).
+     *
+     * @param {BroadcastUncertainError} err - The thrown error
+     * @param {Array<Object>} opContexts - Original opContexts from the failed batch
+     * @returns {Promise<Object>} Result object compatible with batch return shape
+     */
+    _reconcileAfterUncertainBroadcast(err: any, opContexts: any, options?: {
+        fillLockAlreadyHeld?: boolean;
+        [key: string]: any;
+    }): Promise<any>;
+    _reconcileAfterUncertainBroadcastImpl(err: any, opContexts: any, options: any): Promise<{
+        executed: boolean;
+        hadRotation: boolean;
+        uncertain: boolean;
+        adopted?: undefined;
+        discarded?: undefined;
+    } | {
+        executed: boolean;
+        hadRotation: boolean;
+        uncertain: boolean;
+        adopted: any[];
+        discarded: any[];
+    }>;
+    /**
+     * Auto-cancel a single unmatched chain order from the recovery snapshot.
+     *
+     * This is the post-recovery safety net: if, after
+     * _reconcileAfterUncertainBroadcast runs, there are still chain orders
+     * the bot doesn't recognize (e.g. from a network partition, or from a
+     * daemon timeout that we couldn't even fingerprint), we cancel ONE of
+     * them per call. Per-cycle cap = 1 — the next cycle will pick up the
+     * next unmatched order if more remain.
+     *
+     * Safety conditions (ALL must hold):
+     *   1. _pendingBroadcasts is empty (no in-flight recovery)
+     *   2. _lastUnmatchedChainOrders is non-empty
+     *   3. The current cycle has not already auto-cancelled an orphan
+     *      (tracked via this._autoCancelOrphanCycleMarker)
+     *
+     * Records the cancel via _recordOwnCancelOps so the fill consumer
+     * doesn't trip the self-cancel guard.
+     *
+     * @returns {Promise<{cancelled: boolean, orderId?: string, reason?: string}>}
+     */
+    _autoCancelOneUnmatchedOrphan(): Promise<{
+        cancelled: boolean;
+        reason: string;
+        orderId?: undefined;
+        error?: undefined;
+    } | {
+        cancelled: boolean;
+        orderId: any;
+        reason?: undefined;
+        error?: undefined;
+    } | {
+        cancelled: boolean;
+        reason: string;
+        error: any;
+        orderId?: undefined;
+    }>;
+    /**
+     * Check whether to execute creates in outside-in pair mode (mixed BUY/SELL operations).
+     * @param {Array<Object>} opContexts - Operation contexts array
+     * @returns {boolean} True if pair mode should be used
+     */
+    _shouldExecuteCreatePairMode(opContexts: any): boolean;
+    /**
+     * Execute operations with retry on BroadcastUncertainError.
+     * The daemon already retries internally against a 25s deadline.
+     * If all expire, a fresh bot-level attempt buys a new 25s window.
+     *
+     * Skips retry when partialOnChainState is true (pair-mode grouped
+     * execution where earlier groups already committed). Re-broadcasting
+     * the full operations array would duplicate those creates on chain.
+     */
+    _executeWithRetryOnUncertain(operations: any, opContexts: any): Promise<{
+        result: any;
+        opContexts: any;
+    }>;
+    /**
+     * Execute blockchain operations with appropriate strategy (single batch or pair mode).
+     * @param {Array<import('./types').CreatedOperation>} operations - Array of operation objects
+     * @param {Array<Object>} opContexts - Array of operation context metadata (1:1 with operations)
+     * @returns {Promise<{result: Object, opContexts: Array}>} Execution result with contexts
+     */
+    _executeOperationsWithStrategy(operations: any, opContexts: any): Promise<{
+        result: any;
+        opContexts: any;
+    }>;
+    /**
+     * Validate that operations can be executed with available funds before broadcasting.
+     * Checks sufficient available funds for all operations.
+     * @param {Array} operations - Operations to validate
+     * @param {Object} assetA - Asset A metadata (id, precision, symbol)
+     * @param {Object} assetB - Asset B metadata (id, precision, symbol)
+     * @returns {Object} { isValid: boolean, summary: string }
+     * @private
+     */
+    _validateOperationFunds(operations: any, assetA: any, assetB: any): {
+        isValid: boolean;
+        summary: string;
+        violations?: undefined;
+    } | {
+        isValid: boolean;
+        summary: string;
+        violations: any[];
+    };
+    /**
+     * Resolve the ideal size from an order-like object with fallback.
+     * @param {Object|null} orderLike - Order-like object with optional idealSize/size nested properties
+     * @param {number|null} [fallbackSize=null] - Fallback size if none found
+     * @returns {number|null} Resolved size or null
+     */
+    _resolveIdealSizeForValidation(orderLike: any, fallbackSize?: any): number;
+    /**
+     * Validate that an order size is safe to execute (above minimum dust thresholds).
+     * @param {number} size - Order size to validate
+     * @param {string} type - ORDER_TYPES.BUY or ORDER_TYPES.SELL
+     * @param {Object|null} [orderLike=null] - Optional order-like object for ideal size comparison
+     * @param {number|null} [fallbackSize=null] - Fallback ideal size
+     * @returns {import('./types').OrderValidationResult}
+     */
+    _validateOrderSizeForExecution(size: any, type: any, orderLike?: any, fallbackSize?: any): any;
+    /**
+     * Execute a batch of order operations if the rebalance result has executable actions.
+     * @param {Object} rebalanceResult - COW rebalance result with actions
+     * @param {string} [contextLabel='rebalance'] - Context label for logging
+     * @returns {Promise<Object>} Batch execution result
+     */
+    _executeBatchIfNeeded(rebalanceResult: any, contextLabel?: string): Promise<any>;
+    /**
+     * Process filled orders in capped batches per FILL_PROCESSING.MAX_FILL_BATCH_SIZE.
+     * Each chunk triggers its own processFilledOrders → COW plan → broadcast cycle.
+     *
+     * @param {Array} fills - Filled order objects to process
+     * @param {Set|null} excl - Exclusion set (order IDs to skip)
+     * @param {string} contextLabel - Label for logging and batch context
+     * @param {Object} [options={}] - Passed through to processFilledOrders
+     * @returns {{aborted: boolean}}
+     */
+    _processFillsWithBatching(fills: any, excl: any, contextLabel: any, options?: {}): Promise<{
+        aborted: boolean;
+    }>;
+    /**
+     * Check if the bot requires credential daemon for write operations.
+     * @returns {boolean}
+     */
+    _isCredentialDaemonWriteRequired(): any;
+    /**
+     * Suspend grid persistence due to credential daemon outage.
+     * @param {string} reason - Reason for suspension
+     * @returns {void}
+     */
+    _suspendGridPersistenceForCredentialOutage(reason: any): void;
+    /**
+     * Resume grid persistence after credential daemon recovery.
+     * @param {string} reason - Reason for resuming
+     * @returns {void}
+     */
+    _resumeGridPersistenceAfterCredentialRecovery(reason: any): void;
+    /**
+     * Ensure the credential daemon is writable before broadcasting operations.
+     * @param {string} [contextLabel='write batch'] - Context label for logging
+     * @returns {Promise<void>}
+     * @throws {Error} With code CREDENTIAL_DAEMON_UNAVAILABLE if daemon is down
+     */
+    _ensureCredentialDaemonWritable(contextLabel?: string): Promise<void>;
+    /**
+     * Check if an error is related to credential daemon unavailability.
+     * @param {Error|*} err - Error to check
+     * @returns {boolean}
+     */
+    _isCredentialDaemonError(err: any): boolean;
+    /**
+     * Run state recovery after credential daemon is restored.
+     * @returns {Promise<void>}
+     */
+    _runCredentialRecoveryAfterDaemonRestored(): Promise<void>;
+    /**
+     * Start the credential daemon watchdog interval that periodically probes daemon health.
+     * @returns {void}
+     */
+    _setupCredentialDaemonWatchdogInterval(): void;
+    /**
+     * Stop the credential daemon watchdog interval.
+     * @returns {void}
+     */
+    _stopCredentialDaemonWatchdogInterval(): void;
+    /**
+     * Executes a batch of order operations on the blockchain using COW pattern.
+     * Master grid is only updated after successful blockchain confirmation.
+     * @param {Object} rebalanceResult - COW result containing workingGrid + actions.
+     * @returns {Promise<Object>} The batch result.
+     */
+    updateOrdersOnChainBatch(rebalanceResult: any): Promise<any>;
+    /**
+     * Converts simple plan payloads (place/update/rotate/cancel) into a COW batch.
+     * Used by spread/divergence maintenance and bootstrap helpers.
+     * @param {Object|Array} plan - Plan object or array of ordersToPlace
+     * @returns {Promise<Object>} Batch execution result
+     */
+    updateOrdersOnChainPlan(plan: any): Promise<any>;
+    /**
+     * Build COW actions array from a simple plan object or array of ordersToPlace.
+     * @param {Object|Array} plan - Plan object with ordersToPlace/ordersToRotate/ordersToUpdate/ordersToCancel, or array of ordersToPlace
+     * @returns {Array<{type: string, id: string, order?: Object, orderId?: string, newSize?: number, newPrice?: number, newGridId?: string}>}
+     */
+    _buildActionsFromPlan(plan: any): any[];
+    /**
+     * Build a COW result object (workingGrid + actions) from a simple plan.
+     * @param {Object|Array} plan - Plan object or array of ordersToPlace
+     * @returns {{workingGrid: import('./types').WorkingGrid, workingIndexes: Object, workingBoundary: number, actions: Array}}
+     */
+    _buildCowResultFromPlan(plan: any): {
+        workingGrid: any;
+        workingIndexes: any;
+        workingBoundary: any;
+        actions: any[];
+    };
+    /**
+     * Restore skipped update slots in the working grid to master state.
+     * @param {import('./types').WorkingGrid} workingGrid - Working grid to restore slots into
+     * @param {Set<string>} skippedSlotIds - Set of slot IDs that were skipped
+     * @param {number} [skippedCount=0] - Count of skipped actions for logging
+     * @returns {void}
+     */
+    _restoreSkippedUpdateSlotsInWorkingGrid(workingGrid: any, skippedSlotIds: any, skippedCount?: number): void;
+    /**
+     * COW broadcast: Execute blockchain operations and commit working grid on success.
+     * Master grid is ONLY updated after successful blockchain confirmation.
+     * @param {Object} cowResult - COW result with workingGrid, actions, etc.
+     * @returns {Promise<Object>} The batch result.
+     * @private
+     */
+    _updateOrdersOnChainBatchCOW(cowResult: any): Promise<any>;
+    /**
+     * Process results from batch transaction execution.
+     * Updates order state, synchronizes with chain, and deducts BTS fees.
+     * @param {Object} result - Transaction result from executeBatch
+     * @param {Array} opContexts - Operation context array with operation metadata (must be 1:1 with result.operation_results)
+     * @returns {Object} Result with { executed: boolean, hadRotation: boolean }
+     * @private
+     */
+    _processBatchResults(result: any, opContexts: any): Promise<{
+        executed: boolean;
+        hadRotation: boolean;
+        updateOperationCount: number;
+    }>;
+    /**
+     * Perform grid recalculation triggered by trigger file.
+     * Reloads config from disk, recalculates grid, resets funds, and removes trigger file.
+     * Must be called with _fillProcessingLock already held.
+     * @param {Object} [options] - Optional configuration for grid resync.
+     * @returns {Promise<boolean>} True if resync succeeded
+     * @private
+     */
+    _performGridResync(options?: {}): Promise<any>;
+    /**
+     * Handle any pending trigger file reset at startup.
+     * This is called FIRST during startup before any grid operations.
+     * @returns {Promise<boolean>} True if trigger reset completed successfully, false otherwise
+     * @private
+     */
+    _handlePendingTriggerReset(): Promise<any>;
+    /**
+     * Setup trigger file detection for grid reset.
+     * Monitors the trigger file and performs grid resync when it's created.
+     * @private
+     */
+    _setupTriggerFileDetection(): Promise<any>;
+    /**
+     * Starts the bot's operation.
+     * @param {string|Object|Buffer} [vaultSecret=null] - The unlock secret.
+     * @returns {Promise<void>}
+     */
+    start(vaultSecret?: any): Promise<void>;
+    /**
+     * Start bot with a pre-decrypted private key.
+     * Alternative to start(vaultSecret) when the signing secret is already available.
+     * @param {string|Object} privateKey - Pre-decrypted private key or daemon signing token
+     * @returns {Promise<void>}
+     */
+    startWithPrivateKey(privateKey: any): Promise<void>;
+    /**
+     * Common startup sequence logic shared between start() and startWithPrivateKey().
+     * @private
+     */
+    _runStartupSequence(): Promise<void>;
+    /**
+     * Perform periodic grid checks: fund thresholds, spread condition, grid health.
+     * Called by the periodic blockchain fetch interval to check if grid needs updates.
+     *
+     * IMPORTANT: This method MUST only be called from within _fillProcessingLock.acquire()
+     * (specifically from _setupBlockchainFetchInterval). It passes fillLockAlreadyHeld
+     * to avoid deadlock with _consumeFillQueue which uses the same lock ordering.
+     *
+     * @private
+     */
+    _performPeriodicGridChecks(): Promise<any>;
+    _isOpenOrdersSyncLoopEnabled(): any;
+    /**
+     * Start the open-orders watchdog sync loop.
+     * Uses fill lock contention checks to avoid competing with fill processing.
+     * @private
+     */
+    _startOpenOrdersSyncLoop(): any;
+    /**
+     * Stop the open-orders watchdog sync loop.
+     * @private
+     */
+    _stopOpenOrdersSyncLoop(): Promise<any>;
+    /**
+     * Set up periodic blockchain account balance fetch interval.
+     * Fetches available funds at regular intervals to keep blockchain variables up-to-date.
+     * @private
+     */
+    _setupBlockchainFetchInterval(): any;
+    /**
+     * Stop the periodic blockchain fetch interval.
+     * @private
+     */
+    _stopBlockchainFetchInterval(): any;
+    _releaseMarketAdapterRuntime(context?: string): Promise<any>;
+    /**
+     * Get or create the credit runtime for debt policy management.
+     * @returns {import('./credit_runtime').CreditRuntime|null}
+     */
+    _getCreditRuntime(): any;
+    /**
+     * Set up the credit runtime by loading its persisted state.
+     * @returns {Promise<import('./credit_runtime').CreditRuntime|null>}
+     */
+    _setupCreditRuntime(): Promise<any>;
+    /**
+     * Refresh credit runtime state from chain and sync internal tracking.
+     * @returns {Promise<void>}
+     */
+    _refreshAndSyncCreditRuntime(): Promise<void>;
+    /**
+     * Run credit runtime maintenance (deal checks, collateral monitoring).
+     * @param {string} [context='periodic'] - Maintenance context
+     * @param {Object} [options={}] - Maintenance options
+     * @returns {Promise<*>} Maintenance result from runtime
+     */
+    _runCreditRuntimeMaintenance(context?: string, options?: {}): Promise<any>;
+    /**
+     * Start the credit deal watchdog interval.
+     * @returns {void}
+     */
+    _setupCreditWatchdogInterval(): void;
+    /**
+     * Stop the credit deal watchdog interval.
+     * @returns {void}
+     */
+    _stopCreditWatchdogInterval(): void;
+    requestGridReset(reason?: string, options?: {
+        refreshCenterPrice?: boolean;
+        fillLockAlreadyHeld?: boolean;
+        [key: string]: any;
+    }): Promise<any>;
+    _wireStructuralGridResyncRequest(): void;
+    /**
+     * Get current metrics for monitoring and debugging.
+     * @returns {Object} Metrics snapshot
+     */
+    getMetrics(): any;
+    /**
+     * Execute grid maintenance checks in strict order with pipeline consensus.
+     *
+     * CRITICAL DESIGN: All structural grid modifications are deferred until the pipeline
+     * is empty to prevent "race-to-resize" conditions where the bot attempts to reallocate
+     * temporary fund surpluses from filled orders before their counter-orders/rotations
+     * are placed.
+     *
+     * MAINTENANCE SEQUENCE:
+     * 1. Fund Recalculation (ALWAYS) - Updates internal fund metrics
+     * 2. Pipeline Check (GATE) - Verifies no pending operations
+     * 3. Health Check (IF IDLE) - Detects and cleans dust orders
+     * 4. Divergence Detection (IF IDLE) - Identifies structural mismatches
+     * 5. Grid Resizing (IF IDLE) - Applies size corrections on-chain
+     * 6. Spread Correction (IF IDLE) - Corrects spread after structural work completes
+     *
+     * WHY PIPELINE CONSENSUS MATTERS:
+     * - After a fill, funds temporarily show a "surplus" from the filled order
+     * - If grid maintenance runs immediately, it sees the surplus and triggers a resize
+     * - The resize attempts to allocate funds that will be consumed by pending counter-orders
+     * - This causes cascading trades, fund accounting errors, and grid instability
+     * - Solution: Wait for pipeline to empty (all rotations placed) before resizing
+     *
+     * TIMEOUT SAFETY:
+     * - clearStalePipelineOperations() clears stuck operations after 5-minute timeout
+     * - Called before pipeline check to prevent indefinite blocking
+     * - See manager.clearStalePipelineOperations() for details
+     *
+     * @param {Object} context - Maintenance context for logging.
+     * @private
+     */
+    _executeMaintenanceLogic(context: any): Promise<any>;
+    /**
+     * Cancel dust partial orders immediately — no maps, no timers, no delay.
+     * Each dust order is cancelled on chain and its slot rotated through the
+     * synthetic-fill pipeline.
+     * @param {{ buy: Array, sell: Array, fillLockAlreadyHeld?: boolean }} options
+     * @returns {Promise<{cancelledCount: number, batchResult: {aborted: boolean}|null}>}
+     * @private
+     */
+    _cancelDustOrders({ buy: buyDust, sell: sellDust, fillLockAlreadyHeld }?: {
+        buy?: any[];
+        sell?: any[];
+        fillLockAlreadyHeld?: boolean;
+    }): Promise<any>;
+    /**
+     * Set up the periodic dust health check interval.
+     * Catches partials below the dust threshold that were missed by the post-fill
+     * pipeline (e.g. from a prior bot lifetime after crash/restart).
+     * Cancels dust immediately inside the fill-processing lock.
+     * @private
+     */
+    _setupDustHealthCheckInterval(): void;
+    /**
+     * Perform grid maintenance: fund thresholds, spread condition, grid health, divergence.
+     * Consolidates maintenance checks used during startup, periodic updates, and post-fill.
+     *
+     * ENTRY POINTS:
+     * 1. Startup (line ~681): After grid initialization, ensures grid is healthy
+     * 2. Periodic (line ~2682): Every BLOCKCHAIN_FETCH_INTERVAL_MIN (default 240 min)
+     * 3. Post-Fill (line ~1059): After order fills are rotated
+     *
+     * PIPELINE PROTECTION:
+     * All maintenance operations inside _executeMaintenanceLogic respect isPipelineEmpty().
+     * This prevents grid modifications while fills/rotations/corrections are pending.
+     * See _executeMaintenanceLogic documentation for detailed rationale.
+     *
+     * LOCK ORDERING:
+     * - Canonical order: _fillProcessingLock → _divergenceLock
+     * - This function handles lock acquisition based on fillLockAlreadyHeld parameter
+     * - When called from post-fill context, fill lock is already held
+     * - When called from periodic context, both locks must be acquired
+     * - Matches the order used in _consumeFillQueue to prevent deadlocks
+     *
+     * @param {string} context - Maintenance context for logging (e.g. 'startup', 'periodic', 'post-fill')
+     * @param {Object} options - Maintenance options
+     * @private
+     */
+    _runGridMaintenance(context?: string, options?: {}): Promise<any>;
+    /**
+     * Gracefully shutdown the bot.
+     * Waits for current fill processing to complete, persists state, and stops intervals.
+     * Idempotent: subsequent calls await the first shutdown so duplicate cleanup
+     * invocations do not run the body twice or exit before persistence finishes.
+     * @returns {Promise<void>}
+     */
+    shutdown(): Promise<void>;
+    _shutdownImpl(): Promise<void>;
+}
+declare const _default: typeof DEXBot & {
+    normalizeBotEntry: any;
+};
+export = _default;
+//# sourceMappingURL=dexbot_class.d.ts.map