Merge branch 'main' into t-colors

Author: bbenligiray

docs/dapps/index.md

@@ -15,24 +15,23 @@ 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
 
 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
 

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.

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.
 
 :::