First-party source verification

docs/dapps/integration/aggregatorv2v3interface.md

@@ -22,8 +22,8 @@ Instead, we recommend using IApi3ReaderProxy with a custom adapter that fits you
 You can interact with Api3ReaderProxyV1 through AggregatorV2V3Interface if all of the following conditions apply:
 
 - 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.
+- If your contract uses the current data feed timestamp (`latestTimestamp()` of AggregatorInterface or `updatedAt` returned by `latestRoundData()` of AggregatorV3Interface), it uses it only for a staleness check (e.g., to verify if the feed has been updated within the last heartbeat interval).
+- Any other values used do 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.
 

docs/dapps/integration/index.md

@@ -161,3 +161,35 @@ Can't find your dApp?
 Follow the OEV Rewards [onboarding steps](/dapps/oev-rewards/index.md#how-to-get-onboard) first.
 
 :::
+
+## Verifying first-party sources
+
+The term _first-party oracle_ is coined in the Api3 whitepaper and refers to an API provider that provides oracle services without depending on any middlemen.
+There are three conditions to be verified to check if an oracle service is first-party:
+
+- Each individual node must operate an independent API service as their primary business model (for them to be called API providers).
+- Each API provider must certify their public key and sign their data with the respective private key.
+- Each API provider must make their signed data available themselves, without depending on third-party APIs, blockchains, or state channels.
+
+Api3 provides the only first-party oracle solution.
+Furthermore, we have implemented functionality for the public to be able to easily audit this.
+On a data feed page, when you hover your mouse over the logo of a source, you can observe the Market frontend verifying the conditions above in real-time.
+
+<center><img src="./images/first-party-source.png"></center>
+
+If you want to see what happens under the hood, you can click "Verified," which allows you to make an HTTP request to the "signed API" of the source, https://signed-api.coingecko.com/, and receive a response such as the following:
+
+```json
+{
+  "stage": "aws",
+  "version": "3.0.1",
+  "currentTimestamp": "1740583493",
+  "deploymentTimestamp": "1739870993",
+  "configHash": "0xbd159fb423d5eef7abd7947cf8ad1731f0c60cc2e093877837988907580539c9",
+  "certifiedAirnodes": ["0x6b56E47DccFbC82D63Df3da417d26e8B1B877f0f"]
+}
+```
+
+We know that CoinGecko is a reputable API provider, they own the `coingecko.com` domain, and this response comes from that domain.
+`certifiedAirnodes` is the list of addresses of the accounts that CoinGecko uses to sign its data (only `0x6b56E47DccFbC82D63Df3da417d26e8B1B877f0f` in this case), and the Market frontend confirms that the respective data feed is configured to use data signed by one of these certified accounts.
+Finally, all recent data points signed by CoinGecko can be fetched directly from them through https://signed-api.coingecko.com/public/0x6b56E47DccFbC82D63Df3da417d26e8B1B877f0f.

docs/dapps/integration/security-considerations.md

@@ -43,6 +43,29 @@ Multisig signers have access to this data and are responsible for its verificati
 
 :::
 
+## Data correctness
+
+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 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 these individual data feeds, which provides the strongest security guarantees (for example, compared to off-chain aggregation).
+You can easily verify the first-party nature of our data feeds [directly on the data feed page in Api3 Market.](/dapps/integration/index.md#verifying-first-party-sources)
+
+::: info ⚠️ Warning
+
+While some oracle solutions are at peace with their third-party status, 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, 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://www.google.com/search?q=wormhole+down+%22pyth%22)
+
+:::
+
 ## Update parameters
 
 Once a plan is purchased on Api3 Market, the respective data feed will maintain the advertised deviation threshold and heartbeat interval until plan expiration.
@@ -59,40 +82,17 @@ With this understanding, we designed our architecture and operations from the gr
 
 :::
 
-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.
+## Data availability
+
+We obtain API provider-signed data for feed updates from publicly accessible APIs (the same ones you can use to [verify first-party sources on Api3 Market.](/dapps/integration/index.md#verifying-first-party-sources))
+While similar to the [Coinbase price oracle](https://www.coinbase.com/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 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 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, 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, 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 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 identical guarantees to regular updates—they are on-chain aggregations of API provider-signed data—so they introduce no additional data integrity risk.
+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 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.