# Oracle

#### Overview

The `Oracle` contract is responsible for secure and configurable **price reporting** for supported assets. It is tightly coupled with a vault module (implementing `IShareModule`) and provides **price validation**, **deviation tracking**, and **rate-limited report submission**.

It enforces strong assumptions around **data integrity**, **report timing**, and **trust minimization** through roles and deviation thresholds. This oracle ensures consistent pricing across all queue, share, and vault-related computations.

#### Key Responsibilities

* **Report Submission**: Allows trusted accounts to submit price updates
* **Deviation Analysis**: Compares new prices against the last report for suspicious behavior
* **Timestamp-based Rate Limiting**: Prevents frequent or premature reports
* **Asset Management**: Controls which tokens are supported by the oracle
* **Oracle Price Validation**: Used by other modules (e.g., `SignatureQueue`) to verify incoming prices

#### Roles

| Role                           | Description                                   |
| ------------------------------ | --------------------------------------------- |
| `SUBMIT_REPORTS_ROLE`          | Permission to submit regular price reports    |
| `ACCEPT_REPORT_ROLE`           | Permission to accept suspicious reports       |
| `SET_SECURITY_PARAMS_ROLE`     | Can modify validation rules and intervals     |
| `ADD_SUPPORTED_ASSETS_ROLE`    | Can whitelist new assets for reporting        |
| `REMOVE_SUPPORTED_ASSETS_ROLE` | Can remove assets and delete associated state |

#### **`SecurityParameters`**

```solidity
struct SecurityParams {
  uint224 maxAbsoluteDeviation;
  uint224 suspiciousAbsoluteDeviation;
  uint64 maxRelativeDeviationD18;
  uint64 suspiciousRelativeDeviationD18;
  uint32 timeout;
  uint32 depositInterval;
  uint32 redeemInterval;
}
```

* **Absolute Deviation**: Hard limits on price delta in price units
* **Relative Deviation**: Tolerance as a percentage (e.g., 5% = 0.05e18)
* **Timeout**: Minimum time between valid reports (ignored if the previous report is suspicious)
* **depositInterval**: Minimum age required for a deposit to be processed
* **redeemInterval**: Same, but for redemptions

#### **`Reports`**

```solidity
struct Report {
  address asset;
  uint224 priceD18;
}

struct DetailedReport {
  uint224 priceD18;
  uint32 timestamp;
  bool isSuspicious;
}
```

Used to validate asset prices and coordinate cross-queue processing.

#### Key Functions

#### View

| Function                         | Description                                                            |
| -------------------------------- | ---------------------------------------------------------------------- |
| `vault()`                        | Returns the linked vault (must implement `IShareModule`)               |
| `securityParams()`               | Current oracle thresholds and intervals                                |
| `supportedAssets()`              | Count of whitelisted tokens                                            |
| `supportedAssetAt(index)`        | Token at a given index                                                 |
| `isSupportedAsset(address)`      | Whether an asset is valid for reporting                                |
| `getReport(asset)`               | Returns last report (price, timestamp, suspicious flag)                |
| `validatePrice(priceD18, asset)` | Validates a given price against the current report and security params |

#### Mutable

| Function                                | Description                                     |
| --------------------------------------- | ----------------------------------------------- |
| `initialize(params)`                    | Initializes with assets and security settings   |
| `setVault(vault)`                       | Registers the vault for report consumption      |
| `submitReports(reports[])`              | Batch-submits prices for multiple assets        |
| `acceptReport(asset, price, timestamp)` | Marks a previously suspicious report as trusted |
| `setSecurityParams(params)`             | Updates thresholds and timing rules             |
| `addSupportedAssets(assets[])`          | Adds tokens to the supported set                |
| `removeSupportedAssets(assets[])`       | Removes tokens and clears their reports         |

#### Reporting Logic

When calling `submitReports(...)`:

1. Each asset is checked for support
2. The previous report is evaluated:
   * If `timeout` has not passed, and the report is not suspicious → **revert** `TooEarly`
3. Price is compared against previous:
   * Too far off → **revert** `InvalidPrice`
   * Moderately off → flagged `isSuspicious`
4. If the report is accepted:
   * Triggers `vault.handleReport(...)` with adjusted deposit and redeem timestamps
   * Emits `ReportsSubmitted`

#### Validation Logic

Prices are validated by:

* Calculating **absolute deviation**
* Calculating **relative deviation**
* Comparing against `max` and `suspicious` thresholds

A price is:

* **Rejected** if either deviation exceeds max
* **Accepted but suspicious** if above suspicious threshold
* **Accepted as normal** if within all limits

Used by:

* `SignatureDepositQueue`, `SignatureRedeemQueue`, `DepositQueue` and `RedeemQueue` contracts
* Vault's limit accounting (RiskManager)

#### Events

| Event                                     | Purpose                            |
| ----------------------------------------- | ---------------------------------- |
| `ReportsSubmitted(Report[])`              | Emitted when new prices are posted |
| `ReportAccepted(asset, price, timestamp)` | Suspicious report accepted         |
| `SecurityParamsSet(params)`               | Oracle thresholds changed          |
| `SupportedAssetsAdded(addresses[])`       | New tokens added                   |
| `SupportedAssetsRemoved(addresses[])`     | Tokens delisted                    |
| `SetVault(address)`                       | Vault set                          |

#### Security Considerations

* Only trusted roles can push prices
* Suspicious reports cannot be accepted without explicit approval
* No pricing logic oracles trust external feeds — price validation is local
* Prevents manipulation by enforcing absolute & relative deviation constraints


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.mellow.finance/core-vaults/architecture/oracle.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.