The access control contracts in this repo uses the term "admin role" in two different contexts:
adminRolein AccessControlRegistry, in the same way that OpenZeppelin uses it in AccessControl (i.e., if Role A is the admin role of Role B, accounts that have Role A can grant and revoke Role B)adminRolein AccessControlRegistryAdminned and AccessControlRegistryAdminnedWithManager, referring to the abstraction layer between the root role and the contract-specific roles. This is also what AccessControlRegistryAdminned and AccessControlRegistryAdminnedWithManager refer to.
Airnode is a first-party oracle node designed to be operated by API providers. The on-chain counterpart of Airnode is referred to as the Airnode protocol.
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 for Airnode protocol purposes.
All Airnode protocols involve the API provider signing their data with an EOA wallet.
The address of this wallet is referred to as airnode in the contracts and is announced by the respective API provider in the DNS records of the base URL of their API.
Airnode feed is an iteration on Airnode that is optimized to power data feeds. It supports much larger bandwidth (i.e., number of data feeds that can be supported simultaneously) and lower latency.
Airnode protocol refers to a range of protocols that are used by Airnode and Airnode feed. Some examples are:
- Request–response protocol: Airnode detects generic on-chain requests and responds by fulfillment transactions
- Publish–subscribe protocol: Airnode detects generic on-chain subscriptions and fulfills them whenever their specified conditions are satisfied
- Airseeker protocol: Airnode feed pre-emptively pushes signed data to a signed API, and Airseeker periodically fetches this data from the signed API to update on-chain data feeds whenever the conditions specified by the respective update parameters are satisfied
Airseeker is an application that periodically fetches signed data from signed APIs to update data feeds whenever the conditions specified by the update parameters in the respective AirseekerRegistry are satisfied. In the case that the signed APIs are publicly accessible, anyone can operate an Airseeker against any AirseekerRegistry for redundancy.
An API provider is a business that has productized their services in the form of an API.
API3 Market is a dApp where users can purchase dAPI plans, which get reflected on-chain immediately.
An auctioneer is an account that has the auctioneer role on OevAuctionHouse. Auctioneers are hot wallets used in auctioner resolvers and auction cops, which are managed by API3 to facilitate OEV aucitons.
Auction cop is an application that confirms or contradicts fulfillments related to awarded OEV auctions. In other words, it slashes the collateral of winning OEV auction participants that did not pay their bid amounts. An auction cop controls a hot wallet that has the auctioneer role on OevAuctionHouse.
OEV auctions take a fixed amount of time, happen periodically, and are packed tightly. The amount of time that an auction takes is called the auction period.
Auction resolver is an application that awards bids placed on an OEV auction. An auction resolver controls a hot wallet that has the auctioneer role on OevAuctionHouse and Api3ServerV1OevExtension.
At the end of an OEV auction, the respective auction resolver responds with an award transaction. This award transaction provides a signature that allows the searcher that has placed the winning bid to be able to update OEV feeds on Api3ServerV1OevExtension, given that they have paid their bid amount.
Award phase is the second phase of an OEV auction where auction resolves are supposed to award searchers' bids. It is preceded by the bid phase.
Each data feed has a base version that lives in Api3ServerV1, and an OEV version that lives in Api3ServerV1OevExtension. The base feed can be updated by anyone at will by using the signed data served by the signed API.
A Beacon is a single-source data feed. A Beacon is identified by the respective Airnode address and template ID.
beaconId = keccak256(abi.encodePacked(airnode, templateId));Api3ServerV1 allows Beacons to be read individually, or arbitrary combinations of them to be aggregated on-chain to form multiple-source data feeds, which are called Beacon sets.
A Beacon set is an on-chain aggregation of Beacons. A Beacon set is identified by the hash of the constituting Beacon IDs.
beaconSetId = keccak256(abi.encode(beaconIds));Warning
This concept is deprecated as the OEV functionality implemented in Api3ServerV1 is supplanted by Api3ServerV1OevExtension.
In a previous OEV implementation, dApps used DapiProxyWithOev/DataFeedProxyWithOev as proxies. The OEV proceeds accumulated in Api3ServerV1, and the beneficiary address that was specified by a proxy was allowed to withdraw the respective OEV proceeds. In short, the beneficiary is the account that a dApp specified as the recipient of its OEV proceeds.
By placing a bid on OevAuctionHouse, a searcher signals to the auctioneers that they want to participate in an OEV auction. Most generally, the bid specifies what update the searcher wants to do and how much they are willing to pay for that.
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.
Warning
The description below assumes that the protocol fee is deprecated and will be set to zero.
OevAuctionHouse specifies that a percentage of the bid amount will be used as collateral. While an auction resolver awards a bid, the collateral amount derived from the respective bid amount gets locked. Then, the searcher needs to pay the bid on Api3ServerV1OevExtension and report their fulfillment. This is followed by an auction cop confirming the fulfillment, which releases the collateral, or contradicting the fulfillment, which slashes the collateral.
The API3 whitepaper definition of a dAPI is a first-party oracle-based data feed that is managed decentrally.
The Api3ServerV1 implementation of this concept is simply an abstraction layer that maps bytes32 strings to data feed IDs, which is managed by a dAPI name setter role.
We use the term dApp interchangeably to refer to the whole entity, its implementation, or specifically, its contract implementation.
API3 holds separate OEV auctions for different dApps to be able to keep their proceeds isolated. In this scheme, dApps are identified by IDs that are assigned by API3. The dApps are required to use proxies with the respective dApp IDs to receive any OEV proceeds.
Where whether we are referring to a Beacon or a Beacon set does not matter, we use the term data feed. For example, since a dAPI can be pointed to a Beacon ID or a Beacon set ID, we simply say that a dAPI can be pointed to a data feed ID.
In the context of HashRegistry, a signer can delegate its signing responsibilities to another account, which will affect contracts that use the respective delegation hash type.
Used to refer to the funds a searcher deposits to OevAuctionHouse to be used as collateral when they are awarded an auction.
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.
In the context of the Airnode protocol, and endpoint represents a distinct type of oracle service provided by an Airnode, which can be parameterized by Airnode ABI-encoded parameters.
An endpoint is identified by the respective OIS title and endpoint name.
endpointId = keccak256(abi.encode(oisTitle, endpointName));An API provider that provides oracle services without the use of any middlemen is a first-party oracle. Compare to third-party oracles.
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.
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.
In the context of AccessControlRegistry, a manager is the only account that has the root role of a tree of roles.
On each chain, an OwnableCallForwarder deployment is designated as the manager of the contracts that facilitate API3 data feed services. The owner of each of these OwnableCallForwarder deployments is currently set to be a GnosisSafeWithoutProxy deployment on the respective chain. Since these GnosisSafeWithoutProxy deployments effectively act as the manager on the respective chain, they are referred to as the manager multisigs.
Maximal extractable value (MEV) is a superset of OEV that can be extracted by including, excluding or reordering any interaction.
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.
API3 periodically holds time-limited OEV auctions at OEV Network where searchers bid to receive priority on updating data feeds of a specific dApp for a period of time.
Each data feed has a base version that lives in Api3ServerV1, and an OEV version that lives in Api3ServerV1OevExtension. The OEV feed can be updated by the searcher that has won the respective OEV auction by using the signed data served by the signed API.
OEV Network is an Arbitrum Nitro L2. Its chain ID is 4913 and it uses ETH as the gas token. OevAuctionHouse is deployed on OEV Network, and searchers bridge ETH to OEV Network to use as collateral.
Warning
This concept is deprecated as API3 will monetize OEV independently from the data feed implementation. As such, the protocol fee at OevAuctionHouse will be set to zero.
OevAuctionHouse specifies that a percentage of the bid amount will be charged as a protocol fee. While an auction resolver awards a bid, the larger of the collateral amount and protocol fee derived from the respective bid amount gets locked. Then, the searcher needs to pay the bid on Api3ServerV1OevExtension and report their fulfillment. This is followed by an auction cop confirming the fulfillment, which releases locked amount and charges the protocol fee, or contradicting the fulfillment, which releases locked amount and slashes the collateral.
Although the base feeds and OEV feeds are readable from Api3ServerV1 and Api3ServerV1OevExtension, respectively, dApps are advised to call the proxy contract that abstracts away the complexity of correctly doing so.
A previous version of the contracts implemented four proxy types (DataFeedProxy, DapiProxy, DataFeedProxyWithOev, DapiProxyWithOev), which were deployed by a ProxyFactory contract. In the current iteration, this is streamlined down to a single proxy contract (Api3ReaderProxyV1), which implements the IApi3ReaderProxy interface and the AggregatorV2V3Interface interface of Chainlink. The dApps are advised to only use Api3ReaderProxyV1 contracts deployed by Api3ReaderProxyV1Factory.
AccessControlRegistry enables each manager to manage a tree of roles. Root roles are literally the respective roots of these trees. Only the respective manager can have a root role, and once initialized, root roles cannot be renounced by the respective managers.
Originating from MEV jargon, a searcher refers to an entity that seeks to make a profit by capturing OEV. Since searchers need to place bids on OevAuctionHouse to receive priority on updating data feeds, they are also referred to as bidders. Similarly, since they need to update OEV feeds on Api3ServerV1OevExtension, they are also referred to as updaters.
A signed API receives signed data from Airnode feeds, and serves it to the public through a delivery network with high-availability. For example, an Airseeker may depend on a signed API to update data feeds.
API providers should host their own signed APIs (in addition to Airnodes), resulting in a robust and end-to-end first-party oracle service. Signed APIs that serve data from a variety of Airnodes act as one-stop shops that are both convenient and provide redundancy. The ideal solution is to use a mix of both types.
All Airnode protocols include Airnodes calling an API and signing the returned data to be ingested by a contract, where the signing scheme differs across protocols. However, this repo specifically refers to the kind of data signed by Airnode feeds, served by signed APIs and used by Airseekers to update data feeds according to update parameters.
The Airseeker protocol uses an ERC-191 signature of the template ID, off-chain timestamp at the time of the API response and the data returned by the API processed and contract ABI-encoded in a bytes type by the respective Airnode address.
bytes32 ethSignedMessageHash = keccak256(abi.encodePacked(templateId, timestamp, data)).toEthSignedMessageHash();Sponsor wallets are derived from the Airnode or Airseeker mnemonic in a protocol-specific way to provide a specific service. Then, the party that requires to receive the service funds the respective sponsor wallet, and the wallet uses these funds to send the transactions to deliver the service. An example of this is the Nodary Airseeker serving self-funded Beacons that update based on specific update parameters depending on which sponsor wallet is funded.
In the context of the Airseeker protocol, the HD wallet path of a specific dAPI is calculated as follows:
- Take the hash of the dAPI name
hashedDapiName = keccak256(dapiName);
- Throw away the last 12 bytes so that we are left with an address-long bytes string (which corresponds to the sponsor address in other Airnode protocols)
- The path is
m/44'/60'/0'/5/FIRST_31_BITS/SECOND_31_BITS/THIRD_31_BITS/FOURTH_31_BITS/FIFTH_31_BITS/SIXTH_31_BITS
By announcing the extended public key of m/44'/60'/0' of the Airseeker HD wallet, anyone can derive the sponsor wallet address related to a dAPI name.
dApps can go to API3 Market to purchase a 3 month-long subscription plan for any dAPI they want with specific update parameters on a specific chain. The purchase of the subscription guarantees the respective update parameters to be upheld regardless of the gas price conditions.
In the context of the Airseeker protocol, a template is short for request template, and represents an endpoint and some Airnode ABI-encoded parameters. A template is identified by the respective endpoint ID and Airnode ABI-encoded parameters.
templateId = keccak256(abi.encode(endpointID, parameters));A middlemen that calls an API operated by an API provider and provides a downstream oracle service. In other words, an oracle that is not a first-party oracle.
Parameters that specify when an Airseeker should update a data feed. Typically, there are two aspects that require an update: