Bidder Node Commands

Interacting with the Bidder Node

Ensure you have completed the Quickstart step in a separate terminal. This will set up your environment and place your key in the $HOME/.mev-commit directory, along with running the required bidder node.

Now that you’ve made sure we have a bidder node running, we can interact with it using the following commands:

❯_ terminal

cd $HOME/.mev-commit;
export KEY=$(cat key);
export ADDRESS=$(cast wallet address --private-key 0x$(cat key))

Getting Deposit

To get the currently deposited balance on-chain for a provider:

❯_ terminal

> curl -s "http://localhost:13523/v1/bidder/get_deposit?provider=0x3C44CdDdB6a900fa2b585dd299e03d12FA4293BC" | jq
{
"amount": "0",
"provider": "0x3C44CdDdB6a900fa2b585dd299e03d12FA4293BC"
}

Or to query all deposits and the bidder’s EOA balance:

❯_ terminal

> curl -s "http://localhost:13523/v1/bidder/get_all_deposits" | jq
{
"deposits": [
	{
	"provider": "0x3C44CdDdB6a900fa2b585dd299e03d12FA4293BC",
	"amount": "3000000000000000000"
	}
],
"bidderBalance": "9996999791340641239011"
}

Deposit represents the funds in the bidder’s account that can be used to submit bids on the mev-commit p2p-network and settled on-chain.

Deposit Manager

It’s recommended that bidders leverage the deposit manager to deposit, and automate ongoing re-deposits to specific providers. The deposit manager is an on-chain contract that a bidder account can enable by “setting their code” to the implementation using EIP-7702. After enabling the deposit manager, a bidder’s deposits are automatically replenished from the bidder’s EOA balance during the preconf settlement process, according to target deposit amounts configured by the bidder. A target deposit is the desired amount of funds that a bidder wants to be deposited for a specific provider. Bidders should set this to the maximum cumulative amount of ETH they would ever bid to a provider with respect to a single L1 block. There are two ways to enable this feature…

On node boot up (recommended)

The easiest way to enable the deposit manager is by setting two flags/environment variables upon starting your bidder node:

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

Through API

To enable the deposit manager through API, use the following command:

> curl -s -X POST http://localhost:13523/v1/bidder/enable_deposit_manager | jq
{
  "success": true
}

Then to set target deposits customized to each provider:

> 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"
  ]
}

Get Deposit Manager Status

❯_ terminal

curl -s http://localhost:13523/v1/bidder/deposit_manager_status | jq

{
  "enabled": true,
  "targetDeposits": [
    {
      "provider": "0x3C44CdDdB6a900fa2b585dd299e03d12FA4293BC",
      "targetDeposit": "3000000000000000000"
    },
    {
      "provider": "0x3C44CdDdB6a900fa2b585dd299e03d12FA4293BC",
      "targetDeposit": "3000000000000000000"
    }
  ]
}

Disable Deposit Manager

To disable the deposit manager call:

❯_ terminal

curl -X POST http://localhost:13523/v1/bidder/disable_deposit_manager

This will set the bidder EOA’s code to zero address, effectively disabling the previous EIP-7702 delegation for the EOA.

Withdraw Funds

To withdraw funds from your deposit to a specific provider, use the following command:

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

curl -s -X POST http://localhost:13523/v1/bidder/withdraw \
  -H 'Content-Type: application/json' \
  -d '{
    "providers": [
      "0x3C44CdDdB6a900fa2b585dd299e03d12FA4293BC"
    ]
  }' | jq
{
  "providers": [
    "3c44cdddb6a900fa2b585dd299e03d12fa4293bc"
  ],
  "amounts": [
    "3000000000000000000"
  ]
}

Checking the Balance of your Wallet

Mainnet

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

❯_ terminal

cast b $ADDRESS --rpc-url https://chainrpc.mev-commit.xyz

Testnet

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

❯_ terminal

cast b $ADDRESS --rpc-url https://chainrpc.testnet.mev-commit.xyz

Check Total Value Locked in Contracts

Mainnet

❯_ terminal

python3 -c "print($(cast b 0xb772Add4718E5BD6Fe57Fb486A6f7f008E52167E \
--rpc-url https://chainrpc.mev-commit.xyz) + $(cast b 0xC973D09e51A20C9Ab0214c439e4B34Dbac52AD67 \
--rpc-url https://chainrpc.mev-commit.xyz))"

Testnet

❯_ terminal

python3 -c "print($(cast b 0x401B3287364f95694c43ACA3252831cAc02e5C41 \
--rpc-url https://chainrpc.testnet.mev-commit.xyz) + $(cast b 0xf4F10e18244d836311508917A3B04694D88999Dd \
--rpc-url https://chainrpc.testnet.mev-commit.xyz))"

Health

The health endpoint checks whether the bidder node is receiving events from mev-commit chain. This command is useful to determine whether the bidder node has become out of sync.

❯_ terminal

curl http://localhost:13523/health

Topology

The topology endpoint can be used to check which provider nodes the bidder node is connected to.

❯_ terminal

curl http://localhost:13523/v1/debug/topology

Querying for Proposers API

This API is enabled by default, the following environment variables could be set when launching a mev-commit client:

MEV_COMMIT_VALIDATOR_ROUTER_ADDR
MEV_COMMIT_BEACON_API_URL
MEV_COMMIT_L1_RPC_URL

Current address for the ValidatorOptInRouter contract 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 and 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 and 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:

❯_ terminal

curl http://localhost:13523/v1/validator/get_validators?epoch=1

To get the information on whether validators for a latest epoch are opted in to mev-commit:

❯_ terminal

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:

❯_ terminal

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 and here.

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

❯_ terminal

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

❯_ terminal

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

Get Started

Concepts

Developers

Interacting with the Bidder Node

Getting Deposit

Deposit Manager

On node boot up (recommended)

Through API

Get Deposit Manager Status

Disable Deposit Manager

Withdraw Funds

Checking the Balance of your Wallet

Mainnet

Testnet

Check Total Value Locked in Contracts

Mainnet

Testnet

Health

Topology

Querying for Proposers API

Configuring custom provider sets

Mainnet

Testnet

Get Started

Concepts

Developers

​Interacting with the Bidder Node

​Getting Deposit

​Deposit Manager

​On node boot up (recommended)

​Through API

​Get Deposit Manager Status

​Disable Deposit Manager

​Withdraw Funds

​Checking the Balance of your Wallet

​Mainnet

​Testnet

​Check Total Value Locked in Contracts

​Mainnet

​Testnet

​Health

​Topology

​Querying for Proposers API

​Configuring custom provider sets

​Mainnet

​Testnet

Interacting with the Bidder Node

Getting Deposit

Deposit Manager

On node boot up (recommended)

Through API

Get Deposit Manager Status

Disable Deposit Manager

Withdraw Funds

Checking the Balance of your Wallet

Mainnet

Testnet

Check Total Value Locked in Contracts

Mainnet

Testnet

Health

Topology

Querying for Proposers API

Configuring custom provider sets

Mainnet

Testnet