priliminary OEV Network docs (#12)

* update sidebar changes * update docs for new oev-network * Update docs/reference/oev-network/overview/oev-network.md Co-authored-by: Emanuel Tesař <[email protected]> * Update docs/reference/oev-network/overview/auction-cycle.md Co-authored-by: Emanuel Tesař <[email protected]> * Update docs/reference/oev-network/searchers/understanding-auctioneer.md Co-authored-by: Emanuel Tesař <[email protected]> * Update docs/reference/oev-network/overview/auction-cycle.md Co-authored-by: Emanuel Tesař <[email protected]> * Update docs/reference/oev-network/overview/auction-cycle.md Co-authored-by: Emanuel Tesař <[email protected]> * Update docs/reference/oev-network/overview/auction-cycle.md Co-authored-by: Emanuel Tesař <[email protected]> * Update docs/reference/oev-network/overview/auction-cycle.md Co-authored-by: Emanuel Tesař <[email protected]> * Update docs/reference/oev-network/overview/auction-cycle.md Co-authored-by: Emanuel Tesař <[email protected]> * Update docs/reference/oev-network/overview/auction-cycle.md Co-authored-by: Emanuel Tesař <[email protected]> * Update docs/reference/oev-network/overview/auction-cycle.md Co-authored-by: Emanuel Tesař <[email protected]> * Update docs/reference/oev-network/searchers/submit-bids.md Co-authored-by: Emanuel Tesař <[email protected]> * Update docs/reference/oev-network/searchers/submit-bids.md Co-authored-by: Emanuel Tesař <[email protected]> * Update docs/reference/oev-network/searchers/submit-bids.md Co-authored-by: Emanuel Tesař <[email protected]> * Update docs/reference/oev-network/searchers/submit-bids.md Co-authored-by: Emanuel Tesař <[email protected]> * Update docs/reference/oev-network/searchers/submit-bids.md Co-authored-by: Emanuel Tesař <[email protected]> * Update docs/reference/oev-network/searchers/submit-bids.md Co-authored-by: Emanuel Tesař <[email protected]> * Update docs/reference/oev-network/searchers/submit-bids.md Co-authored-by: Emanuel Tesař <[email protected]> * Update docs/reference/oev-network/searchers/submit-bids.md Co-authored-by: Emanuel Tesař <[email protected]> * Update docs/reference/oev-network/searchers/submit-bids.md Co-authored-by: Emanuel Tesař <[email protected]> * Update docs/reference/oev-network/searchers/understanding-auctioneer.md Co-authored-by: Emanuel Tesař <[email protected]> * Update docs/reference/oev-network/searchers/understanding-auctioneer.md Co-authored-by: Emanuel Tesař <[email protected]> * Update docs/reference/oev-network/searchers/understanding-auctioneer.md Co-authored-by: Emanuel Tesař <[email protected]> * Update docs/reference/oev-network/searchers/understanding-auctioneer.md Co-authored-by: Emanuel Tesař <[email protected]> * Update docs/reference/oev-network/searchers/understanding-auctioneer.md Co-authored-by: Emanuel Tesař <[email protected]> * Update docs/reference/oev-network/searchers/understanding-auctioneer.md Co-authored-by: Emanuel Tesař <[email protected]> * Update docs/reference/oev-network/searchers/understanding-auctioneer.md Co-authored-by: Emanuel Tesař <[email protected]> * Update docs/reference/oev-network/searchers/understanding-auctioneer.md Co-authored-by: Emanuel Tesař <[email protected]> * Apply suggestions from code review Co-authored-by: Aaron Scheiner <[email protected]> * update auction cycle * PR suggestions * typo * PR suggestions * add fulfillments * Apply suggestions from code review Co-authored-by: Emanuel Tesař <[email protected]> * add graphics for overview * pr suggestions * change auction cycle --------- Co-authored-by: Emanuel Tesař <[email protected]> Co-authored-by: Aaron Scheiner <[email protected]>
api3dao · Jul 3, 2024 · b2dff67 · b2dff67
1 parent 1e5f016
commit b2dff67
Show file tree

Hide file tree

Showing 20 changed files with 780 additions and 455 deletions.
diff --git a/docs/.vitepress/config.js b/docs/.vitepress/config.js
@@ -101,7 +101,10 @@ function nav() {
         },
         { text: 'OIS', link: '/reference/ois/latest/' },
         { text: 'QRNG', link: '/reference/qrng/' },
-        { text: `OEV Network`, link: '/reference/oev-network/' },
+        {
+          text: `OEV Network`,
+          link: '/reference/oev-network/',
+        },
         { text: 'DAO Members', link: '/reference/dao-members/' },
       ],
     },

diff --git a/docs/reference/oev-network/dapps/assets/market.png b/docs/reference/oev-network/dapps/assets/market.png
diff --git a/docs/reference/oev-network/dapps/index.md b/docs/reference/oev-network/dapps/index.md
@@ -15,9 +15,20 @@ tags:
 # {{$frontmatter.title}}
 
 OEV auctions operate as a supplementary service to regular data feed operations,
-ensuring that updates persist through the oracle even during OEV relay downtime
-or periods with limited OEV opportunities. Integration involves deploying a
-proxy data feed contract and directing the dApp to it.
+ensuring that updates persist through the oracle even during OEV Network
+downtime or periods with limited OEV opportunities.
+
+## Integration
+
+Integration involves reading from a proxy contract visible on the
+[API3 Market](https://market.api3.org).
+
+All the dAPIs on over 35+ chains have their own proxy addresses listed on the
+market.
+
+<div>
+  <img src="/reference/oev-network/dapps/assets/market.png" />
+</div>
 
 ## Proxy Contract
 
@@ -27,24 +38,15 @@ proxy data feed contract and directing the dApp to it.
 
 Searchers use signed data from Airnodes to update the proxy contract with the
 latest data point. However, if
-[`Api3ServerV1`](https://dapi-docs.api3.org/reference/dapis/understand/read-dapis.htmls)
+[`Api3ServerV1`](https://docs.api3.org/reference/dapis/understand/read-dapis.htmls)
 has a more recent timestamp than the last searcher update, the data point from
-`Api3ServerV1` will be displayed. Each dApp has its own proxy to determine the
-distribution of OEV proceeds. The data feed also reads from `Api3ServerV1` to
-provide a fallback that is updated by the oracle instead of the searcher.
-
-### Deploying a Proxy
-
-When deploying a proxy, the dApp specifies an address that can withdraw OEV
-proceeds from
-[`Api3ServerV1`](https://dapi-docs.api3.org/reference/dapis/understand/read-dapis.htmls).
-This enables the distribution of proceeds to the appropriate dApp.
+`Api3ServerV1` will be displayed.
 
 ::: tip
 
 Please refer to the following guide on how to read from a proxy contract:
 
-- [Reading a Self-Funded dAPI Proxy](https://dapi-docs.api3.org/guides/dapis/read-self-funded-dapi/)
+- [Reading a dAPI Proxy](https://docs.api3.org/guides/dapis/read-a-dapi/)
 
 :::
 

diff --git a/docs/reference/oev-network/index.md b/docs/reference/oev-network/index.md
@@ -1,9 +1,9 @@
 ---
-title: Oracle Extractable Value
+title: OEV Network
 sidebarHeader: Reference
 sidebarSubHeader: OEV Network
-pageHeader: Reference → OEV Network → Understanding OEV
-path: /reference/oev-network/understand/using-oev-network.html
+pageHeader: Reference → OEV Network
+path: /reference/oev-network/oev-network.html
 outline: deep
 tags:
 ---
@@ -16,4 +16,32 @@ tags:
 
 # {{$frontmatter.title}}
 
+![Auction Cycle](/reference/oev-network/overview/assets/oev-network.png)
+
+The OEV Network is an open marketplace designed to facilitate the distribution
+of oracle updates. Operating on an optimistic-rollup, the system ensures
+transparency and verification of transactions. In this marketplace, OEV
+searchers place bids for the first opportunity to update a specific dAPI within
+a short window of time. This timing allows them to extract value, especially if
+the dAPI’s data indicates a price that could lead to a profitable action before
+the next scheduled update.
+
+The auctions conducted on the OEV Network aim to ensure that the value extracted
+by searchers is shared with the dApps responsible for creating these
+opportunities, rather than being monopolized by validators through competitive
+bidding.
+
+An auction on the OEV Network signals two things: a dAPI's data suggests a
+potentially valuable action (such as a liquidation in a lending dApp) that has
+not yet been reflected on-chain, and an update (either scheduled or triggered by
+significant price deviations) has not yet occurred. By facilitating updates
+through this auction system, the OEV Network enhances the accuracy and
+responsiveness of dAPIs, ensuring that updates are made when most needed.
+
+Winners of OEV auctions must include their payment within the transaction that
+updates the data feed, ensuring immediate value return to the dApp, the data
+providers, and the creators of the dAPIs and the OEV Network itself, API3. This
+approach not only improves the efficiency of oracle operations but also
+distributes the extracted value more equitably among participants.
+
 <FlexEndTag/>
diff --git a/docs/reference/oev-network/overview/assets/oev-auction-sequence.png b/docs/reference/oev-network/overview/assets/oev-auction-sequence.png
diff --git a/...etwork/understand/assets/oev-bridge-2.png → ...-network/overview/assets/oev-bridge-2.png b/...etwork/understand/assets/oev-bridge-2.png → ...-network/overview/assets/oev-bridge-2.png
diff --git a/docs/reference/oev-network/overview/assets/oev-bridge.png b/docs/reference/oev-network/overview/assets/oev-bridge.png
diff --git a/docs/reference/oev-network/overview/assets/oev-network.png b/docs/reference/oev-network/overview/assets/oev-network.png
diff --git a/docs/reference/oev-network/overview/auction-cycle.md b/docs/reference/oev-network/overview/auction-cycle.md
@@ -0,0 +1,144 @@
+---
+title: Auction Cycle
+sidebarHeader: Reference
+sidebarSubHeader: OEV Network
+pageHeader: Reference → OEV Network → Auction Cycle
+path: /reference/oev-network/overview/auction-cycle.html
+outline: deep
+tags:
+---
+
+<PageHeader/>
+
+<SearchHighlight/>
+
+<FlexStartTag/>
+
+# {{$frontmatter.title}}
+
+The OEV Network uses an on-chain auction mechanism to facilitate the
+distribution of conditional oracle updates. The condition embedded in the oracle
+update is the value that the searcher is willing to pay to for the update to the
+beneficiary of the dAPI proxy.
+
+To fully understand the auction mechanism let's break down the auction cycle
+using the following sequence diagram:
+
+![Auction Cycle](/reference/oev-network/overview/assets/oev-auction-sequence.png)
+
+The auction cycle consists of the following steps:
+
+1. <b> Bridging to the OEV Network</b>
+
+In order to interact with the OEV Network and participate in the auction the
+searcher needs to
+[bridge](/reference/oev-network/overview/bridge-oev-network.md) their ETH to the
+OEV Network and deposit ETH into the
+[OevAuctionHouse](https://github.com/api3dao/contracts/blob/main/contracts/api3-server-v1/OevAuctionHouse.sol)
+contract.
+
+2. <b> Update searcher balance in OevAuctionHouse </b>
+
+Depositing ETH updates the searcher's balance in the OevAuctionHouse contract.
+The deposit serves as
+[Collateral](/reference/oev-network/searchers/collateral-protocol-fee.md) which
+is needed to be able to win in the auction. The amount of Collateral that needed
+is a percentage of the bid amount.
+
+3. <b>Identify profitable oracle update</b>
+
+The searcher identifies conditions for an oracle update that would be valuable,
+for example a liquidation event if the price of ETH falls below 2000.
+
+4. <b>Submitting a bid</b>
+
+The searcher would then submit a bid to the OevAuctionHouse contract with the
+specified conditions to receive the price update i.e if the price of ETH
+<= 2000. In order to submit a bid, the searcher doesn't need to have collateral
+deposited in the OevAuctionHouse contract. However for a bid to be eligible to
+win an auction, the searcher needs to have the required collateral deposited in
+the OevAuctionHouse contract.
+
+Note: The collateral doesn't get locked until the bid is awarded.
+
+5. <b>Start of a new Auction Round</b>
+
+An auction rounds starts when the auctioneer receives a dAPI value update from
+Airnodes (eg: ETH/USD = 2000) or new blocks are produced on the OEV Network.
+
+:::info Auction Rounds
+
+- Off-chain Airnodes stream dAPI values to the auctioneer. Whenever there is a
+  change in the dAPI value, the auctioneer would check if the new dAPI value
+  satisfies the conditions of any of the bids on the OevAuctionHouse contract.
+  If no bids are satisfied, the auctioneer waits for the next dAPI value change
+  or new bids being placed. If a bid has just won an auction, the auctioneer
+  waits for 60 seconds before starting the next auction round for that dAPI
+  proxy.
+
+- In addition to fetching dAPI values, the auctioneer also fetches new blocks on
+  the OEV Network periodically. The auctioneer checks if new bids have been
+  placed and if any of the bids are satisfied by the current dAPI value. If no
+  bids are satisfied, the auctioneer waits for the next block or dAPI value
+  change. If a bid has just won an auction, the auctioneer waits for 60 seconds
+  before starting the next auction round for that dAPI proxy.
+
+:::
+
+6. <b>Check for bid conditions </b>
+
+The auctioneer checks the current dAPI value against bids received from the
+OevAuctionHouse contract to determine if any of the bids conditions have been
+met.
+
+7. <b>Finding the winning bid</b>
+
+If there are multiple bids that are satisfied, the auctioneer finds the winning
+bid by selecting the bid with the highest bid amount. More details on how the
+auctioneer selects the winning bid can be found in the
+[Understanding Auctioneer](/reference/oev-network/searchers/understanding-auctioneer.html#parallel-auctions)
+page.
+
+8. <b> Sign the winning bid</b>
+
+The winning bid is sent to the Airnodes to obtain a signature allowing the
+searcher to update the dAPI value for the given proxy. These signatures are then
+processed by Auctioneer to prepare the update transaction calldata for
+searchers' convenience.
+
+9. <b> Fetch the encoded transaction from the airnodes</b>
+
+The auctioneer fetches the encoded transaction and signatures from the airnodes.
+
+10. <b> Award the winning bid</b>
+
+The auctioneer publishes the winning bid along with the encoded transaction and
+signatures to the OevAuctionHouse contract. The collateral of the winning bid is
+locked in the OevAuctionHouse contract in the same transaction that the winning
+bid is awarded.
+
+11. <b> Fetch the awarded bid transaction</b>
+
+The searcher fetches the awarded bid transaction from the OEV Network. This
+transaction contains the encoded transaction. The searcher has 60 second window
+of exclusivity to trigger the oracle update.
+
+12. <b>Triggering the oracle update</b>
+
+The searcher can then use the encoded transaction to trigger the oracle update
+on the dAPI proxy and trigger the liquidation event atomically in a multicall
+transaction. The searcher can only do the price update if they transfer the bid
+amount to the beneficiary of the dAPI proxy.
+
+13. <b> Submit fulfillment transaction hash to OevAuctionHouse</b>
+
+The searcher submits the fulfillment transaction hash to the OevAuctionHouse
+contract to confirm that the oracle update has been triggered. The searcher has
+a 24 hour window to submit the fulfillment transaction hash. In the event that
+the searcher does not submit the fulfillment transaction hash, the collateral of
+the winning bid is slashed.
+
+14. <b> Release collateral and charge protocol fee</b>
+
+Once the fulfillment transaction hash is submitted, the collateral of the
+winning bid is released and the protocol fee is charged.
diff --git a/docs/reference/oev-network/overview/bridge-oev-network.md b/docs/reference/oev-network/overview/bridge-oev-network.md
@@ -0,0 +1,50 @@
+---
+title: Bridging to the OEV Network
+sidebarHeader: Reference
+sidebarSubHeader: OEV Network
+pageHeader: Reference → Overview → Bridging to the OEV Network
+path: /reference/oev-network/overview/bridge-oev-network.html
+outline: deep
+tags:
+---
+
+<PageHeader/>
+
+<SearchHighlight/>
+
+<FlexStartTag/>
+
+# {{$frontmatter.title}}
+
+## Network Details
+
+### Mainnet
+
+OEV Network can be added as a custom network to an EVM compatible wallet.
+
+| Details            | Value                          |
+| ------------------ | ------------------------------ |
+| Network            | OEV Network                    |
+| Chain ID           | 4913                           |
+| RPC URL (HTTP)     | http://oev.rpc.api3.org/http   |
+| RPC URL (WS)       | http://oev.rpc.api3.org/ws     |
+| Symbol             | ETH                            |
+| Block Explorer URL | https://oev.explorer.api3.org/ |
+| Bridge URL         | https://oev.bridge.api3.org/   |
+
+## Using the Bridge
+
+Use this link to bridge your ETH to the OEV Network
+[OEV Network Bridge](https://oev-network.bridge.caldera.xyz/)
+
+Make sure you have some ETH in your wallet to use the Bridge.
+
+![OEV Network Bridge](/reference/oev-network/overview/assets/oev-bridge.png)
+
+Clicking on `Transfer Tokens` will automatically add the OEV Network to your
+Metamask wallet.
+
+Confirm the transaction in your wallet. Wait for it to bridge and you will see
+your ETH on OEV Network.
+
+<FlexEndTag/>
diff --git a/docs/reference/oev-network/searchers/arguments.md b/docs/reference/oev-network/searchers/arguments.md
@@ -18,9 +18,9 @@ tags:
 
 ### Proxy Address
 
-dAPPs use a proxy address to read the latest data point from the dAPI. OEV
-Network enabled proxies can be deployed using the [API3 Market](market.api3.org)
-(soon)
+dAPPs use a proxy address to read the latest data point from a dAPI. The
+[API3 Market](market.api3.org) lists the proxy addresses for dAPIs across all
+chains.
 
 ### Condition and Condition Value
 
@@ -34,26 +34,21 @@ from the dAPI is less than or equal to `50000`.
 
 ### bidTopic - Bytes32
 
-The bid topic is an identifier for the type of bid. it can be derived using the
-hash of the chainId and the [proxy address](#proxy-address).
+The `bidTopic` is a constant value used by auctioneer to filter bids that
+pertain to a specific auctioneer instance. That is to say, different versions of
+the auctioneer will have different bid topics.
 
-```javascript
-const { keccak256, solidityPacked } = require('ethers');
-const chainId = 11155111;
-const proxyAddress = '0xa8cea58ab9060600e94bb28b2c8510b73171b55c';
-const bidTopic = keccak256(
-  solidityPacked(['uint256', 'address'], [BigInt(chainId), proxyAddress])
-);
-```
+The current bid topic is
+`0x76302d70726f642d61756374696f6e6565720000000000000000000000000000`
 
 ### bidDetails - Bytes
 
-The bid details are the encoded parameters for the bid. The parameters are
+The `bidDetails` are the encoded parameters for the bid. The parameters are
 [proxy address](#proxy-address), [condition](#condition-and-condition-value),
 [condition value](#condition-and-condition-value) and updater address.
 
 ```javascript
-const { AbiCoder } = require('ethers');
+const { AbiCoder, hexlify } = require('ethers');
 const abiCoder = new AbiCoder();
 
 const BID_CONDITIONS = [
@@ -65,8 +60,14 @@ const conditionValue = 50000;
 const updaterAddress = '<searcher address doing the update>';
 const condition = BID_CONDITIONS.find((c) => c.description === 'LTE');
 const bidDetails = abiCoder.encode(
-  ['address', 'uint256', 'int224', 'address'],
-  [proxyAddress, condition.onchainIndex, conditionValue, updaterAddress]
+  ['address', 'uint256', 'int224', 'address', 'bytes32'],
+  [
+    proxyAddress,
+    condition.onchainIndex,
+    conditionValue,
+    updaterAddress,
+    hexlify(randomBytes(32)),
+  ]
 );
 ```