# 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.

<Note>The timestamp is specified in Unix milliseconds. For example, a timestamp of `1633046400000` represents `October 1, 2021 00:00:00 GMT`.</Note>

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.

<Frame>
  <img />
</Frame>

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.

<CardGroup>
  <Card title="Launch Fast Swaps" icon="bolt" href="https://fastprotocol.io">
    Start swapping and earning miles.
  </Card>

  <Card title="Fast Swaps Docs" icon="book" href="/v1.2.x/concepts/fast-swaps">
    Technical deep-dive: architecture, contracts, and EIP-712 signing.
  </Card>
</CardGroup>

***

### 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

<Card title="What is Fast Protocol?" icon="circle-question" href="/v1.2.x/knowledge-base/what-is-fast-protocol">
  Simplified FAQ overview of Fast Protocol for newcomers.
</Card>


# 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**.

<Card title="Launch Fast Swaps" icon="bolt" href="https://fastprotocol.io">
  Start swapping at fastprotocol.io
</Card>

***

# 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.

<Steps>
  <Step title="One-time Permit2 approval">
    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.
  </Step>

  <Step title="Sign the swap intent">
    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.
  </Step>

  <Step title="FAST RPC executes the swap">
    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
  </Step>
</Steps>

### ETH Path

When swapping ETH as the input token, the user submits a transaction directly:

<Steps>
  <Step title="Submit the swap transaction">
    The user signs and broadcasts a transaction that calls `executeWithETH` on the FastSettlement contract, sending ETH along with the call.
  </Step>

  <Step title="Contract executes the swap">
    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.
  </Step>
</Steps>

<Info>
  In both paths, the transaction is routed through FAST RPC, which enables mev-commit preconfirmations and mev capture.
</Info>

***

## 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
```

<Info>
  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.
</Info>

### 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

<Warning>
  Always verify the contract address when adding custom tokens. Fast Swaps does not verify the legitimacy of user-added tokens.
</Warning>

***

## 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

<CardGroup>
  <Card title="What are Fast Swaps?" icon="circle-question" href="/v1.2.x/knowledge-base/what-are-fast-swaps">
    Quick FAQ for first-time users.
  </Card>

  <Card title="Fast Swaps Guide" icon="book-open" href="/v1.2.x/get-started/fast-swaps">
    Step-by-step guide to performing your first swap.
  </Card>
</CardGroup>


# 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.

<Frame>
  <img />
</Frame>

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:

<Frame>
  <img alt="" />
</Frame>

### 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.

<Frame>
  <img alt="" />
</Frame>


# 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).

<Frame>
  <img />
</Frame>

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:

<Frame>
  <img />
</Frame>

**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.

<Frame>
  <img />
</Frame>

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:

<Frame>
  <img />
</Frame>

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



<Info>
  If you operate L1 validators, start at the [validator coalition welcome](/v1.2.x/get-started/welcome-to-primev). Opt-in is coalition membership (one signal across many keys), not extra yield from the bid and commitment flow described below.
</Info>

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.

<Frame>
  <img />
</Frame>

## 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.&#x20;

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.&#x20;

## 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.&#x20;

## 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:

<Frame>
  <img />
</Frame>

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.

<Tip>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.</Tip>

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.

<Frame>
  <img />
</Frame>

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.

<Frame>
  <img />
</Frame>

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



This page describes an older points writeup. **Opt-in today is coalition membership**, not extra bid yield. See [Why should validators opt in](/v1.2.x/knowledge-base/why-should-validators-opt-in).

The `mev-commit` Points Program, as originally written, accrued over **6-month Seasons**. Opt in with the [mev-commit-opt-in skill](/v1.2.x/get-started/validators/agentic-opt-in). The old [validator dashboard](https://validators.mev-commit.xyz/) is deprecated.

<img alt="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.

<Note>Stay opted in with as many validators through all seasons for the maximum multiplier bonus.</Note>

***

## 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.

<img alt="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.

<Info>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.</Info>

***

## 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**
   * Opt in with the [mev-commit-opt-in skill](/v1.2.x/get-started/validators/agentic-opt-in).
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.

<Note>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.</Note>

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



Validator opt-in is membership in the [mev-commit validator coalition](/v1.2.x/knowledge-base/why-should-validators-opt-in). Stake or restake is collateral for that roster, not a ticket to extra block revenue today.

Historical bidder and provider pages still describe a commitment market on the mev-commit chain. That is not why L1 validators opt in now, and it is not a live extra yield stream for proposers.

The sections below keep provider slashing notes for that older path, and the validator slashing notes (validators are not slashed for relay choice). Validator "rewards" are coalition membership, later fees, and founding-member tokens. See [Why should validators opt in](/v1.2.x/knowledge-base/why-should-validators-opt-in).

<Tip>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/).</Tip>

## Validators/Proposers

A validator that opts into mev-commit adds keys to the coalition roster (Hub-true). Keep your existing relay set. Opt-in does not pay extra producer rewards from mev-commit bids today.

### What membership is

1. One signal across many keys, used for policy and innovation review
2. Later coalition fees, only after members actively approve them, that fund Ethereum AI research (a step toward about 1% of validator yield)
3. Founding-member tokens, sized to match or exceed fees contributed, used to create proposals for holders to accept

**No fees are enabled at this stage.** There is no fee switch without your approval. Token grants are not live. An older [points](/v1.2.x/concepts/rewards-and-slashing/points) writeup exists; do not treat it as extra bid yield.

<Note>Do not use the old "higher-value blocks from mev-commit bids" story when talking to operators. That is not the current reason to opt in.</Note>

### Slashing

Validators are **not expected to be slashed** on mev-commit. Providers (block builders) are the primary decision makers liable for slashing — they are accountable for honoring the commitments they issued. Validators are not penalized for missed blocks, self-built blocks, or for the builder their relay happened to select.

#### Missed Block

A proposer can completely miss its slot and not include any block in L1. This can happen due to network issues, relay delivery problems, or chain reorgs. mev-commit does not slash proposers for missed blocks — the proposer does not profit from omitting a block and the cause is often outside their control.

#### Block from Non-Registered Builder

A proposer may include a block in L1 that was not produced by a registered mev-commit provider — for example because the highest-value bid that slot came from a non-registered builder. mev-commit does not slash validators for this. Commitment accountability is enforced at the provider layer: if a registered provider issued a commitment for a transaction, breaking that commitment slashes the provider regardless of who ultimately won the slot.

#### Self-Built Block

A proposer can include a block that was built locally rather than through mev-boost. This typically happens when relay-supplied bids are below the locally-built value or when mev-boost falls back due to a fault. mev-commit does not slash proposers for self-built blocks.

## 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 the mev-boost relay set they run for commitment attribution. mev-commit no longer maintains a curated "supporting relays" list — opted-in validators can use any relay, and mev-commit's oracle attributes commitments via standard `proposer_payload_delivered` data.

### 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 their trust and communicate blocks that do not abide by existing commitments. Commitment accountability sits on the provider side — providers that fail to honor commitments are slashed regardless of which relay delivered the block.

### 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

<Card title="Why Should Validators Opt In?" icon="circle-question" href="/v1.2.x/knowledge-base/why-should-validators-opt-in">
  FAQ on validator incentives, earnings, and the opt-in rationale.
</Card>


# 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=<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/<your module>/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:

<CodeGroup>
  ```shell ❯_ structure theme={null}
  curl -X POST http://localhost:13523/v1/bidder/bid \
  -d '{
    "txHashes": [<the hash of the transaction>],
    "amount": <amount in wei>,
    "blockNumber": <l1blocknumber>
    "decayStartTimestamp": <timestamp>,
    "decayEndTimestamp": <timestamp>
  }'
  ```

  ```shell ❯_ example theme={null}
  curl -X POST http://localhost:13523/v1/bidder/bid \
  -d '{
    "txHashes": ["91a89B633194c0D86C539A1A5B14DCCacfD47094"],
    "amount": 10000000000000000,
    "blockNumber": 4123456,
    "decayStartTimestamp": 1716935571901,
    "decayEndTimestamp": 1716935572901
  }'
  ```
</CodeGroup>

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/)   |
| Validator opt-in  | [https://primev.xyz/ai](https://primev.xyz/ai)                         |

# Contracts deployed to mev-commit chain

### **Core Contracts**

<table>
  <thead>
    <tr>
      <th>Contract</th>
      <th>Address</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>BidderRegistry</td>
    </tr>

    <tr>
      <td>ProviderRegistry</td>
    </tr>

    <tr>
      <td>PreconfManager</td>
    </tr>

    <tr>
      <td>Oracle</td>
    </tr>

    <tr>
      <td>BlockTracker</td>
    </tr>
  </tbody>
</table>

### **Settlement Bridge Gateway**

<table>
  <thead>
    <tr>
      <th>Contract</th>
      <th>Address</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>SettlementGateway</td>
    </tr>
  </tbody>
</table>

# Contracts deployed to L1 Ethereum

### **L1 Bridge Gateway**

<table>
  <thead>
    <tr>
      <th>Entity</th>
      <th>Address Type</th>
      <th>Address</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>L1Gateway</td>
      <td>Proxy</td>
    </tr>

    <tr>
      <td>Implementation</td>
    </tr>
  </tbody>
</table>

### **L1 Validator Registries**

<table>
  <thead>
    <tr>
      <th>Contract</th>
      <th>Address Type</th>
      <th>Address</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>MevCommitAVS</td>
      <td>Proxy</td>
    </tr>

    <tr>
      <td>Implementation</td>
    </tr>

    <tr>
      <td>MevCommitMiddleware</td>
      <td>Proxy</td>
    </tr>

    <tr>
      <td>Implementation</td>
    </tr>

    <tr>
      <td>VanillaRegistry</td>
      <td>Proxy</td>
    </tr>

    <tr>
      <td>Implementation</td>
    </tr>

    <tr>
      <td>Reputational VanillaRegistry</td>
      <td>Proxy</td>
    </tr>

    <tr>
      <td>Implementation</td>
    </tr>

    <tr>
      <td>ValidatorOptInRouter</td>
      <td>Proxy</td>
    </tr>

    <tr>
      <td>Implementation</td>
    </tr>

    <tr>
      <td>ValidatorOptInHub</td>
      <td>Proxy</td>
    </tr>

    <tr>
      <td>Implementation</td>
    </tr>
  </tbody>
</table>

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

<table>
  <thead>
    <tr>
      <th>Description</th>
      <th>Address</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Primev Team Multisig</td>
    </tr>

    <tr>
      <td>Commitment Holdings Multisig</td>
    </tr>

    <tr>
      <td>Symbiotic "network address" (Served by Primev Team Multisig)</td>
    </tr>
  </tbody>
</table>

# 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)**

<table>
  <thead>
    <tr>
      <th>Contract</th>
      <th>Address</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>BidderRegistry</td>
    </tr>

    <tr>
      <td>ProviderRegistry</td>
    </tr>

    <tr>
      <td>PreconfManager</td>
    </tr>

    <tr>
      <td>Oracle</td>
    </tr>

    <tr>
      <td>BlockTracker</td>
    </tr>
  </tbody>
</table>

### **Bridge Gateway (mev-commit chain)**

<table>
  <thead>
    <tr>
      <th>Contract</th>
      <th>Address</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>SettlementGateway</td>
    </tr>

    <tr>
      <td>L1Gateway</td>
    </tr>
  </tbody>
</table>

### **Validator Registry Contract Addresses (Hoodi)**

<table>
  <thead>
    <tr>
      <th>Contract</th>
      <th>Address</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>ValidatorOptInRouter</td>
    </tr>

    <tr>
      <td>ValidatorOptInHub</td>
    </tr>

    <tr>
      <td>VanillaRegistry</td>
    </tr>

    <tr>
      <td>MevCommitAVS</td>
    </tr>

    <tr>
      <td>MevCommitMiddleware</td>
    </tr>

    <tr>
      <td>Lido Registry</td>
    </tr>

    <tr>
      <td>RocketMinipoolRegistry</td>
    </tr>
  </tbody>
</table>

### **Other addresses (Hoodi)**

<table>
  <thead>
    <tr>
      <th>Entity</th>
      <th>Address</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Mev-commit (Symbiotic) Network Address</td>
    </tr>

    <tr>
      <td>Mev-commit (Symbiotic) Vault Address</td>
    </tr>

    <tr>
      <td>Mev-commit (Symbiotic) Subnetwork</td>
    </tr>
  </tbody>
</table>

## 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/providers/registering-a-provider#querying-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": "<amount in wei>",
    "blockNumber": <integer l1blocknumber>,
    "decayStartTimestamp": <timestamp milliseconds>,
    "decayEndTimestamp": <timestamp milliseconds>,
    "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": "<amount in wei>",
    "blockNumber": <integer l1blocknumber>,
    "decayStartTimestamp": <timestamp milliseconds>,
    "decayEndTimestamp": <timestamp milliseconds>,
    "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.

<Note> 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.</Note>

```shell ❯_ example theme={null}
./bidder-cli send-tx \
  --from <PRIVATE KEY of source account> \
  --to <DESTINATION on L1 chain> \
  --value <Amount of ETH to be sent in wei> \
  --bid-amount <Amount to be sent to provider node> \
  --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 <HASH 1> \
  --tx-hashes <HASH 2> \
  --bid-amount <Amount to be sent to provider node> \
  --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.

<Note>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.</Note>

## 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"
}
```

<Tip>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.</Tip>

## 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=<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 <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 <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

<Info>
  The hosted bridge UI at mev-commit.xyz/bridge is decommissioned. That path now redirects here. Use the [Bridge CLI](/v1.2.x/get-started/bridge/bridge-cli) to move ETH. The steps below describe the old UI for reference.
</Info>

The old mev-commit bridge UI transferred ETH between Ethereum and the mev-commit chain.

## Bridging to mev-commit

<video />

1. Visit [mev-commit.xyz/bridge](https://www.mev-commit.xyz/bridge)
2. Connect your wallet when prompted
3. Select Ethereum as the source chain and mev-commit as the destination chain
4. Enter the amount of ETH you want to transfer
5. Click "Bridge" and approve the transaction in your wallet
6. Wait for the bridging transaction to complete (approximately 15 minutes for L1 finality)

## Bridging from mev-commit

<Frame>
  <img />
</Frame>

1. Visit [mev-commit.xyz/bridge](https://www.mev-commit.xyz/bridge)
2. Connect your wallet when prompted
3. Select mev-commit as the source chain and Ethereum as the destination chain
4. Enter the amount of ETH you want to transfer
5. Click "Bridge" and approve the transaction in your wallet
6. Transaction should complete within a few minutes

Note: A fixed fee of 0.005 ETH is charged when bridging from mev-commit to L1 to cover relayer costs.

For advanced users, programmatic access, or automation needs, the bridge CLI tool is also available - see [Bridge CLI](/v1.2.x/get-started/bridge-cli) for details.


# Bridge CLI
Source: https://docs.primev.xyz/v1.2.x/get-started/bridge/bridge-cli



<p> The mev-commit chain uses native ETH that must be bridged from L1 using our lock and mint bridge. A user CLI application can be downloaded from the [releases page](https://github.com/primev/mev-commit/releases/latest). </p>

You can confirm your operating system and architecture by running `uname -sm`.

Or use the following command which automatically downloads and extracts the latest bridge user CLI binary for your system into your \$HOME directory:

```shell theme={null}
curl -Ls $(curl -s https://api.github.com/repos/primev/mev-commit/releases \
  | grep browser_download_url \
  | grep "mev-commit-bridge-user-cli_[0-9].*$(uname -s)_$(uname -m)\.tar\.gz" \
  | cut -d '"' -f 4 \
  | head -n1) | tar -xz -C ~
```

The binary will then be available in your \$HOME directory as `user-cli`.

<Note>In order to bridge funds, users need to have an account which is funded with mainnet ETH. </Note>

<CodeGroup>
  ```bash ❯_ bridge to settlement chain from L1 theme={null}
  user-cli bridge-to-settlement \
  	--account-key <Private Key of source account> \
  	--dest-addr <Address to fund on the mev-commit chain> \
  	--amount <Amount in Wei>
  ```

  ```bash ❯_ bridge to L1 from settlement chain theme={null}
  user-cli bridge-to-l1 \
  	--account-key <Private Key of source account> \
  	--dest-addr <Address to fund on the mev-commit chain> \
  	--amount <Amount in Wei>
  ```
</CodeGroup>

<Accordion title="Testnet command">
  ```bash ❯_ bridge to settlement chain from L1 theme={null}
  user-cli bridge-to-settlement \
          --account-key $PRIVATE_KEY \
          --dest-addr $DEST_ADDR \
          --amount $AMOUNT_IN_WEI \
          --l1-rpc-url https://0xrpc.io/hoodi \
          --settlement-rpc-url https://chainrpc.testnet.mev-commit.xyz \
          --l1-contract-addr 0x0b3b6Cf113959214E313d6Ad37Ad56831acb1776 \
          --settlement-contract-addr 0xFaF6F0d4bbc7bC33a4b403b274aBb82d0E794202
  ```
</Accordion>

A static fee is charged for bridging from the mev-commit chain to L1, to compensate the relayer for transaction inclusion. This fee is currently set to 0.005 ETH.

<Note> Users can also use a keystore file instead of using the private key. </Note>

<Note> CLI currently uses default contract addresses for mainnet and default mainnet RPC endpoints. Users can use separate RPC URLs using the respective options. </Note>

<p> To check other options available in the user CLI, users can use the `-h` option </p>

```
./user-cli -h
NAME:
   mev-commit-bridge-user-cli - CLI for interacting with a custom bridge between L1 and the mev-commit (settlement) chain

USAGE:
   mev-commit-bridge-user-cli [global options] command [command options]

COMMANDS:
   bridge-to-settlement  Submit a transaction to bridge ether to the settlement chain
   bridge-to-l1          Submit a transaction to bridge ether back to L1
   help, h               Shows a list of commands or help for one command

GLOBAL OPTIONS:
   --help, -h  show help

```

```
./user-cli bridge-to-settlement -h
NAME:
   mev-commit-bridge-user-cli bridge-to-settlement - Submit a transaction to bridge ether to the settlement chain

USAGE:
   mev-commit-bridge-user-cli bridge-to-settlement [command options]

OPTIONS:
   --account-key value               private key of the account to use for signing transactions in hex encoding [$ACCOUNT_KEY]
   --keystore-path value             path to keystore location [$MEV_ORACLE_KEYSTORE_PATH]
   --keystore-password value         use to access keystore [$MEV_ORACLE_KEYSTORE_PASSWORD]
   --amount value                    amount of ether to bridge in wei [$AMOUNT]
   --dest-addr value                 destination address on the mev-commit (settlement) chain [$DEST_ADDR]
   --l1-rpc-url value                URL for L1 RPC [$L1_RPC_URL]
   --settlement-rpc-url value        URL for settlement RPC [$SETTLEMENT_RPC_URL]
   --l1-contract-addr value          address of the L1 gateway contract [$L1_CONTRACT_ADDR]
   --settlement-contract-addr value  address of the settlement gateway contract [$SETTLEMENT_CONTRACT_ADDR]
   --silent                          disable spinner (default: false) [$SILENT]
   --help, -h                        show help
```

<Note> The current bridge waits for finalization. Thus when moving funds from L1 to the settlement chain, users will have to wait for at least 15 mins (L1 finalization time) before getting a confirmation. Conversely, bridging from settlement to L1 chain will be significantly faster (less than 1 second settlement chain finalization time). </Note>

After the bridge is successful, the following command can be used to check their mev-commit chain balance

### Mainnet

```
curl -L https://foundry.paradigm.xyz | bash && foundryup && cast balance mev_commit_mainnet_address --rpc-url https://chainrpc.mev-commit.xyz/
```

### Testnet

```
curl -L https://foundry.paradigm.xyz | bash && foundryup && cast balance mev_commit_testnet_address --rpc-url https://chainrpc.testnet.mev-commit.xyz/
```


# Settlement explorer
Source: https://docs.primev.xyz/v1.2.x/get-started/explorer

The public mev-commit explorer is decommissioned. Apex now redirects to the validator opt-in page.

<Info>
  The public explorer at [mev-commit.xyz](https://mev-commit.xyz) is decommissioned. That host now redirects to [primev.xyz/ai](https://primev.xyz/ai), the validator opt-in homepage. The app is archived in [primev/mev-commit-ui](https://github.com/primev/mev-commit-ui) (`apps/xplorer`) and can be restored from there.
</Info>

It was a settlement-chain explorer for the mev-commit chain (Chain ID 57173): decoded contract calls, block and transaction feeds, and address lookup. Those routes are not served on a public host anymore.

## What it used to show

| Contract              | Purpose                                                   |
| --------------------- | --------------------------------------------------------- |
| **PreconfManager**    | Preconfirmation commitments between bidders and providers |
| **BidderRegistry**    | Bidder registrations and deposits                         |
| **ProviderRegistry**  | Provider registrations and stakes                         |
| **Oracle**            | Settles commitments from L1 block outcomes                |
| **BlockTracker**      | L1 block numbers for settlement                           |
| **SettlementGateway** | Cross-chain settlement                                    |

Query the chain directly if you need the same data: RPC `https://chainrpc.mev-commit.xyz`, Chain ID `57173`. See [chain details](/v1.2.x/concepts/mev-commit-chain/chain-details).

For validator opt-in use [primev.xyz/ai](https://primev.xyz/ai) or the [agentic opt-in guide](/v1.2.x/get-started/validators/agentic-opt-in).


# Fast Swaps
Source: https://docs.primev.xyz/v1.2.x/get-started/fast-swaps

Your first token swap on Fast Swaps — a step-by-step guide

This guide walks you through performing your first token swap on [Fast Swaps](https://fastprotocol.io). By the end, you will have swapped tokens on Ethereum with near-instant preconfirmations and started earning mev rewards (Fast Miles).

<Info>
  **What you need before starting:**

  * A web browser (Chrome, Firefox, or Brave recommended)
  * A wallet extension installed ([MetaMask](https://metamask.io) or [Rabby](https://rabby.io) recommended)
  * ETH in your wallet for gas fees (if swapping ETH) or for the one-time token approval
  * The tokens you want to swap
</Info>

***

<Steps>
  <Step title="Go to Fast Swaps">
    Open your browser and navigate to **[fastprotocol.io](https://fastprotocol.io)**.

    You will see the Fast Swaps landing page with the swap interface.

    <Frame>
      <img alt="Fast Swaps landing page" />
    </Frame>
  </Step>

  <Step title="Connect Your Wallet">
    Click the **Connect Wallet** button in the top-right corner of the page.

    A wallet selection modal will appear. Choose your wallet provider:

    * **MetaMask**
    * **Rabby**
    * **WalletConnect** (for mobile wallets or other providers)

    Your wallet extension will prompt you to approve the connection. Confirm the connection in your wallet.

    <Tip>
      Make sure your wallet is set to **Ethereum Mainnet**. For the best experience, set your Ethereum RPC to [FAST RPC](/v1.2.x/get-started/fastrpc) (`https://fastrpc.mev-commit.xyz`). This enables preconfirmations and mev rewards on all your Ethereum transactions — not just Fast Swaps. See the [FAST RPC setup guide](/v1.2.x/get-started/fastrpc#usage-for-wallets) for instructions.
    </Tip>
  </Step>

  <Step title="Select the Token You Want to Sell">
    The swap interface has two sections: **Sell** (top) and **Buy** (bottom).

    Click the token selector dropdown in the **Sell** section. By default, it shows ETH.

    A token selector modal opens where you can:

    * **Search** by token name, symbol, or contract address
    * **Browse popular tokens** in the quick-select bar (ETH, DAI, USDT, WBTC)
    * **Add a custom token** by pasting any ERC-20 contract address

    Select the token you want to sell. For this guide, we will use **ETH**.

    <Frame>
      <img alt="Token selector modal" />
    </Frame>
  </Step>

  <Step title="Select the Token You Want to Buy">
    Click the token selector button in the **Buy** section and choose your desired output token. For this guide, we will select **USDC**.

    <Tip>
      You can click the **switch button** (↕) between the Sell and Buy sections to reverse the swap direction at any time.
    </Tip>
  </Step>

  <Step title="Enter the Swap Amount">
    Click the amount field in the **Sell** section and type the amount you want to swap. For example, enter `0.1` to swap 0.1 ETH.

    As you type, Fast Swaps automatically:

    * **Fetches a real-time quote** via a competitive solver auction
    * **Displays the output amount** in the Buy section (with USD equivalent)
    * **Shows the exchange rate** between the two tokens
    * **Shows price impact** — the effect your trade has on the market price

    The quote refreshes every **15 seconds**. A countdown timer next to the exchange rate shows when the next refresh will occur.

    <Frame>
      <img alt="Swap form with quote" />
    </Frame>
  </Step>

  <Step title="Review Swap Details">
    Before confirming, review the swap details displayed below the Buy section:

    | Detail            | What It Means                                                                                                                        |
    | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
    | **Exchange Rate** | How much of the output token you get per unit of input token, with a countdown timer showing when the quote refreshes                |
    | **Price Impact**  | How much your swap moves the market price — green is negligible, yellow is moderate, red means you may want to reduce your swap size |

    ### Adjust Settings (Optional)

    Click the **gear icon** (⚙) next to the Swap heading to open settings. Here you can adjust:

    * **Max slippage** — The maximum price movement you are willing to accept (default: 0.5%). You can set a custom percentage.
    * **Swap deadline** — How long (in minutes) the swap remains valid before it expires (default: 30 minutes).

    <Frame>
      <img alt="Swap settings panel" />
    </Frame>

    <Warning>
      Setting slippage too low may cause the swap to fail if the price moves. Setting it too high may result in a worse exchange rate.
    </Warning>
  </Step>

  <Step title="Approve the Token (First Time Only)">
    <Info>
      **This step only applies to ERC-20 token swaps** (e.g., USDC → ETH). If you are swapping **ETH as the input token**, skip to the next step.
    </Info>

    If this is your first time swapping a particular ERC-20 token on Fast Swaps, you need to approve the **Permit2** contract to access that token. This is a one-time on-chain transaction per token.

    Click the **Approve** button. Your wallet will prompt you to confirm the approval transaction.

    <Tip>
      If you have previously approved this token for Permit2 on another app (like Uniswap), you will not need to approve it again.
    </Tip>

    Once the approval transaction confirms, the button changes to **Swap**.
  </Step>

  <Step title="Confirm the Swap">
    Click the **Swap** button to initiate the swap.

    A confirmation modal appears showing the full details of your swap, including input and output amounts, the exchange rate, price impact, minimum received after slippage, and estimated gas cost.

    Review the details and click **Confirm Swap**.
  </Step>

  <Step title="Sign in Your Wallet">
    Your wallet will prompt you to sign the transaction:

    * **For ERC-20 input tokens**: You will sign an **EIP-712 message** (a signature, not a transaction). This is gasless — you do not pay gas at this step.
    * **For ETH input**: You will sign and submit an **on-chain transaction**. This requires gas.

    Confirm the signature or transaction in your wallet.
  </Step>

  <Step title="Receive Preconfirmation">
    Within seconds of signing, your swap is **preconfirmed**. A confirmation toast appears at the bottom of the screen.

    **Preconfirmed** means Ethereum block builders on the [mev-commit](/v1.2.x/concepts/mev-commit-intro/what-is-mev-commit) network have committed to including your swap in an upcoming block. This gives you near-instant confidence that your swap will settle — no need to wait for the full block to be produced.

    This is the core Fast Swaps experience: your swap feels **instant**.

    <Accordion title="What happens after preconfirmation?">
      After the preconfirmation, your swap progresses to full on-chain confirmation in the background. The toast will update once the swap is included in a finalized Ethereum block. You do not need to wait for this — the preconfirmation is your signal that the swap is done.

      | Status           | What It Means                                                                                                      |
      | ---------------- | ------------------------------------------------------------------------------------------------------------------ |
      | **Pending**      | Your swap intent has been submitted to FAST RPC                                                                    |
      | **Preconfirmed** | Ethereum block builders on mev-commit have committed to including your transaction — your swap is effectively done |
      | **Confirmed**    | The swap has been included in a finalized Ethereum block. Your output tokens are fully settled on-chain            |
    </Accordion>
  </Step>

  <Step title="Swap Complete">
    Once fully confirmed on-chain, the toast updates with a link to the transaction on Etherscan.

    Your output tokens are now in your wallet. The swap form resets, ready for your next trade.

    You will see an **Earning Fast Rewards** indicator below the swap card — this confirms you are accumulating Fast Miles. Check your miles balance from the **My Miles** tab in the top navigation.
  </Step>
</Steps>

***

## Earn Fast Miles

Every swap you make on Fast Swaps earns **Fast Miles** — mev rewards proportional to the value your swaps generate through [Fast Protocol](/v1.2.x/concepts/fast-protocol). The more you swap, the more miles you earn. Users receive at least **90%** of the mev their transactions generate.

Click **My Miles** in the top navigation bar to view your miles balance and swap history.

<CardGroup>
  <Card title="View Dashboard" icon="chart-line" href="https://fastprotocol.io/dashboard">
    Check your Fast Miles balance, swap history, and leaderboard position.
  </Card>

  <Card title="Leaderboard" icon="trophy" href="https://fastprotocol.io/leaderboard">
    See how you rank against other Fast Swaps users.
  </Card>
</CardGroup>

***

## Tips & Troubleshooting

<Accordion title="My swap is taking a long time">
  Ethereum block times are approximately 12 seconds. Most swaps are preconfirmed within seconds and fully confirmed within 1-2 blocks (12-24 seconds). If a swap takes longer:

  * Check your wallet for any pending transactions
  * The swap may be waiting for a mev-commit opted-in proposer — see [FAST RPC](/v1.2.x/get-started/fastrpc) for details
  * If the swap times out (exceeds your deadline), it will automatically cancel and your tokens will remain in your wallet
</Accordion>

<Accordion title="My swap failed — what happened?">
  Common reasons for swap failure:

  * **Slippage exceeded** — The price moved more than your max slippage setting between quote and execution. Try increasing slippage via the gear icon (⚙).
  * **Insufficient balance** — Make sure you have enough of the input token plus ETH for gas (if swapping ETH).
  * **Deadline expired** — The swap was not executed before the swap deadline. Try again with a fresh quote.
  * **Price impact too high** — For large swaps, try splitting into smaller amounts.
</Accordion>

<Accordion title="I approved a token but still see the Approve button">
  The Permit2 approval may still be confirming on-chain. Wait for the approval transaction to be mined (check your wallet's activity tab), then refresh the page.
</Accordion>

<Accordion title="Can I swap any token?">
  Fast Swaps supports any ERC-20 token with on-chain liquidity on Ethereum. If a token does not appear in the default list, you can add it by pasting its contract address in the token selector search bar. Always verify the contract address from a trusted source like [Etherscan](https://etherscan.io) or [CoinGecko](https://coingecko.com).
</Accordion>

<Accordion title="Do I need ETH for gas?">
  * **Swapping ERC-20 tokens** (e.g., USDC → ETH): After the initial one-time Permit2 approval, subsequent swaps are **gasless** — you only sign a message.
  * **Swapping ETH** (e.g., ETH → USDC): You submit an on-chain transaction and pay standard Ethereum gas fees.
  * **First-time token approval**: The one-time Permit2 approval requires a small amount of ETH for gas.
</Accordion>

***

## What's Next?

<CardGroup>
  <Card title="How Fast Swaps Works" icon="gears" href="/v1.2.x/concepts/fast-swaps">
    Learn about the technical architecture, smart contracts, and mev reward mechanics behind Fast Swaps.
  </Card>

  <Card title="Fast Protocol Economics" icon="coins" href="/v1.2.x/concepts/fast-protocol">
    Understand how mev is captured, distributed, and why users receive at least 90% of the mev their transactions generate.
  </Card>

  <Card title="FAST RPC" icon="forward-fast" href="/v1.2.x/get-started/fastrpc">
    Learn about the FAST RPC that powers preconfirmations and mev capture for Fast Swaps.
  </Card>

  <Card title="What are Fast Swaps?" icon="circle-question" href="/v1.2.x/knowledge-base/what-are-fast-swaps">
    Quick FAQ on Fast Swaps fundamentals.
  </Card>
</CardGroup>


# FAST RPC
Source: https://docs.primev.xyz/v1.2.x/get-started/fastrpc



The FAST RPC is a drop-in replacement for standard Ethereum RPC transaction sending endpoints that enables dapps and wallets to easily obtain preconfirmations. Users interact with the RPC like they would with a normal Ethereum node (via `eth_sendRawTransaction`, `eth_getTransactionReceipt`, etc.), but under the hood, the RPC leverages mev-commit to coordinate a decentralized network of block builders who issue and honor transaction commitments. Additionally, the RPC also provides additional methods (such as `mevcommit_getTransactionCommitments`) for advanced use cases. See [FAST RPC API](/v1.2.x/developers/fast-rpc-api) for an overview of the supported methods.

<Columns>
  <Card title="For dApps" icon="code">
    <p><span>[FAST RPC Usage Instructions for dApps](#usage-for-dapps)</span></p>
  </Card>

  <Card title="For Wallets" icon="wallet">
    <p><span>[Usage Instructions for Wallets](#usage-for-wallets)</span></p>&#x20;
  </Card>
</Columns>

## How it Works

Users first configure their application to use the FAST RPC. Since fees are paid through a pre-funded gas tank, the user needs to deposit some ETH before sending transactions. For basic usage, the RPC can then be used transparently as any other Ethereum RPC. In particular, `eth_sendRawTransaction` is used to send transactions to the RPC. Instead of sending the transaction to the public mempool, the RPC instead sends encrypted bids to block builders in the mev-commit network. Once all registered block builders have issued a commitment and if the next block proposer is opted in, the RPC considers the transaction as preconfirmed. From that point on, `eth_getTransactionReceipt` will return a receipt for that transaction, including a special block hash, that can be used to call `eth_getBlockByHash`. That call will in turn return a special block that only contains this specific preconfirmed transaction. This ensures compatibility with existing wallets to recognize preconfirmed transactions.

The RPC is designed to integrate easily into existing tools and infrastructure. That means after setup, basic usage is equivalent to using any regular RPC, except that transactions quickly get preconfirmed.

## Usage for dApps

This guide walks you through integrating and using the FAST RPC into your DApp to obtain preconfirmations for Ethereum transactions.

<Steps>
  <Step title="Point your application to the FAST RPC">
    To start using the FAST RPC, configure your application or wallet to use the following RPC endpoint:

    ```
    https://fastrpc.mev-commit.xyz
    ```

    This replaces your standard Ethereum RPC URL (e.g., from Infura or Alchemy).
  </Step>

  <Step title="Deposit funds in the gas tank">
    Before submitting transactions through the FAST RPC, you must fund your gas tank. This is an internal balance used to pay for preconfirmation bids. Use the following RPC method to initiate the deposit process: `mevcommit_estimateDeposit`. This call returns:

    * A deposit address (Ethereum address owned by the FAST RPC service),
    * A bid amount, representing the cost of confirming your initial deposit.
      Once you receive these details, fund the deposit address by sending a regular EOA transfer as described in the next step to the deposit address. The deposited amount will be the amount you send minus the bid amount.

    <Info>
      The deposit transaction will already be preconfirmed in the same way as all future transactions via the RPC.
    </Info>
  </Step>

  <Step title="Submit transactions">
    You can send transactions via the FAST RPC as usual using `eth_sendRawTransaction`.

    <Warning>
      Since fees are handled via mev-commit using the gas tank, the priority fee of the transaction should always be set to 0. To reflect this, the method `eth_maxPriorityFeePerGas` of the RPC therefore always returns 0.
    </Warning>
  </Step>

  <Step title="Monitor preconf status">
    To monitor the transaction status, you can as usual use the method `eth_getTransactionReceipt`. The FAST RPC will already return a receipt once a preconfirmation is obtained from all providers and if the next block proposer is opted in.

    For more detailed information, you can also call `mevcommit_getTransactionCommitments`. This method takes the transaction hash as input and returns the commitments received for that transactions on the mev-commit network. This can be useful for advanced decision making in case `eth_getTransactionReceipt` does not return a receipt, e.g., if the block proposer is not opted in or if some, but not all, providers have committed to a transaction.
  </Step>
</Steps>

### Additional Features

Some useful additional features are described here. For an overview of the full available functionality see [FAST RPC API](/v1.2.x/developers/fast-rpc-api).

#### Checking current deposit balance

The balance available in the deposit for future transactions can be checked using `mevcommit_getBalance`. Once this balance runs low, it should be topped up as in the initial deposit described above.

#### Checking for opted in validators

The RPC only issues preconfs via `eth_getTransactionReceipt` if the next block proposer is opted into mev-commit. The DApp may therefore want to adjust its strategy based on whether the next proposers are opted in or not. To enable this, the FAST RPC provides the method `mevcommit_optedInBlock`, which returns the time in seconds until the next block with a mev-commit opted-in proposer.

## Usage for Wallets

<Info>
  **No deposit required — for a limited time, the FAST RPC sponsors your transactions.** Simply add the RPC to your wallet, set your priority fee to `0`, and transact as normal. The RPC will cover your preconfirmation fees, preconfirm your transactions, and rebalance any MEV generated back to your address.
</Info>

Configure the RPC in your wallet with the values below. The old helper page at `/fastrpc` now redirects here.

<Frame>
  <img />
</Frame>

### Manual Setup

<Steps>
  <Step title="Add the FAST RPC to your wallet">
    Open your wallet's **Add Custom RPC** or **Add Network** screen and enter:

    | Field           | Value                            |
    | --------------- | -------------------------------- |
    | Network Name    | Ethereum Mainnet                 |
    | RPC URL         | `https://fastrpc.mev-commit.xyz` |
    | Chain ID        | `1`                              |
    | Currency Symbol | ETH                              |
    | Block Explorer  | `https://etherscan.io`           |

    This replaces your standard Ethereum RPC URL (e.g., from Infura or Alchemy) with the FAST RPC.
  </Step>

  <Step title="Set priority fee to 0">
    When sending transactions, set your priority fee to `0`. The FAST RPC handles preconfirmation fees on your behalf — you do not need to pay any extra tip.
  </Step>

  <Step title="Transact with preconfirmations">
    Send ETH, use a dApp, or mint an NFT on mainnet with blazing speed. Your transactions are preconfirmed by mev-commit's decentralized network of block builders.
  </Step>
</Steps>

***

## Learn More

<CardGroup>
  <Card title="FAST RPC API Reference" icon="code" href="/v1.2.x/developers/fast-rpc-api">
    Full API method documentation.
  </Card>

  <Card title="What is Fast Protocol?" icon="circle-question" href="/v1.2.x/knowledge-base/what-is-fast-protocol">
    FAQ on how FAST RPC fits into Fast Protocol.
  </Card>
</CardGroup>


# Consuming Bids from mev-commit
Source: https://docs.primev.xyz/v1.2.x/get-started/providers/consuming-bids



Providers that have registered in the mev-commit registry will automatically start receiving bids on the mev-commit p2p network from bidders. In order to see incoming bids, providers need to communicate with their mev-commit node:

Use the official go RPC client to communicate with your mev-commit node. Go get the mev-commit package and then import the generated client as below:

<Steps>
  <Step title="Install the mev-commit package">
    ```bash ❯_ terminal theme={null}
    go install github.com/primev/mev-commit@latest
    ```
  </Step>

  <Step title="Incorporate the generated client into your Go application as follows">
    ```go theme={null}
    import providerapiv1 "github.com/primev/mev-commit/p2p/gen/go/providerapi/v1"

    conn, err = grpc.DialContext(
    	context.Background(),
    	"localhost:13524",
    	grpc.WithBlock(),
    	grpc.WithTransportCredentials(insecure.NewCredentials()),
    )

    if err != nil {
    	// handle error
    }

    client := providerapiv1.NewProviderClient(conn)

    bidStream, err := client.ReceiveBids(context.Background(), &providerapiv1.EmptyMessage{})
    if err != nil {
    	// handle error
    }

    bidC := make(chan *providerapiv1.Bid)
    go func() {
    	defer close(bidC)
    	for {
    		bid, err := bidStream.Recv()
    		if err != nil {
    			// handle error
    		}
    		select {
    		case <-bidStream.Context().Done():
    		case bidC <- bid:
    		}
    	}
    }()

    stream, err := client.SendProcessedBids(context.Background())
    if err != nil {
    	// handle error
    }

    for bid := range bidS {
    	// check the bid details and communicate with the block-building
    	// infrastructure to make a decision
    	status := getDecision(bid)

    	err := stream.Send(&providerapiv1.BidResponse{
    			BidDigest: bid.BidDigest,
    			Status:    status,
    	})
    	if err != nil {
    		// handle error
    	}
    }
    ```

    There is an [example implementation](https://github.com/primev/mev-commit/tree/main/p2p/examples/provideremulator) of a dummy provider client which blindly accepts all the bids it sees from its mev-commit node. This could be a good starting point for providers implementing their commitment decision logic in golang.
  </Step>
</Steps>

### Alternative Methods

1. Use [https://github.com/fullstorydev/grpcurl](https://github.com/fullstorydev/grpcurl) or [https://github.com/bloomrpc/bloomrpc](https://github.com/bloomrpc/bloomrpc) or other GUI clients like [Postman](https://www.postman.com). Relevant protobuf files are available in the [mev-commit repository](https://github.com/primev/mev-commit).
2. Check the [API docs](/v1.2.x/api-reference/introduction) to use the REST APIs. The RPC APIs are also available on the HTTP server.
3. Users can use the protobuf files to generate a client in language of their choice.


# Registering as a Provider
Source: https://docs.primev.xyz/v1.2.x/get-started/providers/registering-a-provider



To register on the mev-commit network, providers need to stake ETH in the provider registry contract. This adds credibility to issued commitments, as stake may be slashed in the event of a broken commitment, such as committing to a preconfirmation bid and not including the relevant transaction in a block.

<Warning>Providers must adhere to some rules and satisfy some criteria described [here](/v1.2.x/concepts/actors#rules-for-providers).</Warning>

<Note>
  **Validator opt-in status and proposal eligibility.** Registered providers are eligible to win blocks for **any** validator slot — there is no longer a relay-side filter restricting opted-in proposers to registered builders. Your builder competes for every slot on its merits.

  **Forthcoming: rewards contract.** A future protocol upgrade will introduce a rewards contract that providers winning blocks for opted-in proposers must route through as the block's `fee_recipient`. The contract takes a protocol fee from the producer reward and forwards the remainder to the validator's registered fee recipient. The fee is dynamic, bounded so opting in remains net-positive for validators. Specifications and activation timing will be published before this is enabled.
</Note>

Once a provider is registered on the network, other nodes will connect to it, and the provider node will receive bids.

You can use the provider API to stake and check your stake balance.

<Steps>
  <Step title="Launch mev-commit Node">
    Make sure you've [funded your account and launched a mev-commit node](/v1.2.x/get-started/quickstart) first.
  </Step>

  <Step title="Check Minimum Stake Amount">
    Check the minimum amount that can be staked, and consider staking more than the minimum. Bidders will only connect to providers which have stake higher than this minimum. The larger a provider's stake, the greater the credibility behind that provider's commitments. The amount is set in `wei`.

    ```shell theme={null}
    > curl localhost:13523/v1/provider/get_min_stake | jq
    {
      "amount": "1000000000000000000"
    }
    ```
  </Step>

  <Step title="Get Provider's Ethereum Address">
    Get your provider's Ethereum address from the topology endpoint. This will be used as the challenge message for BLS signing:

    ```shell theme={null}
    > curl localhost:13523/v1/debug/topology | jq .self."Ethereum Address"
    "0xB9286CB4782E43A202BfD426AbB72c8cb34f886c"
    ```
  </Step>

  <Step title="Generate BLS Signature">
    <Warning>
      Rewards on mev-commit now rely on the BLS key found in the relay and are then tied to the BLS key registered. The BLS key that is sending messages to the relay should be registered. This registration can now be done automatically without manual intervention. Once the registration is done, the settlement chain will be able to correctly attribute the winning providers on L1.
    </Warning>

    Download the bls-signer tool from the releases page and use it to generate your signature:

    ```shell theme={null}
    > bls-signer --private-key YOUR_BLS_PRIVATE_KEY --payload 0xB9286CB4782E43A202BfD426AbB72c8cb34f886c
    Payload: 0xB9286CB4782E43A202BfD426AbB72c8cb34f886c
    Public Key: 0x8e7884b3c4961550c13c87c0d0d30bdf8f3c9f3b5e0fb6259b2d1dc8c93432fac8f55d8c0f9e4f2a0f7d0a7b9b9f5d1
    Signature: 0xa1b2c3... # Your actual signature will be different
    ```

    Make note of both the public key and signature outputs - you'll need these in the next step.
  </Step>

  <Step title="Submit Stake Registration">
    <Info>
      You can map multiple BLS keys to a single stake registration by including multiple public keys and signatures in the arrays. This allows you to use different BLS keys while maintaining a single stake amount.
    </Info>

    Register your stake by submitting:

    * The stake amount (in wei)
    * Your BLS public key from the previous step
    * The BLS signature you generated

    Here's an example request:

    ```shell theme={null}
    # Replace with your actual values from the previous step
    > curl -sS -X POST "http://localhost:13523/v1/provider/stake/{AMOUNT}?bls_public_keys=${PK1}&bls_public_keys=${PK2}&bls_signatures=${SG1}&bls_signatures=${SG2}" | jq
    ```
  </Step>

  <Step title="Verify Registration">
    Once staked, peer connection logs should appear within a few minutes. You can check the `/topology` endpoint again to verify connected peers.
  </Step>
</Steps>

<Check>Congrats, your provider node is registered on mev-commit and you're ready to [consume bids](/v1.2.x/get-started/providers/consuming-bids).</Check>

Be sure to view [Querying for Proposers API](/v1.2.x/get-started/bidders/bidder-node-commands#querying-for-proposers-api) for information on detecting mev-commit opted-in Ethereum validators. Other commands that can be used are:

* Check stake balance

  ```shell theme={null}
  > curl localhost:13523/v1/provider/get_stake | jq
  {
    "amount": "0"
  }
  ```

* Get the 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": "provider",
      "Underlay": "16Uiu2HAmDWZb4DxZQkS9yseXNukBFe6MhZdimSKuZcHFeJrF3jC9"
    },
    "connected_peers": null,
    "blocked_peers": null
  }
  ```

We recommend reading the [consuming bids](/v1.2.x/get-started/providers/consuming-bids) section next to consume bids effectively.

## Querying the Provider Registry

Bidders, relays, and other observers may want to enumerate currently registered providers and their BLS keys — for example, to identify which providers can issue credible commitments. The Provider Registry contract on the mev-commit chain is the source of truth.

**Contract address (mainnet):** see [Contracts](/v1.2.x/developers/contracts).

<Accordion title="Example: list all registered providers with their BLS keys">
  ```javascript theme={null}
  const ethers = require("ethers");

  const provider = new ethers.JsonRpcProvider("https://chainrpc.mev-commit.xyz/");
  const providerRegistryAddress = "0xb772Add4718E5BD6Fe57Fb486A6f7f008E52167E"; // mainnet

  const abi = [
      "event ProviderRegistered(address indexed provider, uint256 stakedAmount)",
      "function isProviderValid(address provider) public view",
      "function getBLSKeys(address provider) external view returns (bytes[])"
  ];

  const contract = new ethers.Contract(providerRegistryAddress, abi, provider);

  async function getRegisteredProviders() {
      const events = await contract.queryFilter(contract.filters.ProviderRegistered());
      const providerMap = {};
      for (const event of events) {
          const addr = event.args.provider;
          try {
              await contract.isProviderValid(addr);
              const blsKeys = await contract.getBLSKeys(addr);
              providerMap[addr] = blsKeys.map(k => ethers.hexlify(k));
          } catch { /* skip invalid */ }
      }
      return providerMap;
  }

  getRegisteredProviders().then(map => {
      for (const [addr, keys] of Object.entries(map)) {
          console.log(`Provider: ${addr}`);
          keys.forEach((k, i) => console.log(`  Key ${i + 1}: ${k}`));
      }
  });
  ```
</Accordion>


# Sending Commitments
Source: https://docs.primev.xyz/v1.2.x/get-started/providers/sending-commitments



To send your first commitment, you will need to connect to the mev-commit Testnet. This will allow you to consume bids incoming to the network and submit commitments. To do this, you'll want to run an emulator to simulate accepting and rejecting bids.

<Tip>You will want to connect to a decisioning system that will accept and reject bids based on custom criteria. You can read more about the API to open a gRPC stream [here](/v1.2.x/api-reference/provider/sendprocessedbids).</Tip>

As an example, a dummy decisioning system is implemented in the repository. This dummy system accepts all the bids it gets. To try it, you can open a new terminal and run the following command:

<Warning>You require Go Version 1.21.1 to run the example emulator</Warning>

```
git clone --recurse-submodules https://github.com/primev/mev-commit.git && cd mev-commit &&
git checkout v1.1.0 && cd p2p/examples/provideremulator && go run . 
```

## Configuring custom logic to process bids and send Commitments

We can take a deeper look at how you can add custom logic to decision on the sending of commitments.

### Integrating Bid Processing in Your System

To integrate bid processing in your system using the Provider API, follow these steps to receive bid information and send back processed bids:

<Steps>
  <Step title="Implement the gRPC Service">
    Implement the Provider service as outlined in the [providerapi.proto](https://github.com/primev/mev-commit/blob/main/p2p/rpc/providerapi/v1/providerapi.proto#L20). This requires setting up a server that can manage RPC methods, with a particular emphasis on the reception of bids and response of commitment authorizations.
  </Step>

  <Step title="Receive Bids">
    Utilize the ReceiveBids RPC method to listen for incoming bids from clients. This method streams bid messages to your server.
    The structure of the bid is as follows:

    ```proto theme={null}
    message Bid {
      option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_schema) = {
        json_schema: {
          title: "Bid message"
          description: "Signed bid message from bidders to the provider."
          required: ["txHashes", "bidAmount", "blockNumber", "bidDigest"]
        }
        example: "{\"txHashes\": [\"fe4cb47db3630551beedfbd02a71ecc69fd59758e2ba699606e2d5c74284ffa7\", \"71c1348f2d7ff7e814f9c3617983703435ea7446de420aeac488bf1de35737e8\"], \"amount\": \"1000000000000000000\", \"blockNumber\": 123456, \"bidDigest\": \"9dJinwL+FZ6B1xsIQQo8t8B0ZXJubJwY86l/Yu7yAH159QrPHU0qj2P+YFj+llbuI1ZygdxGsX8+P3byMEA5ig==\", \"decayStartTimestamp\":1725365301000, \"decayEndTimestamp\":1725365302000, \"revertingTxHashes\":[\"fe4cb47db3630551beedfbd02a71ecc69fd59758e2ba699606e2d5c74284ffa7\"]}"
      };
      repeated string tx_hashes = 1 [(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
        description: "Hex string encoding of the hashes of the transactions that the bidder wants to include in the block."
        pattern: "[a-fA-F0-9]{64}"
      }, (buf.validate.field).cel = {
          id: "tx_hashes",
          message: "tx_hashes must be a valid array of transaction hashes.",
          expression: "this.all(r, r.matches('^[a-fA-F0-9]{64}$'))"
      }];
      string bid_amount = 2 [(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
        description: "Amount of ETH that the bidder is willing to pay to the provider for including the transaction in the block."
        pattern: "[0-9]+"
      }, (buf.validate.field).cel = {
          id: "bid_amount",
          message: "bid_amount must be a valid integer.",
          expression: "this.matches('^[1-9][0-9]*$')"
      }];
      int64 block_number = 3 [(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
        description: "Max block number that the bidder wants to include the transaction in."
      }, (buf.validate.field).int64.gt = 0];
      bytes bid_digest = 4 [(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
        description: "Digest of the bid message signed by the bidder."
      }, (buf.validate.field).bytes = {
          min_len: 1,
          max_len: 64
      }];
      int64 decay_start_timestamp = 5 [(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
        description: "Timestamp at which the bid starts decaying."
      }, (buf.validate.field).cel = {
          id: "decay_start_timestamp",
          message: "decay_start_timestamp must be a valid integer.",
          expression: "uint(this) > 0"
      }];
      int64 decay_end_timestamp = 6 [(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
        description: "Timestamp at which the bid ends decaying."
      }, (buf.validate.field).cel = {
          id: "decay_end_timestamp",
          message: "decay_end_timestamp must be a valid integer.",
          expression: "uint(this) > 0"
      }];
      repeated string reverting_tx_hashes = 7 [(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
        description: "Optional array of tx hashes that are allowed to revert or be discarded."
      }, (buf.validate.field).cel = {
          id: "reverting_tx_hashes",
          message: "reverting_tx_hashes must be an array of valid transaction hashes.",
          expression: "this.all(r, r.matches('^[a-fA-F0-9]{64}$'))"
      }];
      repeated string raw_transactions = 8 [(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
        description: "Optional array of RLP encoded raw signed transaction payloads that the bidder wants to include in the block."
      }, (buf.validate.field).cel = {
          id: "raw_transactions",
          message: "raw_transactions must be an array of valid raw transactions.",
          expression: "this.all(r, r.matches('^[a-fA-F0-9]+$'))"
      }];
      string slash_amount = 9 [(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
        description: "Amount of ETH that will be slashed from the provider if they fail to include the transaction. If zero, the decayed bid amount is used for slashing."
        pattern: "[0-9]+"
      }, (buf.validate.field).cel = {
          id: "slash_amount",
          message: "slash_amount must be a valid integer.",
          expression: "this == '' || (this.matches('^[0-9]+$') && uint(this) >= 0)"
      }];
      BidOptions bid_options = 10 [(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
        description: "Optional bid options for the transaction."
      }];
      string bidder_address = 11 [(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
        description: "Hex string encoding of the bidder's address recovered from the bid signature."
        pattern: "^[a-fA-F0-9]{40}$"
      }];
    };
    ```

    The raw transactions are optionally provided by the bidder. If provided the order of the transaction hashes in `txHashes` will be the same as the order or the corresponding `rawTransactions`.

    Below is an image of the flow through which bids would be received through the gRPC API

    <img alt="gRPC Flow for Getting Bids" />

    The bid options are optionally used by bidders if they want additional constraints on the transaction. Currently, mev-commit supports positional constraints on the transactions w\.r.t the block. The decision logic should take these into consideration before returning.

    ```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."
      }];
    };
    ```
  </Step>

  <Step title="Process Bids">
    For each received bid, implement your custom logic to validate and process these bids. This could involve checking the bid's validity and feasibility based on orderflow, computing the effective gas price, and deciding whether to accept or reject the bid.
  </Step>

  <Step title="Send Processed Bid Responses (Accept/Reject)">
    After processing each bid, construct a BidResponse message indicating the outcome. This message should include the bid's digest and a status indicating acceptance or rejection.
    At a high level, to commit to a bid, your code must send a `STATUS_ACCEPTED` with the bid digest specified, and correspondingly `STATUS_REJECTED` to reject the bid.

    <Accordion title="Details on BidResponse">
      The BidResponse structure is as follows:

      ```
      message BidResponse {
        option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_schema) = {
          json_schema: {
            title: "Bid response"
            description: "Response sent by the provider with the decision on the bid received."
            required: ["bidDigest", "status"]
          }
          example: "{\"bidDigest\": \"9dJinwL+FZ6B1xsIQQo8t8B0ZXJubJwY86l/Yu7yAH159QrPHU0qj2P+YFj+llbuI1ZygdxGsX8+P3byMEA5ig==\", \"status\": \"STATUS_ACCEPTED\"}"
        };
        bytes bid_digest = 1 [(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
          description: "Digest of the bid message signed by the bidder."
        }];
        enum Status {
          STATUS_UNSPECIFIED = 0;
          STATUS_ACCEPTED = 1;
          STATUS_REJECTED = 2;
        }
        Status status = 2 [(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
          description: "Status of the bid."
        }, (buf.validate.field).enum = {
            defined_only: true,
            in: [
              1,
              2
            ]
        }];
        int64 dispatch_timestamp = 3;
      };
      ```

      It contains the following fields:

      1. bid\_digest: A byte array (bytes type) that represents the digest of the bid message signed by the bidder. This serves as a unique identifier for the bid in question.
      2. status: An enumeration (enum Status) that indicates the status of the bid. The status can be one of three values:
         STATUS\_UNSPECIFIED: The default value, indicating that the status has not been set or is unknown.
         STATUS\_ACCEPTED: Indicates that the bid has been accepted by the provider.
         STATUS\_REJECTED: Indicates that the bid has been rejected by the provider.
      3. dispatch\_timestamp: Timestamp (int64 type) at which the commitment is accepted by provider and is used to compute the expected revenue from the preconfirmation.
    </Accordion>
  </Step>

  <Step title="Server Setup">
    Deploy your gRPC server on suitable infrastructure, ensuring it's accessible to clients. Configure necessary network settings for security and connectivity.
    Example Server Implementation in Go:

    ```go theme={null}

    import (
    	...

    	"github.com/primev/mev-commit/p2p/examples/provideremulator/client"
    	providerapiv1 "github.com/primev/mev-commit/p2p/gen/go/providerapi/v1"
    )

    func ...() {
    	...

    	providerClient, _ := client.NewProviderClient(*serverAddr, logger)

    	bidS, _ := providerClient.ReceiveBids()

    	for {
    		select {
    		case bid, more := <-bidS:
    			if !more {
    				return
    			}
    			logger.Info("received new bid", "bid", bid)
    			_ := providerClient.SendBidResponse(context.Background(), &providerapiv1.BidResponse{
    				BidDigest: bid.BidDigest,
    				Status:    providerapiv1.BidResponse_STATUS_ACCEPTED, // decide here if you want to accept or reject
            DispatchTimestamp: time.Now().Unix(),
    			})
    		}
    	}
    }
    ```
  </Step>
</Steps>

This should help you integrate bid processing into your system, allowing you to receive bid information and send back processed bids as commitments.


# Withdraw Stake
Source: https://docs.primev.xyz/v1.2.x/get-started/providers/withdraw

Withdraws the stake from the provider registry.

Withdrawal on mev-commit chain should be done in two steps:

<Steps>
  <Step title="Unstake Funds">
    Unstake the funds from the provider registry.

    ```shell theme={null}
    > curl -X POST "http://localhost:13523/v1/provider/unstake"
    ```
  </Step>

  <Step title="Withdraw Stake">
    Withdraw the stake from the provider registry.

    After 24 hours following the unstake operation, you can withdraw the funds from the provider registry.

    ```shell theme={null}
    > curl -X POST "http://localhost:13523/v1/provider/withdraw_stake" | jq
    {
        "amount": "1000000000000000000"
    }
    ```
  </Step>
</Steps>


# Quickstart: opt in validators
Source: https://docs.primev.xyz/v1.2.x/get-started/quickstart

Opt L1 validator keys into mev-commit with the mev-commit-opt-in skill.

The default path is agentic. Open [primev.xyz/ai](https://primev.xyz/ai), install the **mev-commit-opt-in** skill, and ask Claude, ChatGPT, or Grok to register your keys into the **mev-commit validator coalition**. Hub-true keys are one signal across many validators. Opt-in is membership, not extra block revenue from a live commitment market.

The old dashboard is deprecated. Any mev-boost relay set is fine. Why this exists: [why opt in](/v1.2.x/knowledge-base/why-should-validators-opt-in).

Full method detail lives on the [agentic opt-in](/v1.2.x/get-started/validators/agentic-opt-in) page.

<Steps>
  <Step title="Install the skill">
    <Tabs>
      <Tab title="Claude">
        ```bash theme={null}
        claude plugin marketplace add primev/claude-plugin
        claude plugin install primev
        ```
      </Tab>

      <Tab title="Grok">
        ```bash theme={null}
        grok plugin marketplace add primev/claude-plugin
        grok plugin install primev --trust
        ```
      </Tab>

      <Tab title="ChatGPT">
        Add [https://primev.xyz/skills/mev-commit-opt-in.md](https://primev.xyz/skills/mev-commit-opt-in.md) as a skill in ChatGPT or Codex. Or click **Copy skill** on [primev.xyz/ai](https://primev.xyz/ai).
      </Tab>
    </Tabs>
  </Step>

  <Step title="Give the agent your keys">
    Upload a `.txt` or `.csv` of BLS pubkeys (`0x` + 96 hex, comma or newline separated). Batch 40 to 60 keys per transaction. Confirm the first and last key and the count before anything is sent.
  </Step>

  <Step title="Ask it to opt in">
    Pick the method you already use:

    * Vanilla: `Opt these validator pubkeys into mev-commit with simple staking`
    * EigenLayer: `Register these BLS keys on the mev-commit AVS as this pod owner`
    * Symbiotic: `Register these keys on the mev-commit Symbiotic middleware`

    The agent uses **your** Ethereum RPC and wallet. It simulates, sends, waits for the receipt, then checks `ValidatorOptInHub`.

    Then finish the steps in [Complete the registry](/v1.2.x/get-started/validators/agentic-opt-in#complete-the-registry). Do not stop after the send.
  </Step>

  <Step title="Confirm the registry">
    After the receipt, the agent must call Hub `areValidatorsOptedIn` on the full set.

    Success is every key `true`, plus a report of method, key count, tx hash, and an Etherscan or Hoodi link. If any key is `false`, treat the job as unfinished.

    Then ask: `Are these pubkeys opted in, and what is my total on-chain ETH stake?`
  </Step>
</Steps>

<Check>
  Hub `true` on each key means registration succeeded. Keep your existing relay set.
</Check>

Path pages if you want `cast` instead of an agent: [vanilla](/v1.2.x/get-started/validators/vanilla), [EigenLayer](/v1.2.x/get-started/validators/eigenlayer), [Symbiotic](/v1.2.x/get-started/validators/symbiotic).

***

## Bidder or provider node

Running a p2p bidder or provider node is a different path. Create a keystore, [bridge](/v1.2.x/get-started/bridge/bridge-cli) ETH to the mev-commit chain, then start the binary from [releases](https://github.com/primev/mev-commit/releases/).

```bash theme={null}
# bidder
./mev-commit \
    --keystore-path $HOME/keystore \
    --keystore-password <PASSWORD> \
    --enable-deposit-manager=true \
    --target-deposit-amount <WEI_AMOUNT> \
    --bootnodes /dnsaddr/bootnode.mev-commit.xyz \
    --settlement-rpc-endpoint https://chainrpc.mev-commit.xyz
```

```bash theme={null}
# provider
./mev-commit \
    --peer-type provider \
    --keystore-path $HOME/keystore \
    --keystore-password <PASSWORD> \
    --bootnodes /dnsaddr/bootnode.mev-commit.xyz \
    --settlement-rpc-endpoint https://chainrpc.mev-commit.xyz \
    --nat-addr <PUBLIC_IP>
```

Then see [bidder best practices](/v1.2.x/get-started/bidders/best-practices) or [provider registration](/v1.2.x/get-started/providers/registering-a-provider). System notes: [system requirements](/v1.2.x/developers/system-requirements).


# Agentic Opt-In
Source: https://docs.primev.xyz/v1.2.x/get-started/validators/agentic-opt-in

Join the mev-commit validator coalition with the mev-commit-opt-in skill. The old validator dashboard is deprecated.

<Info>
  The validator dashboard at validators.mev-commit.xyz is deprecated. Every opt-in path (vanilla, EigenLayer, Symbiotic) lives in the **mev-commit-opt-in** skill. Manual contract calls on the path pages remain valid if you want them.
</Info>

Opt L1 validator BLS pubkeys into the **mev-commit validator coalition** from Claude, ChatGPT, or Grok. The skill uses your RPC and wallet, verifies on the ValidatorOptInHub, computes real on-chain ETH stake, and can opt out.

Membership is a single on-chain signal across many keys. It is not extra yield from a live bid market. No fees are enabled at this stage. There is no fee switch without your approval. When a fee is approved and enabled, it funds AI research. [Why join](/v1.2.x/knowledge-base/why-should-validators-opt-in).

Homepage: [primev.xyz/ai](https://primev.xyz/ai) (also [mev-commit.xyz](https://mev-commit.xyz), which redirects here).

Any mev-boost relay set is fine. There is no relay configuration step.

## Install the skill

<Tabs>
  <Tab title="Claude">
    ```bash theme={null}
    claude plugin marketplace add primev/claude-plugin
    claude plugin install primev
    ```
  </Tab>

  <Tab title="Grok">
    ```bash theme={null}
    grok plugin marketplace add primev/claude-plugin
    grok plugin install primev --trust
    ```
  </Tab>

  <Tab title="ChatGPT">
    Open [https://primev.xyz/skills/mev-commit-opt-in.md](https://primev.xyz/skills/mev-commit-opt-in.md) and add it as a skill in ChatGPT or Codex.
  </Tab>
</Tabs>

Source: [github.com/primev/claude-plugin](https://github.com/primev/claude-plugin)

## Complete the registry

Skill install is not registration. Walk this list to a Hub-true result. Agents should execute it in order and ask before every write.

1. **Pick one method.** Vanilla, EigenLayer, or Symbiotic. One pubkey, one method. Do not double-register.
2. **Parse keys.** Accept `.txt`, `.csv`, paste, commas, or newlines. Normalize to `0x` + 96 hex. Confirm count and first/last pubkey with the operator.
3. **Confirm signer and RPC.** Use their `ETH_RPC_URL` (mainnet chain id 1, or Hoodi 560048). Wallet is Foundry keystore, hardware, or `PRIVATE_KEY` only if they insist. Never print a private key.
4. **Prerequisites.**
   * Vanilla: read `minStake()`. `msg.value` is split evenly. Extra ETH is a slash buffer. Hoodi vanilla is whitelisted. Mainnet whitelist is coming.
   * EigenLayer: caller is the pod owner or the delegated AVS operator. Function name is plural: `registerValidatorsByPodOwners`.
   * Symbiotic: vault and operator must already be registered. If not, stop and name the gap.
5. **Simulate, then send.** Batch 40 to 60 keys. Wait for the receipt. A receipt is not opted in.
6. **Verify on the Hub.** `ValidatorOptInHub.areValidatorsOptedIn(bytes[])` at `0x1059155bD5854224bF58e43CD3EEC6B07b4F30Ad`. Every key must be `true`.
7. **Report.** Method, key count, tx hash, Etherscan or Hoodi link, Hub booleans, next step. For stake, sum real on-chain balances. Never `32 ETH × key count`.

If a write reverts, name the contract, function, revert, and the address or pubkey that failed. If the vault or operator is missing, tell them to ping Primev with that address.

## What to say

After install:

* "Opt these validator pubkeys into mev-commit with simple staking."
* "Register these keys on the EigenLayer AVS as this pod owner."
* "Check whether these pubkeys are opted in, and sum my on-chain ETH stake."
* "Unstake these vanilla keys and withdraw when the period is done."

Upload a `.txt` or `.csv` of BLS pubkeys (`0x` + 96 hex, comma or newline separated). Batch 40 to 60 keys per transaction.

## How it works

The skill follows the same registry calls the old dashboard used after a wallet was connected.

1. Choose a method: [vanilla](/v1.2.x/get-started/validators/vanilla), [EigenLayer](/v1.2.x/get-started/validators/eigenlayer), or [Symbiotic](/v1.2.x/get-started/validators/symbiotic).
2. Parse your key file.
3. Simulate, then send on **your** Ethereum RPC and wallet (Foundry keystore, hardware, or `PRIVATE_KEY` in the environment).
4. Wait for the receipt, then verify `ValidatorOptInHub.areValidatorsOptedIn`.

Mainnet Hub: `0x1059155bD5854224bF58e43CD3EEC6B07b4F30Ad`

| Method     | Contract                                                         | Function                                              |
| ---------- | ---------------------------------------------------------------- | ----------------------------------------------------- |
| Vanilla    | VanillaRegistry `0x47afdcB2B089C16CEe354811EA1Bbe0DB7c335E9`     | `stake(bytes[])` payable                              |
| EigenLayer | MevCommitAVS `0xBc77233855e3274E1903771675Eb71E602D9DC2e`        | `registerValidatorsByPodOwners(bytes[][], address[])` |
| Symbiotic  | MevCommitMiddleware `0x21fD239311B050bbeE7F32850d99ADc224761382` | `registerValidators(bytes[][], address[])`            |

Read `minStake()` on-chain before vanilla staking. Extra ETH in that tx is a slash buffer, not prepaid capacity. Hoodi vanilla is whitelisted (mainnet whitelist coming).

Prerequisites that are not the skill's job (vault registration, AVS operator registration, EigenLayer delegation) stay on the path pages. If a revert says the vault or operator is missing, the skill names that step so you can ping Primev with the exact address.

## Opt out

* Vanilla: `unstake`, wait `unstakePeriodBlocks`, then `withdraw`
* EigenLayer: `requestValidatorsDeregistration`, wait, then `deregisterValidators`
* Symbiotic: `requestValDeregistrations`, wait, then `deregisterValidators`

## On-chain stake

Ask the skill for your total ETH stake. It sums beacon effective balances (beacon node or beaconcha.in; a `BEACONCHAIN_API_KEY` is fine) plus VanillaRegistry `getStakedAmount` and real EigenLayer / Symbiotic collateral. It will not use `32 ETH × key count`.

## Manual calls

Path pages still document `cast` / Foundry for operators who do not want an agent:

* [Vanilla](/v1.2.x/get-started/validators/vanilla)
* [EigenLayer](/v1.2.x/get-started/validators/eigenlayer)
* [Symbiotic](/v1.2.x/get-started/validators/symbiotic)


# Eigenlayer Opt-in
Source: https://docs.primev.xyz/v1.2.x/get-started/validators/eigenlayer

Opt into mev-commit by natively restaking to our AVS.

## Why use this method?

Opting-in validators through the mev-commit AVS is ideal for validators that are already natively restaked, or wish to natively restake through Eigenlayer.

This method of opt-in is capital efficient in that a validator's 32 ETH already staked with the beacon chain can be reused as collateral for opting-in to mev-commit. Further, that beacon chain ETH can be restaked towards other protocols.

## Prerequisites

If you plan to bulk opt-in a large number of validator pubkeys, check out the [Eigenlayer Operator Registration](/v1.2.x/knowledge-base/eigenlayer-operator-registration) guide.

Individual validator entities represented by a pod owner must delegate their natively restaked ETH to an Operator that's registered with the mev-commit AVS. See how to delegate [here](https://docs.eigenlayer.xyz/eigenlayer/restaking-guides/restaking-user-guide/restaker-delegation/delegate-to-an-operator).

Operators currently registered with the mev-commit AVS can be found through the Eigenlayer dashboard:

* [Mainnet](https://app.eigenlayer.xyz/avs/0xbc77233855e3274e1903771675eb71e602d9dc2e)

If your currently delegated operator is not registered with mev-commit, you have the option to [change your delegation](https://docs.eigenlayer.xyz/eigenlayer/restaking-guides/restaking-user-guide/restaker-delegation/redelegation-process).

The [Primev Operator](https://app.eigenlayer.xyz/operator/0xEde6F5F1Bf064a7Ee002D83A87C4890bE7B9b415) is available for delegation on mainnet, but will only operate for the mev-commit AVS.

Operators serve the purpose of (optionally) being able to register natively restaked validator pubkeys with the mev-commit AVS. Only the operator that a validator specifically delegates to, and a validator's pod owner, are given validator pubkey registration permissions.

If an Operator is registering pubkeys on behalf of validators, it should manage those validators itself, or represent them well enough to register them into the coalition (staking-as-a-service providers for example). This trustful relationship between validators and their delegated Operator piggybacks off already agreed upon trust assumptions with eigenlayer delegation.

## Pubkey Registration

Following operator delegation, each validator pubkey must be *registered* with the mev-commit AVS from the delegated operator's account, or from the pod owner account. This action adds those pubkeys to the [mev-commit validator coalition](/v1.2.x/knowledge-base/why-should-validators-opt-in). Any mev-boost relay set is fine.

<Info>
  The validator dashboard is deprecated. Pubkey registration is done with the [mev-commit-opt-in skill](/v1.2.x/get-started/validators/agentic-opt-in), which calls `MevCommitAVS.registerValidatorsByPodOwners`.
</Info>

Pubkey registration is facilitated through the [agentic skill](/v1.2.x/get-started/validators/agentic-opt-in) (or a direct `cast send` to the same function).

The connected metamask account (who is invoking the pubkey registration transaction) must be the delegated operator, or pod owner, of the validator pubkeys that are being registered.


# Lido Opt-in
Source: https://docs.primev.xyz/v1.2.x/get-started/validators/lido

Opt into mev-commit using Validators registered through Lido.

## Why use this method?

Opting-in validators through the Lido Registry is for Lido validators that want those keys on the [mev-commit validator coalition](/v1.2.x/knowledge-base/why-should-validators-opt-in) roster. Hoodi only for now.

## Overview

⚠️ **Important Notes:**

* This contract is only deployed on **Hoodi** testnet at the moment. Mainnet and frontend integration coming soon!
* Operators must be **whitelisted by our team** before registering (see step 1 below).

***

## Contract

You can interact directly with the Hoodi contract on Etherscan using the "Write as Proxy" tab:

[Lido Registry Hoodi Contract](https://hoodi.etherscan.io/address/0xefd6333907fc73c1ac3167d843488b8899bac91b)

***

## Registering as an Operator

### Step 1: Get Whitelisted

To register, you must first be whitelisted as an operator. To request whitelisting, please fill out [this short google form](https://docs.google.com/forms/d/e/1FAIpQLSfIYZs1l7wqd6jkHHFZA8FQ6vg3T6KF6R_XBZsSGGbzN7q4Hg/viewform) with your operator info, or reach out to our team through [telegram](https://t.me/+-aiQNWqjZRQ1OWJh).

### Step 2: Call `stake`

Once whitelisted, you can register by calling:

```solidity theme={null}
stake(bytes[] blsKeys)
```

* **blsKeys**: Provide a list of your validator public keys.
* You must also provide the required ETH collateral when calling.

**Formatting Note for Etherscan:** When providing `bytes[]` input on Etherscan, use the format:

```
0xkey1,0xkey2,0xkey3,...
```

(No brackets, no quotes)

### Stake Requirement

The parameter `VanillaRegistry.minStake` determines how much ETH must be staked per validator pubkey to opt-in to mev-commit:

* **Mainnet**: .0001 ETH (not live yet)
* **Hoodi**: .0001 ETH

***

## Claiming Rewards

For instructions on how to claim rewards for your validators, please refer to the [Rewards Guide](/v1.2.x/get-started/validators/rewards).

## Withdrawing

If you need to deregister and withdraw:

1. Call `unstake(bytes[] blsKeys)` to start the process. Validators are considered opted out during this time.
2. Wait **96 blocks** on Hoodi (the unstaking period).
3. Call `withdraw(bytes[] blsKeys)` to receive your ETH back.


# Rewards
Source: https://docs.primev.xyz/v1.2.x/get-started/validators/rewards

RewardDistributor Operator Guide

The `RewardDistributor` contract is **Hoodi test plumbing** for later coalition fees and token grants. It is not a mainnet payout for extra block revenue.

**No fees are enabled at this stage.** There is no fee switch without your approval. Members must actively approve any fee before it starts. When a fee is approved and enabled, this contract can track it per operator and recipient so operators (or their delegates) can claim to the right addresses.

Opt-in today is coalition membership. See [Why should validators opt in](/v1.2.x/knowledge-base/why-should-validators-opt-in).

## Contract Details

* **Network**: Hoodi (Testnet)
* **Address**: [0x69f286fc7869c30809a9695462fa79a0fd99c5bc](https://hoodi.etherscan.io/address/0x69f286fc7869c30809a9695462fa79a0fd99c5bc#writeProxyContract)

## Interacting with the Contract

The Rewards Distributor is currently live on the [Hoodi testnet](https://hoodi.etherscan.io/address/0x69f286fc7869c30809a9695462fa79a0fd99c5bc#writeProxyContract). A Mainnet deployment and a dedicated claiming UI will be available in the future.

For now, you can manage and claim rewards programmatically or by interacting directly with the contract on Etherscan.

## Claiming rewards

Rewards do not stream automatically to your wallet; you must explicitly [claim them from the contract](https://hoodi.etherscan.io/address/0x69f286fc7869c30809a9695462fa79a0fd99c5bc#writeProxyContract).

### Claim as the operator

To transfer all pending rewards to your recipients:

1. Find the `claimRewards` function.
2. **recipients**: Enter your recipient address(es) in bracket format.
   * Example: `[0xYourRecipientAddress]`
3. **tokenID**: Enter the ID of the token to claim.
   * For **ETH**: `0`
   * For **Tokens**: `1`
4. Click **Write** and confirm the transaction.

## Setting reward recipients

By default, if a recipient is not set, rewards earned by a validator are granted to the validator's operator address.

### Set a global default recipient

To ensure all rewards go to a specific address (e.g. a cold wallet or a splitter contract), you should set a global operator override. This applies to all your validator keys unless specifically overridden for a key. Individual key recipient overrides can also be set.

1. Find the `setOperatorGlobalOverride` function.
2. **recipient**: Enter the address you want to receive the rewards.
3. Click **Write** and confirm the transaction.


# Rocket Pool Opt-in
Source: https://docs.primev.xyz/v1.2.x/get-started/validators/rocketpool

Opt into mev-commit using Validators registered through Rocket Minipools.

This guide explains how to register Rocket Pool validators with the **Rocket Pool Minipool Registry** for mev-commit, how freezing works, and how to deregister. This Registry is only available on Hoodi testnet at the moment, with mainnet deployment coming soon.

***

## Why use this method?

Opting-in validators through the RocketMinipool Registry is for Rocket Pool validators that want those keys on the [mev-commit validator coalition](/v1.2.x/knowledge-base/why-should-validators-opt-in) roster. Hoodi only for now.

***

## How the Registry integrates with Rocket Pool

The registry relies on Rocket Pool's contracts to check for each validator's associated minipool and determine the **authorized operators**. The registry itself does not remap keys to minipools and operators; Rocket Pool contract data is checked at the time of the relevant call.

***

## Registering validators

### Registering using a withdrawal address

Simple registration can currently be executed on Hoodi etherscan from a Rocket Pool <strong>withdrawal address</strong> using the "Write as Proxy" tab on the [RocketMinipoolRegistry contract](https://hoodi.etherscan.io/address/0xbe5a803a7b68f442eff1953c672a3499779680b0#writeProxyContract) (address ). Mainnet deployment is planned in the near future.

Call:

```solidity theme={null}
registerValidators(bytes[] valPubKeys)
```

Requirements per key:

* The pubkey must be associated with an **active Rocket Pool minipool**.
* The validator must not already be registered.
* The caller must be the **withdrawal address** for that minipool.

**Etherscan input tip (bytes\[]):**

```
0xkey1, 0xkey2, 0xkey3, ...
```

No brackets, no quotes.

***

### Registering using a signature from your node address

Users can also register by authorizing an executor with a signature from their node address, signed locally via Smart Node. Full front-end support for generating these signatures will be available soon.

> **⚠️ Caution: Do not use your node address in a web browser**
>
> For node security, it is best practice to avoid putting <strong>node address keys</strong> into web browsers.
> When registering via a browser, use your <strong>withdrawal address</strong> instead, or perform the action locally via so keys never touch a website.

## Freezing & unfreezing

* **Freeze:** The **freeze oracle** can call `freeze(bytes[] valPubKeys)` for validators that violate protocol rules. Frozen validators are considered opted out.
* **Unfreeze:** Anyone can call `unfreeze(bytes[] valPubKeys)` and pay `unfreezeFee * numberOfKeys`. The current fee and receiver can be checked on-chain. The owner can also override with `ownerUnfreeze(bytes[] valPubKeys)`.

***

## Deregistration

Deregistration is a two-step process:

* Call `requestValidatorDeregistration(bytes[] valPubKeys)` to start the timer.
* After `deregistrationPeriod` has passed, call `deregisterValidators(bytes[] valPubKeys)` to complete it. Validators must not be frozen.

Helper: `getEligibleTimeForDeregistration(bytes pubkey)` returns the timestamp when a validator can be deregistered. A value of 0 indicates that no deregistration request has been made for the key.


# Symbiotic Opt-in
Source: https://docs.primev.xyz/v1.2.x/get-started/validators/symbiotic

Opt into mev-commit by ERC20 restaking with the MevCommitMiddleware contract through Symbiotic.

# Context

### Why use this method?

Opting-in through Symbiotic is ideal for validators that wish to be secured by ERC20 collateral residing from a Symbiotic vault.

Symbiotic is capital efficient in that vault collateral can be restaked towards other protocols. Further, Symbiotic offers a large degree of restaking configurability.

### Prerequisites

Prior to opt-in through Symbiotic, it's worth familiarizing yourself with their [documentation](https://docs.symbiotic.fi/) on Networks, Vaults, and Operators. This method of validator opt-in requires competency in vault and operator curation.

### Who is this for?

Mev-commit is flexible in the type of entities that use Symbiotic to restake, and secure validators with our protocol. Any combination of Operator and Vault entities can be used, whether each are from the same organization or not.

Most importantly, For L1 validators to be opted-in to mev-commit, a minimum of 3 ETH worth of restake must be slashable for each validator, in case that validator acts against its protocol commitments. This can be reduced for operators with a large number of validators to 1,000 ETH at the entity level. Vaults allocate slashable ERC20 collateral to Operators that are registered with the mev-commit network in Symbiotic. This collateral may be slashable by other Symbiotic networks, hence it is restaked.

Operators for the mev-commit network are responsible for bulk registering groups of L1 validator pubkeys to an associated vault. Every registered validator is represented by restaked collateral from a single Vault and Operator. Each Vault’s total collateral can be split up to secure/represent many validators in groups.

<Frame>
  <img alt="Diagram showing the relationship between Vaults, Operators, Network Middleware, and the mev-commit Oracle" />
</Frame>

### What opt-in means

Opt-in through this method adds keys to the [mev-commit validator coalition](/v1.2.x/knowledge-base/why-should-validators-opt-in). It is not extra yield from higher mev-boost bids today.

All vault/operator pairs must agree how any later coalition fee or token grant is split.

See [Why Participate](/v1.2.x/get-started/validators/validator-guide#why-participate).

### Network Overview

The Symbiotic "network" in this context is mev-commit. Our network is represented by:

* A "network address", aka the Primev team multisig at [0x9101eda106A443A0fA82375936D0D1680D5a64F5](https://etherscan.io/address/0x9101eda106A443A0fA82375936D0D1680D5a64F5)
* A "middleware contract" at [0x21fD239311B050bbeE7F32850d99ADc224761382](https://etherscan.io/address/0x21fD239311B050bbeE7F32850d99ADc224761382)

# Setup

The following setup steps will reference various Symbiotic core contracts. Refer to their [deployments page](https://docs.symbiotic.fi/category/deployments) and [core source code](https://github.com/symbioticfi/core).

<Info>
  For technical users who're comfortable running foundry scripts, we've provided example code for every step in the setup process [here](https://github.com/primev/mev-commit/blob/main/contracts/scripts/validator-registry/middleware/ExampleSetup.s.sol).

  Alternatively the Symbiotic CLI can assist in many of these steps. Refer to their [docs](https://docs.symbiotic.fi/guides/cli/).
</Info>

<Steps>
  <Step title="Vault Configuration">
    A vault contract must be deployed and configured with slashable ERC20 `collateral`. Mev-commit will accept most forms of ERC20 collateral, unless they present significant risk of losing value. For non ETH denominated assets, overcollateralization may be required compared to their ETH denominated counterparts.

    See Symbiotic's [vault deployment guide](https://docs.symbiotic.fi/guides/vault-deployment/) and [vault configuration docs](https://docs.symbiotic.fi/handbooks/vaults-handbook#vault-configuration).

    <Warning>
      We enforce that all of the `Vault`, `Delegator`, `Slasher`, and `BurnerRouter` contracts are deployed via their relevant "factory" contract. Using Symbiotic's `VaultConfigurator` achieves this, and is recommended. Factory and vault configurator addresses can be found from the Symbiotic [deployments page](https://docs.symbiotic.fi/category/deployments).
    </Warning>

    Mev-commit enforces vault configuration from the following dropdowns:

    <Accordion title="Configure Burner Router">
      The `IVaultStorage.burner` address must be set to a `BurnerRouter` contract, and this contract must be deployed via Symbiotic's `IBurnerRouterFactory.create()`. Find more details about burner routers [here](https://docs.symbiotic.fi/modules/extensions/burners#burner-router).

      <Info>
        If you're deploying a burner router for the first time, please set all necessary parameters upon contract initialization. This avoids unnecessary delays in the setup process. If your burner router is already deployed, the `delay` must elapse before `acceptNetworkReceiver` can be called, to properly set the network receiver.
      </Info>

      The deployed burner router must be configured as follows:

      * `IBurnerRouter.networkReceiver()` must be set to `0xD5881f91270550B8850127f05BD6C8C203B3D33f`.
      * `IBurnerRouter.operatorNetworkReceiver()` must be disable by setting to `address(0)`, or set to `0xD5881f91270550B8850127f05BD6C8C203B3D33f`. Essentially this value must not override a valid network receiver.
      * `IBurnerRouter.delay()` must be greater than `2 days`.

      Upon vault registration, and validator registration, all burner router configuration is validated on-chain. If later on this validation fails, all validators associated to a vault will no longer be opted-in, as enforced in `_isValidatorOptedIn`.
    </Accordion>

    <Accordion title="Configure Delegator Module">
      The delegator module for the vault must be the `NetworkRestakeDelegator` or `OperatorSpecificDelegator` type. `FullRestakeDelegator` is not supported.

      <Warning>
        If using an `OperatorSpecificDelegator`, ensure the `IOperatorSpecificDelegator.operator()` field is initialized to the operator address that'll be used in subsequent steps. The operator field is immutable after delegator deployment!
      </Warning>
    </Accordion>

    <Accordion title="Configure Slasher Module">
      The slasher module must be set, and can be either a `Slasher` or `VetoSlasher` type.

      Vaults with an instant `Slasher` must have an `epochDuration` greater than `1 day` to register with our middleware contract.

      Vaults with veto slashers:

      * must have an `epochDuration` greater than `1 day + vetoDuration`, where `vetoDuration` is specified by the slasher.
      * require the resolver to be disabled via `address(0)`, since a permissioned oracle account invokes slashing, requiring only the most basic slashing interface.

      `IBaseSlasher.BaseParams` must have `isBurnerHook` set to `true`.
    </Accordion>

    Considering these requirements, below is an example of how to deploy a vault with a burner router, delegator, and slasher, using a foundry script.

    <Accordion title="Example">
      ```solidity theme={null}
      contract SetupVault is Script {
        function run() external {
        vm.startBroadcast();

        // Deploy burner router
        address burnerRouterFactory = 0x42dD40dC2130c658AB32d9989FF8aBe6c36463c0;
        IBurnerRouter.NetworkReceiver[] memory networkReceivers = new IBurnerRouter.NetworkReceiver[](1);
        networkReceivers[0] = IBurnerRouter.NetworkReceiver({
            network: 0x9101eda106A443A0fA82375936D0D1680D5a64F5,
            receiver: 0xD5881f91270550B8850127f05BD6C8C203B3D33f
        });
        address burnerRouter = IBurnerRouterFactory(burnerRouterFactory).create(
            IBurnerRouter.InitParams({
               owner: msg.sender,                       
               collateral: 0xae7ab96520DE3A18E5e111B5EaAb095312D7fE84, // stETH                  
               delay: 3 days, // > 2 days
               globalReceiver: msg.sender,             
               networkReceivers: networkReceivers,
               operatorNetworkReceivers: new IBurnerRouter.OperatorNetworkReceiver[](0) // Empty or same as networkReceivers
         }));

        console.log("Burner router deployed to:", address(burnerRouter));

        // Deploy vault with delegator and slasher
        IVaultConfigurator vaultConfigurator = IVaultConfigurator(0x29300b1d3150B4E2b12fE80BE72f365E200441EC);

        address[] memory networkLimitSetRoleHolders = new address[](1);
        networkLimitSetRoleHolders[0] = msg.sender;
        address[] memory operatorNetworkSharesSetRoleHolders = new address[](1);
        operatorNetworkSharesSetRoleHolders[0] = msg.sender;
        IVaultConfigurator.InitParams memory initParams = IVaultConfigurator.InitParams({
            version: 1,                                                                   
            owner: msg.sender,                            
            vaultParams: abi.encode(IVault.InitParams({
                collateral: 0xae7ab96520DE3A18E5e111B5EaAb095312D7fE84, // stETH
                burner: address(burnerRouter),                                                   
                epochDuration: 1 weeks,
                depositWhitelist: false, 
                isDepositLimit: false, 
                depositLimit: 0, 
                defaultAdminRoleHolder: msg.sender, 
                depositWhitelistSetRoleHolder: msg.sender, 
                depositorWhitelistRoleHolder: msg.sender, 
                isDepositLimitSetRoleHolder: msg.sender, 
                depositLimitSetRoleHolder: msg.sender
            })),
            delegatorIndex: 2, // OperatorSpecificDelegator
            delegatorParams: abi.encode(IOperatorSpecificDelegator.InitParams({
                baseParams: IBaseDelegator.BaseParams({
                    defaultAdminRoleHolder: msg.sender,
                    hook: 0x0000000000000000000000000000000000000000,
                    hookSetRoleHolder: msg.sender
                }),
                networkLimitSetRoleHolders: networkLimitSetRoleHolders,
                operator: 0xb4F13624966E874967d7C9231F2F740F03F1A832
            })),
            withSlasher: true,
            slasherIndex: 0, // Instant slasher
            slasherParams: abi.encode(ISlasher.InitParams({
                baseParams: IBaseSlasher.BaseParams({
                    isBurnerHook: true // Required
                })
            }))
        });
      ```

      To run the script, use a command similar to

      ```bash theme={null}
      	forge script scripts/validator-registry/middleware/ExampleSetup.s.sol:SetupVault \
          --via-ir \
          --rpc-url $RPC_URL \
          --keystore $KEYSTORE \
          --password $PASSWORD \
          --broadcast
      ```
    </Accordion>
  </Step>

  <Step title="Obtain Deposits">
    After the vault, burner router, delegator, and slasher are deployed in the previous step, the vault must obtain deposits of the appropriate ERC20 collateral type. These deposits can come from a variety of sources depending on the vault.

    <Accordion title="Example">
      Here is an example of how an account would deposit to a vault using a foundry script.

      ```solidity theme={null}
      contract DepositToVault is Script {
        function run() external {
          vm.startBroadcast();
          address stEthVault = 0x5DF518571733d5F4f496D76C9087110FAe98a946;
          address stEthToken = 0xae7ab96520DE3A18E5e111B5EaAb095312D7fE84;
          IERC20(stEthToken).approve(stEthVault, 0.1 ether);
          IVault vault = IVault(stEthVault);
          vault.deposit(msg.sender, 0.1 ether);
          vm.stopBroadcast();
        }
      }
      ```

      To run the script, use a command similar to

      ```bash theme={null}
      forge script scripts/validator-registry/middleware/ExampleSetup.s.sol:DepositToVault \
          --via-ir \
          --rpc-url $RPC_URL \
          --keystore $KEYSTORE \
          --password $PASSWORD \
          --broadcast
      ```
    </Accordion>
  </Step>

  <Step title="Operator Actions">
    Next, a Symbiotic operator can be setup as an EOA or a contract. The Operator must be registered with Symbiotic via `OperatorRegistry.registerOperator()`.

    The operator must then opt-in to any vault which will secure validators via `VaultOptInService.optIn(vaultAddress)`.

    The operator then opts-in to the mev-commit network via `NetworkOptInService.optIn(networkAddress)`. The network address is `0x9101eda106A443A0fA82375936D0D1680D5a64F5` for mainnet. An operator only needs to opt-in to the mev-commit network once even if an operator represents multiple vaults.

    <Accordion title="Example">
      Here is an example of the operator actions required in this step, using a foundry script.

      ```solidity theme={null}
      contract OperatorActions is Script {
        function run() external {
          vm.startBroadcast();
          IOperatorRegistry operatorRegistry = IOperatorRegistry(0xAd817a6Bc954F678451A71363f04150FDD81Af9F);
          operatorRegistry.registerOperator();

          IOptInService vaultOptInService = IOptInService(0xb361894bC06cbBA7Ea8098BF0e32EB1906A5F891);
          address stEthVault = 0x5DF518571733d5F4f496D76C9087110FAe98a946;
          vaultOptInService.optIn(stEthVault);

          IOptInService networkOptInService = IOptInService(0x7133415b33B438843D581013f98A08704316633c);
          networkOptInService.optIn(0x9101eda106A443A0fA82375936D0D1680D5a64F5);
          vm.stopBroadcast();
        }
      }
      ```

      To run the script, use a command similar to

      ```bash theme={null}
      forge script scripts/validator-registry/middleware/ExampleSetup.s.sol:OperatorActions \
          --via-ir \
          --rpc-url $RPC_URL \
          --keystore $KEYSTORE \
          --password $PASSWORD \
          --broadcast
      ```
    </Accordion>
  </Step>

  <Step title="Coordinate with our Team">
    At this point you've setup a vault and operator pair that can be used to opt-in a group of validator pubkeys. Next you'll need communicate the following details to our team:

    * The vault address and operator address setup in previous steps.
    * The type of ERC20 collateral that will be used to secure the validator pubkeys.
    * The decimal precision of the ERC20 collateral (not all ERC20s have 18 decimal precision).
    * The max amount of collateral your vault plans to allocate toward securing the mev-commit network. This value should be equal to or less than the total collateral in the vault.

    <Accordion title="Example">
      Hey Primev team, here are the required details for step 4 of the Symbiotic opt-in process.

      * Vault Address: `0xa0Fc5e70aad58028020A13ACd2e5B1f2431C912f`
      * Operator Address: `0x7c096554FCb894DE83aEf8e5F31CC6B04cD9570d`
      * Collateral Type: `stETH`, contract address: `0xae7ab96520DE3A18E5e111B5EaAb095312D7fE84`
      * Collateral Precision: `18`
      * Amount of collateral available to allocate: `1000000.0 stETH`
    </Accordion>

    <Warning>
      Please provide these values to our team in the exact format described, and let us know if you have any questions.
    </Warning>

    From here our team will assign a `slashAmount` appropriate for the collateral type. `slashAmount` of collateral is required to define a single validator as being slashable, and therefore opted-in to mev-commit. The vault/operator pair is able to opt-in `totalCollateral / slashAmount` number of validators.

    The network address (represented by Primev) will then set a max network limit for the vault's delegator module, `IBaseDelegator.setMaxNetworkLimit(uint96 identifier, uint256 amount)`. This is the maximum amount of collateral that will be accepted by the network from the vault.

    The network address will also call:

    * `MevCommitMiddleware.registerOperators` to register the operator with the middleware contract.
    * `MevCommitMiddleware.registerVaults` to register the vault with the middleware contract, associated to a `slashAmount`.
  </Step>

  <Step title="Vault Actions">
    Finally the vault curator address must make some calls. `setNetworkLimit(bytes32 subnetwork, uint256 amount)` should be called on the delegator module of the vault. This sets the total amount of collateral the vault would like to restake to the mev-commit network.

    <Info>
      For mev-commit, the subnetwork id is always `1`, and the `subnetwork` argument can be computed using Symbiotic's [Subnetwork library](https://github.com/symbioticfi/core/blob/main/src/contracts/libraries/Subnetwork.sol), by concatenating the network address with the subnetwork ID. For mainnet the subnetwork bytes32 value is `0x9101eda106a443a0fa82375936d0d1680d5a64f5000000000000000000000001`.
    </Info>

    If using a `NetworkRestakeDelegator`, the vault curator must then call `INetworkRestakeDelegator.setOperatorNetworkShares(bytes32 subnetwork, address operator, uint256 shares)`. This sets what portion of the mev-commit allocated stake the vault curator is allocating to a particular operator.

    If using an `OperatorSpecificDelegator`, calling `setOperatorNetworkShares` is not required, as this type of delegator automatically allocates 100% of the "shares" to a single operator.

    <Accordion title="Example">
      Here is an example of how the vault curator would complete this step, using a foundry script.

      ```solidity theme={null}
      contract VaultActions is Script { 
        function run() external {
          vm.startBroadcast();

          IOperatorSpecificDelegator delegator = IOperatorSpecificDelegator(0x75b131De299A5D343b9408081DD6A8D6a9891b8c);
          delegator.setNetworkLimit(0x9101eda106a443a0fa82375936d0d1680d5a64f5000000000000000000000001, 1000000 ether);

          uint256 stake = delegator.stake(0x9101eda106a443a0fa82375936d0d1680d5a64f5000000000000000000000001, msg.sender);
          console.log("Stake toward operator:", stake);

          vm.stopBroadcast();
        }
      }
      ```

      To run the script, use a command similar to

      ```bash theme={null}
      forge script scripts/validator-registry/middleware/ExampleSetup.s.sol:VaultActions \
          --via-ir \
          --rpc-url $RPC_URL \
          --keystore $KEYSTORE \
          --password $PASSWORD \
          --broadcast
      ```
    </Accordion>
  </Step>

  <Step title="Setup Complete - Register Validators">
    Now that setup is complete, the operator can register validators to the vault, so long as enough slashable collateral is allocated to the operator from previous steps.

    This is done with the [mev-commit-opt-in skill](/v1.2.x/get-started/validators/agentic-opt-in), which calls `MevCommitMiddleware.registerValidators`. The [old dashboard](https://validators.mev-commit.xyz/) is deprecated.

    Validator deregistration is also done through this dashboard, and requires waiting a deregistration period.
  </Step>
</Steps>

# Hoodi Testnet

Users can test Symbiotic flow using our Hoodi Vault (no stake necessary) by completing step 3 of the setup process above using our Hoodi Vault and Hoodi Network address, then contacting our team for registration within the Hoodi MevCommitMiddleware contract.

Alternatively, users can follow the full setup steps to test using their own Hoodi Vaults.

**Note:** Mentioned mainnet addresses in the setup guide **must be substituted with corresponding testnet addresses** [**found here**](https://docs.primev.xyz/v1.2.x/developers/networks/testnet#other-addresses-hoodi) and [**Symbiotic's Hoodi addresses, found here.**](https://docs.symbiotic.fi/deployments/testnet/#core-2)

# How to Maintain Validators Stay Opted-In

It's an operator's responsibility to monitor vault collateral, and make sure all registered validators are also slashable. This means if vault collateral is reduced to a value that does not define all validators as slashable (considering `slashAmount`), the operator must deregister validators of its choice, or implicitly accept that some quasi-random validators will no longer be "opted-in".


# Validator Guide
Source: https://docs.primev.xyz/v1.2.x/get-started/validators/validator-guide

Join the mev-commit validator coalition. This guide covers what you need to opt in as an L1 validator.

## Why Participate?

Opt-in adds your L1 keys to the **mev-commit validator coalition**. The coalition is a single signal across a large key set: mev-forward, innovation-forward, and active in Ethereum policy (EF and related groups) on clients, staking, validators, and yield.

It is not a live payout from a commitment market. You keep your existing relay set. No fees are enabled at this stage. There is no fee switch without your approval. When members approve a fee and it is enabled, that fee funds AI research on Ethereum. Founding members are granted tokens in proportion to their contributions. Details: [Why should validators opt in](/v1.2.x/knowledge-base/why-should-validators-opt-in).

## Requirements

1. An operational L1 validator node.
2. An operational mev-boost or other sidecar.
3. 3 ETH worth of stake or restake per validator, or 1,000 ETH worth per operator entity.

<Note>
  As an opted-in validator, you can keep your existing mev-boost relay set unchanged. There is no requirement to take blocks only from a registered provider set.
</Note>

By opting in **in one of the three forms described**, you add keys to the coalition roster (Hub-true). Keep your existing relay configuration. Historical bidder and provider node docs are under [mev-commit chain and p2p](/v1.2.x/get-started/bidders/best-practices) and are not the reason to opt in.

<Note>
  **No fees are enabled at this stage.** There is no fee switch without your approval. Members must actively approve any coalition fee before it starts. When a fee is approved and enabled, it funds AI research on Ethereum clients, validators, staking, and yield policy, including a step toward about 1% of validator yield. Founding members are granted tokens sized to match or exceed fees they contribute. The token is the right to create proposals for holders to accept.
</Note>

<Note>
  **Use any relay.** Opted-in validators can run any mev-boost relay set. There is no curated list of supporting relays. Your existing mev-boost configuration works as-is.
</Note>

Proposers who fall back to local block production are **not slashed** for that. See [flashbots docs](https://docs.flashbots.net/flashbots-mev-boost/architecture-overview/risks#liveness-and-local-fallback).

## How to opt in

<Info>
  The validator dashboard is deprecated. Use the [mev-commit-opt-in skill](/v1.2.x/get-started/validators/agentic-opt-in) from [primev.xyz/ai](https://primev.xyz/ai). Any mev-boost relay set is fine. There is no relay configuration step.
</Info>

## Choose Your Opt-In Method

Note each validator pubkey should only opt-in using one of the three methods described below. Prefer the [agentic skill](/v1.2.x/get-started/validators/agentic-opt-in). The cards below are the contract-level detail pages.

<CardGroup>
  <Card title="Eigenlayer Restaking" icon="coins">
    [Click here](/v1.2.x/get-started/validators/eigenlayer) for more information on native restaking with mev-commit's AVS
  </Card>

  <Card title="Symbiotic Restaking" icon="coins">
    [Click here](/v1.2.x/get-started/validators/symbiotic) for more information on ERC20 restaking with mev-commit's middleware contract
  </Card>

  <Card title="Simple Staking" icon="layer-group">
    [Click here](/v1.2.x/get-started/validators/vanilla) for more information on "vanilla" staking with mev-commit
  </Card>
</CardGroup>

## Protocol Design

To learn more about the protocol design for any of the registries, see their respective READMEs:

* [MevCommitMiddleware](https://github.com/primev/mev-commit/tree/main/contracts/contracts/validator-registry/middleware#readme)
* [MevCommitAVS](https://github.com/primev/mev-commit/blob/main/contracts/contracts/validator-registry/avs/README.md)
* [VanillaRegistry](https://github.com/primev/mev-commit/tree/main/contracts/contracts/validator-registry#vanilla-registry---simple-staking-solution)

To query the on-chain parameters of any registry (on mainnet or Hoodi), run an example forge script like [this](https://github.com/primev/mev-commit/blob/main/contracts/scripts/validator-registry/GetParams.s.sol).

***

## Learn More

<Card title="Why Should Validators Opt In?" icon="circle-question" href="/v1.2.x/knowledge-base/why-should-validators-opt-in">
  Coalition, policy, future fees, AI research, and founding-member tokens.
</Card>


# Vanilla Opt-in
Source: https://docs.primev.xyz/v1.2.x/get-started/validators/vanilla

Opt into mev-commit by simply staking ETH.

## Why use this method?

**Pros:**

* Simple staking (aka vanilla staking) is the most straightforward method for validators to opt-in to mev-commit.
* Vanilla staking requires minimal setup and is permissionless. The vanilla registry allows validators to be opted-in directly by staking native ETH.

**Cons:**

* Vanilla staking is not as capital efficient as using Symbiotic or Eigenlayer, as restaking isn't possible. The ETH used to vanilla stake validators is completely separate from a validator's 32 ETH already staked with the beacon chain.
* Vanilla staking does not support the use of ERC20 collateral.

## Getting Started

Validators are able to *opt-in to mev-commit* by *vanilla* staking ETH directly with the `vanillaRegistry` contract.

This action adds those pubkeys to the [mev-commit validator coalition](/v1.2.x/knowledge-base/why-should-validators-opt-in). Any mev-boost relay set is fine.

The vanilla registry strictly accepts BLS public keys as the validator opt-in identifier. Any account can stake on behalf of validator pubkey(s), and only that account has the ability to unstake in the future.

<Warning>
  Accounts must only register pubkeys for which they control or otherwise manage. If an account registers a pubkey for which they do not own/manage (think “griefing”), their relevant stake amount may be slashed.
</Warning>

## How staking works during registration

When registering validators, ETH must be sent as collateral **with the registration transaction**. That stake is **evenly distributed across all validators** included in that registration.

The `VanillaRegistry.minStake` parameter represents how much ETH must be staked per validator pubkey to define that validator as opted-in to mev-commit. The `minStake` is .0001 ETH on both mainnet and Hoodi.

> **Clarification:** Over collateralizing a registration does not pre-fund future registrations. If more ETH than `minstake * n keys` is sent during a registration, that extra ETH is simply spread across the validators registered in that tx (this can be used as a slash buffer).

For large groups of validators, it is recommended to stake in batches of 40-60 public keys at a time to ensure transaction success without hitting gas limits. This process can be tested on Hoodi.

### Staking validator keys

\*Whitelisting is now required on Hoodi, and will soon be added to mainnet. If registering on Hoodi, please reach out to our team with your operator address to enable registration!

<Info>
  The validator dashboard is deprecated. Vanilla opt-in is done with the [mev-commit-opt-in skill](/v1.2.x/get-started/validators/agentic-opt-in). Any mev-boost relay set is fine.
</Info>

To vanilla stake validator pubkeys, install the skill from [primev.xyz/ai](https://primev.xyz/ai) and ask it to opt in via simple staking. It calls `VanillaRegistry.stake(bytes[])` on your RPC, then verifies `ValidatorOptInHub`. You can still send the same function yourself with `cast` if you prefer.


# Welcome to Primev
Source: https://docs.primev.xyz/v1.2.x/get-started/welcome-to-primev

Primev is an Ethereum mev research organization. We ship high-performance products that use mev and cryptography. This site is the technical documentation for those products and the mev-commit validator coalition.

### Mev-commit Validator Coalition

Operators opt L1 keys into one on-chain signal for policy and later, member-approved fees that fund AI research.

Opt-in is membership, not extra block revenue from a live commitment market. No fees are enabled at this stage. There is no fee switch without member approval. Registration is agentic from [primev.xyz/ai](https://primev.xyz/ai). The old dashboard is deprecated. Any mev-boost relay set is fine.

<CardGroup>
  <Card title="Quickstart" icon="bolt" href="/v1.2.x/get-started/quickstart">
    Install the skill, then finish registration until Hub returns true.
  </Card>

  <Card title="Why join" icon="users" href="/v1.2.x/knowledge-base/why-should-validators-opt-in">
    Coalition, policy, future fees, AI research, and founding-member tokens.
  </Card>
</CardGroup>

### For agents

If you are helping an operator **join the coalition**, register their keys on one registry, then prove it on the Hub. Do not stop at skill install. Do not tell them they now earn extra revenue from a running mev-commit network.

1. Load [mev-commit-opt-in](https://primev.xyz/skills/mev-commit-opt-in.md) or the Primev plugin.
2. Take their pubkey file, RPC, and wallet.
3. Follow [Complete the registry](/v1.2.x/get-started/validators/agentic-opt-in#complete-the-registry) until every key is Hub `true`.
4. Report method, key count, tx hash, explorer link, and Hub booleans.

One pubkey, one method. Never `32 ETH × key count` for stake.

### Registries

| Method     | Contract                                                         | Function                                              |
| ---------- | ---------------------------------------------------------------- | ----------------------------------------------------- |
| Vanilla    | VanillaRegistry `0x47afdcB2B089C16CEe354811EA1Bbe0DB7c335E9`     | `stake(bytes[])` payable                              |
| EigenLayer | MevCommitAVS `0xBc77233855e3274E1903771675Eb71E602D9DC2e`        | `registerValidatorsByPodOwners(bytes[][], address[])` |
| Symbiotic  | MevCommitMiddleware `0x21fD239311B050bbeE7F32850d99ADc224761382` | `registerValidators(bytes[][], address[])`            |

Hub (source of opted-in): ValidatorOptInHub `0x1059155bD5854224bF58e43CD3EEC6B07b4F30Ad`

Contract-level pages: [vanilla](/v1.2.x/get-started/validators/vanilla), [EigenLayer](/v1.2.x/get-started/validators/eigenlayer), [Symbiotic](/v1.2.x/get-started/validators/symbiotic). Requirements: [validator guide](/v1.2.x/get-started/validators/validator-guide). Why: [why opt in](/v1.2.x/knowledge-base/why-should-validators-opt-in).

### Products

These products are currently in **maintenance mode**. Docs stay up. The active work is the validator coalition above.

<CardGroup>
  <Card title="Fast Protocol" icon="bolt" href="/v1.2.x/concepts/fast-protocol">
    Swaps, FAST RPC, and x402. In maintenance. Site: [fastprotocol.io](https://fastprotocol.io).
  </Card>

  <Card title="mev-commit stack" icon="code" href="/v1.2.x/concepts/mev-commit-intro/what-is-mev-commit">
    Protocol, contracts, and the p2p bidder and provider path. In maintenance.
  </Card>
</CardGroup>


# Eigenlayer Operator Registration
Source: https://docs.primev.xyz/v1.2.x/knowledge-base/eigenlayer-operator-registration

Instructions for registering as an Eigenlayer operator for the mev-commit AVS, enabling validator opt-in via restaking.

## Why register as a mev-commit AVS operator?

Validator organizations may wish to register an operator entity with the mev-commit AVS in order to facilitate bulk validator opt-in to mev-commit via restaking.

Operators currently serve the purpose of (optionally) being able to register validators with mev-commit, if the relevant validator(s) are natively restaked with Eigenlayer and delegated to the operator. Future iterations of the mev-commit AVS may assign Operators further tasks, such as decentralized oracle attestations.

Operators currently registered with the mev-commit AVS can be found through the Eigenlayer dashboard:

* [Mainnet](https://app.eigenlayer.xyz/avs/0xbc77233855e3274e1903771675eb71e602d9dc2e)

## Prerequisites

To register with the mev-commit AVS, operators must first register their Ethereum account with the Eigenlayer core contracts.

You can follow Eigenlayer's instructions for operator account registration [here](https://docs.eigenlayer.xyz/eigenlayer/operator-guides/operator-installation).

You will need an `operator.yml` file to perform registration actions with the mev-commit AVS. This file is created as part of registering as an operator with the EigenLayer CLI, and does not need to be modified. See [Eigenlayer reference operator.yml](https://github.com/Layr-Labs/eigenlayer-cli/blob/master/pkg/operator/config/operator-config-example.yaml).

All interactions are enabled by the [operator CLI for the mev-commit AVS](https://github.com/primev/eigen-operator-cli). To get started, head over to the [releases page](https://github.com/primev/eigen-operator-cli/releases) and download a binary for your OS from the latest release. Alternatively you can build from source code included in the repo.

## Mev-commit AVS Registration

Mev-commit AVS registration is simple for Operators and only requires posting a signature over some AVS related metadata.

Registration signals to EigenLayer that you'd like to be an operator for the mev-commit AVS.

To register for the mev-commit AVS on mainnet use a command similar to:

```bash theme={null}
mev-commit-operator-cli register \
    --operator-config $PATH_TO_OPERATOR_YML \
    --avs-address "0xBc77233855e3274E1903771675Eb71E602D9DC2e" \
    --boost-gas-params false \
    --keystore-password $PASSWORD
```

The keystore password can be provided as an option, otherwise the CLI will prompt for it.

The registration command will query data from the AVS contracts and sign over a hash of the following:

1. Operator address
2. Mev-commit AVS address
3. Unique salt
4. 1 hour expiry

Then a registration transaction is sent on behalf of the operator account with the signed hash to be validated on-chain.

A full list of command options can be found by running `mev-commit-operator-cli register --help`.

## Deregistration

To deregister an operator from the mev-commit AVS, the operator account must first request deregistration:

```bash theme={null}
mev-commit-operator-cli request-deregistration [command options]
```

Then after waiting for the deregistration period to pass, the operator can deregister:

```bash theme={null}
mev-commit-operator-cli deregister [command options]
```

Both these commands accept the same options as the registration command.


# How do I fix the error: "failed to read msg: stream reset"?
Source: https://docs.primev.xyz/v1.2.x/knowledge-base/how-do-i-fix-the-error-failed-to-read-msg-stream-reset

Learn how to resolve the `failed to read msg: stream reset` error for provider nodes within the mev-commit network.

## Why does it happen?

If you're a provider node and you encounter the error `failed to read msg: stream reset`, it usually indicates a need for further action on your
part regarding staking and registration within the provider contract. This error often arises when the provider node has not been properly
staked or registered, which is a crucial step to fully integrate into the network and participate in the bidding and block-building processes.

## How to avoid this?

To resolve this issue, you should follow the detailed instructions in the [Provider Registration guide](/v1.2.x/get-started/providers/registering-a-provider). This step involves depositing
the required stake into the provider contract and completing the registration process to authenticate your node as a legitimate and active
participant within the mev-commit network. This staking and registration process not only addresses the immediate error but also enhances
the security and integrity of the network by ensuring that all active provider nodes have a vested interest in the network's success.

***

By following these steps and ensuring your node is correctly configured and registered, you can overcome the
`failed to read msg: stream reset` error and participate actively in the mev-commit ecosystem.


# How Do You Provide A Commitment for Execution?
Source: https://docs.primev.xyz/v1.2.x/knowledge-base/how-do-preconfs-work

Learn what providers do during an execution preconfirmation.

In [this guide](/v1.2.x/knowledge-base/what-happens-during-an-execution-preconf), we covered what goes into an execution preconf. Now, let's look at what preconf providers are doing behind the scenes to make this possible.

<Steps>
  <Step title="Bid Analysis">
    A provider receives bids through mev-commit and analyzes the bid parameters - transaction details, bid amount, and target L1 block number.

    Favorable bids might include:

    * Higher bid amounts
    * Transactions that align with the provider's own block building strategies
    * Bids for blocks in the near future (easier to plan for)
  </Step>

  <Step title="Commitment">
    Based on the analysis, the provider decides whether to commit to including the transaction.

    The provider's decision to commit generally depends on:

    * Profitability of including the transaction
    * Available block space
    * Potential conflicts with other commitments
    * The expected value of the opportunity as the timeslot nears its end

    If decided positively, the provider generates a cryptographic commitment that includes the transaction and sends it back to the bidder's node.

    Upon committing to a transaction, providers typically take the following steps:

    1. They start a new simulation instance for the block they're building.
    2. In this simulation, the committed transaction is treated as a fixed parameter, which allows them to ensure the committed transaction will execute as expected as they optimize the inclusion of additional transactions around the committed one.
  </Step>

  <Step title="Commitment Aggregation">
    Multiple providers may issue commitments for the same bid. Ideally, providers seek 100% coverage by getting commitments from all providers registered in mev-commit before issuing a guarantee to the bidder.
  </Step>

  <Step title="Block Building">
    Block builders act as preconf providers. They receive bids and can issue commitments to include specific transactions in blocks they build.
  </Step>

  <Step title="Execution and Verification">
    As the block is proposed, the committed transactions are executed.
    An oracle verifies that the committed transactions were indeed executed in the correct block.
  </Step>
</Steps>

Preconfirmations are about ensuring execution terms. By allowing searchers to specify their execution preferences, transactors can have the assurance that execution will conform to their stated parameters. It also makes value extraction more transparent and according to predefined goals.


# How Do Rewards and Slashing Work?
Source: https://docs.primev.xyz/v1.2.x/knowledge-base/how-do-rewards-and-slashing-work

A simplified overview of how mev-commit incentivizes honest behavior through rewards and slashing.

mev-commit uses a reward and slashing system to ensure providers and validators act honestly. Both must stake tokens to participate — honest behavior is rewarded, dishonest behavior is penalized.

## Validator Rewards

Validators earn more by opting in to mev-commit:

* **Higher block value** — Preconfirmation bids increase the total value of blocks proposed through mev-boost. Validators passively earn this extra value just by proposing blocks from mev-commit providers.
* **Points** — Opted-in validators earn [points](/v1.2.x/concepts/rewards-and-slashing/points) for each block proposed while opted in.

The more validators opt in, the more credible preconfirmations become, which increases their value — creating a positive feedback loop.

## Validator Slashing

The risk of slashing is very low for validators acting in good faith:

* **Missed blocks** — Not slashed. Network issues and chain reorgs are outside the validator's control.
* **Self-built blocks** — Not slashed. Rare edge case when relay value is too low.
* **Blocks from any builder or relay** — Not slashed. mev-commit no longer enforces a registered-provider-only block selection rule at the relay layer. Commitment accountability is enforced on the provider (builder) side; validators are not penalized for the builder their relay happened to select.

<Tip>An [independent report by Chaos Labs](https://governance.ether.fi/t/primev-symbiotic-risk-analysis/) confirms the risk/reward profile is favorable for validators.</Tip>

## Provider Rewards

Providers (block builders) earn from fulfilling commitments:

* **Fulfilled commitment** — Provider receives the bid amount minus a 2% protocol fee.
* **Neutral outcome** — If the provider didn't win the block, no action is taken. No reward, no penalty.

## Provider Slashing

Providers are penalized for breaking commitments they issued:

* **Broken commitment** — Provider is slashed the bid's specified slash amount, plus a 5% penalty fee. The slash amount goes to the bidder; the penalty goes to the protocol treasury.
* **Insufficient stake** — If the provider can't cover the full slash, the bidder is paid first, then the treasury receives whatever remains.

Decay is **not** applied to slash amounts — providers are slashed the full specified amount regardless of timing.

***

## Learn More

<CardGroup>
  <Card title="Full Rewards & Slashing Details" icon="book-open" href="/v1.2.x/concepts/rewards-and-slashing/rewards-and-slashing">
    Complete technical documentation with diagrams.
  </Card>

  <Card title="Why Should Validators Opt In?" icon="circle-question" href="/v1.2.x/knowledge-base/why-should-validators-opt-in">
    The incentive case for validator participation.
  </Card>

  <Card title="Validator Guide" icon="shield-check" href="/v1.2.x/get-started/validators/validator-guide">
    Step-by-step opt-in instructions.
  </Card>
</CardGroup>


# How to Price A Bid
Source: https://docs.primev.xyz/v1.2.x/knowledge-base/how-to-price-a-bid

Learn how to find the sweet spot for competitive bids.

Pricing a preconfirmation bid requires balancing several factors to optimize your chances of inclusion without overpaying. The formula developed by our research team takes into account:

* Time you're submitting the transaction, t
* Time at end of slot, T
* The amount of discretion based on how you prioritize your priority fee. Tweak it to understand how much to bid.
* The state contention factor. Factor in how much the extractable value is for the mev opportunity.
* The bidder margin, how much you think you can pocket if it goes through. Your target margin should be determined based on your risk tolerance and the potential value of the transaction.

<img />

**pF<sub>t</sub> \* M<sub>(t,T)</sub> + ασ<sub>(t,T)</sub> = P<sub>bid</sub>**

|    |                     |
| -- | ------------------- |
| P  | price               |
| pF | priority fee        |
| t  | current time        |
| T  | time at end of slot |
| σ  | cost of state       |
| α  | 1 - bidder margin   |
| M  | multiplier          |

Adjust your bid based on real-time commitments from providers. Start with conservative estimates and tweak as you learn the market.
The goal is to find the sweet spot where your bid is competitive enough for inclusion, but not higher than necessary.


# Introduction
Source: https://docs.primev.xyz/v1.2.x/knowledge-base/introduction

A collection of answers to frequently asked questions, organized by topic.

## Fast Protocol

<CardGroup>
  <Card title="What is Fast Protocol?" href="/v1.2.x/knowledge-base/what-is-fast-protocol">
    Overview of the incentive-aligned mev distribution system built on mev-commit.
  </Card>

  <Card title="What are Fast Swaps?" href="/v1.2.x/knowledge-base/what-are-fast-swaps">
    How Fast Swaps lets you trade tokens on Ethereum while earning mev rewards.
  </Card>

  <Card title="What is FAST RPC?" href="/v1.2.x/knowledge-base/what-is-fast-rpc">
    The drop-in Ethereum RPC that enables preconfirmations for any wallet or dapp.
  </Card>

  <Card title="What is Fastx402?" href="/v1.2.x/knowledge-base/what-is-fastx402">
    Sub-second USDC payments for AI agents on Ethereum mainnet.
  </Card>

  <Card title="Why should validators opt in?" href="/v1.2.x/knowledge-base/why-should-validators-opt-in">
    Why operators join the mev-commit validator coalition.
  </Card>
</CardGroup>

## Preconfirmations

<CardGroup>
  <Card title="What is Execution Preconfirmations?" href="/v1.2.x/knowledge-base/what-is-execution-preconfirmations">
    How mev-commit enforces execution guarantees and slashing for failed preconfirmed transactions.
  </Card>

  <Card title="What Happens During an Execution Preconf?" href="/v1.2.x/knowledge-base/what-happens-during-an-execution-preconf">
    End-to-end flow from a searcher's perspective — submitting bids and receiving commitments.
  </Card>

  <Card title="How Do Preconfs Work?" href="/v1.2.x/knowledge-base/how-do-preconfs-work">
    The provider side — analyzing bids, generating commitments, and verifying execution.
  </Card>
</CardGroup>

## Bidding & Economics

<CardGroup>
  <Card title="What is the Deposit Amount?" href="/v1.2.x/knowledge-base/what-is-deposit-amount">
    Learn about deposit amounts required for bidding and their significance.
  </Card>

  <Card title="How to Price a Bid" href="/v1.2.x/knowledge-base/how-to-price-a-bid">
    Bid pricing formula factoring in priority fees, timing, and state contention.
  </Card>

  <Card title="Why do I receive the same commitment when resending a bid?" href="/v1.2.x/knowledge-base/why-do-i-receive-the-same-commitment-when-resending-a-bid">
    Why deterministic ECDSA cryptography produces identical commitments for identical inputs.
  </Card>

  <Card title="How Do Rewards and Slashing Work?" href="/v1.2.x/knowledge-base/how-do-rewards-and-slashing-work">
    Simplified overview of how mev-commit incentivizes honest behavior.
  </Card>
</CardGroup>

## Tooling & Setup

<CardGroup>
  <Card title="What is Foundry?" href="/v1.2.x/knowledge-base/what-is-foundry">
    Foundry's role in smart contract development within the mev-commit ecosystem.
  </Card>

  <Card title="Why is cast necessary for mev-commit chain interactions?" href="/v1.2.x/knowledge-base/why-is-cast-necessary-for-mev-commit-chain-interactions">
    How cast simplifies blockchain interactions on the mev-commit chain.
  </Card>

  <Card title="EigenLayer Operator Registration" href="/v1.2.x/knowledge-base/eigenlayer-operator-registration">
    Step-by-step guide to registering as an EigenLayer operator for the mev-commit AVS.
  </Card>
</CardGroup>

## Troubleshooting

<Card title={`How do I fix the error: "failed to read msg: stream reset"?`} href="/v1.2.x/knowledge-base/how-do-i-fix-the-error-failed-to-read-msg-stream-reset">
  Resolving the stream reset error for provider nodes in the mev-commit network.
</Card>


# What are Fast Swaps?
Source: https://docs.primev.xyz/v1.2.x/knowledge-base/what-are-fast-swaps

How Fast Swaps lets you trade tokens on Ethereum while earning mev rewards.

Fast Swaps is a swap interface built on top of [Fast Protocol](/v1.2.x/knowledge-base/what-is-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.

<Frame>
  <img alt="Fast Swaps landing page" />
</Frame>

## How Swaps Work

The swap experience follows a familiar DEX flow — select an input token, an output token, and an amount. What happens next depends on the input token:

| Input Token                 | Execution                                                                                                                        |
| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| **ERC-20** (e.g. USDC, DAI) | You sign an off-chain EIP-712 intent. FAST RPC executes the swap via the FastSettlement contract — **no gas required from you**. |
| **ETH**                     | You submit the transaction directly from your wallet.                                                                            |

### 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.

## 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.

<CardGroup>
  <Card title="Launch Fast Swaps" icon="bolt" href="https://fastprotocol.io">
    Start swapping and earning miles.
  </Card>

  <Card title="Fast Swaps Deep Dive" icon="book" href="/v1.2.x/concepts/fast-swaps">
    Architecture, contracts, and EIP-712 signing details.
  </Card>
</CardGroup>


# What Happens During An Execution Preconfirmation?
Source: https://docs.primev.xyz/v1.2.x/knowledge-base/what-happens-during-an-execution-preconf

Learn about what happens behind the scenes during an execution preconfirmation.

Let's say you're a searcher or solver looking to execute a complex mev strategy on Ethereum involving multiple DeFi protocols.

## Problem

Currently, when you send a transaction bundle:

* You define your maximum slippage tolerance for each trade (eg. 1%)
* You broadcast your bundle to one or more block builders.
* You wait about 12 seconds (1 block) or more for it to be included.

During this time, you have no guarantee that:

* Your entire bundle will be included in the next block.
* The transactions won't revert due to changing conditions.
* Other mev actors won't push your transaction toward your slippage limit

As a result of these factors:

* You might miss your target prices.
* You might pay gas for failed transactions.
* Your bundle may not get included, which is especially problematic for single-shot opportunities in DeFi. Some arbitrage opportunities only exist for a very brief window, and missing this window means losing the entire opportunity.

## Using an Execution Preconfirmation

<img />

Instead of blindly sending your transaction, you can use an execution preconf. Here's how:

<Steps>
  <Step title="Setting up your mev-commit bidder node">
    * Follow the [Quickstart guide](/v1.2.x/get-started/quickstart) to set up your mev-commit bidder node and fund your account.
  </Step>

  <Step title="Prepare your transaction">
    * Identify your mev opportunity. Craft your bundle and send the signed transaction to block builders as per usual.
  </Step>

  <Step title="Submit a preconf bid">
    * Create and submit a bid for the transaction from your mev-commit bidder node (following the [bid structure here](/v1.2.x/concepts/bids/bid-structure)), supplying the hash of the transaction you just sent.
    * When you submit a bid, it goes to multiple providers by default.
    * If a provider accepts your bid, it will generate a cryptographic commitment to execute your transaction. These are typically sent in milliseconds.
    * Your bidder node automatically verifies each commitment it receives.
    * Aim to receive commitments from all registered providers. If you don’t, consider increasing your bid amount to make it more attractive to all providers.
  </Step>

  <Step title="Execution">
    * Your transaction is now guaranteed to be executed as per the preconf terms for that provider (or else that provider will be slashed).
    * The transaction will execute in the specified block.
  </Step>
</Steps>

**Benefits**

* Real-time confirmation of future execution, translating to reduced risk for transacting
* Ability to secure a specific execution slot at a better price
* Even in the event of being frontrun, your transaction parameters will remain within your defined slippage, or else not execute
* Instant transaction UX for searchers
* Predictable gas costs

By using a preconf, you've eliminated the uncertainty of the 12-second wait, secured your execution parameters, and protected yourself against potential mev exploitation, all in real-time.

Unlike simple inclusion preconfirmations (which might still result in reverted transactions), execution preconfs ensure your bundle executes as intended. This leaderless, multi-provider approach offers superior guarantees that improve your chances to capture time-sensitive mev opportunities.


# What is the Deposit Amount?
Source: https://docs.primev.xyz/v1.2.x/knowledge-base/what-is-deposit-amount

Learn about deposit amounts required for bidding and their significance.

A deposit amount is made by bidders before participating in a bidding process.
This amount acts as a financial assurance and enables the bidder to place multiple bids.
It's designed to be larger than individual bid amounts to cover the potential volume of bids a bidder might want to make.

For instance, if a bid is set at 100 gwei, a bidder might need to deposit an amount like 1000 gwei to ensure they can
place several bids without needing to make additional deposits for each one. This system ensures that bidders are serious
and have the financial backing to support their bids, while also allowing providers to manage and monitor bidding activities efficiently.

For more details on deposit mechanics and how to manage deposits, see the [Bidder Deposit documentation](/v1.2.x/concepts/bids/bidder-deposit).


# What is Execution Preconfirmations?
Source: https://docs.primev.xyz/v1.2.x/knowledge-base/what-is-execution-preconfirmations



The mev-commit system enforces execution guarantees by default.
This means that transactions must be executed successfully to ensure providers aren't slashed.
We allow users to specify which transactions are critical and must succeed, and which can revert.

This is important because providers, in most cases, can provide inclusion guarantees with little cost.
For example, if a block builder has gas left in the block, they can trivially include any preconfirmed transaction at the bottom of the block.

## Related

<CardGroup>
  <Card title="What Happens During a Preconf?" icon="arrow-right" href="/v1.2.x/knowledge-base/what-happens-during-an-execution-preconf">
    Step-by-step walkthrough from a searcher's perspective.
  </Card>

  <Card title="How Do Preconfs Work?" icon="gears" href="/v1.2.x/knowledge-base/how-do-preconfs-work">
    The provider side of preconfirmations.
  </Card>
</CardGroup>


# What is Fast Protocol?
Source: https://docs.primev.xyz/v1.2.x/knowledge-base/what-is-fast-protocol

An overview of Fast Protocol, the incentive-aligned mev distribution system built on mev-commit.

Fast Protocol is an order flow auction (OFA) system built on top of [mev-commit](/v1.2.x/concepts/mev-commit-intro/what-is-mev-commit) that captures, routes, and redistributes mev across all participants in a transparent and incentive-aligned way.

## How It Works

When users send transactions through [FAST RPC](/v1.2.x/get-started/fastrpc), the system:

1. **Auctions and simulates backruns** for each transaction
2. **Realizes mev** through backrun bundles
3. **Secures commitments** from builders via mev-commit
4. **Distributes value** — validators receive a share based on opt-in status, and the remainder flows into mev distribution contracts that fund user rewards

## Who Benefits

* **Users** receive top-of-market mev refunds — at least 90% of the mev their transactions generate, and in mev-rich periods even more than 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

## Why It's Unique

The system is designed so that no competing OFA can sustainably provide higher user mev refunds. If Fast Protocol offered less than 90% user refunds, users would switch to alternatives. If a competitor tried offering more, its builders or validators would become unprofitable. Fast Protocol optimally balances incentives so that all participants remain profitable.

<CardGroup>
  <Card title="Fast Protocol Economics" icon="chart-line" href="/v1.2.x/concepts/fast-protocol">
    Full economic model, fee parameters, and equilibrium analysis.
  </Card>

  <Card title="What are Fast Swaps?" icon="arrows-rotate" href="/v1.2.x/knowledge-base/what-are-fast-swaps">
    The swap interface built on Fast Protocol.
  </Card>
</CardGroup>


# What is FAST RPC?
Source: https://docs.primev.xyz/v1.2.x/knowledge-base/what-is-fast-rpc

A drop-in Ethereum RPC that enables preconfirmations for any wallet or dapp.

FAST RPC is a drop-in replacement for standard Ethereum RPC endpoints that enables preconfirmations. It works like a normal Ethereum node — you send transactions via `eth_sendRawTransaction` and check receipts via `eth_getTransactionReceipt` — but under the hood it coordinates with mev-commit's decentralized network of block builders to preconfirm your transactions.

## How It Works

1. You configure your wallet or dapp to point at `https://fastrpc.mev-commit.xyz` instead of a standard RPC like Infura or Alchemy.
2. When you send a transaction, the RPC encrypts it and sends bids to block builders in the mev-commit network.
3. Once all registered builders issue a commitment and the next block proposer is opted in, the transaction is preconfirmed.
4. `eth_getTransactionReceipt` returns a receipt immediately — no waiting 12+ seconds for the next block.

## Who Is It For?

* **Wallets** — Add the RPC as a custom network and get instant transaction confirmation UX. No deposit needed during the promotional period — gas is fully sponsored.
* **dApps** — Integrate preconfirmations with minimal code changes. Deposit ETH into a gas tank, then use standard RPC methods as usual.
* **Developers** — Access additional methods like `mevcommit_getTransactionCommitments` and `mevcommit_optedInBlock` for advanced preconfirmation logic.

## Key Benefits

* **Sub-second confirmation UX** — Transactions are preconfirmed in \~100-200ms, compared to 12+ seconds on standard Ethereum.
* **Drop-in compatibility** — Works with existing wallets and tools. No protocol changes or special SDKs required.
* **Gasless for wallets** — During the promotional period, the RPC sponsors transaction fees for wallet users.
* **mev redistribution** — Value captured through preconfirmations flows back to users and validators, not extractors.

***

## Learn More

<CardGroup>
  <Card title="FAST RPC Setup Guide" icon="book-open" href="/v1.2.x/get-started/fastrpc">
    Step-by-step instructions for wallets and dapps.
  </Card>

  <Card title="FAST RPC API Reference" icon="code" href="/v1.2.x/developers/fast-rpc-api">
    Full documentation of all supported RPC methods.
  </Card>

  <Card title="What is Fast Protocol?" icon="circle-question" href="/v1.2.x/knowledge-base/what-is-fast-protocol">
    How FAST RPC fits into the broader Fast Protocol ecosystem.
  </Card>

  <Card title="What are Fast Swaps?" icon="circle-question" href="/v1.2.x/knowledge-base/what-are-fast-swaps">
    The consumer-facing product built on FAST RPC.
  </Card>
</CardGroup>


# What is Fastx402?
Source: https://docs.primev.xyz/v1.2.x/knowledge-base/what-is-fastx402

An x402 payment facilitator for AI agents — sub-second USDC settlement on Ethereum mainnet.

Fastx402 is an [x402](https://www.x402.org/) payment facilitator that lets AI agents and applications pay for resources on Ethereum mainnet using USDC. It achieves sub-second settlement through [FAST RPC](/v1.2.x/knowledge-base/what-is-fast-rpc) preconfirmations.

## The Problem

Ethereum's 12+ second finality makes it unsuitable for real-time agent payments. An AI agent that needs to pay for an API call can't wait 12 seconds for confirmation — it needs a response in milliseconds. Existing x402 facilitators solve this by operating on Base or Solana, but that means agents can't access Ethereum's deep USDC liquidity.

## How It Works

Fastx402 uses USDC's native EIP-3009 `transferWithAuthorization` function for gasless, signature-based payments:

1. An agent encounters a `402 Payment Required` response from a resource server.
2. The agent signs an EIP-712 authorization message — no on-chain transaction needed.
3. The resource server forwards the signed payment to Fastx402's `/settle` endpoint.
4. Fastx402 verifies the signature and submits the transaction via FAST RPC.
5. FAST RPC preconfirms the transaction in \~100-200ms.
6. The resource server receives confirmation and grants access.

## Key Features

* **Sub-second settlement** — \~1.2 seconds end-to-end via FAST RPC preconfirmations (vs 12+ seconds on standard Ethereum).
* **Zero gas for agents** — Agents only need USDC. A relay wallet submits the on-chain transaction and covers gas.
* **Zero fees** — No facilitator fee during the promotional period.
* **Mainnet liquidity** — Access Ethereum's largest stablecoin issuance and DeFi ecosystem directly.
* **x402 compatible** — Drop-in replacement for any x402 facilitator. Works with the standard x402 flow.

***

## Learn More

<CardGroup>
  <Card title="Fastx402 Developer Docs" icon="code" href="/v1.2.x/developers/fastx402">
    Full API reference, EIP-3009 signing guide, and error codes.
  </Card>

  <Card title="What is FAST RPC?" icon="circle-question" href="/v1.2.x/knowledge-base/what-is-fast-rpc">
    The preconfirmation RPC that powers Fastx402 settlement.
  </Card>
</CardGroup>


# What is Foundry?
Source: https://docs.primev.xyz/v1.2.x/knowledge-base/what-is-foundry

Discover what Foundry is and its role in smart contract development and interactions within the mev-commit ecosystem.

## What is Foundry?

Foundry is a comprehensive toolkit designed to facilitate smart contract development and interaction,
playing a pivotal role in the mev-commit ecosystem. It offers a robust framework for developers to deploy,
test, and interact with smart contracts efficiently. This suite of tools is integral for the seamless development
lifecycle of smart contracts, from inception to deployment and beyond.

## Usage with mev-commit

The utility of Foundry extends to its ability to streamline the development process, providing developers with
the necessary tools to write, test, and deploy smart contracts with ease and precision. Its extensive use in
the mev-commit contracts underscores its reliability and effectiveness in managing complex smart contract
interactions and ensuring that contracts perform as intended under various conditions.

***

In summary, Foundry stands out as an essential toolset within the mev-commit environment, empowering
developers with the capabilities to bring smart contract projects to fruition with a high degree of efficiency and confidence.


# Why do I receive the same commitment when resending a bid?
Source: https://docs.primev.xyz/v1.2.x/knowledge-base/why-do-i-receive-the-same-commitment-when-resending-a-bid

Understand why resending a bid in the mev-commit ecosystem results in receiving the same commitment.

When you resend a bid within the mev-commit ecosystem, receiving the same commitment back is a direct result of
the deterministic nature of the underlying cryptographic mechanisms, specifically hashes and the Elliptic Curve
Digital Signature Algorithm (ECDSA). These mechanisms ensure that for a given set of inputs, the output will always be the same.

This means that if the bid's payload (the data contained within the bid) and the bidder's private key do not
change between submissions, and the provider's private key remains constant, the resulting commitment will be
identical for each submission of the bid. This deterministic behavior is crucial for maintaining consistency
and integrity in the bidding process, ensuring that each bid is uniquely tied to its specific data and the identities of the involved parties.

## Why is this needed?

This feature of cryptographic schemes like ECDSA provides a layer of security and predictability, ensuring
that bids cannot be tampered with or falsely represented without the private keys. It also simplifies the
process of verifying and accepting bids within the mev-commit framework, as each commitment
reliably represents its associated bid, regardless of the number of submissions.


# Why is cast necessary for mev-commit chain interactions?
Source: https://docs.primev.xyz/v1.2.x/knowledge-base/why-is-cast-necessary-for-mev-commit-chain-interactions



## What is cast?

The cli tool `cast` is used in the mev-commit ecosystem, designed to simplify user interactions with the blockchain.
It serves various purposes, from executing transactions and querying data to deploying smart contracts, making blockchain interactions more accessible and user-friendly.

## EVM Compatibility

While `cast` is highlighted for its ease of use and efficiency, the mev-commit chain's compatibility with the
Ethereum Virtual Machine (EVM) broadens the scope for user interaction. This EVM compatibility means users are
not limited to `cast`; they can leverage any EVM-compatible tools for their blockchain activities.
To use these tools, it's essential to configure the RPC URL appropriately to ensure connectivity with the mev-commit chain.

This flexibility underscores the mev-commit chain's user-centric approach, allowing for a choice in interaction methods
to suit diverse user preferences and technical backgrounds. Whether through `cast` or other EVM-compatible tools, the key
is seamless and effective interaction with the mev-commit chain.


# Why Should Validators Opt In?
Source: https://docs.primev.xyz/v1.2.x/knowledge-base/why-should-validators-opt-in

Opt-in is coalition membership: one signal across many keys, policy work, and a later fee that funds Ethereum AI research.

Opt-in adds your L1 BLS keys to the **mev-commit validator coalition**. That is the reason to join. It is not extra block revenue from a live commitment market.

## What you join

The coalition is a validator union that is mev-forward and innovation-forward. Hub-true keys produce **one signal** for a large number of validators. That roster is what the coalition uses when it:

* Frames policy with the Ethereum Foundation and Ethereum working groups, aimed at validator interest and durable yield
* Reviews and greenlights innovation as the protocol evolves
* Speaks as a set of keys, not as one operator

Keep your existing mev-boost relay set. There is no sidecar and no relay configuration step.

## What you do not get today

You do not earn extra producer rewards from mev-commit bids today. Do not treat Hub-true as a claim on a running preconf network. The [RewardDistributor](/v1.2.x/get-started/validators/rewards) on Hoodi is test plumbing, not mainnet yield.

## Fees and AI research (not enabled)

**No fees are enabled at this stage.** There is no fee switch without your approval. Members must actively approve any coalition fee before it starts.

When a fee is approved and enabled, it funds **AI research** on Ethereum clients, validators, staking, and yield policy. That work can fund researchers directly, join funding rounds, and run R\&D in house. The intended path is a small share of Ethereum validator yield (about 1%).

The entity can be a **nonprofit**.

**Founding members** are granted tokens in proportion to their contributions, sized so token value matches or exceeds fees they contribute. The token is the right to **create proposals** for holders to accept. Token grants are not live.

## How to opt in

Use the [mev-commit-opt-in skill](/v1.2.x/get-started/validators/agentic-opt-in) from [primev.xyz/ai](https://primev.xyz/ai). See the [Validator Guide](/v1.2.x/get-started/validators/validator-guide) for requirements, or the [EigenLayer](/v1.2.x/get-started/validators/eigenlayer), [Symbiotic](/v1.2.x/get-started/validators/symbiotic), and [vanilla](/v1.2.x/get-started/validators/vanilla) pages for contract details. The old validator dashboard is deprecated.