Integrating oracle data securely into your application is critical. Tellor, an L1 oracle chain, enables developers on any chain to access subjective data through robust verification mechanisms. This article provides a technical overview to help developers understand the necessary integration steps, verification checks, and specific considerations for common oracle use cases.
Tellor Integration Workflow Overview
Tellor oracle users access verified data through a secure and trustless bridge. The integration process involves:
- Accessing tellor’s data (relayer) – Fetching oracle data and attestations from tellor into the user contract
- Verifying the data came from tellor – Connecting user contracts to the tellor data bridge contract which verifies that data came from tellor.
- Implementing custom data verification – Implementing user specific data verification checks
For example, let’s imagine that Sara, a web3 developer, decides to build a prediction market platform which allows users to bet on the outcomes of real world events such as elections, sports, weather, and more. Ethereum is her chain of choice. She wants her prediction market to be as trustless and secure as possible. In order for each market to resolve, her protocol needs to know the outcomes of the world events after they occur, and therefore she needs an oracle. In her contracts she implements custom data verification checks to evaluate the data provided by tellor. She will need to connect her contracts to the tellor data bridge contract to have access to verified data about real world events.
Accessing tellor’s data (relayer)
Let’s say someone creates a prediction market on Sara’s platform which asks “Will the Bitcoin price be above $100,000 on July 31, 2025?”. Once this market expires, the relayer requests the answer to this question to tellor. The relayer retrieves the report (answer), metadata, and the attestations, and submits them to Sara’s contract on Ethereum, along with some proofs of the data integrity.
Figure 1.
Verifying the data came from tellor
Sara’s contract asks the tellor bridge contract to verify the attestations, making sure that at least 2/3 of tellor validators signed the data.
Every user contract integrating tellor oracle data should perform the following checks on relayed data:
- Validator signature check: Verify that at least ⅔ of tellor validators have attested to the data.
- Attestation freshness check: Ensure attestations are recent and reflect a current state of the tellor chain. This should usually be 10 minutes or less.
- Query ID Check: Confirm that the provided query ID matches the expected query ID.
Implementing custom data verification
In addition to the essential bridged data checks, each use case should implement custom checks.
For Sara, this would include making sure the aggregate value consists of reports from at least ⅔ of tellor reporters. Note that this is different from the ⅔ validator power check mentioned above. The ⅔ reporter power threshold is important because it defines how quickly Sara can use the data. For anything with reporter power below ⅔, a grace period should be implemented to allow for disputes. If ⅔ or greater reporter power is reached, and the data timestamp is after the market expiration, the data is saved in Sara’s contract.
Additional user security measures
Once the data is saved, users can then employ any additional security measures using time delays and governance.
In the case of Sara, within her protocol, she opted to include a delay before the oracle data is used and a dispute mechanism. She implemented a two hour waiting period before the prediction market can be resolved. During this time period, anyone can pay a hefty fee to dispute the oracle result. In this case, the dispute goes to a governance vote of her community and can go to multiple rounds. This safety feature helps mitigate the risk of some prediction market having a lot of money at stake, and bad actors deciding to burn lots of their personal money to manipulate the oracle results and ultimately resolve a prediction market in their malicious favor. These additional security measures are completely up to the user but highly recommended.
Specific Use Cases and Checks
Similar to additional security measures, custom checks depend on the use case. Below we describe additional checks relevant to various oracle data use cases.
Prediction Market Integration
Prediction markets require precise, verifiable outcomes with robust dispute mechanisms:
Tellor-Specific Checks:
- Timestamp Verification: Confirm the report timestamp is greater than the market’s minimum allowable timestamp (either market start or expiration time).
- Optimistic Delay Check: If the data has not reached consensus, ensure it has passed the optimistic delay period determined by the user.
System-Level Checks:
- Implement an optimistic waiting period (eg. 2 hours) so that, after a value is pushed to the user contract, the user’s governance can dispute a value before the market is resolved.
Price Feed Integration
Price feed contracts require frequent, accurate, and recent data updates. The following checks ensure these conditions are met:
- Data Recency Check: Verify the report timestamp is not older than a user defined maximum data age (e.g., 4 hours).
- Timestamp Order Enforcement: Ensure each new report timestamp increases relative to the previously stored timestamp.
- Latest Data Check: If nextTimestamp is non-zero, this means there is a new report available.
- Consensus vs. Optimistic Data:
- Prefer immediate use if the data has reached consensus (at least ⅔ reporter power). (Further information on tellor security available at Tellor Layer Security 201.)
- If consensus isn’t reached, verify the data has passed the optimistic delay and exceeds the minimum optimistic power threshold (1/3 total reporter power).
EVM Call Integration
For cross-chain governance or critical EVM calls, correctness is the most important factor:
- Optimistic Delay: Ensure sufficient delay between report and attestation timestamps (typically at least 1 hour):
- Aggregate Power Check: Verify that the report’s aggregate power surpasses the preferred power threshold (eg. 1/3 total reporter power):
Metadata and Its Importance
We discussed the recommended checks for Sara’s prediction market above but she could come up with additional checks based on the additional metadata provided. Tellor validators sign not just the oracle data, but a set of metadata which acts to help users’ contracts make sure they are consuming the data they need at a given time. Below is all of the data validators attest to:
- QueryId – The unique identifier for each data type. For example, the
- Aggregate Value – This is the aggregated data from all reporters who submitted. For example, if this is the ETH/USD queryId, the aggregate value is the stake-weighted median of all reporters who submitted ETH/USD spot prices within a 2 block window.
- Report Timestamp – This is the timestamp of the block when the report was aggregated
- Aggregate Power – This is the total stake power of all reporters who reported to create this aggregate data.
- Previous Timestamp – This is the timestamp of the last aggregate report before this one.
- Next Timestamp – This is the timestamp of the next report aggregated after this one.
- Last Validator Set Checkpoint – This is a hash of the current validator set and some extra metadata.
- Attestation Timestamp – This is the time of when the attestation was created
- Last Consensus Timestamp – This is the timestamp of the last aggregate which had at least ⅔ of reporter power.
- Power Threshold – This is equal to ⅔ of the total tokens tellor validators have at stake.
Conclusion
Integrating tellor oracle data involves careful consideration of security checks and data freshness. By adhering to the guidelines and verification steps outlined above, developers can have a better idea of how to integrate reliable, secure oracle data into their decentralized applications.
For additional context, explore the following guides:
