From b2d4909dc7f256660fe938aa39257acf3ee06e2d Mon Sep 17 00:00:00 2001 From: andesign31 Date: Thu, 18 Dec 2025 22:23:41 -0300 Subject: [PATCH 1/9] 1st change --- v1.2.x/get-started/bidders/best-practices.mdx | 125 +++++++++--------- 1 file changed, 61 insertions(+), 64 deletions(-) diff --git a/v1.2.x/get-started/bidders/best-practices.mdx b/v1.2.x/get-started/bidders/best-practices.mdx index 537e29f8..f8f0c2b9 100644 --- a/v1.2.x/get-started/bidders/best-practices.mdx +++ b/v1.2.x/get-started/bidders/best-practices.mdx @@ -1,96 +1,93 @@ ---- 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 + +This guide outlines the best practices for bidders to optimize their interactions with the mev-commit network and maximize their utility. + +## Understanding Commitments + +In the mev-commit network, commitments are essential to the bidding process. You receive two types of commitments: **Credible** and **General**. + +### 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* is available by default and will notify you when commitments become credible. + +### General Commitments +* **Definition:** Promises made by network participants with a lower level of assurance. +* **Reliability:** These can approach the reliability of credible commitments when aggregated across multiple providers (e.g., 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:** View the [list of all registered providers](https://link-para-provedores). -**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. +--- -**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). +## Submitting Bundles -## 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. +To include transaction bundles, submit them in the exact atomic sequence they appear. You can submit bundles using two methods: -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). +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.* -### Transaction Payload -Include the raw transaction payloads in your bid in the atomic sequence in which they need to be placed in the block. +### Option 1: Transaction Payload +Include the raw payloads in the atomic sequence required for the block. -```shell ❯_ example +```bash curl -X POST http://localhost:13523/v1/bidder/bid \ -d '{ - "rawTransactions": ["0x02f8db82426882010c8410433624841043362f8303425094ea593b730d745fb5fe01b6d20e6603915252c6bf87016e03ce313800b864ce0b63ce0000000000000000000000000e94804eaa3c4c5355992086647f683f6f41ef1f000000000000000000000000000000000000000000000000000150e0786cc000000000000000000000000000000000000000000000000000000000000004e378c001a0ece6d13b20247abdc07d669c9186ee5a1ac9601db8c98a3323024ab299cb6662a01c20680efe4e0bb48a3a936b5ab27c741819f0ac567b12b34b230004b20b78a0", "0x02f8748242682c841043362684104336318252089412b141665da4a5f617c759ad996ef91ad806a9c0880de0b6b3a764000080c001a0806552ed846808580eb896994825f07e73de2f42e2d3554f228284ecfaa89d9ca046d58b62ba565982fb07a64b436dd7a6c210b2f59c4fb2aee2cdd150ccf8bfaa"], + "rawTransactions": ["0x02f8..."], "amount": "", - "blockNumber": , - "decayStartTimestamp": , - "decayEndTimestamp": , - "revertingTxHashes": ["7ca16add2aa1b1ef718006b791cb48a6ad729d22f5d2a0b294705320e4825abb"] + "blockNumber": , + "decayStartTimestamp": , + "decayEndTimestamp": , + "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. +```bashcurl -X POST http://localhost:13523/v1/bidder/bid \ -d '{ - "txHashes": ["0549fc7c57fffbdbfb2cf9d5e0de165fc68dadb5c27c42fdad0bdf506f4eacae", "22145ba31366d29a893ae3ffbc95c36c06e8819a289ac588594c9512d0a99810", "7e1506f266bc86c81ae46018053a274a3bd96a9eff17392930707bf8fa5ff6be"], + "txHashes": ["0549..."], "amount": "", - "blockNumber": , - "decayStartTimestamp": , - "decayEndTimestamp": , - "revertingTxHashes": ["22145ba31366d29a893ae3ffbc95c36c06e8819a289ac588594c9512d0a99810"] + "blockNumber": , + "decayStartTimestamp": , + "decayEndTimestamp": , + "revertingTxHashes": ["2214..."] }' -``` -You can change the values in the fields `txHashes`, `amount`, `blockNumber`, `decayStartTimestamp`, `decayEndTimestamp` and `revertingTxHashes` as desired. +``` +## Bid Parameters ## +**Bid Amount**: Set this to the total amount you are willing to pay for the bundle. +The gas used does not affect the final amount paid. -### Bid amount +**Bid Decay**: Use `decayStartTimestamp` and `decayEndTimestamp` to control +the price sensitivity of the preconfirmation. [Learn more here](https://docs.primev.xyz/v1.2.x/concepts/bids/bid-structure#details-on-decay-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 Options**: Set positional constraints on transactions within the block. [View options here](https://github.com/andesign31/mev-commit-docs/blob/main/v1.2.x/concepts/bids/bid-structure#details-on-bidOptions). +---- -### 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). +## Bidder Depositing & Automation ## +Bidders must bridge ETH to the mev-commit chain and deposit it toward providers. -### 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). +**Deposit Manager** -## 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)). +To avoid manual "top-ups", enable the **Deposit Manager**: -## Bidder Depositing +Target Deposit: Set a desired amount for a specific provider. -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. +**Auto Top-up**: The system automatically restores the target value during settlement. -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. +**Strategy**: Set target deposits to the maximum cumulative ETH you intend to bid for a single L1 block. -Read more about the deposit manager [here](https://docs.primev.xyz/v1.2.x/get-started/bidders/bidder-node-commands#deposit-manager). +[Read more about the Deposit Manager](https://www.google.com/search?q=https://link-manager). -{/* ## (Optional) Provider RPCs +---- -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. +## Troubleshooting +If you are not receiving commitments: - - - - - - - - - - - - - - - - - - - -
ProviderRPC Endpoint MainnetRPC Endpoint Testnet
Preconf Buildertbd[http://52.11.201.67/execution/rpc](http://52.11.201.67/execution/rpc)
Titan[rpc.titanbuilder.xyz](https://rpc.titanbuilder.xyz/)
*/} +**Check Parameters**: Ensure your bid amount is competitive for the requested commitment. +**Verify Topology**: Use the `/topology` endpoint to check provider connections. +**Health Check**: Use the `/health` endpoint to ensure you are receiving mev-commit events. \ No newline at end of file From 3926aabd04dc882a72733f0719705bfee58a1403 Mon Sep 17 00:00:00 2001 From: andesign31 Date: Thu, 18 Dec 2025 22:26:03 -0300 Subject: [PATCH 2/9] 2nd --- v1.2.x/get-started/bidders/best-practices.mdx | 4 ---- 1 file changed, 4 deletions(-) diff --git a/v1.2.x/get-started/bidders/best-practices.mdx b/v1.2.x/get-started/bidders/best-practices.mdx index f8f0c2b9..f0b029e1 100644 --- a/v1.2.x/get-started/bidders/best-practices.mdx +++ b/v1.2.x/get-started/bidders/best-practices.mdx @@ -1,7 +1,3 @@ -title: "Bidder Best Practices" -sidebarTitle: "Best Practices" ---- - # Bidder Best Practices This guide outlines the best practices for bidders to optimize their interactions with the mev-commit network and maximize their utility. From 2c0c2a1abf526a2af7e49136782ab1def5855c6f Mon Sep 17 00:00:00 2001 From: andesign31 Date: Thu, 18 Dec 2025 22:27:27 -0300 Subject: [PATCH 3/9] 3rd --- v1.2.x/get-started/bidders/best-practices.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/v1.2.x/get-started/bidders/best-practices.mdx b/v1.2.x/get-started/bidders/best-practices.mdx index f0b029e1..272ca779 100644 --- a/v1.2.x/get-started/bidders/best-practices.mdx +++ b/v1.2.x/get-started/bidders/best-practices.mdx @@ -9,7 +9,7 @@ In the mev-commit network, commitments are essential to the bidding process. You ### 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* is available by default and will notify you when commitments become credible. +* **Automation:** Querying for Proposers is available by default and will notify you when commitments become credible. ### General Commitments * **Definition:** Promises made by network participants with a lower level of assurance. From ab2bbb025f5c57b774dd9cbb409417c2f13f3fa1 Mon Sep 17 00:00:00 2001 From: andesign31 Date: Thu, 18 Dec 2025 22:29:05 -0300 Subject: [PATCH 4/9] 4th --- v1.2.x/get-started/bidders/best-practices.mdx | 1 + 1 file changed, 1 insertion(+) diff --git a/v1.2.x/get-started/bidders/best-practices.mdx b/v1.2.x/get-started/bidders/best-practices.mdx index 272ca779..0296e170 100644 --- a/v1.2.x/get-started/bidders/best-practices.mdx +++ b/v1.2.x/get-started/bidders/best-practices.mdx @@ -60,6 +60,7 @@ The gas used does not affect the final amount paid. the price sensitivity of the preconfirmation. [Learn more here](https://docs.primev.xyz/v1.2.x/concepts/bids/bid-structure#details-on-decay-parameters). **Bid Options**: Set positional constraints on transactions within the block. [View options here](https://github.com/andesign31/mev-commit-docs/blob/main/v1.2.x/concepts/bids/bid-structure#details-on-bidOptions). + ---- ## Bidder Depositing & Automation ## From 3ba7f0ebb3c68f619b29320fdd55531036f17a77 Mon Sep 17 00:00:00 2001 From: andesign31 Date: Fri, 19 Dec 2025 08:00:17 -0300 Subject: [PATCH 5/9] 5th --- v1.2.x/get-started/bidders/best-practices.mdx | 26 ++++++++----------- 1 file changed, 11 insertions(+), 15 deletions(-) diff --git a/v1.2.x/get-started/bidders/best-practices.mdx b/v1.2.x/get-started/bidders/best-practices.mdx index 0296e170..ae62d2b3 100644 --- a/v1.2.x/get-started/bidders/best-practices.mdx +++ b/v1.2.x/get-started/bidders/best-practices.mdx @@ -4,24 +4,20 @@ This guide outlines the best practices for bidders to optimize their interaction ## Understanding Commitments -In the mev-commit network, commitments are essential to the bidding process. You receive two types of commitments: **Credible** and **General**. +In the mev-commit network, you receive two types of commitments during the bidding process: **Credible** and **General**. -### 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 is available by default and will notify you when commitments become credible. +* **Credible**: Guarantees with direct proposer opt-in. -### General Commitments -* **Definition:** Promises made by network participants with a lower level of assurance. -* **Reliability:** These can approach the reliability of credible commitments when aggregated across multiple providers (e.g., 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:** View the [list of all registered providers](https://link-para-provedores). +* **General**: Promises with a lower level of assurance. + + +Registered providers are described in the [Providers Registry list](https://providers-list). --- ## Submitting Bundles -To include transaction bundles, submit them in the exact atomic sequence they appear. You can submit bundles using two methods: +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.* @@ -40,7 +36,7 @@ curl -X POST http://localhost:13523/v1/bidder/bid \ "revertingTxHashes": ["7ca1..."] }' ``` -## Option 2: Transaction Hash ## +### Option 2: Transaction Hash ## Use this for transactions already available in the public mempool. ```bashcurl -X POST http://localhost:13523/v1/bidder/bid \ -d '{ @@ -52,14 +48,14 @@ Use this for transactions already available in the public mempool. "revertingTxHashes": ["2214..."] }' ``` -## Bid Parameters ## +### **Bid Parameters** ## **Bid Amount**: Set this to the total amount you are willing to pay for the bundle. The gas used does not affect the final amount paid. **Bid Decay**: Use `decayStartTimestamp` and `decayEndTimestamp` to control -the price sensitivity of the preconfirmation. [Learn more here](https://docs.primev.xyz/v1.2.x/concepts/bids/bid-structure#details-on-decay-parameters). +the price sensitivity of the preconfirmation. [Learn how to control](https://docs.primev.xyz/v1.2.x/concepts/bids/bid-structure#details-on-decay-parameters). -**Bid Options**: Set positional constraints on transactions within the block. [View options here](https://github.com/andesign31/mev-commit-docs/blob/main/v1.2.x/concepts/bids/bid-structure#details-on-bidOptions). +**Bid Options**: Set positional constraints on transactions within the block. [Positional constraints options ](https://github.com/andesign31/mev-commit-docs/blob/main/v1.2.x/concepts/bids/bid-structure#details-on-bidOptions). ---- From 42f4e079ff6f86ace8fd2fc26992a1a8fb0d5f2e Mon Sep 17 00:00:00 2001 From: andesign31 Date: Sat, 20 Dec 2025 20:36:22 -0300 Subject: [PATCH 6/9] Last version --- v1.2.x/get-started/bidders/best-practices.mdx | 70 +++++++++++-------- v1.2.x/get-started/bidders/bidder-cli.mdx | 26 ++++--- 2 files changed, 56 insertions(+), 40 deletions(-) diff --git a/v1.2.x/get-started/bidders/best-practices.mdx b/v1.2.x/get-started/bidders/best-practices.mdx index ae62d2b3..963bc038 100644 --- a/v1.2.x/get-started/bidders/best-practices.mdx +++ b/v1.2.x/get-started/bidders/best-practices.mdx @@ -1,27 +1,38 @@ +--- +title: "Bidder Best Practices" +sidebarTitle: "Best Practices" +--- + # Bidder Best Practices This guide outlines the best practices for bidders to optimize their interactions with the mev-commit network and maximize their utility. ## Understanding Commitments -In the mev-commit network, you receive two types of commitments during the bidding process: **Credible** and **General**. +In the mev-commit network, commitments are essential to the bidding process. You receive two types of commitments: **Credible** and **General**. -* **Credible**: Guarantees with direct proposer opt-in. +### 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. -* **General**: Promises with a lower level of assurance. - - -Registered providers are described in the [Providers Registry list](https://providers-list). +### 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). --- ## Submitting Bundles -To include transaction bundles, submit them in the exact atomic sequence they appear. You can **submit bundles** using two methods: +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. @@ -37,8 +48,8 @@ curl -X POST http://localhost:13523/v1/bidder/bid \ }' ``` ### Option 2: Transaction Hash ## -Use this for transactions already available in the public mempool. -```bashcurl -X POST http://localhost:13523/v1/bidder/bid \ +Use this for transactions already available in the public mempool or provider RPCs. +```curl -X POST http://localhost:13523/v1/bidder/bid \ -d '{ "txHashes": ["0549..."], "amount": "", @@ -48,39 +59,36 @@ Use this for transactions already available in the public mempool. "revertingTxHashes": ["2214..."] }' ``` -### **Bid Parameters** ## -**Bid Amount**: Set this to the total amount you are willing to pay for the bundle. -The gas used does not affect the final amount paid. -**Bid Decay**: Use `decayStartTimestamp` and `decayEndTimestamp` to control -the price sensitivity of the preconfirmation. [Learn how to control](https://docs.primev.xyz/v1.2.x/concepts/bids/bid-structure#details-on-decay-parameters). +## Bid Parameters -**Bid Options**: Set positional constraints on transactions within the block. [Positional constraints options ](https://github.com/andesign31/mev-commit-docs/blob/main/v1.2.x/concepts/bids/bid-structure#details-on-bidOptions). +**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**: 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). -## Bidder Depositing & Automation ## -Bidders must bridge ETH to the mev-commit chain and deposit it toward providers. +**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). -**Deposit Manager** - -To avoid manual "top-ups", enable the **Deposit Manager**: - -Target Deposit: Set a desired amount for a specific provider. +---- -**Auto Top-up**: The system automatically restores the target value during settlement. +## Troubleshooting +If you are not receiving commitments instantly: -**Strategy**: Set target deposits to the maximum cumulative ETH you intend to bid for a single L1 block. + 1. **Check Parameters**: Ensure your bid is high enough for the requested commitment. -[Read more about the Deposit Manager](https://www.google.com/search?q=https://link-manager). +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). +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)/. ---- -## Troubleshooting -If you are not receiving commitments: +## 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. + +### Deposit Manager +To automate this, enable the **Deposit Manager**: -**Check Parameters**: Ensure your bid amount is competitive for the requested commitment. +* **Target Deposit**: Set the maximum cumulative amount of ETH you would bid to a provider for a single L1 block. -**Verify Topology**: Use the `/topology` endpoint to check provider connections. +* **Auto Top-up**: The relevant deposit will be automatically restored to the target value during settlement. -**Health Check**: Use the `/health` endpoint to ensure you are receiving mev-commit events. \ No newline at end of file +Read more about the [deposit manager here](https://docs.primev.xyz/v1.2.x/get-started/bidders/bidder-node-commands#deposit-manager). \ No newline at end of file diff --git a/v1.2.x/get-started/bidders/bidder-cli.mdx b/v1.2.x/get-started/bidders/bidder-cli.mdx index d5c8f539..080793d4 100644 --- a/v1.2.x/get-started/bidders/bidder-cli.mdx +++ b/v1.2.x/get-started/bidders/bidder-cli.mdx @@ -3,11 +3,13 @@ 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. + +The `bidder-cli` sends raw transactions or bids on existing transactions to the mev-commit network. +Download [releases](https://github.com/primev/mev-commit/releases/latest) page. ``` NAME: - bidder-cli - A CLI tool for interacting with a gRPC bidder server + bidder-cli - A CLI tool interacts with a gRPC bidder server USAGE: bidder-cli [global options] command [command options] @@ -16,16 +18,17 @@ 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 + send-tx-hash Sends a bid to the gRPC bidder server + send-tx Sends a transaction to the gRPC bidder server help, h Shows a list of commands or help for one command GLOBAL OPTIONS: --help, -h show help --version, -v print the version ``` +The `send-tx` command creates new transactions on the L1 chain and sends to the mev-commit network. -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. +User account is needed to sign the transaction. ``` NAME: @@ -47,15 +50,20 @@ OPTIONS: --help, -h show help ``` -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`. +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`. If `block-number` is not specified, the next block number is used for the bid. -Similarly, the default `decay-duration` is 10 minutes. Which means the bid amount will decay starting from current time to 10 minutes from now. +Similarly, the default `decay-duration` is 10 minutes. Which means the bid amount +will decay starting from current time to 10 minutes from now. -`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. +`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. - 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. +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. ```shell ❯_ example ./bidder-cli send-tx \ From 8a78be3494b346ebc16e7fe9f6d30646e4230e0d Mon Sep 17 00:00:00 2001 From: andesign31 Date: Sat, 20 Dec 2025 21:40:35 -0300 Subject: [PATCH 7/9] 1st --- v1.2.x/get-started/bidders/bidder-cli.mdx | 127 ++++++++-------------- 1 file changed, 44 insertions(+), 83 deletions(-) diff --git a/v1.2.x/get-started/bidders/bidder-cli.mdx b/v1.2.x/get-started/bidders/bidder-cli.mdx index 080793d4..abf1ce5e 100644 --- a/v1.2.x/get-started/bidders/bidder-cli.mdx +++ b/v1.2.x/get-started/bidders/bidder-cli.mdx @@ -3,104 +3,65 @@ title: "Bidder CLI application" sidebarTitle: "Bidder CLI" --- +# Bidder CLI -The `bidder-cli` sends raw transactions or bids on existing transactions to the mev-commit network. -Download [releases](https://github.com/primev/mev-commit/releases/latest) page. +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. -``` -NAME: - bidder-cli - A CLI tool interacts with a gRPC bidder server +<> +You can download the latest version of the tool from the [official releases page](https://github.com/primev/mev-commit/releases/latest). -USAGE: - bidder-cli [global options] command [command options] -VERSION: - 1.1.0 +## General Usage -COMMANDS: - send-tx-hash Sends a bid to the gRPC bidder server - send-tx Sends a transaction to the gRPC bidder server - help, h Shows a list of commands or help for one command +The basic structure for interacting with the gRPC bidder server is: -GLOBAL OPTIONS: - --help, -h show help - --version, -v print the version -``` -The `send-tx` command creates new transactions on the L1 chain and sends to the mev-commit network. +```bash +bidder-cli [global options] command [command options] +``` +## Global Commands +* `send-tx`: Used to create and sign a new L1 transaction and send it to the network. -User account is needed to sign the transaction. +* `send-tx-hash`: Used to send bids for transactions already present in the mempool. -``` -NAME: - bidder-cli send-tx - Send a transaction to the gRPC bidder server - -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 -``` - -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`. - -If `block-number` is not specified, the next block number is used for the bid. - -Similarly, the default `decay-duration` is 10 minutes. Which means the bid amount -will decay starting from current time to 10 minutes from now. - -`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. +* `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 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. +**Security**: You must provide the private key of the account to sign the transaction. Never share this key or include it in public scripts. -```shell ❯_ example +**Example Usage** +```` ./bidder-cli send-tx \ - --from \ - --to \ - --value \ - --bid-amount \ + --from \ + --to \ + --value \ + --bid-amount \ --rpc-url localhost:13524 -``` - -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. - -``` -NAME: - bidder-cli send-tx-hash - Send a bid to the gRPC bidder server + ```` + **Key Options** -USAGE: - bidder-cli send-tx-hash [command options] +* `--rpc-url`: The URL for the gRPC server (default is `localhost:13524`). -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 -``` +* `--block-number`: Target block for the bid. If omitted, the next block is used. -Users can provider multiple transaction hashes to bid on. Rest of the flags have similar use cases as above. +* `--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 +**Example Usage** +```` ./bidder-cli send-tx-hash \ - --tx-hashes \ - --tx-hashes \ - --bid-amount \ + --tx-hashes \ + --tx-hashes \ + --bid-amount \ --rpc-url localhost:13524 -``` +```` +Users can provide multiple --`tx-hashes` flags to bid on several transactions simultaneously. + +Important Considerations +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 for submission. + +Reverting Hashes: You can specify transactions that should be considered "reverting" using the --reverting-tx-hashes flag. \ No newline at end of file From b8756b6a4e0d2c761f0017305f70bf3c5115f7d1 Mon Sep 17 00:00:00 2001 From: andesign31 Date: Sun, 21 Dec 2025 07:35:07 -0300 Subject: [PATCH 8/9] docs: add structured guide for bidder cli with callouts --- v1.2.x/get-started/bidders/bidder-cli.mdx | 31 +++++++++++++++-------- 1 file changed, 21 insertions(+), 10 deletions(-) diff --git a/v1.2.x/get-started/bidders/bidder-cli.mdx b/v1.2.x/get-started/bidders/bidder-cli.mdx index abf1ce5e..925b760f 100644 --- a/v1.2.x/get-started/bidders/bidder-cli.mdx +++ b/v1.2.x/get-started/bidders/bidder-cli.mdx @@ -7,8 +7,8 @@ sidebarTitle: "Bidder CLI" 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. -<> -You can download the latest version of the tool from the [official releases page](https://github.com/primev/mev-commit/releases/latest). + +You can download the latest version of the tool from the [official releases page](https://github.com/primev/mev-commit/releases/latest). ## General Usage @@ -18,17 +18,17 @@ The basic structure for interacting with the gRPC bidder server is: ```bash bidder-cli [global options] command [command options] ``` -## Global Commands -* `send-tx`: Used to create and sign a new L1 transaction and send it to the network. +## Commands +* `send-tx`: Send a transaction to the gRPC bidder server. -* `send-tx-hash`: Used to send bids for transactions already present in the mempool. +* `send-tx-hash`: Send a bid to the gRPC bidder server for existing transactions. * `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. -**Security**: You must provide the private key of the account to sign the transaction. Never share this key or include it in public scripts. +**Security**: You must provide the private key of the account to sign the transaction. Never share this key or include it in public enviroments. **Example Usage** ```` @@ -38,7 +38,7 @@ This command allows you to create a simple transfer transaction on the L1 chain --value \ --bid-amount \ --rpc-url localhost:13524 - ```` +```` **Key Options** * `--rpc-url`: The URL for the gRPC server (default is `localhost:13524`). @@ -59,9 +59,20 @@ Use this command to bid on transactions that are already in the public mempool o --bid-amount \ --rpc-url localhost:13524 ```` -Users can provide multiple --`tx-hashes` flags to bid on several transactions simultaneously. +Users can provide multiple --`tx-hashes` flags to bid on several transactions simultaneously. Important Considerations -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 for submission. -Reverting Hashes: You can specify transactions that should be considered "reverting" using the --reverting-tx-hashes flag. \ No newline at end of file +**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. + +**Reverting Hashes**: You can specify transactions that should be considered "reverting" using the --reverting-tx-hashes flag. +--- +## Troubleshooting +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. \ No newline at end of file From 492e3034c847e1fdb262d9366383482a340cfd8d Mon Sep 17 00:00:00 2001 From: andesign31 Date: Sun, 21 Dec 2025 08:04:44 -0300 Subject: [PATCH 9/9] docs: improve readability and structure of bidder best practices --- v1.2.x/get-started/bidders/bidder-cli.mdx | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/v1.2.x/get-started/bidders/bidder-cli.mdx b/v1.2.x/get-started/bidders/bidder-cli.mdx index 925b760f..8c4cba39 100644 --- a/v1.2.x/get-started/bidders/bidder-cli.mdx +++ b/v1.2.x/get-started/bidders/bidder-cli.mdx @@ -63,12 +63,15 @@ Use this command to bid on transactions that are already in the public mempool o Important Considerations -**Gossip Latency**: There is a possibility that a transaction is not gossiped to the provider's infrastructure in time. +* **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. -**Reverting Hashes**: You can specify transactions that should be considered "reverting" using the --reverting-tx-hashes flag. +* **Reverting Hashes**: You can specify transactions that should be considered "reverting" using the `--reverting-tx-hashes` flag. + --- + ## Troubleshooting + If you're having trouble receiving commitments: 1. **Check Connectivity**: Ensure you are connected to providers via the topology endpoint.