diff --git a/v1.1.0/get-started/bidders/best-practices.mdx b/v1.1.0/get-started/bidders/best-practices.mdx index b2b3b5a7..5f93753b 100644 --- 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). - - - + */} diff --git a/v1.2.x/concepts/bids/bidder-deposit.mdx b/v1.2.x/concepts/bids/bidder-deposit.mdx index ae5d46fc..55c03034 100644 --- 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 - - - - - -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 index 5e705e1d..2ece6322 100644 --- 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= ``` -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 index cbecd0a6..a8f10140 100644 --- 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). - + */} diff --git a/v1.2.x/get-started/bidders/bidder-node-commands.mdx b/v1.2.x/get-started/bidders/bidder-node-commands.mdx index bdb83222..998c7a6b 100644 --- a/v1.2.x/get-started/bidders/bidder-node-commands.mdx +++ b/v1.2.x/get-started/bidders/bidder-node-commands.mdx @@ -17,91 +17,157 @@ export ADDRESS=$(cast wallet address --private-key 0x$(cat key)) ## Getting Deposit -To get the current deposit balance in the contract for the current [window](/v1.2.x/concepts/bids/bidder-deposit): +To get the currently deposited balance on-chain for a provider: ```shell ❯_ terminal -curl -s http://localhost:13523/v1/bidder/get_deposit +> curl -s "http://localhost:13523/v1/bidder/get_deposit?provider=0x3C44CdDdB6a900fa2b585dd299e03d12FA4293BC" | jq +{ +"amount": "0", +"provider": "0x3C44CdDdB6a900fa2b585dd299e03d12FA4293BC" +} ``` -To get the current deposit balance in the contract for a specific [window](/v1.2.x/concepts/bids/bidder-deposit): +Or to query all deposits and the bidder's EOA balance: ```shell ❯_ terminal -curl -s http://localhost:13523/v1/bidder/get_deposit?windowNumber=1 +> 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. -## Withdraw Deposited Funds +## Deposit Manager -This command will allow you to withdraw funds from the specific [window](/v1.2.x/concepts/bids/bidder-deposit). -Window number is the number where the bidder deposited funds. +It's recommended that bidders leverage the _deposit manager_ to deposit, and automate ongoing re-deposits to specific providers. -```shell ❯_ terminal -curl -X POST http://localhost:13523/v1/bidder/withdraw?windowNumber=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. -## Autodeposit 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. -The auto deposit feature allows you to automate the process of depositing funds for the bidder account. This is useful for ensuring your bidder account always has funds available to bid. In order to achieve this, the node will keep issuing deposits for the new windows and also withdrawing funds from the previous windows. +There are two ways to enable this feature... - For seamless availability of funds, the deposits would be locked for around 3 windows at a time. So the total amount locked would be `3 * amountPerWindow`. The user's wallet should have enough funds to be able to maintain these deposits as well as cover gas costs to issue transactions. +### On node boot up (recommended) -There are two ways to enable this feature: +The easiest way to enable the deposit manager is by setting two flags/environment variables upon starting your bidder node: -### On node boot up +```shell +> ./mev-commit --enable-deposit-manager=true --target-deposit-amount= +``` -Users can use the command-line or the configuration file to enable this feature on node boot-up. The `autodeposit-enabled` flag should be set as well as the `autodeposit-amount` needs to be set to the amount to be deposited in each window. +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. - In order to enable this at node boot up, users needs to fund their wallet before starting the node. So we would need to know the private-key used for the account beforehand. +### Through API -```shell ❯_ terminal -mev-commit --keystore-path ~/.mev-commit \ - --keystore-password \ - --bootnodes /dnsaddr/bootnode.testnet.mev-commit.xyz \ - --settlement-rpc-endpoint https://chainrpc.testnet.mev-commit.xyz - --autodeposit-enabled true - --autodeposit-amount 1000000000000000000 +To enable the deposit manager through API, use the following command: + +```shell +> curl -s -X POST http://localhost:13523/v1/bidder/enable_deposit_manager | jq +{ + "success": true +} ``` -### Use the Bidder API +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" + ] +} +``` -Another option to enable this is using the Bidder API. +## Get Deposit Manager Status ```shell ❯_ terminal -curl -X POST http://localhost:13523/v1/bidder/auto_deposit/1000000000000000000 +curl -s http://localhost:13523/v1/bidder/deposit_manager_status | jq ``` -## Get Auto Deposit Status - -To get the status of the auto deposit process: - -```shell ❯_ terminal -curl -s http://localhost:13523/v1/bidder/auto_deposit_status +```json +{ + "enabled": true, + "targetDeposits": [ + { + "provider": "0x3C44CdDdB6a900fa2b585dd299e03d12FA4293BC", + "targetDeposit": "3000000000000000000" + }, + { + "provider": "0x3C44CdDdB6a900fa2b585dd299e03d12FA4293BC", + "targetDeposit": "3000000000000000000" + } + ] +} ``` -## Cancel Auto Deposit +## Disable Deposit Manager -To cancel the auto deposit process: +To disable the deposit manager call: ```shell ❯_ terminal -curl -X POST http://localhost:13523/v1/bidder/cancel_auto_deposit?withdraw=true +curl -X POST http://localhost:13523/v1/bidder/disable_deposit_manager ``` -This will stop the ongoing auto deposit process. - - If withdraw is set, the node will try to withdraw the deposit at the earliest possible time. It might take time before we are able to withdraw from the current window. The bidder node should be running in order to allow this process to complete. If withdraw is not set, the API will return the window numbers which have been already deposited to. The user can then manually issue withdraw at a later point using the API. +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 the several windows, you can use the following command: +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 '{ + "providers": [ + "0x3C44CdDdB6a900fa2b585dd299e03d12FA4293BC" + ] + }' | jq +{ + "providers": [ + "3c44cdddb6a900fa2b585dd299e03d12fa4293bc" + ], + "amounts": [ + "3000000000000000000" + ] +} +``` -```shell ❯_ terminal -curl -X POST http://localhost:13523/v1/bidder/withdraw_from_windows \ --H "Content-Type: application/json" \ --d '{"windowNumbers": [1, 2, 3]}' +Then you must wait the withdrawal period to elapse, currently ~10 minutes. Then finally call: + +```shell +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: @@ -130,7 +196,7 @@ python3 -c "print($(cast b 0x401B3287364f95694c43ACA3252831cAc02e5C41 \ ``` ## 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 (e.g. can't find the window balance). +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 curl http://localhost:13523/health ```