Architecture
Five-server model and data flow patterns
The Diffusal backend consists of five distinct server components, each with specific responsibilities and security profiles.
Implementation Status: Currently, only the Indexer and API Server are implemented. The RFQ Server, Operator Server, and Keeper Server are planned for future development.
Five-Server Model
╔═══════════════════════════════════════════════════════════════════╗
║ EXTERNAL (PUBLIC) ║
║ ┌────────────────────┐ ┌────────────────────┐ ┌────────────┐ ║
║ │ Indexer (Ponder) │ │ API Server (Elysia)│ │ Frontend / │ ║
║ │ • GraphQL │──│ • REST API │◀─│ External │ ║
║ │ • SQL-HTTP │ │ • WebSocket │ │ Clients │ ║
║ │ • Events │ │ • No keys │ └────────────┘ ║
║ └─────────┬──────────┘ └────────────────────┘ ║
╚════════════╪══════════════════════════════════════════════════════╝
│ Events
▼
┌───────────────────────────────────────────────────────────────────┐
│ BLOCKCHAIN │
│ CollateralVault • OrderBook • RFQ • SettlementEngine • etc. │
└───────────────────────────────────────────────────────────────────┘
▲ ▲ ▲
│ Transactions │ Transactions │ Transactions
╔════════════╪════════════════════╪════════════════════╪════════════╗
║ │ │ │ ║
║ ┌─────────┴──────────┐ ┌───────┴───────┐ ┌─────────┴─────────┐ ║
║ │ RFQ Server │ │ Operator Srv │ │ Keeper Server │ ║
║ │ • MMM keys │ │ • Admin ops │ │ • Snapshots │ ║
║ │ • Quotes/Fills │ │ • Oracle │ │ • Liquidate │ ║
║ └────────────────────┘ └───────────────┘ └───────────────────┘ ║
║ INTERNAL (PRIVATE) ║
╚═══════════════════════════════════════════════════════════════════╝Server Descriptions
1. Indexer (Ponder)
Role: Blockchain event indexer and data store
| Aspect | Details |
|---|---|
| Technology | Ponder framework, PostgreSQL |
| Port | 42069 (GraphQL + SQL-over-HTTP) |
| Database Port | 54322 |
| Security | Public read-only, no keys |
Responsibilities:
- Index all protocol events (trades, positions, deposits, etc.)
- Maintain queryable database of on-chain state
- Provide GraphQL and SQL-over-HTTP APIs
- Serve historical data (trade history, position changes)
Events Indexed:
| Contract | Events |
|---|---|
| CollateralVault | DepositedToPortfolio, WithdrawnFromPortfolio, TransferredOut, TransferredIn, DebitedFromPortfolio, CreditedToPortfolio |
| PositionManager | PositionUpdated, OptionsBought, OptionsSold |
| SeriesRegistry | OpenInterestUpdated, PairCapsSet, SeriesCreated, SeriesSettled |
| OrderBook | OrderRegistered, OrderCancelled, Trade, MatchSettled, FeesCollected, MinOrderNonceIncremented |
| RFQ | RfqQuoteFilled |
| LiquidationEngine | PortfolioLiquidated, PositionLiquidated |
| SettlementEngine | PositionSettled, InsuranceProrated |
| Oracle | VolatilityUpdated, PremiumUpdated, RiskFreeRateUpdated |
| PriceHistory | PriceSnapshotRecorded |
2. API Server (Elysia)
Role: Public API gateway for frontend clients
| Aspect | Details |
|---|---|
| Technology | Elysia (Bun), Drizzle ORM |
| Port | 8080 (REST + WebSocket) |
| Database Port | 54323 |
| Security | Public, no keys, SIWE auth for user data |
Responsibilities:
- Aggregate data from Indexer and on-chain sources
- Calculate mark prices and Greeks
- Serve REST API and WebSocket streams
- Cache expensive computations
- Handle user authentication (SIWE)
Data Sources:
| Data | Source | Method |
|---|---|---|
| Positions, balances | Indexer | SQL-over-HTTP |
| Margin calculations | Computed | @diffusal/algorithms |
| Mark prices, Greeks | Computed | @diffusal/algorithms |
| Oracle data | Indexer | SQL-over-HTTP (cached from chain) |
Note: The API server has no direct RPC calls to the blockchain. All on-chain data is consumed via the Indexer's SQL-over-HTTP interface.
3. RFQ Server
Status: Not yet implemented
Role: Main Market Maker quote generation
| Aspect | Details |
|---|---|
| Security | Internal only, holds MMM keys |
| Access | Not exposed to public internet |
Planned Responsibilities:
- Generate RFQ quotes for users
- Sign quotes with MMM private key
- Manage MMM inventory and risk
- Execute quote fills on-chain
Key Characteristics:
- Holds private keys (critical security)
- Internal network only
- Monitored for health/solvency
4. Operator Server
Status: Not yet implemented
Role: Administrative operations
| Aspect | Details |
|---|---|
| Security | Internal only, holds operator keys |
| Access | Restricted to authorized personnel |
Planned Responsibilities:
- Set oracle parameters (volatility, rates)
- Update protocol configuration
- Emergency operations
- Native price overrides (when needed)
5. Keeper Server
Status: Not yet implemented
Role: Automated protocol maintenance
| Aspect | Details |
|---|---|
| Security | Internal only, holds keeper keys |
| Access | Automated, monitored |
Planned Responsibilities:
- Take price snapshots (30-second intervals)
- Trigger liquidations when users become undercollateralized
- Settle expired series (TWAP calculation)
- Settlement readiness liquidations
Data Flow Patterns
Read Flow (User → API)
User Request
│
▼
┌─────────────────────────────────────────────────────────────┐
│ API Server │
├─────────────────────────────────────────────────────────────┤
│ 1. Auth? ─── If protected, verify JWT ───► │
│ │ │
│ ▼ │
│ 2. Cache? ─── Check if cached data is fresh ───► │
│ │ │
│ ▼ │
│ 3. Query ─── Fetch from Indexer (SQL-over-HTTP) ───► │
│ │ │
│ ▼ │
│ 4. Compute ─── Calculate Greeks, margins ───► │
│ │ │
│ ▼ │
│ 5. Return ─── JSON response ───► │
└─────────────────────────────────────────────────────────────┘Write Flow (User → Chain)
User Action (e.g., deposit)
│
▼
┌──────────────────────────────────────┐
│ FRONTEND │
├──────────────────────────────────────┤
│ 1. Build tx ── helper endpoints │
│ │ │
│ ▼ │
│ 2. Sign ── wallet signature │
│ │ │
│ ▼ │
│ 3. Submit ── blockchain RPC │
└──────────┬───────────────────────────┘
│
▼
┌──────────────────────────────────────┐
│ BLOCKCHAIN │
│ Transaction executes │
└──────────┬───────────────────────────┘
│ Events
▼
┌──────────────────────────────────────┐
│ INDEXER │
│ Indexes new events │
└──────────┬───────────────────────────┘
│
▼
┌──────────────────────────────────────┐
│ API SERVER │
│ WebSocket broadcasts update │
└──────────┬───────────────────────────┘
│
▼
┌──────────────────────────────────────┐
│ FRONTEND │
│ UI updates in real-time │
└──────────────────────────────────────┘Real-Time Update Flow
Blockchain Event (e.g., Trade)
│
▼
┌──────────────────────────────────────┐
│ INDEXER │
│ Persists to database │
└──────────┬───────────────────────────┘
│ Subscription
▼
┌──────────────────────────────────────┐
│ API SERVER │
├──────────────────────────────────────┤
│ 1. Receive ── from Indexer stream │
│ │ │
│ ▼ │
│ 2. Process ── update caches │
│ │ │
│ ▼ │
│ 3. Broadcast ── push to WebSocket │
└──────────┬───────────────────────────┘
│
▼
┌──────────────────────────────────────┐
│ CLIENTS │
│ Receive real-time updates │
└──────────────────────────────────────┘Security Model
Public Servers (No Keys)
| Server | Keys | Risk if Compromised |
|---|---|---|
| Indexer | None | Data leak only, no fund loss |
| API Server | None | Data leak only, no fund loss |
Mitigations:
- Rate limiting
- Input validation
- CORS whitelisting
- DDoS protection
Internal Servers (With Keys)
| Server | Keys | Risk if Compromised |
|---|---|---|
| RFQ Server | MMM keys | Fund loss possible |
| Operator Server | Operator keys | Protocol manipulation |
| Keeper Server | Keeper keys | Limited (can trigger liquidations) |
Mitigations:
- Network isolation (no public access)
- Key management (HSM, secure enclaves)
- Multi-sig for high-value operations
- Monitoring and alerting
- Transaction limits
Deployment Topology
Development
┌───────────────────────────────────────────────────────────┐
│ localhost │
├───────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ Anvil (8545) - Local blockchain │ │
│ └─────────────────────────────────────────────────────┘ │
│ │
│ ┌──────────────────────┐ ┌──────────────────────────┐ │
│ │ Indexer Postgres │ │ API Postgres │ │
│ │ (54322) │ │ (54323) │ │
│ └──────────┬───────────┘ └─────────────┬────────────┘ │
│ │ │ │
│ ┌──────────▼───────────┐ ┌─────────────▼────────────┐ │
│ │ Indexer (42069) │ │ API Server (8080) │ │
│ │ GraphQL + SQL-HTTP │ │ REST + WebSocket │ │
│ └──────────────────────┘ └──────────────────────────┘ │
│ │
└───────────────────────────────────────────────────────────┘Production
┌─────────────────────────────────────────────────────────┐
│ PUBLIC ZONE │
├─────────────────────────────────────────────────────────┤
│ │
│ ┌───────────────────────┐ │
│ │ Load Balancer │ │
│ └───────────┬───────────┘ │
│ ┌─────┴─────┐ │
│ │ │ │
│ ┌──────▼─────┐ ┌───▼──────────────┐ │
│ │ API Server │ │ Indexer │ │
│ │ (replicated)│ │ (replicated, │ │
│ └────────────┘ │ read-only) │ │
│ └──────────────────┘ │
└─────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────┐
│ PRIVATE ZONE (VPN/VPC only) │
├─────────────────────────────────────────────────────────┤
│ │
│ ┌────────────┐ ┌─────────────┐ ┌────────────────┐ │
│ │ RFQ Server │ │ Operator │ │ Keeper Server │ │
│ │ │ │ Server │ │ │ │
│ └────────────┘ └─────────────┘ └────────────────┘ │
│ │
│ ┌──────────────────────────┐ │
│ │ Databases (PostgreSQL) │ │
│ └──────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────┘Related
- API Reference - REST endpoint specifications
- WebSocket - Real-time data streams
- Keepers - Keeper operations guide