> For the complete documentation index, see [llms.txt](https://docs.uniocean.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.uniocean.io/protocol-and-infrastructure/protocol/core-modules/oracle-module.md).

# Oracle Module

The Oracle Module functions as the centralized data ingestion layer for the Uniocean blockchain. It is exclusively responsible for sourcing and persisting off-chain data — ranging from continuous asset prices to discrete event outcomes — into the chain's state. This synchronized data is then securely queried by the Exchange Module to calculate funding rates, evaluate margin health, and execute deterministic market settlements.

## Single-Provider Architecture and Relayer Network

To ensure strict data provenance and mitigate vector attacks, Uniocean utilizes a Single-Provider Oracle architecture.

Instead of relying on fragmented external providers, the network designates a singular logical namespace (e.g., `zeeve_oracle`) as the canonical data provider. Redundancy and decentralization are achieved through a decentralized cluster of authorized relayers operating under this single namespace. These relayers continuously observe off-chain data and submit consensus-backed values mapped to deterministic symbols.

This architecture supports a highly extensible symbol taxonomy, natively handling standard price tickers (e.g., `BTC/USD`) as well as highly specific event-resolution symbols (e.g., `SPORT-CRICKET-IND-AUS-2026-03-11` or `CHAIN-UPGRADE-V161-SUCCESS`).

## Governance-Gated Relayer Authority

To maintain the integrity of the data feeds, the relayer network is strictly controlled by an on-chain allowlist (`authorized_relayers`).

* **Privilege Management:** Operational privileges are entirely governance-gated. New relayers must be approved through formal network governance proposals. Once the voting period concludes and the proposal executes, the relayer addresses are appended to the allowlist, granting them write access for data publishing.
* **Revocation Mechanics:** If a relayer degrades, ceases operation, or acts maliciously, their privileges must be revoked via a `MsgUpdateAuthorizedRelayers` governance payload. Because this relies on the standard governance lifecycle (submission, deposit, voting, and execution), the network relies on its decentralized validator set to identify and vote out bad actors efficiently.

## Data Resolution and Mark Price Calculation

The Oracle Module is designed to handle different data profiles based on the symbol queried, storing both raw inputs and historical price data in the module's KVStore.

* **Continuous Price Feeds:** For standard spot and derivative markets, the oracle ingests continuous price values. To protect downstream Exchange modules from oracle manipulation or localized flash crashes, the protocol does not rely solely on the raw index price for sensitive operations like liquidations. Instead, the keeper logic dynamically calculates a secure mark price by evaluating `max(IndexPrice, TWAP)`, utilizing the Time-Weighted Average Price derived from the stored history.
* **Discrete Event Resolution:** For event-based binary markets, the oracle ingests specific threshold values. The module stores the reported value, allowing downstream market logic to evaluate it against programmatic limits (e.g., a reported value of ≥ 0.5 resolving to a `TRUE` state for settlement).