Updates and fixes v2

developers/bidder-api.mdx → api-reference/bidder-api.mdx

@@ -1,5 +1,6 @@
 ---
 title: "Bidder API"
+sidebarTitle: "Bidder API Overview"
 ---
 
 ## **Bidders**

developers/provider-api.mdx → api-reference/provider-api.mdx

@@ -1,5 +1,6 @@
 ---
 title: "Provider API"
+sidebarTitle: "Provider API Overview"
 ---
 
 ## **Providers**

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:
-<Note>The timestamp is specified in Unix milliseconds. For example, a timestamp of `1633046400000` represents `October 1, 2021 00:00:00 GMT`.</Note>
+## 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. 
+<Note>The timestamp is specified in Unix milliseconds. For example, a timestamp of `1633046400000` represents `October 1, 2021 00:00:00 GMT`.</Note>
 
 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.
 

concepts/bids/bid-structure.mdx

@@ -1,4 +1,5 @@
 ---
+title: Bid Structure
 sidebarTitle: Bid Structure
 ---
 

concepts/mev-commit-chain/chain-details.mdx

@@ -3,33 +3,33 @@ 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.
 
 At this point of the network's inception, Primev entities will run all validating infrastructure for the mev-commit chain. Correct and honest operation can be permissionlessly audited by spinning up a full node and connecting to the mev-commit chain as a peer. Over time we plan to have entities outside of Primev to become POA signers or bridge validators to progressively decentralize the centralized components of the system.
 
 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.
 

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:
 
 <Frame>

concepts/what-is-mev-commit.mdx

@@ -9,6 +9,18 @@ Mev-commit is a peer-to-peer (P2P) networking platform designed to facilitate re
   <img src="/images/mev-commit.png" />
 </Frame>
 
+## 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.&#x20;
+
+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.&#x20;
+
+## 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.&#x20;
+
 ## 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
   <img src="/images/supply-chain.png" />
 </Frame>
 
-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.&#x20;
-
-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.&#x20;
-
-## 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.&#x20;
-
-## 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/).

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
   <img src="/images/mev-commit-nodes.png" />
 </Frame>
 
+## 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.