# Add Auto Deposit 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. One 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 get /v1/bidder/auto_deposit_status AutoDepositStatus is called by the bidder node to get the status of the auto deposit. # Cancel Auto Deposit 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 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 get /v1/bidder/get_deposit GetDeposit is called by the bidder to get its deposit in the bidder registry. # Send Bid 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 post /v1/bidder/withdraw Withdraw is called by the bidder to withdraw deposit from the bidder registry. # Withdraw Deposit From Windows post /v1/bidder/withdraw_from_windows WithdrawFromWindows is called by the bidder node to withdraw funds from multiple windows. # Cancel Transaction post /v1/debug/cancel_transaction/{txHash} CancelTransaction is called by the provider to cancel a transaction sent from this wallet. # Pending Transactions get /v1/debug/pending_transactions GetPendingTransactions is called by the provider to get the pending transactions for the wallet. # 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 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. # Retrieve Minimum Stake 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 get /v1/provider/get_stake GetStake is called by the provider to get its stake in the provider registry. # Receive Bids 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 post /v1/provider/register_stake/{amount} RegisterStake is called by the provider to register its stake in the provider registry. # Send Processed Bids 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 post /v1/provider/unstake Unstake is called by the provider to request a unstake from the provider registry. # Withdraw Stake post /v1/provider/withdraw_stake WithdrawStake is called by the provider to withdraw its stake from the provider registry. # Get Validators get /v1/validator/get_validators GetValidators is called by the bidder to get the validators for a given epoch. # null 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. * **Proposers**: Validators who are positioned to propose a block to the network. As prime providers of execution services, they outsource this process to block builders by using mev-boost. As the mev pipeline evolves, they may have additional preferences or an Inclusion List to communicate to other execution service providers. * **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**](/v0.6.3/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 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$%. ## 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 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 | 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 { "txHashes":"0549fc7c57fffbdbfb2cf9d5e0de165fc68dadb5c27c42fdad0bdf506f4eacae,0549fc7c57fffbdbfb2cf9d5e0de165fc68dadb5c27c42fdad0bdf506f4eacaf,0549fc7c57fffbdbfb2cf9d5e0de165fc68dadb5c27c42fdad0bdf506f4effff", "amount":277610, "revertingTxHashes":"22145ba31366d29a893ae3ffbc95c36c06e8819a289ac588594c9512d0a99810", "blockNumber":2703, "digest":"uU2p20f5KmehWqpuY1u+CbhcS8jNwdQAJQe2dh0Vnrk=", "signature":"nY6jYsGPxj6LVlSVQJbZcxvmRrw8Ym5rqOL1x0W/xPlJGBaF/ZzzjkxiioY/MDiRGvlflSWeoT0fh3aIJiJxAhw=", "decayStartTimestamp":1716935571901, "decayEndTimestamp": 1716935572901, "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 | | ------------------- | --------------------------------------------------------- | | txnHashes | Array of transaction hashes represented as strings | | amount | 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 | ### 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](/v0.6.3/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 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 ## 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. # null 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 # 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 is currently being audited and has always been open source. ## **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](/v0.6.3/developers/contracts) to gain context on contracts necessary to enable bridging. # Chain Details The mev-commit chain mainnet is set to launch soon. In the meantime, join the testnet and get familiar with its functionalities at the [Testnet](/v0.6.3/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 Holesky blocks, and will transition to Mainnet as mev-commit migrates to Mainnet. * 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 ## 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 ### 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 **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 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. 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). ARUBE is used to efficiently disseminate bids from bidders to providers of their choice in a privacy-preserving manner, and DPCOM is used to securely commit to those bids and later allow for the opening of such commitments. 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 these protocols [here](https://mirror.xyz/preconf.eth/iz2J0uTXHhl8DiAkG-VLLwvCp-8qcc_Z7A8_4rU0A3g). # 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 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](/v0.6.3/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 providers and validators in more detail. ## 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. The provider is slashed if the commitment is not opened by either the provider or the bidder. 4. Nothing happens as the provider was not the winning execution provider for the Ethereum block. 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 In this section we discuss the provider's slashing cases. #### 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. #### Unopened Commitment If a commitment is not opened by either the provider or the bidder within 24 hours from the time of inclusion of the commitment in the mev-commit chain then the provider is penalized by the fixed amount of 1 ETH. The penalized amount from the provider goes to the mev-commit treasury, not to the bidder. This is because the bidder is not known in this case and to discourage the bidder from omitting the opening of the commitment based on the bid amount. ### Neutral Outcome The protocol will not take action in the event of a commitment being made and the provider not being the execution provider for the winning block. However, the network will be monitored to see how these neutral outcomes affect the mev-commit protocol, and a reputation scoring system can be employed in the future to quantify the credibility of a provider’s commitment. Providers with a higher reputation score can then have lower staking requirements, and vice versa. ## 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 Upon successfully including a block built by mev-commit providers in L1, the proposer is paid by the provider/builder through the mev-boost auction. 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 In this section we discuss the proposer's slashing cases. #### 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. ## Builder and Proposer Attribution The current methodology for identifying the provider responsible for building the L1 block relies on the **`extra_data`** field within the block's execution payload for block builders. The builder must post its EOA address registered with the mev-commit provider registry, in the `extra_data` field. This correlates an L1 block built by a mev-commit provider to its corresponding EOA registered with the mev-commit protocol. We plan to upgrade this with a cryptographically secure method of attribution and are actively championing the availability of robust builder identity in Ethereum. For proposers the attribution method is simpler as proposers are recognized within the Ethereum protocol. # 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 ### 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](/v0.6.3/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. The Titan Holesky relay is the only such relay at this time, see the [Titan Holesky Relay here](https://docs.titanrelay.xyz/). * 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 Validators opting into the mev-commit protocol should be aware of the following risks: * **Relay block delivery:** Relays could communicate blocks that do not abide by existing commitments. This would lead to slashing of the validator. * **Failure to propose block:** Validators could fail to propose a block for a slot that has preconf commitments. This would lead to slashing of the validator if there are existing commitments ### 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 through bundling them into an AVS. Stay tuned for more updates on this. # 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, Proposers, 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](/v0.6.3/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 ## **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 PreConfirmation) ``` **Message Definitions** ```protobuf message Bid { string tx_hash = 1; string bid_amount = 2; int64 block_number = 3; bytes digest = 4; bytes signature = 5; int64 decay_start_timestamp = 6; int64 decay_end_timestamp = 7; bytes nike_public_key = 8; string reverting_tx_hashes = 9; }; message PreConfirmation { 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; }; ``` ### **HTTP API** The same API is also available on the HTTP port configured on the node. Please review the [API docs](/v0.6.3/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 **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 [testnet faucet](http://faucet.testnet.mev-commit.xyz/). * **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 # 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 testnet contract addresses please refer to [Testnet](/v0.6.3/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. ## Deploying Custom Contracts 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 ### **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 # **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. * Afunded MEV-Commit address. * A valid Holesky private key for authentication. If you need 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 export const MevCommitAVSImplementationAddress = "0x5A68216faE665dF4650597B7472101Bb1b66C208"; export const MevCommitAVSProxyAddress = "0xBc77233855e3274E1903771675Eb71E602D9DC2e"; export const VanillaRegistryImplementationAddress = "0x59fBE4CC4CA974e98300F41Ac661f7204F0c3fCd"; export const VanillaRegistryProxyAddress = "0x47afdcB2B089C16CEe354811EA1Bbe0DB7c335E9"; Mev-commit is rolling out support for Ethereum mainnet in the coming weeks! Below is what's been deployed so far. ### **L1 Validator Registries**
Contract Address Type Address
MevCommitAVS Proxy {MevCommitAVSProxyAddress}
Implementation {MevCommitAVSImplementationAddress}
VanillaRegistry Proxy {VanillaRegistryProxyAddress}
Implementation {VanillaRegistryImplementationAddress}
All contract calls should be made through the proxy contracts. Implementations are listed for transparency, where verified contract code can be viewed. # Manual Node Setup 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_$(uname -s)_$(uname -m).tar.gz" curl -L \ "https://github.com/primev/mev-commit/releases/download/v0.5.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/v0.5.0/mev-commit_v0.5.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. ```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](/v0.6.3/developers/bidder-deposit) to start sending bids.


In order to register as a provider please go through the [registration process](/v0.6.3/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: v0.5.0 COMMANDS: help, h Shows a list of commands or help for one command GLOBAL OPTIONS: --config value path to config file [$MEV_COMMIT_CONFIG] --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] --keystore-password value use to access keystore [$MEV_COMMIT_KEYSTORE_PASSWORD] --keystore-path value path to keystore location (default: "~/.mev-commit/keystore") [$MEV_COMMIT_KEYSTORE_PATH] --p2p-port value port to listen for p2p connections (default: 13522) [$MEV_COMMIT_P2P_PORT] --p2p-addr value address to bind for p2p connections (default: "0.0.0.0") [$MEV_COMMIT_P2P_ADDR] --http-port value port to listen for http connections (default: 13523) [$MEV_COMMIT_HTTP_PORT] --http-addr value address to bind for http connections [$MEV_COMMIT_HTTP_ADDR] --rpc-port value port to listen for rpc connections (default: 13524) [$MEV_COMMIT_RPC_PORT] --rpc-addr value address to bind for RPC connections [$MEV_COMMIT_RPC_ADDR] --bootnodes value [ --bootnodes value ] list of bootnodes to connect to [$MEV_COMMIT_BOOTNODES] --secret value secret to use for signing (default: "secret") [$MEV_COMMIT_SECRET] --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] --bidder-registry-contract value address of the bidder registry contract (default: "0x401B3287364f95694c43ACA3252831cAc02e5C41") [$MEV_COMMIT_BIDDER_REGISTRY_ADDR] --provider-registry-contract value address of the provider registry contract (default: "0xf4F10e18244d836311508917A3B04694D88999Dd") [$MEV_COMMIT_PROVIDER_REGISTRY_ADDR] --preconf-contract value address of the preconfirmation commitment store contract (default: "0x9433bCD9e89F923ce587f7FA7E39e120E93eb84D") [$MEV_COMMIT_PRECONF_ADDR] --settlement-rpc-endpoint value rpc endpoint of the settlement layer (default: "http://localhost:8545") [$MEV_COMMIT_SETTLEMENT_RPC_ENDPOINT] --nat-addr value external address of the node [$MEV_COMMIT_NAT_ADDR] --nat-port value externally mapped port for the node (default: 13522) [$MEV_COMMIT_NAT_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] --help, -h show help --version, -v print the version ``` # 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; }; 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](/v0.6.3/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 ## 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 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 export const MevCommitNetworkAddress = "0x4535bd6fF24860b5fd2889857651a85fb3d3C6b1"; export const MevCommitMiddlewareAddress = "0x0D5A6dd3Ba8C6385ecA623B56199b7FFC490792a"; export const MevCommitAVSAddress = "0xEDEDB8ed37A43Fd399108A44646B85b780D85DD4"; export const VanillaRegistryAddress = "0x87D5F694fAD0b6C8aaBCa96277DE09451E277Bcf"; export const ValidatorOptInRouterAddress = "0x251Fbc993f58cBfDA8Ad7b0278084F915aCE7fc3"; export const BlockTrackerAddress = "0x7538F3AaA07dA1990486De21A0B438F55e9639e4"; export const OracleAddress = "0x0a3ad886AEfd3bA877bcB23E171e0e2a375806a0"; export const PreconfManagerAddress = "0x9433bCD9e89F923ce587f7FA7E39e120E93eb84D"; export const ProviderRegistryAddress = "0xf4F10e18244d836311508917A3B04694D88999Dd"; export const BidderRegistryAddress = "0x401B3287364f95694c43ACA3252831cAc02e5C41"; 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) | | Faucet | [http://faucet.testnet.mev-commit.xyz/](http://faucet.testnet.mev-commit.xyz/) | ### **Core Contract Addresses (Mev-commit chain)**
Contract Address
BidderRegistry {BidderRegistryAddress}
ProviderRegistry {ProviderRegistryAddress}
PreconfManager {PreconfManagerAddress}
Oracle {OracleAddress}
BlockTracker {BlockTrackerAddress}
### **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}
## 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.](/v0.6.3/developers/system-requirements) # Tools for Bid Submission We 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. Start by installing the mev-commit package: ```shell ❯_ terminal go install github.com/primev/mev-commit@latest ``` Then, incorporate the generated client into your Go application as follows: ```go import bidderapiv1 "github.com/primev/mev-commit/p2p/gen/go/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/blob/main/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](/v0.6.3/api-reference/bidder/sendbid). # Bidder 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](/v0.6.3/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](/v0.6.3/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 Decay The `decayStartTimestamp` and `decayEndTimestamp` are important components for how sensitive the [price of a preconfirmation](https://docs.primev.xyz/knowledge-base/how-to-price-a-bid) will be. More details can be found about it [here](/v0.6.3/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](/v0.6.3/v0.6.3/get-started/bidders/bidder-node-commands#topology)) and that you are receiving mev-commit events (via the [health endpoint](/v0.6.3/v0.6.3/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 [faucet](https://faucet.testnet.mev-commit.xyz/). Once funds are deposited, the auto deposit function will automatically deposit funds into your account for the next 3 [windows](/v0.6.3/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](/v0.6.3/v0.6.3/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
Preconf Builder [http://52.11.201.67:8545/](http://52.11.201.67:8545/)
Titan [holesky-rpc.titanbuilder.xyz](https://holesky-rpc.titanbuilder.xyz/)
# Bidder Node Commands ## Interacting with the Bidder Node Ensure you have completed the [Quickstart](/v0.6.3/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](/v0.6.3/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](/v0.6.3/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](/v0.6.3/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 This command will allow you to check your current wallet balance on mev-commit chain: ```shell ❯_ terminal cast b $ADDRESS --rpc-url https://chainrpc.testnet.mev-commit.xyz ``` ## Check Total Value Locked in Contracts ```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 is `0xCae46e1013D33587180Db5933Abd75D977c2d7ab`. The default URLs for the 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 ``` 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. ```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 ``` # Testnet Faucet This faucet is for Providers and Bidders only, Validators please visit the faucet links listed on [this](/v0.6.3/get-started/validators) page for Holesky ETH.

Visit our testnet [faucet page](http://faucet.testnet.mev-commit.xyz/), to easily request up to 10 ETH per request for your wallet.

To facilitate your interaction with the mev-commit Testnet, we provide a convenient method to fund your node with Ether using our dedicated faucet.

Simply enter your wallet address and submit your request. The transaction will process automatically, and the funds should appear in your account shortly, allowing you to engage with the network. # Querying for Proposers Use the pointers below to determine whether an upcoming proposer has opted in to mev-commit or not. ## Querying for Proposers API Although querying for proposers may be more appropriate for bidders, provider nodes still have the ability to access this API. See [Querying for Proposers API](/v0.6.3/get-started/bidders/bidder-node-commands#querying-for-proposers-api) for more information. # Consuming Bids from mev-commit Providers that have registered in the mev-commit registry will automatically start receiving bids on the mev-commit p2p network from bidders. In order to see incoming bids, providers need to communicate with their mev-commit node: Use the official go RPC client to communicate with your mev-commit node. Go get the mev-commit package and then import the generated client as below: ```bash ❯_ terminal go install github.com/primev/mev-commit@latest ``` ```go import providerapiv1 "github.com/primev/mev-commit/p2p/gen/go/providerapi/v1" conn, err = grpc.DialContext( context.Background(), "localhost:13524", grpc.WithBlock(), grpc.WithTransportCredentials(insecure.NewCredentials()), ) if err != nil { // handle error } client := providerapiv1.NewProviderClient(conn) bidStream, err := client.ReceiveBids(context.Background(), &providerapiv1.EmptyMessage{}) if err != nil { // handle error } bidC := make(chan *providerapiv1.Bid) go func() { defer close(bidC) for { bid, err := bidStream.Recv() if err != nil { // handle error } select { case <-bidStream.Context().Done(): case bidC <- bid: } } }() stream, err := client.SendProcessedBids(context.Background()) if err != nil { // handle error } for bid := range bidS { // check the bid details and communicate with the block-building // infrastructure to make a decision status := getDecision(bid) err := stream.Send(&providerapiv1.BidResponse{ BidDigest: bid.BidDigest, Status: status, }) if err != nil { // handle error } } ``` There is an [example implementation](https://github.com/primev/mev-commit/tree/main/p2p/examples/provideremulator) of a dummy provider client which blindly accepts all the bids it sees from its mev-commit node. This could be a good starting point for providers implementing their commitment decision logic in golang. ### Alternative Methods 1. Use [https://github.com/fullstorydev/grpcurl](https://github.com/fullstorydev/grpcurl) or [https://github.com/bloomrpc/bloomrpc](https://github.com/bloomrpc/bloomrpc) or other GUI clients like [Postman](https://www.postman.com). Relevant protobuf files are available in the [mev-commit repository](https://github.com/primev/mev-commit). 2. Check the [API docs](/v0.6.3/api-reference/introduction) to use the REST APIs. The RPC APIs are also available on the HTTP server. 3. Users can use the protobuf files to generate a client in language of their choice. # Registering as a Provider To register on the mev-commit network, providers need to stake ETH in the provider registry contract. This adds credibility to issued commitments, as stake may be slashed in the event of a broken commitment, such as committing to a preconfirmation bid and not including the relevant transaction in a block. Once a provider is registered on the network, other nodes will connect to it, and the provider node will receive bids. You can use the provider API to stake and check your stake balance. Make sure you've [launched a mev-commit node](/v0.6.3/developers/manual-start-mev-commit) first. Make sure you've also [funded your account on the mev-commit chain](/v0.6.3/get-started/faucet). Check the minimum amount that can be staked, and consider staking more than the minimum. Bidders will only connect to providers which have stake higher than this minimum. The larger a provider's stake, the greater the credibility behind that provider's commitments. The amount is set in `wei`. ```shell > curl localhost:13523/v1/provider/get_min_stake | jq { "amount": "1000000000000000000" } ``` ```shell > curl -X POST "http://localhost:13523/v1/provider/register_stake/1000000000000000000?blsPublicKey=0xpk" | jq { "amount": "10000000000000000000", "blsPublicKey": "0xpk" } ``` Once staked, peer connection logs should appear within a few minutes. You can check the `/topology` endpoint again to verify connected peers. Congrats, your provider node is registered on mev-commit and you're ready to [consume bids](/v0.6.3/get-started/providers/consuming-bids). Rewards on mev-commit rely on the `extra-data` field in the block header to attribute the winning providers. Providers need to register their node's Ethereum address and BLS public key against the unique `extra-data` field they use while building blocks. This registration is currently done manually by the Primev team, please contact us to register these details. Once the registration is done, the settlement chain will be able to correctly attribute the winning providers on L1. This will be automated in future. Other commands that can be used are: * Check stake balance ```shell > curl localhost:13523/v1/provider/get_stake | jq { "amount": "0" } ``` * Get the 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": "provider", "Underlay": "16Uiu2HAmDWZb4DxZQkS9yseXNukBFe6MhZdimSKuZcHFeJrF3jC9" }, "connected_peers": null, "blocked_peers": null } ``` We recommend reading the [consuming bids](/v0.6.3/get-started/providers/consuming-bids) section next to consume bids effectively. # Sending Commitments To send your first commitment, you will need to connect to the mev-commit Testnet. This will allow you to consume bids incoming to the network and submit commitments. To do this, you'll want to run an emulator to simulate accepting and rejecting bids. You will want to connect to a decisioning system that will accept and reject bids based on custom criteria. You can read more about the API to open a gRPC stream [here](/v0.6.3/api-reference/provider/sendprocessedbids). As an example, a dummy decisioning system is implemented in the repository. This dummy system accepts all the bids it gets. To try it, you can open a new terminal and run the following command: You require Go Version 1.21.1 to run the example emulator ``` git clone --recurse-submodules https://github.com/primev/mev-commit.git && cd mev-commit && git checkout v0.5.0 && cd p2p/examples/provideremulator && go run . ``` ## Configuring custom logic to process bids and send Commitments We can take a deeper look at how you can add custom logic to decision on the sending of commitments. ### Integrating Bid Processing in Your System To integrate bid processing in your system using the Provider API, follow these steps to receive bid information and send back processed bids: Implement the Provider service as outlined in the [providerapi.proto](https://github.com/primev/mev-commit/blob/main/p2p/rpc/providerapi/v1/providerapi.proto#L20). This requires setting up a server that can manage RPC methods, with a particular emphasis on the reception of bids and response of commitment authorizations. Utilize the ReceiveBids RPC method to listen for incoming bids from clients. This method streams bid messages to your server. The structure of the bid is as follows: ```proto message Bid { option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_schema) = { json_schema: { title: "Bid message" description: "Signed bid message from bidders to the provider." required: ["txHashes", "bidAmount", "blockNumber", "bidDigest"] } example: "{"bidDigest": "9dJinwL+FZ6B1xsIQQo8t8B0ZXJubJwY86l/Yu7yAH159QrPHU0qj2P+YFj+llbuI1ZygdxGsX8+P3byMEA5ig==", "status": "STATUS_ACCEPTED"}" }; 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 rawTransactions = 8; }; ``` The raw transactions are optionally provided by the bidder. If provided the order of the transaction hashes in `txHashes` will be the same as the order or the corresponding `rawTransactions`. Below is an image of the flow through which bids would be received through the gRPC API ![gRPC Flow for Getting Bids](https://mintlify.s3-us-west-1.amazonaws.com/primev-24/v0.6.3/images/grpc-flow-getbids.png) For each received bid, implement your custom logic to validate and process these bids. This could involve checking the bid's validity and feasibility based on orderflow, computing the effective gas price, and deciding whether to accept or reject the bid. After processing each bid, construct a BidResponse message indicating the outcome. This message should include the bid's digest and a status indicating acceptance or rejection. At a high level, to commit to a bid, your code must send a `STATUS_ACCEPTED` with the bid digest specified, and correspondingly `STATUS_REJECTED` to reject the bid. The BidResponse structure is as follows: ``` message BidResponse { option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_schema) = { json_schema: { title: "Bid response" description: "Response sent by the provider with the decision on the bid received." required: ["bidDigest", "status"] } example: "{\"bidDigest\": \"9dJinwL+FZ6B1xsIQQo8t8B0ZXJubJwY86l/Yu7yAH159QrPHU0qj2P+YFj+llbuI1ZygdxGsX8+P3byMEA5ig==\", \"status\": \"STATUS_ACCEPTED\"}" }; bytes bid_digest = 1 [(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = { description: "Digest of the bid message signed by the bidder." }]; enum Status { STATUS_UNSPECIFIED = 0; STATUS_ACCEPTED = 1; STATUS_REJECTED = 2; } Status status = 2 [(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = { description: "Status of the bid." }, (buf.validate.field).enum = { defined_only: true, in: [ 1, 2 ] }]; int64 dispatch_timestamp = 3; }; ``` It contains the following fields: 1. bid\_digest: A byte array (bytes type) that represents the digest of the bid message signed by the bidder. This serves as a unique identifier for the bid in question. 2. status: An enumeration (enum Status) that indicates the status of the bid. The status can be one of three values: STATUS\_UNSPECIFIED: The default value, indicating that the status has not been set or is unknown. STATUS\_ACCEPTED: Indicates that the bid has been accepted by the provider. STATUS\_REJECTED: Indicates that the bid has been rejected by the provider. 3. dispatch\_timestamp: Timestamp (int64 type) at which the commitment is accepted by provider and is used to compute the expected revenue from the preconfirmation. Deploy your gRPC server on suitable infrastructure, ensuring it's accessible to clients. Configure necessary network settings for security and connectivity. Example Server Implementation in Go: ```go import ( ... "github.com/primev/mev-commit/p2p/examples/provideremulator/client" providerapiv1 "github.com/primev/mev-commit/p2p/gen/go/providerapi/v1" ) func ...() { ... providerClient, _ := client.NewProviderClient(*serverAddr, logger) bidS, _ := providerClient.ReceiveBids() for { select { case bid, more := <-bidS: if !more { return } logger.Info("received new bid", "bid", bid) _ := providerClient.SendBidResponse(context.Background(), &providerapiv1.BidResponse{ BidDigest: bid.BidDigest, Status: providerapiv1.BidResponse_STATUS_ACCEPTED, // decide here if you want to accept or reject DispatchTimestamp: time.Now().Unix(), }) } } } ``` This should help you integrate bid processing into your system, allowing you to receive bid information and send back processed bids as commitments. # Withdraw Stake Withdraws the stake from the provider registry. Withdrawal on mev-commit chain should be done in two steps: Unstake the funds from the provider registry. ```shell > curl -X POST "http://localhost:13523/v1/provider/unstake" ``` Withdraw the stake from the provider registry. After 24 hours following the unstake operation, you can withdraw the funds from the provider registry. ```shell > curl -X POST "http://localhost:13523/v1/provider/withdraw_stake" | jq { "amount": "1000000000000000000" } ``` # Quickstart for mev-commit bidder node Step into the Primev ecosystem with ease. This guide covers everything you need to set up your mev-commit bidder node. For providers, please refer to the [manual start mev-commit](/v0.6.3/developers/manual-start-mev-commit) section ```bash ❯_ bidder curl -L -o launchmevcommit launch.mev-commit.xyz; chmod +x launchmevcommit; ./launchmevcommit --node-type bidder ``` ## Script Overview This script automates the setup and initialization of your Primev node, catering to both bidder and provider roles. Below is a detailed breakdown of the script's operations: ### 1. Initialization * Sets up essential variables like the RPC URL (`https://chainrpc.testnet.mev-commit.xyz) for network communication and the node type (either `bidder`or`provider\`). * Establishes the root directory (`$HOME/.mev-commit`) where the mev-commit node will be installed. ### 2. Download * Fetches the appropriate mev-commit binary for your system from the [Primev GitHub releases page](https://github.com/primev/mev-commit/releases/latest), considering your operating system and architecture. ### 3. Installation * Extracts the downloaded binary into the specified root directory, ensuring all necessary executables are correctly placed for the node's operation. ### 4. Configuration * Initializes the mev-commit node with your specified settings, including the node type and the RPC endpoint, along with necessary contract addresses for the node's functionality. ### 5. Wallet Setup * Generates a new private key and wallet address for your node. ### 6. Node Startup * Launches the mev-commit node in the background tailored to the specified role, enabling it to begin its operations within the Primev network. ### 7. Cleanup * Includes a cleanup function to ensure the node is properly shut down when the script exits, preventing any residual processes. To fund your account, please visit our [Testnet Faucet](/v0.6.3/get-started/faucet). Details about the account address will be displayed after running the command above. Open a new terminal window to send a bid and receive commitments from providers. Run the following command: ```shell ❯_ example curl -X POST http://localhost:13523/v1/bidder/bid \ -d '{ "txHashes": ["0549fc7c57fffbdbfb2cf9d5e0de165fc68dadb5c27c42fdad0bdf506f4eacae"], "amount": "", "blockNumber": , "decayStartTimestamp": , "decayEndTimestamp": , "revertingTxHashes": [] }' ``` | 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 hexadecimal encoded raw signed transaction payloads | You can change the values in the fields `txHashes`, `amount`, `blockNumber`, `decayStartTimestamp`, `decayEndTimestamp` and `revertingTxHashes` as desired. Make sure your bid amount is sufficiently high for the commitment you're requesting, and your target L1 block number is accurate. It's up to the providers to commit to your bid, so try to ensure a commitment is feasible to your bid by its construction. Selecting a target block of n+1 where n is the current block number generally makes it easy to receive a commitment for standard bid amounts. We recommend sending the raw transaction payloads in the bid. The `rawTransactions` field contains hexadecimal string of the RLP encoded raw transaction payloads. Only one out of `txHashes` or `rawTransactions` need to be sent in a bid. ```shell ❯_ example curl -X POST http://localhost:13523/v1/bidder/bid \ -d '{ "rawTransactions": ["0x02f8db82426882010c8410433624841043362f8303425094ea593b730d745fb5fe01b6d20e6603915252c6bf87016e03ce313800b864ce0b63ce0000000000000000000000000e94804eaa3c4c5355992086647f683f6f41ef1f000000000000000000000000000000000000000000000000000150e0786cc000000000000000000000000000000000000000000000000000000000000004e378c001a0ece6d13b20247abdc07d669c9186ee5a1ac9601db8c98a3323024ab299cb6662a01c20680efe4e0bb48a3a936b5ab27c741819f0ac567b12b34b230004b20b78a0"], "amount": "", "blockNumber": , "decayStartTimestamp": , "decayEndTimestamp": , "revertingTxHashes": [] }' ``` Congrats, you just sent your first L1 preconfirmation bid! You should be receiving commitments nearly instantly. Make sure to check [System Requirements](/v0.6.3/developers/system-requirements) to better understand what is needed to run mev-commit without any interruptions. If you want to perform a manual setup and learn details, please skip to the [manual start mev-commit](/v0.6.3/developers/manual-start-mev-commit) section. # Preconf Bot Example with Docker Ready to work preconf bot examples can be found [here](https://github.com/primev/preconf_bot_example) and ready to be dockerized. Additionally, the dockerized bidder node example repository can be found [here](https://docs.primev.xyz/v0.6.3/developers/docker-bidder). # Relay Integration Guide export const ProviderRegistryAddress = "0xf4F10e18244d836311508917A3B04694D88999Dd"; ## Overview This guide will walk you through integrating your relay with mev-commit. Once integrated, your relay will automatically: * Track which validators have opted into mev-commit * Only deliver mev-commit compliant blocks when opted-in validators are due to propose. Relay filtering diagram ## Quick Start * Check out this [mev-commit relay integration](https://github.com/flashbots/mev-boost-relay/pull/657) * Add required environment variables: MEV\_COMMIT\_RPC=wss\://chainrpc-wss.testnet.mev-commit.xyz PROVIDER\_REGISTRY\_ADDR={ProviderRegistryAddress} Test filtering behavior on Holesky: * Register a [test builder](/v0.6.3/get-started/quickstart) * Submit [test bids](/bidders/best-practices#submit-bundles) * Verify correct block filtering 1. Add your relay to our [supporting relays list](https://github.com/primev/mev-commit-docs/blob/main/v0.6.3/get-started/validators.mdx) 2. Provide connection details for validators 3. Contact the Primev team to coordinate validator outreach You have now successfully integrated your relay with mev-commit. ## Implementation Details ### How to Query the Provider Registry The mev-commit provider registry contract maintains the list of authorized providers such as block builders. You can query this contract to validate builder addresses. **Contract Details:** * Network: mev-commit * Address: {ProviderRegistryAddress} You can retrieve all connected providers using the following script: ```javascript // Import the ethers library const ethers = require("ethers"); // Define the provider using the RPC URL const provider = new ethers.JsonRpcProvider("https://chainrpc.testnet.mev-commit.xyz/"); // Define the contract address and ABI const providerRegistryAddress = "0xf4F10e18244d836311508917A3B04694D88999Dd"; const abi = [ "event ProviderRegistered(address indexed provider, uint256 stakedAmount, bytes blsPublicKey)" ]; // Create a new contract instance const contract = new ethers.Contract(providerRegistryAddress, abi, provider); // Function to retrieve the list of registered providers async function getRegisteredProviders() { // Create a filter for the ProviderRegistered event const filter = contract.filters.ProviderRegistered(); // Query the contract for the ProviderRegistered events const events = await contract.queryFilter(filter); // Map the events to get the list of provider bls public keys const providers = events.map(event => event.args.blsPublicKey); return providers; } // Call the function and log the result getRegisteredProviders().then(providers => { console.log("Registered Providers:", providers); }).catch(error => { console.error("Error:", error); }); ``` The output will be a list of providers, identified by their BLS pubkey, that have registered with mev-commit. ```bash Registered Providers: [ '0x4e9c5b21bb1df120a7000fac8e3b1978bc308d28b54bbeae76eff010d8d8f83d785adc4141faf179715f550088becd7f', '0x2e6b986435137b88685d8a2783c46ec9a68958bbb3f50b09a538954942c0f9066493d35b3e341a059a507d66d4545c23', '0x43c615787576375f2c7db9c03c8899bab545881e373a963873b0f10c00faa3da57c7c7ecc1915809c651bb40c055b22e', ... ] ``` ### What Contracts to Monitor To track which validators have opted into mev-commit monitor the appropriate validator registry contracts: * Native Restaking: MevCommitAVS contract * ERC20 Restaking: MevCommitMiddleware contract * Direct Staking: VanillaRegistry contract ### About Bid Filtering When receiving bids from builders: First, check if target validator has opted into mev-commit. For opted-in validators, verify the submitting builder: * Ensure builder is registered on mev-commit, OR * Builder is on the relay's registered builder list Only forward bids that satisfy one of these conditions. # Eigenlayer Opt-in Opt into mev-commit by natively restaking to our AVS. ## Why use this method? Opting-in validators through the mev-commit AVS is ideal for validators that are already natively restaked, or wish to natively restake through Eigenlayer. This method of opt-in is capital efficient in that a validator's 32 ETH already staked with the beacon chain can be reused as collateral for opting-in to mev-commit. Further, that beacon chain ETH can be restaked towards other protocols. ## Prerequisites If you plan to bulk opt-in a large number of validator pubkeys, check out the [Eigenlayer Operator Registration](/v0.6.3/knowledge-base/eigenlayer-operator-registration) guide. Individual validator entities represented by a pod owner must delegate their natively restaked ETH to an Operator that's registered with the mev-commit AVS. See how to delegate [here](https://docs.eigenlayer.xyz/eigenlayer/restaking-guides/restaking-user-guide/restaker-delegation/delegate-to-an-operator). For Holesky, already registered operators can be found on the mev-commit AVS [Eigenlayer dashboard](https://holesky.eigenlayer.xyz/avs/0xededb8ed37a43fd399108a44646b85b780d85dd4). Mainnet link coming soon. If your currently delegated operator is not registered with mev-commit, you have the option to [change your delegation](https://docs.eigenlayer.xyz/eigenlayer/restaking-guides/restaking-user-guide/restaker-delegation/redelegation-process). Operators serve the purpose of (optionally) being able to register natively restaked validator pubkeys with the mev-commit AVS. Only the operator that a validator specifically delegates to, and a validator's pod owner, are given validator pubkey registration permissions. If an Operator is registering pubkeys on behalf of validators, it's expected that the Operator manages those validators itself, or represents the validators to an extent that the Operator can realistically attest to the validator following the rules of mev-commit (staking-as-a-service providers for example). This trustful relationship between validators and their delegated Operator piggybacks off already agreed upon trust assumptions with eigenlayer delegation. ## Pubkey Registration Following operator delegation, each validator pubkey must be *registered* with the mev-commit AVS from the delegated operator's account, or from the pod owner account. This action confirms a validator's attestation to follow the relay selection rule mentioned in the [Validator Guide](/v0.6.3/get-started/validators/validator-guide#requirements). Pubkey registration is facilitated through the [validator dashboard](https://validators.mev-commit.xyz/dashboard) interface to the `MevCommitAVS.registerValidatorsByPodOwners` function. The connected metamask account (who is invoking the pubkey registration transaction) must be the delegated operator, or pod owner, of the validator pubkeys that are being registered. # Symbiotic Opt-in Opt into mev-commit by ERC20 restaking with the MevCommitMiddleware contract through Symbiotic. ## Why use this method? Opting-in through Symbiotic is ideal for validators that wish to be secured by ERC20 collateral residing from a Symbiotic vault. Symbiotic is capital efficient in that vault collateral can be restaked towards other protocols. Further, Symbiotic offers a large degree of restaking configurability. ## Prerequisites Prior to opt-in through Symbiotic, it's worth familiarizing yourself with their [documentation](https://docs.symbiotic.fi/) on Networks, Vaults, and Operators. This method of validator opt-in requires competency in vault and operator curation. ## Who is this for? Mev-commit is flexible in the type of entities that use Symbiotic to restake, and secure validators with our protocol. Any combination of Operator and Vault entities can be used, whether each are from the same organization or not. Most importantly, For L1 validators to be opted-in to mev-commit, some collateral stake must be slashable for each validator, in case that validator acts against its protocol commitments. In the context of Symbiotic, Vaults allocate slashable ERC20 collateral to Operators that are registered with the mev-commit network. This collateral may be slashable by other Symbiotic networks, hence it is restaked. Operators for the mev-commit network are responsible for bulk registering groups of L1 validator pubkeys to an associated vault. Every registered validator is represented by restaked collateral from a single Vault and Operator. Each Vault’s total collateral can be split up to secure/represent many validators in groups. Diagram showing the relationship between Vaults, Operators, Network Middleware, and the mev-commit Oracle ## Setup The following setup steps will reference various Symbiotic core contracts. Refer to their [deployments page](https://docs.symbiotic.fi/category/deployments) and [core source code](https://github.com/symbioticfi/core). ### Initial Network Setup The Network in this context is mev-commit. Our network is represented by a network address, and a middleware contract. Both of which can be found on the [testnet](/v0.6.3/developers/testnet#validator-registry-contract-addresses-holesky) page. Mainnet support is coming soon. Initially, the network address calls `NetworkRegistry.registerNetwork` to register with Symbiotic. Then `NetworkMiddlewareService.setMiddleware` to configure our middleware contract. This stage is completed by the mev-commit team (Primev). ### Vault Configuration A vault contract must be deployed and configured with slashable ERC20 `collateral`. Mev-commit will accept most forms of ERC20 collateral, unless they present significant risk of losing value. For non ETH denominated assets, overcollateralization may be required compared to their ETH denominated counterparts. In general vault configuration is immutable, and thus important to get right. See [Symbiotic's vault configuration docs](https://docs.symbiotic.fi/handbooks/vaults-handbook#vault-configuration). Mev-commit requires the following vault configuration: 1. The `burner` address must be set to a specialized "burner router" contract. This is a WIP from the Symbiotic team. Essentially, funds slashed specifically by the mev-commit protocol must routed to a mev-commit address. For now on Holesky, this requirement can be ignored. 2. The delegator module for the vault must be the `NetworkRestakeDelegator` type. `FullRestakeDelegator` is not supported. 3. The slasher module must be set, and can be either a `Slasher` or `VetoSlasher` type. Finally, vaults with instant slashers must have an `epochDuration` greater than `slashPeriodSeconds` to register with our middleware contract, ensuring collateral is slashable during the full slashing period. Vaults with veto slashers: * must have an `epochDuration` greater than `slashPeriodSeconds` + `vetoDuration`, where `vetoDuration` is specified by the slasher. * require the resolver to be disabled via `address(0)`, since a permissioned oracle account invokes slashing, requiring only the most basic slashing interface. ### Operator Actions Next, a Symbiotic operator can be setup as an EOA or a contract. The Operator must be registered with Symbiotic via `OperatorRegistry.registerOperator()`. The operator must then opt-in to the any vault which will secure validators via `VaultOptInService.optIn(vaultAddress)`. The operator then opts-in to the mev-commit network via `NetworkOptInService.optIn(networkAddress)`. Do not confuse the mev-commit network address with the middleware contract address. ### Vault Actions Next the vault curator address must make some calls. `INetworkRestakeDelegator.setNetworkLimit(bytes32 subnetwork, uint256 amount)` should be called on the delegator module of the vault. This sets the total amount of collateral the vault would like to restake to the mev-commit network. The `subnetwork` argument can be computed using Symbiotic's `Subnetwork` library, where the subnetwork id will always be `1`. The vault curator must then call `INetworkRestakeDelegator.setOperatorNetworkShares(bytes32 subnetwork, address operator, uint256 shares)` on the delegator module of the vault. This sets what portion of the mev-commit allocated stake the vault curator is allocating to the operator. ### Network Finishes Setup The final steps are completed by the network address, ie. the mev-commit team. Please reach out to us over twitter or telegram if you need this step to be completed. The network address must set a max network limit for the vault's delegator module, `IBaseDelegator.setMaxNetworkLimit(uint96 identifier, uint256 amount)` (subnetwork id = 1 in our case). This is the maximum amount of collateral that will be accepted by the network from the vault. The relevant operator must be registered with the middleware contract via `MevCommitMiddleware.registerOperators`, this is only callable by the network address. Finally, `MevCommitMiddleware.registerVaults` must be called by the network address to register the vault with the middleware contract. A `slashAmount` is set during this step for each vault. This slash amount depends on the underlying erc20 collateral type, and may be updated if/when token prices deviate on-chain. ## Setup Complete - Register Validators Now that setup is complete, the operator can register validators to the vault, so long as enough slashable collateral is allocated to the operator from previous steps. This is done through the [validator dashboard](https://validators.mev-commit.xyz/). Validator deregistration is also done through this dashboard, and requires waiting a deregistration period. ## How to Maintain Validators Stay Opted-In It's an operator's responsibility to monitor vault collateral, and make sure all registered validators are also slashable. This means if vault collateral is reduced to a value that does not define all validators as slashable (considering `slashAmount`), the operator must deregister validators of its choice, or implicitly accept that some quasi-random validators will no longer be "opted-in". # Validator Guide Opt into mev-commit with ease. This guide covers everything you need to passively opt-in to mev-commit as an L1 validator. ## Why Participate? Participation of L1 validators in the mev-commit protocol increases the credibility of preconfs made through mev-commit and consequently their value. Due to increased preconf values, providers have additional value to bid in the mev-boost auction, thus driving up the total revenue a proposer will get. ## Supported Networks Both Holesky and Mainnet L1 validators are able to opt-in to mev-commit. The opt-in process is initiated from the chain the validator is staked on. See [mainnet](/v0.6.3/developers/mainnet#l1-validator-registries) and [testnet](/v0.6.3/developers/testnet#validator-registry-contract-addresses-holesky) for relevant contract addresses. ## Requirements 1. An operational L1 validator node for either mainnet or Holesky. 2. An operational mev-boost sidecar. 3. Capital requirements as described further below. As a validator opting into the mev-commit protocol, ensure your mev-boost client only connects to mev-commit opted-in relays to avoid slashing for proposing blocks without delivering commitments. By opting-in to the mev-commit protocol as a validator **in one of the three forms described**, you agree to only use **opted-in relays**. These opted-in relays will only forward mev-boost bids from addresses that have registered with the mev-commit provider registry, such that any provider can be slashed in case of a protocol violation. This allows validators to passively opt-in to mev-commit, letting block builders and relays do the work. **Supporting Relays:** | Relay | Docs | | ------ | --------------------------------------------------- | | Titan | [docs.titanrelay.xyz](https://docs.titanrelay.xyz/) | | Aestus | [holesky.aestus.live](https://holesky.aestus.live/) | We expect all known relays to support opting-in to mev-commit within a few months of being live on mainnet. If you are a relay looking to join the mev-commit network please visit our [Relays page](/v0.6.3/get-started/relays) to get more information. Proposers who fallback to local block production, from either a fault in the mev-boost software or a lack of economically viable block bids, **will not be slashed**. See [flashbots docs](https://docs.flashbots.net/flashbots-mev-boost/architecture-overview/risks#liveness-and-local-fallback) for more on this scenario. The protocol may in the future slash for abuse of this local fallback mechanism. ## Choose Your Opt-In Method Note each validator pubkey should only opt-in using one of the three methods described below. [Click here](/v0.6.3/get-started/validators/eigenlayer) for more information on native restaking with mev-commit's AVS [Click here](/v0.6.3/get-started/validators/symbiotic) for more information on ERC20 restaking with mev-commit's middleware contract [Click here](/v0.6.3/get-started/validators/vanilla) for more information on "vanilla" staking with mev-commit ## Protocol Design To learn more about the protocol design for any of the registries, see their respective READMEs: * [MevCommitMiddleware](https://github.com/primev/mev-commit/tree/main/contracts/contracts/validator-registry/middleware#readme) * [MevCommitAVS](https://github.com/primev/mev-commit/blob/main/contracts/contracts/validator-registry/avs/README.md) * [VanillaRegistry](https://github.com/primev/mev-commit/tree/main/contracts/contracts/validator-registry#vanilla-registry---simple-staking-solution) To query the on-chain parameters of any registry (on mainnet or Holesky), run an example forge script like [this](https://github.com/primev/mev-commit/blob/main/contracts/scripts/validator-registry/GetParams.s.sol). # Vanilla Opt-in Opt into mev-commit by simply staking ETH. ## Why use this method? **Pros:** * Simple staking (aka vanilla staking) is the most straightforward method for validators to opt-in to mev-commit. * Vanilla staking requires minimal setup and is permissionless. The vanilla registry allows validators to be opted-in directly by staking native ETH. **Cons:** * Vanilla staking is not as capital efficient as using Symbiotic or Eigenlayer, as restaking isn't possible. The ETH used to vanilla stake validators is completely separate from a validator's 32 ETH already staked with the beacon chain. * Vanilla staking does not support the use of ERC20 collateral. ## Getting Started Validators are able to *opt-in to mev-commit* by *vanilla* staking ETH directly with the `vanillaRegistry` contract. This action confirms a validator’s attestation to follow the relay selection rule mentioned in the [Validator Guide](/v0.6.3/get-started/validators/validator-guide#requirements). The vanilla registry strictly accepts BLS public keys as the validator opt-in identifier. Any account can stake on behalf of validator pubkey(s), and only that account has the ability to unstake in the future. Accounts must only register pubkeys for which they control or otherwise manage. If an account registers a pubkey for which they do not own/manage (think “griefing”), their relevant stake amount may be slashed. The `VanillaRegistry.minStake` parameter represents how much ETH must be staked per validator pubkey to define that validator as opted-in to mev-commit. On mainnet, `minStake` is 1 ETH, while on Holesky it's 0.0001 ETH. For large groups of validators, it is recommended to stake in batches of 10-20 public keys at a time to ensure transaction success without hitting gas limits. This process can be tested on Holesky. ### Staking validator keys To vanilla stake validator pubkeys, navigate to the [validator dashboard](https://validators.mev-commit.xyz/dashboard). Choose "Opt-in", confirm the relevant validator's relays have been correctly configured as specified in the [Validator Guide](/v0.6.3/get-started/validators/validator-guide#requirements), then choose the "Simple" staking route. # Welcome to Primev Primev is building mev-commit; a credible commitment network used for preconfirmations & more export const QuickStartCardFooter = ({children}) =>
{children}
; export const CardContent = ({children}) =>
{children}
; export const Separator = () =>
; export const CardDescription = ({children}) =>
{children}
; export const QuickStartCard = ({children, title, icon}) =>
{children}
; Welcome to the starting point of your mev-commit journey! You can either visit our [quickstart guide](/v0.6.3/get-started/quickstart) which is tailored to your specific role within the Ethereum ecosystem and designed to get you up and running quickly. Or if you want to learn about specific concepts first, please visit the pages below that best align with your interests and needs: Searchers, Solvers, Rollup Provers, AA Bundlers, End Users Bidders seek to optimize their transaction execution strategies. Explore the resources below to efficiently identify and capture valuable transactions. • [Quickstart Your Node](/v0.6.3/get-started/quickstart) • [Send Transactions to Providers](/v0.6.3/get-started/bidders/best-practices#provider-rpcs) • [Node Commands](/v0.6.3/get-started/bidders/bidder-node-commands) • [Bid Structure](/v0.6.3/concepts/bids/bid-structure) • [Bidder Deposit](/v0.6.3/concepts/bids/bidder-deposit) • [Bid Decay](/v0.6.3/concepts/bids/bid-decay-mechanism) Block Builders, Relays, Proposers, Rollup Sequencers Providers form the backbone of the Primev ecosystem. Learn how to optimize your block production and validation processes with the resources below. • [Registering as a Provider](/v0.6.3/get-started/providers/registering-a-provider) • [Consuming Bids](/v0.6.3/get-started/providers/consuming-bids) • [Sending Commitments](/v0.6.3/get-started/providers/sending-commitments) • [Commitments Structure](/v0.6.3/concepts/commitments) • [Querying for Proposers](/v0.6.3/get-started/providers/Querying-for-proposers) • [Relay Guide](/v0.6.3/get-started/relays) L1 Ethereum Validators Validators add ultimate credibility to commitments for the mev-commit network. Start here to passively opt-in to mev-commit as a Validator through staking or restaking. • [Opting-in as a Validator](/v0.6.3/get-started/validators) • [Eigenlayer Operator Registration](/knowledge-base/eigenlayer-operator-registration) • [Validator Considerations](/v0.6.3/concepts/validator-considerations) ## About Primev Our mission at Primev is to solve coordination inefficiencies in decentralized domains additively to mev, driving network welfare and increase transparency and decentralization of the mev pipeline. ### Engage with Us Connect with us on various platforms to stay updated and get involved: * **X**: Follow us for real-time updates and announcements [here](https://x.com/primev_xyz). * **Github**: Track our progress, contribute to our open-source projects, and explore our repositories [here](https://github.com/primev). * **Mirror**: Stay informed with our latest articles and research papers [here](https://mirror.xyz/preconf.eth). Our work is open-source, and we welcome contributions from the community to enhance and expand our ecosystem. # Eigenlayer Operator Registration Instructions for registering as an Eigenlayer operator for the mev-commit AVS, enabling validator opt-in via restaking. ## Why register as a mev-commit AVS operator? Validator organizations may wish to register an operator entity with the mev-commit AVS in order to facilitate bulk validator opt-in to mev-commit via restaking. Operators currently serve the purpose of (optionally) being able to register validators with mev-commit, if the relevant validator(s) are natively restaked with Eigenlayer and delegated to the operator. Future iterations of the mev-commit AVS may assign Operators further tasks, such as decentralized oracle attestations. The mev-commit AVS dashboard can be found at [https://holesky.eigenlayer.xyz/avs/0xededb8ed37a43fd399108a44646b85b780d85dd4](https://holesky.eigenlayer.xyz/avs/0xededb8ed37a43fd399108a44646b85b780d85dd4). ## Prerequisites To register with the mev-commit AVS, operators must first register their Ethereum account with the Eigenlayer core contracts on Holesky. You can follow Eigenlayer's instructions for operator account registration [here](https://docs.eigenlayer.xyz/eigenlayer/operator-guides/operator-installation). You will need an `operator.yml` file to perform registration actions with the mev-commit AVS. This file is created as part of registering as an operator with the EigenLayer CLI, and does not need to be modified. See [Eigenlayer reference operator.yml](https://github.com/Layr-Labs/eigenlayer-cli/blob/master/pkg/operator/config/operator-config-example.yaml). All interactions are enabled by the [operator CLI for the mev-commit AVS](https://github.com/primev/eigen-operator-cli). To get started, head over to the [releases page](https://github.com/primev/eigen-operator-cli/releases) and download a binary for your OS from the latest release. Alternatively you can build from source code included in the repo. ## Mev-commit AVS Registration Mev-commit AVS registration is simple for Operators and only requires posting a signature over some AVS related metadata. Registration signals to EigenLayer that you'd like to be an operator for the mev-commit AVS. To register for the Holesky mev-commit AVS use a command similar to: ```bash mev-commit-operator-cli register \ --operator-config $PATH_TO_OPERATOR_YML \ --avs-address "0xededb8ed37a43fd399108a44646b85b780d85dd4" \ --boost-gas-params false \ --keystore-password $PASSWORD ``` The keystore password can be provided as an option, otherwise the CLI will prompt for it. The registration command will query data from the AVS contracts and sign over a hash of the following: 1. Operator address 2. Mev-commit AVS address 3. Unique salt 4. 1 hour expiry Then a registration transaction is sent on behalf of the operator account with the signed hash to be validated on-chain. A full list of command options can be found by running `mev-commit-operator-cli register --help`. ## Deregistration To deregister an operator from the mev-commit AVS, the operator account must first request deregistration: ```bash mev-commit-operator-cli request-deregistration [command options] ``` Then after waiting for the deregistration period to pass, the operator can deregister: ```bash mev-commit-operator-cli deregister [command options] ``` Both these commands accept the same options as the registration command. # How do I fix the error: "failed to read msg: stream reset"? Learn how to resolve the `failed to read msg: stream reset` error for provider nodes within the mev-commit network. ## Why does it happen? If you're a provider node and you encounter the error `failed to read msg: stream reset`, it usually indicates a need for further action on your part regarding staking and registration within the provider contract. This error often arises when the provider node has not been properly staked or registered, which is a crucial step to fully integrate into the network and participate in the bidding and block-building processes. ## How to avoid this? To resolve this issue, you should follow the detailed instructions provided in "Step 7. Stake Funds and Register". This step involves depositing the required stake into the provider contract and completing the registration process to authenticate your node as a legitimate and active participant within the mev-commit network. This staking and registration process not only addresses the immediate error but also enhances the security and integrity of the network by ensuring that all active provider nodes have a vested interest in the network's success. *** By following these steps and ensuring your node is correctly configured and registered, you can overcome the `failed to read msg: stream reset` error and participate actively in the mev-commit ecosystem. # How Do You Provide A Commitment for Execution? Learn what providers do during an execution preconfirmation. In [this guide](/knowledge-base/what-happens-during-an-execution-preconf), we covered what goes into an execution preconf. Now, let's look at what preconf providers are doing behind the scenes to make this possible. A provider receives bids through mev-commit and analyzes the bid parameters - transaction details, bid amount, and target L1 block number. Favorable bids might include: * Higher bid amounts * Transactions that align with the provider's own block building strategies * Bids for blocks in the near future (easier to plan for) Based on the analysis, the provider decides whether to commit to including the transaction. The provider's decision to commit generally depends on: * Profitability of including the transaction * Available block space * Potential conflicts with other commitments * The expected value of the opportunity as the timeslot nears its end If decided positively, the provider generates a cryptographic commitment that includes the transaction and sends it back to the bidder's node. Upon committing to a transaction, providers typically take the following steps: 1. They start a new simulation instance for the block they're building. 2. In this simulation, the committed transaction is treated as a fixed parameter, which allows them to ensure the committed transaction will execute as expected as they optimize the inclusion of additional transactions around the committed one. Multiple providers may issue commitments for the same bid. Ideally, providers seek 100% coverage by getting commitments from all providers registered in mev-commit before issuing a guarantee to the bidder. Block builders act as preconf providers. They receive bids and can issue commitments to include specific transactions in blocks they build. As the block is proposed, the committed transactions are executed. An oracle verifies that the committed transactions were indeed executed in the correct block. Preconfirmations are about ensuring execution terms. By allowing searchers to specify their execution preferences, transactors can have the assurance that execution will conform to their stated parameters. It also makes value extraction more transparent and according to predefined goals. # How to Price A Bid Learn how to find the sweet spot for competitive bids. Pricing a preconfirmation bid requires balancing several factors to optimize your chances of inclusion without overpaying. The formula developed by our research team takes into account: * Time you're submitting the transaction, t * Time at end of slot, T * The amount of discretion based on how you prioritize your priority fee. Tweak it to understand how much to bid. * The state contention factor. Factor in how much the extractable value is for the mev opportunity. * The bidder margin, how much you think you can pocket if it goes through. Your target margin should be determined based on your risk tolerance and the potential value of the transaction. **pFt \* M(t,T) + ασ(t,T) = Pbid** | | | | -- | ------------------- | | P | price | | pF | priority fee | | t | current time | | T | time at end of slot | | σ | cost of state | | α | 1 - bidder margin | | M | multiplier | Adjust your bid based on real-time commitments from providers. Start with conservative estimates and tweak as you learn the market. The goal is to find the sweet spot where your bid is competitive enough for inclusion, but not higher than necessary. # Introduction A collection of answers to frequently asked questions. Learn about deposit amounts required for bidding and their significance. Learn how to resolve this error for provider nodes within the mev-commit network. Discover what Foundry is and its role in smart contract development and interactions within the mev-commit ecosystem. Explore the reasons behind the necessity of using 'cast' for interacting with the mev-commit chain. Understand why resending a bid in the mev-commit ecosystem results in receiving the same commitment. # What Happens During An Execution Preconfirmation? Learn about what happens behind the scenes during an execution preconfirmation. Let's say you're a searcher or solver looking to execute a complex mev strategy on Ethereum involving multiple DeFi protocols. ## Problem Currently, when you send a transaction bundle: * You define your maximum slippage tolerance for each trade (eg. 1%) * You broadcast your bundle to one or more block builders. * You wait about 12 seconds (1 block) or more for it to be included. During this time, you have no guarantee that: * Your entire bundle will be included in the next block. * The transactions won't revert due to changing conditions. * Other mev actors won't push your transaction toward your slippage limit As a result of these factors: * You might miss your target prices. * You might pay gas for failed transactions. * Your bundle may not get included, which is especially problematic for single-shot opportunities in DeFi. Some arbitrage opportunities only exist for a very brief window, and missing this window means losing the entire opportunity. ## Using an Execution Preconfirmation Instead of blindly sending your transaction, you can use an execution preconf. Here's how: * Follow the [Quickstart guide](/v0.6.3/get-started/quickstart) to set up your mev-commit bidder node and fund your account. * Identify your mev opportunity. Craft your bundle and send the signed transaction to block builders as per usual. * Create and submit a bid for the transaction from your mev-commit bidder node (following the [bid structure here](/v0.6.3/concepts/bids/bid-structure)), supplying the hash of the transaction you just sent. * When you submit a bid, it goes to multiple providers by default. * If a provider accepts your bid, it will generate a cryptographic commitment to execute your transaction. These are typically sent in milliseconds. * Your bidder node automatically verifies each commitment it receives. * Aim to receive commitments from all registered providers. If you don’t, consider increasing your bid amount to make it more attractive to all providers. * Your transaction is now guaranteed to be executed as per the preconf terms for that provider (or else that provider will be slashed). * The transaction will execute in the specified block. **Benefits** * Real-time confirmation of future execution, translating to reduced risk for transacting * Ability to secure a specific execution slot at a better price * Even in the event of being frontrun, your transaction parameters will remain within your defined slippage, or else not execute * Instant transaction UX for searchers * Predictable gas costs By using a preconf, you've eliminated the uncertainty of the 12-second wait, secured your execution parameters, and protected yourself against potential mev exploitation, all in real-time. Unlike simple inclusion preconfirmations (which might still result in reverted transactions), execution preconfs ensure your bundle executes as intended. This leaderless, multi-provider approach offers superior guarantees that improve your chances to capture time-sensitive mev opportunities. # What is the Deposit Amount? Learn about deposit amounts required for bidding and their significance. A deposit amount is made by bidders before participating in a bidding process. This amount acts as a financial assurance and enables the bidder to place multiple bids. It's designed to be larger than individual bid amounts to cover the potential volume of bids a bidder might want to make. For instance, if a bid is set at 100 gwei, a bidder might need to deposit an amount like 1000 gwei to ensure they can place several bids without needing to make additional deposits for each one. This system ensures that bidders are serious and have the financial backing to support their bids, while also allowing providers to manage and monitor bidding activities efficiently. # What is Execution Preconfirmations? The mev-commit system enforces execution guarantees by default. This means that transactions must be executed successfully to ensure providers aren't slashed. We allow users to specify which transactions are critical and must succeed, and which can revert. This is important because providers, in most cases, can provide inclusion guarantees with little cost. For example, if a block builder has gas left in the block, they can trivially include any preconfirmed transaction at the bottom of the block. # What is Foundry? Discover what Foundry is and its role in smart contract development and interactions within the mev-commit ecosystem. ## What is Foundry? Foundry is a comprehensive toolkit designed to facilitate smart contract development and interaction, playing a pivotal role in the mev-commit ecosystem. It offers a robust framework for developers to deploy, test, and interact with smart contracts efficiently. This suite of tools is integral for the seamless development lifecycle of smart contracts, from inception to deployment and beyond. ## Usage with mev-commit The utility of Foundry extends to its ability to streamline the development process, providing developers with the necessary tools to write, test, and deploy smart contracts with ease and precision. Its extensive use in the mev-commit contracts underscores its reliability and effectiveness in managing complex smart contract interactions and ensuring that contracts perform as intended under various conditions. *** In summary, Foundry stands out as an essential toolset within the mev-commit environment, empowering developers with the capabilities to bring smart contract projects to fruition with a high degree of efficiency and confidence. # Why do I receive the same commitment when resending a bid? Understand why resending a bid in the mev-commit ecosystem results in receiving the same commitment. When you resend a bid within the mev-commit ecosystem, receiving the same commitment back is a direct result of the deterministic nature of the underlying cryptographic mechanisms, specifically hashes and the Elliptic Curve Digital Signature Algorithm (ECDSA). These mechanisms ensure that for a given set of inputs, the output will always be the same. This means that if the bid's payload (the data contained within the bid) and the bidder's private key do not change between submissions, and the provider's private key remains constant, the resulting commitment will be identical for each submission of the bid. This deterministic behavior is crucial for maintaining consistency and integrity in the bidding process, ensuring that each bid is uniquely tied to its specific data and the identities of the involved parties. ## What is this needed? This feature of cryptographic schemes like ECDSA provides a layer of security and predictability, ensuring that bids cannot be tampered with or falsely represented without the private keys. It also simplifies the process of verifying and accepting bids within the mev-commit framework, as each commitment reliably represents its associated bid, regardless of the number of submissions. # Why is cast necessary for mev-commit chain interactions? ## What is cast? The cli tool `cast` is used in the mev-commit ecosystem, designed to simplify user interactions with the blockchain. It serves various purposes, from executing transactions and querying data to deploying smart contracts, making blockchain interactions more accessible and user-friendly. ## EVM Compatibility While `cast` is highlighted for its ease of use and efficiency, the mev-commit chain's compatibility with the Ethereum Virtual Machine (EVM) broadens the scope for user interaction. This EVM compatibility means users are not limited to `cast`; they can leverage any EVM-compatible tools for their blockchain activities. To use these tools, it's essential to configure the RPC URL appropriately to ensure connectivity with the mev-commit chain. This flexibility underscores the mev-commit chain's user-centric approach, allowing for a choice in interaction methods to suit diverse user preferences and technical backgrounds. Whether through `cast` or other EVM-compatible tools, the key is seamless and effective interaction with the mev-commit chain.