# ClaimSlashedFunds Source: https://docs.primev.xyz/v1.2.x/api-reference/bidder/claimslashedfunds /v1.2.x/api-reference/bidder-openapi-spec.json post /v1/bidder/claim_slashed_funds ClaimSlashedFunds is called by the bidder to claim slashed funds from the provider. The response will show the amount claimed if any in wei. # Deposit Source: https://docs.primev.xyz/v1.2.x/api-reference/bidder/deposit /v1.2.x/api-reference/bidder-openapi-spec.json post /v1/bidder/deposit/{amount} Deposit is called by the bidder node to add deposit in the bidder registry, specific to a provider. # DepositEvenly Source: https://docs.primev.xyz/v1.2.x/api-reference/bidder/depositevenly /v1.2.x/api-reference/bidder-openapi-spec.json post /v1/bidder/deposit_evenly DepositEvenly is called by the bidder node to deposit a total amount evenly across multiple providers. # DepositManagerStatus Source: https://docs.primev.xyz/v1.2.x/api-reference/bidder/depositmanagerstatus /v1.2.x/api-reference/bidder-openapi-spec.json get /v1/bidder/deposit_manager_status DepositManagerStatus is called by the bidder node to query whether the bidder has enabled the deposit manager via eip 7702. # DisableDepositManager Source: https://docs.primev.xyz/v1.2.x/api-reference/bidder/disabledepositmanager /v1.2.x/api-reference/bidder-openapi-spec.json post /v1/bidder/disable_deposit_manager DisableDepositManager is called by the bidder node to disable the deposit manager by setting the bidder EOA's code to zero address. # EnableDepositManager Source: https://docs.primev.xyz/v1.2.x/api-reference/bidder/enabledepositmanager /v1.2.x/api-reference/bidder-openapi-spec.json post /v1/bidder/enable_deposit_manager EnableDepositManager is called by the bidder node to enable the deposit manager via eip 7702. # GetAllDeposits Source: https://docs.primev.xyz/v1.2.x/api-reference/bidder/getalldeposits /v1.2.x/api-reference/bidder-openapi-spec.json get /v1/bidder/get_all_deposits GetAllDeposits is called by the bidder to get all its deposits in the bidder registry, and the balance of the bidder EOA itself. # GetBidInfo Source: https://docs.primev.xyz/v1.2.x/api-reference/bidder/getbidinfo /v1.2.x/api-reference/bidder-openapi-spec.json get /v1/bidder/get_bid_info GetBidInfo is called by the bidder to get the bid information. If block number is not specified, all known block numbers are returned in the ascending order. # GetDeposit Source: https://docs.primev.xyz/v1.2.x/api-reference/bidder/getdeposit /v1.2.x/api-reference/bidder-openapi-spec.json get /v1/bidder/get_deposit GetDeposit is called by the bidder to get its deposit specific to a provider in the bidder registry. # GetValidProviders Source: https://docs.primev.xyz/v1.2.x/api-reference/bidder/getvalidproviders /v1.2.x/api-reference/bidder-openapi-spec.json get /v1/bidder/get_valid_providers GetValidProviders is called by the bidder node to get a list of all valid providers. Each provider returned by this RPC must: - Be "registered" in the provider registry - Have deposit >= minStake in provider registry - Have no pending withdrawal request with provider registry - Have at least one BLS key registered with provider registry # RequestWithdrawals Source: https://docs.primev.xyz/v1.2.x/api-reference/bidder/requestwithdrawals /v1.2.x/api-reference/bidder-openapi-spec.json post /v1/bidder/request_withdrawals RequestWithdrawals is called by the bidder node to request withdrawals from provider(s) # SendBid Source: https://docs.primev.xyz/v1.2.x/api-reference/bidder/sendbid /v1.2.x/api-reference/bidder-openapi-spec.json 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. # SetTargetDeposits Source: https://docs.primev.xyz/v1.2.x/api-reference/bidder/settargetdeposits /v1.2.x/api-reference/bidder-openapi-spec.json post /v1/bidder/set_target_deposits SetTargetDeposits is called by the bidder node to set target deposits per provider within the deposit manager. During this call, the bidder node will also attempt to top-up deposits for each new target deposit. # Withdraw Source: https://docs.primev.xyz/v1.2.x/api-reference/bidder/withdraw /v1.2.x/api-reference/bidder-openapi-spec.json post /v1/bidder/withdraw Withdraw is called by the bidder to withdraw their deposit to a provider. # CancelTransaction Source: https://docs.primev.xyz/v1.2.x/api-reference/debug/canceltransaction /v1.2.x/api-reference/debug-openapi-spec.json post /v1/debug/cancel_transaction/{txHash} CancelTransaction is called by the provider to cancel a transaction sent from this wallet. # GetPendingTransactions Source: https://docs.primev.xyz/v1.2.x/api-reference/debug/getpendingtransactions /v1.2.x/api-reference/debug-openapi-spec.json get /v1/debug/pending_transactions GetPendingTransactions is called by the provider to get the pending transactions for the wallet. # GetTopology Source: https://docs.primev.xyz/v1.2.x/api-reference/debug/gettopology /v1.2.x/api-reference/debug-openapi-spec.json 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. # Subscribe Source: https://docs.primev.xyz/v1.2.x/api-reference/notifications/subscribe /v1.2.x/api-reference/notifications-openapi-spec.json post /v1/subscribe Subscribe to notifications for given topics. The client will receive notifications for the topics it has subscribed to. The client can subscribe to multiple topics. # GetCommitmentInfo Source: https://docs.primev.xyz/v1.2.x/api-reference/provider/getcommitmentinfo /v1.2.x/api-reference/provider-openapi-spec.json get /v1/provider/get_commitment_info GetCommitmentInfo is called by the provider to retrieve the commitment information. # GetMinStake Source: https://docs.primev.xyz/v1.2.x/api-reference/provider/getminstake /v1.2.x/api-reference/provider-openapi-spec.json get /v1/provider/get_min_stake GetMinStake is called by the provider to get the minimum stake required to be in the provider registry. # GetProviderReward Source: https://docs.primev.xyz/v1.2.x/api-reference/provider/getproviderreward /v1.2.x/api-reference/provider-openapi-spec.json get /v1/provider/get_provider_reward GetProviderReward is called by the provider to retrieve their current reward balance without withdrawing it from the bidder registry. # GetStake Source: https://docs.primev.xyz/v1.2.x/api-reference/provider/getstake /v1.2.x/api-reference/provider-openapi-spec.json get /v1/provider/get_stake GetStake is called by the provider to get its stake in the provider registry. # ReceiveBids Source: https://docs.primev.xyz/v1.2.x/api-reference/provider/receivebids /v1.2.x/api-reference/provider-openapi-spec.json 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. # SendProcessedBids Source: https://docs.primev.xyz/v1.2.x/api-reference/provider/sendprocessedbids /v1.2.x/api-reference/provider-openapi-spec.json 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. # Stake Source: https://docs.primev.xyz/v1.2.x/api-reference/provider/stake /v1.2.x/api-reference/provider-openapi-spec.json post /v1/provider/stake/{amount} Stake is called by the provider to register or add to its stake in the provider registry. # Unstake Source: https://docs.primev.xyz/v1.2.x/api-reference/provider/unstake /v1.2.x/api-reference/provider-openapi-spec.json post /v1/provider/unstake Unstake is called by the provider to request a unstake from the provider registry. # WithdrawProviderReward Source: https://docs.primev.xyz/v1.2.x/api-reference/provider/withdrawproviderreward /v1.2.x/api-reference/provider-openapi-spec.json post /v1/provider/withdraw_provider_reward WithdrawProviderReward is called by the provider to withdraw their accumulated rewards from the bidder registry contract. # WithdrawStake Source: https://docs.primev.xyz/v1.2.x/api-reference/provider/withdrawstake /v1.2.x/api-reference/provider-openapi-spec.json post /v1/provider/withdraw_stake WithdrawStake is called by the provider to withdraw its stake from the provider registry. # Bid Decay Mechanism Source: https://docs.primev.xyz/v1.2.x/concepts/bids/bid-decay-mechanism Learn about how bids decay in value in real time In the mev-commit auction for transaction bundles, bidders submit their bids to providers and their goal is to receive a confirmation that the bundle they bid for will be included in the next block produced by the provider. Bidders aim to receive confirmation for their bundle as soon as possible since early confirmations tend to be more valuable to the bidders. However, providers may want to wait until the last moment to issue confirmations in order to build the most valuable block possible without missing out on any late bids. Therefore, it's essential to have a mechanism that encourages providers to confirm bids as early as possible. This is where a bid decay mechanism comes into play, which reduces the value of a bid based on the time elapsed since it was issued. ## Mechanism Description Every bid has two timestamps attached to it: **(1)** a timestamp indicating the exact time of dispatch of the bid, and **(2)** an expiry timestamp, marking the moment when the decay for this bid reaches 100%—essentially, the point in time beyond which the bidder is unwilling to pay anything to a provider for a commitment. The timestamp is specified in Unix milliseconds. For example, a timestamp of `1633046400000` represents `October 1, 2021 00:00:00 GMT`. When a provider decides to commit to the bid, they must issue a commitment and also assign a "commitment timestamp" to it. This commitment is then sent to the mev-commit chain for inclusion. The mev-commit chain will include the commitment into the chain, however the commitment will only be considered valid if the commitment timestamp supplied by the provider is not "too old" in comparison to the block timestamp where the commitment was included, or more formally, their difference is within some time interval $\Delta$. This time parameter $\Delta$ is set to be $500$ms, and its goal is to account for the latency in message delivery among nodes and the discrepancy between the commitment and block timestamps. More precisely, for validation of a commitment it is required that $t_b - t_c \le \Delta$, where $t_c$ denotes the commitment timestamp and $t_b$ denotes the timestamp of the block where the commitment was included. Note that even when $t_c > t_b$, i.e., the commitment timestamp was set to be greater than the timestamp of the block that it was included, the commitment is still considered valid. ## Computing the Bid Decay Once the commitment is included in the chain it can be publicly determined if the commitment is valid, and if so, what is the exact value that the bid has decayed. The bid's value decreases linearly from the moment it is issued until its expiry deadline is reached. Below we show a diagram of how providers can use the timestamps to first compute the proportion to which a commitment has decayed. Once the proportion has been computed the value of the bid can be decayed accordingly. For example, if the decay proportion is $1/2$ as in the example above, the bid's value decays by $50$%. In general, when a provider issues a commitment at time $t$ for a bid with amount $\mathrm{bidAmt}$, the bidder pays the provider the value $v$ computed as $$ v = \mathrm{bidAmt} \cdot \frac{\mathrm{decayEndTimestamp} - t}{\mathrm{decayEndTimestamp} - \mathrm{decayStartTimestamp}}, $$ constraint to $0 \leq v \leq \mathrm{bidAmt}$, i.e., the value $v$ paid is never more than $\mathrm{bidAmt}$. ## Analysis of the Mechanism The security of the mechanism comes from the fact that the participating parties have conflicting incentives. In particular, we note that there is no incentive for the bidder to manipulate the choice of the bid’s timestamps; if the bidder includes a timestamp in the future, then the provider essentially gets less decay (i.e., the bidder pays more). If the bidder includes a timestamp that is too old, then the provider can choose to not commit as the decay is too high (then the bidder gets no commitment). Moreover, we note that this would have the exact same effect as the bidder changing the price of its bid prior to the submission of the bid. Similarly, the commitment timestamp set by the provider must not be too old, as otherwise, it won't be valid when included in the mev-commit chain. In many network-based systems, including our decay mechanism, faster connections often provide better opportunities, such as quicker access to information or response times. This situation is similar to high-frequency trading in financial markets, where traders with faster connections can outperform others. In our system, any advantage due to a faster connection is bounded by the parameter $\Delta$. ## Properties of the Mechanism Our decay mechanism design achieves the following properties: **1. Predictability of Decay:** The providers can *accurately compute* how much their decay will be for a commitment. **2. Public Verifiability of Decay**: The decay mechanism offers public verifiability, as the decay amount can be calculated using the public timestamps from the bid and the commitment. **3. L1 Synchrony Independent:** Our decay mechanism maintains independence from the L1 actual slot time, ensuring that the decay mechanism functions correctly regardless of whether the L1 block confirmation occurs more quickly or experiences delays. **4. Just in time (JIT) Awareness of Bid:** JIT awareness of a bid ensures that the decay mechanism operates independently of the bid's submission time within the network, meaning a bid can be sent at anytime during a slot and experience correct decay. This is achieved by specifying the onset of decay and its deadline directly within the bid's structure, thus guaranteeing the mechanism functions as designed, irrespective of the bid's dispatch time. # Bid Structure Source: https://docs.primev.xyz/v1.2.x/concepts/bids/bid-structure The bid payload sent to the internal mev-commit API is as follows: | Key | Description | | --------------------- | ---------------------------------------------------------------- | | `txHashes` | Array of transaction hashes as strings | | `amount` | Bid amount in wei | | `blockNumber` | L1 block number targeted for bid inclusion | | `decayStartTimestamp` | Start timestamp for bid decay (in Unix milliseconds) | | `decayEndTimestamp` | End timestamp for bid decay (in Unix milliseconds) | | `revertingTxHashes` | Array of transaction hashes as strings that can revert | | `rawTransactions` | Array of raw signed transaction payloads | | `slashAmount` | Amount to be slashed from provider stake in case of a failed bid | | `bidOptions` | One or more of the available options | 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 theme={null} { "txHashes": ["0549fc7c57fffbdbfb2cf9d5e0de165fc68dadb5c27c42fdad0bdf506f4eacae", "0549fc7c57fffbdbfb2cf9d5e0de165fc68dadb5c27c42fdad0bdf506f4eacaf","0549fc7c57fffbdbfb2cf9d5e0de165fc68dadb5c27c42fdad0bdf506f4effff"], "amount": "100040", "blockNumber": 133459, "decayStartTimestamp": 1716935571901, "decayEndTimestamp": 1716935572901, "revertingTxHashes": ["22145ba31366d29a893ae3ffbc95c36c06e8819a289ac588594c9512d0a99810"] } ``` ```json Example bid with raw transaction payloads theme={null} { "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 theme={null} { "txHash":"0549fc7c57fffbdbfb2cf9d5e0de165fc68dadb5c27c42fdad0bdf506f4eacae,0549fc7c57fffbdbfb2cf9d5e0de165fc68dadb5c27c42fdad0bdf506f4eacaf,0549fc7c57fffbdbfb2cf9d5e0de165fc68dadb5c27c42fdad0bdf506f4effff", "bidAmount":277610, "revertingTxHashes":"22145ba31366d29a893ae3ffbc95c36c06e8819a289ac588594c9512d0a99810", "blockNumber":2703, "digest":"uU2p20f5KmehWqpuY1u+CbhcS8jNwdQAJQe2dh0Vnrk=", "signature":"nY6jYsGPxj6LVlSVQJbZcxvmRrw8Ym5rqOL1x0W/xPlJGBaF/ZzzjkxiioY/MDiRGvlflSWeoT0fh3aIJiJxAhw=", "decayStartTimestamp":1716935571901, "decayEndTimestamp": 1716935572901, "slashAmt":0, "rawTransactions":["0x02f8db82426882010c8410433624841043362f8303425094ea593b730d745fb5fe01b6d20e6603915252c6bf87016e03ce313800b864ce0b63ce0000000000000000000000000e94804eaa3c4c5355992086647f683f6f41ef1f000000000000000000000000000000000000000000000000000150e0786cc000000000000000000000000000000000000000000000000000000000000004e378c001a0ece6d13b20247abdc07d669c9186ee5a1ac9601db8c98a3323024ab299cb6662a01c20680efe4e0bb48a3a936b5ab27c741819f0ac567b12b34b230004b20b78a0"], "nikePublicKey": "04c631d017981efdc0c319b475de36389a10ede86fbbc9adcf573844a858ce8ddcddb41306eb9c34ec4ee9bc0234f7e30684bf389142437166d407e47974d5cbf7" } ``` ## Details on Bid Structure | Property | Description | | ------------------- | --------------------------------------------------------------------------------------------------------- | | txnHash | Array of transaction hashes represented as strings | | bidAmount | Amount to bid in wei | | blockNumber | L1 target block to have bid included | | decayStartTimestamp | Start timestamp for bid decay (in Unix milliseconds) | | decayEndTimestamp | End timestamp for bid decay (in Unix milliseconds) | | bidDigest | Hash of the bid | | bidSignature | Signed bidВigest = sign(bidDigest, signingKey) | | nikePublicKey | NIKE public key of the bidder, autogenerated for each bid | | revertingTxHashes | Array of transaction hashes as strings that can revert | | rawTransactions | Array of hexadecimal encoded raw signed transaction payloads | | slashAmount | Amount to be slashed from provider stake (and directly transferred to the bidder) in case of a failed bid | | bidOptions | Position constraints or other available options | ### 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](/v1.2.x/concepts/bids/bid-decay-mechanism). ### Details on BidOptions The `bidOptions` provides a way to put certain constraints on the transaction with respect to the block. Currently we have the position constraint option. This option allows users to configure the location of the transaction in the block. This could be an absolute index or percentile or gas percentile index of the block. ```proto theme={null} message PositionConstraint { option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_schema) = { json_schema: { title: "Position Constraint" description: "Constraint on the position of the transaction in the block." } }; enum Anchor { ANCHOR_UNSPECIFIED = 0; ANCHOR_TOP = 1; // Position is at the top of the block ANCHOR_BOTTOM = 2; // Position is at the bottom of the block } enum Basis { BASIS_UNSPECIFIED = 0; BASIS_PERCENTILE = 1; // Position is a percentile of the block size BASIS_ABSOLUTE = 2; // Position is an absolute position in the block BASIS_GAS_PERCENTILE = 3; // Position is a percentile of the gas used in the block } Anchor anchor = 1 [(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = { description: "Anchor position of the transaction in the block." }]; Basis basis = 2 [(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = { description: "Basis for the position constraint." }]; int32 value = 3 [(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = { description: "Value of the position constraint. If anchor is TOP, this is the position from the top of the block. If anchor is BOTTOM, this is the position from the bottom of the block." }]; }; ``` For example, ```json theme={null} { anchor: ANCHOR_TOP, basis: BASIS_PERCENTILE, value: 10 } ``` would let the provider know that this transaction or bundle has to be in the top 10% of the block. If we get a commitment and the transaction is not in the top 10%, the provider will be slashed. Multiple constraints can be combined, in which case the transaction needs to satisfy all of them. In case of transaction bundles, a set of constraints is considered satisfied if each constraint is satisfied by at least one transaction in the bundle. ### 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 theme={null} { "ciphertext": "5750d8af6296296f1147f5e11f47f253f376dea3fd5c2760cd82bd82a7066a8fe1c84f48a4e738d1df7c0e64f930c6b0b642800156e453a501c8b993951fcb50fe0b9fce4a2046838f499317a6018eb59abd5e84dbe3b7e296d4e0e70ef3bb221af7afe341908dbd02e8c91b4eff935b2697208f51ccacf5fe744c199afca687d85850a2e12a75433510dccda9258612348c586e971cc521486806ea25ec94d5fa7038beda3f532970e7b06198deef96677af3a6889c84d657585a9eefd224961f87a3353ad4ede4a7368e2e5bc9571d320a8a3be0f1e08e769f9bb2da6fb76c81cd" } ``` # Understanding Bidder Deposit Rules Source: https://docs.primev.xyz/v1.2.x/concepts/bids/bidder-deposit Bidders need to deposit funds to be able to place bids on the mev-commit network. As bids are posted privately, providers cannot determine how much bidders have bid to other providers for the relevant L1 block. To ensure that bidders can cover all their bids, we bind deposits to specific providers. Providers can thus ensure that bids from a given bidder do not exceed the amount deposited for them. It is important to note that if a bidder deposits, for example, 1 ETH for every provider, they can still only post bids totaling 1 ETH for a given block. This is because only a single provider can post the block to L1, meaning bids made to other providers will not be executed. Deposited funds can be withdrawn by the bidder at any time, after waiting the \~10 minute cooldown period. ## Deposit Manager It's recommended that bidders leverage the *deposit manager* to deposit, and automate ongoing re-deposits to specific providers. The deposit manager is an on-chain contract that a bidder account can enable by "setting their code" to the implementation using EIP-7702. After enabling the deposit manager, a bidder's deposits are automatically replenished from the bidder's EOA balance during the preconf settlement process, according to *target deposit* amounts configured by the bidder. A target deposit is the desired amount of funds that a bidder wants to be deposited for a specific provider. Bidders should set this to the maximum cumulative amount of ETH they would ever bid to a provider with respect to a single L1 block. # Reverting txns Source: https://docs.primev.xyz/v1.2.x/concepts/bids/reverting-txns ## Reverting Transactions Transactions are by default execution commitments when put in the bid payload. The `revertingTxHashes` field is used to describe transactions that you would like to allow to not need to be executed. When you include transaction hashes in the `revertingTxHashes` array, you are indicating that these transactions can be reverted if necessary. This can be useful in scenarios where certain transactions are optional or conditional, and their execution is not strictly required for the bid to be valid. Here is an example of how to include reverting transactions in your bid payload: ```json Example bid theme={null} { "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. # Commitments Source: https://docs.primev.xyz/v1.2.x/concepts/commitments Commitments represent promises made by providers in a cryptographically verifiable manner. | Key | Description | | --------------------------- | --------------------------------------------------------------------- | | `commitmentDigest` | Represents the hash of the bid structure, including the bid signature | | `commitmentSignature` | Represents an ECDSA signature of the `commitmentDigest` | | `commitmentProviderAddress` | Represents the address of the provider | | `sharedSecret` | Represents the shared secret between the bidder and provider | ```json Example commitment theme={null} { "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 theme={null} { "result":{ "commitment":"08a98d4c9d45f8431b46d99a23e6e8f82601ccf0773499d4e47bcd857cad92a6", "signature":"cfc1e4e2ea9cc417027ed5846fa073c8e6031f70f91ffa9b92051b5b7738c0500d8fefb0fc189bce16004b3c0e1c4cfa41260968161adf8b55446ed5c40d1ac51b", } } ``` # Fast Protocol Economics & Mev Distribution Model Source: https://docs.primev.xyz/v1.2.x/concepts/fast-protocol This document explains how **FAST RPC**, **mev-commit**, and the **Fast Protocol** collectively capture, route, and redistribute mev. It aims to give engineers, integrators, and validators a clear understanding of the value flows, incentive design, and equilibrium properties of the system. *** # Summary Fast Protocol transforms mev into a transparent, shared, incentive-aligned mechanism: * **Users** receive top-of-market mev refunds (≥90%, even >100%) * **Validators** earn strictly more when opting in, and materially more than in other OFA systems * **Builders** maintain sustainable margins while delivering transactions * **The protocol** becomes more valuable as usage increases, creating a positive feedback loop No competing OFA can sustainably provide higher user mev refunds than Fast Protocol. The design is mathematically constrained, incentive-compatible, and self-stabilizing under normal market conditions. ## Overview of Fast Protocol FAST RPC adds an **order flow auction (OFA)** on top of **mev-commit**. When users send transactions through FAST RPC: * The RPC auctions and simulates backruns * Mev is realized through backrun bundles * Builders commit via mev-commit * A portion of the mev goes to validators, depending on opt-in status * The rest flows into the **mev distribution contracts**, forming the basis of tokenized mev rewards The system ensures: * Users receive **≥90%** of the mev their transactions generate when feasible * Opted-in validators earn **significantly more** mev than non-opted-in validators * The protocol achieves a **unique equilibrium** where no competing OFA can sustainably pay users more *** # MEV Flow & Core Definitions ## MEV Components For each mev-commit bundle: $$ M_{bundle} = M_{bid} + M_{priority} + M_{direct} $$ Where: * $M_{bid}$ — the builder's decayed commitment * $M_{priority}$ — sum of transaction priority fees * $M_{direct}$ — any explicit builder payment We also define: * $M_{rpc}$ — total mev generated by FAST RPC transactions * $M_{block}$ — total mev in the block * $\rho = \dfrac{M_{rpc}}{M_{block}}$ — share of block mev attributable to FAST RPC * $\rho' = \dfrac{M_{bundle}}{M_{rpc}}$ — fraction of RPC mev appearing in bundles *** ## Fee Parameters FAST Protocol uses two fees: * **Mev fee on bundles:** $$ \text{mev\_fee} = f_{mev} \cdot M_{bundle} $$ * **Validator fee (opted-in only):** $$ \text{val\_fee} = f_{val} \cdot M_{block} $$ Typical values: | Parameter | Value | Meaning | | --------------- | ------ | --------------------------- | | $f_{mev}$ | 0.05 | 5% mev fee on bundles | | $f_{val}$ | 0.05 | 5% validator fee | | $\mu_{builder}$ | \~0.10 | Builder’s margin on RPC mev | *** # FAST RPC MEV Generation ## Per-Transaction MEV Estimation For each transaction $tx$: $$ m(tx) = \text{estimated backrun profit} $$ Total mev driven by FAST RPC in a given slot: $$ M_{rpc} = \sum_{tx} m(tx) $$ *** # MEV Redistribution Model Redistributed mev accumulates into a pool $T$ composed of: * Builder mev fees ($f_{mev} M_{bundle}$) * Validator fees ($f_{val} M_{block}$) * Backrun-captured mev from non-opt-in slots *** ## User Distribution Each user $u$ has a weight: $$ w_u = \frac{M_{rpc}^{(u)}}{M_{rpc}} $$ Their payout is: $$ P_u = T \cdot \tau_{rpc} \cdot w_u $$ Payout may be delivered in points or tokens depending on availability. *** # User Refund Ratio (γ) Define: $$ \gamma = \frac{T \cdot \tau_{rpc}}{M_{rpc}} $$ Interpretation: * $\gamma = 0.9$ → 90% mev refund * $\gamma > 1$ → users receive **more than 100%** of their generated mev System objectives: * Maintain $\gamma \ge 0.9$ under normal conditions * Allow $\gamma > 1$ in mev-rich phases (treasury surplus) *** # Adaptive Parameter Logic The protocol continuously adjusts how much mev goes to users versus the protocol treasury based on how abundant mev is in a given period. Let: $$ r = \frac{M_{rpc}}{T} $$ The protocol adapts how value is split between users and treasury based on mev abundance, summarized by the parameter $r$. *** ## Case 1 — Scarce MEV When mev relative to the redistribution pool is scarce (high $r$), the system caps what it can give back while preserving protocol sustainability. We can express the scarce regime as: $$ r > r_{\text{crit}} $$ for some critical $r_{\text{crit}}$ corresponding numerically to: * approximately $\dfrac{0.95}{0.9}$ in the original parameterization. In this regime: $$ \tau_{rpc} = \tau_{\text{max}} $$ $$ \tau_{fast} = 1 - \tau_{\text{max}} $$ with $\tau_{\text{max}}$ set so that users get as much as the system can afford (slightly under 90% refunds in the most constrained conditions). *** ## Case 2 — MEV Rich When mev is abundant relative to the pool, i.e. $$ r \le r_{\text{crit}}, $$ the protocol: * Preserves at least a 90% user refund on average * Allocates the surplus between users based on the share of mev they generate * Keeps a minimum fraction of value for the protocol We can express $\tau_{rpc}$ generically as: $$ \tau_{rpc} = a \cdot r + b \cdot (1 - r) $$ for suitable constants $a$ and $b$ chosen so that: * Users always receive at least 90% of their generated mev on average * The protocol receives at least 5% in total Then: $$ \tau_{fast} = 1 - \tau_{rpc} $$ In practice, parameter choices are tuned so that: * For typical orderflow conditions, $\gamma$ is around or above $0.9$ * In mev-rich conditions, $\gamma$ can exceed $1$, sharing surplus with users while still realizing value for protocol treasury This ensures: * Users always receive ≥90% * Protocol always receives ≥5% * Treasury surpluses enhance both sides proportionally *** ## Greater than 100% Refunds ("Casino Effect") Because the total value returned to RPC users ($T$) can include both: * **Immediate mev** generated in the current epoch * **Historical value** previously accumulated in the treasury and redistributed in later epochs it is possible for the effective refund rate ($\gamma$) to exceed 1. ### Interpretation * $M_{\text{rpc}}$ — total mev generated by a user's transactions in the epoch * $\tau_{\text{rpc}}$ — fraction of the distribution flow allocated to users * $T$ — total ETH distributed from the treasury to all users in the epoch When $\gamma > 1$, users receive **more than 100%** of the mev their transactions generated—an effect referred to as the **casino effect**. This arises naturally when prior epochs accumulated surplus mev in the treasury, allowing later epochs to over-refund users. *** # Validator Incentive Model FAST Protocol is designed so that **opting in is rational and strictly profitable** for validators. Opted-in validators gain: * All backrun-captured mev from FAST RPC bundles * Their share of traditional builder → validator mev * Competitive advantage in attracting order flow Non-opted-in validators receive only the small residual share left after RPC backruns and mev fees. *** ## Opt-in Profit Condition Incremental profit from opting in: $$ \Delta_{opt} = M_{rpc} \cdot (1 - \mu_{builder}) - f_{val} \cdot M_{block} $$ Opt-in is profitable if: $$ \rho > \frac{f_{val}}{1 - \mu_{builder}} $$ With typical values ($f_{val} = 0.05$, $\mu_{builder} = 0.10$): $$ \rho > 0.0555 $$ Meaning: **If Fast Protocol generates more than \~5.6% of block mev, opting in and even paying a 5% fee is profitable.** In practice, Fast Protocol exceeds this threshold comfortably. *** ## What Validators Earn | Validator Type | Approx. RPC mev Capture | Reason | | ---------------- | ----------------------- | ---------------------- | | **Opted-In** | \~95% | Backrun mev + residual | | **Not Opted-In** | \~5% | Similar to Mev Blocker | Opted-in validators therefore enjoy **\~20× higher mev capture** on FAST RPC flows. *** # Why FAST RPC Is the Best-Paying OFA The equilibrium analysis shows: * If FAST RPC offered **less** than 90% user refunds, users would defect to other options * If an OFA tried offering **more**, its builders or validators would become unprofitable * FAST RPC optimally balances incentives so validators, builders, the protocol, and users all remain profitable Thus, no competing OFA can sustainably provide higher user mev refunds than Fast Protocol. *** # Fast Swaps Fast Swaps is a swap interface built on top of Fast Protocol that lets users trade tokens on Ethereum mainnet while earning mev rewards. Swaps are backed by mev-commit preconfirmations, routed through the [FAST RPC](/v1.2.x/get-started/fastrpc), and settled via the **FastSettlement** smart contracts on L1. Start swapping and earning miles. Technical deep-dive: architecture, contracts, and EIP-712 signing. *** ### How It Works The swap flow follows a familiar DEX experience — select an input token, an output token, and an amount. Execution depends on the input token: | Input Token | Execution | | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | | **ERC-20** (e.g. USDC, DAI) | The user signs an off-chain EIP-712 intent. FAST RPC executes the swap via the FastSettlement contract — **no gas required from the user**. | | **ETH** | The user submits the transaction directly from their wallet via `executeWithETH`. | #### Permit2 ERC-20 swaps require a one-time [Permit2](https://docs.uniswap.org/contracts/permit2/overview) approval per input token. Once a token is approved, subsequent swaps with that token only require a signature. If Permit2 has already been approved for a given token on another application (such as Uniswap), no additional approval is needed. For a full explanation of the swap architecture, smart contracts, pricing mechanism, and security model, see the dedicated [Fast Swaps](/v1.2.x/concepts/fast-swaps) page. *** ### Fast Miles Users earn Fast Miles proportional to the mev their swaps generate through Fast Protocol. Miles are planned to be tokenized in the near future. Early users can also earn bonus miles through one-time tasks and referrals available in the app. *** ## Knowledge Base Simplified FAQ overview of Fast Protocol for newcomers. # Fast Swaps Source: https://docs.primev.xyz/v1.2.x/concepts/fast-swaps How Fast Swaps enables token swaps on Ethereum with mev reward redistribution Fast Swaps is a swap interface built on top of [Fast Protocol](/v1.2.x/concepts/fast-protocol) that lets users trade tokens on Ethereum mainnet while earning mev rewards. Unlike traditional DEX frontends where mev is extracted from traders, Fast Swaps routes swaps through the [FAST RPC](/v1.2.x/get-started/fastrpc) and settles them via the **FastSettlement** smart contracts, redistributing captured mev back to users as **Fast Miles**. Start swapping at fastprotocol.io *** # How Fast Swaps Works ## Overview When a user initiates a swap on Fast Swaps, the following happens: 1. The user selects tokens and enters an amount — a **solver auction** runs to find the best available price across liquidity sources 2. The user signs an **EIP-712 intent** (for ERC-20 tokens) or submits a direct transaction (for ETH) 3. [FAST RPC](/v1.2.x/get-started/fastrpc) picks up the signed intent and executes it through the **FastSettlement** contract on Ethereum 4. The winning solver routes the swap through the best available liquidity and the FastSettlement contract settles it on-chain 5. mev generated from the swap is captured by Fast Protocol and redistributed to the user as Fast Miles The swap flow is designed to feel like any familiar DEX — select tokens, enter an amount, review the quote, confirm. The key difference is the settlement layer: instead of the user submitting a swap transaction directly to a DEX router, Fast Swaps uses an intent-based architecture where FAST RPC executes the trade on the user's behalf via a competitive solver auction. *** ## Execution Paths Fast Swaps supports two execution paths depending on the input token: | Input Token | Path | User Action | Gas | | ---------------------------------- | ------- | --------------------------------- | ----------------------------- | | **ERC-20** (e.g., USDC, DAI, WBTC) | Permit2 | Sign an off-chain EIP-712 message | No gas required from the user | | **ETH** | Direct | Submit a transaction from wallet | User pays gas | ### ERC-20 Path (Permit2) For ERC-20 token swaps, Fast Swaps uses [Uniswap's Permit2](https://docs.uniswap.org/contracts/permit2/overview) contract to enable gasless, signature-based token transfers. The first time you swap a given ERC-20 token, you must approve the Permit2 contract to spend that token. This is a standard ERC-20 `approve` transaction. If you've already approved the token for Permit2 on another application (like Uniswap), no additional approval is needed. For each swap, you sign an off-chain EIP-712 typed data message. This message encodes a `PermitWitnessTransferFrom` that includes: * The **token permission** (which token and how much FAST RPC can transfer) * A **witness** containing your `Intent` struct (input/output tokens, amounts, recipient, deadline, nonce) No gas is required for this step — it is only a signature. FAST RPC receives your signed intent and calls `executeWithPermit` on the FastSettlement contract. The contract: 1. Verifies your Permit2 signature 2. Transfers your input tokens via Permit2 3. Routes the swap through the solver's chosen liquidity path 4. Sends the output tokens to your wallet 5. Returns any surplus to the protocol for mev redistribution ### ETH Path When swapping ETH as the input token, the user submits a transaction directly: The user signs and broadcasts a transaction that calls `executeWithETH` on the FastSettlement contract, sending ETH along with the call. The FastSettlement contract wraps the ETH to WETH if needed, executes the swap through the DEX route, and sends the output tokens to the user's wallet. In both paths, the transaction is routed through FAST RPC, which enables mev-commit preconfirmations and mev capture. *** ## Pricing & Quoting Fast Swaps uses a **solver auction** to find the best price for each swap. When a user enters a swap amount, the system: 1. **Runs a competitive solver auction** — Multiple solvers compete to offer the best execution price across available liquidity sources. The winning solver's quote is presented to the user. 2. **Estimates gas costs** — Each quote includes a gas estimate so the user can see the total cost of the swap. 3. **Calculates price impact** — The difference between the quoted price and the mid-market price is displayed to the user. Price impact severity is color-coded: * **Green** — Less than 0.1% (negligible) * **Yellow** — 0.1% to 1% (moderate) * **Red** — Greater than 1% (significant) 4. **Refreshes every 15 seconds** — Quotes have a 15-second validity window. A countdown timer in the UI shows when the next refresh will occur. Users can also manually refresh at any time. ### Slippage Protection Users can configure max slippage to protect against price movement between quoting and execution. The default is 0.5%, and users can set a custom percentage via the settings gear icon. The max slippage is encoded into the `userAmtOut` (minimum output amount) field of the swap intent. If the swap would result in less than this minimum, the transaction reverts. ### Swap Deadline Each swap intent includes a deadline timestamp. If FAST RPC does not execute the swap before this deadline, the intent expires and cannot be executed. The default deadline is 30 minutes. *** ## Smart Contracts Fast Swaps is powered by smart contracts deployed on **Ethereum L1** (Chain ID: 1). ### FastSettlement V3 The core settlement contract that executes swaps on behalf of users. | Property | Value | | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | | **Contract** | FastSettlementV3 (Upgradeable Proxy) | | **Network** | Ethereum Mainnet (Chain ID: 1) | | **Proxy Address** | [`0x084C0EC7f5C0585195c1c713ED9f06272F48cB45`](https://etherscan.io/address/0x084C0EC7f5C0585195c1c713ED9f06272F48cB45#code) | | **Implementation Address** | [`0x9bc916d7cf71ac34e3d407d8ed8838071a3b6ebf`](https://etherscan.io/address/0x9bc916d7cf71ac34e3d407d8ed8838071a3b6ebf#code) | | **Source** | [GitHub](https://github.com/primev/mev-commit) | #### Functions **`executeWithETH(intent, swapData)`** Executes a swap where ETH is the input token. The user sends ETH with the transaction. ```solidity theme={null} function executeWithETH( Intent calldata intent, SwapCall calldata swapData ) external payable returns (uint256 received, uint256 surplus); ``` **`executeWithPermit(intent, signature, swapData)`** Executes a swap where an ERC-20 token is the input. FAST RPC provides the user's Permit2 signature. ```solidity theme={null} function executeWithPermit( Intent calldata intent, bytes calldata signature, SwapCall calldata swapData ) external returns (uint256 received, uint256 surplus); ``` #### Data Structures **Intent** — Encodes the user's swap parameters: ```solidity theme={null} struct Intent { address user; // The user initiating the swap address inputToken; // Token being sold address outputToken; // Token being bought uint256 inputAmt; // Amount of input token uint256 userAmtOut; // Minimum output amount (slippage protection) address recipient; // Address receiving the output tokens uint256 deadline; // Unix timestamp after which the intent expires uint256 nonce; // Permit2 nonce (prevents replay) } ``` **SwapCall** — Encodes the DEX routing data: ```solidity theme={null} struct SwapCall { address to; // Target DEX router contract uint256 value; // ETH value to send (if applicable) bytes data; // Encoded swap calldata for the router } ``` ### Permit2 Fast Swaps uses Uniswap's canonical [Permit2](https://docs.uniswap.org/contracts/permit2/overview) contract for gasless ERC-20 approvals. | Property | Value | | ------------ | -------------------------------------------- | | **Contract** | Permit2 | | **Network** | Ethereum Mainnet | | **Address** | `0x000000000022D473030F116dDEE9F6B43aC78BA3` | | **Source** | [GitHub](https://github.com/Uniswap/permit2) | Permit2 allows users to approve a token once and then sign off-chain messages (EIP-712) for subsequent transfers. This eliminates the need for per-swap on-chain approval transactions. *** ## EIP-712 Signing For ERC-20 swaps, Fast Swaps constructs an EIP-712 typed data message that combines a Permit2 transfer with a swap intent witness. The signing domain is: ```json theme={null} { "name": "Permit2", "chainId": 1, "verifyingContract": "0x000000000022D473030F116dDEE9F6B43aC78BA3" } ``` The typed data includes: * **PermitWitnessTransferFrom** — Standard Permit2 transfer with an additional witness field * **TokenPermissions** — Specifies which token and amount FAST RPC can transfer * **Intent** (witness) — The full swap parameters that the FastSettlement contract will verify on-chain This design ensures FAST RPC can only execute the exact swap the user intended. The signature covers both the token transfer authorization and the swap parameters, preventing any modification of the swap terms after signing. *** ## Third-Party Integration Wallets and dApps can integrate Fast Swaps directly via the FAST RPC HTTP API. Instead of building a full swap UI, you call two endpoints to get quotes and execute swaps on behalf of your users — with mev redistribution, preconfirmations, and gasless ERC-20 swaps included out of the box. **Base URL:** `https://fastrpc.mev-commit.xyz` ### ERC-20 Swaps (Gasless) For ERC-20 token swaps, users sign an off-chain EIP-712 Permit2 message and the FAST RPC executor submits the transaction on their behalf. The user pays no gas. **Prerequisites:** 1. The user must have approved the [Permit2](https://docs.uniswap.org/contracts/permit2/overview) contract (`0x000000000022D473030F116dDEE9F6B43aC78BA3`) to spend the input token (one-time per token) 2. Your app must construct and have the user sign an EIP-712 `PermitWitnessTransferFrom` message that includes the swap `Intent` as a witness (see [EIP-712 Signing](#eip-712-signing) above for the full typed data structure) #### `POST /fastswap` **Request:** ```json theme={null} { "user": "0x...", // User's wallet address "inputToken": "0x...", // ERC-20 token being sold "outputToken": "0x...", // Token being bought "inputAmt": "1000000", // Amount in wei (string) "userAmtOut": "950000", // Minimum output amount — slippage protection (string) "recipient": "0x...", // Address to receive output tokens "deadline": "1700000000", // Unix timestamp — intent expires after this (string) "nonce": "0", // Permit2 nonce (string) "signature": "0x...", // EIP-712 Permit2 signature (hex) "slippage": "0.5" // Optional: slippage % (default 0.5%) } ``` **Response:** ```json theme={null} { "txHash": "0x...", // Transaction hash "outputAmount": "955000", // Expected output amount "gasLimit": 350000, // Gas limit used "status": "success", // "success" or "error" "error": "" // Error details if status is "error" } ``` ### ETH Swaps (User-Submitted) For native ETH swaps, the API returns unsigned transaction data that the user signs and submits themselves. The user pays gas. #### `POST /fastswap/eth` **Request:** ```json theme={null} { "outputToken": "0x...", // ERC-20 token to receive "inputAmt": "1000000000000000000", // ETH amount in wei (string) "userAmtOut": "950000", // Minimum output amount (string) "sender": "0x...", // User's wallet address "deadline": "1700000000", // Unix timestamp (string) "slippage": "0.5" // Optional: slippage % (default 0.5%) } ``` **Response:** ```json theme={null} { "to": "0x084C0EC7f5C0585195c1c713ED9f06272F48cB45", // FastSettlement contract "data": "0x...", // Hex-encoded calldata "value": "1000000000000000000", // ETH to send (matches inputAmt) "chainId": 1, // Ethereum mainnet "gasLimit": 400000, // Estimated gas limit "status": "success", "error": "" } ``` The user should construct a transaction from this response, sign it, and broadcast it to the network. ### Integration Flow **ERC-20 path** — gasless, executor-submitted: ```mermaid theme={null} sequenceDiagram participant App as Your App participant RPC as FAST RPC participant L1 as Ethereum L1 App->>RPC: POST /fastswap (intent + Permit2 signature) RPC->>L1: Executor submits tx (preconfirmed) RPC-->>App: txHash + outputAmount L1-->>App: Output tokens sent to recipient ``` **ETH path** — user-submitted: ```mermaid theme={null} sequenceDiagram participant App as Your App participant RPC as FAST RPC participant L1 as Ethereum L1 App->>RPC: POST /fastswap/eth (swap params) RPC-->>App: Unsigned tx data (to, data, value, gasLimit) App->>L1: User signs & submits tx L1-->>App: Output tokens sent to user ``` For the ETH path, the user submits the transaction themselves. To get a preconfirmation, the signed transaction should be submitted through FAST RPC via `eth_sendRawTransaction` rather than a standard Ethereum RPC. See [FAST RPC Usage](/v1.2.x/get-started/fastrpc) for setup details. ### Error Handling Both endpoints return structured errors: * **HTTP 400** — Invalid request (missing fields, malformed addresses, invalid amounts) * **HTTP 405** — Wrong HTTP method (only POST is accepted) * **HTTP 500** — Internal error (Barter API failure, transaction building failure) When `status` is `"error"`, the `error` field contains a description of what went wrong. Common errors include: * `"barter minReturn (...) < user required (...)"` — The best available price doesn't meet the user's minimum output. Suggest the user increase slippage or reduce the swap amount. * `"executor dependencies not configured"` — Path 1 (ERC-20) is not enabled on this RPC instance. *** ## Supported Tokens Fast Swaps supports over **2,400 ERC-20 tokens** on Ethereum mainnet. Any token with on-chain liquidity can be traded. The token list includes: * **Major tokens**: ETH, WETH, USDC, USDT, DAI, WBTC * **DeFi tokens**: UNI, AAVE, LINK, MKR, SNX, COMP * **Meme tokens**: PEPE, SHIB, DOGE (wrapped) * **Custom tokens**: Users can add any ERC-20 token by entering its contract address Always verify the contract address when adding custom tokens. Fast Swaps does not verify the legitimacy of user-added tokens. *** ## Fast Miles Users earn **Fast Miles** proportional to the mev their swaps generate through Fast Protocol. The mev distribution model is detailed in the [Fast Protocol Economics](/v1.2.x/concepts/fast-protocol) page. Key points: * Users receive **at least 90%** of the mev their transactions generate under normal conditions * Fast Miles are tracked in the Fast Swaps dashboard and leaderboard * Miles are planned to be tokenized — early users accumulate before the official points system launches * Bonus miles are available through referrals and one-time tasks in the app For a full explanation of mev distribution, fee parameters, and the adaptive parameter model, see [Fast Protocol](/v1.2.x/concepts/fast-protocol). *** ## Architecture Diagram The following shows how a swap flows through the Fast Swaps system: ```mermaid theme={null} sequenceDiagram participant User participant App as Fast Swaps App participant RPC as FAST RPC participant L1 as Ethereum L1 User->>App: 1. Select tokens & enter amount App->>RPC: 2. Request quote RPC-->>App: Solver auction runs, best price returned User->>App: 3. Review quote & confirm User->>App: 4. Sign EIP-712 intent (wallet) App->>RPC: 5. Submit signed intent RPC->>L1: 6. Execute via FastSettlement L1-->>RPC: 7. Swap settles, output tokens to user, surplus captured for mev RPC-->>App: Tx preconfirmed App-->>User: 8. Preconfirmation + Fast Miles earned ``` *** ## Comparison with Traditional DEX Frontends | Feature | Traditional DEX (e.g., Uniswap App) | Fast Swaps | | -------------------------- | -------------------------------------------------------------- | ----------------------------------------------------------------------------- | | **Token selection** | User selects tokens | User selects tokens | | **Pricing** | DEX router quote | Solver auction across liquidity sources | | **Transaction submission** | User submits directly to public mempool | Intent signed off-chain, FAST RPC executes | | **mev exposure** | User's swap is visible in mempool; bots can front-run/sandwich | Swap routed through FAST RPC; mev is captured and redistributed | | **mev rewards** | None | User earns Fast Miles proportional to mev generated | | **Gas for ERC-20 swaps** | User pays gas | FAST RPC pays gas (gasless for user) | | **Settlement** | Direct DEX router call | FastSettlement contract with surplus capture | | **Preconfirmations** | None | Transaction preconfirmed by Ethereum block builders on the mev-commit network | *** ## Security Considerations * **Intent signing is non-custodial.** The user's wallet signs an EIP-712 message authorizing a specific swap with specific parameters. FAST RPC cannot modify the intent (tokens, amounts, recipient, deadline) after signing. * **Permit2 nonces prevent replay.** Each signed intent uses a unique nonce from the Permit2 nonce bitmap. A used nonce cannot be reused. * **Deadline enforcement.** Intents expire after the user-specified deadline. Stale intents cannot be executed. * **Minimum output protection.** The `userAmtOut` field ensures the user receives at least the expected amount minus slippage tolerance. If the swap would produce less, the transaction reverts. * **Smart contract audits.** The FastSettlement contracts are [open source](https://github.com/primev/mev-commit) and subject to security review. *** ## Quick Start Quick FAQ for first-time users. Step-by-step guide to performing your first swap. # Bridging Details Source: https://docs.primev.xyz/v1.2.x/concepts/mev-commit-chain/bridging-details # Understanding Bridging Mechanisms The mev-commit chain utilizes a standard bridging mechanism to ensure a secure and efficient transfer of ETH between mainnet Ethereum and the mev-commit chain. We envision mev-commit to eventually integrate with a multitude of interoperability protocols (think wormhole, layerzero, etc.). In the meantime Primev has implemented its own lock/mint bridging protocol as described below. ## Lock/Mint Peg Native ETH on the mev-commit chain maintains a 1:1 peg with ETH on L1. The only way to mint ETH on the mev-commit chain is to lock an equivalent amount on L1. ETH can be burned on the mev-commit chain to release/receive an equivalent amount on L1. ## Security There are inherent security assumptions in bridging ETH to the mev-commit chain. While these are similar to other bridge trust assumptions, we've listed them below: * Liveness of the bridge relayer actor. * POA signers that maintain mev-commit chain state. * Correctness of Primev's [standard bridge protocol](https://github.com/primev/mev-commit-bridge/tree/main/standard/bridge-v1) and integration into the mev-commit chain. Our standard bridge implementation has been audited by Cantina. More details can be found [here](https://blog.primev.xyz/Battle-Testing-mev-commit-Key-Findings-from-Our-Spearbit-Security-Review-1436865efd6f8025bd6ce3824349821d). ## **Importance of Origin Chain Security** **Selective Bridging**: Only bridges originating from Ethereum L1 should be allowed to mint native ETH on the mev-commit chain. This is to prevent the impact of compromised states on other chains affecting the mev-commit chain. ## Bridge Contracts See **Bridge Contracts** section of [contracts page](/v1.2.x/developers/contracts) to gain context on contracts necessary to enable bridging. ## Relayer The main off-chain component of the bridge is the relayer. Primev currently operates the relayer, with open-sourced implementation [here](https://github.com/primev/mev-commit/tree/main/bridge/standard). # Chain Details Source: https://docs.primev.xyz/v1.2.x/concepts/mev-commit-chain/chain-details The mev-commit chain is live on [mainnet](/v1.2.x/developers/mainnet). To test and experiment, join the testnet and get familiar with its functionalities at the [testnet](/v1.2.x/developers/testnet) section. ## Design Mev-commit chain is currently built out as an Ethereum sidechain run with [go-ethereum’s Clique proof-of-authority consensus mechanism](https://geth.ethereum.org/docs/tools/clef/clique-signing). It's not a generalized chain for everyone to launch dapps on, but only for specific execution service applications, such as preconfirmations, top of block, bottom of block, or other services. Source code for the geth fork which runs the mev-commit chain can be found in the [mev-commit-geth repo](https://github.com/primev/mev-commit-geth). ## Progressive decentralization Today, most or arguably all Ethereum scaling solutions rely on centralized bridging and sequencing. Mev-commit components rely on existing tech, and consequently inherit this property. However anyone can permissionlessly validate correct execution, and operation of chain infrastructure. Moreover, because the mev-commit p2p network is decentralized and commitments are cryptographic, actors can theoretically settle commitments without the mev-commit chain. At this point of the network's inception, Primev entities will run all validating infrastructure for the mev-commit chain. Correct and honest operation can be permissionlessly audited by spinning up a full node and connecting to the mev-commit chain as a peer. Over time we plan to have entities outside of Primev to become POA signers or bridge validators to progressively decentralize the centralized components of the system. The mev-commit chain will continue to evolve. We have ongoing research into consensus algorithms we can employ to decentralize the mev-commit chain without compromising on speed. Open source scaling solutions that prove to be practical, decentralized, and meet security thresholds will be considered to decentralize the mev-commit chain. ## POA geth nodes Primev currently maintains a mev-commit-geth bootnode which doesn’t participate in consensus, and a set of full-node POA signers that run consensus. These signers take turns proposing the next block by utilizing a waiting period. The current target block period is 200ms, meaning about 60 mev-commit chain blocks will be committed for every Ethereum mainnet block. The block time will likely change as enhancements are added and chain state grows. ## Fee Mechanism **Non-inflationary**: The fee mechanism on the mev-commit chain is non-inflationary, maintaining a strict 1:1 peg between sidechain ether and L1 escrowed ether. This is achieved through a variation of EIP-1559, where both the base and priority fee accumulate to a treasury account (preconf.eth address). ## Smart Contracts Smart Contracts are deployed on the mev-commit chain to enable use cases, follow bid and commitment states, and invoke rewards or slashing as needed. Anyone can deploy contracts on the mev-commit chain, however there'll be additional integration work needed with mev-commit off-chain components to fully enable the use case under the current design. Thus we first recommend getting in touch with the Primev team to enable a use case at this stage of the network. Currently deployed contracts are designed as follows: * A preconfirmation contract allows preconfirmation commitments to be stored and tracked on-chain. * Two separate registry contracts exist to manage bidders and providers, both parties must stake ETH to participate. Rewards and/or slashing are managed by these contracts. * An oracle contract receives L1 payloads from the oracle service. It currently operates by checking confirmed mainnet blocks. * An block tracker contract which designed to track Ethereum blocks and their respective winners. ## Oracle service The oracle service is an off-chain process that interacts with the oracle contract as needed. This service monitors and extracts the winning builder and corresponding transaction hash list from each L1 block, and submits this data to the oracle contract residing on the mev-commit chain. This is a centralized oracle currently operated by Primev. We're actively looking into decentralizing the oracle role through existing decentralized Oracle protocols and evaluating creating a service where this can be decentralized. # Differences Between Ethereum and mev-commit Chain Source: https://docs.primev.xyz/v1.2.x/concepts/mev-commit-chain/differences-between-ethereum-and-mev-commit-chain ## Introduction Mev-commit chain is an Ethereum-compatible blockchain designed to provide faster transaction processing and lower fees. It aims to optimize the extraction of Maximal Extractable Value (mev) by utilizing a specialized architecture. This document highlights the key differences between Ethereum and mev-commit chain. ## Overview The following table provides an overview of the key features and differences between Ethereum and mev-commit chain: | Feature | Ethereum | Mev-Commit Chain | | ---------------- | ------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- | | Mempool | Larger mempool size | Smaller mempool size, transactions may be encrypted, limited chain mempool visibility due to fewer chain node operators | | Validators | Decentralized proof of stake system with a large number of validators | Centralized setup with only two validator nodes creating blocks in a round-robin fashion, allowing for faster consensus and block production | | Opcodes | Supports Ethereum opcodes | Supports all Ethereum opcodes, ensuring compatibility with existing Ethereum smart contracts and tools | | Consensus | Uses proof of stake consensus, prioritizing decentralization | Uses clique proof of authority consensus, where authorized validators take turns creating blocks, prioritizing performance and fast block times | | Block time | 12 seconds | 200 milliseconds | | Transaction Fees | Supports both legacy and EIP-1559 transactions, with base fee being burned and priority fee going to the proposer/signer | Supports both legacy and EIP-1559 transactions, with base fee directed to the protocol treasury and priority fee going to the proposer/signer | ### Transaction Fees Like Ethereum, mev-commit chain supports both legacy and EIP-1559 transactions, with a preference for EIP-1559. The allocation of fees differs: * The base fee is directed to the protocol treasury, instead of being burned. * The priority fee goes to the proposer/signer, as in Ethereum. ### Mempool Mev-commit chain's mempool is smaller compared to Ethereum's. While the mempool is public, transactions may be encrypted, and chain mempool visibility is limited due to the presence of only a few chain node operators. This reduces the potential for front-running and other mev-related activities. ### Number of Validators Mev-commit chain currently operates with only two validator nodes that create blocks in a round-robin fashion. This centralized setup allows for faster consensus and block production. However, it also introduces a higher level of trust in the validators compared to Ethereum's decentralized proof of stake system. ### Opcodes Mev-commit chain supports all Ethereum opcodes, as it consists of Ethereum nodes. Opcodes are low-level instructions that define the operations a blockchain can perform. By supporting all Ethereum opcodes, mev-commit chain ensures compatibility with existing Ethereum smart contracts and tools. ### Consensus Mainnet Ethereum uses proof of stake, while mev-commit chain currently uses clique proof of authority consensus. In clique proof of authority, a set of authorized validators take turns creating blocks. This consensus mechanism prioritizes performance and fast block times over decentralization. ## Conclusion Mev-commit chain offers a specialized blockchain environment optimized for mev extraction. With faster block times, a different fee structure, and a centralized validator setup, mev-commit chain provides an alternative to Ethereum for use cases that prioritize speed and mev optimization. # Actors Source: https://docs.primev.xyz/v1.2.x/concepts/mev-commit-intro/actors Network actors’ roles are defined based on their interactions with other ecosystem actors. A diagram below depicts a given mev actor’s relative placement compared to others. A list of potential Actors on the mev-commit network are listed below: ### **Providers:** Providers of execution services include but are not limited to: * **Block Builders**: They curate and order transactions in blocks, and have their own private mempool, giving them an advantage in committing to transaction inclusion or making related decisions. * **Relays**: Relays are trusted actors that accept block bids from block builders and make them available to proposers, also relaying the block payload when requested. Due to their fundamental role in the mev pipeline, they can also act as guardians of proposer preferences for blocks and provide execution services. * **Rollup Sequencers**: They're practically block builders for the L2 ecosystem, curating and ordering transactions for the L2 rollups. * **Miners and Mining Pools**: In PoW systems such as Bitcoin, miners and mining pools can provide execution services as they mine the blocks that contain transactions. #### Rules for Providers To participate in the mev-commit network, providers must adhere to the following requirements: * **Node Availability:** Providers must operate a mev-commit provider node continuously, ensuring high availability and reliability. * **Consistent Commitment:** Providers must be willing to commit to profitable bids for all available slots. * **Builder Activity:** The associated builder must have consistently produced at least 0.5% of recent mev-boost blocks to demonstrate meaningful network contribution. Failure to comply with the above requirements may result in removal from the mev-commit network. ### **Bidders** Bidders are users of execution services, bidding for inclusion of their transactions, for some specific preference to be adhered to by providers, and more. Bidders include but are not limited to: * **Searchers**: Searchers of mev opportunities are in prime position to bid for execution services as they may have specific preferences or time constraints that maximize the profitability of their strategies. * [**Solvers**](/v1.2.x/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. # Understanding mev-commit Source: https://docs.primev.xyz/v1.2.x/concepts/mev-commit-intro/network-overview ### Overview Mev-commit is designed as an out of protocol layer to systems like mev-boost, facilitating the exchange of execution bids and commitments between mev actors, solving for coordination inefficiencies. This design ensures that only necessary parts of this faciliation happen on mev-commit (bids, commitments, settlement) and not the transaction flow itself. This design achieves chain abstraction by its nature, as any transaction hash on any chain can be referred to in a mev-commit bid, and be paid in eth. Bids and commitments on mev-commit also do not rely on blockchain bottlenecks and are real-time. ### Bids and Commitments Bids are received and evaluated by providers, who run decisioning logic in their own environment and may decide to issue a cryptographic commitment against whatever the bid is for. In the preconfirmation case, the minimum a commitment can be made is for inclusion of the referred transaction hash(es) in the bid on the target L1 block number specified. ### Settling Commitments Commitments are simultaneously sent to bidders and the mev-commit chain in hash format. This ensures the network can operate with end-to-end pre-execution privacy and low latency. Once the commitment is revealed by either of the participating parties at the end of a slot, an oracle will check the target L1 block number as it gets confirmed to see if the commitment is delivered. If so, the bid amount will be rewarded to the provider. If not, the provider stake will be slashed. ### Rewards and Slashing *Only the actors who participated in the block's confirmation are considered for rewards or slashing.* This means if Block Builder A and Block Builder B commit to a bid and the target block is built by Block Builder A, the oracle will reward or slash Block Builder A. ### Network Architechture The architecture of the mev-commit peer-to-peer (P2P) network is designed to support instantaneous communication among network participants. The diagram below depicts how mev-commit acts as a layer on bidder and provider operations, that are external to the mev-commit network by its nature: ### Network Connectivity The network is structured to ensure robust connectivity among users and providers. Each participant node connects to a primary network node, known as a bootnode, during the initial startup phase, establishing a foundational network link. ### Gateway Nodes The subsequent diagram provides a detailed representation of the bid, commitment, and fund flows within the mev-commit framework, showcasing the efficiency and effectiveness of interactions among mev actors. # Oracle Source: https://docs.primev.xyz/v1.2.x/concepts/mev-commit-intro/oracle **The primary role of the oracle is to ensure that the provider carries through on their commitments.** The oracle consists of two parts: * A smart contract component [here](https://github.com/primev/mev-commit/blob/main/contracts/contracts/core/Oracle.sol). * A microservice [here](https://github.com/primev/mev-commit/tree/main/oracle). The oracle automates the verification of provider commitments and queries the L1 data source for transaction hashes and block extra data. It then cross-references these with commitments logged in the commitments contract, and then verifies adherence using the oracle contract. If a commitment is satisfied, the oracle contract triggers a reward to the provider using the bidder contract; if not, it slashes the provider by interacting with the provider contract. ## Prior to Oracle Engagement Before the oracle can be engaged according to the protocol's intended sequence of events, several preliminary actions must be taken: **1a.** Simultaneously, the bidder issues an encrypted bid via the mev-commit peer-to-peer network. *After the bidder's actions, the provider proceeds to:* **2a.** Retrieve the encrypted bid from the mev-commit network. **2b.** Issue an encrypted commitment for the transaction mentioned in the bid. ## Oracle Happy Path Flow When a bid for a transaction (txnj) is circulated through the mev-commit p2p network, and the provider has made an encrypted commitment and then opened it after the L1 block was created, the oracle is activated to verify whether the provider has honored this commitment. The process is as follows: 1. The provider assembles the complete L1 block, incorporating txnj, to which it previously committed. **Note: If the provider doesn’t get selected to construct the L1 block, the oracle flow does not get triggered.** 2. The oracle microservice fetches the block from the L1 chain and verifies the presence of txnj. 3. Upon confirmation that txnj is included, the microservice notifies the oracle smart contract of the commitment's fulfillment. 4. The oracle smart contract then initiates the transfer of funds from the bidder's deposited balance to the provider's account. ## Oracle Slashing Path In the event that a provider fails to include a committed transaction (txnj) in the L1 block, the oracle slashing path is initiated to penalize the provider for the breach of commitment. This process is outlined below: 1. The provider is expected to produce an L1 block that includes the committed transaction (txnj). However, if the provider does not include txnj, the protocol moves to the slashing phase. 2. The oracle microservice retrieves the block from the L1 chain and searches for txnj. If the transaction is not found, it triggers the next step. 3. The oracle communicates that txnj was not seen in the oracle contract. 4. The oracle contract, upon receiving this information, initiates the slashing procedure. This involves penalizing the provider by triggering a slash event, which results in the forfeiture of the stake held by the provider contract as a guarantee of honest behavior. 5. The confiscated stake is subsequently allocated to the bidder as compensation for the provider's failure to include the committed transaction, thereby ensuring that the bidder is recompensed for the provider's breach of trust. # What is mev-commit? Source: https://docs.primev.xyz/v1.2.x/concepts/mev-commit-intro/what-is-mev-commit Mev-commit is a peer-to-peer (P2P) networking platform designed to facilitate real-time interactions and coordination between mev actors and execution providers. It provides a robust network for exchanging execution bids and cryptographic commitments, which are used to specify execution requirements in detail and to receive credible commitments that act as promises to fulfill bid requirements. Mev-commit allows actors to engage in “fast games” such as preconfirmations through real-time cryptographic commitments and settles results using a high throughput blockchain for permissionless access. ## What are Bids? Within mev-commit, bids act as the foundational requests placed by bidders, signaling their need for specific transaction execution services. This process occurs within a peer-to-peer networking setup to streamline direct negotiations with execution service providers like block builders and rollup sequencers. Each bid, marked by the unique identifier of a transaction hash, enables a straightforward mechanism for providers across the network to recognize and respond to these requests. Bids essentially convey a user's readiness to pay a certain fee for the execution of their transaction, proposing a price designed to motivate execution providers to give priority to their transaction. ## What are Commitments? Commitments within mev-commit represent the execution providers' affirmative responses to bids, confirming their agreement to execute the specified transactions at the proposed prices within designated blocks. These commitments are conveyed through cryptographic proofs or digital signatures, signifying the providers' acceptance of a bid. Commitments serve as the critical link that aligns the supply and demand dynamics of the network, facilitating an effective and streamlined process for transaction execution. ## Actors Network actors' roles are defined based on their interactions with other ecosystem actors. The diagram below depicts a given mev actor's relative placement compared to others: For example, a Searcher can be a bidder for a Sequencer, but that same Sequencer can be a bidder for a block builder. Thus, it's best to think of actors' roles in mev-commit as similar to their roles in the mev pipeline. To the left of the diagram are bidders, and to the right of the diagram are execution providers who can issue commitments against these bids. Under the Proposer Builder Separation (PBS) model, information only moves to the right among actors in the mev pipeline. With mev-commit, credible commitments for execution and bits of information flow from providers back to bidders, enabling them to effectively utilize block space. This two-way exchange of information and commitments within the mev-commit system enhances the dynamic utilization and management of block space, supporting a more interactive and responsive ecosystem. ### **Providers** Providers in the mev ecosystem include **Block Builders, Relays, Rollup Sequencers, and even Solvers**. They are crucial for the delivery of commitments through their role in the respective ecosystem or their sophistication. These providers receive bids and deliver transaction inclusion and execution, ensuring the efficient and effective use of block space. ### **Bidders** Bidders consist of **Searchers, Solvers, Blob Producers, AA Bundlers, Wallets, and even End Users**. They bid for execution services, aiming to optimize their transactions within the block space. Their activities are fundamental to maintaining a competitive and efficient environment within the mev pipeline, facilitating a dynamic market for block space utilization. For a detailed look at these roles and their interactions, please visit the [Actors](/v1.2.x/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) # Security & Privacy Source: https://docs.primev.xyz/v1.2.x/concepts/privacy If bids and transaction bundles were transmitted in clear text over the peer-to-peer (P2P) network, it could allow competing bidders and providers to observe and adjust their strategies based on the visible bids. This visibility potentially harms the expected utility of bidders, as their competitors could outbid them by adjusting their bids accordingly. Moreover, the premature revelation of a provider’s commitment to a bid could lead to information leakage about the total value of the block being constructed. This would not only affect the privacy of the providers but also skews the competitive landscape, enabling providers to underbid based on the leaked value information. To counteract these privacy issues mev-commit provides end-to-end privacy for all bids and commitments in the sense that until commitments are opened after the corresponding L1 block has been confirmed, the contents of the commitment and the corresponding bid are only visible to the bidder who made the bid and the provider who made the commitment. All other bidders and providers and external parties learn nothing except that this provider has made a commitment. Moreover, it is crucial that commitments to bids are binding to the specific bid, i.e., that the commitment can only be opened for that single bid. Since bidders and providers can have conflicting incentives, it is important that they can both open the commitments, which is guaranteed using zero-knowledge proofs. The security and privacy of mev-commit is achieved by combining two novel cryptographic primitives, anonymous receiver-updatable broadcast encryption (ARUBE), and dual-phase commitments (DPCOM), with a highly efficient ZK proof. ARUBE is used to efficiently disseminate bids from bidders to providers of their choice in a privacy-preserving manner, DPCOM is used to securely commit to those bids and later allow for the opening of such commitments, and a ZK proof is used to ensure that commitments can be opened by providers and bidders. Below we expand on the specific security and privacy notions achieved for the bidders and the providers along with a short description of the corresponding cryptographic primitive used for each. ### Signature Schemes We implement ECDSA (Elliptic Curve Digital Signature Algorithm) keys for our signature process. Additionally, our messages are formatted using EIP-712 standards, enhancing human readability and structured data representation. The ECDSA framework enables the recovery of both the public key and the signer's address through the ECRecover function, which are native to Geth. ### Hashing Our system employs keccak256 (SHA-3) for hashing, aligning with EVM standards for optimal interoperability. This is useful for interoperability with the EVM, as it natively supports keccak256 through pre-compiles, both on L1 Ethereum and our mev-commit chain. ## Posting Bids Each bidder can choose a group of providers who will have access to their bids. The bids are then encrypted and sent to this specific group of providers. Other bidders and providers remain unaware of the details of a bid and its designated receivers. The cryptographic primitve that mev-commit leverages to achieve this privacy notion in an efficient way is called ARUBE. ### Anonymous Receiver-Updatable Broadcast Encryption (ARUBE) ARUBE is the primitive that allows bidders in the mev-commit protocol to privately send bids to a subset of the providers without revealing what this subset is. This functionality is commonly provided by anonymous broadcast encryption [\[BBW06\]](https://www.cs.utexas.edu/~bwaters/publications/papers/privatebe.pdf). A feature of broadcast encryption is that a new set of recipients can be specified for each message that is encrypted. In commitment games, the set of recipients for a given bidder typically remains stable since bidders mostly send their bids to the set of providers they work with and occasionally add or remove a provider from that set. To be able to leverage this for more efficient schemes, we refine the notion of broadcast encryption by adding an algorithm for updating the set of recipients, while the encryption algorithm encrypts a message for a previously determined recipient set. We call this notion anonymous receiver-updatable broadcast encryption (ARUBE). The image below illustrates ARUBE in operation, where a bidder securely posts an encrypted bid to providers A and B. Provider C and any eavesdropper will be unable to decrypt the bid. Using ARUBE, mev-commit keeps all information and value related to bids private pre-execution while allowing them to be settled in a decentralized manner. ## Committing to Bids A provider who receives a bid can make a commitment to it, which they also sign for authentication. The signed commitment binds the provider to the bid. Furthermore, the process is executed in such a way that only the bidder who issued the bid can identify a commitment as being related to their bid. This approach ensures a high level of privacy for the providers, as the commitments they issue are not linkable to a specific bid. In a normal run of the protocol the provider opens all its commitments at the end of the L1 slot, however if the provider refuses to open any of its commtiments, the bidder can independently open the commitment without needing assistance from the provider. This functionality is provided by the novel notion of dual-phase commitments. ### Dual-Phase Commitment (DPCOM) DPCOM is a two-party commitment protocol that allows a message to be committed in two distinct phases. In the first phase, one party precommits to a message and receives both a precommitment and an opening key. In the second phase, the other party commits to the precommitment generated in the first phase, receiving a decommitment information as the output. A key feature of a dual-phase commitment scheme is its flexibility in opening the resulting commitment using either the opening key or the decommitment information. This is especially useful in the context of the mev-commit protocol, where the bidder generates a precommitment to its bid, after which the provider commits to that precommitment. This process also ensures that both parties can open the commitment: the bidder obtains the opening key when generating the precommitment, and the provider obtains the decommitment information when committing to the precommitment. Consequently, both parties can later prove the content of the committed message to third parties. Crucially, if the provider misbehaves and refuses to publicly open the commitment, the bidder can independently open it without needing assistance from the provider. The image below illustrates provider B committing to a bid posted by bidder 2, while the other parties remain unaware of the specific bid being committed to. You can read more on ARUBE and DPCOM [here](https://mirror.xyz/preconf.eth/iz2J0uTXHhl8DiAkG-VLLwvCp-8qcc_Z7A8_4rU0A3g). ## ZK Proofs for Opening Commitments A crucial property of the commitments issued by providers on mev-commit is that they can both be opened by providers as well as bidders. Being able for the bidders to open commitments is necessary when providers violate the commitment and thus have no incentive to open it. Therefore, when providers open a commitment, they have to prove in zero-knowledge that the commitment was generated correctly. This ZK proof is verified in a smart contract on the mev-commit chain when the provider sends the commitment-opening transaction. Thus, a provider can only open commitments that have been generated correctly and could also have been opened by the bidder. ### Implementation and Efficiency The ZK proof used has been tailor-made for this particular use-case and optimized for efficiency. It is based on so-called sigma protocols and only requires a few elliptic curve operations and the computation of a hash. Generating a single ZK proof for the commitment opening takes only 0.122 milliseconds on a Mac M1 Pro. Furthermore, only around 32k gas is consumed in the smart contract to verify the proof. For comparison, the overall gas cost of the commitment opening transaction is around 488k gas. Hence, only less than 7% of the gas cost is attributed to the zero-knowledge proof verification. More details on the used ZK proofs can be found [here](https://mirror.xyz/preconf.eth/AgtLSBob1hd2A924vlL7jCyJxQDZZE2tCq_K07w5vuU). # Builder Attribution Source: https://docs.primev.xyz/v1.2.x/concepts/rewards-and-slashing/builder-attribution Understanding how builders are identified and attributed in mev-commit # Builder Attribution Builder attribution in the mev-commit system involves identifying the provider responsible for building an L1 block. This is crucial for ensuring that rewards and slashing mechanisms are correctly applied based on the commitments made by providers. ## How Builder Attribution Works ### Oracle and Builder Attribution The oracle plays a central role in verifying whether commitments made by providers are fulfilled. It does this by: * Querying the PBS relay to obtain block delivery data and associated BLS keys * Cross-referencing block hashes from L1 with those delivered via the relay * Identifying the builder through their registered BLS key when block hashes match * Validating commitments against the identified builder in the mev-commit system This system ensures accurate provider attribution for block building and appropriate distribution of rewards or penalties based on commitment fulfillment. # mev-commit Points Program Source: https://docs.primev.xyz/v1.2.x/concepts/rewards-and-slashing/points The `mev-commit` Points Program rewards validators who opt-in and remain actively opted-in. Points accrue over **6-month Seasons**, with each Season offering base points plus growing multipliers. All points will be visible on the [Validator Dashboard](https://validators.mev-commit.xyz/) like the screenshot below. Read more to learn how points are awarded and how to maximize your total. Points on the Dashboard ## Quick Overview * **Immediate Reward:** Earn **1,000 points** per validator right when you opt in. * **6-Month Seasons:** Completing an entire Season nets you up to **10,000 points** total in Season 1, and double for following seasons. * **Multipliers:** * Season 1: base schedule (see table below). * Season 2 & 3: rewards are **2×** each month’s total. * **Opt-Out Penalties:** If you opt out early during a season, you keep the **base points** for fully completed months but **lose** that month’s multiplier. Stay opted in with as many validators through all seasons for the maximum multiplier bonus. *** ## Monthly Accrual (Season 1) Below is the monthly schedule for Season 1, showing **cumulative** points if you remain opted in through each month: | Month | Total Points if Still Opted In at Month End | | --------- | ------------------------------------------- | | 1 | 1,000 | | 2 | 1,270 | | 3 | 1,530 | | 4 | 1,800 | | 5 | 2,070 | | 6 | 2,330 | | **Total** | **10,000** | * Points accrue **daily**, but the monthly multiplier is only **finalized** if you remain opted-in through each 6 month Season. * **Season 2 & 3** double all monthly totals shown above (2x). ## Points Chart Below is a visualization of your points over the planned 3 Seasons. Accrued points represent all points available at the end of a season. Solidified points represent points that will remain with your operator before a Season is over. Points Chart ## Aggregated Points at Operator Level Your dashboard displays **one aggregate total** across all your opted-in validators. Operators can see total points and watch them grow daily. ## Maximize Points via Partner Protocols You can earn additional or parallel rewards when using partner protocols alongside `mev-commit`: * **EigenLayer:** Operators opted-in to the `mev-commit AVS` on EigenLayer may earn `$eigen` token rewards (based on EigenLayer’s policies). * **Symbiotic, Mellow, SSV:** Opt-in validators using these protocols to earn points from them AND mev-commit. Points will be available on the Symbiotic dashboard as well. If you participated in prior **testnet phases**, you may be eligible for extra **genesis points**. Please reach out to our team so we can verify your participation and make your bonus available. *** ## Opt-Out Scenarios * **Before Month Ends** * You keep points from previous fully completed months. * You **forfeit** any partially accrued points for the current month. * **Before 6 Months But After Some Full Months** * You keep **1,000 base points** for each fully completed month in Season 1, double for subsequent seasons. * You **lose** the monthly multiplier for those months. * Example: If you leave before the end of a Season, you only keep 1,000 for each completed month without the monthly multiplier. * **Opting Out and Re-Opting In** * A **7-day cooldown** applies for each validator key if you opt out. If you have trouble with this, reach out to our team. * Rejoining resets you to Season 1 status. *** ## Getting Started 1. **Opt In** * Visit the [Validator Dashboard](https://validators.mev-commit.xyz/) to onboard. 2. **Stay In** * Maintain participation for all seasons to maximize multipliers. 3. **Explore Partner Integrations** * Symbiotic, Mellow, SSV, or supporting `mev-commit AVS` on EigenLayer for additional rewards. Participating early and continuously strengthens the network, making each individual’s participation more valuable. Your yield goes up more by opting-in as many validators as you can. That’s it! Maximize your `mev-commit` points and help make Ethereum FAST for everyone. Earn juicy yield AND points! # Rewards and Slashing Source: https://docs.primev.xyz/v1.2.x/concepts/rewards-and-slashing/rewards-and-slashing The providers and validators that opt-in to the mev-commit protocol are incentivized to act honestly and follow the protocol. This honest behavior is enforced by a reward and slashing mechanism. Both the providers and the validators are required to stake or restake a certain amount of tokens to participate in the mev-commit protocol. The mechanism is designed to reward providers for fulfilling their commitments and to penalize them for breaking them. It also disincentivizes providers from issuing commitments that they cannot fulfill. Additionally, validators can be penalized if they fail to propose a block from mev-commit registered block builders on the L1 chain. Validators have three methods to opt-in to mev-commit, as described in the [validators section](/v1.2.x/get-started/validators). The staked (or restaked) tokens are used to secure the mev-commit protocol and to incentivize validators to include blocks built by mev-commit providers in the L1 chain. Crucially, if the validator acts maliciously on the mev-commit protocol they can be slashed and lose a portion of their staked (or restaked) tokens. Next, we discuss the rewards and slashing mechanisms for validators and providers in more detail. The risk of getting slashed is very low for validators, unless they intentionally behave dishonestly. This has been confirmed by an [independent report on the risk/reward profile of mev-commit by Chaos Labs](https://governance.ether.fi/t/primev-symbiotic-risk-analysis/). ## Validators/Proposers A validator that opts into mev-commit makes an implicit commitment to include a block from a mev-commit registered block builder in L1 whenever they become the proposer of the slot. ### Rewards There are two categories of rewards for validators opting in to mev-commit: 1. Increased yield 2. [Points](/v1.2.x/concepts/rewards-and-slashing/points) The main reward for proposers opting in to mev-commit is increased yield by proposing a more valuable block, paid through the mev-boost auction. Upon proposing a block while opted-in to mev-commit, a proposer will receive all bid related value in the mev-commit network that is surfaced by the mev-boost auction embedded in the block they propose. In other words, proposers passively receive rewards from mev-commit by proposing more valuable blocks that include increased value from mev-commit bids. A proposer will almost always propose a more valuable block using mev-commit than without while mev-commit bids are present for its slot. Using an example of a block worth 1 ETH and mev-commit bids worth 0.1 ETH, the diagram below depicts Validator Rewards with and without mev-commit: Validator Rewards An important observation here is that proposers opting in increases the credibility of the preconfs and consequently their value. Due to the increased preconf values, the providers have additional value to bid in the mev-boost auction, thus driving up the total revenue a proposer will get. ### Slashing Validators are generally **not expected to be slashed** on mev-commit unless they act maliciously, as providers on mev-commit are the primary decision makers liable for any slashing. The only case for a proposer slash is acting maliciously or using an unsupported relay / validator sidecar misconfiguration. For missed blocks or self-built blocks, mev-commit does not slash proposers. We detail these cases below. #### Missed Block A proposer can completely miss its slot and not include any block in L1. This can happen either due to network issues by the proposer, due to the relay not delivering the block's contents on time, or due to chain reorgs. In any case, mev-commit does not slash the proposer for missing a block as the proposer does not profit from omitting a block and it is potentially out of their control. #### Included Block Not Built by mev-commit Provider A proposer can include a block in L1 that was not produced by a mev-commit provider. This can happen for the following reasons: 1. The proposer includes a block from a builder that is not participating in the mev-commit protocol. This can be due to a malicious behavior by the proposer or due to the proposer using a relay that is not compatible with mev-commit (and thus delivering blocks not built by mev-commit providers). 2. The proposer includes a block that was built by itself. Case (1) is considered non-compliant behavior and thus the proposer will be slashed from their stake the fixed amount of 1 ETH. Case (2) should only happen very rarely when the value of the block it receives from the relay is too low, and mev-commit will not slash proposers in this case. However, due to the lack of a robust mechanism for builder attribution of a block in Ethereum's PBS, we will monitor how often proposers choose to build their own blocks, and if needed we will revisit this decision to discourage misbehavior by the proposers. Currently, the restaking case with Eigenlayer only allows the stake to be frozen for an undetermined period of time and not slashed permanently (i.e., burned). While the stake is frozen, the proposer is not able to participate in mev-commit. The proposer can pay a fee to unfreeze its stake. This is a limitation of the current Eigenlayer implementation, and it is expected to be resolved. ## Providers There are four possible outcomes after a commitment is made by a provider and an Ethereum block is proposed: 1. The bid amount is rewarded to the provider for fulfilling the commitment. 2. The provider stake is slashed for breaking the commitment. 3. Nothing happens as neither the provider nor the bidder opened the commitment. We discuss each case in more detail below. ### Rewards Upon successfully fulfilling a commitment, a provider will be rewarded the bid amount, minus a 2% fee (this fee accumulates in the mev-commit protocol treasury). This reward is paid by the mev-commit oracle to the provider’s account after the corresponding slot is settled by the oracle according to the block included in L1. ### Slashing for Broken Commitment Upon breaking a commitment, a provider's stake will be slashed exactly equal to the slash amount specified in the bid they committed to, in addition to a 5% penalty fee. Decay is **not** applied to the slash amount. 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 slash amount and penalty fee, the maximal amount of the slash 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 slash amount that goes to the bidder will be prioritized first, and only after that will the treasury be compensated for as much of the 5% slashing penalty as possible. ### Neutral Outcome The protocol does not take action on commitments that are not opened by the provider or the bidder. This happens if the commitment provider is not the execution provider for the corresponding winning block, in which case there is no point in opening the commitment. ## Builder and Proposer Attribution We rely on the BLS key used to submit to the relay to do attribution and determine the block builder for a particular block. # Validator considerations Source: https://docs.primev.xyz/v1.2.x/concepts/validator-considerations ### Trust Assumptions Opting into the mev-commit protocol signals from a validator that they: * Trust correctness of execution from the mev-commit chain. See [mev-commit chain](/v1.2.x/concepts/mev-commit-chain/chain-details) for more information. * Trust correctness of slashing transactions residing from the Primev operated [mev-commit-oracle](https://github.com/primev/mev-commit/tree/main/oracle) service. * Trust at least one mev-commit opted in relay. [View the list of supported relays here](/v1.2.x/get-started/validators/validator-guide#supporting-relays). * Attest they will follow the rules of the protocol given the above trust assumptions. This currently entails *only* proposing blocks that come from a mev-commit opted in relay. ### Risks While mev-commit is generally not set up to slash validators, validators opting into the mev-commit protocol should be aware of the following risks: * **Trusted Relay block delivery:** Relays could break your trust and communicate blocks that do not abide by existing commitments. This would lead to slashing of the validator. ### Future plans While mev-commit AVS is passive and doesn't require operators to run any software today, Primev is researching means to decentralize centralized components of the mev-commit stack. Stay tuned for more updates on this. *** ### More Resources FAQ on validator incentives, earnings, and the opt-in rationale. # Bidder API Source: https://docs.primev.xyz/v1.2.x/developers/bidder-api/bidder-api ## **Bidders** Bidders will use the `bidder` role to run their nodes. The node provides the **Bidder API** to submit bids to the network and will sign the bid before sending it out. In response, bidders will receive commitments from providers if their bid is accepted. This is a streaming response, and bidders are expected to keep their connection alive until their node receives all relevant commitments. The Bidder API is also implemented using the gRPC framework, supporting two primary operations: * **Send Bid:** The user submit their bid. * **Receive Preconfirmation:** The user receives streaming preconfirmations if accepted. ### **RPC API for Bidders** Users can find the protobuf file in the [repository](https://github.com/primev/mev-commit/blob/main/p2p/rpc/bidderapi/v1/bidderapi.proto). This can be used to generate the client for the RPC in the language of your choice. The Go client has already been generated in the repository. For other languages, please follow the instructions in the [gRPC documentation](https://grpc.io/docs/languages/) to generate them separately. **API Operation:** ``` rpc SendBid(Bid) returns (stream Commitment) ``` **Message Definitions** ```protobuf theme={null} message Bid { repeated string tx_hashes = 1; string amount = 2; int64 block_number = 3; int64 decay_start_timestamp = 4; int64 decay_end_timestamp = 5; repeated string reverting_tx_hashes = 6; repeated string raw_transactions = 7; string slash_amount = 8; }; message Commitment { repeated string tx_hashes = 1; string bid_amount = 2; int64 block_number = 3; string received_bid_digest = 4; string received_bid_signature = 5; string commitment_digest = 6; string commitment_signature = 7; string provider_address = 8; int64 decay_start_timestamp = 9; int64 decay_end_timestamp = 10; int64 dispatch_timestamp = 11; repeated string reverting_tx_hashes = 12; string slash_amount = 13; } ``` ### **HTTP API** The same API is also available on the HTTP port configured on the node. Please review the [API docs](/v1.2.x/api-reference/bidder/sendbid) to understand the usage. An [example CLI application](https://github.com/primev/mev-commit/blob/main/p2p/examples/biddercli) is implemented in the repository. The primary purpose of this example is to demonstrate the process of integrating with the RPC API. # Managing Your Bidder Deposit Source: https://docs.primev.xyz/v1.2.x/developers/bidder-api/bidder-deposit **To check your deposit for a specific provider** ```shell theme={null} > curl -s "http://localhost:13523/v1/bidder/get_deposit?provider=0x3C44CdDdB6a900fa2b585dd299e03d12FA4293BC" | jq { "amount": "0", "provider": "0x3C44CdDdB6a900fa2b585dd299e03d12FA4293BC" } ``` **To check deposits for all providers and get bidder EOA balance** ```shell theme={null} > curl -s "http://localhost:13523/v1/bidder/get_all_deposits" | jq { "deposits": [ { "provider": "0x3C44CdDdB6a900fa2b585dd299e03d12FA4293BC", "amount": "3000000000000000000" } ], "bidderBalance": "9996999791340641239011" } ``` **Funding your node account** First, retrieve the Ethereum account address of your node: ```shell theme={null} > 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 bidder EOA on the mev-commit chain, you may use the [bridge](/v1.2.x/get-started/bridge). **Automate depositing - The easy way** It's recommended that bidders leverage the *deposit manager* to deposit, and automate ongoing re-deposits to specific providers. The deposit manager is an on-chain contract that a bidder account can enable by "setting their code" to the implementation using EIP-7702. After enabling the deposit manager, a bidder's deposits are automatically replenished from the bidder's EOA balance during the preconf settlement process, according to *target deposit* amounts configured by the bidder. The easiest way to enable the deposit manager is by setting two flags/environment variables upon starting your bidder node: ```shell theme={null} > ./mev-commit --enable-deposit-manager=true --target-deposit-amount= ``` Where the target deposit amount will be set for all valid providers that're currently a part of the network. Alternatively you can use the `MEV_COMMIT_ENABLE_DEPOSIT_MANAGER` and `MEV_COMMIT_TARGET_DEPOSIT_AMOUNT` environment variables. **Automate depositing - Through API** To enable the deposit manager through API, use the following command: ```shell theme={null} > curl -s -X POST http://localhost:13523/v1/bidder/enable_deposit_manager | jq { "success": true } ``` Then to set target deposits customized to each provider: ```shell theme={null} > curl -s -X POST http://localhost:13523/v1/bidder/set_target_deposits -H 'Content-Type: application/json' -d '{"target_deposits":[{"provider":"0x3C44CdDdB6a900fa2b585dd299e03d12FA4293BC","target_deposit":"3000000000000000000"}]}' | jq { "successfullySetDeposits": [ { "provider": "3c44cdddb6a900fa2b585dd299e03d12fa4293bc", "targetDeposit": "3000000000000000000" } ], "successfullyToppedUpProviders": [ "0x3C44CdDdB6a900fa2b585dd299e03d12FA4293BC" ] } ``` **Manually adding to your deposit** If you'd like to manually increase the deposit for a provider, use the following command, specifying the desired amount: ```shell theme={null} > curl -s -X POST "http://localhost:13523/v1/bidder/deposit/1000000000000000000?provider=0x3C44CdDdB6a900fa2b585dd299e03d12FA4293BC" | jq { "amount": "1000000000000000000", "provider": "0x3C44CdDdB6a900fa2b585dd299e03d12FA4293BC" } ``` To manually deposit evenly to multiple providers, use the following command: ```shell theme={null} > curl -s -X POST "http://localhost:13523/v1/bidder/deposit_evenly?total_amount=2000000000000000000&providers=0x8F644015Aa59984BF849259375d9135A89a940e7&providers=0x353ff5537cc2fe78C8632c41Bb848735C2982c45" | jq { "providers": [ "8f644015aa59984bf849259375d9135a89a940e7", "353ff5537cc2fe78c8632c41bb848735c2982c45" ], "amounts": [ "1000000000000000000", "1000000000000000000" ] } ``` After successfully depositing, you are ready to send bids and receive preconfirmations on the network. **Withdrawing from your deposit** To withdraw funds from your deposit to a specific provider, use the following command: ```shell theme={null} > curl -s -X POST http://localhost:13523/v1/bidder/request_withdrawals \ -H 'Content-Type: application/json' \ -d '{ "providers": [ "0x3C44CdDdB6a900fa2b585dd299e03d12FA4293BC" ] }' | jq { "providers": [ "3c44cdddb6a900fa2b585dd299e03d12fa4293bc" ], "amounts": [ "3000000000000000000" ] } ``` Then you must wait the withdrawal period to elapse, currently \~10 minutes. Then finally call: ```shell theme={null} curl -s -X POST http://localhost:13523/v1/bidder/withdraw \ -H 'Content-Type: application/json' \ -d '{ "providers": [ "0x3C44CdDdB6a900fa2b585dd299e03d12FA4293BC" ] }' | jq { "providers": [ "3c44cdddb6a900fa2b585dd299e03d12fa4293bc" ], "amounts": [ "3000000000000000000" ] } ``` ### 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 | # Docker Container for Bidder Node Source: https://docs.primev.xyz/v1.2.x/developers/bidder-api/docker-bidder The mev-commit bidder setup leverages Docker to deploy a bidder node service within a single container, the repository [can be found here](https://github.com/primev/bidder_node_docker) . This bidder node connects to the mev-commit chain, enabling users to submit bids seamlessly. By containerizing the service, you ensure a consistent and reproducible environment, simplifying deployment and scaling. # Prerequisites Before you begin, ensure you have the following: * Docker: Install Docker on your machine. You can download it from the official Docker website. * Docker Compose: Ensure Docker Compose is installed. It typically comes bundled with Docker Desktop, but you can verify by running docker-compose --version. * A funded mev-commit address. * A valid Hoodi or Mainnet private key for authentication. If you need testnet funds, use the MEV-Commit [faucet](https://faucet.testnet.mev-commit.xyz/). # Setup Instructions Follow these steps to set up and run your mev-commit bidder node. 1. Clone the Repository Begin by cloning the repository to your local machine: ```bash theme={null} 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 theme={null} Copy code touch .env ``` Define the required variables: Open the .env file in your preferred text editor and add the following: ```env theme={null} 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 theme={null} 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 theme={null} Copy code docker-compose up --build ``` ## Networking with Other Repositories Before deploying your containers, create a shared Docker network: ```bash theme={null} 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 theme={null} 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 ``` # Tools for Bid Submission Source: https://docs.primev.xyz/v1.2.x/developers/bidder-api/tools-for-bid-submission The team has developed the [bidder CLI](/v1.2.x/get-started/bidders/bidder-cli) tool to make it easier for users to send bids or raw transactions to the network. Please go through the instructions there on how to use this. We also recommend leveraging the Go RPC client or alternatively using the REST API below to send bids. For those who prefer to use command-line tools, options like [grpcurl](https://github.com/fullstorydev/grpcurl), or [BloomRPC](https://github.com/bloomrpc/bloomrpc) are available. These tools require the protobuf definitions from the repository to interact with the RPC services. ## Official Go RPC Client For Go developers, leveraging the official Go RPC client is the recommended approach. It is easier for users to copy the [bidder API protobuf generated](https://github.com/primev/mev-commit/tree/v1.2.x/p2p/gen/go/bidderapi/v1) files into their local project. Then, incorporate the generated client into your Go application as follows: ```go theme={null} import bidderapiv1 "github.com//bidderapi/v1" conn, err := grpc.DialContext( context.Background(), "localhost:13524", grpc.WithBlock(), grpc.WithTransportCredentials(insecure.NewCredentials()), ) if err != nil { // Error handling logic here } currentTime := time.Now().UnixMilli() bid := &pb.Bid{ TxHashes: []string{ "fe4cb47db3630551beedfbd02a71ecc69fd59758e2ba699606e2d5c74284ffa7", "71c1348f2d7ff7e814f9c3617983703435ea7446de420aeac488bf1de35737e8", }, Amount: "1000000000", // Specify amount in wei BlockNumber: 123456, DecayStartTimestamp: currentTime - (time.Duration(8 * time.Second).Milliseconds()), DecayEndTimestamp: currentTime + (time.Duration(8 * time.Second).Milliseconds()), } rcv, err := bidderClient.SendBid(context.Background(), bid) if err != nil { // Error handling logic here } for { pc, err := rcv.Recv() if err == io.EOF { break } if err != nil { // Error handling logic here } fmt.Println("Received preconfirmation:", pc.String()) } ``` ### Custom Client Generation Utilize the provided protobuf [files](https://github.com/primev/mev-commit/tree/v1.2.x/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 theme={null} curl -X POST http://localhost:13523/v1/bidder/bid \ -d '{ "txHashes": [], "amount": , "blockNumber": "decayStartTimestamp": , "decayEndTimestamp": }' ``` ```shell ❯_ example theme={null} curl -X POST http://localhost:13523/v1/bidder/bid \ -d '{ "txHashes": ["91a89B633194c0D86C539A1A5B14DCCacfD47094"], "amount": 10000000000000000, "blockNumber": 4123456, "decayStartTimestamp": 1716935571901, "decayEndTimestamp": 1716935572901 }' ``` The REST API provides a straightforward way to submit bids using HTTP requests. For detailed usage instructions, refer to [the Bidder API documentation](/v1.2.x/api-reference/bidder/sendbid). # Contracts Source: https://docs.primev.xyz/v1.2.x/developers/contracts # Introduction The [mev-commit contracts](https://github.com/primev/mev-commit/tree/main/contracts) verify and manage the movement of funds as a response to bid and commitment activities that occur on our p2p network. For mev-commit mainnet contract addresses please refer to [Mainnet](/v1.2.x/developers/networks/mainnet) section. For mev-commit testnet contract addresses please refer to [Testnet](/v1.2.x/developers/networks/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. * **Validator Opt-In Hub** * ValidatorOptInHub is an updated version of the Opt-In Router that enables actors to query whether a validator is opted-in to the mev-commit protocol from any of our supported registries. * **Vanilla Registry** * VanillaRegistry allows validators to opt-in to mev-commit by staking native ETH directly with the contract. * This stake is separate from a validator's 32 ETH already staked with the beacon chain. * **Mev-commit AVS** * MevCommitAVS acts as a tie-in to Eigenlayer core contracts, enabling validators to opt-in to the mev-commit protocol via native restaking. * **Mev-commit middleware** * MevCommitMiddleware serves as tie-in to Symbiotic core contracts, enabling validators to opt-in to the mev-commit protocol via restaking ERC20 tokens with vaults. ## Bridge Contracts The standard bridge protocol for native ETH transfers between L1 and the mev-commit chain is implemented in [this directory](https://github.com/primev/mev-commit/tree/main/contracts/contracts/standard-bridge). Contracts include: * **L1 Gateway** * The L1 gateway contract allows users to lock their native ETH on L1, where an equivalent amount will be allocated to a specified account on the mev-commit chain. This contract is also responsible for unlocking ETH when bridging back to L1. * **Settlement Gateway** * The settlement gateway integrates with the allocator contract to allocate native ETH on the mev-commit chain. It also allows users to bridge native ETH back to L1. * **Allocator** * The allocator contract is responsible paying out ETH to bridge users as necessary on the mev-commit chain. It's currently only integrated with the settlement gateway, but will be extended to other bridging protocols in the future. ## Deploying Custom Contracts ### Mainnet You can deploy any EVM compatible contracts to the mev-commit chain, simply set your **Chain ID to 57173** and RPC Url to `https://chainrpc.mev-commit.xyz`. ### Testnet You can deploy any EVM compatible contracts to the mev-commit chain, simply set your **Chain ID to 17864** and RPC Url to `https://chainrpc.testnet.mev-commit.xyz`. # Debugging Source: https://docs.primev.xyz/v1.2.x/developers/debugging ### **Debugging Tools in mev-commit Node** As the mev-commit node is under active development, it includes debugging tools for in-depth analysis. These tools, primarily intended for developers and not for everyday users, offer insights into the node's functionality. They are accessible via the HTTP API endpoint. ### **Understanding Network Topology** You can view the network's topology as recognized by the mev-commit node at the `/v1/debug/topology` endpoint. This provides information such as the number of connected nodes and their roles, helping to ensure your node is well-connected within the network. Example of Topology Data: ```json theme={null} { "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. # FAST RPC API Source: https://docs.primev.xyz/v1.2.x/developers/fast-rpc-api The FAST RPC provides all the methods of the regular Ethereum API. Some of the default methods (starting with `eth_`) have been overridden to provide improved functionality and some additional methods have been added (starting with `mevcommit_`). ## Overridden Standard Methods All methods here have exactly the same interface as the default API to preserve compatiblity, i.e., all arguments and responses are compliant with standard RPCs. We here describe how they differ internally from the default implementation. ### eth\_sendRawTransaction This method sources preconfs on the mev-commit chain. The RPC creates a local record of the transaction and returns the transaction hash. The transaction is enqueued in the background and is sent to the mev-commit network. Transaction are not send to the public mempool. ### eth\_getTransactionCount If users query the public mempool after submitting transactions through the FAST RPC, they might see a different nonce as FAST RPC transactions are private on the mev-commit network. This RPC method thus returns the mempool count + the queued transactions in the private pool of the service. ### eth\_maxPriorityFeePerGas For users of the FAST RPC, the priority fee should be set to 0. Thus, this method always returns 0. ### eth\_getTransactionReceipt This method is used by clients to query the receipt of the transaction corresponding to the hash they received when sending the transaction. To enable the FAST experience, it will return the receipt early if it is a mev-commit opted-in slot and enough preconfirmations have been obtained for the transaction. The block hash of a preconfirmed transaction is set to the transaction hash and can be used in the `eth_getBlockByHash` method. ### eth\_getBlockByHash For regular block hashes, this method returns the usual block information. For block hashes corresponding to preconfirmed transactions, it returns a fictitious block containing only this transaction. ## Additional FAST RPC Methods ### mevcommit\_getTransactionCommitments For a preconfirmed transaction, this method takes the transaction hash as argument and returns the commitments received on the mev-commit network. **Example output:** ```json theme={null} { "jsonrpc": "2.0", "id": 1, "result": [ { "tx_hashes": [ "751d9aa7a64b59f63c8374216b4b13e29d9085821846900461b9b95595554449" ], "bid_amount": "2310000000000", "block_number": 12594, "received_bid_digest": "4cd2d1253a9f884d0618be7b71be668c1f628a650d569bf9891e698d04180f37", "received_bid_signature": "ae696428129521f5ea1284e5648715d1d6f9878327d8a0ee64f38c92af31bdeb5bcdb4eb45dd74774ae27e8e80e9f7980a8aa18c6c47df7f4c0474ae8771cf381c", "commitment_digest": "b76625bd8f5041d62ab18bfc1d688d1507efef801670afa7c227b45720ccae00", "commitment_signature": "c2611b430bc38198715ed537d06d5a8e548cd7e73a6b4c9cd3b8898851c736b75b851d5547d46eefe2456a45b71eed4b13f54a1f5949c3a8945d1aa8afd979b01b", "provider_address": "e9f91e47e36b4705ccdb91213291069e49d245c0", "decay_start_timestamp": 1752134873021, "decay_end_timestamp": 1752134884921, "dispatch_timestamp": 1752134872924, "reverting_tx_hashes": [ "" ], "slash_amount": "0" }, { "tx_hashes": [ "751d9aa7a64b59f63c8374216b4b13e29d9085821846900461b9b95595554449" ], "bid_amount": "2310000000000", "block_number": 12594, "received_bid_digest": "4cd2d1253a9f884d0618be7b71be668c1f628a650d569bf9891e698d04180f37", "received_bid_signature": "ae696428129521f5ea1284e5648715d1d6f9878327d8a0ee64f38c92af31bdeb5bcdb4eb45dd74774ae27e8e80e9f7980a8aa18c6c47df7f4c0474ae8771cf381c", "commitment_digest": "9e54edce7f895079ee836dc4915eabe7c39892aae281640ffeb96541618908f4", "commitment_signature": "de356ccedc9812f9cd8e3a0048f6408c667cbfe854ac4bb5a9090180c90aa025603ae74f2a70cf043e8b81f2a09c4c1e2bb6d9750db602a31d2d31458e1938c11b", "provider_address": "71303204575c024cd185ca3809a0964925f10ce4", "decay_start_timestamp": 1752134873021, "decay_end_timestamp": 1752134884921, "dispatch_timestamp": 1752134872925, "reverting_tx_hashes": [ "" ], "slash_amount": "0" } ] } ``` ### mevcommit\_getBalance This method takes as input an account address and returns the available deposit balance for that address. **Example output:** ```json theme={null} { "jsonrpc": "2.0", "id": 1, "result": { "balance": "499997942000000000" } } ``` ### mevcommit\_optInBlock This method returns the time in seconds until the next block that has a mev-commit opted in validator. Since these blocks are exclusively built using the mev-commit network, the method can be used for decisioning by users and applications. **Example output:** ```json theme={null} { "jsonrpc": "2.0", "id": 1, "result": { "timeInSecs": "57" } } ``` ### mevcommit\_cancelTransaction This method takes as input a transaction hash and cancels attempts to get commitments for the corresponding transaction. If commitments have already been obtained, the transaction can still land on chain. The cancellation itself involves no additional transactions and incurs no cost. The method returns whether the cancellation was successful and the hash of the transaction. **Example output:** ```json theme={null} { "jsonrpc": "2.0", "id": 1, "result": { "cancelled": true, "txHash": "0x38e5a04d8670cac7851c992445b76e6862e6bb567e076e183c7984c8fc71a3c7" } } ``` ### mevcommit\_estimateDeposit In order to send transactions using the RPC service, the user has to deposit funds, which will be used to send bids on the network. To deposit funds, the user has to send a transaction to the RPC with the amount they want to deposit + the cost of deposit to a specific EOA wallet which is owned by the service. This transaction should be sent to the same RPC with no priority fee. This method returns the estimated cost of deposit and the EOA wallet to use to send the funds. **Example output:** ```json theme={null} { "jsonrpc": "2.0", "id": 1, "result": { "bidAmount": "0x24abbb47000", // In hex "depositAddress": "0x945A9e492B98f05c37F5B98349A716F828D5A5bA" } } ``` ### mevcommit\_estimateBridge The RPC also provides an instant bridging service to the mev-commit chain. This can be used without depositing anything in the service beforehand. In order to do the bridging, the user has to create a transaction on L1 to a specific account managed by the RPC service with the amount they want to bridge + the cost of bridging. The funds will be released on mev-commit chain as soon as the transaction is preconfirmed. This method returns the estimated cost and the destination address. **Example output:** ```json theme={null} { "jsonrpc": "2.0", "id": 1, "result": { "bidAmount": "0x4957768e000", // In hex "bridgeAddress": "0x6F3191AdCaeD764cAB858A1B0f522e701C336F70" } } ``` # Fastx402 Source: https://docs.primev.xyz/v1.2.x/developers/fastx402 x402 payment facilitator on Ethereum mainnet powered by FAST RPC preconfirmations Fastx402 is an [x402](https://www.x402.org/) payment facilitator that enables AI agents and applications to pay for resources on Ethereum mainnet using USDC. It achieves sub-second settlement through FAST RPC preconfirmations, solving the slow finality problem that has left agents unable to access Ethereum's stablecoin liquidity for real-time payments. | Property | Value | | -------------- | ------------------------------------------------------------ | | **Endpoint** | `https://facilitator.primev.xyz` | | **Network** | Ethereum Mainnet (Chain ID: 1) | | **Asset** | USDC (`0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48`) | | **Settlement** | FAST RPC (\~100-200ms preconfirmation) | | **Fees** | 0% | | **Source** | [GitHub](https://github.com/primev/mainnet-x402-facilitator) | *** ## Why Fastx402 Traditional Ethereum payments require 12+ seconds for finality, making them unsuitable for real-time API access. Existing x402 facilitators only work on Base and Solana. Fastx402 changes this: * **Sub-second settlement** — \~1.2s end-to-end via [FAST RPC](/v1.2.x/get-started/fastrpc) preconfirmations (vs 12+ seconds) * **Zero gas for agents** — Agents only need USDC, no ETH required. Gas is fully sponsored via the relay wallet * **Mainnet liquidity** — Access Ethereum's largest stablecoin issuance and DeFi ecosystem * **x402 compatible** — Drop-in replacement for any x402 facilitator * **Gasless signatures** — Uses EIP-3009 `transferWithAuthorization` so agents never submit transactions *** ## How It Works Fastx402 uses USDC's native [EIP-3009](https://eips.ethereum.org/EIPS/eip-3009) `transferWithAuthorization` function for gasless, signature-based payments. The flow: 1. An agent encounters a `402 Payment Required` response from a resource server 2. The agent signs an EIP-712 `TransferWithAuthorization` message authorizing a USDC transfer 3. The resource server forwards the signed payment to Fastx402's `/settle` endpoint 4. Fastx402 verifies the signature, checks balances and nonces, then submits the transaction via FAST RPC 5. FAST RPC preconfirms the transaction in \~100-200ms 6. The resource server receives confirmation and grants access ``` Agent Resource Server Fastx402 FAST RPC / L1 │ │ │ │ │ GET /resource │ │ │ │ ──────────────────────────> │ │ │ │ │ │ │ │ <── 402 Payment Required │ │ │ │ (paymentRequirements) │ │ │ │ │ │ │ │ (sign EIP-3009 authorization locally) │ │ │ │ │ │ │ GET /resource + signature │ │ │ │ ──────────────────────────> │ │ │ │ │ POST /settle │ │ │ │ ──────────────────────> │ │ │ │ │ transferWithAuthorization│ │ │ │ ──────────────────────> │ │ │ │ <── preconfirmed │ │ │ <── { success: true } │ │ │ │ │ │ │ <── 200 OK + resource │ │ │ ``` *** ## API Reference ### POST /settle Verify a payment signature and settle it on-chain via FAST RPC. **Request body:** ```json theme={null} { "paymentPayload": { "x402Version": 2, "scheme": "exact", "network": "eip155:1", "payload": { "signature": "0x...", "authorization": { "from": "0x...", "to": "0x...", "value": "1000000", "validAfter": "0", "validBefore": "1718000000", "nonce": "0x..." } } }, "paymentRequirements": { "scheme": "exact", "network": "eip155:1", "amount": "1000000", "asset": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", "payTo": "0x...", "maxTimeoutSeconds": 60 } } ``` **Response (success):** ```json theme={null} { "success": true, "payer": "0x...", "transaction": "0x...", "network": "eip155:1" } ``` **Response (failure):** ```json theme={null} { "success": false, "error": "insufficient_funds", "payer": "0x..." } ``` ### POST /verify Validate a payment signature without settling (dry run). Same request body as `/settle`. ```json theme={null} { "isValid": true, "payer": "0x..." } ``` ### GET /supported Discover facilitator capabilities. ```json theme={null} { "kinds": [ { "x402Version": 2, "scheme": "exact", "network": "eip155:1" } ], "extensions": ["bazaar"], "signers": { "eip155:*": ["0x488d87a9A88a6A878B3E7cf0bEece8984af9518D"] } } ``` ### GET /health Health check endpoint. *** ## EIP-3009 Signing Agents sign a `TransferWithAuthorization` typed data message using USDC's EIP-712 domain: ```typescript theme={null} const signature = await walletClient.signTypedData({ domain: { name: 'USD Coin', version: '2', chainId: 1, verifyingContract: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48', }, types: { TransferWithAuthorization: [ { name: 'from', type: 'address' }, { name: 'to', type: 'address' }, { name: 'value', type: 'uint256' }, { name: 'validAfter', type: 'uint256' }, { name: 'validBefore', type: 'uint256' }, { name: 'nonce', type: 'bytes32' }, ], }, primaryType: 'TransferWithAuthorization', message: { from: agentAddress, to: merchantAddress, value: BigInt(1_000_000), // 1 USDC (6 decimals) validAfter: 0n, validBefore: BigInt(Math.floor(Date.now() / 1000) + 900), nonce: `0x${randomBytes(32).toString('hex')}`, }, }); ``` The relay wallet (`0x488d87a9A88a6A878B3E7cf0bEece8984af9518D`) submits the `transferWithAuthorization` call on-chain. The agent never needs ETH — only USDC. *** ## Error Codes | Code | Description | | ----------------------------- | ------------------------------------------------------------- | | `unsupported_scheme` | Scheme is not "exact" | | `unsupported_network` | Network is not "eip155:1" | | `unsupported_asset` | Asset is not USDC | | `invalid_from_address` | Invalid sender address | | `recipient_mismatch` | `authorization.to` does not match `paymentRequirements.payTo` | | `insufficient_payment` | Authorization value \< required amount | | `authorization_expired` | Current time + 60s >= `validBefore` | | `authorization_not_yet_valid` | Current time \< `validAfter` | | `invalid_signature` | EIP-712 signature verification failed | | `insufficient_funds` | Payer USDC balance \< authorization value | | `nonce_already_used` | Nonce already consumed (replay protection) | *** ## ERC-8004 Agent Identity Fastx402 is registered as an on-chain agent via [ERC-8004](https://eips.ethereum.org/EIPS/eip-8004): | Property | Value | | ----------------------- | -------------------------------------------- | | **Agent ID** | 23175 | | **Identity Registry** | `0x8004A169FB4a3325136EB29fA0ceB6D2e539a432` | | **Reputation Registry** | `0x8004BAa17C55a88189AE136b182e5fdA19dE9b63` | | **Metadata URI** | `/agent.json` | # Mev-commit Mainnet Source: https://docs.primev.xyz/v1.2.x/developers/networks/mainnet Live on Ethereum Mainnet, mev-commit allows bidders and providers to engage in execution service bids and commitments. Preconfirmations, the first use case for real-time bids and commitments, are available with mev-commit. # Service Links | Service | Link | | ----------------- | ---------------------------------------------------------------------- | | Mainnet RPC | [https://chainrpc.mev-commit.xyz/](https://chainrpc.mev-commit.xyz/) | | Mainnet WebSocket | [wss://chainrpc-wss.mev-commit.xyz](wss://chainrpc-wss.mev-commit.xyz) | | Bootnode endpoint | [https://bootnode.mev-commit.xyz/](https://bootnode.mev-commit.xyz/) | | Block explorer | [http://mev-commit.xyz](http://mev-commit.xyz) | # Contracts deployed to mev-commit chain ### **Core Contracts**
Contract Address
BidderRegistry
ProviderRegistry
PreconfManager
Oracle
BlockTracker
### **Settlement Bridge Gateway**
Contract Address
SettlementGateway
# Contracts deployed to L1 Ethereum ### **L1 Bridge Gateway**
Entity Address Type Address
L1Gateway Proxy
Implementation
### **L1 Validator Registries**
Contract Address Type Address
MevCommitAVS Proxy
Implementation
MevCommitMiddleware Proxy
Implementation
VanillaRegistry Proxy
Implementation
Reputational VanillaRegistry Proxy
Implementation
ValidatorOptInRouter Proxy
Implementation
ValidatorOptInHub Proxy
Implementation
All contract calls should be made through the proxy contracts. Implementations are listed for transparency, where verified contract code can be viewed. # Other L1 Ethereum addresses
Description Address
Primev Team Multisig
Commitment Holdings Multisig
Symbiotic "network address" (Served by Primev Team Multisig)
# How can users provide feedback or report issues encountered on testnet or mainnet? Users can open an issue on the GitHub repository that is associated with any issue they encounter. They can also tag @primev\_xyz on Twitter, or reach out to us to join a Telegram group for early power users. # Other Networks Source: https://docs.primev.xyz/v1.2.x/developers/networks/other-networks mev-commit is designed to be network-agnostic. While it currently operates on Ethereum mainnet and testnet, the protocol can be extended to support preconfirmations on any network where execution service providers — whether validators, miners, sequencers, or other block producers — are willing to issue commitments against future block space. ## How It Works When mev-commit is deployed for a new network, Primev spins up a **dedicated mev-commit network instance** for that ecosystem. This includes: * **Custom bootnode** — A dedicated bootnode endpoint is provisioned for the target network, allowing providers and bidders to discover peers within the correct mev-commit network instance. * **Provider registration** — The network's execution service providers (validators, sequencers, etc.) register as mev-commit providers and run provider nodes connected to the custom bootnode. * **Bidder access** — Bidders who want preconfirmations on the target network connect their bidder nodes to the same custom bootnode. * **Oracle and settlement** — A network-specific oracle is configured to verify commitment fulfillment against the target network's block production. * **FastRPC endpoint** — A [FastRPC](/v1.2.x/get-started/fastrpc) instance can be stood up for the network, giving users a single RPC endpoint that automatically wraps transactions with preconfirmation bids. Each network instance operates independently, so providers and bidders should run separate mev-commit nodes per network they participate in. ## Architecture ``` ┌─────────────────────────────────────────────────┐ │ Target Network │ │ (validators / sequencers / block producers) │ └──────────────────────┬──────────────────────────┘ │ run provider nodes ▼ ┌─────────────────────────────────────────────────┐ │ Dedicated mev-commit Instance │ │ │ │ ┌──────────┐ ┌──────────┐ ┌──────────────┐ │ │ │ Bootnode │ │ Oracle │ │ Contracts │ │ │ └──────────┘ └──────────┘ └──────────────┘ │ │ │ │ ┌──────────────────┐ ┌─────────────────────┐ │ │ │ Provider Nodes │ │ Bidder Nodes │ │ │ └──────────────────┘ └─────────────────────┘ │ └─────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────┐ │ Optional: FastRPC Endpoint │ │ (single RPC wrapping txns with preconf bids) │ └─────────────────────────────────────────────────┘ ``` ## For Execution Service Providers If you are a validator, sequencer, miner, or other block producer on a network and want to bring mev-commit preconfirmations to your ecosystem: 1. **Reach out to the Primev team** — Contact us to discuss your network's architecture and requirements. We will work with you to configure a custom mev-commit instance. 2. **Run a provider node** — Once the instance is provisioned, you will run a mev-commit provider node alongside your existing infrastructure, pointed at the custom bootnode for your network. 3. **Register as a provider** — Stake and register on the provider registry so bidders can discover and interact with you. 4. **Process bids and issue commitments** — Receive bids from bidders in your network's mev-commit instance and issue cryptographic commitments for execution. ## For Bidders If you want preconfirmations on a supported network: 1. **Deploy a bidder node** — Run a mev-commit bidder node configured with the custom bootnode endpoint for the target network. 2. **Fund your bidder account** — Deposit funds into the bidder registry to back your bids. 3. **Submit bids** — Send bids specifying the transactions you want preconfirmed. Providers on the target network will issue commitments. We recommend running a **separate bidder node** for each network you participate in. ## What Primev Provisions When onboarding a new network, the Primev team sets up: | Component | Description | | ------------------- | ---------------------------------------------------------------------------- | | Bootnode | Dedicated peer discovery endpoint for the network | | Oracle | Configured to read and verify block production on the target chain | | Contract deployment | Core mev-commit contracts (BidderRegistry, ProviderRegistry, PreconfManager) | | FastRPC (optional) | RPC endpoint that wraps transactions with preconfirmation bids | | Monitoring | Observability and alerting for the network instance | ## Get Started To bring mev-commit and preconfirmations to your network, reach out to the Primev team: * **Twitter**: [@primev\_xyz](https://twitter.com/primev_xyz) * **GitHub**: [github.com/primev](https://github.com/primev) * **Telegram**: Contact us on Twitter to join our integration channel # Mev-commit Testnet Source: https://docs.primev.xyz/v1.2.x/developers/networks/testnet Live on Hoodi testnet, mev-commit allows bidders and providers to engage in execution service bids and commitments. Preconfirmations, the first use case for real-time bids and commitments, are available with mev-commit. ## **Links and Connection Details** ### **Services links** | Service | Link | | ----------------- | -------------------------------------------------------------------------------------- | | Testnet RPC | [https://chainrpc.testnet.mev-commit.xyz/](https://chainrpc.testnet.mev-commit.xyz/) | | Testnet WebSocket | [wss://chainrpc-wss.testnet.mev-commit.xyz](wss://chainrpc-wss.testnet.mev-commit.xyz) | | Bootnode endpoint | [https://bootnode.testnet.mev-commit.xyz/](https://bootnode.testnet.mev-commit.xyz/) | | Block explorer | [http://explorer.testnet.mev-commit.xyz](http://explorer.testnet.mev-commit.xyz) | ### **Core Contract Addresses (mev-commit chain)**
Contract Address
BidderRegistry
ProviderRegistry
PreconfManager
Oracle
BlockTracker
### **Bridge Gateway (mev-commit chain)**
Contract Address
SettlementGateway
L1Gateway
### **Validator Registry Contract Addresses (Hoodi)**
Contract Address
ValidatorOptInRouter
ValidatorOptInHub
VanillaRegistry
MevCommitAVS
MevCommitMiddleware
Lido Registry
RocketMinipoolRegistry
### **Other addresses (Hoodi)**
Entity Address
Mev-commit (Symbiotic) Network Address
Mev-commit (Symbiotic) Vault Address
Mev-commit (Symbiotic) Subnetwork
## How can users provide feedback or report issues encountered on the testnet? Users can open an issue on the GitHub repository that is associated with any issue they encounter. They can also tag @primev\_xyz on Twitter, or reach out to us to join a Telegram group for early power users. ## Testnet System Requirements Please refer to the System Requirements section [here.](/v1.2.x/developers/system-requirements) # Provider API Source: https://docs.primev.xyz/v1.2.x/developers/provider-api ## **Providers** Execution providers can use the `provider` role to run their nodes. This allows them to receive signed bids and issue commitments for execution. The **Provider RPC API** allows providers to receive signed bids that are being propagated in the network. Once they get a bid, they'll need to communicate with the mev-commit node to **Accept**. Accepted bids result in the mev-commit node sending a signed commitment to the p2p network. The Provider API is implemented using the gRPC framework, supporting two primary operations: * **Receiving Bids:** Providers receive streaming bids from the mev-commit node. * **Sending Processed Bids:** Providers send information about processed bids back to the mev-commit node. ### **RPC API Details** The protobuf file is available in the [repository](https://github.com/primev/mev-commit/blob/main/p2p/rpc/providerapi/v1/providerapi.proto). The Go client has already been generated in the repository. To generate the RPC client for other languages, please follow the instructions in the [gRPC documentation](https://grpc.io/docs/languages/). **Primary RPC Operations:** ```protobuf theme={null} // 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 theme={null} message Bid { repeated string tx_hashes = 1; string bid_amount = 2; int64 block_number = 3; bytes bid_digest = 4; int64 decay_start_timestamp = 5; int64 decay_end_timestamp = 6; repeated string reverting_tx_hashes = 7; repeated string raw_transactions = 8; string slash_amount = 9; BidOptions bid_options = 10; string bidder_address = 11; }; message BidResponse { bytes bid_digest = 1; enum Status { STATUS_UNSPECIFIED = 0; STATUS_ACCEPTED = 1; STATUS_REJECTED = 2; } Status status = 2; int64 dispatch_timestamp; }; ``` ### **HTTP API** The same API is also available on the HTTP port configured on the node. Please review the [API docs](/v1.2.x/api-reference/provider/receivebids) to understand the usage. An [example client](https://github.com/primev/mev-commit/tree/main/p2p/examples/provideremulator) is implemented in the repository. This example showcases how to integrate a client into the provider's operational framework. While the sample client automatically accepts every incoming bid, providers should incorporate their own decision-making logic to evaluate and respond to these bids. # Run mev-commit Chain Node Source: https://docs.primev.xyz/v1.2.x/developers/run-mev-commit-chain-node ## Setting Up Your Full Node for the mev-commit Testnet To join the mev-commit chain testnet with your own full-node, use [mev-commit geth](https://github.com/primev/mev-commit-geth). We've modified go-ethereum to achieve shorter block periods than mainnet Ethereum, and to enable seamless native token bridging capabilities. Geth configuration will vary based on environment, but an example is provided below: ```shell ❯_ terminal theme={null} exec geth \ --verbosity="$VERBOSITY" \ --datadir="$GETH_DATA_DIR" \ --port 30311 \ --syncmode=full \ --gcmode=full \ --http \ --http.corsdomain="_" \ --http.vhosts="_" \ --http.addr=0.0.0.0 \ --http.port="$RPC_PORT" \ --http.api=web3,debug,eth,txpool,net,engine \ --bootnodes enode://34a2a388ad31ca37f127bb9ffe93758ee711c5c2277dff6aff2e359bcf2c9509ea55034196788dbd59ed70861f523c1c03d54f1eabb2b4a5c1c129d966fe1e65@103.219.170.127:29746 \ --networkid=$CHAIN_ID \ --unlock=$BLOCK_SIGNER_ADDRESS \ --password="$GETH_DATA_DIR"/password \ --mine \ --miner.etherbase=$BLOCK_SIGNER_ADDRESS \ --allow-insecure-unlock \ --nousb \ --netrestrict 172.13.0.0/24 \ --metrics \ --metrics.addr=0.0.0.0 \ --metrics.port=6060 \ --ws \ --ws.addr=0.0.0.0 \ --ws.port="$WS_PORT" \ --ws.origins="_" \ --ws.api=debug,eth,txpool,net,engine \ --rpc.allow-unprotected-txs \ --authrpc.addr="0.0.0.0" \ --authrpc.port="8551" \ --authrpc.vhosts="_" \ --nat extip:$NODE_IP ``` # System Requirements Source: https://docs.primev.xyz/v1.2.x/developers/system-requirements Below are the minimum system requirements to run a mev-commit node: * Software: mev-commit client and curl * OS: 64-bit Linux, Mac OS X 10.14+ * CPU: 4+ cores @ 2.8+ GHz * Memory: 16GB+ RAM * Network: 1 GBit/sec broadband In order to run a `provider` node, the machine needs to have a public IP assigned to it. This will be used by the other bidder nodes to connect. # Bidder Best Practices Source: https://docs.primev.xyz/v1.2.x/get-started/bidders/best-practices ## Understanding Credible and General Commitments In the mev-commit network, commitments are essential to the bidding process. You may receive two types of commitments: credible and general. If the slot proposer is opted-in to mev-commit, provider commitments become credible. Understanding the difference between these two types of commitments will help you, as a bidder, optimize your interactions with the network and maximize your utility. **Credible Commitments** - Credible commitments are guarantees made by network participants who have direct control over fulfilling your bid. This could include block builders, proposers, or sequencers. These commitments offer the highest level of assurance that your bid will be delivered as promised, as they mean the proposer has opted in to mev-commit. [Querying for Proposers](/v1.2.x/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. You can obtain the list of all registered providers as described [here](/v1.2.x/get-started/relays#how-to-query-the-provider-registry). ## 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](/v1.2.x/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 theme={null} 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 theme={null} curl -X POST http://localhost:13523/v1/bidder/bid \ -d '{ "txHashes": ["0549fc7c57fffbdbfb2cf9d5e0de165fc68dadb5c27c42fdad0bdf506f4eacae", "22145ba31366d29a893ae3ffbc95c36c06e8819a289ac588594c9512d0a99810", "7e1506f266bc86c81ae46018053a274a3bd96a9eff17392930707bf8fa5ff6be"], "amount": "", "blockNumber": , "decayStartTimestamp": , "decayEndTimestamp": , "revertingTxHashes": ["22145ba31366d29a893ae3ffbc95c36c06e8819a289ac588594c9512d0a99810"] }' ``` You can change the values in the fields `txHashes`, `amount`, `blockNumber`, `decayStartTimestamp`, `decayEndTimestamp` and `revertingTxHashes` as desired. ### Bid amount Note the bid `amount` should be set to the total amount the bidder is willing to pay for the bundle. Gas used by the transactions in the bundle does **not** affect the final amount paid. ### Bid Decay The `decayStartTimestamp` and `decayEndTimestamp` are important components for how sensitive the [price of a preconfirmation](/v1.2.x/knowledge-base/how-to-price-a-bid) will be. More details can be found about it [here](/v1.2.x/concepts/bids/bid-structure#details-on-decay-parameters). ### Bid Options The `bidOptions` can be used to set positional constraints on the transactions or bundles in the block. Learn more about the different [options here](/v1.2.x/concepts/bids/bid-structure#details-on-bidOptions). ## 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](/v1.2.x/get-started/bidders/bidder-node-commands#topology)) and that you are receiving mev-commit events (via the [health endpoint](/v1.2.x/get-started/bidders/bidder-node-commands#health)). ## Bidder Depositing Bidders must bridge ETH to the mev-commit chain, then deposit toward one or more providers. As bids are settled, the bidder must "top up" their deposits. To automate this process, the bidder can enable the deposit manager and set target deposits for each provider. A target deposit is the desired amount of funds that a bidder wants to be deposited for a specific provider. Once a target deposit is set, the relevant deposit will be automatically "topped up" to the target value during the settlement process. Bidders should set their target deposits to the maximum cumulative amount of ETH they would ever bid to a provider with respect to a single L1 block. Read more about the deposit manager [here](/v1.2.x/get-started/bidders/bidder-node-commands#deposit-manager). # Bidder CLI application Source: https://docs.primev.xyz/v1.2.x/get-started/bidders/bidder-cli The `bidder-cli` aims to provide a better UX for users to send raw transactions or bids on existing transactions, to the mev-commit network. The tool can be downloaded from the [releases](https://github.com/primev/mev-commit/releases/latest) page. ``` NAME: bidder-cli - A CLI tool for interacting with a gRPC bidder server USAGE: bidder-cli [global options] command [command options] VERSION: 1.1.0 COMMANDS: send-tx-hash Send a bid to the gRPC bidder server send-tx Send a transaction to the gRPC bidder server help, h Shows a list of commands or help for one command GLOBAL OPTIONS: --help, -h show help --version, -v print the version ``` The `send-tx` command is used to send raw transaction payloads. Here users can create a new transaction on the L1 chain and send it directly to the mev-commit network. Users need to provide the account to be used as source of the funds and to sign the transaction. Currently this allows users to send simple transfer transactions. ``` NAME: bidder-cli send-tx - Send a transaction to the gRPC bidder server USAGE: bidder-cli send-tx [command options] OPTIONS: --rpc-url value URL of the gRPC server [$BIDDER_CLI_RPC_URL] --l1-rpc-url value URL of the L1 RPC (default: "https://ethereum-hoodi-rpc.publicnode.com") [$BIDDER_CLI_L1_RPC_URL] --verbose enable verbose logging (default: false) [$BIDDER_CLI_VERBOSE] --from value private key of the account sending the transaction --to value to address --value value amount of the transaction --block-number value block number (default: 0) --decay-duration value decay duration (default: "10m") --bid-amount value bid amount --help, -h show help ``` The `rpc-url` is the URL for the gRPC server running on the bidder node. This is by default running on port 13524. So if you run the node locally, this would typically be `localhost:13524`. If `block-number` is not specified, the next block number is used for the bid. Similarly, the default `decay-duration` is 10 minutes. Which means the bid amount will decay starting from current time to 10 minutes from now. `value` is the amount of ETH to be sent in the L1 transaction and `bid-amount` is the amount the bidder is willing to give to the providers for preconfirming the transaction. All the other flags have sane defaults. The CLI uses the `l1-rpc-url` to get the nonce for the account. Users can point it to a different RPC URL if they are sending transactions to a custom RPC. ```shell ❯_ example theme={null} ./bidder-cli send-tx \ --from \ --to \ --value \ --bid-amount \ --rpc-url localhost:13524 ``` The `send-tx-hash` is used to send bids for transactions that were already submitted to the mempool of the block-builders or to the public mempool. There is a possibility that the transaction is not gossiped to the provider's block building infrastructure in time, so it is better to use the Provider's RPC for submitting transactions. ``` NAME: bidder-cli send-tx-hash - Send a bid to the gRPC bidder server USAGE: bidder-cli send-tx-hash [command options] OPTIONS: --rpc-url value URL of the gRPC server [$BIDDER_CLI_RPC_URL] --l1-rpc-url value URL of the L1 RPC (default: "https://ethereum-hoodi-rpc.publicnode.com") [$BIDDER_CLI_L1_RPC_URL] --verbose enable verbose logging (default: false) [$BIDDER_CLI_VERBOSE] --tx-hashes value [ --tx-hashes value ] transaction hashes --bid-amount value bid amount --block-number value block number (default: 0) --decay-duration value decay duration (default: "10m") --reverting-tx-hashes value [ --reverting-tx-hashes value ] reverting transaction hashes --help, -h show help ``` Users can provider multiple transaction hashes to bid on. Rest of the flags have similar use cases as above. ```shell ❯_ example theme={null} ./bidder-cli send-tx-hash \ --tx-hashes \ --tx-hashes \ --bid-amount \ --rpc-url localhost:13524 ``` # Bidder Node Commands Source: https://docs.primev.xyz/v1.2.x/get-started/bidders/bidder-node-commands This guide covers how to interact with your bidder node. Ensure you have completed the steps from the [quickstart guide](/v1.2.x/get-started/quickstart) in a separate terminal. This will set up your environment and spin up a bidder node. ## Getting deposits and bidder balance To query all deposits and your bidder's balance on the mev-commit chain: ```shell ❯_ terminal theme={null} curl -s "http://localhost:13523/v1/bidder/get_all_deposits" | jq ``` ```json ❯_ typical response theme={null} { "deposits": [ { "provider": "0x3C44CdDdB6a900fa2b585dd299e03d12FA4293BC", "amount": "3000000000000000000" } ], "bidderBalance": "9996999791340641239011" } ``` Or to query a deposit specific to a single provider: ```shell ❯_ terminal theme={null} curl -s "http://localhost:13523/v1/bidder/get_deposit?provider=0x3C44CdDdB6a900fa2b585dd299e03d12FA4293BC" | jq ``` ```json ❯_ typical response theme={null} { "amount": "0", "provider": "0x3C44CdDdB6a900fa2b585dd299e03d12FA4293BC" } ``` 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. ## Deposit manager It's recommended that bidders leverage the *deposit manager* to deposit, and automate ongoing re-deposits to specific providers. The deposit manager is an on-chain contract that a bidder account can enable by "setting their code" to the implementation using EIP-7702. After enabling the deposit manager, a bidder's deposits are automatically replenished from the bidder's EOA balance during the preconf settlement process, according to *target deposit* amounts configured by the bidder. A target deposit is the desired amount of funds that a bidder wants to be deposited for a specific provider. Bidders should set their target deposits to the maximum cumulative amount of ETH they would ever bid to a provider with respect to a single L1 block. If you followed the [quickstart guide](/v1.2.x/get-started/quickstart) exactly, your bidder node will already have the deposit manager enabled. To confirm: ### Get deposit manager status ```shell ❯_ terminal theme={null} curl -s http://localhost:13523/v1/bidder/deposit_manager_status | jq ``` ```json ❯_ typical response theme={null} { "enabled": true, "targetDeposits": [ { "provider": "0x3C44CdDdB6a900fa2b585dd299e03d12FA4293BC", "targetDeposit": "3000000000000000000" } ] } ``` There are two ways to enable the deposit manager... ### Enabling deposit manager on boot up (recommended) The easiest way to enable the deposit manager is by setting two flags/environment variables upon starting your bidder node: ```shell ❯_ terminal theme={null} mev-commit --enable-deposit-manager=true --target-deposit-amount= ``` Where the target deposit amount will be set for all valid providers that're currently a part of the network. Alternatively you can use the `MEV_COMMIT_ENABLE_DEPOSIT_MANAGER` and `MEV_COMMIT_TARGET_DEPOSIT_AMOUNT` environment variables. This is the method used by the [quickstart guide](/v1.2.x/get-started/quickstart). ### Enabling deposit manager through API To enable the deposit manager through API, use the following command: ```shell ❯_ terminal theme={null} curl -s -X POST http://localhost:13523/v1/bidder/enable_deposit_manager | jq ``` ```json ❯_ typical response theme={null} { "success": true } ``` ### Setting target deposits Then to set target deposits customized to each provider: ```shell ❯_ terminal theme={null} curl -s -X POST http://localhost:13523/v1/bidder/set_target_deposits -H 'Content-Type: application/json' -d '{"target_deposits":[{"provider":"0x3C44CdDdB6a900fa2b585dd299e03d12FA4293BC","target_deposit":"3000000000000000000"}]}' | jq ``` ```json ❯_ typical response theme={null} { "successfullySetDeposits": [ { "provider": "3c44cdddb6a900fa2b585dd299e03d12fa4293bc", "targetDeposit": "3000000000000000000" } ], "successfullyToppedUpProviders": [ "0x3C44CdDdB6a900fa2b585dd299e03d12FA4293BC" ] } ``` You should be able to overwrite target deposits for providers at any time using the `set_target_deposits` endpoint. ### Disable deposit manager To disable the deposit manager call: ```shell ❯_ terminal theme={null} curl -X POST http://localhost:13523/v1/bidder/disable_deposit_manager | jq ``` ```json ❯_ typical response theme={null} { "success": true } ``` This will set the bidder EOA's code to zero address, effectively disabling the previous EIP-7702 delegation for the EOA. ## Withdraw deposited funds To withdraw funds from your deposit to a specific provider, use the following command: ```shell ❯_ terminal theme={null} curl -s -X POST http://localhost:13523/v1/bidder/request_withdrawals \ -H 'Content-Type: application/json' \ -d '{ "providers": [ "0x3C44CdDdB6a900fa2b585dd299e03d12FA4293BC" ] }' | jq ``` ```json ❯_ typical response theme={null} { "providers": [ "3c44cdddb6a900fa2b585dd299e03d12fa4293bc" ], "amounts": [ "3000000000000000000" ] } ``` Then you must wait the withdrawal period to elapse, currently \~10 minutes. Then finally call: ```shell theme={null} curl -s -X POST http://localhost:13523/v1/bidder/withdraw \ -H 'Content-Type: application/json' \ -d '{ "providers": [ "0x3C44CdDdB6a900fa2b585dd299e03d12FA4293BC" ] }' | jq ``` ```json ❯_ typical response theme={null} { "providers": [ "3c44cdddb6a900fa2b585dd299e03d12fa4293bc" ], "amounts": [ "3000000000000000000" ] } ``` ## Querying valid providers The valid providers endpoint can be used to get a list of all staked and fully registered providers. ```shell ❯_ terminal theme={null} curl -s http://localhost:13523/v1/bidder/get_valid_providers | jq ``` ```json ❯_ typical response theme={null} { "validProviders": [ "0x88f231bcAa0384936121c31F3972D47F078784Ef" ] } ``` ## 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. ```shell ❯_ terminal theme={null} curl http://localhost:13523/health ``` ## Topology The topology endpoint can be used to check which provider nodes the bidder node is connected to. It'll also display your `Ethereum Address` and `Peer Type`. ```shell ❯_ terminal theme={null} curl http://localhost:13523/v1/debug/topology ``` ## Querying for proposers API This API is enabled by default, the following environment variables could be set when launching a mev-commit client: * `MEV_COMMIT_VALIDATOR_ROUTER_ADDR` * `MEV_COMMIT_BEACON_API_URL` * `MEV_COMMIT_L1_RPC_URL` Current address for the ValidatorOptInRouter contract on Hoodi is and on Mainnet is . The default URLs for the *Mainnet* Beacon Chain and L1 RPC are [https://ethereum-beacon-api.publicnode.com](https://ethereum-beacon-api.publicnode.com) and [https://ethereum-rpc.publicnode.com](https://ethereum-rpc.publicnode.com), respectively, but you can set your own URLs. The default URLs for the *Testnet* Beacon Chain and L1 RPC are [https://ethereum-hoodi-beacon-api.publicnode.com](https://ethereum-hoodi-beacon-api.publicnode.com) and [https://ethereum-hoodi-rpc.publicnode.com](https://ethereum-hoodi-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 theme={null} 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 theme={null} curl http://localhost:13523/v1/validator/get_validators ``` You can also subscribe to notifications to receive real-time updates when validators opt in or when a new epoch starts with opted-in validators. To subscribe to these notifications: ```shell ❯_ terminal theme={null} curl -N -H "Content-Type: application/json" -d '{"topics": ["validator_opted_in", "epoch_validators_opted_in"]}' http://localhost:13523/v1/subscribe ``` This will establish a streaming connection that will send notifications when: * The next block proposer has opted in to the mev-commit protocol (`validator_opted_in`) * A new epoch begins, providing a list of all opted-in validators for that epoch (`epoch_validators_opted_in`) Note proposer selection is only stable within the context of the current epoch, and must be checked during the epoch in question. See specification [here](https://github.com/ethereum/consensus-specs/blob/dev/specs/phase0/validator.md#validator-assignments) and [here](https://github.com/ethereum/consensus-specs/blob/dev/specs/phase0/validator.md#lookahead). ## Configuring custom provider sets Users can also set-up a specific subset of provider nodes in order to send their bids. By default the mev-commit bidder node will send bids to all the available and staked providers. However, if the user wants only a specific subset of providers to be able to see their bids, the can use the `--provider-whitelist` option to set it up. The list should contain the ethereum wallet addresses of the provider nodes. ### Mainnet ```shell ❯_ terminal theme={null} mev-commit --keystore-path ~/.mev-commit \ --keystore-password \ --bootnodes /dnsaddr/bootnode.mev-commit.xyz \ --settlement-rpc-endpoint https://chainrpc.mev-commit.xyz --provider-whitelist 0x6DcE7bcF4fCA9E14b546e583049B82474631b185,0x0979c194EaD08444B6e40415F5822AB32363f580 ``` ### Testnet ```shell ❯_ terminal theme={null} mev-commit --keystore-path ~/.mev-commit \ --keystore-password \ --bootnodes /dnsaddr/bootnode.testnet.mev-commit.xyz \ --settlement-rpc-endpoint https://chainrpc.testnet.mev-commit.xyz --provider-whitelist 0x6DcE7bcF4fCA9E14b546e583049B82474631b185,0x0979c194EaD08444B6e40415F5822AB32363f580 ``` # Using the Bridge UI Source: https://docs.primev.xyz/v1.2.x/get-started/bridge/bridge How to bridge ETH between L1 and mev-commit using the web interface The mev-commit bridge UI provides an intuitive interface for transferring ETH between Ethereum and the mev-commit chain. ## Bridging to mev-commit