Merge pull request #253 from primev/bidder-deposit-revamp

shaspitz · web-flow · commit 1100638d580c · 2025-09-02T22:49:27.000-07:00
diff --git a/v1.1.0/get-started/bidders/best-practices.mdx b/v1.1.0/get-started/bidders/best-practices.mdx
@@ -61,7 +61,7 @@ Bidders will start receiving commitments instantly in most cases. If you're havi
 
 Bidders on mev-commit need funds available in their account to submit bids, which can be obtained via bridging to your wallet address and then depositing to your node address. For testnet, you can obtain funds by using the [bridge](/v1.1.0/get-started/bridge). Once funds are deposited, the auto deposit function will automatically deposit funds into your account for the next 3 [windows](/v1.1.0/concepts/bids/bidder-deposit) to bid. Unused funds will automatically transfer into upcoming windows for bidding. You can read more about the auto deposit feature [here](https://docs.primev.xyz/v1.1.0/get-started/bidders/bidder-node-commands#autodeposit-funds).
 
-<!-- ## (Optional) Provider RPCs
+{/* ## (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. 
 
@@ -84,6 +84,4 @@ If you don't send transaction payloads in your bid, you can send your transactio
       <td>[rpc.titanbuilder.xyz](https://rpc.titanbuilder.xyz/)</td>
     </tr>
   </tbody>
-</table> -->
-
-
+</table> */}
diff --git a/v1.2.x/concepts/bids/bidder-deposit.mdx b/v1.2.x/concepts/bids/bidder-deposit.mdx
@@ -3,62 +3,16 @@ title: Understanding Bidder Deposit Rules
 sidebarTitle: Bidder Deposit
 ---
 
-Bidders need to deposit funds to be able to place bids on the mev-commit network. As bids are posted privately, providers cannot determine how much bidders have bid previously. To still ensure that bidders can cover all their bids, we bind deposits to specific L1 block numbers. Providers con thus ensure that bids from a given bidder do not exceed the amount deposited for the corresponding L1 block number. It is important to note that if a bidder deposits, for example, 1 ETH for some L1 block number, they can post bids totaling 1 ETH for each provider. This is because only a single provider can post the block to L1, meaning bids made to other providers will not be executed.
+Bidders need to deposit funds to be able to place bids on the mev-commit network. As bids are posted privately, providers cannot determine how much bidders have bid to other providers for the relevant L1 block. To ensure that bidders can cover all their bids, we bind deposits to specific providers. Providers can thus ensure that bids from a given bidder do not exceed the amount deposited for them.
 
-To simplify the user experience, mev-commit considers windows consisting of $\text{blocksPerWindow} = 10$ blocks and splits deposits to a window evenly over the corresponding blocks.
+It is important to note that if a bidder deposits, for example, 1 ETH for every provider, they can still only post bids totaling 1 ETH for a given block. This is because only a single provider can post the block to L1, meaning bids made to other providers will not be executed.
 
-The remaining funds of a bidder from a window (if any) can be unlocked after the corresponding blocks have been settled. The bidder can then withdraw the funds from the deposit. To further ease the user experience, bidders can enable autodeposits in their nodes, to automatically withdraw deposits from previous windows and redeposit them into future ones.
+Deposited funds can be withdrawn by the bidder at any time, after waiting the ~10 minute cooldown period.
 
-## Current window number
+## Deposit Manager
 
-The window number for a given L1 block can be calculated via the following formula, where `blocksPerWindow` is equal to 10 and `blockNumber` is the L1 block number for which the bidder wants to bid:
+It's recommended that bidders leverage the _deposit manager_ to deposit, and automate ongoing re-deposits to specific providers.
 
-$$
-\frac{{\text{{blockNumber}} - 1}}{{\text{{blocksPerWindow}}}} + 1
-$$
+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.
 
-
-## Minimum Deposit
-
-Since deposits are split across $\text{blocksPerWindow} = 10$ L1 blocks, bidders have to deposit at least 10 times the amount they want to bid for a single block.
-
-In the case of autodeposit, the deposits would be locked for around 3 windows at a time. Therefore, the total amount locked would be 30 times the amount.
-
-## Withdrawal Time
-
-The earliest withdrawal time can be calculated as follows: the withdrawal start time plus 20 L1 blocks (which is 240 seconds or 4 minutes) and the oracle lag of 10 L1 blocks (which is 120 seconds or 2 minutes), totaling 360 seconds or 6 minutes. Therefore, the total time before funds can be withdrawn is approximately 30 blocks (6 minutes) from the initial deposit.
-
-## Deposit/Withdrawal Flow
-
-<Frame>
-    <img src="/v1.2.x/images/bidder-deposit.png" />
-</Frame>
-
-This diagram illustrates the process and timeline of bidding, settlements, and withdrawals within mev-commit system, structured around a series of windows.
-
-### Diagram Description
-
-#### Timeline of Blocks
-
-- The horizontal axis represents a sequence of windows.
-- Windows are labeled as `n-2`, `n-1`, `n` and `n+1`, indicating their position relative to the current window `n`.
-
-#### Current Window
-
-- The "Current Window" is the interval within which bidding occurs.
-- The window consists of 10 L1 blocks.
-
-#### Bidding Phase
-
-- Bidding occurs in the current window, starting from the current block `n` and extending into the future blocks (`n+1`, etc.).
-- The arrow labeled "Bidding" points to the right, indicating that bidding continues into future blocks.
-
-#### Settlements Phase
-
-- Settlements happen after the bidding window closes.
-- The arrow labeled "Settlements" points downward, showing the transition from the bidding phase to the settlement phase.
-
-#### Withdrawals Phase
-
-- Withdrawals occur after settlements are completed.
-- The arrow labeled "Withdrawals" points to the left, indicating the final phase where bidders can withdraw their remaining funds.
+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.
diff --git a/v1.2.x/developers/bidder-api/bidder-deposit.mdx b/v1.2.x/developers/bidder-api/bidder-deposit.mdx
@@ -3,27 +3,33 @@ title: "Managing Your Bidder Deposit"
 sidebarTitle: Managing Your Bidder Deposit
 ---
 
-**To Check Your Deposit for current window:**
+**To check your deposit for a specific provider**
 
   ```shell
-  > curl localhost:13523/v1/bidder/get_deposit | jq
+  > curl -s "http://localhost:13523/v1/bidder/get_deposit?provider=0x3C44CdDdB6a900fa2b585dd299e03d12FA4293BC" | jq
   {
     "amount": "0",
-    "windowNumber": 1
+    "provider": "0x3C44CdDdB6a900fa2b585dd299e03d12FA4293BC"
   }
   ```
 
-**To Check Your Deposit for a specific window:**
+**To check deposits for all providers and get bidder EOA balance**
 
   ```shell
-  > curl localhost:13523/v1/bidder/get_deposit?window_number=1 | jq
+  > curl -s "http://localhost:13523/v1/bidder/get_all_deposits" | jq
   {
-    "amount": "0",
-    "windowNumber": 1
+    "deposits": [
+      {
+        "provider": "0x3C44CdDdB6a900fa2b585dd299e03d12FA4293BC",
+        "amount": "3000000000000000000"
+      }
+    ],
+    "bidderBalance": "9996999791340641239011"
   }
   ```
 
-**Funding Your Node Account:**
+**Funding your node account**
+
   First, retrieve the Ethereum account address of your node:
 
     ```shell
@@ -49,52 +55,124 @@ sidebarTitle: Managing Your Bidder Deposit
     }
     ```
 
-To add funds to your account on the mev-commit chain, you may use the [bridge](/v1.2.x/getting-started/bridge). 
+To add funds to your bidder EOA on the mev-commit chain, you may use the [bridge](/v1.2.x/get-started/bridge). 
 
+**Automate depositing - The easy way**
 
-- **Adding to Your Deposit:**
+It's recommended that bidders leverage the _deposit manager_ to deposit, and automate ongoing re-deposits to specific providers.
 
-To increase your deposit for the current window, use the following command, specifying the desired amount:
+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.
+
+The easiest way to enable the deposit manager is by setting two flags/environment variables upon starting your bidder node:
 
 ```shell
-> curl -X POST localhost/v1/bidder/deposit/YOUR_AMOUNT | jq
+> ./mev-commit --enable-deposit-manager=true --target-deposit-amount=<amount>
 ```
 
-To increase your deposit for the specific window, use the following command, specifying the desired amount and window number:
+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.
+
+**Automate depositing - Through API**
+
+To enable the deposit manager through API, use the following command:
 
 ```shell
-> curl -X POST "localhost/v1/bidder/deposit/YOUR_AMOUNT" \
-  -H "Content-Type: application/json" \
-  -d '{
-    "window_number": 1
-  }' | jq
+> curl -s -X POST http://localhost:13523/v1/bidder/enable_deposit_manager | jq
+{
+  "success": true
+}
+```
+
+Then to set target deposits customized to each provider:
+
+```shell
+> 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"
+  ]
+}
 ```
 
-To increase your deposit for the specific L1 block number, use the following command, specifying the desired amount and L1 block number:
+**Manually adding to your deposit**
+
+If you'd like to manually increase the deposit for a provider, use the following command, specifying the desired amount:
 
 ```shell
-> curl -X POST "localhost/v1/bidder/deposit/YOUR_AMOUNT" \
-  -H "Content-Type: application/json" \
+> curl -s -X POST "http://localhost:13523/v1/bidder/deposit/1000000000000000000?provider=0x3C44CdDdB6a900fa2b585dd299e03d12FA4293BC" | jq
+{
+  "amount": "1000000000000000000",
+  "provider": "0x3C44CdDdB6a900fa2b585dd299e03d12FA4293BC"
+}
+```
+
+To manually deposit evenly to multiple providers, use the following command:
+
+```shell
+> curl -s -X POST "http://localhost:13523/v1/bidder/deposit_evenly?total_amount=2000000000000000000&providers=0x8F644015Aa59984BF849259375d9135A89a940e7&providers=0x353ff5537cc2fe78C8632c41Bb848735C2982c45" | jq
+{
+  "providers": [
+    "8f644015aa59984bf849259375d9135a89a940e7",
+    "353ff5537cc2fe78c8632c41bb848735c2982c45"
+  ],
+  "amounts": [
+    "1000000000000000000",
+    "1000000000000000000"
+  ]
+}
+```
+
+After successfully depositing, you are ready to send bids and receive preconfirmations on the network.
+
+**Withdrawing from your deposit**
+
+To withdraw funds from your deposit to a specific provider, use the following command:
+
+```shell
+> curl -s -X POST http://localhost:13523/v1/bidder/request_withdrawals \
+  -H 'Content-Type: application/json' \
   -d '{
-    "block_number": 1,
+    "providers": [
+      "0x3C44CdDdB6a900fa2b585dd299e03d12FA4293BC"
+    ]
   }' | jq
+{
+  "providers": [
+    "3c44cdddb6a900fa2b585dd299e03d12fa4293bc"
+  ],
+  "amounts": [
+    "3000000000000000000"
+  ]
+}
 ```
-After successfully adding to your deposit, you are ready to send bids and receive preconfirmations on the network.
-
-- **Withdrawing from Your Deposit:**
 
-To withdraw funds from your deposit, use the following command:
+Then you must wait the withdrawal period to elapse, currently ~10 minutes. Then finally call:
 
 ```shell
-> curl -X POST localhost/v1/bidder/withdraw \
-  -H "Content-Type: application/json" \
+curl -s -X POST http://localhost:13523/v1/bidder/withdraw \
+  -H 'Content-Type: application/json' \
   -d '{
-    "window_number": 1
+    "providers": [
+      "0x3C44CdDdB6a900fa2b585dd299e03d12FA4293BC"
+    ]
   }' | jq
+{
+  "providers": [
+    "3c44cdddb6a900fa2b585dd299e03d12fa4293bc"
+  ],
+  "amounts": [
+    "3000000000000000000"
+  ]
+}
 ```
-If you don't specify a window number, the current window will be used by default.
 
-### Outcome of Preconfirmed Bids:
+### Outcome of preconfirmed bids
+
 When a bid is preconfirmed by a provider, there are several possible outcomes:
 
 | Outcome Matrix | Provider Wins Slot Auction| Provider Loses Slot Auction |
diff --git a/v1.2.x/get-started/bidders/best-practices.mdx b/v1.2.x/get-started/bidders/best-practices.mdx
@@ -57,11 +57,11 @@ The `decayStartTimestamp` and `decayEndTimestamp` are important components for h
 ## 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 Funds and Autodeposit Window
+## Bidder Depositing
 
-Bidders on mev-commit need funds available in their account to submit bids, which can be obtained via bridging to your wallet address and then depositing to your node address. For testnet, you can obtain funds by using the [bridge](/v1.2.x/get-started/bridge). Once funds are deposited, the auto deposit function will automatically deposit funds into your account for the next 3 [windows](/v1.2.x/concepts/bids/bidder-deposit) to bid. Unused funds will automatically transfer into upcoming windows for bidding. You can read more about the auto deposit feature [here](https://docs.primev.xyz/v1.2.x/get-started/bidders/bidder-node-commands#autodeposit-funds).
+Bidders on mev-commit need to be funded with ETH which can be obtained via [bridging](/v1.2.x/get-started/bridge). Then a bidder must deposit toward one or more providers. To automate this process, the bidder can enable the deposit manager and set target deposits for each provider. Read more about the deposit manager [here](https://docs.primev.xyz/v1.2.x/get-started/bidders/bidder-node-commands#deposit-manager).
 
-<!-- ## (Optional) Provider RPCs
+{/* ## (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. 
 
@@ -84,6 +84,6 @@ If you don't send transaction payloads in your bid, you can send your transactio
       <td>[rpc.titanbuilder.xyz](https://rpc.titanbuilder.xyz/)</td>
     </tr>
   </tbody>
-</table> -->
+</table> */}
 
 
diff --git a/v1.2.x/get-started/bidders/bidder-node-commands.mdx b/v1.2.x/get-started/bidders/bidder-node-commands.mdx
