Module databento_oracle 

Databento-backed vol oracle for CME products (initially GC gold options).

This module holds everything Databento-specific behind a single file: the CME symbology parser, expiry calendar, MBP-1 book cache, chain-to-IV aggregator, a mockable feed trait, and the RiskVolOracle implementation that publishes surfaces to the rest of the API. Nothing here is exposed to consumers except the final DatabentoVolOracle struct.

The build-out follows a test-driven sequence; see the cycle markers in the tests submodules.

Structs

Bbo 🔒

A single top-of-book snapshot. Databento MBP-1 records carry exactly this shape (best bid/size + best ask/size + timestamp), so we just store what we’re given.

BookCache 🔒

Per-instrument top-of-book cache. Intentionally dumb: the Databento MBP-1 feed already collapses the full book to a single BBO per update, so there’s no order book to maintain here — just the most-recent snapshot per instrument.

ChainContext 🔒

Quality filters applied to raw option quotes before we even try to solve for IV. Tuned defaults aim to reject obvious garbage (one-sided markets, locked books, stale prints) without being so aggressive that we eat the thin wings of a real CME chain.

CmeFutureSymbol 🔒

A parsed CME futures contract symbol.

CmeOptionSymbol 🔒

A parsed CME option-on-future symbol.

DatabentoLiveFeed

Adapter that wraps Databento Live behind our DatabentoFeed trait.

DatabentoOracleState 🔒

DatabentoOrchestrator 🔒

Stateful glue that turns a stream of FeedRecords into a live vol surface. Holds the instrument registry, the BBO cache, and the most recent forward we’ve seen for the underlying futures contract.

DatabentoVolOracle

A RiskVolOracle backed by a Databento feed. Owns a DatabentoOrchestrator under an RwLock and a cached VolatilitySurface that is rebuilt on every ingested record.

DatabentoVolOracleConfig

Config for the Databento vol oracle.

FakeFeed 🔒

Deterministic in-memory feed used exclusively in tests. Hand it a Vec<FeedRecord> and it replays them in order, one per next_record call, then returns None forever.

FittedIvPoint 🔒

A single (strike, expiry, iv) point fit from a quality quote. Ready to insert into a VolatilitySurface.

OptionQuote 🔒

A raw option quote as we pull it off Databento. Normalised to the shape the aggregator wants: one strike, one expiry, one side, BBO, and the timestamp we received it at.

Enums

CmeOptionSide 🔒

Which side of the option — call or put.

FeedRecord 🔒

Events we consume from a Databento feed, after the SDK-specific DBN records have been adapted to our internal representation.

InstrumentKind 🔒

A product-type-agnostic view of a single Databento instrument definition, normalised to the fields we actually consume.

Constants

DATABENTO_DEFINITION_DRAIN_IDLE_SECS 🔒

How long to wait (idle seconds) before we consider the Definition snapshot drained and shut that client down. Local reproduction shows the full GLBX.MDP3 GC+OG directory (43 730 records) drains in ~5s — a 3s idle window is a comfortable cutoff.

DATABENTO_MBP1_REPLAY_MINUTES 🔒

How far back to replay MBP1 on connect. Only used to re-seed book_cache on pod restart — 5 minutes is plenty, the live tail does the rest.

RECONNECT_BASE_DELAY 🔒

Initial delay before the first reconnect attempt.

RECONNECT_MAX_DELAY 🔒

Maximum delay between reconnect attempts (capped exponential backoff).

SECONDS_PER_YEAR 🔒

Seconds per year used to convert seconds-to-expiry into Black-76’s time-to-expiry parameter (τ). 365.0 matches the existing calculate_implied_volatility callers in this repo.

Traits

DatabentoFeed 🔒

Abstraction over a Databento live-or-historical feed, narrowed to the two calls the provider needs: pull the next record, or stop.

Functions

cme_month_code_to_number 🔒

CME Globex month codes. Standard across every listed product.

compute_iv_points 🔒

Fit an implied-vol point from each quote in the chain that survives quality checks. Filters silently — the count of dropped quotes is observable by comparing input/output lengths if a caller needs it.

is_weekday 🔒

last_day_of_month 🔒

og_monthly_expiry 🔒

Compute the nominal expiry for a CME OG (gold-on-futures) monthly option contract in the requested option-contract month.

spawn_databento_live_feed_task

Spawns a detached tokio task that connects to Databento, drives the oracle’s run loop, and automatically reconnects with exponential backoff when the feed drops or fails to connect.

Type Aliases

InstrumentId 🔒

Databento’s canonical 64-bit instrument identifier.