# Circle EURC/EUR Oracle

### High-Level Overview

The CircleEurcOracle contract is a specialized oracle implementation that serves as a proxy for Circle EURC price feeds. It implements the Chainlink AggregatorV3Interface to provide standardized price feed data for EURC in terms of EUR (not USD), making it compatible with the broader Chainlink oracle ecosystem. **The aim of this oracle is to return a price of EURC in EUR and not in USD.**

### Contract Summary

This contract acts as a wrapper around two separate Chainlink price feeds (EURC/USD and EUR/USD), converting the USD-denominated prices into a standardized EURC/EUR price feed format. It maintains compatibility with the Chainlink AggregatorV3Interface while providing real-time EURC/EUR price data through cross-rate calculation.

### Key Features

#### Chainlink Compatibility

* Implements the AggregatorV3Interface
* Provides standardized price feed data structure
* Maintains consistent decimal precision (8 decimals)

#### Cross-Rate Price Calculation

* Fetches live EURC/USD and EUR/USD conversion rates from Chainlink feeds
* Calculates EURC/EUR price through cross-rate conversion: `EURC/EUR = (EURC/USD) / (EUR/USD)`
* Updates price data on every query using the most recent available data

#### Standardized Interface

* Returns price data in a format compatible with Chainlink consumers
* Includes round information, timestamps, and price values
* Maintains consistent decimal precision across all operations

### Functions Description

#### Public/External Functions

* **`decimals()`**: Returns the number of decimals used in the price feed (8)
* **`description()`**: Returns the description of the price feed ("EURC / EUR")
* **`version()`**: Returns the version of the price feed implementation (1)
* **`getRoundData(uint80 roundId_)`**: Returns historical price data for a specific round
* **`latestRoundData()`**: Returns the most recent price data

**Returns:**

* **roundId**: The round ID from the EURC/USD feed
* **answer**: The calculated EURC/EUR price
* **startedAt**: Timestamp from the EURC/USD feed
* **updatedAt**: Minimum timestamp between EURC/USD and EUR/USD feeds
* **answeredInRound**: The round ID from the EURC/USD feed

### State Variables

* **`EURC_USD_FEED`**: Immutable address of the EURC/USD Chainlink price feed
* **`EUR_USD_FEED`**: Immutable address of the EUR/USD Chainlink price feed
* **`PRICE_FEED_DECIMALS`**: Constant value of 8, representing the number of decimals used in price feed output

### Error Handling

* **InvalidDecimalsNumber()**: Thrown when either price feed's decimals don't match the expected PRICE\_FEED\_DECIMALS (8)

### Security Considerations

#### Immutable Contract Addresses

* Both price feed addresses are set during construction and cannot be changed
* Prevents potential manipulation of the price sources

#### Decimal Validation

* Validates both price feeds' decimals during construction
* Ensures consistent decimal precision across the system

#### Cross-Rate Calculation

* Price data is calculated in real-time using the latest available data from both feeds
* Uses the minimum timestamp between both feeds to ensure data freshness
* No stale price data is stored or returned

#### Price Feed Independence

* Relies on two independent Chainlink price feeds
* Reduces single points of failure in price discovery
* Provides more robust price data through cross-validation

### Integration Notes

#### Chainlink Compatibility

* Can be used as a drop-in replacement for Chainlink price feeds
* Compatible with any system expecting AggregatorV3Interface implementation

#### Price Data Usage

* The answer returned represents the EURC/EUR exchange rate calculated as: `(EURC/USD price) / (EUR/USD price)`
* All price data is returned with 8 decimal precision
* Timestamps are synchronized between both feeds for accuracy

#### Round Data

* Historical round data is based on the EURC/USD feed's round structure
* EUR/USD data is always fetched from the latest round for cross-rate calculation
* Round queries return calculated prices with appropriate round identifiers


---

# 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://tech.usual.money/smart-contracts/utility-contracts/eur0/circle-eurc-eur-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.