# Configuration

## Reference

### Configuration Overview

The Nekuti Matching Engine is configured through a series of feature blocks, each controlling specific aspects of the engine's behavior. Most settings are hard-coded as part of each client's optimized software package. Settings can be changed or exposed as runtime configuration parameters on request. Below is a comprehensive reference of all configuration options.

### Environment Variables

The following environment variables can be used to control specific engine behaviors:

#### THREAD_MODEL
Controls the engine's threading behavior.
- Values: `dev-laptop` | `production`
- Default: `production`
- **Note**: The `dev-laptop` setting is for testing purposes only
  - `production`: Runs multi-threaded and optimizes for latency by utilizing 4 CPU cores
  - `dev-laptop`: Runs single-threaded without CPU core optimization

#### DISABLE_PERSISTENCE
Controls persistence behavior of the engine.
- Values: `yes` | `no`
- Default: `no`
- **Note**: Setting to `yes` is for testing purposes only
  - Starts engine with no persisted state
  - Prevents command persistence and snapshot generation
  - Enables runtime exchange data wiping without process restart

#### ABANDONMENT_TIMEOUT_MS
Configures recovery behavior for abandoned command files after hard exits.
- Values: Time in milliseconds
- Default: Not set
- Enables recovery of command files from failed instances
- Waits specified duration and verifies no writes occurred before takeover
- See [Multiple Instance Protection and Recovery](../deployment/persistence#multiple-instance-protection-and-recovery) for detailed documentation

#### SUSPEND_ON_RESTART
There are two modes of suspension: **full suspension** and **post only**. Please refer to the [suspension documentation](../suspension).
This variable puts the engine in one of these modes and provides a duration after which the engine automatically unsuspends.
The variable expects this format: (suspend|postonly):(duration_in_milliseconds).

Examples of configurations:
- `suspend:10000` (suspended for 10 seconds on restart)
- `postonly:30000` (post-only for 30 seconds on restart)

### Core Features

#### Clock
Controls the temporal granularity of the system.
```yaml
Clock[tickFrequency=PT0.01S]
```
- `tickFrequency`: Maximum duration between clock tick events (Shown in ISO-8601 duration format)

#### Engine
Defines core engine behavior parameters.
```yaml
Engine[commandQueueCapacity=1000000]
```
- `commandQueueCapacity`: Maximum number of pending commands before backpressure is applied
  - When queue is full, REST calls will block until capacity becomes available

#### Persistence
Controls how the engine persists data.
```yaml
Persistence(
    path=persistence/,
    archivePath=persistence/archived,
    commandFileBaseName=commandLog,
    fileSystem=NativeFilesystem,
    incompatibleCommandFilePolicy=FatalError
)
```
- `path`: Directory for active persistence files
- `archivePath`: Directory for archived command and snapshot files
- `commandFileBaseName`: Base name for command log files
- `fileSystem`: Filesystem implementation to use
- `incompatibleCommandFilePolicy`: How to handle incompatible command files

#### CommandFileReading
```yaml
CommandFileReading[
    preferredReadChunkSize=524288,
    shouldDropSubscriptionsFromPersistedState=true
]
```
- `preferredReadChunkSize`: Optimal chunk size for file reads (in bytes)
- `shouldDropSubscriptionsFromPersistedState`: Whether to maintain subscriptions across restarts. Always true

#### CommandFileWriting
```yaml
CommandFileWriting[
    preferredWriteChunkSize=2097152,
    fileMaxSize=1073741824
]
```
- `preferredWriteChunkSize`: Optimal chunk size for file writes (in bytes)
- `fileMaxSize`: Maximum size of command files before rolling over (in bytes)

### Data Management

#### DefaultMessageStore
```yaml
DefaultMessageStore[
    maxHoldingPeriod=PT24H,
    purgeInterval=PT21M39.827S
]
```
The default message store is created only when the engine starts from zero with nothing persisted.
- `maxHoldingPeriod`: How long messages are retained
- `purgeInterval`: Frequency of message purging operations

#### OrderPurging
```yaml
OrderPurging[
    orderPurgeInterval=PT9M59S,
    orderPurgeAge=PT10M
]
```
- `orderPurgeInterval`: Frequency of order purging operations
- `orderPurgeAge`: Age threshold for purging final-state orders
  - Affects orders in filled, canceled, or expired states
  - Purged orders will return `UnknownOrderId` or `UnknownClOrdId` on amendment attempts

### System Optimization

#### PreventRuntimeAllocations
```yaml
PreventRuntimeAllocations[]
```
Ensures fixed heap size by asserting starting and maximum heap sizes are identical.

#### ReadModels
```yaml
ReadModels[includeOrders=true]
```
- `includeOrders`: Enables historical order querying
  - Required for querying final-state orders
  - Orders become unqueryable immediately upon reaching final state if disabled

#### SnapshotCommandGeneration
```yaml
SnapshotCommandGeneration[snapshotInterval=PT8M7.349S]
```
- `snapshotInterval`: Frequency of snapshot generation

#### Logging
```yaml
Logging[level=info, writingThread=true]
```
- `level`: Log level (info)
- `writingThread`: Whether to use a background thread for log output

### System Constants

These values are hardcoded and cannot be currently be configured. Future updates may include the ability to modify these settings:

- **Market Order Slippage Limit**: 5%
  - Market orders will not fill beyond 5% from best bid/ask
  - Order is partially filled and then canceled
- **Dense Levels**: 1 million
  - Innermost price levels kept in dense array
  - Optimizes performance at cost of memory usage