details around auction, opportunities, and permissioning

Author: anihamde

pages/express-relay/how-express-relay-works/auction.mdx

@@ -0,0 +1,9 @@
+The auction in Express Relay is held off-chain at the auction server. Bids arrive at the auction server and compete against other bids vying for the same permission key. A relayer selected by governance serves as the auctioneer and is expected to determine the auction in line with the criterion of maximizing the revenue shared back to the protocol that generated this opportunity. That means the auctioneer is expected to forward the subset of bids that maximizes the revenue back to the protocol.
+
+Thus, the Express Relay auction is analogous to a sealed-bid auction, in that participants in the auction will not have the contents of their bid disclosed publicly unless they are forwarded on-chain. Generally, bids are forwarded on-chain if they are expected to execute successfully on-chain, though additional "fallback" bids may be forwarded as well in case of execution failures for the expected winners. The `ExpressRelay` contract extracts the payment of the specified bid amount only if the searcher's bid executes successfully on-chain. Hence, the Express Relay auction can be seen as a generalization of a [first-price sealed-bid auction](https://en.wikipedia.org/wiki/First-price_sealed-bid_auction), in that multiple bids can win and pay their first price.
+
+The revenue from the auction is shared amongst relevant stakeholders in the Express Relay system. This includes:
+- the protocol, which generated the relevant opportunity
+- the relayer, which handled running the off-chain components of the system
+
+The exact revenue splits can be found in the Express Relay read contract and are subject to ...

pages/express-relay/how-express-relay-works/example_ez_lend.mdx

@@ -0,0 +1,11 @@
+In the context of Express Relay, an opportunity refers to a potential transaction that a searcher can execute on a protocol. Typically, the term "opportunity" is used for such transactions that are lucrative and therefore hotly contested by many searchers. 
+
+In the pre-Express Relay world, opportunities therefore correspond to MEV: a protocol generates MEV when an opportunity appears on that protocol and searchers bid up the right to execute the opportunity at the validator level.
+
+In the context of Express Relay, the value deriving from an opportunity no longer flows to the validator but instead is recaptured by the system and shared back with the protocol. In Express Relay, protocols expose opportunities to the network of integrated searchers, and the searchers then bid on priority to execute those opportunities. Critically, the auction has moved from being determined by validators to a lower level at the protocol level.
+
+Explain Opportunity Adapter contract
+
+Brief explanation of and Links to permit2/create2/factory
+
+Explanation of how to write the monitor at a high level

pages/express-relay/how-express-relay-works/opportunities.mdx

@@ -0,0 +1,17 @@
+`permissionId` is a `bytes` object that represents the unique identifying information of a position within the protocol. `permissionId` allows the system to distinguish between bids competing on different opportunities and thereby run more scoped and efficient auctions.
+
+For some protocols, each borrower has a unique position, so the borrower address uniquely identifies a position. For other protocols, each borrower might have multiple positions, distinguished by the address of the collateral asset or by a uint256 id number. In those cases, the set of information that uniquely identifies a position would include multiple fields.
+
+`permissionId` is the concatenation of all these fields in bytes format. To concatenate these fields together, you can call `abi.encode()`. For example, if a protocol featured a unique position per borrower, then it could form `permissionId` as
+
+```
+bytes memory permissionId = abi.encode(borrowerAddress);
+```
+
+On the other hand, if a protocol allowed a borrower to open as many new positions as they wanted, denoted by an identifier `uint256 positionId`, then it could form permissionId as
+
+```
+bytes memory permissionId = abi.encode(borrowerAddress, positionId);
+```
+
+The `permissionId` is used in the `ExpressRelay` contract to toggle permissions for interacting with the protocol. This toggling is checked within the protocol's code to ensure that the current transaction is within the context of Express Relay, so that recaptured value can be returned to the protocol.