# Add Auto Deposit Source: https://docs.primev.xyz/v1.1.0/api-reference/bidder/autodeposit post /v1/bidder/auto_deposit/{amount} AutoDeposit is called by the bidder node to add a recurring deposit in the bidder registry. The bidder can specify the amount of ETH to be deposited in each window. The bidder can also specify the start window number for the deposit. If the start window number is not specified, the current block number is used to calculate the window number. If the block number is specified, the window number is calculated based on the block number. Once it is enabled, the node will automatically deposit the specified amount in each window as well as withdraw the deposit from the previous window. # Get Auto Deposit Status Source: https://docs.primev.xyz/v1.1.0/api-reference/bidder/autodepositstatus get /v1/bidder/auto_deposit_status AutoDepositStatus is called by the bidder node to get the status of the auto deposit. # Cancel Auto Deposit Source: https://docs.primev.xyz/v1.1.0/api-reference/bidder/cancelautodeposit post /v1/bidder/cancel_auto_deposit CancelAutoDeposit is called by the bidder node to cancel the auto deposit. The bidder can specify if it wants to withdraw the deposit from the current deposited windows. If the withdraw flag is set to true, the API will wait till we can withdraw the deposit from the latest deposited window. # Add Deposit Source: https://docs.primev.xyz/v1.1.0/api-reference/bidder/deposit post /v1/bidder/deposit/{amount} Deposit is called by the bidder node to add deposit in the bidder registry. The bidder can deposit funds in a particular window by specifying the window number. If the window number is not specified, the current block number is used to calculate the window number. If the block number is specified, the window number is calculated based on the block number. If AutoDeposit is enabled, the deposit API returns error. # Retrieve Deposit Source: https://docs.primev.xyz/v1.1.0/api-reference/bidder/getdeposit get /v1/bidder/get_deposit GetDeposit is called by the bidder to get its deposit in the bidder registry. # Send Bid Source: https://docs.primev.xyz/v1.1.0/api-reference/bidder/sendbid post /v1/bidder/bid Send a bid to the bidder mev-commit node. The bid is a message from the bidder to the provider with the transaction hashes and the amount of ETH that the bidder is willing to pay to the provider for including the transaction in the block. The bid also includes the block number that the bidder wants to include the transaction in, the start and end timestamps for the bid decay. The bidder can optionally include the raw transaction payloads (hex encoded RLP) instead of transaction hashes. # Withdraw Deposit Source: https://docs.primev.xyz/v1.1.0/api-reference/bidder/withdraw post /v1/bidder/withdraw Withdraw is called by the bidder to withdraw deposit from the bidder registry. # Withdraw Deposit From Windows Source: https://docs.primev.xyz/v1.1.0/api-reference/bidder/withdrawfromwindows post /v1/bidder/withdraw_from_windows WithdrawFromWindows is called by the bidder node to withdraw funds from multiple windows. # Cancel Transaction Source: https://docs.primev.xyz/v1.1.0/api-reference/debug/canceltx post /v1/debug/cancel_transaction/{txHash} CancelTransaction is called by the provider to cancel a transaction sent from this wallet. # Pending Transactions Source: https://docs.primev.xyz/v1.1.0/api-reference/debug/pendingtxs get /v1/debug/pending_transactions GetPendingTransactions is called by the provider to get the pending transactions for the wallet. # Topology Source: https://docs.primev.xyz/v1.1.0/api-reference/debug/topology get /v1/debug/topology GetTopology is called by the user to get the topology of the node. The topology includes connectivity information about the node. # Introduction Source: https://docs.primev.xyz/v1.1.0/api-reference/introduction Primev's API facilitates seamless interaction with Ethereum's blockbuilding and execution bids, providing a robust set of endpoints for developers to engage with the network efficiently. The API is designed to be both flexible and powerful, allowing for a wide range of actions including querying bid statuses, submitting new bids, and retrieving block information. Key features of the Primev API include: * **Bid Management**: Endpoints for creating, querying, and managing execution bids within the Primev ecosystem. * **Blockbuilding Tools**: Functions to assist in the construction and submission of blocks, enhancing the efficiency of the blockbuilding process. * **Security and Authentication**: Utilizing industry-standard protocols to ensure secure communication between clients and the Primev network. * **Real-time Data Access**: Providing access to live blockchain data, enabling informed decision-making based on the latest network state. ## FAQ * **How can I authenticate with the Primev API?**\ Authentication details, including API keys and access tokens, are essential for secure interactions with the Primev API. Ensure you follow the provided guidelines for authentication to maintain the integrity of your transactions. * **What are the rate limits for the Primev API?**\ Understanding the rate limits is crucial to ensure your application adheres to the API's usage policies and avoids service disruptions. Check the documentation for specific rate limit information. * **How do I handle errors returned by the Primev API?**\ Proper error handling is key to building robust applications. The Primev API uses standard HTTP response codes to indicate the success or failure of requests. Refer to the error handling section for guidance on interpreting these codes and troubleshooting. # Subscribe Source: https://docs.primev.xyz/v1.1.0/api-reference/notifications/subscribe post /v1/subscribe Subscribe to notifications for given topics. The client will receive notifications for the topics it has subscribed to. ### Available Topics - peer_connected: Emitted when a peer connects to the network - peer_disconnected: Emitted when a peer disconnects from the network - validator_opted_in: Emitted before an upcoming L1 block proposer has opted in to the mev-commit protocol. The "proposer-notify-offset" param configures how far in advance the notification is emitted - epoch_validators_opted_in: Emitted at the beginning of an epoch, specifying any slots where the L1 validator is opted-in to mev-commit. See the API description for response structure details. # Retrieve Minimum Stake Source: https://docs.primev.xyz/v1.1.0/api-reference/provider/getminstake get /v1/provider/get_min_stake GetMinStake is called by the provider to get the minimum stake required to be in the provider registry. # Retrieve Stake Source: https://docs.primev.xyz/v1.1.0/api-reference/provider/getstake get /v1/provider/get_stake GetStake is called by the provider to get its stake in the provider registry. # Receive Bids Source: https://docs.primev.xyz/v1.1.0/api-reference/provider/receivebids get /v1/provider/receive_bids ReceiveBids is called by the provider to receive bids from the mev-commit node. The mev-commit node will stream bids to the provider as the response. The bid can optionally have the raw transaction payload in it. The order of the transaction hashes will be the same as the raw transaction payloads if included. # Register Stake Source: https://docs.primev.xyz/v1.1.0/api-reference/provider/registerstake post /v1/provider/stake/{amount} Stake is called by the provider to register or add to its stake in the provider registry. # Send Processed Bids Source: https://docs.primev.xyz/v1.1.0/api-reference/provider/sendprocessedbids post /v1/provider/send_processed_bids SendProcessedBids is called by the provider to send processed bids to the mev-commit node. The provider will stream processed bids to the mev-commit node. # Unstake Funds Source: https://docs.primev.xyz/v1.1.0/api-reference/provider/unstake post /v1/provider/unstake Unstake is called by the provider to request a unstake from the provider registry. # Withdraw Stake Source: https://docs.primev.xyz/v1.1.0/api-reference/provider/withdraw_stake post /v1/provider/withdraw_stake WithdrawStake is called by the provider to withdraw its stake from the provider registry. # Get Validators Source: https://docs.primev.xyz/v1.1.0/api-reference/validator/getvalidators get /v1/validator/get_validators GetValidators is called by the bidder to get the validators for a given epoch. # null Source: https://docs.primev.xyz/v1.1.0/concepts/actors Network actors’ roles are defined based on their interactions with other ecosystem actors. A diagram below depicts a given mev actor’s relative placement compared to others. A list of potential Actors on the mev-commit network are listed below: ### **Providers:** Providers of execution services include but are not limited to: * **Block Builders**: They curate and order transactions in blocks, and have their own private mempool, giving them an advantage in committing to transaction inclusion or making related decisions. * **Relays**: Relays are trusted actors that accept block bids from block builders and make them available to proposers, also relaying the block payload when requested. Due to their fundamental role in the mev pipeline, they can also act as guardians of proposer preferences for blocks and provide execution services. * **Rollup Sequencers**: They're practically block builders for the L2 ecosystem, curating and ordering transactions for the L2 rollups. * **Miners and Mining Pools**: In PoW systems such as Bitcoin, miners and mining pools can provide execution services as they mine the blocks that contain transactions. ### **Bidders** Bidders are users of execution services, bidding for inclusion of their transactions, for some specific preference to be adhered to by providers, and more. Bidders include but are not limited to: * **Searchers**: Searchers of mev opportunities are in prime position to bid for execution services as they may have specific preferences or time constraints that maximize the profitability of their strategies. * [**Solvers**](/v1.1.0/concepts/solvers): Solvers practically act similar to searchers, and will want to bid for execution services that optimize their order in specific ways depending on the protocols they adhere to. * **Rollup Provers**: Provers and other rollup actors that create blobs and calldata to be posted to L1 will bid for execution services so their data can reliably make it on-chain. * **AA Bundlers, Wallets, and other transaction aggregators** : These entities possess transactions from end users, and can bid for execution services with them or on their behalf so their platform provides the best user experience. * **End Users**: While we don't anticipate most end users to send execution service bids directly beyond the gas price of their transactions, end users are considered bidders of execution services in general whether through gas price or other deal or engagement with where they send their transaction order flow to. Generally, if you send transactions you'll be a bidder, and if you receive transactions you'll be a provider. If you are unsure whether you should be a bidder or provider, or both, reach out to our team and we will guide you according to your specific considerations. # Bid Decay Mechanism Source: https://docs.primev.xyz/v1.1.0/concepts/bids/bid-decay-mechanism Learn about how bids decay in value in real time In the mev-commit auction for transaction bundles, bidders submit their bids to providers and their goal is to receive a confirmation that the bundle they bid for will be included in the next block produced by the provider. Bidders aim to receive confirmation for their bundle as soon as possible since early confirmations tend to be more valuable to the bidders. However, providers may want to wait until the last moment to issue confirmations in order to build the most valuable block possible without missing out on any late bids. Therefore, it's essential to have a mechanism that encourages providers to confirm bids as early as possible. This is where a bid decay mechanism comes into play, which reduces the value of a bid based on the time elapsed since it was issued. ## Mechanism Description Every bid has two timestamps attached to it: **(1)** a timestamp indicating the exact time of dispatch of the bid, and **(2)** an expiry timestamp, marking the moment when the decay for this bid reaches 100%—essentially, the point in time beyond which the bidder is unwilling to pay anything to a provider for a commitment. The timestamp is specified in Unix milliseconds. For example, a timestamp of `1633046400000` represents `October 1, 2021 00:00:00 GMT`. When a provider decides to commit to the bid, they must issue a commitment and also assign a "commitment timestamp" to it. This commitment is then sent to the mev-commit chain for inclusion. The mev-commit chain will include the commitment into the chain, however the commitment will only be considered valid if the commitment timestamp supplied by the provider is not "too old" in comparison to the block timestamp where the commitment was included, or more formally, their difference is within some time interval $\Delta$. This time parameter $\Delta$ is set to be $500$ms, and its goal is to account for the latency in message delivery among nodes and the discrepancy between the commitment and block timestamps. More precisely, for validation of a commitment it is required that $t_b - t_c \le \Delta$, where $t_c$ denotes the commitment timestamp and $t_b$ denotes the timestamp of the block where the commitment was included. Note that even when $t_c > t_b$, i.e., the commitment timestamp was set to be greater than the timestamp of the block that it was included, the commitment is still considered valid. ## Computing the Bid Decay Once the commitment is included in the chain it can be publicly determined if the commitment is valid, and if so, what is the exact value that the bid has decayed. The bid's value decreases linearly from the moment it is issued until its expiry deadline is reached. Below we show a diagram of how providers can use the timestamps to first compute the proportion to which a commitment has decayed. Once the proportion has been computed the value of the bid can be decayed accordingly. For example, if the decay proportion is $1/2$ as in the example above, the bid's value decays by $50$%. In general, when a provider issues a commitment at time $t$ for a bid with amount $\mathrm{bidAmt}$, the bidder pays the provider the value $v$ computed as $$ v = \mathrm{bidAmt} \cdot \frac{\mathrm{decayEndTimestamp} - t}{\mathrm{decayEndTimestamp} - \mathrm{decayStartTimestamp}}, $$ constraint to $0 \leq v \leq \mathrm{bidAmt}$, i.e., the value $v$ paid is never more than $\mathrm{bidAmt}$. ## Analysis of the Mechanism The security of the mechanism comes from the fact that the participating parties have conflicting incentives. In particular, we note that there is no incentive for the bidder to manipulate the choice of the bid’s timestamps; if the bidder includes a timestamp in the future, then the provider essentially gets less decay (i.e., the bidder pays more). If the bidder includes a timestamp that is too old, then the provider can choose to not commit as the decay is too high (then the bidder gets no commitment). Moreover, we note that this would have the exact same effect as the bidder changing the price of its bid prior to the submission of the bid. Similarly, the commitment timestamp set by the provider must not be too old, as otherwise, it won't be valid when included in the mev-commit chain. In many network-based systems, including our decay mechanism, faster connections often provide better opportunities, such as quicker access to information or response times. This situation is similar to high-frequency trading in financial markets, where traders with faster connections can outperform others. In our system, any advantage due to a faster connection is bounded by the parameter $\Delta$. ## Properties of the Mechanism Our decay mechanism design achieves the following properties: **1. Predictability of Decay:** The providers can *accurately compute* how much their decay will be for a commitment. **2. Public Verifiability of Decay**: The decay mechanism offers public verifiability, as the decay amount can be calculated using the public timestamps from the bid and the commitment. **3. L1 Synchrony Independent:** Our decay mechanism maintains independence from the L1 actual slot time, ensuring that the decay mechanism functions correctly regardless of whether the L1 block confirmation occurs more quickly or experiences delays. **4. Just in time (JIT) Awareness of Bid:** JIT awareness of a bid ensures that the decay mechanism operates independently of the bid's submission time within the network, meaning a bid can be sent at anytime during a slot and experience correct decay. This is achieved by specifying the onset of decay and its deadline directly within the bid's structure, thus guaranteeing the mechanism functions as designed, irrespective of the bid's dispatch time. # Bid Structure Source: https://docs.primev.xyz/v1.1.0/concepts/bids/bid-structure The bid payload sent to the internal mev-commit API is as follows: | Key | Description | | --------------------- | ---------------------------------------------------------------- | | `txHashes` | Array of transaction hashes as strings | | `amount` | Bid amount in wei | | `blockNumber` | L1 block number targeted for bid inclusion | | `decayStartTimestamp` | Start timestamp for bid decay (in Unix milliseconds) | | `decayEndTimestamp` | End timestamp for bid decay (in Unix milliseconds) | | `revertingTxHashes` | Array of transaction hashes as strings that can revert | | `rawTransactions` | Array of raw signed transaction payloads | | `slashAmount` | Amount to be slashed from provider stake in case of a failed bid | Only one out of the `txHashes` or `rawTransactions` need to be provided in the bid. If the `rawTransactions` is given, the `txHashes` are inferred from it. ```json Example bid { "txHashes": ["0549fc7c57fffbdbfb2cf9d5e0de165fc68dadb5c27c42fdad0bdf506f4eacae", "0549fc7c57fffbdbfb2cf9d5e0de165fc68dadb5c27c42fdad0bdf506f4eacaf","0549fc7c57fffbdbfb2cf9d5e0de165fc68dadb5c27c42fdad0bdf506f4effff"], "amount": "100040", "blockNumber": 133459, "decayStartTimestamp": 1716935571901, "decayEndTimestamp": 1716935572901, "revertingTxHashes": ["22145ba31366d29a893ae3ffbc95c36c06e8819a289ac588594c9512d0a99810"] } ``` ```json Example bid with raw transaction payloads { "rawTransactions": ["0x02f8db82426882010c8410433624841043362f8303425094ea593b730d745fb5fe01b6d20e6603915252c6bf87016e03ce313800b864ce0b63ce0000000000000000000000000e94804eaa3c4c5355992086647f683f6f41ef1f000000000000000000000000000000000000000000000000000150e0786cc000000000000000000000000000000000000000000000000000000000000004e378c001a0ece6d13b20247abdc07d669c9186ee5a1ac9601db8c98a3323024ab299cb6662a01c20680efe4e0bb48a3a936b5ab27c741819f0ac567b12b34b230004b20b78a0", "0x02f8748242682c841043362684104336318252089412b141665da4a5f617c759ad996ef91ad806a9c0880de0b6b3a764000080c001a0806552ed846808580eb896994825f07e73de2f42e2d3554f228284ecfaa89d9ca046d58b62ba565982fb07a64b436dd7a6c210b2f59c4fb2aee2cdd150ccf8bfaa"], "amount": "100040", "blockNumber": 133459, "decayStartTimestamp": 1716935571901, "decayEndTimestamp": 1716935572901, "revertingTxHashes": ["22145ba31366d29a893ae3ffbc95c36c06e8819a289ac588594c9512d0a99810"] } ``` The final bid structure includes a hash and signature that is auto-constructed by your mev-commit bidder node and looks as follows. ```json { "txHash":"0549fc7c57fffbdbfb2cf9d5e0de165fc68dadb5c27c42fdad0bdf506f4eacae,0549fc7c57fffbdbfb2cf9d5e0de165fc68dadb5c27c42fdad0bdf506f4eacaf,0549fc7c57fffbdbfb2cf9d5e0de165fc68dadb5c27c42fdad0bdf506f4effff", "bidAmount":277610, "revertingTxHashes":"22145ba31366d29a893ae3ffbc95c36c06e8819a289ac588594c9512d0a99810", "blockNumber":2703, "digest":"uU2p20f5KmehWqpuY1u+CbhcS8jNwdQAJQe2dh0Vnrk=", "signature":"nY6jYsGPxj6LVlSVQJbZcxvmRrw8Ym5rqOL1x0W/xPlJGBaF/ZzzjkxiioY/MDiRGvlflSWeoT0fh3aIJiJxAhw=", "decayStartTimestamp":1716935571901, "decayEndTimestamp": 1716935572901, "slashAmt":0, "rawTransactions":["0x02f8db82426882010c8410433624841043362f8303425094ea593b730d745fb5fe01b6d20e6603915252c6bf87016e03ce313800b864ce0b63ce0000000000000000000000000e94804eaa3c4c5355992086647f683f6f41ef1f000000000000000000000000000000000000000000000000000150e0786cc000000000000000000000000000000000000000000000000000000000000004e378c001a0ece6d13b20247abdc07d669c9186ee5a1ac9601db8c98a3323024ab299cb6662a01c20680efe4e0bb48a3a936b5ab27c741819f0ac567b12b34b230004b20b78a0"], "nikePublicKey": "04c631d017981efdc0c319b475de36389a10ede86fbbc9adcf573844a858ce8ddcddb41306eb9c34ec4ee9bc0234f7e30684bf389142437166d407e47974d5cbf7" } ``` Note that the deposit amount a bidder has set needs to be 10 times higher than the amount in the bid. ## Details on Bid Structure | Property | Description | | ------------------- | ---------------------------------------------------------------- | | txnHash | Array of transaction hashes represented as strings | | bidAmount | Amount to bid in wei | | blockNumber | L1 target block to have bid included | | decayStartTimestamp | Start timestamp for bid decay (in Unix milliseconds) | | decayEndTimestamp | End timestamp for bid decay (in Unix milliseconds) | | bidDigest | Hash of the bid | | bidSignature | Signed bidВigest = sign(bidDigest, signingKey) | | nikePublicKey | NIKE public key of the bidder, autogenerated for each bid | | revertingTxHashes | Array of transaction hashes as strings that can revert | | rawTransactions | Array of hexadecimal encoded raw signed transaction payloads | | slashAmount | Amount to be slashed from provider stake in case of a failed bid | ### Details on Decay Parameters The `decayStartTimestamp` and `decayEndTimestamp` parameters allow bidders to control the range over which their bid decays. Due to inherent network delays, preconfirmation times can range between 50 to 250 milliseconds even if providers commit immediately after seeing the bid. To account for this, you might want to set your `decayStartTimestamp` approximately 300 milliseconds in the future. However, setting this delay is not mandatory and should be adjusted based on your strategic preferences for bid timing and pricing. For more detailed information about the decay mechanism, refer to the [Bid Decay Page](https://docs.primev.xyz/v1.1.0/concepts/bids/bid-decay-mechanism). ### Details on Encrypted Bid Structure The bid structure is encrypted using an AES key, which the bidder P2P node generates at the start, and is then sent to the provider. ```json { "ciphertext": "5750d8af6296296f1147f5e11f47f253f376dea3fd5c2760cd82bd82a7066a8fe1c84f48a4e738d1df7c0e64f930c6b0b642800156e453a501c8b993951fcb50fe0b9fce4a2046838f499317a6018eb59abd5e84dbe3b7e296d4e0e70ef3bb221af7afe341908dbd02e8c91b4eff935b2697208f51ccacf5fe744c199afca687d85850a2e12a75433510dccda9258612348c586e971cc521486806ea25ec94d5fa7038beda3f532970e7b06198deef96677af3a6889c84d657585a9eefd224961f87a3353ad4ede4a7368e2e5bc9571d320a8a3be0f1e08e769f9bb2da6fb76c81cd" } ``` # Understanding Bidder Deposit Rules Source: https://docs.primev.xyz/v1.1.0/concepts/bids/bidder-deposit Bidders need to deposit funds to be able to place bids on the mev-commit network. As bids are posted privately, providers cannot determine how much bidders have bid previously. To still ensure that bidders can cover all their bids, we bind deposits to specific L1 block numbers. Providers con thus ensure that bids from a given bidder do not exceed the amount deposited for the corresponding L1 block number. It is important to note that if a bidder deposits, for example, 1 ETH for some L1 block number, they can post bids totaling 1 ETH for each provider. This is because only a single provider can post the block to L1, meaning bids made to other providers will not be executed. To simplify the user experience, mev-commit considers windows consisting of $\text{blocksPerWindow} = 10$ blocks and splits deposits to a window evenly over the corresponding blocks. The remaining funds of a bidder from a window (if any) can be unlocked after the corresponding blocks have been settled. The bidder can then withdraw the funds from the deposit. To further ease the user experience, bidders can enable autodeposits in their nodes, to automatically withdraw deposits from previous windows and redeposit them into future ones. ## Current window number The window number for a given L1 block can be calculated via the following formula, where `blocksPerWindow` is equal to 10 and `blockNumber` is the L1 block number for which the bidder wants to bid: $$ \frac{{\text{{blockNumber}} - 1}}{{\text{{blocksPerWindow}}}} + 1 $$ ## Minimum Deposit Since deposits are split across $\text{blocksPerWindow} = 10$ L1 blocks, bidders have to deposit at least 10 times the amount they want to bid for a single block. In the case of autodeposit, the deposits would be locked for around 3 windows at a time. Therefore, the total amount locked would be 30 times the amount. ## Withdrawal Time The earliest withdrawal time can be calculated as follows: the withdrawal start time plus 20 L1 blocks (which is 240 seconds or 4 minutes) and the oracle lag of 10 L1 blocks (which is 120 seconds or 2 minutes), totaling 360 seconds or 6 minutes. Therefore, the total time before funds can be withdrawn is approximately 30 blocks (6 minutes) from the initial deposit. ## Deposit/Withdrawal Flow This diagram illustrates the process and timeline of bidding, settlements, and withdrawals within mev-commit system, structured around a series of windows. ### Diagram Description #### Timeline of Blocks * The horizontal axis represents a sequence of windows. * Windows are labeled as `n-2`, `n-1`, `n` and `n+1`, indicating their position relative to the current window `n`. #### Current Window * The "Current Window" is the interval within which bidding occurs. * The window consists of 10 L1 blocks. #### Bidding Phase * Bidding occurs in the current window, starting from the current block `n` and extending into the future blocks (`n+1`, etc.). * The arrow labeled "Bidding" points to the right, indicating that bidding continues into future blocks. #### Settlements Phase * Settlements happen after the bidding window closes. * The arrow labeled "Settlements" points downward, showing the transition from the bidding phase to the settlement phase. #### Withdrawals Phase * Withdrawals occur after settlements are completed. * The arrow labeled "Withdrawals" points to the left, indicating the final phase where bidders can withdraw their remaining funds. # null Source: https://docs.primev.xyz/v1.1.0/concepts/bids/reverting-txns ## Reverting Transactions Transactions are by default execution commitments when put in the bid payload. The `revertingTxHashes` field is used to describe transactions that you would like to allow to not need to be executed. When you include transaction hashes in the `revertingTxHashes` array, you are indicating that these transactions can be reverted if necessary. This can be useful in scenarios where certain transactions are optional or conditional, and their execution is not strictly required for the bid to be valid. Here is an example of how to include reverting transactions in your bid payload: ```json Example bid { "txHashes": ["0549fc7c57fffbdbfb2cf9d5e0de165fc68dadb5c27c42fdad0bdf506f4eacae", "0549fc7c57fffbdbfb2cf9d5e0de165fc68dadb5c27c42fdad0bdf506f4eacaf","0549fc7c57fffbdbfb2cf9d5e0de165fc68dadb5c27c42fdad0bdf506f4effff"], "amount": "100040", "blockNumber": 133459, "decayStartTimestamp": 1716935571901, "decayEndTimestamp": 1716935572901, "revertingTxHashes": ["22145ba31366d29a893ae3ffbc95c36c06e8819a289ac588594c9512d0a99810"] } ``` In the example above, the `revertingTxHashes` field is used to specify a list of transaction hashes that can be reverted if necessary. This field is an array of strings, where each string represents a transaction hash. In this particular example, the `revertingTxHashes` array contains a single transaction hash: `"22145ba31366d29a893ae3ffbc95c36c06e8819a289ac588594c9512d0a99810"`. This means that the transaction with this hash can be reverted if needed, without invalidating the bid. By including the `revertingTxHashes` field, bidders can provide flexibility in their bids, allowing certain transactions to be reverted if necessary, which can be useful in various scenarios where transaction execution is conditional or optional. # Builder Attribution Source: https://docs.primev.xyz/v1.1.0/concepts/builder-attribution Understanding how builders are identified and attributed in mev-commit # Builder Attribution Builder attribution in the mev-commit system involves identifying the provider responsible for building an L1 block. This is crucial for ensuring that rewards and slashing mechanisms are correctly applied based on the commitments made by providers. ## How Builder Attribution Works ### Oracle and Builder Attribution The oracle plays a central role in verifying whether commitments made by providers are fulfilled. It does this by: * Querying the PBS relay to obtain block delivery data and associated BLS keys * Cross-referencing block hashes from L1 with those delivered via the relay * Identifying the builder through their registered BLS key when block hashes match * Validating commitments against the identified builder in the mev-commit system This system ensures accurate provider attribution for block building and appropriate distribution of rewards or penalties based on commitment fulfillment. # null Source: https://docs.primev.xyz/v1.1.0/concepts/commitments Commitments represent promises made by providers in a cryptographically verifiable manner. | Key | Description | | --------------------------- | --------------------------------------------------------------------- | | `commitmentDigest` | Represents the hash of the bid structure, including the bid signature | | `commitmentSignature` | Represents an ECDSA signature of the `commitmentDigest` | | `commitmentProviderAddress` | Represents the address of the provider | | `sharedSecret` | Represents the shared secret between the bidder and provider | ```json Example commitment { "result":{ "txHash":"91a89B633194c0D86C539A1A5B14DCCacfD47094", "bidAmount":"2000", "blockNumber":"890200", "receivedBidDigest":"61634fad9081e1b23a00234a52a85386a91fc0fad3fb32d325891bdc4f8a52a9", "receivedBidSignature":"be99f499be5483665d569bd52fa8c4c9ed5c3bed2f94fb9949259bf640d8bd365b1d9a4b9ccb3ace86ffdcd1fdadc605b0f49b3adaf1c6a9ffea25585234664f1c", "decayStartTimestamp":"1716935571901", "decayEndTimestamp":"1716935572901", "nikePublicKey":"04c631d017981efdc0c319b475de36389a10ede86fbbc9adcf573844a858ce8ddcddb41306eb9c34ec4ee9bc0234f7e30684bf389142437166d407e47974d5cbf7", "commitmentDigest":"08a98d4c9d45f8431b46d99a23e6e8f82601ccf0773499d4e47bcd857cad92a6", "commitmentSignature":"cfc1e4e2ea9cc417027ed5846fa073c8e6031f70f91ffa9b92051b5b7738c0500d8fefb0fc189bce16004b3c0e1c4cfa41260968161adf8b55446ed5c40d1ac51b", "commitmentProviderAddress":"0x1234567890123456789012345678901234567890", "sharedSecret":"0x1234567890123456789012345678901234567890", } } ``` The commitment consists of the details associated with the bid along with signatures made by the provider. The provider generates a digest from the commitment, signs it with their private key, stores the digest and signature as an encrypted commitment on the mev-commit chain, and sends the commitment back to the originating bidder via the P2P network. ```json { "result":{ "commitment":"08a98d4c9d45f8431b46d99a23e6e8f82601ccf0773499d4e47bcd857cad92a6", "signature":"cfc1e4e2ea9cc417027ed5846fa073c8e6031f70f91ffa9b92051b5b7738c0500d8fefb0fc189bce16004b3c0e1c4cfa41260968161adf8b55446ed5c40d1ac51b", } } ``` # Bridging Details Source: https://docs.primev.xyz/v1.1.0/concepts/mev-commit-chain/bridging-details # Understanding Bridging Mechanisms The mev-commit chain utilizes a standard bridging mechanism to ensure a secure and efficient transfer of ETH between mainnet Ethereum and the mev-commit chain. We envision mev-commit to eventually integrate with a multitude of interoperability protocols (think wormhole, layerzero, etc.). In the meantime Primev has implemented its own lock/mint bridging protocol as described below. ## Lock/Mint Peg Native ETH on the mev-commit chain maintains a 1:1 peg with ETH on L1. The only way to mint ETH on the mev-commit chain is to lock an equivalent amount on L1. ETH can be burned on the mev-commit chain to release/receive an equivalent amount on L1. ## Security There are inherent security assumptions in bridging ETH to the mev-commit chain. While these are similar to other bridge trust assumptions, we've listed them below: * Liveness of the bridge relayer actor. * POA signers that maintain mev-commit chain state. * Correctness of Primev's [standard bridge protocol](https://github.com/primev/mev-commit-bridge/tree/main/standard/bridge-v1) and integration into the mev-commit chain. Our standard bridge implementation has been audited by Cantina. More details can be found [here](https://blog.primev.xyz/Battle-Testing-mev-commit-Key-Findings-from-Our-Spearbit-Security-Review-1436865efd6f8025bd6ce3824349821d). ## **Importance of Origin Chain Security** **Selective Bridging**: Only bridges originating from Ethereum L1 should be allowed to mint native ETH on the mev-commit chain. This is to prevent the impact of compromised states on other chains affecting the mev-commit chain. ## Bridge Contracts See **Bridge Contracts** section of [contracts page](/v1.1.0/developers/contracts) to gain context on contracts necessary to enable bridging. ## Relayer The main off-chain component of the bridge is the relayer. Primev currently operates the relayer, with open-sourced implementation [here](https://github.com/primev/mev-commit/tree/main/bridge/standard). # Chain Details Source: https://docs.primev.xyz/v1.1.0/concepts/mev-commit-chain/chain-details The mev-commit chain is live on [mainnet](/v1.1.0/developers/mainnet). To test and experiment, join the testnet and get familiar with its functionalities at the [testnet](/v1.1.0/developers/testnet) section. ## Design Mev-commit chain is currently built out as an Ethereum sidechain run with [go-ethereum’s Clique proof-of-authority consensus mechanism](https://geth.ethereum.org/docs/tools/clef/clique-signing). It's not a generalized chain for everyone to launch dapps on, but only for specific execution service applications, such as preconfirmations, top of block, bottom of block, or other services. Source code for the geth fork which runs the mev-commit chain can be found in the [mev-commit-geth repo](https://github.com/primev/mev-commit-geth). ## Progressive decentralization Today, most or arguably all Ethereum scaling solutions rely on centralized bridging and sequencing. Mev-commit components rely on existing tech, and consequently inherit this property. However anyone can permissionlessly validate correct execution, and operation of chain infrastructure. Moreover, because the mev-commit p2p network is decentralized and commitments are cryptographic, actors can theoretically settle commitments without the mev-commit chain. At this point of the network's inception, Primev entities will run all validating infrastructure for the mev-commit chain. Correct and honest operation can be permissionlessly audited by spinning up a full node and connecting to the mev-commit chain as a peer. Over time we plan to have entities outside of Primev to become POA signers or bridge validators to progressively decentralize the centralized components of the system. The mev-commit chain will continue to evolve. We have ongoing research into consensus algorithms we can employ to decentralize the mev-commit chain without compromising on speed. Open source scaling solutions that prove to be practical, decentralized, and meet security thresholds will be considered to decentralize the mev-commit chain. ## POA geth nodes Primev currently maintains a mev-commit-geth bootnode which doesn’t participate in consensus, and a set of full-node POA signers that run consensus. These signers take turns proposing the next block by utilizing a waiting period. The current target block period is 200ms, meaning about 60 mev-commit chain blocks will be committed for every Ethereum mainnet block. The block time will likely change as enhancements are added and chain state grows. ## Fee Mechanism **Non-inflationary**: The fee mechanism on the mev-commit chain is non-inflationary, maintaining a strict 1:1 peg between sidechain ether and L1 escrowed ether. This is achieved through a variation of EIP-1559, where both the base and priority fee accumulate to a treasury account (preconf.eth address). ## Smart Contracts Smart Contracts are deployed on the mev-commit chain to enable use cases, follow bid and commitment states, and invoke rewards or slashing as needed. Anyone can deploy contracts on the mev-commit chain, however there'll be additional integration work needed with mev-commit off-chain components to fully enable the use case under the current design. Thus we first recommend getting in touch with the Primev team to enable a use case at this stage of the network. Currently deployed contracts are designed as follows: * A preconfirmation contract allows preconfirmation commitments to be stored and tracked on-chain. * Two separate registry contracts exist to manage bidders and providers, both parties must stake ETH to participate. Rewards and/or slashing are managed by these contracts. * An oracle contract receives L1 payloads from the oracle service. It currently operates by checking confirmed mainnet blocks. * An block tracker contract which designed to track Ethereum blocks and their respective winners. ## Oracle service The oracle service is an off-chain process that interacts with the oracle contract as needed. This service monitors and extracts the winning builder and corresponding transaction hash list from each L1 block, and submits this data to the oracle contract residing on the mev-commit chain. This is a centralized oracle currently operated by Primev. We're actively looking into decentralizing the oracle role through existing decentralized Oracle protocols and evaluating creating a service where this can be decentralized. # Differences Between Ethereum and mev-commit Chain Source: https://docs.primev.xyz/v1.1.0/concepts/mev-commit-chain/differences-between-ethereum-and-mev-commit-chain ## Introduction Mev-commit chain is an Ethereum-compatible blockchain designed to provide faster transaction processing and lower fees. It aims to optimize the extraction of Maximal Extractable Value (mev) by utilizing a specialized architecture. This document highlights the key differences between Ethereum and mev-commit chain. ## Overview The following table provides an overview of the key features and differences between Ethereum and mev-commit chain: | Feature | Ethereum | Mev-Commit Chain | | ---------------- | ------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- | | Mempool | Larger mempool size | Smaller mempool size, transactions may be encrypted, limited chain mempool visibility due to fewer chain node operators | | Validators | Decentralized proof of stake system with a large number of validators | Centralized setup with only two validator nodes creating blocks in a round-robin fashion, allowing for faster consensus and block production | | Opcodes | Supports Ethereum opcodes | Supports all Ethereum opcodes, ensuring compatibility with existing Ethereum smart contracts and tools | | Consensus | Uses proof of stake consensus, prioritizing decentralization | Uses clique proof of authority consensus, where authorized validators take turns creating blocks, prioritizing performance and fast block times | | Block time | 12 seconds | 200 milliseconds | | Transaction Fees | Supports both legacy and EIP-1559 transactions, with base fee being burned and priority fee going to the proposer/signer | Supports both legacy and EIP-1559 transactions, with base fee directed to the protocol treasury and priority fee going to the proposer/signer | ### Transaction Fees Like Ethereum, mev-commit chain supports both legacy and EIP-1559 transactions, with a preference for EIP-1559. The allocation of fees differs: * The base fee is directed to the protocol treasury, instead of being burned. * The priority fee goes to the proposer/signer, as in Ethereum. ### Mempool Mev-commit chain's mempool is smaller compared to Ethereum's. While the mempool is public, transactions may be encrypted, and chain mempool visibility is limited due to the presence of only a few chain node operators. This reduces the potential for front-running and other mev-related activities. ### Number of Validators Mev-commit chain currently operates with only two validator nodes that create blocks in a round-robin fashion. This centralized setup allows for faster consensus and block production. However, it also introduces a higher level of trust in the validators compared to Ethereum's decentralized proof of stake system. ### Opcodes Mev-commit chain supports all Ethereum opcodes, as it consists of Ethereum nodes. Opcodes are low-level instructions that define the operations a blockchain can perform. By supporting all Ethereum opcodes, mev-commit chain ensures compatibility with existing Ethereum smart contracts and tools. ### Consensus Mainnet Ethereum uses proof of stake, while mev-commit chain currently uses clique proof of authority consensus. In clique proof of authority, a set of authorized validators take turns creating blocks. This consensus mechanism prioritizes performance and fast block times over decentralization. ## Conclusion Mev-commit chain offers a specialized blockchain environment optimized for mev extraction. With faster block times, a different fee structure, and a centralized validator setup, mev-commit chain provides an alternative to Ethereum for use cases that prioritize speed and mev optimization. # Understanding mev-commit Source: https://docs.primev.xyz/v1.1.0/concepts/network-overview ### Overview Mev-commit is designed as an out of protocol layer to systems like mev-boost, facilitating the exchange of execution bids and commitments between mev actors, solving for coordination inefficiencies. This design ensures that only necessary parts of this faciliation happen on mev-commit (bids, commitments, settlement) and not the transaction flow itself. This design achieves chain abstraction by its nature, as any transaction hash on any chain can be referred to in a mev-commit bid, and be paid in eth. Bids and commitments on mev-commit also do not rely on blockchain bottlenecks and are real-time. ### Bids and Commitments Bids are received and evaluated by providers, who run decisioning logic in their own environment and may decide to issue a cryptographic commitment against whatever the bid is for. In the preconfirmation case, the minimum a commitment can be made is for inclusion of the referred transaction hash(es) in the bid on the target L1 block number specified. ### Settling Commitments Commitments are simultaneously sent to bidders and the mev-commit chain in hash format. This ensures the network can operate with end-to-end pre-execution privacy and low latency. Once the commitment is revealed by either of the participating parties at the end of a slot, an oracle will check the target L1 block number as it gets confirmed to see if the commitment is delivered. If so, the bid amount will be rewarded to the provider. If not, the provider stake will be slashed. ### Rewards and Slashing *Only the actors who participated in the block's confirmation are considered for rewards or slashing.* This means if Block Builder A and Block Builder B commit to a bid and the target block is built by Block Builder A, the oracle will reward or slash Block Builder A. ### Network Architechture The architecture of the mev-commit peer-to-peer (P2P) network is designed to support instantaneous communication among network participants. The diagram below depicts how mev-commit acts as a layer on bidder and provider operations, that are external to the mev-commit network by its nature: ### Network Connectivity The network is structured to ensure robust connectivity among users and providers. Each participant node connects to a primary network node, known as a bootnode, during the initial startup phase, establishing a foundational network link. ### Gateway Nodes The subsequent diagram provides a detailed representation of the bid, commitment, and fund flows within the mev-commit framework, showcasing the efficiency and effectiveness of interactions among mev actors. # null Source: https://docs.primev.xyz/v1.1.0/concepts/oracle **The primary role of the oracle is to ensure that the provider carries through on their commitments.** The oracle consists of two parts: * A smart contract component [here](https://github.com/primev/mev-commit/blob/main/contracts/contracts/core/Oracle.sol). * A microservice [here](https://github.com/primev/mev-commit/tree/main/oracle). The oracle automates the verification of provider commitments and queries the L1 data source for transaction hashes and block extra data. It then cross-references these with commitments logged in the commitments contract, and then verifies adherence using the oracle contract. If a commitment is satisfied, the oracle contract triggers a reward to the provider using the bidder contract; if not, it slashes the provider by interacting with the provider contract. ## Prior to Oracle Engagement Before the oracle can be engaged according to the protocol's intended sequence of events, several preliminary actions must be taken: **1a.** Simultaneously, the bidder issues an encrypted bid via the mev-commit peer-to-peer network. *After the bidder's actions, the provider proceeds to:* **2a.** Retrieve the encrypted bid from the mev-commit network. **2b.** Issue an encrypted commitment for the transaction mentioned in the bid. ## Oracle Happy Path Flow When a bid for a transaction (txnj) is circulated through the mev-commit p2p network, and the provider has made an encrypted commitment and then opened it after the L1 block was created, the oracle is activated to verify whether the provider has honored this commitment. The process is as follows: 1. The provider assembles the complete L1 block, incorporating txnj, to which it previously committed. **Note: If the provider doesn’t get selected to construct the L1 block, the oracle flow does not get triggered.** 2. The oracle microservice fetches the block from the L1 chain and verifies the presence of txnj. 3. Upon confirmation that txnj is included, the microservice notifies the oracle smart contract of the commitment's fulfillment. 4. The oracle smart contract then initiates the transfer of funds from the bidder's deposited balance to the provider's account. ## Oracle Slashing Path In the event that a provider fails to include a committed transaction (txnj) in the L1 block, the oracle slashing path is initiated to penalize the provider for the breach of commitment. This process is outlined below: 1. The provider is expected to produce an L1 block that includes the committed transaction (txnj). However, if the provider does not include txnj, the protocol moves to the slashing phase. 2. The oracle microservice retrieves the block from the L1 chain and searches for txnj. If the transaction is not found, it triggers the next step. 3. The oracle communicates that txnj was not seen in the oracle contract. 4. The oracle contract, upon receiving this information, initiates the slashing procedure. This involves penalizing the provider by triggering a slash event, which results in the forfeiture of the stake held by the provider contract as a guarantee of honest behavior. 5. The confiscated stake is subsequently allocated to the bidder as compensation for the provider's failure to include the committed transaction, thereby ensuring that the bidder is recompensed for the provider's breach of trust. # Security & Privacy Source: https://docs.primev.xyz/v1.1.0/concepts/privacy If bids and transaction bundles were transmitted in clear text over the peer-to-peer (P2P) network, it could allow competing bidders and providers to observe and adjust their strategies based on the visible bids. This visibility potentially harms the expected utility of bidders, as their competitors could outbid them by adjusting their bids accordingly. Moreover, the premature revelation of a provider’s commitment to a bid could lead to information leakage about the total value of the block being constructed. This would not only affect the privacy of the providers but also skews the competitive landscape, enabling providers to underbid based on the leaked value information. To counteract these privacy issues mev-commit provides end-to-end privacy for all bids and commitments in the sense that until commitments are opened after the corresponding L1 block has been confirmed, the contents of the commitment and the corresponding bid are only visible to the bidder who made the bid and the provider who made the commitment. All other bidders and providers and external parties learn nothing except that this provider has made a commitment. Moreover, it is crucial that commitments to bids are binding to the specific bid, i.e., that the commitment can only be opened for that single bid. Since bidders and providers can have conflicting incentives, it is important that they can both open the commitments, which is guaranteed using zero-knowledge proofs. The security and privacy of mev-commit is achieved by combining two novel cryptographic primitives, anonymous receiver-updatable broadcast encryption (ARUBE), and dual-phase commitments (DPCOM), with a highly efficient ZK proof. ARUBE is used to efficiently disseminate bids from bidders to providers of their choice in a privacy-preserving manner, DPCOM is used to securely commit to those bids and later allow for the opening of such commitments, and a ZK proof is used to ensure that commitments can be opened by providers and bidders. Below we expand on the specific security and privacy notions achieved for the bidders and the providers along with a short description of the corresponding cryptographic primitive used for each. ## Posting Bids Each bidder can choose a group of providers who will have access to their bids. The bids are then encrypted and sent to this specific group of providers. Other bidders and providers remain unaware of the details of a bid and its designated receivers. The cryptographic primitve that mev-commit leverages to achieve this privacy notion in an efficient way is called ARUBE. ### Anonymous Receiver-Updatable Broadcast Encryption (ARUBE) ARUBE is the primitive that allows bidders in the mev-commit protocol to privately send bids to a subset of the providers without revealing what this subset is. This functionality is commonly provided by anonymous broadcast encryption [\[BBW06\]](https://www.cs.utexas.edu/~bwaters/publications/papers/privatebe.pdf). A feature of broadcast encryption is that a new set of recipients can be specified for each message that is encrypted. In commitment games, the set of recipients for a given bidder typically remains stable since bidders mostly send their bids to the set of providers they work with and occasionally add or remove a provider from that set. To be able to leverage this for more efficient schemes, we refine the notion of broadcast encryption by adding an algorithm for updating the set of recipients, while the encryption algorithm encrypts a message for a previously determined recipient set. We call this notion anonymous receiver-updatable broadcast encryption (ARUBE). The image below illustrates ARUBE in operation, where a bidder securely posts an encrypted bid to providers A and B. Provider C and any eavesdropper will be unable to decrypt the bid. Using ARUBE, mev-commit keeps all information and value related to bids private pre-execution while allowing them to be settled in a decentralized manner. ## Committing to Bids A provider who receives a bid can make a commitment to it, which they also sign for authentication. The signed commitment binds the provider to the bid. Furthermore, the process is executed in such a way that only the bidder who issued the bid can identify a commitment as being related to their bid. This approach ensures a high level of privacy for the providers, as the commitments they issue are not linkable to a specific bid. In a normal run of the protocol the provider opens all its commitments at the end of the L1 slot, however if the provider refuses to open any of its commtiments, the bidder can independently open the commitment without needing assistance from the provider. This functionality is provided by the novel notion of dual-phase commitments. ### Dual-Phase Commitment (DPCOM) DPCOM is a two-party commitment protocol that allows a message to be committed in two distinct phases. In the first phase, one party precommits to a message and receives both a precommitment and an opening key. In the second phase, the other party commits to the precommitment generated in the first phase, receiving a decommitment information as the output. A key feature of a dual-phase commitment scheme is its flexibility in opening the resulting commitment using either the opening key or the decommitment information. This is especially useful in the context of the mev-commit protocol, where the bidder generates a precommitment to its bid, after which the provider commits to that precommitment. This process also ensures that both parties can open the commitment: the bidder obtains the opening key when generating the precommitment, and the provider obtains the decommitment information when committing to the precommitment. Consequently, both parties can later prove the content of the committed message to third parties. Crucially, if the provider misbehaves and refuses to publicly open the commitment, the bidder can independently open it without needing assistance from the provider. The image below illustrates provider B committing to a bid posted by bidder 2, while the other parties remain unaware of the specific bid being committed to. You can read more on ARUBE and DPCOM [here](https://mirror.xyz/preconf.eth/iz2J0uTXHhl8DiAkG-VLLwvCp-8qcc_Z7A8_4rU0A3g). ## ZK Proofs for Opening Commitments A crucial property of the commitments issued by providers on mev-commit is that they can both be opened by providers as well as bidders. Being able for the bidders to open commitments is necessary when providers violate the commitment and thus have no incentive to open it. Therefore, when providers open a commitment, they have to prove in zero-knowledge that the commitment was generated correctly. This ZK proof is verified in a smart contract on the mev-commit chain when the provider sends the commitment-opening transaction. Thus, a provider can only open commitments that have been generated correctly and could also have been opened by the bidder. ### Implementation and Efficiency The ZK proof used has been tailor-made for this particular use-case and optimized for efficiency. It is based on so-called sigma protocols and only requires a few elliptic curve operations and the computation of a hash. Generating a single ZK proof for the commitment opening takes only 0.122 milliseconds on a Mac M1 Pro. Furthermore, only around 32k gas is consumed in the smart contract to verify the proof. For comparison, the overall gas cost of the commitment opening transaction is around 488k gas. Hence, only less than 7% of the gas cost is attributed to the zero-knowledge proof verification. More details on the used ZK proofs can be found [here](https://mirror.xyz/preconf.eth/AgtLSBob1hd2A924vlL7jCyJxQDZZE2tCq_K07w5vuU). # mev-commit Points Program Source: https://docs.primev.xyz/v1.1.0/concepts/rewards-and-slashing/points The `mev-commit` Points Program rewards validators who opt-in and remain actively opted-in. Points accrue over **6-month Seasons**, with each Season offering base points plus growing multipliers. All points will be visible on the [Validator Dashboard](https://validators.mev-commit.xyz/) like the screenshot below. Read more to learn how points are awarded and how to maximize your total. ![Points on the Dashboard](https://mintlify.s3.us-west-1.amazonaws.com/primev-24/v1.1.0/images/dashboard-points.png) ## Quick Overview * **Immediate Reward:** Earn **1,000 points** per validator right when you opt in. * **6-Month Seasons:** Completing an entire Season nets you up to **10,000 points** total in Season 1, and double for following seasons. * **Multipliers:** * Season 1: base schedule (see table below). * Season 2 & 3: rewards are **2×** each month’s total. * **Opt-Out Penalties:** If you opt out early during a season, you keep the **base points** for fully completed months but **lose** that month’s multiplier. Stay opted in with as many validators through all seasons for the maximum multiplier bonus. *** ## Monthly Accrual (Season 1) Below is the monthly schedule for Season 1, showing **cumulative** points if you remain opted in through each month: | Month | Total Points if Still Opted In at Month End | | --------- | ------------------------------------------- | | 1 | 1,000 | | 2 | 1,270 | | 3 | 1,530 | | 4 | 1,800 | | 5 | 2,070 | | 6 | 2,330 | | **Total** | **10,000** | * Points accrue **daily**, but the monthly multiplier is only **finalized** if you remain opted-in through each 6 month Season. * **Season 2 & 3** double all monthly totals shown above (2x). ## Points Chart Below is a visualization of your points over the planned 3 Seasons. Accrued points represent all points available at the end of a season. Solidified points represent points that will remain with your operator before a Season is over. ![Points Chart](https://mintlify.s3.us-west-1.amazonaws.com/primev-24/v1.1.0/images/points-chart.jpg) ## Aggregated Points at Operator Level Your dashboard displays **one aggregate total** across all your opted-in validators. Operators can see total points and watch them grow daily. ## Maximize Points via Partner Protocols You can earn additional or parallel rewards when using partner protocols alongside `mev-commit`: * **EigenLayer:** Operators opted-in to the `mev-commit AVS` on EigenLayer may earn `$eigen` token rewards (based on EigenLayer’s policies). * **Symbiotic, Mellow, SSV:** Opt-in validators using these protocols to earn points from them AND mev-commit. Points will be available on the Symbiotic dashboard as well. If you participated in prior **testnet phases**, you may be eligible for extra **genesis points**. Please reach out to our team so we can verify your participation and make your bonus available. *** ## Opt-Out Scenarios * **Before Month Ends** * You keep points from previous fully completed months. * You **forfeit** any partially accrued points for the current month. * **Before 6 Months But After Some Full Months** * You keep **1,000 base points** for each fully completed month in Season 1, double for subsequent seasons. * You **lose** the monthly multiplier for those months. * Example: If you leave before the end of a Season, you only keep 1,000 for each completed month without the monthly multiplier. * **Opting Out and Re-Opting In** * A **7-day cooldown** applies for each validator key if you opt out. If you have trouble with this, reach out to our team. * Rejoining resets you to Season 1 status. *** ## Getting Started 1. **Opt In** * Visit the [Validator Dashboard](https://validators.mev-commit.xyz/) to onboard. 2. **Stay In** * Maintain participation for all seasons to maximize multipliers. 3. **Explore Partner Integrations** * Symbiotic, Mellow, SSV, or supporting `mev-commit AVS` on EigenLayer for additional rewards. Participating early and continuously strengthens the network, making each individual’s participation more valuable. Your yield goes up more by opting-in as many validators as you can. That’s it! Maximize your `mev-commit` points and help make Ethereum FAST for everyone. Earn juicy yield AND points! # Rewards and Slashing Source: https://docs.primev.xyz/v1.1.0/concepts/rewards-and-slashing/rewards-and-slashing The providers and validators that opt-in to the mev-commit protocol are incentivized to act honestly and follow the protocol. This honest behavior is enforced by a reward and slashing mechanism. Both the providers and the validators are required to stake or restake a certain amount of tokens to participate in the mev-commit protocol. The mechanism is designed to reward providers for fulfilling their commitments and to penalize them for breaking them. It also disincentivizes providers from issuing commitments that they cannot fulfill. Additionally, validators can be penalized if they fail to propose a block from mev-commit registered block builders on the L1 chain. Validators have three methods to opt-in to mev-commit, as described in the [validators section](/v1.1.0/get-started/validators). The staked (or restaked) tokens are used to secure the mev-commit protocol and to incentivize validators to include blocks built by mev-commit providers in the L1 chain. Crucially, if the validator acts maliciously on the mev-commit protocol they can be slashed and lose a portion of their staked (or restaked) tokens. Next, we discuss the rewards and slashing mechanisms for validators and providers in more detail. The risk of getting slashed is very low for validators, unless they intentionally behave dishonestly. This has been confirmed by an [independent report on the risk/reward profile of mev-commit by Chaos Labs](https://governance.ether.fi/t/primev-symbiotic-risk-analysis/). ## Validators/Proposers A validator that opts into mev-commit makes an implicit commitment to include a block from a mev-commit registered block builder in L1 whenever they become the proposer of the slot. ### Rewards There are two categories of rewards for validators opting in to mev-commit: 1. Increased yield 2. [Points](/v1.1.0/concepts/rewards-and-slashing/points) The main reward for proposers opting in to mev-commit is increased yield by proposing a more valuable block, paid through the mev-boost auction. Upon proposing a block while opted-in to mev-commit, a proposer will receive all bid related value in the mev-commit network that is surfaced by the mev-boost auction embedded in the block they propose. In other words, proposers passively receive rewards from mev-commit by proposing more valuable blocks that include increased value from mev-commit bids. A proposer will almost always propose a more valuable block using mev-commit than without while mev-commit bids are present for its slot. Using an example of a block worth 1 ETH and mev-commit bids worth 0.1 ETH, the diagram below depicts Validator Rewards with and without mev-commit: ![Validator Rewards](https://mintlify.s3.us-west-1.amazonaws.com/primev-24/v1.1.0/images/validator-rewards.png) An important observation here is that proposers opting in increases the credibility of the preconfs and consequently their value. Due to the increased preconf values, the providers have additional value to bid in the mev-boost auction, thus driving up the total revenue a proposer will get. ### Slashing Validators are generally **not expected to be slashed** on mev-commit unless they act maliciously, as providers on mev-commit are the primary decision makers liable for any slashing. The only case for a proposer slash is acting maliciously or using an unsupported relay / validator sidecar misconfiguration. For missed blocks or self-built blocks, mev-commit does not slash proposers. We detail these cases below. #### Missed Block A proposer can completely miss its slot and not include any block in L1. This can happen either due to network issues by the proposer, due to the relay not delivering the block's contents on time, or due to chain reorgs. In any case, mev-commit does not slash the proposer for missing a block as the proposer does not profit from omitting a block and it is potentially out of their control. #### Included Block Not Built by mev-commit Provider A proposer can include a block in L1 that was not produced by a mev-commit provider. This can happen for the following reasons: 1. The proposer includes a block from a builder that is not participating in the mev-commit protocol. This can be due to a malicious behavior by the proposer or due to the proposer using a relay that is not compatible with mev-commit (and thus delivering blocks not built by mev-commit providers). 2. The proposer includes a block that was built by itself. Case (1) is considered non-compliant behavior and thus the proposer will be slashed from their stake the fixed amount of 1 ETH. Case (2) should only happen very rarely when the value of the block it receives from the relay is too low, and mev-commit will not slash proposers in this case. However, due to the lack of a robust mechanism for builder attribution of a block in Ethereum's PBS, we will monitor how often proposers choose to build their own blocks, and if needed we will revisit this decision to discourage misbehavior by the proposers. Currently, the restaking case with Eigenlayer only allows the stake to be frozen for an undetermined period of time and not slashed permanently (i.e., burned). While the stake is frozen, the proposer is not able to participate in mev-commit. The proposer can pay a fee to unfreeze its stake. This is a limitation of the current Eigenlayer implementation, and it is expected to be resolved. ## Providers There are four possible outcomes after a commitment is made by a provider and an Ethereum block is proposed: 1. The bid amount is rewarded to the provider for fulfilling the commitment. 2. The provider stake is slashed for breaking the commitment. 3. Nothing happens as neither the provider nor the bidder opened the commitment. We discuss each case in more detail below. ### Rewards Upon successfully fulfilling a commitment, a provider will be rewarded the bid amount, minus a 2% fee (this fee accumulates in the mev-commit protocol treasury). This reward is paid by the mev-commit oracle to the provider’s account after the corresponding slot is settled by the oracle according to the block included in L1. ### Slashing for Broken Commitment Upon breaking a commitment, a provider will be slashed from their stake equal to the bid amount they committed to (taking into account the bid decay), including a 5% penalty fee. The principal slash amount will be transferred to the bidder for the broken commitment, and the penalty fee will be transferred to the mev-commit protocol treasury. If the provider does not have enough stake left to cover the entirety of the slashing penalty and the bid amount, the maximal amount of the bid amount that can be slashed will be slashed and given to the bidder. Any remaining funds in the provider's stake will go towards maximally paying the 5% slashing penalty to the treasury. The precedence means the bid amount slashing that goes to the bidder will be prioritized first, and only after that will the treasury be compensated for as much of the 5% slashing penalty as possible. ### Neutral Outcome The protocol does not take action on commitments that are not opened by the provider or the bidder. This happens if the commitment provider is not the execution provider for the corresponding winning block, in which case there is no point in opening the commitment. ## Builder and Proposer Attribution We rely on the BLS key used to submit to the relay to do attribution and determine the block builder for a particular block. # Solvers Source: https://docs.primev.xyz/v1.1.0/concepts/solvers This article explains how third parties, referred to as solvers, can use mev-commit as a tool to offer commitment services to users. By offering commitments, solvers can fulfill a range of user requests, from basic operations such as a preconfirmation for a fast bundle inclusion in the chain to complex operations involving multiple chains. Solvers aim to abstract these detailed processes from end-users, who may lack the expertise to perform these operations independently. Here we discuss how solvers can help users secure commitments for their transaction bundle. Commitments serve various purposes. They can benefit a searcher looking to profit from an arbitrage opportunity by getting a preconfirmation or a regular user wanting to sell assets on Ethereum while buying assets on Solana at the same time. We anticipate sophisticated actors to interact directly with mev-commit to request and acquire the necessary commitments from providers to fulfill their needs, abstracting the commitment bidding and receiving process from end users. We assume there is a single solver (called the "leader") performing operations on behalf of the users. The leader can be selected in various ways, such as through an auction or a lottery. ## Sourcing and Handling Commitments The solver leader interacts with its users and the mev-commit protocol by receiving user's messages and transforming them into mev-commit bids. The solver then tries to source commitments for the bid on the mev-commit protocol. Once the commitments are successfully acquired, there are three main ways the solver can handle them. We describe each of them next. 1. The solver accumulates the commitments it receives for each bid and it only sends a commitment to the user if/when it manages to source commitments from all the providers for a bid. In this case, we say the commitment is credible as it was issued by all the providers in mev-commit. 2. The solver relays all the commitments it receives from the providers back to the user. In this case, the commitments the user gets are "weak commitments" because they are tied to specific providers, unlike the credible commitment from above. 3. The solver can immediately send a commitment to the user (if it chooses to) even before getting commitments from the providers. In this case, the solver issues a commitment to the user optimistically and is responsible for sourcing the commitments from all the providers. If the solver cannot source the commitments from the providers, it may be penalized by having its collateral slashed. The approaches mentioned above would most likely differ in the economical aspects and should be priced differently by the solver. An interesting future direction is to analyze the game-theoretical aspects that each approach encompasses. For instance, understanding the strategies and trade-offs a solver must consider when deciding how to manage their bids and commitments, or how different pricing models might affect the user experience and the overall efficiency of the process. # null Source: https://docs.primev.xyz/v1.1.0/concepts/validator-considerations ### Trust Assumptions Opting into the mev-commit protocol signals from a validator that they: * Trust correctness of execution from the mev-commit chain. See [mev-commit chain](/v1.1.0/concepts/mev-commit-chain/chain-details) for more information. * Trust correctness of slashing transactions residing from the Primev operated [mev-commit-oracle](https://github.com/primev/mev-commit/tree/main/oracle) service. * Trust at least one mev-commit opted in relay. [View the list of supported relays here](https://docs.primev.xyz/v1.1.0/get-started/validators/validator-guide#supporting-relays). * Attest they will follow the rules of the protocol given the above trust assumptions. This currently entails *only* proposing blocks that come from a mev-commit opted in relay. ### Risks While mev-commit is generally not set up to slash validators, validators opting into the mev-commit protocol should be aware of the following risks: * **Trusted Relay block delivery:** Relays could break your trust and communicate blocks that do not abide by existing commitments. This would lead to slashing of the validator. ### Future plans While mev-commit AVS is passive and doesn't require operators to run any software today, Primev is researching means to decentralize centralized components of the mev-commit stack. Stay tuned for more updates on this. # What is mev-commit? Source: https://docs.primev.xyz/v1.1.0/concepts/what-is-mev-commit Mev-commit is a peer-to-peer (P2P) networking platform designed to facilitate real-time interactions and coordination between mev actors and execution providers. It provides a robust network for exchanging execution bids and cryptographic commitments, which are used to specify execution requirements in detail and to receive credible commitments that act as promises to fulfill bid requirements. Mev-commit allows actors to engage in “fast games” such as preconfirmations through real-time cryptographic commitments and settles results using a high throughput blockchain for permissionless access. ## What are Bids? Within mev-commit, bids act as the foundational requests placed by bidders, signaling their need for specific transaction execution services. This process occurs within a peer-to-peer networking setup to streamline direct negotiations with execution service providers like block builders and rollup sequencers. Each bid, marked by the unique identifier of a transaction hash, enables a straightforward mechanism for providers across the network to recognize and respond to these requests. Bids essentially convey a user's readiness to pay a certain fee for the execution of their transaction, proposing a price designed to motivate execution providers to give priority to their transaction. ## What are Commitments? Commitments within mev-commit represent the execution providers' affirmative responses to bids, confirming their agreement to execute the specified transactions at the proposed prices within designated blocks. These commitments are conveyed through cryptographic proofs or digital signatures, signifying the providers' acceptance of a bid. Commitments serve as the critical link that aligns the supply and demand dynamics of the network, facilitating an effective and streamlined process for transaction execution. ## Actors Network actors' roles are defined based on their interactions with other ecosystem actors. The diagram below depicts a given mev actor's relative placement compared to others: For example, a Searcher can be a bidder for a Sequencer, but that same Sequencer can be a bidder for a block builder. Thus, it's best to think of actors' roles in mev-commit as similar to their roles in the mev pipeline. To the left of the diagram are bidders, and to the right of the diagram are execution providers who can issue commitments against these bids. Under the Proposer Builder Separation (PBS) model, information only moves to the right among actors in the mev pipeline. With mev-commit, credible commitments for execution and bits of information flow from providers back to bidders, enabling them to effectively utilize block space. This two-way exchange of information and commitments within the mev-commit system enhances the dynamic utilization and management of block space, supporting a more interactive and responsive ecosystem. ### **Providers** Providers in the mev ecosystem include **Block Builders, Relays, Rollup Sequencers, and even Solvers**. They are crucial for the delivery of commitments through their role in the respective ecosystem or their sophistication. These providers receive bids and deliver transaction inclusion and execution, ensuring the efficient and effective use of block space. ### **Bidders** Bidders consist of **Searchers, Solvers, Blob Producers, AA Bundlers, Wallets, and even End Users**. They bid for execution services, aiming to optimize their transactions within the block space. Their activities are fundamental to maintaining a competitive and efficient environment within the mev pipeline, facilitating a dynamic market for block space utilization. For a detailed look at these roles and their interactions, please visit the [Actors](/v1.1.0/concepts/actors) section. ## Why mev-commit? Through our experience developing products for the Ethereum and the broader crypto ecosystem, we’ve learned that users want to interact with networks as a whole as opposed to single actors that represent some percentage of the network, which is challenging to provide in decentralized systems that have goals beyond user needs. We've created mev-commit to address this and optimized it to solve coordination inefficiencies across the actors of any blockchain network, which are sure to increase with decentralization and greater transaction complexity. Mev-commit's actor and chain agnostic credible commitment approach ensures that users are not only able to convey their needs to a blockchain network, but receive commitments from the executors of those needs in real time so they can confidently take actions based on their expectation being satisfied or not. We’re constructing mev-commit to be aligned with the ethos of the crypto ecosystem, specifically the vision being laid out by the Ethereum Foundation, and out of protocol services that supplement that vision such as the current mev pipeline largely introduced by Flashbots. We don’t aim to design a different mev pipeline, but create new avenues for efficiency in solving coordination problems between actors that can be used to have an expectation matching experience when engaging in the existing auctions and mev pipeline. We plan to continue supporting mev-commit’s evolution and adoption according to this mission as the existing landscape shifts and new paradigms are introduced. ## mev-commit software components * [mev-commit p2p client](https://github.com/primev/mev-commit/tree/main/p2p) * [mev-commit-geth](https://github.com/primev/mev-commit-geth) * [contracts](https://github.com/primev/mev-commit/tree/main/contracts) * [mev-commit-oracle](https://github.com/primev/mev-commit/tree/main/oracle) * [mev-commit-bridge](https://github.com/primev/mev-commit/tree/main/bridge) # Bidder API Source: https://docs.primev.xyz/v1.1.0/developers/bidder-api ## **Bidders** Bidders will use the `bidder` role to run their nodes. The node provides the **Bidder API** to submit bids to the network and will sign the bid before sending it out. In response, bidders will receive commitments from providers if their bid is accepted. This is a streaming response, and bidders are expected to keep their connection alive until their node receives all relevant commitments. The Bidder API is also implemented using the gRPC framework, supporting two primary operations: * **Send Bid:** The user submit their bid. * **Receive Preconfirmation:** The user receives streaming preconfirmations if accepted. ### **RPC API for Bidders** Users can find the protobuf file in the [repository](https://github.com/primev/mev-commit/blob/main/p2p/rpc/bidderapi/v1/bidderapi.proto). This can be used to generate the client for the RPC in the language of your choice. The Go client has already been generated in the repository. For other languages, please follow the instructions in the [gRPC documentation](https://grpc.io/docs/languages/) to generate them separately. **API Operation:** ``` rpc SendBid(Bid) returns (stream Commitment) ``` **Message Definitions** ```protobuf message Bid { repeated string tx_hashes = 1; string amount = 2; int64 block_number = 3; int64 decay_start_timestamp = 4; int64 decay_end_timestamp = 5; repeated string reverting_tx_hashes = 6; repeated string raw_transactions = 7; string slash_amount = 8; }; message Commitment { repeated string tx_hashes = 1; string bid_amount = 2; int64 block_number = 3; string received_bid_digest = 4; string received_bid_signature = 5; string commitment_digest = 6; string commitment_signature = 7; string provider_address = 8; int64 decay_start_timestamp = 9; int64 decay_end_timestamp = 10; int64 dispatch_timestamp = 11; repeated string reverting_tx_hashes = 12; string slash_amount = 13; } ``` ### **HTTP API** The same API is also available on the HTTP port configured on the node. Please review the [API docs](/v1.1.0/api-reference/bidder/sendbid) to understand the usage. An [example CLI application](https://github.com/primev/mev-commit/blob/main/p2p/examples/biddercli) is implemented in the repository. The primary purpose of this example is to demonstrate the process of integrating with the RPC API. # Managing Your Bidder Deposit Source: https://docs.primev.xyz/v1.1.0/developers/bidder-deposit **To Check Your Deposit for current window:** ```shell > curl localhost:13523/v1/bidder/get_deposit | jq { "amount": "0", "windowNumber": 1 } ``` **To Check Your Deposit for a specific window:** ```shell > curl localhost:13523/v1/bidder/get_deposit?window_number=1 | jq { "amount": "0", "windowNumber": 1 } ``` **Funding Your Node Account:** First, retrieve the Ethereum account address of your node: ```shell > curl localhost:13523/v1/debug/topology | jq { "self": { "Addresses": [ "/ip4/127.0.0.1/tcp/13522", "/ip4/172.29.0.4/tcp/13522" ], "Ethereum Address": "0xB9286CB4782E43A202BfD426AbB72c8cb34f886c", "Peer Type": "bidder", "Underlay": "16Uiu2HAmDWZb4DxZQkS9yseXNukBFe6MhZdimSKuZcHFeJrF3jC9" }, "connected_peers": { "providers": [ "0x48ddc642514370bdafad81c91e23759b0302c915", "0x972eb4fc3c457da4c957306be7fa1976bb8f39a6", "0xa1e8fdb3bb6a0db7aa5db49a3512b01671686dcb" ] }, "blocked_peers": null } ``` To add funds to your account on the mev-commit chain, you may use the [bridge](/v1.1.0/getting-started/bridge). * **Adding to Your Deposit:** To increase your deposit for the current window, use the following command, specifying the desired amount: ```shell > curl -X POST localhost/v1/bidder/deposit/YOUR_AMOUNT | jq ``` To increase your deposit for the specific window, use the following command, specifying the desired amount and window number: ```shell > curl -X POST "localhost/v1/bidder/deposit/YOUR_AMOUNT" \ -H "Content-Type: application/json" \ -d '{ "window_number": 1 }' | jq ``` To increase your deposit for the specific L1 block number, use the following command, specifying the desired amount and L1 block number: ```shell > curl -X POST "localhost/v1/bidder/deposit/YOUR_AMOUNT" \ -H "Content-Type: application/json" \ -d '{ "block_number": 1, }' | jq ``` After successfully adding to your deposit, you are ready to send bids and receive preconfirmations on the network. * **Withdrawing from Your Deposit:** To withdraw funds from your deposit, use the following command: ```shell > curl -X POST localhost/v1/bidder/withdraw \ -H "Content-Type: application/json" \ -d '{ "window_number": 1 }' | jq ``` If you don't specify a window number, the current window will be used by default. ### Outcome of Preconfirmed Bids: When a bid is preconfirmed by a provider, there are several possible outcomes: | Outcome Matrix | Provider Wins Slot Auction | Provider Loses Slot Auction | | ---------------------------- | ------------------------------------- | --------------------------- | | **Transaction in block** | Reward Provider | Refund Bid to Bidder | | **Transaction not in block** | Slash Provider & Refund Bid To Bidder | Refund Bid to Bidder | # null Source: https://docs.primev.xyz/v1.1.0/developers/contracts # Introduction The [mev-commit contracts](https://github.com/primev/mev-commit/tree/main/contracts) verify and manage the movement of funds as a response to bid and commitment activities that occur on our p2p network. For mev-commit mainnet contract addresses please refer to [Mainnet](/v1.1.0/developers/mainnet) section. For mev-commit testnet contract addresses please refer to [Testnet](/v1.1.0/developers/testnet) section. ## Core Contracts The mev-commit protocol has 5 **core contracts**, which are all deployed on the mev-commit chain: * **Preconf Manager** * This will persist details about the commitments that have been made into contract storage. * **Bidder Registry** * This will be where the bulk of monetary transfer occurs. * Bidders deposit for bids into this contract. * The payment gets processed into a provider-allocated section that a provider can later retrieve. * **Provider Registry** * This contract stores the stake a provider bounds to ensure it doesn't break its promises under preconfirmations. * **Oracle** * This simply retrieves details on which commitments to process for rewarding or slashing. * Access to the functions on this contract is restricted to the owner of the Oracle key. * **Block Tracker** * This will track Ethereum blocks and their winners, so commitments could be rewarded or slashed * Access to the functions on this contract is restricted to the owner of the Oracle key. ## Validator Registry Contracts The validator registry contracts are deployed on L1, and enable three methods of validator opt-in: * **Validator Opt-In Router** * ValidatorOptInRouter enables actors to query whether a validator is opted-in to the mev-commit protocol from any of the below three methods. * **Vanilla Registry** * VanillaRegistry allows validators to opt-in to mev-commit by staking native ETH directly with the contract. * This stake is separate from a validator's 32 ETH already staked with the beacon chain. * **Mev-commit AVS** * MevCommitAVS acts as a tie-in to Eigenlayer core contracts, enabling validators to opt-in to the mev-commit protocol via native restaking. * **Mev-commit middleware** * MevCommitMiddleware serves as tie-in to Symbiotic core contracts, enabling validators to opt-in to the mev-commit protocol via restaking ERC20 tokens with vaults. ## Bridge Contracts The standard bridge protocol for native ETH transfers between L1 and the mev-commit chain is implemented in [this directory](https://github.com/primev/mev-commit/tree/main/contracts/contracts/standard-bridge). Contracts include: * **L1 Gateway** * The L1 gateway contract allows users to lock their native ETH on L1, where an equivalent amount will be allocated to a specified account on the mev-commit chain. This contract is also responsible for unlocking ETH when bridging back to L1. * **Settlement Gateway** * The settlement gateway integrates with the allocator contract to allocate native ETH on the mev-commit chain. It also allows users to bridge native ETH back to L1. * **Allocator** * The allocator contract is responsible paying out ETH to bridge users as necessary on the mev-commit chain. It's currently only integrated with the settlement gateway, but will be extended to other bridging protocols in the future. ## Deploying Custom Contracts ### Mainnet You can deploy any EVM compatible contracts to the mev-commit chain, simply set your **Chain ID to 8855** and RPC Url to `https://chainrpc.mev-commit.xyz`. ### Testnet You can deploy any EVM compatible contracts to the mev-commit chain, simply set your **Chain ID to 17864** and RPC Url to `https://chainrpc.testnet.mev-commit.xyz`. # null Source: https://docs.primev.xyz/v1.1.0/developers/debugging ### **Debugging Tools in mev-commit Node** As the mev-commit node is under active development, it includes debugging tools for in-depth analysis. These tools, primarily intended for developers and not for everyday users, offer insights into the node's functionality. They are accessible via the HTTP API endpoint. ### **Understanding Network Topology** You can view the network's topology as recognized by the mev-commit node at the `/v1/debug/topology` endpoint. This provides information such as the number of connected nodes and their roles, helping to ensure your node is well-connected within the network. Example of Topology Data: ```json { "self": { "Addresses": ["/ip4/127.0.0.1/tcp/13522", "/ip4/172.29.18.2/tcp/13522"], "Ethereum Address": "0xB8c29FfD307067471fd7997873DfC496Fd02956f", "Peer Type": "bootnode", "Underlay": "16Uiu2HAmLYUvthfDCewNMdfPhrVefBbsfaPL22fWWfC2zuoh5SpV" }, "connected_peers": { "bidders": ["0xb9286cb4782e43a202bfd426abb72c8cb34f886c"] }, "blocked_peers": [ { "Peer": "0x48ddc642514370bdafad81c91e23759b0302c915", "Reason": "insufficient stake", "Duration": "1m58.244219375s" } ] } ``` ### **Prometheus Metrics for Monitoring** The node emits various Prometheus metrics, which can be utilized to create dashboards displaying the node's statistics. These include default metrics from the `libp2p` networking library and are available at the `/metrics` endpoint. ### **Pprof Endpoints** For advanced users, pprof endpoints are available at `/debug/pprof` for performance profiling, such as monitoring memory and CPU usage. However, understanding and using these endpoints requires prior knowledge of pprof tools and is not covered in this documentation. # null Source: https://docs.primev.xyz/v1.1.0/developers/docker-bidder # **Docker Container for Bidder Node** The mev-commit bidder setup leverages Docker to deploy a bidder node service within a single container, the repository [can be found here](https://github.com/primev/bidder_node_docker) . This bidder node connects to the mev-commit chain, enabling users to submit bids seamlessly. By containerizing the service, you ensure a consistent and reproducible environment, simplifying deployment and scaling. # Prerequisites Before you begin, ensure you have the following: * Docker: Install Docker on your machine. You can download it from the official Docker website. * Docker Compose: Ensure Docker Compose is installed. It typically comes bundled with Docker Desktop, but you can verify by running docker-compose --version. * A funded mev-commit address. * A valid Holesky or Mainnet private key for authentication. If you need testnet funds, use the MEV-Commit [faucet](https://faucet.testnet.mev-commit.xyz/). # Setup Instructions Follow these steps to set up and run your mev-commit bidder node. 1. Clone the Repository Begin by cloning the repository to your local machine: ```bash Copy code git clone https://github.com/your-repo/mev-commit-bidder-docker.git cd mev-commit-bidder-docker ``` 2. Configure Environment Variables Create a .env file in the root directory of the repository to store your environment variables securely. Create the .env file: ```bash Copy code touch .env ``` Define the required variables: Open the .env file in your preferred text editor and add the following: ```env Copy code PRIVATE_KEY_BIDDER=your_private_key_here DOMAIN=testnet.mev-commit.xyz ``` Replace your\_private\_key\_here with your actual private key. The DOMAIN variable defaults to testnet.mev-commit.xyz, but you can modify it if needed. 3. Build and Run Docker Containers With the environment configured, proceed to build and run the Docker containers. ```bash Copy code docker-compose up --build ``` This command performs the following actions: * Builds the Docker image based on Ubuntu 20.04. * Installs necessary dependencies such as curl and jq. * Downloads and installs the latest MEV-Commit binary from the official repository. * Starts the bidder node service within the container. # Customization Tailor the bidder node to fit your specific needs by adjusting environment variables or modifying the startup script. ## Modifying the Entry Point The container uses an entrypoint.sh script to initiate the bidder service. If you need to alter the startup sequence: Edit the entrypoint.sh script: Locate and open the entrypoint.sh file in the repository. Make your desired changes to customize the startup behavior. Rebuild the Docker Image: After modifying the script, rebuild the Docker image to apply the changes: ```bash Copy code docker-compose up --build ``` ## Networking with Other Repositories Before deploying your containers, create a shared Docker network: ```bash Copy code docker network create app-network ``` This network, named app-network, facilitates communication between the bidder node and other services. ## Using the Network with Other Containers To enable other Docker services to communicate with the MEV-Commit bidder node, ensure they reference the same app-network. Here's how to configure another repository's docker-compose.yml to join the network: ```yaml Copy code version: '3' services: bid-sender: image: your-bid-sender-image networks: - app-network environment: - RPC_ENDPOINT=http://mev-commit-bidder:13524 networks: app-network: external: true ``` # Mev-commit Mainnet Source: https://docs.primev.xyz/v1.1.0/developers/mainnet export const CommitmentHoldingsMultisig = "0xD5881f91270550B8850127f05BD6C8C203B3D33f"; export const PrimevTeamMultisig = "0x9101eda106A443A0fA82375936D0D1680D5a64F5"; export const ValidatorOptInRouterImplementationAddress = "0x585963E61dd3943bAe02F4f2dBaE0f9EDBa842Af"; export const ValidatorOptInRouterProxyAddress = "0x821798d7b9d57dF7Ed7616ef9111A616aB19ed64"; export const MevCommitMiddlewareImplementationAddress = "0x3d9Af87Bc4E20a7a1c7d81208D44432E9b313734"; export const MevCommitMiddlewareProxyAddress = "0x21fD239311B050bbeE7F32850d99ADc224761382"; export const MevCommitAVSImplementationAddress = "0x5A68216faE665dF4650597B7472101Bb1b66C208"; export const MevCommitAVSProxyAddress = "0xBc77233855e3274E1903771675Eb71E602D9DC2e"; export const VanillaRegistryImplementationAddress = "0x59fBE4CC4CA974e98300F41Ac661f7204F0c3fCd"; export const VanillaRegistryProxyAddress = "0x47afdcB2B089C16CEe354811EA1Bbe0DB7c335E9"; export const L1GatewayMainnet1_0_0Implementation = "0xC973D09e51A20C9Ab0214c439e4B34Dbac52AD67"; export const L1GatewayMainnet1_0_0Proxy = "0xDBf24cafF1470a6D08bF2FF2c6875bafC60Cf881"; export const SettlementGatewayMainnet1_0_0 = "0x138c60599946280e5a2DCc1f553B8f0cC0554E03"; export const BlockTrackerAddressMainnet1_0_0 = "0x0DA2a367C51f2a34465ACd6AE5d8A48385e9cB03"; export const OracleAddressMainnet1_0_0 = "0xa1aaCA1e4583dB498D47f3D5901f2B2EB49Bd8f6"; export const PreconfManagerAddressMainnet1_1_0 = "0x3761bF3932cD22d684A7485002E1424c3aCCD69c"; export const ProviderRegistryAddressMainnet1_0_0 = "0xb772Add4718E5BD6Fe57Fb486A6f7f008E52167E"; export const BidderRegistryAddressMainnet1_0_0 = "0xC973D09e51A20C9Ab0214c439e4B34Dbac52AD67"; Live with Ethereum Mainnet, mev-commit allows bidders and providers to engage in execution service bids and commitments. Preconfirmations, the first use case for real-time bids and commitments, are available with mev-commit. # Service Links | Service | Link | | ----------------- | ---------------------------------------------------------------------- | | Mainnet RPC | [https://chainrpc.mev-commit.xyz/](https://chainrpc.mev-commit.xyz/) | | Mainnet WebSocket | [wss://chainrpc-wss.mev-commit.xyz](wss://chainrpc-wss.mev-commit.xyz) | | Bootnode endpoint | [https://bootnode.mev-commit.xyz/](https://bootnode.mev-commit.xyz/) | | Block explorer | [http://explorer.mev-commit.xyz](http://explorer.mev-commit.xyz) | # Contracts deployed to mev-commit chain ### **Core Contracts**
Contract Address
BidderRegistry {BidderRegistryAddressMainnet1_0_0}
ProviderRegistry {ProviderRegistryAddressMainnet1_0_0}
PreconfManager {PreconfManagerAddressMainnet1_1_0}
Oracle {OracleAddressMainnet1_0_0}
BlockTracker {BlockTrackerAddressMainnet1_0_0}
### **Settlement Bridge Gateway**
Contract Address
SettlementGateway {SettlementGatewayMainnet1_0_0}
# Contracts deployed to L1 Ethereum ### **L1 Bridge Gateway**
Entity Address Type Address
L1Gateway Proxy {L1GatewayMainnet1_0_0Proxy}
Implementation {L1GatewayMainnet1_0_0Implementation}
### **L1 Validator Registries**
Contract Address Type Address
MevCommitAVS Proxy {MevCommitAVSProxyAddress}
Implementation {MevCommitAVSImplementationAddress}
MevCommitMiddleware Proxy {MevCommitMiddlewareProxyAddress}
Implementation {MevCommitMiddlewareImplementationAddress}
VanillaRegistry Proxy {VanillaRegistryProxyAddress}
Implementation {VanillaRegistryImplementationAddress}
ValidatorOptInRouter Proxy {ValidatorOptInRouterProxyAddress}
Implementation {ValidatorOptInRouterImplementationAddress}
All contract calls should be made through the proxy contracts. Implementations are listed for transparency, where verified contract code can be viewed. # Other L1 Ethereum addresses
Description Address
Primev Team Multisig {PrimevTeamMultisig}
Commitment Holdings Multisig {CommitmentHoldingsMultisig}
Symbiotic "network address" (Served by Primev Team Multisig) {PrimevTeamMultisig}
# How can users provide feedback or report issues encountered on testnet or mainnet? Users can open an issue on the GitHub repository that is associated with any issue they encounter. They can also tag @primev\_xyz on Twitter, or reach out to us to join a Telegram group for early power users. # Manual Node Setup Source: https://docs.primev.xyz/v1.1.0/developers/manual-start-mev-commit Below, you'll find a guide tailored for those who prefer a more customized installation approach. We use the [cast](https://book.getfoundry.sh/cast/) CLI tool for making Ethereum RPC calls. If it's not already installed on your system, you can set up the entire Foundry toolchain, including `cast`, with the following command: ```bash ❯_ terminal curl -L https://foundry.paradigm.xyz | bash ``` After installation, execute `foundryup` to update to the latest versions of Foundry's suite of tools: `forge`, `cast`, `anvil`, and `chisel`: ```bash ❯_ terminal foundryup ``` For detailed guidance, refer to the official [Foundry Book](https://book.getfoundry.sh/getting-started/installation) installation instructions. Run the following command which will identify your OS, and chip architecture: ```bash ❯_ terminal uname -sm ``` This command will output something like `Linux x86_64` or `Darwin arm64`, depending on your system. Navigate to the [mev-commit repo](https://github.com/primev/mev-commit/releases/latest) and select the mev-commit binary tailored to your system. For example, if `uname -sm` yields `Linux x86_64`, opt for `mev-commit_Linux_x86_64.tar.gz`. Download, then extract the binary into your preferred root directory to continue with setup. You can use the following command which automatically downloads and extracts the appropriate mev-commit binary for your system into your home directory: ```bash ❯_ terminal FILENAME="mev-commit_1.1.0_$(uname -s)_$(uname -m).tar.gz" curl -L \ "https://github.com/primev/mev-commit/releases/download/v1.1.0/$FILENAME" \ | tar -xz -C $HOME ``` Before executing any code downloaded from the internet, it's recommended to verify the checksum, a practice that ensures the file's integrity and authenticity. Checksums, provided with each release on GitHub, serve as a safeguard, allowing you to confirm that the downloaded binary has not been compromised or altered, thus protecting your system from potential security risks. To verify the checksum of the mev-commit binary, you can follow these simplified steps (assumes binary is the home directory): Set the binary's name based on your system and retrieve the corresponding checksum: ```bash ❯_ terminal FILENAME="mev-commit_$(uname -s)_$(uname -m).tar.gz" CHECKSUM=$(curl -L \ "https://github.com/primev/mev-commit/releases/download/v1.1.0/mev-commit_v1.1.0_checksums.txt" \ | awk "/$FILENAME/ {print \$1}") ``` Verify the binary's checksum by running the following: ```bash linux echo "$CHECKSUM $HOME/$FILENAME" | sha256sum -c - ``` ```bash macOs (Darwin) echo "$CHECKSUM $HOME/$FILENAME" | shasum -a 256 -c - ``` ✅ **Success** If the output resembles the following, you may confidently proceed to the next steps: ```bash ❯_ bidder filename.tar.gz: OK ``` ❌ **Failure** Should the output indicate a failure, as shown below, re-download the file and attempt verification once more. ```bash filename.tar.gz: FAILED shasum: WARNING: 1 computed checksum did NOT match ``` If checksum verification continues to fail after multiple attempts, reach out to Primev for support. ## Starting up your Node Execute the script to initiate your node, selecting either a bidder or provider configuration based on your role in the network. ### Mainnet ```bash ❯_ provider mev-commit \ --peer-type provider \ --keystore-path ~/.mev-commit \ --keystore-password \ --bootnodes /dnsaddr/bootnode.mev-commit.xyz \ --settlement-ws-rpc-endpoint wss://chainrpc-wss.mev-commit.xyz ``` ```bash ❯_ bidder mev-commit \ --keystore-path ~/.mev-commit \ --keystore-password \ --bootnodes /dnsaddr/bootnode.mev-commit.xyz \ --settlement-ws-rpc-endpoint wss://chainrpc-wss.mev-commit.xyz ``` ### Testnet ```bash ❯_ provider mev-commit \ --peer-type provider \ --keystore-path ~/.mev-commit \ --keystore-password \ --bootnodes /dnsaddr/bootnode.testnet.mev-commit.xyz \ --settlement-ws-rpc-endpoint wss://chainrpc-wss.testnet.mev-commit.xyz ``` ```bash ❯_ bidder mev-commit \ --keystore-path ~/.mev-commit \ --keystore-password \ --bootnodes /dnsaddr/bootnode.testnet.mev-commit.xyz \ --settlement-ws-rpc-endpoint wss://chainrpc-wss.testnet.mev-commit.xyz ```


Once the node is started you can go through the [funding process](/v1.1.0/developers/bidder-deposit) to start sending bids.


In order to register as a provider please go through the [registration process](/v1.1.0/get-started/providers/registering-a-provider).
* `--bootnodes` This should point to the bootnode for the Primev testnet network. * `--settlement-rpc-endpoint` This should point to the Primev Settlement Chain RPC endpoint. At present this is managed by the Primev team. ❗ The `--peer-type` flag can be used to run a `provider` or `bidder` node. ❗ The default contract addresses point to the Primev testnet at the moment. All the options can be provided using a YAML config file or environment variables as described in the above help output. ❗ The mev-commit node, when started for the first time will create a private key for the node at `~/.mev-commit/key`. This is a plain-text key. In order to store encrypted keys, users need to use the keystore. This can be configured using the `--keystore-path` and `--keystore-password`. ❗ In order to run a provider node, the machine needs to be publicly accessible. Also, the mev-commit node will have to be configured with the public IP of the node using the `nat-addr` parameter. ## CLI Reference ```shell NAME: mev-commit - Start mev-commit node USAGE: mev-commit [global options] command [command options] VERSION: v1.1.0 COMMANDS: help, h Shows a list of commands or help for one command GLOBAL OPTIONS: --help, -h show help --version, -v print the version API options --http-addr value Address to bind for http connections [$MEV_COMMIT_HTTP_ADDR] --http-port value Port to listen for http connections (default: 13523) [$MEV_COMMIT_HTTP_PORT] --rpc-addr value Address to bind for RPC connections [$MEV_COMMIT_RPC_ADDR] --rpc-port value Port to listen for rpc connections (default: 13524) [$MEV_COMMIT_RPC_PORT] --server-tls-certificate value Path to the server TLS certificate [$MEV_COMMIT_SERVER_TLS_CERTIFICATE] --server-tls-private-key value Path to the server TLS private key [$MEV_COMMIT_SERVER_TLS_PRIVATE_KEY] Bidder options --autodeposit-amount value Amount to auto deposit in each window in wei [$MEV_COMMIT_AUTODEPOSIT_AMOUNT] --autodeposit-enabled Enable auto deposit (default: false) [$MEV_COMMIT_AUTODEPOSIT_ENABLED] --bidder-bid-timeout value Timeout to use on bidder node to wait for preconfirmations after submitting bids (default: 30s) [$MEV_COMMIT_BIDDER_BID_TIMEOUT] --provider-whitelist value [ --provider-whitelist value ] List of provider addresses to whitelist for bids [$MEV_COMMIT_PROVIDER_WHITELIST] Contracts --bidder-registry-contract value Address of the bidder registry contract (default: "0x401B3287364f95694c43ACA3252831cAc02e5C41") [$MEV_COMMIT_BIDDER_REGISTRY_ADDR] --block-tracker-contract value Address of the block tracker contract (default: "0x7538F3AaA07dA1990486De21A0B438F55e9639e4") [$MEV_COMMIT_BLOCK_TRACKER_ADDR] --preconf-contract value Address of the preconfirmation commitment store contract (default: "0x9433bCD9e89F923ce587f7FA7E39e120E93eb84D") [$MEV_COMMIT_PRECONF_ADDR] --provider-registry-contract value Address of the provider registry contract (default: "0xf4F10e18244d836311508917A3B04694D88999Dd") [$MEV_COMMIT_PROVIDER_REGISTRY_ADDR] --validator-router-contract value Address of the validator router contract (default: "0x251Fbc993f58cBfDA8Ad7b0278084F915aCE7fc3") [$MEV_COMMIT_VALIDATOR_ROUTER_ADDR] Debug options --log-fmt value Log format to use, options are 'text' or 'json' (default: "text") [$MEV_COMMIT_LOG_FMT] --log-level value Log level to use, options are 'debug', 'info', 'warn', 'error' (default: "info") [$MEV_COMMIT_LOG_LEVEL] --log-tags value Log tags is a comma-separated list of pairs that will be inserted into each log line [$MEV_COMMIT_LOG_TAGS] --otel-collector-endpoint-url value URL for OpenTelemetry collector endpoint [$MEV_COMMIT_OTEL_COLLECTOR_ENDPOINT_URL] Ethereum RPC options --beacon-api-url value URL of the beacon chain API (default: "https://ethereum-holesky-beacon-api.publicnode.com") [$MEV_COMMIT_BEACON_API_URL] --l1-rpc-url value URL for L1 RPC (default: "https://ethereum-holesky-rpc.publicnode.com") [$MEV_COMMIT_L1_RPC_URL] --settlement-rpc-endpoint value RPC endpoint of the settlement layer (default: "http://localhost:8545") [$MEV_COMMIT_SETTLEMENT_RPC_ENDPOINT] --settlement-ws-rpc-endpoint value WebSocket RPC endpoint of the settlement layer [$MEV_COMMIT_SETTLEMENT_WS_RPC_ENDPOINT] Global options --config value Path to configuration file [$MEV_COMMIT_CONFIG] --data-dir value Path to data directory (default: "~/.mev-commit/db") [$MEV_COMMIT_DATA_DIR] --gas-fee-cap value Use predefined gas fee cap for transactions (default: "2000000000") [$MEV_COMMIT_GAS_FEE_CAP] --gas-limit value Use predefined gas limit for transactions (default: 2000000) [$MEV_COMMIT_GAS_LIMIT] --gas-tip-cap value Use predefined gas tip cap for transactions (default: "1000000000") [$MEV_COMMIT_GAS_TIP_CAP] --keystore-password value Password to use to access keystore [$MEV_COMMIT_KEYSTORE_PASSWORD] --keystore-path value Path to keystore location (default: "~/.mev-commit/keystore") [$MEV_COMMIT_KEYSTORE_PATH] --peer-type value Peer type to use, options are 'bidder', 'provider' or 'bootnode' (default: "bidder") [$MEV_COMMIT_PEER_TYPE] --priv-key-file value Path to private key file (default: "~/.mev-commit/key") [$MEV_COMMIT_PRIVKEY_FILE] P2P options --bootnodes value [ --bootnodes value ] List of bootnodes to connect to [$MEV_COMMIT_BOOTNODES] --nat-addr value External address of the node to advertise to other peers [$MEV_COMMIT_NAT_ADDR] --nat-port value Externally mapped port for the node (default: 13522) [$MEV_COMMIT_NAT_PORT] --p2p-addr value Address to bind for p2p connections (default: "0.0.0.0") [$MEV_COMMIT_P2P_ADDR] --p2p-port value Port to listen for p2p connections (default: 13522) [$MEV_COMMIT_P2P_PORT] --secret value Secret to use for authenticating node in the p2p network (default: "secret") [$MEV_COMMIT_SECRET] Provider options --provider-decision-timeout value Timeout to use on provider node to allow for preconfirmation decision logic after receiving bids (default: 30s) [$MEV_COMMIT_PROVIDER_DECISION_TIMEOUT] ``` # Provider API Source: https://docs.primev.xyz/v1.1.0/developers/provider-api ## **Providers** Execution providers can use the `provider` role to run their nodes. This allows them to receive signed bids and issue commitments for execution. The **Provider RPC API** allows providers to receive signed bids that are being propagated in the network. Once they get a bid, they'll need to communicate with the mev-commit node to **Accept**. Accepted bids result in the mev-commit node sending a signed commitment to the p2p network. The Provider API is implemented using the gRPC framework, supporting two primary operations: * **Receiving Bids:** Providers receive streaming bids from the mev-commit node. * **Sending Processed Bids:** Providers send information about processed bids back to the mev-commit node. ### **RPC API Details** The protobuf file is available in the [repository](https://github.com/primev/mev-commit/blob/main/p2p/rpc/providerapi/v1/providerapi.proto). The Go client has already been generated in the repository. To generate the RPC client for other languages, please follow the instructions in the [gRPC documentation](https://grpc.io/docs/languages/). **Primary RPC Operations:** ```protobuf // ReceiveBids is called by the execution provider to receive bids from the mev-commit node. // The mev-commit node will stream bids to the execution provider. rpc ReceiveBids(EmptyMessage) returns (stream Bid) {} // SendProcessedBids is called by the provider to send processed bids to the mev-commit node. // The execution provider will stream processed bids to the mev-commit node. rpc SendProcessedBids(stream BidResponse) returns (EmptyMessage) {} ``` **Message Structures** ```protobuf message Bid { repeated string tx_hashes = 1; string bid_amount = 2; int64 block_number = 3; bytes bid_digest = 4; int64 decay_start_timestamp = 5; int64 decay_end_timestamp = 6; repeated string reverting_tx_hashes = 7; repeated string raw_transactions = 8; string slash_amount = 9; }; message BidResponse { bytes bid_digest = 1; enum Status { STATUS_UNSPECIFIED = 0; STATUS_ACCEPTED = 1; STATUS_REJECTED = 2; } Status status = 2; int64 dispatch_timestamp; }; ``` ### **HTTP API** The same API is also available on the HTTP port configured on the node. Please review the [API docs](/v1.1.0/api-reference/provider/receivebids) to understand the usage. An [example client](https://github.com/primev/mev-commit/tree/main/p2p/examples/provideremulator) is implemented in the repository. This example showcases how to integrate a client into the provider's operational framework. While the sample client automatically accepts every incoming bid, providers should incorporate their own decision-making logic to evaluate and respond to these bids. # Run mev-commit Chain Node Source: https://docs.primev.xyz/v1.1.0/developers/run-mev-commit-chain-node ## Setting Up Your Full Node for the mev-commit Testnet To join the mev-commit chain testnet with your own full-node, use [mev-commit geth](https://github.com/primev/mev-commit-geth). We've modified go-ethereum to achieve shorter block periods than mainnet Ethereum, and to enable seamless native token bridging capabilities. Geth configuration will vary based on environment, but an example is provided below: ```shell ❯_ terminal exec geth \ --verbosity="$VERBOSITY" \ --datadir="$GETH_DATA_DIR" \ --port 30311 \ --syncmode=full \ --gcmode=full \ --http \ --http.corsdomain="_" \ --http.vhosts="_" \ --http.addr=0.0.0.0 \ --http.port="$RPC_PORT" \ --http.api=web3,debug,eth,txpool,net,engine \ --bootnodes enode://34a2a388ad31ca37f127bb9ffe93758ee711c5c2277dff6aff2e359bcf2c9509ea55034196788dbd59ed70861f523c1c03d54f1eabb2b4a5c1c129d966fe1e65@103.219.170.127:29746 \ --networkid=$CHAIN_ID \ --unlock=$BLOCK_SIGNER_ADDRESS \ --password="$GETH_DATA_DIR"/password \ --mine \ --miner.etherbase=$BLOCK_SIGNER_ADDRESS \ --allow-insecure-unlock \ --nousb \ --netrestrict 172.13.0.0/24 \ --metrics \ --metrics.addr=0.0.0.0 \ --metrics.port=6060 \ --ws \ --ws.addr=0.0.0.0 \ --ws.port="$WS_PORT" \ --ws.origins="_" \ --ws.api=debug,eth,txpool,net,engine \ --rpc.allow-unprotected-txs \ --authrpc.addr="0.0.0.0" \ --authrpc.port="8551" \ --authrpc.vhosts="_" \ --nat extip:$NODE_IP ``` # System Requirements Source: https://docs.primev.xyz/v1.1.0/developers/system-requirements Below are the minimum system requirements to run a mev-commit node: * Software: mev-commit client and curl * OS: 64-bit Linux, Mac OS X 10.14+ * CPU: 4+ cores @ 2.8+ GHz * Memory: 16GB+ RAM * Network: 1 GBit/sec broadband In order to run a `provider` node, the machine needs to have a public IP assigned to it. This will be used by the other bidder nodes to connect. # Mev-commit Testnet Source: https://docs.primev.xyz/v1.1.0/developers/testnet export const L1Gateway_0_8_0 = "0x567f0f6d4f7A306c9824d5Ffd0E26f39682cDd7c"; export const MevCommitNetworkAddress = "0x4535bd6fF24860b5fd2889857651a85fb3d3C6b1"; export const MevCommitMiddlewareAddress = "0x79FeCD427e5A3e5f1a40895A0AC20A6a50C95393"; export const MevCommitAVSAddress = "0xEDEDB8ed37A43Fd399108A44646B85b780D85DD4"; export const VanillaRegistryAddress = "0x87D5F694fAD0b6C8aaBCa96277DE09451E277Bcf"; export const ValidatorOptInRouterAddress = "0x251Fbc993f58cBfDA8Ad7b0278084F915aCE7fc3"; export const SettlementGateway_0_7_0 = "0xFaF6F0d4bbc7bC33a4b403b274aBb82d0E794202"; export const BlockTrackerAddress0_7_0 = "0x0b3b6Cf113959214E313d6Ad37Ad56831acb1776"; export const OracleAddress0_7_0 = "0xCd27C2Dc26d37Bb17686F709Db438D3Dc546437C"; export const PreconfManagerAddress = "0x8420F290a412D87Ae4Aa12be63e1836b91717910"; export const ProviderRegistryAddress0_7_0 = "0x1C2a592950E5dAd49c0E2F3A402DCF496bdf7b67"; export const BidderRegistryAddress0_7_0 = "0x948eCD70FaeF6746A30a00F30f8b9fB2659e4062"; Live with Holesky, mev-commit allows bidders and providers to engage in execution service bids and commitments. Preconfirmations, the first use case for real-time bids and commitments, are available with mev-commit. ## **Links and Connection Details** ### **Services links** | Service | Link | | ----------------- | -------------------------------------------------------------------------------------- | | Testnet RPC | [https://chainrpc.testnet.mev-commit.xyz/](https://chainrpc.testnet.mev-commit.xyz/) | | Testnet WebSocket | [wss://chainrpc-wss.testnet.mev-commit.xyz](wss://chainrpc-wss.testnet.mev-commit.xyz) | | Bootnode endpoint | [https://bootnode.testnet.mev-commit.xyz/](https://bootnode.testnet.mev-commit.xyz/) | | Block explorer | [http://explorer.testnet.mev-commit.xyz](http://explorer.testnet.mev-commit.xyz) | ### **Core Contract Addresses (mev-commit chain)**
Contract Address
BidderRegistry {BidderRegistryAddress0_7_0}
ProviderRegistry {ProviderRegistryAddress0_7_0}
PreconfManager {PreconfManagerAddress}
Oracle {OracleAddress0_7_0}
BlockTracker {BlockTrackerAddress0_7_0}
### **Bridge Gateway (mev-commit chain)**
Contract Address
SettlementGateway {SettlementGateway_0_7_0}
### **Validator Registry Contract Addresses (Holesky)**
Contract Address
ValidatorOptInRouter {ValidatorOptInRouterAddress}
VanillaRegistry {VanillaRegistryAddress}
MevCommitAVS {MevCommitAVSAddress}
MevCommitMiddleware {MevCommitMiddlewareAddress}
### **Other addresses (Holesky)**
Entity Address
Mev-commit (Symbiotic) Network Address {MevCommitNetworkAddress}
### **Bridge Gateway (Holesky)**
Entity Address
L1Gateway {L1Gateway_0_8_0}
## How can users provide feedback or report issues encountered on the testnet? Users can open an issue on the GitHub repository that is associated with any issue they encounter. They can also tag @primev\_xyz on Twitter, or reach out to us to join a Telegram group for early power users. ## Testnet System Requirements Please refer to the System Requirements section [here.](/v1.1.0/developers/system-requirements) # Tools for Bid Submission Source: https://docs.primev.xyz/v1.1.0/developers/tools-for-bid-submission The team has developed the [bidder CLI](/v1.1.0/get-started/bidders/bidder-cli) tool to make it easier for users to send bids or raw transactions to the network. Please go through the instructions there on how to use this. We also recommend leveraging the Go RPC client or alternatively using the REST API below to send bids. For those who prefer to use command-line tools, options like [grpcurl](https://github.com/fullstorydev/grpcurl), or [BloomRPC](https://github.com/bloomrpc/bloomrpc) are available. These tools require the protobuf definitions from the repository to interact with the RPC services. ## Official Go RPC Client For Go developers, leveraging the official Go RPC client is the recommended approach. It is easier for users to copy the [bidder API protobuf generated](https://github.com/primev/mev-commit/tree/v1.1.0/p2p/gen/go/bidderapi/v1) files into their local project. Then, incorporate the generated client into your Go application as follows: ```go import bidderapiv1 "github.com//bidderapi/v1" conn, err := grpc.DialContext( context.Background(), "localhost:13524", grpc.WithBlock(), grpc.WithTransportCredentials(insecure.NewCredentials()), ) if err != nil { // Error handling logic here } currentTime := time.Now().UnixMilli() bid := &pb.Bid{ TxHashes: []string{ "fe4cb47db3630551beedfbd02a71ecc69fd59758e2ba699606e2d5c74284ffa7", "71c1348f2d7ff7e814f9c3617983703435ea7446de420aeac488bf1de35737e8", }, Amount: "1000000000", // Specify amount in wei BlockNumber: 123456, DecayStartTimestamp: currentTime - (time.Duration(8 * time.Second).Milliseconds()), DecayEndTimestamp: currentTime + (time.Duration(8 * time.Second).Milliseconds()), } rcv, err := bidderClient.SendBid(context.Background(), bid) if err != nil { // Error handling logic here } for { pc, err := rcv.Recv() if err == io.EOF { break } if err != nil { // Error handling logic here } fmt.Println("Received preconfirmation:", pc.String()) } ``` ### Custom Client Generation Utilize the provided protobuf [files](https://github.com/primev/mev-commit/tree/v1.1.0/p2p/rpc/bidderapi/v1/bidderapi.proto) to generate a client in your preferred programming language, enabling seamless integration with your existing codebase. ## REST API 🚀 **Ready to send bids?** Just execute this command: ```shell ❯_ structure curl -X POST http://localhost:13523/v1/bidder/bid \ -d '{ "txHashes": [], "amount": , "blockNumber": "decayStartTimestamp": , "decayEndTimestamp": }' ``` ```shell ❯_ example curl -X POST http://localhost:13523/v1/bidder/bid \ -d '{ "txHashes": ["91a89B633194c0D86C539A1A5B14DCCacfD47094"], "amount": 10000000000000000, "blockNumber": 4123456, "decayStartTimestamp": 1716935571901, "decayEndTimestamp": 1716935572901 }' ``` The REST API provides a straightforward way to submit bids using HTTP requests. For detailed usage instructions, refer to [the Bidder API documentation](/v1.1.0/api-reference/bidder/sendbid). # Bidder Best Practices Source: https://docs.primev.xyz/v1.1.0/get-started/bidders/best-practices ## Understanding Credible and General Commitments In the mev-commit network, commitments are essential to the bidding process. You may receive two types of commitments: credible and general. If the slot proposer is opted-in to mev-commit, provider commitments become credible. Understanding the difference between these two types of commitments will help you, as a bidder, optimize your interactions with the network and maximize your utility. **Credible Commitments** - Credible commitments are guarantees made by network participants who have direct control over fulfilling your bid. This could include block builders, proposers, or sequencers. These commitments offer the highest level of assurance that your bid will be delivered as promised, as they mean the proposer has opted in to mev-commit. [Querying for Proposers](/v1.1.0/get-started/bidders/bidder-node-commands#querying-for-proposers-api) is available by default and will notify you when your commitments are ultimately credible. **General Commitments** - General commitments are also promises made by network participants, but they offer a lower level of assurance compared to credible commitments. However, general commitments can approach the reliability of credible commitments when aggregated across multiple providers, such as all block builders for a mev-boost-enabled validator. This simply means that the proposer hasn't opted in to mev-commit, but a committing block builder may still win the mev-boost auction and deliver its commitment for your bid. ## Submit Bundles To include bundles of transactions, submit them in the exact atomic sequence they appear in the bundle. Bundles can be submitted as either: * An array of transaction hashes. * An array of transaction payloads. Submitting raw transaction payloads is more efficient for providers, as it eliminates the extra step of looking up the payload based on a transaction hash when matching transactions with preconfirmation bids. This allows providers to be able to send preconfirmation commitments back to the bidder faster as well. You can learn more about bid structure [here](https://docs.primev.xyz/v1.1.0/concepts/bids/bid-structure). ### Transaction Payload Include the raw transaction payloads in your bid in the atomic sequence in which they need to be placed in the block. ```shell ❯_ example curl -X POST http://localhost:13523/v1/bidder/bid \ -d '{ "rawTransactions": ["0x02f8db82426882010c8410433624841043362f8303425094ea593b730d745fb5fe01b6d20e6603915252c6bf87016e03ce313800b864ce0b63ce0000000000000000000000000e94804eaa3c4c5355992086647f683f6f41ef1f000000000000000000000000000000000000000000000000000150e0786cc000000000000000000000000000000000000000000000000000000000000004e378c001a0ece6d13b20247abdc07d669c9186ee5a1ac9601db8c98a3323024ab299cb6662a01c20680efe4e0bb48a3a936b5ab27c741819f0ac567b12b34b230004b20b78a0", "0x02f8748242682c841043362684104336318252089412b141665da4a5f617c759ad996ef91ad806a9c0880de0b6b3a764000080c001a0806552ed846808580eb896994825f07e73de2f42e2d3554f228284ecfaa89d9ca046d58b62ba565982fb07a64b436dd7a6c210b2f59c4fb2aee2cdd150ccf8bfaa"], "amount": "", "blockNumber": , "decayStartTimestamp": , "decayEndTimestamp": , "revertingTxHashes": ["7ca16add2aa1b1ef718006b791cb48a6ad729d22f5d2a0b294705320e4825abb"] }' ``` ### Transaction Hash Alternatively, you may refer to transactions that providers may already have through their RPCs or the public mempool by using transaction hashes. Note that not all providers may support this feature, and we encourage the use of the transaction payload option for optimal results. ```shell ❯_ example curl -X POST http://localhost:13523/v1/bidder/bid \ -d '{ "txHashes": ["0549fc7c57fffbdbfb2cf9d5e0de165fc68dadb5c27c42fdad0bdf506f4eacae", "22145ba31366d29a893ae3ffbc95c36c06e8819a289ac588594c9512d0a99810", "7e1506f266bc86c81ae46018053a274a3bd96a9eff17392930707bf8fa5ff6be"], "amount": "", "blockNumber": , "decayStartTimestamp": , "decayEndTimestamp": , "revertingTxHashes": ["22145ba31366d29a893ae3ffbc95c36c06e8819a289ac588594c9512d0a99810"] }' ``` You can change the values in the fields `txHashes`, `amount`, `blockNumber`, `decayStartTimestamp`, `decayEndTimestamp` and `revertingTxHashes` as desired. ### Bid amount Note the bid `amount` should be set to the total amount the bidder is willing to pay for the bundle. Gas used by the transactions in the bundle does **not** affect the final amount paid. ### Bid Decay The `decayStartTimestamp` and `decayEndTimestamp` are important components for how sensitive the [price of a preconfirmation](https://docs.primev.xyz/v1.1.0/knowledge-base/how-to-price-a-bid) will be. More details can be found about it [here](https://docs.primev.xyz/v1.1.0/concepts/bids/bid-structure#details-on-decay-parameters). ## Troubleshooting Bidders will start receiving commitments instantly in most cases. If you're having trouble receiving commitments, check your bid parameters and ensure your bid is high enough for the commitment you're requesting. Additionally check that you are connected to providers (via the [topology endpoint](https://docs.primev.xyz/v1.1.0/get-started/bidders/bidder-node-commands#topology)) and that you are receiving mev-commit events (via the [health endpoint](https://docs.primev.xyz/v1.1.0/get-started/bidders/bidder-node-commands#health)). ## Bidder Funds and Autodeposit Window Bidders on mev-commit need funds available in their account to submit bids, which can be obtained via bridging to your wallet address and then depositing to your node address. For testnet, you can obtain funds by using the [bridge](/v1.1.0/get-started/bridge). Once funds are deposited, the auto deposit function will automatically deposit funds into your account for the next 3 [windows](/v1.1.0/concepts/bids/bidder-deposit) to bid. Unused funds will automatically transfer into upcoming windows for bidding. You can read more about the auto deposit feature [here](https://docs.primev.xyz/v1.1.0/get-started/bidders/bidder-node-commands#autodeposit-funds). ## (Optional) Provider RPCs If you don't send transaction payloads in your bid, you can send your transactions directly to block builders. Below is a table of Provider RPCs to send your transactions to on testnet. You may already be sending transactions to these providers if you have existing transaction operations.
Provider RPC Endpoint Mainnet RPC Endpoint Testnet
Preconf Builder tbd [http://52.11.201.67/execution/rpc](http://52.11.201.67/execution/rpc)
Titan [rpc.titanbuilder.xyz](https://rpc.titanbuilder.xyz/) [holesky-rpc.titanbuilder.xyz](https://holesky-rpc.titanbuilder.xyz/)
# Bidder CLI application Source: https://docs.primev.xyz/v1.1.0/get-started/bidders/bidder-cli The `bidder-cli` aims to provide a better UX for users to send raw transactions or bids on existing transactions, to the mev-commit network. The tool can be downloaded from the [releases](https://github.com/primev/mev-commit/releases/latest) page. ``` NAME: bidder-cli - A CLI tool for interacting with a gRPC bidder server USAGE: bidder-cli [global options] command [command options] VERSION: 1.1.0 COMMANDS: send-tx-hash Send a bid to the gRPC bidder server send-tx Send a transaction to the gRPC bidder server help, h Shows a list of commands or help for one command GLOBAL OPTIONS: --help, -h show help --version, -v print the version ``` The `send-tx` command is used to send raw transaction payloads. Here users can create a new transaction on the L1 chain and send it directly to the mev-commit network. Users need to provide the account to be used as source of the funds and to sign the transaction. Currently this allows users to send simple transfer transactions. ``` NAME: bidder-cli send-tx - Send a transaction to the gRPC bidder server USAGE: bidder-cli send-tx [command options] OPTIONS: --rpc-url value URL of the gRPC server [$BIDDER_CLI_RPC_URL] --l1-rpc-url value URL of the L1 RPC (default: "https://ethereum-holesky-rpc.publicnode.com") [$BIDDER_CLI_L1_RPC_URL] --verbose enable verbose logging (default: false) [$BIDDER_CLI_VERBOSE] --from value private key of the account sending the transaction --to value to address --value value amount of the transaction --block-number value block number (default: 0) --decay-duration value decay duration (default: "10m") --bid-amount value bid amount --help, -h show help ``` The `rpc-url` is the URL for the gRPC server running on the bidder node. This is by default running on port 13524. So if you run the node locally, this would typically be `localhost:13524`. If `block-number` is not specified, the next block number is used for the bid. Similarly, the default `decay-duration` is 10 minutes. Which means the bid amount will decay starting from current time to 10 minutes from now. `value` is the amount of ETH to be sent in the L1 transaction and `bid-amount` is the amount the bidder is willing to give to the providers for preconfirming the transaction. All the other flags have sane defaults. The CLI uses the `l1-rpc-url` to get the nonce for the account. Users can point it to a different RPC URL if they are sending transactions to a custom RPC. ```shell ❯_ example ./bidder-cli send-tx \ --from \ --to \ --value \ --bid-amount \ --rpc-url localhost:13524 ``` The `send-tx-hash` is used to send bids for transactions that were already submitted to the mempool of the block-builders or to the public mempool. There is a possibility that the transaction is not gossiped to the provider's block building infrastructure in time, so it is better to use the Provider's RPC for submitting transactions. ``` NAME: bidder-cli send-tx-hash - Send a bid to the gRPC bidder server USAGE: bidder-cli send-tx-hash [command options] OPTIONS: --rpc-url value URL of the gRPC server [$BIDDER_CLI_RPC_URL] --l1-rpc-url value URL of the L1 RPC (default: "https://ethereum-holesky-rpc.publicnode.com") [$BIDDER_CLI_L1_RPC_URL] --verbose enable verbose logging (default: false) [$BIDDER_CLI_VERBOSE] --tx-hashes value [ --tx-hashes value ] transaction hashes --bid-amount value bid amount --block-number value block number (default: 0) --decay-duration value decay duration (default: "10m") --reverting-tx-hashes value [ --reverting-tx-hashes value ] reverting transaction hashes --help, -h show help ``` Users can provider multiple transaction hashes to bid on. Rest of the flags have similar use cases as above. ```shell ❯_ example ./bidder-cli send-tx-hash \ --tx-hashes \ --tx-hashes \ --bid-amount \ --rpc-url localhost:13524 ``` # Bidder Node Commands Source: https://docs.primev.xyz/v1.1.0/get-started/bidders/bidder-node-commands ## Interacting with the Bidder Node Ensure you have completed the [Quickstart](/v1.1.0/get-started/quickstart) step in a separate terminal. This will set up your environment and place your key in the `$HOME/.mev-commit` directory, along with running the required bidder node. Now that you've made sure we have a bidder node running, we can interact with it using the following commands: ```shell ❯_ terminal cd $HOME/.mev-commit; export KEY=$(cat key); export ADDRESS=$(cast wallet address --private-key 0x$(cat key)) ``` ## Getting Deposit To get the current deposit balance in the contract for the current [window](/v1.1.0/concepts/bids/bidder-deposit): ```shell ❯_ terminal curl -s http://localhost:13523/v1/bidder/get_deposit ``` To get the current deposit balance in the contract for a specific [window](/v1.1.0/concepts/bids/bidder-deposit): ```shell ❯_ terminal curl -s http://localhost:13523/v1/bidder/get_deposit?windowNumber=1 ``` Deposit represents the funds in the bidder's account that can be used to submit bids on the mev-commit p2p-network and settled on-chain. ## Withdraw Deposited Funds This command will allow you to withdraw funds from the specific [window](/v1.1.0/concepts/bids/bidder-deposit). Window number is the number where the bidder deposited funds. ```shell ❯_ terminal curl -X POST http://localhost:13523/v1/bidder/withdraw?windowNumber=1 \ ``` ## Autodeposit Funds The auto deposit feature allows you to automate the process of depositing funds for the bidder account. This is useful for ensuring your bidder account always has funds available to bid. In order to achieve this, the node will keep issuing deposits for the new windows and also withdrawing funds from the previous windows. For seamless availability of funds, the deposits would be locked for around 3 windows at a time. So the total amount locked would be `3 * amountPerWindow`. The user's wallet should have enough funds to be able to maintain these deposits as well as cover gas costs to issue transactions. There are two ways to enable this feature: ### On node boot up Users can use the command-line or the configuration file to enable this feature on node boot-up. The `autodeposit-enabled` flag should be set as well as the `autodeposit-amount` needs to be set to the amount to be deposited in each window. In order to enable this at node boot up, users needs to fund their wallet before starting the node. So we would need to know the private-key used for the account beforehand. ```shell ❯_ terminal mev-commit --keystore-path ~/.mev-commit \ --keystore-password \ --bootnodes /dnsaddr/bootnode.testnet.mev-commit.xyz \ --settlement-rpc-endpoint https://chainrpc.testnet.mev-commit.xyz --autodeposit-enabled true --autodeposit-amount 1000000000000000000 ``` ### Use the Bidder API Another option to enable this is using the Bidder API. ```shell ❯_ terminal curl -X POST http://localhost:13523/v1/bidder/auto_deposit/1000000000000000000 ``` ## Get Auto Deposit Status To get the status of the auto deposit process: ```shell ❯_ terminal curl -s http://localhost:13523/v1/bidder/auto_deposit_status ``` ## Cancel Auto Deposit To cancel the auto deposit process: ```shell ❯_ terminal curl -X POST http://localhost:13523/v1/bidder/cancel_auto_deposit?withdraw=true ``` This will stop the ongoing auto deposit process. If withdraw is set, the node will try to withdraw the deposit at the earliest possible time. It might take time before we are able to withdraw from the current window. The bidder node should be running in order to allow this process to complete. If withdraw is not set, the API will return the window numbers which have been already deposited to. The user can then manually issue withdraw at a later point using the API. ## Withdraw Funds To withdraw funds from the several windows, you can use the following command: ```shell ❯_ terminal curl -X POST http://localhost:13523/v1/bidder/withdraw_from_windows \ -H "Content-Type: application/json" \ -d '{"windowNumbers": [1, 2, 3]}' ``` ## Checking the Balance of your Wallet ### Mainnet This command will allow you to check your current wallet balance on mainnet mev-commit chain: ```shell ❯_ terminal cast b $ADDRESS --rpc-url https://chainrpc.mev-commit.xyz ``` ### Testnet This command will allow you to check your current wallet balance on testnet mev-commit chain: ```shell ❯_ terminal cast b $ADDRESS --rpc-url https://chainrpc.testnet.mev-commit.xyz ``` ## Check Total Value Locked in Contracts ### Mainnet ```shell ❯_ terminal python3 -c "print($(cast b 0xb772Add4718E5BD6Fe57Fb486A6f7f008E52167E \ --rpc-url https://chainrpc.mev-commit.xyz) + $(cast b 0xC973D09e51A20C9Ab0214c439e4B34Dbac52AD67 \ --rpc-url https://chainrpc.mev-commit.xyz))" ``` ### Testnet ```shell ❯_ terminal python3 -c "print($(cast b 0x401B3287364f95694c43ACA3252831cAc02e5C41 \ --rpc-url https://chainrpc.testnet.mev-commit.xyz) + $(cast b 0xf4F10e18244d836311508917A3B04694D88999Dd \ --rpc-url https://chainrpc.testnet.mev-commit.xyz))" ``` ## Health The health endpoint checks whether the bidder node is receiving events from mev-commit chain. This command is useful to determine whether the bidder node has become out of sync (e.g. can't find the window balance). ```shell ❯_ terminal curl http://localhost:13523/health ``` ## Topology The topology endpoint can be used to check which provider nodes the bidder node is connected to. ```shell ❯_ terminal curl http://localhost:13523/v1/debug/topology ``` ## Querying for Proposers API This API is enabled by default, the following environment variables could be set when launching a mev-commit client: * `MEV_COMMIT_VALIDATOR_ROUTER_ADDR` * `MEV_COMMIT_BEACON_API_URL` * `MEV_COMMIT_L1_RPC_URL` Current address for the ValidatorOptInRouter contract on Holesky is `0x251Fbc993f58cBfDA8Ad7b0278084F915aCE7fc3` and on Mainnet is `0x821798d7b9d57dF7Ed7616ef9111A616aB19ed64`. The default URLs for the *Mainnet* Beacon Chain and L1 RPC are [https://ethereum-beacon-api.publicnode.com](https://ethereum-beacon-api.publicnode.com) and [https://ethereum-rpc.publicnode.com](https://ethereum-rpc.publicnode.com), respectively, but you can set your own URLs. The default URLs for the *Testnet* Beacon Chain and L1 RPC are [https://ethereum-holesky-beacon-api.publicnode.com](https://ethereum-holesky-beacon-api.publicnode.com) and [https://ethereum-holesky-rpc.publicnode.com](https://ethereum-holesky-rpc.publicnode.com), respectively, but you can set your own URLs. To get the information on whether validators for a specific epoch are opted in to mev-commit: ```shell ❯_ terminal curl http://localhost:13523/v1/validator/get_validators?epoch=1 ``` To get the information on whether validators for a latest epoch are opted in to mev-commit: ```shell ❯_ terminal curl http://localhost:13523/v1/validator/get_validators ``` You can also subscribe to notifications to receive real-time updates when validators opt in or when a new epoch starts with opted-in validators. To subscribe to these notifications: ```shell ❯_ terminal curl -N -H "Content-Type: application/json" -d '{"topics": ["validator_opted_in", "epoch_validators_opted_in"]}' http://localhost:13523/v1/subscribe ``` This will establish a streaming connection that will send notifications when: * The next block proposer has opted in to the mev-commit protocol (`validator_opted_in`) * A new epoch begins, providing a list of all opted-in validators for that epoch (`epoch_validators_opted_in`) Note proposer selection is only stable within the context of the current epoch, and must be checked during the epoch in question. See specification [here](https://github.com/ethereum/consensus-specs/blob/dev/specs/phase0/validator.md#validator-assignments) and [here](https://github.com/ethereum/consensus-specs/blob/dev/specs/phase0/validator.md#lookahead). ## Configuring custom provider sets Users can also set-up a specific subset of provider nodes in order to send their bids. By default the mev-commit bidder node will send bids to all the available and staked providers. However, if the user wants only a specific subset of providers to be able to see their bids, the can use the `--provider-whitelist` option to set it up. The list should contain the ethereum wallet addresses of the provider nodes. ### Mainnet ```shell ❯_ terminal mev-commit --keystore-path ~/.mev-commit \ --keystore-password \ --bootnodes /dnsaddr/bootnode.mev-commit.xyz \ --settlement-rpc-endpoint https://chainrpc.mev-commit.xyz --provider-whitelist 0x6DcE7bcF4fCA9E14b546e583049B82474631b185,0x0979c194EaD08444B6e40415F5822AB32363f580 ``` ### Testnet ```shell ❯_ terminal mev-commit --keystore-path ~/.mev-commit \ --keystore-password \ --bootnodes /dnsaddr/bootnode.testnet.mev-commit.xyz \ --settlement-rpc-endpoint https://chainrpc.testnet.mev-commit.xyz --provider-whitelist 0x6DcE7bcF4fCA9E14b546e583049B82474631b185,0x0979c194EaD08444B6e40415F5822AB32363f580 ``` # Using the Bridge UI Source: https://docs.primev.xyz/v1.1.0/get-started/bridge/bridge How to bridge ETH between L1 and mev-commit using the web interface The mev-commit bridge UI provides an intuitive interface for transferring ETH between Ethereum and the mev-commit chain. ## Bridging to mev-commit