Documentation

Appearance

OEV Searchers

Glossary ​

Below are brief descriptions of commonly used terms within the documentation.

Airnode ​

Airnode is a first-party oracle node designed to be operated by API providers. For dAPIs specifically, an Airnode feed is used instead.

The key concept is that an API provider uses an Airnode wallet to sign its data. In the context of smart contracts, airnode refers to the Airnode address of this wallet.

Airnode ABI ​

To decode a bytes string that was encoded with contract ABI, one needs to know the schema used while encoding. Airnode ABI is a specification built on contract ABI to allow encoding without knowing the schema.

Airnode Address ​

All API providers sign their data with an EOA wallet. The address of this wallet is announced by the respective API provider in the DNS records of the base URL of their API.

Airnode Feed ​

Airnode feed is an iteration on Airnode that is optimized to power data feeds. Airnode feeds are hosted by API providers themselves and are identified by the respective Airnode address. The wallet of this account is used to cryptographically sign the data to prove the validity of the data.

Airnode Wallet ​

A secret wallet only known to the API provider who deploys the Airnode or Airnode feed used to sign its data.

Airseeker ​

Airseeker is an application that periodically fetches signed data from Signed APIs to update data feeds whenever the conditions specified by the update parameters are satisfied.

AirseekerRegistry Contract ​

AirseekerRegistry contract serves as an on-chain configuration file for Airseeker. It provides a source of truth for dAPIs and can be used to obtain which data feed a dAPI points to and what its sources are.

API Provider ​

An API provider is a business that has productized their services in the form of an API.

API3 Market ​

API3 Market is a dApp where users can purchase dAPI plans, which get reflected on-chain immediately.

Api3ServerV1 Contract ​

Api3ServerV1 contract is the main contract for dAPIs. It is used by Airseekers to update base feeds.

Api3ServerV1OevExtension Contract ​

Api3ServerV1OevExtension contract is an extension of the Api3ServerV1 contract. It is used by searchers for OEV feed updates.

Auctioneer ​

Short term for OEV Auctioneer.

Award Phase ​

Award phase is the second phase of an OEV auction where OEV Auctioneer resolves the auction and awards the winner. It is preceded by the bid phase.

Base Feed ​

In the context of OEV extraction, the base feed refers to a data feed behind a particular dAPI. An update of this data feed is reflected across all OEV proxies that read from this dAPI.

Beacon ​

A beacon is a single-source data feed. A beacon is identified by the respective Airnode address and template ID.

solidity
beaconId = keccak256(abi.encodePacked(airnode, templateId));

Beacon Set ​

A beacon set is an on-chain aggregation of beacons. A beacon set is identified by the hash of the constituting beacon IDs.

solidity
beaconSetId = keccak256(abi.encode(beaconIds));

Bid ​

Searchers place bids on OEV Network to participate in OEV auctions to obtain exclusive rights to capture OEV.

Bid Amount ​

The amount a searcher is willing to pay for winning the OEV auction.

Bid Phase ​

Bid phase is the first phase of an OEV auction where searchers are supposed to place their bids. It is followed by the award phase.

Collateral ​

Also referred to as collateral amount.

When Auctioneer awards a bid, the OevAuctionHouse contract reserves a portion of the bid amount as collateral. This collateral, with the exception of protocol fee, is released once the Auctioneer confirms the fulfillment reported by the auction winner after they've paid the bid amount.

dAPI ​

The API3 whitepaper definition of a dAPI is a first-party oracle-based data feed that is managed decentrally.

In practice, a dAPI is mapped to a particular data feed. The mapping is managed by API3 DAO.

dApp ​

An application that uses smart contracts. Usually referred to as a source of OEV. Each dApp eligible for OEV proceeds has a dApp ID assigned and uses OEV proxies.

dApp ID ​

API3 holds separate OEV auctions for different dApps to keep their proceeds isolated. In this scheme, dApps are identified by IDs that are assigned by API3 DAO.

Data Feed ​

The common term used to refer to a beacon or a beacon set. Each data feed has a base version that lives in Api3ServerV1 contract, and an OEV version that lives in Api3ServerV1OevExtension.

Data feeds are powered by Airseekers.

Deviation ​

Deviation is the difference between the on-chain value of a data feed and its off-chain value based on the data served by Signed APIs. It is measured as a percentage value, and an update needs to be made when the value exceeds the deviation threshold. A deviation reference value is used as the reference value according to which the percentage value will be calculated.

Endpoint ​

In the context of data feeds, an endpoint represents a distinct type of oracle service provided by an Airnode feed, which can be parameterized by Airnode ABI-encoded parameters.

An endpoint is identified by the respective OIS title and endpoint name.

solidity
endpointId = keccak256(abi.encode(oisTitle, endpointName));

First-party Oracles ​

An API provider that provides oracle services without the use of any middlemen is a first-party oracle.

Our first-party oracles are powered by Airnode feeds.

Fulfillment ​

The searcher that has won an OEV auction is expected to pay their bid amount. This payment is referred to as a fulfillment in the context of OevAuctionHouse.

Heartbeat ​

A heartbeat is a data feed update that was made to uphold a maximum period of time between two consecutive updates, which is called the heartbeat interval.

MEV ​

Maximal extractable value (MEV) is a superset of OEV that can be extracted by including, excluding or reordering any interaction.

OEV ​

Oracle extractable value (OEV) is a subset of MEV that can be extracted by guaranteeing a specific relative order of oracle updates and related interactions within a transaction.

API3 monetizes its dAPI services by holding OEV auctions and forwarding the proceeds to the respective dApps. This is both a net gain for the dApps (which otherwise would have bled these funds to MEV bots and validators) and a fair and scalable business model for API3 DAO.

OEV Auction ​

API3 periodically holds OEV auctions on OEV Network where searchers bid to receive exclusive update rights to update the data feeds for a specific dApp for a limited amount of time.

OEV Auctioneer ​

OEV Auctioneer, or simply Auctioneer, is the off-chain component powering the OEV Auctions.

OEV Beacon ​

Each base feed beacon has a corresponding OEV beacon, which is derived from the original one by hashing the template ID using keccak256. These beacons are needed for OEV searchers to query Signed APIs for their real-time values.

OEV Feed ​

In the context of OEV extraction, the OEV feed refers to a data feed used by OEV proxy. This feed is proxy specific and can be updated by a searcher who won the OEV auction.

OEV Network ​

OEV Network is an Arbitrum Nitro L2. Its chain ID is 4913 and it uses ETH as the gas token. Its purpose is to hold OEV auctions in a transparent and retrospectively verifiable way.

OEV Proceeds ​

We refer to OEV proceeds in two contexts:

  1. As the revenue from capturing the OEV opportunities.
  2. As the amount paid to the dApps as a result of bid amount payments of OEV auction winners.

OEV Proxy ​

An OEV proxy is a proxy contract that reads a value from both base feed and OEV feed and prefers the fresher out of the two. Our implementation is called Api3ReaderProxyV1 and partially supports Chainlink's AggregatorV2V3Interface for convenience.

Protocol Fee ​

When Auctioneer confirms a fulfillment and releases the collateral amount, it deducts a protocol fee which is kept by API3 DAO. The protocol fee is currently set to 0.

Searcher ​

A searcher is an entity that searches for profitable MEV or OEV opportunities in the market. While searching is typically performed by automated bots, we choose to refer to searchers as people.

Signed API ​

A Signed API receives signed data from Airnode feeds and serves it to the public through an API. For example, an Airseeker depends on Signed APIs to update data feeds.

Signed Data ​

Refers to the data signed by Airnode feeds, served by Signed APIs and used by Airseekers to update data feeds.

Target Chain ​

Target chain is the chain where the Api3ServerV1 contract, Api3ServerV1OevExtension contract and the dApp contracts are deployed. This is the chain where the MEV/OEV extraction happens.

Template ​

In the context of data feeds, a template represents an endpoint and some Airnode ABI-encoded parameters. A template is identified by the respective endpoint ID and Airnode ABI-encoded parameters.

solidity
templateId = keccak256(abi.encode(endpointID, parameters));

Update Parameters ​

Parameters that specify when an Airseeker should update a data feed. Typically, there are two aspects that require an update:

  • Deviation: Defined by the deviation threshold and deviation reference
  • Heartbeat: Defined by the heartbeat interval

Released under the MIT License.

Copyright © 2019-present API3