> ## Documentation Index
> Fetch the complete documentation index at: https://docs.primev.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Bidder Node Commands

> This guide covers how to interact with your bidder node.

export const ValidatorOptInRouterProxyAddress = "0x821798d7b9d57dF7Ed7616ef9111A616aB19ed64";

export const HoodiValidatorOptInRouterAddress = "0xa380ba6d6083a4Cb2a3B62b0a81Ea8727861c13e";

<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 {HoodiValidatorOptInRouterAddress} and on Mainnet is {ValidatorOptInRouterProxyAddress}.

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