Rust edition: this page follows the live DeepWiki structure but treats the current Rust crates as implementation authority. Non-Rust surfaces are identified at their boundary and are not presented as Rust APIs.

Cache and State Management

Relevant Rust source files

• crates/common/src/cache/mod.rs
• crates/infrastructure/src/redis/cache.rs
• crates/infrastructure/src/sql/cache.rs

The Cache is the central in-memory database for all trading system state. It stores instruments, orders, positions, accounts, and market data in indexed structures for fast O(1) lookups. User code accesses the cache through a read-only CacheFacade, while system engines have full read/write access. The cache can optionally persist state to Redis or PostgreSQL for recovery across restarts.

This page documents:

• Cache architecture and component responsibilities.
• Initialization and database backing configuration.
• State persistence and recovery mechanisms.
• Integration patterns with system engines.
• Query methods and access patterns.

Cache Architecture

The Rust cache subsystem provides fast in-memory state, secondary indexes, and an optional CacheDatabaseAdapter durability boundary.

Cache Architecture Diagram

Component responsibilities:

• Cache ( ): Full read/write interface for storing and retrieving all trading state. It maintains in-memory dictionaries (or AHashMap in Rust) indexed by various keys for fast O(1) lookups.
• CacheFacade ( ): Read-only wrapper around Cache exposed to user code (strategies/actors) preventing accidental state modification.
• CacheDatabaseAdapter ( ): Bridges the Cache to persistent storage. It handles serialization and routes operations to specific database implementations.
• RedisCacheDatabase ( ): High-performance Redis implementation using an asynchronous write task to avoid blocking the main trading loop.
• SQL Persistence ( ): Provides relational backing via PostgreSQL, including complex schema support for orders, positions, and accounts.

Core Cache Implementation

The Cache maintains multiple internal data structures to provide comprehensive state management.

Internal Storage Structures

The following tables describe the primary storage dictionaries maintained within the Cache class

Storage Member (Py)	Storage Member (RS)	Key Type	Value Type	Description
_instruments	instruments	InstrumentId	Instrument	Trading instrument definitions.
_orders	orders	ClientOrderId	Order	All orders indexed by client ID.
_positions	positions	PositionId	Position	Open and closed positions.
_accounts	accounts	AccountId	Account	Balances and margin state.
_quote_ticks	quotes	InstrumentId	VecDeque[QuoteTick]	FIFO buffer of recent quotes.
_trade_ticks	trades	InstrumentId	VecDeque[TradeTick]	FIFO buffer of recent trades.
_bars	bars	BarType	VecDeque[Bar]	FIFO buffer of recent OHLCV bars.
_order_books	books	InstrumentId	OrderBook	Current L1/L2/L3 market depth.

Indexing and Fast Lookups

To support queries without full scans, the Rust cache maintains secondary indexes through CacheIndex and the collections owned by Cache:

• _index_venue_orders: Maps a Venue to a set of ClientOrderId.
• _index_venue_order_ids: Maps a VenueOrderId (from the exchange) to the internal ClientOrderId.
• _index_order_position: Maps a ClientOrderId to the PositionId it belongs to.
• _index_strategy_positions: Maps a StrategyId to its associated PositionId set.

Persistence and Database Backing

NautilusTrader supports optional persistent backing to allow state recovery after a system restart. This is critical for live trading.

Redis Implementation Architecture

The RedisCacheDatabase in Rust uses a dual-connection architecture to maximize performance :

1. READ Connection (self.con): Synchronous queries (keys, read, load_all) for loading state during startup.
2. WRITE Connection: Managed by a background task on the Nautilus runtime. Write operations (insert, update, delete, flush) are sent via an unbounded tokio::sync::mpsc channel

Redis Persistence Flow

PostgreSQL Support

The system also supports PostgreSQL via CachePostgresAdapter. The schema includes specialized tables for accounts, instruments, orders, and positions This implementation is used for robust, transactional state persistence and is supported by the Nautilus CLI for database management.

Query Interface and Facade

The CacheFacade provides the public API for strategies and actors. It ensures that user-level components cannot modify the global state directly.

Key Query Methods

The Cache implementation (and its facade) provides comprehensive methods for retrieving state :

• Market Data:

  • quote_tick(instrument_id, index=0): Returns the Nth most recent quote.
  • bars(bar_type): Returns the full list of cached bars for a type.
  • price(instrument_id, price_type): Returns the latest price (Bid, Ask, Last, etc.).

• Execution State:

  • orders_open(strategy_id=...): Returns all currently active orders for a strategy.
  • positions_open(instrument_id=...): Returns all open positions for an instrument.
  • account(account_id): Returns the current balance and margin for an account.

Memory Management

The cache prevents memory exhaustion through configurable capacities :

• tick_capacity: Limits the number of ticks stored per instrument.
• bar_capacity: Limits the number of bars stored per bar type. When capacity is reached, the oldest data is evicted from the internal storage (FIFO behavior).

State Recovery Workflow

State recovery is triggered during system initialization if a database is configured.

Code Entity Space: Recovery Flow

1. Trader.load(): Orchestrates the loading of all system components.
2. Cache.cache_all(): Triggers loading of all categories (Instruments, Orders, Positions, Accounts)
3. CacheDatabaseAdapter.load(): Uses the configured Serializer to turn database bytes back into Rust objects
4. Cache.build_index(): Reconstructs the secondary indexes (like _index_venue_orders) from the loaded primary data