DOLPHIN/nautilus_dolphin/DOLPHIN_SYSTEM_ENCYCLOPEDIA.md

# DOLPHIN NG HD - Nautilus Trading System Specification

**Version:** 4.1.0-MetaAdaptive
**Date:** 2026-03-03
**Status:** Frozen & Fully Integrated

---

## 1. System Abstract

DOLPHIN NG HD (Next Generation High-Definition) is a fully algorithmic, Short-biased mean-reversion and divergence-trading engine. Originally conceived as a standalone Python research engine, it has now been meticulously ported to the **Nautilus Trader** event-driven architecture, enabling HFT-grade execution, microseconds-scale order placement, and rigorous temporal safety.

At its core, the system listens to 512-bit Flint-computed eigenvalues generated by the `correlation_arb512` core, extracting macro-market entropy, local volatility, and orderbook micro-structure to precisely time trade entries and continuously throttle internal leverage boundaries.

---

## 2. The 7-Layer Alpha Engine (nautilus_dolphin/nautilus/alpha_orchestrator.py)

The Alpha Engine manages trade lifecycle and sizing through 7 strict gating layers.

### **Layer 1: Primary Signal Transducer (`vel_div`)**
- **Metric:** `lambda_max_velocity` (referred to as `vel_div`)
- **Threshold:** `<= -0.02` (configurable)
- **Function:** Identifies accelerating breakdowns in the macro eigenvalue spectrum. Only signals breaching the threshold proceed to Layer 2.

### **Layer 2: Volatility Regime Gate (`volatility_detector.py`)**
- **Metric:** 50-bar rolling standard deviation of BTC/USDT price returns.
- **Bootstrapping:** The first 100 bars of the day are used to establish `p20`, `p40`, `p60`, and `p80` percentiles.
- **Rule:** The system **only trades** if the current 50-bar volatility exceeds the `p60` threshold (defined as "Elevated" or "High" volatility).

### **Layer 3: Instrument Responsiveness Profile (IRP)**
- **Metric:** Asset-specific alignment score.
- **Rule:** Rejects assets with an IRP alignment `< 0.45`. Filters out mathematically un-responsive alts (e.g., stablecoins or broken correlation pairs).

### **Layer 4: Cubic-Convex Dynamic Leverage**
- **Math:** 
  `strength_score = max(0, min(1, (-0.02 - vel_div) / (-0.02 - (-0.05))))`
  `base_leverage = min_lev + strength_score^3 * (max_lev - min_lev)`
- **Function:** Exponentially rewards "perfect" signals (`vel_div <= -0.05`) while heavily clamping mediocre signals (`vel_div ~= -0.02`).

### **Layer 5: Historical Alpha Multipliers (The "Meta" Adjusters)**
Three independent momentum components multiply against the allocated capital fraction (cap at 20%):
1. **Bucket Boost (`bb`):** Tracks win-rates across 4 strength archetypes. (WR > 60% yields 1.3x, WR < 40% yields 0.7x).
2. **Streak Multiplier (`sm`):** Examines the last 5 trades. (4+ losses drops size to 0.5x, 1 or fewer losses boosts to 1.1x).
3. **Trend Multiplier (`tm`):** Looks back 10 bars on `vel_div`. Falling trend = 1.3x, recovering trend = 0.7x.

### **Layer 6: Direction Confirmation (DC)**
- **Metric:** 7-bar trailing return on BTC/USDT.
- **Rule:** If price drops by >0.75bps, the market pressure confirms our SHORT intent -> Apply `dc_leverage_boost` (currently 1.0x). If price rises by >0.75bps, it contradicts -> `HARD REJECT` (skip trade).

### **Layer 7: Exit Management (`alpha_exit_manager.py`)**
- **Take-Profit:** Fixed 99 bps (0.99%) gross limit exit.
- **Stop-Loss:** **Time-based** only. Trades are forcibly liquidated after 120 5-second bars (10 minutes) if they have not reached the TP, bounding the fat-tail variance natively.

CRITICAL, ALSO:
- (FORK files for any testing): We *should* use all the advanced "tail loss"-avoidance subsystems we now HAVE in place (ACBv6, definitely, ExF [External Factors system] definitely, MC-Forewaring maybe, EsoF [Esoteric Factors system] maybe: It has proven - not yet to statistical significance - to *severely and effectively clip* negative tail events) to DINAMICALLY ADJUST max_hold (the "hard wall") and tp_bps to *maximize returns* WHILE avoiding the taill events, in the specific sense, while VERY carefully, sensitively and intelligently adjusting in-trade (hold, tp, sl and all) according to lilely tail-risk. WE CAN DO this. This should heavily increase profitability while not increasing tail risk.-

---

## 3. Adaptive Circuit Breaker (ACB) v6: Inverse Meta-Boost

The ACB (`adaptive_circuit_breaker.py`) serves as the ultimate governor of system-wide Leverage ceilings, assessing macroeconomic entropy directly from the Daily Context.

IMPORTANT NOTE: Following research, ACB is now "sub-day"-resolution, it uses per-factor (FR, DVOL, F&G, Taker, et al.) timings and a *cache* system to have as-close-to-realtime granularity as possible. This was tested to MUCH improve results. THIS sub-day feature MAY OR MAY NOT HAVE BEEN IMPLEMENTED, and needs to either be validated as done *OR* extant research needs consulted to *indeed immplement* - prototype code for the needed sub-day mechanics SHOULD exist.-

### **The Factors:**
Calculated daily via median arrays from `scan_*__Indicators.npz`:
- **Funding Rate** (`<= 0.0` Bearish, `<= -0.0001` Very Bearish)
- **DVOL** (`>55` Elevated, `>80` Extreme)
- **Fear & Greed** (`<40` Fear, `<25` Extreme Fear)
- **Taker Buy/Sell Ratio** (`<0.9` Mild Selling, `<0.8` Extreme Selling)

### **The Math (Inverse Bootstrapping):**
Instead of cutting leverage during stress, the engine *increases* leverage dynamically, as the strategy is natively short-biased. Crashes are highly profitable.
`Signals (0 to 5.0) -> ACB_Boost = 1.0 + 0.5 * ln(1 + Signals)`

### **w750 Real-time Velocity Switch (`Dynamic Beta`):**
Reads `lambda_vel_w750`.
If accelerating past the historically-computed `p60` threshold -> beta = 0.8, else beta = 0.2.

`Final Regime Multiplier = ACB_Boost * (1.0 + beta * strength_score^3)`

This **Regime Size Multiplier directly modifies the Maximum Leverage limit** (e.g. 5.0x becomes 9.0x or clamped to 2.25x), dictating exactly how hard the `Alpha Orchestrator` is allowed to push the account balance bounding limit.

IMPORTANT NOTE: We need to check *how* this is implemented: *Deep* testing indicates *any* leverage beyond 6x is unsustainable, falling outside of the the envelope of the MC-Forewarning system (NOTE ALSO: MC-Forwarner EXISTS, is operational, and SHOULD be fully documented and accounted for).-
---

## 4. Order Book Core Intelligence (OB Subsystems) -> `ob_features.py`

This HFT enhancement brings micro-structural truth to eigenvalues.

- **Subsystem 1: Per-Asset Placement (Depth Quality)**
  Samples cumulative L2 notional spread at strict 1-5% bands against a pre-warmed median reference framework. Top alpha signals thrown into environments with `< 0.20%` Depth Quality are instantly rejected to prevent lethal Taker slippage cascades.
- **Subsystem 2: Per-Asset Signal (Imbalance Persistence)**
  Tracks the rolling 10-snapshot MA of volume pressure to determine local asset trajectory.
- **Subsystem 3: Market Consensus Multiplier**
  Modulates Leverage boundaries (+/- 20%) dynamically based on how synchronized all tracked orderbooks are moving simultaneously.
- **Subsystem 4: Macro Withdrawal Cascade**
  Tracks the `-30 minute` delta in 1% liquidity pools. Corroborates the `ACB Dynamic Beta` to inject massive capital if panic withdrawal is detected (`regime_signal=1`).

---

## 5. Esoteric Engine (EsoF) Overdrives (Passive Sync)

The Esoteric Factors sub-loop (`esf_alpha_orchestrator.py`) handles temporally-linked systemic oddities (Lunar cycles, specific weekday harmonics). Currently loaded passively, it inherits the EXACT `clamped_max_leverage` structural boundaries of the main Alpha Orchestrator to ensure tests remain "Apples to Apples" before introducing exotic tail caps.

---

## 6. Execution Loop Details

1. **Parquet Integration:** Backtest ticks execute utilizing PyArrow optimized DataFrames.
2. **Tick Routing:** `simulate_multi_asset_nb` / `strategy.py` processes updates every 5-seconds.
3. **Execution Edge:** 
   - `MockOBProvider` applies `run_pf_ob_putative_test` methodologies mimicking Maker fee limits (-0.2bps limit extraction) leveraging the 86% empirical fill rate probabilities attached to optimal Depth Quality vectors. This entire "mock" subsystem is of course to be substituted either during better backtesting and/or live operation, with the *actual* OB subsystems as implemented.-

--- 
## 7. The "MC-Forewarning" System (MC-Fw)

The "MC-Forewarning" System (referred to as "MC-Fw" only within this document) is a "meta-monitoring" that uses a pre-computed "Monte Carlo"-all parameters simulation to determine the "safe" overall operating envelope for the system as a whole, providing colored (GREEN, RED, ETC.,) status that inform the operation of the rest of the system.-
THIS SYSTEM IS FULLY IMPLEMENTED, HAVING BEEN FOUND to be HIGHLY effective, AND MUST BE DOCUMENTED, prior to "reverse-engineering" of extant code and review of extensive, prior, research and tests.-


*End of Document. All structures functionally mapped and frozen.*