Understanding Band Oracle #2 — Requesting Data on BandChain

Preface

This article is the second part of a series in which we will explore how Band Protocol’s oracle system operates and its constituents.

The series consists of three main components:

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

A data request to BandChain’s oracle can be made in two ways:

We will cover how to actually use these two methods later in the article. First, let’s go over what actually happens on the BandChain decentralized oracle network when a data request is made.

Data Request Flow

When someone makes a request to BandChain’s oracle, they need to specify the following parameters:

• the oracle script ID they want to call
• the parameters to be used in the oracle script specified
• the number of validators they wish to respond to the request
• the minimum number of validators required to respond to qualify as a successful request

Once they’ve made the request specifying the above parameters and the associated transaction is confirmed on BandChain, the requested oracle script will begin its execution.

The flow after this point can then be split into two sections:

1. fetching the data from the data sources (preparation phase)
2. aggregating the request’s results onto Bandchain (aggregation phase)

Fetching Data from the Specified Data Sources

First, the oracle script’s preparation function will emit the set of data sources necessary to fulfill the request. The validators, that were chosen based on a randomized stake-weighted algorithm to respond to the request, will then inspect the data requests and execute the associated data sources' procedures as instructed by the request.

Specifically, each of the chosen validators will attempt to retrieve information from all of the data sources specified in the executed oracle script, improving resistance to manipulation through multiple redundancies. The validators that successfully retrieved data from all the sources will then submit a raw data report, containing the results they retrieved, to BandChain. If enough validators successfully submit these reports, BandChain will begin executing the oracle script’s aggregation phase.

Aggregating the Request Results onto BandChain

The aggregation phase begins by aggregating all of the validators’ reports into a single result. This final result is then permanently stored in BandChain’s application state. Once stored, the result becomes available on the chain’s state tree and can be sent to other blockchains.

When the final result is successfully stored, an oracle data proof is also produced. This proof is a Merkle proof that shows the existence of the final result of the data request as well as other related information (oracle script hash, the parameters, the time of execution, etc.) on BandChain.

This proof can then be used by smart contracts on other blockchains to verify the existence of the data on BandChain as well as to decode and retrieve the result stored. Both of these can be done by interacting with our lite client, which will explain in the next and final part of this series.

Making a Data Request

As mentioned above, there are two main ways of requesting data from BandChain; through the CosmoScan or using the BandChain.js package.

Requesting Data via CosmoScan

The first way of submitting a data request is through BandChain’s provided explorer.

To do so, go to https://guanyu-devnet.cosmoscan.io. There you will find our devnet explorer with information on BandChain. From there, navigate to the Oracle Scripts tab on the top left corner.

On the oracle script page, you will see a list of all of the oracle scripts currently available on BandChain. BandChain’s Devnet comes with many pre-defined oracle scripts, which you can explore the spec on the left-hand sidebar of this documentation. In this walkthrough, we’ll experiment using the Yahoo stock price oracle script.

On the oracle script’s page, you will see various tabs containing information related to the script, including:

• its execution parameters
• its Owasm code
• its Bridge code to encode and decode the script’s input and output structs
• a history of all the requests that were made to this script
• a history of all of the revisions made on this script

We will proceed with execute tab to create our first data request to BandChain.

Under Execute tab, we can specify the execution parameters for our request. In this case, we will specify GOOGL (Google stock ticker) as the symbol and 1 as the multiplier.

Once we have input the parameters, we then hit the Request button. The explorer will take care of sending the message to BandChain.

Once the validators have retrieved the information and the final result is stored on BandChain, the explorer will show the transaction hash of the request, the final result (1420), as well as the proof of validity.

Requesting Data via BandChain.js Library

Alternatively, instead of manually making the requests using the explorer, a data request can also be made using the provided BandChain.js NodeJS library. This allows developers to submit data requests right from their dApp client.

Once BandChain has successfully executed the requested data request and oracle script, it will return the data and proof payload back to the client to then be passed to your smart contracts.

To show an example requesting data using the library, we will write a simple Node file that queries the current Google stock price (GOOGL) from BandChain. The full code is shown below.

Let’s go through each section of the code.

Importing the Required Libraries

The example code requires two libraries

• @bandprotocol/obi.js: a helper library to assist us when encoding/decoding data to/from Band Protocol's OBI standard
• @bandprotocol/bandchain.js: the library that we'll be using to make the queries to BandChain

Setting the Request Parameters

Here we set the values that we will be using to make the request

• endpoint: the endpoint we will make the query to
• mnemonic: the mnemonic we will use to make the query. The associated account must have a balance to make a request
• oracleScriptID: the ID of the oracle script that we will be executing to retrieve the data
• minCount: the minimum number of BandChain's validators that responds for us to consider the request successful
• askCount: the maximum number of validators that we want to respond to the request
• gasAmount/gasLimit: transaction gas config

Instantiating the Necessary Variables and Objects

After we have declared the base variable we need, we can begin to make the request.

We begin by creating a new bandchain class object from the specified endpoint variable. The BandChain class contains the necessary functions we'll need to make the request.

We then retrieve information related to the oracle script we want to execute to get the requested data.

Following that, we create a new obi object that we will use to decode the result we receive from BandChain.

Making the Oracle Request and Getting the Results

Finally, we execute the submitRequestTx member function of the previously created bandchain object to make the oracle data request.

We can then do one of two things with regards to this request:

• Call getRequestResult, as we did here, to get the actual result of the request
• Call getRequestProof to get the proof bytes associated with the request

Both of these functions take in one argument, the requestID of the request you want to retrieve the result/proof from.

If the query is successful, the code should print a value similar to:{ px: 91795049n }.

Wrapping Up

This article aims to provide an overview of the process when a data request is made to BandChain’s oracle. In the next and final part of this series, we will explore BandChain’s lite client verification mechanics used for cross-chain compatibility, and how the data requester can verify the validity of the results they received.

For the most updated and detailed instructions on how to make requests on BandChain and how to use the results in your smart contract, please see our developer documentation.

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