# coriom/deopt-v2-sol architecture

> Architecture diagram of the GitHub repository coriom/deopt-v2-sol, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/coriom/deopt-v2-sol
- Repository: https://github.com/coriom/deopt-v2-sol

## Overview

DeOpt v2 is a derivatives protocol for on-chain options and perpetual markets, with unified collateral, risk controls, liquidation, and governance. The main user flow is collateral deposited into the vault, then options or perp trading through matching and engine execution, with oracle-backed risk checks and liquidation safeguards. The repository also contains substantial Base Sepolia cutover tooling for snapshot verification, migration replay and resealing, and maintenance-lock operations. Solidity relationships below rely on README documentation; tool relationships use the shown excerpts and SOURCE INDEX references, so unsampled links are omitted.

Main entry points: [`src/margin/MarginEngine.sol`](https://github.com/coriom/deopt-v2-sol/blob/main/src/margin/MarginEngine.sol) (Options Engine), [`src/perp/PerpEngine.sol`](https://github.com/coriom/deopt-v2-sol/blob/main/src/perp/PerpEngine.sol) (Perp Engine), [`tools/perps_v2_cutover/migration_reseal_preflight.py`](https://github.com/coriom/deopt-v2-sol/blob/main/tools/perps_v2_cutover/migration_reseal_preflight.py) (Reseal Preflight), [`src/matching`](https://github.com/coriom/deopt-v2-sol/tree/main/src/matching) (Matching Engines)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_trading["Trading"]
  node_option_registry["Option Registry"]
  node_option_engine["Options Engine<br/>[MarginEngine.sol]"]
  node_perp_registry["Perp Registry"]
  node_perp_engine["Perp Engine<br/>[PerpEngine.sol]"]
  node_matching["Matching Engines"]
end

subgraph group_risk["Collateral and Risk"]
  node_vault[("Collateral Vault")]
  node_risk_module["Risk Modules"]
  node_perp_risk["Perp Risk<br/>[PerpRiskModule.sol]"]
  node_liquidation["Collateral Seizer"]
end

subgraph group_protocol["Protocol Services"]
  node_oracle["Oracle Router<br/>[OracleRouter.sol]"]
  node_insurance[("Insurance Fund<br/>[InsuranceFund.sol]")]
  node_fees["Fee Routing<br/>[FeesManager.sol]"]
  node_governance["Governance Controls"]
end

subgraph group_cutover["Cutover Operations"]
  node_snapshot["Snapshot Hashing<br/>[snapshot_hash.py]"]
  node_replay["Migration Replay"]
  node_replay_preflight["Replay Preflight"]
  node_replay_execute["Replay Executor"]
  node_reseal_preflight["Reseal Preflight"]
  node_reseal_execute["Reseal Executor"]
  node_maintenance_preflight["Maintenance Preflight"]
  node_maintenance_execute["Maintenance Executor"]
  node_fee_guard["Fee Guard"]
end

node_trader(("Trader"))

node_trader -->|"deposits collateral"| node_vault
node_trader -->|"submits trades"| node_matching
node_matching -->|"executes options"| node_option_engine
node_matching -->|"executes perps"| node_perp_engine
node_option_registry -->|"manages series"| node_option_engine
node_perp_registry -->|"manages markets"| node_perp_engine
node_option_engine -->|"accounts collateral"| node_vault
node_perp_engine -->|"accounts collateral"| node_vault
node_option_engine -->|"checks risk"| node_risk_module
node_perp_engine -->|"checks risk"| node_perp_risk
node_risk_module -->|"values collateral"| node_oracle
node_perp_risk -->|"values collateral"| node_oracle
node_option_engine -->|"resolves unsafe accounts"| node_liquidation
node_perp_engine -->|"resolves unsafe accounts"| node_liquidation
node_liquidation -->|"requests backstop"| node_insurance
node_option_engine -->|"routes fees"| node_fees
node_perp_engine -->|"routes fees"| node_fees
node_governance -->|"controls parameters"| node_risk_module
node_replay -->|"imports hashing"| node_snapshot
node_replay_preflight -->|"imports replay checks"| node_replay
node_replay_preflight -->|"imports hashing"| node_snapshot
node_replay_execute -.->|"reuses checks"| node_replay_preflight
node_reseal_preflight -.->|"imports hashing"| node_snapshot
node_reseal_execute -->|"uses preview"| node_reseal_preflight
node_maintenance_preflight -->|"imports preflight"| node_reseal_preflight
node_maintenance_execute -.->|"checks preflight"| node_maintenance_preflight
node_maintenance_execute -.->|"imports preflight"| node_reseal_preflight
node_fee_guard -.->|"guards fees"| node_maintenance_execute

click node_option_registry "https://github.com/coriom/deopt-v2-sol/blob/main/src/OptionProductRegistry.sol"
click node_option_engine "https://github.com/coriom/deopt-v2-sol/blob/main/src/margin/MarginEngine.sol"
click node_perp_registry "https://github.com/coriom/deopt-v2-sol/blob/main/src/perp/PerpMarketRegistry.sol"
click node_perp_engine "https://github.com/coriom/deopt-v2-sol/blob/main/src/perp/PerpEngine.sol"
click node_matching "https://github.com/coriom/deopt-v2-sol/tree/main/src/matching"
click node_vault "https://github.com/coriom/deopt-v2-sol/blob/main/src/collateral/CollateralVault.sol"
click node_risk_module "https://github.com/coriom/deopt-v2-sol/tree/main/src/risk"
click node_perp_risk "https://github.com/coriom/deopt-v2-sol/blob/main/src/perp/PerpRiskModule.sol"
click node_liquidation "https://github.com/coriom/deopt-v2-sol/blob/main/src/liquidation/CollateralSeizer.sol"
click node_oracle "https://github.com/coriom/deopt-v2-sol/blob/main/src/oracle/OracleRouter.sol"
click node_insurance "https://github.com/coriom/deopt-v2-sol/blob/main/src/core/InsuranceFund.sol"
click node_fees "https://github.com/coriom/deopt-v2-sol/blob/main/src/fees/FeesManager.sol"
click node_governance "https://github.com/coriom/deopt-v2-sol/tree/main/src/gouvernance"
click node_snapshot "https://github.com/coriom/deopt-v2-sol/blob/main/tools/perps_v2_cutover/snapshot_hash.py"
click node_replay "https://github.com/coriom/deopt-v2-sol/blob/main/tools/perps_v2_cutover/migration_replay.py"
click node_replay_preflight "https://github.com/coriom/deopt-v2-sol/blob/main/tools/perps_v2_cutover/migration_replay_preflight.py"
click node_replay_execute "https://github.com/coriom/deopt-v2-sol/blob/main/tools/perps_v2_cutover/migration_replay_execute.py"
click node_reseal_preflight "https://github.com/coriom/deopt-v2-sol/blob/main/tools/perps_v2_cutover/migration_reseal_preflight.py"
click node_reseal_execute "https://github.com/coriom/deopt-v2-sol/blob/main/tools/perps_v2_cutover/migration_reseal_execute.py"
click node_maintenance_preflight "https://github.com/coriom/deopt-v2-sol/blob/main/tools/perps_v2_cutover/maintenance_lock_preflight.py"
click node_maintenance_execute "https://github.com/coriom/deopt-v2-sol/blob/main/tools/perps_v2_cutover/maintenance_lock_execute.py"
click node_fee_guard "https://github.com/coriom/deopt-v2-sol/blob/main/tools/perps_v2_cutover/maintenance_fee_guard.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_option_registry,node_option_engine,node_perp_registry,node_perp_engine,node_matching toneBlue
class node_vault,node_risk_module,node_perp_risk,node_liquidation toneAmber
class node_oracle,node_insurance,node_fees,node_governance toneMint
class node_snapshot,node_replay,node_replay_preflight,node_replay_execute,node_reseal_preflight,node_reseal_execute,node_maintenance_preflight,node_maintenance_execute,node_fee_guard toneRose
class node_trader toneIndigo
```

## Components

### Trading

- [Option Registry](https://github.com/coriom/deopt-v2-sol/blob/main/src/OptionProductRegistry.sol): `src/OptionProductRegistry.sol`
- [Options Engine](https://github.com/coriom/deopt-v2-sol/blob/main/src/margin/MarginEngine.sol): `src/margin/MarginEngine.sol`
- [Perp Registry](https://github.com/coriom/deopt-v2-sol/blob/main/src/perp/PerpMarketRegistry.sol): `src/perp/PerpMarketRegistry.sol`
- [Perp Engine](https://github.com/coriom/deopt-v2-sol/blob/main/src/perp/PerpEngine.sol): `src/perp/PerpEngine.sol`
- [Matching Engines](https://github.com/coriom/deopt-v2-sol/tree/main/src/matching): `src/matching`

### Collateral and Risk

- [Collateral Vault](https://github.com/coriom/deopt-v2-sol/blob/main/src/collateral/CollateralVault.sol): `src/collateral/CollateralVault.sol`
- [Risk Modules](https://github.com/coriom/deopt-v2-sol/tree/main/src/risk): `src/risk`
- [Perp Risk](https://github.com/coriom/deopt-v2-sol/blob/main/src/perp/PerpRiskModule.sol): `src/perp/PerpRiskModule.sol`
- [Collateral Seizer](https://github.com/coriom/deopt-v2-sol/blob/main/src/liquidation/CollateralSeizer.sol): `src/liquidation/CollateralSeizer.sol`

### Protocol Services

- [Oracle Router](https://github.com/coriom/deopt-v2-sol/blob/main/src/oracle/OracleRouter.sol): `src/oracle/OracleRouter.sol`
- [Insurance Fund](https://github.com/coriom/deopt-v2-sol/blob/main/src/core/InsuranceFund.sol): `src/core/InsuranceFund.sol`
- [Fee Routing](https://github.com/coriom/deopt-v2-sol/blob/main/src/fees/FeesManager.sol): `src/fees/FeesManager.sol`
- [Governance Controls](https://github.com/coriom/deopt-v2-sol/tree/main/src/gouvernance): `src/gouvernance`

### Cutover Operations

- [Snapshot Hashing](https://github.com/coriom/deopt-v2-sol/blob/main/tools/perps_v2_cutover/snapshot_hash.py): `tools/perps_v2_cutover/snapshot_hash.py`
- [Migration Replay](https://github.com/coriom/deopt-v2-sol/blob/main/tools/perps_v2_cutover/migration_replay.py): `tools/perps_v2_cutover/migration_replay.py`
- [Replay Preflight](https://github.com/coriom/deopt-v2-sol/blob/main/tools/perps_v2_cutover/migration_replay_preflight.py): `tools/perps_v2_cutover/migration_replay_preflight.py`
- [Replay Executor](https://github.com/coriom/deopt-v2-sol/blob/main/tools/perps_v2_cutover/migration_replay_execute.py): `tools/perps_v2_cutover/migration_replay_execute.py`
- [Reseal Preflight](https://github.com/coriom/deopt-v2-sol/blob/main/tools/perps_v2_cutover/migration_reseal_preflight.py): `tools/perps_v2_cutover/migration_reseal_preflight.py`
- [Reseal Executor](https://github.com/coriom/deopt-v2-sol/blob/main/tools/perps_v2_cutover/migration_reseal_execute.py): `tools/perps_v2_cutover/migration_reseal_execute.py`
- [Maintenance Preflight](https://github.com/coriom/deopt-v2-sol/blob/main/tools/perps_v2_cutover/maintenance_lock_preflight.py): `tools/perps_v2_cutover/maintenance_lock_preflight.py`
- [Maintenance Executor](https://github.com/coriom/deopt-v2-sol/blob/main/tools/perps_v2_cutover/maintenance_lock_execute.py): `tools/perps_v2_cutover/maintenance_lock_execute.py`
- [Fee Guard](https://github.com/coriom/deopt-v2-sol/blob/main/tools/perps_v2_cutover/maintenance_fee_guard.py): `tools/perps_v2_cutover/maintenance_fee_guard.py`

### Other components

- **Trader**

## Connections

- Trader → Collateral Vault: deposits collateral (evidence: `README.md`)
- Trader → Matching Engines: submits trades (evidence: `README.md`)
- Matching Engines → Options Engine: executes options (evidence: `README.md`)
- Matching Engines → Perp Engine: executes perps (evidence: `README.md`)
- Option Registry → Options Engine: manages series (evidence: `README.md`)
- Perp Registry → Perp Engine: manages markets (evidence: `README.md`)
- Options Engine → Collateral Vault: accounts collateral (evidence: `README.md`)
- Perp Engine → Collateral Vault: accounts collateral (evidence: `README.md`)
- Options Engine → Risk Modules: checks risk (evidence: `README.md`)
- Perp Engine → Perp Risk: checks risk (evidence: `README.md`)
- Risk Modules → Oracle Router: values collateral (evidence: `README.md`)
- Perp Risk → Oracle Router: values collateral (evidence: `README.md`)
- Options Engine → Collateral Seizer: resolves unsafe accounts (evidence: `README.md`)
- Perp Engine → Collateral Seizer: resolves unsafe accounts (evidence: `README.md`)
- Collateral Seizer → Insurance Fund: requests backstop (evidence: `README.md`)
- Options Engine → Fee Routing: routes fees (evidence: `README.md`)
- Perp Engine → Fee Routing: routes fees (evidence: `README.md`)
- Governance Controls → Risk Modules: controls parameters (evidence: `README.md`)
- Migration Replay → Snapshot Hashing: imports hashing (evidence: `tools/perps_v2_cutover/migration_replay.py`)
- Replay Preflight → Migration Replay: imports replay checks (evidence: `tools/perps_v2_cutover/migration_replay_preflight.py`)
- Replay Preflight → Snapshot Hashing: imports hashing (evidence: `tools/perps_v2_cutover/migration_replay_preflight.py`)
- Replay Executor → Replay Preflight: reuses checks
- Reseal Preflight → Snapshot Hashing: imports hashing
- Reseal Executor → Reseal Preflight: uses preview (evidence: `tools/perps_v2_cutover/migration_reseal_execute.py`)
- Maintenance Preflight → Reseal Preflight: imports preflight (evidence: `tools/perps_v2_cutover/maintenance_lock_preflight.py`)
- Maintenance Executor → Maintenance Preflight: checks preflight (evidence: `tools/perps_v2_cutover/maintenance_lock_execute.py`)
- Maintenance Executor → Reseal Preflight: imports preflight (evidence: `tools/perps_v2_cutover/maintenance_lock_execute.py`)
- Fee Guard → Maintenance Executor: guards fees
