Skip to content

docs: improve readability and structure of bidder best practices #290

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
andesign31 wants to merge 9 commits into
base: main
Choose a base branch
from
Open

docs: improve readability and structure of bidder best practices #290

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
b2d4909
1st change
andesign31 Dec 19, 2025
3926aab
2nd
andesign31 Dec 19, 2025
2c0c2a1
3rd
andesign31 Dec 19, 2025
ab2bbb0
4th
andesign31 Dec 19, 2025
3ba7f0e
5th
andesign31 Dec 19, 2025
42f4e07
Last version
andesign31 Dec 20, 2025
8a78be3
1st
andesign31 Dec 21, 2025
b8756b6
docs: add structured guide for bidder cli with callouts
andesign31 Dec 21, 2025
492e303
docs: improve readability and structure of bidder best practices
andesign31 Dec 21, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
124 changes: 61 additions & 63 deletions v1.2.x/get-started/bidders/best-practices.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,94 +3,92 @@ title: "Bidder Best Practices"
sidebarTitle: "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.
# Bidder Best Practices

**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.
This guide outlines the best practices for bidders to optimize their interactions with the mev-commit network and maximize their utility.

**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/relays#how-to-query-the-provider-registry).
## Understanding Commitments

## 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.
In the mev-commit network, commitments are essential to the bidding process. You receive two types of commitments: **Credible** and **General**.

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](https://docs.primev.xyz/v1.2.x/concepts/bids/bid-structure).
### Credible Commitments
* **Definition:** Guarantees made by network participants who have direct control over fulfilling your bid.
* **Assurance:** These offer the highest level of assurance because the proposer has opted in to mev-commit.
* **Automation:** [Querying for Proposers](/v1.2.x/get-started/providers/querying-for-proposers) is available by default and will notify you when commitments become credible.

### Transaction Payload
Include the raw transaction payloads in your bid in the atomic sequence in which they need to be placed in the block.
### General Commitments
* **Definition:** Promises made by network participants with a lower level of assurance compared to credible commitments.
* **Reliability:** These can approach the reliability of credible commitments when aggregated across multiple providers (e.g., all block builders for a mev-boost-enabled validator).
* **Mechanism:** The proposer hasn't opted in yet, but a committing block builder may still win the auction and deliver the commitment.
* **Resources:** You can obtain the list of all registered providers as described [here](/v1.2.x/get-started/providers/registering-as-a-provider).

```shell ❯_ example
---

## Submitting Bundles

To include transaction bundles, submit them in the exact atomic sequence they appear. You can submit bundles using two methods:

1. **Transaction Payloads (Recommended):** More efficient as it eliminates payload lookups, allowing providers to return commitments faster.
2. **Transaction Hashes:** Useful if providers already have the transactions via RPC or mempool. *Note: Not all providers support this.*

Learn more about the detailed **[bid structure here](/v1.2.x/concepts/bids)**.

### Option 1: Transaction Payload
Include the raw payloads in the atomic sequence required for the block.

```bash
curl -X POST http://localhost:13523/v1/bidder/bid \
-d '{
"rawTransactions": ["0x02f8db82426882010c8410433624841043362f8303425094ea593b730d745fb5fe01b6d20e6603915252c6bf87016e03ce313800b864ce0b63ce0000000000000000000000000e94804eaa3c4c5355992086647f683f6f41ef1f000000000000000000000000000000000000000000000000000150e0786cc000000000000000000000000000000000000000000000000000000000000004e378c001a0ece6d13b20247abdc07d669c9186ee5a1ac9601db8c98a3323024ab299cb6662a01c20680efe4e0bb48a3a936b5ab27c741819f0ac567b12b34b230004b20b78a0", "0x02f8748242682c841043362684104336318252089412b141665da4a5f617c759ad996ef91ad806a9c0880de0b6b3a764000080c001a0806552ed846808580eb896994825f07e73de2f42e2d3554f228284ecfaa89d9ca046d58b62ba565982fb07a64b436dd7a6c210b2f59c4fb2aee2cdd150ccf8bfaa"],
"rawTransactions": ["0x02f8..."],
"amount": "<amount in wei>",
"blockNumber": <integer l1blocknumber>,
"decayStartTimestamp": <timestamp milliseconds>,
"decayEndTimestamp": <timestamp milliseconds>,
"revertingTxHashes": ["7ca16add2aa1b1ef718006b791cb48a6ad729d22f5d2a0b294705320e4825abb"]
"blockNumber": <integer>,
"decayStartTimestamp": <timestamp>,
"decayEndTimestamp": <timestamp>,
"revertingTxHashes": ["7ca1..."]
}'
```
### 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
curl -X POST http://localhost:13523/v1/bidder/bid \
### Option 2: Transaction Hash ##
Use this for transactions already available in the public mempool or provider RPCs.
```curl -X POST http://localhost:13523/v1/bidder/bid \
-d '{
"txHashes": ["0549fc7c57fffbdbfb2cf9d5e0de165fc68dadb5c27c42fdad0bdf506f4eacae", "22145ba31366d29a893ae3ffbc95c36c06e8819a289ac588594c9512d0a99810", "7e1506f266bc86c81ae46018053a274a3bd96a9eff17392930707bf8fa5ff6be"],
"txHashes": ["0549..."],
"amount": "<amount in wei>",
"blockNumber": <integer l1blocknumber>,
"decayStartTimestamp": <timestamp milliseconds>,
"decayEndTimestamp": <timestamp milliseconds>,
"revertingTxHashes": ["22145ba31366d29a893ae3ffbc95c36c06e8819a289ac588594c9512d0a99810"]
"blockNumber": <integer>,
"decayStartTimestamp": <timestamp>,
"decayEndTimestamp": <timestamp>,
"revertingTxHashes": ["2214..."]
}'
```
You can change the values in the fields `txHashes`, `amount`, `blockNumber`, `decayStartTimestamp`, `decayEndTimestamp` and `revertingTxHashes` as desired.
```

### Bid amount
## Bid Parameters

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 Amount**: Set this to the **total amount** the bidder is willing to pay for the bundle.
Gas used by transactions does **not** affect the final amount paid.

### Bid Decay
The `decayStartTimestamp` and `decayEndTimestamp` are important components for how sensitive the [price of a preconfirmation](https://docs.primev.xyz/v1.2.x/knowledge-base/how-to-price-a-bid) will be. More details can be found about it [here](https://docs.primev.xyz/v1.2.x/concepts/bids/bid-structure#details-on-decay-parameters).
**Bid Decay**: Use `decayStartTimestamp` and `decayEndTimestamp` to control price sensitivity. More details can be found [here](https://docs.primev.xyz/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).
**Bid Options**: Used to set positional constraints on transactions. Learn more about the [options here](https://github.com/primev/mev-commit-docs/blob/main/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](https://docs.primev.xyz/v1.2.x/get-started/bidders/bidder-node-commands#topology)) and that you are receiving mev-commit events (via the [health endpoint](https://docs.primev.xyz/v1.2.x/get-started/bidders/bidder-node-commands#health)).
----

## Bidder Depositing
## Troubleshooting
If you are not receiving commitments instantly:

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.
1. **Check Parameters**: Ensure your bid is high enough for the requested commitment.

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.
2. **Connectivity**: Check that you are connected to providers via the [topology endpoint](https://docs.primev.xyz/v1.2.x/get-started/bidders/bidder-node-commands#health).

Read more about the deposit manager [here](https://docs.primev.xyz/v1.2.x/get-started/bidders/bidder-node-commands#deposit-manager).
3. **Health Check**: Ensure you are receiving events via the [health endpoint](https://docs.primev.xyz/v1.2.x/get-started/bidders/bidder-node-commands#health)/.
----

{/* ## (Optional) Provider RPCs
## Bidder Depositing & Automation
Bidders must bridge ETH to the mev-commit chain and deposit it toward providers. As bids are settled, you must "top up" your deposits.

If you don't send transaction payloads in your bid, you can send your transactions directly to block builders. Below is a table of Provider RPCs to send your transactions to on testnet. You may already be sending transactions to these providers if you have existing transaction operations.
### Deposit Manager
To automate this, enable the **Deposit Manager**:

<table>
<thead>
<tr>
<th width="350">Provider</th>
<th width="350">RPC Endpoint Mainnet</th>
<th width="350">RPC Endpoint Testnet</th>
</tr>
</thead>
<tbody>
<tr>
<td>Preconf Builder</td>
<td>tbd</td>
<td>[http://52.11.201.67/execution/rpc](http://52.11.201.67/execution/rpc)</td>
</tr>
<tr>
<td>Titan</td>
<td>[rpc.titanbuilder.xyz](https://rpc.titanbuilder.xyz/)</td>
</tr>
</tbody>
</table> */}
* **Target Deposit**: Set the maximum cumulative amount of ETH you would bid to a provider for a single L1 block.

* **Auto Top-up**: The relevant deposit will be automatically restored to the target value during settlement.

Read more about the [deposit manager here](https://docs.primev.xyz/v1.2.x/get-started/bidders/bidder-node-commands#deposit-manager).
127 changes: 55 additions & 72 deletions v1.2.x/get-started/bidders/bidder-cli.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,96 +3,79 @@ title: "Bidder CLI application"
sidebarTitle: "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.
# Bidder CLI

```
NAME:
bidder-cli - A CLI tool for interacting with a gRPC bidder server
The `bidder-cli` is a tool designed to provide a better User Experience (UX) for users sending raw transactions or bids on existing transactions to the mev-commit network.

USAGE:
bidder-cli [global options] command [command options]
<Note>
You can download the latest version of the tool from the [official releases page](https://github.com/primev/mev-commit/releases/latest).</Note>

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

GLOBAL OPTIONS:
--help, -h show help
--version, -v print the version
```
The basic structure for interacting with the gRPC bidder server is:

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.
```bash
bidder-cli [global options] command [command options]
```
## Commands
* `send-tx`: Send a transaction to the gRPC bidder server.

```
NAME:
bidder-cli send-tx - Send a transaction to the gRPC bidder server
* `send-tx-hash`: Send a bid to the gRPC bidder server for existing transactions.

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
```
* `help`: Shows the full list of commands and options.
---
## Sending Transactions (`send-tx`)
This command allows you to create a simple transfer transaction on the L1 chain and submit it directly to mev-commit.

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`.
<Warning>**Security**: You must provide the private key of the account to sign the transaction. Never share this key or include it in public enviroments.</Warning>

If `block-number` is not specified, the next block number is used for the bid.
**Example Usage**
````
./bidder-cli send-tx \
--from <PRIVATE_KEY> \
--to <DESTINATION_ADDRESS> \
--value <AMOUNT_IN_WEI> \
--bid-amount <BID_IN_WEI> \
--rpc-url localhost:13524
````
**Key Options**

Similarly, the default `decay-duration` is 10 minutes. Which means the bid amount will decay starting from current time to 10 minutes from now.
* `--rpc-url`: The URL for the gRPC server (default is `localhost:13524`).

`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.
* `--block-number`: Target block for the bid. If omitted, the next block is used.

<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>
* `--decay-duration`: The time window for the bid amount to decay (default: 10m).
* `--l1-rpc-url`: Used to fetch the account nonce. Default: `https://ethereum-hoodi-rpc.publicnode.com`.
---
## Bidding by Transaction Hash (`send-tx-hash`)
Use this command to bid on transactions that are already in the public mempool or block-builder mempools.

```shell ❯_ example
./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> \
**Example Usage**
````
./bidder-cli send-tx-hash \
--tx-hashes <HASH_1> \
--tx-hashes <HASH_2> \
--bid-amount <AMOUNT> \
--rpc-url localhost:13524
```
````
<Tip>Users can provide multiple --`tx-hashes` flags to bid on several transactions simultaneously.</Tip>

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.
Important Considerations

```
NAME:
bidder-cli send-tx-hash - Send a bid to the gRPC bidder server
* **Gossip Latency**: There is a possibility that a transaction is not gossiped to the provider's infrastructure in time.
For better results, consider using the [Provider's RPC](/v1.2.x/get-started/bidders/best-practices#option-1-transaction-payload) for submitting transactions.

USAGE:
bidder-cli send-tx-hash [command options]
* **Reverting Hashes**: You can specify transactions that should be considered "reverting" using the `--reverting-tx-hashes` flag.

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

```shell ❯_ example
./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
```
If you're having trouble receiving commitments:

1. **Check Connectivity**: Ensure you are connected to providers via the topology endpoint.

2. **Port Configuration**: By default, the gRPC server runs on port `13524`.

3. **Verbose Logging**: Use the `--verbose` flag to enable detailed logging for debugging.