Note: this article is scheduled to be published on Friday July 10th 2020 at 5 PM
This article is part of a technical series in which we will explore how Band Protocol's decentralized oracle network architecture operates. The series will consist of three segments:
1. Data Sources and Oracle Scripts
We will explore the two main components of Band's oracle system; data sources and oracle scripts. Specifically, we will define the two concepts as well as going over how they relate and operate interdependently with each other.
2. Requesting Data on BandChain
Once we have defined what data sources and oracle scripts are, we will examine the actual flow that occurs when someone submits a data request to BandChain and how the two components fit in. This section will cover both the individual processes that make up the flow and how anyone can make such requests permissionlessly with no barrier to entry.
3. BandChain Lite Client Verification
Finally, to tie everything together in the Understanding Band Oracle series, we will explore how data can be sent from BandChain to be used and verified in other blockchains. In particular, we will explore the process that makes up BandChain's lite client verification protocol and how a data requester can use it to verify the validity of the result they received from BandChain.
Band Protocol is building a protocol that enables our users to create highly secure and reliable decentralized applications trustworthy decentralized applications. There are three main components necessary for building the decentralized oracle network:
- a trusted data source in which to acquire the data needed for the application
- a trusted platform that will handle the data requests and any data processing required
- a trusted set of smart contracts to make use of the data
Given the above, our aim for this set of articles is to provide an overview of BandChain's oracle protocol and how our solution weaves the first two key components to power decentralized applications above.
In this first article in the series, we will be outlining Band's solution to the first requirement: building trusted sources of data. Specifically, on the BandChain oracle network, this solution comprises of two components: data sources and oracle scripts.
Data sources are the most fundamental units in BandChain's oracle system. At the simplest level, it is an executable that describes the procedure to retrieve raw data points from a set of primary sources. These primary sources can either be a traditional API or any other source that returns the desired result.
It is important to note that during phase 1, only permissionless and free API will be supported. As we move into phase 2, we will be supporting additional paywall and private APIs, where we will introduce an automated and seamless fee collection service for data sources providers to generate revenue.
As the data sources have no access restrictions in phase 1, this means that they are openly available to anyone who might want to audit the data source, any subsequent oracle scripts that depend on it, or the actual application that requests the oracle script itself. This openness helps build the trustworthiness of each of those components, which is ultimately what we're looking to do.
Band Protocol works closely with all data source owners, including ones that are open, private, and under paywalls to ensure high quality of data, 100% uptime and unlimited access for anyone looking to integrate Band oracles.
To better explain what data sources are, let's look at two possible examples.
First, let's look at a data source that queries CoinGecko for the current price of a cryptocurrency. The script itself is written in Python and expects one argument: the symbol of the currency to query.
https://gist.github.com/e4e3fe21e5b13a15a1e1f67a90c4de3a
However, as mentioned above, the primary source used in a data source does not need to be an API endpoint. Instead, it can be any artifact that returns a value.
In addition, as a data source is simply an executable that is called to retrieve some desired result, it can be written in any programming language that the executable runner's machine can run.
The example below, written in Bash, gives an example of such a script. Instead of querying the API like in the first example, it instead calls getent to resolve a hostname to an IP address.
https://gist.github.com/0b30f609af0094303d8e27f24f2a4388
For more data source examples, please refer to the ones available on our devnet. Some of these includes:
- Current stock prie (link)
- Current oil price (link)
- Retrieving weather data (link)
- Quantum Random Number Generator (link)
- CS:Go match result (link)
When someone wants to request data from BandChain's oracle, they do not interact or call the data sources directly. Instead, they call the corresponding oracle script, which then proceeds to execute the necessary data sources. The reason for this decoupling of data source and oracle script is threefold.
First, this design reduces the amount of data required to be stored on BandChain. Also, expensive computations can be performed off-chain, helping to mitigate dependencies or limitations from any layer-1 blockchain.
Second, this design allows data sources to be reused. Different oracle scripts can have different purposes while having some data sources in common. This reusability promotes modularity in the data sources, allowing them to be modified and upgraded independently of the oracle script.
Lastly, in Phase 2, the decoupling of the data source and oracle script will allow data source owners of permissioned APIs to collect fees irrespective of the oracle script or DApps that use it.
The oracle scripts itself is an executable program that encodes two pieces of data:
- the set of data requests to the sources it needs
- the way to aggregate the raw data reports into the final results
The sources mentioned above can be any data sources published on the network. Oracle scripts themselves are Turing complete and can be written in any programming language that supports compilation into WebAssembly code. This composability and Turing-completeness make oracle scripts very similar to smart contracts.
An oracle script's execution flow can be broken down into two main phases: preparation and aggregation.
In the preparation phase, the script outlines the data sources that are required for its execution. It then sends out a request to BandChain's validators to retrieve the result from those data sources. The contents of this request consist of the data sources' execution steps and the parameters required by said data sources.
In the second phase, the oracle script then aggregates all of the data reports returned by the validators. Each report contains the values the validator received from the said data sources. The script then proceeds to combine those values into a single final result.
Note that the specifics of the aggregation process is entirely up to the design of the oracle script. BandChain does not enforce any regulations regarding the aggregation method used and entirely leaves that design decision to the creator of the script.
For more information on oracle scripts and its execution, please refer to the corresponding page on our wiki.
https://gist.github.com/f442a93531304a7410634ca5bbd4b3d4
The code above shows an example of an oracle script. This oracle script aims to query the 24-hour trading volume of a cryptocurrency, according to CoinGecko, given the token's symbol.
The code itself can be broken down into three main sections:
- Importing the required libraries
- Defining the script's input and output parameters
- Defining the preparation and execution phases
Let's look at each of these sections in more detail.
https://gist.github.com/6c31ede43b88c41ad0d428ad9352a4d6
The script starts by importing the crates it will need. In this case, the script requires two crates; obi and owasm.
obi contains functions to work with BandChain's OBI standard. This standard defines the method to serialize and deserialize binary data in the BandChain ecosystem and will be used when working with the oracle script's inputs and outputs. For a more detailed explanation and the full standard specification, please see here.
Similarly, owasm defines methods to work with Band's Owasm Domain Specific Language (DSL) for writing oracle scripts. We will be using this crate to work with the results returned by BandChain's validators following a data request. Again, the full owasm specification can be found here.
https://gist.github.com/836847ec9a2f50eda8818e6a256b282f
This section defines the expected inputs and outputs of the oracle script. In this case, the scripts expect two input arguments; the symbol of the cryptocurrency to retrieve the volume and the multiplier to which to multiply the returned volume value. The oracle script is then defined to return one value, the 24H trading volume of the specified cryptocurrency, multiplied by the specified multiplier.
https://gist.github.com/08e98c9fd437a43a9011712747edfd07
This is where the majority of the oracle script logic is implemented. In this particular case, the preparation phase is implemented to make a request to BandChain's validators to retrieve volume data of the specified symbol.
The execution phase then simply calls ext's load_average method to calculate the mean value of the results returned by the validators that responded to the request. Lastly, it multiplies the computed average value by the specified multiplier and returns the result.
For a more detailed explanation of the helper methods used, please see the Owasm section of our wiki.
This article aims to serve as an introduction to understanding how BandChain's oracle works. For anyone looking to better understand how to use these data sources and oracle scripts to make data requests and how to use the returned result in your smart contracts or dApps, you might find our developer documentation helpful.
In the next article in the series, we will continue to explore our solution to the second component in our BandChain decentralized oracle network; a trusted platform that will handle the data requests. We will look at how the data sources and oracle scripts we defined here are used. Lastly, we will go over the flow that happens when someone makes a data request on Band's oracle and how to make those requests ourselves.