The off-chain reporting protocol

✏   ✂ 2024-01-30

Abstract

This article is a high-level overview of the Off-Chain Reporting protocol (ocr) powering most of Chainlink products. The protocol allows a group of n nodes called oracles, up to f of which could be byzantine (f < n⁄3), to agree on a data point and record it on a blockchain supporting smart contracts (e.g., Ethereum).

Protocol components

All ocr deployments have two parts with different execution models: the on-chain part, implemented as a smart contract called the aggregator, and the off-chain part, implemented as a peer-to-peer network of oracles. The off-chain communication protocol, in turn, consists of three sub-protocols layered on top of one another: the pacemaker, the report generation, and the transmission protocols.

The aggregator contract

The aggregator contract is deployed on the blockchain and serves multiple roles:

  1. It stores the oracle network configuration, such as public keys of nodes participating in the protocol and report generation parameters.
  2. It records the oracle network’s reports on the blockchain and makes them available to other smart contracts.
  3. It distributes rewards to the oracles signing and transmitting reports.

The contract owner has administrative privileges, such as adding or removing nodes from the network, changing billing settings, and updating the report generation configuration.

Pacemaker

The pacemaker algorithm of the ocr protocol periodically assigns a node to be a leader coordinating the rest of the protocol functions. The period between two consecutive leader assignments is called an epoch. Within each epoch, the leader initiates rounds of the report generation algorithm. The tuple (e, r), where e is the epoch number and r is the round number, serves as a logical clock for the protocol.

Leader rotation in the pacemaker algorithm. Note that the leader is also a follower.

The protocol can advance the epoch in two circumstances:

  1. The current epoch duration exceeded the configured time amount.
  2. The protocol didn’t progress for the configured time amount.

The function mapping epoch numbers to leader nodes is a cryptographic pseudo-random function parameterized by a secret key (called the seed key) known only to the oracles. Thus, oracles know the exact sequence of all leader assignments in advance, but to all outside observers, the assignments are indistinguishable from random.

Report generation

The report generation algorithm produces a data point for the aggregator contract. For example, if the aggregator contract records an asset price in usd, the algorithm produces a price that faulty oracles can’t manipulate.

First, the leader initiates a new round by picking a query describing the task the followers need to execute and sending it to all the followers.

The followers execute the query (usually by observing an external data source) and send a signed observation back to the leader. In the asset price example, the observation will be their guess of the asset price.

If the leader receives at least 2f+1 observations, it distributes these signed (or attributed) observations among the followers.

Next, the followers distill attributed observations into a report, sign it, and send it to the leader. In the asset price example, the report is the median price. The observation aggregation function must consider any f out of at least 2f+1 observations untrustworthy for the protocol to be byzantine-fault-tolerant. For example, the asset price application must not pick one of the top or bottom f prices.

If at least f+1 followers signed the same report, the leader aggregates the report and the signatures into an attested report and transmits it to all the followers.

Once the followers receive an attested report, they initiate the transmission algorithm.

Transmission

The goal of the transmission algorithm is to record an attested report on the blockchain.

The algorithm has the following steps:

  1. The nodes check the aggregator contract’s state and skip the transmission if the state matches the report data or deviates insignificantly.
  2. Every node sets a timer with a pseudo-random delay depending on the node’s ranking in the current round. After the timer expires, the node rechecks the contract state to account for other nodes sending a transaction earlier. If the contract state is still stale, the node submits a blockchain transaction to update it.
  3. Once the aggregator contract receives an attested report, it validates the signatures, updates its state accordingly, and distributes rewards to the report signers and the transaction transmitter.

The transmission algorithm guarantees the correctness and freshness of data on the blockchain but not the fairness of transmission rewards. A malicious node can reap transmission rewards in every round if it ignores the randomized transmission schedule. The aggregator contract owner can mitigate this issue by monitoring the transmission order and punishing misbehaving nodes.

Protocol version iterations

  • ocr 1.0 specifically targeted data feeds for evm blockchains.
  • ocr 2.0 is a major iteration that introduced a plugin architecture, significantly extending the protocol’s capabilities. This version also features reduced gas costs, a more secure p2p networking stack based on tls1.3, and better performance characteristics (lower latency, higher throughput).
  • ocr 3.0 made the plugin interface more flexible, introduced the observation history chain, reduced the latency, and improved throughput using the report batching feature.

Resources