WIP-ER

aditya520 · aditya520 · commit d1726281e964 · 2024-07-08T19:08:02.000+02:00
diff --git a/pages/express-relay/index.mdx b/pages/express-relay/index.mdx
@@ -8,10 +8,13 @@ import ContractIcon from "../../components/icons/ContractIcon";
 
 Express Relay is a priority auction that enables protocols to eliminate maximal extractable value (MEV).
 
-- **For Protocol Developers:** Express Relay’s auction primitive allows your protocol to prioritize access to permissionless operations, eliminating the extractive role of miners in ordering transactions.
-A network of established searchers compete in the auctions, allowing you to avoid spending time and energy bootstrapping your own protocol-specific searcher network.
 
-- **For Searchers:** Express Relay aggregates liquidation and other MEV opportunities across integrated DeFi protocols, providing easy and unified access.
+
+- **For Protocol Developers:** Express Relay allows protocols to recapture MEV and access a network of searchers. 
+With Express Relay, protocols don't need to spend time and energy bootstrapping the protocol-specific searcher network.
+
+- **For Searchers:** Express Relay provides easy and unified access by aggregating liquidation and other MEV opportunities across integrated DeFi protocols. 
+Searchers integrate once and gain access to all existing and future opportunities. 
 
 <Cards>
   <Card
@@ -29,3 +32,5 @@ A network of established searchers compete in the auctions, allowing you to avoi
 To learn more about Express Relay's design and how it eliminates MEV, please see [How Express Relay Works](/express-relay/how-express-relay-works).
 
 ## Useful Links
+
+TODO: Add Useful Links
diff --git a/pages/express-relay/integrate-as-protocol.mdx b/pages/express-relay/integrate-as-protocol.mdx
@@ -2,21 +2,21 @@ import { Callout, Tabs, Steps } from 'nextra/components'
 
 # How to Integrate Express Relay as a Protocol
 
-Defi protocols can **permissionlessly** integrate with Express Relay to recapture MEV and access a network of searchers. 
+This guide will explain how DeFi protocols can integrate Express Relay.
 
 Integrating with Express Relay involves two main steps:
 
-- Update your defi protocol's contract to **permit** Express Relay transactions.
-- Write a script to **expose** opportunities to searchers for auction.
+- **Update** your DeFi protocol's contract.
+- **Expose** opportunities to searchers for auction.
 
 ## Update your defi Protocol's Contract
 
-To integrate with Express Relay, your protocol's contract must permit Express Relay to access opportunities.
+To integrate with Express Relay, your protocol's contract must check if Express Relay has permissioned the current transaction.
 
 <Steps>
 ### Install the Express Relay SDK
 
-Pyth provides a [Solidity SDK](https://www.npmjs.com/package/@pythnetwork/express-relay-sdk-solidity) to help developers integrate Express Relay into their defi protocol. 
+Pyth provides a [Solidity SDK](https://www.npmjs.com/package/@pythnetwork/express-relay-sdk-solidity) to help developers integrate Express Relay into their DeFi protocol. 
 The SDK exposes [`IExpressRelay`](https://github.com/pyth-network/pyth-crosschain/blob/main/express_relay/sdk/solidity/IExpressRelay.sol) and [`IExpressRelayFeeReceiver`](https://github.com/pyth-network/pyth-crosschain/blob/main/express_relay/sdk/solidity/IExpressRelayFeeReceiver.sol) interfaces to interact with Express Relay.
 
 <Tabs items={['Hardhat', 'Foundry']}>
@@ -47,39 +47,40 @@ Then add the following line to `remappings.txt` file:
 
 The following steps show how to modify your protocol's contract to permit Express Relay transactions and receive funds from Express Relay.
 
-1. Utilize [`isPermissioned`](https://github.com/pyth-network/pyth-crosschain/blob/main/express_relay/sdk/solidity/IExpressRelay.sol#L10C14-L10C28) method from `IExpressRelay` interface to **permit** Express Relay transactions.
-1. Implement the [`IExpressRelayFeeReceiver`](https://github.com/pyth-network/pyth-crosschain/blob/main/express_relay/sdk/solidity/IExpressRelayFeeReceiver.sol#L4) interface to **receive** funds from Express Relay.
+1. Call [`isPermissioned`](https://github.com/pyth-network/pyth-crosschain/blob/main/express_relay/sdk/solidity/IExpressRelay.sol#L10C14-L10C28) method from `IExpressRelay` interface to **permit** Express Relay transactions.
+1. Implement the [`IExpressRelayFeeReceiver`](https://github.com/pyth-network/pyth-crosschain/blob/main/express_relay/sdk/solidity/IExpressRelayFeeReceiver.sol#L4) interface to **receive** auction proceedings. 
 
 #### 1. Permit Express Relay Transactions
 
 The `isPermissioned` function takes two arguments:
-1. `protocolFeeReceiver`: The contract address that will receive the protocol fee from the winning searcher after a successful auction.
-1. `permissionId`: A unique identifier of a vault or position eligible to expose as an opportunity.
+1. `protocolFeeReceiver`: The address to receive the protocol's share of auction proceedings.
+1. `permissionId`: A unique identifier for the opportunity.
 
 ```solidity copy
 import "@pythnetwork/express-relay-sdk-solidity/IExpressRelay.sol";
 
 // Express Relay contract address on Optimism Sepolia
-// Check https://docs.pyth.network/express-relay/contract-addresses for the address deployed on other networks
+// 
+// Check https://docs.pyth.network/express-relay/contract-addresses 
+// for the address deployed on other networks
 address expressRelay = 0xD6e417287b875A3932c1Ff5dcB26D4D2C8b90B40;
 
 require(
 		IExpressRelay(expressRelay).isPermissioned(
         protocolFeeReceiver,
         permissionId
     ),
-		"invalid liquidation"
+		"not permissioned"
 );
 ```
 <Callout type="info" emoji="ℹ️">
-  The `permissionId` represents unique identifying information for the vault or position within a protocol. 
-  It can be the vault address or the vault ID, concatenated into `bytes` format. 
+  The `permissionId` represents unique identifying information of an opportunity. 
+  For a liquidation opportunity, the vault address or ID could be concatenated into `bytes` format. 
   Consult [`Permissioning`](./how-express-relay-works/permissioning.mdx) for more information on generating permission IDs. 
 </Callout>
 
 #### 2. Set up Fee Receiver
-
-After a successful auction, the Express Relay calls the `receiveAuctionProceedings` function present in `IExpressRelayFeeReceiver` to send the portion of the fee paid by the winning searcher to the Protocol's contract
+The Express Relay will call the `receiveAuctionProceedings` method present in `IExpressRelayFeeReceiver`. The call will transfer the protocol's share of the auction proceeding to the `protocolFeeReceiver` address.
 
 ```solidity copy
 interface IExpressRelayFeeReceiver {
@@ -89,7 +90,6 @@ interface IExpressRelayFeeReceiver {
 }
 ```
 
-
 The following code snippet shows a sample liquidation opportunity via Express Relay.
 Note: The highlighted lines show the contract's relevant additions for Express Relay integration.
 
@@ -163,26 +163,26 @@ contract EasyLend is IExpressRelayFeeReceiver {
 
 ## Expose Opportunities to Searchers
 
-Your defi protocol should fetch vaults and positions eligible as opportunites and expose them to Express Relay for auction.
+DeFi protocols must fetch opportunities and expose them to Express Relay for auction.
 
-The Express Relay auction server provides a **POST** method, `/v1/opportunities`, which accepts a JSON payload containing the details of the opportunity.
+The Express Relay provides a **POST** method, [`/v1/opportunities`](https://per-staging.dourolabs.app/redoc#tag/opportunity/operation/post_opportunity), which accepts a JSON payload containing the details of the opportunity.
 
-The JSON payload should contain liquidation opportunities in the following format:
+The JSON payload should contain opportunities in the following format:
 
 ```json
 {
-  "target_calldata": "0xdeadbeef",                                      // Calldata to perform liquidation
+  "target_calldata": "0xdeadbeef",                                      // Calldata to the execute opportunity
   "chain_id": "op_sepolia",                                             
-  "target_contract": "0xcA11bde05977b3631167028862bE2a173976CA11",      // Protocol contract address to call for liquidation
-  "permission_key": "0xcafebabe",                                       // Unique identifier for the liquidation opportunity
+  "target_contract": "0xcA11bde05977b3631167028862bE2a173976CA11",      // Protocol contract address to call for
+  "permission_key": "0xcafebabe",                                       // Unique identifier for the opportunity
   "target_call_value": "1",                                             // Value(in Wei) to send with to the Protocol contract.
-  "buy_tokens": [                                                       // Tokens to buy (Collateral)
+  "buy_tokens": [                                                       // Tokens to buy 
     {
       "amount": "1000",
       "token": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2"
     }
   ],
-  "sell_tokens": [                                                      // Tokens to sell (Oustadaing Debt)
+  "sell_tokens": [                                                      // Tokens to S
     {
       "amount": "900",
       "token": "0x2260fac5e5542a773aa44fbcfedf7c193bc2c599"
@@ -196,7 +196,7 @@ The JSON payload should contain liquidation opportunities in the following forma
 Each protocol integrated with Express Relay must evaluate every position's health using the latest Oracle prices before exposing them to Express Relay. 
 You can do this by indexing the chain, listening to protocol events, or querying open positions through an RPC provider.
 
-Check the [`monitor.ts`](https://github.com/pyth-network/pyth-crosschain/blob/main/express_relay/examples/easy_lend/src/monitor.ts) script, which fetches liquidation opportunities for the below-mentioned [Easy Lend](https://github.com/pyth-network/pyth-crosschain/tree/main/express_relay/examples/easy_lend) example and exposes them to Express Relay for auction.
+Check the [`monitor.ts`](https://github.com/pyth-network/pyth-crosschain/blob/main/express_relay/examples/easy_lend/src/monitor.ts) script, which fetches opportunities for the below-mentioned [Easy Lend](https://github.com/pyth-network/pyth-crosschain/tree/main/express_relay/examples/easy_lend) example and exposes them to Express Relay for auction.
 
 
 ## Additional Resources
diff --git a/pages/express-relay/integrate-as-searcher.mdx b/pages/express-relay/integrate-as-searcher.mdx
@@ -80,7 +80,7 @@ You can fetch historical opportunities by setting the `mode` parameter to `histo
 
 </Tabs.Tab>
 <Tabs.Tab>
-Searchers can connect to the server via WebSocket to reduce latency and subscribe to various events. The WebSocket endpoint relies at `/v1/ws`(e.g `wss://pyth-express-relay-mainnet.asymmetric.re/v1/ws`)
+Searchers can connect to the server via WebSocket to reduce latency and subscribe to various events. The WebSocket endpoint relies at `/v1/ws`(e.g `wss://pyth-express-relay-mainnet.asymmetric.re/v1/ws`).
 Here is a sample JSON payload to subscribe to opportunities:
 
 ```bash copy
@@ -107,15 +107,13 @@ The server responds with opportunities in the following format:
   "target_contract": "0xcA11bde05977b3631167028862bE2a173976CA11",  // Protocol contract address to call for execution
   "permission_key": "0xcafebabe",                                   // Permission key required for the liquidation opportunity
   "target_call_value": "1",                                         // Value(in Wei) to send with to the Protocol contract.
-  "buy_tokens": [
-    // Tokens to buy
+  "buy_tokens": [                                                   // Tokens to buy
     {
       "amount": "1000",
       "token": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2"
     }
   ],
-  "sell_tokens": [
-    // Tokens to sell
+  "sell_tokens": [                                                  // Tokens to sell
     {
       "amount": "900",
       "token": "0x2260fac5e5542a773aa44fbcfedf7c193bc2c599"
@@ -132,9 +130,11 @@ The SDKs provide an easy way to construct a bid using the `OpportunityAdapter` c
 The `OpportunityAdapter` contract handles asset transfers and ensures the opportunity is executed correctly.
 
 You can learn more about the `OpportunityAdapter` contract and how to prepare your assets in the [Opportunity Adapter](./integrate-as-searcher/opportunity-adapter.mdx) section.
-If you have already developed an in-house searcher contract there is no need to integrate using the Opportunity Adapter contract.
-You can use our lower level APIs which allows higher flexibility for advanced users.
-Please refer to the [custom contracts](./custom-contract) section for more details.
+If you have already developed an in-house searcher contract, integrating using the Opportunity Adapter contract is unnecessary.
+You can use our lower-level APIs, which allow higher flexibility for advanced users.
+Please refer to the [custom contracts](./integrate-as-searcher/custom-contract.mdx) section for more details.
+
+Here is an example of how to construct a bid using the SDKs:
 
 <Tabs items={['Typescript', 'Python']}>
 <Tabs.Tab>
@@ -153,32 +153,34 @@ const handleOpportunity = async (opportunity: Opportunity) => {
 from datetime import datetime
 
 from express_relay.client import (
-ExpressRelayClient,
-sign_bid
+    ExpressRelayClient,
+    sign_bid
 )
 from secrets import randbits
 from express_relay.express_relay_types import Opportunity, OpportunityBidParams
 
 def opportunity_callback(opportunity: Opportunity):
-nonce = randbits(64)
-deadline = datetime.utcnow().timestamp() + 60 # bid is valid for a minute
-amount = 1000 # This should be determined based on opportunity
-private_key = '0x00000'
-signed_bid = sign_bid(opportunity,
-OpportunityBidParams(amount=amount, deadline=int(deadline), nonce=nonce),
-private_key)
-
+    nonce = randbits(64)
+    deadline = datetime.utcnow().timestamp() + 60 # bid is valid for a minute
+    amount = 1000 # This should be determined based on the opportunity
+    private_key = '0x00000'
+    signed_bid = sign_bid(opportunity, 
+                          OpportunityBidParams(amount=amount, deadline=int(deadline), nonce=nonce), 
+                          private_key)
 ```
 </Tabs.Tab>
 </Tabs>
 
 ### Submit bids on opportunities to the auction server
 
-Searchers can submit the constructed bids to the auction server via the SDKs, an HTTP POST request, or through a WebSocket connection.
+Searchers can submit the constructed bids to the auction server via the SDKs, an HTTP POST request, or a WebSocket connection.
 
 <Tabs items={['Typescript', 'Python', 'HTTP', 'Websocket']}>
 
 <Tabs.Tab>
+
+The code snippet below demonstrates how to submit a bid using the Typescript SDK:
+
 ```typescript {4} copy
 const handleOpporunity = async (opportunity: Opportunity) => {
     ...
@@ -189,6 +191,9 @@ const handleOpporunity = async (opportunity: Opportunity) => {
 
 </Tabs.Tab>
 <Tabs.Tab>
+
+The code snippet below demonstrates how to submit a bid using the Python   SDK:
+
 ```python {5} copy
 def opportunity_callback(opportunity: Opportunity):
     signed_bid = sign_bid(opportunity,
@@ -212,14 +217,12 @@ curl -X POST https://pyth-express-relay-mainnet.asymmetric.re/v1/bids \
 }'
 ```
 
-TODO: Explain the fields here.
-
 </Tabs.Tab>
 <Tabs.Tab>
 
 Searchers can submit bids via Websocket to avoid additional network round-trips and get notified about changes to the bid status.
 
-```json copy
+```bash copy
 {
   "id": "1",
   "method": "post_bid",
