Oracle network

Autonity oracle network: the role of oracles, the functions they perform, and their lifecycle

Overview

This section describes the oracle protocol, the role of validators in providing and agreeing median price data, and the lifecycle for oracle voting and currency pair management.

Autonity provides consensus-computed median price data for selected currency pairs as an L1 platform feature. The submission of price data for aggregation and voting is a validator responsibility and executed according to an oracle protocol. As consequence, validator nodes form an oracle network. When serving as a member of the consensus committee, validators must submit raw price data reports for currency pairs on-chain, and participate in the oracle protocol to agree an aggregated median price for the submitted price data in discrete voting rounds using a commit and reveal protocol. As voting rounds complete, the aggregated median price data computed and provided by the Autonity network is updated. As an epoch ends the set of oracle voters changes to accord with new consensus committee membership.

In the oracle protocol a validator has responsibilities to:

• Source raw price data for selected currency pairs from one-or-more external data sources off-chain.
• Provide price data reports as input for the computation of aggregated median price data for currency pairs during oracle voting rounds.
• Vote for aggregated median price data for currency pairs during oracle voting rounds.
• Maintain the set of symbols for which raw price data is provided by the validator oracle, revising as required if the connected Autonity network updates its selected set of currency pairs.

Oracle prerequisites

To operate as a validator node the operator must operate Autonity oracle server software as an adjunct to its Autonity full node software.

Prerequisites for participating in the oracle network as a validator node operator are:

• An Autonity Go Client full node installation, joined to an Autonity network.
• An Autonity Oracle Server installation, configured to connect to your full node and external price data sources via plugin adaptors.
• Plugin adaptors for connecting to external data provider sources to retrieve price data for the currency pairs required for your node’s connected Autonity network.

Oracle identity, accounts and keypairs

The oracle server makes use of a single account and private/public key pair for oracle identity, oracle protocol participation, and cryptographic security.

Oracle server key

The private/public key pair of the oracle server node.

The private key is used:

• By an oracle server for submitting price report transactions to the Oracle Contract on-chain.
• To generate the proof of enode ownership required for validator registration. The proof is generated with the oracle server private key and the validator’s p2p node key using the genOwnershipProof command-line option of the Autonity Go Client.

The public key is used:

• To derive an ethereum format account that is then used to identify the oracle server. See oracle identifier.
• As the msg.Sender address used by the oracle server to submit transactions for oracle price report submissions by function call to the Oracle Contract on-chain.

Oracle identifier

A unique identifier for the Autonity Oracle Server used as the oracle identity in validator registration, where it is provided as an oracleAddress parameter.

The identity is created as an ethereum format account address, generated by the entity operating the oracle server as part of the deployment process. It provides an unambiguous relationship between oracle server identity and the associated validator node for which the oracle server is a data provider.

Note

The oracle identifier is stored in the oracleAddress field in the Validator data struct maintained in state.

Note that this identifier is the oracle server’s on-chain identity and is distinct from the nodeAddress which is the validator node identifier, and the treasury account which is the validator operator’s account. The identifier may be referred to as the oracle account.

Oracle network

Validator nodes must participate in the oracle protocol when serving as a member of the consensus committee.

This results in a logical ‘oracle network’ of validator-operated oracles responsible for sourcing price data, submitting price reports on-chain, and participating in voting rounds to agree on aggregated median prices for the currency pairs provided by an Autonity network.

Oracle protocol

The computation of median price data is governed by protocol logic and rules. The protocol has off- and on-chain operations. Price data is collected from external data providers by oracle servers run by validator operators and submitted on-chain to an oracle contract that computes aggregate median price data in voting rounds. Validators are responsible for providing source data from off-chain and voting to agree a median price on-chain when members of the consensus committee.

The protocol computes median price by aggregation:

• Off-chain aggregation. Oracle Server’s collect source price data for currency pairs from one or more sources. If data is taken from multiple sources, then aggregation is performed to consolidate price data into a standardised report format. This price report (or price data ‘sample’) is then pushed to the Oracle contract via a transaction submitted from the oracle server account.
• On-chain aggregation. The Oracle contract aggregates the supplied price data reports to compute a reference exchange rate data through a voting mechanism using a commit-reveal protocol in voting rounds.

The commit and reveal scheme is applied for security in price voting and results in a round lag between oracle price updates.

Voting rounds

To coordinate the submission of source price data reports and computation of median price in the oracle network, oracle voting on median price computation takes place in voting rounds run over a fixed duration of blocks, the voting period (the duration in blocks of which is set as the protocol parameter votePeriod).

In the last block of each vote period the Oracle contract issues a NewRound event. The round event provides a tuple of round ID, block number, block timestamp, and vote period, which tells the oracle server that on the round with that ID a price report for that timestamp is required for submission by the oracle server. The block number indicates the block height at which the new round begins, while the vote period is the length measured in blocks of the new round.

The oracle server uses the metadata to estimate and manage data sampling for submission to the new round. The oracle server initiates a data sampling window 5 seconds before the required timestamp. It pre samples data from its configured data sources throughout the window range, then submits a price data report - i.e. ‘vote’ - as close as possible to the required timestamp.

Voter selection

Oracle voters are selected from the current consensus committee and are kept in sync with consensus committee changes by protocol as the committee changes with new epochs.

Voters are allowed to vote once each round. If a validator leaves the consensus committee then their vote is discarded; if a validator joins the consensus committee then their first vote is not taken into account.

Commit and reveal

A commit and reveal protocol is used for price voting. In each round the oracle voter submits a vote transaction providing:

• _commit: a cryptographic hash of the new price report submitted for the round
• _reports: a reveal of the price report submitted for the previous round
• _salt: a salt value used to generate the previous round’s commitment

Protocol then uses the salt to verify the previous round’s commit matches the reveal for that commit provided by the voter in the current round. This introduces a time lag in oracle price updates: prices are submitted in round 1, revealed during round 2, with median price data computed at the end of round 2.

To exemplify oracle frequency of new median price data publication from genesis in a scenario of vote period set to 30 blocks:

Time (Block Height)	Event
Genesis	Network genesis; initiation of first oracle voting round: R1
Block 1...29	Oracle voters submit price report vote, providing commit; reveal and salt null.
Block 30	R1 voting round ends. No previous round so no commits to reveal and no valid price submissions for median price computation for R1. New Round event emitted for R2.
Block 31	New Round begins: R2
Block 31...60	Oracle voters submit price report vote, providing commit for R2; reveal and salt for R1.
Block 60	R2 voting round ends. Commit and reveal; median price round data computed for R2. New Round event emitted for R3…

Note

If an oracle fails to vote in a round, or the reveal does not match the past commit, then the oracle voter is recorded as submitting an invalid price for the round.

Currency pair management

The currency pair symbols for which the oracle network provides price data is set at network genesis in the genesis configuration file in the symbols field; see config.oracle object.

The currency pair symbols set for a network can be returned by a contract call using the getSymbols() function.

The pairs can be updated post-genesis by a governance-only function, `setSymbols().

Note that if currency pair symbols are changed there is a 2-round delay in applying the change after the symbol update round. This is because of the commit and reveal process for submitting and revealing price reports: oracles send commits for the new symbols in “symbol updated round + 1” and reveals for the new symbols in “symbol updated round + 2”.

To exemplify:

Time (Block Height)	Event
Genesis	Symbols set in network genesis configuration
Round n - symbol updated round	Governance operation to update symbols. setSymbols function called and a NewSymbols event is emitted logging the new currency pair symbols and the round number at which oracles must begin providing price report submissions for the new symbol set - i.e. current round +1. Oracles provide commits and reveals for the old pre-update symbol set.
Round n+1	Oracles submit commits for the new symbol set and reveals for the old symbol set
Round n+2	Oracles submit commits and reveals for the new symbol set

Oracle data consumers

Primary consumers of oracle data are:

• Auton Stabilization Mechanism
• Smart contracts deployed on the Autonity L1 network can access median price data via the oracle contract interface.

Oracle economics

Participation in the oracle network is a validator responsibility and receives no specific reward beyond transaction fees for submitting oracle price vote transactions to the oracle contract. For validator revenue, see Validator economics in the validator concept page.

Transaction fee refund

Oracle transactions are refunded if successfully committed.

The oracle account must be funded with a seed balance to cover at least one voting transaction.

The validator is registered and eligible for selection to the consensus committee.

Note

Limiting the oracle vote transaction to 1 each Round prevents the refund funding a spam attack vector in a Byzantine behaviour scenario. Once 1 vote transaction from an oracle account has been successfully processed, any further vote transactions from that oracle account during the round are reverted.