Persistence System
Position Recovery
The trading engine includes a built-in persistence layer designed to survive crashes, restarts, and unexpected shutdowns without losing critical trading state.
All active trading data is automatically stored on disk using the custom PersistentMap component.
The system persistently stores:
- •Active positions
- •Pending orders
- •Symbol trading controls
- •Risk management states
When the bot restarts:
- 1.Persistent files are automatically loaded.
- 2.Previous trading state is restored into memory.
- 3.Active positions continue to be monitored immediately.
- 4.Pending orders continue tracking exchange execution status.
- 5.Risk controls remain preserved.
This allows the bot to continue operation without manual intervention after interruptions.
Purpose:
- •Prevent losing track of open positions
- •Preserve trading continuity
- •Maintain accurate risk management state
- •Avoid duplicate entries after restart
Position Recovery & State Storage Flow
Interactive architecture visualizer showing state persistence and automatic startup recovery
1. Active Engine Write-Back
Trading Engine continuously pushes updated positions, orders, and symbol rules to the persistent async queue.
Database Structure
The persistence layer uses lightweight local file-based storage built on top of Python pickle serialization.
Each persistent structure is stored in an independent file:
- •
active_positions.pkl - •
pending_orders.pkl - •
symbol_controls.pkl
The architecture is intentionally minimalistic and optimized for low-latency trading systems.
Database Structure & Schema Inspector
Select a file to inspect stored attributes, field types, and persistence purpose
Stores currently open trades and position tracking parameters required for automated management.
| Field Name | Type | Sample Value | Description |
|---|---|---|---|
| symbol | str | "BTCUSDT" | Trading pair identifier |
| side | str | "LONG" | Position direction |
| qty | float | 0.45 | Position contract size |
| entry_price | float | 64250.50 | Average entry price |
| stop_loss | float | 63100.00 | Active stop loss trigger price |
| take_profit | float | 66500.00 | Target take profit price |
| trailing_stop | bool | true | Trailing stop activation flag |
| timestamp | int | 1722345600 | Position creation timestamp |
- •Resume position management instantly after bot restart
- •Continue automated stop loss and trailing stop calculations
- •Preserve exact entry prices and execution state across crashes
Active Positions
Stores currently open trades.
Each position contains:
- •Trading symbol
- •Position side
- •Quantity
- •Entry price
- •Stop loss price
- •Take profit price
- •Trailing stop status
- •Timestamp
Purpose:
- •Resume position management after restart
- •Continue stop loss and trailing logic
- •Preserve exact entry state
Pending Orders
Stores exchange orders waiting for execution confirmation.
Each order contains:
- •Symbol
- •Order side
- •Order type
- •Quantity
- •Exchange order ID
- •Current status
Purpose:
- •Prevent duplicate orders
- •Continue monitoring exchange execution state
- •Recover unfinished order flows
Symbol Controls
Stores runtime trading permissions and protection states.
Each symbol may contain:
- •Buying enabled status
- •Selling enabled status
- •Disable reasons
- •Risk lock states
Purpose:
- •Preserve automated risk restrictions
- •Prevent accidental reactivation after restart
Crash Recovery Logic
The persistence system is designed for automatic recovery during:
- •Process crashes
- •Server restarts
- •VPS failures
- •Power outages
- •Unexpected exceptions
Asynchronous Persistence
All writes are processed in a dedicated background thread.
Features:
- •Non-blocking trading execution
- •Continuous automatic saving
- •Queue-based save scheduling
Purpose:
- •Prevent trading delays caused by disk operations.
Atomic File Saving
The system uses atomic file replacement for maximum data safety.
Save flow:
- 1.Data is written into a temporary .tmp file.
- 2.Temporary file is fully completed.
- 3.File is atomically renamed into the final persistence file.
Purpose:
- •Prevent corrupted persistence files during crashes or interrupted writes.
Atomic File Saving & Crash Safety Visualizer
Interactive simulator of temporary file creation, validation, and atomic OS rename
Updated engine state is written to a separate temporary file on disk without touching the live file.
The persistence layer verifies checksum and payload completeness before proceeding.
The OS atomically replaces active_positions.pkl with the validated .tmp file in a single operation.
Atomic file replacement guarantees that disk storage is either 100% updated or unchanged. Partial or corrupted saves are physically impossible.
Save Deduplication
The persistence queue automatically removes outdated save requests.
Behavior:
- •Only the newest state is persisted.
- •Redundant disk writes are skipped.
Purpose:
- •Reduce disk usage
- •Improve performance under heavy update frequency
Automatic State Reload
During startup:
- 1.Persistence files are detected.
- 2.Serialized objects are loaded back into memory.
- 3.Trading engine resumes monitoring immediately.
If persistence files do not exist:
- •New clean storage is automatically initialized.
Thread Safety
The persistence engine uses internal synchronization locks during save operations.
Features:
- •Concurrent-safe writes
- •Safe multi-threaded access
- •Protected file replacement
Purpose:
- •Ensure consistency between trading threads and persistence layer
Graceful Shutdown Protection
Before shutdown:
- 1.Final save operation is forced.
- 2.Save queue is flushed completely.
- 3.Background persistence thread is stopped safely.
Purpose:
- •Guarantee latest trading state is written to disk before exit.