diff --git a/developers/bidder-api.mdx b/api-reference/bidder-api.mdx similarity index 98% rename from developers/bidder-api.mdx rename to api-reference/bidder-api.mdx index 2bd651a3..5518efe3 100644 --- a/developers/bidder-api.mdx +++ b/api-reference/bidder-api.mdx @@ -1,5 +1,6 @@ --- title: "Bidder API" +sidebarTitle: "Bidder API Overview" --- ## **Bidders** diff --git a/developers/provider-api.mdx b/api-reference/provider-api.mdx similarity index 98% rename from developers/provider-api.mdx rename to api-reference/provider-api.mdx index e140a407..f5dece4a 100644 --- a/developers/provider-api.mdx +++ b/api-reference/provider-api.mdx @@ -1,5 +1,6 @@ --- title: "Provider API" +sidebarTitle: "Provider API Overview" --- ## **Providers** diff --git a/concepts/bids/bid-decay-mechanism.mdx b/concepts/bids/bid-decay-mechanism.mdx index 91bc0022..07760e75 100644 --- a/concepts/bids/bid-decay-mechanism.mdx +++ b/concepts/bids/bid-decay-mechanism.mdx @@ -1,18 +1,18 @@ --- title: Bid Decay Mechanism sidebarTitle: Bid Decay -description: "Learn about how bids decay in value after they are issued." +description: "Learn about how bids decay in value after they are issued" --- In the mev-commit auction for transaction bundles, bidders submit their bids to providers and their goal is to receive a confirmation that the bundle they bid for will be included in the next block produced by the provider. Bidders aim to receive confirmation for their bundle as soon as possible since early confirmations tend to be more valuable to the bidders. However, providers may want to wait until the last moment to issue confirmations in order to build the most valuable block possible without missing out on any late bids. Therefore, it's essential to have a mechanism that encourages providers to confirm bids as early as possible. This is where a bid decay mechanism comes into play, which reduces the value of a bid based on the time elapsed since it was issued. -## Mechanism Description: -The timestamp is specified in Unix milliseconds. For example, a timestamp of `1633046400000` represents `October 1, 2021 00:00:00 GMT`. +## Mechanism Description +Every bid has two timestamps attached to it: **(1)** a timestamp indicating the exact time of dispatch of the bid, and **(2)** an expiry timestamp, marking the moment when the decay for this bid reaches 100%—essentially, the point in time beyond which the bidder is unwilling to pay anything to a provider for a commitment. -Every bid has two timestamps attached to it: (1) a timestamp indicating the exact time of dispatch of the bid, and (2) an expiry timestamp, marking the moment when the decay for this bid reaches 100%—essentially, the point in time beyond which the bidder is unwilling to pay anything to a provider for a commitment. +The timestamp is specified in Unix milliseconds. For example, a timestamp of `1633046400000` represents `October 1, 2021 00:00:00 GMT`. When a provider decides to commit to the bid, they must issue a commitment and also assign a "commitment timestamp" to it. This commitment is then sent to the mev-commit chain for inclusion. The mev-commit chain will include the commitment into the chain, however the commitment will only be considered valid if the commitment timestamp supplied by the provider is not "too old" in comparison to the block timestamp where the commitment was included, or more formally, their difference is within some time interval $\Delta$. @@ -42,7 +42,7 @@ In many network-based systems, including our decay mechanism, faster connections Our decay mechanism design achieves the following properties: -**1. Predictability of Decay:** the providers can *accurately compute* how much their decay will be for a commitment. +**1. Predictability of Decay:** The providers can *accurately compute* how much their decay will be for a commitment. **2. Public Verifiability of Decay**: The decay mechanism offers public verifiability, as the decay amount can be calculated using the public timestamps from the bid and the commitment. diff --git a/concepts/bids/bid-structure.mdx b/concepts/bids/bid-structure.mdx index e5dea326..032c35f3 100644 --- a/concepts/bids/bid-structure.mdx +++ b/concepts/bids/bid-structure.mdx @@ -1,4 +1,5 @@ --- +title: Bid Structure sidebarTitle: Bid Structure --- diff --git a/concepts/commitments.mdx b/concepts/bids/commitments.mdx similarity index 100% rename from concepts/commitments.mdx rename to concepts/bids/commitments.mdx diff --git a/concepts/mev-commit-chain/chain-details.mdx b/concepts/mev-commit-chain/chain-details.mdx index cf840c6a..e0b6a172 100644 --- a/concepts/mev-commit-chain/chain-details.mdx +++ b/concepts/mev-commit-chain/chain-details.mdx @@ -3,15 +3,15 @@ title: "Chain Details" sidebarTitle: Chain Details --- -Mev-commit chain mainnet is set to launch soon. In the meantime, join the testnet and get familiar with its functionalities at the [Testnet](/developers/testnet) section. +The mev-commit chain mainnet is set to launch soon. In the meantime, join the testnet and get familiar with its functionalities at the [Testnet](/developers/testnet) section. -## **Design** +## Design Mev-commit chain is currently built out as an Ethereum sidechain run with [go-ethereum’s Clique proof-of-authority consensus mechanism](https://geth.ethereum.org/docs/tools/clef/clique-signing). It's not a generalized chain for everyone to launch dapps on, but only for specific execution service applications, such as preconfirmations, top of block, bottom of block, or other services. Source code for the geth fork which runs the mev-commit chain can be found in the [mev-commit-geth repo](https://github.com/primev/mev-commit-geth). -## **Progressive decentralization** +## Progressive decentralization Today, most or arguably all Ethereum scaling solutions rely on centralized bridging and sequencing. Mev-commit components rely on existing tech, and consequently inherit this property. However anyone can permissionlessly validate correct execution, and operation of chain infrastructure. Moreover, because the mev-commit p2p network is decentralized and commitments are cryptographic, actors can theoretically settle commitments without the mev-commit chain. @@ -19,17 +19,17 @@ At this point of the network's inception, Primev entities will run all validatin The mev-commit chain will continue to evolve. We have ongoing research into consensus algorithms we can employ to decentralize the mev-commit chain without compromising on speed. Open source scaling solutions that prove to be practical, decentralized, and meet security thresholds will be considered to decentralize the mev-commit chain. -## **POA geth nodes** +## POA geth nodes Primev currently maintains a mev-commit-geth bootnode which doesn’t participate in consensus, and a set of full-node POA signers that run consensus. These signers take turns proposing the next block by utilizing a waiting period. The current target block period is 200ms, meaning about 60 mev-commit chain blocks will be committed for every Ethereum mainnet block. The block time will likely change as enhancements are added and chain state grows. -## **Fee Mechanism** +## Fee Mechanism **Non-inflationary Approach**: The fee mechanism on the mev-commit chain is designed to be non-inflationary, maintaining a strict 1:1 peg between the sidechain ether and the L1 escrowed ether. This is achieved through a variation of EIP-1559, where base fees are accumulated in a treasury and priority fees are allocated to block signers. -## **Smart Contracts** +## Smart Contracts Smart Contracts are deployed on the mev-commit chain to enable use cases, follow bid and commitment states, and invoke rewards or slashing as needed. Anyone can deploy contracts on the mev-commit chain, however there'll be additional integration work needed with mev-commit off-chain components to fully enable the use case under the current design. Thus we first recommend getting in touch with the Primev team to enable a use case at this stage of the network. @@ -40,7 +40,7 @@ Currently deployed contracts are designed as follows: - An oracle contract receives L1 payloads from the oracle service. It currently operates by checking confirmed Holesky blocks, and will transition to Mainnet as mev-commit migrates to Mainnet. - An block tracker contract which designed to track Ethereum blocks and their respective winners. -## **Oracle service** +## Oracle service The oracle service is an off-chain process that interacts with the oracle contract as needed. This service monitors and extracts the winning builder and corresponding transaction hash list from each L1 block, and submits this data to the oracle contract residing on the mev-commit chain. diff --git a/concepts/network-overview.mdx b/concepts/network-overview.mdx index f7e14069..16f7155b 100644 --- a/concepts/network-overview.mdx +++ b/concepts/network-overview.mdx @@ -3,14 +3,24 @@ title: Understanding mev-commit sidebarTitle: Network Overview --- +### Overview + Mev-commit is designed as an out of protocol layer to systems like mev-boost, facilitating the exchange of execution bids and commitments between mev actors, solving for coordination inefficiencies. This design ensures that only necessary parts of this faciliation happen on mev-commit (bids, commitments, settlement) and not the transaction flow itself. This design achieves chain abstraction by its nature, as any transaction hash on any chain can be referred to in a mev-commit bid, and be paid in eth. Bids and commitments on mev-commit also do not rely on blockchain bottlenecks and are real-time. +### Bids and Commitments + Bids are received and evaluated by providers, who run decisioning logic in their own environment and may decide to issue a cryptographic commitment against whatever the bid is for. In the preconfirmation case, the minimum a commitment can be made is for inclusion of the referred transaction hash(es) in the bid on the target L1 block number specified. +### Commitment Settlements + Once the commitment is recorded on the mev-commit chain, an oracle will check the target L1 block number as it gets confirmed to see if the commitment is satisfied by the committing actor. If so, the bid amount will be rewarded to the provider. If not, the provider stake will be slashed. +### Rewards and Slashing + _Only the actors who participated in the block's confirmation are considered for rewards or slashing._ This means if Block Builder A and Block Builder B commit to a bid and the target block is built by Block Builder A, the oracle will reward or slash Block Builder A. +### Network Architechture + The architecture of the mev-commit peer-to-peer (P2P) network is designed to support instantaneous communication among network participants. The diagram below depicts how mev-commit acts as a layer on bidder and provider operations, that are external to the mev-commit network by its nature: diff --git a/concepts/what-is-mev-commit.mdx b/concepts/what-is-mev-commit.mdx index 138307c0..bcfb51ea 100644 --- a/concepts/what-is-mev-commit.mdx +++ b/concepts/what-is-mev-commit.mdx @@ -9,6 +9,18 @@ Mev-commit is a peer-to-peer (P2P) networking platform designed to facilitate re +## What are Bids? + +Within mev-commit, bids act as the foundational requests placed by bidders, signaling their need for specific transaction execution services. This process occurs within a peer-to-peer networking setup to streamline direct negotiations with execution service providers like block builders and rollup sequencers. Each bid, marked by the unique identifier of a transaction hash, enables a straightforward mechanism for providers across the network to recognize and respond to these requests. + +Bids essentially convey a user's readiness to pay a certain fee for the execution of their transaction, proposing a price designed to motivate execution providers to give priority to their transaction. + +## What are Commitments? + +Commitments within mev-commit represent the execution providers' affirmative responses to bids, confirming their agreement to execute the specified transactions at the proposed prices within designated blocks. These commitments are conveyed through cryptographic proofs or digital signatures, signifying the providers' acceptance of a bid. + +Commitments serve as the critical link that aligns the supply and demand dynamics of the network, facilitating an effective and streamlined process for transaction execution. + ## Actors Network actors' roles are defined based on their interactions with other ecosystem actors. The diagram below depicts a given mev actor's relative placement compared to others: @@ -17,48 +29,24 @@ Network actors' roles are defined based on their interactions with other ecosyst -For example, a Searcher can be a bidder for a Sequencer; but that same Sequencer can be a bidder for a block builder. Thus it's best to think of actors' roles in mev-commit similar to their roles in the mev pipeline. To the left of the diagram are bidders, and to the right of the diagram are execution providers who can issue commitments against these bids. +For example, a Searcher can be a bidder for a Sequencer, but that same Sequencer can be a bidder for a block builder. Thus, it's best to think of actors' roles in mev-commit as similar to their roles in the mev pipeline. To the left of the diagram are bidders, and to the right of the diagram are execution providers who can issue commitments against these bids. Under the Proposer Builder Separation (PBS) model, information only moves to the right among actors in the mev pipeline. With mev-commit, credible commitments for execution and bits of information flow from providers back to bidders, enabling them to effectively utilize block space. This two-way exchange of information and commitments within the mev-commit system enhances the dynamic utilization and management of block space, supporting a more interactive and responsive ecosystem. ### **Providers** -Providers in the mev ecosystem include **Block Builders, Relays, Proposers, Rollup Sequencers, and even Solvers**. They are crucial for the delivery of commitments through their role in respective ecosystem or their sophistication. These providers receive bids and deliver transaction inclusion and execution, ensuring the efficient and effective use of block space. +Providers in the mev ecosystem include **Block Builders, Relays, Proposers, Rollup Sequencers, and even Solvers**. They are crucial for the delivery of commitments through their role in the respective ecosystem or their sophistication. These providers receive bids and deliver transaction inclusion and execution, ensuring the efficient and effective use of block space. ### **Bidders** -Bidders consist of **Searchers, Solvers, Blob Producers, AA Bundlers, Wallets and even End Users**. They bid for execution services, aiming to optimize their transactions within the block space. Their activities are fundamental to maintaining a competitive and efficient environment within the mev pipeline, facilitating a dynamic market for block space utilization. - -For a deep-dive into these roles and their interactions, please visit the [Actors](/concepts/actors) section. - -## Bids +Bidders consist of **Searchers, Solvers, Blob Producers, AA Bundlers, Wallets, and even End Users**. They bid for execution services, aiming to optimize their transactions within the block space. Their activities are fundamental to maintaining a competitive and efficient environment within the mev pipeline, facilitating a dynamic market for block space utilization. -Within mev-commit, bids act as the foundational requests placed by bidders, signaling their need for specific transaction execution services. This process occurs within a peer-to-peer networking setup to streamline direct negotiations with execution service providers like block builders and rollup sequencers. Each bid, marked by the unique identifier of a transaction hash, enables a straightforward mechanism for providers across the network to recognize and respond to these requests. - -Bids essentially convey a user's readiness to pay a certain fee for the execution of their transaction, proposing a price designed to motivate execution providers to give priority to their transaction. - -## Commitments - -Commitments within mev-commit represent the execution providers' affirmative responses to bids, confirming their agreement to execute the specified transactions at the proposed prices within designated blocks. These commitments are conveyed through cryptographic proofs or digital signatures, signifying the providers' acceptance of a bid. - -Commitments serve as the critical link that aligns the supply and demand dynamics of the network, facilitating an effective and streamlined process for transaction execution. - -## mev-commit software components - -- [mev-commit p2p client](https://github.com/primev/mev-commit/tree/main/p2p) -- [mev-commit-geth](https://github.com/primev/mev-commit-geth) -- [contracts](https://github.com/primev/mev-commit/tree/main/contracts) -- [mev-commit-oracle](https://github.com/primev/mev-commit/tree/main/oracle) -- [mev-commit-bridge](https://github.com/primev/mev-commit/tree/main/bridge) +For a detailed look at these roles and their interactions, please visit the [Actors](/concepts/actors) section. ## Why mev-commit? Through our experience developing products for the Ethereum and the broader crypto ecosystem, we’ve learned that users want to interact with networks as a whole as opposed to single actors that represent some percentage of the network, which is challenging to provide in decentralized systems that have goals beyond user needs. -We've created mev-commit to address this and optimized it to solve for coordination inefficiencies across the actors of any blockchain network, which are sure to increase with decentralization and greater transaction complexity. Mev-commit's actor and chain agnostic credible commitment approach ensures that users are not only able to convey their needs to a blockchain network, but receive commitments from the executors of those needs in real time so they can confidently take actions based on their expectation being satisfied or not. +We've created mev-commit to address this and optimized it to solve coordination inefficiencies across the actors of any blockchain network, which are sure to increase with decentralization and greater transaction complexity. Mev-commit's actor and chain agnostic credible commitment approach ensures that users are not only able to convey their needs to a blockchain network, but receive commitments from the executors of those needs in real time so they can confidently take actions based on their expectation being satisfied or not. We’re constructing mev-commit to be aligned with the ethos of the crypto ecosystem, specifically the vision being laid out by the Ethereum Foundation, and out of protocol services that supplement that vision such as the current mev pipeline largely introduced by Flashbots. We don’t aim to design a different mev pipeline, but create new avenues for efficiency in solving coordination problems between actors that can be used to have an expectation matching experience when engaging in the existing auctions and mev pipeline. We plan to continue supporting mev-commit’s evolution and adoption according to this mission as the existing landscape shifts and new paradigms are introduced. - -## Contribute - -Stay updated and engage with Primev through our social platforms. Follow us on [Twitter](https://twitter.com/primev_xyz) for the latest news and updates, and contribute to our open-source journey on [GitHub](https://github.com/primev/). diff --git a/developers/testnet.mdx b/developers/testnet.mdx index 8a312f74..9263c0ba 100644 --- a/developers/testnet.mdx +++ b/developers/testnet.mdx @@ -3,9 +3,7 @@ title: mev-commit Testnet sidebarTitle: Testnet --- -## mev-commit Testnet - -Live on Holesky Testnet, mev-commit allows bidders and providers to engage in execution service bids and commitments. Preconfirmations, the first use case for real time bids and commitments, are available to be tested on the mev-commit testnet. +Live on Holesky Testnet, mev-commit allows bidders and providers to engage in execution service bids and commitments. Preconfirmations, the first use case for real-time bids and commitments, are available to be tested on the mev-commit testnet. ## **Links and Connection Details** @@ -61,6 +59,14 @@ Primev will maintain a testnet consisting of the mev-commit chain, oracle servic +## mev-commit software components + +- [mev-commit p2p client](https://github.com/primev/mev-commit/tree/main/p2p) +- [mev-commit-geth](https://github.com/primev/mev-commit-geth) +- [contracts](https://github.com/primev/mev-commit/tree/main/contracts) +- [mev-commit-oracle](https://github.com/primev/mev-commit/tree/main/oracle) +- [mev-commit-bridge](https://github.com/primev/mev-commit/tree/main/bridge) + ## Differences Between the Testnet and Mainnet Environments Testnet bridging ether to/from Holesky, whereas mainnet mev-commit chain will bridge using mainnet ether. Commitments are also written to the settlement chain in plaintext, whereas mainnnet will include private commitments. diff --git a/get-started/quickstart.mdx b/get-started/quickstart.mdx deleted file mode 100644 index 149dbc2f..00000000 --- a/get-started/quickstart.mdx +++ /dev/null @@ -1,78 +0,0 @@ ---- -title: "Quickstart Your mev-commit Node" -description: "Step into the Primev ecosystem with ease. This guide covers everything you need to set up your mev-commit node, whether you're aiming to be a bidder or a provider." -sidebarTitle: Quickstart -icon: "gear" ---- - -# Quickstart - -Ready to get your node up and running? This streamlined process will guide you through launching either a bidder or provider node on the mev-commit network. - - - - ```bash ❯_ bidder - curl -L -o launchmevcommit launch.mev-commit.xyz; chmod +x launchmevcommit; ./launchmevcommit --node-type bidder - ``` - - ```bash ❯_ provider - curl -L -o launchmevcommit launch.mev-commit.xyz; chmod +x launchmevcommit; ./launchmevcommit --node-type provider - ``` - - - - To fund your account, please visit http://faucet.testnet.mev-commit.xyz/. Details about the account address will be displayed after running the commands below. - -

- - - - ## Script Overview - - This script automates the setup and initialization of your Primev node, catering to both bidder and provider roles. Below is a detailed breakdown of the script's operations: - - ### 1. Initialization - - Sets up essential variables like the RPC URL (`https://chainrpc.testnet.mev-commit.xyz) for network communication and the node type (either `bidder` or `provider`). - - Establishes the root directory (`$HOME/.mev-commit`) where the mev-commit node will be installed. - - ### 2. Download - - Fetches the appropriate mev-commit binary for your system from the [Primev GitHub releases page](https://github.com/primev/mev-commit/releases/latest), considering your operating system and architecture. - - ### 3. Installation - - Extracts the downloaded binary into the specified root directory, ensuring all necessary executables are correctly placed for the node's operation. - - ### 4. Configuration - - Initializes the mev-commit node with your specified settings, including the node type and the RPC endpoint, along with necessary contract addresses for the node's functionality. - - ### 5. Wallet Setup - - Generates a new private key and wallet address for your node and secures it with test ether to facilitate transactions within the testnet environment. - - ### 6. Node Startup - - Launches the mev-commit node in the background tailored to the specified role, enabling it to begin its operations within the Primev network. - - ### 7. Cleanup - - Includes a cleanup function to ensure the node is properly shut down when the script exits, preventing any residual processes. - - - -If you want to perform a manual setup with detailed steps, please skip to the [manual start mev-commit](/developers/manual-start-mev-commit) section. - -# What's next? - - -
- -
-
- Once your node is funded, you can move on to [My First Preconf](/get-started/bidders/first-preconf) to start sending bids. - -
-
- -
-
- In order to register as a provider, please go through the [registration - process](/get-started/providers/registering-a-provider). - -
- diff --git a/get-started/introduction.mdx b/get-started/welcome-to-primev.mdx similarity index 50% rename from get-started/introduction.mdx rename to get-started/welcome-to-primev.mdx index c4878f9b..97304e8e 100644 --- a/get-started/introduction.mdx +++ b/get-started/welcome-to-primev.mdx @@ -1,9 +1,9 @@ --- title: Welcome to Primev -sidebarTitle: Welcome +sidebarTitle: Welcome to Primev description: "Primev is building mev-commit; a credible commitment network used for preconfirmations & more" -icon: sailboat -mode: wide +mode: "wide" +icon: "sailboat" --- import { @@ -14,11 +14,10 @@ import { QuickStartCardFooter, } from "/snippets/quick-start-card.mdx"; -## Get Started - -Welcome to the starting point of your mev-commit journey! -Our quickstart guides are tailored to your specific role within the Ethereum ecosystem and designed to get you up and running quickly. -Choose the guide below that best aligns with your interests and needs: +Welcome to the starting point of your mev-commit journey! + +You can either visit our [quickstart guide](/get-started/quickstart) which is tailored to your specific role within the Ethereum ecosystem and designed to get you up and running quickly. +Or if you want to learn about specific concepts first, please visit the pages below that best align with your interests and needs: @@ -30,21 +29,20 @@ Choose the guide below that best aligns with your interests and needs: - For those looking to explore MEV opportunities, follow our Bidder Quickstart to learn how to - efficiently identify and capture valuable transactions. + Bidders seek to optimize their transaction execution strategies. Explore the resources below to efficiently identify and capture valuable transactions. • [Receive a Preconfirmation](/get-started/bidders/first-preconf) - • [Bidder Node Commands](/get-started/bidders/bidder-node-commands) + • [Node Commands](/get-started/bidders/bidder-node-commands) - • [Bid Structure](/concepts/bids) + • [Bid Structure](/concepts/bids/bid-structure) - • [Tools For Bid Submission](/developers/tools-for-bid-submission) + • [Bidder Deposit](/concepts/bids/bidder-deposit) - • [Managing Your Bidder Deposit](/developers/bidder-deposit) + • [Bid Decay](/concepts/bids/bid-decay-mechanism) @@ -57,8 +55,7 @@ Choose the guide below that best aligns with your interests and needs: - Providers are the backbone of the Primev ecosystem. Start with our Provider's Quick Setup to - optimize your block production and validation processes. + Providers form the backbone of the Primev ecosystem. Learn how to optimize your block production and validation processes with the resources below. @@ -79,7 +76,7 @@ Choose the guide below that best aligns with your interests and needs: - L1 Ethereum validators + L1 Ethereum Validators @@ -91,12 +88,23 @@ Choose the guide below that best aligns with your interests and needs: • [Opting-in as a Validator](/get-started/validators) - • [What is mev-commit?](/concepts/what-is-mev-commit) - - • [Validator considerations](/concepts/validator-considerations) + • [Validator Considerations](/concepts/validator-considerations) - • [mev-commit Testnet](/developers/testnet) + +## About Primev + +Our mission at Primev is to create a robust, transparent, and efficient ecosystem for mev actors through the development of mev-commit, a credible commitment network utilized for preconfirmations and more. We are dedicated to fostering a permissionless, transparent, and sustainable mev ecosystem. + +### Engage with Us + +Connect with us on various platforms to stay updated and get involved: + +- **X**: Follow us for real-time updates and announcements [here](https://x.com/primev_xyz). +- **Github**: Track our progress, contribute to our open-source projects, and explore our repositories [here](https://github.com/primev). +- **Mirror**: Stay informed with our latest articles and research papers [here](https://mirror.xyz/preconf.eth). + +Our work is open-source, and we welcome contributions from the community to enhance and expand our ecosystem. diff --git a/mint.json b/mint.json index 9480a8d8..d491da94 100644 --- a/mint.json +++ b/mint.json @@ -15,7 +15,20 @@ "to": "#E97D25" } }, - + "topbarLinks": [ + { + "name": "Follow", + "url": "https://twitter.com/primev_xyz" + }, + { + "name": "Writings", + "url": "https://mirror.xyz/preconf.eth" + } + ], + "topbarCtaButton": { + "type": "github", + "url": "https://github.com/primev/mev-commit" + }, "tabs": [ { "name": "API Reference", @@ -30,29 +43,39 @@ { "group": "Get Started", "pages": [ - "get-started/introduction", - "get-started/quickstart", - "get-started/faucet", - "get-started/validators", - "get-started/relays", + "get-started/welcome-to-primev" + ] + }, + { + "group": "Quickstart", + "pages": [ { - "group": "Bidders", + "group": "Providers & Bidders", "pages": [ - "get-started/bidders/first-preconf", - "get-started/bidders/bidder-node-commands" + "quickstart/providers-and-bidders/set-up-mev-commit-node", + "quickstart/providers-and-bidders/faucet", + { + "group": "Bidders", + "pages": [ + "quickstart/providers-and-bidders/bidders/first-preconf", + "quickstart/providers-and-bidders/bidders/bidder-node-commands", + "quickstart/providers-and-bidders/bidders/bidder-deposit" + ] + }, + { + "group": "Providers", + "pages": [ + "quickstart/providers-and-bidders/providers/registering-a-provider", + "quickstart/providers-and-bidders/providers/consuming-bids", + "quickstart/providers-and-bidders/providers/sending-commitments", + "quickstart/providers-and-bidders/providers/querying-for-proposers" + ] + } ], - "icon": "user-bounty-hunter" + "icon": "arrow-right-arrow-left" }, - { - "group": "Providers", - "pages": [ - "get-started/providers/registering-a-provider", - "get-started/providers/consuming-bids", - "get-started/providers/sending-commitments", - "get-started/providers/Querying-for-proposers" - ], - "icon": "network-wired" - } + "quickstart/validators", + "quickstart/relays" ] }, { @@ -62,17 +85,17 @@ "concepts/actors", "concepts/network-overview", "concepts/privacy", - "concepts/commitments", - { - "group": "Bids", + { + "group": "Bids & Commitments", "pages": [ "concepts/bids/bid-structure", + "concepts/bids/commitments", "concepts/bids/bidder-deposit", "concepts/bids/bid-decay-mechanism" ] }, { - "group": "mev-commit Chain", + "group": "Mev-commit Chain", "pages": [ "concepts/mev-commit-chain/chain-details", "concepts/mev-commit-chain/differences-between-ethereum-and-mev-commit-chain", @@ -89,13 +112,10 @@ "pages": [ "developers/testnet", "developers/system-requirements", - "developers/provider-api", - "developers/bidder-api", - "developers/bidder-deposit", - "developers/tools-for-bid-submission", - "developers/stake-validator-keys-manually", "developers/contracts", "developers/debugging", + "developers/tools-for-bid-submission", + "developers/stake-validator-keys-manually", "developers/manual-start-mev-commit", "developers/run-mev-commit-chain-node" ] @@ -113,7 +133,11 @@ }, { "group": "API Reference", - "pages": ["api-reference/introduction"] + "pages": [ + "api-reference/introduction", + "api-reference/provider-api", + "api-reference/bidder-api" + ] }, { "group": "Provider", diff --git a/developers/bidder-deposit.mdx b/quickstart/providers-and-bidders/bidders/bidder-deposit.mdx similarity index 98% rename from developers/bidder-deposit.mdx rename to quickstart/providers-and-bidders/bidders/bidder-deposit.mdx index 98433768..56543fce 100644 --- a/developers/bidder-deposit.mdx +++ b/quickstart/providers-and-bidders/bidders/bidder-deposit.mdx @@ -1,6 +1,6 @@ --- title: "Managing Your Bidder Deposit" -sidebarTitle: Managing Your Bidder Deposit +sidebarTitle: Bidder Deposit --- **To Check Your Deposit for current window:** diff --git a/get-started/bidders/bidder-node-commands.mdx b/quickstart/providers-and-bidders/bidders/bidder-node-commands.mdx similarity index 85% rename from get-started/bidders/bidder-node-commands.mdx rename to quickstart/providers-and-bidders/bidders/bidder-node-commands.mdx index 9740ed02..c90a1324 100644 --- a/get-started/bidders/bidder-node-commands.mdx +++ b/quickstart/providers-and-bidders/bidders/bidder-node-commands.mdx @@ -17,23 +17,23 @@ 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](https://docs.primev.xyz/concepts/bidder-deposit): +To get the current deposit balance in the contract for the current [window](/concepts/bids/bidder-deposit): ```shell ❯_ terminal curl -s http://localhost:13523/v1/bidder/get_deposit ``` -To get the current deposit balance in the contract for a specific [window](https://docs.primev.xyz/concepts/bidder-deposit): +To get the current deposit balance in the contract for a specific [window](/concepts/bids/bidder-deposit): ```shell ❯_ terminal curl -s http://localhost:13523/v1/bidder/get_deposit?windowNumber=1 ``` -💡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. +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 -This command will allow you to withdraw funds from the specific [window](https://docs.primev.xyz/concepts/bidder-deposit). +This command will allow you to withdraw funds from the specific [window](/concepts/bids/bidder-deposit). Window number is the number where the bidder deposited funds. ```shell ❯_ terminal diff --git a/get-started/bidders/bidder-overview.mdx b/quickstart/providers-and-bidders/bidders/bidder-overview.mdx similarity index 100% rename from get-started/bidders/bidder-overview.mdx rename to quickstart/providers-and-bidders/bidders/bidder-overview.mdx diff --git a/get-started/bidders/first-preconf.mdx b/quickstart/providers-and-bidders/bidders/first-preconf.mdx similarity index 70% rename from get-started/bidders/first-preconf.mdx rename to quickstart/providers-and-bidders/bidders/first-preconf.mdx index 277c5a88..88021220 100644 --- a/get-started/bidders/first-preconf.mdx +++ b/quickstart/providers-and-bidders/bidders/first-preconf.mdx @@ -3,28 +3,19 @@ title: "Receive your First Preconfirmation" sidebarTitle: "My First Preconf" --- -## Pre-requisites - -Make sure you: - -1. Get a [mev-commit Bidder Node up and running](/get-started/quickstart). -2. [Fund your node](/get-started/faucet) so you have the funds to submit bids. - -## Introduction - Once you've funded your bidder node wallet, you're ready to start submitting bids to the network. It's crucial to verify that your bidder node is connected to at least one provider node. This connectivity can be confirmed via the [localhost:13523/topology](http://localhost:13523/topology) endpoint. -### 💳 Deposit For Bids - -Run this command to load your account with funds to start bidding: + + + Run this command to load your account with funds to start bidding: ```shell ❯_ terminal curl -X POST http://localhost:13523/v1/bidder/deposit/1000000000000000000 ``` -This tops up your account with `1000000000000000000 wei` (1 ETH) for the current [window](https://docs.primev.xyz/concepts/bidder-deposit), ensuring you're all set to send bids! +This tops up your account with `1000000000000000000 wei` (1 ETH) for the current [window](/concepts/bids/bidder-deposit), ensuring you're all set to send bids! The window is the number of L1 blocks in the round for which the bidder can post bids. If you want to deposit funds for a specific L1 block number, which will be automatically converted to the corresponding window, use the following command: @@ -32,10 +23,9 @@ If you want to deposit funds for a specific L1 block number, which will be autom ```shell ❯_ terminal curl -X POST "http://localhost:13523/v1/bidder/deposit/1000000000000000000?block_number=" ``` - -### Sending Bids - -Open a new terminal window. To send bids, we simply run the following command: + + + Open a new terminal window. To send bids, we simply run the following command: ```shell ❯_ example curl -X POST http://localhost:13523/v1/bidder/bid \ @@ -47,6 +37,8 @@ curl -X POST http://localhost:13523/v1/bidder/bid \ "decayEndTimestamp": }' ``` + +Make sure your bid amount is sufficiently high for the commitment you're requesting, and your target L1 block number is accurate. It's up to the providers to commit to your bid, so try to ensure a commitment is feasible to your bid by its construction. | Key | Description | @@ -57,7 +49,7 @@ curl -X POST http://localhost:13523/v1/bidder/bid \ | `decayStartTimestamp` | Start timestamp for bid decay (in Unix milliseconds) | | `decayEndTimestamp` | End timestamp for bid decay (in Unix milliseconds) | - If you want to learn more about Bids and Bid Structure visit [Bids](/concepts/bids) section. + If you want to learn more about Bids and Bid Structure visit [Bid Structure](/concepts/bids/bid-structure) section. To include bundles of transactions, add them in the atomic sequence in which they exist in the bundle, as follows: @@ -71,10 +63,9 @@ curl -X POST http://localhost:13523/v1/bidder/bid \ "decayStartTimestamp": , "decayEndTimestamp": }' -``` - -💡You can change the values in the fields txHashes, amount, blockNumber, decayStartTimestamp and decayEndTimestamp as desired. - -🎉 Congrats, you just sent your first L1 preconfirmation bid! You should be receiving commmitments near instantly. +``` +You can change the values in the fields txHashes, amount, blockNumber, decayStartTimestamp and decayEndTimestamp as desired. + + -Make sure your bid amount is sufficiently high for the commitment you're requesting, and your target L1 block number is accurate. It's up to the providers to commit to your bid, so try to ensure a commitment is feasible to your bid by its construction. +Congrats, you just sent your first L1 preconfirmation bid! You should be receiving commitments nearly instantly. diff --git a/get-started/faucet.mdx b/quickstart/providers-and-bidders/faucet.mdx similarity index 80% rename from get-started/faucet.mdx rename to quickstart/providers-and-bidders/faucet.mdx index 2b80be2a..eb0591cd 100644 --- a/get-started/faucet.mdx +++ b/quickstart/providers-and-bidders/faucet.mdx @@ -1,8 +1,10 @@ --- title: "Testnet Faucet" sidebarTitle: Testnet Faucet -icon: "faucet" --- + +This faucet is for Providers and Bidders only, Validators please visit the faucet links listed on [this](/get-started/validators) page +

Visit our testnet [faucet page](http://faucet.testnet.mev-commit.xyz/), to easily request up to 10 ETH per request for your wallet.

To facilitate your interaction with the mev-commit Testnet, we provide a convenient method to fund your node with Ether using our dedicated faucet.

diff --git a/get-started/providers/Querying-for-proposers.mdx b/quickstart/providers-and-bidders/providers/Querying-for-proposers.mdx similarity index 100% rename from get-started/providers/Querying-for-proposers.mdx rename to quickstart/providers-and-bidders/providers/Querying-for-proposers.mdx diff --git a/get-started/providers/consuming-bids.mdx b/quickstart/providers-and-bidders/providers/consuming-bids.mdx similarity index 88% rename from get-started/providers/consuming-bids.mdx rename to quickstart/providers-and-bidders/providers/consuming-bids.mdx index 1b1c68c5..72a9fe0f 100644 --- a/get-started/providers/consuming-bids.mdx +++ b/quickstart/providers-and-bidders/providers/consuming-bids.mdx @@ -5,15 +5,17 @@ sidebarTitle: Consuming Bids Providers that have registered in the mev-commit registry will automatically start receiving bids on the mev-commit p2p network from bidders. In order to see incoming bids, providers need to communicate with their mev-commit node: -- Use the official go RPC client to communicate with your mev-commit node. Go get the mev-commit package and then import the generated client as below: +Use the official go RPC client to communicate with your mev-commit node. Go get the mev-commit package and then import the generated client as below: - 1. Install the mev-commit package: + + + ```bash ❯_ terminal go install github.com/primev/mev-commit@latest ``` - - 2. Incorporate the generated client into your Go application as follows: + + ```go import providerapiv1 "github.com/primev/mev-commit/p2p/gen/go/providerapi/v1" @@ -72,7 +74,8 @@ Providers that have registered in the mev-commit registry will automatically sta ``` There is an [example implementation](https://github.com/primev/mev-commit/tree/main/p2p/examples/provideremulator) of a dummy provider client which blindly accepts all the bids it sees from its mev-commit node. This could be a good starting point for providers implementing their commitment decision logic in golang. - + + ### Alternative Methods 1. Use [https://github.com/fullstorydev/grpcurl](https://github.com/fullstorydev/grpcurl) or [https://github.com/bloomrpc/bloomrpc](https://github.com/bloomrpc/bloomrpc) or other GUI clients like [Postman](https://www.postman.com). Relevant protobuf files are available in the [mev-commit repository](https://github.com/primev/mev-commit). diff --git a/get-started/providers/registering-a-provider.mdx b/quickstart/providers-and-bidders/providers/registering-a-provider.mdx similarity index 66% rename from get-started/providers/registering-a-provider.mdx rename to quickstart/providers-and-bidders/providers/registering-a-provider.mdx index f21f0bc7..373e1226 100644 --- a/get-started/providers/registering-a-provider.mdx +++ b/quickstart/providers-and-bidders/providers/registering-a-provider.mdx @@ -5,13 +5,26 @@ sidebarTitle: Registering as a Provider To register on the mev-commit network, providers need to stake ETH in the provider registry contract. This adds credibility to issued commitments, as stake may be slashed in the event of a broken commitment, such as committing to a preconfirmation bid and not including the relevant transaction in a block. -Once a provider is registered on the network, other nodes will connect to it and the provider node will see bids come in. +Once a provider is registered on the network, other nodes will connect to it, and the provider node will receive bids. You can use the provider API to stake and check your stake balance. -- Stake (make sure you've [funded your account on the mev-commit chain](/get-started/faucet) first). + + + Make sure you've [funded your account on the mev-commit chain](/get-started/faucet) first. + + + Check the minimum amount that can be staked, and consider staking more than the minimum. Bidders will only connect to providers which have stake higher than this minimum. The larger a provider's stake, the greater the credibility behind that provider's commitments. The amount is set in `wei`. - ```shell + ```shell + > curl localhost:13523/v1/provider/get_min_stake | jq + { + "amount": "1000000000000000000" + } + ``` + + + ```shell > curl -X POST localhost:13523/v1/provider/register_stake/10000000000000000000 | jq { "amount": "10000000000000000000" @@ -20,6 +33,13 @@ You can use the provider API to stake and check your stake balance. Once staked, peer connection logs should appear within a few minutes. You can check the `/topology` endpoint again to verify connected peers. + + + + + +Other commands that can be used are: + - Check stake balance ```shell @@ -48,13 +68,4 @@ You can use the provider API to stake and check your stake balance. } ``` -- Check the minimum amount that can be staked, and consider staking more than the minimum. Bidders will only connect to providers which have stake higher than this minimum. The larger a provider's stake, the greater the credibility behind that provider's commitments. The amount is set in `wei`. - - ```shell - > curl localhost:13523/v1/provider/get_min_stake | jq - { - "amount": "1000000000000000000" - } - ``` - -Congrats, your provider node is registered on mev-commit and you're ready to [consume bids](/get-started/providers/consuming-bids). + Congrats! Your provider node is registered on mev-commit, and you're ready to [consume bids](/get-started/providers/consuming-bids). diff --git a/get-started/providers/sending-commitments.mdx b/quickstart/providers-and-bidders/providers/sending-commitments.mdx similarity index 87% rename from get-started/providers/sending-commitments.mdx rename to quickstart/providers-and-bidders/providers/sending-commitments.mdx index 408f374d..f0a3e24c 100644 --- a/get-started/providers/sending-commitments.mdx +++ b/quickstart/providers-and-bidders/providers/sending-commitments.mdx @@ -3,15 +3,9 @@ title: Sending Commitments sidebarTitle: Sending Commitments --- -To send your first commitment, you will need to connect to the mev-commit Testnet. -This will allow you to consume bids incoming to the network and submit commitments. -Your first step is to set up a provider node. The following command will allow you to automatically set up a full provider mev-commit node: +To send your first commitment, you will need to connect to the mev-commit Testnet. This will allow you to consume bids incoming to the network and submit commitments. To do this, you'll want to run an emulator to simulate accepting and rejecting bids. -``` -curl -L -o launchmevcommit launch.mev-commit.xyz && chmod +x launchmevcommit && ./launchmevcommit --node-type provider -``` - -Now you'll want to run an emulator to simulate the accepting and rejecting of bids. You can read more about the internal builder API [here](/api-reference/provider/sendprocessedbids). +You can read more about the internal builder API [here](/api-reference/provider/sendprocessedbids). To get started with the emulator, open a new terminal and run the following command: @@ -30,11 +24,13 @@ We can take a deeper look at how you can add custom logic to decision on the sen To integrate bid processing in your system using the Provider API, follow these steps to receive bid information and send back processed bids: -#### 1. Implement the gRPC Service + + Implement the Provider service as outlined in the [providerapi.proto](https://github.com/primev/mev-commit/blob/main/p2p/rpc/providerapi/v1/providerapi.proto#L20). This requires setting up a server that can manage RPC methods, with a particular emphasis on the reception of bids and response of commitment authorizations. + -#### 2. Receive Bids + Utilize the ReceiveBids RPC method to listen for incoming bids from clients. This method streams bid messages to your server. The structure of the bid is as follows: @@ -60,12 +56,12 @@ message Bid { Below is an image of the flow through which bids would be received through the gRPC API ![gRPC Flow for Getting Bids](/images/grpc-flow-getbids.png) - -#### 3. Process Bids + + For each received bid, implement your custom logic to validate and process these bids. This could involve checking the bid's validity and feasibility based on orderflow, computing the effective gas price, and deciding whether to accept or reject the bid. - -#### 4. Send Processed Bid Responses (Accept/Reject) + + After processing each bid, construct a BidResponse message indicating the outcome. This message should include the bid's digest and a status indicating acceptance or rejection. At a high level, to commit to a bid, your code must send a `STATUS_ACCEPTED` with the bid digest specified, and correspondingly `STATUS_REJECTED` to reject the bid. @@ -112,8 +108,8 @@ It contains the following fields: STATUS_REJECTED: Indicates that the bid has been rejected by the provider. 3. dispatch_timestamp: Timestamp (int64 type) at which the commitment is accepted by provider and is used to compute the expected revenue from the preconfirmation. - -#### 5. Server Setup + + Deploy your gRPC server on suitable infrastructure, ensuring it's accessible to clients. Configure necessary network settings for security and connectivity. Example Server Implementation in Go: @@ -150,5 +146,6 @@ func ...() { } } ``` - -This should help you integrate bid processing into your system, allowing for the reception of bid information and sending back processed bids as commitments. + + +This should help you integrate bid processing into your system, allowing you to receive bid information and send back processed bids as commitments. diff --git a/quickstart/providers-and-bidders/set-up-mev-commit-node.mdx b/quickstart/providers-and-bidders/set-up-mev-commit-node.mdx new file mode 100644 index 00000000..26dcd281 --- /dev/null +++ b/quickstart/providers-and-bidders/set-up-mev-commit-node.mdx @@ -0,0 +1,104 @@ +--- +title: "Quickstart Your mev-commit Node" +description: "Step into the Primev ecosystem with ease. This guide covers everything you need to set up your mev-commit node, whether you're aiming to be a bidder or a provider." +sidebarTitle: Setup Node +mode: "wide" +--- + + + +Make sure to check [System Requirements](/developers/system-requirements) to better understand what is needed to run mev-commit without any interruptions. + + + ```bash ❯_ bidder + curl -L -o launchmevcommit launch.mev-commit.xyz; chmod +x launchmevcommit; ./launchmevcommit --node-type bidder + ``` + + + ## Script Overview + + This script automates the setup and initialization of your Primev node, catering to both bidder and provider roles. Below is a detailed breakdown of the script's operations: + + ### 1. Initialization + - Sets up essential variables like the RPC URL (`https://chainrpc.testnet.mev-commit.xyz) for network communication and the node type (either `bidder` or `provider`). + - Establishes the root directory (`$HOME/.mev-commit`) where the mev-commit node will be installed. + + ### 2. Download + - Fetches the appropriate mev-commit binary for your system from the [Primev GitHub releases page](https://github.com/primev/mev-commit/releases/latest), considering your operating system and architecture. + + ### 3. Installation + - Extracts the downloaded binary into the specified root directory, ensuring all necessary executables are correctly placed for the node's operation. + + ### 4. Configuration + - Initializes the mev-commit node with your specified settings, including the node type and the RPC endpoint, along with necessary contract addresses for the node's functionality. + + ### 5. Wallet Setup + - Generates a new private key and wallet address for your node and secures it with test ether to facilitate transactions within the testnet environment. + + ### 6. Node Startup + - Launches the mev-commit node in the background tailored to the specified role, enabling it to begin its operations within the Primev network. + + ### 7. Cleanup + - Includes a cleanup function to ensure the node is properly shut down when the script exits, preventing any residual processes. + + + + + + To fund your account, please visit our [Testnet Faucet](/get-started/faucet). Details about the account address will be displayed after running the command above. + + + Visit [My First Preconf](/get-started/bidders/first-preconf) page to submit bids on the network and start receiving preconfirmations. +If you want to perform a manual setup with detailed steps, please skip to the [manual start mev-commit](/developers/manual-start-mev-commit) section. + + + + + + Make sure to check [System Requirements](/developers/system-requirements) to better understand what is needed to run mev-commit without any interruptions. + + + ```bash ❯_ provider + curl -L -o launchmevcommit launch.mev-commit.xyz; chmod +x launchmevcommit; ./launchmevcommit --node-type provider + ``` + + + ## Script Overview + + This script automates the setup and initialization of your Primev node, catering to both bidder and provider roles. Below is a detailed breakdown of the script's operations: + + ### 1. Initialization + - Sets up essential variables like the RPC URL (`https://chainrpc.testnet.mev-commit.xyz) for network communication and the node type (either `bidder` or `provider`). + - Establishes the root directory (`$HOME/.mev-commit`) where the mev-commit node will be installed. + + ### 2. Download + - Fetches the appropriate mev-commit binary for your system from the [Primev GitHub releases page](https://github.com/primev/mev-commit/releases/latest), considering your operating system and architecture. + + ### 3. Installation + - Extracts the downloaded binary into the specified root directory, ensuring all necessary executables are correctly placed for the node's operation. + + ### 4. Configuration + - Initializes the mev-commit node with your specified settings, including the node type and the RPC endpoint, along with necessary contract addresses for the node's functionality. + + ### 5. Wallet Setup + - Generates a new private key and wallet address for your node and secures it with test ether to facilitate transactions within the testnet environment. + + ### 6. Node Startup + - Launches the mev-commit node in the background tailored to the specified role, enabling it to begin its operations within the Primev network. + + ### 7. Cleanup + - Includes a cleanup function to ensure the node is properly shut down when the script exits, preventing any residual processes. + + + + + + To fund your account, please visit our [Testnet Faucet](/get-started/faucet). Details about the account address will be displayed after running the command above. + + + Visit [Register as a Provider](/get-started/providers/registering-a-provider) page to register yourself as a provider on mev-commit network and follow the steps to start sending commitments. +If you want to perform a manual setup with detailed steps, please skip to the [manual start mev-commit](/developers/manual-start-mev-commit) section. + + + + diff --git a/get-started/relays.mdx b/quickstart/relays.mdx similarity index 99% rename from get-started/relays.mdx rename to quickstart/relays.mdx index 6139385e..fd388495 100644 --- a/get-started/relays.mdx +++ b/quickstart/relays.mdx @@ -1,7 +1,7 @@ --- title: Relay Guide sidebarTitle: Relays -icon: 'arrow-right-arrow-left' +icon: 'satellite-dish' --- import { ProviderRegistryAddress } from '/snippets/testnet-addresses.mdx'; diff --git a/get-started/validators.mdx b/quickstart/validators.mdx similarity index 91% rename from get-started/validators.mdx rename to quickstart/validators.mdx index 49d5cb7b..627e5e7c 100644 --- a/get-started/validators.mdx +++ b/quickstart/validators.mdx @@ -28,19 +28,22 @@ By opting-in to the mev-commit protocol as a Holesky validator, you agree to the - - + + - - + +
RelayDocsRelayDocs
Titan[docs.titanrelay.xyz](https://docs.titanrelay.xyz/)Titan + docs.titanrelay.xyz +
-If you are a relay looking to join mev-commit network please visit our [Relays page](/get-started/relays) to get more information. + +If you are a relay looking to join mev-commit network please visit our [Relays page](/get-started/relays) for more information. 0.0001 ETH must be staked with the registry contract on Holesky for each validator pubkey. Below are a few options for obtaining this testnet ETH: