1

Create an account (optional)

First you’ll need to obtain or create a standard Ethereum account (secp256k1 keypair). We highly recommend storing your account in a password protected keystore file, rather than storing the private key unencrypted. If you plan to fund this account with a non-trivial amount of ETH, please independently verify any tools and/or procedures you adopt.If you already have a keystore generated, or want to use an existing L1 account’s keystore, you’re good to move on from this step.Otherwise the quickest way to generate a new keystore is to install geth and create the file in a single command:
brew install geth && geth account new --keystore $HOME/keystore
❯_
brew install geth && geth account import --keystore "$HOME/keystore" private_key_file.txt
Import geth as a dependency in your golang project and programmatically create a new keystore file. Read more here.
package main

import (
    "fmt"
    "log"
    "os"
    "path/filepath"

    "github.com/ethereum/go-ethereum/accounts/keystore"
)

func main() {
    home, err := os.UserHomeDir()
    if err != nil {
        log.Fatal(err)
    }
    keystoreDir := filepath.Join(home, "keystore")
    ks := keystore.NewKeyStore(keystoreDir, keystore.StandardScryptN, keystore.StandardScryptP)
    password := os.Getenv("PASSWORD")
    if password == "" {
        log.Fatal("PASSWORD environment variable not set")
    }
    account, err := ks.NewAccount(password)
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println("New account address:", account.Address.Hex())
    fmt.Println("Keystore file saved in:", keystoreDir)
}
2

Bridge to the mev-commit chain

In order to fund your account on the mev-commit chain, you’ll need to bridge ETH from an L1 account. We suggest using our web interface:
  1. Visit mev-commit.xyz/bridge for mainnet. Testnet bridge frontend is coming soon.
  2. Connect your wallet (MetaMask or WalletConnect supported)
  3. Select Ethereum as the source chain and mev-commit as the destination
  4. Enter the amount of ETH you want to transfer
  5. Click “Bridge” and approve the transaction
Wait for the bridge transaction to complete. You can see detailed instructions in our Bridge UI guide.
Testnet currently requires using the bridge CLI.
For automated or programmatic bridging, you can use our CLI tool by first confirming your operating system and architecture by running uname -sm, then downloading the appropriate bridge user CLI binary from the releases page.Or use the following command which automatically downloads and extracts the latest bridge user CLI binary for your system into your $HOME directory:
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.The CLI application provides two sub-commands to bridge to and from the settlement chain. For more details go the the bridge CLI documentation.
When using the bridge CLI, make sure to specify the newly generated account address from the previous step as the destination address for the bridge command.
❯_ example
./user-cli bridge-to-settlement --account-key <PRIVATE KEY of source account for funds> --dest-addr <Address to fund on mev-commit chain> --amount 1000000000000000000
3

Run a mev-commit node

Navigate to the mev-commit releases page and download the appropriate binary for your system. Since you’re reading the v1.2.x version of the docs, choose a release starting with v1.2.You can use the following command which automatically downloads and extracts the latest mev-commit binary for your system into your $HOME directory:
curl -Ls $(curl -s https://api.github.com/repos/primev/mev-commit/releases/latest \
  | grep browser_download_url \
  | grep "mev-commit_[0-9].*$(uname -s)_$(uname -m).*\.tar\.gz" \
  | cut -d '"' -f 4 \
  | head -n1) | tar -xz -C ~
Run cd $HOME if you used the command above.Now execute the node binary, selecting either a bidder or provider configuration based on your role in the network. Bidders must set a target-deposit-amount which will be deposited for each valid provider, in order to send bids.

Mainnet

./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-ws-rpc-endpoint wss://chainrpc-wss.mev-commit.xyz

Testnet

./mev-commit \
    --keystore-path $HOME/keystore \
    --keystore-password <PASSWORD> \
    --enable-deposit-manager=true \
    --target-deposit-amount <WEI_AMOUNT> \
    --bootnodes /dnsaddr/bootnode.testnet.mev-commit.xyz \
    --settlement-ws-rpc-endpoint wss://chainrpc-wss.testnet.mev-commit.xyz
❗ The keystore-path flag expects the directory path for your keystore, not the file path itself. Example: if your keystore file is at /Users/bob/keystore/30d2db95-keystore.json you would use --keystore-path /Users/bob/keystore.❗ If you get an could not decrypt key with given password error, make sure there’s no other keystore files in the relevant directory.❗ If you really don’t want to use a keystore, priv-key-file can replace the keystore-path and keystore-password flags.❗ The --peer-type flag can be used to run a provider or bidder node.❗ In order to run a provider node, the machine needs to be publicly accessible. Also, the mev-commit node will have to be configured with the public IP of the node using the nat-addr parameter.See the CLI reference by running ./mev-commit --help.
4

If bidder, send a bid

If you’ve started a bidder node, open a new terminal window to send a bid and receive commitments from providers. Run the following command:
❯_ example
curl -X POST http://localhost:13523/v1/bidder/bid \
-d '{
    "rawTransactions": ["0x02f8db82426882010c8410433624841043362f8303425094ea593b730d745fb5fe01b6d20e6603915252c6bf87016e03ce313800b864ce0b63ce0000000000000000000000000e94804eaa3c4c5355992086647f683f6f41ef1f000000000000000000000000000000000000000000000000000150e0786cc000000000000000000000000000000000000000000000000000000000000004e378c001a0ece6d13b20247abdc07d669c9186ee5a1ac9601db8c98a3323024ab299cb6662a01c20680efe4e0bb48a3a936b5ab27c741819f0ac567b12b34b230004b20b78a0"],
    "amount": "<amount in wei>",
    "blockNumber": <integer l1blocknumber>,
    "decayStartTimestamp": <timestamp milliseconds>,
    "decayEndTimestamp": <timestamp milliseconds>,
    "revertingTxHashes": []
}'
KeyDescription
txHashesArray of transaction hashes as strings
amountBid amount in wei
blockNumberL1 block number targeted for bid inclusion
decayStartTimestampStart timestamp for bid decay (in Unix milliseconds)
decayEndTimestampEnd timestamp for bid decay (in Unix milliseconds)
revertingTxHashesArray of transaction hashes as strings that can revert
rawTransactionsArray of hexadecimal encoded raw signed transaction payloads
slashAmountAmount to be slashed from provider stake in case of a failed bid
You can change the values in the fields amount, blockNumber, decayStartTimestamp, decayEndTimestamp and revertingTxHashes as desired. The rawTransactions field contains hexadecimal string of the RLP encoded raw transaction payloads, include raw transaction payloads in your bid in the atomic sequence in which they need to be placed in the block. Only one out of txHashes or rawTransactions need to be sent in a bid.Make sure your bid amount is sufficiently high for the commitment you’re requesting, and your target L1 block number is accurate. It’s up to the providers to commit to your bid, so try to ensure a commitment is feasible to your bid by its construction. Selecting a target block of n+1 where n is the current block number generally makes it easy to receive a commitment for standard bid amounts.
Congrats, you just sent your first L1 preconfirmation bid! You should be receiving commitments nearly instantly.
Alternatively you can send a bid using the txHashes field instead of rawTransactions to refer to a transaction a provider has in their own environment using its hash. This method also allows you to bid on others’ behalf using their transaction hashes.
❯_ example
curl -X POST http://localhost:13523/v1/bidder/bid \
-d '{
    "txHashes": ["0549fc7c57fffbdbfb2cf9d5e0de165fc68dadb5c27c42fdad0bdf506f4eacae"],
    "amount": "<amount in wei>",
    "blockNumber": <integer l1blocknumber>,
    "decayStartTimestamp": <timestamp milliseconds>,
    "decayEndTimestamp": <timestamp milliseconds>,
    "revertingTxHashes": []
}'
Make sure to check System Requirements to better understand what is needed to run mev-commit without any interruptions.

Bidder CLI application

In order to make it simpler for users to interact with the bidder node, the team has also created a CLI application which aims to provider a simpler UX to send transactions or bids to the mev-commit network. You can check the bidder CLI docs for more details.

Docker Compose setup

An example docker compose setup for a bidder driver process along with mev-commit bidder node can be found here.