diff --git a/docs/dapps/index.md b/docs/dapps/index.md index 6accd112..a9f16adc 100644 --- a/docs/dapps/index.md +++ b/docs/dapps/index.md @@ -15,11 +15,10 @@ API3 provides data feeds and pays dApps for using them. ## API3 Market -Liquidity is increasingly shifting to newly launched L2 networks, and dApps that are able to branch out to these faster are at a significant competitive advantage. +Liquidity is increasingly shifting to newly launched L2 networks, and dApps that are able to branch out to these more quickly are at a significant competitive advantage. For dApps that utilize data feeds, this is only possible with a data feed provider that has recognized this fact and designed their solutions accordingly. -Our answer to this is [API3 Market](https://market.api3.org/), a B2B SaaS marketplace that serves data feeds. -Without speaking to a representative or signing a contract, it enables a dApp developer to purchase a plan for the data feed they need, and integrate it within minutes. +Our answer to this is [API3 Market,](https://market.api3.org/) which enables a dApp developer to purchase a plan for the data feed they need and integrate it within minutes, without speaking to a representative or signing a contract. Furthermore, the whole system is designed to streamline the addition of support for new networks and data feed types, resulting in a large and dynamic catalog. ## OEV Rewards @@ -27,12 +26,12 @@ Furthermore, the whole system is designed to streamline the addition of support The state of a blockchain can only be updated in a discrete manner, with a confirmed block or a sequenced transaction. Practical limits (such as block size and block time) apply to this process, which implies that these updates will invariably lag. Since data feeds are also updated by updating the chain state, every data feed is at least slightly out of date at all times. -This fact can often be exploited to extract funds from the users of the data feed by rent-seeking third parties in the form of Maximal Extractable Value (MEV). +Rent-seeking third parties can exploit this fact to extract funds from data feed users in the form of Maximal Extractable Value (MEV). -[Oracle Extractable Value (OEV)](https://medium.com/api3/oracle-extractable-value-oev-13c1b6d53c5b) is a subset of MEV that oracles have priority on extracting by batching additional operations with their updates. +[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/) the auction proceeds to the respective dApps. -OEV Rewards is effectively a new and sustainable revenue stream for dApps. +OEV Rewards serves as a new and sustainable revenue stream for dApps. ::: info ⚠️ Disclaimer diff --git a/docs/dapps/integration/aggregatorv2v3interface.md b/docs/dapps/integration/aggregatorv2v3interface.md index b2393ef2..2936966e 100644 --- a/docs/dapps/integration/aggregatorv2v3interface.md +++ b/docs/dapps/integration/aggregatorv2v3interface.md @@ -7,44 +7,44 @@ pageHeader: dApps → Integration # AggregatorV2V3Interface -AggregatorV2V3Interface is intended to be used by contracts that were originally built to use Chainlink data feeds. -All considerations in the [contract integration page](/dapps/integration/contract-integration.md) still apply. +AggregatorV2V3Interface is intended for use by contracts that were originally built to use Chainlink data feeds. +All considerations from the [contract integration page](/dapps/integration/contract-integration.md) still apply. ::: info ⚠️ Warning -API3 data feeds are aggregated from asynchronous data feeds for maximal availability guarantees, which means they are not updated in rounds. +API3 data feeds are aggregated from asynchronous data feeds to provide maximal availability guarantees, which means they are not updated in rounds. As a side effect, Api3ReaderProxyV1 does not implement the round-related functionality of AggregatorV2V3Interface. -If your contract depends on these, it would not be appropriate to use Api3ReaderProxyV1 via AggregatorV2V3Interface. -We would instead recommend you to use IApi3ReaderProxy with a custom adapter that fits your specific needs. +If your contract depends on round-related functionality, it would not be appropriate to use Api3ReaderProxyV1 via AggregatorV2V3Interface. +Instead, we recommend using IApi3ReaderProxy with a custom adapter that fits your specific needs. ::: -You can interact with Api3ReaderProxyV1 through AggregatorV2V3Interface if all of the below apply: +You can interact with Api3ReaderProxyV1 through AggregatorV2V3Interface if all of the following conditions apply: -- Your contract mainly depends on the current data feed value (`latestAnswer()` of AggregatorInterface or `answer` returned by `latestRoundData()` of AggregatorV3Interface). -- If your contract uses the current data feed timestamp (`latestTimestamp()` of AggregatorInterface or `updatedAt` returned by `latestRoundData()` of AggregatorV3Interface), and it is only for a staleness check, e.g., to check if the feed has been updated in the last heartbeat interval. -- If any other values are used, they do not affect the logic of your contract or the off-chain infrastructure of your dApp. - For example, your contract only emits `roundId` in an event, and strictly for logging purposes. -- The off-chain infrastructure of your dApp does not depend on the events defined in AggregatorInterface. +- Your contract primarily relies on the current data feed value (`latestAnswer()` of AggregatorInterface or `answer` returned by `latestRoundData()` of AggregatorV3Interface). +- If your contract uses the current data feed timestamp (`latestTimestamp()` of AggregatorInterface or `updatedAt` returned by `latestRoundData()` of AggregatorV3Interface), it must be used only for staleness checks (e.g., to verify if the feed has been updated within the last heartbeat interval). +- Any other values used must not affect your contract's logic or your dApp's off-chain infrastructure. + For example, your contract may emit `roundId` in an event strictly for logging purposes. +- Your dApp's off-chain infrastructure does not depend on events defined in AggregatorInterface. ::: info 💡 Tip -Lending protocols typically satisfy the above. +Lending protocols typically satisfy these conditions. ::: -On the other hand, you should not interact with Api3ReaderProxyV1 through AggregatorV2V3Interface if any of the below applies: +On the other hand, you should not interact with Api3ReaderProxyV1 through AggregatorV2V3Interface if any of the following conditions applies: - Your contract depends on Chainlink feed implementation details, such as the round ID increasing with every update. -- Your contract depends on being able to query past updates using `getAnswer()` or `getTimestamp()` of AggregatorInterface, or `getRoundData()` of AggregatorV3Interface. -- The off-chain infrastructure of your dApp depends on the events defined in AggregatorInterface. +- Your contract depends on querying past updates using `getAnswer()` or `getTimestamp()` of AggregatorInterface, or `getRoundData()` of AggregatorV3Interface. +- Your dApp's off-chain infrastructure depends on events defined in AggregatorInterface. ::: info 💡 Tip DeFi protocols such as perpetual derivative exchanges are typically vulnerable to MEV searchers performing time arbitrage. -The main reason Chainlink data feeds provide past round data is to address this issue, which comes with significant UX degradation by requiring some actions to take multiple transactions. -Instead, you can simply read the latest data feed value from an API3 data feed, and get paid the value extracted through time arbitrage in the form of [OEV Rewards.](/dapps/oev-rewards/) +Chainlink data feeds provide past round data primarily to address this issue, but this solution significantly degrades UX by requiring multiple transactions for certain actions. +Instead, you can simply read the latest data feed value from an API3 data feed and receive compensation for time arbitrage value extraction through [OEV Rewards.](/dapps/oev-rewards/) ::: -If you have any doubts about interacting with your Api3ReaderProxyV1 over AggregatorV2V3Interface, you can refer to the [Api3ReaderProxyV1 implementation](https://github.com/api3dao/contracts/blob/main/contracts/api3-server-v1/proxies/Api3ReaderProxyV1.sol) to see how exactly the respective functions will behave. +If you have any doubts about interacting with Api3ReaderProxyV1 through AggregatorV2V3Interface, you can refer to the [Api3ReaderProxyV1 implementation](https://github.com/api3dao/contracts/blob/main/contracts/api3-server-v1/proxies/Api3ReaderProxyV1.sol) to see exactly how these functions behave. diff --git a/docs/dapps/integration/api3-contracts.md b/docs/dapps/integration/api3-contracts.md index 1c3cb034..5105d941 100644 --- a/docs/dapps/integration/api3-contracts.md +++ b/docs/dapps/integration/api3-contracts.md @@ -7,16 +7,19 @@ pageHeader: dApps → Integration # `@api3/contracts` -[`@api3/contracts`](https://www.npmjs.com/package/@api3/contracts) is an npm package that provides three basic features that will be useful to API3 data feed users: +[`@api3/contracts`](https://www.npmjs.com/package/@api3/contracts) is an npm package that provides three basic features for API3 data feed users: -1. `@api3/contracts/interfaces/IApi3ReaderProxy.sol` is imported by contracts that call Api3ReaderProxyV1 contracts using IApi3ReaderProxy. +1. `@api3/contracts/interfaces/IApi3ReaderProxy.sol` is imported by contracts that call Api3ReaderProxyV1 contracts through IApi3ReaderProxy. 2. `@api3/contracts/mock/MockApi3ReaderProxy.sol` is used in tests. -3. `computeCommunalApi3ReaderProxyV1Address()` and `computeDappSpecificApi3ReaderProxyV1Address()` are used to validate the respective types of Api3ReaderProxyV1 addresses. +3. - `computeCommunalApi3ReaderProxyV1Address()` is used to validate adresses shown by API3 Market when ["Skip OEV Rewards"](/dapps/integration/index.md#integration-information) is selected. + - `computeDappSpecificApi3ReaderProxyV1Address()` is used to validate adresses shown by API3 Market when ["Earn OEV Rewards"](/dapps/integration/index.md#integration-information) is selected. -You can refer to [`data-feed-reader-example`](https://github.com/api3dao/data-feed-reader-example) for a demonstration of how each can be used. +For detailed examples of how to use these features, see the [`data-feed-reader-example` repository.](https://github.com/api3dao/data-feed-reader-example) + +Additionally, `@api3/contracts` provides a CLI command for printing OEV Rewards-enabled (i.e., dApp-specific) Api3ReaderProxyV1 addresses, as described [here.](/dapps/integration/contract-integration.md#printing-api3readerproxyv1-addresses) ::: info ℹ️ Info -Note that we do not export [AggregatorV2V3Interface](/dapps/integration/aggregatorv2v3interface.md), as contracts that are built to use it are expected to have imported it. +[AggregatorV2V3Interface](/dapps/integration/aggregatorv2v3interface.md) is not exported from this package, since contracts using this interface must have already imported it from elsewhere. ::: diff --git a/docs/dapps/integration/api3readerproxyv1-deployment.md b/docs/dapps/integration/api3readerproxyv1-deployment.md deleted file mode 100644 index f2be6e13..00000000 --- a/docs/dapps/integration/api3readerproxyv1-deployment.md +++ /dev/null @@ -1,54 +0,0 @@ ---- -title: Contract integration -pageHeader: dApps → Integration -outline: deep ---- - - - -# Api3ReaderProxyV1 deployment - -::: info 💡 Tip - -If API3 representatives have provided you with [commands to print Api3ReaderProxyV1 addresses](/dapps/integration/contract-integration#printing-dapp-specific-api3readerproxyv1-addresses), your proxies should already be deployed and you do not need to follow this page. - -::: - -Api3ReaderProxyV1 is designed to be deployed by calling the `deployApi3ReaderProxyV1()` function of Api3ReaderProxyV1Factory. -Purchasing a plan for a data feed on API3 Market deploys a communal Api3ReaderProxyV1 for it automatically, whose address is displayed on the [integration page.](https://market.api3.org/blast/eth-usd/integrate) -Alternatively, [`data-feed-reader-example`](https://github.com/api3dao/data-feed-reader-example) provides [instructions](https://github.com/api3dao/data-feed-reader-example/blob/main/scripts/README.md#deploying-proxy-contracts-programmatically) for how (communal and dApp-specific) Api3ReaderProxyV1 contracts can be deployed programmatically. - -::: info 💡 Tip - -In short, if your dApp has a [dApp alias](/dapps/oev-rewards/dapp-alias) assigned, deploy your own Api3ReaderProxyV1 contracts by referring to the [instructions in `data-feed-reader-example`.](https://github.com/api3dao/data-feed-reader-example/blob/main/scripts/README.md#deploying-proxy-contracts-programmatically) -Otherwise, use the communal Api3ReaderProxyV1 addresses displayed on the integration pages of the respective data feeds. - -With either option, we recommended you to validate the Api3ReaderProxyV1 addresses using [`@api3/contracts`.](/dapps/integration/api3-contracts.md) - -::: - -## Parameters - -Deploying Api3ReaderProxyV1 by calling Api3ReaderProxyV1Factory requires three parameters: - -- `dapiName` is the name of the data feed in `bytes32` string form. - For example, `dapiName` for the ETH/USD data feed is [`0x4554482f55534400000000000000000000000000000000000000000000000000`.](https://blastscan.io/address/0x5b0cf2b36a65a6BB085D501B971e4c102B9Cd473#readProxyContract#F4) - ::: info ℹ️ Info - - The term dAPI can be traced back to the [API3 whitepaper](https://github.com/api3dao/api3-whitepaper/blob/master/api3-whitepaper.pdf), and refers to a DAO-governed data feed that is built out of first-party oracles. - For the purposes of this page, you can think of the terms dAPI and data feed to be interchangeable. - - ::: - -- `dappId` is a `uint256` that API3 has assigned to a specific dApp on a specific chain. - It is similar to a chain ID in function. - In Solidity, it can be derived as - - ```solidity - uint256(keccak256(abi.encodePacked(keccak256(abi.encodePacked(dappAliasAsString)), block.chainid))); - ``` - - For the communal Api3ReaderProxyV1 deployments, `dappId` is [`1`.](https://blastscan.io/address/0x5b0cf2b36a65a6BB085D501B971e4c102B9Cd473#readProxyContract#F5) - -- While deploying an Api3ReaderProxyV1, a `bytes`-type `metadata` is specified, whose hash is used as the CREATE2 salt. - It should be left [empty](https://blastscan.io/tx/0x0e98bc849985df6d5489396d66b766019c547fedfe3c3fb881276d7fb76ef26e#eventlog#17), i.e., as `0x`. diff --git a/docs/dapps/integration/contract-integration.md b/docs/dapps/integration/contract-integration.md index 72177b98..1daca6dd 100644 --- a/docs/dapps/integration/contract-integration.md +++ b/docs/dapps/integration/contract-integration.md @@ -8,12 +8,12 @@ outline: deep # Contract integration -This page provides important information on how to integrate API3 data feeds to a contract. +This page provides important information on how to integrate API3 data feeds into a contract. Please read it in its entirety before attempting an integration. ::: info ⚠️ Warning -API3 does not authorize any member or affiliate to provide security advice. +API3 does not authorize any members or affiliates to provide security advice. You are solely responsible for following the instructions on this page. ::: @@ -21,25 +21,30 @@ You are solely responsible for following the instructions on this page. ## Api3ReaderProxyV1 Api3ReaderProxyV1 is a contract that is used to read a specific API3 data feed. -For example, to read ETH/USD on Blast, one can simply call the `read()` function of the respective [Api3ReaderProxyV1.](https://blastscan.io/address/0x5b0cf2b36a65a6BB085D501B971e4c102B9Cd473#readProxyContract#F17) +For example, to read ETH/USD on Blast, one can simply call the [`read()` function](https://blastscan.io/address/0x5b0cf2b36a65a6BB085D501B971e4c102B9Cd473#readProxyContract#F17) of a respective Api3ReaderProxyV1. -The Api3ReaderProxyV1 addresses displayed on API3 Market are communal—they do not belong to a specific dApp. -Alternatively, an Api3ReaderProxyV1 can belong to a specific dApp, which is required for [OEV Rewards](/dapps/oev-rewards/) support. -There is no other functional difference between the two. +You can use API3 Market to see the Api3ReaderProxyV1 address you should use for a specific data feed, as described [here.](/dapps/integration/index.md#integration-information) +To summarize, you should use the Api3ReaderProxyV1 address that appears after selecting "Earn OEV Rewards" and entering the name of your dApp. -### Printing dApp-specific Api3ReaderProxyV1 addresses +::: info ⚠️ Warning + +To be eligible for OEV Rewards, you are required to use the Api3ReaderProxyV1 contracts belonging to your dApp. + +::: + +### Printing Api3ReaderProxyV1 addresses -API3 representatives will assign your [dApp alias](/dapps/oev-rewards/dapp-alias.md), deploy your dApp-specific Api3ReaderProxyV1 contracts, and give you a list of commands that will print their addresses. +For your convenience, API3 representatives may deploy OEV Rewards-enabled Api3ReaderProxyV1 contracts on your behalf and provide you with a list of commands that will print their addresses. By running these commands yourself, you can ensure that you are using the correct addresses. ::: info 💡 Tip -We try to verify our contracts on all block explorers with varying success due to their practical limitations. -Since Api3ReaderProxyV1 is deployed deterministically, it not being verified on a block explorer is not a security concern. +We try to verify our contracts on all block explorers, with varying success due to their practical limitations. +Since Api3ReaderProxyV1 is deployed deterministically, the lack of verification on a block explorer does not pose a security concern. ::: -These commands should be in the following format, where the dApp alias, chain ID, and dAPI names match your case: +These commands should be in the following format, where the dApp alias (assigned to you by API3 during [registration](/dapps/oev-rewards/index.md#how-to-get-onboard)), chain ID, and dAPI names match your specific case: ```sh npx @api3/contracts@latest print-api3readerproxyv1-address \ @@ -59,14 +64,8 @@ dAPI name: ETH/USD Please confirm that there is a contract deployed at this address before using it. ``` -Note that if an API3 representative has provided you with this command, you can expect the Market page to point to an active feed and the proxy to be already deployed. -Do not proceed with the integration until you confirm these. - -::: info 💡 Tip - -If you are using the API3 Market in a self-serve manner and want to use dApp-specific Api3ReaderProxyV1 contracts, see the [Api3ReaderProxyV1 deployment guide](/dapps/integration/api3readerproxyv1-deployment). - -::: +Note that if an API3 representative has provided you with this command, you can expect the Market page to point to an active feed and the proxy to already be deployed. +Do not proceed with the integration until you confirm both conditions. ### Reading the data feed @@ -93,7 +92,7 @@ Refer to the [AggregatorV2V3Interface page](/dapps/integration/aggregatorv2v3int Note that `value` has a signed type. However, in the context of a data feed that reports the price of an asset, non-positive values do not make sense. -It is good practice to validate such conditions, as in `require(value > 0)`. +It is good practice to validate against such conditions, as in `require(value > 0)`. ::: @@ -104,40 +103,40 @@ For example, if ETH/USD is `2918.5652133`, `value` will read `291856521330000000 It is extremely risky to validate the data feed value based on practical assumptions. An example where doing so went wrong was Chainlink requiring their LUNA/USD data feed value to be at least `0.1`. -Doing so caused them to misreport by an order or magnitude during the UST depeg, and caused a dApp to suffer more than $14MM in damages. +Doing so caused them to misreport by an order of magnitude during the UST depeg, and caused a dApp to suffer more than $14MM in damages. -We do not utilize such heuristics at our end, and recommend you to be very careful if you do. +We do not utilize such heuristics on our end, and recommend that you be very careful if you do. ::: #### Using `timestamp` `timestamp` is a `uint32`, which is the median of individual on-chain data feed `timestamp`s that contribute to the aggregation. -The `timestamp` of an individual data feed is what the respective API provider reported their system timestamp to be at the time they called their API to get the value. +The `timestamp` of an individual data feed represents the system timestamp that the respective API provider reported when they called their API to get the value. Its main role is to act as a nonce that prevents data feed updates from being replayed. ::: info ⚠️ Warning `timestamp` is not the block timestamp at the time of the update. It is the reported system (i.e., off-chain) time. -A common mistake is using `require(timestamp <= block.timestamp)`. -This should be avoided for two reasons: +One common mistake is using `require(timestamp <= block.timestamp)`. +This check should be avoided for two reasons: 1. If `block.timestamp` lags compared to actual time, this will revert. - However, that is not a valid reason to avoid using the data feed, and will cause unnecessary downtime for your contract. + However, that is not a valid reason to avoid using the data feed, as doing so will cause unnecessary downtime for your contract. 2. Some L2 implementations use the timestamp of the latest block as `block.timestamp` (rather than the system time of the node) when a static call is made to the RPC endpoint. - This means that this `require()` will revert during static calls even when `block.timestamp` does not actually lag. - This disables OEV searchers from using the intended workflow, and will reduce the amount of OEV Rewards you will receive in practice. + This means that the `require()` will revert during static calls even when `block.timestamp` does not actually lag. + This prevents OEV searchers from using the intended workflow and reduces the amount of OEV Rewards you will receive in practice. ::: -In general, the only acceptable use of `timestamp` is validating if the heartbeat interval is upheld, as in `require(timestamp + 24 hours > block.timestamp)`. -However, unless your contract design specifically relies on the data feed value being at most a day old (which is unlikely), we do not necessarily recommend this either. +In general, the only acceptable use of `timestamp` is validating whether the heartbeat interval is upheld, as in `require(timestamp + 24 hours > block.timestamp)`. +However, unless your contract design specifically relies on the data feed value being at most a day old (which is unlikely), we do not necessarily recommend this approach either. ::: info 💡 Tip -Your auditors may not be familiar with the best practices in the context of API3 data feeds. -It is a good idea to direct them to this page. +Your auditors may not be familiar with best practices in the context of API3 data feeds. +We recommend directing them to this page. ::: @@ -146,28 +145,28 @@ It is a good idea to direct them to this page. 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 letting other oracle solutions interfere during such times may result in losing out on a significant amount of OEV revenue. +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 put off OEV searchers from your dApp, or cause them to bid much less to hedge the risk, reducing your [OEV Rewards](/dapps/oev-rewards/). +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 fallback, you should tolerate as much inconsistency as possible. +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 you to tolerate at least 10% inconsistency. +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. -Say a lending platform uses the ETH/USD API3 data feed, and the USDT/USD data feed of another oracle solution. +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, which causes them to avoid bidding a fair amount. +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 loss of profits and thus is a security issue. +Not maximizing OEV Rewards causes a loss of profits and therefore constitutes a security issue. ::: diff --git a/docs/dapps/integration/images/earn-oev-rewards.png b/docs/dapps/integration/images/earn-oev-rewards.png new file mode 100644 index 00000000..617f39ee Binary files /dev/null and b/docs/dapps/integration/images/earn-oev-rewards.png differ diff --git a/docs/dapps/integration/images/skip-oev-rewards.png b/docs/dapps/integration/images/skip-oev-rewards.png new file mode 100644 index 00000000..786c66d2 Binary files /dev/null and b/docs/dapps/integration/images/skip-oev-rewards.png differ diff --git a/docs/dapps/integration/index.md b/docs/dapps/integration/index.md index 9c585069..5ee13d0f 100644 --- a/docs/dapps/integration/index.md +++ b/docs/dapps/integration/index.md @@ -9,7 +9,7 @@ outline: deep # Using API3 Market See the [Quickstart](/dapps/quickstart/index.md) page for a basic guide on how to use [API3 Market.](https://market.api3.org/) -This page will provide further details about using it in production. +This page provides further details about using it in production. ## Update parameters @@ -19,14 +19,14 @@ API3 Market supports two update parameters: [deviation threshold](#deviation-thr ### Deviation threshold Deviation is the difference between the on-chain and off-chain values of a data feed. -It is measured as a percentage value, and an update is initiated when the deviation exceeds the **deviation threshold**. +It is measured as a percentage, and an update is initiated when the deviation exceeds the **deviation threshold**. For example, if the deviation threshold is 1% and the on-chain value of the data feed is 100, an update is initiated when the off-chain value goes below 99 or above 101. ::: info ℹ️ Info -Note that it is not possible to guarantee a maximum deviation amount, as there is no theoretical bound to how fast the off-chain value of a data feed can change. +Note that it is not possible to guarantee a maximum deviation amount, as there is no theoretical limit to how fast the off-chain value of a data feed can change. -When we refer to a 1% deviation threshold, we mean that at the time of a deviation threshold-related update, the deviation amount will have exceeded 1%. +When we refer to a 1% deviation threshold, we mean that at the time of a deviation threshold-related update, the deviation will have exceeded 1%. ::: @@ -40,73 +40,73 @@ API3 Market offers the following deviation threshold options: ::: info ⚠️ Warning We assume that lower deviation thresholds are always more desirable, and thus do not validate if updates are necessary according to the update parameters. -In simpler terms, a data feed with 1% deviation threshold can be updated even if it has only deviated by 0.5%. -In the rare use-cases whose requirements do not agree with this, we do not recommend API3 data feeds to be used. +In simpler terms, a data feed with a 1% deviation threshold can be updated even if it has only deviated by 0.5%. +For rare use cases that require different behavior, we do not recommend using API3 data feeds. ::: -Upholding a lower deviation threshold requires more frequent data feeds updates. +Upholding a lower deviation threshold requires more frequent data feed updates. Consequently, you can expect higher [prices](#pricing) for lower deviation thresholds. ### Heartbeat interval -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**. +A heartbeat is a data feed update that is made to uphold a maximum period of time between two consecutive updates, which is called the **heartbeat interval**. -API3 Market only offers a 24 hour-heartbeat interval. +API3 Market only offers a 24-hour heartbeat interval. ::: info ℹ️ Info -Similar to how deviation threshold works, it can be expected for an update to be initiated when the on-chain value is older than the heartbeat interval. -However, we have observed that some users `require()` in their contracts that the heartbeat interval is upheld. -To reduce the probability of this usage pattern causing any transactions to revert, we initiate heartbeat interval-related updates 2 minutes earlier than necessary. -Note that this still does not provide a hard guarantee, and your contract should be able to handle the case where the on-chain value is older than the heartbeat interval. +Similar to how the deviation threshold works, an update is expected to be initiated when the on-chain value is older than the heartbeat interval. +However, we have observed that some users include `require()` statements in their contracts to verify that the heartbeat interval is upheld. +To reduce the probability of this usage pattern causing transactions to revert, we initiate heartbeat interval-related updates 2 minutes earlier than necessary. +Note that this still does not provide a hard guarantee, and your contract should be able to handle cases where the on-chain value is older than the heartbeat interval. ::: ## Plan durations -API3 Market offers 7 day-plans on testnets and 6 month-plans on mainnets. +API3 Market offers 7-day plans on testnets and 6-month plans on mainnets. Each purchased plan has an expiration date, and the respective update parameters will stop being upheld after that. -Let us go over a few example cases: +Let's go over a few example cases: - BTC/USD on Ethereum is inactive. - The user purchases 1% deviation threshold for 6 months. - The data feed will immediately activate, and deactivate 6 months after. -- BTC/USD on Ethereum is active with 1% deviation threshold, to expire 3 months later. - The user purchases 1% deviation threshold for 6 months (with a [discount](#discounts)). + The user purchases a 1% deviation threshold for 6 months. + The data feed will immediately activate and deactivate 6 months later. +- BTC/USD on Ethereum is active with a 1% deviation threshold, set to expire 3 months later. + The user purchases a 1% deviation threshold for 6 months (with a [discount](#discounts)). The expiration will be extended to 6 months from now. -- BTC/USD on Ethereum is active with 5% deviation threshold, to expire 3 months later. - The user purchases 1% deviation threshold for 6 months (with a [discount](#discounts)). - The data feed will switch to 1% deviation threshold, and deactivate 6 months after. -- BTC/USD on Ethereum is active with 0.5% deviation threshold, to expire 3 months later. - The user purchases 1% deviation threshold for 6 months (with a [discount](#discounts)). - The data feed will continue running with 0.5% deviation threshold for 3 months, switch to 1% deviation threshold, run for another 3 months, and deactivate. +- BTC/USD on Ethereum is active with a 5% deviation threshold, set to expire 3 months later. + The user purchases a 1% deviation threshold for 6 months (with a [discount](#discounts)). + The data feed will switch to a 1% deviation threshold and deactivate 6 months later. +- BTC/USD on Ethereum is active with a 0.5% deviation threshold, set to expire 3 months later. + The user purchases a 1% deviation threshold for 6 months (with a [discount](#discounts)). + The data feed will continue running with a 0.5% deviation threshold for 3 months, switch to a 1% deviation threshold, run for another 3 months, and deactivate. -In the case that plans with different deviation parameters are queued, API3 Market interface displays them as below. +When plans with different deviation parameters are queued, the API3 Market interface displays them as shown below.
::: info 💡 Tip Once a plan has been purchased, API3 guarantees that the [update parameters](#update-parameters) will be upheld for the [plan duration](#plan-durations). -However, it is the user's responsibility to make sure that plans are purchased to keep the data feed active as long as necessary. +However, it is the user's responsibility to ensure that plans are purchased to keep the data feed active as long as necessary. You can use the "Set Reminder" button under the expiration date to avoid forgetting to renew your plans. ::: ## Pricing -The gas cost of operating a data feed is a function of +The gas cost of operating a data feed is a function of: -- How expensive data feed updates are, -- How long the data feed will be operated, -- How often the data feed will be updated. +- The expense of data feed updates +- The frequency of data feed updates +- The duration of data feed operation We maintain a history of data feed update gas costs and update counts required to uphold the offered deviation thresholds, and estimate the future operational costs of the offered plans based on these. ::: info 💰 Financial -The prices you see on API3 Market are the exact operational costs that we estimate (or $0.1/day, whichever is higher.) +The prices you see on API3 Market are the exact operational costs that we estimate (or $0.1/day, whichever is higher). This means that it is unlikely that you will find a better bargain. We do not plan to monetize data feed plans at any point. @@ -117,17 +117,17 @@ Our monetization model is designed around OEV, which makes this pricing strategy ### Discounts It is not possible to estimate the future gas cost of operating a data feed with perfect accuracy. -In the case that we underestimate and find that the price was below the gas cost, we cover the difference. +If we underestimate and find that the price was below the gas cost, we cover the difference. ::: info ⚠️ Warning **On testnets only**, we stop updating if the payment runs out, even if the plan has not expired yet. -In such cases, simply purchase a new plan for updates to continue. +To resume updates in such cases, simply purchase a new plan. ::: -In the case that we overestimate the price, the remainder rolls over to the next plan purchased for the same network–data feed pair, which appears as a **discount** on API3 Market. -Similarly, while a user is purchasing a plan for a data feed that is already active, the remainder of the payments made for the earlier purchases will appear as a discount. +If we overestimate the price, the remainder rolls over to the next plan purchased for the same network–data feed pair, which appears as a **discount** on API3 Market. +Similarly, when a user purchases a plan for a data feed that is already active, the remainder of the payments made for earlier purchases will appear as a discount. ::: info 💰 Financial @@ -139,4 +139,25 @@ In some cases, the discount allows you to get the plan for free. ### Gas grants -You can ask for a gas grant for your dApp by filling in [this form,](https://api3dao.typeform.com/to/TBTu8bJt) where you can request us to purchase plans for you. +You can request a gas grant for your dApp by filling out [this form,](https://api3dao.typeform.com/to/TBTu8bJt) where you can ask us to purchase plans for you. + +## Integration information + +Clicking "Integrate" on a data feed page will display the information needed for a [contract integration.](/dapps/integration/contract-integration.md) +By default, you will see that "Skip OEV Rewards" is selected and an Api3ReaderProxyV1 address is displayed. +If you wish to forgo OEV Rewards, you can simply use this address in your integration. + +
+ +Alternatively, you can select the "Earn OEV Rewards" option, provide the name of your dApp, and (if the proxy has not been deployed earlier) click the "Deploy Proxy" button to send a transaction. +Once the transaction goes through, the Api3ReaderProxyV1 address you should use in your integration will be displayed. +Note that this address is different from the one displayed when "Skip OEV Rewards" is selected. + +
+ +::: info 💡 Tip + +Can't find your dApp? +Follow the OEV Rewards [onboarding flow](/dapps/oev-rewards/index.md#how-to-get-onboard) first. + +::: diff --git a/docs/dapps/integration/old-integrations.md b/docs/dapps/integration/old-integrations.md index 3eb75bc7..0eaf953c 100644 --- a/docs/dapps/integration/old-integrations.md +++ b/docs/dapps/integration/old-integrations.md @@ -8,9 +8,9 @@ pageHeader: dApps → Integration # Old integrations If you are calling `read()` of a DapiProxy or a DapiProxyWithOev instead of [Api3ReaderProxyV1](/dapps/integration/contract-integration.md#api3readerproxyv1), your integration is of an older version. -Although these old integrations will be supported for the foreseeable future, please refer to the [integration instructions](/dapps/integration/index) to switch to the new version. -Doing so will allow us to upgrade your proxy if necessary (and there may be instances where us not being able to do so puts you at risk.) -As an additional note, DapiProxyWithOev users have stopped receiving OEV support, and will need to switch to the new integration version to continue receiving support. +While we'll continue supporting these older integrations, we recommend upgrading to the new version following our [integration instructions](/dapps/integration/index). +This upgrade enables us to update your proxy when needed, protecting you from potential risks. +Note that DapiProxyWithOev users must upgrade to restore their discontinued OEV support. -If you are calling `read()` of a DataFeedProxy, or a DataFeedProxyWithOev, or Api3ServerV1 directly, you are strongly recommended to switch to the new integration version. -Note that such usage was never recommended in API3 docs, and we are making a stronger effort in steering users away from these now. +If you are calling `read()` of a DataFeedProxy, or a DataFeedProxyWithOev, or Api3ServerV1 directly, we strongly recommend switching to the new integration version. +These integration methods were never documented in API3 docs, and we now actively discourage their use. diff --git a/docs/dapps/integration/security-considerations.md b/docs/dapps/integration/security-considerations.md index 80886d1f..1135d94d 100644 --- a/docs/dapps/integration/security-considerations.md +++ b/docs/dapps/integration/security-considerations.md @@ -13,112 +13,105 @@ Therefore, as long as you continue to use it, there will be ongoing security con ::: info 💡 Tip API3 data feeds have never misreported or experienced an outage. -This page merely discusses theoretical scenarios, which apply to any data feed. +This page merely discusses theoretical scenarios that apply to any data feed. ::: ## Smart contract risk -Imperfections in a smart contract implementation may cause it to behave unexpectedly. -This may cause interacting parties to lose funds, which is referred to as the smart contract risk. -As with any smart contract, interacting with Api3ReaderProxyV1 will subject you to a smart contract risk. +Imperfections in a smart contract implementation may cause it to behave unexpectedly, potentially resulting in financial losses for interacting parties—a scenario known as smart contract risk. +Like all smart contracts, Api3ReaderProxyV1 carries this inherent risk. We propose three methods to assess the smart contract risk. -Firstly, you can refer to the related [audit reports.](https://github.com/api3dao/contracts?tab=readme-ov-file#security) -A more practical method is to refer to [our historical TVS](https://defillama.com/oracles/API3) to get a general idea of the _battle-testedness_ of our data feeds. -Finally, you are welcome to review the contracts behind [Api3ReaderProxyV1](/dapps/integration/contract-integration.md#api3readerproxyv1), specifically [Api3ServerV1](https://github.com/api3dao/contracts/blob/main/contracts/api3-server-v1/Api3ServerV1.sol) and [Api3ServerV1OevExtension](https://github.com/api3dao/contracts/blob/main/contracts/api3-server-v1/Api3ServerV1OevExtension.sol). -Note that our [contract developer docs](https://github.com/api3dao/contracts/tree/main/docs) may be helpful in interpreting the design decisions made for these contracts. +You can refer to the related [audit reports.](https://github.com/api3dao/contracts?tab=readme-ov-file#security) +A more practical approach is to refer to [our historical TVS](https://defillama.com/oracles/API3) to understand the _battle-testedness_ of our data feeds. +Additionally, you are welcome to review the contracts behind [Api3ReaderProxyV1](/dapps/integration/contract-integration.md#api3readerproxyv1), specifically [Api3ServerV1](https://github.com/api3dao/contracts/blob/main/contracts/api3-server-v1/Api3ServerV1.sol) and [Api3ServerV1OevExtension](https://github.com/api3dao/contracts/blob/main/contracts/api3-server-v1/Api3ServerV1OevExtension.sol). +Our [contract developer docs](https://github.com/api3dao/contracts/tree/main/docs) provide additional context for understanding the design decisions behind these contracts. ## Privileged accounts Api3ReaderProxyV1 is a [UUPS-upgradeable](https://eips.ethereum.org/EIPS/eip-1822) contract, which can be upgraded by [a 4-of-8 multisig](https://github.com/api3dao/contracts/blob/main/data/manager-multisig-metadata.json#L2) that is owned by members of the API3 technical team. -This upgradeability feature is intended to be used only in exceptional occasions to: +This upgradeability feature is intended to be used only in exceptional occasions to respond to newly discovered compiler, library or contract vulnerabilities, or to migrate users to potential new versions of the contracts. -- Respond to newly discovered compiler, library or contract vulnerabilities, -- Migrate users to potential new versions of the contracts. - -[A 4-of-4 multisig,](https://github.com/api3dao/contracts/blob/main/data/dapi-management-metadata.json#L2) which again is owned by members of the API3 technical team, approves the root of a Merkle tree that contains the data feed configurations. -In other words, adding, removing or replacing API providers that contribute to the aggregation of data feeds requires signatures from all owners of this multisig. +[A 4-of-4 multisig,](https://github.com/api3dao/contracts/blob/main/data/dapi-management-metadata.json#L2) which again is owned by members of the API3 technical team, approves the root of a Merkle tree containing data feed configurations. +This means adding, removing or replacing API providers that contribute to the aggregation of data feeds requires signatures from all owners of this multisig. ::: info ℹ️ Info -The configuration of data feed sources depends on various factors such as uptime, accuracy, response time to incidents and qualitative considerations. -The signers of the multisig have access to these data and are responsible for verifying them. +Data feed source configuration depends on multiple factors including uptime, accuracy, incident response time, and qualitative considerations. +Multisig signers have access to this data and are responsible for its verification. ::: ## Update parameters -Once a plan has been purchased on API3 Market, the respective data feed will be updated with the advertised deviation threshold and heartbeat interval until the expiration of the plan. +Once a plan is purchased on API3 Market, the respective data feed will maintain the advertised deviation threshold and heartbeat interval until plan expiration. This depends on the API3 technical team to keep the wallets that will send the update transactions funded, and maintain the infrastructure that will use these wallets to send the update transactions. -This operation is supported by dedicated monitoring personnel, automated alerting systems, and multiple redundant infrastructure layers. +The operation is backed by dedicated monitoring personnel, automated alerts, and redundant infrastructure layers. ::: info ℹ️ Info We have been providing oracle services as early as [2019](https://etherscan.io/txs?a=0x78e76126719715eddf107cd70f3a31dddf31f85a&p=1029), and were listed as the [best responding oracle](/assets/reputation-link.CxhU2iIj.png) among all Chainlink oracles by [`reputation.link`](https://www.google.com/search?q=%22reputation.link%22+chainlink) as of September 2020, which is when we published the [API3 whitepaper](https://github.com/api3dao/api3-whitepaper) and requested to be removed from Chainlink data feeds. -An important driving factor for this was having visibility into systemic issues that would inevitably cause damage to the users, and believing that we could do better. -We had the opportunity to design our architecture and operations from ground up with this hindsight, which is what we owe our performance to. +An important driving factor for this was our insight into systemic issues that could harm users and our confidence in building a better solution. +With this understanding, we designed our architecture and operations from the ground up, leading to our current performance. ::: -Note that we get the API provider-signed data that we use to update data feeds from publicly accessible APIs. -This is similar to the [Coinbase price oracle](https://www.coinbase.com/en-tr/blog/introducing-the-coinbase-price-oracle), but done by many API providers using the same standard that API3 has created, which makes aggregation feasible. -This means that us not updating a data feed does not necessarily prevent further updates. -For example, MEV searchers can be expected to use these APIs to execute updates that are financially relevant. -Furthermore, our OEV implementation utilizes an equivalent mechanism, which implies that OEV updates will continue going through even if we stop updating the data feed according to the update parameters. +We obtain API provider-signed data for feed updates from publicly accessible APIs. +While similar to the [Coinbase price oracle](https://www.coinbase.com/en-tr/blog/introducing-the-coinbase-price-oracle), our approach involves multiple API providers using our standardized protocol, enabling aggregation. +As a result, even if we cease updating a data feed, further updates remain possible. +MEV searchers, for instance, can access these APIs to perform financially relevant updates. +Similarly, our OEV implementation uses this mechanism, ensuring OEV updates continue even if we stop updating the feed according to the update parameters. ## Correctness of data -The [API3 whitepaper](https://github.com/api3dao/api3-whitepaper) poses that all data that is served in an oracle service comes from API providers in practice, and the trust-minimized way to receive data from an API provider is for there to be no third-party intermediaries. -We have coined the term _first-party oracle_ to refer to this architecture, where API providers provide oracle services without needing third parties to facilitate. +The [API3 whitepaper](https://github.com/api3dao/api3-whitepaper) poses that all oracle data comes from API providers in practice, and the trust-minimized way to receive data from an API provider is for there to be no third-party intermediaries. +We have coined the term _first-party oracle_ to refer to this architecture, where API providers deliver oracle services without needing third parties to facilitate. -API3 data feeds are on-chain aggregations of data feeds that are powered by individual first-party oracles. -In other words, each API provider powers a single-source data feed on-chain, and the API3 data feed is an on-chain median of the these individual data feeds, which provides the strongest security guarantees (for example, compared to off-chain aggregation.) +API3 data feeds are on-chain aggregations of data feeds powered by individual first-party oracles. +Each API provider powers a single-source data feed on-chain, and the API3 data feed is an on-chain median of the these individual data feeds, which provides the strongest security guarantees (for example, compared to off-chain aggregation). ::: info ⚠️ Warning -Other oracle solutions, such as Pyth, wrongly claim that their oracles are first party. -This is not true in two important ways: - -- An API provider is a business that provides an API as a service. - Most Pyth oracles are not API providers to begin with. -- Even in the case that a Pyth oracle is an API provider, their data gets aggregated and served through Wormhole, which is a third party point of failure. +Other oracle solutions, such as Pyth, incorrectly claim their oracles are first party. +This claim fails in two ways: +First, an API provider is a business that provides an API as a service, and most Pyth oracles are not API providers. +Second, even when a Pyth oracle is an API provider, their data is aggregated and served through Wormhole, introducing a third-party point of failure. -In general, aggregating and/or serving an oracle service through an intermediary blockchain or state channel whose consensus model is not identical to the aggregation itself renders it third party. -For example, if 7 API providers provide the data and 100+ node operators aggregate the data and make the aggregation available, the resulting architecture has two points of failure, which is typical of third-party oracle setups. -Furthermore, the redundant point of failure can be expected to be much weaker than the forced one consisting of API providers. -In practice, this means that when a dApp uses Pyth data on Ethereum, their users pay Ethereum gas fees while the dApp is not more secure than [Wormhole.](https://thedefiant.io/news/defi/wormhole-exploit-320m) +In general, when oracle services use an intermediary blockchain or state channel for delivery, they create a third-party system since the intermediary's consensus model will not match the aggregation model. +Consider a system where 7 API providers supply data and 100+ node operators provide aggregation and data availability—this creates two points of failure, typical of third-party oracle designs. +The secondary point of failure (the node operators) is typically weaker than the primary one (the API providers). +Consequently, when dApps use Pyth data on Ethereum, users pay Ethereum gas fees while only receiving security equivalent to [Wormhole.](https://thedefiant.io/news/defi/wormhole-exploit-320m) ::: -API3 maintains a roster of first-party oracle partners and curates data feeds based on continuous analysis of their performance. -We consider the resulting aggregation to be superior to alternatives that aggregate a large number of downstream oracle service providers. +API3 maintains a roster of first-party oracle partners and curates data feeds through continuous performance analysis. +This focused approach produces better aggregation than alternatives that rely on numerous downstream oracle service providers. ## Oracle Extractable Value (OEV) -OEV updates provide the exact same guarantees as regular updates—they are an on-chain aggregations of API provider-signed data—and thus from a data integrity point of view, OEV does not introduce any additional risk. -However, the OEV auction mechanism favors winners by letting them frontrun the updates of an artifically delayed base feed, which is intended to be a tradeoff that is ultimately beneficial to the dApp. +OEV updates provide identical guarantees to regular updates—they are on-chain aggregations of API provider-signed data—so they introduce no additional data integrity risk. +The OEV auction mechanism allows winners to frontrun updates of an artificially delayed base feed, a tradeoff designed to benefit the dApp. -Let us provide more detail about how this works. -In general terms, the lifetime of a data point has three phases: +Here's how the process works. +The lifecycle of a data point consists of three phases: -1. While the data point is 0–30 seconds-old, OEV searchers browse it and place bids if it enables OEV opportunities. -2. While the data point 30–60 seconds-old and if at least one valid bid has been placed, the OEV searcher that has won the auction can use the data point to update the data feed to capture the respective OEV opportunities. -3. While the data point is at least 60 seconds-old, the public can use the data point to update the data feed (and this is also when we update the data feed based on update parameters.) +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. -This means that dApps can expect their data feed to operate with a 30–60 second delay. -Some are concerned about this, which may be warranted. -Let us propose a framework for assessing such situations. -Say your dApp generates `X1` revenue with your current oracle solution. -It would have generated `X2` revenue if you have used API3 data feeds (where `X2` may be smaller than `X1` due to the delay) and an additional `Y` in the form of OEV Rewards. -If `X1 < X2 + Y`, which is the case more often than not, using API3 feeds is the more secure option. +dApps using our system will experience a 30–60 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. +When `X1 < X2 + Y`—which is common—API3 feeds are the more secure choice. ::: info 💡 Tip -An underrated perspective here is that the traditional oracle solutions that do not allow OEV capture are simply vulnerable. -They caused their users to be exploited for [hundreds of millions of dollars](https://members.delphidigital.io/reports/api3-the-state-of-oev) over the years without anyone realizing that this was avoidable. -Therefore, auditors should start flagging dApps that do not make use of an effective OEV capture mechanism, and the dApps that continue using the traditional solutions with the now-known vulnerability should have to justify their position. +An overlooked fact is that traditional oracle solutions without OEV capture are inherently vulnerable. +Their users have faced [hundreds of millions of dollars](https://members.delphidigital.io/reports/api3-the-state-of-oev) in exploits over the years—exploits that were entirely preventable. +Auditors should flag dApps lacking effective OEV capture mechanisms, and dApps continuing to use vulnerable traditional solutions should be required to justify this choice. ::: diff --git a/docs/dapps/oev-rewards/dapp-alias.md b/docs/dapps/oev-rewards/dapp-alias.md deleted file mode 100644 index 04696859..00000000 --- a/docs/dapps/oev-rewards/dapp-alias.md +++ /dev/null @@ -1,33 +0,0 @@ ---- -title: dApp alias -pageHeader: dApps → OEV Rewards ---- - - - -# dApp alias - -API3 uses aliases to identify dApps. -If you are planning to use API3 data feeds and receive OEV Rewards, you want to have a dApp alias assigned to your dApp. -You can see the current list of dApps with aliases [here.](https://github.com/api3dao/contracts/tree/main/data/dapps) - -## Why do you need to be assigned a dApp alias? - -While reading API3 data feeds, dApps must use the [Api3ReaderProxyV1 contracts](/dapps/integration/contract-integration#api3readerproxyv1) deployed with their own dApp alias to be eligible for OEV Rewards. - -::: info ⚠️ Warning - -dApps that use any dApp-specific Api3ReaderProxyV1 contracts that are deployed with the alias of another dApp are not eligible for OEV Rewards. -They will not receive auction proceeds even if there has been any. - -::: - -## How to get assigned a dApp alias - -Fill in [this form](https://api3dao.typeform.com/to/FHhFIL41), specifying - -- The URL of your dApp, -- The networks that your dApp is deployed on, -- Your Telegram handle. - -We will create a Telegram group to guide you along the rest of the way. diff --git a/docs/dapps/oev-rewards/index.md b/docs/dapps/oev-rewards/index.md index b1596dec..c27fe030 100644 --- a/docs/dapps/oev-rewards/index.md +++ b/docs/dapps/oev-rewards/index.md @@ -10,44 +10,29 @@ outline: deep 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 the privilege to determine the order of operations around data feed updates to OEV searchers. -The resulting auction proceeds get paid to the dApp in the form of OEV Rewards. +As the antidote, API3's OEV Network auctions off to OEV searchers the privilege to determine the order of operations around data feed updates. +The resulting auction proceeds are paid to the dApp in the form of OEV Rewards. Assuming competitive auctions, OEV Rewards will be equal to the amount that would otherwise have been lost to the MEV bots. 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 in place of your current data feeds, and immediately start earning OEV Rewards. +You can drop in API3 data feeds to replace your current data feeds and immediately start earning OEV Rewards. ## How to get onboard -1. Get assigned a [dApp alias.](/dapps/oev-rewards/dapp-alias) -2. [Deploy](/dapps/integration/api3readerproxyv1-deployment) Api3ReaderProxyV1 contracts with this dApp alias. -3. [Integrate](/dapps/integration/contract-integration) the Api3ReaderProxyV1 contracts that you have deployed. +Use [this form](https://api3dao.typeform.com/to/FHhFIL41) to contact an API3 representative who will walk you through the following steps: -::: info 💡 Tip - -You can use [this form](https://api3dao.typeform.com/to/FHhFIL41) to get in contact with an API3 representative who can handle the first two steps for you. - -::: +1. We register your dApp so it appears on the API3 Market [integration page.](/dapps/integration/index.md#integration-information) +2. You let us know which chains you operate on and which data feeds you want to use. +3. We purchase subscriptions for you (if applicable) and deploy an OEV Rewards-enabled Api3ReaderProxyV1 contract for each data feed you will use. +4. You integrate these Api3ReaderProxyV1 contracts according to the [instructions.](/dapps/integration/contract-integration) -At the end of each month, API3 will make available a report and 80% of the auction proceeds in the native gas token of the network on which your dApp is deployed, with the remainder of the auction proceeds retained as the OEV Network protocol fee. +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 remaining auction proceeds retained as the protocol fee. ::: info 💰 Financial API3 provides data feeds [at cost](/dapps/integration/index#pricing) and enables dApps to benefit from OEV Rewards on top. -You might ask "What's the catch?" -There is none; OEV Rewards are at the expense of the third parties that otherwise solely benefit from MEV. - -::: - -### DEAL - -The onboarding workflow described above is temporary. -API3 is developing a protocol, DEAL, to determine the OEV Rewards beneficiary in a self-serve manner. -DEAL will provide transparent proof that you are the rightful beneficiary of your dApp's OEV Rewards. - -::: info 💡 Tip - -DEAL will not require any changes to your contract integration, including the Api3ReaderProxyV1 addresses. +You might ask, "What's the catch?" +There is none; OEV Rewards come at the expense of third parties who would otherwise solely benefit from MEV. ::: @@ -55,42 +40,42 @@ DEAL will not require any changes to your contract integration, including the Ap ::: info ⚠️ Warning -[Mixed oracle design](/dapps/integration/contract-integration#mixed-oracle-design) is the main culprit of lackluster OEV Rewards. +[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. ::: -OEV Rewards are proceeds from auctions that OEV searchers participate in. -For the bids placed at the auctions to be competitive, there needs to be multiple independent OEV searcher parties. -An OEV searcher is a blockchain developer with a specific expertise, whose time typically is quite valuable. +OEV Rewards are proceeds from auctions in which OEV searchers participate. +For the auction bids 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 some resources into bootstrapping OEV searcher activity may be required to maximize OEV Rewards. +Investing resources in bootstrapping OEV searcher activity may be required to maximize OEV Rewards. ::: -OEV searchers make a simple revenue–cost estimation before deciding if they will search for your dApp. -The easiest way to tilt this equation to your favor would be to provide excellent documentation for how OEV searchers should interact with your dApp. -One step ahead of this 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 find many users, which will drive searcher profit margins down and your OEV Rewards up. +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 the fork of a well-established DeFi protocol, the barrier to entry to search for your dApp will be minimal. +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 the revenue. -For example, a lending platform that pays 10% of the position size as the liquidation reward will attract more attention than another one that pays 5%. +The second way to attract OEV searchers and maximize OEV Rewards is to increase revenue. +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 properly uses API3 data feeds 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 one. -Do you really need to charge a protocol fee on your dApp if you are receiving enough in OEV Rewards? +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/quickstart/images/proxy-address-raw.png b/docs/dapps/quickstart/images/proxy-address-raw.png index e9414b80..22e117a3 100644 Binary files a/docs/dapps/quickstart/images/proxy-address-raw.png and b/docs/dapps/quickstart/images/proxy-address-raw.png differ diff --git a/docs/dapps/quickstart/images/proxy-address.png b/docs/dapps/quickstart/images/proxy-address.png index 27bb74de..5b0f0b86 100644 Binary files a/docs/dapps/quickstart/images/proxy-address.png and b/docs/dapps/quickstart/images/proxy-address.png differ diff --git a/docs/dapps/quickstart/index.md b/docs/dapps/quickstart/index.md index c600771b..f51dafe2 100644 --- a/docs/dapps/quickstart/index.md +++ b/docs/dapps/quickstart/index.md @@ -8,21 +8,21 @@ pageHeader: dApps # Quickstart [API3 Market](https://market.api3.org/) serves a large and dynamic catalog of data feeds on all major EVM networks. -Follow this guide to learn how to use API3 Market to integrate a data feed to an example contract. +Follow this guide to learn how to use API3 Market to integrate a data feed into an example contract. ## Using API3 Market - Go to [market.api3.org.](https://market.api3.org/) -- Click the toggle button to view the testnets, and pick one for which you have funds. +- Click the toggle button to view the testnets, and pick one where you have funds. -- On the network page, you will see a searchbar (1), some of the data feeds that are already active on the network under "Featured Feeds" (2), and a link to the catalog (3). +- On the network page, you will see a search bar (1), some of the data feeds that are already active on the network under "Featured Feeds" (2), and a link to the catalog (3). - Start typing the name of a data feed in the searchbar, and click it once it appears in the dropdown. + Start typing the name of a data feed in the search bar, and click it once it appears in the drop-down. @@ -39,17 +39,17 @@ On the network page, active feeds appear as cards, and inactive feeds appear as If you pick a data feed that is already active on the network, you will be taken to the data feed page directly. Otherwise, you will be taken to the activation page first. -To experience the entire flow, we recommend you to pick a data feed that is not active. +To experience the entire flow, we recommend picking a data feed that is not active. ::: - If you have picked a data feed that is not active, you will be taken to the activation page next. - Select the parameters, review the duration and the price, and click the "Purchase" button to pay. + Select the parameters, review the duration and price, and click the "Purchase" button to pay.
- Once your purchase transaction is confirmed, you can proceed to view the data feed page. - Leave this tab open, we will come back to it later in the guide. + Leave this tab open, as we will come back to it later in the guide. @@ -67,28 +67,28 @@ If you prefer using Hardhat, you can clone [`data-feed-reader-example`](https:// - Go to [Remix.](https://remix.ethereum.org) -- While the "File explorer" tab is selected on the left sidebar, click the hamburger button and select "Clone". +- With the "File explorer" tab selected on the left sidebar, click the hamburger button and select "Clone". Enter `https://github.com/api3dao/data-feed-reader-example` and click "OK". -- While the "File explorer" tab is selected on the left sidebar, double click `contracts/` to expand it, and click `DataFeedReaderExample.sol`. +- With the "File explorer" tab selected on the left sidebar, double-click `contracts/` to expand it, then click `DataFeedReaderExample.sol`. -- While the "Solidity compiler" tab is selected on the left sidebar, click "Compile DataFeedReaderExample". +- With the "Solidity compiler" tab selected on the left sidebar, click "Compile DataFeedReaderExample". -- While the "Deploy & run transactions" tab is selected on the left sidebar, select "Injected Provider - MetaMask" from the "Environment" dropdown. +- With the "Deploy & run transactions" tab selected on the left sidebar, select "Injected Provider - MetaMask" from the "Environment" drop-down. ::: info 💡 Tip -If you have just used API3 Market to purchase a plan, your MetaMask wallet should be connected to the correct network. -If not, make sure that your wallet is connected to the network that the data feed is on, where we will deploy DataFeedReaderExample. +If you just purchased a plan on API3 Market, your MetaMask wallet should be connected to the correct network. +If not, ensure your wallet is connected to the network where the data feed exists, where we'll deploy DataFeedReaderExample. ::: @@ -96,23 +96,25 @@ If not, make sure that your wallet is connected to the network that the data fee -- Click the copy icon next to the displayed communal Api3ReaderProxyV1 address. +- Click the copy icon next to the displayed Api3ReaderProxyV1 address. +Please note that [OEV Rewards](/dapps/oev-rewards/) is disabled on testnets. +For information about using this selection on mainnets, refer to [this section.](/dapps/integration/index.md#integration-information)
- Return to Remix IDE. - While the "Deploy & run transactions" tab is selected on the left sidebar, paste the Api3ReaderProxyV1 address in the textbox next to the "Deploy" button, and click it. + With the "Deploy & run transactions" tab selected on the left sidebar, paste the Api3ReaderProxyV1 address into the textbox next to the "Deploy" button, then click the button. - After the transaction is confirmed, you can call the publicly accessible functions of DataFeedReaderExample. - Expand "DATAFEEDREADEREXAMPLE AT ..." under "Deployed Contracts", and click "readDataFeed". - You will see the values that DataFeedReaderExample read from Api3ReaderProxyV1. + Under "Deployed Contracts", expand 'DATAFEEDREADEREXAMPLE AT ...', then click "readDataFeed". + You'll see the values that DataFeedReaderExample reads from Api3ReaderProxyV1. ## What next? -This guide should be enough to get you started for a hackathon. -However, if you want to use API3 data feeds in production, continue reading the [integration section.](/dapps/integration/) -Alternatively, find out how to [get paid](/dapps/oev-rewards/) by using API3 data feeds. +This guide should help you get started with a hackathon project. +For production use of API3 data feeds, please continue to the [integration section.](/dapps/integration/) +You can also learn how to [get paid](/dapps/oev-rewards/) for using API3 data feeds." diff --git a/docs/dapps/sidebar.js b/docs/dapps/sidebar.js index f1a4050c..dcd18947 100644 --- a/docs/dapps/sidebar.js +++ b/docs/dapps/sidebar.js @@ -16,10 +16,6 @@ module.exports = [ text: 'Contract integration', link: '/dapps/integration/contract-integration', }, - { - text: 'Api3ReaderProxyV1 deployment', - link: '/dapps/integration/api3readerproxyv1-deployment', - }, { text: 'AggregatorV2V3Interface', link: '/dapps/integration/aggregatorv2v3interface', @@ -41,9 +37,6 @@ module.exports = [ { text: 'OEV Rewards', collapsed: false, - items: [ - { text: 'Getting paid', link: '/dapps/oev-rewards/' }, - { text: 'dApp alias', link: '/dapps/oev-rewards/dapp-alias' }, - ], + items: [{ text: 'Getting paid', link: '/dapps/oev-rewards/' }], }, ];