System Architecture
Three layers work together: external services (Pyth oracle, The Graph indexer) provide market data and event indexing, off-chain services (publisher, keeper, frontend) bridge data to the chain, and onchain contracts enforce all trading rules, margin, and settlement. For step-by-step interaction flows, see Trading Flows and System Flows.Contract Architecture
The Protocol Registry is the root — all contracts discover each other through it rather than storing direct addresses. Solid arrows show ownership, dotted arrows show runtime reads. Each pool can have its own operating mode. M2 deploys a single USDC pool; the architecture supports future multi-collateral pools.Shared Infrastructure
Singleton contracts that serve all pools:- Config — Stores all tunable parameters: margin factors, fee rates, tenor durations, risk caps, and oracle thresholds. The admin can adjust parameters without redeploying contracts.
- OracleModule — Manages two price feeds: Pyth spot prices (read onchain) and publisher-submitted forward prices (with safeguard checks on staleness, deviation, and price movement).
- ModeController — Implements a four-state operating mode machine (NORMAL → DEGRADED → REDUCE_ONLY → PAUSED) that progressively restricts protocol operations during adverse conditions.
- RiskManager — Enforces per-position, per-account, and pool-level risk caps, plus rate-of-change throttling to prevent sudden large exposures.
Pool Contracts
Instantiated per collateral token (currently USDC only):- MarginAccounts — Holds trader collateral. Manages deposits, withdrawals, and per-position margin locking so that each position’s risk is isolated.
- PoolVault — ERC-4626 vault for LP deposits. Serves as the counterparty to all trader positions, paying out trader profits and absorbing trader losses.
- PositionManager — Handles the full position lifecycle: opening new positions, increasing existing ones, reducing exposure, and managing margin adjustments.
- SettlementEngine — Executes settlement at maturity, liquidation of underwater positions, and early termination requests.
For design rationale (zero-sum pool model, immutable contracts, isolated margin, ERC-4626 vault), see Core Design.
Access Control
| Role | Capabilities |
|---|---|
DEFAULT_ADMIN_ROLE | Full admin — set config, manage roles, mode transitions |
PAUSER_ROLE | Emergency pause/unpause only |
PUBLISHER_ROLE | Submit forward prices via OracleModule |
ORACLE_ADMIN_ROLE | Configure oracle safeguard parameters |
RISK_ADMIN_ROLE | Configure risk caps and rate-of-change limits |
Technology Stack
| Layer | Technology | Purpose |
|---|---|---|
| Contracts | Solidity 0.8.34, OpenZeppelin 5.6.1 | Core protocol logic |
| Upgradeability | None (immutable bytecode) | All contracts are deployed without proxies |
| Oracle (Spot) | Pyth Network | EUR/USD spot price |
| Oracle (Forward) | Custom ForwardPublisher | Computed forward prices via interest rate parity |
| Indexer | The Graph (Subgraph) | Event indexing and GraphQL API |
| API Gateway | Cloudflare Workers | Read-only REST API over subgraph + RPC |
| Publisher | Rust + Tokio + alloy-rs | Forward price computation and onchain publishing |
| Keeper | Rust + Tokio + alloy-rs | Batch settlement and liquidation |
| Risk | RiskManager | Position, account, and pool exposure caps |
| Frontend | Next.js 16 + shadcn/ui + Tailwind 4.x + wagmi 3.x + viem 2.x | User interface |
| Network | Ethereum Sepolia | Testnet deployment |
Next Steps
Trading Flows
Sequence diagrams for open, increase, reduce, margin adjust, and settlement.
System Flows
Oracle publishing, keeper automation, fee distribution, and LP deposits.
Core Design
Zero-sum pool model, immutable contracts, and design principles.