Decision Rule
Subgraph for data that is historical, paginated, aggregated, or spans multiple contracts. RPC for data that must reflect the latest block, powers transaction pre-validation, or represents authoritative onchain state.Subgraph Data
Use GraphQL queries against the subgraph for:| Data Category | Examples | Why Subgraph |
|---|---|---|
| Position history | Closed positions, PnL history, liquidation records | Unbounded growth, needs pagination and filtering |
| Activity feeds | PoolTransaction timeline, VaultEvent history | Append-only logs across multiple contracts |
| Analytics | DailyStats aggregates, fee breakdowns, volume | Pre-aggregated by the indexer |
| Cross-contract joins | Position with its Account, reductions with parent position | Single query spans what would require multiple RPC calls |
| Oracle history | Forward round history, fixing price archive | Time-series data for charts |
| Protocol audit trail | ModeTransition history, fee event records | Immutable event log |
Latency
The subgraph indexes events as blocks are confirmed. On Sepolia, expect 1-2 block latency (12-24 seconds). Polling the subgraph at a 15-second interval (the default in the UI) covers most use cases.RPC Data
Use direct contract reads (useReadContract, publicClient.readContract) for:
| Data Category | Contract | Functions | Why RPC |
|---|---|---|---|
| Current prices | OracleModule | getForwardPrice, getForward | Prices change every publisher update; subgraph may lag |
| Position PnL | PositionManager | unrealizedPnl, positionEquity, isLiquidatable | Computed from latest forward price, not stored onchain |
| Account state | MarginAccounts | availableBalance, collateralBalance, imLockedTotal | Authoritative balance for transaction pre-validation |
| Pool metrics | PoolVault | poolEquity, utilization, maxWithdrawable | Derived from current totalAssets and live exposure |
| Config values | Config | imFactorBps, tradingFeeBps, minPositionNotional | Source of truth for form validation and fee estimates |
| Risk caps | RiskManager | maxPositionNotional, maxAccountNotional, maxNetExposure | Computed from live pool equity |
| Protocol mode | ModeController | currentMode, canOpenPosition | Must be authoritative for button enable/disable states |
| Open position IDs | PositionManager | getOpenPositions, allOpenPositionIds | Authoritative set for the current block |
Anti-Patterns
Never Use getContractEvents
All event-based data comes from the subgraph. Scanning events via RPC (getContractEvents, getLogs with fromBlock: "earliest") scans the entire chain and times out on testnets.
Never Duplicate Sources
If position history comes from the subgraph, do not also fetch closed positions via RPC. If the current mode comes from RPC, do not also queryProtocolState from the subgraph for the same purpose.
Never Use Subgraph for Pre-Validation
Transaction forms (open position, deposit, withdraw) must validate against RPC reads. A subgraph value that is 15 seconds stale could allow a transaction that immediately reverts.Hybrid Pattern
Some UI views combine both sources. The pattern is: subgraph for the list, RPC for live-updating fields on each item. Example: Open positions table- Query open position IDs from the subgraph (paginated, with
entryStrike,notional,fixingTimestamp) - For each visible position, read
unrealizedPnlandpositionEquityfrom PositionManager via RPC - Refresh subgraph data every 15 seconds, RPC data every block
Source Assignment Summary
| Data Point | Source | Rationale |
|---|---|---|
| Position list (open) | Subgraph | Paginated, filterable |
| Position list (closed) | Subgraph | Historical, unbounded |
| Unrealized PnL | RPC | Computed from live price |
| Account collateral balance | RPC | Authoritative for tx validation |
| Account position count | Subgraph | Aggregated |
| Pool total assets | RPC | Changes every block |
| Pool share price (live) | RPC | Derived from live total assets |
| Pool share price (historical) | Subgraph | Stored per-event in PoolState |
| Fee totals | Subgraph | Pre-aggregated |
| Forward price (current) | RPC | Must be fresh for trading |
| Forward price (history) | Subgraph | Time-series for charts |
| Fixing prices | Subgraph | Historical archive |
| Daily volume | Subgraph | Pre-aggregated in DailyStats |
| Operating mode | RPC | Authoritative for UI state |
| Mode history | Subgraph | Audit trail |
Related Pages
Subgraph Overview
Endpoint URLs and indexed data sources.
Query Examples
Ready-to-use GraphQL patterns.
TypeScript SDK
SDK setup for RPC reads via wagmi.