Join mev-commit Testnet

Bidder Quickstart

This section is tailored for users who want to participate in the mev-commit network as bidders. Bidders are crucial participants who submit bids for transaction execution.

1-Minute Quickstart

This section provides a fast and straightforward method to start using mev-commit as a bidder. It's designed for users who prefer a quick setup without delving into the technical details. Follow these simple steps to get started:


  • Ensure you have curl installed on your system. curl is a command-line tool used to transfer data from or to a server.
  • A terminal to execute the command. This can be any command-line interface like Command Prompt on Windows, Terminal on macOS, or a Linux shell.

Simply run the following command in your terminal:

curl -o launchmevcommit https://raw.githubusercontent.com/primevprotocol/scripts/main/launchmevcommit && chmod +x launchmevcommit && ./launchmevcommit --rpc-url --node-type bidder

This command performs several actions automatically:

  • Downloads the mev-commit startup script using curl.
  • Makes the script executable with chmod.
  • Executes the script to set up mev-commit with the required configurations.

Once the command execution is complete, your mev-commit bidder node setup is done. You don't need to perform any additional manual setup steps.

If you want to perform a manual setup please skip to Bidder Manual Start (opens in a new tab) section.

Interacting with the Bidder Node

First, you can set the local environment variables to set your KEY and ADDRESS. Change directories to the one with your key (this should be the same folder as mev-commit). If you used the 1-minute quickstart command, your folder would be $HOME/.mev-commit

Setting these will make running the commands to interact with your account easier.

export KEY=$(cat key)
export ADDRESS=$(cast wallet address --private-key 0x$(cat key))

Sending Bids

Open a new terminal window. To send bids, we simply run the following command:

curl -X POST http://localhost:13523/v1/bidder/bid \
-d '{
  "txHash": "91a89B633194c0D86C539A1A5B14DCCacfD47094",
  "amount": <amount in wei>,
  "blockNumber": <blocknumber>

Getting Allowance

To get the current prepaid balance in the contract:

curl -s http://localhost:13523/v1/bidder/get_allowance

Withdraw Prepaid Funds

cast send 0x62197Abd7672925c7606Bdf9931e42baCa6619AD "withdrawPrepayedAmount(address)" $ADDRESS --rpc-url --private-key $KEY

Checking the Balance of your Wallet

This command will allow you to check your current wallet balance on mev-commit chain:

cast b $ADDRESS --rpc-url

Check Total Value Locked in Contracts

python3 -c "print($(cast b 0x62197Abd7672925c7606Bdf9931e42baCa6619AD --rpc-url + $(cast b 0xeA73E67c2E34C4E02A2f3c5D416F59B76e7617fC --rpc-url"


curl http://localhost:13523/topology

Provider Quickstart

This section is designed for users who wish to set up and run a mev-commit node as a provider. Providers play a crucial role in the network by handling bids and commitments.

1-Minute Quickstart

This quickstart method is ideal for users who prefer a straightforward and rapid setup process without delving into detailed configurations. If you want to perform a manual setup please skip to Provider Manual Start (opens in a new tab) section.


  • curl: A command-line tool used for downloading files from the internet. Ensure you have it installed on your system.
  • terminal: Your command-line interface where you will execute the setup commands.

Steps to Become a Provider:

  • Setting Up the Provider Node: The provider node is essential for participating in the network as a provider. It handles bid reception and processing.
  • Provider Emulator or gRPC-Enabled Service: You also need to run a provider emulator or set up your own gRPC-enabled service. This is necessary for interacting with the provider node and managing bids effectively. To start your Provider node, execute the following command in your terminal:
curl -o launchmevcommit https://raw.githubusercontent.com/primevprotocol/scripts/main/launchmevcommit && chmod +x launchmevcommit && ./launchmevcommit --rpc-url --node-type provider

gRPC Node Connection

Once a provider node is up and running, you can use the ReceiveBids stream to receive bids into offline infrastructure and send decisions based on those bids via the SendProcessedBids stream.

  • Config file with ProviderAPIEnabled set to true

    **expose_provider_api: true**
    priv_key_file: /path/to/key
    peer_type: provider
    p2p_port: 13522
    http_port: 13523
    rpc_port: 13524
    secret: hello
    log_fmt: text
    log_level: debug
    bidder_registry_contract: 0x62197Abd7672925c7606Bdf9931e42baCa6619AD
    provider_registry_contract: 0xeA73E67c2E34C4E02A2f3c5D416F59B76e7617fC
    preconf_contract: 0xBB632720f817792578060F176694D8f7230229d9
      - /ip4/
  • gRPC API Specification

    // 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) {}

The following file (opens in a new tab) shows an implementation of a wrapped client that interfaces with the GRPC API client that was autogenerated here (opens in a new tab).

Getting Started with the CLI

mev-commit software operates as a command-line interface (CLI) tool, designed for users to run in their own environments. The CLI mainly includes two commands. To view available commands, use the -h or --help option with the main command.


❯ mev-commit -h
   mev-commit - Start mev-commit node
   mev-commit [global options] command [command options]
   help, h  Shows a list of commands or help for one command
   --config value                           path to config file [$MEV_COMMIT_CONFIG]
   --peer-type value                        peer type to use, options are 'bidder', 'provider' or 'bootnode' (default: "bidder") [$MEV_COMMIT_PEER_TYPE]
   --priv-key-file value                    path to private key file (default: "~/.mev-commit/key") [$MEV_COMMIT_PRIVKEY_FILE]
   --p2p-port value                         port to listen for p2p connections (default: 13522) [$MEV_COMMIT_P2P_PORT]
   --p2p-addr value                         address to bind for p2p connections (default: "") [$MEV_COMMIT_P2P_ADDR]
   --http-port value                        port to listen for http connections (default: 13523) [$MEV_COMMIT_HTTP_PORT]
   --http-addr value                        address to bind for http connections [$MEV_COMMIT_HTTP_ADDR]
   --rpc-port value                         port to listen for rpc connections (default: 13524) [$MEV_COMMIT_RPC_PORT]
   --rpc-addr value                         address to bind for RPC connections [$MEV_COMMIT_RPC_ADDR]
   --bootnodes value [ --bootnodes value ]  list of bootnodes to connect to [$MEV_COMMIT_BOOTNODES]
   --secret value                           secret to use for signing (default: "secret") [$MEV_COMMIT_SECRET]
   --log-fmt value                          log format to use, options are 'text' or 'json' (default: "text") [$MEV_COMMIT_LOG_FMT]
   --log-level value                        log level to use, options are 'debug', 'info', 'warn', 'error' (default: "info") [$MEV_COMMIT_LOG_LEVEL]
   --bidder-registry-contract value         address of the bidder registry contract (default: "0x5340b92E261141D6B4D0DC6F847667E5e4A63544") [$MEV_COMMIT_BIDDER_REGISTRY_ADDR]
   --provider-registry-contract value       address of the provider registry contract (default: "0xeA73E67c2E34C4E02A2f3c5D416F59B76e7617fC") [$MEV_COMMIT_PROVIDER_REGISTRY_ADDR]
   --preconf-contract value                 address of the preconfirmation commitment store contract (default: "0x451656c1E7eDf82397EBE04f38819c9970AA3658") [$MEV_COMMIT_PRECONF_ADDR]
   --settlement-rpc-endpoint value          rpc endpoint of the settlement layer (default: "http://localhost:8545") [$MEV_COMMIT_SETTLEMENT_RPC_ENDPOINT]
   --nat-addr value                         external address of the node [$MEV_COMMIT_NAT_ADDR]
   --nat-port value                         externally mapped port for the node (default: 13522) [$MEV_COMMIT_NAT_PORT]
   --help, -h                               show help
   --version, -v                            print the version

If you're not using Docker:

  1. Run Make in the root directory
  2. This will compile the mev-commit binary under the bin folder
mev-commit % tree -L 2
├── Dockerfile
├── bin
   ├── config.yaml
   ├── key
**│   └── mev-commit**
  1. Run the mev-commit directly:
RPC_URL="";bin/mev-commit --peer-type <peerType> --bootnodes <bootnode> --settlement-rpc-endpoint $RPC_URL

If you're using Docker:

  1. Build Docker Image:
    • Open your terminal and navigate to where your Dockerfile is located.

    • Run:

      sqlCopy code
      docker build -t mev-commit:latest .

© 2023 Open Source