Understanding Band Oracle #1 — Oracle Scripts and Data Sources
Preface
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.
Introduction
Band Protocol is building a decentralized cross-chain data oracle that enables our users to create highly secure, reliable and 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
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 API will be supported. As we move into phase 2, we will be supporting additional private APIs, where we will introduce an automated and seamless fee collection service for data source providers to generate revenue.
Permissionless API 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 are looking to do.
Band Protocol works closely with all data source owners, whether they are public, private, or under paywalls to ensure high quality of data, 100% uptime, and unlimited access for anyone looking to integrate Band oracles.
Example Data Sources
To better explain what data sources are, let’s look at two possible examples.
CoinGecko Cryptocurrency Price Data
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 queried.
Resolve Hostname to IP addresses
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 supports.
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.
For more data source examples, please refer to the ones available on our devnet to get an idea of the type of data source we are working with our partners. Some of these includes:
Oracle Scripts
Data Source and Oracle Script Design
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. 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 play an important role. It allows data source owners of permissioned APIs to collect fees irrespective of the oracle script or DApps that use it.
Oracle Script Specification
The oracle script 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.
Oracle Script Execution Flow
An oracle script’s execution flow can be broken down into two main phases: preparation and aggregation.
1. Preparation Phase
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.
2. Aggregation Phase
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. Instead of a typical plain medianizer, dApps can specifically encode conditions such as data deviation rule to ensure all data points return stay within certain percentage deviation from each other, otherwise reverts transaction.
👉 For more information on oracle scripts and its execution, please refer to the corresponding page on our wiki.
Example Oracle Script
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.
Importing the Required Libraries
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 on our wiki.
Defining the Oracle Script’s Input and Output Parameters
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 multiply the returned volume value by. The oracle script is then defined to return one value, the 24H trading volume of the specified cryptocurrency, multiplied by the multiplier.
Defining the Preparation and Execution Phases
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.
Wrapping Up
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.
Any other contents you would like to see about Band Protocol, feel free to let us know!
About Band Protocol
Band Protocol is a cross-chain data oracle platform that aggregates and connects real-world data and APIs to smart contracts. Blockchains are great at immutable storage and deterministic, verifiable computations — however, they cannot securely access data available outside the blockchain networks. Band Protocol enables smart contract applications such as DeFi, prediction markets, and games to be built on-chain without relying on the single point of failure of a centralized oracle. Band Protocol is backed by a strong network of stakeholders including Sequoia Capital, one of the top venture capital firms in the world, and the leading cryptocurrency exchange, Binance.
Website | Whitepaper | Telegram | Medium | Twitter | Reddit | Github
