From f9f7640e07b3296cc5f5bf4d085a459798d7bb65 Mon Sep 17 00:00:00 2001 From: bbenligiray Date: Mon, 3 Nov 2025 12:01:39 +0300 Subject: [PATCH 1/3] Update dApp docs according to the OEV Network changes --- docs/dapps/index.md | 5 +- .../dapps/integration/contract-integration.md | 31 ------------ .../integration/security-considerations.md | 9 +--- docs/dapps/oev-rewards/best-practices.md | 49 ------------------- docs/dapps/oev-rewards/index.md | 33 +++---------- 5 files changed, 9 insertions(+), 118 deletions(-) delete mode 100644 docs/dapps/oev-rewards/best-practices.md diff --git a/docs/dapps/index.md b/docs/dapps/index.md index 45534f7b..14924223 100644 --- a/docs/dapps/index.md +++ b/docs/dapps/index.md @@ -36,12 +36,11 @@ Rent-seeking third parties can exploit this fact to extract funds from data feed [Oracle Extractable Value (OEV)](https://medium.com/api3/oracle-extractable-value-oev-13c1b6d53c5b) is a subset of MEV that oracles have priority in extracting by batching additional operations with their updates. Furthermore, instead of searching for such OEV opportunities themselves, oracles can auction off this privilege. -Api3 holds transparent and permissionless auctions for OEV opportunities on OEV Network, and [pays](/dapps/oev-rewards/) 80% of the auction proceeds to the respective dApps. -OEV Rewards serves as a new and sustainable revenue stream for dApps. +Api3 facilitates the capturing of such OEV opportunities, and pays 80% of the associated revenue to the respective partner dApps in the form of [OEV Rewards](/dapps/oev-rewards/), which serves as a new and sustainable revenue stream for them. ::: info ⚠️ Disclaimer -We refer you to the Api3 [terms and conditions](https://api3.org/terms-and-conditions/), which apply to all services and software provided by Api3 (including but not limited to data feeds, OEV Network, and any example OEV bots). +We refer you to the Api3 [terms and conditions](https://api3.org/terms-and-conditions/), which apply to all services and software provided by Api3 (including but not limited to data feeds, and any example OEV bots). Nothing in this documentation nor related materials should be interpreted as financial, business, nor professional advice. ::: diff --git a/docs/dapps/integration/contract-integration.md b/docs/dapps/integration/contract-integration.md index ffde65c0..481d60fa 100644 --- a/docs/dapps/integration/contract-integration.md +++ b/docs/dapps/integration/contract-integration.md @@ -144,34 +144,3 @@ We recommend directing them to this page. See the [`data-feed-proxy-combinators`](https://github.com/api3dao/data-feed-proxy-combinators) repository for various modular contracts that you can use to create combinations out of Api3ReaderProxyV1 contracts. For example, you can combine an `ETH/USD` Api3ReaderProxyV1 contract and a `wstETH/ETH Exchange Rate` Api3ReaderProxyV1 contract to read a `wstETH/USD` value. - -## Mixed oracle design - -Some dApps choose to mix oracle solutions, either by refusing service if they are not in consensus, or by using one primarily and deferring to another in case of inconsistency. - -In such setups, Api3 data feeds need to be treated differently due to OEV considerations. -Specifically, the vast majority of OEV is extracted during times of volatility, and allowing other oracle solutions interfere during such times may result in the loss of a significant amount of OEV revenue. -In practice, this will play out as an OEV searcher bidding a significant amount for a detected OEV opportunity, only to realize after the auction ends that the dApp now defers to a non-Api3 data feed and the OEV opportunity no longer exists. -Such ambiguity will deter OEV searchers from your dApp or cause them to bid much less to hedge their risk, reducing your [OEV Rewards](/dapps/oev-rewards/). - -The golden standard is only using Api3 data feeds, in which case OEV searchers will be able to bid on OEV opportunities with full confidence, knowing that they will be able to extract if they win the auction. -If you must use Api3 data feeds as your primary source with another solution as a fallback, you should tolerate as much inconsistency as possible. - -::: info 💡 Tip - -We recommend that you tolerate at least 10% inconsistency. -Based on our analysis, any less will hinder OEV extraction during times of high volatility. - -::: - -Note that using Api3 data feeds for only some asset prices still counts as a mixed design. -Consider a lending platform that uses the ETH/USD Api3 data feed and the USDT/USD data feed from another oracle solution. -A user takes out a USDT loan with ETH collateral, and the following price action renders the position liquidatable once the ETH/USD data feed is updated. -Even if an OEV searcher detects the opportunity, they must consider that a rogue USDT/USD update by the other oracle solution may expose it to the public before they can claim it, leading them to avoid bidding a fair amount. - -::: info 💰 Financial - -It is up to you to maximize your OEV Rewards by integrating correctly. -Not maximizing OEV Rewards causes a loss of profits and therefore constitutes a security issue. - -::: diff --git a/docs/dapps/integration/security-considerations.md b/docs/dapps/integration/security-considerations.md index d90f84bf..85e0c800 100644 --- a/docs/dapps/integration/security-considerations.md +++ b/docs/dapps/integration/security-considerations.md @@ -95,14 +95,7 @@ Similarly, our OEV implementation uses this mechanism, ensuring OEV updates cont OEV updates provide identical guarantees to regular updates—they are on-chain aggregations of API provider-signed data—so they introduce no additional [data correctness](#data-correctness) risk. The OEV auction mechanism allows winners to frontrun updates of an artificially delayed base feed, a tradeoff designed to benefit the dApp. -Here's how the process works for auctions with a length of 30 seconds. -The lifecycle of a data point consists of three phases: - -1. From 0-30 seconds: OEV searchers examine the data point and place bids on potential OEV opportunities. -2. From 30-60 seconds: If valid bids exist, the auction winner can update the data feed to capture OEV opportunities. -3. After 60 seconds: The data point becomes publicly available for updates, including our update parameter-based updates. - -dApps using our system will experience a 30–60 second delay in their data feed. +dApps using our system will experience a 0–30 second delay in their data feed. While this delay concerns some users, we can evaluate its impact through a simple framework: Consider a dApp that generates `X1` revenue with its current oracle solution. Using Api3 data feeds would generate `X2` revenue (potentially lower than `X1` due to the delay) plus `Y` in OEV Rewards. diff --git a/docs/dapps/oev-rewards/best-practices.md b/docs/dapps/oev-rewards/best-practices.md deleted file mode 100644 index 5526cfa1..00000000 --- a/docs/dapps/oev-rewards/best-practices.md +++ /dev/null @@ -1,49 +0,0 @@ ---- -title: Best practices -pageHeader: dApps → OEV Rewards ---- - - - -# Best practices - -::: info ⚠️ Warning - -[Mixed oracle design](/dapps/integration/contract-integration#mixed-oracle-design) is the main culprit behind lackluster OEV Rewards. -If your contract integration is faulty, the suggestions below are unlikely to help. - -::: - -For OEV auctions to be competitive, there must be multiple independent OEV searcher parties. -An OEV searcher is a blockchain developer with specific expertise whose time is typically quite valuable. -Therefore, for a maximum amount of OEV Rewards, searching for your dApp must be as easy as possible. - -::: info 💰 Financial - -Investing resources in bootstrapping OEV searcher activity may be required to maximize OEV Rewards. - -::: - -OEV searchers make a simple revenue–cost estimation before deciding whether to search for your dApp. -The easiest way to tilt this equation in your favor is to provide excellent documentation on how OEV searchers should interact with your dApp. -Going one step further is developing and open-sourcing an OEV bot for your dApp that anyone can use and improve upon. -An open-source bot that works well and is easy to operate will attract many users, driving searcher profit margins down and your OEV Rewards up. -Finally, you can [be your own OEV searcher](/oev-searchers/) and participate in the auctions of your dApp. - -::: info 💡 Tip - -If your dApp is a fork of a well-established DeFi protocol, the barrier to entry for searching your dApp will be minimal. -Since Api3 is also incentivized to maximize OEV Rewards, we will provide access to a library of example open-source OEV bots. - -::: - -The second way to attract OEV searchers and maximize OEV Rewards is to increase incentives. -For example, a lending platform that pays 10% of the position size as a liquidation reward will attract more attention than one that pays 5%. -Similarly, a perpetual derivative exchange that uses Api3 data feeds as intended is likely to yield a significant amount of OEV Rewards. - -::: info 💰 Financial - -Consider treating OEV Rewards as your main source of revenue rather than an extra source. -Do you really need to charge a protocol fee for your dApp if you're receiving sufficient OEV Rewards? - -::: diff --git a/docs/dapps/oev-rewards/index.md b/docs/dapps/oev-rewards/index.md index 0c1c3d09..ff7eb353 100644 --- a/docs/dapps/oev-rewards/index.md +++ b/docs/dapps/oev-rewards/index.md @@ -9,8 +9,8 @@ pageHeader: dApps → OEV Rewards dApps that use traditional data feeds are constantly exploited by MEV bots that manipulate the order of operations around individual data feed updates. In practice, this causes dApps to suffer significant and continuous financial losses. -As the antidote, Api3's OEV Network auctions off to OEV searchers the privilege to determine the order of operations around data feed updates. -80% of the [resulting revenue](#breaking-down-oev-rewards) is paid to the dApp in the form of OEV Rewards. +As the antidote, Api3 enables OEV searchers to determine the order of operations around data feed updates. +80% of the resulting revenue is paid to the dApp in the form of OEV Rewards. ::: info 💰 Financial @@ -22,46 +22,25 @@ There is none; OEV Rewards come at the expense of third parties who would otherw Api3 data feeds work identically to traditional data feeds, which means that you do not need to modify your contracts in any way to use them. You can drop in Api3 data feeds to replace your current data feeds and immediately start earning OEV Rewards. -If you want to maximize your OEV Rewards, make sure to check out our [guide for best practices.](/dapps/oev-rewards/best-practices) ## How to get onboard Use [this form](https://api3dao.typeform.com/to/FHhFIL41) to get in contact with an Api3 representative who will walk you through the following steps: 1. We register your dApp for it to show up on the Api3 Market [integration page.](/dapps/integration/index.md#integration-information) -2. You let us know which chains you operate on so we can start running the respective auctions. +2. You let us know which chains you operate on and which data feeds you will use. ::: info 💡 Tip - Don't forget to notify us if you expand to new chains later on. + Don't forget to notify us if you expand to new chains and data feeds later on. ::: -3. You let us know which data feeds you will use. If a gas grant is applicable, we purchase subscriptions for you and deploy an OEV Rewards-enabled Api3ReaderProxyV1 contract for each data feed. ::: info 💡 Tip Alternatively, you can complete this step on your own using [Api3 Market.](https://market.api3.org/) ::: -4. You let us know an address where to receive the OEV Rewards. +3. You let us know an address where to receive the OEV Rewards. ::: info 💡 Tip OEV Rewards are paid in the native currency of your dApp's chain. The receiving address must be an EOA you control or a contract capable of receiving native currency payments. ::: -5. You [integrate](/dapps/integration/contract-integration) the OEV Rewards-enabled Api3ReaderProxyV1 contracts. +4. You [integrate](/dapps/integration/contract-integration) the OEV Rewards-enabled Api3ReaderProxyV1 contracts. At the end of each month, Api3 will make available a report and 80% of the OEV revenue in the native gas token of the network where your dApp is deployed, with the remainder retained as the protocol fee. - -## Breaking down OEV Rewards - -dApps receive 80% of the OEV revenue in the form of OEV Rewards. -This revenue can be broken down into three parts: - -1. Proceeds of the auctions held on OEV Network -2. Revenue from OEV searching activity facilitated by Api3 to ensure a baseline level of competition in the auctions (e.g., with a 20% profit margin, which should be easily beaten by organic searchers) -3. Revenue from MEV searching activity facilitated by Api3 as a failsafe for the above - -::: info ℹ️ Info - -The OEV and MEV searching activity facilitated by Api3 is strictly limited to using data that is already available to the public, as documented in the [OEV searcher docs.](/oev-searchers/) -This can be audited retrospectively by referring to data on OEV Network and the chain that the dApp is on. - -A side-effect of the above is that once organic searcher activity takes hold for a dApp, Api3 will no longer be able to generate searcher revenue, and the auction proceeds will constitute the entirety of the OEV Rewards. -This will result in more efficient and robust capturing of OEV, and thus is a desirable outcome for the dApp. - -::: From 11f9f33769f952859747838f8932557666ff3098 Mon Sep 17 00:00:00 2001 From: bbenligiray Date: Mon, 3 Nov 2025 14:52:21 +0300 Subject: [PATCH 2/3] Reintroduce the mixed oracle design section --- .../dapps/integration/contract-integration.md | 27 +++++++++++++++++++ 1 file changed, 27 insertions(+) diff --git a/docs/dapps/integration/contract-integration.md b/docs/dapps/integration/contract-integration.md index 481d60fa..2ed4f17e 100644 --- a/docs/dapps/integration/contract-integration.md +++ b/docs/dapps/integration/contract-integration.md @@ -144,3 +144,30 @@ We recommend directing them to this page. See the [`data-feed-proxy-combinators`](https://github.com/api3dao/data-feed-proxy-combinators) repository for various modular contracts that you can use to create combinations out of Api3ReaderProxyV1 contracts. For example, you can combine an `ETH/USD` Api3ReaderProxyV1 contract and a `wstETH/ETH Exchange Rate` Api3ReaderProxyV1 contract to read a `wstETH/USD` value. + +## Mixed oracle design + +Some dApps choose to mix oracle solutions, either by refusing service if they are not in consensus, or by using one primarily and deferring to another in case of inconsistency. + +In such setups, Api3 data feeds need to be treated differently due to OEV considerations. +Specifically, the vast majority of OEV is extracted during times of volatility, and allowing other oracle solutions interfere during such times may result in the loss of a significant amount of OEV revenue, reducing your [OEV Rewards](/dapps/oev-rewards/). +The golden standard is only using Api3 data feeds, and if you must use Api3 data feeds as your primary source with another solution as a fallback, you should tolerate as much inconsistency as possible. + +::: info 💡 Tip + +We recommend that you tolerate at least 10% inconsistency. +Based on our analysis, any less will hinder OEV extraction during times of high volatility. + +::: + +Note that using Api3 data feeds for only some asset prices still counts as a mixed design. +Consider a lending platform that uses the ETH/USD Api3 data feed and the USDT/USD data feed from another oracle solution. +A user takes out a USDT loan with ETH collateral, and the following price action renders the position liquidatable once the ETH/USD data feed is updated. +However, a rogue USDT/USD update by the other oracle solution may expose the OEV opportunity to the public before it can be claimed for you. + +::: info 💰 Financial + +It is up to you to maximize your OEV Rewards by integrating correctly. +Not maximizing OEV Rewards causes a loss of profits and therefore constitutes a security issue. + +::: From 4e09aba2ffb325b38d1b15e6e910c1dd822e0130 Mon Sep 17 00:00:00 2001 From: bbenligiray Date: Mon, 3 Nov 2025 14:53:36 +0300 Subject: [PATCH 3/3] Remove the best practices page from the sidebar --- docs/dapps/sidebar.js | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/docs/dapps/sidebar.js b/docs/dapps/sidebar.js index e20f030b..c7a23de7 100644 --- a/docs/dapps/sidebar.js +++ b/docs/dapps/sidebar.js @@ -33,9 +33,6 @@ module.exports = [ { text: 'OEV Rewards', collapsed: false, - items: [ - { text: 'Getting paid', link: '/dapps/oev-rewards/' }, - { text: 'Best practices', link: '/dapps/oev-rewards/best-practices' }, - ], + items: [{ text: 'Getting paid', link: '/dapps/oev-rewards/' }], }, ];