oracle

Abstract

This document specifies the oracle module, which allows to to store data from external sources based on the specified documents.

This module is responsible for managing oracle data in the blockchain. It provides functionality for registering, updating, and managing oracle request documents, as well as submitting and aggregating oracle data.

Contents

1. Concepts
2. State
3. Begin Block
4. Keeper
5. Hooks
6. Events
7. Params
8. Client
9. Oracle Daemon

Concepts

Oracle module is used to store/update the external data through Oracle Daemon (oracled) and aggregate the data based on the registered documents and rules.

Oracle Data Aggregation

The x/oracle module allows to register documents to enable retreiving external data. Each oracle document includes rules and information needed for reading and parsing the external data. The result from document execution will be stored in KV store as oracle data.

When registering a new document, the oracle module allows to register more than one endpoints to retreive the data. one of the result of all endpoints will be saved to store according to the aggregation rules.

Aggregation Rules

The x/oracle module supports these aggregation rules:

• AGGREGATION_RULE_AVG: Calculate the average of all submitted values
• AGGREGATION_RULE_MIN: Use the minimum value from all submissions
• AGGREGATION_RULE_MAX: Use the maximum value from all submissions
• AGGREGATION_RULE_MEDIAN: Calculate the median of all submitted values

Moderator

The x/oracle module requires a registered moderator address withing the genesis state.

• Only the moderator can register and update oracle request documents.
• Only authorized accounts can submit oracle data.
• Only the current moderator can update the moderator address.

State

The x/oracle module keeps the state variables needed for oracle reteiving external data.

	Description	Key	Value	Store
ModeratorAdress	module moderator address	[]byte{2}	[]byte{string}	KV
OracleRequestDocuments	oracle request documents	[]byte{3}	[]byte{OracleRequestDoc}	KV
OracleRequestDocumentCount	oracle document counter	[]byte{4}	[]byte{uint64}	KV
OracleData	oracle data	[]byte{5}	[]byte{OracleData}	KV
OracleDataSets	oracle data sets	[]byte{6}	[]byte{OracleDataSet}	KV

Begin Block

Oracle data sets are aggregated at the beginning of each block.

In case the Oracle Data is updated, the aggregator calls the Hook which allows the external modules to update their state based on the updated data.

Keeper

The x/oracle module provides this exported keeper that can be passed to other modules, which require access to oracle data

type Keeper interface {
    GetParams(ctx sdk.Context) types.Params
    GetModeratorAddress(ctx sdk.Context) string
    GetOracleRequestDocCount(ctx sdk.Context) uint64
    GetOracleRequestDoc(ctx sdk.Context, id uint64) (*types.OracleRequestDoc, error)
    GetOracleRequestDocs(ctx sdk.Context) []*types.OracleRequestDoc
    GetOracleRequestDocsByStatus(ctx sdk.Context, status types.RequestStatus) []*types.OracleRequestDoc
    GetSubmitData(ctx sdk.Context, requestId uint64, nonce uint64, provider string) ([]*types.SubmitDataSet, error)
    GetSubmitDatas(ctx sdk.Context, requestId uint64, nonce uint64) ([]*types.SubmitDataSet, error)
    GetDataSet(ctx sdk.Context, requestId uint64, nonce uint64) (*types.DataSet, error)
}

Hooks

The x/oracle module provides a hook for external modules to react oracle events:

• AfterOracleEnd: Called after an oracle data set is completed

Events

The x/oracle module emits the following events:

BeginBlocker

Type	Attribute Key	Attribute Value
complete_oracle_data_set	request_id	{requestId}
complete_oracle_data_set	nonce	{nonce}
complete_oracle_data_set	raw_data	{aggregatedValue}
complete_oracle_data_set	block_height	{blockHeight}
complete_oracle_data_set	block_time	{blockTime}

MsgRegisterOracleRequestDoc

Type	Attribute Key	Attribute Value
register_oracle_request_doc	request_id	{requestId}
register_oracle_request_doc	oracle_type	{oracleType}
register_oracle_request_doc	name	{name}
register_oracle_request_doc	description	{description}
register_oracle_request_doc	period	{period}
register_oracle_request_doc	account_list	{accountList}
register_oracle_request_doc	endpoints	{endpoints}
register_oracle_request_doc	aggregation_rule	{aggregationRule}
register_oracle_request_doc	status	{status}
register_oracle_request_doc	nonce	{nonce}

MsgUpdateOracleRequestDoc

Type	Attribute Key	Attribute Value
update_oracle_request_doc	request_id	{requestId}
update_oracle_request_doc	oracle_type	{oracleType}
update_oracle_request_doc	name	{name}
update_oracle_request_doc	description	{description}
update_oracle_request_doc	period	{period}
update_oracle_request_doc	account_list	{accountList}
update_oracle_request_doc	endpoints	{endpoints}
update_oracle_request_doc	aggregation_rule	{aggregationRule}
update_oracle_request_doc	status	{status}
update_oracle_request_doc	nonce	{nonce}

MsgSubmitOracleData

Type	Attribute Key	Attribute Value
submit_oracle_data	request_id	{requestId}
submit_oracle_data	nonce	{nonce}
submit_oracle_data	raw_data	{aggregatedValue}
submit_oracle_data	from_address	{msgSender}

MsgUpdateModeratorAddress

Type	Attribute Key	Attribute Value
update_moderator_address	moderator_address	{newModeratorAddress}

Params

The x/oracle module contains the following parameters:

Key	Type	Default Values	Description
EnableOracle	bool	true	enable/disable the roacle module
SubmitWindow	uint64	3600	window in seconds to submit oracle data
MinSubmitPerWindow	LegacyDec	1.0	minimum number of submission per window
SlashFractionDowntime	LegacyDec	0.01	percentage of slash for downtime

Client

CLI

A user can query and interact with the oracle module using the CLI.

Queries

The query commands allow users to query oracle state.

Command	Subcommand	Description
query oracle	params	Get module params
query oracle	request-doc [request-id]	Get oracle request doc by id
query oracle	data [request-id]	Get oracle data by request id
query oracle	submit-data [request-id] [nonce] [provider-account]	Get oracle data by request id
query oracle	request-docs [status]	Get documents list
query oracle	moderator-address	Get current moderator address

Params

The params command allows users to query the params.

gurud query oracle params [flags]

Example:

gurud query oracle params ...

Example Output:

enable_oracle: true
min_submit_per_window: "1.000000000000000000"
slash_fraction_downtime: "0.010000000000000000"
submit_window: "3600"

RequestDocs

The request-docs command allows users to query the registered all documents and the registered documents by status.

Request Statuses

The Oracle module supports the following statuses for oracle requests:

Constant	Value	Description
REQUEST_STATUS_UNSPECIFIED	0	Default value, should not be used
REQUEST_STATUS_ENABLED	1	Request is enabled
REQUEST_STATUS_PAUSED	2	Request is paused
REQUEST_STATUS_DISABLED	3	Request is disabled

gurud query oracle request-docs [STATUS] [flags]

Example:

gurud query oracle request-docs ...
gurud query oracle request-docs 1 ...

RequestDoc

The request-doc command allows users to query the registered documents by request id.

gurud query oracle request-doc REQUEST_ID [flags]

Example:

gurud query oracle request-doc 1 ...

Data

The data command allows users to query the oracle data by request id.

gurud query oracle data REQUEST_ID [flags]

Example:

gurud query oracle data 1 ...

SubmitData

The submit-data command allows users to query the oracle submit data by request id, nonce and provider account.

gurud query oracle submit-data REQUEST_ID NONCE ADDRESS [flags]

Example:

gurud query oracle submit-data 1 1 guru1cml96vmptgw99syqrrz8az79xer2pcgpawsch9 ...

ModeratorAddress

The moderator-address command allows users to query the current moderator address.

gurud query oracle moderator-address [flags]

Example:

gurud query oracle moderator-address ...

Example Output:

moderator-address: guru1gzsvk8rruqn2sx64acfsskrwy8hvrmaf6dvhj3

Transactions

The tx commands allow the users to change the oracle state.

Command	Subcommand	Description
tx oracle	register-request [path/to/request-doc.json]	Register new pracle request doc
tx oracle	update-request [path/to/request-doc.json] [reason]	Update update existing request
tx oracle	submit-data [request-id] [nonce] [raw-data]	Submit oracle data
tx oracle	update-moderator-address	Change the moderator address

RegisterRequest

The register-request command allows the moderator to register new oracle document.

gurud tx oracle register-request PATH_TO_REQUEST_DOC_JSON [flags]

Example:

gurud tx oracle register-request ./request-doc.json --from moderator_address ...

Example request-doc.json:

{
    "Oracle_Type": 1,
    "Name": "GURU Price Info",
    "Description": "Pricing information for setting min_gas_price",
    "Period": 10,
    "Account_List":[
            "guru1cml96vmptgw99syqrrz8az79xer2pcgpawsch9",
            "guru1jcltmuhplrdcwp7stlr4hlhlhgd4htqhtx0smk",
            "guru1gzsvk8rruqn2sx64acfsskrwy8hvrmaf6dvhj3"],
    "quorum": 2,
    "endpoints": [
        {
            "url": "https://api.coinbase.com/v2/prices/GXN-USD/spot",
            "parse_rule": "data.amount"
        },
        {
            "url": "https://api.upbit.com/v2/prices/GXN-USD/spot",
            "parse_rule": "data.amount"
        }
    ],
    "Aggregation_Rule": 1,
    "Status": 1
}

UpdateRequest

The update-request command allows the moderator to update existing oracle document.

gurud tx oracle update-request PATH_TO_REQUEST_DOC_JSON REASON [flags]

Example:

gurud tx oracle update-request ./request-update-doc.json removing_outdated_endpoint  --from moderator_address ...

Example request-update-doc.json:

{
    "Oracle_Type": 1,
    "Name": "GURU Price Info",
    "Description": "Pricing information for setting min_gas_price",
    "Period": 10,
    "Account_List":[
            "guru1cml96vmptgw99syqrrz8az79xer2pcgpawsch9",
            "guru1jcltmuhplrdcwp7stlr4hlhlhgd4htqhtx0smk",
            "guru1gzsvk8rruqn2sx64acfsskrwy8hvrmaf6dvhj3"],
    "quorum": 2,
    "endpoints": [
        {
            "url": "https://api.coinbase.com/v2/prices/GXN-USD/spot",
            "parse_rule": "data.amount"
        }
    ],
    "Aggregation_Rule": 1,
    "Status": 1
}

SubmitData

The submit-data command allows the authorized accounts to submit data by request id.

gurud tx oracle submit-data REQUEST_ID NONCE RAW_DATA [flags]

Example:

gurud tx oracle submit-data 1 1 1.5 --from moderator_address ...

UpdateModerator

The update-moderator-address command allows the moderator to change the current moderator address.

gurud tx oracle update-moderator-address NEW_MODERATOR_ADDRESS [flags]

Example:

gurud tx oracle update-moderator-address guru1gzsvk8rruqn2sx64acfsskrwy8hvrmaf6dvhj3 --from moderator_address ...

Oracle Daemon

The oracled is a client service that is integrated with the x/oracle module.

This is an external client service, that runs alongside the Guru chain. When the x/oracle module is enabled, the oracled reads through registered documents and data update rules. When the condition is met, the oracled makes an external request to the registered sources, parse that data and update the x/oracle module state though MsgSubmitOracleData.