Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.quanux.org/llms.txt

Use this file to discover all available pages before exploring further.

quanuxctl risk gives you a stateless control surface over the QuanuX risk plane. It never connects directly to a database or interrupts live C++ execution threads via RPC. Instead, it communicates exclusively through the CNATS JetStream KV store, where the running RiskKernel instances on each node listen asynchronously for updates and apply them to their local RAM state without pausing the execution loop.

​
Synopsis

quanuxctl risk <command> [arguments]

​
The Sovereign Sentinel

Before exploring the commands, it helps to understand what you are controlling. Risk enforcement in QuanuX is handled by the Sovereign Sentinel — an independent C++ binary pinned to Core 5 of the execution CPU. The Sentinel runs a bare-metal loop with no OS context switching, enforcing risk rules via hardware cache operations at 11.33 nanoseconds. The Sentinel enforces the following rules continuously:
RuleTrigger condition
Stale tick (drift)TSC heartbeat delta exceeds 3,000,000 cycles (~1ms at 3GHz). Indicates stale market data.
Notional breachabs_pos × best_bid exceeds the configured hard cap (e.g., $5M).
Order stormorders_fired count climbs faster than the allocated burst per second.
Partial fillExecutionState::PARTIAL is registered. Sentinel replaces max_position_limit_ with the exact executed quantity, allowing hedging exits but blocking further accumulation.
When the Sentinel detects a violation, it asserts a LOCK BTS (Bit Test and Set) instruction on the risk_interlock byte in the shared L3 cache. The Spreader on Core 3 detects this within ~59ns and enters STATE_HALT.
STATE_HALT is a terminal state initiated by hardware-level interlock. It cannot be overridden by software configuration. To recover, you must investigate the root cause of the Sentinel violation, resolve the position or data condition that triggered it, and restart the engine via systemctl restart quanux-engine.

​
Commands

​
view-state

Subscribes to the NATS JetStream KV store (Bucket: RISK_STATE) and returns the current real-time aggregated global notional exposure. 
quanuxctl risk view-state
This command reads global.notional.exposure from the KV store. It proves global state without locking any C++ hot-path memory or querying a database. Example: 
$ quanuxctl risk view-state

​
update-cap

Publishes a new daily notional cap limit to the NATS subject quanux.control.risk.cap. Running RiskKernel instances subscribe to this subject on asynchronous background threads and apply the new cap to their daily_notional_cap_ variable without pausing the primary execution loop. 
quanuxctl risk update-cap <new_cap_value>
​
new_cap_value
int64
required
The new daily notional cap as an int64 implied 2-decimal scalar. Multiply the dollar value by 100 to express cents. For example, 1,000,000.00is‘100000000‘and1,000,000.00 is `100000000` and 25,000,000.00 is 2500000000.
Example — Set the global notional limit to $25,000,000: 
quanuxctl risk update-cap 2500000000
Cap updates propagate to all active RiskKernel instances across the mesh asynchronously. There is no synchronous acknowledgement — the update is durable in JetStream and nodes will apply it when they process the message. Allow a few seconds before expecting the new cap to be reflected in view-state.

​
force-hydrate

Commands a specific node to drop its is_hot_ flag to false, suspend local trading, perform a blocking thread read from the JetStream KV store to re-seed its RAM matrix, verify the SHA-256 hash of the global state, and then restore execution. 
quanuxctl risk force-hydrate <node_id>
​
node_id
string
required
The target node identifier (e.g., SFO-EXEC-01, LON-EXEC-02). Node IDs correspond to the names in your QuanuX node inventory.
Use force-hydrate in the following scenarios:
  • After a STONITH fencing event, when a standby node has been promoted and needs to synchronize its local RAM matrix with the current global JetStream record before resuming live trading
  • When you suspect a node’s local risk state has drifted from the global consensus due to a network partition or restart
Example — Re-hydrate a newly promoted node in London after a STONITH event: 
quanuxctl risk force-hydrate LON-EXEC-02

​
The Ritchie FSM states

The QuanuX execution engine is governed by the Ritchie Finite State Machine. Risk events transition the engine through these states:
StateDescription
STATE_VOIDInitial state. Engine has not yet received market data or confirmed connectivity.
Running statesNormal execution. The Sentinel continuously monitors the risk rules above.
STATE_RECOVERYTransitional state. Engine encountered a recoverable condition and is re-synchronizing state.
STATE_HALTTerminal halted state. Triggered by a Sentinel violation. Trading is suspended entirely.
You can observe FSM state transitions in real time by subscribing to the NATS mesh: nats sub "quanux.telemetry.fsm.*". Every state change is published as a durable JetStream message for forensic reconstruction.

​
Examples

$ quanuxctl risk view-state

​
Architecture note

The risk plane is intentionally severed from the execution plane at the hardware level. The Sentinel binary runs on Core 5. The Spreader runs on Core 3. They share state only through a 64-byte L3 cache “Dead Drop.” No syscall, mutex, or OS scheduler is involved in the risk check itself — only a LOCK BTS assembly instruction that the Spreader detects within one L3 cache bus synchronization cycle. This is why the Sentinel cannot be disabled in software: it does not operate through software.