Fallback Chain

Rubicon's oracle implements a multi-tier fallback system to ensure price availability even when individual sources fail.

Fallback Hierarchy

                    ┌─────────────┐
                    │   Polygon   │
                    │  (Primary)  │
                    └──────┬──────┘
                           │
              ┌────────────┴────────────┐
              │ Success?                │
              │                         │
         ┌────▼────┐             ┌──────▼──────┐
         │  YES    │             │     NO      │
         │ Submit  │             │ Try Yahoo   │
         └─────────┘             └──────┬──────┘
                                        │
                           ┌────────────┴────────────┐
                           │ Success?                │
                           │                         │
                      ┌────▼────┐             ┌──────▼──────┐
                      │  YES    │             │     NO      │
                      │ Submit  │             │ Try Cache   │
                      └─────────┘             └──────┬──────┘
                                                     │
                                        ┌────────────┴────────────┐
                                        │ Cache < 60s old?        │
                                        │                         │
                                   ┌────▼────┐             ┌──────▼──────┐
                                   │  YES    │             │     NO      │
                                   │ Submit  │             │  DEGRADED   │
                                   └─────────┘             └─────────────┘

Tier 1: Polygon (Primary)

Conditions for Use

• API responding with 2xx status
• Price data present in response
• Price within validation bounds

Failure Triggers

• HTTP errors (4xx, 5xx)
• Network timeout (>5 seconds)
• Invalid/missing price data
• Price outside ±20% of last known

Recovery

Automatically retries on next 3-second cycle.

Tier 2: Yahoo Finance (Secondary)

Conditions for Use

• Polygon has failed
• Yahoo API responding
• Price data valid

Failure Triggers

• HTTP errors
• Parsing failures
• Rate limiting (HTTP 429)
• Invalid data format

Considerations

• Higher latency than Polygon
• May have slight delay in quotes
• Logs warning when used

Tier 3: Stale Cache (Tertiary)

Conditions for Use

• Both Polygon and Yahoo failed
• Cached price is less than 60 seconds old
• Cache file exists and is readable

Failure Triggers

• Cache older than 60 seconds
• Cache file corrupted or missing
• No previous price recorded

Implementation

// Pseudocode
if (cacheAge < 60_000) {
  return cachedPrice;
} else {
  enterDegradedMode();
}

Degraded Mode

When all sources fail:

What Happens

1. Alert triggered — Operations team notified
2. UI warning — Users see "Price Stale" indicator
3. Trading restricted — New positions may be blocked
4. Oracle submission paused — Last valid price remains

Recovery

• System continuously attempts to reconnect
• Automatic recovery when source responds
• Manual intervention if extended outage

Error Counting

We track consecutive errors:

Error 1 → Try secondary
Error 2 → Try cache
Error 3 → Degraded mode

Reset Conditions

• Any successful price fetch resets counter
• Counter resets to 0 on recovery

Logging

Each fallback event is logged:

[WARN] Polygon fetch failed: timeout
[INFO] Falling back to Yahoo Finance
[WARN] Yahoo fetch failed: rate limit
[INFO] Using cached price (age: 12s)

Logs are monitored for patterns indicating source issues.

Failure Scenarios

Scenario 1: Temporary Polygon Outage

t=0s:  Polygon fails → Yahoo succeeds → Submit
t=3s:  Polygon fails → Yahoo succeeds → Submit
t=6s:  Polygon recovers → Submit

Impact: None — seamless fallback.

Scenario 2: Both APIs Rate Limited

t=0s:  Polygon: 429 → Yahoo: 429 → Cache (age: 5s) → Submit
t=3s:  Polygon: 429 → Yahoo: 429 → Cache (age: 8s) → Submit
...
t=57s: Polygon: 429 → Yahoo: 429 → Cache (age: 62s) → DEGRADED

Impact: Degraded mode after ~60 seconds.

Scenario 3: Network Outage

t=0s:  All requests timeout → Cache → Submit
t=60s: DEGRADED MODE

Impact: Degraded mode, requires network recovery.

Best Practices

For traders during source issues:

1. Watch status indicator — UI shows oracle health
2. Avoid new positions — If "stale" warning shown
3. Existing positions safe — Liquidation uses last valid price
4. Wait for recovery — Usually resolves in minutes

Monitoring Dashboard

Operations team monitors:

Metric	Healthy	Warning	Critical
Primary success rate	>99%	95-99%	<95%
Fallback usage	<1%	1-5%	>5%
Cache usage	0%	<0.1%	>0.1%
Degraded events	0	1/day	>1/day