Skip to main content

The Tellor protocol stands out for its decentralized and permissionless design.  Beyond decentralization, Tellor offers flexibility in allowing users to request custom data. Yet, one aspect we’ve continually strived to improve is the decentralization of how we handle our data specifications or ‘dataSpecs’. These are currently hosted on GitHub, but now we are taking a significant leap towards a fully decentralized approach. Let’s dive deeper into what this change entails and why it’s crucial.


what are the data specs

In order for Tellor to provide flexibility and allow anyone to utilize the protocol, we developed a system of data specifications for defining “query types”.  A query type, like “SpotPrice” for example, contains a name, output type, and arguments like “asset” and “currency.” The hash of the query type and its elements form unique identifiers, or queryIds, for every Tellor data interaction, streamlining communication about specific data requests, reports, disputes, and retrievals.

Query types are defined in a repository known as DataSpecs. These documents act as the instruction manual for data requests, providing the extra layers of detail needed to satisfy a particular request for data. They define a query type name, its arguments, and its return values. They clarify the data types of the return values and what they mean. They may define which sources should be used for retrieving data, possible data transformations, and what factors should be considered in the event of a dispute. 

These definitions are meant to be read and interpreted by the human participants in the protocol. Given that these documents can be of arbitrary length and data storage on blockchains is expensive, it is not necessary or cost effective for these documents to be hosted on-chain. The most important thing is that they remain easily accessible for reading by protocol participants. They have long been hosted in a repository on github, and the tellor team is now in the process of transitioning them over to a system which consists of an on-chain registry of document hashes, and document hosting on IPFS.


why they are important

The tellor oracle depends on a variety of participants being in sync and appropriately playing their roles. Users who rely on oracle data need to be able to precisely define the data they require. Data reporters risk their stake each time they report some data, so they have to have some assurance that their stake is safe if they report correct data. Data validators need to know whether reported data is correct or not so they can decide whether to pay a dispute fee and dispute a given piece of data. In the case of a dispute, voters need to be able to determine whether the reported data is correct or not. 

The dataSpecs guide all of these tellor protocol participants and allow them to interpret a given data query, retrieve the appropriate information from the outside world, and determine what the correct answer should be. 


why decentralize them and how

The nature of the Tellor protocol is centered around decentralization, and this principle extends to our handling of the dataSpecs. These documents guide all Tellor stakeholders in playing their respective roles accurately and reliably. By decentralizing the dataSpecs, we ensure that they are readily available and resilient against manipulation.

A decentralized dataSpecs means that everyone knows where to find the dataSpecs definition for a particular query, and they can detect whether this document has been tampered with. This uniform access and transparency helps maintain a consistent understanding of the protocol across all parties.

Consider an alternative scenario where dataSpecs are hosted solely on GitHub. The risk here is multifold: GitHub may one day refuse to provide access to these documents, or it could show differing versions of the same document to different users. Such inconsistencies could lead to disruptions for the Tellor protocol participants and compromise the protocol’s reliability.

To uphold our commitment to decentralization, the Tellor team has implemented a novel approach. We’ve created an on-chain registry, linking a query type name with a document hosted on IPFS. This registry provides a verifiable history of each DataSpecs document, mitigating any chance of manipulation by a single party for personal gain.

Our strategy optimizes accessibility and transparency without compromising cost-efficiency. The on-chain registry, held in a smart contract, allows everyone to locate and monitor changes to the DataSpecs, while hosting only the IPFS document hashes on-chain leverages gas savings from not storing the entire document on-chain.

The beauty of IPFS lies in the fact that documents are addressed by their hashes. Any changes to a document necessarily alters its hash, which must then be updated on-chain. This system inherently provides an audit trail, safeguarding the integrity of our protocol.


soft consensus and limits of the dataSpecs

Soft consensus refers to people deliberating and interpreting to come to a subjective understanding, and it acts as an important force in the crypto space. It often involves a shared understanding of values held by protocol participants which cannot be hardcoded directly into the protocol’s code. For example, soft consensus serves as a backstop for Ethereum validators acting badly. If Ethereum validators as a whole begin censoring particular transactions, the Ethereum community has the option of forking the chain, slashing the censoring validators’ stakes, and continuing with only the validators who have not been censoring transactions. In this scenario, there are two versions of Ethereum, and everyone in the world has the choice of valuing and using either version. In that way, the Ethereum community upholds its values and prevents actions that go against these values. The fact that this possibility exists may act as a credible threat to help ward off censoring validators

The validity of Tellor data is maintained by soft consensus as well.  For this reason, it is often recommended to leave some room for subjectivity when defining a query type. As opposed to defining a SpotPrice as “the current average price on exchanges A, B, and C”, a more robust spec may define a SpotPrice as “the current average price”. Sometimes exchanges get manipulated, or their APIs break or return bad data. A given large exchange may cease to exist tomorrow. Relying on soft consensus and leaving some room for interpretation helps a protocol maintain access to its expected data in a subjective changing world. 


edge cases and examples

The dataSpecs provide guidance for all Tellor stakeholders to know how to act. Because the validity of Tellor data is enforced by soft consensus, the data can be adapted in a complex changing world. If the price of ETH/USD for example gets manipulated on a few big exchanges, but the “real” price is something else, Tellor’s social consensus can be used to adapt to this situation and help ensure that the real price is provided. 

Another edge case might be a scenario where the validity of a data point is disputed because of a temporary glitch or error in a data source. Suppose an exchange experiences a momentary downtime, resulting in a price spike that doesn’t reflect the actual market conditions. Rigid middleware oracles might treat this aberration as legitimate data, but Tellor’s system allows for a more nuanced response. The community can recognize the glitch for what it is and decide not to include the anomalous data in their responses.

Alternatively, if some query type “QueryTypeA” is created and actively used by a few protocols, and then the query type creator maliciously updates the dataSpecs document for QueryTypeA in order to manipulate those protocols, Tellor’s stakeholders may choose to continue using the original query type definition to ensure that those protocols keep functioning as expected. In this sense, the dataSpecs act as a guide for finding that soft consensus, but there are still higher values that Tellor stakeholders can strive for.



In our exploration of the Tellor protocol and the intrinsic value of DataSpecs, it’s evident that decentralizing the dataSpecs is an important step in limiting any central point of control from the Tellor protocol. By intertwining on-chain registries with IPFS, and emphasizing the irreplaceable role of DataSpecs in guiding protocol participants, Tellor not only champions an environment of trust and clarity but also establishes a blueprint for the decentralized future we’re all striving for.