Overview
DEX-native API architecture for the Diffusal protocol
The Diffusal backend follows a DEX-native philosophy: the API server is a read-only data provider, while all writes go directly to smart contracts via user wallets.
Implementation Status: The Indexer and API Server are currently implemented. Internal servers (RFQ, Operator, Keeper) are planned for future development.
Three-Tier Interaction Model
┌─────────────────────────────────────────────────────────┐
│ CLIENT │
│ Frontend / Client │
└─────────────┬───────────────────────────────┬───────────┘
│ │
▼ ▼
┌─────────────────────────────┐ ┌─────────────────────────┐
│ READS │ │ WRITES │
├─────────────────────────────┤ ├─────────────────────────┤
│ API Server (read-only) │ │ Direct Transactions │
│ │ │ │ (via wallet) │
│ ▼ │ │ │
│ Indexer (Ponder) │ │ │
└─────────────┬───────────────┘ └────────────┬────────────┘
│ │
└──────────────┬───────────────┘
│
▼
┌─────────────────────────────┐
│ BLOCKCHAIN │
│ Smart Contracts │
└─────────────────────────────┘Read Operations (API Server)
The API server aggregates data from multiple sources and serves it to clients:
| Data Type | Source | Processing |
|---|---|---|
| Positions, balances | Indexer (PostgreSQL) | SQL-over-HTTP queries |
| Trade history | Indexer | Aggregation, pagination |
| Order book | Indexer + Cache | Real-time aggregation |
| Mark prices, Greeks | Computed | Black-Scholes via @diffusal/algorithms |
| Margin requirements | Computed | @diffusal/algorithms (TypeScript) |
| Oracle data | Indexer | Cached from indexed chain events |
| 24h statistics | Computed | Rolling window calculations |
Write Operations (Direct to Contracts)
All state-changing operations go directly to smart contracts:
| Operation | Contract | Function |
|---|---|---|
| Deposit collateral | CollateralVault | depositToPortfolio() |
| Withdraw collateral | CollateralVault | withdrawFromPortfolio() |
| Register order | OrderBook | registerOrder() |
| Cancel order | OrderBook | cancelOrder() |
| Fill RFQ quote | RFQ | fillQuote() |
| Create portfolio | PortfolioManager | createPortfolio() |
| Transfer positions | PortfolioManager | transferPositionBetweenPortfolios() |
Quick Reference
Endpoint Categories
| Category | Base Path | Auth Required | Description |
|---|---|---|---|
| Auth | /auth/api/* | No | SIWE authentication |
| Markets | /markets, /orderbook, /ticker | No | Public market data |
| Account | /account/* | Yes | User positions, balances |
| Helpers | /helpers/* | No | Transaction parameter computation |
| WebSocket | /ws | Optional | Real-time data streams |
Port Reference (Local Development)
| Service | Port | Protocol | Description |
|---|---|---|---|
| Anvil | 8545 | HTTP | Local blockchain RPC |
| Indexer PostgreSQL | 54322 | TCP | Ponder database |
| Indexer (Ponder) | 42069 | HTTP | GraphQL + SQL-over-HTTP |
| API PostgreSQL | 54323 | TCP | API server database |
| API Server (Elysia) | 8080 | HTTP/WS | REST API + WebSocket |
Key Design Principles
1. No Private Keys
The API server holds zero private keys. It cannot:
- Sign transactions
- Execute trades on behalf of users
- Move user funds
This eliminates entire classes of security vulnerabilities.
2. Trustless Reads
All data served by the API can be independently verified:
- Position data comes from indexed blockchain events
- Margin calculations can be verified via on-chain view calls
- Mark prices use transparent Black-Scholes formulas
3. Real-Time Updates
The API maintains WebSocket connections for:
- Order book updates
- Trade notifications
- Position changes
- Oracle price updates
Architecture Deep Dive
- Architecture - Five-server model and data flows
- API Reference - REST endpoint specifications
- WebSocket - Real-time data streams
- On-Chain Guide - Contract interaction patterns
- Authentication - SIWE + session management