Native Oracle

Summary

Gameluk offers an Oracle module that supports asset exchange rate pricing for use by other modules and contracts. Validators are expected and required to participate as Oracles when validating for the network to ensure the most reliable and accurate pricing for assets.

During each voting window, a validator must provide asset pricing for the whitelisted assets. At the end of each voting window, the chain aggregates the votes and computes a weighted median based on validator voting power to determine the effective exchange rate for each asset.

Price Feeder

The validator must participate in providing pricing for the oracle to avoid penalties and legal consequences. A systemd service can be configured to run the oracle sidecar, providing a more reliable and customizable solution for asset price provision. The sidecar can be built with make install-price-feeder from the gameluk-chain repo dir, and needs an associated config file that specifies the account from which to send oracle votes along with additional configuration information such as assets to provide and providers to use for pricing information.

Example Config File

Validators must update the addresses keyring information and currency pairs to include assets whitelisted by the oracle module.

Below is an example of a systemd service file for running the oracle sidecar:

[Unit]
Description=Oracle Price Feeder
After=network.target

[Service]
User=root
Type=simple
Environment="PRICE_FEEDER_PASS={your keyring password for the oracle account here}"
# alternatively to `Environment`, validators can use `EnvironmentFile` to designate a file from which to get env var info
ExecStart=/root/go/bin/price-feeder /path/to/oracle/price_feeder_config.toml
Restart=on-failure
LimitNOFILE=6553500

[Install]
WantedBy=multi-user.target

Oracle Penalties

Validators will be penalized for non-participation or submitting bad data. Each validator has a miss count and an abstain count that is tracked. The abstain count tracks the number of voting windows in which the validator did not submit a vote. The miss count tracks the number of voting windows in which the validator's vote was improper, either because it contained data outside of 1 standard deviation or because it did not include asset prices for all whitelisted assets. A slash window is a period of blocks specified by oracle parameters. If the validator has too many misses and/or abstains across this window, they are slashed and jailed. This is because oracle integrity and freshness are treated as core chain services, and validators that do not participate in the upkeep of oracle asset pricing are penalized.

Misses and abstains both contribute to oracle penalization

Feeder Delegation

To run the oracle price feeder while signing from a different account, it is recommended to set up a feeder for your validator. This will allow the feeder account to perform oracle votes on behalf of the validator.

Example

gameid tx oracle set-feeder $FEEDER_ADDR --from $WALLET_NAME --fees 2000ugame --chain-id $CHAIN_ID

Queries

Actives

Returns the current active denoms for which there are exchange rates

# Query
gameid q oracle actives
# Example Response
actives:
- uatom
- ubtc
- ueth
- ugame

Exchange Rates

Returns the current exchange rates for supported assets. Optionally can query for a specific denom by entering it as an additional param.

# Query
gameid q oracle exchange-rates
# Example Response
- denom: uatom
  oracle_exchange_rate:
    exchange_rate: "10.813741474077133110"
    last_update: "7809045"
- denom: ubtc
  oracle_exchange_rate:
    exchange_rate: "28378.473894707711800815"
    last_update: "7806841"
- denom: ueth
  oracle_exchange_rate:
    exchange_rate: "1865.245279694096497292"
    last_update: "7809045"

TWAPs

Returns the time weighted average price for a given time interval in seconds. The maximum lookback is determined by oracle parameters.

# Query
gameid q oracle twaps $LOOKBACK_SECONDS
# Example Response
oracle_twaps:
- denom: uatom
  lookback_seconds: "12"
  twap: "10.820090685543308091"
- denom: ubtc
  lookback_seconds: "12"
  twap: "28356.159567933482758461"
- denom: ueth
  lookback_seconds: "12"
  twap: "1865.748268727863484183"

Vote Penalty Counter

Returns the penalty counter for a validator queried by validator address.

# Query
gameid q oracle vote-penalty-counter $VALIDATOR_ADDR
# Example Response
vote_penalty_counter:
  abstain_count: "40618"
  miss_count: "0"
  success_count: "0"

Params

Returns the current parameters for the oracle module

# Query
gameid q oracle params
# Example Response
params:
  lookback_duration: "3600"
  min_valid_per_window: "0.050000000000000000"
  reward_band: "0.020000000000000000"
  slash_fraction: "0.000100000000000000"
  slash_window: "201600"
  vote_period: "1"
  vote_threshold: "0.667000000000000000"
  whitelist:
  - name: uatom
  - name: ugame
  - name: ueth
  - name: ubtc